From a337d933f3dc86f76327cb9cecbfe4903bcca61b Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 20 Apr 2026 02:54:27 +0200
Subject: [PATCH 01/17] feat(react-headless-components-preview): add headless
 Popover built on native CSS anchor positioning

---
 .../Dialog/useDialogContextValues copy.ts     |  38 +
 .../react-headless-components-preview.api.md  |   9 -
 .../library/package.json                      |   3 +
 .../src/components/Popover/Popover.cy.tsx     | 653 ++++++++++++++++++
 .../src/components/Popover/Popover.test.tsx   | 234 +++++++
 .../src/components/Popover/Popover.tsx        |  22 +
 .../src/components/Popover/Popover.types.ts   | 195 ++++++
 .../PopoverSurface/PopoverSurface.test.tsx    | 165 +++++
 .../Popover/PopoverSurface/PopoverSurface.tsx |  20 +
 .../PopoverSurface/PopoverSurface.types.ts    |   1 +
 .../Popover/PopoverSurface/index.ts           |   4 +
 .../PopoverSurface/renderPopoverSurface.tsx   |  24 +
 .../PopoverSurface/usePopoverSurface.ts       | 111 +++
 .../PopoverTrigger/PopoverTrigger.test.tsx    | 140 ++++
 .../Popover/PopoverTrigger/PopoverTrigger.tsx |  19 +
 .../PopoverTrigger/PopoverTrigger.types.ts    |   1 +
 .../Popover/PopoverTrigger/index.ts           |   4 +
 .../PopoverTrigger/renderPopoverTrigger.ts    |   9 +
 .../PopoverTrigger/usePopoverTrigger.ts       | 103 +++
 .../library/src/components/Popover/index.ts   |  17 +
 .../src/components/Popover/popoverContext.ts  |  38 +
 .../src/components/Popover/renderPopover.tsx  |  17 +
 .../src/components/Popover/usePopover.ts      | 210 ++++++
 .../library/src/hooks/index.ts                |  13 +
 .../library/src/hooks/useFocusScope.ts        | 428 ++++++++++++
 .../src/hooks/usePositioning/constants.ts     |  46 ++
 .../hooks/usePositioning/fallbackStyles.ts    |  55 ++
 .../library/src/hooks/usePositioning/index.ts |  12 +
 .../src/hooks/usePositioning/placement.ts     |  39 ++
 .../src/hooks/usePositioning/resolvers.ts     |  30 +
 .../src/hooks/usePositioning/styleHelpers.ts  | 137 ++++
 .../library/src/hooks/usePositioning/types.ts |  99 +++
 .../src/hooks/usePositioning/useAnchorName.ts |  44 ++
 .../usePositioning/useAutoSizeBoundary.ts     | 126 ++++
 .../hooks/usePositioning/usePlacementSync.ts  | 170 +++++
 .../usePositioning/usePositioning.test.tsx    |  67 ++
 .../hooks/usePositioning/usePositioning.ts    | 166 +++++
 .../library/src/popover.ts                    |  35 +
 .../src/Popover/PopoverNested.stories.tsx     |  64 ++
 39 files changed, 3559 insertions(+), 9 deletions(-)
 create mode 100644 packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/renderPopoverSurface.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/renderPopover.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/popover.ts
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx

diff --git a/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts b/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts
new file mode 100644
index 00000000000000..a56ed7233ebbc7
--- /dev/null
+++ b/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts	
@@ -0,0 +1,38 @@
+import type { DialogContextValue, DialogSurfaceContextValue } from '../../contexts';
+import type { DialogContextValues, DialogState } from './Dialog.types';
+
+export function useDialogContextValues_unstable(state: DialogState): DialogContextValues {
+  const {
+    modalType,
+    open,
+    dialogRef,
+    dialogTitleId,
+    isNestedDialog,
+    inertTrapFocus,
+    requestOpenChange,
+    modalAttributes,
+    triggerAttributes,
+    unmountOnClose,
+  } = state;
+
+  /**
+   * This context is created with "@fluentui/react-context-selector",
+   * there is no sense to memoize it
+   */
+  const dialog: DialogContextValue = {
+    open,
+    modalType,
+    dialogRef,
+    dialogTitleId,
+    isNestedDialog,
+    inertTrapFocus,
+    modalAttributes,
+    triggerAttributes,
+    unmountOnClose,
+    requestOpenChange,
+  };
+
+  const dialogSurface: DialogSurfaceContextValue = false;
+
+  return { dialog, dialogSurface };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
deleted file mode 100644
index 6bef1c6e594fed..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
+++ /dev/null
@@ -1,9 +0,0 @@
-## API Report File for "@fluentui/react-headless-components-preview"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-
-// (No @packageDocumentation comment for this package)
-
-```
diff --git a/packages/react-components/react-headless-components-preview/library/package.json b/packages/react-components/react-headless-components-preview/library/package.json
index f9ca4be78888cc..552e5e6061c43f 100644
--- a/packages/react-components/react-headless-components-preview/library/package.json
+++ b/packages/react-components/react-headless-components-preview/library/package.json
@@ -19,6 +19,8 @@
   "license": "MIT",
   "dependencies": {
     "@fluentui/react-accordion": "^9.11.0",
+    "@fluentui/react-aria": "^9.17.10",
+    "@fluentui/keyboard-keys": "^9.0.8",
     "@fluentui/react-avatar": "^9.11.1",
     "@fluentui/react-badge": "^9.5.2",
     "@fluentui/react-button": "^9.9.1",
@@ -41,6 +43,7 @@
     "@fluentui/react-search": "^9.4.2",
     "@fluentui/react-select": "^9.5.1",
     "@fluentui/react-shared-contexts": "^9.26.2",
+    "@fluentui/react-context-selector": "^9.2.15",
     "@fluentui/react-skeleton": "^9.7.2",
     "@fluentui/react-slider": "^9.6.2",
     "@fluentui/react-spinbutton": "^9.6.2",
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
new file mode 100644
index 00000000000000..e94ce6adff9dfe
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
@@ -0,0 +1,653 @@
+import * as React from 'react';
+import { mount as mountBase } from '@fluentui/scripts-cypress';
+import { Popover } from './Popover';
+import { PopoverTrigger } from './PopoverTrigger/PopoverTrigger';
+import { PopoverSurface } from './PopoverSurface/PopoverSurface';
+import type { PopoverProps } from './Popover.types';
+import type { JSXElement } from '@fluentui/react-utilities';
+
+const mount = (element: JSXElement) => {
+  mountBase(element);
+};
+
+const popoverTriggerSelector = '[aria-expanded]';
+const popoverContentSelector = '[role="group"]';
+const popoverDialogContentSelector = '[role="dialog"]';
+
+describe('Popover', () => {
+  ['uncontrolled', 'controlled'].forEach(scenario => {
+    const UncontrolledExample = () => (
+      <Popover>
+        <PopoverTrigger disableButtonEnhancement>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>This is a popover</PopoverSurface>
+      </Popover>
+    );
+
+    const ControlledExample = () => {
+      const [open, setOpen] = React.useState(false);
+
+      return (
+        <Popover open={open} onOpenChange={(e, data) => setOpen(data.open)}>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>This is a popover</PopoverSurface>
+        </Popover>
+      );
+    };
+
+    describe(scenario, () => {
+      const Example = scenario === 'controlled' ? ControlledExample : UncontrolledExample;
+
+      beforeEach(() => {
+        mount(<Example />);
+        cy.get('body').click('bottomRight');
+      });
+
+      it('should open when clicked', () => {
+        cy.get(popoverTriggerSelector).click().get(popoverContentSelector).should('be.visible');
+      });
+
+      (['{enter}', 'Space'] as const).forEach((key: '{enter}' | 'Space') => {
+        it(`should open with ${key}`, () => {
+          cy.get(popoverTriggerSelector).focus().realPress(key);
+          cy.get(popoverContentSelector).should('be.visible');
+        });
+      });
+
+      it('should dismiss on click outside', () => {
+        cy.get(popoverTriggerSelector)
+          .click()
+          .get('body')
+          .click('bottomRight')
+          .get(popoverContentSelector)
+          .should('not.exist');
+      });
+
+      it('should dismiss on Escape keydown', () => {
+        cy.get(popoverTriggerSelector).click().realPress('Escape');
+        cy.get(popoverContentSelector).should('not.exist');
+      });
+
+      it('should keep open state on scroll outside', () => {
+        cy.get(popoverTriggerSelector).click().get(popoverContentSelector).should('be.visible');
+        cy.get('body').trigger('wheel').get(popoverContentSelector).should('be.visible');
+      });
+    });
+  });
+
+  describe('ARIA attributes', () => {
+    it('should set aria-expanded="false" on closed trigger', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).should('have.attr', 'aria-expanded', 'false');
+    });
+
+    it('should set aria-expanded="true" when open', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click().should('have.attr', 'aria-expanded', 'true');
+    });
+
+    it('should set aria-haspopup="true" by default', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).should('have.attr', 'aria-haspopup', 'true');
+    });
+
+    it('should set aria-haspopup="dialog" with trapFocus', () => {
+      mount(
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).should('have.attr', 'aria-haspopup', 'dialog');
+    });
+
+    it('should set role="group" on surface by default', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click();
+      cy.get(popoverContentSelector).should('exist');
+    });
+
+    it('should set role="dialog" and aria-modal with trapFocus', () => {
+      mount(
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click();
+      cy.get(popoverDialogContentSelector).should('have.attr', 'aria-modal', 'true');
+    });
+  });
+
+  describe('data-* attributes', () => {
+    it('should set data-open on trigger when open', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).should('not.have.attr', 'data-open');
+      cy.get(popoverTriggerSelector).click().should('have.attr', 'data-open');
+    });
+
+    it('should set data-open on surface', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click();
+      cy.get(popoverContentSelector).should('have.attr', 'data-open');
+    });
+
+    it('should set popover="manual" on surface', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click();
+      cy.get(popoverContentSelector).should('have.attr', 'popover', 'manual');
+    });
+  });
+
+  describe('Open on hover', () => {
+    beforeEach(() => {
+      mount(
+        <Popover openOnHover>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>This is a popover</PopoverSurface>
+        </Popover>,
+      );
+      cy.get('body').click('bottomRight');
+    });
+
+    it('should open on hover, and keep open on mouse move to content', () => {
+      cy.get(popoverTriggerSelector).trigger('mouseover').get(popoverContentSelector).should('be.visible');
+      cy.get(popoverContentSelector).trigger('mouseover').get(popoverContentSelector).should('be.visible');
+    });
+  });
+
+  describe('With custom trigger', () => {
+    const CustomTrigger = React.forwardRef<HTMLButtonElement, {}>((props, ref) => {
+      return (
+        <button {...props} ref={ref}>
+          Custom Trigger
+        </button>
+      );
+    });
+
+    it('should dismiss on click outside', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger disableButtonEnhancement>
+            <CustomTrigger />
+          </PopoverTrigger>
+          <PopoverSurface>This is a popover</PopoverSurface>
+        </Popover>,
+      );
+      cy.get(popoverTriggerSelector).get('body').click('bottomRight').get(popoverContentSelector).should('not.exist');
+    });
+  });
+
+  describe('Context popover', () => {
+    beforeEach(() => {
+      mount(
+        <Popover openOnContext>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>This is a popover</PopoverSurface>
+        </Popover>,
+      );
+      cy.get('body').click('bottomRight');
+    });
+
+    it('should open when right clicked', () => {
+      cy.get(popoverTriggerSelector).rightclick().get(popoverContentSelector).should('be.visible');
+    });
+
+    it('should dismiss on scroll outside', () => {
+      cy.get(popoverTriggerSelector)
+        .rightclick()
+        .get('body')
+        .trigger('wheel')
+        .get(popoverContentSelector)
+        .should('not.exist');
+    });
+  });
+
+  describe('popover with closeOnScroll', () => {
+    beforeEach(() => {
+      mount(
+        <Popover closeOnScroll>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>This is a popover</PopoverSurface>
+        </Popover>,
+      );
+      cy.get('body').click('bottomRight');
+    });
+
+    it('should dismiss on scroll outside', () => {
+      cy.get(popoverTriggerSelector).click().get(popoverContentSelector).should('be.visible');
+      cy.get('body').trigger('wheel').get(popoverContentSelector).should('not.exist');
+    });
+  });
+
+  describe('Nested', () => {
+    const PopoverL1 = () => {
+      return (
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>First nested trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            <button>First nested button</button>
+            <PopoverL2 />
+            <PopoverL2 />
+          </PopoverSurface>
+        </Popover>
+      );
+    };
+
+    const PopoverL2 = () => {
+      return (
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Second nested trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            <button>Second nested button</button>
+          </PopoverSurface>
+        </Popover>
+      );
+    };
+
+    const Example = () => {
+      return (
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Root trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            <button>Root button</button>
+            <PopoverL1 />
+          </PopoverSurface>
+        </Popover>
+      );
+    };
+
+    beforeEach(() => {
+      mount(<Example />);
+      cy.contains('Root').click().get('body').contains('First').click().get('body').contains('Second').first().click();
+    });
+
+    it('should trap focus with tab', () => {
+      cy.focused().then(beforeFocused => {
+        cy.focused().realPress('Tab');
+        cy.realPress(['Shift', 'Tab']);
+        cy.focused().then(afterFocused => {
+          expect(beforeFocused[0]).eq(afterFocused[0]);
+        });
+      });
+    });
+
+    it('should trap focus with shift+tab', () => {
+      cy.focused().then(beforeFocused => {
+        cy.focused().realPress('Tab');
+        cy.realPress(['Shift', 'Tab']);
+        cy.focused().then(afterFocused => {
+          expect(beforeFocused[0]).eq(afterFocused[0]);
+        });
+      });
+    });
+
+    it('should dismiss all nested popovers on outside click', () => {
+      cy.get('body').click('bottomRight').get(popoverDialogContentSelector).should('not.exist');
+    });
+
+    it('should not dismiss when clicking on nested content', () => {
+      cy.contains('Second nested button').click().get(popoverDialogContentSelector).should('have.length', 3);
+    });
+
+    it('should dismiss child popovers when clicking on parents', () => {
+      // Native top-layer popovers stack visually, so deeper popovers cover
+      // ancestor surface buttons. `{ force: true }` bypasses Cypress's
+      // obscurement check — we're asserting dismissal behavior, not
+      // spatial layout.
+      cy.contains('First nested button')
+        .click({ force: true })
+        .get(popoverDialogContentSelector)
+        .should('have.length', 2)
+        .contains('Root button')
+        .click({ force: true })
+        .get(popoverDialogContentSelector)
+        .should('have.length', 1);
+    });
+
+    it('should when opening a sibling popover, should dismiss other sibling popover', () => {
+      const secondNestedTriggerSelector = 'button:contains(Second nested trigger)';
+
+      // The first sibling's popover is in the top layer and can cover the
+      // other sibling's trigger depending on viewport size. `{ force: true }`
+      // bypasses Cypress's obscurement check — the test asserts dismissal
+      // behavior, not spatial layout.
+      cy.get(secondNestedTriggerSelector)
+        .eq(1)
+        .click({ force: true })
+        .get(popoverDialogContentSelector)
+        .should('have.length', 3)
+        .get(secondNestedTriggerSelector)
+        .eq(0)
+        .click({ force: true })
+        .get(popoverDialogContentSelector)
+        .should('have.length', 3);
+    });
+
+    it('should dismiss each popover in the stack with Escape keydown', () => {
+      cy.focused().realPress('Escape');
+      cy.get(popoverDialogContentSelector).should('have.length', 2);
+      cy.focused().realPress('Escape');
+      cy.get(popoverDialogContentSelector).should('have.length', 1);
+      cy.focused().realPress('Escape');
+      cy.get(popoverDialogContentSelector).should('not.exist');
+    });
+  });
+
+  describe('updating content', () => {
+    const Example = () => {
+      const [visible, setVisible] = React.useState(false);
+
+      const changeContent = () => setVisible(true);
+      const onOpenChange: PopoverProps['onOpenChange'] = (e, data) => {
+        if (data.open === false) {
+          setVisible(false);
+        }
+      };
+
+      return (
+        <Popover onOpenChange={onOpenChange}>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Popover trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            {visible ? (
+              <div>The second panel</div>
+            ) : (
+              <div>
+                <button onClick={changeContent}>Action</button>
+              </div>
+            )}
+          </PopoverSurface>
+        </Popover>
+      );
+    };
+
+    it('should not close popover', () => {
+      mount(<Example />);
+      cy.get(popoverTriggerSelector)
+        .click()
+        .get(popoverContentSelector)
+        .within(() => {
+          cy.get('button').click();
+        })
+        .get(popoverContentSelector)
+        .should('exist');
+    });
+  });
+
+  describe('with inline prop', () => {
+    it('should render PopoverSurface in DOM order', () => {
+      mount(
+        <>
+          <div>
+            <Popover inline>
+              <PopoverTrigger disableButtonEnhancement>
+                <button>Popover trigger</button>
+              </PopoverTrigger>
+              <PopoverSurface>This is a Popover</PopoverSurface>
+            </Popover>
+          </div>
+          <div>Outside content</div>
+        </>,
+      );
+
+      cy.get(popoverTriggerSelector)
+        .click()
+        .get(popoverContentSelector)
+        .prev()
+        .then(popoverSurfacePrev => {
+          cy.get(popoverTriggerSelector).then(popoverTrigger => {
+            expect(popoverTrigger[0]).eq(popoverSurfacePrev[0]);
+          });
+        });
+    });
+
+    it('should not have popover attribute when inline', () => {
+      mount(
+        <Popover inline>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>Content</PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).click();
+      cy.get(popoverContentSelector).should('not.have.attr', 'popover');
+    });
+  });
+
+  describe('focus trap', () => {
+    it('Tab should cycle within the surface', () => {
+      mount(
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Popover trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            <button>One</button>
+            <button>Two</button>
+          </PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).focus().realPress('Enter');
+
+      cy.contains('One').should('have.focus').realPress('Tab');
+      cy.contains('Two').should('have.focus').realPress('Tab');
+      cy.contains('One').should('have.focus').realPress(['Shift', 'Tab']);
+      cy.contains('Two').should('have.focus');
+    });
+
+    it('should focus on PopoverSurface when its tabIndex is a number', () => {
+      mount(
+        <Popover trapFocus>
+          <PopoverTrigger disableButtonEnhancement>
+            <button>Popover trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface tabIndex={-1} id="popover-surface">
+            <button>One</button>
+            <button>Two</button>
+          </PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get(popoverTriggerSelector).focus().realPress('Enter');
+
+      cy.get('#popover-surface').should('have.focus').realPress('Tab');
+      cy.contains('One').should('have.focus').realPress('Tab');
+      cy.contains('Two').should('have.focus').realPress('Tab');
+      cy.contains('One').should('have.focus').realPress(['Shift', 'Tab']);
+      cy.contains('Two').should('have.focus');
+    });
+  });
+
+  describe('Focus restoration', () => {
+    it('should restore focus to trigger on close', () => {
+      mount(
+        <Popover>
+          <PopoverTrigger>
+            <button id="trigger">trigger</button>
+          </PopoverTrigger>
+          <PopoverSurface>
+            <button id="button">button</button>
+          </PopoverSurface>
+        </Popover>,
+      );
+
+      cy.get('#trigger')
+        .click()
+        .get(popoverContentSelector)
+        .should('exist')
+        .get('#button')
+        .focus()
+        .type('{esc}')
+        .get(popoverContentSelector)
+        .should('not.exist')
+        .get('#trigger')
+        .should('have.focus');
+    });
+  });
+
+  describe('with Iframe', () => {
+    const iframeContent = `<div id="iframecontent">
+  <button>Hello World!</button>
+</div>`;
+
+    const ExampleFrame = () => {
+      return <iframe title="frame" srcDoc={iframeContent} />;
+    };
+
+    it('should close when focus is on an external iframe', () => {
+      mount(
+        <>
+          <ExampleFrame />
+          <div />
+          <Popover>
+            <PopoverTrigger disableButtonEnhancement>
+              <button>Popover trigger</button>
+            </PopoverTrigger>
+            <PopoverSurface>This is a popover</PopoverSurface>
+          </Popover>
+        </>,
+      );
+
+      cy.get(popoverTriggerSelector).click().get('iframe').focus().get(popoverContentSelector).should('not.exist');
+    });
+
+    it('should not close when focus is on an internal iframe', () => {
+      mount(
+        <>
+          <Popover>
+            <PopoverTrigger disableButtonEnhancement>
+              <button>Popover trigger</button>
+            </PopoverTrigger>
+            <PopoverSurface>
+              <ExampleFrame />
+            </PopoverSurface>
+          </Popover>
+        </>,
+      );
+
+      cy.get(popoverTriggerSelector)
+        .click()
+        .get('iframe')
+        .focus()
+        .wait(2000)
+        .get(popoverContentSelector)
+        .should('exist');
+    });
+
+    it('should not close when focus is on an internal iframe in a nested popover', () => {
+      mount(
+        <>
+          <Popover>
+            <PopoverTrigger disableButtonEnhancement>
+              <button>First</button>
+            </PopoverTrigger>
+            <PopoverSurface>
+              <Popover>
+                <PopoverTrigger>
+                  <button>Second</button>
+                </PopoverTrigger>
+                <PopoverSurface>
+                  <ExampleFrame />
+                </PopoverSurface>
+              </Popover>
+            </PopoverSurface>
+          </Popover>
+        </>,
+      );
+
+      cy.get(popoverTriggerSelector)
+        .first()
+        .click()
+        .get(popoverTriggerSelector)
+        .eq(1)
+        .click()
+        .get('iframe')
+        .focus()
+        .wait(2000)
+        .get(popoverContentSelector)
+        .should('have.length', 2);
+    });
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
new file mode 100644
index 00000000000000..95ea877c0f663a
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
@@ -0,0 +1,234 @@
+import * as React from 'react';
+import { render, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Popover } from './Popover';
+import { PopoverTrigger } from './PopoverTrigger/PopoverTrigger';
+import { PopoverSurface } from './PopoverSurface/PopoverSurface';
+
+beforeAll(() => {
+  HTMLElement.prototype.showPopover = jest.fn();
+  HTMLElement.prototype.hidePopover = jest.fn();
+
+  // JSDOM does not implement ResizeObserver
+  global.ResizeObserver = class ResizeObserver {
+    public observe(): void {
+      /* no-op */
+    }
+    public unobserve(): void {
+      /* no-op */
+    }
+    public disconnect(): void {
+      /* no-op */
+    }
+  } as unknown as typeof globalThis.ResizeObserver;
+});
+
+afterAll(() => {
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).showPopover;
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).hidePopover;
+  delete (global as unknown as Record<string, unknown>).ResizeObserver;
+});
+
+describe('Popover', () => {
+  it('renders trigger and surface children', () => {
+    const { getByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toBeInTheDocument();
+    expect(getByText('Surface content')).toBeInTheDocument();
+  });
+
+  it('opens on trigger click (uncontrolled)', () => {
+    const { getByText, queryByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(queryByText('Surface content')).not.toBeInTheDocument();
+
+    userEvent.click(getByText('Trigger'));
+
+    expect(getByText('Surface content')).toBeInTheDocument();
+  });
+
+  it('closes on trigger click when open', () => {
+    const { getByText, queryByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Surface content')).toBeInTheDocument();
+
+    userEvent.click(getByText('Trigger'));
+
+    expect(queryByText('Surface content')).not.toBeInTheDocument();
+  });
+
+  it('fires onOpenChange callback', () => {
+    const onOpenChange = jest.fn();
+
+    const { getByText } = render(
+      <Popover onOpenChange={onOpenChange}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    userEvent.click(getByText('Trigger'));
+
+    expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: true }));
+  });
+
+  it('supports controlled open state', () => {
+    const { getByText, queryByText, rerender } = render(
+      <Popover open={false}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(queryByText('Surface')).not.toBeInTheDocument();
+
+    rerender(
+      <Popover open={true}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Surface')).toBeInTheDocument();
+  });
+
+  it('sets aria-expanded on trigger', () => {
+    const { getByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    const trigger = getByText('Trigger');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    userEvent.click(trigger);
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('sets data-open on trigger when open', () => {
+    const { getByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toHaveAttribute('data-open');
+  });
+
+  it('sets role="dialog" and aria-modal on surface when trapFocus', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen trapFocus>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    const surface = getByRole('dialog');
+    expect(surface).toHaveAttribute('aria-modal', 'true');
+  });
+
+  it('sets role="group" on surface when no trapFocus', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toBeInTheDocument();
+  });
+
+  it('sets data-open attribute on surface', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toHaveAttribute('data-open');
+  });
+
+  it('closes on Escape key', () => {
+    const { getByRole, queryByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    const surface = getByRole('group');
+    fireEvent.keyDown(surface, { key: 'Escape' });
+
+    expect(queryByText('Surface')).not.toBeInTheDocument();
+  });
+
+  it('sets popover="manual" on surface by default', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toHaveAttribute('popover', 'manual');
+  });
+
+  it('does not set popover attribute when inline', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen inline>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).not.toHaveAttribute('popover');
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
new file mode 100644
index 00000000000000..563b7fe586b650
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
@@ -0,0 +1,22 @@
+'use client';
+
+import type { PopoverProps } from './Popover.types';
+import type { JSXElement } from '@fluentui/react-utilities';
+import { usePopover, usePopoverContextValues } from './usePopover';
+import { renderPopover } from './renderPopover';
+
+/**
+ * Headless Popover component.
+ *
+ * Provides unstyled popover behavior with native browser APIs.
+ * Uses HTML popover attribute for top-layer rendering and
+ * CSS anchor positioning for placement.
+ */
+export const Popover = (props: PopoverProps): JSXElement => {
+  const state = usePopover(props, null);
+  const contextValues = usePopoverContextValues(state);
+
+  return renderPopover(state, contextValues);
+};
+
+Popover.displayName = 'Popover';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
new file mode 100644
index 00000000000000..d58af7ca8f08a6
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
@@ -0,0 +1,195 @@
+import type * as React from 'react';
+import type { ComponentProps, ComponentState, EventData, EventHandler, Slot } from '@fluentui/react-utilities';
+import type { PositioningShorthand, PositioningReturn } from '../../hooks/usePositioning';
+
+/**
+ * Events that can trigger Popover open/close changes.
+ */
+export type OpenPopoverEvents =
+  | MouseEvent
+  | TouchEvent
+  | React.FocusEvent<HTMLElement>
+  | React.KeyboardEvent<HTMLElement>
+  | React.MouseEvent<HTMLElement>;
+
+/**
+ * Data attached to open/close events. Uses the canonical `EventData` shape so
+ * consumers can discriminate on `type` or use the handler directly via
+ * `EventHandler<OnOpenChangeData>`.
+ */
+export type OnOpenChangeData = EventData<string, React.SyntheticEvent | Event> & { open: boolean };
+
+/**
+ * Popover Props
+ */
+export type PopoverProps = {
+  /**
+   * Can contain two children including PopoverTrigger and PopoverSurface.
+   * Alternatively can only contain PopoverSurface if using a custom target.
+   */
+  children: [React.ReactElement, React.ReactElement] | React.ReactElement;
+
+  /** Controlled open state. */
+  open?: boolean;
+
+  /**
+   * Default open state for uncontrolled mode.
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /** Callback when the open state changes. */
+  onOpenChange?: EventHandler<OnOpenChangeData>;
+
+  /**
+   * Open on hover.
+   * @default false
+   */
+  openOnHover?: boolean;
+
+  /**
+   * Open on context menu (right-click).
+   * @default false
+   */
+  openOnContext?: boolean;
+
+  /**
+   * Delay in ms before closing on mouse leave.
+   * @default 500
+   */
+  mouseLeaveDelay?: number;
+
+  /**
+   * Positioning configuration. Accepts either a full `PositioningProps`
+   * object or a shorthand string such as `'below'` / `'above-end'`.
+   */
+  positioning?: PositioningShorthand;
+
+  /**
+   * Display an arrow pointing to the target.
+   * @default false
+   */
+  withArrow?: boolean;
+
+  /**
+   * Enable focus trap.
+   * @default false
+   */
+  trapFocus?: boolean;
+
+  /**
+   * By default Popover focuses the first focusable element in `PopoverSurface` on open.
+   * Set this to prevent that behavior.
+   *
+   * @default false
+   */
+  disableAutoFocus?: boolean;
+
+  /**
+   * Close when scrolling outside.
+   * @default false
+   */
+  closeOnScroll?: boolean;
+
+  /**
+   * Close when an iframe outside focuses.
+   * @default true
+   */
+  closeOnIframeFocus?: boolean;
+
+  /**
+   * Render inline instead of using native popover top-layer.
+   * @default false
+   */
+  inline?: boolean;
+
+  /**
+   * DOM node where the `PopoverSurface` is rendered. When provided, the surface is
+   * portaled to that node; when omitted, the surface renders in place in the
+   * component tree. The native HTML popover top layer still handles visual
+   * elevation, so this controls DOM placement rather than stacking.
+   */
+  mountNode?: HTMLElement | null;
+};
+
+/**
+ * Popover State
+ */
+export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> &
+  Pick<
+    PopoverProps,
+    'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'
+  > & {
+    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
+    toggleOpen: (e: OpenPopoverEvents) => void;
+    triggerRef: React.RefObject<HTMLElement | null>;
+    contentRef: React.RefObject<HTMLElement | null>;
+    arrowRef: React.RefObject<HTMLDivElement | null>;
+    popoverTrigger: React.ReactElement | undefined;
+    popoverSurface: React.ReactElement | undefined;
+    contextTarget: { x: number; y: number } | undefined;
+    setContextTarget: (target: { x: number; y: number } | undefined) => void;
+    positioning: PositioningReturn;
+  };
+
+/**
+ * PopoverTrigger Props
+ */
+export type PopoverTriggerProps = {
+  children: React.ReactElement;
+  /**
+   * Disable ARIA button enhancement on the trigger.
+   * @default false
+   */
+  disableButtonEnhancement?: boolean;
+};
+
+/**
+ * PopoverTrigger State
+ */
+export type PopoverTriggerState = {
+  children: React.ReactElement | null;
+};
+
+/**
+ * PopoverSurface Slots
+ */
+export type PopoverSurfaceSlots = {
+  root: Slot<'div'>;
+};
+
+export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
+
+export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
+  inline: boolean;
+  withArrow: boolean | undefined;
+  arrowRef: React.RefObject<HTMLDivElement | null>;
+  mountNode: HTMLElement | null | undefined;
+  'data-open': string;
+};
+
+/**
+ * Context shared between Popover and its children.
+ */
+export type PopoverContextValue = Pick<
+  PopoverState,
+  | 'open'
+  | 'setOpen'
+  | 'toggleOpen'
+  | 'triggerRef'
+  | 'contentRef'
+  | 'arrowRef'
+  | 'openOnHover'
+  | 'openOnContext'
+  | 'trapFocus'
+  | 'disableAutoFocus'
+  | 'withArrow'
+  | 'inline'
+  | 'mountNode'
+> & {
+  positioning: {
+    targetRef: React.RefCallback<HTMLElement>;
+    containerRef: React.RefCallback<HTMLElement>;
+    arrowRef: React.RefCallback<HTMLElement>;
+  };
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
new file mode 100644
index 00000000000000..9138c90cece987
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
@@ -0,0 +1,165 @@
+import * as React from 'react';
+import { render, fireEvent } from '@testing-library/react';
+import { Popover } from '../Popover';
+import { PopoverTrigger } from '../PopoverTrigger/PopoverTrigger';
+import { PopoverSurface } from './PopoverSurface';
+
+beforeAll(() => {
+  HTMLElement.prototype.showPopover = jest.fn();
+  HTMLElement.prototype.hidePopover = jest.fn();
+
+  global.ResizeObserver = class ResizeObserver {
+    public observe(): void {
+      /* no-op */
+    }
+    public unobserve(): void {
+      /* no-op */
+    }
+    public disconnect(): void {
+      /* no-op */
+    }
+  } as unknown as typeof globalThis.ResizeObserver;
+});
+
+afterAll(() => {
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).showPopover;
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).hidePopover;
+  delete (global as unknown as Record<string, unknown>).ResizeObserver;
+});
+
+describe('PopoverSurface', () => {
+  it('renders surface content', () => {
+    const { getByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Surface content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Surface content')).toBeInTheDocument();
+  });
+
+  it('has role="group" by default', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toBeInTheDocument();
+  });
+
+  it('has role="dialog" when trapFocus is enabled', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen trapFocus>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('dialog')).toBeInTheDocument();
+  });
+
+  it('has aria-modal="true" when trapFocus is enabled', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen trapFocus>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
+  });
+
+  it('has data-open attribute when open', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toHaveAttribute('data-open');
+  });
+
+  it('has popover="manual" attribute by default', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toHaveAttribute('popover', 'manual');
+  });
+
+  it('does not have popover attribute when inline', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen inline>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).not.toHaveAttribute('popover');
+  });
+
+  it('closes on Escape key within surface', () => {
+    const onOpenChange = jest.fn();
+
+    const { getByRole } = render(
+      <Popover defaultOpen onOpenChange={onOpenChange}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    fireEvent.keyDown(getByRole('group'), { key: 'Escape' });
+    expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: false }));
+  });
+
+  it('renders arrow when withArrow is set', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen withArrow>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    const surface = getByRole('group');
+    // Arrow is the first child div before content
+    expect(surface.firstElementChild?.tagName).toBe('DIV');
+  });
+
+  it('applies custom className', () => {
+    const { getByRole } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface className="my-surface">Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByRole('group')).toHaveClass('my-surface');
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.tsx
new file mode 100644
index 00000000000000..b8050b7c43c588
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+import * as React from 'react';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import type { PopoverSurfaceProps } from './PopoverSurface.types';
+import { usePopoverSurface } from './usePopoverSurface';
+import { renderPopoverSurface } from './renderPopoverSurface';
+
+/**
+ * Headless PopoverSurface component.
+ *
+ * Renders the popover content area using native HTML popover attribute
+ * for top-layer rendering.
+ */
+export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps> = React.forwardRef((props, ref) => {
+  const state = usePopoverSurface(props, ref);
+  return renderPopoverSurface(state);
+});
+
+PopoverSurface.displayName = 'PopoverSurface';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.types.ts
new file mode 100644
index 00000000000000..203c6095544778
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.types.ts
@@ -0,0 +1 @@
+export type { PopoverSurfaceSlots, PopoverSurfaceProps, PopoverSurfaceState } from '../Popover.types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/index.ts
new file mode 100644
index 00000000000000..4ea02c09f2653b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/index.ts
@@ -0,0 +1,4 @@
+export { PopoverSurface } from './PopoverSurface';
+export { usePopoverSurface } from './usePopoverSurface';
+export { renderPopoverSurface } from './renderPopoverSurface';
+export type { PopoverSurfaceSlots, PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/renderPopoverSurface.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/renderPopoverSurface.tsx
new file mode 100644
index 00000000000000..a4f3bb501c447f
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/renderPopoverSurface.tsx
@@ -0,0 +1,24 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource @fluentui/react-jsx-runtime */
+
+import * as ReactDOM from 'react-dom';
+import { assertSlots } from '@fluentui/react-utilities';
+import type { PopoverSurfaceSlots, PopoverSurfaceState } from './PopoverSurface.types';
+import type { JSXElement } from '@fluentui/react-utilities';
+
+/**
+ * Renders the PopoverSurface component. Portals to `state.mountNode` when
+ * provided; otherwise renders in place.
+ */
+export const renderPopoverSurface = (state: PopoverSurfaceState): JSXElement => {
+  assertSlots<PopoverSurfaceSlots>(state);
+
+  const surface = (
+    <state.root>
+      {state.withArrow && <div ref={state.arrowRef} data-arrow="" />}
+      {state.root.children}
+    </state.root>
+  );
+
+  return state.mountNode ? ReactDOM.createPortal(surface, state.mountNode) : surface;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
new file mode 100644
index 00000000000000..16b28d6e5df116
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
@@ -0,0 +1,111 @@
+'use client';
+
+import type * as React from 'react';
+import { useMergedRefs, slot, useEventCallback } from '@fluentui/react-utilities';
+import { usePopoverContext } from '../popoverContext';
+import { useFocusScope } from '../../../hooks';
+import { stringifyDataAttribute } from '../../../utils';
+import type { PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.types';
+
+/**
+ * Returns the state for a PopoverSurface component.
+ */
+export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTMLDivElement>): PopoverSurfaceState => {
+  const contentRef = usePopoverContext(context => context.contentRef);
+  const openOnHover = usePopoverContext(context => context.openOnHover);
+  const setOpen = usePopoverContext(context => context.setOpen);
+  const arrowRef = usePopoverContext(context => context.arrowRef);
+  const withArrow = usePopoverContext(context => context.withArrow);
+  const trapFocus = usePopoverContext(context => context.trapFocus);
+  const disableAutoFocus = usePopoverContext(context => context.disableAutoFocus);
+  const inline = usePopoverContext(context => context.inline);
+  const open = usePopoverContext(context => context.open);
+  const mountNode = usePopoverContext(context => context.mountNode);
+  const positioningCtx = usePopoverContext(context => context.positioning);
+  const tabIndex = typeof props.tabIndex === 'number' ? props.tabIndex : undefined;
+
+  const onMountAutoFocus = useEventCallback((event: Event) => {
+    if (disableAutoFocus) {
+      event.preventDefault();
+      return;
+    }
+
+    if (tabIndex !== undefined) {
+      event.preventDefault();
+      contentRef.current?.focus({ preventScroll: true });
+    }
+  });
+
+  const focusScope = useFocusScope({
+    trapped: trapFocus,
+    loop: trapFocus,
+    onMountAutoFocus,
+  });
+
+  const mergedArrowRef = useMergedRefs(arrowRef, positioningCtx.arrowRef);
+
+  const state: PopoverSurfaceState = {
+    inline,
+    withArrow,
+    arrowRef: mergedArrowRef as React.RefObject<HTMLDivElement | null>,
+    mountNode,
+    components: { root: 'div' },
+    root: slot.always(
+      {
+        ref: useMergedRefs(
+          ref,
+          contentRef,
+          positioningCtx.containerRef,
+          focusScope.containerRef,
+        ) as React.Ref<HTMLDivElement>,
+        role: trapFocus ? 'dialog' : 'group',
+        'aria-modal': trapFocus ? true : undefined,
+        tabIndex: focusScope.containerProps.tabIndex,
+        ...props,
+        'data-popover-surface': '',
+        'data-open': stringifyDataAttribute(open),
+      },
+      { elementType: 'div' },
+    ),
+    'data-open': open ? 'true' : 'false',
+  };
+
+  const {
+    onMouseEnter: onMouseEnterOriginal,
+    onMouseLeave: onMouseLeaveOriginal,
+    onKeyDown: onKeyDownOriginal,
+  } = state.root;
+
+  state.root.onMouseEnter = useEventCallback((e: React.MouseEvent<HTMLDivElement>) => {
+    if (openOnHover) {
+      setOpen(e, true);
+    }
+    onMouseEnterOriginal?.(e);
+  });
+
+  state.root.onMouseLeave = useEventCallback((e: React.MouseEvent<HTMLDivElement>) => {
+    if (openOnHover) {
+      setOpen(e, false);
+    }
+    onMouseLeaveOriginal?.(e);
+  });
+
+  const focusScopeKeyDown = focusScope.containerProps.onKeyDown;
+
+  state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
+    focusScopeKeyDown(e);
+
+    if (e.key === 'Escape') {
+      const target = e.target as HTMLElement;
+      const surface = contentRef.current;
+      if (surface && target.closest('[data-popover-surface]') === surface) {
+        e.preventDefault();
+        setOpen(e, false);
+      }
+    }
+
+    onKeyDownOriginal?.(e);
+  });
+
+  return state;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
new file mode 100644
index 00000000000000..b0fd5feda238d3
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
@@ -0,0 +1,140 @@
+import * as React from 'react';
+import { render, fireEvent } from '@testing-library/react';
+import { Popover } from '../Popover';
+import { PopoverTrigger } from './PopoverTrigger';
+import { PopoverSurface } from '../PopoverSurface/PopoverSurface';
+
+beforeAll(() => {
+  HTMLElement.prototype.showPopover = jest.fn();
+  HTMLElement.prototype.hidePopover = jest.fn();
+
+  global.ResizeObserver = class ResizeObserver {
+    public observe(): void {
+      /* no-op */
+    }
+    public unobserve(): void {
+      /* no-op */
+    }
+    public disconnect(): void {
+      /* no-op */
+    }
+  } as unknown as typeof globalThis.ResizeObserver;
+});
+
+afterAll(() => {
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).showPopover;
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>).hidePopover;
+  delete (global as unknown as Record<string, unknown>).ResizeObserver;
+});
+
+describe('PopoverTrigger', () => {
+  it('renders the child element', () => {
+    const { getByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Click me</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('applies aria-expanded attribute', () => {
+    const { getByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('applies aria-haspopup="true" by default', () => {
+    const { getByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toHaveAttribute('aria-haspopup', 'true');
+  });
+
+  it('applies aria-haspopup="dialog" when trapFocus', () => {
+    const { getByText } = render(
+      <Popover trapFocus>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toHaveAttribute('aria-haspopup', 'dialog');
+  });
+
+  it('applies data-open when popover is open', () => {
+    const { getByText } = render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).toHaveAttribute('data-open');
+  });
+
+  it('does not have data-open when popover is closed', () => {
+    const { getByText } = render(
+      <Popover>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    expect(getByText('Trigger')).not.toHaveAttribute('data-open');
+  });
+
+  it('toggles popover on click', () => {
+    const onOpenChange = jest.fn();
+
+    const { getByText } = render(
+      <Popover onOpenChange={onOpenChange}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    fireEvent.click(getByText('Trigger'));
+    expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: true }));
+  });
+
+  it('closes on Escape key press', () => {
+    const onOpenChange = jest.fn();
+
+    const { getByText } = render(
+      <Popover defaultOpen onOpenChange={onOpenChange}>
+        <PopoverTrigger>
+          <button>Trigger</button>
+        </PopoverTrigger>
+        <PopoverSurface>Content</PopoverSurface>
+      </Popover>,
+    );
+
+    fireEvent.keyDown(getByText('Trigger'), { key: 'Escape' });
+    expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: false }));
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.tsx
new file mode 100644
index 00000000000000..f4a978749628c1
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.tsx
@@ -0,0 +1,19 @@
+'use client';
+
+import type * as React from 'react';
+import type { PopoverTriggerProps } from './PopoverTrigger.types';
+import { usePopoverTrigger } from './usePopoverTrigger';
+import { renderPopoverTrigger } from './renderPopoverTrigger';
+
+/**
+ * Headless PopoverTrigger component.
+ *
+ * Wraps a trigger element, applying event handlers and ARIA attributes
+ * for popover interaction.
+ */
+export const PopoverTrigger: React.FC<PopoverTriggerProps> = props => {
+  const state = usePopoverTrigger(props);
+  return renderPopoverTrigger(state);
+};
+
+PopoverTrigger.displayName = 'PopoverTrigger';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.types.ts
new file mode 100644
index 00000000000000..41a1195a14fcce
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.types.ts
@@ -0,0 +1 @@
+export type { PopoverTriggerProps, PopoverTriggerState } from '../Popover.types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/index.ts
new file mode 100644
index 00000000000000..1d9c59eb776ff9
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/index.ts
@@ -0,0 +1,4 @@
+export { PopoverTrigger } from './PopoverTrigger';
+export { usePopoverTrigger } from './usePopoverTrigger';
+export { renderPopoverTrigger } from './renderPopoverTrigger';
+export type { PopoverTriggerProps, PopoverTriggerState } from './PopoverTrigger.types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
new file mode 100644
index 00000000000000..f802782cbd0dd8
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
@@ -0,0 +1,9 @@
+import type * as React from 'react';
+import type { PopoverTriggerState } from './PopoverTrigger.types';
+
+/**
+ * Renders the PopoverTrigger (returns the cloned child element).
+ */
+export const renderPopoverTrigger = (state: PopoverTriggerState): React.ReactElement | null => {
+  return state.children;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
new file mode 100644
index 00000000000000..eb084b81ef1578
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
@@ -0,0 +1,103 @@
+'use client';
+
+import type * as React from 'react';
+import {
+  applyTriggerPropsToChildren,
+  getTriggerChild,
+  getReactElementRef,
+  mergeCallbacks,
+  useMergedRefs,
+  useEventCallback,
+} from '@fluentui/react-utilities';
+import { useARIAButtonProps } from '@fluentui/react-aria';
+import { Escape } from '@fluentui/keyboard-keys';
+import { usePopoverContext } from '../popoverContext';
+import { stringifyDataAttribute } from '../../../utils';
+import type { PopoverTriggerProps, PopoverTriggerState } from './PopoverTrigger.types';
+
+/**
+ * Returns the state for a PopoverTrigger component.
+ * Applies event handlers and ARIA attributes to the child element.
+ */
+export const usePopoverTrigger = (props: PopoverTriggerProps): PopoverTriggerState => {
+  const { children, disableButtonEnhancement = false } = props;
+  const child = getTriggerChild(children);
+
+  const open = usePopoverContext(context => context.open);
+  const setOpen = usePopoverContext(context => context.setOpen);
+  const toggleOpen = usePopoverContext(context => context.toggleOpen);
+  const triggerRef = usePopoverContext(context => context.triggerRef);
+  const openOnHover = usePopoverContext(context => context.openOnHover);
+  const openOnContext = usePopoverContext(context => context.openOnContext);
+  const trapFocus = usePopoverContext(context => context.trapFocus);
+  const positioningCtx = usePopoverContext(context => context.positioning);
+
+  const onContextMenu = (e: React.MouseEvent<HTMLElement>) => {
+    if (openOnContext) {
+      e.preventDefault();
+      setOpen(e, true);
+    }
+  };
+
+  const onClick = (e: React.MouseEvent<HTMLElement>) => {
+    if (!openOnContext) {
+      toggleOpen(e);
+    }
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLElement>) => {
+    if (e.key === Escape && open && !e.isDefaultPrevented()) {
+      setOpen(e, false);
+      e.preventDefault();
+    }
+  };
+
+  const onMouseEnter = (e: React.MouseEvent<HTMLElement>) => {
+    if (openOnHover) {
+      setOpen(e, true);
+    }
+  };
+
+  const onMouseLeave = (e: React.MouseEvent<HTMLElement>) => {
+    if (openOnHover) {
+      setOpen(e, false);
+    }
+  };
+
+  const childProps = (child?.props ?? {}) as Record<string, unknown>;
+
+  const triggerChildProps = {
+    'aria-expanded': `${open}` as 'true' | 'false',
+    'aria-haspopup': (trapFocus ? 'dialog' : 'true') as 'dialog' | 'true',
+    'data-open': stringifyDataAttribute(open),
+    ...child?.props,
+    onMouseEnter: useEventCallback(
+      mergeCallbacks(childProps.onMouseEnter as React.MouseEventHandler<HTMLElement> | undefined, onMouseEnter),
+    ),
+    onMouseLeave: useEventCallback(
+      mergeCallbacks(childProps.onMouseLeave as React.MouseEventHandler<HTMLElement> | undefined, onMouseLeave),
+    ),
+    onContextMenu: useEventCallback(
+      mergeCallbacks(childProps.onContextMenu as React.MouseEventHandler<HTMLElement> | undefined, onContextMenu),
+    ),
+    onClick: useEventCallback(
+      mergeCallbacks(childProps.onClick as React.MouseEventHandler<HTMLElement> | undefined, onClick),
+    ),
+    onKeyDown: useEventCallback(
+      mergeCallbacks(childProps.onKeyDown as React.KeyboardEventHandler<HTMLElement> | undefined, onKeyDown),
+    ),
+    ref: useMergedRefs(triggerRef, positioningCtx.targetRef, getReactElementRef(child)),
+  };
+
+  const ariaButtonProps = useARIAButtonProps(
+    child?.type === 'button' || child?.type === 'a' ? child.type : 'div',
+    triggerChildProps,
+  );
+
+  return {
+    children: applyTriggerPropsToChildren(
+      children,
+      openOnContext ? triggerChildProps : disableButtonEnhancement ? triggerChildProps : ariaButtonProps,
+    ),
+  };
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
new file mode 100644
index 00000000000000..eb77fa652f7646
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
@@ -0,0 +1,17 @@
+export { Popover } from './Popover';
+export { renderPopover } from './renderPopover';
+export { usePopover, usePopoverContextValues } from './usePopover';
+export { usePopoverContext } from './popoverContext';
+export type {
+  PopoverProps,
+  PopoverState,
+  PopoverContextValue,
+  OpenPopoverEvents,
+  OnOpenChangeData,
+} from './Popover.types';
+
+export { PopoverTrigger, usePopoverTrigger, renderPopoverTrigger } from './PopoverTrigger';
+export type { PopoverTriggerProps, PopoverTriggerState } from './PopoverTrigger';
+
+export { PopoverSurface, usePopoverSurface, renderPopoverSurface } from './PopoverSurface';
+export type { PopoverSurfaceSlots, PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
new file mode 100644
index 00000000000000..7b77492f5ebfc5
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
@@ -0,0 +1,38 @@
+'use client';
+
+import { createContext, useContextSelector } from '@fluentui/react-context-selector';
+import type { ContextSelector, Context } from '@fluentui/react-context-selector';
+import type { PopoverContextValue } from './Popover.types';
+
+export const PopoverContext: Context<PopoverContextValue> = createContext<PopoverContextValue | undefined>(
+  undefined,
+) as Context<PopoverContextValue>;
+
+const popoverContextDefaultValue: PopoverContextValue = {
+  open: false,
+  setOpen: () => null,
+  toggleOpen: () => null,
+  triggerRef: { current: null },
+  contentRef: { current: null },
+  arrowRef: { current: null },
+  openOnContext: false,
+  openOnHover: false,
+  trapFocus: false,
+  disableAutoFocus: false,
+  withArrow: false,
+  inline: false,
+  mountNode: null,
+  positioning: {
+    targetRef: () => undefined,
+    containerRef: () => undefined,
+    arrowRef: () => undefined,
+  },
+};
+
+export const PopoverProvider = PopoverContext.Provider;
+
+/**
+ * Hook to consume PopoverContext with a selector for optimized re-renders.
+ */
+export const usePopoverContext = <T>(selector: ContextSelector<PopoverContextValue, T>): T =>
+  useContextSelector(PopoverContext, (ctx = popoverContextDefaultValue) => selector(ctx));
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/renderPopover.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/renderPopover.tsx
new file mode 100644
index 00000000000000..08e1c00828f48f
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/renderPopover.tsx
@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { PopoverProvider } from './popoverContext';
+import type { PopoverState, PopoverContextValue } from './Popover.types';
+
+/**
+ * Renders the Popover component by wrapping children with the PopoverContext.Provider.
+ * The surface portals itself via `mountNode` from context — no portal here.
+ */
+export const renderPopover = (
+  state: PopoverState,
+  contextValues: { popover: PopoverContextValue },
+): React.ReactElement => (
+  <PopoverProvider value={contextValues.popover}>
+    {state.popoverTrigger}
+    {state.open ? state.popoverSurface : null}
+  </PopoverProvider>
+);
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
new file mode 100644
index 00000000000000..277ec3c4f93e9f
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -0,0 +1,210 @@
+'use client';
+
+import * as React from 'react';
+import {
+  useControllableState,
+  useEventCallback,
+  useOnClickOutside,
+  useOnScrollOutside,
+  elementContains,
+  useTimeout,
+} from '@fluentui/react-utilities';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import { usePositioning, resolvePositioningShorthand } from '../../hooks';
+import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents } from './Popover.types';
+
+/**
+ * Returns the state for a Popover component, given its props and ref.
+ */
+export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): PopoverState => {
+  const {
+    openOnHover = false,
+    openOnContext = false,
+    mouseLeaveDelay = 500,
+    withArrow = false,
+    trapFocus = false,
+    disableAutoFocus = false,
+    closeOnScroll = false,
+    closeOnIframeFocus = true,
+    inline = false,
+    mountNode,
+  } = props;
+
+  const [open, setOpenState] = useControllableState({
+    state: props.open,
+    defaultState: props.defaultOpen,
+    initialState: false,
+  });
+
+  const [contextTarget, setContextTarget] = React.useState<{ x: number; y: number } | undefined>(undefined);
+  const { targetDocument } = useFluent();
+
+  const onOpenChange = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
+    props.onOpenChange?.(e, { event: e, type: e.type, open: shouldOpen });
+  });
+
+  const [setOpenTimeout, clearOpenTimeout] = useTimeout();
+
+  const setOpen = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
+    clearOpenTimeout();
+
+    if (shouldOpen && e.type === 'contextmenu') {
+      const mouseEvent = e as React.MouseEvent<HTMLElement>;
+      setContextTarget({ x: mouseEvent.clientX, y: mouseEvent.clientY });
+    }
+
+    if (!shouldOpen) {
+      setContextTarget(undefined);
+    }
+
+    if (e.type === 'mouseleave') {
+      setOpenTimeout(() => {
+        setOpenState(shouldOpen);
+        onOpenChange(e, shouldOpen);
+      }, mouseLeaveDelay);
+    } else {
+      setOpenState(shouldOpen);
+      onOpenChange(e, shouldOpen);
+    }
+  });
+
+  const toggleOpen = React.useCallback(
+    (e: OpenPopoverEvents) => {
+      setOpen(e, !open);
+    },
+    [setOpen, open],
+  );
+
+  const triggerRef = React.useRef<HTMLElement>(null);
+  const contentRef = React.useRef<HTMLElement>(null);
+  const arrowRef = React.useRef<HTMLDivElement>(null);
+
+  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
+
+  useOnClickOutside({
+    contains: elementContains,
+    element: targetDocument,
+    callback: ev => setOpen(ev, false),
+    refs: [triggerRef, contentRef],
+    disabled: !open,
+    disabledFocusOnIframe: !closeOnIframeFocus,
+  });
+
+  useOnScrollOutside({
+    contains: elementContains,
+    element: targetDocument,
+    callback: ev => setOpen(ev, false),
+    refs: [triggerRef, contentRef],
+    disabled: !open || !(openOnContext || closeOnScroll),
+  });
+
+  React.useEffect(() => {
+    const surface = contentRef.current;
+
+    if (!surface || inline || !open) {
+      return;
+    }
+
+    // Feature-detect the native Popover API — it's only available in
+    // Chrome 114+, Safari 17+, Firefox 125+. Older browsers fall back to
+    // in-flow rendering (the surface is still rendered in the DOM; top-layer
+    // elevation just isn't available).
+    if (typeof surface.showPopover !== 'function') {
+      return;
+    }
+
+    if (!surface.hasAttribute('popover')) {
+      surface.setAttribute('popover', 'manual');
+    }
+
+    surface.showPopover();
+  }, [open, inline]);
+
+  const children = React.Children.toArray(props.children) as React.ReactElement[];
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (children.length === 0) {
+      // eslint-disable-next-line no-console
+      console.warn('Popover must contain at least one child');
+    }
+
+    if (children.length > 2) {
+      // eslint-disable-next-line no-console
+      console.warn('Popover must contain at most two children');
+    }
+  }
+
+  let popoverTrigger: React.ReactElement | undefined;
+  let popoverSurface: React.ReactElement | undefined;
+
+  if (children.length === 2) {
+    popoverTrigger = children[0];
+    popoverSurface = children[1];
+  } else if (children.length === 1) {
+    popoverSurface = children[0];
+  }
+
+  return {
+    open,
+    setOpen,
+    toggleOpen,
+    triggerRef,
+    contentRef,
+    arrowRef,
+    popoverTrigger,
+    popoverSurface,
+    openOnHover,
+    openOnContext,
+    trapFocus,
+    withArrow,
+    disableAutoFocus,
+    inline,
+    mountNode,
+    onOpenChange: props.onOpenChange,
+    contextTarget,
+    setContextTarget,
+    positioning,
+  };
+};
+
+export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
+  const {
+    open,
+    setOpen,
+    toggleOpen,
+    triggerRef,
+    contentRef,
+    arrowRef,
+    openOnHover,
+    openOnContext,
+    trapFocus,
+    disableAutoFocus,
+    withArrow,
+    inline,
+    mountNode,
+    positioning,
+  } = state;
+
+  return {
+    popover: {
+      open,
+      setOpen,
+      toggleOpen,
+      triggerRef,
+      contentRef,
+      arrowRef,
+      openOnHover,
+      openOnContext,
+      trapFocus,
+      disableAutoFocus,
+      withArrow,
+      inline,
+      mountNode,
+      positioning: {
+        targetRef: positioning.targetRef,
+        containerRef: positioning.containerRef,
+        arrowRef: positioning.arrowRef,
+      },
+    },
+  };
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
new file mode 100644
index 00000000000000..081ca84ec54c13
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
@@ -0,0 +1,13 @@
+export { usePositioning } from './usePositioning';
+export { useFocusScope } from './useFocusScope';
+export type { UseFocusScopeOptions, UseFocusScopeReturn } from './useFocusScope';
+export type {
+  Position,
+  Alignment,
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from './usePositioning';
+export { POSITIONS, ALIGNMENTS, getPlacementString, resolvePositioningShorthand } from './usePositioning';
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
new file mode 100644
index 00000000000000..17525f5e44d910
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
@@ -0,0 +1,428 @@
+'use client';
+
+import * as React from 'react';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import { isHTMLElement } from '@fluentui/react-utilities';
+
+const AUTOFOCUS_ON_MOUNT = 'focusScope.autoFocusOnMount';
+const AUTOFOCUS_ON_UNMOUNT = 'focusScope.autoFocusOnUnmount';
+const EVENT_OPTIONS = { bubbles: false, cancelable: true };
+
+export interface UseFocusScopeOptions {
+  /**
+   * When `true`, tabbing from the last item will focus the first tabbable element,
+   * and shift+tab from the first item will focus the last tabbable.
+   * @defaultValue false
+   */
+  loop?: boolean;
+
+  /**
+   * When `true`, focus cannot escape the scope via keyboard, pointer,
+   * or programmatic focus.
+   * @defaultValue false
+   */
+  trapped?: boolean;
+
+  /**
+   * Called when auto-focusing on mount. Call `event.preventDefault()` to cancel.
+   */
+  onMountAutoFocus?: (event: Event) => void;
+
+  /**
+   * Called when auto-focusing on unmount (restoring focus to the previously focused
+   * element). Call `event.preventDefault()` to cancel the restore.
+   */
+  onUnmountAutoFocus?: (event: Event) => void;
+}
+
+export interface UseFocusScopeReturn {
+  /**
+   * Ref callback to attach to the container element.
+   * Can be composed with other refs via `useMergedRefs`.
+   */
+  containerRef: React.RefCallback<HTMLElement>;
+
+  /**
+   * Props to spread onto the container element.
+   * Provides `tabIndex` and `onKeyDown` for keyboard looping.
+   */
+  containerProps: {
+    tabIndex: number;
+    onKeyDown: React.KeyboardEventHandler<HTMLElement>;
+  };
+}
+
+/**
+ * Manages focus scoping within a container element.
+ *
+ * When `trapped` is `true`, focus is kept inside the container — including
+ * programmatic focus changes. When `loop` is `true`, tab navigation wraps around
+ * from the last tabbable element to the first and vice versa.
+ *
+ * On mount, focus moves to the first tabbable element inside the container
+ * (links excluded). On unmount, focus is restored to the element that was
+ * focused before the scope mounted.
+ *
+ * Nested scopes are supported via a global stack: the outermost scope is paused
+ * while an inner scope is active and automatically resumes when the inner scope unmounts.
+ *
+ * @example
+ * ```tsx
+ * function Popover({ children }) {
+ *   const { containerRef, containerProps } = useFocusScope({ loop: true, trapped: true });
+ *   return (
+ *     <div ref={containerRef} {...containerProps}>
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useFocusScope(options: UseFocusScopeOptions = {}): UseFocusScopeReturn {
+  const { loop = false, trapped = false, onMountAutoFocus, onUnmountAutoFocus } = options;
+  const { targetDocument } = useFluent();
+  const targetWindow = targetDocument?.defaultView ?? undefined;
+
+  const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+  // Keep mutable refs so effects always call the latest callback without re-running.
+  const onMountAutoFocusRef = React.useRef(onMountAutoFocus);
+  const onUnmountAutoFocusRef = React.useRef(onUnmountAutoFocus);
+  onMountAutoFocusRef.current = onMountAutoFocus;
+  onUnmountAutoFocusRef.current = onUnmountAutoFocus;
+
+  const lastFocusedElementRef = React.useRef<HTMLElement | null>(null);
+
+  // Stable per-instance object used by the global focusScopesStack to pause/resume.
+  const focusScope = React.useRef({
+    paused: false,
+    pause() {
+      this.paused = true;
+    },
+    resume() {
+      this.paused = false;
+    },
+  }).current;
+
+  // --- Focus trapping ---
+  // Document-level listeners redirect any focus that escapes back into the container.
+  // A MutationObserver re-focuses the container if the focused element is removed from the DOM.
+  React.useEffect(() => {
+    if (!trapped || !container || !targetDocument || !targetWindow) {
+      return;
+    }
+
+    const handleFocusIn = (event: FocusEvent) => {
+      if (focusScope.paused) {
+        return;
+      }
+      const target = event.target as HTMLElement | null;
+      if (container.contains(target)) {
+        lastFocusedElementRef.current = target;
+      } else {
+        focusElement(lastFocusedElementRef.current, targetDocument, { select: true });
+      }
+    };
+
+    const handleFocusOut = (event: FocusEvent) => {
+      if (focusScope.paused) {
+        return;
+      }
+      const relatedTarget = event.relatedTarget as HTMLElement | null;
+      // Null relatedTarget means the browser/app/tab lost focus, or Chrome removed
+      // the focused element. Calling focus() in the Chrome removal case spikes CPU
+      // to 100%, so we let the browser recover on its own.
+      if (relatedTarget === null) {
+        return;
+      }
+      if (!container.contains(relatedTarget)) {
+        focusElement(lastFocusedElementRef.current, targetDocument, { select: true });
+      }
+    };
+
+    // When the focused element is removed from the DOM, Chrome moves focus to
+    // document.body. Re-focus the container to keep the trap intact.
+    const handleMutations = (mutations: MutationRecord[]) => {
+      const active = targetDocument.activeElement as HTMLElement | null;
+      if (active !== targetDocument.body) {
+        return;
+      }
+      for (const mutation of mutations) {
+        if (mutation.removedNodes.length > 0) {
+          focusElement(container, targetDocument);
+        }
+      }
+    };
+
+    targetDocument.addEventListener('focusin', handleFocusIn);
+    targetDocument.addEventListener('focusout', handleFocusOut);
+    const observer = new targetWindow.MutationObserver(handleMutations);
+    observer.observe(container, { childList: true, subtree: true });
+
+    return () => {
+      targetDocument.removeEventListener('focusin', handleFocusIn);
+      targetDocument.removeEventListener('focusout', handleFocusOut);
+      observer.disconnect();
+    };
+  }, [trapped, container, focusScope, targetDocument, targetWindow]);
+
+  // --- Auto-focus on mount / restore focus on unmount ---
+  React.useEffect(() => {
+    if (!container || !targetDocument || !targetWindow) {
+      return;
+    }
+
+    focusScopesStack.add(focusScope);
+    const previouslyFocused = targetDocument.activeElement as HTMLElement | null;
+
+    // Only auto-focus if nothing inside the scope already has focus.
+    if (!container.contains(previouslyFocused)) {
+      // Dispatch a cancellable custom event so consumers can call preventDefault()
+      // to suppress the built-in auto-focus behaviour.
+      const onMount = (e: Event) => onMountAutoFocusRef.current?.(e);
+      const mountEvent = new CustomEvent(AUTOFOCUS_ON_MOUNT, EVENT_OPTIONS);
+      container.addEventListener(AUTOFOCUS_ON_MOUNT, onMount);
+      container.dispatchEvent(mountEvent);
+      container.removeEventListener(AUTOFOCUS_ON_MOUNT, onMount);
+
+      if (!mountEvent.defaultPrevented) {
+        focusFirst(removeLinks(getTabbableCandidates(container, targetDocument)), targetDocument, { select: true });
+        // If no tabbable element accepted focus, fall back to the container itself.
+        if (targetDocument.activeElement === previouslyFocused) {
+          focusElement(container, targetDocument);
+        }
+      }
+    }
+
+    return () => {
+      // Delay to work around a React ≤16 bug where calling focus() during unmount throws:
+      // https://github.com/facebook/react/issues/17894
+      targetWindow.setTimeout(() => {
+        const onUnmount = (e: Event) => onUnmountAutoFocusRef.current?.(e);
+        const unmountEvent = new CustomEvent(AUTOFOCUS_ON_UNMOUNT, EVENT_OPTIONS);
+        container.addEventListener(AUTOFOCUS_ON_UNMOUNT, onUnmount);
+        container.dispatchEvent(unmountEvent);
+        container.removeEventListener(AUTOFOCUS_ON_UNMOUNT, onUnmount);
+
+        if (!unmountEvent.defaultPrevented) {
+          focusElement(previouslyFocused ?? targetDocument.body, targetDocument, { select: true });
+        }
+
+        focusScopesStack.remove(focusScope);
+      }, 0);
+    };
+  }, [container, focusScope, targetDocument, targetWindow]);
+
+  // --- Keyboard looping ---
+  // Intercepts Tab / Shift+Tab at the edges of the scope and wraps focus around.
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      if (!loop && !trapped) {
+        return;
+      }
+      if (focusScope.paused) {
+        return;
+      }
+
+      const isTab = event.key === 'Tab' && !event.altKey && !event.ctrlKey && !event.metaKey;
+      if (!isTab) {
+        return;
+      }
+
+      const focused = targetDocument?.activeElement as HTMLElement | null;
+      if (!focused) {
+        return;
+      }
+
+      const scopeContainer = event.currentTarget as HTMLElement;
+      const [first, last] = getTabbableEdges(scopeContainer, targetDocument, targetWindow);
+
+      if (!first || !last) {
+        // No tabbable children — block tab from leaving when the container itself is focused.
+        if (focused === scopeContainer) {
+          event.preventDefault();
+        }
+        return;
+      }
+
+      if (!event.shiftKey && focused === last) {
+        event.preventDefault();
+        if (loop) {
+          focusElement(first, targetDocument, { select: true });
+        }
+      } else if (event.shiftKey && focused === first) {
+        event.preventDefault();
+        if (loop) {
+          focusElement(last, targetDocument, { select: true });
+        }
+      }
+    },
+    [focusScope, loop, trapped, targetDocument, targetWindow],
+  );
+
+  const containerRef = React.useCallback((node: HTMLElement | null) => {
+    setContainer(node);
+  }, []);
+
+  return {
+    containerRef,
+    containerProps: {
+      tabIndex: -1,
+      onKeyDown: handleKeyDown,
+    },
+  };
+}
+
+/* ---------------------------------------------------------------------------
+ * Internal focus utilities
+ * -------------------------------------------------------------------------*/
+
+/**
+ * Attempts to focus the first candidate that accepts focus.
+ * Stops as soon as `document.activeElement` changes.
+ */
+function focusFirst(candidates: HTMLElement[], targetDocument: Document | undefined, { select = false } = {}): void {
+  if (!targetDocument) {
+    return;
+  }
+
+  const prev = targetDocument.activeElement;
+  for (const candidate of candidates) {
+    focusElement(candidate, targetDocument, { select });
+    if (targetDocument.activeElement !== prev) {
+      return;
+    }
+  }
+}
+
+/**
+ * Returns the first and last tabbable elements inside `container`.
+ */
+function getTabbableEdges(
+  container: HTMLElement,
+  targetDocument?: Document,
+  targetWindow?: Window,
+): [HTMLElement | undefined, HTMLElement | undefined] {
+  const candidates = getTabbableCandidates(container, targetDocument);
+  const first = findVisible(candidates, container, targetWindow);
+  const last = findVisible([...candidates].reverse(), container, targetWindow);
+  return [first, last];
+}
+
+/**
+ * Returns all tabbable candidates within `container` in DOM order.
+ *
+ * This is an approximation — runtime visibility is resolved separately by
+ * `findVisible`. Positive `tabIndex` values are intentionally ignored to avoid
+ * diverging from visual order, which hinders accessibility.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
+ */
+function getTabbableCandidates(container: HTMLElement, targetDocument?: Document): HTMLElement[] {
+  if (!targetDocument) {
+    return [];
+  }
+
+  const nodes: HTMLElement[] = [];
+  const walker = targetDocument.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
+    acceptNode(node: Element) {
+      const el = node as HTMLElement;
+      if (el.tagName === 'INPUT' && (el as HTMLInputElement).type === 'hidden') {
+        return NodeFilter.FILTER_SKIP;
+      }
+      if ((el as HTMLInputElement).disabled || el.hidden) {
+        return NodeFilter.FILTER_SKIP;
+      }
+      return el.tabIndex >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+    },
+  });
+  while (walker.nextNode()) {
+    nodes.push(walker.currentNode as HTMLElement);
+  }
+  return nodes;
+}
+
+/**
+ * Returns the first element in `elements` that is not visually hidden.
+ * Visibility is only checked up to (but not including) `container`.
+ */
+function findVisible(elements: HTMLElement[], container: HTMLElement, targetWindow?: Window): HTMLElement | undefined {
+  for (const el of elements) {
+    if (!isHidden(el, targetWindow, { upTo: container })) {
+      return el;
+    }
+  }
+}
+
+function isHidden(node: HTMLElement, targetWindow?: Window, { upTo }: { upTo?: HTMLElement } = {}): boolean {
+  if (!targetWindow) {
+    return false;
+  }
+  if (targetWindow.getComputedStyle(node).visibility === 'hidden') {
+    return true;
+  }
+  let current: HTMLElement | null = node;
+  while (current) {
+    if (upTo !== undefined && current === upTo) {
+      return false;
+    }
+    if (targetWindow.getComputedStyle(current).display === 'none') {
+      return true;
+    }
+    current = current.parentElement;
+  }
+  return false;
+}
+
+function focusElement(element?: HTMLElement | null, targetDocument?: Document, { select = false } = {}): void {
+  if (!element?.focus || !targetDocument) {
+    return;
+  }
+  const prev = targetDocument.activeElement;
+  // preventScroll avoids jarring scroll jumps when focus moves programmatically.
+  element.focus({ preventScroll: true });
+  if (element !== prev && isHTMLElement(element, { constructorName: 'HTMLInputElement' }) && select) {
+    element.select();
+  }
+}
+
+/** Excludes anchor elements — links can't be auto-focused on mount without side effects. */
+function removeLinks(items: HTMLElement[]): HTMLElement[] {
+  return items.filter(item => item.tagName !== 'A');
+}
+
+/* ---------------------------------------------------------------------------
+ * Focus scope stack
+ *
+ * Maintains a stack of active focus scopes. When a new scope mounts, the
+ * previously active scope is paused. When a scope unmounts, the scope below
+ * it in the stack is resumed. This allows nested modals / popovers to work
+ * correctly without scopes fighting each other.
+ * -------------------------------------------------------------------------*/
+
+type FocusScopeAPI = { paused: boolean; pause(): void; resume(): void };
+
+const focusScopesStack = createFocusScopesStack();
+
+function createFocusScopesStack() {
+  let stack: FocusScopeAPI[] = [];
+
+  return {
+    add(scope: FocusScopeAPI) {
+      // Pause the currently active scope before pushing the new one.
+      const active = stack[0];
+      if (scope !== active) {
+        active?.pause();
+      }
+      // Re-insert at the top in case this scope already exists deeper in the stack.
+      stack = stack.filter(s => s !== scope);
+      stack.unshift(scope);
+    },
+
+    remove(scope: FocusScopeAPI) {
+      stack = stack.filter(s => s !== scope);
+      // Resume the scope that is now at the top of the stack.
+      stack[0]?.resume();
+    },
+  };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
new file mode 100644
index 00000000000000..895e152d2e2641
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
@@ -0,0 +1,46 @@
+import type { Position, Alignment } from './types';
+
+export const FALLBACK_NAME_PREFIX = '--fluent-fallback-';
+
+export const POSITIONS = {
+  above: 'above',
+  below: 'below',
+  before: 'before',
+  after: 'after',
+};
+
+export const ALIGNMENTS = {
+  start: 'start',
+  center: 'center',
+  end: 'end',
+};
+
+export const FLIP_POSITION_MAP: Record<Position, Position> = {
+  above: 'below',
+  below: 'above',
+  before: 'after',
+  after: 'before',
+};
+
+export const POSITION_AREA_MAP: Record<Position, Record<Alignment, string>> = {
+  above: {
+    center: 'block-start center',
+    start: 'block-start span-inline-end',
+    end: 'block-start span-inline-start',
+  },
+  below: {
+    center: 'block-end center',
+    start: 'block-end span-inline-end',
+    end: 'block-end span-inline-start',
+  },
+  before: {
+    center: 'center inline-start',
+    start: 'inline-start span-block-end',
+    end: 'inline-start span-block-start',
+  },
+  after: {
+    center: 'center inline-end',
+    start: 'inline-end span-block-end',
+    end: 'inline-end span-block-start',
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
new file mode 100644
index 00000000000000..7aa4ce10e1d147
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
@@ -0,0 +1,55 @@
+import type { PositioningShorthandValue } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+import { FALLBACK_NAME_PREFIX, POSITION_AREA_MAP } from './constants';
+
+/**
+ * Tracks documents that already have the `@position-try` fallback stylesheet
+ * injected. Keyed by Document so iframes, test renderers, and multiple windows
+ * each get their own injection.
+ */
+const fallbackStylesInjected = new WeakSet<Document>();
+
+/**
+ * Injects `@position-try` rules for every (position, align) combination into
+ * the given document, once per document. Idempotent — subsequent calls with
+ * the same document are no-ops.
+ *
+ * Each rule mirrors the primary-placement style: `position-area: X`, plus
+ * `justify-self/align-self: center` for the center alignment case to match
+ * `applyPositionAreaStyles`.
+ */
+export function ensureFallbackStyles(targetDocument: Document | undefined): void {
+  if (!targetDocument || fallbackStylesInjected.has(targetDocument)) {
+    return;
+  }
+
+  fallbackStylesInjected.add(targetDocument);
+
+  let css = '';
+
+  for (const position of Object.values(POSITIONS)) {
+    for (const align of Object.values(ALIGNMENTS)) {
+      const suffix = align === ALIGNMENTS.center ? '' : `-${align}`;
+      const name = `${FALLBACK_NAME_PREFIX}${position}${suffix}`;
+      const area = POSITION_AREA_MAP[position][align];
+      const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
+      const selfValue = align === ALIGNMENTS.center ? 'center' : 'initial';
+      const justifySelf = isBlockMain ? selfValue : 'initial';
+      const alignSelf = isBlockMain ? 'initial' : selfValue;
+
+      const body = `position-area: ${area}; justify-self: ${justifySelf}; align-self: ${alignSelf};`;
+
+      css += `@position-try ${name} {\n  ${body}\n}\n`;
+    }
+  }
+
+  const style = targetDocument.createElement('style');
+  style.setAttribute('data-fluent-positioning-fallbacks', '');
+  style.textContent = css;
+  targetDocument.head.appendChild(style);
+}
+
+/** Maps a shorthand placement ("below", "above-end") to its `@position-try` rule name. */
+export function shorthandToFallbackName(shorthand: PositioningShorthandValue): string {
+  return `${FALLBACK_NAME_PREFIX}${shorthand}`;
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
new file mode 100644
index 00000000000000..b8d3ec2b884df5
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
@@ -0,0 +1,12 @@
+export { usePositioning } from './usePositioning';
+export { getPlacementString, resolvePositioningShorthand } from './placement';
+export type {
+  Position,
+  Alignment,
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from './types';
+export { POSITIONS, ALIGNMENTS } from './constants';
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
new file mode 100644
index 00000000000000..99127582a92412
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
@@ -0,0 +1,39 @@
+import type { Position, Alignment, PositioningProps, PositioningShorthand } from './types';
+
+/**
+ * Maps position + align to a human-readable placement string for the
+ * `data-placement` attribute. Center alignment uses the bare position.
+ */
+export function getPlacementString(position: Position, align: Alignment): string {
+  if (align === 'center') {
+    return position;
+  }
+
+  return `${position}-${align}`;
+}
+
+/**
+ * Normalizes a {@link PositioningShorthand} (string or object) into a full
+ * {@link PositioningProps} object. Strings like `'below-start'` parse into
+ * `{ position: 'below', align: 'start' }`; objects pass through unchanged.
+ */
+export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps {
+  if (!value) {
+    return {};
+  }
+
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  const dash = value.indexOf('-');
+
+  if (dash === -1) {
+    return { position: value as Position };
+  }
+
+  return {
+    position: value.slice(0, dash) as Position,
+    align: value.slice(dash + 1) as Alignment,
+  };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts
new file mode 100644
index 00000000000000..d5cc8c388bcf9c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts
@@ -0,0 +1,30 @@
+import type * as React from 'react';
+import type { PositioningProps } from './types';
+
+/**
+ * Normalizes an `HTMLElement | RefObject | null | undefined` to a plain
+ * element (or null). Safe across realms — checks for the `current` property
+ * rather than doing `instanceof HTMLElement`.
+ */
+export function resolveElementRef(
+  source: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined,
+): HTMLElement | null {
+  if (!source) {
+    return null;
+  }
+
+  return 'current' in source ? source.current : source;
+}
+
+/** Normalizes the `offset` prop into explicit `{ mainAxis, crossAxis }`. */
+export function resolveOffset(offset: PositioningProps['offset']): { mainAxis: number; crossAxis: number } {
+  if (typeof offset === 'number') {
+    return { mainAxis: offset, crossAxis: 0 };
+  }
+
+  if (offset) {
+    return { mainAxis: offset.mainAxis ?? 0, crossAxis: offset.crossAxis ?? 0 };
+  }
+
+  return { mainAxis: 0, crossAxis: 0 };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
new file mode 100644
index 00000000000000..f53a9f97a369ba
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
@@ -0,0 +1,137 @@
+import type { Position, Alignment, PositioningProps } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+
+/** Applies `offset` as logical margins on the side facing the trigger. */
+export function applyOffsetStyles(node: HTMLElement, position: Position, mainAxis: number, crossAxis: number): void {
+  if (mainAxis) {
+    switch (position) {
+      case POSITIONS.above:
+        node.style.marginBlockEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.below:
+        node.style.marginBlockStart = `${mainAxis}px`;
+        break;
+      case POSITIONS.before:
+        node.style.marginInlineEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.after:
+        node.style.marginInlineStart = `${mainAxis}px`;
+        break;
+    }
+  }
+
+  if (crossAxis) {
+    switch (position) {
+      case POSITIONS.above:
+      case POSITIONS.below:
+        node.style.marginInlineStart = `${crossAxis}px`;
+        break;
+      case POSITIONS.before:
+      case POSITIONS.after:
+        node.style.marginBlockStart = `${crossAxis}px`;
+        break;
+    }
+  }
+}
+
+/**
+ * Applies CSS-only `autoSize`: caps `max-width` / `max-height` to the viewport
+ * minus an 8px gap. When an `overflowBoundary` is provided, the JS-based
+ * `useAutoSizeBoundary` effect overrides these values with boundary-aware math.
+ */
+export function applyAutoSize(node: HTMLElement, autoSize: PositioningProps['autoSize'], position: Position): void {
+  if (!autoSize) {
+    return;
+  }
+  const enableHeight = autoSize === true || autoSize === 'height';
+  const enableWidth = autoSize === true || autoSize === 'width';
+  // Breathing-room buffer (px) so the surface never touches the viewport edge.
+  // Consumers can shrink further via their own `max-width` / `max-height`.
+  const gap = 8;
+
+  if (enableHeight) {
+    switch (position) {
+      case POSITIONS.above:
+        node.style.maxHeight = `calc(anchor(top) - ${gap}px)`;
+        break;
+      case POSITIONS.below:
+        node.style.maxHeight = `calc(100dvh - anchor(bottom) - ${gap}px)`;
+        break;
+      case POSITIONS.before:
+      case POSITIONS.after:
+        node.style.maxHeight = `calc(100dvh - ${gap * 2}px)`;
+        break;
+    }
+  }
+
+  if (enableWidth) {
+    switch (position) {
+      case POSITIONS.before:
+        node.style.maxWidth = `calc(anchor(left) - ${gap}px)`;
+        break;
+      case POSITIONS.after:
+        node.style.maxWidth = `calc(100dvw - anchor(right) - ${gap}px)`;
+        break;
+      case POSITIONS.above:
+      case POSITIONS.below:
+        node.style.maxWidth = `calc(100dvw - ${gap * 2}px)`;
+        break;
+    }
+  }
+}
+
+/**
+ * Returns the `align-self` / `justify-self` values that make the surface
+ * cover the target (overlap instead of sit beside it).
+ */
+export function getCoverSelfAlignment(
+  position: Position,
+  align: Alignment,
+): { alignSelf: string; justifySelf: string } {
+  if (position === POSITIONS.above) {
+    return { alignSelf: ALIGNMENTS.end, justifySelf: align };
+  }
+
+  if (position === POSITIONS.below) {
+    return { alignSelf: ALIGNMENTS.start, justifySelf: align };
+  }
+
+  if (position === POSITIONS.before) {
+    return { alignSelf: align, justifySelf: ALIGNMENTS.end };
+  }
+
+  return { alignSelf: align, justifySelf: ALIGNMENTS.start };
+}
+
+/**
+ * Writes `position-area` on the surface. For center alignment also sets
+ * `justify-self/align-self: center` so the surface centers within the
+ * anchor-sized cell — this is what lets the built-in `flip-block`/`flip-inline`
+ * fallbacks natively flip the surface on overflow.
+ */
+export function applyPositionAreaStyles(
+  node: HTMLElement,
+  positionArea: string,
+  position: Position,
+  align: Alignment,
+): void {
+  node.style.setProperty('position-area', positionArea);
+  node.style.removeProperty('top');
+  node.style.removeProperty('bottom');
+  node.style.removeProperty('left');
+  node.style.removeProperty('right');
+
+  if (align === ALIGNMENTS.center) {
+    const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
+    if (isBlockMain) {
+      node.style.setProperty('justify-self', 'center');
+      node.style.removeProperty('align-self');
+    } else {
+      node.style.setProperty('align-self', 'center');
+      node.style.removeProperty('justify-self');
+    }
+  } else {
+    node.style.removeProperty('justify-self');
+    node.style.removeProperty('align-self');
+  }
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
new file mode 100644
index 00000000000000..4fb89ab36ec23b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
@@ -0,0 +1,99 @@
+import type * as React from 'react';
+import type { POSITIONS, ALIGNMENTS } from './constants';
+
+export type Position = (typeof POSITIONS)[keyof typeof POSITIONS];
+export type Alignment = (typeof ALIGNMENTS)[keyof typeof ALIGNMENTS];
+
+export type PositioningShorthandValue =
+  | 'above'
+  | 'above-start'
+  | 'above-end'
+  | 'below'
+  | 'below-start'
+  | 'below-end'
+  | 'before'
+  | 'before-top'
+  | 'before-bottom'
+  | 'after'
+  | 'after-top'
+  | 'after-bottom';
+
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+export type PositioningProps = {
+  /**
+   * @default 'above'
+   */
+  position?: Position;
+  /**
+   * @default 'center'
+   */
+  align?: Alignment;
+  /** Offset from the anchor element */
+  offset?: number | { mainAxis?: number; crossAxis?: number };
+  /**
+   * Fallback placements tried in order when the primary placement would
+   * overflow the viewport. Accepts shorthand strings like `'below-start'`.
+   * When omitted, the default is the native `flip-block, flip-inline`
+   * fallback chain.
+   */
+  fallbackPositions?: PositioningShorthandValue[];
+  /** Position on top of the target */
+  coverTarget?: boolean;
+  /** Auto-size to available space */
+  autoSize?: boolean | 'width' | 'height';
+  /**
+   * Custom anchor element for the positioned surface. When provided, the
+   * anchor-name is written to this element instead of the target assigned via
+   * the returned `targetRef`. Accepts a DOM element or a RefObject.
+   */
+  target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
+  /**
+   * CSS `position` value used on the positioned surface.
+   * @default 'fixed'
+   */
+  strategy?: 'absolute' | 'fixed';
+  /**
+   * Makes the surface match one of the trigger's dimensions. Currently only
+   * `'width'` is supported; the surface's `width` is set via CSS
+   * `anchor-size(width)`.
+   */
+  matchTargetSize?: 'width';
+  /**
+   * When true the surface stays at its requested placement even if it overflows
+   * the viewport (no `flip` fallback). Useful for menus or tooltips that must
+   * not switch sides unexpectedly.
+   * @default false
+   */
+  pinned?: boolean;
+  /**
+   * Imperative handle for programmatically retargeting the surface or
+   * triggering a position update. See {@link PositioningImperativeRef}.
+   */
+  positioningRef?: React.Ref<PositioningImperativeRef>;
+  /**
+   * Element that clips the surface when `autoSize` is set. Instead of
+   * constraining the surface to the viewport, `max-width` / `max-height`
+   * are computed from this element's rect. Accepts a DOM element or ref.
+   */
+  overflowBoundary?: HTMLElement | React.RefObject<HTMLElement | null> | null;
+};
+
+/**
+ * Imperative API exposed via `PositioningProps.positioningRef`.
+ */
+export type PositioningImperativeRef = {
+  /** Retarget the surface to the given element (or clear the target with `null`). */
+  setTarget: (target: HTMLElement | null) => void;
+  /** Request a position recomputation. With CSS anchor positioning layout is automatic, so this is a no-op on supporting browsers. */
+  updatePosition: () => void;
+};
+
+export type PositioningReturn = {
+  /** Ref callback for the trigger / anchor element. */
+  targetRef: React.RefCallback<HTMLElement>;
+  /** Ref callback for the positioned surface element. Sets anchor-binding styles and `data-placement`. */
+  containerRef: React.RefCallback<HTMLElement>;
+  /** Ref callback for the arrow element. */
+  arrowRef: React.RefCallback<HTMLElement>;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
new file mode 100644
index 00000000000000..179c4fb089e745
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
@@ -0,0 +1,44 @@
+'use client';
+
+import * as React from 'react';
+import { useId } from '@fluentui/react-utilities';
+
+/**
+ * Generates a unique `anchor-name` and keeps it applied to whichever target
+ * element is currently active. Swapping targets clears the previous element's
+ * `anchor-name`; unmounting clears the last-known target.
+ *
+ * Returns the anchor-name string so the surface can reference it via
+ * `position-anchor`.
+ */
+export function useAnchorName(effectiveTarget: HTMLElement | null): string {
+  const anchorName = useId('--popover-anchor-');
+  const anchoredTargetRef = React.useRef<HTMLElement | null>(null);
+
+  React.useEffect(() => {
+    const prev = anchoredTargetRef.current;
+
+    if (prev && prev !== effectiveTarget) {
+      prev.style.removeProperty('anchor-name');
+    }
+
+    if (effectiveTarget) {
+      effectiveTarget.style.setProperty('anchor-name', anchorName);
+    }
+
+    anchoredTargetRef.current = effectiveTarget;
+  }, [effectiveTarget, anchorName]);
+
+  React.useEffect(() => {
+    return () => {
+      const last = anchoredTargetRef.current;
+
+      if (last) {
+        last.style.removeProperty('anchor-name');
+        anchoredTargetRef.current = null;
+      }
+    };
+  }, []);
+
+  return anchorName;
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
new file mode 100644
index 00000000000000..e8982bd77e3adc
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
@@ -0,0 +1,126 @@
+'use client';
+
+import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import type { Position, Alignment, PositioningProps } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+import { resolveElementRef } from './resolvers';
+
+/**
+ * Breathing-room buffer (px) subtracted when computing autoSize so the
+ * surface never touches the boundary edge. Matches the default `padding` on
+ * floating-ui's `shift()` middleware and canonical v9's Popover. Consumers
+ * who need a different inset can layer their own `max-width` / `max-height`
+ * / `padding` on the surface — the value this hook writes is a ceiling.
+ */
+const GAP = 8;
+
+function computeAvailableHeight(
+  position: Position,
+  align: Alignment,
+  boundaryRect: DOMRect,
+  triggerRect: DOMRect,
+): number {
+  if (position === POSITIONS.above) {
+    return triggerRect.top - boundaryRect.top - GAP;
+  }
+  if (position === POSITIONS.below) {
+    return boundaryRect.bottom - triggerRect.bottom - GAP;
+  }
+
+  if (align === ALIGNMENTS.start) {
+    return boundaryRect.bottom - triggerRect.top - GAP;
+  }
+
+  if (align === ALIGNMENTS.end) {
+    return triggerRect.bottom - boundaryRect.top - GAP;
+  }
+
+  return boundaryRect.height - GAP * 2;
+}
+
+function computeAvailableWidth(
+  position: Position,
+  align: Alignment,
+  boundaryRect: DOMRect,
+  triggerRect: DOMRect,
+): number {
+  if (position === POSITIONS.before) {
+    return triggerRect.left - boundaryRect.left - GAP;
+  }
+
+  if (position === POSITIONS.after) {
+    return boundaryRect.right - triggerRect.right - GAP;
+  }
+
+  if (align === ALIGNMENTS.start) {
+    return boundaryRect.right - triggerRect.left - GAP;
+  }
+
+  if (align === ALIGNMENTS.end) {
+    return triggerRect.right - boundaryRect.left - GAP;
+  }
+
+  return boundaryRect.width - GAP * 2;
+}
+
+export type UseAutoSizeBoundaryOptions = {
+  autoSize: PositioningProps['autoSize'];
+  overflowBoundary: PositioningProps['overflowBoundary'];
+  containerEl: HTMLElement | null;
+  targetEl: HTMLElement | null;
+  position: Position;
+  align: Alignment;
+  targetDocument: Document | undefined;
+};
+
+/**
+ * When `autoSize` is combined with an `overflowBoundary`, size the surface
+ * against the boundary's rect rather than the viewport. The CSS-based
+ * `applyAutoSize` runs first (and handles the no-boundary case); this effect
+ * overrides `max-width` / `max-height` with boundary-aware values and keeps
+ * them in sync via a `ResizeObserver`.
+ */
+export function useAutoSizeBoundary({
+  autoSize,
+  overflowBoundary,
+  containerEl,
+  targetEl,
+  position,
+  align,
+  targetDocument,
+}: UseAutoSizeBoundaryOptions): void {
+  useIsomorphicLayoutEffect(() => {
+    if (!autoSize || !containerEl || !targetEl) {
+      return;
+    }
+    const boundary = resolveElementRef(overflowBoundary);
+    const ResizeObserverCtor = targetDocument?.defaultView?.ResizeObserver;
+    if (!boundary || !ResizeObserverCtor) {
+      return;
+    }
+
+    const applyHeight = autoSize === true || autoSize === 'height';
+    const applyWidth = autoSize === true || autoSize === 'width';
+    const surface = containerEl;
+
+    const apply = () => {
+      const boundaryRect = boundary.getBoundingClientRect();
+      const triggerRect = targetEl.getBoundingClientRect();
+      if (applyHeight) {
+        const available = computeAvailableHeight(position, align, boundaryRect, triggerRect);
+        surface.style.maxHeight = `${Math.max(0, available)}px`;
+      }
+      if (applyWidth) {
+        const available = computeAvailableWidth(position, align, boundaryRect, triggerRect);
+        surface.style.maxWidth = `${Math.max(0, available)}px`;
+      }
+    };
+
+    apply();
+
+    const observer = new ResizeObserverCtor(apply);
+    observer.observe(boundary);
+    observer.observe(targetEl);
+    return () => observer.disconnect();
+  }, [autoSize, overflowBoundary, containerEl, targetEl, position, align, targetDocument]);
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
new file mode 100644
index 00000000000000..a897be934dc561
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
@@ -0,0 +1,170 @@
+'use client';
+
+import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import type { Position, Alignment } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+import { FLIP_POSITION_MAP, POSITION_AREA_MAP } from './constants';
+import { getPlacementString } from './placement';
+
+const PLACEMENT_TOLERANCE = 2;
+
+const closeTo = (a: number, b: number) => Math.abs(a - b) <= PLACEMENT_TOLERANCE;
+
+function detectPosition(surfaceRect: DOMRect, targetRect: DOMRect): Position | null {
+  if (surfaceRect.bottom <= targetRect.top + PLACEMENT_TOLERANCE) {
+    return POSITIONS.above;
+  }
+
+  if (surfaceRect.top >= targetRect.bottom - PLACEMENT_TOLERANCE) {
+    return POSITIONS.below;
+  }
+
+  if (surfaceRect.right <= targetRect.left + PLACEMENT_TOLERANCE) {
+    return POSITIONS.before;
+  }
+
+  if (surfaceRect.left >= targetRect.right - PLACEMENT_TOLERANCE) {
+    return POSITIONS.after;
+  }
+
+  return null;
+}
+
+function detectAlign(position: Position, surfaceRect: DOMRect, targetRect: DOMRect): Alignment {
+  const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
+  const startAligned = isBlockMain
+    ? closeTo(surfaceRect.left, targetRect.left)
+    : closeTo(surfaceRect.top, targetRect.top);
+
+  if (startAligned) {
+    return ALIGNMENTS.start;
+  }
+
+  const endAligned = isBlockMain
+    ? closeTo(surfaceRect.right, targetRect.right)
+    : closeTo(surfaceRect.bottom, targetRect.bottom);
+
+  if (endAligned) {
+    return ALIGNMENTS.end;
+  }
+
+  return ALIGNMENTS.center;
+}
+
+function detectActualPlacement(
+  surfaceRect: DOMRect,
+  targetRect: DOMRect,
+): { position: Position; align: Alignment } | null {
+  const position = detectPosition(surfaceRect, targetRect);
+  if (!position) {
+    return null;
+  }
+  return { position, align: detectAlign(position, surfaceRect, targetRect) };
+}
+
+function decideFlip(
+  requested: Position,
+  surfaceRect: DOMRect,
+  targetRect: DOMRect,
+  win: Window,
+  mainOffset: number,
+): Position {
+  const isBlockMain = requested === POSITIONS.above || requested === POSITIONS.below;
+
+  if (isBlockMain) {
+    const needed = surfaceRect.height + mainOffset;
+    const spaceBelow = win.innerHeight - targetRect.bottom;
+    const spaceAbove = targetRect.top;
+    const preferSpace = requested === POSITIONS.below ? spaceBelow : spaceAbove;
+    const otherSpace = requested === POSITIONS.below ? spaceAbove : spaceBelow;
+    return preferSpace < needed && otherSpace > preferSpace ? FLIP_POSITION_MAP[requested] : requested;
+  }
+
+  const needed = surfaceRect.width + mainOffset;
+  const spaceAfter = win.innerWidth - targetRect.right;
+  const spaceBefore = targetRect.left;
+  const preferSpace = requested === POSITIONS.after ? spaceAfter : spaceBefore;
+  const otherSpace = requested === POSITIONS.after ? spaceBefore : spaceAfter;
+  return preferSpace < needed && otherSpace > preferSpace ? FLIP_POSITION_MAP[requested] : requested;
+}
+
+export type UsePlacementSyncOptions = {
+  containerEl: HTMLElement | null;
+  targetEl: HTMLElement | null;
+  coverTarget: boolean;
+  pinned: boolean;
+  useCssFallbacks: boolean;
+  position: Position;
+  align: Alignment;
+  mainOffset: number;
+  targetDocument: Document | undefined;
+};
+
+export function usePlacementSync({
+  containerEl,
+  targetEl,
+  coverTarget,
+  pinned,
+  useCssFallbacks,
+  position,
+  align,
+  mainOffset,
+  targetDocument,
+}: UsePlacementSyncOptions): void {
+  useIsomorphicLayoutEffect(() => {
+    if (!containerEl || !targetEl || coverTarget) {
+      return;
+    }
+
+    const win = targetDocument?.defaultView;
+
+    if (!win) {
+      return;
+    }
+
+    const update = () => {
+      if (!pinned && !useCssFallbacks) {
+        const effective = decideFlip(
+          position,
+          containerEl.getBoundingClientRect(),
+          targetEl.getBoundingClientRect(),
+          win,
+          mainOffset,
+        );
+
+        const nextArea = POSITION_AREA_MAP[effective][align];
+
+        if (containerEl.style.getPropertyValue('position-area') !== nextArea) {
+          containerEl.style.setProperty('position-area', nextArea);
+        }
+      }
+
+      const actual = detectActualPlacement(containerEl.getBoundingClientRect(), targetEl.getBoundingClientRect());
+
+      if (!actual) {
+        return;
+      }
+
+      const next = getPlacementString(actual.position, actual.align);
+
+      if (containerEl.getAttribute('data-placement') !== next) {
+        containerEl.setAttribute('data-placement', next);
+      }
+    };
+
+    update();
+
+    const ResizeObserverCtor = win.ResizeObserver;
+    const observer = ResizeObserverCtor ? new ResizeObserverCtor(update) : null;
+    observer?.observe(containerEl);
+    observer?.observe(targetEl);
+    win.addEventListener('scroll', update, true);
+    win.addEventListener('resize', update);
+
+    return () => {
+      observer?.disconnect();
+      win.removeEventListener('scroll', update, true);
+      win.removeEventListener('resize', update);
+    };
+  }, [containerEl, targetEl, coverTarget, pinned, useCssFallbacks, position, align, mainOffset, targetDocument]);
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
new file mode 100644
index 00000000000000..178b658b8d5a1d
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { act, render } from '@testing-library/react';
+import { usePositioning } from './usePositioning';
+import { getPlacementString } from './placement';
+import type { PositioningProps, PositioningReturn } from './types';
+
+/**
+ * Lightweight alternative to `renderHook` (not available across the React 17/18
+ * versions matrix we test). Renders a component that calls the hook and exposes
+ * its return value via a ref.
+ */
+function mountHook(options: PositioningProps = {}) {
+  const resultRef = React.createRef<{ current: PositioningReturn }>();
+  const Capture = () => {
+    const result = usePositioning(options);
+    (resultRef as unknown as { current: PositioningReturn }).current = result;
+    return null;
+  };
+  render(<Capture />);
+  return resultRef as unknown as { current: PositioningReturn };
+}
+
+describe('usePositioning', () => {
+  it('returns targetRef, containerRef, and arrowRef callbacks', () => {
+    const result = mountHook();
+
+    expect(typeof result.current.targetRef).toBe('function');
+    expect(typeof result.current.containerRef).toBe('function');
+    expect(typeof result.current.arrowRef).toBe('function');
+  });
+
+  it('targetRef causes anchor-name to be written to the trigger element', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+    act(() => {
+      result.current.targetRef(node);
+    });
+    expect(node.style.getPropertyValue('anchor-name')).toMatch(/^--popover-anchor-/);
+  });
+
+  it('containerRef writes data-placement derived from position and align', () => {
+    const result = mountHook({ position: 'below', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+    expect(node.getAttribute('data-placement')).toBe('below-start');
+  });
+
+  it('containerRef applies position:fixed and position-anchor', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+    expect(node.style.position).toBe('fixed');
+    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+  });
+});
+
+describe('getPlacementString', () => {
+  it('returns position only for center alignment', () => {
+    expect(getPlacementString('above', 'center')).toBe('above');
+    expect(getPlacementString('below', 'center')).toBe('below');
+  });
+
+  it('returns position-align for non-center alignment', () => {
+    expect(getPlacementString('above', 'start')).toBe('above-start');
+    expect(getPlacementString('below', 'end')).toBe('below-end');
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
new file mode 100644
index 00000000000000..29747be3572f83
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
@@ -0,0 +1,166 @@
+'use client';
+
+import * as React from 'react';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import type { PositioningProps, PositioningReturn, PositioningImperativeRef } from './types';
+import { POSITION_AREA_MAP, ALIGNMENTS, POSITIONS } from './constants';
+import { getPlacementString } from './placement';
+import { resolveElementRef, resolveOffset } from './resolvers';
+import { ensureFallbackStyles, shorthandToFallbackName } from './fallbackStyles';
+import { applyAutoSize, applyOffsetStyles, applyPositionAreaStyles, getCoverSelfAlignment } from './styleHelpers';
+import { useAnchorName } from './useAnchorName';
+import { usePlacementSync } from './usePlacementSync';
+import { useAutoSizeBoundary } from './useAutoSizeBoundary';
+
+function useImperativeAnchor(
+  positioningRef: React.Ref<PositioningImperativeRef> | undefined,
+  anchorName: string,
+): void {
+  const imperativeTargetRef = React.useRef<HTMLElement | null>(null);
+  React.useImperativeHandle<PositioningImperativeRef, PositioningImperativeRef>(
+    positioningRef,
+    () => ({
+      setTarget: el => {
+        if (imperativeTargetRef.current && imperativeTargetRef.current !== el) {
+          imperativeTargetRef.current.style.removeProperty('anchor-name');
+        }
+        imperativeTargetRef.current = el;
+        if (el) {
+          el.style.setProperty('anchor-name', anchorName);
+        }
+      },
+      updatePosition: () => undefined,
+    }),
+    [anchorName],
+  );
+}
+
+/**
+ * Positions a container element relative to a target (anchor) using the
+ * native CSS anchor positioning API. Returns ref callbacks for the target,
+ * container, and arrow; caller wires them to the respective elements.
+ */
+export function usePositioning(options: PositioningProps): PositioningReturn {
+  const position = options.position ?? POSITIONS.above;
+  const align = options.align ?? ALIGNMENTS.center;
+  const coverTarget = options.coverTarget ?? false;
+  const autoSize = options.autoSize ?? false;
+  const strategy = options.strategy ?? 'fixed';
+  const pinned = options.pinned ?? false;
+  const {
+    offset,
+    target: customTarget = null,
+    matchTargetSize,
+    positioningRef,
+    fallbackPositions,
+    overflowBoundary,
+  } = options;
+
+  const { targetDocument } = useFluent();
+
+  const [triggerElement, setTriggerElement] = React.useState<HTMLElement | null>(null);
+  const [containerEl, setContainerEl] = React.useState<HTMLElement | null>(null);
+  const [targetEl, setTargetEl] = React.useState<HTMLElement | null>(null);
+
+  const effectiveTarget = resolveElementRef(customTarget) ?? triggerElement;
+  const anchorName = useAnchorName(effectiveTarget);
+  useImperativeAnchor(positioningRef, anchorName);
+
+  React.useEffect(() => {
+    setTargetEl(effectiveTarget);
+  }, [effectiveTarget]);
+
+  const { mainAxis, crossAxis } = resolveOffset(offset);
+  const positionArea = coverTarget ? 'center' : POSITION_AREA_MAP[position][align];
+  const coverAlignment = coverTarget ? getCoverSelfAlignment(position, align) : null;
+  const placement = getPlacementString(position, align);
+
+  const targetRef: React.RefCallback<HTMLElement> = React.useCallback(node => {
+    setTriggerElement(node);
+  }, []);
+
+  const containerRef: React.RefCallback<HTMLElement> = React.useCallback(
+    node => {
+      setContainerEl(node);
+      if (!node) {
+        return;
+      }
+
+      const surface = node;
+
+      surface.style.setProperty('position', strategy);
+      surface.style.setProperty('position-anchor', anchorName);
+      surface.setAttribute('data-placement', placement);
+
+      if (coverAlignment) {
+        surface.style.setProperty('position-area', positionArea);
+        surface.style.setProperty('align-self', coverAlignment.alignSelf);
+        surface.style.setProperty('justify-self', coverAlignment.justifySelf);
+      } else {
+        if (pinned) {
+          surface.style.removeProperty('position-try-fallbacks');
+        } else if (fallbackPositions && fallbackPositions.length > 0) {
+          ensureFallbackStyles(targetDocument);
+          surface.style.setProperty(
+            'position-try-fallbacks',
+            fallbackPositions.map(shorthandToFallbackName).join(', '),
+          );
+        } else {
+          surface.style.setProperty('position-try-fallbacks', 'flip-block, flip-inline');
+        }
+        applyPositionAreaStyles(surface, positionArea, position, align);
+      }
+
+      if (matchTargetSize === 'width') {
+        surface.style.setProperty('width', 'anchor-size(width)');
+      }
+
+      applyOffsetStyles(surface, position, mainAxis, crossAxis);
+      applyAutoSize(surface, autoSize, position);
+    },
+    [
+      anchorName,
+      positionArea,
+      coverAlignment,
+      placement,
+      position,
+      align,
+      mainAxis,
+      crossAxis,
+      autoSize,
+      strategy,
+      matchTargetSize,
+      pinned,
+      fallbackPositions,
+      targetDocument,
+    ],
+  );
+
+  const arrowRef: React.RefCallback<HTMLElement> = React.useCallback(() => {
+    // Arrow placement is consumer-owned CSS keyed off `[data-placement]`.
+  }, []);
+
+  usePlacementSync({
+    containerEl,
+    targetEl,
+    coverTarget,
+    pinned,
+    useCssFallbacks: !!fallbackPositions && fallbackPositions.length > 0,
+    position,
+    align,
+    mainOffset: mainAxis,
+    targetDocument,
+  });
+
+  useAutoSizeBoundary({
+    autoSize,
+    overflowBoundary,
+    containerEl,
+    targetEl,
+    position,
+    align,
+    targetDocument,
+  });
+
+  return { targetRef, containerRef, arrowRef };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/popover.ts b/packages/react-components/react-headless-components-preview/library/src/popover.ts
new file mode 100644
index 00000000000000..0935588213760e
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/popover.ts
@@ -0,0 +1,35 @@
+export {
+  Popover,
+  renderPopover,
+  usePopover,
+  usePopoverContext,
+  usePopoverContextValues,
+  PopoverTrigger,
+  usePopoverTrigger,
+  renderPopoverTrigger,
+  PopoverSurface,
+  usePopoverSurface,
+  renderPopoverSurface,
+} from './components/Popover';
+export type {
+  PopoverProps,
+  PopoverState,
+  PopoverContextValue,
+  OpenPopoverEvents,
+  OnOpenChangeData,
+  PopoverTriggerProps,
+  PopoverTriggerState,
+  PopoverSurfaceSlots,
+  PopoverSurfaceProps,
+  PopoverSurfaceState,
+} from './components/Popover';
+
+export type {
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthandValue,
+  PositioningShorthand,
+  Position,
+  Alignment,
+} from './hooks/usePositioning';
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
new file mode 100644
index 00000000000000..202ae1423433fc
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -0,0 +1,64 @@
+import * as React from 'react';
+import type { JSXElement } from '@fluentui/react-components';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  rootTrigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  nestedTrigger:
+    'px-3 py-1.5 rounded-md bg-indigo-600 text-white text-sm font-medium hover:bg-indigo-700 data-[open]:bg-indigo-700 focus-visible:outline-2 focus-visible:outline-indigo-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  deepTrigger:
+    'px-3 py-1.5 rounded-md bg-purple-600 text-white text-sm font-medium hover:bg-purple-700 data-[open]:bg-purple-700 focus-visible:outline-2 focus-visible:outline-purple-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  actionButton:
+    'px-3 py-1.5 rounded-md bg-gray-200 text-gray-900 text-sm font-medium hover:bg-gray-300 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-3',
+  heading: 'text-sm font-semibold text-gray-900 m-0',
+  body: 'text-sm text-gray-600',
+  row: 'flex flex-wrap items-center gap-2',
+};
+
+const SecondNestedPopover = (): JSXElement => (
+  <Popover trapFocus>
+    <PopoverTrigger>
+      <button className={classes.deepTrigger}>Second nested trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <button className={classes.actionButton}>Second nested button</button>
+    </PopoverSurface>
+  </Popover>
+);
+
+const FirstNestedPopover = (): JSXElement => (
+  <Popover trapFocus>
+    <PopoverTrigger>
+      <button className={classes.nestedTrigger}>First nested trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <button className={classes.actionButton}>First nested button</button>
+      <div className={classes.row}>
+        <SecondNestedPopover />
+        <SecondNestedPopover />
+      </div>
+    </PopoverSurface>
+  </Popover>
+);
+
+export const Nested = (): React.ReactNode => (
+  <Popover trapFocus>
+    <PopoverTrigger>
+      <button className={classes.rootTrigger}>Root trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <div className={classes.row}>
+        <button className={classes.actionButton}>Root button</button>
+        <FirstNestedPopover />
+      </div>
+    </PopoverSurface>
+  </Popover>
+);

From 9f3b6b9f29ec0825403de5ea14462cbad879f865 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 20 Apr 2026 02:54:42 +0200
Subject: [PATCH 02/17] docs(react-headless-components-preview): add Popover
 Storybook stories

---
 .../stories/.storybook/preview-head.html      | 19 +++++
 .../PopoverAnchorToCustomTarget.stories.tsx   | 48 +++++++++++++
 .../src/Popover/PopoverBestPractices.md       | 13 ++++
 .../src/Popover/PopoverControlled.stories.tsx | 32 +++++++++
 .../Popover/PopoverCustomTrigger.stories.tsx  | 32 +++++++++
 .../src/Popover/PopoverDefault.stories.tsx    | 22 ++++++
 .../stories/src/Popover/PopoverDescription.md |  3 +
 .../src/Popover/PopoverInline.stories.tsx     | 25 +++++++
 .../PopoverInternalUpdateContent.stories.tsx  | 51 +++++++++++++
 .../src/Popover/PopoverNested.stories.tsx     | 35 +++++++++
 .../Popover/PopoverOpenOnContext.stories.tsx  | 23 ++++++
 .../Popover/PopoverOpenOnHover.stories.tsx    | 23 ++++++
 .../src/Popover/PopoverTrapFocus.stories.tsx  | 33 +++++++++
 .../src/Popover/PopoverWithArrow.stories.tsx  | 72 +++++++++++++++++++
 .../Popover/PopoverWithoutTrigger.stories.tsx | 36 ++++++++++
 .../stories/src/Popover/index.stories.tsx     | 30 ++++++++
 .../stories/src/index.ts                      |  2 +-
 17 files changed, 498 insertions(+), 1 deletion(-)
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx

diff --git a/packages/react-components/react-headless-components-preview/stories/.storybook/preview-head.html b/packages/react-components/react-headless-components-preview/stories/.storybook/preview-head.html
index 670a7917313c64..5221e2fdf2ed00 100644
--- a/packages/react-components/react-headless-components-preview/stories/.storybook/preview-head.html
+++ b/packages/react-components/react-headless-components-preview/stories/.storybook/preview-head.html
@@ -4,3 +4,22 @@
     interpolate-size: allow-keywords;
   }
 </style>
+<style>
+  /* Entrance / exit transition for native-popover surfaces used by stories */
+  [popover] {
+    opacity: 1;
+    transform: scale(1);
+    transition: opacity 150ms ease-out, transform 150ms ease-out, display 150ms allow-discrete,
+      overlay 150ms allow-discrete;
+  }
+  [popover]:not(:popover-open) {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+  @starting-style {
+    [popover]:popover-open {
+      opacity: 0;
+      transform: scale(0.96);
+    }
+  }
+</style>
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
new file mode 100644
index 00000000000000..2921b972f22131
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'p-16 min-h-[320px]',
+  container: 'flex items-start gap-10',
+  column: 'flex flex-col items-start gap-2',
+  label: 'text-xs font-semibold text-gray-500 uppercase tracking-wide',
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  target:
+    'px-4 py-2 rounded-md bg-purple-600 text-white font-medium hover:bg-purple-700 focus-visible:outline-2 focus-visible:outline-purple-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-2',
+};
+
+export const AnchorToCustomTarget = (): React.ReactNode => {
+  const [target, setTarget] = React.useState<HTMLElement | null>(null);
+
+  return (
+    <div className={classes.outer}>
+      <div className={classes.container}>
+        <div className={classes.column}>
+          <span className={classes.label}>Custom anchor (target)</span>
+          <button ref={setTarget} className={classes.target}>
+            Anchor
+          </button>
+        </div>
+
+        <div className={classes.column}>
+          <span className={classes.label}>Popover trigger (unrelated)</span>
+          <Popover positioning={{ target, position: 'below', offset: 4 }}>
+            <PopoverTrigger>
+              <button className={classes.trigger}>Open popover</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              <h3 className="text-sm font-semibold text-gray-900 m-0">Popover content</h3>
+              <p className="text-sm text-gray-600">
+                Clicking <em>Open popover</em> toggles this surface, but <code>positioning.target</code> makes it anchor
+                to the purple <em>Anchor</em> button instead of the trigger. It appears to the right of the anchor
+                regardless of where the trigger sits.
+              </p>
+            </PopoverSurface>
+          </Popover>
+        </div>
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
new file mode 100644
index 00000000000000..d3130e0c12634d
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
@@ -0,0 +1,13 @@
+## Best practices
+
+### Do
+
+- Use the `trapFocus` prop when focusable elements are in the `Popover`.
+- Create nested `Popover`s as separate components.
+- If there are no interactive items in the `Popover` content, set `tabIndex={-1}` on the `PopoverSurface`.
+- Use `Popover` to reduce screen clutter and host non-essential information.
+
+### Don't
+
+- Don't use more than 2 levels of nested `Popover`s.
+- Don't use `Popover`s to display too much content; consider if that content belongs on the main page.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
new file mode 100644
index 00000000000000..74fb75b85f316d
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs',
+  checkbox: 'flex items-center gap-2 mb-4 text-sm text-gray-700',
+};
+
+export const Controlled = (): React.ReactNode => {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <label className={classes.checkbox}>
+        <input type="checkbox" checked={open} onChange={e => setOpen(e.target.checked)} />
+        Popover open
+      </label>
+      <Popover open={open} onOpenChange={(_e, data) => setOpen(data.open)}>
+        <PopoverTrigger>
+          <button className={classes.trigger}>Controlled popover</button>
+        </PopoverTrigger>
+        <PopoverSurface className={classes.surface}>
+          <p className="text-sm text-gray-600">
+            This popover is controlled externally. Toggle the checkbox above or click the trigger to open and close it.
+          </p>
+        </PopoverSurface>
+      </Popover>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
new file mode 100644
index 00000000000000..3de26b3cbff5ad
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs',
+};
+
+type CustomTriggerProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+const CustomTriggerButton = React.forwardRef<HTMLButtonElement, CustomTriggerProps>((props, ref) => (
+  <button ref={ref} {...props} className={classes.trigger}>
+    Custom trigger
+  </button>
+));
+
+export const CustomTrigger = (): React.ReactNode => (
+  <Popover>
+    <PopoverTrigger>
+      <CustomTriggerButton />
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className="text-sm font-semibold text-gray-900 mb-1">Custom trigger</h3>
+      <p className="text-sm text-gray-600">
+        Native elements and Fluent components have first-class support as children of <code>PopoverTrigger</code>. To
+        use your own component, forward its ref with <code>React.forwardRef</code> so the popover can wire up the
+        trigger ref and aria attributes.
+      </p>
+    </PopoverSurface>
+  </Popover>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
new file mode 100644
index 00000000000000..284b6a3ce92b59
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs',
+};
+
+export const Default = (): React.ReactNode => (
+  <Popover>
+    <PopoverTrigger>
+      <button className={classes.trigger}>Show popover</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className="text-sm font-semibold text-gray-900 mb-1">Popover title</h3>
+      <p className="text-sm text-gray-600">
+        This is the content of the popover. Click the trigger again or press Escape to close.
+      </p>
+    </PopoverSurface>
+  </Popover>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDescription.md
new file mode 100644
index 00000000000000..e0f574a530ffc7
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDescription.md
@@ -0,0 +1,3 @@
+A popover displays lightweight content anchored to a trigger element.
+
+Popovers are used for transient UI that appears on user interaction, such as additional information, forms, or menus. They support click, hover, and context-menu triggers, optional focus trapping for dialog-like behavior, and can render with an arrow pointing to the trigger.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
new file mode 100644
index 00000000000000..1bcd0ff909604b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs',
+};
+
+export const Inline = (): React.ReactNode => (
+  <div className="p-16">
+    <Popover inline positioning="below">
+      <PopoverTrigger>
+        <button className={classes.trigger}>Inline popover</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface}>
+        <h3 className="text-sm font-semibold text-gray-900 mb-1">Inline rendering</h3>
+        <p className="text-sm text-gray-600">
+          This popover renders without the native HTML <code>popover</code> top-layer. It is still positioned via CSS
+          Anchor Positioning, but stacks with regular z-index rather than being auto-elevated above siblings.
+        </p>
+      </PopoverSurface>
+    </Popover>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
new file mode 100644
index 00000000000000..1a2143d008e7cd
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 w-80',
+  action:
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 cursor-pointer border-none',
+  link: 'text-blue-600 hover:text-blue-700 underline',
+};
+
+export const InternalUpdateContent = (): React.ReactNode => {
+  const [revealed, setRevealed] = React.useState(false);
+  const linkRef = React.useRef<HTMLAnchorElement>(null);
+
+  React.useEffect(() => {
+    if (revealed) {
+      linkRef.current?.focus();
+    }
+  }, [revealed]);
+
+  return (
+    <Popover onOpenChange={(_, data) => !data.open && setRevealed(false)}>
+      <PopoverTrigger>
+        <button className={classes.trigger}>Popover trigger</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface}>
+        <h3 className="text-sm font-semibold text-gray-900 mb-2">First panel</h3>
+        <p className="text-sm text-gray-600 mb-3">
+          Popover content can change while the popover is open. When new focusable content is revealed, move focus to it
+          so keyboard users can continue interacting.
+        </p>
+
+        {revealed ? (
+          <div className="text-sm text-gray-700">
+            Revealed content with{' '}
+            <a ref={linkRef} href="#" className={classes.link}>
+              a focusable link
+            </a>
+            .
+          </div>
+        ) : (
+          <button className={classes.action} onClick={() => setRevealed(true)}>
+            Reveal more
+          </button>
+        )}
+      </PopoverSurface>
+    </Popover>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index 202ae1423433fc..f60f18f7b85085 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -1,4 +1,5 @@
 import * as React from 'react';
+<<<<<<< HEAD
 import type { JSXElement } from '@fluentui/react-components';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
 
@@ -31,6 +32,40 @@ const SecondNestedPopover = (): JSXElement => (
 );
 
 const FirstNestedPopover = (): JSXElement => (
+||||||| parent of 2135364493 (docs(react-headless-components-preview): add Popover Storybook stories)
+=======
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  rootTrigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  nestedTrigger:
+    'px-3 py-1.5 rounded-md bg-indigo-600 text-white text-sm font-medium hover:bg-indigo-700 data-[open]:bg-indigo-700 focus-visible:outline-2 focus-visible:outline-indigo-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  deepTrigger:
+    'px-3 py-1.5 rounded-md bg-purple-600 text-white text-sm font-medium hover:bg-purple-700 data-[open]:bg-purple-700 focus-visible:outline-2 focus-visible:outline-purple-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  actionButton:
+    'px-3 py-1.5 rounded-md bg-gray-200 text-gray-900 text-sm font-medium hover:bg-gray-300 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-3',
+  heading: 'text-sm font-semibold text-gray-900 m-0',
+  body: 'text-sm text-gray-600',
+  row: 'flex flex-wrap items-center gap-2',
+};
+
+const SecondNestedPopover = (): React.ReactNode => (
+  <Popover trapFocus>
+    <PopoverTrigger>
+      <button className={classes.deepTrigger}>Second nested trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <button className={classes.actionButton}>Second nested button</button>
+    </PopoverSurface>
+  </Popover>
+);
+
+const FirstNestedPopover = (): React.ReactNode => (
+>>>>>>> 2135364493 (docs(react-headless-components-preview): add Popover Storybook stories)
   <Popover trapFocus>
     <PopoverTrigger>
       <button className={classes.nestedTrigger}>First nested trigger</button>
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
new file mode 100644
index 00000000000000..8184dfc95c47e6
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-6 py-4 rounded-md bg-gray-100 text-gray-700 font-medium border border-dashed border-gray-400 cursor-context-menu focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 py-2 min-w-[160px]',
+  menuItem:
+    'block w-full px-4 py-1.5 text-sm text-gray-700 text-left hover:bg-gray-100 cursor-pointer border-none bg-transparent',
+};
+
+export const OpenOnContext = (): React.ReactNode => (
+  <Popover openOnContext>
+    <PopoverTrigger>
+      <div className={classes.trigger}>Right-click this area</div>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <button className={classes.menuItem}>Cut</button>
+      <button className={classes.menuItem}>Copy</button>
+      <button className={classes.menuItem}>Paste</button>
+    </PopoverSurface>
+  </Popover>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
new file mode 100644
index 00000000000000..de9a53e3bf8ecf
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs',
+};
+
+export const OpenOnHover = (): React.ReactNode => (
+  <Popover openOnHover>
+    <PopoverTrigger>
+      <button className={classes.trigger}>Hover me</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className="text-sm font-semibold text-gray-900 mb-1">Hover popover</h3>
+      <p className="text-sm text-gray-600">
+        This popover opens when you hover over the trigger and closes when the mouse leaves both the trigger and the
+        surface.
+      </p>
+    </PopoverSurface>
+  </Popover>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx
new file mode 100644
index 00000000000000..19f5475a87ecd8
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx
@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 max-w-sm',
+  input:
+    'w-full px-3 py-1.5 rounded-md border border-gray-300 text-sm focus:outline-2 focus:outline-blue-500 focus:border-transparent',
+  button:
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+};
+
+export const TrapFocus = (): React.ReactNode => (
+  <Popover trapFocus>
+    <PopoverTrigger>
+      <button className={classes.trigger}>Open dialog popover</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className="text-sm font-semibold text-gray-900 mb-3">Subscribe</h3>
+      <div className="flex flex-col gap-3">
+        <label className="text-sm text-gray-600">
+          Email
+          <input type="email" placeholder="you@example.com" className={classes.input} />
+        </label>
+        <div className="flex justify-end gap-2">
+          <button className={classes.button}>Submit</button>
+        </div>
+      </div>
+      <p className="text-xs text-gray-400 mt-2">Focus is trapped inside this surface. Press Escape to close.</p>
+    </PopoverSurface>
+  </Popover>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
new file mode 100644
index 00000000000000..db2fa5cb34ca6b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
@@ -0,0 +1,72 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  wrapper: 'flex flex-col items-start gap-4 p-16',
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'popover-with-arrow bg-white rounded-lg p-4 min-w-[240px] max-w-xs',
+};
+
+// The headless Popover renders an unstyled <div data-arrow /> inside the
+// PopoverSurface when `withArrow` is set. Stories own the arrow styling —
+// here the arrow is a 12px rotated square sharing the surface's
+// background, and the surface uses `filter: drop-shadow(...)` (not
+// `box-shadow`) so the shadow follows the combined silhouette of surface
+// + arrow without casting any shadow into the popover's interior.
+// Orientation is driven by data-placement, which usePositioning keeps in
+// sync with the on-screen placement (including manual flip on overflow).
+const arrowCss = `
+.popover-with-arrow {
+  overflow: visible;
+  background: white;
+  filter: drop-shadow(0 0 1px rgba(0, 0, 0, 0.12)) drop-shadow(0 4px 8px rgba(0, 0, 0, 0.14));
+}
+.popover-with-arrow [data-arrow] {
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  background: white;
+  transform: rotate(45deg);
+}
+.popover-with-arrow[data-placement^='above'] [data-arrow] {
+  bottom: -6px;
+  inset-inline: 0;
+  margin-inline: auto;
+}
+.popover-with-arrow[data-placement^='below'] [data-arrow] {
+  top: -6px;
+  inset-inline: 0;
+  margin-inline: auto;
+}
+.popover-with-arrow[data-placement^='before'] [data-arrow] {
+  right: -6px;
+  inset-block: 0;
+  margin-block: auto;
+}
+.popover-with-arrow[data-placement^='after'] [data-arrow] {
+  left: -6px;
+  inset-block: 0;
+  margin-block: auto;
+}
+`;
+
+export const WithArrow = (): React.ReactNode => (
+  <div className={classes.wrapper}>
+    <style>{arrowCss}</style>
+    <Popover withArrow positioning={{ position: 'below', offset: 10 }}>
+      <PopoverTrigger>
+        <button className={classes.trigger}>With arrow</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface}>
+        <h3 className="text-sm font-semibold text-gray-900 mb-1">Arrow popover</h3>
+        <p className="text-sm text-gray-600">
+          The headless <code>Popover</code> renders an unstyled <code>{`<div data-arrow />`}</code> when{' '}
+          <code>withArrow</code> is set. This story styles the div as a CSS border-triangle and positions it at the
+          surface edge that faces the trigger, using the <code>data-placement</code> attribute that{' '}
+          <code>usePositioning</code> writes.
+        </p>
+      </PopoverSurface>
+    </Popover>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
new file mode 100644
index 00000000000000..cdc4dbea081231
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { Popover, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  container: 'flex flex-col items-start gap-4 p-4',
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-2',
+};
+
+export const WithoutTrigger = (): React.ReactNode => {
+  const [open, setOpen] = React.useState(false);
+  const buttonRef = React.useRef<HTMLButtonElement>(null);
+
+  return (
+    <div className={classes.container}>
+      <button ref={buttonRef} className={classes.trigger} onClick={() => setOpen(value => !value)}>
+        Toggle popover
+      </button>
+      <Popover
+        open={open}
+        onOpenChange={(_e, data) => setOpen(data.open)}
+        trapFocus
+        positioning={{ target: buttonRef }}
+      >
+        <PopoverSurface className={classes.surface}>
+          <h3 className="text-sm font-semibold text-gray-900 m-0">Popover content</h3>
+          <p className="text-sm text-gray-600">
+            This popover has no <code>PopoverTrigger</code>. The surface is controlled externally and anchored to the
+            button via the <code>positioning.target</code> prop.
+          </p>
+        </PopoverSurface>
+      </Popover>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
new file mode 100644
index 00000000000000..62ba4068d3fdb6
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
@@ -0,0 +1,30 @@
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+import descriptionMd from './PopoverDescription.md';
+import bestPracticesMd from './PopoverBestPractices.md';
+
+export { Default } from './PopoverDefault.stories';
+export { WithArrow } from './PopoverWithArrow.stories';
+export { Controlled } from './PopoverControlled.stories';
+export { OpenOnHover } from './PopoverOpenOnHover.stories';
+export { OpenOnContext } from './PopoverOpenOnContext.stories';
+export { CustomTrigger } from './PopoverCustomTrigger.stories';
+export { WithoutTrigger } from './PopoverWithoutTrigger.stories';
+export { AnchorToCustomTarget } from './PopoverAnchorToCustomTarget.stories';
+export { TrapFocus } from './PopoverTrapFocus.stories';
+export { Nested } from './PopoverNested.stories';
+export { InternalUpdateContent } from './PopoverInternalUpdateContent.stories';
+export { Inline } from './PopoverInline.stories';
+
+export default {
+  title: 'Headless Components/Popover',
+  component: Popover,
+  subcomponents: { PopoverTrigger, PopoverSurface },
+  parameters: {
+    docs: {
+      description: {
+        component: [descriptionMd, bestPracticesMd].join('\n'),
+      },
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/index.ts b/packages/react-components/react-headless-components-preview/stories/src/index.ts
index cb0ff5c3b541f6..de03c5324958d3 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/index.ts
+++ b/packages/react-components/react-headless-components-preview/stories/src/index.ts
@@ -1 +1 @@
-export {};
+export {} from './Popover/index.stories';

From 9c9b1a85e3851a8d0a3cdc87c6cd04d5ac13a77a Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 20 Apr 2026 02:54:53 +0200
Subject: [PATCH 03/17] docs(react-headless-components-preview): add
 Positioning concept Storybook stories

---
 .../src/components/Popover/usePopover.ts      | 11 +--
 .../PositioningAutoSize.stories.tsx           | 67 +++++++++++++++++
 .../Positioning/PositioningBestPractices.md   |  3 +
 .../PositioningCoverTarget.stories.tsx        | 49 +++++++++++++
 .../PositioningDefault.stories.tsx            | 46 ++++++++++++
 .../Positioning/PositioningDescription.md     |  7 ++
 .../PositioningFallbackPositions.stories.tsx  | 36 ++++++++++
 .../PositioningMatchTargetSize.stories.tsx    | 27 +++++++
 .../Positioning/PositioningOffset.stories.tsx | 64 +++++++++++++++++
 .../PositioningOverflowBoundary.stories.tsx   | 71 +++++++++++++++++++
 .../PositioningShorthandPositions.stories.tsx | 49 +++++++++++++
 .../Concepts/Positioning/index.stories.tsx    | 25 +++++++
 .../Concepts/Positioning/utils.stories.tsx    |  7 ++
 13 files changed, 458 insertions(+), 4 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningBestPractices.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx

diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index 277ec3c4f93e9f..c4139c2546d026 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -13,6 +13,9 @@ import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts
 import { usePositioning, resolvePositioningShorthand } from '../../hooks';
 import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents } from './Popover.types';
 
+const SUPPORTS_POPOVER_OPEN_SELECTOR =
+  typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
+
 /**
  * Returns the state for a Popover component, given its props and ref.
  */
@@ -105,10 +108,6 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
       return;
     }
 
-    // Feature-detect the native Popover API — it's only available in
-    // Chrome 114+, Safari 17+, Firefox 125+. Older browsers fall back to
-    // in-flow rendering (the surface is still rendered in the DOM; top-layer
-    // elevation just isn't available).
     if (typeof surface.showPopover !== 'function') {
       return;
     }
@@ -117,6 +116,10 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
       surface.setAttribute('popover', 'manual');
     }
 
+    if (SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open')) {
+      return;
+    }
+
     surface.showPopover();
   }, [open, inline]);
 
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
new file mode 100644
index 00000000000000..fefc07c8e261af
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'w-full overflow-auto',
+  wrapper: 'flex flex-col items-start gap-4 mx-16 my-16 w-max',
+  row: 'flex items-center gap-3 text-sm text-gray-700',
+  input: 'w-24 px-2 py-1 border border-gray-300 rounded',
+  checkbox: 'flex items-center gap-2',
+  boundary: 'relative border-2 border-dashed border-red-500 w-[300px] h-[300px] flex flex-col items-center p-2',
+  trigger:
+    'w-[150px] inline-flex justify-center px-3 py-2 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-1 overflow-auto flex flex-col gap-0.5 min-w-[150px]',
+  item: 'px-3 py-1.5 rounded text-sm text-gray-800 hover:bg-gray-100 cursor-default whitespace-nowrap',
+};
+
+export const AutoSize = (): React.ReactNode => {
+  const [open, setOpen] = React.useState(false);
+  const [itemCount, setItemCount] = React.useState(10);
+  const [boundary, setBoundary] = React.useState<HTMLDivElement | null>(null);
+
+  return (
+    <div className={classes.outer}>
+      <div className={classes.wrapper}>
+        <label className={classes.checkbox}>
+          <input type="checkbox" checked={open} onChange={e => setOpen(e.target.checked)} />
+          <span className="text-sm text-gray-700">Open</span>
+        </label>
+        <label className={classes.row}>
+          <span>Menu item count</span>
+          <input
+            type="number"
+            className={classes.input}
+            min={1}
+            value={itemCount}
+            onChange={e => setItemCount(parseInt(e.target.value, 10) || 1)}
+          />
+        </label>
+
+        <div ref={setBoundary} className={classes.boundary}>
+          <Popover
+            open={open}
+            onOpenChange={(_, data) => setOpen(data.open)}
+            positioning={{ position: 'below', autoSize: true, overflowBoundary: boundary, strategy: 'absolute' }}
+          >
+            <PopoverTrigger>
+              <button className={classes.trigger}>AutoSized popover</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              {Array.from({ length: itemCount }, (_, i) => (
+                <div key={i} className={classes.item}>
+                  Item {i + 1}
+                </div>
+              ))}
+            </PopoverSurface>
+          </Popover>
+        </div>
+
+        <p className="text-xs text-gray-500 max-w-lg">
+          <code>autoSize</code> sets inline <code>max-width</code> and <code>max-height</code> styles on the surface
+          derived from <code>overflowBoundary</code> (here, the dashed 300×300 box). As the item count grows the popover
+          clips to the boundary and scrolls instead of bursting outside.
+        </p>
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningBestPractices.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningBestPractices.md
new file mode 100644
index 00000000000000..1a949854c1339b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningBestPractices.md
@@ -0,0 +1,3 @@
+# Best practices
+
+These examples are intended to document the `positioning` prop used in Fluent UI Headless Components; please refer to component-specific documentation for best practices for a specific component.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
new file mode 100644
index 00000000000000..cdd933922eb60e
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'w-full overflow-auto',
+  wrapper: 'grid grid-cols-[repeat(3,auto)] grid-rows-[repeat(5,auto)] gap-16 mx-32 my-16 w-max',
+  trigger:
+    'h-12 w-32 flex items-center justify-center px-3 rounded-md bg-blue-600 text-white text-xs font-medium hover:bg-blue-700 cursor-pointer border-none',
+  surface:
+    'bg-white/95 rounded-lg shadow-lg border border-gray-200 px-4 py-3 text-sm w-56 h-28 flex items-center justify-center',
+};
+
+const cells: Array<{
+  label: string;
+  position: NonNullable<PositioningProps['position']>;
+  align: NonNullable<PositioningProps['align']>;
+  gridClass: string;
+}> = [
+  { label: 'above-start', position: 'above', align: 'start', gridClass: 'row-start-1 col-start-1' },
+  { label: 'above', position: 'above', align: 'center', gridClass: 'row-start-1 col-start-2' },
+  { label: 'above-end', position: 'above', align: 'end', gridClass: 'row-start-1 col-start-3' },
+  { label: 'before-top', position: 'before', align: 'start', gridClass: 'row-start-2 col-start-1' },
+  { label: 'before', position: 'before', align: 'center', gridClass: 'row-start-3 col-start-1' },
+  { label: 'before-bottom', position: 'before', align: 'end', gridClass: 'row-start-4 col-start-1' },
+  { label: 'after-top', position: 'after', align: 'start', gridClass: 'row-start-2 col-start-3' },
+  { label: 'after', position: 'after', align: 'center', gridClass: 'row-start-3 col-start-3' },
+  { label: 'after-bottom', position: 'after', align: 'end', gridClass: 'row-start-4 col-start-3' },
+  { label: 'below-start', position: 'below', align: 'start', gridClass: 'row-start-5 col-start-1' },
+  { label: 'below', position: 'below', align: 'center', gridClass: 'row-start-5 col-start-2' },
+  { label: 'below-end', position: 'below', align: 'end', gridClass: 'row-start-5 col-start-3' },
+];
+
+export const CoverTarget = (): React.ReactNode => (
+  <div className={classes.outer}>
+    <div className={classes.wrapper}>
+      {cells.map(cell => (
+        <div key={cell.label} className={cell.gridClass}>
+          <Popover positioning={{ position: cell.position, align: cell.align, coverTarget: true }}>
+            <PopoverTrigger>
+              <button className={classes.trigger}>{cell.label}</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>Container</PopoverSurface>
+          </Popover>
+        </div>
+      ))}
+    </div>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
new file mode 100644
index 00000000000000..f9c63d7cf87a5d
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
@@ -0,0 +1,46 @@
+import * as React from 'react';
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverSurface,
+  type PositioningProps,
+} from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[160px]',
+};
+
+export const Default = (props: PositioningProps): React.ReactNode => (
+  <Popover positioning={props}>
+    <PopoverTrigger>
+      <button className={classes.trigger}>Click me</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>Container</PopoverSurface>
+  </Popover>
+);
+
+Default.argTypes = {
+  position: {
+    control: 'select',
+    options: ['above', 'below', 'before', 'after'],
+  },
+  align: {
+    control: 'select',
+    options: ['start', 'center', 'end'],
+  },
+  offset: {
+    control: 'number',
+  },
+  coverTarget: {
+    control: 'boolean',
+  },
+  fallbackPositions: { control: { disable: true } },
+  autoSize: { control: { disable: true } },
+};
+
+Default.args = {
+  position: 'above',
+  align: 'center',
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDescription.md
new file mode 100644
index 00000000000000..9ef2fe2dc48866
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDescription.md
@@ -0,0 +1,7 @@
+Headless Fluent components that make use of positioning can all be configured in the same way. In this preview package, positioning currently applies to:
+
+- Popover
+
+Components that have slots which are positioned will always expose a `positioning` prop where the positioning of the slot can be configured.
+
+Below you can try out the different positioning options in the playground. Further examples try to explain more clearly different configuration options for the `positioning` prop.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
new file mode 100644
index 00000000000000..9019b49de37ed2
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  wrapper: 'flex flex-col items-start gap-4 m-16',
+  trigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 max-w-xs',
+  note: 'text-xs text-gray-500 max-w-lg',
+};
+
+export const FallbackPositions = (): React.ReactNode => (
+  <div className={classes.wrapper}>
+    <Popover
+      positioning={{
+        position: 'above',
+        align: 'center',
+        fallbackPositions: ['below-start', 'after'],
+      }}
+    >
+      <PopoverTrigger>
+        <button className={classes.trigger}>Open near an edge</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface}>
+        When <code>above</code> overflows the viewport, the browser walks <code>fallbackPositions</code> in order —
+        first <code>below-start</code>, then <code>after</code> — and picks the first placement that fits.
+      </PopoverSurface>
+    </Popover>
+
+    <p className={classes.note}>
+      <code>fallbackPositions</code> accepts shorthand strings like <code>'below-start'</code>. Each entry is compiled
+      into a <code>@position-try</code> rule so the browser can try them natively. When omitted, the default fallback is{' '}
+      <code>flip-block, flip-inline</code>.
+    </p>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
new file mode 100644
index 00000000000000..30a5f325bfa1d5
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  wrapper: 'flex flex-col items-start gap-4 m-16',
+  trigger:
+    'w-[350px] px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 box-border',
+  note: 'text-xs text-gray-500 max-w-lg',
+};
+
+export const MatchTargetSize = (): React.ReactNode => (
+  <div className={classes.wrapper}>
+    <Popover open positioning={{ matchTargetSize: 'width' }}>
+      <PopoverTrigger>
+        <button className={classes.trigger}>Click me</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface}>This popover has the same width as its target anchor</PopoverSurface>
+    </Popover>
+
+    <p className={classes.note}>
+      <code>matchTargetSize: 'width'</code> applies <code>width: anchor-size(width)</code> to the surface so its inline
+      size tracks the trigger's. Handy for combobox / autocomplete dropdowns that should line up with the input. Ensure
+      the surface uses <code>box-sizing: border-box</code> so padding doesn't exceed the matched width.
+    </p>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
new file mode 100644
index 00000000000000..6df415cf2b34c2
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
@@ -0,0 +1,64 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'w-full overflow-auto',
+  wrapper: 'flex flex-col items-start gap-6 mx-32 my-16 w-max',
+  row: 'flex items-center gap-3 text-sm text-gray-700',
+  input: 'w-20 px-2 py-1 border border-gray-300 rounded',
+  trigger:
+    'inline-flex w-fit px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 px-3 py-2 text-sm w-40',
+  group: 'flex flex-col items-start gap-2',
+  label: 'text-xs font-semibold text-gray-500 uppercase tracking-wide',
+};
+
+export const Offset = (): React.ReactNode => {
+  const [mainAxis, setMainAxis] = React.useState(10);
+  const [crossAxis, setCrossAxis] = React.useState(0);
+
+  return (
+    <div className={classes.outer}>
+      <div className={classes.wrapper}>
+        <label className={classes.row}>
+          <code>mainAxis</code>
+          <input
+            type="number"
+            className={classes.input}
+            value={mainAxis}
+            onChange={e => setMainAxis(parseInt(e.target.value, 10) || 0)}
+          />
+        </label>
+        <label className={classes.row}>
+          <code>crossAxis</code>
+          <input
+            type="number"
+            className={classes.input}
+            value={crossAxis}
+            onChange={e => setCrossAxis(parseInt(e.target.value, 10) || 0)}
+          />
+        </label>
+
+        <div className={classes.group}>
+          <span className={classes.label}>offset: number (mainAxis only)</span>
+          <Popover positioning={{ position: 'after', offset: mainAxis }}>
+            <PopoverTrigger>
+              <button className={classes.trigger}>Number offset</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>Container</PopoverSurface>
+          </Popover>
+        </div>
+
+        <div className={classes.group}>
+          <span className={classes.label}>offset: {'{ mainAxis, crossAxis }'}</span>
+          <Popover positioning={{ position: 'after', offset: { mainAxis, crossAxis } }}>
+            <PopoverTrigger>
+              <button className={classes.trigger}>Object offset</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>Container</PopoverSurface>
+          </Popover>
+        </div>
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
new file mode 100644
index 00000000000000..8587e08982e1ce
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
@@ -0,0 +1,71 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'w-full overflow-auto min-h-[400px]',
+  wrapper: 'flex flex-col items-start gap-4 m-16',
+  checkbox: 'flex items-center gap-2 text-sm text-gray-700',
+  boundary:
+    'relative border-2 border-dashed border-red-500 w-[300px] h-[300px] p-5 flex flex-col justify-between items-end box-border',
+  trigger:
+    'w-[150px] px-3 py-2 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  boundedSurface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm overflow-auto',
+  freeSurface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm w-64 overflow-auto',
+  note: 'text-xs text-gray-500 max-w-lg',
+};
+
+export const OverflowBoundary = (): React.ReactNode => {
+  const [open, setOpen] = React.useState(true);
+  const [boundary, setBoundary] = React.useState<HTMLDivElement | null>(null);
+
+  return (
+    <div className={classes.outer}>
+      <div className={classes.wrapper}>
+        <label className={classes.checkbox}>
+          <input type="checkbox" checked={open} onChange={e => setOpen(e.target.checked)} />
+          <span>Open</span>
+        </label>
+
+        <div ref={setBoundary} className={classes.boundary}>
+          <Popover
+            open={open}
+            onOpenChange={(_, data) => setOpen(data.open)}
+            positioning={{ position: 'below', align: 'start', autoSize: 'width', overflowBoundary: boundary }}
+          >
+            <PopoverTrigger>
+              <button className={classes.trigger}>Bounded</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.boundedSurface}>
+              Stays within the overflow boundary — <code>autoSize</code> + <code>overflowBoundary</code> clamps
+              max-width to the space between the trigger's left edge and the dashed box's right edge, so this popover
+              wraps to fit.
+            </PopoverSurface>
+          </Popover>
+
+          <Popover
+            open={open}
+            onOpenChange={(_, data) => setOpen(data.open)}
+            positioning={{ position: 'below', align: 'start' }}
+          >
+            <PopoverTrigger>
+              <button className={classes.trigger}>Free</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.freeSurface}>
+              Overflows the overflow boundary — no <code>overflowBoundary</code> is set and the surface carries an
+              explicit <code>w-64</code>, so it keeps its natural 256px width and extends past the dashed box.
+            </PopoverSurface>
+          </Popover>
+        </div>
+
+        <p className={classes.note}>
+          <code>overflowBoundary</code> tells the positioning hook which element to treat as the clip area for
+          <code> autoSize</code>. The bounded popover's <code>max-width</code> (and <code>max-height</code> when
+          <code> autoSize: true</code>) is derived from that element's rect and kept in sync via a{' '}
+          <code>ResizeObserver</code>. Without <code>overflowBoundary</code>, <code>autoSize</code> falls back to the
+          viewport — and when <code>autoSize</code> is off entirely, the surface sizes freely and can extend past the
+          boundary.
+        </p>
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
new file mode 100644
index 00000000000000..11842c897f5a5c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+
+const classes = {
+  outer: 'w-full overflow-auto',
+  wrapper: 'grid grid-cols-[repeat(3,auto)] grid-rows-[repeat(5,auto)] gap-16 mx-32 my-16 w-max',
+  trigger:
+    'h-12 w-32 flex items-center justify-center px-3 rounded-md bg-blue-600 text-white text-xs font-medium hover:bg-blue-700 cursor-pointer border-none',
+  surface:
+    'bg-white rounded-lg shadow-lg border border-gray-200 px-4 py-3 text-sm w-40 h-20 flex items-center justify-center',
+};
+
+const cells: Array<{
+  label: string;
+  position: NonNullable<PositioningProps['position']>;
+  align: NonNullable<PositioningProps['align']>;
+  gridClass: string;
+}> = [
+  { label: 'above-start', position: 'above', align: 'start', gridClass: 'row-start-1 col-start-1' },
+  { label: 'above', position: 'above', align: 'center', gridClass: 'row-start-1 col-start-2' },
+  { label: 'above-end', position: 'above', align: 'end', gridClass: 'row-start-1 col-start-3' },
+  { label: 'before-top', position: 'before', align: 'start', gridClass: 'row-start-2 col-start-1' },
+  { label: 'before', position: 'before', align: 'center', gridClass: 'row-start-3 col-start-1' },
+  { label: 'before-bottom', position: 'before', align: 'end', gridClass: 'row-start-4 col-start-1' },
+  { label: 'after-top', position: 'after', align: 'start', gridClass: 'row-start-2 col-start-3' },
+  { label: 'after', position: 'after', align: 'center', gridClass: 'row-start-3 col-start-3' },
+  { label: 'after-bottom', position: 'after', align: 'end', gridClass: 'row-start-4 col-start-3' },
+  { label: 'below-start', position: 'below', align: 'start', gridClass: 'row-start-5 col-start-1' },
+  { label: 'below', position: 'below', align: 'center', gridClass: 'row-start-5 col-start-2' },
+  { label: 'below-end', position: 'below', align: 'end', gridClass: 'row-start-5 col-start-3' },
+];
+
+export const ShorthandPositions = (): React.ReactNode => (
+  <div className={classes.outer}>
+    <div className={classes.wrapper}>
+      {cells.map(cell => (
+        <div key={cell.label} className={cell.gridClass}>
+          <Popover positioning={{ position: cell.position, align: cell.align }}>
+            <PopoverTrigger>
+              <button className={classes.trigger}>{cell.label}</button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>Container</PopoverSurface>
+          </Popover>
+        </div>
+      ))}
+    </div>
+  </div>
+);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
new file mode 100644
index 00000000000000..0db9d0a970722e
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
@@ -0,0 +1,25 @@
+import { Positioning } from './utils.stories';
+
+import descriptionMd from './PositioningDescription.md';
+import bestPracticesMd from './PositioningBestPractices.md';
+
+export { Default } from './PositioningDefault.stories';
+export { ShorthandPositions } from './PositioningShorthandPositions.stories';
+export { Offset } from './PositioningOffset.stories';
+export { CoverTarget } from './PositioningCoverTarget.stories';
+export { AutoSize } from './PositioningAutoSize.stories';
+export { OverflowBoundary } from './PositioningOverflowBoundary.stories';
+export { MatchTargetSize } from './PositioningMatchTargetSize.stories';
+export { FallbackPositions } from './PositioningFallbackPositions.stories';
+
+export default {
+  title: 'Headless Concepts/Developer/Positioning',
+  component: Positioning,
+  parameters: {
+    docs: {
+      description: {
+        component: [descriptionMd, bestPracticesMd].join('\n'),
+      },
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx
new file mode 100644
index 00000000000000..500f0973c70adb
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+
+/**
+ * Helper component used by Storybook to auto-generate the positioning props args table.
+ */
+export const Positioning: React.FC<PositioningProps> = () => <div />;

From 31da14c4a046e2b030f114f2901433314ca79385 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Wed, 22 Apr 2026 00:14:39 +0200
Subject: [PATCH 04/17] refactor(react-headless-components-preview): rebuild
 usePositioning on spec-pure CSS anchor positioning

---
 .../library/docs/popover-spec.md              | 268 ++++++++++++++++++
 .../library/etc/popover.api.md                | 183 ++++++++++++
 .../react-headless-components-preview.api.md  |   9 +
 .../src/components/Popover/Popover.types.ts   |  16 +-
 .../PopoverSurface/usePopoverSurface.ts       |   4 +-
 .../PopoverTrigger/renderPopoverTrigger.ts    |   4 +-
 .../src/components/Popover/popoverContext.ts  |   1 -
 .../src/components/Popover/usePopover.ts      |   1 -
 .../src/hooks/usePositioning/constants.ts     |  25 +-
 .../hooks/usePositioning/fallbackStyles.ts    |  55 ----
 .../library/src/hooks/usePositioning/index.ts |   4 +-
 .../src/hooks/usePositioning/placement.ts     |  39 ---
 .../src/hooks/usePositioning/styleHelpers.ts  | 137 ---------
 .../library/src/hooks/usePositioning/types.ts |  52 ++--
 .../src/hooks/usePositioning/useAnchorName.ts |  44 ---
 .../usePositioning/useAutoSizeBoundary.ts     | 126 --------
 .../usePositioning/usePlacementObserver.ts    | 110 +++++++
 .../hooks/usePositioning/usePlacementSync.ts  | 170 -----------
 .../usePositioning/usePositioning.test.tsx    | 122 +++++++-
 .../hooks/usePositioning/usePositioning.ts    | 204 ++++++-------
 .../src/hooks/usePositioning/utils/index.ts   |   8 +
 .../src/hooks/usePositioning/utils/offset.ts  |  48 ++++
 .../hooks/usePositioning/utils/placement.ts   |  99 +++++++
 .../resolveElementRef.ts}                     |  15 -
 .../PositioningAutoSize.stories.tsx           |  18 +-
 .../PositioningAutoSizeDescription.md         |   1 +
 .../PositioningFallbackPositions.stories.tsx  | 142 ++++++++--
 ...PositioningFallbackPositionsDescription.md |   5 +
 .../PositioningFlippingBlock.stories.tsx      |  61 ++++
 .../PositioningFlippingBlockDescription.md    |   3 +
 .../PositioningFlippingCorner.stories.tsx     |  81 ++++++
 .../PositioningFlippingCornerDescription.md   |   3 +
 .../PositioningFlippingInline.stories.tsx     |  65 +++++
 .../PositioningFlippingInlineDescription.md   |   3 +
 .../PositioningMatchTargetSize.stories.tsx    |  17 +-
 .../PositioningMatchTargetSizeDescription.md  |   1 +
 .../PositioningOverflowBoundary.stories.tsx   |  44 +--
 .../PositioningOverflowBoundaryDescription.md |   1 +
 .../src/Concepts/Positioning/demoBox.ts       |  21 ++
 .../Concepts/Positioning/index.stories.tsx    |   5 +-
 .../src/Popover/PopoverWithArrow.stories.tsx  |  87 +++---
 .../stories/src/index.ts                      |   2 +-
 42 files changed, 1414 insertions(+), 890 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
 create mode 100644 packages/react-components/react-headless-components-preview/library/etc/popover.api.md
 create mode 100644 packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementObserver.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/offset.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/placement.ts
 rename packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/{resolvers.ts => utils/resolveElementRef.ts} (50%)
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositionsDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlockDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCornerDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInlineDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSizeDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/demoBox.ts

diff --git a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
new file mode 100644
index 00000000000000..0a2ae066b8306f
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
@@ -0,0 +1,268 @@
+# Popover — Headless Spec
+
+## Overview
+
+Popover is an anchored overlay surface that displays transient content (actions, details, confirmations, rich tooltips) next to a trigger element. It composes a trigger (optional if opened programmatically), a surface (the floating content), and an optional arrow. The surface can elevate into the browser's **top layer** via the native HTML Popover API, or render inline in DOM order when `inline={true}`. Placement is computed via the native **CSS Anchor Positioning API** — no JS layout loop.
+
+Popover manages dismissal (click-outside, scroll-outside, Escape, iframe blur), opt-in focus trapping, opt-in hover/context interaction, and keeps `data-placement` in sync with the browser's post-flip decision so consumer CSS can style flipped placements.
+
+## Composition
+
+```
+Popover
+├── PopoverTrigger (optional — clones a single child, wires events)
+└── PopoverSurface
+    ├── [arrow] (optional — rendered when withArrow={true})
+    └── children / content
+```
+
+Popover is a compound component. `PopoverTrigger` is optional — a surface with no trigger can be opened via `defaultOpen`, a controlled `open` prop, or imperatively via `positioning.target` / `positioning.positioningRef.setTarget`.
+
+`PopoverTrigger` takes **exactly one child** and clones it to attach click/keydown/hover/context-menu handlers plus a merged ref.
+
+## Props API
+
+### `Popover`
+
+| Prop                 | Type                                                        | Default     | Description                                                                                                                  |
+| -------------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `open`               | `boolean`                                                   | `undefined` | Controlled: whether the surface is visible. Omit for uncontrolled.                                                           |
+| `defaultOpen`        | `boolean`                                                   | `false`     | Uncontrolled: initial visibility.                                                                                            |
+| `onOpenChange`       | `(e, data: { open: boolean; type: string; event }) => void` | —           | Fires whenever the surface wants to open or close. Always paired with the originating event and its `type` (click/key/etc.). |
+| `openOnHover`        | `boolean`                                                   | `false`     | Open on `mouseenter` of the trigger; close on `mouseleave` (with delay).                                                     |
+| `mouseLeaveDelay`    | `number` (ms)                                               | `500`       | Delay before closing when hover leaves, giving the user time to move into the surface.                                       |
+| `openOnContext`      | `boolean`                                                   | `false`     | Open on the trigger's context-menu event (right-click / Shift+F10). Click and keyboard activation are ignored while on.      |
+| `closeOnScroll`      | `boolean`                                                   | `false`     | Close when the user scrolls anywhere outside the trigger + surface.                                                          |
+| `closeOnIframeFocus` | `boolean`                                                   | `true`      | Close when focus moves into an external iframe. Internal iframes (inside the surface) don't dismiss.                         |
+| `trapFocus`          | `boolean`                                                   | `false`     | Trap Tab/Shift+Tab inside the surface while open. Also switches the surface's ARIA role to `dialog` + `aria-modal="true"`.   |
+| `disableAutoFocus`   | `boolean`                                                   | `false`     | Don't move focus into the surface on open.                                                                                   |
+| `withArrow`          | `boolean`                                                   | `false`     | Render an arrow element inside the surface. Consumer CSS positions/rotates it using `[data-placement]`.                      |
+| `inline`             | `boolean`                                                   | `false`     | Render the surface in DOM order (no top-layer elevation, no `popover="manual"`).                                             |
+| `mountNode`          | `HTMLElement \| null`                                       | `null`      | Optional portal target for the surface. When omitted, the surface renders in place (top layer if not `inline`).              |
+| `positioning`        | `PositioningShorthand`                                      | `undefined` | Shorthand (`'below-start'`) or object (`{ position, align, offset, ... }`). See [Positioning](#positioning).                 |
+
+### `PopoverTrigger`
+
+| Prop                       | Type           | Default | Description                                                                                        |
+| -------------------------- | -------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactElement` | —       | Exactly one child element. Cloned with merged handlers and ref.                                    |
+| `disableButtonEnhancement` | `boolean`      | `false` | Skip `useARIAButtonProps` enhancement. Use when the child is already a fully-featured ARIA button. |
+
+### `PopoverSurface`
+
+| Prop       | Type        | Default | Description                                                                                          |
+| ---------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `tabIndex` | `number`    | —       | When set, focus is placed on the surface itself on open (instead of the first focusable descendant). |
+| `children` | `ReactNode` | —       | Surface content.                                                                                     |
+
+## States
+
+| State              | Trigger                                                                                         | Behaviour                                                                                                                                                                                                                           | ARIA                                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **Closed**         | Initial, or after dismissal                                                                     | Surface unmounted. Trigger has `aria-expanded="false"`, no `data-open`.                                                                                                                                                             | `aria-expanded="false"` on trigger.                                                                                      |
+| **Open**           | `open={true}` / click / keyboard activation / hover / right-click (depending on props)          | Surface mounted. In non-`inline` mode it's promoted into the top layer via `showPopover()` (feature-detected). `data-placement` reflects the requested placement; `usePlacementObserver` overwrites it with the resolved placement. | `aria-expanded="true"`, `data-open` on trigger; `role="group"` (or `"dialog"` when `trapFocus`), `data-open` on surface. |
+| **Focused (trap)** | `trapFocus={true}` + surface mounted                                                            | Focus moves into the surface (first focusable, or the surface itself if `tabIndex` is numeric, or nothing when `disableAutoFocus`). Tab/Shift+Tab wrap inside the surface. On close, focus restores to the trigger.                 | `role="dialog"`, `aria-modal="true"`, `aria-haspopup="dialog"` on trigger.                                               |
+| **Hover-held**     | `openOnHover` and pointer inside trigger or surface                                             | Popover stays open while pointer is inside either element; closes `mouseLeaveDelay` ms after it leaves both.                                                                                                                        | Same as Open.                                                                                                            |
+| **Context-pinned** | `openOnContext` + right-click                                                                   | `onOpenChange(e, { type: 'contextmenu', open: true })` with the mouse event; `contextTarget` state stores `{ x, y }`. Click and keyboard activation on the trigger do nothing.                                                      | Same as Open.                                                                                                            |
+| **Dismissing**     | Click-outside / Escape inside surface / scroll-outside (if `closeOnScroll`) / iframe-focus move | `onOpenChange(e, { open: false, type })` fires with the originating DOM event. Consumer decides to close by updating state or letting uncontrolled state flip.                                                                      | `aria-expanded` returns to `"false"` on trigger.                                                                         |
+| **Nested**         | Popover rendered inside another Popover's surface                                               | Each instance manages its own Escape / click-outside. Escape filters via `e.target.closest('[data-popover-surface]') === ownSurface` — no `stopPropagation`, no cross-popover coupling.                                             | Each surface keeps its own `role` / `aria-modal`.                                                                        |
+
+## Keyboard Navigation
+
+### On trigger
+
+| Key                              | Action                                                                                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Enter / Space**                | Toggle open state. (Provided by `useARIAButtonProps` when the child is not already a button/link; disabled when `openOnContext={true}`.) |
+| **Escape**                       | If the surface is open, close it. (Handled on trigger + inside surface — see below.)                                                     |
+| **Context-menu key / Shift+F10** | Fires the native `contextmenu` event. When `openOnContext={true}`, opens the popover.                                                    |
+
+### Inside surface
+
+| Key               | Action                                                                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tab**           | Move focus to next focusable descendant. With `trapFocus={true}`, wraps at the last focusable back to the first.                                    |
+| **Shift + Tab**   | Move focus to previous. Wraps at first back to last when `trapFocus={true}`.                                                                        |
+| **Escape**        | Dismiss the current popover. Filtered to the nearest enclosing surface, so Escape in a nested popover only closes that popover — not its ancestors. |
+| **Enter / Space** | Default button activation inside the surface.                                                                                                       |
+
+## Events
+
+| Event          | Signature                                                                       | When it fires                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `onOpenChange` | `(e: SyntheticEvent \| DOMEvent, data: { event; type; open: boolean }) => void` | Whenever the popover wants to open or close (trigger click, trigger keyboard activation, hover, context menu, Escape, click-outside, scroll-outside, iframe focus move). |
+
+There is no separate `onDismiss`. The `open: false` dispatches go through `onOpenChange` with a `type` that identifies the source (`'click'`, `'keydown'`, `'mouseleave'`, `'contextmenu'`, `'scroll'`, …).
+
+## Accessibility
+
+### ARIA pattern
+
+```tsx
+// Trigger
+<button
+  aria-expanded={open ? 'true' : 'false'}
+  aria-haspopup={trapFocus ? 'dialog' : 'true'}
+  data-open={open || undefined}
+  // click / keydown / context / hover handlers merged onto the cloned child
+/>
+
+// Surface (inline mode)
+<div
+  role={trapFocus ? 'dialog' : 'group'}
+  aria-modal={trapFocus ? true : undefined}
+  data-popover-surface=""
+  data-placement="below-start"   // requested placement; live-updated by observer
+  data-open="true"
+  tabIndex={trapFocus ? -1 : undefined}
+/>
+
+// Surface (top layer mode — non-inline, default)
+<div
+  popover="manual"
+  role="group" /* or "dialog" */
+  data-popover-surface=""
+  data-placement="below-start"
+  data-open="true"
+/>
+```
+
+### Role selection
+
+- **`role="group"`** (default) — non-modal popover with no focus trap. Fine for menus, cards, informational overlays.
+- **`role="dialog"`** — set automatically when `trapFocus={true}`. Makes the surface a modal dialog with `aria-modal="true"` and `aria-haspopup="dialog"` on the trigger.
+
+The package does not implement `role="alertdialog"`; consumers needing an alert pattern should use the `Dialog` headless component instead.
+
+### Focus management
+
+Focus is governed by the shared `useFocusScope` hook (same hook Dialog uses):
+
+- **Initial focus on open** —
+  - `disableAutoFocus={true}` → no focus moves.
+  - Surface has a numeric `tabIndex` → focus the surface itself (`preventScroll: true`).
+  - Otherwise → focus the first focusable descendant. If there isn't one and `trapFocus={true}`, the surface's own `tabIndex={-1}` catches focus.
+- **Focus trap** — when `trapFocus={true}`, Tab/Shift+Tab wrap inside the surface; outside elements cannot receive focus.
+- **Restore focus on close** — focus returns to whatever element was focused immediately before the surface mounted (usually the trigger).
+
+### Labeling
+
+- For `role="dialog"` popovers, the consumer is responsible for providing an accessible name — typically via `aria-labelledby` pointing to a heading inside the surface, or `aria-label`.
+- For `role="group"` popovers, labels are optional but recommended when the surface's role in the interface isn't obvious from nearby context.
+- The trigger's accessible name remains the child element's own name (the component does nothing that would clobber it).
+
+### Live regions
+
+The headless Popover does **not** add `aria-live` to the surface. Consumers rendering dynamic content (loading states, async messages) inside the surface should wrap the dynamic region in their own live region.
+
+## Positioning
+
+Placement is handled entirely by the `usePositioning` hook, which writes native CSS anchor-positioning properties onto the surface element. No JS layout loop.
+
+### Options (all optional)
+
+| Option                    | Type                                                  | Default      | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `position`                | `'above' \| 'below' \| 'before' \| 'after'`           | `'above'`    | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized.                                                                                                                                                                                                                                                                                                                                              |
+| `align`                   | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'`   | `'center'`   | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases).                                                                                                                                                                                                                                                                                                                                                                                   |
+| `offset`                  | `number \| { mainAxis?: number; crossAxis?: number }` | `0`          | Logical-margin offset from the anchor.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `fallbackPositions`       | `PositioningShorthandValue[]`                         | `[]`         | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`.                                                                                                                                                                                                                                                                                                                                         |
+| `coverTarget`             | `boolean`                                             | `false`      | Overlap the anchor instead of sitting beside it.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `pinned`                  | `boolean`                                             | `false`      | Disable fallback flipping; surface stays at the requested placement even if it overflows.                                                                                                                                                                                                                                                                                                                                                               |
+| `matchTargetSize`         | `'width'`                                             | —            | Sets the surface's `width` to `anchor-size(width)`.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `strategy`                | `'fixed' \| 'absolute'`                               | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes.                                                                                                                                                                                                                                                                    |
+| `target`                  | `HTMLElement \| RefObject`                            | —            | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger.                                                                                                                                                                                                                                                                                                                                                       |
+| `positioningRef`          | `Ref<PositioningImperativeRef>`                       | —            | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates.                                                                                                                                                                                                                                                                                                                                       |
+| `autoSize`                | `boolean \| 'width' \| 'height'`                      | `false`      | Cap the surface dimensions against `overflowBoundary`. Requires `overflowBoundary` — pure-CSS autoSize isn't possible due to spec-level restrictions on `anchor()` in `max-*`.                                                                                                                                                                                                                                                                          |
+| `overflowBoundary`        | `HTMLElement \| RefObject`                            | —            | Element the surface must stay inside. Drives a JS-measured `transform: translate3d()` **cross-axis shift** whenever the primary placement would exceed the boundary. Accepts a DOM element or a React ref to one. When paired with `autoSize`, the same rect is used to compute `max-*` caps. `overflowBoundaryPadding` adds breathing room on top of the shift.                                                                                        |
+| `overflowBoundaryPadding` | `number \| { top, end, bottom, start }`               | —            | Breathing room kept between the surface and the `overflowBoundary` rect. Implemented as a JS-measured `transform: translate3d()` **cross-axis shift** on the surface (only — main-axis overflow is native flip's job, matching v9 / Floating UI's `shift()` middleware). Does not affect the surface's size. Accepts a uniform number or a logical-side object (RTL-aware). Has no effect when `overflowBoundary` is unset or when `coverTarget` is on. |
+
+### Rendering
+
+- The hook writes `anchor-name: --popover-anchor-<id>` on the anchor (trigger or custom target) via `useIsomorphicLayoutEffect`.
+- On the surface it writes `position: absolute` (or `fixed` if `strategy: 'fixed'`); `inset: auto; margin: 0; position-anchor: --popover-anchor-<id>; position-area: <value>; position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline`. The `inset: auto; margin: 0` reset is required because the UA popover stylesheet sets `inset: 0; margin: auto`, which fights `position-area`.
+- For center alignment, the hook also writes `place-self: anchor-center` as a workaround for https://crbug.com/438334710 (Chromium <=130 doesn't reliably apply the implicit anchor-center self-alignment to single-keyword `position-area` values).
+- `data-placement` is set to the requested placement and then live-updated by `usePlacementObserver` (ResizeObserver + scroll listener) to reflect the browser's post-flip decision.
+
+### Arrow
+
+Arrow positioning is **consumer-owned CSS** keyed off `[data-placement]`. The hook doesn't manipulate the arrow element. Consumers writing arrow styles typically target `[data-placement^='above']`, `[data-placement^='below']`, etc., and use anchor queries (`@container anchored()`) for flip-aware styling when supported.
+
+## Dismissal
+
+All dismissal paths are React-side (not the UA `popover="auto"` light-dismiss), so every `open: false` transition carries the originating event:
+
+| Source                  | Mechanism                                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Click outside           | `useOnClickOutside` across `triggerRef` + `contentRef`, optionally gated on `closeOnIframeFocus` behaviour. |
+| Escape inside surface   | `onKeyDown` on the surface filters to `e.target.closest('[data-popover-surface]') === contentRef.current`.  |
+| Scroll outside (opt-in) | `useOnScrollOutside` with `closeOnScroll` or `openOnContext`.                                               |
+| Iframe focus (external) | Same mechanism as click-outside; `closeOnIframeFocus` gates the "iframe focus" case.                        |
+| Programmatic            | Consumer sets `open={false}` or the uncontrolled state flips via toggleOpen.                                |
+
+`openOnHover` close fires only after `mouseLeaveDelay` ms of pointer being outside both trigger and surface.
+
+## Controlled vs uncontrolled
+
+### Uncontrolled
+
+```tsx
+<Popover defaultOpen={false} positioning="below-start">
+  <PopoverTrigger>
+    <button>Open</button>
+  </PopoverTrigger>
+  <PopoverSurface>…content…</PopoverSurface>
+</Popover>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = React.useState(false);
+
+<Popover open={open} onOpenChange={(_, data) => setOpen(data.open)} positioning={{ position: 'below', align: 'start' }}>
+  <PopoverTrigger>
+    <button>Open</button>
+  </PopoverTrigger>
+  <PopoverSurface>…content…</PopoverSurface>
+</Popover>;
+```
+
+### Without a trigger
+
+```tsx
+const triggerRef = React.useRef<HTMLButtonElement>(null);
+
+<>
+  <button ref={triggerRef}>External trigger</button>
+  <Popover open={open} positioning={{ target: triggerRef }}>
+    <PopoverSurface>…</PopoverSurface>
+  </Popover>
+</>;
+```
+
+## RTL support
+
+Positioning uses CSS _logical_ properties throughout (`block-start`, `block-end`, `inline-start`, `inline-end`, `margin-inline-start`, …), so placement semantics flip correctly in RTL:
+
+- `position: 'before'` anchors on the inline-start side — left in LTR, right in RTL.
+- `align: 'start'` anchors at the writing-mode start — top in horizontal-tb, left in vertical-rl.
+- Physical v9 aliases (`top` / `bottom` / `left` / `right`) are normalized at the shorthand boundary and become logical internally.
+
+## Native API surface
+
+The package relies on three native browser APIs:
+
+- **CSS Anchor Positioning** (Chromium 125+) — `anchor-name`, `position-anchor`, `position-area`, `anchor-size()`, `position-try-fallbacks`.
+- **HTML Popover API** (Chromium 114+) — `popover="manual"` + `showPopover()` for top-layer elevation. Feature-detected (`typeof el.showPopover === 'function'`); SSR-safe; `inline={true}` opts out entirely.
+- **ResizeObserver** — used sparingly by `usePlacementObserver` (for live `data-placement`) and `useAutoSizeBoundary` (for boundary-aware `max-*`).
+
+Firefox and Safari are implementing CSS Anchor Positioning; most features work but flip behaviour is still WIP. `inline={true}` works in every engine.
+
+## Notes
+
+- **Top layer vs inline**: by default the surface is promoted to the top layer via `showPopover()`, which escapes `overflow: hidden` and `z-index` stacking contexts. Set `inline={true}` for scenarios where the surface must stay within a containing block (containerized demos, `contain: layout` ancestors).
+- **Nested popovers**: each popover runs its own Escape / click-outside handlers. Escape in a nested surface closes only that surface.
+- **Hover-to-open**: `openOnHover` opens on `mouseenter` of the trigger and _stays_ open while the pointer is over the surface (the surface has its own `mouseenter`/`mouseleave` handlers). `mouseLeaveDelay` protects against accidental close during pointer transitions.
+- **Context popovers**: when `openOnContext={true}`, the mouse event's `clientX` / `clientY` are stored as `contextTarget` state — available to consumers via the popover context if they want to anchor the surface at the cursor position instead of on the trigger.
+- **Positioning is CSS, not JS**: because placement computation is pushed to the browser, there's no JS layout loop and `positioning.updatePosition()` is a no-op. Consumers that need imperative retargeting use `positioning.setTarget(el)`.
diff --git a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
new file mode 100644
index 00000000000000..df2e9427dc472a
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
@@ -0,0 +1,183 @@
+## API Report File for "@fluentui/react-headless-components-preview"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { ComponentProps } from '@fluentui/react-utilities';
+import type { ComponentState } from '@fluentui/react-utilities';
+import type { ContextSelector } from '@fluentui/react-context-selector';
+import type { EventData } from '@fluentui/react-utilities';
+import type { EventHandler } from '@fluentui/react-utilities';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import type { JSXElement } from '@fluentui/react-utilities';
+import * as React_2 from 'react';
+import type { Slot } from '@fluentui/react-utilities';
+
+// @public (undocumented)
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+
+// @public
+export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
+    open: boolean;
+};
+
+// @public
+export type OpenPopoverEvents = MouseEvent | TouchEvent | React_2.FocusEvent<HTMLElement> | React_2.KeyboardEvent<HTMLElement> | React_2.MouseEvent<HTMLElement>;
+
+// @public
+export const Popover: {
+    (props: PopoverProps): JSXElement;
+    displayName: string;
+};
+
+// @public
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+    positioning: {
+        targetRef: React_2.RefCallback<HTMLElement>;
+        containerRef: React_2.RefCallback<HTMLElement>;
+    };
+};
+
+// @public
+export type PopoverProps = {
+    children: [JSXElement, JSXElement] | JSXElement;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: EventHandler<OnOpenChangeData>;
+    openOnHover?: boolean;
+    openOnContext?: boolean;
+    mouseLeaveDelay?: number;
+    positioning?: PositioningShorthand;
+    withArrow?: boolean;
+    trapFocus?: boolean;
+    disableAutoFocus?: boolean;
+    closeOnScroll?: boolean;
+    closeOnIframeFocus?: boolean;
+    inline?: boolean;
+    mountNode?: HTMLElement | null;
+};
+
+// @public
+export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
+    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
+    toggleOpen: (e: OpenPopoverEvents) => void;
+    triggerRef: React_2.RefObject<HTMLElement | null>;
+    contentRef: React_2.RefObject<HTMLElement | null>;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    popoverTrigger: React_2.ReactElement | undefined;
+    popoverSurface: React_2.ReactElement | undefined;
+    contextTarget: {
+        x: number;
+        y: number;
+    } | undefined;
+    setContextTarget: (target: {
+        x: number;
+        y: number;
+    } | undefined) => void;
+    positioning: PositioningReturn;
+};
+
+// @public
+export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps>;
+
+// @public (undocumented)
+export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
+
+// @public
+export type PopoverSurfaceSlots = {
+    root: Slot<'div'>;
+};
+
+// @public (undocumented)
+export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
+    inline: boolean;
+    withArrow: boolean | undefined;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    mountNode: HTMLElement | null | undefined;
+    'data-open': string;
+};
+
+// @public
+export const PopoverTrigger: React_2.FC<PopoverTriggerProps>;
+
+// @public
+export type PopoverTriggerProps = {
+    children: React_2.ReactElement;
+    disableButtonEnhancement?: boolean;
+};
+
+// @public
+export type PopoverTriggerState = {
+    children: React_2.ReactElement | null;
+};
+
+// @public (undocumented)
+export type Position = 'above' | 'below' | 'before' | 'after';
+
+// @public
+export type PositioningImperativeRef = {
+    setTarget: (target: HTMLElement | null) => void;
+    updatePosition: () => void;
+};
+
+// @public (undocumented)
+export type PositioningProps = {
+    position?: Position;
+    align?: Alignment;
+    offset?: number | {
+        mainAxis?: number;
+        crossAxis?: number;
+    };
+    fallbackPositions?: PositioningShorthandValue[];
+    coverTarget?: boolean;
+    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+    strategy?: 'absolute' | 'fixed';
+    matchTargetSize?: 'width';
+    pinned?: boolean;
+    positioningRef?: React_2.Ref<PositioningImperativeRef>;
+};
+
+// @public (undocumented)
+export type PositioningReturn = {
+    targetRef: React_2.RefCallback<HTMLElement>;
+    containerRef: React_2.RefCallback<HTMLElement>;
+};
+
+// @public (undocumented)
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+// @public (undocumented)
+export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
+
+// @public
+export const renderPopover: (state: PopoverState, contextValues: {
+    popover: PopoverContextValue;
+}) => React_2.ReactElement;
+
+// @public
+export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
+
+// @public
+export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
+
+// @public
+export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
+
+// @public
+export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
+
+// @public (undocumented)
+export const usePopoverContextValues: (state: PopoverState) => {
+    popover: PopoverContextValue;
+};
+
+// @public
+export const usePopoverSurface: (props: PopoverSurfaceProps, ref: React_2.Ref<HTMLDivElement>) => PopoverSurfaceState;
+
+// @public
+export const usePopoverTrigger: (props: PopoverTriggerProps) => PopoverTriggerState;
+
+// (No @packageDocumentation comment for this package)
+
+```
diff --git a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
new file mode 100644
index 00000000000000..6bef1c6e594fed
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
@@ -0,0 +1,9 @@
+## API Report File for "@fluentui/react-headless-components-preview"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// (No @packageDocumentation comment for this package)
+
+```
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
index d58af7ca8f08a6..8113ab8171f688 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
@@ -1,5 +1,12 @@
 import type * as React from 'react';
-import type { ComponentProps, ComponentState, EventData, EventHandler, Slot } from '@fluentui/react-utilities';
+import type {
+  ComponentProps,
+  ComponentState,
+  EventData,
+  EventHandler,
+  Slot,
+  JSXElement,
+} from '@fluentui/react-utilities';
 import type { PositioningShorthand, PositioningReturn } from '../../hooks/usePositioning';
 
 /**
@@ -24,10 +31,10 @@ export type OnOpenChangeData = EventData<string, React.SyntheticEvent | Event> &
  */
 export type PopoverProps = {
   /**
-   * Can contain two children including PopoverTrigger and PopoverSurface.
-   * Alternatively can only contain PopoverSurface if using a custom target.
+   * Can contain two children including `PopoverTrigger` and `PopoverSurface`.
+   * Alternatively can only contain `PopoverSurface` if using a custom `target`.
    */
-  children: [React.ReactElement, React.ReactElement] | React.ReactElement;
+  children: [JSXElement, JSXElement] | JSXElement;
 
   /** Controlled open state. */
   open?: boolean;
@@ -190,6 +197,5 @@ export type PopoverContextValue = Pick<
   positioning: {
     targetRef: React.RefCallback<HTMLElement>;
     containerRef: React.RefCallback<HTMLElement>;
-    arrowRef: React.RefCallback<HTMLElement>;
   };
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
index 16b28d6e5df116..3f445ec06d3041 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
@@ -42,12 +42,10 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
     onMountAutoFocus,
   });
 
-  const mergedArrowRef = useMergedRefs(arrowRef, positioningCtx.arrowRef);
-
   const state: PopoverSurfaceState = {
     inline,
     withArrow,
-    arrowRef: mergedArrowRef as React.RefObject<HTMLDivElement | null>,
+    arrowRef,
     mountNode,
     components: { root: 'div' },
     root: slot.always(
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
index f802782cbd0dd8..05454b01f5b2fa 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/renderPopoverTrigger.ts
@@ -1,9 +1,9 @@
-import type * as React from 'react';
 import type { PopoverTriggerState } from './PopoverTrigger.types';
+import type { JSXElement } from '@fluentui/react-utilities';
 
 /**
  * Renders the PopoverTrigger (returns the cloned child element).
  */
-export const renderPopoverTrigger = (state: PopoverTriggerState): React.ReactElement | null => {
+export const renderPopoverTrigger = (state: PopoverTriggerState): JSXElement | null => {
   return state.children;
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
index 7b77492f5ebfc5..b024bd7cedc351 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
@@ -25,7 +25,6 @@ const popoverContextDefaultValue: PopoverContextValue = {
   positioning: {
     targetRef: () => undefined,
     containerRef: () => undefined,
-    arrowRef: () => undefined,
   },
 };
 
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index c4139c2546d026..65042544ea69e9 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -206,7 +206,6 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
       positioning: {
         targetRef: positioning.targetRef,
         containerRef: positioning.containerRef,
-        arrowRef: positioning.arrowRef,
       },
     },
   };
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
index 895e152d2e2641..082b2365a68b62 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/constants.ts
@@ -1,45 +1,38 @@
-import type { Position, Alignment } from './types';
+import type { LogicalAlignment, Position } from './types';
 
-export const FALLBACK_NAME_PREFIX = '--fluent-fallback-';
+export const GAP = 8;
 
 export const POSITIONS = {
   above: 'above',
   below: 'below',
   before: 'before',
   after: 'after',
-};
+} as const;
 
 export const ALIGNMENTS = {
   start: 'start',
   center: 'center',
   end: 'end',
-};
-
-export const FLIP_POSITION_MAP: Record<Position, Position> = {
-  above: 'below',
-  below: 'above',
-  before: 'after',
-  after: 'before',
-};
+} as const;
 
-export const POSITION_AREA_MAP: Record<Position, Record<Alignment, string>> = {
+export const POSITION_AREA_MAP: Record<Position, Record<LogicalAlignment, string>> = {
   above: {
-    center: 'block-start center',
+    center: 'block-start',
     start: 'block-start span-inline-end',
     end: 'block-start span-inline-start',
   },
   below: {
-    center: 'block-end center',
+    center: 'block-end',
     start: 'block-end span-inline-end',
     end: 'block-end span-inline-start',
   },
   before: {
-    center: 'center inline-start',
+    center: 'inline-start',
     start: 'inline-start span-block-end',
     end: 'inline-start span-block-start',
   },
   after: {
-    center: 'center inline-end',
+    center: 'inline-end',
     start: 'inline-end span-block-end',
     end: 'inline-end span-block-start',
   },
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
deleted file mode 100644
index 7aa4ce10e1d147..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/fallbackStyles.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import type { PositioningShorthandValue } from './types';
-import { ALIGNMENTS, POSITIONS } from './constants';
-import { FALLBACK_NAME_PREFIX, POSITION_AREA_MAP } from './constants';
-
-/**
- * Tracks documents that already have the `@position-try` fallback stylesheet
- * injected. Keyed by Document so iframes, test renderers, and multiple windows
- * each get their own injection.
- */
-const fallbackStylesInjected = new WeakSet<Document>();
-
-/**
- * Injects `@position-try` rules for every (position, align) combination into
- * the given document, once per document. Idempotent — subsequent calls with
- * the same document are no-ops.
- *
- * Each rule mirrors the primary-placement style: `position-area: X`, plus
- * `justify-self/align-self: center` for the center alignment case to match
- * `applyPositionAreaStyles`.
- */
-export function ensureFallbackStyles(targetDocument: Document | undefined): void {
-  if (!targetDocument || fallbackStylesInjected.has(targetDocument)) {
-    return;
-  }
-
-  fallbackStylesInjected.add(targetDocument);
-
-  let css = '';
-
-  for (const position of Object.values(POSITIONS)) {
-    for (const align of Object.values(ALIGNMENTS)) {
-      const suffix = align === ALIGNMENTS.center ? '' : `-${align}`;
-      const name = `${FALLBACK_NAME_PREFIX}${position}${suffix}`;
-      const area = POSITION_AREA_MAP[position][align];
-      const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
-      const selfValue = align === ALIGNMENTS.center ? 'center' : 'initial';
-      const justifySelf = isBlockMain ? selfValue : 'initial';
-      const alignSelf = isBlockMain ? 'initial' : selfValue;
-
-      const body = `position-area: ${area}; justify-self: ${justifySelf}; align-self: ${alignSelf};`;
-
-      css += `@position-try ${name} {\n  ${body}\n}\n`;
-    }
-  }
-
-  const style = targetDocument.createElement('style');
-  style.setAttribute('data-fluent-positioning-fallbacks', '');
-  style.textContent = css;
-  targetDocument.head.appendChild(style);
-}
-
-/** Maps a shorthand placement ("below", "above-end") to its `@position-try` rule name. */
-export function shorthandToFallbackName(shorthand: PositioningShorthandValue): string {
-  return `${FALLBACK_NAME_PREFIX}${shorthand}`;
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
index b8d3ec2b884df5..b624fb8c4170a2 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/index.ts
@@ -1,5 +1,6 @@
 export { usePositioning } from './usePositioning';
-export { getPlacementString, resolvePositioningShorthand } from './placement';
+export { getPlacementString, resolvePositioningShorthand } from './utils';
+export { POSITIONS, ALIGNMENTS } from './constants';
 export type {
   Position,
   Alignment,
@@ -9,4 +10,3 @@ export type {
   PositioningShorthand,
   PositioningShorthandValue,
 } from './types';
-export { POSITIONS, ALIGNMENTS } from './constants';
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
deleted file mode 100644
index 99127582a92412..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/placement.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import type { Position, Alignment, PositioningProps, PositioningShorthand } from './types';
-
-/**
- * Maps position + align to a human-readable placement string for the
- * `data-placement` attribute. Center alignment uses the bare position.
- */
-export function getPlacementString(position: Position, align: Alignment): string {
-  if (align === 'center') {
-    return position;
-  }
-
-  return `${position}-${align}`;
-}
-
-/**
- * Normalizes a {@link PositioningShorthand} (string or object) into a full
- * {@link PositioningProps} object. Strings like `'below-start'` parse into
- * `{ position: 'below', align: 'start' }`; objects pass through unchanged.
- */
-export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps {
-  if (!value) {
-    return {};
-  }
-
-  if (typeof value !== 'string') {
-    return value;
-  }
-
-  const dash = value.indexOf('-');
-
-  if (dash === -1) {
-    return { position: value as Position };
-  }
-
-  return {
-    position: value.slice(0, dash) as Position,
-    align: value.slice(dash + 1) as Alignment,
-  };
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
deleted file mode 100644
index f53a9f97a369ba..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/styleHelpers.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import type { Position, Alignment, PositioningProps } from './types';
-import { ALIGNMENTS, POSITIONS } from './constants';
-
-/** Applies `offset` as logical margins on the side facing the trigger. */
-export function applyOffsetStyles(node: HTMLElement, position: Position, mainAxis: number, crossAxis: number): void {
-  if (mainAxis) {
-    switch (position) {
-      case POSITIONS.above:
-        node.style.marginBlockEnd = `${mainAxis}px`;
-        break;
-      case POSITIONS.below:
-        node.style.marginBlockStart = `${mainAxis}px`;
-        break;
-      case POSITIONS.before:
-        node.style.marginInlineEnd = `${mainAxis}px`;
-        break;
-      case POSITIONS.after:
-        node.style.marginInlineStart = `${mainAxis}px`;
-        break;
-    }
-  }
-
-  if (crossAxis) {
-    switch (position) {
-      case POSITIONS.above:
-      case POSITIONS.below:
-        node.style.marginInlineStart = `${crossAxis}px`;
-        break;
-      case POSITIONS.before:
-      case POSITIONS.after:
-        node.style.marginBlockStart = `${crossAxis}px`;
-        break;
-    }
-  }
-}
-
-/**
- * Applies CSS-only `autoSize`: caps `max-width` / `max-height` to the viewport
- * minus an 8px gap. When an `overflowBoundary` is provided, the JS-based
- * `useAutoSizeBoundary` effect overrides these values with boundary-aware math.
- */
-export function applyAutoSize(node: HTMLElement, autoSize: PositioningProps['autoSize'], position: Position): void {
-  if (!autoSize) {
-    return;
-  }
-  const enableHeight = autoSize === true || autoSize === 'height';
-  const enableWidth = autoSize === true || autoSize === 'width';
-  // Breathing-room buffer (px) so the surface never touches the viewport edge.
-  // Consumers can shrink further via their own `max-width` / `max-height`.
-  const gap = 8;
-
-  if (enableHeight) {
-    switch (position) {
-      case POSITIONS.above:
-        node.style.maxHeight = `calc(anchor(top) - ${gap}px)`;
-        break;
-      case POSITIONS.below:
-        node.style.maxHeight = `calc(100dvh - anchor(bottom) - ${gap}px)`;
-        break;
-      case POSITIONS.before:
-      case POSITIONS.after:
-        node.style.maxHeight = `calc(100dvh - ${gap * 2}px)`;
-        break;
-    }
-  }
-
-  if (enableWidth) {
-    switch (position) {
-      case POSITIONS.before:
-        node.style.maxWidth = `calc(anchor(left) - ${gap}px)`;
-        break;
-      case POSITIONS.after:
-        node.style.maxWidth = `calc(100dvw - anchor(right) - ${gap}px)`;
-        break;
-      case POSITIONS.above:
-      case POSITIONS.below:
-        node.style.maxWidth = `calc(100dvw - ${gap * 2}px)`;
-        break;
-    }
-  }
-}
-
-/**
- * Returns the `align-self` / `justify-self` values that make the surface
- * cover the target (overlap instead of sit beside it).
- */
-export function getCoverSelfAlignment(
-  position: Position,
-  align: Alignment,
-): { alignSelf: string; justifySelf: string } {
-  if (position === POSITIONS.above) {
-    return { alignSelf: ALIGNMENTS.end, justifySelf: align };
-  }
-
-  if (position === POSITIONS.below) {
-    return { alignSelf: ALIGNMENTS.start, justifySelf: align };
-  }
-
-  if (position === POSITIONS.before) {
-    return { alignSelf: align, justifySelf: ALIGNMENTS.end };
-  }
-
-  return { alignSelf: align, justifySelf: ALIGNMENTS.start };
-}
-
-/**
- * Writes `position-area` on the surface. For center alignment also sets
- * `justify-self/align-self: center` so the surface centers within the
- * anchor-sized cell — this is what lets the built-in `flip-block`/`flip-inline`
- * fallbacks natively flip the surface on overflow.
- */
-export function applyPositionAreaStyles(
-  node: HTMLElement,
-  positionArea: string,
-  position: Position,
-  align: Alignment,
-): void {
-  node.style.setProperty('position-area', positionArea);
-  node.style.removeProperty('top');
-  node.style.removeProperty('bottom');
-  node.style.removeProperty('left');
-  node.style.removeProperty('right');
-
-  if (align === ALIGNMENTS.center) {
-    const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
-    if (isBlockMain) {
-      node.style.setProperty('justify-self', 'center');
-      node.style.removeProperty('align-self');
-    } else {
-      node.style.setProperty('align-self', 'center');
-      node.style.removeProperty('justify-self');
-    }
-  } else {
-    node.style.removeProperty('justify-self');
-    node.style.removeProperty('align-self');
-  }
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
index 4fb89ab36ec23b..503e486b23ff7d 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts
@@ -1,8 +1,18 @@
 import type * as React from 'react';
-import type { POSITIONS, ALIGNMENTS } from './constants';
 
-export type Position = (typeof POSITIONS)[keyof typeof POSITIONS];
-export type Alignment = (typeof ALIGNMENTS)[keyof typeof ALIGNMENTS];
+export type Position = 'above' | 'below' | 'before' | 'after';
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+export type LogicalAlignment = 'start' | 'center' | 'end';
+
+/**
+ * Imperative API exposed via `PositioningProps.positioningRef`.
+ */
+export type PositioningImperativeRef = {
+  /** Retarget the surface to the given element (or clear the target with `null`). */
+  setTarget: (target: HTMLElement | null) => void;
+  /** Request a position recomputation. With CSS anchor positioning layout is automatic, so this is a no-op on supporting browsers. */
+  updatePosition: () => void;
+};
 
 export type PositioningShorthandValue =
   | 'above'
@@ -12,13 +22,11 @@ export type PositioningShorthandValue =
   | 'below-start'
   | 'below-end'
   | 'before'
-  | 'before-top'
-  | 'before-bottom'
+  | 'before-start'
+  | 'before-end'
   | 'after'
-  | 'after-top'
-  | 'after-bottom';
-
-export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+  | 'after-start'
+  | 'after-end';
 
 export type PositioningProps = {
   /**
@@ -40,8 +48,6 @@ export type PositioningProps = {
   fallbackPositions?: PositioningShorthandValue[];
   /** Position on top of the target */
   coverTarget?: boolean;
-  /** Auto-size to available space */
-  autoSize?: boolean | 'width' | 'height';
   /**
    * Custom anchor element for the positioned surface. When provided, the
    * anchor-name is written to this element instead of the target assigned via
@@ -49,8 +55,8 @@ export type PositioningProps = {
    */
   target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
   /**
-   * CSS `position` value used on the positioned surface.
-   * @default 'fixed'
+   * CSS `position` value used on the positioned surface. Matches v9's default.
+   * @default 'absolute'
    */
   strategy?: 'absolute' | 'fixed';
   /**
@@ -71,29 +77,11 @@ export type PositioningProps = {
    * triggering a position update. See {@link PositioningImperativeRef}.
    */
   positioningRef?: React.Ref<PositioningImperativeRef>;
-  /**
-   * Element that clips the surface when `autoSize` is set. Instead of
-   * constraining the surface to the viewport, `max-width` / `max-height`
-   * are computed from this element's rect. Accepts a DOM element or ref.
-   */
-  overflowBoundary?: HTMLElement | React.RefObject<HTMLElement | null> | null;
 };
 
-/**
- * Imperative API exposed via `PositioningProps.positioningRef`.
- */
-export type PositioningImperativeRef = {
-  /** Retarget the surface to the given element (or clear the target with `null`). */
-  setTarget: (target: HTMLElement | null) => void;
-  /** Request a position recomputation. With CSS anchor positioning layout is automatic, so this is a no-op on supporting browsers. */
-  updatePosition: () => void;
-};
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
 
 export type PositioningReturn = {
-  /** Ref callback for the trigger / anchor element. */
   targetRef: React.RefCallback<HTMLElement>;
-  /** Ref callback for the positioned surface element. Sets anchor-binding styles and `data-placement`. */
   containerRef: React.RefCallback<HTMLElement>;
-  /** Ref callback for the arrow element. */
-  arrowRef: React.RefCallback<HTMLElement>;
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
deleted file mode 100644
index 179c4fb089e745..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAnchorName.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-'use client';
-
-import * as React from 'react';
-import { useId } from '@fluentui/react-utilities';
-
-/**
- * Generates a unique `anchor-name` and keeps it applied to whichever target
- * element is currently active. Swapping targets clears the previous element's
- * `anchor-name`; unmounting clears the last-known target.
- *
- * Returns the anchor-name string so the surface can reference it via
- * `position-anchor`.
- */
-export function useAnchorName(effectiveTarget: HTMLElement | null): string {
-  const anchorName = useId('--popover-anchor-');
-  const anchoredTargetRef = React.useRef<HTMLElement | null>(null);
-
-  React.useEffect(() => {
-    const prev = anchoredTargetRef.current;
-
-    if (prev && prev !== effectiveTarget) {
-      prev.style.removeProperty('anchor-name');
-    }
-
-    if (effectiveTarget) {
-      effectiveTarget.style.setProperty('anchor-name', anchorName);
-    }
-
-    anchoredTargetRef.current = effectiveTarget;
-  }, [effectiveTarget, anchorName]);
-
-  React.useEffect(() => {
-    return () => {
-      const last = anchoredTargetRef.current;
-
-      if (last) {
-        last.style.removeProperty('anchor-name');
-        anchoredTargetRef.current = null;
-      }
-    };
-  }, []);
-
-  return anchorName;
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
deleted file mode 100644
index e8982bd77e3adc..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/useAutoSizeBoundary.ts
+++ /dev/null
@@ -1,126 +0,0 @@
-'use client';
-
-import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
-import type { Position, Alignment, PositioningProps } from './types';
-import { ALIGNMENTS, POSITIONS } from './constants';
-import { resolveElementRef } from './resolvers';
-
-/**
- * Breathing-room buffer (px) subtracted when computing autoSize so the
- * surface never touches the boundary edge. Matches the default `padding` on
- * floating-ui's `shift()` middleware and canonical v9's Popover. Consumers
- * who need a different inset can layer their own `max-width` / `max-height`
- * / `padding` on the surface — the value this hook writes is a ceiling.
- */
-const GAP = 8;
-
-function computeAvailableHeight(
-  position: Position,
-  align: Alignment,
-  boundaryRect: DOMRect,
-  triggerRect: DOMRect,
-): number {
-  if (position === POSITIONS.above) {
-    return triggerRect.top - boundaryRect.top - GAP;
-  }
-  if (position === POSITIONS.below) {
-    return boundaryRect.bottom - triggerRect.bottom - GAP;
-  }
-
-  if (align === ALIGNMENTS.start) {
-    return boundaryRect.bottom - triggerRect.top - GAP;
-  }
-
-  if (align === ALIGNMENTS.end) {
-    return triggerRect.bottom - boundaryRect.top - GAP;
-  }
-
-  return boundaryRect.height - GAP * 2;
-}
-
-function computeAvailableWidth(
-  position: Position,
-  align: Alignment,
-  boundaryRect: DOMRect,
-  triggerRect: DOMRect,
-): number {
-  if (position === POSITIONS.before) {
-    return triggerRect.left - boundaryRect.left - GAP;
-  }
-
-  if (position === POSITIONS.after) {
-    return boundaryRect.right - triggerRect.right - GAP;
-  }
-
-  if (align === ALIGNMENTS.start) {
-    return boundaryRect.right - triggerRect.left - GAP;
-  }
-
-  if (align === ALIGNMENTS.end) {
-    return triggerRect.right - boundaryRect.left - GAP;
-  }
-
-  return boundaryRect.width - GAP * 2;
-}
-
-export type UseAutoSizeBoundaryOptions = {
-  autoSize: PositioningProps['autoSize'];
-  overflowBoundary: PositioningProps['overflowBoundary'];
-  containerEl: HTMLElement | null;
-  targetEl: HTMLElement | null;
-  position: Position;
-  align: Alignment;
-  targetDocument: Document | undefined;
-};
-
-/**
- * When `autoSize` is combined with an `overflowBoundary`, size the surface
- * against the boundary's rect rather than the viewport. The CSS-based
- * `applyAutoSize` runs first (and handles the no-boundary case); this effect
- * overrides `max-width` / `max-height` with boundary-aware values and keeps
- * them in sync via a `ResizeObserver`.
- */
-export function useAutoSizeBoundary({
-  autoSize,
-  overflowBoundary,
-  containerEl,
-  targetEl,
-  position,
-  align,
-  targetDocument,
-}: UseAutoSizeBoundaryOptions): void {
-  useIsomorphicLayoutEffect(() => {
-    if (!autoSize || !containerEl || !targetEl) {
-      return;
-    }
-    const boundary = resolveElementRef(overflowBoundary);
-    const ResizeObserverCtor = targetDocument?.defaultView?.ResizeObserver;
-    if (!boundary || !ResizeObserverCtor) {
-      return;
-    }
-
-    const applyHeight = autoSize === true || autoSize === 'height';
-    const applyWidth = autoSize === true || autoSize === 'width';
-    const surface = containerEl;
-
-    const apply = () => {
-      const boundaryRect = boundary.getBoundingClientRect();
-      const triggerRect = targetEl.getBoundingClientRect();
-      if (applyHeight) {
-        const available = computeAvailableHeight(position, align, boundaryRect, triggerRect);
-        surface.style.maxHeight = `${Math.max(0, available)}px`;
-      }
-      if (applyWidth) {
-        const available = computeAvailableWidth(position, align, boundaryRect, triggerRect);
-        surface.style.maxWidth = `${Math.max(0, available)}px`;
-      }
-    };
-
-    apply();
-
-    const observer = new ResizeObserverCtor(apply);
-    observer.observe(boundary);
-    observer.observe(targetEl);
-    return () => observer.disconnect();
-  }, [autoSize, overflowBoundary, containerEl, targetEl, position, align, targetDocument]);
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementObserver.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementObserver.ts
new file mode 100644
index 00000000000000..69320196b42b0a
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementObserver.ts
@@ -0,0 +1,110 @@
+'use client';
+
+import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import type { LogicalAlignment, Position } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+import { getPlacementString } from './utils/placement';
+
+const PLACEMENT_TOLERANCE = 2;
+
+const closeTo = (a: number, b: number): boolean => Math.abs(a - b) <= PLACEMENT_TOLERANCE;
+
+function detectPosition(surfaceRect: DOMRect, targetRect: DOMRect): Position | null {
+  if (surfaceRect.bottom <= targetRect.top + PLACEMENT_TOLERANCE) {
+    return POSITIONS.above;
+  }
+
+  if (surfaceRect.top >= targetRect.bottom - PLACEMENT_TOLERANCE) {
+    return POSITIONS.below;
+  }
+
+  if (surfaceRect.right <= targetRect.left + PLACEMENT_TOLERANCE) {
+    return POSITIONS.before;
+  }
+
+  if (surfaceRect.left >= targetRect.right - PLACEMENT_TOLERANCE) {
+    return POSITIONS.after;
+  }
+
+  return null;
+}
+
+function detectAlign(position: Position, surfaceRect: DOMRect, targetRect: DOMRect): LogicalAlignment {
+  const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
+
+  const startAligned = isBlockMain
+    ? closeTo(surfaceRect.left, targetRect.left)
+    : closeTo(surfaceRect.top, targetRect.top);
+
+  if (startAligned) {
+    return ALIGNMENTS.start;
+  }
+
+  const endAligned = isBlockMain
+    ? closeTo(surfaceRect.right, targetRect.right)
+    : closeTo(surfaceRect.bottom, targetRect.bottom);
+
+  if (endAligned) {
+    return ALIGNMENTS.end;
+  }
+
+  return ALIGNMENTS.center;
+}
+
+/**
+ * Pure-observation hook: reads the rendered rects of the surface and anchor
+ * and mirrors the resolved placement into the surface's `data-placement`
+ * attribute. This keeps the attribute in sync with the browser's decision
+ * after native flip fires (scroll, resize, ResizeObserver tick).
+ *
+ */
+export function usePlacementObserver(
+  containerEl: HTMLElement | null,
+  targetEl: HTMLElement | null,
+  targetDocument: Document | undefined,
+  disabled = false,
+): void {
+  useIsomorphicLayoutEffect(() => {
+    if (disabled || !containerEl || !targetEl) {
+      return;
+    }
+
+    const win = targetDocument?.defaultView;
+
+    if (!win) {
+      return;
+    }
+
+    const update = () => {
+      const surfaceRect = containerEl.getBoundingClientRect();
+      const targetRect = targetEl.getBoundingClientRect();
+      const position = detectPosition(surfaceRect, targetRect);
+
+      if (!position) {
+        return;
+      }
+
+      const align = detectAlign(position, surfaceRect, targetRect);
+      const next = getPlacementString(position, align);
+
+      if (containerEl.getAttribute('data-placement') !== next) {
+        containerEl.setAttribute('data-placement', next);
+      }
+    };
+
+    update();
+
+    const ResizeObserverCtor = win.ResizeObserver;
+    const observer = ResizeObserverCtor ? new ResizeObserverCtor(update) : null;
+    observer?.observe(containerEl);
+    observer?.observe(targetEl);
+    win.addEventListener('scroll', update, true);
+    win.addEventListener('resize', update);
+
+    return () => {
+      observer?.disconnect();
+      win.removeEventListener('scroll', update, true);
+      win.removeEventListener('resize', update);
+    };
+  }, [containerEl, targetEl, targetDocument, disabled]);
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
deleted file mode 100644
index a897be934dc561..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePlacementSync.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-'use client';
-
-import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
-import type { Position, Alignment } from './types';
-import { ALIGNMENTS, POSITIONS } from './constants';
-import { FLIP_POSITION_MAP, POSITION_AREA_MAP } from './constants';
-import { getPlacementString } from './placement';
-
-const PLACEMENT_TOLERANCE = 2;
-
-const closeTo = (a: number, b: number) => Math.abs(a - b) <= PLACEMENT_TOLERANCE;
-
-function detectPosition(surfaceRect: DOMRect, targetRect: DOMRect): Position | null {
-  if (surfaceRect.bottom <= targetRect.top + PLACEMENT_TOLERANCE) {
-    return POSITIONS.above;
-  }
-
-  if (surfaceRect.top >= targetRect.bottom - PLACEMENT_TOLERANCE) {
-    return POSITIONS.below;
-  }
-
-  if (surfaceRect.right <= targetRect.left + PLACEMENT_TOLERANCE) {
-    return POSITIONS.before;
-  }
-
-  if (surfaceRect.left >= targetRect.right - PLACEMENT_TOLERANCE) {
-    return POSITIONS.after;
-  }
-
-  return null;
-}
-
-function detectAlign(position: Position, surfaceRect: DOMRect, targetRect: DOMRect): Alignment {
-  const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
-  const startAligned = isBlockMain
-    ? closeTo(surfaceRect.left, targetRect.left)
-    : closeTo(surfaceRect.top, targetRect.top);
-
-  if (startAligned) {
-    return ALIGNMENTS.start;
-  }
-
-  const endAligned = isBlockMain
-    ? closeTo(surfaceRect.right, targetRect.right)
-    : closeTo(surfaceRect.bottom, targetRect.bottom);
-
-  if (endAligned) {
-    return ALIGNMENTS.end;
-  }
-
-  return ALIGNMENTS.center;
-}
-
-function detectActualPlacement(
-  surfaceRect: DOMRect,
-  targetRect: DOMRect,
-): { position: Position; align: Alignment } | null {
-  const position = detectPosition(surfaceRect, targetRect);
-  if (!position) {
-    return null;
-  }
-  return { position, align: detectAlign(position, surfaceRect, targetRect) };
-}
-
-function decideFlip(
-  requested: Position,
-  surfaceRect: DOMRect,
-  targetRect: DOMRect,
-  win: Window,
-  mainOffset: number,
-): Position {
-  const isBlockMain = requested === POSITIONS.above || requested === POSITIONS.below;
-
-  if (isBlockMain) {
-    const needed = surfaceRect.height + mainOffset;
-    const spaceBelow = win.innerHeight - targetRect.bottom;
-    const spaceAbove = targetRect.top;
-    const preferSpace = requested === POSITIONS.below ? spaceBelow : spaceAbove;
-    const otherSpace = requested === POSITIONS.below ? spaceAbove : spaceBelow;
-    return preferSpace < needed && otherSpace > preferSpace ? FLIP_POSITION_MAP[requested] : requested;
-  }
-
-  const needed = surfaceRect.width + mainOffset;
-  const spaceAfter = win.innerWidth - targetRect.right;
-  const spaceBefore = targetRect.left;
-  const preferSpace = requested === POSITIONS.after ? spaceAfter : spaceBefore;
-  const otherSpace = requested === POSITIONS.after ? spaceBefore : spaceAfter;
-  return preferSpace < needed && otherSpace > preferSpace ? FLIP_POSITION_MAP[requested] : requested;
-}
-
-export type UsePlacementSyncOptions = {
-  containerEl: HTMLElement | null;
-  targetEl: HTMLElement | null;
-  coverTarget: boolean;
-  pinned: boolean;
-  useCssFallbacks: boolean;
-  position: Position;
-  align: Alignment;
-  mainOffset: number;
-  targetDocument: Document | undefined;
-};
-
-export function usePlacementSync({
-  containerEl,
-  targetEl,
-  coverTarget,
-  pinned,
-  useCssFallbacks,
-  position,
-  align,
-  mainOffset,
-  targetDocument,
-}: UsePlacementSyncOptions): void {
-  useIsomorphicLayoutEffect(() => {
-    if (!containerEl || !targetEl || coverTarget) {
-      return;
-    }
-
-    const win = targetDocument?.defaultView;
-
-    if (!win) {
-      return;
-    }
-
-    const update = () => {
-      if (!pinned && !useCssFallbacks) {
-        const effective = decideFlip(
-          position,
-          containerEl.getBoundingClientRect(),
-          targetEl.getBoundingClientRect(),
-          win,
-          mainOffset,
-        );
-
-        const nextArea = POSITION_AREA_MAP[effective][align];
-
-        if (containerEl.style.getPropertyValue('position-area') !== nextArea) {
-          containerEl.style.setProperty('position-area', nextArea);
-        }
-      }
-
-      const actual = detectActualPlacement(containerEl.getBoundingClientRect(), targetEl.getBoundingClientRect());
-
-      if (!actual) {
-        return;
-      }
-
-      const next = getPlacementString(actual.position, actual.align);
-
-      if (containerEl.getAttribute('data-placement') !== next) {
-        containerEl.setAttribute('data-placement', next);
-      }
-    };
-
-    update();
-
-    const ResizeObserverCtor = win.ResizeObserver;
-    const observer = ResizeObserverCtor ? new ResizeObserverCtor(update) : null;
-    observer?.observe(containerEl);
-    observer?.observe(targetEl);
-    win.addEventListener('scroll', update, true);
-    win.addEventListener('resize', update);
-
-    return () => {
-      observer?.disconnect();
-      win.removeEventListener('scroll', update, true);
-      win.removeEventListener('resize', update);
-    };
-  }, [containerEl, targetEl, coverTarget, pinned, useCssFallbacks, position, align, mainOffset, targetDocument]);
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
index 178b658b8d5a1d..31018f373c2d63 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
@@ -1,14 +1,9 @@
 import * as React from 'react';
 import { act, render } from '@testing-library/react';
 import { usePositioning } from './usePositioning';
-import { getPlacementString } from './placement';
+import { getPlacementString } from './utils/placement';
 import type { PositioningProps, PositioningReturn } from './types';
 
-/**
- * Lightweight alternative to `renderHook` (not available across the React 17/18
- * versions matrix we test). Renders a component that calls the hook and exposes
- * its return value via a ref.
- */
 function mountHook(options: PositioningProps = {}) {
   const resultRef = React.createRef<{ current: PositioningReturn }>();
   const Capture = () => {
@@ -21,47 +16,144 @@ function mountHook(options: PositioningProps = {}) {
 }
 
 describe('usePositioning', () => {
-  it('returns targetRef, containerRef, and arrowRef callbacks', () => {
+  it('returns targetRef and containerRef callbacks', () => {
     const result = mountHook();
 
     expect(typeof result.current.targetRef).toBe('function');
     expect(typeof result.current.containerRef).toBe('function');
-    expect(typeof result.current.arrowRef).toBe('function');
   });
 
-  it('targetRef causes anchor-name to be written to the trigger element', () => {
+  it('targetRef writes anchor-name onto the trigger element', () => {
     const result = mountHook();
     const node = document.createElement('div');
+
     act(() => {
       result.current.targetRef(node);
     });
+
     expect(node.style.getPropertyValue('anchor-name')).toMatch(/^--popover-anchor-/);
   });
 
-  it('containerRef writes data-placement derived from position and align', () => {
+  it('containerRef writes position-anchor and position-area matching the props', () => {
     const result = mountHook({ position: 'below', align: 'start' });
     const node = document.createElement('div');
     result.current.containerRef(node);
-    expect(node.getAttribute('data-placement')).toBe('below-start');
+
+    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
   });
 
-  it('containerRef applies position:fixed and position-anchor', () => {
+  it('containerRef writes position: absolute by default and clears the UA inset/margin defaults', () => {
     const result = mountHook();
     const node = document.createElement('div');
     result.current.containerRef(node);
+
+    expect(node.style.position).toBe('absolute');
+    expect(node.style.inset).toBe('auto');
+    expect(node.style.margin).toBe('0px');
+  });
+
+  it('containerRef honors strategy: "fixed"', () => {
+    const result = mountHook({ strategy: 'fixed' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
     expect(node.style.position).toBe('fixed');
-    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+  });
+
+  it('containerRef writes data-placement matching (position, align)', () => {
+    const result = mountHook({ position: 'below', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.getAttribute('data-placement')).toBe('below-start');
+  });
+
+  it('containerRef sets position-try-fallbacks to the three-try flip chain by default', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe(
+      'flip-block, flip-inline, flip-block flip-inline',
+    );
+  });
+
+  it('containerRef uses custom fallbackPositions verbatim when provided', () => {
+    const result = mountHook({ fallbackPositions: ['below-start', 'after'] });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('block-end span-inline-end, inline-end');
+  });
+
+  it('containerRef removes position-try-fallbacks when pinned', () => {
+    const result = mountHook({ pinned: true });
+    const node = document.createElement('div');
+    node.style.setProperty('position-try-fallbacks', 'flip-block');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('');
+  });
+
+  it('containerRef writes cover self-alignment when coverTarget is true', () => {
+    const result = mountHook({ coverTarget: true, position: 'above', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-area')).toBe('center');
+    expect(node.style.getPropertyValue('align-self')).toBe('end');
+    expect(node.style.getPropertyValue('justify-self')).toBe('start');
+  });
+
+  it('containerRef writes place-self: anchor-center for center alignment (crbug 438334710 workaround)', () => {
+    const result = mountHook({ position: 'above', align: 'center' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('place-self')).toBe('anchor-center');
+  });
+
+  it('containerRef does not write place-self for non-center alignments', () => {
+    const result = mountHook({ position: 'above', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('place-self')).toBe('');
+    expect(node.style.getPropertyValue('justify-self')).toBe('');
+    expect(node.style.getPropertyValue('align-self')).toBe('');
+  });
+
+  it('containerRef writes matchTargetSize width via anchor-size()', () => {
+    const result = mountHook({ matchTargetSize: 'width' });
+    const node = document.createElement('div');
+    const spy = jest.spyOn(node.style, 'setProperty');
+    result.current.containerRef(node);
+
+    expect(spy).toHaveBeenCalledWith('width', 'anchor-size(width)');
+    spy.mockRestore();
+  });
+
+  it('containerRef applies offset as logical margins', () => {
+    const result = mountHook({ position: 'below', offset: { mainAxis: 8, crossAxis: 4 } });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.marginBlockStart).toBe('8px');
+    expect(node.style.marginInlineStart).toBe('4px');
   });
 });
 
 describe('getPlacementString', () => {
-  it('returns position only for center alignment', () => {
+  it('returns the bare position for center alignment', () => {
     expect(getPlacementString('above', 'center')).toBe('above');
     expect(getPlacementString('below', 'center')).toBe('below');
   });
 
-  it('returns position-align for non-center alignment', () => {
+  it('returns position-align for non-center alignments', () => {
     expect(getPlacementString('above', 'start')).toBe('above-start');
     expect(getPlacementString('below', 'end')).toBe('below-end');
+    expect(getPlacementString('before', 'start')).toBe('before-start');
+    expect(getPlacementString('after', 'end')).toBe('after-end');
   });
 });
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
index 29747be3572f83..75723c0a97b799 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
@@ -1,166 +1,142 @@
 'use client';
 
 import * as React from 'react';
+import { useId, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
-import type { PositioningProps, PositioningReturn, PositioningImperativeRef } from './types';
-import { POSITION_AREA_MAP, ALIGNMENTS, POSITIONS } from './constants';
-import { getPlacementString } from './placement';
-import { resolveElementRef, resolveOffset } from './resolvers';
-import { ensureFallbackStyles, shorthandToFallbackName } from './fallbackStyles';
-import { applyAutoSize, applyOffsetStyles, applyPositionAreaStyles, getCoverSelfAlignment } from './styleHelpers';
-import { useAnchorName } from './useAnchorName';
-import { usePlacementSync } from './usePlacementSync';
-import { useAutoSizeBoundary } from './useAutoSizeBoundary';
-
-function useImperativeAnchor(
-  positioningRef: React.Ref<PositioningImperativeRef> | undefined,
-  anchorName: string,
-): void {
-  const imperativeTargetRef = React.useRef<HTMLElement | null>(null);
-  React.useImperativeHandle<PositioningImperativeRef, PositioningImperativeRef>(
-    positioningRef,
-    () => ({
-      setTarget: el => {
-        if (imperativeTargetRef.current && imperativeTargetRef.current !== el) {
-          imperativeTargetRef.current.style.removeProperty('anchor-name');
-        }
-        imperativeTargetRef.current = el;
-        if (el) {
-          el.style.setProperty('anchor-name', anchorName);
-        }
-      },
-      updatePosition: () => undefined,
-    }),
-    [anchorName],
-  );
-}
+import type { PositioningImperativeRef, PositioningProps, PositioningReturn } from './types';
+import { POSITIONS, ALIGNMENTS, POSITION_AREA_MAP } from './constants';
+import { getPlacementString, normalizeAlign } from './utils/placement';
+import { applyOffset, getCoverSelfAlignment, resolveElementRef, resolveOffset, shorthandToPositionArea } from './utils';
+import { usePlacementObserver } from './usePlacementObserver';
+
+const DEFAULT_FLIP = ['flip-block', 'flip-inline', 'flip-block flip-inline'];
 
-/**
- * Positions a container element relative to a target (anchor) using the
- * native CSS anchor positioning API. Returns ref callbacks for the target,
- * container, and arrow; caller wires them to the respective elements.
- */
 export function usePositioning(options: PositioningProps): PositioningReturn {
-  const position = options.position ?? POSITIONS.above;
-  const align = options.align ?? ALIGNMENTS.center;
-  const coverTarget = options.coverTarget ?? false;
-  const autoSize = options.autoSize ?? false;
-  const strategy = options.strategy ?? 'fixed';
-  const pinned = options.pinned ?? false;
   const {
-    offset,
+    pinned,
     target: customTarget = null,
+    align: alignInput = ALIGNMENTS.center,
+    position = POSITIONS.above,
+    fallbackPositions = [],
+    offset,
+    coverTarget = false,
+    strategy = 'absolute',
     matchTargetSize,
     positioningRef,
-    fallbackPositions,
-    overflowBoundary,
   } = options;
 
-  const { targetDocument } = useFluent();
+  const align = normalizeAlign(alignInput);
 
-  const [triggerElement, setTriggerElement] = React.useState<HTMLElement | null>(null);
+  const { mainAxis, crossAxis } = resolveOffset(offset);
+  const coverAlignment = coverTarget ? getCoverSelfAlignment(position, align) : null;
+
+  const [triggerEl, setTriggerEl] = React.useState<HTMLElement | null>(null);
   const [containerEl, setContainerEl] = React.useState<HTMLElement | null>(null);
-  const [targetEl, setTargetEl] = React.useState<HTMLElement | null>(null);
+  const [imperativeTarget, setImperativeTarget] = React.useState<HTMLElement | null>(null);
+  const effectiveTarget = imperativeTarget ?? resolveElementRef(customTarget) ?? triggerEl;
 
-  const effectiveTarget = resolveElementRef(customTarget) ?? triggerElement;
-  const anchorName = useAnchorName(effectiveTarget);
-  useImperativeAnchor(positioningRef, anchorName);
+  const anchorName = useId('--popover-anchor-');
+  const positionArea = POSITION_AREA_MAP[position][align];
+  const placement = getPlacementString(position, align);
 
-  React.useEffect(() => {
-    setTargetEl(effectiveTarget);
-  }, [effectiveTarget]);
+  const { targetDocument } = useFluent();
 
-  const { mainAxis, crossAxis } = resolveOffset(offset);
-  const positionArea = coverTarget ? 'center' : POSITION_AREA_MAP[position][align];
-  const coverAlignment = coverTarget ? getCoverSelfAlignment(position, align) : null;
-  const placement = getPlacementString(position, align);
+  const fallbackAreas = React.useMemo(() => fallbackPositions.map(shorthandToPositionArea), [fallbackPositions]);
+
+  React.useImperativeHandle<PositioningImperativeRef, PositioningImperativeRef>(
+    positioningRef,
+    () => ({
+      setTarget: (el: HTMLElement | null) => {
+        setImperativeTarget(el);
+      },
+      updatePosition: () => undefined,
+    }),
+    [],
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    effectiveTarget?.style.setProperty('anchor-name', anchorName);
+  }, [effectiveTarget, anchorName]);
 
   const targetRef: React.RefCallback<HTMLElement> = React.useCallback(node => {
-    setTriggerElement(node);
+    setTriggerEl(node);
   }, []);
 
   const containerRef: React.RefCallback<HTMLElement> = React.useCallback(
     node => {
       setContainerEl(node);
+
       if (!node) {
         return;
       }
 
-      const surface = node;
+      node.style.setProperty('position', strategy);
+      node.style.setProperty('inset', 'auto');
+      node.style.setProperty('margin', '0');
 
-      surface.style.setProperty('position', strategy);
-      surface.style.setProperty('position-anchor', anchorName);
-      surface.setAttribute('data-placement', placement);
+      applyOffset(node, position, mainAxis, crossAxis);
+
+      if (matchTargetSize === 'width') {
+        node.style.setProperty('width', 'anchor-size(width)');
+      } else {
+        node.style.removeProperty('width');
+      }
+
+      node.style.setProperty('position-anchor', anchorName);
+      node.setAttribute('data-placement', placement);
 
       if (coverAlignment) {
-        surface.style.setProperty('position-area', positionArea);
-        surface.style.setProperty('align-self', coverAlignment.alignSelf);
-        surface.style.setProperty('justify-self', coverAlignment.justifySelf);
+        node.style.setProperty('position-area', 'center');
+        node.style.setProperty('align-self', coverAlignment.alignSelf);
+        node.style.setProperty('justify-self', coverAlignment.justifySelf);
+        node.style.removeProperty('position-try-fallbacks');
+        return;
+      }
+
+      node.style.setProperty('position-area', positionArea);
+
+      /* 
+       * Workaround for https://crbug.com/438334710: Chromium (<=130-ish) doesn't
+         apply the implicit `anchor-center` self-alignment that the spec defines
+         for single-keyword `position-area` values (`block-start`, `block-end`,
+    `    inline-start`, `inline-end`) or `span-all`. 
+      */
+      if (align === ALIGNMENTS.center) {
+        node.style.setProperty('place-self', 'anchor-center');
       } else {
-        if (pinned) {
-          surface.style.removeProperty('position-try-fallbacks');
-        } else if (fallbackPositions && fallbackPositions.length > 0) {
-          ensureFallbackStyles(targetDocument);
-          surface.style.setProperty(
-            'position-try-fallbacks',
-            fallbackPositions.map(shorthandToFallbackName).join(', '),
-          );
-        } else {
-          surface.style.setProperty('position-try-fallbacks', 'flip-block, flip-inline');
-        }
-        applyPositionAreaStyles(surface, positionArea, position, align);
+        node.style.removeProperty('place-self');
+        node.style.removeProperty('align-self');
+        node.style.removeProperty('justify-self');
       }
 
-      if (matchTargetSize === 'width') {
-        surface.style.setProperty('width', 'anchor-size(width)');
+      if (pinned) {
+        node.style.removeProperty('position-try-fallbacks');
+        return;
       }
 
-      applyOffsetStyles(surface, position, mainAxis, crossAxis);
-      applyAutoSize(surface, autoSize, position);
+      if (fallbackAreas.length > 0) {
+        node.style.setProperty('position-try-fallbacks', fallbackAreas.join(', '));
+      } else {
+        node.style.setProperty('position-try-fallbacks', DEFAULT_FLIP.join(', '));
+      }
     },
     [
       anchorName,
       positionArea,
-      coverAlignment,
       placement,
+      fallbackAreas,
+      pinned,
       position,
       align,
       mainAxis,
       crossAxis,
-      autoSize,
+      coverAlignment,
       strategy,
       matchTargetSize,
-      pinned,
-      fallbackPositions,
-      targetDocument,
     ],
   );
 
-  const arrowRef: React.RefCallback<HTMLElement> = React.useCallback(() => {
-    // Arrow placement is consumer-owned CSS keyed off `[data-placement]`.
-  }, []);
+  usePlacementObserver(containerEl, effectiveTarget, targetDocument, coverTarget);
 
-  usePlacementSync({
-    containerEl,
-    targetEl,
-    coverTarget,
-    pinned,
-    useCssFallbacks: !!fallbackPositions && fallbackPositions.length > 0,
-    position,
-    align,
-    mainOffset: mainAxis,
-    targetDocument,
-  });
-
-  useAutoSizeBoundary({
-    autoSize,
-    overflowBoundary,
-    containerEl,
-    targetEl,
-    position,
-    align,
-    targetDocument,
-  });
-
-  return { targetRef, containerRef, arrowRef };
+  return { targetRef, containerRef };
 }
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/index.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/index.ts
new file mode 100644
index 00000000000000..78d00ae45eb4cf
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/index.ts
@@ -0,0 +1,8 @@
+export { applyOffset, resolveOffset } from './offset';
+export {
+  getCoverSelfAlignment,
+  getPlacementString,
+  resolvePositioningShorthand,
+  shorthandToPositionArea,
+} from './placement';
+export { resolveElementRef } from './resolveElementRef';
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/offset.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/offset.ts
new file mode 100644
index 00000000000000..0661a2bb91f548
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/offset.ts
@@ -0,0 +1,48 @@
+import { POSITIONS } from '../constants';
+import type { Position } from '../types';
+import type { PositioningProps } from '../types';
+
+export function applyOffset(node: HTMLElement, position: Position, mainAxis: number, crossAxis: number): void {
+  if (mainAxis) {
+    switch (position) {
+      case POSITIONS.above:
+        node.style.marginBlockEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.below:
+        node.style.marginBlockStart = `${mainAxis}px`;
+        break;
+      case POSITIONS.before:
+        node.style.marginInlineEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.after:
+        node.style.marginInlineStart = `${mainAxis}px`;
+        break;
+    }
+  }
+
+  if (crossAxis) {
+    switch (position) {
+      case POSITIONS.above:
+      case POSITIONS.below:
+        node.style.marginInlineStart = `${crossAxis}px`;
+        break;
+      case POSITIONS.before:
+      case POSITIONS.after:
+        node.style.marginBlockStart = `${crossAxis}px`;
+        break;
+    }
+  }
+}
+
+/** Normalises the `offset` prop into explicit `{ mainAxis, crossAxis }`. */
+export function resolveOffset(offset: PositioningProps['offset']): { mainAxis: number; crossAxis: number } {
+  if (typeof offset === 'number') {
+    return { mainAxis: offset, crossAxis: 0 };
+  }
+
+  if (offset) {
+    return { mainAxis: offset.mainAxis ?? 0, crossAxis: offset.crossAxis ?? 0 };
+  }
+
+  return { mainAxis: 0, crossAxis: 0 };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/placement.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/placement.ts
new file mode 100644
index 00000000000000..cd03b35337be06
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/placement.ts
@@ -0,0 +1,99 @@
+import type {
+  Position,
+  LogicalAlignment,
+  PositioningProps,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from '../types';
+import { ALIGNMENTS, POSITIONS, POSITION_AREA_MAP } from '../constants';
+
+const POSITION_ALIASES: Record<string, Position> = {
+  top: POSITIONS.above,
+  bottom: POSITIONS.below,
+  left: POSITIONS.before,
+  right: POSITIONS.after,
+};
+
+const ALIGN_ALIASES: Record<string, LogicalAlignment> = {
+  top: ALIGNMENTS.start,
+  bottom: ALIGNMENTS.end,
+};
+
+export function normalizePosition(raw: string): Position {
+  if (raw in POSITIONS) {
+    return raw as Position;
+  }
+
+  return POSITION_ALIASES[raw] ?? POSITIONS.above;
+}
+
+export function normalizeAlign(raw: string): LogicalAlignment {
+  if (raw === ALIGNMENTS.start || raw === ALIGNMENTS.center || raw === ALIGNMENTS.end) {
+    return raw;
+  }
+
+  return ALIGN_ALIASES[raw] ?? ALIGNMENTS.center;
+}
+
+/**
+ * Maps (position, align) into the human-readable placement string used for the
+ * `data-placement` attribute. Center alignment renders as the bare position.
+ */
+export function getPlacementString(position: Position, align: LogicalAlignment): string {
+  return align === ALIGNMENTS.center ? position : `${position}-${align}`;
+}
+
+/**
+ * Normalizes a shorthand (string or object) into a full `PositioningProps`.
+ * Strings like `'below-start'` become `{ position: 'below', align: 'start' }`;
+ * objects pass through unchanged.
+ *
+ */
+export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps {
+  if (!value) {
+    return {};
+  }
+
+  if (typeof value !== 'string') {
+    return {
+      ...value,
+      position: value.position !== undefined ? normalizePosition(value.position) : undefined,
+      align: value.align !== undefined ? normalizeAlign(value.align) : undefined,
+    };
+  }
+
+  const dash = value.indexOf('-');
+
+  if (dash === -1) {
+    return { position: normalizePosition(value) };
+  }
+
+  return {
+    position: normalizePosition(value.slice(0, dash)),
+    align: normalizeAlign(value.slice(dash + 1)),
+  };
+}
+
+export function shorthandToPositionArea(shorthand: PositioningShorthandValue): string {
+  const { position = POSITIONS.above, align = ALIGNMENTS.center } = resolvePositioningShorthand(shorthand);
+  return POSITION_AREA_MAP[position][normalizeAlign(align)];
+}
+
+export function getCoverSelfAlignment(
+  position: Position,
+  align: LogicalAlignment,
+): { alignSelf: string; justifySelf: string } {
+  if (position === POSITIONS.above) {
+    return { alignSelf: ALIGNMENTS.end, justifySelf: align };
+  }
+
+  if (position === POSITIONS.below) {
+    return { alignSelf: ALIGNMENTS.start, justifySelf: align };
+  }
+
+  if (position === POSITIONS.before) {
+    return { alignSelf: align, justifySelf: ALIGNMENTS.end };
+  }
+
+  return { alignSelf: align, justifySelf: ALIGNMENTS.start };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/resolveElementRef.ts
similarity index 50%
rename from packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts
rename to packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/resolveElementRef.ts
index d5cc8c388bcf9c..d002f9601823f2 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/resolvers.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/utils/resolveElementRef.ts
@@ -1,5 +1,4 @@
 import type * as React from 'react';
-import type { PositioningProps } from './types';
 
 /**
  * Normalizes an `HTMLElement | RefObject | null | undefined` to a plain
@@ -12,19 +11,5 @@ export function resolveElementRef(
   if (!source) {
     return null;
   }
-
   return 'current' in source ? source.current : source;
 }
-
-/** Normalizes the `offset` prop into explicit `{ mainAxis, crossAxis }`. */
-export function resolveOffset(offset: PositioningProps['offset']): { mainAxis: number; crossAxis: number } {
-  if (typeof offset === 'number') {
-    return { mainAxis: offset, crossAxis: 0 };
-  }
-
-  if (offset) {
-    return { mainAxis: offset.mainAxis ?? 0, crossAxis: offset.crossAxis ?? 0 };
-  }
-
-  return { mainAxis: 0, crossAxis: 0 };
-}
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
index fefc07c8e261af..d2c85776b4db98 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
@@ -1,6 +1,8 @@
 import * as React from 'react';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
 
+import descriptionMd from './PositioningAutoSizeDescription.md';
+
 const classes = {
   outer: 'w-full overflow-auto',
   wrapper: 'flex flex-col items-start gap-4 mx-16 my-16 w-max',
@@ -41,7 +43,7 @@ export const AutoSize = (): React.ReactNode => {
           <Popover
             open={open}
             onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'below', autoSize: true, overflowBoundary: boundary, strategy: 'absolute' }}
+            positioning={{ position: 'below', overflowBoundary: boundary, strategy: 'absolute' }}
           >
             <PopoverTrigger>
               <button className={classes.trigger}>AutoSized popover</button>
@@ -55,13 +57,15 @@ export const AutoSize = (): React.ReactNode => {
             </PopoverSurface>
           </Popover>
         </div>
-
-        <p className="text-xs text-gray-500 max-w-lg">
-          <code>autoSize</code> sets inline <code>max-width</code> and <code>max-height</code> styles on the surface
-          derived from <code>overflowBoundary</code> (here, the dashed 300×300 box). As the item count grows the popover
-          clips to the boundary and scrolls instead of bursting outside.
-        </p>
       </div>
     </div>
   );
 };
+
+AutoSize.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
new file mode 100644
index 00000000000000..d86f03dd4fb693
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
@@ -0,0 +1 @@
+`autoSize` sets inline `max-width` and `max-height` styles on the surface derived from `overflowBoundary`. As the content grows the surface clips to the boundary and scrolls instead of bursting outside.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
index 9019b49de37ed2..e536b3f675f342 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
@@ -1,36 +1,128 @@
 import * as React from 'react';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
 
 const classes = {
-  wrapper: 'flex flex-col items-start gap-4 m-16',
+  page: 'flex flex-col gap-6 p-4',
+  sectionTitle: 'text-sm font-semibold text-gray-800 mb-1',
+  sectionNote: 'text-xs text-gray-500 max-w-xl mb-2',
+  grid: 'grid grid-cols-1 sm:grid-cols-2 gap-4',
   trigger:
-    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 max-w-xs',
-  note: 'text-xs text-gray-500 max-w-lg',
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'flip-demo bg-white rounded-md shadow-md border border-gray-200 p-3 min-w-[200px] max-w-xs text-sm',
 };
 
 export const FallbackPositions = (): React.ReactNode => (
-  <div className={classes.wrapper}>
-    <Popover
-      positioning={{
-        position: 'above',
-        align: 'center',
-        fallbackPositions: ['below-start', 'after'],
-      }}
-    >
-      <PopoverTrigger>
-        <button className={classes.trigger}>Open near an edge</button>
-      </PopoverTrigger>
-      <PopoverSurface className={classes.surface}>
-        When <code>above</code> overflows the viewport, the browser walks <code>fallbackPositions</code> in order —
-        first <code>below-start</code>, then <code>after</code> — and picks the first placement that fits.
-      </PopoverSurface>
-    </Popover>
+  <div className={classes.page}>
+    <style>{flipDemoSurfaceCss}</style>
 
-    <p className={classes.note}>
-      <code>fallbackPositions</code> accepts shorthand strings like <code>'below-start'</code>. Each entry is compiled
-      into a <code>@position-try</code> rule so the browser can try them natively. When omitted, the default fallback is{' '}
-      <code>flip-block, flip-inline</code>.
-    </p>
+    <section>
+      <h3 className={classes.sectionTitle}>Basic fallback</h3>
+      <p className={classes.sectionNote}>
+        Primary <code>above</code> overflows the box → first fallback <code>below-start</code> fits → surface renders
+        there.
+      </p>
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover
+          inline
+          defaultOpen
+          positioning={{
+            position: 'above',
+            align: 'center',
+            fallbackPositions: ['below-start', 'after'],
+          }}
+        >
+          <PopoverTrigger>
+            <button
+              className={classes.trigger}
+              style={{ position: 'absolute', top: 12, left: '50%', transform: 'translateX(-50%)' }}
+            >
+              trigger near top
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> above · fallbacks: <code>below-start</code>, <code>after</code>
+          </PopoverSurface>
+        </Popover>
+      </div>
+    </section>
+
+    <section>
+      <h3 className={classes.sectionTitle}>Chain walking</h3>
+      <p className={classes.sectionNote}>
+        Trigger pinned to top-left. Primary <code>above</code> overflows, first fallback <code>before</code> also
+        overflows (no room to the left), so the browser falls through to <code>below</code>. The live{' '}
+        <strong>Actual</strong> readout should read <code>below</code>.
+      </p>
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover
+          inline
+          defaultOpen
+          positioning={{
+            position: 'above',
+            align: 'center',
+            fallbackPositions: ['before', 'below'],
+          }}
+        >
+          <PopoverTrigger>
+            <button className={classes.trigger} style={{ position: 'absolute', top: 12, left: 12 }}>
+              top-left trigger
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> above · fallbacks: <code>before</code>, <code>below</code>
+          </PopoverSurface>
+        </Popover>
+      </div>
+    </section>
+
+    <section>
+      <h3 className={classes.sectionTitle}>Custom chain replaces default flip</h3>
+      <p className={classes.sectionNote}>
+        Same overflow condition, different chains. Left popover has no <code>fallbackPositions</code> → default{' '}
+        <code>flip-block, flip-inline</code> fires → surface ends up below. Right popover passes <code>['after']</code>{' '}
+        → custom chain replaces defaults → surface goes to the right instead of flipping.
+      </p>
+      <div className={classes.grid}>
+        <div className={demoBoxClass} style={demoBoxStyle}>
+          <Popover inline defaultOpen positioning={{ position: 'above', align: 'center' }}>
+            <PopoverTrigger>
+              <button
+                className={classes.trigger}
+                style={{ position: 'absolute', top: 12, left: '50%', transform: 'translateX(-50%)' }}
+              >
+                default (flip)
+              </button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              <strong>Requested:</strong> above · no custom fallbacks
+            </PopoverSurface>
+          </Popover>
+        </div>
+        <div className={demoBoxClass} style={demoBoxStyle}>
+          <Popover
+            inline
+            defaultOpen
+            positioning={{
+              position: 'above',
+              align: 'center',
+              fallbackPositions: ['after', 'below'],
+            }}
+          >
+            <PopoverTrigger>
+              <button
+                className={classes.trigger}
+                style={{ position: 'absolute', top: 12, left: '50%', transform: 'translateX(-50%)' }}
+              >
+                custom ({`['after']`})
+              </button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              <strong>Requested:</strong> above · fallbacks: <code>after</code>, <code>below</code>
+            </PopoverSurface>
+          </Popover>
+        </div>
+      </div>
+    </section>
   </div>
 );
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositionsDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositionsDescription.md
new file mode 100644
index 00000000000000..3b98950f7436a1
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositionsDescription.md
@@ -0,0 +1,5 @@
+`fallbackPositions` supplies a custom fallback chain for `position-try-fallbacks` — the browser tries each placement in order when the primary placement would overflow. Each entry is a shorthand string (e.g. `'below-start'`, `'after'`) that maps to an inline `<position-area>` value in the final CSS.
+
+When `fallbackPositions` is omitted, the default chain is the native `flip-block, flip-inline` tactics. When it's supplied, the custom chain **replaces** the default — it does not compose with flip tactics. The browser walks the list in order and picks the first entry that fits.
+
+The three sub-demos below cover: (1) the basic chain + single fallback picked up, (2) chain walking when the first fallback also overflows, and (3) how a custom chain opts out of the default flip tactics entirely.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
new file mode 100644
index 00000000000000..d5a8c9d1baf80c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
+
+import descriptionMd from './PositioningFlippingBlockDescription.md';
+
+const classes = {
+  page: 'flex flex-col gap-4 p-4',
+  grid: 'grid grid-cols-1 sm:grid-cols-2 gap-4',
+  trigger:
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'flip-demo bg-white rounded-md shadow-md border border-gray-200 p-2 w-[160px] text-xs',
+};
+
+export const FlippingBlock = (): React.ReactNode => (
+  <div className={classes.page}>
+    <style>{flipDemoSurfaceCss}</style>
+
+    <div className={classes.grid}>
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'above' }}>
+          <PopoverTrigger>
+            <button
+              className={classes.trigger}
+              style={{ position: 'absolute', top: 12, left: '50%', transform: 'translateX(-50%)' }}
+            >
+              trigger near top
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> above → flips below
+          </PopoverSurface>
+        </Popover>
+      </div>
+
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'below' }}>
+          <PopoverTrigger>
+            <button
+              className={classes.trigger}
+              style={{ position: 'absolute', bottom: 12, left: '50%', transform: 'translateX(-50%)' }}
+            >
+              trigger near bottom
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> below → flips above
+          </PopoverSurface>
+        </Popover>
+      </div>
+    </div>
+  </div>
+);
+
+FlippingBlock.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlockDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlockDescription.md
new file mode 100644
index 00000000000000..1d220afd4b0ce0
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlockDescription.md
@@ -0,0 +1,3 @@
+`flip-block` — the browser swaps the block axis (`above` ↔ `below`) when the requested side would overflow. Each demo lives in a dashed, `contain: layout` box so the overflow check happens relative to the box.
+
+Both triggers overflow their requested side → native `position-try-fallbacks: flip-block` swaps the block axis. Compare the **Requested** label with the live **Actual** readout rendered from `[data-placement]`.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
new file mode 100644
index 00000000000000..21c3063daee75f
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
@@ -0,0 +1,81 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
+
+import descriptionMd from './PositioningFlippingCornerDescription.md';
+
+const classes = {
+  page: 'flex flex-col gap-4 p-4',
+  grid: 'grid grid-cols-1 sm:grid-cols-2 gap-4',
+  trigger:
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-xs font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'bg-white rounded-md shadow-md border border-gray-200 p-3 w-[320px] max-h-[140px] text-sm',
+};
+
+export const FlippingCorner = (): React.ReactNode => (
+  <div className={classes.page}>
+    <style>{flipDemoSurfaceCss}</style>
+
+    <div className={classes.grid}>
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'above', align: 'end' }}>
+          <PopoverTrigger>
+            <button className={classes.trigger} style={{ position: 'absolute', top: 12, left: 12 }}>
+              top-left · requested above-end
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> above-end → below-start
+          </PopoverSurface>
+        </Popover>
+      </div>
+
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'above', align: 'start' }}>
+          <PopoverTrigger>
+            <button className={classes.trigger} style={{ position: 'absolute', top: 12, right: 12 }}>
+              top-right · requested above-start
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> above-start → below-end
+          </PopoverSurface>
+        </Popover>
+      </div>
+
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'below', align: 'end' }}>
+          <PopoverTrigger>
+            <button className={classes.trigger} style={{ position: 'absolute', bottom: 12, left: 12 }}>
+              bottom-left · requested below-end
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> below-end → above-start
+          </PopoverSurface>
+        </Popover>
+      </div>
+
+      <div className={demoBoxClass} style={demoBoxStyle}>
+        <Popover inline open positioning={{ position: 'below', align: 'start' }}>
+          <PopoverTrigger>
+            <button className={classes.trigger} style={{ position: 'absolute', bottom: 12, right: 12 }}>
+              bottom-right · requested below-start
+            </button>
+          </PopoverTrigger>
+          <PopoverSurface className={classes.surface}>
+            <strong>Requested:</strong> below-start → above-end
+          </PopoverSurface>
+        </Popover>
+      </div>
+    </div>
+  </div>
+);
+
+FlippingCorner.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCornerDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCornerDescription.md
new file mode 100644
index 00000000000000..e8bbbf7f6dc7ec
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCornerDescription.md
@@ -0,0 +1,3 @@
+Combined flip — when the requested placement overflows on both axes, `flip-block` and `flip-inline` fire together and yield the diagonally opposite placement (e.g. a top-left trigger requesting `above-end` → actual `below-start`).
+
+Each trigger sits in a corner of its dashed box and requests a placement that overflows on both axes. Native `flip-block` + `flip-inline` together resolve to the diagonally opposite placement.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
new file mode 100644
index 00000000000000..67983522ede239
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
+
+import descriptionMd from './PositioningFlippingInlineDescription.md';
+
+const classes = {
+  page: 'flex flex-col gap-6 p-4',
+  sectionLabel: 'text-xs font-semibold uppercase tracking-wide text-gray-500',
+  grid: 'grid grid-cols-1 sm:grid-cols-2 gap-4',
+  trigger:
+    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  surface: 'flip-demo bg-white rounded-md shadow-md border border-gray-200 p-3 min-w-[200px] max-w-xs text-sm',
+};
+
+export const FlippingInline = (): React.ReactNode => (
+  <div className={classes.page}>
+    <style>{flipDemoSurfaceCss}</style>
+
+    <section className="flex flex-col gap-2">
+      <div className={classes.sectionLabel}>Headless (native position-try-fallbacks)</div>
+      <div className={classes.grid}>
+        <div className={demoBoxClass} style={demoBoxStyle}>
+          <Popover open positioning={{ position: 'before' }}>
+            <PopoverTrigger>
+              <button
+                className={classes.trigger}
+                style={{ position: 'absolute', left: 12, top: '50%', transform: 'translateY(-50%)' }}
+              >
+                trigger on left
+              </button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              <strong>Requested:</strong> before → flips after
+            </PopoverSurface>
+          </Popover>
+        </div>
+
+        <div className={demoBoxClass} style={demoBoxStyle}>
+          <Popover open positioning={{ position: 'after' }}>
+            <PopoverTrigger>
+              <button
+                className={classes.trigger}
+                style={{ position: 'absolute', right: 12, top: '50%', transform: 'translateY(-50%)' }}
+              >
+                trigger on right
+              </button>
+            </PopoverTrigger>
+            <PopoverSurface className={classes.surface}>
+              <strong>Requested:</strong> after → flips before
+            </PopoverSurface>
+          </Popover>
+        </div>
+      </div>
+    </section>
+  </div>
+);
+
+FlippingInline.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInlineDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInlineDescription.md
new file mode 100644
index 00000000000000..ea0940ff8db079
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInlineDescription.md
@@ -0,0 +1,3 @@
+`flip-inline` — the browser swaps the inline axis (`before` ↔ `after`) when the requested side would overflow. Same dashed, `contain: layout` box pattern as the block-flip demo.
+
+Native `position-try-fallbacks: flip-inline` swaps the inline axis: `before` ↔ `after`. Compare each popover's **Requested** label with the live **Actual** readout rendered from `[data-placement]`.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
index 30a5f325bfa1d5..a6c2731b7e6437 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
@@ -1,12 +1,13 @@
 import * as React from 'react';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
 
+import descriptionMd from './PositioningMatchTargetSizeDescription.md';
+
 const classes = {
   wrapper: 'flex flex-col items-start gap-4 m-16',
   trigger:
     'w-[350px] px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
   surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 box-border',
-  note: 'text-xs text-gray-500 max-w-lg',
 };
 
 export const MatchTargetSize = (): React.ReactNode => (
@@ -17,11 +18,13 @@ export const MatchTargetSize = (): React.ReactNode => (
       </PopoverTrigger>
       <PopoverSurface className={classes.surface}>This popover has the same width as its target anchor</PopoverSurface>
     </Popover>
-
-    <p className={classes.note}>
-      <code>matchTargetSize: 'width'</code> applies <code>width: anchor-size(width)</code> to the surface so its inline
-      size tracks the trigger's. Handy for combobox / autocomplete dropdowns that should line up with the input. Ensure
-      the surface uses <code>box-sizing: border-box</code> so padding doesn't exceed the matched width.
-    </p>
   </div>
 );
+
+MatchTargetSize.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSizeDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSizeDescription.md
new file mode 100644
index 00000000000000..0e1c277719865c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSizeDescription.md
@@ -0,0 +1 @@
+`matchTargetSize: 'width'` applies `width: anchor-size(width)` to the surface so its inline size tracks the trigger's. Handy for combobox / autocomplete dropdowns that should line up with the input. Ensure the surface uses `box-sizing: border-box` so padding doesn't exceed the matched width.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
index 8587e08982e1ce..be171e7aa0f082 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
@@ -1,6 +1,8 @@
 import * as React from 'react';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
 
+import overflowBoundaryDescriptionMd from './PositioningOverflowBoundaryDescription.md';
+
 const classes = {
   outer: 'w-full overflow-auto min-h-[400px]',
   wrapper: 'flex flex-col items-start gap-4 m-16',
@@ -9,9 +11,8 @@ const classes = {
     'relative border-2 border-dashed border-red-500 w-[300px] h-[300px] p-5 flex flex-col justify-between items-end box-border',
   trigger:
     'w-[150px] px-3 py-2 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  boundedSurface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm overflow-auto',
-  freeSurface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm w-64 overflow-auto',
-  note: 'text-xs text-gray-500 max-w-lg',
+  surfaceBase: 'box-border bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm',
+  surfaceWider: 'w-[340px]',
 };
 
 export const OverflowBoundary = (): React.ReactNode => {
@@ -30,42 +31,41 @@ export const OverflowBoundary = (): React.ReactNode => {
           <Popover
             open={open}
             onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'below', align: 'start', autoSize: 'width', overflowBoundary: boundary }}
+            positioning={{ position: 'below', align: 'start', overflowBoundary: boundary }}
           >
             <PopoverTrigger>
-              <button className={classes.trigger}>Bounded</button>
+              <button className={classes.trigger}>Below</button>
             </PopoverTrigger>
-            <PopoverSurface className={classes.boundedSurface}>
-              Stays within the overflow boundary — <code>autoSize</code> + <code>overflowBoundary</code> clamps
-              max-width to the space between the trigger's left edge and the dashed box's right edge, so this popover
-              wraps to fit.
+            <PopoverSurface className={classes.surfaceBase}>
+              Natural width is 240px. With <code>overflowBoundary</code> set, the hook caps <code>max-inline-size</code>{' '}
+              to the room between the trigger&rsquo;s left edge and the boundary&rsquo;s right edge, so the
+              surface&rsquo;s right edge lands exactly at the boundary.
             </PopoverSurface>
           </Popover>
 
           <Popover
             open={open}
             onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'below', align: 'start' }}
+            positioning={{ position: 'above', align: 'start' }}
           >
             <PopoverTrigger>
               <button className={classes.trigger}>Free</button>
             </PopoverTrigger>
-            <PopoverSurface className={classes.freeSurface}>
-              Overflows the overflow boundary — no <code>overflowBoundary</code> is set and the surface carries an
-              explicit <code>w-64</code>, so it keeps its natural 256px width and extends past the dashed box.
+            <PopoverSurface className={`${classes.surfaceBase}, ${classes.surfaceWider}`}>
+              No <code>overflowBoundary</code> — the surface keeps its natural 340px width and spills past the dashed
+              rect. Native CSS flip only checks the viewport, not this custom boundary.
             </PopoverSurface>
           </Popover>
         </div>
-
-        <p className={classes.note}>
-          <code>overflowBoundary</code> tells the positioning hook which element to treat as the clip area for
-          <code> autoSize</code>. The bounded popover's <code>max-width</code> (and <code>max-height</code> when
-          <code> autoSize: true</code>) is derived from that element's rect and kept in sync via a{' '}
-          <code>ResizeObserver</code>. Without <code>overflowBoundary</code>, <code>autoSize</code> falls back to the
-          viewport — and when <code>autoSize</code> is off entirely, the surface sizes freely and can extend past the
-          boundary.
-        </p>
       </div>
     </div>
   );
 };
+
+OverflowBoundary.parameters = {
+  docs: {
+    description: {
+      story: overflowBoundaryDescriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
new file mode 100644
index 00000000000000..e69b51341f943c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
@@ -0,0 +1 @@
+`overflowBoundary` names a rect the positioned surface must stay within. When set, the hook writes logical `max-inline-size` and `max-block-size` on the surface so its far edge can never extend past the boundary — the surface's start edge stays anchored where CSS anchor positioning placed it, and content reflows inside the clamped box. Pair with `overflowBoundaryPadding` to reserve breathing room between the surface and the boundary edges.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/demoBox.ts b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/demoBox.ts
new file mode 100644
index 00000000000000..dbb331b9ae84a8
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/demoBox.ts
@@ -0,0 +1,21 @@
+import type * as React from 'react';
+
+export const demoBoxClass =
+  'relative w-full max-w-xl min-h-[260px] border border-dashed border-gray-300 rounded-lg bg-gray-50 p-4';
+
+export const demoBoxStyle: React.CSSProperties = {
+  contain: 'layout',
+};
+
+export const flipDemoSurfaceCss = `
+.flip-demo::after {
+  content: 'Actual: ' attr(data-placement);
+  display: block;
+  margin-top: 0.5rem;
+  padding-top: 0.5rem;
+  border-top: 1px dashed #d1d5db;
+  font-family: monospace;
+  font-size: 0.75rem;
+  color: #6b7280;
+}
+`;
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
index 0db9d0a970722e..ebeff1b4a0736b 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
@@ -11,9 +11,12 @@ export { AutoSize } from './PositioningAutoSize.stories';
 export { OverflowBoundary } from './PositioningOverflowBoundary.stories';
 export { MatchTargetSize } from './PositioningMatchTargetSize.stories';
 export { FallbackPositions } from './PositioningFallbackPositions.stories';
+export { FlippingBlock } from './PositioningFlippingBlock.stories';
+export { FlippingInline } from './PositioningFlippingInline.stories';
+export { FlippingCorner } from './PositioningFlippingCorner.stories';
 
 export default {
-  title: 'Headless Concepts/Developer/Positioning',
+  title: 'Headless Concepts/Positioning',
   component: Positioning,
   parameters: {
     docs: {
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
index db2fa5cb34ca6b..04117cf9ea10d7 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
@@ -5,66 +5,53 @@ const classes = {
   wrapper: 'flex flex-col items-start gap-4 p-16',
   trigger:
     'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  surface: 'popover-with-arrow bg-white rounded-lg p-4 min-w-[240px] max-w-xs',
+  surface: [
+    // Base surface look
+    'bg-white rounded-lg p-4 min-w-[240px] max-w-xs overflow-visible',
+    '[filter:drop-shadow(0_0_1px_rgba(0,0,0,0.12))_drop-shadow(0_4px_8px_rgba(0,0,0,0.14))]',
+    // Arrow base (the rotated square rendered by withArrow)
+    '[&_[data-arrow]]:absolute [&_[data-arrow]]:w-3 [&_[data-arrow]]:h-3 [&_[data-arrow]]:bg-white [&_[data-arrow]]:rotate-45',
+    // Main-axis offset — arrow protrudes from the side that faces the trigger
+    "[&[data-placement^='above']_[data-arrow]]:-bottom-1.5",
+    "[&[data-placement^='below']_[data-arrow]]:-top-1.5",
+    "[&[data-placement^='before']_[data-arrow]]:-right-1.5",
+    "[&[data-placement^='after']_[data-arrow]]:-left-1.5",
+    // Cross-axis centering for the plain (center-aligned) placements
+    "[&[data-placement='above']_[data-arrow]]:inset-x-0 [&[data-placement='above']_[data-arrow]]:mx-auto",
+    "[&[data-placement='below']_[data-arrow]]:inset-x-0 [&[data-placement='below']_[data-arrow]]:mx-auto",
+    "[&[data-placement='before']_[data-arrow]]:inset-y-0 [&[data-placement='before']_[data-arrow]]:my-auto",
+    "[&[data-placement='after']_[data-arrow]]:inset-y-0 [&[data-placement='after']_[data-arrow]]:my-auto",
+    // Start/end-aligned placements — arrow pinned via logical inset, padding from --arrow-padding
+    "[&[data-placement$='-start']_[data-arrow]]:start-[var(--arrow-padding,12px)]",
+    "[&[data-placement$='-end']_[data-arrow]]:end-[var(--arrow-padding,12px)]",
+  ].join(' '),
 };
 
-// The headless Popover renders an unstyled <div data-arrow /> inside the
-// PopoverSurface when `withArrow` is set. Stories own the arrow styling —
-// here the arrow is a 12px rotated square sharing the surface's
-// background, and the surface uses `filter: drop-shadow(...)` (not
-// `box-shadow`) so the shadow follows the combined silhouette of surface
-// + arrow without casting any shadow into the popover's interior.
-// Orientation is driven by data-placement, which usePositioning keeps in
-// sync with the on-screen placement (including manual flip on overflow).
-const arrowCss = `
-.popover-with-arrow {
-  overflow: visible;
-  background: white;
-  filter: drop-shadow(0 0 1px rgba(0, 0, 0, 0.12)) drop-shadow(0 4px 8px rgba(0, 0, 0, 0.14));
-}
-.popover-with-arrow [data-arrow] {
-  position: absolute;
-  width: 12px;
-  height: 12px;
-  background: white;
-  transform: rotate(45deg);
-}
-.popover-with-arrow[data-placement^='above'] [data-arrow] {
-  bottom: -6px;
-  inset-inline: 0;
-  margin-inline: auto;
-}
-.popover-with-arrow[data-placement^='below'] [data-arrow] {
-  top: -6px;
-  inset-inline: 0;
-  margin-inline: auto;
-}
-.popover-with-arrow[data-placement^='before'] [data-arrow] {
-  right: -6px;
-  inset-block: 0;
-  margin-block: auto;
-}
-.popover-with-arrow[data-placement^='after'] [data-arrow] {
-  left: -6px;
-  inset-block: 0;
-  margin-block: auto;
-}
-`;
-
 export const WithArrow = (): React.ReactNode => (
   <div className={classes.wrapper}>
-    <style>{arrowCss}</style>
     <Popover withArrow positioning={{ position: 'below', offset: 10 }}>
       <PopoverTrigger>
-        <button className={classes.trigger}>With arrow</button>
+        <button className={classes.trigger}>Center-aligned</button>
       </PopoverTrigger>
       <PopoverSurface className={classes.surface}>
         <h3 className="text-sm font-semibold text-gray-900 mb-1">Arrow popover</h3>
         <p className="text-sm text-gray-600">
-          The headless <code>Popover</code> renders an unstyled <code>{`<div data-arrow />`}</code> when{' '}
-          <code>withArrow</code> is set. This story styles the div as a CSS border-triangle and positions it at the
-          surface edge that faces the trigger, using the <code>data-placement</code> attribute that{' '}
-          <code>usePositioning</code> writes.
+          Arrow orientation follows the <code>data-placement</code> attribute, which <code>usePositioning</code> keeps
+          in sync with the actual placement as you scroll or resize.
+        </p>
+      </PopoverSurface>
+    </Popover>
+
+    <Popover withArrow positioning={{ position: 'below', align: 'start', offset: 10 }}>
+      <PopoverTrigger>
+        <button className={classes.trigger}>Start-aligned (--arrow-padding: 16px)</button>
+      </PopoverTrigger>
+      <PopoverSurface className={classes.surface} style={{ '--arrow-padding': '16px' } as React.CSSProperties}>
+        <h3 className="text-sm font-semibold text-gray-900 mb-1">Arrow padded from corner</h3>
+        <p className="text-sm text-gray-600">
+          Arrow positioning is fully CSS-owned. For start/end alignments, the Tailwind variant reads{' '}
+          <code>var(--arrow-padding, 12px)</code>; this surface overrides the fallback by setting{' '}
+          <code>--arrow-padding: 16px</code> in its inline <code>style</code>.
         </p>
       </PopoverSurface>
     </Popover>
diff --git a/packages/react-components/react-headless-components-preview/stories/src/index.ts b/packages/react-components/react-headless-components-preview/stories/src/index.ts
index de03c5324958d3..cb0ff5c3b541f6 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/index.ts
+++ b/packages/react-components/react-headless-components-preview/stories/src/index.ts
@@ -1 +1 @@
-export {} from './Popover/index.stories';
+export {};

From a57bdf6014aeb60ab4661ed624b15fb317576ad5 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Wed, 22 Apr 2026 14:08:32 +0200
Subject: [PATCH 05/17] docs(headless): add Popover spec

---
 .../library/docs/popover-spec.md              | 27 ++++++--------
 .../src/Popover/PopoverNested.stories.tsx     | 37 -------------------
 2 files changed, 12 insertions(+), 52 deletions(-)

diff --git a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
index 0a2ae066b8306f..efbdc131ff18bd 100644
--- a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
+++ b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
@@ -161,21 +161,18 @@ Placement is handled entirely by the `usePositioning` hook, which writes native
 
 ### Options (all optional)
 
-| Option                    | Type                                                  | Default      | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `position`                | `'above' \| 'below' \| 'before' \| 'after'`           | `'above'`    | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized.                                                                                                                                                                                                                                                                                                                                              |
-| `align`                   | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'`   | `'center'`   | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases).                                                                                                                                                                                                                                                                                                                                                                                   |
-| `offset`                  | `number \| { mainAxis?: number; crossAxis?: number }` | `0`          | Logical-margin offset from the anchor.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `fallbackPositions`       | `PositioningShorthandValue[]`                         | `[]`         | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`.                                                                                                                                                                                                                                                                                                                                         |
-| `coverTarget`             | `boolean`                                             | `false`      | Overlap the anchor instead of sitting beside it.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `pinned`                  | `boolean`                                             | `false`      | Disable fallback flipping; surface stays at the requested placement even if it overflows.                                                                                                                                                                                                                                                                                                                                                               |
-| `matchTargetSize`         | `'width'`                                             | —            | Sets the surface's `width` to `anchor-size(width)`.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `strategy`                | `'fixed' \| 'absolute'`                               | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes.                                                                                                                                                                                                                                                                    |
-| `target`                  | `HTMLElement \| RefObject`                            | —            | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger.                                                                                                                                                                                                                                                                                                                                                       |
-| `positioningRef`          | `Ref<PositioningImperativeRef>`                       | —            | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates.                                                                                                                                                                                                                                                                                                                                       |
-| `autoSize`                | `boolean \| 'width' \| 'height'`                      | `false`      | Cap the surface dimensions against `overflowBoundary`. Requires `overflowBoundary` — pure-CSS autoSize isn't possible due to spec-level restrictions on `anchor()` in `max-*`.                                                                                                                                                                                                                                                                          |
-| `overflowBoundary`        | `HTMLElement \| RefObject`                            | —            | Element the surface must stay inside. Drives a JS-measured `transform: translate3d()` **cross-axis shift** whenever the primary placement would exceed the boundary. Accepts a DOM element or a React ref to one. When paired with `autoSize`, the same rect is used to compute `max-*` caps. `overflowBoundaryPadding` adds breathing room on top of the shift.                                                                                        |
-| `overflowBoundaryPadding` | `number \| { top, end, bottom, start }`               | —            | Breathing room kept between the surface and the `overflowBoundary` rect. Implemented as a JS-measured `transform: translate3d()` **cross-axis shift** on the surface (only — main-axis overflow is native flip's job, matching v9 / Floating UI's `shift()` middleware). Does not affect the surface's size. Accepts a uniform number or a logical-side object (RTL-aware). Has no effect when `overflowBoundary` is unset or when `coverTarget` is on. |
+| Option              | Type                                                  | Default      | Effect                                                                                                                                                                               |
+| ------------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `position`          | `'above' \| 'below' \| 'before' \| 'after'`           | `'above'`    | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized.                                                                           |
+| `align`             | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'`   | `'center'`   | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases).                                                                                                                |
+| `offset`            | `number \| { mainAxis?: number; crossAxis?: number }` | `0`          | Logical-margin offset from the anchor.                                                                                                                                               |
+| `fallbackPositions` | `PositioningShorthandValue[]`                         | `[]`         | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`.                                                                      |
+| `coverTarget`       | `boolean`                                             | `false`      | Overlap the anchor instead of sitting beside it.                                                                                                                                     |
+| `pinned`            | `boolean`                                             | `false`      | Disable fallback flipping; surface stays at the requested placement even if it overflows.                                                                                            |
+| `matchTargetSize`   | `'width'`                                             | —            | Sets the surface's `width` to `anchor-size(width)`.                                                                                                                                  |
+| `strategy`          | `'fixed' \| 'absolute'`                               | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes. |
+| `target`            | `HTMLElement \| RefObject`                            | —            | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger.                                                                                    |
+| `positioningRef`    | `Ref<PositioningImperativeRef>`                       | —            | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates.                                                                    |
 
 ### Rendering
 
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index f60f18f7b85085..0c71cd139f3fd2 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -1,39 +1,4 @@
 import * as React from 'react';
-<<<<<<< HEAD
-import type { JSXElement } from '@fluentui/react-components';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-
-const classes = {
-  rootTrigger:
-    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  nestedTrigger:
-    'px-3 py-1.5 rounded-md bg-indigo-600 text-white text-sm font-medium hover:bg-indigo-700 data-[open]:bg-indigo-700 focus-visible:outline-2 focus-visible:outline-indigo-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  deepTrigger:
-    'px-3 py-1.5 rounded-md bg-purple-600 text-white text-sm font-medium hover:bg-purple-700 data-[open]:bg-purple-700 focus-visible:outline-2 focus-visible:outline-purple-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  actionButton:
-    'px-3 py-1.5 rounded-md bg-gray-200 text-gray-900 text-sm font-medium hover:bg-gray-300 cursor-pointer border-none',
-  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-3',
-  heading: 'text-sm font-semibold text-gray-900 m-0',
-  body: 'text-sm text-gray-600',
-  row: 'flex flex-wrap items-center gap-2',
-};
-
-const SecondNestedPopover = (): JSXElement => (
-  <Popover trapFocus>
-    <PopoverTrigger>
-      <button className={classes.deepTrigger}>Second nested trigger</button>
-    </PopoverTrigger>
-    <PopoverSurface className={classes.surface}>
-      <h3 className={classes.heading}>Popover content</h3>
-      <div className={classes.body}>This is some popover content.</div>
-      <button className={classes.actionButton}>Second nested button</button>
-    </PopoverSurface>
-  </Popover>
-);
-
-const FirstNestedPopover = (): JSXElement => (
-||||||| parent of 2135364493 (docs(react-headless-components-preview): add Popover Storybook stories)
-=======
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
 
 const classes = {
@@ -65,7 +30,6 @@ const SecondNestedPopover = (): React.ReactNode => (
 );
 
 const FirstNestedPopover = (): React.ReactNode => (
->>>>>>> 2135364493 (docs(react-headless-components-preview): add Popover Storybook stories)
   <Popover trapFocus>
     <PopoverTrigger>
       <button className={classes.nestedTrigger}>First nested trigger</button>
@@ -76,7 +40,6 @@ const FirstNestedPopover = (): React.ReactNode => (
       <button className={classes.actionButton}>First nested button</button>
       <div className={classes.row}>
         <SecondNestedPopover />
-        <SecondNestedPopover />
       </div>
     </PopoverSurface>
   </Popover>

From 583dd255cf015e1a0d8d2ead249e41e5b88c91a5 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Wed, 22 Apr 2026 15:03:00 +0200
Subject: [PATCH 06/17] chore(react-dialog): remove accidentally committed
 duplicate file

---
 .../Dialog/useDialogContextValues copy.ts     | 38 -------------------
 .../src/Popover/PopoverNested.stories.tsx     |  5 ++-
 2 files changed, 3 insertions(+), 40 deletions(-)
 delete mode 100644 packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts

diff --git a/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts b/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts
deleted file mode 100644
index a56ed7233ebbc7..00000000000000
--- a/packages/react-components/react-dialog/library/src/components/Dialog/useDialogContextValues copy.ts	
+++ /dev/null
@@ -1,38 +0,0 @@
-import type { DialogContextValue, DialogSurfaceContextValue } from '../../contexts';
-import type { DialogContextValues, DialogState } from './Dialog.types';
-
-export function useDialogContextValues_unstable(state: DialogState): DialogContextValues {
-  const {
-    modalType,
-    open,
-    dialogRef,
-    dialogTitleId,
-    isNestedDialog,
-    inertTrapFocus,
-    requestOpenChange,
-    modalAttributes,
-    triggerAttributes,
-    unmountOnClose,
-  } = state;
-
-  /**
-   * This context is created with "@fluentui/react-context-selector",
-   * there is no sense to memoize it
-   */
-  const dialog: DialogContextValue = {
-    open,
-    modalType,
-    dialogRef,
-    dialogTitleId,
-    isNestedDialog,
-    inertTrapFocus,
-    modalAttributes,
-    triggerAttributes,
-    unmountOnClose,
-    requestOpenChange,
-  };
-
-  const dialogSurface: DialogSurfaceContextValue = false;
-
-  return { dialog, dialogSurface };
-}
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index 0c71cd139f3fd2..2a6cd345d7ab94 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import type { JSXElement } from '@fluentui/react-components';
 
 const classes = {
   rootTrigger:
@@ -16,7 +17,7 @@ const classes = {
   row: 'flex flex-wrap items-center gap-2',
 };
 
-const SecondNestedPopover = (): React.ReactNode => (
+const SecondNestedPopover = (): JSXElement => (
   <Popover trapFocus>
     <PopoverTrigger>
       <button className={classes.deepTrigger}>Second nested trigger</button>
@@ -29,7 +30,7 @@ const SecondNestedPopover = (): React.ReactNode => (
   </Popover>
 );
 
-const FirstNestedPopover = (): React.ReactNode => (
+const FirstNestedPopover = (): JSXElement => (
   <Popover trapFocus>
     <PopoverTrigger>
       <button className={classes.nestedTrigger}>First nested trigger</button>

From b62dcc6b1a4ccb6ac8ace4a8cb708fca59a3f23d Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 12:45:15 +0200
Subject: [PATCH 07/17] refactor(react-headless-components-preview): remove
 custom trapFocus and unsupported positioning props

---
 .../library/docs/popover-spec.md              |    2 +-
 .../react-headless-components-preview.api.md  | 2328 +++++++++++++++++
 .../src/components/Popover/Popover.cy.tsx     |   97 +-
 .../src/components/Popover/Popover.test.tsx   |   16 +-
 .../src/components/Popover/Popover.types.ts   |    9 +-
 .../PopoverSurface/PopoverSurface.test.tsx    |   26 -
 .../PopoverSurface/usePopoverSurface.ts       |   37 +-
 .../PopoverTrigger/PopoverTrigger.test.tsx    |   13 -
 .../PopoverTrigger/usePopoverTrigger.ts       |    3 +-
 .../src/components/Popover/hooks/index.ts     |   11 +
 .../Popover/hooks/usePositioning/constants.ts |   39 +
 .../Popover/hooks/usePositioning/index.ts     |   12 +
 .../Popover/hooks/usePositioning/types.ts     |   88 +
 .../usePositioning/usePlacementObserver.ts    |  110 +
 .../usePositioning/usePositioning.test.tsx    |  159 ++
 .../hooks/usePositioning/usePositioning.ts    |  142 +
 .../hooks/usePositioning/utils/index.ts       |    8 +
 .../hooks/usePositioning/utils/offset.ts      |   48 +
 .../hooks/usePositioning/utils/placement.ts   |   99 +
 .../usePositioning/utils/resolveElementRef.ts |   15 +
 .../src/components/Popover/popoverContext.ts  |    1 -
 .../src/components/Popover/usePopover.ts      |    4 -
 .../library/src/hooks/index.ts                |    2 -
 .../library/src/hooks/useFocusScope.ts        |  428 ---
 .../hooks/usePositioning/usePositioning.ts    |    4 +-
 .../library/src/index.ts                      |  453 ++++
 .../library/src/positioning.ts                |    0
 .../PositioningAutoSize.stories.tsx           |   71 -
 .../PositioningAutoSizeDescription.md         |    1 -
 .../PositioningOverflowBoundary.stories.tsx   |   71 -
 .../PositioningOverflowBoundaryDescription.md |    1 -
 .../Concepts/Positioning/index.stories.tsx    |    2 -
 .../src/Popover/PopoverBestPractices.md       |    1 -
 .../src/Popover/PopoverNested.stories.tsx     |    6 +-
 .../src/Popover/PopoverTrapFocus.stories.tsx  |   33 -
 .../Popover/PopoverWithoutTrigger.stories.tsx |    7 +-
 .../stories/src/Popover/index.stories.tsx     |    1 -
 37 files changed, 3536 insertions(+), 812 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/positioning.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
 delete mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
 delete mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
 delete mode 100644 packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
 delete mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx

diff --git a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
index efbdc131ff18bd..e78f77203602f6 100644
--- a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
+++ b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
@@ -252,7 +252,7 @@ The package relies on three native browser APIs:
 
 - **CSS Anchor Positioning** (Chromium 125+) — `anchor-name`, `position-anchor`, `position-area`, `anchor-size()`, `position-try-fallbacks`.
 - **HTML Popover API** (Chromium 114+) — `popover="manual"` + `showPopover()` for top-layer elevation. Feature-detected (`typeof el.showPopover === 'function'`); SSR-safe; `inline={true}` opts out entirely.
-- **ResizeObserver** — used sparingly by `usePlacementObserver` (for live `data-placement`) and `useAutoSizeBoundary` (for boundary-aware `max-*`).
+- **ResizeObserver** — used sparingly by `usePlacementObserver` (for live `data-placement`)
 
 Firefox and Safari are implementing CSS Anchor Positioning; most features work but flip behaviour is still WIP. `inline={true}` works in every engine.
 
diff --git a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
index 6bef1c6e594fed..b6d45ed6ba60a6 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
@@ -4,6 +4,2334 @@
 
 ```ts
 
+<<<<<<< HEAD
+||||||| parent of 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
+import type { AccordionBaseProps } from '@fluentui/react-accordion';
+import { AccordionBaseState } from '@fluentui/react-accordion';
+import { AccordionContextValue } from '@fluentui/react-accordion';
+import { AccordionContextValues as AccordionContextValues_2 } from '@fluentui/react-accordion';
+import type { AccordionHeaderBaseProps } from '@fluentui/react-accordion';
+import { AccordionHeaderBaseState } from '@fluentui/react-accordion';
+import { AccordionHeaderContextValues } from '@fluentui/react-accordion';
+import type { AccordionHeaderSlots as AccordionHeaderSlots_2 } from '@fluentui/react-accordion';
+import { AccordionItemContextValues } from '@fluentui/react-accordion';
+import type { AccordionItemProps as AccordionItemProps_2 } from '@fluentui/react-accordion';
+import type { AccordionItemSlots as AccordionItemSlots_2 } from '@fluentui/react-accordion';
+import { AccordionItemState as AccordionItemState_2 } from '@fluentui/react-accordion';
+import type { AccordionPanelBaseProps } from '@fluentui/react-accordion';
+import type { AccordionPanelBaseState } from '@fluentui/react-accordion';
+import type { AccordionPanelSlots as AccordionPanelSlots_2 } from '@fluentui/react-accordion';
+import type { AccordionSlots as AccordionSlots_2 } from '@fluentui/react-accordion';
+import type { AvatarBaseProps } from '@fluentui/react-avatar';
+import { AvatarBaseState } from '@fluentui/react-avatar';
+import type { BadgeBaseProps } from '@fluentui/react-badge';
+import { BadgeBaseState } from '@fluentui/react-badge';
+import type { BreadcrumbBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonBaseProps } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonSlots as BreadcrumbButtonSlots_2 } from '@fluentui/react-breadcrumb';
+import { BreadcrumbContextValues as BreadcrumbContextValues_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbDividerBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbDividerBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbDividerSlots as BreadcrumbDividerSlots_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbItemBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbItemBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbItemSlots as BreadcrumbItemSlots_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbSlots as BreadcrumbSlots_2 } from '@fluentui/react-breadcrumb';
+import type { ButtonBaseProps } from '@fluentui/react-button';
+import { ButtonBaseState } from '@fluentui/react-button';
+import type { ButtonSlots as ButtonSlots_2 } from '@fluentui/react-button';
+import type { CheckboxBaseProps } from '@fluentui/react-checkbox';
+import { CheckboxBaseState } from '@fluentui/react-checkbox';
+import type { CheckboxSlots as CheckboxSlots_2 } from '@fluentui/react-checkbox';
+import { ComponentProps } from '@fluentui/react-utilities';
+import type { ComponentState } from '@fluentui/react-utilities';
+import { ContextSelector } from '@fluentui/react-context-selector';
+import type { DividerBaseProps } from '@fluentui/react-divider';
+import { DividerBaseState } from '@fluentui/react-divider';
+import type { DividerSlots as DividerSlots_2 } from '@fluentui/react-divider';
+import type { EventData } from '@fluentui/react-utilities';
+import type { EventHandler } from '@fluentui/react-utilities';
+import type { FieldBaseProps } from '@fluentui/react-field';
+import { FieldBaseState } from '@fluentui/react-field';
+import { FieldContextValues } from '@fluentui/react-field';
+import type { FieldSlots as FieldSlots_2 } from '@fluentui/react-field';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import type { InputBaseProps } from '@fluentui/react-input';
+import { InputBaseState } from '@fluentui/react-input';
+import type { InputSlots as InputSlots_2 } from '@fluentui/react-input';
+import { JSXElement } from '@fluentui/react-utilities';
+import type { LinkBaseProps } from '@fluentui/react-link';
+import { LinkBaseState } from '@fluentui/react-link';
+import type { LinkSlots as LinkSlots_2 } from '@fluentui/react-link';
+import { MessageBarActionsContextValues as MessageBarActionsContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarActionsProps as MessageBarActionsProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarActionsSlots as MessageBarActionsSlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarActionsState as MessageBarActionsState_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBaseProps } from '@fluentui/react-message-bar';
+import { MessageBarBaseState } from '@fluentui/react-message-bar';
+import { MessageBarBodyContextValues as MessageBarBodyContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBodyProps as MessageBarBodyProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBodySlots as MessageBarBodySlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarBodyState as MessageBarBodyState_2 } from '@fluentui/react-message-bar';
+import { MessageBarContextValue } from '@fluentui/react-message-bar';
+import { MessageBarContextValues as MessageBarContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarIntent } from '@fluentui/react-message-bar';
+import type { MessageBarSlots as MessageBarSlots_2 } from '@fluentui/react-message-bar';
+import type { MessageBarTitleProps as MessageBarTitleProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarTitleSlots as MessageBarTitleSlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarTitleState as MessageBarTitleState_2 } from '@fluentui/react-message-bar';
+import type { ProgressBarBaseProps } from '@fluentui/react-progress';
+import type { ProgressBarBaseState } from '@fluentui/react-progress';
+import type { ProgressBarSlots as ProgressBarSlots_2 } from '@fluentui/react-progress';
+import type { RadioBaseProps } from '@fluentui/react-radio';
+import { RadioBaseState } from '@fluentui/react-radio';
+import type { RadioGroupBaseProps } from '@fluentui/react-radio';
+import { RadioGroupBaseState } from '@fluentui/react-radio';
+import { RadioGroupContextValues } from '@fluentui/react-radio';
+import type { RadioGroupSlots as RadioGroupSlots_2 } from '@fluentui/react-radio';
+import { RadioOnChangeData } from '@fluentui/react-radio';
+import { RadioSlots as RadioSlots_2 } from '@fluentui/react-radio';
+import type { RatingBaseProps } from '@fluentui/react-rating';
+import { RatingBaseState } from '@fluentui/react-rating';
+import { RatingContextValues } from '@fluentui/react-rating';
+import type { RatingDisplayBaseProps } from '@fluentui/react-rating';
+import { RatingDisplayBaseState } from '@fluentui/react-rating';
+import { RatingDisplayContextValues } from '@fluentui/react-rating';
+import type { RatingDisplaySlots as RatingDisplaySlots_2 } from '@fluentui/react-rating';
+import type { RatingItemBaseProps } from '@fluentui/react-rating';
+import { RatingItemBaseState } from '@fluentui/react-rating';
+import { RatingItemSlots as RatingItemSlots_2 } from '@fluentui/react-rating';
+import type { RatingSlots as RatingSlots_2 } from '@fluentui/react-rating';
+import * as React_2 from 'react';
+import type { SearchBoxBaseProps } from '@fluentui/react-search';
+import { SearchBoxBaseState } from '@fluentui/react-search';
+import type { SearchBoxSlots as SearchBoxSlots_2 } from '@fluentui/react-search';
+import type { SelectBaseProps } from '@fluentui/react-select';
+import { SelectBaseState } from '@fluentui/react-select';
+import type { SelectSlots as SelectSlots_2 } from '@fluentui/react-select';
+import { SkeletonBaseProps } from '@fluentui/react-skeleton';
+import { SkeletonBaseState } from '@fluentui/react-skeleton';
+import { SkeletonContextValues } from '@fluentui/react-skeleton';
+import { SkeletonItemBaseProps } from '@fluentui/react-skeleton';
+import { SkeletonItemBaseState } from '@fluentui/react-skeleton';
+import type { SkeletonItemSlots as SkeletonItemSlots_2 } from '@fluentui/react-skeleton';
+import type { SkeletonSlots as SkeletonSlots_2 } from '@fluentui/react-skeleton';
+import type { SliderBaseProps } from '@fluentui/react-slider';
+import { SliderBaseState } from '@fluentui/react-slider';
+import type { SliderSlots as SliderSlots_2 } from '@fluentui/react-slider';
+import type { Slot } from '@fluentui/react-utilities';
+import type { SpinButtonBaseProps } from '@fluentui/react-spinbutton';
+import { SpinButtonBaseState } from '@fluentui/react-spinbutton';
+import type { SpinButtonSlots as SpinButtonSlots_2 } from '@fluentui/react-spinbutton';
+import type { SpinnerBaseProps } from '@fluentui/react-spinner';
+import { SpinnerBaseState } from '@fluentui/react-spinner';
+import type { SpinnerSlots as SpinnerSlots_2 } from '@fluentui/react-spinner';
+import type { SwitchBaseProps } from '@fluentui/react-switch';
+import { SwitchBaseState } from '@fluentui/react-switch';
+import type { SwitchSlots as SwitchSlots_2 } from '@fluentui/react-switch';
+import type { TabBaseProps } from '@fluentui/react-tabs';
+import { TabBaseState } from '@fluentui/react-tabs';
+import type { TabListBaseProps } from '@fluentui/react-tabs';
+import { TabListBaseState } from '@fluentui/react-tabs';
+import { TabListContextValues } from '@fluentui/react-tabs';
+import type { TabListSlots as TabListSlots_2 } from '@fluentui/react-tabs';
+import { TabSlots } from '@fluentui/react-tabs';
+import { TabValue } from '@fluentui/react-tabs';
+import type { TextareaBaseProps } from '@fluentui/react-textarea';
+import { TextareaBaseState } from '@fluentui/react-textarea';
+import type { TextareaSlots as TextareaSlots_2 } from '@fluentui/react-textarea';
+import type { ToggleButtonBaseProps } from '@fluentui/react-button';
+import type { ToggleButtonBaseState } from '@fluentui/react-button';
+import { useMessageBarBodyContextValues_unstable } from '@fluentui/react-message-bar';
+
+// @public
+export const Accordion: ForwardRefComponent<AccordionProps>;
+
+// @public (undocumented)
+export type AccordionContextValues = AccordionContextValues_2;
+
+// @public
+export const AccordionHeader: ForwardRefComponent<AccordionHeaderProps>;
+
+// @public (undocumented)
+export type AccordionHeaderProps = AccordionHeaderBaseProps;
+
+// @public (undocumented)
+export type AccordionHeaderSlots = AccordionHeaderSlots_2;
+
+// @public (undocumented)
+export type AccordionHeaderState = AccordionHeaderBaseState & {
+    root: {
+        'data-open'?: string;
+        'data-disabled'?: string;
+        'data-expand-icon-position'?: string;
+    };
+};
+
+// @public
+export const AccordionItem: ForwardRefComponent<AccordionItemProps>;
+
+// @public (undocumented)
+export type AccordionItemProps = AccordionItemProps_2;
+
+// @public (undocumented)
+export type AccordionItemSlots = AccordionItemSlots_2;
+
+// @public (undocumented)
+export type AccordionItemState = AccordionItemState_2 & {
+    root: {
+        'data-disabled'?: string;
+        'data-open'?: string;
+    };
+};
+
+// @public
+export const AccordionPanel: ForwardRefComponent<AccordionPanelProps>;
+
+// @public (undocumented)
+export type AccordionPanelProps = AccordionPanelBaseProps;
+
+// @public (undocumented)
+export type AccordionPanelSlots = AccordionPanelSlots_2;
+
+// @public (undocumented)
+export type AccordionPanelState = AccordionPanelBaseState & {
+    root: {
+        'data-open'?: string;
+    };
+};
+
+// @public (undocumented)
+export type AccordionProps = AccordionBaseProps;
+
+// @public (undocumented)
+export type AccordionSlots = AccordionSlots_2;
+
+// @public (undocumented)
+export type AccordionState = AccordionBaseState & {
+    root: {
+        'data-collapsible'?: string;
+        'data-multiple'?: string;
+    };
+};
+
+// @public (undocumented)
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+
+// @public
+export const Avatar: ForwardRefComponent<AvatarProps>;
+
+// @public
+export type AvatarProps = AvatarBaseProps;
+
+// @public
+export type AvatarState = AvatarBaseState;
+
+// @public
+export const Badge: ForwardRefComponent<BadgeProps>;
+
+// @public
+export type BadgeProps = BadgeBaseProps;
+
+// @public
+export type BadgeState = BadgeBaseState & {
+    root: {
+        'data-icon-position'?: 'before' | 'after';
+    };
+};
+
+// @public
+export const Breadcrumb: ForwardRefComponent<BreadcrumbProps>;
+
+// @public
+export const BreadcrumbButton: ForwardRefComponent<BreadcrumbButtonProps>;
+
+// @public
+export type BreadcrumbButtonProps = BreadcrumbButtonBaseProps;
+
+// @public
+export type BreadcrumbButtonSlots = BreadcrumbButtonSlots_2;
+
+// @public
+export type BreadcrumbButtonState = BreadcrumbButtonBaseState & {
+    root: {
+        'data-current'?: string;
+    };
+};
+
+// @public
+export type BreadcrumbContextValues = BreadcrumbContextValues_2;
+
+// @public
+export const BreadcrumbDivider: ForwardRefComponent<BreadcrumbDividerProps>;
+
+// @public
+export type BreadcrumbDividerProps = BreadcrumbDividerBaseProps;
+
+// @public
+export type BreadcrumbDividerSlots = BreadcrumbDividerSlots_2;
+
+// @public
+export type BreadcrumbDividerState = BreadcrumbDividerBaseState;
+
+// @public
+export const BreadcrumbItem: ForwardRefComponent<BreadcrumbItemProps>;
+
+// @public
+export type BreadcrumbItemProps = BreadcrumbItemBaseProps;
+
+// @public
+export type BreadcrumbItemSlots = BreadcrumbItemSlots_2;
+
+// @public
+export type BreadcrumbItemState = BreadcrumbItemBaseState;
+
+// @public
+export type BreadcrumbProps = BreadcrumbBaseProps;
+
+// @public
+export type BreadcrumbSlots = BreadcrumbSlots_2;
+
+// @public
+export type BreadcrumbState = BreadcrumbBaseState;
+
+// @public
+export const Button: ForwardRefComponent<ButtonProps>;
+
+// @public
+export type ButtonProps = ButtonBaseProps;
+
+// @public
+export type ButtonSlots = ButtonSlots_2;
+
+// @public
+export type ButtonState = ButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-icon-only'?: string;
+    };
+};
+
+// @public
+export const Checkbox: ForwardRefComponent<CheckboxProps>;
+
+// @public
+export type CheckboxProps = CheckboxBaseProps;
+
+// @public (undocumented)
+export type CheckboxSlots = CheckboxSlots_2;
+
+// @public
+export type CheckboxState = CheckboxBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const Divider: ForwardRefComponent<DividerProps>;
+
+// @public (undocumented)
+export type DividerProps = DividerBaseProps;
+
+// @public (undocumented)
+export type DividerSlots = DividerSlots_2;
+
+// @public (undocumented)
+export type DividerState = DividerBaseState & {
+    root: {
+        'data-orientation'?: 'vertical' | 'horizontal';
+    };
+};
+
+// @public
+export const Field: ForwardRefComponent<FieldProps>;
+
+// @public
+export type FieldProps = FieldBaseProps;
+
+// @public
+export type FieldSlots = FieldSlots_2;
+
+// @public
+export type FieldState = FieldBaseState & {
+    root: {
+        'data-validate-state'?: FieldBaseState['validationState'];
+    };
+};
+
+// @public
+export const Input: ForwardRefComponent<InputProps>;
+
+// @public
+export type InputProps = InputBaseProps;
+
+// @public
+export type InputSlots = InputSlots_2;
+
+// @public
+export type InputState = InputBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Link: ForwardRefComponent<LinkProps>;
+
+// @public
+export type LinkProps = LinkBaseProps;
+
+// @public
+export type LinkSlots = LinkSlots_2;
+
+// @public
+export type LinkState = LinkBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+    };
+};
+
+// @public
+export const MessageBar: ForwardRefComponent<MessageBarProps>;
+
+// @public
+export const MessageBarActions: ForwardRefComponent<MessageBarActionsProps>;
+
+// @public (undocumented)
+export type MessageBarActionsContextValues = MessageBarActionsContextValues_2;
+
+// @public (undocumented)
+export type MessageBarActionsProps = MessageBarActionsProps_2;
+
+// @public (undocumented)
+export type MessageBarActionsSlots = MessageBarActionsSlots_2;
+
+// @public (undocumented)
+export type MessageBarActionsState = MessageBarActionsState_2 & {
+    root: {
+        'data-layout'?: string;
+        'data-has-actions'?: string;
+    };
+};
+
+// @public
+export const MessageBarBody: ForwardRefComponent<MessageBarBodyProps>;
+
+// @public (undocumented)
+export type MessageBarBodyContextValues = MessageBarBodyContextValues_2;
+
+// @public (undocumented)
+export type MessageBarBodyProps = MessageBarBodyProps_2;
+
+// @public (undocumented)
+export type MessageBarBodySlots = MessageBarBodySlots_2;
+
+// @public (undocumented)
+export type MessageBarBodyState = MessageBarBodyState_2;
+
+// @public (undocumented)
+export type MessageBarContextValues = MessageBarContextValues_2;
+
+export { MessageBarIntent }
+
+// @public (undocumented)
+export type MessageBarProps = MessageBarBaseProps;
+
+// @public (undocumented)
+export type MessageBarSlots = MessageBarSlots_2;
+
+// @public (undocumented)
+export type MessageBarState = MessageBarBaseState & {
+    root: {
+        'data-layout'?: string;
+        'data-intent'?: string;
+    };
+};
+
+// @public
+export const MessageBarTitle: ForwardRefComponent<MessageBarTitleProps>;
+
+// @public (undocumented)
+export type MessageBarTitleProps = MessageBarTitleProps_2;
+
+// @public (undocumented)
+export type MessageBarTitleSlots = MessageBarTitleSlots_2;
+
+// @public (undocumented)
+export type MessageBarTitleState = MessageBarTitleState_2;
+
+// @public
+export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
+    open: boolean;
+};
+
+// @public
+export type OpenPopoverEvents = MouseEvent | TouchEvent | React_2.FocusEvent<HTMLElement> | React_2.KeyboardEvent<HTMLElement> | React_2.MouseEvent<HTMLElement>;
+
+// @public
+export const Popover: {
+    (props: PopoverProps): JSXElement;
+    displayName: string;
+};
+
+// @public
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+    positioning: {
+        targetRef: React_2.RefCallback<HTMLElement>;
+        containerRef: React_2.RefCallback<HTMLElement>;
+    };
+};
+
+// @public
+export type PopoverProps = {
+    children: [JSXElement, JSXElement] | JSXElement;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: EventHandler<OnOpenChangeData>;
+    openOnHover?: boolean;
+    openOnContext?: boolean;
+    mouseLeaveDelay?: number;
+    positioning?: PositioningShorthand;
+    withArrow?: boolean;
+    trapFocus?: boolean;
+    disableAutoFocus?: boolean;
+    closeOnScroll?: boolean;
+    closeOnIframeFocus?: boolean;
+    inline?: boolean;
+    mountNode?: HTMLElement | null;
+};
+
+// @public
+export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
+    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
+    toggleOpen: (e: OpenPopoverEvents) => void;
+    triggerRef: React_2.RefObject<HTMLElement | null>;
+    contentRef: React_2.RefObject<HTMLElement | null>;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    popoverTrigger: React_2.ReactElement | undefined;
+    popoverSurface: React_2.ReactElement | undefined;
+    contextTarget: {
+        x: number;
+        y: number;
+    } | undefined;
+    setContextTarget: (target: {
+        x: number;
+        y: number;
+    } | undefined) => void;
+    positioning: PositioningReturn;
+};
+
+// @public
+export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps>;
+
+// @public (undocumented)
+export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
+
+// @public
+export type PopoverSurfaceSlots = {
+    root: Slot<'div'>;
+};
+
+// @public (undocumented)
+export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
+    inline: boolean;
+    withArrow: boolean | undefined;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    mountNode: HTMLElement | null | undefined;
+    'data-open': string;
+};
+
+// @public
+export const PopoverTrigger: React_2.FC<PopoverTriggerProps>;
+
+// @public
+export type PopoverTriggerProps = {
+    children: React_2.ReactElement;
+    disableButtonEnhancement?: boolean;
+};
+
+// @public
+export type PopoverTriggerState = {
+    children: React_2.ReactElement | null;
+};
+
+// @public (undocumented)
+export type Position = 'above' | 'below' | 'before' | 'after';
+
+// @public
+export type PositioningBoundaryPadding = number | Partial<{
+    top: number;
+    end: number;
+    bottom: number;
+    start: number;
+}>;
+
+// @public
+export type PositioningImperativeRef = {
+    setTarget: (target: HTMLElement | null) => void;
+    updatePosition: () => void;
+};
+
+// @public (undocumented)
+export type PositioningProps = {
+    position?: Position;
+    align?: Alignment;
+    offset?: number | {
+        mainAxis?: number;
+        crossAxis?: number;
+    };
+    fallbackPositions?: PositioningShorthandValue[];
+    coverTarget?: boolean;
+    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+    strategy?: 'absolute' | 'fixed';
+    matchTargetSize?: 'width';
+    pinned?: boolean;
+    positioningRef?: React_2.Ref<PositioningImperativeRef>;
+    overflowBoundary?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+    overflowBoundaryPadding?: PositioningBoundaryPadding;
+};
+
+// @public (undocumented)
+export type PositioningReturn = {
+    targetRef: React_2.RefCallback<HTMLElement>;
+    containerRef: React_2.RefCallback<HTMLElement>;
+};
+
+// @public (undocumented)
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+// @public (undocumented)
+export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
+
+// @public
+export const ProgressBar: ForwardRefComponent<ProgressBarProps>;
+
+// @public
+export type ProgressBarProps = ProgressBarBaseProps;
+
+// @public (undocumented)
+export type ProgressBarSlots = ProgressBarSlots_2;
+
+// @public
+export type ProgressBarState = ProgressBarBaseState;
+
+// @public
+export const Radio: React_2.ForwardRefExoticComponent<Omit<ComponentProps<Partial<RadioSlots_2>, "input">, "onChange" | "size"> & {
+    value?: string;
+    labelPosition?: "after" | "below";
+    disabled?: boolean;
+    onChange?: (ev: React_2.ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void;
+} & React_2.RefAttributes<HTMLInputElement>>;
+
+// @public
+export const RadioGroup: ForwardRefComponent<RadioGroupProps>;
+
+// @public
+export type RadioGroupProps = RadioGroupBaseProps;
+
+// @public
+export type RadioGroupSlots = RadioGroupSlots_2;
+
+// @public
+export type RadioGroupState = RadioGroupBaseState;
+
+// @public
+export type RadioProps = RadioBaseProps;
+
+// @public
+export type RadioSlots = RadioSlots_2;
+
+// @public
+export type RadioState = RadioBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Rating: ForwardRefComponent<RatingProps>;
+
+// @public
+export const RatingDisplay: ForwardRefComponent<RatingDisplayProps>;
+
+// @public
+export type RatingDisplayProps = RatingDisplayBaseProps;
+
+// @public
+export type RatingDisplaySlots = RatingDisplaySlots_2;
+
+// @public
+export type RatingDisplayState = RatingDisplayBaseState;
+
+// @public
+export const RatingItem: React_2.ForwardRefExoticComponent<Omit<Partial<RatingItemSlots_2>, "root"> & Omit<{
+    as?: "span" | undefined;
+} & Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "children"> & {
+    children?: any;
+}, "ref"> & {
+    value?: number;
+} & React_2.RefAttributes<HTMLSpanElement>>;
+
+// @public
+export type RatingItemProps = RatingItemBaseProps;
+
+// @public
+export type RatingItemSlots = RatingItemSlots_2;
+
+// @public
+export type RatingItemState = RatingItemBaseState & {
+    root: {
+        'data-appearance'?: 'filled' | 'filled-half' | 'outline';
+    };
+};
+
+// @public
+export type RatingProps = RatingBaseProps;
+
+// @public
+export type RatingSlots = RatingSlots_2;
+
+// @public
+export type RatingState = RatingBaseState;
+
+// @public
+export const renderAccordion: (state: AccordionBaseState, contextValues: AccordionContextValues_2) => JSXElement;
+
+// @public
+export const renderAccordionHeader: (state: AccordionHeaderBaseState, contextValues: AccordionHeaderContextValues) => JSXElement;
+
+// @public
+export const renderAccordionItem: (state: AccordionItemState_2, contextValues: AccordionItemContextValues) => JSXElement;
+
+// @public
+export const renderAccordionPanel: (state: AccordionPanelState) => JSXElement;
+
+// @public
+export const renderAvatar: (state: AvatarBaseState) => JSXElement;
+
+// @public
+export const renderBadge: (state: BadgeBaseState) => JSXElement;
+
+// @public
+export const renderBreadcrumb: (state: BreadcrumbBaseState, contextValues: BreadcrumbContextValues_2) => JSXElement;
+
+// @public
+export const renderBreadcrumbButton: (state: BreadcrumbButtonState) => JSXElement;
+
+// @public
+export const renderBreadcrumbDivider: (state: BreadcrumbDividerBaseState) => JSXElement;
+
+// @public
+export const renderBreadcrumbItem: (state: BreadcrumbItemBaseState) => JSXElement;
+
+// @public
+export const renderButton: (state: ButtonBaseState) => JSXElement;
+
+// @public
+export const renderCheckbox: (state: CheckboxBaseState) => JSXElement;
+
+// @public
+export const renderDivider: (state: DividerBaseState) => JSXElement;
+
+// @public
+export const renderField: (state: FieldBaseState, contextValues: FieldContextValues) => JSXElement;
+
+// @public
+export const renderInput: (state: InputBaseState) => JSXElement;
+
+// @public
+export const renderLink: (state: LinkBaseState) => JSXElement;
+
+// @public
+export const renderMessageBar: (state: MessageBarBaseState, contexts: MessageBarContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarActions: (state: MessageBarActionsState_2, contexts: MessageBarActionsContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarBody: (state: MessageBarBodyState_2, contextValues: MessageBarBodyContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarTitle: (state: MessageBarTitleState_2) => JSXElement;
+
+// @public
+export const renderPopover: (state: PopoverState, contextValues: {
+    popover: PopoverContextValue;
+}) => React_2.ReactElement;
+
+// @public
+export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
+
+// @public
+export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
+
+// @public
+export const renderProgressBar: (state: ProgressBarState) => JSXElement;
+
+// @public
+export const renderRadio: (state: RadioBaseState) => JSXElement;
+
+// @public
+export const renderRadioGroup: (state: RadioGroupBaseState, contextValues: RadioGroupContextValues) => JSXElement;
+
+// @public
+export const renderRating: (state: RatingBaseState, contextValues: RatingContextValues) => JSXElement;
+
+// @public
+export const renderRatingDisplay: (state: RatingDisplayBaseState, contextValues: RatingDisplayContextValues) => JSXElement;
+
+// @public
+export const renderRatingItem: (state: RatingItemBaseState) => JSXElement;
+
+// @public
+export const renderSearchBox: (state: SearchBoxBaseState) => JSXElement;
+
+// @public
+export const renderSelect: (state: SelectBaseState) => JSXElement;
+
+// @public
+export const renderSkeleton: (state: SkeletonBaseState, contextValues: SkeletonContextValues) => JSXElement;
+
+// @public
+export const renderSkeletonItem: (state: SkeletonItemBaseState) => JSXElement;
+
+// @public
+export const renderSlider: (state: SliderBaseState) => JSXElement;
+
+// @public
+export const renderSpinButton: (state: SpinButtonBaseState) => JSXElement;
+
+// @public
+export const renderSpinner: (state: SpinnerBaseState) => JSXElement;
+
+// @public
+export const renderSwitch: (state: SwitchBaseState) => JSXElement;
+
+// @public
+export const renderTab: (state: TabBaseState) => JSXElement;
+
+// @public
+export const renderTabList: (state: TabListBaseState, contextValues: TabListContextValues) => JSXElement;
+
+// @public
+export const renderTextarea: (state: TextareaBaseState) => JSXElement;
+
+// @public
+export const renderToggleButton: (state: ButtonBaseState) => JSXElement;
+
+// @public
+export const SearchBox: ForwardRefComponent<SearchBoxProps>;
+
+// @public
+export type SearchBoxProps = SearchBoxBaseProps;
+
+// @public
+export type SearchBoxSlots = SearchBoxSlots_2;
+
+// @public
+export type SearchBoxState = SearchBoxBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-focused'?: string;
+    };
+};
+
+// @public
+export const Select: ForwardRefComponent<SelectProps>;
+
+// @public
+export type SelectProps = SelectBaseProps;
+
+// @public (undocumented)
+export type SelectSlots = SelectSlots_2;
+
+// @public
+export type SelectState = SelectBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Skeleton: React_2.ForwardRefExoticComponent<SkeletonBaseProps & React_2.RefAttributes<HTMLDivElement>>;
+
+// @public
+export const SkeletonItem: React_2.ForwardRefExoticComponent<SkeletonItemBaseProps & React_2.RefAttributes<HTMLDivElement>>;
+
+// @public
+export type SkeletonItemProps = SkeletonItemBaseProps;
+
+// @public
+export type SkeletonItemSlots = SkeletonItemSlots_2;
+
+// @public
+export type SkeletonItemState = SkeletonItemBaseState;
+
+// @public
+export type SkeletonProps = SkeletonBaseProps;
+
+// @public
+export type SkeletonSlots = SkeletonSlots_2;
+
+// @public
+export type SkeletonState = SkeletonBaseState;
+
+// @public
+export const Slider: ForwardRefComponent<SliderProps>;
+
+// @public
+export type SliderProps = SliderBaseProps;
+
+// @public
+export type SliderSlots = SliderSlots_2;
+
+// @public
+export type SliderState = SliderBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-vertical'?: string;
+    };
+};
+
+// @public
+export const SpinButton: ForwardRefComponent<SpinButtonProps>;
+
+// @public
+export type SpinButtonProps = SpinButtonBaseProps;
+
+// @public
+export type SpinButtonSlots = SpinButtonSlots_2;
+
+// @public
+export type SpinButtonState = SpinButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-spin-state'?: string;
+        'data-at-bound'?: string;
+    };
+};
+
+// @public
+export const Spinner: ForwardRefComponent<SpinnerProps>;
+
+// @public
+export type SpinnerProps = SpinnerBaseProps;
+
+// @public
+export type SpinnerSlots = SpinnerSlots_2;
+
+// @public
+export type SpinnerState = SpinnerBaseState & {
+    root: {
+        'data-label-position'?: 'before' | 'after' | 'above' | 'below';
+    };
+};
+
+// @public
+export const Switch: ForwardRefComponent<SwitchProps>;
+
+// @public
+export type SwitchProps = SwitchBaseProps;
+
+// @public
+export type SwitchSlots = SwitchSlots_2;
+
+// @public
+export type SwitchState = SwitchBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const Tab: ForwardRefComponent<TabProps>;
+
+// @public
+export const TabList: ForwardRefComponent<TabListProps>;
+
+// @public
+export type TabListProps = TabListBaseProps;
+
+// @public
+export type TabListSlots = TabListSlots_2;
+
+// @public
+export type TabListState = TabListBaseState & {
+    root: {
+        focusgroup?: string;
+        'data-orientation'?: 'vertical' | 'horizontal';
+    };
+};
+
+// @public (undocumented)
+export type TabProps = TabBaseProps;
+
+export { TabSlots }
+
+// @public (undocumented)
+export type TabState = TabBaseState & {
+    root: {
+        focusgroupstart?: string;
+        'data-icon-only'?: string;
+        'data-selected'?: string;
+    };
+};
+
+export { TabValue }
+
+// @public
+export const Textarea: ForwardRefComponent<TextareaProps>;
+
+// @public
+export type TextareaProps = TextareaBaseProps;
+
+// @public
+export type TextareaSlots = TextareaSlots_2;
+
+// @public
+export type TextareaState = TextareaBaseState;
+
+// @public
+export const ToggleButton: ForwardRefComponent<ToggleButtonProps>;
+
+// @public
+export type ToggleButtonProps = ToggleButtonBaseProps;
+
+// @public
+export type ToggleButtonSlots = ButtonSlots;
+
+// @public
+export type ToggleButtonState = ToggleButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-icon-only'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const useAccordion: (props: AccordionProps, ref: React_2.Ref<HTMLElement>) => AccordionState;
+
+// @public
+export const useAccordionContext: <T>(selector: ContextSelector<AccordionContextValue, T>) => T;
+
+// @public
+export const useAccordionContextValues: (state: AccordionState) => AccordionContextValues;
+
+// @public
+export const useAccordionHeader: (props: AccordionHeaderProps, ref: React_2.Ref<HTMLElement>) => AccordionHeaderState;
+
+// @public
+export const useAccordionItem: (props: AccordionItemProps, ref: React_2.Ref<HTMLElement>) => AccordionItemState;
+
+// @public
+export const useAccordionPanel: (props: AccordionPanelProps, ref: React_2.Ref<HTMLElement>) => AccordionPanelState;
+
+// @public
+export const useAvatar: (props: AvatarProps, ref: React_2.Ref<HTMLElement>) => AvatarState;
+
+// @public
+export const useBadge: (props: BadgeProps, ref: React_2.Ref<HTMLDivElement>) => BadgeState;
+
+// @public
+export const useBreadcrumb: (props: BreadcrumbProps, ref: React_2.Ref<HTMLElement>) => BreadcrumbState;
+
+// @public
+export const useBreadcrumbButton: (props: BreadcrumbButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => BreadcrumbButtonState;
+
+// @public
+export const useBreadcrumbContext: () => BreadcrumbContextValues_2;
+
+// @public
+export const useBreadcrumbContextValues: (state: BreadcrumbState) => BreadcrumbContextValues;
+
+// @public
+export const useBreadcrumbDivider: (props: BreadcrumbDividerProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbDividerState;
+
+// @public
+export const useBreadcrumbItem: (props: BreadcrumbItemProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbItemState;
+
+// @public
+export const useButton: (props: ButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
+
+// @public
+export const useCheckbox: (props: CheckboxProps, ref: React_2.Ref<HTMLInputElement>) => CheckboxState;
+
+// @public
+export const useDivider: (props: DividerProps, ref: React_2.Ref<HTMLElement>) => DividerState;
+
+// @public
+export const useField: (props: FieldProps, ref: React_2.Ref<HTMLDivElement>) => FieldState;
+
+// @public
+export const useInput: (props: InputProps, ref: React_2.Ref<HTMLInputElement>) => InputState;
+
+// @public
+export const useLink: (props: LinkProps, ref: React_2.Ref<HTMLElement>) => LinkState;
+
+// @public
+export const useMessageBar: (props: MessageBarProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarState;
+
+// @public
+export const useMessageBarActions: (props: MessageBarActionsProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarActionsState;
+
+// @public
+export const useMessageBarActionsContextValues: () => MessageBarActionsContextValues;
+
+// @public
+export const useMessageBarBody: (props: MessageBarBodyProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarBodyState;
+
+// @public
+export const useMessageBarBodyContextValues: typeof useMessageBarBodyContextValues_unstable;
+
+// @public
+export const useMessageBarContext: () => MessageBarContextValue;
+
+// @public
+export const useMessageBarContextValues: (state: MessageBarState) => MessageBarContextValues;
+
+// @public
+export const useMessageBarTitle: (props: MessageBarTitleProps, ref: React_2.Ref<HTMLElement>) => MessageBarTitleState;
+
+// @public
+export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
+
+// @public
+export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
+
+// @public (undocumented)
+export const usePopoverContextValues: (state: PopoverState) => {
+    popover: PopoverContextValue;
+};
+
+// @public
+export const usePopoverSurface: (props: PopoverSurfaceProps, ref: React_2.Ref<HTMLDivElement>) => PopoverSurfaceState;
+
+// @public
+export const usePopoverTrigger: (props: PopoverTriggerProps) => PopoverTriggerState;
+
+// @public
+export const useProgressBar: (props: ProgressBarProps, ref: React_2.Ref<HTMLDivElement>) => ProgressBarState;
+
+// @public
+export const useRadio: (props: RadioProps, ref: React_2.Ref<HTMLInputElement>) => RadioState;
+
+// @public
+export const useRadioGroup: (props: RadioGroupProps, ref: React_2.Ref<HTMLDivElement>) => RadioGroupState;
+
+// @public
+export const useRating: (props: RatingProps, ref: React_2.Ref<HTMLDivElement>) => RatingState;
+
+// @public
+export const useRatingDisplay: (props: RatingDisplayProps, ref: React_2.Ref<HTMLDivElement>) => RatingDisplayState;
+
+// @public
+export const useRatingItem: (props: RatingItemProps, ref: React_2.Ref<HTMLSpanElement>) => RatingItemState;
+
+// @public
+export const useSearchBox: (props: SearchBoxProps, ref: React_2.Ref<HTMLInputElement>) => SearchBoxState;
+
+// @public
+export const useSelect: (props: SelectProps, ref: React_2.Ref<HTMLSelectElement>) => SelectState;
+
+// @public
+export const useSkeleton: (props: SkeletonProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonState;
+
+// @public
+export const useSkeletonItem: (props: SkeletonItemProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonItemState;
+
+// @public
+export const useSlider: (props: SliderProps, ref: React_2.Ref<HTMLInputElement>) => SliderState;
+
+// @public
+export const useSpinButton: (props: SpinButtonProps, ref: React_2.Ref<HTMLInputElement>) => SpinButtonState;
+
+// @public
+export const useSpinner: (props: SpinnerProps, ref: React_2.Ref<HTMLElement>) => SpinnerState;
+
+// @public
+export const useSwitch: (props: SwitchProps, ref: React_2.Ref<HTMLInputElement>) => SwitchState;
+
+// @public
+export const useTab: (props: TabProps, ref: React_2.Ref<HTMLElement>) => TabState;
+
+// @public
+export const useTabList: (props: TabListProps, ref: React_2.Ref<HTMLElement>) => TabListState;
+
+// @public
+export const useTextarea: (props: TextareaProps, ref: React_2.Ref<HTMLTextAreaElement>) => TextareaState;
+
+// @public
+export const useToggleButton: (props: ToggleButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ToggleButtonState;
+
+=======
+import type { AccordionBaseProps } from '@fluentui/react-accordion';
+import { AccordionBaseState } from '@fluentui/react-accordion';
+import { AccordionContextValue } from '@fluentui/react-accordion';
+import { AccordionContextValues as AccordionContextValues_2 } from '@fluentui/react-accordion';
+import type { AccordionHeaderBaseProps } from '@fluentui/react-accordion';
+import { AccordionHeaderBaseState } from '@fluentui/react-accordion';
+import { AccordionHeaderContextValues } from '@fluentui/react-accordion';
+import type { AccordionHeaderSlots as AccordionHeaderSlots_2 } from '@fluentui/react-accordion';
+import { AccordionItemContextValues } from '@fluentui/react-accordion';
+import type { AccordionItemProps as AccordionItemProps_2 } from '@fluentui/react-accordion';
+import type { AccordionItemSlots as AccordionItemSlots_2 } from '@fluentui/react-accordion';
+import { AccordionItemState as AccordionItemState_2 } from '@fluentui/react-accordion';
+import type { AccordionPanelBaseProps } from '@fluentui/react-accordion';
+import type { AccordionPanelBaseState } from '@fluentui/react-accordion';
+import type { AccordionPanelSlots as AccordionPanelSlots_2 } from '@fluentui/react-accordion';
+import type { AccordionSlots as AccordionSlots_2 } from '@fluentui/react-accordion';
+import type { AvatarBaseProps } from '@fluentui/react-avatar';
+import { AvatarBaseState } from '@fluentui/react-avatar';
+import type { BadgeBaseProps } from '@fluentui/react-badge';
+import { BadgeBaseState } from '@fluentui/react-badge';
+import type { BreadcrumbBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonBaseProps } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbButtonSlots as BreadcrumbButtonSlots_2 } from '@fluentui/react-breadcrumb';
+import { BreadcrumbContextValues as BreadcrumbContextValues_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbDividerBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbDividerBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbDividerSlots as BreadcrumbDividerSlots_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbItemBaseProps } from '@fluentui/react-breadcrumb';
+import { BreadcrumbItemBaseState } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbItemSlots as BreadcrumbItemSlots_2 } from '@fluentui/react-breadcrumb';
+import type { BreadcrumbSlots as BreadcrumbSlots_2 } from '@fluentui/react-breadcrumb';
+import type { ButtonBaseProps } from '@fluentui/react-button';
+import { ButtonBaseState } from '@fluentui/react-button';
+import type { ButtonSlots as ButtonSlots_2 } from '@fluentui/react-button';
+import type { CheckboxBaseProps } from '@fluentui/react-checkbox';
+import { CheckboxBaseState } from '@fluentui/react-checkbox';
+import type { CheckboxSlots as CheckboxSlots_2 } from '@fluentui/react-checkbox';
+import { ComponentProps } from '@fluentui/react-utilities';
+import type { ComponentState } from '@fluentui/react-utilities';
+import { ContextSelector } from '@fluentui/react-context-selector';
+import type { DividerBaseProps } from '@fluentui/react-divider';
+import { DividerBaseState } from '@fluentui/react-divider';
+import type { DividerSlots as DividerSlots_2 } from '@fluentui/react-divider';
+import type { EventData } from '@fluentui/react-utilities';
+import type { EventHandler } from '@fluentui/react-utilities';
+import type { FieldBaseProps } from '@fluentui/react-field';
+import { FieldBaseState } from '@fluentui/react-field';
+import { FieldContextValues } from '@fluentui/react-field';
+import type { FieldSlots as FieldSlots_2 } from '@fluentui/react-field';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import type { InputBaseProps } from '@fluentui/react-input';
+import { InputBaseState } from '@fluentui/react-input';
+import type { InputSlots as InputSlots_2 } from '@fluentui/react-input';
+import { JSXElement } from '@fluentui/react-utilities';
+import type { LinkBaseProps } from '@fluentui/react-link';
+import { LinkBaseState } from '@fluentui/react-link';
+import type { LinkSlots as LinkSlots_2 } from '@fluentui/react-link';
+import { MessageBarActionsContextValues as MessageBarActionsContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarActionsProps as MessageBarActionsProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarActionsSlots as MessageBarActionsSlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarActionsState as MessageBarActionsState_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBaseProps } from '@fluentui/react-message-bar';
+import { MessageBarBaseState } from '@fluentui/react-message-bar';
+import { MessageBarBodyContextValues as MessageBarBodyContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBodyProps as MessageBarBodyProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarBodySlots as MessageBarBodySlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarBodyState as MessageBarBodyState_2 } from '@fluentui/react-message-bar';
+import { MessageBarContextValue } from '@fluentui/react-message-bar';
+import { MessageBarContextValues as MessageBarContextValues_2 } from '@fluentui/react-message-bar';
+import type { MessageBarIntent } from '@fluentui/react-message-bar';
+import type { MessageBarSlots as MessageBarSlots_2 } from '@fluentui/react-message-bar';
+import type { MessageBarTitleProps as MessageBarTitleProps_2 } from '@fluentui/react-message-bar';
+import type { MessageBarTitleSlots as MessageBarTitleSlots_2 } from '@fluentui/react-message-bar';
+import { MessageBarTitleState as MessageBarTitleState_2 } from '@fluentui/react-message-bar';
+import type { ProgressBarBaseProps } from '@fluentui/react-progress';
+import type { ProgressBarBaseState } from '@fluentui/react-progress';
+import type { ProgressBarSlots as ProgressBarSlots_2 } from '@fluentui/react-progress';
+import type { RadioBaseProps } from '@fluentui/react-radio';
+import { RadioBaseState } from '@fluentui/react-radio';
+import type { RadioGroupBaseProps } from '@fluentui/react-radio';
+import { RadioGroupBaseState } from '@fluentui/react-radio';
+import { RadioGroupContextValues } from '@fluentui/react-radio';
+import type { RadioGroupSlots as RadioGroupSlots_2 } from '@fluentui/react-radio';
+import { RadioOnChangeData } from '@fluentui/react-radio';
+import { RadioSlots as RadioSlots_2 } from '@fluentui/react-radio';
+import type { RatingBaseProps } from '@fluentui/react-rating';
+import { RatingBaseState } from '@fluentui/react-rating';
+import { RatingContextValues } from '@fluentui/react-rating';
+import type { RatingDisplayBaseProps } from '@fluentui/react-rating';
+import { RatingDisplayBaseState } from '@fluentui/react-rating';
+import { RatingDisplayContextValues } from '@fluentui/react-rating';
+import type { RatingDisplaySlots as RatingDisplaySlots_2 } from '@fluentui/react-rating';
+import type { RatingItemBaseProps } from '@fluentui/react-rating';
+import { RatingItemBaseState } from '@fluentui/react-rating';
+import { RatingItemSlots as RatingItemSlots_2 } from '@fluentui/react-rating';
+import type { RatingSlots as RatingSlots_2 } from '@fluentui/react-rating';
+import * as React_2 from 'react';
+import type { SearchBoxBaseProps } from '@fluentui/react-search';
+import { SearchBoxBaseState } from '@fluentui/react-search';
+import type { SearchBoxSlots as SearchBoxSlots_2 } from '@fluentui/react-search';
+import type { SelectBaseProps } from '@fluentui/react-select';
+import { SelectBaseState } from '@fluentui/react-select';
+import type { SelectSlots as SelectSlots_2 } from '@fluentui/react-select';
+import { SkeletonBaseProps } from '@fluentui/react-skeleton';
+import { SkeletonBaseState } from '@fluentui/react-skeleton';
+import { SkeletonContextValues } from '@fluentui/react-skeleton';
+import { SkeletonItemBaseProps } from '@fluentui/react-skeleton';
+import { SkeletonItemBaseState } from '@fluentui/react-skeleton';
+import type { SkeletonItemSlots as SkeletonItemSlots_2 } from '@fluentui/react-skeleton';
+import type { SkeletonSlots as SkeletonSlots_2 } from '@fluentui/react-skeleton';
+import type { SliderBaseProps } from '@fluentui/react-slider';
+import { SliderBaseState } from '@fluentui/react-slider';
+import type { SliderSlots as SliderSlots_2 } from '@fluentui/react-slider';
+import type { Slot } from '@fluentui/react-utilities';
+import type { SpinButtonBaseProps } from '@fluentui/react-spinbutton';
+import { SpinButtonBaseState } from '@fluentui/react-spinbutton';
+import type { SpinButtonSlots as SpinButtonSlots_2 } from '@fluentui/react-spinbutton';
+import type { SpinnerBaseProps } from '@fluentui/react-spinner';
+import { SpinnerBaseState } from '@fluentui/react-spinner';
+import type { SpinnerSlots as SpinnerSlots_2 } from '@fluentui/react-spinner';
+import type { SwitchBaseProps } from '@fluentui/react-switch';
+import { SwitchBaseState } from '@fluentui/react-switch';
+import type { SwitchSlots as SwitchSlots_2 } from '@fluentui/react-switch';
+import type { TabBaseProps } from '@fluentui/react-tabs';
+import { TabBaseState } from '@fluentui/react-tabs';
+import type { TabListBaseProps } from '@fluentui/react-tabs';
+import { TabListBaseState } from '@fluentui/react-tabs';
+import { TabListContextValues } from '@fluentui/react-tabs';
+import type { TabListSlots as TabListSlots_2 } from '@fluentui/react-tabs';
+import { TabSlots } from '@fluentui/react-tabs';
+import { TabValue } from '@fluentui/react-tabs';
+import type { TextareaBaseProps } from '@fluentui/react-textarea';
+import { TextareaBaseState } from '@fluentui/react-textarea';
+import type { TextareaSlots as TextareaSlots_2 } from '@fluentui/react-textarea';
+import type { ToggleButtonBaseProps } from '@fluentui/react-button';
+import type { ToggleButtonBaseState } from '@fluentui/react-button';
+import { useMessageBarBodyContextValues_unstable } from '@fluentui/react-message-bar';
+
+// @public
+export const Accordion: ForwardRefComponent<AccordionProps>;
+
+// @public (undocumented)
+export type AccordionContextValues = AccordionContextValues_2;
+
+// @public
+export const AccordionHeader: ForwardRefComponent<AccordionHeaderProps>;
+
+// @public (undocumented)
+export type AccordionHeaderProps = AccordionHeaderBaseProps;
+
+// @public (undocumented)
+export type AccordionHeaderSlots = AccordionHeaderSlots_2;
+
+// @public (undocumented)
+export type AccordionHeaderState = AccordionHeaderBaseState & {
+    root: {
+        'data-open'?: string;
+        'data-disabled'?: string;
+        'data-expand-icon-position'?: string;
+    };
+};
+
+// @public
+export const AccordionItem: ForwardRefComponent<AccordionItemProps>;
+
+// @public (undocumented)
+export type AccordionItemProps = AccordionItemProps_2;
+
+// @public (undocumented)
+export type AccordionItemSlots = AccordionItemSlots_2;
+
+// @public (undocumented)
+export type AccordionItemState = AccordionItemState_2 & {
+    root: {
+        'data-disabled'?: string;
+        'data-open'?: string;
+    };
+};
+
+// @public
+export const AccordionPanel: ForwardRefComponent<AccordionPanelProps>;
+
+// @public (undocumented)
+export type AccordionPanelProps = AccordionPanelBaseProps;
+
+// @public (undocumented)
+export type AccordionPanelSlots = AccordionPanelSlots_2;
+
+// @public (undocumented)
+export type AccordionPanelState = AccordionPanelBaseState & {
+    root: {
+        'data-open'?: string;
+    };
+};
+
+// @public (undocumented)
+export type AccordionProps = AccordionBaseProps;
+
+// @public (undocumented)
+export type AccordionSlots = AccordionSlots_2;
+
+// @public (undocumented)
+export type AccordionState = AccordionBaseState & {
+    root: {
+        'data-collapsible'?: string;
+        'data-multiple'?: string;
+    };
+};
+
+// @public (undocumented)
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+
+// @public
+export const Avatar: ForwardRefComponent<AvatarProps>;
+
+// @public
+export type AvatarProps = AvatarBaseProps;
+
+// @public
+export type AvatarState = AvatarBaseState;
+
+// @public
+export const Badge: ForwardRefComponent<BadgeProps>;
+
+// @public
+export type BadgeProps = BadgeBaseProps;
+
+// @public
+export type BadgeState = BadgeBaseState & {
+    root: {
+        'data-icon-position'?: 'before' | 'after';
+    };
+};
+
+// @public
+export const Breadcrumb: ForwardRefComponent<BreadcrumbProps>;
+
+// @public
+export const BreadcrumbButton: ForwardRefComponent<BreadcrumbButtonProps>;
+
+// @public
+export type BreadcrumbButtonProps = BreadcrumbButtonBaseProps;
+
+// @public
+export type BreadcrumbButtonSlots = BreadcrumbButtonSlots_2;
+
+// @public
+export type BreadcrumbButtonState = BreadcrumbButtonBaseState & {
+    root: {
+        'data-current'?: string;
+    };
+};
+
+// @public
+export type BreadcrumbContextValues = BreadcrumbContextValues_2;
+
+// @public
+export const BreadcrumbDivider: ForwardRefComponent<BreadcrumbDividerProps>;
+
+// @public
+export type BreadcrumbDividerProps = BreadcrumbDividerBaseProps;
+
+// @public
+export type BreadcrumbDividerSlots = BreadcrumbDividerSlots_2;
+
+// @public
+export type BreadcrumbDividerState = BreadcrumbDividerBaseState;
+
+// @public
+export const BreadcrumbItem: ForwardRefComponent<BreadcrumbItemProps>;
+
+// @public
+export type BreadcrumbItemProps = BreadcrumbItemBaseProps;
+
+// @public
+export type BreadcrumbItemSlots = BreadcrumbItemSlots_2;
+
+// @public
+export type BreadcrumbItemState = BreadcrumbItemBaseState;
+
+// @public
+export type BreadcrumbProps = BreadcrumbBaseProps;
+
+// @public
+export type BreadcrumbSlots = BreadcrumbSlots_2;
+
+// @public
+export type BreadcrumbState = BreadcrumbBaseState;
+
+// @public
+export const Button: ForwardRefComponent<ButtonProps>;
+
+// @public
+export type ButtonProps = ButtonBaseProps;
+
+// @public
+export type ButtonSlots = ButtonSlots_2;
+
+// @public
+export type ButtonState = ButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-icon-only'?: string;
+    };
+};
+
+// @public
+export const Checkbox: ForwardRefComponent<CheckboxProps>;
+
+// @public
+export type CheckboxProps = CheckboxBaseProps;
+
+// @public (undocumented)
+export type CheckboxSlots = CheckboxSlots_2;
+
+// @public
+export type CheckboxState = CheckboxBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const Divider: ForwardRefComponent<DividerProps>;
+
+// @public (undocumented)
+export type DividerProps = DividerBaseProps;
+
+// @public (undocumented)
+export type DividerSlots = DividerSlots_2;
+
+// @public (undocumented)
+export type DividerState = DividerBaseState & {
+    root: {
+        'data-orientation'?: 'vertical' | 'horizontal';
+    };
+};
+
+// @public
+export const Field: ForwardRefComponent<FieldProps>;
+
+// @public
+export type FieldProps = FieldBaseProps;
+
+// @public
+export type FieldSlots = FieldSlots_2;
+
+// @public
+export type FieldState = FieldBaseState & {
+    root: {
+        'data-validate-state'?: FieldBaseState['validationState'];
+    };
+};
+
+// @public
+export const Input: ForwardRefComponent<InputProps>;
+
+// @public
+export type InputProps = InputBaseProps;
+
+// @public
+export type InputSlots = InputSlots_2;
+
+// @public
+export type InputState = InputBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Link: ForwardRefComponent<LinkProps>;
+
+// @public
+export type LinkProps = LinkBaseProps;
+
+// @public
+export type LinkSlots = LinkSlots_2;
+
+// @public
+export type LinkState = LinkBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+    };
+};
+
+// @public
+export const MessageBar: ForwardRefComponent<MessageBarProps>;
+
+// @public
+export const MessageBarActions: ForwardRefComponent<MessageBarActionsProps>;
+
+// @public (undocumented)
+export type MessageBarActionsContextValues = MessageBarActionsContextValues_2;
+
+// @public (undocumented)
+export type MessageBarActionsProps = MessageBarActionsProps_2;
+
+// @public (undocumented)
+export type MessageBarActionsSlots = MessageBarActionsSlots_2;
+
+// @public (undocumented)
+export type MessageBarActionsState = MessageBarActionsState_2 & {
+    root: {
+        'data-layout'?: string;
+        'data-has-actions'?: string;
+    };
+};
+
+// @public
+export const MessageBarBody: ForwardRefComponent<MessageBarBodyProps>;
+
+// @public (undocumented)
+export type MessageBarBodyContextValues = MessageBarBodyContextValues_2;
+
+// @public (undocumented)
+export type MessageBarBodyProps = MessageBarBodyProps_2;
+
+// @public (undocumented)
+export type MessageBarBodySlots = MessageBarBodySlots_2;
+
+// @public (undocumented)
+export type MessageBarBodyState = MessageBarBodyState_2;
+
+// @public (undocumented)
+export type MessageBarContextValues = MessageBarContextValues_2;
+
+export { MessageBarIntent }
+
+// @public (undocumented)
+export type MessageBarProps = MessageBarBaseProps;
+
+// @public (undocumented)
+export type MessageBarSlots = MessageBarSlots_2;
+
+// @public (undocumented)
+export type MessageBarState = MessageBarBaseState & {
+    root: {
+        'data-layout'?: string;
+        'data-intent'?: string;
+    };
+};
+
+// @public
+export const MessageBarTitle: ForwardRefComponent<MessageBarTitleProps>;
+
+// @public (undocumented)
+export type MessageBarTitleProps = MessageBarTitleProps_2;
+
+// @public (undocumented)
+export type MessageBarTitleSlots = MessageBarTitleSlots_2;
+
+// @public (undocumented)
+export type MessageBarTitleState = MessageBarTitleState_2;
+
+// @public
+export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
+    open: boolean;
+};
+
+// @public
+export type OpenPopoverEvents = MouseEvent | TouchEvent | React_2.FocusEvent<HTMLElement> | React_2.KeyboardEvent<HTMLElement> | React_2.MouseEvent<HTMLElement>;
+
+// @public
+export const Popover: {
+    (props: PopoverProps): JSXElement;
+    displayName: string;
+};
+
+// @public
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+    positioning: {
+        targetRef: React_2.RefCallback<HTMLElement>;
+        containerRef: React_2.RefCallback<HTMLElement>;
+    };
+};
+
+// @public
+export type PopoverProps = {
+    children: [JSXElement, JSXElement] | JSXElement;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: EventHandler<OnOpenChangeData>;
+    openOnHover?: boolean;
+    openOnContext?: boolean;
+    mouseLeaveDelay?: number;
+    positioning?: PositioningShorthand;
+    withArrow?: boolean;
+    disableAutoFocus?: boolean;
+    closeOnScroll?: boolean;
+    closeOnIframeFocus?: boolean;
+    inline?: boolean;
+    mountNode?: HTMLElement | null;
+};
+
+// @public
+export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
+    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
+    toggleOpen: (e: OpenPopoverEvents) => void;
+    triggerRef: React_2.RefObject<HTMLElement | null>;
+    contentRef: React_2.RefObject<HTMLElement | null>;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    popoverTrigger: React_2.ReactElement | undefined;
+    popoverSurface: React_2.ReactElement | undefined;
+    contextTarget: {
+        x: number;
+        y: number;
+    } | undefined;
+    setContextTarget: (target: {
+        x: number;
+        y: number;
+    } | undefined) => void;
+    positioning: PositioningReturn;
+};
+
+// @public
+export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps>;
+
+// @public (undocumented)
+export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
+
+// @public
+export type PopoverSurfaceSlots = {
+    root: Slot<'div'>;
+};
+
+// @public (undocumented)
+export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
+    inline: boolean;
+    withArrow: boolean | undefined;
+    arrowRef: React_2.RefObject<HTMLDivElement | null>;
+    mountNode: HTMLElement | null | undefined;
+    'data-open': string;
+};
+
+// @public
+export const PopoverTrigger: React_2.FC<PopoverTriggerProps>;
+
+// @public
+export type PopoverTriggerProps = {
+    children: React_2.ReactElement;
+    disableButtonEnhancement?: boolean;
+};
+
+// @public
+export type PopoverTriggerState = {
+    children: React_2.ReactElement | null;
+};
+
+// @public (undocumented)
+export type Position = 'above' | 'below' | 'before' | 'after';
+
+// @public
+export type PositioningImperativeRef = {
+    setTarget: (target: HTMLElement | null) => void;
+    updatePosition: () => void;
+};
+
+// @public (undocumented)
+export type PositioningProps = {
+    position?: Position;
+    align?: Alignment;
+    offset?: number | {
+        mainAxis?: number;
+        crossAxis?: number;
+    };
+    fallbackPositions?: PositioningShorthandValue[];
+    coverTarget?: boolean;
+    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+    strategy?: 'absolute' | 'fixed';
+    matchTargetSize?: 'width';
+    pinned?: boolean;
+    positioningRef?: React_2.Ref<PositioningImperativeRef>;
+    overflowBoundary?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+};
+
+// @public (undocumented)
+export type PositioningReturn = {
+    targetRef: React_2.RefCallback<HTMLElement>;
+    containerRef: React_2.RefCallback<HTMLElement>;
+};
+
+// @public (undocumented)
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+// @public (undocumented)
+export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
+
+// @public
+export const ProgressBar: ForwardRefComponent<ProgressBarProps>;
+
+// @public
+export type ProgressBarProps = ProgressBarBaseProps;
+
+// @public (undocumented)
+export type ProgressBarSlots = ProgressBarSlots_2;
+
+// @public
+export type ProgressBarState = ProgressBarBaseState;
+
+// @public
+export const Radio: React_2.ForwardRefExoticComponent<Omit<ComponentProps<Partial<RadioSlots_2>, "input">, "onChange" | "size"> & {
+    value?: string;
+    labelPosition?: "after" | "below";
+    disabled?: boolean;
+    onChange?: (ev: React_2.ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void;
+} & React_2.RefAttributes<HTMLInputElement>>;
+
+// @public
+export const RadioGroup: ForwardRefComponent<RadioGroupProps>;
+
+// @public
+export type RadioGroupProps = RadioGroupBaseProps;
+
+// @public
+export type RadioGroupSlots = RadioGroupSlots_2;
+
+// @public
+export type RadioGroupState = RadioGroupBaseState;
+
+// @public
+export type RadioProps = RadioBaseProps;
+
+// @public
+export type RadioSlots = RadioSlots_2;
+
+// @public
+export type RadioState = RadioBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Rating: ForwardRefComponent<RatingProps>;
+
+// @public
+export const RatingDisplay: ForwardRefComponent<RatingDisplayProps>;
+
+// @public
+export type RatingDisplayProps = RatingDisplayBaseProps;
+
+// @public
+export type RatingDisplaySlots = RatingDisplaySlots_2;
+
+// @public
+export type RatingDisplayState = RatingDisplayBaseState;
+
+// @public
+export const RatingItem: React_2.ForwardRefExoticComponent<Omit<Partial<RatingItemSlots_2>, "root"> & Omit<{
+    as?: "span" | undefined;
+} & Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "children"> & {
+    children?: any;
+}, "ref"> & {
+    value?: number;
+} & React_2.RefAttributes<HTMLSpanElement>>;
+
+// @public
+export type RatingItemProps = RatingItemBaseProps;
+
+// @public
+export type RatingItemSlots = RatingItemSlots_2;
+
+// @public
+export type RatingItemState = RatingItemBaseState & {
+    root: {
+        'data-appearance'?: 'filled' | 'filled-half' | 'outline';
+    };
+};
+
+// @public
+export type RatingProps = RatingBaseProps;
+
+// @public
+export type RatingSlots = RatingSlots_2;
+
+// @public
+export type RatingState = RatingBaseState;
+
+// @public
+export const renderAccordion: (state: AccordionBaseState, contextValues: AccordionContextValues_2) => JSXElement;
+
+// @public
+export const renderAccordionHeader: (state: AccordionHeaderBaseState, contextValues: AccordionHeaderContextValues) => JSXElement;
+
+// @public
+export const renderAccordionItem: (state: AccordionItemState_2, contextValues: AccordionItemContextValues) => JSXElement;
+
+// @public
+export const renderAccordionPanel: (state: AccordionPanelState) => JSXElement;
+
+// @public
+export const renderAvatar: (state: AvatarBaseState) => JSXElement;
+
+// @public
+export const renderBadge: (state: BadgeBaseState) => JSXElement;
+
+// @public
+export const renderBreadcrumb: (state: BreadcrumbBaseState, contextValues: BreadcrumbContextValues_2) => JSXElement;
+
+// @public
+export const renderBreadcrumbButton: (state: BreadcrumbButtonState) => JSXElement;
+
+// @public
+export const renderBreadcrumbDivider: (state: BreadcrumbDividerBaseState) => JSXElement;
+
+// @public
+export const renderBreadcrumbItem: (state: BreadcrumbItemBaseState) => JSXElement;
+
+// @public
+export const renderButton: (state: ButtonBaseState) => JSXElement;
+
+// @public
+export const renderCheckbox: (state: CheckboxBaseState) => JSXElement;
+
+// @public
+export const renderDivider: (state: DividerBaseState) => JSXElement;
+
+// @public
+export const renderField: (state: FieldBaseState, contextValues: FieldContextValues) => JSXElement;
+
+// @public
+export const renderInput: (state: InputBaseState) => JSXElement;
+
+// @public
+export const renderLink: (state: LinkBaseState) => JSXElement;
+
+// @public
+export const renderMessageBar: (state: MessageBarBaseState, contexts: MessageBarContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarActions: (state: MessageBarActionsState_2, contexts: MessageBarActionsContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarBody: (state: MessageBarBodyState_2, contextValues: MessageBarBodyContextValues_2) => JSXElement;
+
+// @public
+export const renderMessageBarTitle: (state: MessageBarTitleState_2) => JSXElement;
+
+// @public
+export const renderPopover: (state: PopoverState, contextValues: {
+    popover: PopoverContextValue;
+}) => React_2.ReactElement;
+
+// @public
+export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
+
+// @public
+export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
+
+// @public
+export const renderProgressBar: (state: ProgressBarState) => JSXElement;
+
+// @public
+export const renderRadio: (state: RadioBaseState) => JSXElement;
+
+// @public
+export const renderRadioGroup: (state: RadioGroupBaseState, contextValues: RadioGroupContextValues) => JSXElement;
+
+// @public
+export const renderRating: (state: RatingBaseState, contextValues: RatingContextValues) => JSXElement;
+
+// @public
+export const renderRatingDisplay: (state: RatingDisplayBaseState, contextValues: RatingDisplayContextValues) => JSXElement;
+
+// @public
+export const renderRatingItem: (state: RatingItemBaseState) => JSXElement;
+
+// @public
+export const renderSearchBox: (state: SearchBoxBaseState) => JSXElement;
+
+// @public
+export const renderSelect: (state: SelectBaseState) => JSXElement;
+
+// @public
+export const renderSkeleton: (state: SkeletonBaseState, contextValues: SkeletonContextValues) => JSXElement;
+
+// @public
+export const renderSkeletonItem: (state: SkeletonItemBaseState) => JSXElement;
+
+// @public
+export const renderSlider: (state: SliderBaseState) => JSXElement;
+
+// @public
+export const renderSpinButton: (state: SpinButtonBaseState) => JSXElement;
+
+// @public
+export const renderSpinner: (state: SpinnerBaseState) => JSXElement;
+
+// @public
+export const renderSwitch: (state: SwitchBaseState) => JSXElement;
+
+// @public
+export const renderTab: (state: TabBaseState) => JSXElement;
+
+// @public
+export const renderTabList: (state: TabListBaseState, contextValues: TabListContextValues) => JSXElement;
+
+// @public
+export const renderTextarea: (state: TextareaBaseState) => JSXElement;
+
+// @public
+export const renderToggleButton: (state: ButtonBaseState) => JSXElement;
+
+// @public
+export const SearchBox: ForwardRefComponent<SearchBoxProps>;
+
+// @public
+export type SearchBoxProps = SearchBoxBaseProps;
+
+// @public
+export type SearchBoxSlots = SearchBoxSlots_2;
+
+// @public
+export type SearchBoxState = SearchBoxBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-focused'?: string;
+    };
+};
+
+// @public
+export const Select: ForwardRefComponent<SelectProps>;
+
+// @public
+export type SelectProps = SelectBaseProps;
+
+// @public (undocumented)
+export type SelectSlots = SelectSlots_2;
+
+// @public
+export type SelectState = SelectBaseState & {
+    root: {
+        'data-disabled'?: string;
+    };
+};
+
+// @public
+export const Skeleton: React_2.ForwardRefExoticComponent<SkeletonBaseProps & React_2.RefAttributes<HTMLDivElement>>;
+
+// @public
+export const SkeletonItem: React_2.ForwardRefExoticComponent<SkeletonItemBaseProps & React_2.RefAttributes<HTMLDivElement>>;
+
+// @public
+export type SkeletonItemProps = SkeletonItemBaseProps;
+
+// @public
+export type SkeletonItemSlots = SkeletonItemSlots_2;
+
+// @public
+export type SkeletonItemState = SkeletonItemBaseState;
+
+// @public
+export type SkeletonProps = SkeletonBaseProps;
+
+// @public
+export type SkeletonSlots = SkeletonSlots_2;
+
+// @public
+export type SkeletonState = SkeletonBaseState;
+
+// @public
+export const Slider: ForwardRefComponent<SliderProps>;
+
+// @public
+export type SliderProps = SliderBaseProps;
+
+// @public
+export type SliderSlots = SliderSlots_2;
+
+// @public
+export type SliderState = SliderBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-vertical'?: string;
+    };
+};
+
+// @public
+export const SpinButton: ForwardRefComponent<SpinButtonProps>;
+
+// @public
+export type SpinButtonProps = SpinButtonBaseProps;
+
+// @public
+export type SpinButtonSlots = SpinButtonSlots_2;
+
+// @public
+export type SpinButtonState = SpinButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-spin-state'?: string;
+        'data-at-bound'?: string;
+    };
+};
+
+// @public
+export const Spinner: ForwardRefComponent<SpinnerProps>;
+
+// @public
+export type SpinnerProps = SpinnerBaseProps;
+
+// @public
+export type SpinnerSlots = SpinnerSlots_2;
+
+// @public
+export type SpinnerState = SpinnerBaseState & {
+    root: {
+        'data-label-position'?: 'before' | 'after' | 'above' | 'below';
+    };
+};
+
+// @public
+export const Switch: ForwardRefComponent<SwitchProps>;
+
+// @public
+export type SwitchProps = SwitchBaseProps;
+
+// @public
+export type SwitchSlots = SwitchSlots_2;
+
+// @public
+export type SwitchState = SwitchBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const Tab: ForwardRefComponent<TabProps>;
+
+// @public
+export const TabList: ForwardRefComponent<TabListProps>;
+
+// @public
+export type TabListProps = TabListBaseProps;
+
+// @public
+export type TabListSlots = TabListSlots_2;
+
+// @public
+export type TabListState = TabListBaseState & {
+    root: {
+        focusgroup?: string;
+        'data-orientation'?: 'vertical' | 'horizontal';
+    };
+};
+
+// @public (undocumented)
+export type TabProps = TabBaseProps;
+
+export { TabSlots }
+
+// @public (undocumented)
+export type TabState = TabBaseState & {
+    root: {
+        focusgroupstart?: string;
+        'data-icon-only'?: string;
+        'data-selected'?: string;
+    };
+};
+
+export { TabValue }
+
+// @public
+export const Textarea: ForwardRefComponent<TextareaProps>;
+
+// @public
+export type TextareaProps = TextareaBaseProps;
+
+// @public
+export type TextareaSlots = TextareaSlots_2;
+
+// @public
+export type TextareaState = TextareaBaseState;
+
+// @public
+export const ToggleButton: ForwardRefComponent<ToggleButtonProps>;
+
+// @public
+export type ToggleButtonProps = ToggleButtonBaseProps;
+
+// @public
+export type ToggleButtonSlots = ButtonSlots;
+
+// @public
+export type ToggleButtonState = ToggleButtonBaseState & {
+    root: {
+        'data-disabled'?: string;
+        'data-disabled-focusable'?: string;
+        'data-icon-only'?: string;
+        'data-checked'?: string;
+    };
+};
+
+// @public
+export const useAccordion: (props: AccordionProps, ref: React_2.Ref<HTMLElement>) => AccordionState;
+
+// @public
+export const useAccordionContext: <T>(selector: ContextSelector<AccordionContextValue, T>) => T;
+
+// @public
+export const useAccordionContextValues: (state: AccordionState) => AccordionContextValues;
+
+// @public
+export const useAccordionHeader: (props: AccordionHeaderProps, ref: React_2.Ref<HTMLElement>) => AccordionHeaderState;
+
+// @public
+export const useAccordionItem: (props: AccordionItemProps, ref: React_2.Ref<HTMLElement>) => AccordionItemState;
+
+// @public
+export const useAccordionPanel: (props: AccordionPanelProps, ref: React_2.Ref<HTMLElement>) => AccordionPanelState;
+
+// @public
+export const useAvatar: (props: AvatarProps, ref: React_2.Ref<HTMLElement>) => AvatarState;
+
+// @public
+export const useBadge: (props: BadgeProps, ref: React_2.Ref<HTMLDivElement>) => BadgeState;
+
+// @public
+export const useBreadcrumb: (props: BreadcrumbProps, ref: React_2.Ref<HTMLElement>) => BreadcrumbState;
+
+// @public
+export const useBreadcrumbButton: (props: BreadcrumbButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => BreadcrumbButtonState;
+
+// @public
+export const useBreadcrumbContext: () => BreadcrumbContextValues_2;
+
+// @public
+export const useBreadcrumbContextValues: (state: BreadcrumbState) => BreadcrumbContextValues;
+
+// @public
+export const useBreadcrumbDivider: (props: BreadcrumbDividerProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbDividerState;
+
+// @public
+export const useBreadcrumbItem: (props: BreadcrumbItemProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbItemState;
+
+// @public
+export const useButton: (props: ButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
+
+// @public
+export const useCheckbox: (props: CheckboxProps, ref: React_2.Ref<HTMLInputElement>) => CheckboxState;
+
+// @public
+export const useDivider: (props: DividerProps, ref: React_2.Ref<HTMLElement>) => DividerState;
+
+// @public
+export const useField: (props: FieldProps, ref: React_2.Ref<HTMLDivElement>) => FieldState;
+
+// @public
+export const useInput: (props: InputProps, ref: React_2.Ref<HTMLInputElement>) => InputState;
+
+// @public
+export const useLink: (props: LinkProps, ref: React_2.Ref<HTMLElement>) => LinkState;
+
+// @public
+export const useMessageBar: (props: MessageBarProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarState;
+
+// @public
+export const useMessageBarActions: (props: MessageBarActionsProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarActionsState;
+
+// @public
+export const useMessageBarActionsContextValues: () => MessageBarActionsContextValues;
+
+// @public
+export const useMessageBarBody: (props: MessageBarBodyProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarBodyState;
+
+// @public
+export const useMessageBarBodyContextValues: typeof useMessageBarBodyContextValues_unstable;
+
+// @public
+export const useMessageBarContext: () => MessageBarContextValue;
+
+// @public
+export const useMessageBarContextValues: (state: MessageBarState) => MessageBarContextValues;
+
+// @public
+export const useMessageBarTitle: (props: MessageBarTitleProps, ref: React_2.Ref<HTMLElement>) => MessageBarTitleState;
+
+// @public
+export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
+
+// @public
+export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
+
+// @public (undocumented)
+export const usePopoverContextValues: (state: PopoverState) => {
+    popover: PopoverContextValue;
+};
+
+// @public
+export const usePopoverSurface: (props: PopoverSurfaceProps, ref: React_2.Ref<HTMLDivElement>) => PopoverSurfaceState;
+
+// @public
+export const usePopoverTrigger: (props: PopoverTriggerProps) => PopoverTriggerState;
+
+// @public
+export const useProgressBar: (props: ProgressBarProps, ref: React_2.Ref<HTMLDivElement>) => ProgressBarState;
+
+// @public
+export const useRadio: (props: RadioProps, ref: React_2.Ref<HTMLInputElement>) => RadioState;
+
+// @public
+export const useRadioGroup: (props: RadioGroupProps, ref: React_2.Ref<HTMLDivElement>) => RadioGroupState;
+
+// @public
+export const useRating: (props: RatingProps, ref: React_2.Ref<HTMLDivElement>) => RatingState;
+
+// @public
+export const useRatingDisplay: (props: RatingDisplayProps, ref: React_2.Ref<HTMLDivElement>) => RatingDisplayState;
+
+// @public
+export const useRatingItem: (props: RatingItemProps, ref: React_2.Ref<HTMLSpanElement>) => RatingItemState;
+
+// @public
+export const useSearchBox: (props: SearchBoxProps, ref: React_2.Ref<HTMLInputElement>) => SearchBoxState;
+
+// @public
+export const useSelect: (props: SelectProps, ref: React_2.Ref<HTMLSelectElement>) => SelectState;
+
+// @public
+export const useSkeleton: (props: SkeletonProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonState;
+
+// @public
+export const useSkeletonItem: (props: SkeletonItemProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonItemState;
+
+// @public
+export const useSlider: (props: SliderProps, ref: React_2.Ref<HTMLInputElement>) => SliderState;
+
+// @public
+export const useSpinButton: (props: SpinButtonProps, ref: React_2.Ref<HTMLInputElement>) => SpinButtonState;
+
+// @public
+export const useSpinner: (props: SpinnerProps, ref: React_2.Ref<HTMLElement>) => SpinnerState;
+
+// @public
+export const useSwitch: (props: SwitchProps, ref: React_2.Ref<HTMLInputElement>) => SwitchState;
+
+// @public
+export const useTab: (props: TabProps, ref: React_2.Ref<HTMLElement>) => TabState;
+
+// @public
+export const useTabList: (props: TabListProps, ref: React_2.Ref<HTMLElement>) => TabListState;
+
+// @public
+export const useTextarea: (props: TextareaProps, ref: React_2.Ref<HTMLTextAreaElement>) => TextareaState;
+
+// @public
+export const useToggleButton: (props: ToggleButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ToggleButtonState;
+
+>>>>>>> 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
 // (No @packageDocumentation comment for this package)
 
 ```
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
index e94ce6adff9dfe..546a8ce5aeb965 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.cy.tsx
@@ -12,7 +12,6 @@ const mount = (element: JSXElement) => {
 
 const popoverTriggerSelector = '[aria-expanded]';
 const popoverContentSelector = '[role="group"]';
-const popoverDialogContentSelector = '[role="dialog"]';
 
 describe('Popover', () => {
   ['uncontrolled', 'controlled'].forEach(scenario => {
@@ -118,19 +117,6 @@ describe('Popover', () => {
       cy.get(popoverTriggerSelector).should('have.attr', 'aria-haspopup', 'true');
     });
 
-    it('should set aria-haspopup="dialog" with trapFocus', () => {
-      mount(
-        <Popover trapFocus>
-          <PopoverTrigger disableButtonEnhancement>
-            <button>Trigger</button>
-          </PopoverTrigger>
-          <PopoverSurface>Content</PopoverSurface>
-        </Popover>,
-      );
-
-      cy.get(popoverTriggerSelector).should('have.attr', 'aria-haspopup', 'dialog');
-    });
-
     it('should set role="group" on surface by default', () => {
       mount(
         <Popover>
@@ -144,20 +130,6 @@ describe('Popover', () => {
       cy.get(popoverTriggerSelector).click();
       cy.get(popoverContentSelector).should('exist');
     });
-
-    it('should set role="dialog" and aria-modal with trapFocus', () => {
-      mount(
-        <Popover trapFocus>
-          <PopoverTrigger disableButtonEnhancement>
-            <button>Trigger</button>
-          </PopoverTrigger>
-          <PopoverSurface>Content</PopoverSurface>
-        </Popover>,
-      );
-
-      cy.get(popoverTriggerSelector).click();
-      cy.get(popoverDialogContentSelector).should('have.attr', 'aria-modal', 'true');
-    });
   });
 
   describe('data-* attributes', () => {
@@ -294,7 +266,7 @@ describe('Popover', () => {
   describe('Nested', () => {
     const PopoverL1 = () => {
       return (
-        <Popover trapFocus>
+        <Popover>
           <PopoverTrigger disableButtonEnhancement>
             <button>First nested trigger</button>
           </PopoverTrigger>
@@ -309,7 +281,7 @@ describe('Popover', () => {
 
     const PopoverL2 = () => {
       return (
-        <Popover trapFocus>
+        <Popover>
           <PopoverTrigger disableButtonEnhancement>
             <button>Second nested trigger</button>
           </PopoverTrigger>
@@ -322,7 +294,7 @@ describe('Popover', () => {
 
     const Example = () => {
       return (
-        <Popover trapFocus>
+        <Popover>
           <PopoverTrigger disableButtonEnhancement>
             <button>Root trigger</button>
           </PopoverTrigger>
@@ -360,11 +332,11 @@ describe('Popover', () => {
     });
 
     it('should dismiss all nested popovers on outside click', () => {
-      cy.get('body').click('bottomRight').get(popoverDialogContentSelector).should('not.exist');
+      cy.get('body').click('bottomRight').get(popoverContentSelector).should('not.exist');
     });
 
     it('should not dismiss when clicking on nested content', () => {
-      cy.contains('Second nested button').click().get(popoverDialogContentSelector).should('have.length', 3);
+      cy.contains('Second nested button').click().get(popoverContentSelector).should('have.length', 3);
     });
 
     it('should dismiss child popovers when clicking on parents', () => {
@@ -374,11 +346,11 @@ describe('Popover', () => {
       // spatial layout.
       cy.contains('First nested button')
         .click({ force: true })
-        .get(popoverDialogContentSelector)
+        .get(popoverContentSelector)
         .should('have.length', 2)
         .contains('Root button')
         .click({ force: true })
-        .get(popoverDialogContentSelector)
+        .get(popoverContentSelector)
         .should('have.length', 1);
     });
 
@@ -392,22 +364,22 @@ describe('Popover', () => {
       cy.get(secondNestedTriggerSelector)
         .eq(1)
         .click({ force: true })
-        .get(popoverDialogContentSelector)
+        .get(popoverContentSelector)
         .should('have.length', 3)
         .get(secondNestedTriggerSelector)
         .eq(0)
         .click({ force: true })
-        .get(popoverDialogContentSelector)
+        .get(popoverContentSelector)
         .should('have.length', 3);
     });
 
     it('should dismiss each popover in the stack with Escape keydown', () => {
       cy.focused().realPress('Escape');
-      cy.get(popoverDialogContentSelector).should('have.length', 2);
+      cy.get(popoverContentSelector).should('have.length', 2);
       cy.focused().realPress('Escape');
-      cy.get(popoverDialogContentSelector).should('have.length', 1);
+      cy.get(popoverContentSelector).should('have.length', 1);
       cy.focused().realPress('Escape');
-      cy.get(popoverDialogContentSelector).should('not.exist');
+      cy.get(popoverContentSelector).should('not.exist');
     });
   });
 
@@ -495,51 +467,6 @@ describe('Popover', () => {
     });
   });
 
-  describe('focus trap', () => {
-    it('Tab should cycle within the surface', () => {
-      mount(
-        <Popover trapFocus>
-          <PopoverTrigger disableButtonEnhancement>
-            <button>Popover trigger</button>
-          </PopoverTrigger>
-          <PopoverSurface>
-            <button>One</button>
-            <button>Two</button>
-          </PopoverSurface>
-        </Popover>,
-      );
-
-      cy.get(popoverTriggerSelector).focus().realPress('Enter');
-
-      cy.contains('One').should('have.focus').realPress('Tab');
-      cy.contains('Two').should('have.focus').realPress('Tab');
-      cy.contains('One').should('have.focus').realPress(['Shift', 'Tab']);
-      cy.contains('Two').should('have.focus');
-    });
-
-    it('should focus on PopoverSurface when its tabIndex is a number', () => {
-      mount(
-        <Popover trapFocus>
-          <PopoverTrigger disableButtonEnhancement>
-            <button>Popover trigger</button>
-          </PopoverTrigger>
-          <PopoverSurface tabIndex={-1} id="popover-surface">
-            <button>One</button>
-            <button>Two</button>
-          </PopoverSurface>
-        </Popover>,
-      );
-
-      cy.get(popoverTriggerSelector).focus().realPress('Enter');
-
-      cy.get('#popover-surface').should('have.focus').realPress('Tab');
-      cy.contains('One').should('have.focus').realPress('Tab');
-      cy.contains('Two').should('have.focus').realPress('Tab');
-      cy.contains('One').should('have.focus').realPress(['Shift', 'Tab']);
-      cy.contains('Two').should('have.focus');
-    });
-  });
-
   describe('Focus restoration', () => {
     it('should restore focus to trigger on close', () => {
       mount(
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
index 95ea877c0f663a..267442889a32b6 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx
@@ -150,21 +150,7 @@ describe('Popover', () => {
     expect(getByText('Trigger')).toHaveAttribute('data-open');
   });
 
-  it('sets role="dialog" and aria-modal on surface when trapFocus', () => {
-    const { getByRole } = render(
-      <Popover defaultOpen trapFocus>
-        <PopoverTrigger>
-          <button>Trigger</button>
-        </PopoverTrigger>
-        <PopoverSurface>Surface</PopoverSurface>
-      </Popover>,
-    );
-
-    const surface = getByRole('dialog');
-    expect(surface).toHaveAttribute('aria-modal', 'true');
-  });
-
-  it('sets role="group" on surface when no trapFocus', () => {
+  it('sets role="group" on surface', () => {
     const { getByRole } = render(
       <Popover defaultOpen>
         <PopoverTrigger>
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
index 8113ab8171f688..31bbe9baa36430 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
@@ -78,12 +78,6 @@ export type PopoverProps = {
    */
   withArrow?: boolean;
 
-  /**
-   * Enable focus trap.
-   * @default false
-   */
-  trapFocus?: boolean;
-
   /**
    * By default Popover focuses the first focusable element in `PopoverSurface` on open.
    * Set this to prevent that behavior.
@@ -125,7 +119,7 @@ export type PopoverProps = {
 export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> &
   Pick<
     PopoverProps,
-    'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'
+    'onOpenChange' | 'openOnContext' | 'openOnHover' | 'withArrow' | 'disableAutoFocus' | 'mountNode'
   > & {
     setOpen: (e: OpenPopoverEvents, open: boolean) => void;
     toggleOpen: (e: OpenPopoverEvents) => void;
@@ -188,7 +182,6 @@ export type PopoverContextValue = Pick<
   | 'arrowRef'
   | 'openOnHover'
   | 'openOnContext'
-  | 'trapFocus'
   | 'disableAutoFocus'
   | 'withArrow'
   | 'inline'
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
index 9138c90cece987..1d796981a583a9 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/PopoverSurface.test.tsx
@@ -54,32 +54,6 @@ describe('PopoverSurface', () => {
     expect(getByRole('group')).toBeInTheDocument();
   });
 
-  it('has role="dialog" when trapFocus is enabled', () => {
-    const { getByRole } = render(
-      <Popover defaultOpen trapFocus>
-        <PopoverTrigger>
-          <button>Trigger</button>
-        </PopoverTrigger>
-        <PopoverSurface>Content</PopoverSurface>
-      </Popover>,
-    );
-
-    expect(getByRole('dialog')).toBeInTheDocument();
-  });
-
-  it('has aria-modal="true" when trapFocus is enabled', () => {
-    const { getByRole } = render(
-      <Popover defaultOpen trapFocus>
-        <PopoverTrigger>
-          <button>Trigger</button>
-        </PopoverTrigger>
-        <PopoverSurface>Content</PopoverSurface>
-      </Popover>,
-    );
-
-    expect(getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
-  });
-
   it('has data-open attribute when open', () => {
     const { getByRole } = render(
       <Popover defaultOpen>
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
index 3f445ec06d3041..74a0075ba5e4dd 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
@@ -3,7 +3,6 @@
 import type * as React from 'react';
 import { useMergedRefs, slot, useEventCallback } from '@fluentui/react-utilities';
 import { usePopoverContext } from '../popoverContext';
-import { useFocusScope } from '../../../hooks';
 import { stringifyDataAttribute } from '../../../utils';
 import type { PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.types';
 
@@ -16,31 +15,10 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   const setOpen = usePopoverContext(context => context.setOpen);
   const arrowRef = usePopoverContext(context => context.arrowRef);
   const withArrow = usePopoverContext(context => context.withArrow);
-  const trapFocus = usePopoverContext(context => context.trapFocus);
-  const disableAutoFocus = usePopoverContext(context => context.disableAutoFocus);
   const inline = usePopoverContext(context => context.inline);
   const open = usePopoverContext(context => context.open);
   const mountNode = usePopoverContext(context => context.mountNode);
   const positioningCtx = usePopoverContext(context => context.positioning);
-  const tabIndex = typeof props.tabIndex === 'number' ? props.tabIndex : undefined;
-
-  const onMountAutoFocus = useEventCallback((event: Event) => {
-    if (disableAutoFocus) {
-      event.preventDefault();
-      return;
-    }
-
-    if (tabIndex !== undefined) {
-      event.preventDefault();
-      contentRef.current?.focus({ preventScroll: true });
-    }
-  });
-
-  const focusScope = useFocusScope({
-    trapped: trapFocus,
-    loop: trapFocus,
-    onMountAutoFocus,
-  });
 
   const state: PopoverSurfaceState = {
     inline,
@@ -50,15 +28,8 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
     components: { root: 'div' },
     root: slot.always(
       {
-        ref: useMergedRefs(
-          ref,
-          contentRef,
-          positioningCtx.containerRef,
-          focusScope.containerRef,
-        ) as React.Ref<HTMLDivElement>,
-        role: trapFocus ? 'dialog' : 'group',
-        'aria-modal': trapFocus ? true : undefined,
-        tabIndex: focusScope.containerProps.tabIndex,
+        ref: useMergedRefs(ref, contentRef, positioningCtx.containerRef) as React.Ref<HTMLDivElement>,
+        role: 'group',
         ...props,
         'data-popover-surface': '',
         'data-open': stringifyDataAttribute(open),
@@ -88,11 +59,7 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
     onMouseLeaveOriginal?.(e);
   });
 
-  const focusScopeKeyDown = focusScope.containerProps.onKeyDown;
-
   state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
-    focusScopeKeyDown(e);
-
     if (e.key === 'Escape') {
       const target = e.target as HTMLElement;
       const surface = contentRef.current;
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
index b0fd5feda238d3..0de54cfb1c6ff8 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/PopoverTrigger.test.tsx
@@ -67,19 +67,6 @@ describe('PopoverTrigger', () => {
     expect(getByText('Trigger')).toHaveAttribute('aria-haspopup', 'true');
   });
 
-  it('applies aria-haspopup="dialog" when trapFocus', () => {
-    const { getByText } = render(
-      <Popover trapFocus>
-        <PopoverTrigger>
-          <button>Trigger</button>
-        </PopoverTrigger>
-        <PopoverSurface>Content</PopoverSurface>
-      </Popover>,
-    );
-
-    expect(getByText('Trigger')).toHaveAttribute('aria-haspopup', 'dialog');
-  });
-
   it('applies data-open when popover is open', () => {
     const { getByText } = render(
       <Popover defaultOpen>
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
index eb084b81ef1578..43bf93b33c7888 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverTrigger/usePopoverTrigger.ts
@@ -29,7 +29,6 @@ export const usePopoverTrigger = (props: PopoverTriggerProps): PopoverTriggerSta
   const triggerRef = usePopoverContext(context => context.triggerRef);
   const openOnHover = usePopoverContext(context => context.openOnHover);
   const openOnContext = usePopoverContext(context => context.openOnContext);
-  const trapFocus = usePopoverContext(context => context.trapFocus);
   const positioningCtx = usePopoverContext(context => context.positioning);
 
   const onContextMenu = (e: React.MouseEvent<HTMLElement>) => {
@@ -68,7 +67,7 @@ export const usePopoverTrigger = (props: PopoverTriggerProps): PopoverTriggerSta
 
   const triggerChildProps = {
     'aria-expanded': `${open}` as 'true' | 'false',
-    'aria-haspopup': (trapFocus ? 'dialog' : 'true') as 'dialog' | 'true',
+    'aria-haspopup': 'true' as const,
     'data-open': stringifyDataAttribute(open),
     ...child?.props,
     onMouseEnter: useEventCallback(
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
new file mode 100644
index 00000000000000..14bbafd814b9b7
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
@@ -0,0 +1,11 @@
+export { usePositioning } from './usePositioning';
+export type {
+  Position,
+  Alignment,
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from './usePositioning';
+export { POSITIONS, ALIGNMENTS, getPlacementString, resolvePositioningShorthand } from './usePositioning';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
new file mode 100644
index 00000000000000..082b2365a68b62
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
@@ -0,0 +1,39 @@
+import type { LogicalAlignment, Position } from './types';
+
+export const GAP = 8;
+
+export const POSITIONS = {
+  above: 'above',
+  below: 'below',
+  before: 'before',
+  after: 'after',
+} as const;
+
+export const ALIGNMENTS = {
+  start: 'start',
+  center: 'center',
+  end: 'end',
+} as const;
+
+export const POSITION_AREA_MAP: Record<Position, Record<LogicalAlignment, string>> = {
+  above: {
+    center: 'block-start',
+    start: 'block-start span-inline-end',
+    end: 'block-start span-inline-start',
+  },
+  below: {
+    center: 'block-end',
+    start: 'block-end span-inline-end',
+    end: 'block-end span-inline-start',
+  },
+  before: {
+    center: 'inline-start',
+    start: 'inline-start span-block-end',
+    end: 'inline-start span-block-start',
+  },
+  after: {
+    center: 'inline-end',
+    start: 'inline-end span-block-end',
+    end: 'inline-end span-block-start',
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
new file mode 100644
index 00000000000000..b624fb8c4170a2
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
@@ -0,0 +1,12 @@
+export { usePositioning } from './usePositioning';
+export { getPlacementString, resolvePositioningShorthand } from './utils';
+export { POSITIONS, ALIGNMENTS } from './constants';
+export type {
+  Position,
+  Alignment,
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from './types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
new file mode 100644
index 00000000000000..e7168495805b99
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
@@ -0,0 +1,88 @@
+import type * as React from 'react';
+import type { PositioningProps } from '../../hooks/usePositioning';
+
+export type Position = 'above' | 'below' | 'before' | 'after';
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+export type LogicalAlignment = 'start' | 'center' | 'end';
+
+/**
+ * Imperative API exposed via `PositioningProps.positioningRef`.
+ */
+export type PositioningImperativeRef = {
+  /** Retarget the surface to the given element (or clear the target with `null`). */
+  setTarget: (target: HTMLElement | null) => void;
+  /** Request a position recomputation. With CSS anchor positioning layout is automatic, so this is a no-op on supporting browsers. */
+  updatePosition: () => void;
+};
+
+export type PositioningShorthandValue =
+  | 'above'
+  | 'above-start'
+  | 'above-end'
+  | 'below'
+  | 'below-start'
+  | 'below-end'
+  | 'before'
+  | 'before-start'
+  | 'before-end'
+  | 'after'
+  | 'after-start'
+  | 'after-end';
+
+export type PositioningProps = {
+  /**
+   * @default 'above'
+   */
+  position?: Position;
+  /**
+   * @default 'center'
+   */
+  align?: Alignment;
+  /** Offset from the anchor element */
+  offset?: number | { mainAxis?: number; crossAxis?: number };
+  /**
+   * Fallback placements tried in order when the primary placement would
+   * overflow the viewport. Accepts shorthand strings like `'below-start'`.
+   * When omitted, the default is the native `flip-block, flip-inline`
+   * fallback chain.
+   */
+  fallbackPositions?: PositioningShorthandValue[];
+  /** Position on top of the target */
+  coverTarget?: boolean;
+  /**
+   * Custom anchor element for the positioned surface. When provided, the
+   * anchor-name is written to this element instead of the target assigned via
+   * the returned `targetRef`. Accepts a DOM element or a RefObject.
+   */
+  target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
+  /**
+   * CSS `position` value used on the positioned surface. Matches v9's default.
+   * @default 'absolute'
+   */
+  strategy?: 'absolute' | 'fixed';
+  /**
+   * Makes the surface match one of the trigger's dimensions. Currently only
+   * `'width'` is supported; the surface's `width` is set via CSS
+   * `anchor-size(width)`.
+   */
+  matchTargetSize?: 'width';
+  /**
+   * When true the surface stays at its requested placement even if it overflows
+   * the viewport (no `flip` fallback). Useful for menus or tooltips that must
+   * not switch sides unexpectedly.
+   * @default false
+   */
+  pinned?: boolean;
+  /**
+   * Imperative handle for programmatically retargeting the surface or
+   * triggering a position update. See {@link PositioningImperativeRef}.
+   */
+  positioningRef?: React.Ref<PositioningImperativeRef>;
+};
+
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+export type PositioningReturn = {
+  targetRef: React.RefCallback<HTMLElement>;
+  containerRef: React.RefCallback<HTMLElement>;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
new file mode 100644
index 00000000000000..69320196b42b0a
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
@@ -0,0 +1,110 @@
+'use client';
+
+import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import type { LogicalAlignment, Position } from './types';
+import { ALIGNMENTS, POSITIONS } from './constants';
+import { getPlacementString } from './utils/placement';
+
+const PLACEMENT_TOLERANCE = 2;
+
+const closeTo = (a: number, b: number): boolean => Math.abs(a - b) <= PLACEMENT_TOLERANCE;
+
+function detectPosition(surfaceRect: DOMRect, targetRect: DOMRect): Position | null {
+  if (surfaceRect.bottom <= targetRect.top + PLACEMENT_TOLERANCE) {
+    return POSITIONS.above;
+  }
+
+  if (surfaceRect.top >= targetRect.bottom - PLACEMENT_TOLERANCE) {
+    return POSITIONS.below;
+  }
+
+  if (surfaceRect.right <= targetRect.left + PLACEMENT_TOLERANCE) {
+    return POSITIONS.before;
+  }
+
+  if (surfaceRect.left >= targetRect.right - PLACEMENT_TOLERANCE) {
+    return POSITIONS.after;
+  }
+
+  return null;
+}
+
+function detectAlign(position: Position, surfaceRect: DOMRect, targetRect: DOMRect): LogicalAlignment {
+  const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
+
+  const startAligned = isBlockMain
+    ? closeTo(surfaceRect.left, targetRect.left)
+    : closeTo(surfaceRect.top, targetRect.top);
+
+  if (startAligned) {
+    return ALIGNMENTS.start;
+  }
+
+  const endAligned = isBlockMain
+    ? closeTo(surfaceRect.right, targetRect.right)
+    : closeTo(surfaceRect.bottom, targetRect.bottom);
+
+  if (endAligned) {
+    return ALIGNMENTS.end;
+  }
+
+  return ALIGNMENTS.center;
+}
+
+/**
+ * Pure-observation hook: reads the rendered rects of the surface and anchor
+ * and mirrors the resolved placement into the surface's `data-placement`
+ * attribute. This keeps the attribute in sync with the browser's decision
+ * after native flip fires (scroll, resize, ResizeObserver tick).
+ *
+ */
+export function usePlacementObserver(
+  containerEl: HTMLElement | null,
+  targetEl: HTMLElement | null,
+  targetDocument: Document | undefined,
+  disabled = false,
+): void {
+  useIsomorphicLayoutEffect(() => {
+    if (disabled || !containerEl || !targetEl) {
+      return;
+    }
+
+    const win = targetDocument?.defaultView;
+
+    if (!win) {
+      return;
+    }
+
+    const update = () => {
+      const surfaceRect = containerEl.getBoundingClientRect();
+      const targetRect = targetEl.getBoundingClientRect();
+      const position = detectPosition(surfaceRect, targetRect);
+
+      if (!position) {
+        return;
+      }
+
+      const align = detectAlign(position, surfaceRect, targetRect);
+      const next = getPlacementString(position, align);
+
+      if (containerEl.getAttribute('data-placement') !== next) {
+        containerEl.setAttribute('data-placement', next);
+      }
+    };
+
+    update();
+
+    const ResizeObserverCtor = win.ResizeObserver;
+    const observer = ResizeObserverCtor ? new ResizeObserverCtor(update) : null;
+    observer?.observe(containerEl);
+    observer?.observe(targetEl);
+    win.addEventListener('scroll', update, true);
+    win.addEventListener('resize', update);
+
+    return () => {
+      observer?.disconnect();
+      win.removeEventListener('scroll', update, true);
+      win.removeEventListener('resize', update);
+    };
+  }, [containerEl, targetEl, targetDocument, disabled]);
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
new file mode 100644
index 00000000000000..31018f373c2d63
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
@@ -0,0 +1,159 @@
+import * as React from 'react';
+import { act, render } from '@testing-library/react';
+import { usePositioning } from './usePositioning';
+import { getPlacementString } from './utils/placement';
+import type { PositioningProps, PositioningReturn } from './types';
+
+function mountHook(options: PositioningProps = {}) {
+  const resultRef = React.createRef<{ current: PositioningReturn }>();
+  const Capture = () => {
+    const result = usePositioning(options);
+    (resultRef as unknown as { current: PositioningReturn }).current = result;
+    return null;
+  };
+  render(<Capture />);
+  return resultRef as unknown as { current: PositioningReturn };
+}
+
+describe('usePositioning', () => {
+  it('returns targetRef and containerRef callbacks', () => {
+    const result = mountHook();
+
+    expect(typeof result.current.targetRef).toBe('function');
+    expect(typeof result.current.containerRef).toBe('function');
+  });
+
+  it('targetRef writes anchor-name onto the trigger element', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+
+    act(() => {
+      result.current.targetRef(node);
+    });
+
+    expect(node.style.getPropertyValue('anchor-name')).toMatch(/^--popover-anchor-/);
+  });
+
+  it('containerRef writes position-anchor and position-area matching the props', () => {
+    const result = mountHook({ position: 'below', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
+  });
+
+  it('containerRef writes position: absolute by default and clears the UA inset/margin defaults', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.position).toBe('absolute');
+    expect(node.style.inset).toBe('auto');
+    expect(node.style.margin).toBe('0px');
+  });
+
+  it('containerRef honors strategy: "fixed"', () => {
+    const result = mountHook({ strategy: 'fixed' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.position).toBe('fixed');
+  });
+
+  it('containerRef writes data-placement matching (position, align)', () => {
+    const result = mountHook({ position: 'below', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.getAttribute('data-placement')).toBe('below-start');
+  });
+
+  it('containerRef sets position-try-fallbacks to the three-try flip chain by default', () => {
+    const result = mountHook();
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe(
+      'flip-block, flip-inline, flip-block flip-inline',
+    );
+  });
+
+  it('containerRef uses custom fallbackPositions verbatim when provided', () => {
+    const result = mountHook({ fallbackPositions: ['below-start', 'after'] });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('block-end span-inline-end, inline-end');
+  });
+
+  it('containerRef removes position-try-fallbacks when pinned', () => {
+    const result = mountHook({ pinned: true });
+    const node = document.createElement('div');
+    node.style.setProperty('position-try-fallbacks', 'flip-block');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('');
+  });
+
+  it('containerRef writes cover self-alignment when coverTarget is true', () => {
+    const result = mountHook({ coverTarget: true, position: 'above', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-area')).toBe('center');
+    expect(node.style.getPropertyValue('align-self')).toBe('end');
+    expect(node.style.getPropertyValue('justify-self')).toBe('start');
+  });
+
+  it('containerRef writes place-self: anchor-center for center alignment (crbug 438334710 workaround)', () => {
+    const result = mountHook({ position: 'above', align: 'center' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('place-self')).toBe('anchor-center');
+  });
+
+  it('containerRef does not write place-self for non-center alignments', () => {
+    const result = mountHook({ position: 'above', align: 'start' });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('place-self')).toBe('');
+    expect(node.style.getPropertyValue('justify-self')).toBe('');
+    expect(node.style.getPropertyValue('align-self')).toBe('');
+  });
+
+  it('containerRef writes matchTargetSize width via anchor-size()', () => {
+    const result = mountHook({ matchTargetSize: 'width' });
+    const node = document.createElement('div');
+    const spy = jest.spyOn(node.style, 'setProperty');
+    result.current.containerRef(node);
+
+    expect(spy).toHaveBeenCalledWith('width', 'anchor-size(width)');
+    spy.mockRestore();
+  });
+
+  it('containerRef applies offset as logical margins', () => {
+    const result = mountHook({ position: 'below', offset: { mainAxis: 8, crossAxis: 4 } });
+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.marginBlockStart).toBe('8px');
+    expect(node.style.marginInlineStart).toBe('4px');
+  });
+});
+
+describe('getPlacementString', () => {
+  it('returns the bare position for center alignment', () => {
+    expect(getPlacementString('above', 'center')).toBe('above');
+    expect(getPlacementString('below', 'center')).toBe('below');
+  });
+
+  it('returns position-align for non-center alignments', () => {
+    expect(getPlacementString('above', 'start')).toBe('above-start');
+    expect(getPlacementString('below', 'end')).toBe('below-end');
+    expect(getPlacementString('before', 'start')).toBe('before-start');
+    expect(getPlacementString('after', 'end')).toBe('after-end');
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
new file mode 100644
index 00000000000000..7b4508cb563e71
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
@@ -0,0 +1,142 @@
+'use client';
+
+import * as React from 'react';
+import { useId, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import type { PositioningImperativeRef, PositioningProps, PositioningReturn } from './types';
+import { POSITIONS, ALIGNMENTS, POSITION_AREA_MAP } from './constants';
+import { getPlacementString, normalizeAlign } from './utils/placement';
+import { applyOffset, getCoverSelfAlignment, resolveElementRef, resolveOffset, shorthandToPositionArea } from './utils';
+import { usePlacementObserver } from './usePlacementObserver';
+
+const DEFAULT_FLIP = ['flip-block', 'flip-inline', 'flip-block flip-inline'];
+
+export function usePositioning(options: PositioningProps): PositioningReturn {
+  const {
+    pinned,
+    target: customTarget = null,
+    align: alignInput = ALIGNMENTS.center,
+    position = POSITIONS.above,
+    fallbackPositions = [],
+    offset,
+    coverTarget = false,
+    strategy = 'absolute',
+    matchTargetSize,
+    positioningRef,
+  } = options;
+
+  const align = normalizeAlign(alignInput);
+
+  const { mainAxis, crossAxis } = resolveOffset(offset);
+  const coverAlignment = coverTarget ? getCoverSelfAlignment(position, align) : null;
+
+  const [triggerEl, setTriggerEl] = React.useState<HTMLElement | null>(null);
+  const [containerEl, setContainerEl] = React.useState<HTMLElement | null>(null);
+  const [imperativeTarget, setImperativeTarget] = React.useState<HTMLElement | null>(null);
+  const effectiveTarget = imperativeTarget ?? resolveElementRef(customTarget) ?? triggerEl;
+
+  const anchorName = useId('--popover-anchor-');
+  const positionArea = POSITION_AREA_MAP[position][align];
+  const placement = getPlacementString(position, align);
+
+  const { targetDocument } = useFluent();
+
+  const fallbackAreas = React.useMemo(() => fallbackPositions.map(shorthandToPositionArea), [fallbackPositions]);
+
+  React.useImperativeHandle<PositioningImperativeRef, PositioningImperativeRef>(
+    positioningRef,
+    () => ({
+      setTarget: (el: HTMLElement | null) => {
+        setImperativeTarget(el);
+      },
+      updatePosition: () => undefined,
+    }),
+    [],
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    effectiveTarget?.style.setProperty('anchor-name', anchorName);
+  }, [effectiveTarget, anchorName]);
+
+  const targetRef: React.RefCallback<HTMLElement> = React.useCallback(node => {
+    setTriggerEl(node);
+  }, []);
+
+  const containerRef: React.RefCallback<HTMLElement> = React.useCallback(
+    node => {
+      setContainerEl(node);
+
+      if (!node) {
+        return;
+      }
+
+      node.style.setProperty('position', strategy);
+      node.style.setProperty('inset', 'auto');
+      node.style.setProperty('margin', '0');
+
+      applyOffset(node, position, mainAxis, crossAxis);
+
+      if (matchTargetSize === 'width') {
+        node.style.setProperty('width', 'anchor-size(width)');
+      } else {
+        node.style.removeProperty('width');
+      }
+
+      node.style.setProperty('position-anchor', anchorName);
+      node.setAttribute('data-placement', placement);
+
+      if (coverAlignment) {
+        node.style.setProperty('position-area', 'center');
+        node.style.setProperty('align-self', coverAlignment.alignSelf);
+        node.style.setProperty('justify-self', coverAlignment.justifySelf);
+        node.style.removeProperty('position-try-fallbacks');
+        return;
+      }
+
+      node.style.setProperty('position-area', positionArea);
+
+      /*
+       * Workaround for https://crbug.com/438334710: Chromium (<=130-ish) doesn't
+         apply the implicit `anchor-center` self-alignment that the spec defines
+         for single-keyword `position-area` values (`block-start`, `block-end`,
+    `    inline-start`, `inline-end`) or `span-all`.
+      */
+      if (align === ALIGNMENTS.center) {
+        node.style.setProperty('place-self', 'anchor-center');
+      } else {
+        node.style.removeProperty('place-self');
+        node.style.removeProperty('align-self');
+        node.style.removeProperty('justify-self');
+      }
+
+      if (pinned) {
+        node.style.removeProperty('position-try-fallbacks');
+        return;
+      }
+
+      if (fallbackAreas.length > 0) {
+        node.style.setProperty('position-try-fallbacks', fallbackAreas.join(', '));
+      } else {
+        node.style.setProperty('position-try-fallbacks', DEFAULT_FLIP.join(', '));
+      }
+    },
+    [
+      anchorName,
+      positionArea,
+      placement,
+      fallbackAreas,
+      pinned,
+      position,
+      align,
+      mainAxis,
+      crossAxis,
+      coverAlignment,
+      strategy,
+      matchTargetSize,
+    ],
+  );
+
+  usePlacementObserver(containerEl, effectiveTarget, targetDocument, coverTarget);
+
+  return { targetRef, containerRef };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
new file mode 100644
index 00000000000000..78d00ae45eb4cf
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
@@ -0,0 +1,8 @@
+export { applyOffset, resolveOffset } from './offset';
+export {
+  getCoverSelfAlignment,
+  getPlacementString,
+  resolvePositioningShorthand,
+  shorthandToPositionArea,
+} from './placement';
+export { resolveElementRef } from './resolveElementRef';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
new file mode 100644
index 00000000000000..0661a2bb91f548
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
@@ -0,0 +1,48 @@
+import { POSITIONS } from '../constants';
+import type { Position } from '../types';
+import type { PositioningProps } from '../types';
+
+export function applyOffset(node: HTMLElement, position: Position, mainAxis: number, crossAxis: number): void {
+  if (mainAxis) {
+    switch (position) {
+      case POSITIONS.above:
+        node.style.marginBlockEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.below:
+        node.style.marginBlockStart = `${mainAxis}px`;
+        break;
+      case POSITIONS.before:
+        node.style.marginInlineEnd = `${mainAxis}px`;
+        break;
+      case POSITIONS.after:
+        node.style.marginInlineStart = `${mainAxis}px`;
+        break;
+    }
+  }
+
+  if (crossAxis) {
+    switch (position) {
+      case POSITIONS.above:
+      case POSITIONS.below:
+        node.style.marginInlineStart = `${crossAxis}px`;
+        break;
+      case POSITIONS.before:
+      case POSITIONS.after:
+        node.style.marginBlockStart = `${crossAxis}px`;
+        break;
+    }
+  }
+}
+
+/** Normalises the `offset` prop into explicit `{ mainAxis, crossAxis }`. */
+export function resolveOffset(offset: PositioningProps['offset']): { mainAxis: number; crossAxis: number } {
+  if (typeof offset === 'number') {
+    return { mainAxis: offset, crossAxis: 0 };
+  }
+
+  if (offset) {
+    return { mainAxis: offset.mainAxis ?? 0, crossAxis: offset.crossAxis ?? 0 };
+  }
+
+  return { mainAxis: 0, crossAxis: 0 };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
new file mode 100644
index 00000000000000..cd03b35337be06
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
@@ -0,0 +1,99 @@
+import type {
+  Position,
+  LogicalAlignment,
+  PositioningProps,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from '../types';
+import { ALIGNMENTS, POSITIONS, POSITION_AREA_MAP } from '../constants';
+
+const POSITION_ALIASES: Record<string, Position> = {
+  top: POSITIONS.above,
+  bottom: POSITIONS.below,
+  left: POSITIONS.before,
+  right: POSITIONS.after,
+};
+
+const ALIGN_ALIASES: Record<string, LogicalAlignment> = {
+  top: ALIGNMENTS.start,
+  bottom: ALIGNMENTS.end,
+};
+
+export function normalizePosition(raw: string): Position {
+  if (raw in POSITIONS) {
+    return raw as Position;
+  }
+
+  return POSITION_ALIASES[raw] ?? POSITIONS.above;
+}
+
+export function normalizeAlign(raw: string): LogicalAlignment {
+  if (raw === ALIGNMENTS.start || raw === ALIGNMENTS.center || raw === ALIGNMENTS.end) {
+    return raw;
+  }
+
+  return ALIGN_ALIASES[raw] ?? ALIGNMENTS.center;
+}
+
+/**
+ * Maps (position, align) into the human-readable placement string used for the
+ * `data-placement` attribute. Center alignment renders as the bare position.
+ */
+export function getPlacementString(position: Position, align: LogicalAlignment): string {
+  return align === ALIGNMENTS.center ? position : `${position}-${align}`;
+}
+
+/**
+ * Normalizes a shorthand (string or object) into a full `PositioningProps`.
+ * Strings like `'below-start'` become `{ position: 'below', align: 'start' }`;
+ * objects pass through unchanged.
+ *
+ */
+export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps {
+  if (!value) {
+    return {};
+  }
+
+  if (typeof value !== 'string') {
+    return {
+      ...value,
+      position: value.position !== undefined ? normalizePosition(value.position) : undefined,
+      align: value.align !== undefined ? normalizeAlign(value.align) : undefined,
+    };
+  }
+
+  const dash = value.indexOf('-');
+
+  if (dash === -1) {
+    return { position: normalizePosition(value) };
+  }
+
+  return {
+    position: normalizePosition(value.slice(0, dash)),
+    align: normalizeAlign(value.slice(dash + 1)),
+  };
+}
+
+export function shorthandToPositionArea(shorthand: PositioningShorthandValue): string {
+  const { position = POSITIONS.above, align = ALIGNMENTS.center } = resolvePositioningShorthand(shorthand);
+  return POSITION_AREA_MAP[position][normalizeAlign(align)];
+}
+
+export function getCoverSelfAlignment(
+  position: Position,
+  align: LogicalAlignment,
+): { alignSelf: string; justifySelf: string } {
+  if (position === POSITIONS.above) {
+    return { alignSelf: ALIGNMENTS.end, justifySelf: align };
+  }
+
+  if (position === POSITIONS.below) {
+    return { alignSelf: ALIGNMENTS.start, justifySelf: align };
+  }
+
+  if (position === POSITIONS.before) {
+    return { alignSelf: align, justifySelf: ALIGNMENTS.end };
+  }
+
+  return { alignSelf: align, justifySelf: ALIGNMENTS.start };
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts
new file mode 100644
index 00000000000000..d002f9601823f2
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts
@@ -0,0 +1,15 @@
+import type * as React from 'react';
+
+/**
+ * Normalizes an `HTMLElement | RefObject | null | undefined` to a plain
+ * element (or null). Safe across realms — checks for the `current` property
+ * rather than doing `instanceof HTMLElement`.
+ */
+export function resolveElementRef(
+  source: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined,
+): HTMLElement | null {
+  if (!source) {
+    return null;
+  }
+  return 'current' in source ? source.current : source;
+}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
index b024bd7cedc351..63d5073a3890e4 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
@@ -17,7 +17,6 @@ const popoverContextDefaultValue: PopoverContextValue = {
   arrowRef: { current: null },
   openOnContext: false,
   openOnHover: false,
-  trapFocus: false,
   disableAutoFocus: false,
   withArrow: false,
   inline: false,
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index 65042544ea69e9..c593089dc1900b 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -25,7 +25,6 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     openOnContext = false,
     mouseLeaveDelay = 500,
     withArrow = false,
-    trapFocus = false,
     disableAutoFocus = false,
     closeOnScroll = false,
     closeOnIframeFocus = true,
@@ -158,7 +157,6 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     popoverSurface,
     openOnHover,
     openOnContext,
-    trapFocus,
     withArrow,
     disableAutoFocus,
     inline,
@@ -180,7 +178,6 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
     arrowRef,
     openOnHover,
     openOnContext,
-    trapFocus,
     disableAutoFocus,
     withArrow,
     inline,
@@ -198,7 +195,6 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
       arrowRef,
       openOnHover,
       openOnContext,
-      trapFocus,
       disableAutoFocus,
       withArrow,
       inline,
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
index 081ca84ec54c13..14bbafd814b9b7 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/index.ts
@@ -1,6 +1,4 @@
 export { usePositioning } from './usePositioning';
-export { useFocusScope } from './useFocusScope';
-export type { UseFocusScopeOptions, UseFocusScopeReturn } from './useFocusScope';
 export type {
   Position,
   Alignment,
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
deleted file mode 100644
index 17525f5e44d910..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/useFocusScope.ts
+++ /dev/null
@@ -1,428 +0,0 @@
-'use client';
-
-import * as React from 'react';
-import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
-import { isHTMLElement } from '@fluentui/react-utilities';
-
-const AUTOFOCUS_ON_MOUNT = 'focusScope.autoFocusOnMount';
-const AUTOFOCUS_ON_UNMOUNT = 'focusScope.autoFocusOnUnmount';
-const EVENT_OPTIONS = { bubbles: false, cancelable: true };
-
-export interface UseFocusScopeOptions {
-  /**
-   * When `true`, tabbing from the last item will focus the first tabbable element,
-   * and shift+tab from the first item will focus the last tabbable.
-   * @defaultValue false
-   */
-  loop?: boolean;
-
-  /**
-   * When `true`, focus cannot escape the scope via keyboard, pointer,
-   * or programmatic focus.
-   * @defaultValue false
-   */
-  trapped?: boolean;
-
-  /**
-   * Called when auto-focusing on mount. Call `event.preventDefault()` to cancel.
-   */
-  onMountAutoFocus?: (event: Event) => void;
-
-  /**
-   * Called when auto-focusing on unmount (restoring focus to the previously focused
-   * element). Call `event.preventDefault()` to cancel the restore.
-   */
-  onUnmountAutoFocus?: (event: Event) => void;
-}
-
-export interface UseFocusScopeReturn {
-  /**
-   * Ref callback to attach to the container element.
-   * Can be composed with other refs via `useMergedRefs`.
-   */
-  containerRef: React.RefCallback<HTMLElement>;
-
-  /**
-   * Props to spread onto the container element.
-   * Provides `tabIndex` and `onKeyDown` for keyboard looping.
-   */
-  containerProps: {
-    tabIndex: number;
-    onKeyDown: React.KeyboardEventHandler<HTMLElement>;
-  };
-}
-
-/**
- * Manages focus scoping within a container element.
- *
- * When `trapped` is `true`, focus is kept inside the container — including
- * programmatic focus changes. When `loop` is `true`, tab navigation wraps around
- * from the last tabbable element to the first and vice versa.
- *
- * On mount, focus moves to the first tabbable element inside the container
- * (links excluded). On unmount, focus is restored to the element that was
- * focused before the scope mounted.
- *
- * Nested scopes are supported via a global stack: the outermost scope is paused
- * while an inner scope is active and automatically resumes when the inner scope unmounts.
- *
- * @example
- * ```tsx
- * function Popover({ children }) {
- *   const { containerRef, containerProps } = useFocusScope({ loop: true, trapped: true });
- *   return (
- *     <div ref={containerRef} {...containerProps}>
- *       {children}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useFocusScope(options: UseFocusScopeOptions = {}): UseFocusScopeReturn {
-  const { loop = false, trapped = false, onMountAutoFocus, onUnmountAutoFocus } = options;
-  const { targetDocument } = useFluent();
-  const targetWindow = targetDocument?.defaultView ?? undefined;
-
-  const [container, setContainer] = React.useState<HTMLElement | null>(null);
-
-  // Keep mutable refs so effects always call the latest callback without re-running.
-  const onMountAutoFocusRef = React.useRef(onMountAutoFocus);
-  const onUnmountAutoFocusRef = React.useRef(onUnmountAutoFocus);
-  onMountAutoFocusRef.current = onMountAutoFocus;
-  onUnmountAutoFocusRef.current = onUnmountAutoFocus;
-
-  const lastFocusedElementRef = React.useRef<HTMLElement | null>(null);
-
-  // Stable per-instance object used by the global focusScopesStack to pause/resume.
-  const focusScope = React.useRef({
-    paused: false,
-    pause() {
-      this.paused = true;
-    },
-    resume() {
-      this.paused = false;
-    },
-  }).current;
-
-  // --- Focus trapping ---
-  // Document-level listeners redirect any focus that escapes back into the container.
-  // A MutationObserver re-focuses the container if the focused element is removed from the DOM.
-  React.useEffect(() => {
-    if (!trapped || !container || !targetDocument || !targetWindow) {
-      return;
-    }
-
-    const handleFocusIn = (event: FocusEvent) => {
-      if (focusScope.paused) {
-        return;
-      }
-      const target = event.target as HTMLElement | null;
-      if (container.contains(target)) {
-        lastFocusedElementRef.current = target;
-      } else {
-        focusElement(lastFocusedElementRef.current, targetDocument, { select: true });
-      }
-    };
-
-    const handleFocusOut = (event: FocusEvent) => {
-      if (focusScope.paused) {
-        return;
-      }
-      const relatedTarget = event.relatedTarget as HTMLElement | null;
-      // Null relatedTarget means the browser/app/tab lost focus, or Chrome removed
-      // the focused element. Calling focus() in the Chrome removal case spikes CPU
-      // to 100%, so we let the browser recover on its own.
-      if (relatedTarget === null) {
-        return;
-      }
-      if (!container.contains(relatedTarget)) {
-        focusElement(lastFocusedElementRef.current, targetDocument, { select: true });
-      }
-    };
-
-    // When the focused element is removed from the DOM, Chrome moves focus to
-    // document.body. Re-focus the container to keep the trap intact.
-    const handleMutations = (mutations: MutationRecord[]) => {
-      const active = targetDocument.activeElement as HTMLElement | null;
-      if (active !== targetDocument.body) {
-        return;
-      }
-      for (const mutation of mutations) {
-        if (mutation.removedNodes.length > 0) {
-          focusElement(container, targetDocument);
-        }
-      }
-    };
-
-    targetDocument.addEventListener('focusin', handleFocusIn);
-    targetDocument.addEventListener('focusout', handleFocusOut);
-    const observer = new targetWindow.MutationObserver(handleMutations);
-    observer.observe(container, { childList: true, subtree: true });
-
-    return () => {
-      targetDocument.removeEventListener('focusin', handleFocusIn);
-      targetDocument.removeEventListener('focusout', handleFocusOut);
-      observer.disconnect();
-    };
-  }, [trapped, container, focusScope, targetDocument, targetWindow]);
-
-  // --- Auto-focus on mount / restore focus on unmount ---
-  React.useEffect(() => {
-    if (!container || !targetDocument || !targetWindow) {
-      return;
-    }
-
-    focusScopesStack.add(focusScope);
-    const previouslyFocused = targetDocument.activeElement as HTMLElement | null;
-
-    // Only auto-focus if nothing inside the scope already has focus.
-    if (!container.contains(previouslyFocused)) {
-      // Dispatch a cancellable custom event so consumers can call preventDefault()
-      // to suppress the built-in auto-focus behaviour.
-      const onMount = (e: Event) => onMountAutoFocusRef.current?.(e);
-      const mountEvent = new CustomEvent(AUTOFOCUS_ON_MOUNT, EVENT_OPTIONS);
-      container.addEventListener(AUTOFOCUS_ON_MOUNT, onMount);
-      container.dispatchEvent(mountEvent);
-      container.removeEventListener(AUTOFOCUS_ON_MOUNT, onMount);
-
-      if (!mountEvent.defaultPrevented) {
-        focusFirst(removeLinks(getTabbableCandidates(container, targetDocument)), targetDocument, { select: true });
-        // If no tabbable element accepted focus, fall back to the container itself.
-        if (targetDocument.activeElement === previouslyFocused) {
-          focusElement(container, targetDocument);
-        }
-      }
-    }
-
-    return () => {
-      // Delay to work around a React ≤16 bug where calling focus() during unmount throws:
-      // https://github.com/facebook/react/issues/17894
-      targetWindow.setTimeout(() => {
-        const onUnmount = (e: Event) => onUnmountAutoFocusRef.current?.(e);
-        const unmountEvent = new CustomEvent(AUTOFOCUS_ON_UNMOUNT, EVENT_OPTIONS);
-        container.addEventListener(AUTOFOCUS_ON_UNMOUNT, onUnmount);
-        container.dispatchEvent(unmountEvent);
-        container.removeEventListener(AUTOFOCUS_ON_UNMOUNT, onUnmount);
-
-        if (!unmountEvent.defaultPrevented) {
-          focusElement(previouslyFocused ?? targetDocument.body, targetDocument, { select: true });
-        }
-
-        focusScopesStack.remove(focusScope);
-      }, 0);
-    };
-  }, [container, focusScope, targetDocument, targetWindow]);
-
-  // --- Keyboard looping ---
-  // Intercepts Tab / Shift+Tab at the edges of the scope and wraps focus around.
-  const handleKeyDown = React.useCallback(
-    (event: React.KeyboardEvent<HTMLElement>) => {
-      if (!loop && !trapped) {
-        return;
-      }
-      if (focusScope.paused) {
-        return;
-      }
-
-      const isTab = event.key === 'Tab' && !event.altKey && !event.ctrlKey && !event.metaKey;
-      if (!isTab) {
-        return;
-      }
-
-      const focused = targetDocument?.activeElement as HTMLElement | null;
-      if (!focused) {
-        return;
-      }
-
-      const scopeContainer = event.currentTarget as HTMLElement;
-      const [first, last] = getTabbableEdges(scopeContainer, targetDocument, targetWindow);
-
-      if (!first || !last) {
-        // No tabbable children — block tab from leaving when the container itself is focused.
-        if (focused === scopeContainer) {
-          event.preventDefault();
-        }
-        return;
-      }
-
-      if (!event.shiftKey && focused === last) {
-        event.preventDefault();
-        if (loop) {
-          focusElement(first, targetDocument, { select: true });
-        }
-      } else if (event.shiftKey && focused === first) {
-        event.preventDefault();
-        if (loop) {
-          focusElement(last, targetDocument, { select: true });
-        }
-      }
-    },
-    [focusScope, loop, trapped, targetDocument, targetWindow],
-  );
-
-  const containerRef = React.useCallback((node: HTMLElement | null) => {
-    setContainer(node);
-  }, []);
-
-  return {
-    containerRef,
-    containerProps: {
-      tabIndex: -1,
-      onKeyDown: handleKeyDown,
-    },
-  };
-}
-
-/* ---------------------------------------------------------------------------
- * Internal focus utilities
- * -------------------------------------------------------------------------*/
-
-/**
- * Attempts to focus the first candidate that accepts focus.
- * Stops as soon as `document.activeElement` changes.
- */
-function focusFirst(candidates: HTMLElement[], targetDocument: Document | undefined, { select = false } = {}): void {
-  if (!targetDocument) {
-    return;
-  }
-
-  const prev = targetDocument.activeElement;
-  for (const candidate of candidates) {
-    focusElement(candidate, targetDocument, { select });
-    if (targetDocument.activeElement !== prev) {
-      return;
-    }
-  }
-}
-
-/**
- * Returns the first and last tabbable elements inside `container`.
- */
-function getTabbableEdges(
-  container: HTMLElement,
-  targetDocument?: Document,
-  targetWindow?: Window,
-): [HTMLElement | undefined, HTMLElement | undefined] {
-  const candidates = getTabbableCandidates(container, targetDocument);
-  const first = findVisible(candidates, container, targetWindow);
-  const last = findVisible([...candidates].reverse(), container, targetWindow);
-  return [first, last];
-}
-
-/**
- * Returns all tabbable candidates within `container` in DOM order.
- *
- * This is an approximation — runtime visibility is resolved separately by
- * `findVisible`. Positive `tabIndex` values are intentionally ignored to avoid
- * diverging from visual order, which hinders accessibility.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
- */
-function getTabbableCandidates(container: HTMLElement, targetDocument?: Document): HTMLElement[] {
-  if (!targetDocument) {
-    return [];
-  }
-
-  const nodes: HTMLElement[] = [];
-  const walker = targetDocument.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
-    acceptNode(node: Element) {
-      const el = node as HTMLElement;
-      if (el.tagName === 'INPUT' && (el as HTMLInputElement).type === 'hidden') {
-        return NodeFilter.FILTER_SKIP;
-      }
-      if ((el as HTMLInputElement).disabled || el.hidden) {
-        return NodeFilter.FILTER_SKIP;
-      }
-      return el.tabIndex >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
-    },
-  });
-  while (walker.nextNode()) {
-    nodes.push(walker.currentNode as HTMLElement);
-  }
-  return nodes;
-}
-
-/**
- * Returns the first element in `elements` that is not visually hidden.
- * Visibility is only checked up to (but not including) `container`.
- */
-function findVisible(elements: HTMLElement[], container: HTMLElement, targetWindow?: Window): HTMLElement | undefined {
-  for (const el of elements) {
-    if (!isHidden(el, targetWindow, { upTo: container })) {
-      return el;
-    }
-  }
-}
-
-function isHidden(node: HTMLElement, targetWindow?: Window, { upTo }: { upTo?: HTMLElement } = {}): boolean {
-  if (!targetWindow) {
-    return false;
-  }
-  if (targetWindow.getComputedStyle(node).visibility === 'hidden') {
-    return true;
-  }
-  let current: HTMLElement | null = node;
-  while (current) {
-    if (upTo !== undefined && current === upTo) {
-      return false;
-    }
-    if (targetWindow.getComputedStyle(current).display === 'none') {
-      return true;
-    }
-    current = current.parentElement;
-  }
-  return false;
-}
-
-function focusElement(element?: HTMLElement | null, targetDocument?: Document, { select = false } = {}): void {
-  if (!element?.focus || !targetDocument) {
-    return;
-  }
-  const prev = targetDocument.activeElement;
-  // preventScroll avoids jarring scroll jumps when focus moves programmatically.
-  element.focus({ preventScroll: true });
-  if (element !== prev && isHTMLElement(element, { constructorName: 'HTMLInputElement' }) && select) {
-    element.select();
-  }
-}
-
-/** Excludes anchor elements — links can't be auto-focused on mount without side effects. */
-function removeLinks(items: HTMLElement[]): HTMLElement[] {
-  return items.filter(item => item.tagName !== 'A');
-}
-
-/* ---------------------------------------------------------------------------
- * Focus scope stack
- *
- * Maintains a stack of active focus scopes. When a new scope mounts, the
- * previously active scope is paused. When a scope unmounts, the scope below
- * it in the stack is resumed. This allows nested modals / popovers to work
- * correctly without scopes fighting each other.
- * -------------------------------------------------------------------------*/
-
-type FocusScopeAPI = { paused: boolean; pause(): void; resume(): void };
-
-const focusScopesStack = createFocusScopesStack();
-
-function createFocusScopesStack() {
-  let stack: FocusScopeAPI[] = [];
-
-  return {
-    add(scope: FocusScopeAPI) {
-      // Pause the currently active scope before pushing the new one.
-      const active = stack[0];
-      if (scope !== active) {
-        active?.pause();
-      }
-      // Re-insert at the top in case this scope already exists deeper in the stack.
-      stack = stack.filter(s => s !== scope);
-      stack.unshift(scope);
-    },
-
-    remove(scope: FocusScopeAPI) {
-      stack = stack.filter(s => s !== scope);
-      // Resume the scope that is now at the top of the stack.
-      stack[0]?.resume();
-    },
-  };
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
index 75723c0a97b799..7b4508cb563e71 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.ts
@@ -95,11 +95,11 @@ export function usePositioning(options: PositioningProps): PositioningReturn {
 
       node.style.setProperty('position-area', positionArea);
 
-      /* 
+      /*
        * Workaround for https://crbug.com/438334710: Chromium (<=130-ish) doesn't
          apply the implicit `anchor-center` self-alignment that the spec defines
          for single-keyword `position-area` values (`block-start`, `block-end`,
-    `    inline-start`, `inline-end`) or `span-all`. 
+    `    inline-start`, `inline-end`) or `span-all`.
       */
       if (align === ALIGNMENTS.center) {
         node.style.setProperty('place-self', 'anchor-center');
diff --git a/packages/react-components/react-headless-components-preview/library/src/index.ts b/packages/react-components/react-headless-components-preview/library/src/index.ts
index cb0ff5c3b541f6..f65285b35b0b8c 100644
--- a/packages/react-components/react-headless-components-preview/library/src/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/index.ts
@@ -1 +1,454 @@
+<<<<<<< HEAD
 export {};
+||||||| parent of 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
+export {
+  Accordion,
+  renderAccordion,
+  useAccordion,
+  useAccordionContext,
+  useAccordionContextValues,
+  AccordionHeader,
+  renderAccordionHeader,
+  useAccordionHeader,
+  AccordionItem,
+  renderAccordionItem,
+  useAccordionItem,
+  AccordionPanel,
+  renderAccordionPanel,
+  useAccordionPanel,
+} from './Accordion';
+export type {
+  AccordionSlots,
+  AccordionProps,
+  AccordionState,
+  AccordionContextValues,
+  AccordionHeaderSlots,
+  AccordionHeaderProps,
+  AccordionHeaderState,
+  AccordionItemSlots,
+  AccordionItemProps,
+  AccordionItemState,
+  AccordionPanelSlots,
+  AccordionPanelProps,
+  AccordionPanelState,
+} from './Accordion';
+
+export {
+  MessageBar,
+  renderMessageBar,
+  useMessageBar,
+  useMessageBarContext,
+  useMessageBarContextValues,
+  MessageBarActions,
+  renderMessageBarActions,
+  useMessageBarActions,
+  useMessageBarActionsContextValues,
+  MessageBarBody,
+  renderMessageBarBody,
+  useMessageBarBody,
+  useMessageBarBodyContextValues,
+  MessageBarTitle,
+  renderMessageBarTitle,
+  useMessageBarTitle,
+} from './MessageBar';
+export type {
+  MessageBarSlots,
+  MessageBarProps,
+  MessageBarState,
+  MessageBarContextValues,
+  MessageBarIntent,
+  MessageBarActionsSlots,
+  MessageBarActionsProps,
+  MessageBarActionsState,
+  MessageBarActionsContextValues,
+  MessageBarBodySlots,
+  MessageBarBodyProps,
+  MessageBarBodyState,
+  MessageBarBodyContextValues,
+  MessageBarTitleSlots,
+  MessageBarTitleProps,
+  MessageBarTitleState,
+} from './MessageBar';
+
+export { Avatar, renderAvatar, useAvatar } from './Avatar';
+export type { AvatarProps, AvatarState } from './Avatar';
+
+export { Badge, renderBadge, useBadge } from './Badge';
+export type { BadgeProps, BadgeState } from './Badge';
+
+export {
+  Breadcrumb,
+  renderBreadcrumb,
+  useBreadcrumb,
+  useBreadcrumbContext,
+  useBreadcrumbContextValues,
+  BreadcrumbDivider,
+  renderBreadcrumbDivider,
+  useBreadcrumbDivider,
+  BreadcrumbItem,
+  renderBreadcrumbItem,
+  useBreadcrumbItem,
+  BreadcrumbButton,
+  renderBreadcrumbButton,
+  useBreadcrumbButton,
+} from './Breadcrumb';
+export type {
+  BreadcrumbSlots,
+  BreadcrumbProps,
+  BreadcrumbState,
+  BreadcrumbContextValues,
+  BreadcrumbDividerSlots,
+  BreadcrumbDividerProps,
+  BreadcrumbDividerState,
+  BreadcrumbItemSlots,
+  BreadcrumbItemProps,
+  BreadcrumbItemState,
+  BreadcrumbButtonSlots,
+  BreadcrumbButtonProps,
+  BreadcrumbButtonState,
+} from './Breadcrumb';
+
+export { Button, renderButton, useButton } from './Button';
+export type { ButtonSlots, ButtonProps, ButtonState } from './Button';
+
+export { Checkbox, renderCheckbox, useCheckbox } from './Checkbox';
+export type { CheckboxSlots, CheckboxProps, CheckboxState } from './Checkbox';
+
+export { Divider, renderDivider, useDivider } from './Divider';
+export type { DividerSlots, DividerProps, DividerState } from './Divider';
+
+export { Field, renderField, useField } from './Field';
+export type { FieldSlots, FieldProps, FieldState } from './Field';
+
+export { Input, renderInput, useInput } from './Input';
+export type { InputSlots, InputProps, InputState } from './Input';
+
+export { Link, renderLink, useLink } from './Link';
+export type { LinkSlots, LinkProps, LinkState } from './Link';
+
+export { ProgressBar, renderProgressBar, useProgressBar } from './ProgressBar';
+export type { ProgressBarSlots, ProgressBarProps, ProgressBarState } from './ProgressBar';
+
+export { Radio, renderRadio, useRadio, RadioGroup, renderRadioGroup, useRadioGroup } from './RadioGroup';
+export type {
+  RadioSlots,
+  RadioProps,
+  RadioState,
+  RadioGroupSlots,
+  RadioGroupProps,
+  RadioGroupState,
+} from './RadioGroup';
+
+export { RatingItem, renderRatingItem, useRatingItem, Rating, renderRating, useRating } from './Rating';
+export type {
+  RatingItemSlots,
+  RatingItemProps,
+  RatingItemState,
+  RatingSlots,
+  RatingProps,
+  RatingState,
+} from './Rating';
+
+export { RatingDisplay, renderRatingDisplay, useRatingDisplay } from './RatingDisplay';
+export type { RatingDisplaySlots, RatingDisplayProps, RatingDisplayState } from './RatingDisplay';
+
+export { SearchBox, renderSearchBox, useSearchBox } from './SearchBox';
+export type { SearchBoxSlots, SearchBoxProps, SearchBoxState } from './SearchBox';
+
+export { Select, renderSelect, useSelect } from './Select';
+export type { SelectSlots, SelectProps, SelectState } from './Select';
+
+export { SkeletonItem, renderSkeletonItem, useSkeletonItem, Skeleton, renderSkeleton, useSkeleton } from './Skeleton';
+export type {
+  SkeletonItemSlots,
+  SkeletonItemProps,
+  SkeletonItemState,
+  SkeletonSlots,
+  SkeletonProps,
+  SkeletonState,
+} from './Skeleton';
+
+export { Slider, renderSlider, useSlider } from './Slider';
+export type { SliderSlots, SliderProps, SliderState } from './Slider';
+
+export { SpinButton, renderSpinButton, useSpinButton } from './SpinButton';
+export type { SpinButtonSlots, SpinButtonProps, SpinButtonState } from './SpinButton';
+
+export { Spinner, renderSpinner, useSpinner } from './Spinner';
+export type { SpinnerSlots, SpinnerProps, SpinnerState } from './Spinner';
+
+export { Switch, renderSwitch, useSwitch } from './Switch';
+export type { SwitchSlots, SwitchProps, SwitchState } from './Switch';
+
+export { Tab, renderTab, useTab, TabList, renderTabList, useTabList } from './TabList';
+export type { TabSlots, TabValue, TabProps, TabState, TabListSlots, TabListProps, TabListState } from './TabList';
+
+export { Textarea, renderTextarea, useTextarea } from './Textarea';
+export type { TextareaSlots, TextareaProps, TextareaState } from './Textarea';
+
+export { ToggleButton, renderToggleButton, useToggleButton } from './ToggleButton';
+export type { ToggleButtonSlots, ToggleButtonProps, ToggleButtonState } from './ToggleButton';
+
+export {
+  Popover,
+  renderPopover,
+  usePopover,
+  usePopoverContext,
+  usePopoverContextValues,
+  PopoverTrigger,
+  usePopoverTrigger,
+  renderPopoverTrigger,
+  PopoverSurface,
+  usePopoverSurface,
+  renderPopoverSurface,
+} from './Popover';
+
+export type {
+  PopoverProps,
+  PopoverState,
+  PopoverContextValue,
+  OpenPopoverEvents,
+  OnOpenChangeData,
+  PopoverTriggerProps,
+  PopoverTriggerState,
+  PopoverSurfaceSlots,
+  PopoverSurfaceProps,
+  PopoverSurfaceState,
+} from './Popover';
+
+export type {
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthandValue,
+  PositioningShorthand,
+  PositioningBoundaryPadding,
+  Position,
+  Alignment,
+} from './hooks/usePositioning';
+=======
+export {
+  Accordion,
+  renderAccordion,
+  useAccordion,
+  useAccordionContext,
+  useAccordionContextValues,
+  AccordionHeader,
+  renderAccordionHeader,
+  useAccordionHeader,
+  AccordionItem,
+  renderAccordionItem,
+  useAccordionItem,
+  AccordionPanel,
+  renderAccordionPanel,
+  useAccordionPanel,
+} from './Accordion';
+export type {
+  AccordionSlots,
+  AccordionProps,
+  AccordionState,
+  AccordionContextValues,
+  AccordionHeaderSlots,
+  AccordionHeaderProps,
+  AccordionHeaderState,
+  AccordionItemSlots,
+  AccordionItemProps,
+  AccordionItemState,
+  AccordionPanelSlots,
+  AccordionPanelProps,
+  AccordionPanelState,
+} from './Accordion';
+
+export {
+  MessageBar,
+  renderMessageBar,
+  useMessageBar,
+  useMessageBarContext,
+  useMessageBarContextValues,
+  MessageBarActions,
+  renderMessageBarActions,
+  useMessageBarActions,
+  useMessageBarActionsContextValues,
+  MessageBarBody,
+  renderMessageBarBody,
+  useMessageBarBody,
+  useMessageBarBodyContextValues,
+  MessageBarTitle,
+  renderMessageBarTitle,
+  useMessageBarTitle,
+} from './MessageBar';
+export type {
+  MessageBarSlots,
+  MessageBarProps,
+  MessageBarState,
+  MessageBarContextValues,
+  MessageBarIntent,
+  MessageBarActionsSlots,
+  MessageBarActionsProps,
+  MessageBarActionsState,
+  MessageBarActionsContextValues,
+  MessageBarBodySlots,
+  MessageBarBodyProps,
+  MessageBarBodyState,
+  MessageBarBodyContextValues,
+  MessageBarTitleSlots,
+  MessageBarTitleProps,
+  MessageBarTitleState,
+} from './MessageBar';
+
+export { Avatar, renderAvatar, useAvatar } from './Avatar';
+export type { AvatarProps, AvatarState } from './Avatar';
+
+export { Badge, renderBadge, useBadge } from './Badge';
+export type { BadgeProps, BadgeState } from './Badge';
+
+export {
+  Breadcrumb,
+  renderBreadcrumb,
+  useBreadcrumb,
+  useBreadcrumbContext,
+  useBreadcrumbContextValues,
+  BreadcrumbDivider,
+  renderBreadcrumbDivider,
+  useBreadcrumbDivider,
+  BreadcrumbItem,
+  renderBreadcrumbItem,
+  useBreadcrumbItem,
+  BreadcrumbButton,
+  renderBreadcrumbButton,
+  useBreadcrumbButton,
+} from './Breadcrumb';
+export type {
+  BreadcrumbSlots,
+  BreadcrumbProps,
+  BreadcrumbState,
+  BreadcrumbContextValues,
+  BreadcrumbDividerSlots,
+  BreadcrumbDividerProps,
+  BreadcrumbDividerState,
+  BreadcrumbItemSlots,
+  BreadcrumbItemProps,
+  BreadcrumbItemState,
+  BreadcrumbButtonSlots,
+  BreadcrumbButtonProps,
+  BreadcrumbButtonState,
+} from './Breadcrumb';
+
+export { Button, renderButton, useButton } from './Button';
+export type { ButtonSlots, ButtonProps, ButtonState } from './Button';
+
+export { Checkbox, renderCheckbox, useCheckbox } from './Checkbox';
+export type { CheckboxSlots, CheckboxProps, CheckboxState } from './Checkbox';
+
+export { Divider, renderDivider, useDivider } from './Divider';
+export type { DividerSlots, DividerProps, DividerState } from './Divider';
+
+export { Field, renderField, useField } from './Field';
+export type { FieldSlots, FieldProps, FieldState } from './Field';
+
+export { Input, renderInput, useInput } from './Input';
+export type { InputSlots, InputProps, InputState } from './Input';
+
+export { Link, renderLink, useLink } from './Link';
+export type { LinkSlots, LinkProps, LinkState } from './Link';
+
+export { ProgressBar, renderProgressBar, useProgressBar } from './ProgressBar';
+export type { ProgressBarSlots, ProgressBarProps, ProgressBarState } from './ProgressBar';
+
+export { Radio, renderRadio, useRadio, RadioGroup, renderRadioGroup, useRadioGroup } from './RadioGroup';
+export type {
+  RadioSlots,
+  RadioProps,
+  RadioState,
+  RadioGroupSlots,
+  RadioGroupProps,
+  RadioGroupState,
+} from './RadioGroup';
+
+export { RatingItem, renderRatingItem, useRatingItem, Rating, renderRating, useRating } from './Rating';
+export type {
+  RatingItemSlots,
+  RatingItemProps,
+  RatingItemState,
+  RatingSlots,
+  RatingProps,
+  RatingState,
+} from './Rating';
+
+export { RatingDisplay, renderRatingDisplay, useRatingDisplay } from './RatingDisplay';
+export type { RatingDisplaySlots, RatingDisplayProps, RatingDisplayState } from './RatingDisplay';
+
+export { SearchBox, renderSearchBox, useSearchBox } from './SearchBox';
+export type { SearchBoxSlots, SearchBoxProps, SearchBoxState } from './SearchBox';
+
+export { Select, renderSelect, useSelect } from './Select';
+export type { SelectSlots, SelectProps, SelectState } from './Select';
+
+export { SkeletonItem, renderSkeletonItem, useSkeletonItem, Skeleton, renderSkeleton, useSkeleton } from './Skeleton';
+export type {
+  SkeletonItemSlots,
+  SkeletonItemProps,
+  SkeletonItemState,
+  SkeletonSlots,
+  SkeletonProps,
+  SkeletonState,
+} from './Skeleton';
+
+export { Slider, renderSlider, useSlider } from './Slider';
+export type { SliderSlots, SliderProps, SliderState } from './Slider';
+
+export { SpinButton, renderSpinButton, useSpinButton } from './SpinButton';
+export type { SpinButtonSlots, SpinButtonProps, SpinButtonState } from './SpinButton';
+
+export { Spinner, renderSpinner, useSpinner } from './Spinner';
+export type { SpinnerSlots, SpinnerProps, SpinnerState } from './Spinner';
+
+export { Switch, renderSwitch, useSwitch } from './Switch';
+export type { SwitchSlots, SwitchProps, SwitchState } from './Switch';
+
+export { Tab, renderTab, useTab, TabList, renderTabList, useTabList } from './TabList';
+export type { TabSlots, TabValue, TabProps, TabState, TabListSlots, TabListProps, TabListState } from './TabList';
+
+export { Textarea, renderTextarea, useTextarea } from './Textarea';
+export type { TextareaSlots, TextareaProps, TextareaState } from './Textarea';
+
+export { ToggleButton, renderToggleButton, useToggleButton } from './ToggleButton';
+export type { ToggleButtonSlots, ToggleButtonProps, ToggleButtonState } from './ToggleButton';
+
+export {
+  Popover,
+  renderPopover,
+  usePopover,
+  usePopoverContext,
+  usePopoverContextValues,
+  PopoverTrigger,
+  usePopoverTrigger,
+  renderPopoverTrigger,
+  PopoverSurface,
+  usePopoverSurface,
+  renderPopoverSurface,
+} from './Popover';
+
+export type {
+  PopoverProps,
+  PopoverState,
+  PopoverContextValue,
+  OpenPopoverEvents,
+  OnOpenChangeData,
+  PopoverTriggerProps,
+  PopoverTriggerState,
+  PopoverSurfaceSlots,
+  PopoverSurfaceProps,
+  PopoverSurfaceState,
+} from './Popover';
+
+export type {
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthandValue,
+  PositioningShorthand,
+  Position,
+  Alignment,
+} from './hooks/usePositioning';
+>>>>>>> 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
diff --git a/packages/react-components/react-headless-components-preview/library/src/positioning.ts b/packages/react-components/react-headless-components-preview/library/src/positioning.ts
new file mode 100644
index 00000000000000..e69de29bb2d1d6
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
deleted file mode 100644
index d2c85776b4db98..00000000000000
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSize.stories.tsx
+++ /dev/null
@@ -1,71 +0,0 @@
-import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-
-import descriptionMd from './PositioningAutoSizeDescription.md';
-
-const classes = {
-  outer: 'w-full overflow-auto',
-  wrapper: 'flex flex-col items-start gap-4 mx-16 my-16 w-max',
-  row: 'flex items-center gap-3 text-sm text-gray-700',
-  input: 'w-24 px-2 py-1 border border-gray-300 rounded',
-  checkbox: 'flex items-center gap-2',
-  boundary: 'relative border-2 border-dashed border-red-500 w-[300px] h-[300px] flex flex-col items-center p-2',
-  trigger:
-    'w-[150px] inline-flex justify-center px-3 py-2 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-1 overflow-auto flex flex-col gap-0.5 min-w-[150px]',
-  item: 'px-3 py-1.5 rounded text-sm text-gray-800 hover:bg-gray-100 cursor-default whitespace-nowrap',
-};
-
-export const AutoSize = (): React.ReactNode => {
-  const [open, setOpen] = React.useState(false);
-  const [itemCount, setItemCount] = React.useState(10);
-  const [boundary, setBoundary] = React.useState<HTMLDivElement | null>(null);
-
-  return (
-    <div className={classes.outer}>
-      <div className={classes.wrapper}>
-        <label className={classes.checkbox}>
-          <input type="checkbox" checked={open} onChange={e => setOpen(e.target.checked)} />
-          <span className="text-sm text-gray-700">Open</span>
-        </label>
-        <label className={classes.row}>
-          <span>Menu item count</span>
-          <input
-            type="number"
-            className={classes.input}
-            min={1}
-            value={itemCount}
-            onChange={e => setItemCount(parseInt(e.target.value, 10) || 1)}
-          />
-        </label>
-
-        <div ref={setBoundary} className={classes.boundary}>
-          <Popover
-            open={open}
-            onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'below', overflowBoundary: boundary, strategy: 'absolute' }}
-          >
-            <PopoverTrigger>
-              <button className={classes.trigger}>AutoSized popover</button>
-            </PopoverTrigger>
-            <PopoverSurface className={classes.surface}>
-              {Array.from({ length: itemCount }, (_, i) => (
-                <div key={i} className={classes.item}>
-                  Item {i + 1}
-                </div>
-              ))}
-            </PopoverSurface>
-          </Popover>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-AutoSize.parameters = {
-  docs: {
-    description: {
-      story: descriptionMd,
-    },
-  },
-};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
deleted file mode 100644
index d86f03dd4fb693..00000000000000
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningAutoSizeDescription.md
+++ /dev/null
@@ -1 +0,0 @@
-`autoSize` sets inline `max-width` and `max-height` styles on the surface derived from `overflowBoundary`. As the content grows the surface clips to the boundary and scrolls instead of bursting outside.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
deleted file mode 100644
index be171e7aa0f082..00000000000000
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundary.stories.tsx
+++ /dev/null
@@ -1,71 +0,0 @@
-import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-
-import overflowBoundaryDescriptionMd from './PositioningOverflowBoundaryDescription.md';
-
-const classes = {
-  outer: 'w-full overflow-auto min-h-[400px]',
-  wrapper: 'flex flex-col items-start gap-4 m-16',
-  checkbox: 'flex items-center gap-2 text-sm text-gray-700',
-  boundary:
-    'relative border-2 border-dashed border-red-500 w-[300px] h-[300px] p-5 flex flex-col justify-between items-end box-border',
-  trigger:
-    'w-[150px] px-3 py-2 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  surfaceBase: 'box-border bg-white rounded-lg shadow-lg border border-gray-200 p-3 text-sm',
-  surfaceWider: 'w-[340px]',
-};
-
-export const OverflowBoundary = (): React.ReactNode => {
-  const [open, setOpen] = React.useState(true);
-  const [boundary, setBoundary] = React.useState<HTMLDivElement | null>(null);
-
-  return (
-    <div className={classes.outer}>
-      <div className={classes.wrapper}>
-        <label className={classes.checkbox}>
-          <input type="checkbox" checked={open} onChange={e => setOpen(e.target.checked)} />
-          <span>Open</span>
-        </label>
-
-        <div ref={setBoundary} className={classes.boundary}>
-          <Popover
-            open={open}
-            onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'below', align: 'start', overflowBoundary: boundary }}
-          >
-            <PopoverTrigger>
-              <button className={classes.trigger}>Below</button>
-            </PopoverTrigger>
-            <PopoverSurface className={classes.surfaceBase}>
-              Natural width is 240px. With <code>overflowBoundary</code> set, the hook caps <code>max-inline-size</code>{' '}
-              to the room between the trigger&rsquo;s left edge and the boundary&rsquo;s right edge, so the
-              surface&rsquo;s right edge lands exactly at the boundary.
-            </PopoverSurface>
-          </Popover>
-
-          <Popover
-            open={open}
-            onOpenChange={(_, data) => setOpen(data.open)}
-            positioning={{ position: 'above', align: 'start' }}
-          >
-            <PopoverTrigger>
-              <button className={classes.trigger}>Free</button>
-            </PopoverTrigger>
-            <PopoverSurface className={`${classes.surfaceBase}, ${classes.surfaceWider}`}>
-              No <code>overflowBoundary</code> — the surface keeps its natural 340px width and spills past the dashed
-              rect. Native CSS flip only checks the viewport, not this custom boundary.
-            </PopoverSurface>
-          </Popover>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-OverflowBoundary.parameters = {
-  docs: {
-    description: {
-      story: overflowBoundaryDescriptionMd,
-    },
-  },
-};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
deleted file mode 100644
index e69b51341f943c..00000000000000
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOverflowBoundaryDescription.md
+++ /dev/null
@@ -1 +0,0 @@
-`overflowBoundary` names a rect the positioned surface must stay within. When set, the hook writes logical `max-inline-size` and `max-block-size` on the surface so its far edge can never extend past the boundary — the surface's start edge stays anchored where CSS anchor positioning placed it, and content reflows inside the clamped box. Pair with `overflowBoundaryPadding` to reserve breathing room between the surface and the boundary edges.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
index ebeff1b4a0736b..73e33580a16fc8 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx
@@ -7,8 +7,6 @@ export { Default } from './PositioningDefault.stories';
 export { ShorthandPositions } from './PositioningShorthandPositions.stories';
 export { Offset } from './PositioningOffset.stories';
 export { CoverTarget } from './PositioningCoverTarget.stories';
-export { AutoSize } from './PositioningAutoSize.stories';
-export { OverflowBoundary } from './PositioningOverflowBoundary.stories';
 export { MatchTargetSize } from './PositioningMatchTargetSize.stories';
 export { FallbackPositions } from './PositioningFallbackPositions.stories';
 export { FlippingBlock } from './PositioningFlippingBlock.stories';
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
index d3130e0c12634d..799e0ee6976cb0 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverBestPractices.md
@@ -2,7 +2,6 @@
 
 ### Do
 
-- Use the `trapFocus` prop when focusable elements are in the `Popover`.
 - Create nested `Popover`s as separate components.
 - If there are no interactive items in the `Popover` content, set `tabIndex={-1}` on the `PopoverSurface`.
 - Use `Popover` to reduce screen clutter and host non-essential information.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index 2a6cd345d7ab94..46a63cbcd1ab3f 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -18,7 +18,7 @@ const classes = {
 };
 
 const SecondNestedPopover = (): JSXElement => (
-  <Popover trapFocus>
+  <Popover>
     <PopoverTrigger>
       <button className={classes.deepTrigger}>Second nested trigger</button>
     </PopoverTrigger>
@@ -31,7 +31,7 @@ const SecondNestedPopover = (): JSXElement => (
 );
 
 const FirstNestedPopover = (): JSXElement => (
-  <Popover trapFocus>
+  <Popover>
     <PopoverTrigger>
       <button className={classes.nestedTrigger}>First nested trigger</button>
     </PopoverTrigger>
@@ -47,7 +47,7 @@ const FirstNestedPopover = (): JSXElement => (
 );
 
 export const Nested = (): React.ReactNode => (
-  <Popover trapFocus>
+  <Popover>
     <PopoverTrigger>
       <button className={classes.rootTrigger}>Root trigger</button>
     </PopoverTrigger>
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx
deleted file mode 100644
index 19f5475a87ecd8..00000000000000
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverTrapFocus.stories.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-
-const classes = {
-  trigger:
-    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 max-w-sm',
-  input:
-    'w-full px-3 py-1.5 rounded-md border border-gray-300 text-sm focus:outline-2 focus:outline-blue-500 focus:border-transparent',
-  button:
-    'px-3 py-1.5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
-};
-
-export const TrapFocus = (): React.ReactNode => (
-  <Popover trapFocus>
-    <PopoverTrigger>
-      <button className={classes.trigger}>Open dialog popover</button>
-    </PopoverTrigger>
-    <PopoverSurface className={classes.surface}>
-      <h3 className="text-sm font-semibold text-gray-900 mb-3">Subscribe</h3>
-      <div className="flex flex-col gap-3">
-        <label className="text-sm text-gray-600">
-          Email
-          <input type="email" placeholder="you@example.com" className={classes.input} />
-        </label>
-        <div className="flex justify-end gap-2">
-          <button className={classes.button}>Submit</button>
-        </div>
-      </div>
-      <p className="text-xs text-gray-400 mt-2">Focus is trapped inside this surface. Press Escape to close.</p>
-    </PopoverSurface>
-  </Popover>
-);
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
index cdc4dbea081231..bfb6d197bc4a6f 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
@@ -17,12 +17,7 @@ export const WithoutTrigger = (): React.ReactNode => {
       <button ref={buttonRef} className={classes.trigger} onClick={() => setOpen(value => !value)}>
         Toggle popover
       </button>
-      <Popover
-        open={open}
-        onOpenChange={(_e, data) => setOpen(data.open)}
-        trapFocus
-        positioning={{ target: buttonRef }}
-      >
+      <Popover open={open} onOpenChange={(_e, data) => setOpen(data.open)} positioning={{ target: buttonRef }}>
         <PopoverSurface className={classes.surface}>
           <h3 className="text-sm font-semibold text-gray-900 m-0">Popover content</h3>
           <p className="text-sm text-gray-600">
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
index 62ba4068d3fdb6..8f4aea88130a60 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
@@ -11,7 +11,6 @@ export { OpenOnContext } from './PopoverOpenOnContext.stories';
 export { CustomTrigger } from './PopoverCustomTrigger.stories';
 export { WithoutTrigger } from './PopoverWithoutTrigger.stories';
 export { AnchorToCustomTarget } from './PopoverAnchorToCustomTarget.stories';
-export { TrapFocus } from './PopoverTrapFocus.stories';
 export { Nested } from './PopoverNested.stories';
 export { InternalUpdateContent } from './PopoverInternalUpdateContent.stories';
 export { Inline } from './PopoverInline.stories';

From cdbbfcf4f422de35109737eb810d9108fb7dce62 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 13:04:29 +0200
Subject: [PATCH 08/17] docs(react-headless-components-preview): align Popover
 spec with iteration-1 strip-down

---
 .../library/docs/popover-spec.md              |  117 +-
 .../library/etc/popover.api.md                |   46 +-
 .../library/etc/positioning.api.md            |   76 +
 .../react-headless-components-preview.api.md  | 2328 -----------------
 .../library/package.json                      |   12 +
 .../src/components/Popover/hooks/index.ts     |   11 -
 .../Popover/hooks/usePositioning/constants.ts |   39 -
 .../Popover/hooks/usePositioning/index.ts     |   12 -
 .../Popover/hooks/usePositioning/types.ts     |   88 -
 .../usePositioning/usePlacementObserver.ts    |  110 -
 .../usePositioning/usePositioning.test.tsx    |  159 --
 .../hooks/usePositioning/usePositioning.ts    |  142 -
 .../hooks/usePositioning/utils/index.ts       |    8 -
 .../hooks/usePositioning/utils/offset.ts      |   48 -
 .../hooks/usePositioning/utils/placement.ts   |   99 -
 .../usePositioning/utils/resolveElementRef.ts |   15 -
 .../library/src/index.ts                      |  453 ----
 .../library/src/popover.ts                    |   10 -
 .../library/src/positioning.ts                |   10 +
 19 files changed, 170 insertions(+), 3613 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/library/etc/positioning.api.md
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
 delete mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts

diff --git a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
index e78f77203602f6..b4ff4be6b93055 100644
--- a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
+++ b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
@@ -4,7 +4,7 @@
 
 Popover is an anchored overlay surface that displays transient content (actions, details, confirmations, rich tooltips) next to a trigger element. It composes a trigger (optional if opened programmatically), a surface (the floating content), and an optional arrow. The surface can elevate into the browser's **top layer** via the native HTML Popover API, or render inline in DOM order when `inline={true}`. Placement is computed via the native **CSS Anchor Positioning API** — no JS layout loop.
 
-Popover manages dismissal (click-outside, scroll-outside, Escape, iframe blur), opt-in focus trapping, opt-in hover/context interaction, and keeps `data-placement` in sync with the browser's post-flip decision so consumer CSS can style flipped placements.
+Popover manages dismissal (click-outside, scroll-outside, Escape, iframe blur), opt-in hover/context interaction, and keeps `data-placement` in sync with the browser's post-flip decision so consumer CSS can style flipped placements. Focus trapping is deferred to a later iteration — the surface is currently a non-modal `role="group"`.
 
 ## Composition
 
@@ -34,8 +34,7 @@ Popover is a compound component. `PopoverTrigger` is optional — a surface with
 | `openOnContext`      | `boolean`                                                   | `false`     | Open on the trigger's context-menu event (right-click / Shift+F10). Click and keyboard activation are ignored while on.      |
 | `closeOnScroll`      | `boolean`                                                   | `false`     | Close when the user scrolls anywhere outside the trigger + surface.                                                          |
 | `closeOnIframeFocus` | `boolean`                                                   | `true`      | Close when focus moves into an external iframe. Internal iframes (inside the surface) don't dismiss.                         |
-| `trapFocus`          | `boolean`                                                   | `false`     | Trap Tab/Shift+Tab inside the surface while open. Also switches the surface's ARIA role to `dialog` + `aria-modal="true"`.   |
-| `disableAutoFocus`   | `boolean`                                                   | `false`     | Don't move focus into the surface on open.                                                                                   |
+| `disableAutoFocus`   | `boolean`                                                   | `false`     | Reserved for the upcoming focus-management iteration. Currently inert — the surface no longer auto-focuses on open.          |
 | `withArrow`          | `boolean`                                                   | `false`     | Render an arrow element inside the surface. Consumer CSS positions/rotates it using `[data-placement]`.                      |
 | `inline`             | `boolean`                                                   | `false`     | Render the surface in DOM order (no top-layer elevation, no `popover="manual"`).                                             |
 | `mountNode`          | `HTMLElement \| null`                                       | `null`      | Optional portal target for the surface. When omitted, the surface renders in place (top layer if not `inline`).              |
@@ -50,22 +49,21 @@ Popover is a compound component. `PopoverTrigger` is optional — a surface with
 
 ### `PopoverSurface`
 
-| Prop       | Type        | Default | Description                                                                                          |
-| ---------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `tabIndex` | `number`    | —       | When set, focus is placed on the surface itself on open (instead of the first focusable descendant). |
-| `children` | `ReactNode` | —       | Surface content.                                                                                     |
+| Prop       | Type        | Default | Description                                                                                                          |
+| ---------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `tabIndex` | `number`    | —       | Forwarded to the rendered `<div>` so the surface can be focusable when the consumer needs it (e.g. `tabIndex={-1}`). |
+| `children` | `ReactNode` | —       | Surface content.                                                                                                     |
 
 ## States
 
-| State              | Trigger                                                                                         | Behaviour                                                                                                                                                                                                                           | ARIA                                                                                                                     |
-| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| **Closed**         | Initial, or after dismissal                                                                     | Surface unmounted. Trigger has `aria-expanded="false"`, no `data-open`.                                                                                                                                                             | `aria-expanded="false"` on trigger.                                                                                      |
-| **Open**           | `open={true}` / click / keyboard activation / hover / right-click (depending on props)          | Surface mounted. In non-`inline` mode it's promoted into the top layer via `showPopover()` (feature-detected). `data-placement` reflects the requested placement; `usePlacementObserver` overwrites it with the resolved placement. | `aria-expanded="true"`, `data-open` on trigger; `role="group"` (or `"dialog"` when `trapFocus`), `data-open` on surface. |
-| **Focused (trap)** | `trapFocus={true}` + surface mounted                                                            | Focus moves into the surface (first focusable, or the surface itself if `tabIndex` is numeric, or nothing when `disableAutoFocus`). Tab/Shift+Tab wrap inside the surface. On close, focus restores to the trigger.                 | `role="dialog"`, `aria-modal="true"`, `aria-haspopup="dialog"` on trigger.                                               |
-| **Hover-held**     | `openOnHover` and pointer inside trigger or surface                                             | Popover stays open while pointer is inside either element; closes `mouseLeaveDelay` ms after it leaves both.                                                                                                                        | Same as Open.                                                                                                            |
-| **Context-pinned** | `openOnContext` + right-click                                                                   | `onOpenChange(e, { type: 'contextmenu', open: true })` with the mouse event; `contextTarget` state stores `{ x, y }`. Click and keyboard activation on the trigger do nothing.                                                      | Same as Open.                                                                                                            |
-| **Dismissing**     | Click-outside / Escape inside surface / scroll-outside (if `closeOnScroll`) / iframe-focus move | `onOpenChange(e, { open: false, type })` fires with the originating DOM event. Consumer decides to close by updating state or letting uncontrolled state flip.                                                                      | `aria-expanded` returns to `"false"` on trigger.                                                                         |
-| **Nested**         | Popover rendered inside another Popover's surface                                               | Each instance manages its own Escape / click-outside. Escape filters via `e.target.closest('[data-popover-surface]') === ownSurface` — no `stopPropagation`, no cross-popover coupling.                                             | Each surface keeps its own `role` / `aria-modal`.                                                                        |
+| State              | Trigger                                                                                         | Behaviour                                                                                                                                                                                                                           | ARIA                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Closed**         | Initial, or after dismissal                                                                     | Surface unmounted. Trigger has `aria-expanded="false"`, no `data-open`.                                                                                                                                                             | `aria-expanded="false"` on trigger.                                                     |
+| **Open**           | `open={true}` / click / keyboard activation / hover / right-click (depending on props)          | Surface mounted. In non-`inline` mode it's promoted into the top layer via `showPopover()` (feature-detected). `data-placement` reflects the requested placement; `usePlacementObserver` overwrites it with the resolved placement. | `aria-expanded="true"`, `data-open` on trigger; `role="group"`, `data-open` on surface. |
+| **Hover-held**     | `openOnHover` and pointer inside trigger or surface                                             | Popover stays open while pointer is inside either element; closes `mouseLeaveDelay` ms after it leaves both.                                                                                                                        | Same as Open.                                                                           |
+| **Context-pinned** | `openOnContext` + right-click                                                                   | `onOpenChange(e, { type: 'contextmenu', open: true })` with the mouse event; `contextTarget` state stores `{ x, y }`. Click and keyboard activation on the trigger do nothing.                                                      | Same as Open.                                                                           |
+| **Dismissing**     | Click-outside / Escape inside surface / scroll-outside (if `closeOnScroll`) / iframe-focus move | `onOpenChange(e, { open: false, type })` fires with the originating DOM event. Consumer decides to close by updating state or letting uncontrolled state flip.                                                                      | `aria-expanded` returns to `"false"` on trigger.                                        |
+| **Nested**         | Popover rendered inside another Popover's surface                                               | Each instance manages its own Escape / click-outside. Escape filters via `e.target.closest('[data-popover-surface]') === ownSurface` — no `stopPropagation`, no cross-popover coupling.                                             | Each surface keeps its own `role="group"`.                                              |
 
 ## Keyboard Navigation
 
@@ -81,8 +79,8 @@ Popover is a compound component. `PopoverTrigger` is optional — a surface with
 
 | Key               | Action                                                                                                                                              |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Tab**           | Move focus to next focusable descendant. With `trapFocus={true}`, wraps at the last focusable back to the first.                                    |
-| **Shift + Tab**   | Move focus to previous. Wraps at first back to last when `trapFocus={true}`.                                                                        |
+| **Tab**           | Default browser tab order. The surface does **not** trap focus in this iteration; Tab can move focus out of the surface.                            |
+| **Shift + Tab**   | Default browser reverse tab order.                                                                                                                  |
 | **Escape**        | Dismiss the current popover. Filtered to the nearest enclosing surface, so Escape in a nested popover only closes that popover — not its ancestors. |
 | **Enter / Space** | Default button activation inside the surface.                                                                                                       |
 
@@ -102,25 +100,23 @@ There is no separate `onDismiss`. The `open: false` dispatches go through `onOpe
 // Trigger
 <button
   aria-expanded={open ? 'true' : 'false'}
-  aria-haspopup={trapFocus ? 'dialog' : 'true'}
+  aria-haspopup="true"
   data-open={open || undefined}
   // click / keydown / context / hover handlers merged onto the cloned child
 />
 
 // Surface (inline mode)
 <div
-  role={trapFocus ? 'dialog' : 'group'}
-  aria-modal={trapFocus ? true : undefined}
+  role="group"
   data-popover-surface=""
   data-placement="below-start"   // requested placement; live-updated by observer
   data-open="true"
-  tabIndex={trapFocus ? -1 : undefined}
 />
 
 // Surface (top layer mode — non-inline, default)
 <div
   popover="manual"
-  role="group" /* or "dialog" */
+  role="group"
   data-popover-surface=""
   data-placement="below-start"
   data-open="true"
@@ -129,26 +125,20 @@ There is no separate `onDismiss`. The `open: false` dispatches go through `onOpe
 
 ### Role selection
 
-- **`role="group"`** (default) — non-modal popover with no focus trap. Fine for menus, cards, informational overlays.
-- **`role="dialog"`** — set automatically when `trapFocus={true}`. Makes the surface a modal dialog with `aria-modal="true"` and `aria-haspopup="dialog"` on the trigger.
-
-The package does not implement `role="alertdialog"`; consumers needing an alert pattern should use the `Dialog` headless component instead.
+The surface always renders as **`role="group"`** in this iteration — a non-modal anchored container suitable for menus, cards, and informational overlays. Modal `role="dialog"` (with `aria-modal="true"`, `aria-haspopup="dialog"` on the trigger, and a focus trap) is planned for a follow-up iteration that re-introduces a focus-management hook. Consumers needing modal semantics today should reach for the `Dialog` headless component instead.
 
 ### Focus management
 
-Focus is governed by the shared `useFocusScope` hook (same hook Dialog uses):
+This iteration ships **no built-in focus management**:
 
-- **Initial focus on open** —
-  - `disableAutoFocus={true}` → no focus moves.
-  - Surface has a numeric `tabIndex` → focus the surface itself (`preventScroll: true`).
-  - Otherwise → focus the first focusable descendant. If there isn't one and `trapFocus={true}`, the surface's own `tabIndex={-1}` catches focus.
-- **Focus trap** — when `trapFocus={true}`, Tab/Shift+Tab wrap inside the surface; outside elements cannot receive focus.
-- **Restore focus on close** — focus returns to whatever element was focused immediately before the surface mounted (usually the trigger).
+- **No auto-focus on open.** The browser handles focus naturally. Top-layer popovers (`popover="manual"`) leave focus on the trigger; consumers can call `.focus()` on the surface or a descendant if needed.
+- **No focus trap.** Tab / Shift+Tab follow the document's normal tab order. With a top-layer surface, focus may move to elements behind the surface — that's expected for a non-modal popover.
+- **No focus restore.** When the surface unmounts, focus stays wherever the dismissal interaction left it (typically the trigger after click / Escape; arbitrary after click-outside).
+- **`disableAutoFocus`** is preserved on `PopoverProps` for API stability but is currently inert. It will become meaningful again together with the upcoming focus hook.
 
 ### Labeling
 
-- For `role="dialog"` popovers, the consumer is responsible for providing an accessible name — typically via `aria-labelledby` pointing to a heading inside the surface, or `aria-label`.
-- For `role="group"` popovers, labels are optional but recommended when the surface's role in the interface isn't obvious from nearby context.
+- Labels on a `role="group"` surface are optional but recommended when the surface's purpose isn't obvious from nearby context — e.g., `aria-label` or `aria-labelledby` pointing to a heading inside the surface.
 - The trigger's accessible name remains the child element's own name (the component does nothing that would clobber it).
 
 ### Live regions
@@ -161,18 +151,51 @@ Placement is handled entirely by the `usePositioning` hook, which writes native
 
 ### Options (all optional)
 
-| Option              | Type                                                  | Default      | Effect                                                                                                                                                                               |
+<<<<<<< HEAD
+| Option | Type | Default | Effect |
 | ------------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `position`          | `'above' \| 'below' \| 'before' \| 'after'`           | `'above'`    | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized.                                                                           |
-| `align`             | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'`   | `'center'`   | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases).                                                                                                                |
-| `offset`            | `number \| { mainAxis?: number; crossAxis?: number }` | `0`          | Logical-margin offset from the anchor.                                                                                                                                               |
-| `fallbackPositions` | `PositioningShorthandValue[]`                         | `[]`         | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`.                                                                      |
-| `coverTarget`       | `boolean`                                             | `false`      | Overlap the anchor instead of sitting beside it.                                                                                                                                     |
-| `pinned`            | `boolean`                                             | `false`      | Disable fallback flipping; surface stays at the requested placement even if it overflows.                                                                                            |
-| `matchTargetSize`   | `'width'`                                             | —            | Sets the surface's `width` to `anchor-size(width)`.                                                                                                                                  |
-| `strategy`          | `'fixed' \| 'absolute'`                               | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes. |
-| `target`            | `HTMLElement \| RefObject`                            | —            | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger.                                                                                    |
-| `positioningRef`    | `Ref<PositioningImperativeRef>`                       | —            | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates.                                                                    |
+| `position` | `'above' \| 'below' \| 'before' \| 'after'` | `'above'` | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized. |
+| `align` | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'` | `'center'` | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases). |
+| `offset` | `number \| { mainAxis?: number; crossAxis?: number }` | `0` | Logical-margin offset from the anchor. |
+| `fallbackPositions` | `PositioningShorthandValue[]` | `[]` | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`. |
+| `coverTarget` | `boolean` | `false` | Overlap the anchor instead of sitting beside it. |
+| `pinned` | `boolean` | `false` | Disable fallback flipping; surface stays at the requested placement even if it overflows. |
+| `matchTargetSize` | `'width'` | — | Sets the surface's `width` to `anchor-size(width)`. |
+| `strategy` | `'fixed' \| 'absolute'` | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes. |
+| `target` | `HTMLElement \| RefObject` | — | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger. |
+| `positioningRef` | `Ref<PositioningImperativeRef>` | — | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates. |
+||||||| parent of 4f1eba10dc (docs(react-headless-components-preview): align Popover spec with iteration-1 strip-down)
+| Option | Type | Default | Effect |
+| ------------------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `position` | `'above' \| 'below' \| 'before' \| 'after'` | `'above'` | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized. |
+| `align` | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'` | `'center'` | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases). |
+| `offset` | `number \| { mainAxis?: number; crossAxis?: number }` | `0` | Logical-margin offset from the anchor. |
+| `fallbackPositions` | `PositioningShorthandValue[]` | `[]` | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`. |
+| `coverTarget` | `boolean` | `false` | Overlap the anchor instead of sitting beside it. |
+| `pinned` | `boolean` | `false` | Disable fallback flipping; surface stays at the requested placement even if it overflows. |
+| `matchTargetSize` | `'width'` | — | Sets the surface's `width` to `anchor-size(width)`. |
+| `strategy` | `'fixed' \| 'absolute'` | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes. |
+| `target` | `HTMLElement \| RefObject` | — | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger. |
+| `positioningRef` | `Ref<PositioningImperativeRef>` | — | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates. |
+| `autoSize` | `boolean \| 'width' \| 'height'` | `false` | Cap the surface dimensions against `overflowBoundary`. Requires `overflowBoundary` — pure-CSS autoSize isn't possible due to spec-level restrictions on `anchor()` in `max-*`. |
+| `overflowBoundary` | `HTMLElement \| RefObject` | — | Element the surface must stay inside. Drives a JS-measured `transform: translate3d()` **cross-axis shift** whenever the primary placement would exceed the boundary. Accepts a DOM element or a React ref to one. When paired with `autoSize`, the same rect is used to compute `max-*` caps. `overflowBoundaryPadding` adds breathing room on top of the shift. |
+| `overflowBoundaryPadding` | `number \| { top, end, bottom, start }` | — | Breathing room kept between the surface and the `overflowBoundary` rect. Implemented as a JS-measured `transform: translate3d()` **cross-axis shift** on the surface (only — main-axis overflow is native flip's job, matching v9 / Floating UI's `shift()` middleware). Does not affect the surface's size. Accepts a uniform number or a logical-side object (RTL-aware). Has no effect when `overflowBoundary` is unset or when `coverTarget` is on. |
+=======
+| Option | Type | Default | Effect |
+| ------------------- | ----------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `position` | `'above' \| 'below' \| 'before' \| 'after'` | `'above'` | Which side of the anchor the surface sits on. Physical `top` / `bottom` / `left` / `right` are normalized. |
+| `align` | `'start' \| 'center' \| 'end' \| 'top' \| 'bottom'` | `'center'` | Cross-axis alignment. `top` → `start`, `bottom` → `end` (v9 aliases). |
+| `offset` | `number \| { mainAxis?: number; crossAxis?: number }` | `0` | Logical-margin offset from the anchor. |
+| `fallbackPositions` | `PositioningShorthandValue[]` | `[]` | Custom fallback chain. Each entry is converted to a `<position-area>` value inline in `position-try-fallbacks`. |
+| `coverTarget` | `boolean` | `false` | Overlap the anchor instead of sitting beside it. |
+| `pinned` | `boolean` | `false` | Disable fallback flipping; surface stays at the requested placement even if it overflows. |
+| `matchTargetSize` | `'width'` | — | Sets the surface's `width` to `anchor-size(width)`. |
+| `strategy` | `'fixed' \| 'absolute'` | `'absolute'` | CSS `position` property value on the surface. Matches v9's default. Use `'fixed'` when the surface needs to escape transformed / `contain: layout` ancestors for anchoring purposes. |
+| `target` | `HTMLElement \| RefObject` | — | Custom anchor element. When set, `anchor-name` is written on this element instead of the trigger. |
+| `positioningRef` | `Ref<PositioningImperativeRef>` | — | `{ setTarget(el): void; updatePosition(): void }`. `updatePosition` is a no-op — native positioning self-updates. |
+| `overflowBoundary` | `HTMLElement \| RefObject` | — | Element the surface must stay inside. Implemented as a JS-measured **clamp**: `useBoundaryClamp` writes logical `max-inline-size` / `max-block-size` on the surface so its far edge cannot extend past the boundary's opposite edge. The surface's start edge stays where CSS anchor positioning placed it; only the far edge is clamped, so content reflows inside the clamped box rather than the surface sliding. |
+
+> > > > > > > 4f1eba10dc (docs(react-headless-components-preview): align Popover spec with iteration-1 strip-down)
 
 ### Rendering
 
diff --git a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
index df2e9427dc472a..21504e7194bce0 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
@@ -14,9 +14,6 @@ import type { JSXElement } from '@fluentui/react-utilities';
 import * as React_2 from 'react';
 import type { Slot } from '@fluentui/react-utilities';
 
-// @public (undocumented)
-export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
-
 // @public
 export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
     open: boolean;
@@ -32,7 +29,7 @@ export const Popover: {
 };
 
 // @public
-export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
     positioning: {
         targetRef: React_2.RefCallback<HTMLElement>;
         containerRef: React_2.RefCallback<HTMLElement>;
@@ -50,7 +47,6 @@ export type PopoverProps = {
     mouseLeaveDelay?: number;
     positioning?: PositioningShorthand;
     withArrow?: boolean;
-    trapFocus?: boolean;
     disableAutoFocus?: boolean;
     closeOnScroll?: boolean;
     closeOnIframeFocus?: boolean;
@@ -59,7 +55,7 @@ export type PopoverProps = {
 };
 
 // @public
-export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
+export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
     setOpen: (e: OpenPopoverEvents, open: boolean) => void;
     toggleOpen: (e: OpenPopoverEvents) => void;
     triggerRef: React_2.RefObject<HTMLElement | null>;
@@ -112,44 +108,6 @@ export type PopoverTriggerState = {
     children: React_2.ReactElement | null;
 };
 
-// @public (undocumented)
-export type Position = 'above' | 'below' | 'before' | 'after';
-
-// @public
-export type PositioningImperativeRef = {
-    setTarget: (target: HTMLElement | null) => void;
-    updatePosition: () => void;
-};
-
-// @public (undocumented)
-export type PositioningProps = {
-    position?: Position;
-    align?: Alignment;
-    offset?: number | {
-        mainAxis?: number;
-        crossAxis?: number;
-    };
-    fallbackPositions?: PositioningShorthandValue[];
-    coverTarget?: boolean;
-    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
-    strategy?: 'absolute' | 'fixed';
-    matchTargetSize?: 'width';
-    pinned?: boolean;
-    positioningRef?: React_2.Ref<PositioningImperativeRef>;
-};
-
-// @public (undocumented)
-export type PositioningReturn = {
-    targetRef: React_2.RefCallback<HTMLElement>;
-    containerRef: React_2.RefCallback<HTMLElement>;
-};
-
-// @public (undocumented)
-export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
-
-// @public (undocumented)
-export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
-
 // @public
 export const renderPopover: (state: PopoverState, contextValues: {
     popover: PopoverContextValue;
diff --git a/packages/react-components/react-headless-components-preview/library/etc/positioning.api.md b/packages/react-components/react-headless-components-preview/library/etc/positioning.api.md
new file mode 100644
index 00000000000000..e2a3f51c5edb92
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/etc/positioning.api.md
@@ -0,0 +1,76 @@
+## API Report File for "@fluentui/react-headless-components-preview"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type * as React_2 from 'react';
+
+// @public (undocumented)
+export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+
+// @public (undocumented)
+export const ALIGNMENTS: {
+    readonly start: "start";
+    readonly center: "center";
+    readonly end: "end";
+};
+
+// @public
+export function getPlacementString(position: Position, align: LogicalAlignment): string;
+
+// @public (undocumented)
+export type Position = 'above' | 'below' | 'before' | 'after';
+
+// @public
+export type PositioningImperativeRef = {
+    setTarget: (target: HTMLElement | null) => void;
+    updatePosition: () => void;
+};
+
+// @public (undocumented)
+export type PositioningProps = {
+    position?: Position;
+    align?: Alignment;
+    offset?: number | {
+        mainAxis?: number;
+        crossAxis?: number;
+    };
+    fallbackPositions?: PositioningShorthandValue[];
+    coverTarget?: boolean;
+    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
+    strategy?: 'absolute' | 'fixed';
+    matchTargetSize?: 'width';
+    pinned?: boolean;
+    positioningRef?: React_2.Ref<PositioningImperativeRef>;
+};
+
+// @public (undocumented)
+export type PositioningReturn = {
+    targetRef: React_2.RefCallback<HTMLElement>;
+    containerRef: React_2.RefCallback<HTMLElement>;
+};
+
+// @public (undocumented)
+export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+// @public (undocumented)
+export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
+
+// @public (undocumented)
+export const POSITIONS: {
+    readonly above: "above";
+    readonly below: "below";
+    readonly before: "before";
+    readonly after: "after";
+};
+
+// @public
+export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps;
+
+// @public (undocumented)
+export function usePositioning(options: PositioningProps): PositioningReturn;
+
+// (No @packageDocumentation comment for this package)
+
+```
diff --git a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
index b6d45ed6ba60a6..6bef1c6e594fed 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md
@@ -4,2334 +4,6 @@
 
 ```ts
 
-<<<<<<< HEAD
-||||||| parent of 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
-import type { AccordionBaseProps } from '@fluentui/react-accordion';
-import { AccordionBaseState } from '@fluentui/react-accordion';
-import { AccordionContextValue } from '@fluentui/react-accordion';
-import { AccordionContextValues as AccordionContextValues_2 } from '@fluentui/react-accordion';
-import type { AccordionHeaderBaseProps } from '@fluentui/react-accordion';
-import { AccordionHeaderBaseState } from '@fluentui/react-accordion';
-import { AccordionHeaderContextValues } from '@fluentui/react-accordion';
-import type { AccordionHeaderSlots as AccordionHeaderSlots_2 } from '@fluentui/react-accordion';
-import { AccordionItemContextValues } from '@fluentui/react-accordion';
-import type { AccordionItemProps as AccordionItemProps_2 } from '@fluentui/react-accordion';
-import type { AccordionItemSlots as AccordionItemSlots_2 } from '@fluentui/react-accordion';
-import { AccordionItemState as AccordionItemState_2 } from '@fluentui/react-accordion';
-import type { AccordionPanelBaseProps } from '@fluentui/react-accordion';
-import type { AccordionPanelBaseState } from '@fluentui/react-accordion';
-import type { AccordionPanelSlots as AccordionPanelSlots_2 } from '@fluentui/react-accordion';
-import type { AccordionSlots as AccordionSlots_2 } from '@fluentui/react-accordion';
-import type { AvatarBaseProps } from '@fluentui/react-avatar';
-import { AvatarBaseState } from '@fluentui/react-avatar';
-import type { BadgeBaseProps } from '@fluentui/react-badge';
-import { BadgeBaseState } from '@fluentui/react-badge';
-import type { BreadcrumbBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonBaseProps } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonSlots as BreadcrumbButtonSlots_2 } from '@fluentui/react-breadcrumb';
-import { BreadcrumbContextValues as BreadcrumbContextValues_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbDividerBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbDividerBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbDividerSlots as BreadcrumbDividerSlots_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbItemBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbItemBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbItemSlots as BreadcrumbItemSlots_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbSlots as BreadcrumbSlots_2 } from '@fluentui/react-breadcrumb';
-import type { ButtonBaseProps } from '@fluentui/react-button';
-import { ButtonBaseState } from '@fluentui/react-button';
-import type { ButtonSlots as ButtonSlots_2 } from '@fluentui/react-button';
-import type { CheckboxBaseProps } from '@fluentui/react-checkbox';
-import { CheckboxBaseState } from '@fluentui/react-checkbox';
-import type { CheckboxSlots as CheckboxSlots_2 } from '@fluentui/react-checkbox';
-import { ComponentProps } from '@fluentui/react-utilities';
-import type { ComponentState } from '@fluentui/react-utilities';
-import { ContextSelector } from '@fluentui/react-context-selector';
-import type { DividerBaseProps } from '@fluentui/react-divider';
-import { DividerBaseState } from '@fluentui/react-divider';
-import type { DividerSlots as DividerSlots_2 } from '@fluentui/react-divider';
-import type { EventData } from '@fluentui/react-utilities';
-import type { EventHandler } from '@fluentui/react-utilities';
-import type { FieldBaseProps } from '@fluentui/react-field';
-import { FieldBaseState } from '@fluentui/react-field';
-import { FieldContextValues } from '@fluentui/react-field';
-import type { FieldSlots as FieldSlots_2 } from '@fluentui/react-field';
-import type { ForwardRefComponent } from '@fluentui/react-utilities';
-import type { InputBaseProps } from '@fluentui/react-input';
-import { InputBaseState } from '@fluentui/react-input';
-import type { InputSlots as InputSlots_2 } from '@fluentui/react-input';
-import { JSXElement } from '@fluentui/react-utilities';
-import type { LinkBaseProps } from '@fluentui/react-link';
-import { LinkBaseState } from '@fluentui/react-link';
-import type { LinkSlots as LinkSlots_2 } from '@fluentui/react-link';
-import { MessageBarActionsContextValues as MessageBarActionsContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarActionsProps as MessageBarActionsProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarActionsSlots as MessageBarActionsSlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarActionsState as MessageBarActionsState_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBaseProps } from '@fluentui/react-message-bar';
-import { MessageBarBaseState } from '@fluentui/react-message-bar';
-import { MessageBarBodyContextValues as MessageBarBodyContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBodyProps as MessageBarBodyProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBodySlots as MessageBarBodySlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarBodyState as MessageBarBodyState_2 } from '@fluentui/react-message-bar';
-import { MessageBarContextValue } from '@fluentui/react-message-bar';
-import { MessageBarContextValues as MessageBarContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarIntent } from '@fluentui/react-message-bar';
-import type { MessageBarSlots as MessageBarSlots_2 } from '@fluentui/react-message-bar';
-import type { MessageBarTitleProps as MessageBarTitleProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarTitleSlots as MessageBarTitleSlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarTitleState as MessageBarTitleState_2 } from '@fluentui/react-message-bar';
-import type { ProgressBarBaseProps } from '@fluentui/react-progress';
-import type { ProgressBarBaseState } from '@fluentui/react-progress';
-import type { ProgressBarSlots as ProgressBarSlots_2 } from '@fluentui/react-progress';
-import type { RadioBaseProps } from '@fluentui/react-radio';
-import { RadioBaseState } from '@fluentui/react-radio';
-import type { RadioGroupBaseProps } from '@fluentui/react-radio';
-import { RadioGroupBaseState } from '@fluentui/react-radio';
-import { RadioGroupContextValues } from '@fluentui/react-radio';
-import type { RadioGroupSlots as RadioGroupSlots_2 } from '@fluentui/react-radio';
-import { RadioOnChangeData } from '@fluentui/react-radio';
-import { RadioSlots as RadioSlots_2 } from '@fluentui/react-radio';
-import type { RatingBaseProps } from '@fluentui/react-rating';
-import { RatingBaseState } from '@fluentui/react-rating';
-import { RatingContextValues } from '@fluentui/react-rating';
-import type { RatingDisplayBaseProps } from '@fluentui/react-rating';
-import { RatingDisplayBaseState } from '@fluentui/react-rating';
-import { RatingDisplayContextValues } from '@fluentui/react-rating';
-import type { RatingDisplaySlots as RatingDisplaySlots_2 } from '@fluentui/react-rating';
-import type { RatingItemBaseProps } from '@fluentui/react-rating';
-import { RatingItemBaseState } from '@fluentui/react-rating';
-import { RatingItemSlots as RatingItemSlots_2 } from '@fluentui/react-rating';
-import type { RatingSlots as RatingSlots_2 } from '@fluentui/react-rating';
-import * as React_2 from 'react';
-import type { SearchBoxBaseProps } from '@fluentui/react-search';
-import { SearchBoxBaseState } from '@fluentui/react-search';
-import type { SearchBoxSlots as SearchBoxSlots_2 } from '@fluentui/react-search';
-import type { SelectBaseProps } from '@fluentui/react-select';
-import { SelectBaseState } from '@fluentui/react-select';
-import type { SelectSlots as SelectSlots_2 } from '@fluentui/react-select';
-import { SkeletonBaseProps } from '@fluentui/react-skeleton';
-import { SkeletonBaseState } from '@fluentui/react-skeleton';
-import { SkeletonContextValues } from '@fluentui/react-skeleton';
-import { SkeletonItemBaseProps } from '@fluentui/react-skeleton';
-import { SkeletonItemBaseState } from '@fluentui/react-skeleton';
-import type { SkeletonItemSlots as SkeletonItemSlots_2 } from '@fluentui/react-skeleton';
-import type { SkeletonSlots as SkeletonSlots_2 } from '@fluentui/react-skeleton';
-import type { SliderBaseProps } from '@fluentui/react-slider';
-import { SliderBaseState } from '@fluentui/react-slider';
-import type { SliderSlots as SliderSlots_2 } from '@fluentui/react-slider';
-import type { Slot } from '@fluentui/react-utilities';
-import type { SpinButtonBaseProps } from '@fluentui/react-spinbutton';
-import { SpinButtonBaseState } from '@fluentui/react-spinbutton';
-import type { SpinButtonSlots as SpinButtonSlots_2 } from '@fluentui/react-spinbutton';
-import type { SpinnerBaseProps } from '@fluentui/react-spinner';
-import { SpinnerBaseState } from '@fluentui/react-spinner';
-import type { SpinnerSlots as SpinnerSlots_2 } from '@fluentui/react-spinner';
-import type { SwitchBaseProps } from '@fluentui/react-switch';
-import { SwitchBaseState } from '@fluentui/react-switch';
-import type { SwitchSlots as SwitchSlots_2 } from '@fluentui/react-switch';
-import type { TabBaseProps } from '@fluentui/react-tabs';
-import { TabBaseState } from '@fluentui/react-tabs';
-import type { TabListBaseProps } from '@fluentui/react-tabs';
-import { TabListBaseState } from '@fluentui/react-tabs';
-import { TabListContextValues } from '@fluentui/react-tabs';
-import type { TabListSlots as TabListSlots_2 } from '@fluentui/react-tabs';
-import { TabSlots } from '@fluentui/react-tabs';
-import { TabValue } from '@fluentui/react-tabs';
-import type { TextareaBaseProps } from '@fluentui/react-textarea';
-import { TextareaBaseState } from '@fluentui/react-textarea';
-import type { TextareaSlots as TextareaSlots_2 } from '@fluentui/react-textarea';
-import type { ToggleButtonBaseProps } from '@fluentui/react-button';
-import type { ToggleButtonBaseState } from '@fluentui/react-button';
-import { useMessageBarBodyContextValues_unstable } from '@fluentui/react-message-bar';
-
-// @public
-export const Accordion: ForwardRefComponent<AccordionProps>;
-
-// @public (undocumented)
-export type AccordionContextValues = AccordionContextValues_2;
-
-// @public
-export const AccordionHeader: ForwardRefComponent<AccordionHeaderProps>;
-
-// @public (undocumented)
-export type AccordionHeaderProps = AccordionHeaderBaseProps;
-
-// @public (undocumented)
-export type AccordionHeaderSlots = AccordionHeaderSlots_2;
-
-// @public (undocumented)
-export type AccordionHeaderState = AccordionHeaderBaseState & {
-    root: {
-        'data-open'?: string;
-        'data-disabled'?: string;
-        'data-expand-icon-position'?: string;
-    };
-};
-
-// @public
-export const AccordionItem: ForwardRefComponent<AccordionItemProps>;
-
-// @public (undocumented)
-export type AccordionItemProps = AccordionItemProps_2;
-
-// @public (undocumented)
-export type AccordionItemSlots = AccordionItemSlots_2;
-
-// @public (undocumented)
-export type AccordionItemState = AccordionItemState_2 & {
-    root: {
-        'data-disabled'?: string;
-        'data-open'?: string;
-    };
-};
-
-// @public
-export const AccordionPanel: ForwardRefComponent<AccordionPanelProps>;
-
-// @public (undocumented)
-export type AccordionPanelProps = AccordionPanelBaseProps;
-
-// @public (undocumented)
-export type AccordionPanelSlots = AccordionPanelSlots_2;
-
-// @public (undocumented)
-export type AccordionPanelState = AccordionPanelBaseState & {
-    root: {
-        'data-open'?: string;
-    };
-};
-
-// @public (undocumented)
-export type AccordionProps = AccordionBaseProps;
-
-// @public (undocumented)
-export type AccordionSlots = AccordionSlots_2;
-
-// @public (undocumented)
-export type AccordionState = AccordionBaseState & {
-    root: {
-        'data-collapsible'?: string;
-        'data-multiple'?: string;
-    };
-};
-
-// @public (undocumented)
-export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
-
-// @public
-export const Avatar: ForwardRefComponent<AvatarProps>;
-
-// @public
-export type AvatarProps = AvatarBaseProps;
-
-// @public
-export type AvatarState = AvatarBaseState;
-
-// @public
-export const Badge: ForwardRefComponent<BadgeProps>;
-
-// @public
-export type BadgeProps = BadgeBaseProps;
-
-// @public
-export type BadgeState = BadgeBaseState & {
-    root: {
-        'data-icon-position'?: 'before' | 'after';
-    };
-};
-
-// @public
-export const Breadcrumb: ForwardRefComponent<BreadcrumbProps>;
-
-// @public
-export const BreadcrumbButton: ForwardRefComponent<BreadcrumbButtonProps>;
-
-// @public
-export type BreadcrumbButtonProps = BreadcrumbButtonBaseProps;
-
-// @public
-export type BreadcrumbButtonSlots = BreadcrumbButtonSlots_2;
-
-// @public
-export type BreadcrumbButtonState = BreadcrumbButtonBaseState & {
-    root: {
-        'data-current'?: string;
-    };
-};
-
-// @public
-export type BreadcrumbContextValues = BreadcrumbContextValues_2;
-
-// @public
-export const BreadcrumbDivider: ForwardRefComponent<BreadcrumbDividerProps>;
-
-// @public
-export type BreadcrumbDividerProps = BreadcrumbDividerBaseProps;
-
-// @public
-export type BreadcrumbDividerSlots = BreadcrumbDividerSlots_2;
-
-// @public
-export type BreadcrumbDividerState = BreadcrumbDividerBaseState;
-
-// @public
-export const BreadcrumbItem: ForwardRefComponent<BreadcrumbItemProps>;
-
-// @public
-export type BreadcrumbItemProps = BreadcrumbItemBaseProps;
-
-// @public
-export type BreadcrumbItemSlots = BreadcrumbItemSlots_2;
-
-// @public
-export type BreadcrumbItemState = BreadcrumbItemBaseState;
-
-// @public
-export type BreadcrumbProps = BreadcrumbBaseProps;
-
-// @public
-export type BreadcrumbSlots = BreadcrumbSlots_2;
-
-// @public
-export type BreadcrumbState = BreadcrumbBaseState;
-
-// @public
-export const Button: ForwardRefComponent<ButtonProps>;
-
-// @public
-export type ButtonProps = ButtonBaseProps;
-
-// @public
-export type ButtonSlots = ButtonSlots_2;
-
-// @public
-export type ButtonState = ButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-icon-only'?: string;
-    };
-};
-
-// @public
-export const Checkbox: ForwardRefComponent<CheckboxProps>;
-
-// @public
-export type CheckboxProps = CheckboxBaseProps;
-
-// @public (undocumented)
-export type CheckboxSlots = CheckboxSlots_2;
-
-// @public
-export type CheckboxState = CheckboxBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const Divider: ForwardRefComponent<DividerProps>;
-
-// @public (undocumented)
-export type DividerProps = DividerBaseProps;
-
-// @public (undocumented)
-export type DividerSlots = DividerSlots_2;
-
-// @public (undocumented)
-export type DividerState = DividerBaseState & {
-    root: {
-        'data-orientation'?: 'vertical' | 'horizontal';
-    };
-};
-
-// @public
-export const Field: ForwardRefComponent<FieldProps>;
-
-// @public
-export type FieldProps = FieldBaseProps;
-
-// @public
-export type FieldSlots = FieldSlots_2;
-
-// @public
-export type FieldState = FieldBaseState & {
-    root: {
-        'data-validate-state'?: FieldBaseState['validationState'];
-    };
-};
-
-// @public
-export const Input: ForwardRefComponent<InputProps>;
-
-// @public
-export type InputProps = InputBaseProps;
-
-// @public
-export type InputSlots = InputSlots_2;
-
-// @public
-export type InputState = InputBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Link: ForwardRefComponent<LinkProps>;
-
-// @public
-export type LinkProps = LinkBaseProps;
-
-// @public
-export type LinkSlots = LinkSlots_2;
-
-// @public
-export type LinkState = LinkBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-    };
-};
-
-// @public
-export const MessageBar: ForwardRefComponent<MessageBarProps>;
-
-// @public
-export const MessageBarActions: ForwardRefComponent<MessageBarActionsProps>;
-
-// @public (undocumented)
-export type MessageBarActionsContextValues = MessageBarActionsContextValues_2;
-
-// @public (undocumented)
-export type MessageBarActionsProps = MessageBarActionsProps_2;
-
-// @public (undocumented)
-export type MessageBarActionsSlots = MessageBarActionsSlots_2;
-
-// @public (undocumented)
-export type MessageBarActionsState = MessageBarActionsState_2 & {
-    root: {
-        'data-layout'?: string;
-        'data-has-actions'?: string;
-    };
-};
-
-// @public
-export const MessageBarBody: ForwardRefComponent<MessageBarBodyProps>;
-
-// @public (undocumented)
-export type MessageBarBodyContextValues = MessageBarBodyContextValues_2;
-
-// @public (undocumented)
-export type MessageBarBodyProps = MessageBarBodyProps_2;
-
-// @public (undocumented)
-export type MessageBarBodySlots = MessageBarBodySlots_2;
-
-// @public (undocumented)
-export type MessageBarBodyState = MessageBarBodyState_2;
-
-// @public (undocumented)
-export type MessageBarContextValues = MessageBarContextValues_2;
-
-export { MessageBarIntent }
-
-// @public (undocumented)
-export type MessageBarProps = MessageBarBaseProps;
-
-// @public (undocumented)
-export type MessageBarSlots = MessageBarSlots_2;
-
-// @public (undocumented)
-export type MessageBarState = MessageBarBaseState & {
-    root: {
-        'data-layout'?: string;
-        'data-intent'?: string;
-    };
-};
-
-// @public
-export const MessageBarTitle: ForwardRefComponent<MessageBarTitleProps>;
-
-// @public (undocumented)
-export type MessageBarTitleProps = MessageBarTitleProps_2;
-
-// @public (undocumented)
-export type MessageBarTitleSlots = MessageBarTitleSlots_2;
-
-// @public (undocumented)
-export type MessageBarTitleState = MessageBarTitleState_2;
-
-// @public
-export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
-    open: boolean;
-};
-
-// @public
-export type OpenPopoverEvents = MouseEvent | TouchEvent | React_2.FocusEvent<HTMLElement> | React_2.KeyboardEvent<HTMLElement> | React_2.MouseEvent<HTMLElement>;
-
-// @public
-export const Popover: {
-    (props: PopoverProps): JSXElement;
-    displayName: string;
-};
-
-// @public
-export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
-    positioning: {
-        targetRef: React_2.RefCallback<HTMLElement>;
-        containerRef: React_2.RefCallback<HTMLElement>;
-    };
-};
-
-// @public
-export type PopoverProps = {
-    children: [JSXElement, JSXElement] | JSXElement;
-    open?: boolean;
-    defaultOpen?: boolean;
-    onOpenChange?: EventHandler<OnOpenChangeData>;
-    openOnHover?: boolean;
-    openOnContext?: boolean;
-    mouseLeaveDelay?: number;
-    positioning?: PositioningShorthand;
-    withArrow?: boolean;
-    trapFocus?: boolean;
-    disableAutoFocus?: boolean;
-    closeOnScroll?: boolean;
-    closeOnIframeFocus?: boolean;
-    inline?: boolean;
-    mountNode?: HTMLElement | null;
-};
-
-// @public
-export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'trapFocus' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
-    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
-    toggleOpen: (e: OpenPopoverEvents) => void;
-    triggerRef: React_2.RefObject<HTMLElement | null>;
-    contentRef: React_2.RefObject<HTMLElement | null>;
-    arrowRef: React_2.RefObject<HTMLDivElement | null>;
-    popoverTrigger: React_2.ReactElement | undefined;
-    popoverSurface: React_2.ReactElement | undefined;
-    contextTarget: {
-        x: number;
-        y: number;
-    } | undefined;
-    setContextTarget: (target: {
-        x: number;
-        y: number;
-    } | undefined) => void;
-    positioning: PositioningReturn;
-};
-
-// @public
-export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps>;
-
-// @public (undocumented)
-export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
-
-// @public
-export type PopoverSurfaceSlots = {
-    root: Slot<'div'>;
-};
-
-// @public (undocumented)
-export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
-    inline: boolean;
-    withArrow: boolean | undefined;
-    arrowRef: React_2.RefObject<HTMLDivElement | null>;
-    mountNode: HTMLElement | null | undefined;
-    'data-open': string;
-};
-
-// @public
-export const PopoverTrigger: React_2.FC<PopoverTriggerProps>;
-
-// @public
-export type PopoverTriggerProps = {
-    children: React_2.ReactElement;
-    disableButtonEnhancement?: boolean;
-};
-
-// @public
-export type PopoverTriggerState = {
-    children: React_2.ReactElement | null;
-};
-
-// @public (undocumented)
-export type Position = 'above' | 'below' | 'before' | 'after';
-
-// @public
-export type PositioningBoundaryPadding = number | Partial<{
-    top: number;
-    end: number;
-    bottom: number;
-    start: number;
-}>;
-
-// @public
-export type PositioningImperativeRef = {
-    setTarget: (target: HTMLElement | null) => void;
-    updatePosition: () => void;
-};
-
-// @public (undocumented)
-export type PositioningProps = {
-    position?: Position;
-    align?: Alignment;
-    offset?: number | {
-        mainAxis?: number;
-        crossAxis?: number;
-    };
-    fallbackPositions?: PositioningShorthandValue[];
-    coverTarget?: boolean;
-    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
-    strategy?: 'absolute' | 'fixed';
-    matchTargetSize?: 'width';
-    pinned?: boolean;
-    positioningRef?: React_2.Ref<PositioningImperativeRef>;
-    overflowBoundary?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
-    overflowBoundaryPadding?: PositioningBoundaryPadding;
-};
-
-// @public (undocumented)
-export type PositioningReturn = {
-    targetRef: React_2.RefCallback<HTMLElement>;
-    containerRef: React_2.RefCallback<HTMLElement>;
-};
-
-// @public (undocumented)
-export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
-
-// @public (undocumented)
-export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
-
-// @public
-export const ProgressBar: ForwardRefComponent<ProgressBarProps>;
-
-// @public
-export type ProgressBarProps = ProgressBarBaseProps;
-
-// @public (undocumented)
-export type ProgressBarSlots = ProgressBarSlots_2;
-
-// @public
-export type ProgressBarState = ProgressBarBaseState;
-
-// @public
-export const Radio: React_2.ForwardRefExoticComponent<Omit<ComponentProps<Partial<RadioSlots_2>, "input">, "onChange" | "size"> & {
-    value?: string;
-    labelPosition?: "after" | "below";
-    disabled?: boolean;
-    onChange?: (ev: React_2.ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void;
-} & React_2.RefAttributes<HTMLInputElement>>;
-
-// @public
-export const RadioGroup: ForwardRefComponent<RadioGroupProps>;
-
-// @public
-export type RadioGroupProps = RadioGroupBaseProps;
-
-// @public
-export type RadioGroupSlots = RadioGroupSlots_2;
-
-// @public
-export type RadioGroupState = RadioGroupBaseState;
-
-// @public
-export type RadioProps = RadioBaseProps;
-
-// @public
-export type RadioSlots = RadioSlots_2;
-
-// @public
-export type RadioState = RadioBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Rating: ForwardRefComponent<RatingProps>;
-
-// @public
-export const RatingDisplay: ForwardRefComponent<RatingDisplayProps>;
-
-// @public
-export type RatingDisplayProps = RatingDisplayBaseProps;
-
-// @public
-export type RatingDisplaySlots = RatingDisplaySlots_2;
-
-// @public
-export type RatingDisplayState = RatingDisplayBaseState;
-
-// @public
-export const RatingItem: React_2.ForwardRefExoticComponent<Omit<Partial<RatingItemSlots_2>, "root"> & Omit<{
-    as?: "span" | undefined;
-} & Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "children"> & {
-    children?: any;
-}, "ref"> & {
-    value?: number;
-} & React_2.RefAttributes<HTMLSpanElement>>;
-
-// @public
-export type RatingItemProps = RatingItemBaseProps;
-
-// @public
-export type RatingItemSlots = RatingItemSlots_2;
-
-// @public
-export type RatingItemState = RatingItemBaseState & {
-    root: {
-        'data-appearance'?: 'filled' | 'filled-half' | 'outline';
-    };
-};
-
-// @public
-export type RatingProps = RatingBaseProps;
-
-// @public
-export type RatingSlots = RatingSlots_2;
-
-// @public
-export type RatingState = RatingBaseState;
-
-// @public
-export const renderAccordion: (state: AccordionBaseState, contextValues: AccordionContextValues_2) => JSXElement;
-
-// @public
-export const renderAccordionHeader: (state: AccordionHeaderBaseState, contextValues: AccordionHeaderContextValues) => JSXElement;
-
-// @public
-export const renderAccordionItem: (state: AccordionItemState_2, contextValues: AccordionItemContextValues) => JSXElement;
-
-// @public
-export const renderAccordionPanel: (state: AccordionPanelState) => JSXElement;
-
-// @public
-export const renderAvatar: (state: AvatarBaseState) => JSXElement;
-
-// @public
-export const renderBadge: (state: BadgeBaseState) => JSXElement;
-
-// @public
-export const renderBreadcrumb: (state: BreadcrumbBaseState, contextValues: BreadcrumbContextValues_2) => JSXElement;
-
-// @public
-export const renderBreadcrumbButton: (state: BreadcrumbButtonState) => JSXElement;
-
-// @public
-export const renderBreadcrumbDivider: (state: BreadcrumbDividerBaseState) => JSXElement;
-
-// @public
-export const renderBreadcrumbItem: (state: BreadcrumbItemBaseState) => JSXElement;
-
-// @public
-export const renderButton: (state: ButtonBaseState) => JSXElement;
-
-// @public
-export const renderCheckbox: (state: CheckboxBaseState) => JSXElement;
-
-// @public
-export const renderDivider: (state: DividerBaseState) => JSXElement;
-
-// @public
-export const renderField: (state: FieldBaseState, contextValues: FieldContextValues) => JSXElement;
-
-// @public
-export const renderInput: (state: InputBaseState) => JSXElement;
-
-// @public
-export const renderLink: (state: LinkBaseState) => JSXElement;
-
-// @public
-export const renderMessageBar: (state: MessageBarBaseState, contexts: MessageBarContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarActions: (state: MessageBarActionsState_2, contexts: MessageBarActionsContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarBody: (state: MessageBarBodyState_2, contextValues: MessageBarBodyContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarTitle: (state: MessageBarTitleState_2) => JSXElement;
-
-// @public
-export const renderPopover: (state: PopoverState, contextValues: {
-    popover: PopoverContextValue;
-}) => React_2.ReactElement;
-
-// @public
-export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
-
-// @public
-export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
-
-// @public
-export const renderProgressBar: (state: ProgressBarState) => JSXElement;
-
-// @public
-export const renderRadio: (state: RadioBaseState) => JSXElement;
-
-// @public
-export const renderRadioGroup: (state: RadioGroupBaseState, contextValues: RadioGroupContextValues) => JSXElement;
-
-// @public
-export const renderRating: (state: RatingBaseState, contextValues: RatingContextValues) => JSXElement;
-
-// @public
-export const renderRatingDisplay: (state: RatingDisplayBaseState, contextValues: RatingDisplayContextValues) => JSXElement;
-
-// @public
-export const renderRatingItem: (state: RatingItemBaseState) => JSXElement;
-
-// @public
-export const renderSearchBox: (state: SearchBoxBaseState) => JSXElement;
-
-// @public
-export const renderSelect: (state: SelectBaseState) => JSXElement;
-
-// @public
-export const renderSkeleton: (state: SkeletonBaseState, contextValues: SkeletonContextValues) => JSXElement;
-
-// @public
-export const renderSkeletonItem: (state: SkeletonItemBaseState) => JSXElement;
-
-// @public
-export const renderSlider: (state: SliderBaseState) => JSXElement;
-
-// @public
-export const renderSpinButton: (state: SpinButtonBaseState) => JSXElement;
-
-// @public
-export const renderSpinner: (state: SpinnerBaseState) => JSXElement;
-
-// @public
-export const renderSwitch: (state: SwitchBaseState) => JSXElement;
-
-// @public
-export const renderTab: (state: TabBaseState) => JSXElement;
-
-// @public
-export const renderTabList: (state: TabListBaseState, contextValues: TabListContextValues) => JSXElement;
-
-// @public
-export const renderTextarea: (state: TextareaBaseState) => JSXElement;
-
-// @public
-export const renderToggleButton: (state: ButtonBaseState) => JSXElement;
-
-// @public
-export const SearchBox: ForwardRefComponent<SearchBoxProps>;
-
-// @public
-export type SearchBoxProps = SearchBoxBaseProps;
-
-// @public
-export type SearchBoxSlots = SearchBoxSlots_2;
-
-// @public
-export type SearchBoxState = SearchBoxBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-focused'?: string;
-    };
-};
-
-// @public
-export const Select: ForwardRefComponent<SelectProps>;
-
-// @public
-export type SelectProps = SelectBaseProps;
-
-// @public (undocumented)
-export type SelectSlots = SelectSlots_2;
-
-// @public
-export type SelectState = SelectBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Skeleton: React_2.ForwardRefExoticComponent<SkeletonBaseProps & React_2.RefAttributes<HTMLDivElement>>;
-
-// @public
-export const SkeletonItem: React_2.ForwardRefExoticComponent<SkeletonItemBaseProps & React_2.RefAttributes<HTMLDivElement>>;
-
-// @public
-export type SkeletonItemProps = SkeletonItemBaseProps;
-
-// @public
-export type SkeletonItemSlots = SkeletonItemSlots_2;
-
-// @public
-export type SkeletonItemState = SkeletonItemBaseState;
-
-// @public
-export type SkeletonProps = SkeletonBaseProps;
-
-// @public
-export type SkeletonSlots = SkeletonSlots_2;
-
-// @public
-export type SkeletonState = SkeletonBaseState;
-
-// @public
-export const Slider: ForwardRefComponent<SliderProps>;
-
-// @public
-export type SliderProps = SliderBaseProps;
-
-// @public
-export type SliderSlots = SliderSlots_2;
-
-// @public
-export type SliderState = SliderBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-vertical'?: string;
-    };
-};
-
-// @public
-export const SpinButton: ForwardRefComponent<SpinButtonProps>;
-
-// @public
-export type SpinButtonProps = SpinButtonBaseProps;
-
-// @public
-export type SpinButtonSlots = SpinButtonSlots_2;
-
-// @public
-export type SpinButtonState = SpinButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-spin-state'?: string;
-        'data-at-bound'?: string;
-    };
-};
-
-// @public
-export const Spinner: ForwardRefComponent<SpinnerProps>;
-
-// @public
-export type SpinnerProps = SpinnerBaseProps;
-
-// @public
-export type SpinnerSlots = SpinnerSlots_2;
-
-// @public
-export type SpinnerState = SpinnerBaseState & {
-    root: {
-        'data-label-position'?: 'before' | 'after' | 'above' | 'below';
-    };
-};
-
-// @public
-export const Switch: ForwardRefComponent<SwitchProps>;
-
-// @public
-export type SwitchProps = SwitchBaseProps;
-
-// @public
-export type SwitchSlots = SwitchSlots_2;
-
-// @public
-export type SwitchState = SwitchBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const Tab: ForwardRefComponent<TabProps>;
-
-// @public
-export const TabList: ForwardRefComponent<TabListProps>;
-
-// @public
-export type TabListProps = TabListBaseProps;
-
-// @public
-export type TabListSlots = TabListSlots_2;
-
-// @public
-export type TabListState = TabListBaseState & {
-    root: {
-        focusgroup?: string;
-        'data-orientation'?: 'vertical' | 'horizontal';
-    };
-};
-
-// @public (undocumented)
-export type TabProps = TabBaseProps;
-
-export { TabSlots }
-
-// @public (undocumented)
-export type TabState = TabBaseState & {
-    root: {
-        focusgroupstart?: string;
-        'data-icon-only'?: string;
-        'data-selected'?: string;
-    };
-};
-
-export { TabValue }
-
-// @public
-export const Textarea: ForwardRefComponent<TextareaProps>;
-
-// @public
-export type TextareaProps = TextareaBaseProps;
-
-// @public
-export type TextareaSlots = TextareaSlots_2;
-
-// @public
-export type TextareaState = TextareaBaseState;
-
-// @public
-export const ToggleButton: ForwardRefComponent<ToggleButtonProps>;
-
-// @public
-export type ToggleButtonProps = ToggleButtonBaseProps;
-
-// @public
-export type ToggleButtonSlots = ButtonSlots;
-
-// @public
-export type ToggleButtonState = ToggleButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-icon-only'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const useAccordion: (props: AccordionProps, ref: React_2.Ref<HTMLElement>) => AccordionState;
-
-// @public
-export const useAccordionContext: <T>(selector: ContextSelector<AccordionContextValue, T>) => T;
-
-// @public
-export const useAccordionContextValues: (state: AccordionState) => AccordionContextValues;
-
-// @public
-export const useAccordionHeader: (props: AccordionHeaderProps, ref: React_2.Ref<HTMLElement>) => AccordionHeaderState;
-
-// @public
-export const useAccordionItem: (props: AccordionItemProps, ref: React_2.Ref<HTMLElement>) => AccordionItemState;
-
-// @public
-export const useAccordionPanel: (props: AccordionPanelProps, ref: React_2.Ref<HTMLElement>) => AccordionPanelState;
-
-// @public
-export const useAvatar: (props: AvatarProps, ref: React_2.Ref<HTMLElement>) => AvatarState;
-
-// @public
-export const useBadge: (props: BadgeProps, ref: React_2.Ref<HTMLDivElement>) => BadgeState;
-
-// @public
-export const useBreadcrumb: (props: BreadcrumbProps, ref: React_2.Ref<HTMLElement>) => BreadcrumbState;
-
-// @public
-export const useBreadcrumbButton: (props: BreadcrumbButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => BreadcrumbButtonState;
-
-// @public
-export const useBreadcrumbContext: () => BreadcrumbContextValues_2;
-
-// @public
-export const useBreadcrumbContextValues: (state: BreadcrumbState) => BreadcrumbContextValues;
-
-// @public
-export const useBreadcrumbDivider: (props: BreadcrumbDividerProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbDividerState;
-
-// @public
-export const useBreadcrumbItem: (props: BreadcrumbItemProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbItemState;
-
-// @public
-export const useButton: (props: ButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
-
-// @public
-export const useCheckbox: (props: CheckboxProps, ref: React_2.Ref<HTMLInputElement>) => CheckboxState;
-
-// @public
-export const useDivider: (props: DividerProps, ref: React_2.Ref<HTMLElement>) => DividerState;
-
-// @public
-export const useField: (props: FieldProps, ref: React_2.Ref<HTMLDivElement>) => FieldState;
-
-// @public
-export const useInput: (props: InputProps, ref: React_2.Ref<HTMLInputElement>) => InputState;
-
-// @public
-export const useLink: (props: LinkProps, ref: React_2.Ref<HTMLElement>) => LinkState;
-
-// @public
-export const useMessageBar: (props: MessageBarProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarState;
-
-// @public
-export const useMessageBarActions: (props: MessageBarActionsProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarActionsState;
-
-// @public
-export const useMessageBarActionsContextValues: () => MessageBarActionsContextValues;
-
-// @public
-export const useMessageBarBody: (props: MessageBarBodyProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarBodyState;
-
-// @public
-export const useMessageBarBodyContextValues: typeof useMessageBarBodyContextValues_unstable;
-
-// @public
-export const useMessageBarContext: () => MessageBarContextValue;
-
-// @public
-export const useMessageBarContextValues: (state: MessageBarState) => MessageBarContextValues;
-
-// @public
-export const useMessageBarTitle: (props: MessageBarTitleProps, ref: React_2.Ref<HTMLElement>) => MessageBarTitleState;
-
-// @public
-export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
-
-// @public
-export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
-
-// @public (undocumented)
-export const usePopoverContextValues: (state: PopoverState) => {
-    popover: PopoverContextValue;
-};
-
-// @public
-export const usePopoverSurface: (props: PopoverSurfaceProps, ref: React_2.Ref<HTMLDivElement>) => PopoverSurfaceState;
-
-// @public
-export const usePopoverTrigger: (props: PopoverTriggerProps) => PopoverTriggerState;
-
-// @public
-export const useProgressBar: (props: ProgressBarProps, ref: React_2.Ref<HTMLDivElement>) => ProgressBarState;
-
-// @public
-export const useRadio: (props: RadioProps, ref: React_2.Ref<HTMLInputElement>) => RadioState;
-
-// @public
-export const useRadioGroup: (props: RadioGroupProps, ref: React_2.Ref<HTMLDivElement>) => RadioGroupState;
-
-// @public
-export const useRating: (props: RatingProps, ref: React_2.Ref<HTMLDivElement>) => RatingState;
-
-// @public
-export const useRatingDisplay: (props: RatingDisplayProps, ref: React_2.Ref<HTMLDivElement>) => RatingDisplayState;
-
-// @public
-export const useRatingItem: (props: RatingItemProps, ref: React_2.Ref<HTMLSpanElement>) => RatingItemState;
-
-// @public
-export const useSearchBox: (props: SearchBoxProps, ref: React_2.Ref<HTMLInputElement>) => SearchBoxState;
-
-// @public
-export const useSelect: (props: SelectProps, ref: React_2.Ref<HTMLSelectElement>) => SelectState;
-
-// @public
-export const useSkeleton: (props: SkeletonProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonState;
-
-// @public
-export const useSkeletonItem: (props: SkeletonItemProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonItemState;
-
-// @public
-export const useSlider: (props: SliderProps, ref: React_2.Ref<HTMLInputElement>) => SliderState;
-
-// @public
-export const useSpinButton: (props: SpinButtonProps, ref: React_2.Ref<HTMLInputElement>) => SpinButtonState;
-
-// @public
-export const useSpinner: (props: SpinnerProps, ref: React_2.Ref<HTMLElement>) => SpinnerState;
-
-// @public
-export const useSwitch: (props: SwitchProps, ref: React_2.Ref<HTMLInputElement>) => SwitchState;
-
-// @public
-export const useTab: (props: TabProps, ref: React_2.Ref<HTMLElement>) => TabState;
-
-// @public
-export const useTabList: (props: TabListProps, ref: React_2.Ref<HTMLElement>) => TabListState;
-
-// @public
-export const useTextarea: (props: TextareaProps, ref: React_2.Ref<HTMLTextAreaElement>) => TextareaState;
-
-// @public
-export const useToggleButton: (props: ToggleButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ToggleButtonState;
-
-=======
-import type { AccordionBaseProps } from '@fluentui/react-accordion';
-import { AccordionBaseState } from '@fluentui/react-accordion';
-import { AccordionContextValue } from '@fluentui/react-accordion';
-import { AccordionContextValues as AccordionContextValues_2 } from '@fluentui/react-accordion';
-import type { AccordionHeaderBaseProps } from '@fluentui/react-accordion';
-import { AccordionHeaderBaseState } from '@fluentui/react-accordion';
-import { AccordionHeaderContextValues } from '@fluentui/react-accordion';
-import type { AccordionHeaderSlots as AccordionHeaderSlots_2 } from '@fluentui/react-accordion';
-import { AccordionItemContextValues } from '@fluentui/react-accordion';
-import type { AccordionItemProps as AccordionItemProps_2 } from '@fluentui/react-accordion';
-import type { AccordionItemSlots as AccordionItemSlots_2 } from '@fluentui/react-accordion';
-import { AccordionItemState as AccordionItemState_2 } from '@fluentui/react-accordion';
-import type { AccordionPanelBaseProps } from '@fluentui/react-accordion';
-import type { AccordionPanelBaseState } from '@fluentui/react-accordion';
-import type { AccordionPanelSlots as AccordionPanelSlots_2 } from '@fluentui/react-accordion';
-import type { AccordionSlots as AccordionSlots_2 } from '@fluentui/react-accordion';
-import type { AvatarBaseProps } from '@fluentui/react-avatar';
-import { AvatarBaseState } from '@fluentui/react-avatar';
-import type { BadgeBaseProps } from '@fluentui/react-badge';
-import { BadgeBaseState } from '@fluentui/react-badge';
-import type { BreadcrumbBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonBaseProps } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbButtonSlots as BreadcrumbButtonSlots_2 } from '@fluentui/react-breadcrumb';
-import { BreadcrumbContextValues as BreadcrumbContextValues_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbDividerBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbDividerBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbDividerSlots as BreadcrumbDividerSlots_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbItemBaseProps } from '@fluentui/react-breadcrumb';
-import { BreadcrumbItemBaseState } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbItemSlots as BreadcrumbItemSlots_2 } from '@fluentui/react-breadcrumb';
-import type { BreadcrumbSlots as BreadcrumbSlots_2 } from '@fluentui/react-breadcrumb';
-import type { ButtonBaseProps } from '@fluentui/react-button';
-import { ButtonBaseState } from '@fluentui/react-button';
-import type { ButtonSlots as ButtonSlots_2 } from '@fluentui/react-button';
-import type { CheckboxBaseProps } from '@fluentui/react-checkbox';
-import { CheckboxBaseState } from '@fluentui/react-checkbox';
-import type { CheckboxSlots as CheckboxSlots_2 } from '@fluentui/react-checkbox';
-import { ComponentProps } from '@fluentui/react-utilities';
-import type { ComponentState } from '@fluentui/react-utilities';
-import { ContextSelector } from '@fluentui/react-context-selector';
-import type { DividerBaseProps } from '@fluentui/react-divider';
-import { DividerBaseState } from '@fluentui/react-divider';
-import type { DividerSlots as DividerSlots_2 } from '@fluentui/react-divider';
-import type { EventData } from '@fluentui/react-utilities';
-import type { EventHandler } from '@fluentui/react-utilities';
-import type { FieldBaseProps } from '@fluentui/react-field';
-import { FieldBaseState } from '@fluentui/react-field';
-import { FieldContextValues } from '@fluentui/react-field';
-import type { FieldSlots as FieldSlots_2 } from '@fluentui/react-field';
-import type { ForwardRefComponent } from '@fluentui/react-utilities';
-import type { InputBaseProps } from '@fluentui/react-input';
-import { InputBaseState } from '@fluentui/react-input';
-import type { InputSlots as InputSlots_2 } from '@fluentui/react-input';
-import { JSXElement } from '@fluentui/react-utilities';
-import type { LinkBaseProps } from '@fluentui/react-link';
-import { LinkBaseState } from '@fluentui/react-link';
-import type { LinkSlots as LinkSlots_2 } from '@fluentui/react-link';
-import { MessageBarActionsContextValues as MessageBarActionsContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarActionsProps as MessageBarActionsProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarActionsSlots as MessageBarActionsSlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarActionsState as MessageBarActionsState_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBaseProps } from '@fluentui/react-message-bar';
-import { MessageBarBaseState } from '@fluentui/react-message-bar';
-import { MessageBarBodyContextValues as MessageBarBodyContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBodyProps as MessageBarBodyProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarBodySlots as MessageBarBodySlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarBodyState as MessageBarBodyState_2 } from '@fluentui/react-message-bar';
-import { MessageBarContextValue } from '@fluentui/react-message-bar';
-import { MessageBarContextValues as MessageBarContextValues_2 } from '@fluentui/react-message-bar';
-import type { MessageBarIntent } from '@fluentui/react-message-bar';
-import type { MessageBarSlots as MessageBarSlots_2 } from '@fluentui/react-message-bar';
-import type { MessageBarTitleProps as MessageBarTitleProps_2 } from '@fluentui/react-message-bar';
-import type { MessageBarTitleSlots as MessageBarTitleSlots_2 } from '@fluentui/react-message-bar';
-import { MessageBarTitleState as MessageBarTitleState_2 } from '@fluentui/react-message-bar';
-import type { ProgressBarBaseProps } from '@fluentui/react-progress';
-import type { ProgressBarBaseState } from '@fluentui/react-progress';
-import type { ProgressBarSlots as ProgressBarSlots_2 } from '@fluentui/react-progress';
-import type { RadioBaseProps } from '@fluentui/react-radio';
-import { RadioBaseState } from '@fluentui/react-radio';
-import type { RadioGroupBaseProps } from '@fluentui/react-radio';
-import { RadioGroupBaseState } from '@fluentui/react-radio';
-import { RadioGroupContextValues } from '@fluentui/react-radio';
-import type { RadioGroupSlots as RadioGroupSlots_2 } from '@fluentui/react-radio';
-import { RadioOnChangeData } from '@fluentui/react-radio';
-import { RadioSlots as RadioSlots_2 } from '@fluentui/react-radio';
-import type { RatingBaseProps } from '@fluentui/react-rating';
-import { RatingBaseState } from '@fluentui/react-rating';
-import { RatingContextValues } from '@fluentui/react-rating';
-import type { RatingDisplayBaseProps } from '@fluentui/react-rating';
-import { RatingDisplayBaseState } from '@fluentui/react-rating';
-import { RatingDisplayContextValues } from '@fluentui/react-rating';
-import type { RatingDisplaySlots as RatingDisplaySlots_2 } from '@fluentui/react-rating';
-import type { RatingItemBaseProps } from '@fluentui/react-rating';
-import { RatingItemBaseState } from '@fluentui/react-rating';
-import { RatingItemSlots as RatingItemSlots_2 } from '@fluentui/react-rating';
-import type { RatingSlots as RatingSlots_2 } from '@fluentui/react-rating';
-import * as React_2 from 'react';
-import type { SearchBoxBaseProps } from '@fluentui/react-search';
-import { SearchBoxBaseState } from '@fluentui/react-search';
-import type { SearchBoxSlots as SearchBoxSlots_2 } from '@fluentui/react-search';
-import type { SelectBaseProps } from '@fluentui/react-select';
-import { SelectBaseState } from '@fluentui/react-select';
-import type { SelectSlots as SelectSlots_2 } from '@fluentui/react-select';
-import { SkeletonBaseProps } from '@fluentui/react-skeleton';
-import { SkeletonBaseState } from '@fluentui/react-skeleton';
-import { SkeletonContextValues } from '@fluentui/react-skeleton';
-import { SkeletonItemBaseProps } from '@fluentui/react-skeleton';
-import { SkeletonItemBaseState } from '@fluentui/react-skeleton';
-import type { SkeletonItemSlots as SkeletonItemSlots_2 } from '@fluentui/react-skeleton';
-import type { SkeletonSlots as SkeletonSlots_2 } from '@fluentui/react-skeleton';
-import type { SliderBaseProps } from '@fluentui/react-slider';
-import { SliderBaseState } from '@fluentui/react-slider';
-import type { SliderSlots as SliderSlots_2 } from '@fluentui/react-slider';
-import type { Slot } from '@fluentui/react-utilities';
-import type { SpinButtonBaseProps } from '@fluentui/react-spinbutton';
-import { SpinButtonBaseState } from '@fluentui/react-spinbutton';
-import type { SpinButtonSlots as SpinButtonSlots_2 } from '@fluentui/react-spinbutton';
-import type { SpinnerBaseProps } from '@fluentui/react-spinner';
-import { SpinnerBaseState } from '@fluentui/react-spinner';
-import type { SpinnerSlots as SpinnerSlots_2 } from '@fluentui/react-spinner';
-import type { SwitchBaseProps } from '@fluentui/react-switch';
-import { SwitchBaseState } from '@fluentui/react-switch';
-import type { SwitchSlots as SwitchSlots_2 } from '@fluentui/react-switch';
-import type { TabBaseProps } from '@fluentui/react-tabs';
-import { TabBaseState } from '@fluentui/react-tabs';
-import type { TabListBaseProps } from '@fluentui/react-tabs';
-import { TabListBaseState } from '@fluentui/react-tabs';
-import { TabListContextValues } from '@fluentui/react-tabs';
-import type { TabListSlots as TabListSlots_2 } from '@fluentui/react-tabs';
-import { TabSlots } from '@fluentui/react-tabs';
-import { TabValue } from '@fluentui/react-tabs';
-import type { TextareaBaseProps } from '@fluentui/react-textarea';
-import { TextareaBaseState } from '@fluentui/react-textarea';
-import type { TextareaSlots as TextareaSlots_2 } from '@fluentui/react-textarea';
-import type { ToggleButtonBaseProps } from '@fluentui/react-button';
-import type { ToggleButtonBaseState } from '@fluentui/react-button';
-import { useMessageBarBodyContextValues_unstable } from '@fluentui/react-message-bar';
-
-// @public
-export const Accordion: ForwardRefComponent<AccordionProps>;
-
-// @public (undocumented)
-export type AccordionContextValues = AccordionContextValues_2;
-
-// @public
-export const AccordionHeader: ForwardRefComponent<AccordionHeaderProps>;
-
-// @public (undocumented)
-export type AccordionHeaderProps = AccordionHeaderBaseProps;
-
-// @public (undocumented)
-export type AccordionHeaderSlots = AccordionHeaderSlots_2;
-
-// @public (undocumented)
-export type AccordionHeaderState = AccordionHeaderBaseState & {
-    root: {
-        'data-open'?: string;
-        'data-disabled'?: string;
-        'data-expand-icon-position'?: string;
-    };
-};
-
-// @public
-export const AccordionItem: ForwardRefComponent<AccordionItemProps>;
-
-// @public (undocumented)
-export type AccordionItemProps = AccordionItemProps_2;
-
-// @public (undocumented)
-export type AccordionItemSlots = AccordionItemSlots_2;
-
-// @public (undocumented)
-export type AccordionItemState = AccordionItemState_2 & {
-    root: {
-        'data-disabled'?: string;
-        'data-open'?: string;
-    };
-};
-
-// @public
-export const AccordionPanel: ForwardRefComponent<AccordionPanelProps>;
-
-// @public (undocumented)
-export type AccordionPanelProps = AccordionPanelBaseProps;
-
-// @public (undocumented)
-export type AccordionPanelSlots = AccordionPanelSlots_2;
-
-// @public (undocumented)
-export type AccordionPanelState = AccordionPanelBaseState & {
-    root: {
-        'data-open'?: string;
-    };
-};
-
-// @public (undocumented)
-export type AccordionProps = AccordionBaseProps;
-
-// @public (undocumented)
-export type AccordionSlots = AccordionSlots_2;
-
-// @public (undocumented)
-export type AccordionState = AccordionBaseState & {
-    root: {
-        'data-collapsible'?: string;
-        'data-multiple'?: string;
-    };
-};
-
-// @public (undocumented)
-export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
-
-// @public
-export const Avatar: ForwardRefComponent<AvatarProps>;
-
-// @public
-export type AvatarProps = AvatarBaseProps;
-
-// @public
-export type AvatarState = AvatarBaseState;
-
-// @public
-export const Badge: ForwardRefComponent<BadgeProps>;
-
-// @public
-export type BadgeProps = BadgeBaseProps;
-
-// @public
-export type BadgeState = BadgeBaseState & {
-    root: {
-        'data-icon-position'?: 'before' | 'after';
-    };
-};
-
-// @public
-export const Breadcrumb: ForwardRefComponent<BreadcrumbProps>;
-
-// @public
-export const BreadcrumbButton: ForwardRefComponent<BreadcrumbButtonProps>;
-
-// @public
-export type BreadcrumbButtonProps = BreadcrumbButtonBaseProps;
-
-// @public
-export type BreadcrumbButtonSlots = BreadcrumbButtonSlots_2;
-
-// @public
-export type BreadcrumbButtonState = BreadcrumbButtonBaseState & {
-    root: {
-        'data-current'?: string;
-    };
-};
-
-// @public
-export type BreadcrumbContextValues = BreadcrumbContextValues_2;
-
-// @public
-export const BreadcrumbDivider: ForwardRefComponent<BreadcrumbDividerProps>;
-
-// @public
-export type BreadcrumbDividerProps = BreadcrumbDividerBaseProps;
-
-// @public
-export type BreadcrumbDividerSlots = BreadcrumbDividerSlots_2;
-
-// @public
-export type BreadcrumbDividerState = BreadcrumbDividerBaseState;
-
-// @public
-export const BreadcrumbItem: ForwardRefComponent<BreadcrumbItemProps>;
-
-// @public
-export type BreadcrumbItemProps = BreadcrumbItemBaseProps;
-
-// @public
-export type BreadcrumbItemSlots = BreadcrumbItemSlots_2;
-
-// @public
-export type BreadcrumbItemState = BreadcrumbItemBaseState;
-
-// @public
-export type BreadcrumbProps = BreadcrumbBaseProps;
-
-// @public
-export type BreadcrumbSlots = BreadcrumbSlots_2;
-
-// @public
-export type BreadcrumbState = BreadcrumbBaseState;
-
-// @public
-export const Button: ForwardRefComponent<ButtonProps>;
-
-// @public
-export type ButtonProps = ButtonBaseProps;
-
-// @public
-export type ButtonSlots = ButtonSlots_2;
-
-// @public
-export type ButtonState = ButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-icon-only'?: string;
-    };
-};
-
-// @public
-export const Checkbox: ForwardRefComponent<CheckboxProps>;
-
-// @public
-export type CheckboxProps = CheckboxBaseProps;
-
-// @public (undocumented)
-export type CheckboxSlots = CheckboxSlots_2;
-
-// @public
-export type CheckboxState = CheckboxBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const Divider: ForwardRefComponent<DividerProps>;
-
-// @public (undocumented)
-export type DividerProps = DividerBaseProps;
-
-// @public (undocumented)
-export type DividerSlots = DividerSlots_2;
-
-// @public (undocumented)
-export type DividerState = DividerBaseState & {
-    root: {
-        'data-orientation'?: 'vertical' | 'horizontal';
-    };
-};
-
-// @public
-export const Field: ForwardRefComponent<FieldProps>;
-
-// @public
-export type FieldProps = FieldBaseProps;
-
-// @public
-export type FieldSlots = FieldSlots_2;
-
-// @public
-export type FieldState = FieldBaseState & {
-    root: {
-        'data-validate-state'?: FieldBaseState['validationState'];
-    };
-};
-
-// @public
-export const Input: ForwardRefComponent<InputProps>;
-
-// @public
-export type InputProps = InputBaseProps;
-
-// @public
-export type InputSlots = InputSlots_2;
-
-// @public
-export type InputState = InputBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Link: ForwardRefComponent<LinkProps>;
-
-// @public
-export type LinkProps = LinkBaseProps;
-
-// @public
-export type LinkSlots = LinkSlots_2;
-
-// @public
-export type LinkState = LinkBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-    };
-};
-
-// @public
-export const MessageBar: ForwardRefComponent<MessageBarProps>;
-
-// @public
-export const MessageBarActions: ForwardRefComponent<MessageBarActionsProps>;
-
-// @public (undocumented)
-export type MessageBarActionsContextValues = MessageBarActionsContextValues_2;
-
-// @public (undocumented)
-export type MessageBarActionsProps = MessageBarActionsProps_2;
-
-// @public (undocumented)
-export type MessageBarActionsSlots = MessageBarActionsSlots_2;
-
-// @public (undocumented)
-export type MessageBarActionsState = MessageBarActionsState_2 & {
-    root: {
-        'data-layout'?: string;
-        'data-has-actions'?: string;
-    };
-};
-
-// @public
-export const MessageBarBody: ForwardRefComponent<MessageBarBodyProps>;
-
-// @public (undocumented)
-export type MessageBarBodyContextValues = MessageBarBodyContextValues_2;
-
-// @public (undocumented)
-export type MessageBarBodyProps = MessageBarBodyProps_2;
-
-// @public (undocumented)
-export type MessageBarBodySlots = MessageBarBodySlots_2;
-
-// @public (undocumented)
-export type MessageBarBodyState = MessageBarBodyState_2;
-
-// @public (undocumented)
-export type MessageBarContextValues = MessageBarContextValues_2;
-
-export { MessageBarIntent }
-
-// @public (undocumented)
-export type MessageBarProps = MessageBarBaseProps;
-
-// @public (undocumented)
-export type MessageBarSlots = MessageBarSlots_2;
-
-// @public (undocumented)
-export type MessageBarState = MessageBarBaseState & {
-    root: {
-        'data-layout'?: string;
-        'data-intent'?: string;
-    };
-};
-
-// @public
-export const MessageBarTitle: ForwardRefComponent<MessageBarTitleProps>;
-
-// @public (undocumented)
-export type MessageBarTitleProps = MessageBarTitleProps_2;
-
-// @public (undocumented)
-export type MessageBarTitleSlots = MessageBarTitleSlots_2;
-
-// @public (undocumented)
-export type MessageBarTitleState = MessageBarTitleState_2;
-
-// @public
-export type OnOpenChangeData = EventData<string, React_2.SyntheticEvent | Event> & {
-    open: boolean;
-};
-
-// @public
-export type OpenPopoverEvents = MouseEvent | TouchEvent | React_2.FocusEvent<HTMLElement> | React_2.KeyboardEvent<HTMLElement> | React_2.MouseEvent<HTMLElement>;
-
-// @public
-export const Popover: {
-    (props: PopoverProps): JSXElement;
-    displayName: string;
-};
-
-// @public
-export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
-    positioning: {
-        targetRef: React_2.RefCallback<HTMLElement>;
-        containerRef: React_2.RefCallback<HTMLElement>;
-    };
-};
-
-// @public
-export type PopoverProps = {
-    children: [JSXElement, JSXElement] | JSXElement;
-    open?: boolean;
-    defaultOpen?: boolean;
-    onOpenChange?: EventHandler<OnOpenChangeData>;
-    openOnHover?: boolean;
-    openOnContext?: boolean;
-    mouseLeaveDelay?: number;
-    positioning?: PositioningShorthand;
-    withArrow?: boolean;
-    disableAutoFocus?: boolean;
-    closeOnScroll?: boolean;
-    closeOnIframeFocus?: boolean;
-    inline?: boolean;
-    mountNode?: HTMLElement | null;
-};
-
-// @public
-export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pick<PopoverProps, 'onOpenChange' | 'openOnContext' | 'openOnHover' | 'withArrow' | 'disableAutoFocus' | 'mountNode'> & {
-    setOpen: (e: OpenPopoverEvents, open: boolean) => void;
-    toggleOpen: (e: OpenPopoverEvents) => void;
-    triggerRef: React_2.RefObject<HTMLElement | null>;
-    contentRef: React_2.RefObject<HTMLElement | null>;
-    arrowRef: React_2.RefObject<HTMLDivElement | null>;
-    popoverTrigger: React_2.ReactElement | undefined;
-    popoverSurface: React_2.ReactElement | undefined;
-    contextTarget: {
-        x: number;
-        y: number;
-    } | undefined;
-    setContextTarget: (target: {
-        x: number;
-        y: number;
-    } | undefined) => void;
-    positioning: PositioningReturn;
-};
-
-// @public
-export const PopoverSurface: ForwardRefComponent<PopoverSurfaceProps>;
-
-// @public (undocumented)
-export type PopoverSurfaceProps = ComponentProps<PopoverSurfaceSlots>;
-
-// @public
-export type PopoverSurfaceSlots = {
-    root: Slot<'div'>;
-};
-
-// @public (undocumented)
-export type PopoverSurfaceState = ComponentState<PopoverSurfaceSlots> & {
-    inline: boolean;
-    withArrow: boolean | undefined;
-    arrowRef: React_2.RefObject<HTMLDivElement | null>;
-    mountNode: HTMLElement | null | undefined;
-    'data-open': string;
-};
-
-// @public
-export const PopoverTrigger: React_2.FC<PopoverTriggerProps>;
-
-// @public
-export type PopoverTriggerProps = {
-    children: React_2.ReactElement;
-    disableButtonEnhancement?: boolean;
-};
-
-// @public
-export type PopoverTriggerState = {
-    children: React_2.ReactElement | null;
-};
-
-// @public (undocumented)
-export type Position = 'above' | 'below' | 'before' | 'after';
-
-// @public
-export type PositioningImperativeRef = {
-    setTarget: (target: HTMLElement | null) => void;
-    updatePosition: () => void;
-};
-
-// @public (undocumented)
-export type PositioningProps = {
-    position?: Position;
-    align?: Alignment;
-    offset?: number | {
-        mainAxis?: number;
-        crossAxis?: number;
-    };
-    fallbackPositions?: PositioningShorthandValue[];
-    coverTarget?: boolean;
-    target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
-    strategy?: 'absolute' | 'fixed';
-    matchTargetSize?: 'width';
-    pinned?: boolean;
-    positioningRef?: React_2.Ref<PositioningImperativeRef>;
-    overflowBoundary?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
-};
-
-// @public (undocumented)
-export type PositioningReturn = {
-    targetRef: React_2.RefCallback<HTMLElement>;
-    containerRef: React_2.RefCallback<HTMLElement>;
-};
-
-// @public (undocumented)
-export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
-
-// @public (undocumented)
-export type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-start' | 'before-end' | 'after' | 'after-start' | 'after-end';
-
-// @public
-export const ProgressBar: ForwardRefComponent<ProgressBarProps>;
-
-// @public
-export type ProgressBarProps = ProgressBarBaseProps;
-
-// @public (undocumented)
-export type ProgressBarSlots = ProgressBarSlots_2;
-
-// @public
-export type ProgressBarState = ProgressBarBaseState;
-
-// @public
-export const Radio: React_2.ForwardRefExoticComponent<Omit<ComponentProps<Partial<RadioSlots_2>, "input">, "onChange" | "size"> & {
-    value?: string;
-    labelPosition?: "after" | "below";
-    disabled?: boolean;
-    onChange?: (ev: React_2.ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void;
-} & React_2.RefAttributes<HTMLInputElement>>;
-
-// @public
-export const RadioGroup: ForwardRefComponent<RadioGroupProps>;
-
-// @public
-export type RadioGroupProps = RadioGroupBaseProps;
-
-// @public
-export type RadioGroupSlots = RadioGroupSlots_2;
-
-// @public
-export type RadioGroupState = RadioGroupBaseState;
-
-// @public
-export type RadioProps = RadioBaseProps;
-
-// @public
-export type RadioSlots = RadioSlots_2;
-
-// @public
-export type RadioState = RadioBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Rating: ForwardRefComponent<RatingProps>;
-
-// @public
-export const RatingDisplay: ForwardRefComponent<RatingDisplayProps>;
-
-// @public
-export type RatingDisplayProps = RatingDisplayBaseProps;
-
-// @public
-export type RatingDisplaySlots = RatingDisplaySlots_2;
-
-// @public
-export type RatingDisplayState = RatingDisplayBaseState;
-
-// @public
-export const RatingItem: React_2.ForwardRefExoticComponent<Omit<Partial<RatingItemSlots_2>, "root"> & Omit<{
-    as?: "span" | undefined;
-} & Omit<React_2.DetailedHTMLProps<React_2.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "children"> & {
-    children?: any;
-}, "ref"> & {
-    value?: number;
-} & React_2.RefAttributes<HTMLSpanElement>>;
-
-// @public
-export type RatingItemProps = RatingItemBaseProps;
-
-// @public
-export type RatingItemSlots = RatingItemSlots_2;
-
-// @public
-export type RatingItemState = RatingItemBaseState & {
-    root: {
-        'data-appearance'?: 'filled' | 'filled-half' | 'outline';
-    };
-};
-
-// @public
-export type RatingProps = RatingBaseProps;
-
-// @public
-export type RatingSlots = RatingSlots_2;
-
-// @public
-export type RatingState = RatingBaseState;
-
-// @public
-export const renderAccordion: (state: AccordionBaseState, contextValues: AccordionContextValues_2) => JSXElement;
-
-// @public
-export const renderAccordionHeader: (state: AccordionHeaderBaseState, contextValues: AccordionHeaderContextValues) => JSXElement;
-
-// @public
-export const renderAccordionItem: (state: AccordionItemState_2, contextValues: AccordionItemContextValues) => JSXElement;
-
-// @public
-export const renderAccordionPanel: (state: AccordionPanelState) => JSXElement;
-
-// @public
-export const renderAvatar: (state: AvatarBaseState) => JSXElement;
-
-// @public
-export const renderBadge: (state: BadgeBaseState) => JSXElement;
-
-// @public
-export const renderBreadcrumb: (state: BreadcrumbBaseState, contextValues: BreadcrumbContextValues_2) => JSXElement;
-
-// @public
-export const renderBreadcrumbButton: (state: BreadcrumbButtonState) => JSXElement;
-
-// @public
-export const renderBreadcrumbDivider: (state: BreadcrumbDividerBaseState) => JSXElement;
-
-// @public
-export const renderBreadcrumbItem: (state: BreadcrumbItemBaseState) => JSXElement;
-
-// @public
-export const renderButton: (state: ButtonBaseState) => JSXElement;
-
-// @public
-export const renderCheckbox: (state: CheckboxBaseState) => JSXElement;
-
-// @public
-export const renderDivider: (state: DividerBaseState) => JSXElement;
-
-// @public
-export const renderField: (state: FieldBaseState, contextValues: FieldContextValues) => JSXElement;
-
-// @public
-export const renderInput: (state: InputBaseState) => JSXElement;
-
-// @public
-export const renderLink: (state: LinkBaseState) => JSXElement;
-
-// @public
-export const renderMessageBar: (state: MessageBarBaseState, contexts: MessageBarContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarActions: (state: MessageBarActionsState_2, contexts: MessageBarActionsContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarBody: (state: MessageBarBodyState_2, contextValues: MessageBarBodyContextValues_2) => JSXElement;
-
-// @public
-export const renderMessageBarTitle: (state: MessageBarTitleState_2) => JSXElement;
-
-// @public
-export const renderPopover: (state: PopoverState, contextValues: {
-    popover: PopoverContextValue;
-}) => React_2.ReactElement;
-
-// @public
-export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
-
-// @public
-export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
-
-// @public
-export const renderProgressBar: (state: ProgressBarState) => JSXElement;
-
-// @public
-export const renderRadio: (state: RadioBaseState) => JSXElement;
-
-// @public
-export const renderRadioGroup: (state: RadioGroupBaseState, contextValues: RadioGroupContextValues) => JSXElement;
-
-// @public
-export const renderRating: (state: RatingBaseState, contextValues: RatingContextValues) => JSXElement;
-
-// @public
-export const renderRatingDisplay: (state: RatingDisplayBaseState, contextValues: RatingDisplayContextValues) => JSXElement;
-
-// @public
-export const renderRatingItem: (state: RatingItemBaseState) => JSXElement;
-
-// @public
-export const renderSearchBox: (state: SearchBoxBaseState) => JSXElement;
-
-// @public
-export const renderSelect: (state: SelectBaseState) => JSXElement;
-
-// @public
-export const renderSkeleton: (state: SkeletonBaseState, contextValues: SkeletonContextValues) => JSXElement;
-
-// @public
-export const renderSkeletonItem: (state: SkeletonItemBaseState) => JSXElement;
-
-// @public
-export const renderSlider: (state: SliderBaseState) => JSXElement;
-
-// @public
-export const renderSpinButton: (state: SpinButtonBaseState) => JSXElement;
-
-// @public
-export const renderSpinner: (state: SpinnerBaseState) => JSXElement;
-
-// @public
-export const renderSwitch: (state: SwitchBaseState) => JSXElement;
-
-// @public
-export const renderTab: (state: TabBaseState) => JSXElement;
-
-// @public
-export const renderTabList: (state: TabListBaseState, contextValues: TabListContextValues) => JSXElement;
-
-// @public
-export const renderTextarea: (state: TextareaBaseState) => JSXElement;
-
-// @public
-export const renderToggleButton: (state: ButtonBaseState) => JSXElement;
-
-// @public
-export const SearchBox: ForwardRefComponent<SearchBoxProps>;
-
-// @public
-export type SearchBoxProps = SearchBoxBaseProps;
-
-// @public
-export type SearchBoxSlots = SearchBoxSlots_2;
-
-// @public
-export type SearchBoxState = SearchBoxBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-focused'?: string;
-    };
-};
-
-// @public
-export const Select: ForwardRefComponent<SelectProps>;
-
-// @public
-export type SelectProps = SelectBaseProps;
-
-// @public (undocumented)
-export type SelectSlots = SelectSlots_2;
-
-// @public
-export type SelectState = SelectBaseState & {
-    root: {
-        'data-disabled'?: string;
-    };
-};
-
-// @public
-export const Skeleton: React_2.ForwardRefExoticComponent<SkeletonBaseProps & React_2.RefAttributes<HTMLDivElement>>;
-
-// @public
-export const SkeletonItem: React_2.ForwardRefExoticComponent<SkeletonItemBaseProps & React_2.RefAttributes<HTMLDivElement>>;
-
-// @public
-export type SkeletonItemProps = SkeletonItemBaseProps;
-
-// @public
-export type SkeletonItemSlots = SkeletonItemSlots_2;
-
-// @public
-export type SkeletonItemState = SkeletonItemBaseState;
-
-// @public
-export type SkeletonProps = SkeletonBaseProps;
-
-// @public
-export type SkeletonSlots = SkeletonSlots_2;
-
-// @public
-export type SkeletonState = SkeletonBaseState;
-
-// @public
-export const Slider: ForwardRefComponent<SliderProps>;
-
-// @public
-export type SliderProps = SliderBaseProps;
-
-// @public
-export type SliderSlots = SliderSlots_2;
-
-// @public
-export type SliderState = SliderBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-vertical'?: string;
-    };
-};
-
-// @public
-export const SpinButton: ForwardRefComponent<SpinButtonProps>;
-
-// @public
-export type SpinButtonProps = SpinButtonBaseProps;
-
-// @public
-export type SpinButtonSlots = SpinButtonSlots_2;
-
-// @public
-export type SpinButtonState = SpinButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-spin-state'?: string;
-        'data-at-bound'?: string;
-    };
-};
-
-// @public
-export const Spinner: ForwardRefComponent<SpinnerProps>;
-
-// @public
-export type SpinnerProps = SpinnerBaseProps;
-
-// @public
-export type SpinnerSlots = SpinnerSlots_2;
-
-// @public
-export type SpinnerState = SpinnerBaseState & {
-    root: {
-        'data-label-position'?: 'before' | 'after' | 'above' | 'below';
-    };
-};
-
-// @public
-export const Switch: ForwardRefComponent<SwitchProps>;
-
-// @public
-export type SwitchProps = SwitchBaseProps;
-
-// @public
-export type SwitchSlots = SwitchSlots_2;
-
-// @public
-export type SwitchState = SwitchBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const Tab: ForwardRefComponent<TabProps>;
-
-// @public
-export const TabList: ForwardRefComponent<TabListProps>;
-
-// @public
-export type TabListProps = TabListBaseProps;
-
-// @public
-export type TabListSlots = TabListSlots_2;
-
-// @public
-export type TabListState = TabListBaseState & {
-    root: {
-        focusgroup?: string;
-        'data-orientation'?: 'vertical' | 'horizontal';
-    };
-};
-
-// @public (undocumented)
-export type TabProps = TabBaseProps;
-
-export { TabSlots }
-
-// @public (undocumented)
-export type TabState = TabBaseState & {
-    root: {
-        focusgroupstart?: string;
-        'data-icon-only'?: string;
-        'data-selected'?: string;
-    };
-};
-
-export { TabValue }
-
-// @public
-export const Textarea: ForwardRefComponent<TextareaProps>;
-
-// @public
-export type TextareaProps = TextareaBaseProps;
-
-// @public
-export type TextareaSlots = TextareaSlots_2;
-
-// @public
-export type TextareaState = TextareaBaseState;
-
-// @public
-export const ToggleButton: ForwardRefComponent<ToggleButtonProps>;
-
-// @public
-export type ToggleButtonProps = ToggleButtonBaseProps;
-
-// @public
-export type ToggleButtonSlots = ButtonSlots;
-
-// @public
-export type ToggleButtonState = ToggleButtonBaseState & {
-    root: {
-        'data-disabled'?: string;
-        'data-disabled-focusable'?: string;
-        'data-icon-only'?: string;
-        'data-checked'?: string;
-    };
-};
-
-// @public
-export const useAccordion: (props: AccordionProps, ref: React_2.Ref<HTMLElement>) => AccordionState;
-
-// @public
-export const useAccordionContext: <T>(selector: ContextSelector<AccordionContextValue, T>) => T;
-
-// @public
-export const useAccordionContextValues: (state: AccordionState) => AccordionContextValues;
-
-// @public
-export const useAccordionHeader: (props: AccordionHeaderProps, ref: React_2.Ref<HTMLElement>) => AccordionHeaderState;
-
-// @public
-export const useAccordionItem: (props: AccordionItemProps, ref: React_2.Ref<HTMLElement>) => AccordionItemState;
-
-// @public
-export const useAccordionPanel: (props: AccordionPanelProps, ref: React_2.Ref<HTMLElement>) => AccordionPanelState;
-
-// @public
-export const useAvatar: (props: AvatarProps, ref: React_2.Ref<HTMLElement>) => AvatarState;
-
-// @public
-export const useBadge: (props: BadgeProps, ref: React_2.Ref<HTMLDivElement>) => BadgeState;
-
-// @public
-export const useBreadcrumb: (props: BreadcrumbProps, ref: React_2.Ref<HTMLElement>) => BreadcrumbState;
-
-// @public
-export const useBreadcrumbButton: (props: BreadcrumbButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => BreadcrumbButtonState;
-
-// @public
-export const useBreadcrumbContext: () => BreadcrumbContextValues_2;
-
-// @public
-export const useBreadcrumbContextValues: (state: BreadcrumbState) => BreadcrumbContextValues;
-
-// @public
-export const useBreadcrumbDivider: (props: BreadcrumbDividerProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbDividerState;
-
-// @public
-export const useBreadcrumbItem: (props: BreadcrumbItemProps, ref: React_2.Ref<HTMLLIElement>) => BreadcrumbItemState;
-
-// @public
-export const useButton: (props: ButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
-
-// @public
-export const useCheckbox: (props: CheckboxProps, ref: React_2.Ref<HTMLInputElement>) => CheckboxState;
-
-// @public
-export const useDivider: (props: DividerProps, ref: React_2.Ref<HTMLElement>) => DividerState;
-
-// @public
-export const useField: (props: FieldProps, ref: React_2.Ref<HTMLDivElement>) => FieldState;
-
-// @public
-export const useInput: (props: InputProps, ref: React_2.Ref<HTMLInputElement>) => InputState;
-
-// @public
-export const useLink: (props: LinkProps, ref: React_2.Ref<HTMLElement>) => LinkState;
-
-// @public
-export const useMessageBar: (props: MessageBarProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarState;
-
-// @public
-export const useMessageBarActions: (props: MessageBarActionsProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarActionsState;
-
-// @public
-export const useMessageBarActionsContextValues: () => MessageBarActionsContextValues;
-
-// @public
-export const useMessageBarBody: (props: MessageBarBodyProps, ref: React_2.Ref<HTMLDivElement>) => MessageBarBodyState;
-
-// @public
-export const useMessageBarBodyContextValues: typeof useMessageBarBodyContextValues_unstable;
-
-// @public
-export const useMessageBarContext: () => MessageBarContextValue;
-
-// @public
-export const useMessageBarContextValues: (state: MessageBarState) => MessageBarContextValues;
-
-// @public
-export const useMessageBarTitle: (props: MessageBarTitleProps, ref: React_2.Ref<HTMLElement>) => MessageBarTitleState;
-
-// @public
-export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
-
-// @public
-export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
-
-// @public (undocumented)
-export const usePopoverContextValues: (state: PopoverState) => {
-    popover: PopoverContextValue;
-};
-
-// @public
-export const usePopoverSurface: (props: PopoverSurfaceProps, ref: React_2.Ref<HTMLDivElement>) => PopoverSurfaceState;
-
-// @public
-export const usePopoverTrigger: (props: PopoverTriggerProps) => PopoverTriggerState;
-
-// @public
-export const useProgressBar: (props: ProgressBarProps, ref: React_2.Ref<HTMLDivElement>) => ProgressBarState;
-
-// @public
-export const useRadio: (props: RadioProps, ref: React_2.Ref<HTMLInputElement>) => RadioState;
-
-// @public
-export const useRadioGroup: (props: RadioGroupProps, ref: React_2.Ref<HTMLDivElement>) => RadioGroupState;
-
-// @public
-export const useRating: (props: RatingProps, ref: React_2.Ref<HTMLDivElement>) => RatingState;
-
-// @public
-export const useRatingDisplay: (props: RatingDisplayProps, ref: React_2.Ref<HTMLDivElement>) => RatingDisplayState;
-
-// @public
-export const useRatingItem: (props: RatingItemProps, ref: React_2.Ref<HTMLSpanElement>) => RatingItemState;
-
-// @public
-export const useSearchBox: (props: SearchBoxProps, ref: React_2.Ref<HTMLInputElement>) => SearchBoxState;
-
-// @public
-export const useSelect: (props: SelectProps, ref: React_2.Ref<HTMLSelectElement>) => SelectState;
-
-// @public
-export const useSkeleton: (props: SkeletonProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonState;
-
-// @public
-export const useSkeletonItem: (props: SkeletonItemProps, ref: React_2.Ref<HTMLDivElement>) => SkeletonItemState;
-
-// @public
-export const useSlider: (props: SliderProps, ref: React_2.Ref<HTMLInputElement>) => SliderState;
-
-// @public
-export const useSpinButton: (props: SpinButtonProps, ref: React_2.Ref<HTMLInputElement>) => SpinButtonState;
-
-// @public
-export const useSpinner: (props: SpinnerProps, ref: React_2.Ref<HTMLElement>) => SpinnerState;
-
-// @public
-export const useSwitch: (props: SwitchProps, ref: React_2.Ref<HTMLInputElement>) => SwitchState;
-
-// @public
-export const useTab: (props: TabProps, ref: React_2.Ref<HTMLElement>) => TabState;
-
-// @public
-export const useTabList: (props: TabListProps, ref: React_2.Ref<HTMLElement>) => TabListState;
-
-// @public
-export const useTextarea: (props: TextareaProps, ref: React_2.Ref<HTMLTextAreaElement>) => TextareaState;
-
-// @public
-export const useToggleButton: (props: ToggleButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ToggleButtonState;
-
->>>>>>> 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
 // (No @packageDocumentation comment for this package)
 
 ```
diff --git a/packages/react-components/react-headless-components-preview/library/package.json b/packages/react-components/react-headless-components-preview/library/package.json
index 552e5e6061c43f..06dff721d7e46f 100644
--- a/packages/react-components/react-headless-components-preview/library/package.json
+++ b/packages/react-components/react-headless-components-preview/library/package.json
@@ -135,6 +135,18 @@
       "import": "./lib/message-bar.js",
       "require": "./lib-commonjs/message-bar.js"
     },
+    "./popover": {
+      "types": "./dist/popover.d.ts",
+      "node": "./lib-commonjs/popover.js",
+      "import": "./lib/popover.js",
+      "require": "./lib-commonjs/popover.js"
+    },
+    "./positioning": {
+      "types": "./dist/positioning.d.ts",
+      "node": "./lib-commonjs/positioning.js",
+      "import": "./lib/positioning.js",
+      "require": "./lib-commonjs/positioning.js"
+    },
     "./progress-bar": {
       "types": "./dist/progress-bar.d.ts",
       "node": "./lib-commonjs/progress-bar.js",
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
deleted file mode 100644
index 14bbafd814b9b7..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/index.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-export { usePositioning } from './usePositioning';
-export type {
-  Position,
-  Alignment,
-  PositioningProps,
-  PositioningReturn,
-  PositioningImperativeRef,
-  PositioningShorthand,
-  PositioningShorthandValue,
-} from './usePositioning';
-export { POSITIONS, ALIGNMENTS, getPlacementString, resolvePositioningShorthand } from './usePositioning';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
deleted file mode 100644
index 082b2365a68b62..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/constants.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import type { LogicalAlignment, Position } from './types';
-
-export const GAP = 8;
-
-export const POSITIONS = {
-  above: 'above',
-  below: 'below',
-  before: 'before',
-  after: 'after',
-} as const;
-
-export const ALIGNMENTS = {
-  start: 'start',
-  center: 'center',
-  end: 'end',
-} as const;
-
-export const POSITION_AREA_MAP: Record<Position, Record<LogicalAlignment, string>> = {
-  above: {
-    center: 'block-start',
-    start: 'block-start span-inline-end',
-    end: 'block-start span-inline-start',
-  },
-  below: {
-    center: 'block-end',
-    start: 'block-end span-inline-end',
-    end: 'block-end span-inline-start',
-  },
-  before: {
-    center: 'inline-start',
-    start: 'inline-start span-block-end',
-    end: 'inline-start span-block-start',
-  },
-  after: {
-    center: 'inline-end',
-    start: 'inline-end span-block-end',
-    end: 'inline-end span-block-start',
-  },
-};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
deleted file mode 100644
index b624fb8c4170a2..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/index.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-export { usePositioning } from './usePositioning';
-export { getPlacementString, resolvePositioningShorthand } from './utils';
-export { POSITIONS, ALIGNMENTS } from './constants';
-export type {
-  Position,
-  Alignment,
-  PositioningProps,
-  PositioningReturn,
-  PositioningImperativeRef,
-  PositioningShorthand,
-  PositioningShorthandValue,
-} from './types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
deleted file mode 100644
index e7168495805b99..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/types.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import type * as React from 'react';
-import type { PositioningProps } from '../../hooks/usePositioning';
-
-export type Position = 'above' | 'below' | 'before' | 'after';
-export type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
-export type LogicalAlignment = 'start' | 'center' | 'end';
-
-/**
- * Imperative API exposed via `PositioningProps.positioningRef`.
- */
-export type PositioningImperativeRef = {
-  /** Retarget the surface to the given element (or clear the target with `null`). */
-  setTarget: (target: HTMLElement | null) => void;
-  /** Request a position recomputation. With CSS anchor positioning layout is automatic, so this is a no-op on supporting browsers. */
-  updatePosition: () => void;
-};
-
-export type PositioningShorthandValue =
-  | 'above'
-  | 'above-start'
-  | 'above-end'
-  | 'below'
-  | 'below-start'
-  | 'below-end'
-  | 'before'
-  | 'before-start'
-  | 'before-end'
-  | 'after'
-  | 'after-start'
-  | 'after-end';
-
-export type PositioningProps = {
-  /**
-   * @default 'above'
-   */
-  position?: Position;
-  /**
-   * @default 'center'
-   */
-  align?: Alignment;
-  /** Offset from the anchor element */
-  offset?: number | { mainAxis?: number; crossAxis?: number };
-  /**
-   * Fallback placements tried in order when the primary placement would
-   * overflow the viewport. Accepts shorthand strings like `'below-start'`.
-   * When omitted, the default is the native `flip-block, flip-inline`
-   * fallback chain.
-   */
-  fallbackPositions?: PositioningShorthandValue[];
-  /** Position on top of the target */
-  coverTarget?: boolean;
-  /**
-   * Custom anchor element for the positioned surface. When provided, the
-   * anchor-name is written to this element instead of the target assigned via
-   * the returned `targetRef`. Accepts a DOM element or a RefObject.
-   */
-  target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
-  /**
-   * CSS `position` value used on the positioned surface. Matches v9's default.
-   * @default 'absolute'
-   */
-  strategy?: 'absolute' | 'fixed';
-  /**
-   * Makes the surface match one of the trigger's dimensions. Currently only
-   * `'width'` is supported; the surface's `width` is set via CSS
-   * `anchor-size(width)`.
-   */
-  matchTargetSize?: 'width';
-  /**
-   * When true the surface stays at its requested placement even if it overflows
-   * the viewport (no `flip` fallback). Useful for menus or tooltips that must
-   * not switch sides unexpectedly.
-   * @default false
-   */
-  pinned?: boolean;
-  /**
-   * Imperative handle for programmatically retargeting the surface or
-   * triggering a position update. See {@link PositioningImperativeRef}.
-   */
-  positioningRef?: React.Ref<PositioningImperativeRef>;
-};
-
-export type PositioningShorthand = PositioningProps | PositioningShorthandValue;
-
-export type PositioningReturn = {
-  targetRef: React.RefCallback<HTMLElement>;
-  containerRef: React.RefCallback<HTMLElement>;
-};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
deleted file mode 100644
index 69320196b42b0a..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePlacementObserver.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-'use client';
-
-import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
-import type { LogicalAlignment, Position } from './types';
-import { ALIGNMENTS, POSITIONS } from './constants';
-import { getPlacementString } from './utils/placement';
-
-const PLACEMENT_TOLERANCE = 2;
-
-const closeTo = (a: number, b: number): boolean => Math.abs(a - b) <= PLACEMENT_TOLERANCE;
-
-function detectPosition(surfaceRect: DOMRect, targetRect: DOMRect): Position | null {
-  if (surfaceRect.bottom <= targetRect.top + PLACEMENT_TOLERANCE) {
-    return POSITIONS.above;
-  }
-
-  if (surfaceRect.top >= targetRect.bottom - PLACEMENT_TOLERANCE) {
-    return POSITIONS.below;
-  }
-
-  if (surfaceRect.right <= targetRect.left + PLACEMENT_TOLERANCE) {
-    return POSITIONS.before;
-  }
-
-  if (surfaceRect.left >= targetRect.right - PLACEMENT_TOLERANCE) {
-    return POSITIONS.after;
-  }
-
-  return null;
-}
-
-function detectAlign(position: Position, surfaceRect: DOMRect, targetRect: DOMRect): LogicalAlignment {
-  const isBlockMain = position === POSITIONS.above || position === POSITIONS.below;
-
-  const startAligned = isBlockMain
-    ? closeTo(surfaceRect.left, targetRect.left)
-    : closeTo(surfaceRect.top, targetRect.top);
-
-  if (startAligned) {
-    return ALIGNMENTS.start;
-  }
-
-  const endAligned = isBlockMain
-    ? closeTo(surfaceRect.right, targetRect.right)
-    : closeTo(surfaceRect.bottom, targetRect.bottom);
-
-  if (endAligned) {
-    return ALIGNMENTS.end;
-  }
-
-  return ALIGNMENTS.center;
-}
-
-/**
- * Pure-observation hook: reads the rendered rects of the surface and anchor
- * and mirrors the resolved placement into the surface's `data-placement`
- * attribute. This keeps the attribute in sync with the browser's decision
- * after native flip fires (scroll, resize, ResizeObserver tick).
- *
- */
-export function usePlacementObserver(
-  containerEl: HTMLElement | null,
-  targetEl: HTMLElement | null,
-  targetDocument: Document | undefined,
-  disabled = false,
-): void {
-  useIsomorphicLayoutEffect(() => {
-    if (disabled || !containerEl || !targetEl) {
-      return;
-    }
-
-    const win = targetDocument?.defaultView;
-
-    if (!win) {
-      return;
-    }
-
-    const update = () => {
-      const surfaceRect = containerEl.getBoundingClientRect();
-      const targetRect = targetEl.getBoundingClientRect();
-      const position = detectPosition(surfaceRect, targetRect);
-
-      if (!position) {
-        return;
-      }
-
-      const align = detectAlign(position, surfaceRect, targetRect);
-      const next = getPlacementString(position, align);
-
-      if (containerEl.getAttribute('data-placement') !== next) {
-        containerEl.setAttribute('data-placement', next);
-      }
-    };
-
-    update();
-
-    const ResizeObserverCtor = win.ResizeObserver;
-    const observer = ResizeObserverCtor ? new ResizeObserverCtor(update) : null;
-    observer?.observe(containerEl);
-    observer?.observe(targetEl);
-    win.addEventListener('scroll', update, true);
-    win.addEventListener('resize', update);
-
-    return () => {
-      observer?.disconnect();
-      win.removeEventListener('scroll', update, true);
-      win.removeEventListener('resize', update);
-    };
-  }, [containerEl, targetEl, targetDocument, disabled]);
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
deleted file mode 100644
index 31018f373c2d63..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.test.tsx
+++ /dev/null
@@ -1,159 +0,0 @@
-import * as React from 'react';
-import { act, render } from '@testing-library/react';
-import { usePositioning } from './usePositioning';
-import { getPlacementString } from './utils/placement';
-import type { PositioningProps, PositioningReturn } from './types';
-
-function mountHook(options: PositioningProps = {}) {
-  const resultRef = React.createRef<{ current: PositioningReturn }>();
-  const Capture = () => {
-    const result = usePositioning(options);
-    (resultRef as unknown as { current: PositioningReturn }).current = result;
-    return null;
-  };
-  render(<Capture />);
-  return resultRef as unknown as { current: PositioningReturn };
-}
-
-describe('usePositioning', () => {
-  it('returns targetRef and containerRef callbacks', () => {
-    const result = mountHook();
-
-    expect(typeof result.current.targetRef).toBe('function');
-    expect(typeof result.current.containerRef).toBe('function');
-  });
-
-  it('targetRef writes anchor-name onto the trigger element', () => {
-    const result = mountHook();
-    const node = document.createElement('div');
-
-    act(() => {
-      result.current.targetRef(node);
-    });
-
-    expect(node.style.getPropertyValue('anchor-name')).toMatch(/^--popover-anchor-/);
-  });
-
-  it('containerRef writes position-anchor and position-area matching the props', () => {
-    const result = mountHook({ position: 'below', align: 'start' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
-    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
-  });
-
-  it('containerRef writes position: absolute by default and clears the UA inset/margin defaults', () => {
-    const result = mountHook();
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.position).toBe('absolute');
-    expect(node.style.inset).toBe('auto');
-    expect(node.style.margin).toBe('0px');
-  });
-
-  it('containerRef honors strategy: "fixed"', () => {
-    const result = mountHook({ strategy: 'fixed' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.position).toBe('fixed');
-  });
-
-  it('containerRef writes data-placement matching (position, align)', () => {
-    const result = mountHook({ position: 'below', align: 'start' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.getAttribute('data-placement')).toBe('below-start');
-  });
-
-  it('containerRef sets position-try-fallbacks to the three-try flip chain by default', () => {
-    const result = mountHook();
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe(
-      'flip-block, flip-inline, flip-block flip-inline',
-    );
-  });
-
-  it('containerRef uses custom fallbackPositions verbatim when provided', () => {
-    const result = mountHook({ fallbackPositions: ['below-start', 'after'] });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('block-end span-inline-end, inline-end');
-  });
-
-  it('containerRef removes position-try-fallbacks when pinned', () => {
-    const result = mountHook({ pinned: true });
-    const node = document.createElement('div');
-    node.style.setProperty('position-try-fallbacks', 'flip-block');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('');
-  });
-
-  it('containerRef writes cover self-alignment when coverTarget is true', () => {
-    const result = mountHook({ coverTarget: true, position: 'above', align: 'start' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('position-area')).toBe('center');
-    expect(node.style.getPropertyValue('align-self')).toBe('end');
-    expect(node.style.getPropertyValue('justify-self')).toBe('start');
-  });
-
-  it('containerRef writes place-self: anchor-center for center alignment (crbug 438334710 workaround)', () => {
-    const result = mountHook({ position: 'above', align: 'center' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('place-self')).toBe('anchor-center');
-  });
-
-  it('containerRef does not write place-self for non-center alignments', () => {
-    const result = mountHook({ position: 'above', align: 'start' });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.getPropertyValue('place-self')).toBe('');
-    expect(node.style.getPropertyValue('justify-self')).toBe('');
-    expect(node.style.getPropertyValue('align-self')).toBe('');
-  });
-
-  it('containerRef writes matchTargetSize width via anchor-size()', () => {
-    const result = mountHook({ matchTargetSize: 'width' });
-    const node = document.createElement('div');
-    const spy = jest.spyOn(node.style, 'setProperty');
-    result.current.containerRef(node);
-
-    expect(spy).toHaveBeenCalledWith('width', 'anchor-size(width)');
-    spy.mockRestore();
-  });
-
-  it('containerRef applies offset as logical margins', () => {
-    const result = mountHook({ position: 'below', offset: { mainAxis: 8, crossAxis: 4 } });
-    const node = document.createElement('div');
-    result.current.containerRef(node);
-
-    expect(node.style.marginBlockStart).toBe('8px');
-    expect(node.style.marginInlineStart).toBe('4px');
-  });
-});
-
-describe('getPlacementString', () => {
-  it('returns the bare position for center alignment', () => {
-    expect(getPlacementString('above', 'center')).toBe('above');
-    expect(getPlacementString('below', 'center')).toBe('below');
-  });
-
-  it('returns position-align for non-center alignments', () => {
-    expect(getPlacementString('above', 'start')).toBe('above-start');
-    expect(getPlacementString('below', 'end')).toBe('below-end');
-    expect(getPlacementString('before', 'start')).toBe('before-start');
-    expect(getPlacementString('after', 'end')).toBe('after-end');
-  });
-});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
deleted file mode 100644
index 7b4508cb563e71..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/usePositioning.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-'use client';
-
-import * as React from 'react';
-import { useId, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
-import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
-import type { PositioningImperativeRef, PositioningProps, PositioningReturn } from './types';
-import { POSITIONS, ALIGNMENTS, POSITION_AREA_MAP } from './constants';
-import { getPlacementString, normalizeAlign } from './utils/placement';
-import { applyOffset, getCoverSelfAlignment, resolveElementRef, resolveOffset, shorthandToPositionArea } from './utils';
-import { usePlacementObserver } from './usePlacementObserver';
-
-const DEFAULT_FLIP = ['flip-block', 'flip-inline', 'flip-block flip-inline'];
-
-export function usePositioning(options: PositioningProps): PositioningReturn {
-  const {
-    pinned,
-    target: customTarget = null,
-    align: alignInput = ALIGNMENTS.center,
-    position = POSITIONS.above,
-    fallbackPositions = [],
-    offset,
-    coverTarget = false,
-    strategy = 'absolute',
-    matchTargetSize,
-    positioningRef,
-  } = options;
-
-  const align = normalizeAlign(alignInput);
-
-  const { mainAxis, crossAxis } = resolveOffset(offset);
-  const coverAlignment = coverTarget ? getCoverSelfAlignment(position, align) : null;
-
-  const [triggerEl, setTriggerEl] = React.useState<HTMLElement | null>(null);
-  const [containerEl, setContainerEl] = React.useState<HTMLElement | null>(null);
-  const [imperativeTarget, setImperativeTarget] = React.useState<HTMLElement | null>(null);
-  const effectiveTarget = imperativeTarget ?? resolveElementRef(customTarget) ?? triggerEl;
-
-  const anchorName = useId('--popover-anchor-');
-  const positionArea = POSITION_AREA_MAP[position][align];
-  const placement = getPlacementString(position, align);
-
-  const { targetDocument } = useFluent();
-
-  const fallbackAreas = React.useMemo(() => fallbackPositions.map(shorthandToPositionArea), [fallbackPositions]);
-
-  React.useImperativeHandle<PositioningImperativeRef, PositioningImperativeRef>(
-    positioningRef,
-    () => ({
-      setTarget: (el: HTMLElement | null) => {
-        setImperativeTarget(el);
-      },
-      updatePosition: () => undefined,
-    }),
-    [],
-  );
-
-  useIsomorphicLayoutEffect(() => {
-    effectiveTarget?.style.setProperty('anchor-name', anchorName);
-  }, [effectiveTarget, anchorName]);
-
-  const targetRef: React.RefCallback<HTMLElement> = React.useCallback(node => {
-    setTriggerEl(node);
-  }, []);
-
-  const containerRef: React.RefCallback<HTMLElement> = React.useCallback(
-    node => {
-      setContainerEl(node);
-
-      if (!node) {
-        return;
-      }
-
-      node.style.setProperty('position', strategy);
-      node.style.setProperty('inset', 'auto');
-      node.style.setProperty('margin', '0');
-
-      applyOffset(node, position, mainAxis, crossAxis);
-
-      if (matchTargetSize === 'width') {
-        node.style.setProperty('width', 'anchor-size(width)');
-      } else {
-        node.style.removeProperty('width');
-      }
-
-      node.style.setProperty('position-anchor', anchorName);
-      node.setAttribute('data-placement', placement);
-
-      if (coverAlignment) {
-        node.style.setProperty('position-area', 'center');
-        node.style.setProperty('align-self', coverAlignment.alignSelf);
-        node.style.setProperty('justify-self', coverAlignment.justifySelf);
-        node.style.removeProperty('position-try-fallbacks');
-        return;
-      }
-
-      node.style.setProperty('position-area', positionArea);
-
-      /*
-       * Workaround for https://crbug.com/438334710: Chromium (<=130-ish) doesn't
-         apply the implicit `anchor-center` self-alignment that the spec defines
-         for single-keyword `position-area` values (`block-start`, `block-end`,
-    `    inline-start`, `inline-end`) or `span-all`.
-      */
-      if (align === ALIGNMENTS.center) {
-        node.style.setProperty('place-self', 'anchor-center');
-      } else {
-        node.style.removeProperty('place-self');
-        node.style.removeProperty('align-self');
-        node.style.removeProperty('justify-self');
-      }
-
-      if (pinned) {
-        node.style.removeProperty('position-try-fallbacks');
-        return;
-      }
-
-      if (fallbackAreas.length > 0) {
-        node.style.setProperty('position-try-fallbacks', fallbackAreas.join(', '));
-      } else {
-        node.style.setProperty('position-try-fallbacks', DEFAULT_FLIP.join(', '));
-      }
-    },
-    [
-      anchorName,
-      positionArea,
-      placement,
-      fallbackAreas,
-      pinned,
-      position,
-      align,
-      mainAxis,
-      crossAxis,
-      coverAlignment,
-      strategy,
-      matchTargetSize,
-    ],
-  );
-
-  usePlacementObserver(containerEl, effectiveTarget, targetDocument, coverTarget);
-
-  return { targetRef, containerRef };
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
deleted file mode 100644
index 78d00ae45eb4cf..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/index.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-export { applyOffset, resolveOffset } from './offset';
-export {
-  getCoverSelfAlignment,
-  getPlacementString,
-  resolvePositioningShorthand,
-  shorthandToPositionArea,
-} from './placement';
-export { resolveElementRef } from './resolveElementRef';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
deleted file mode 100644
index 0661a2bb91f548..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/offset.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-import { POSITIONS } from '../constants';
-import type { Position } from '../types';
-import type { PositioningProps } from '../types';
-
-export function applyOffset(node: HTMLElement, position: Position, mainAxis: number, crossAxis: number): void {
-  if (mainAxis) {
-    switch (position) {
-      case POSITIONS.above:
-        node.style.marginBlockEnd = `${mainAxis}px`;
-        break;
-      case POSITIONS.below:
-        node.style.marginBlockStart = `${mainAxis}px`;
-        break;
-      case POSITIONS.before:
-        node.style.marginInlineEnd = `${mainAxis}px`;
-        break;
-      case POSITIONS.after:
-        node.style.marginInlineStart = `${mainAxis}px`;
-        break;
-    }
-  }
-
-  if (crossAxis) {
-    switch (position) {
-      case POSITIONS.above:
-      case POSITIONS.below:
-        node.style.marginInlineStart = `${crossAxis}px`;
-        break;
-      case POSITIONS.before:
-      case POSITIONS.after:
-        node.style.marginBlockStart = `${crossAxis}px`;
-        break;
-    }
-  }
-}
-
-/** Normalises the `offset` prop into explicit `{ mainAxis, crossAxis }`. */
-export function resolveOffset(offset: PositioningProps['offset']): { mainAxis: number; crossAxis: number } {
-  if (typeof offset === 'number') {
-    return { mainAxis: offset, crossAxis: 0 };
-  }
-
-  if (offset) {
-    return { mainAxis: offset.mainAxis ?? 0, crossAxis: offset.crossAxis ?? 0 };
-  }
-
-  return { mainAxis: 0, crossAxis: 0 };
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
deleted file mode 100644
index cd03b35337be06..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/placement.ts
+++ /dev/null
@@ -1,99 +0,0 @@
-import type {
-  Position,
-  LogicalAlignment,
-  PositioningProps,
-  PositioningShorthand,
-  PositioningShorthandValue,
-} from '../types';
-import { ALIGNMENTS, POSITIONS, POSITION_AREA_MAP } from '../constants';
-
-const POSITION_ALIASES: Record<string, Position> = {
-  top: POSITIONS.above,
-  bottom: POSITIONS.below,
-  left: POSITIONS.before,
-  right: POSITIONS.after,
-};
-
-const ALIGN_ALIASES: Record<string, LogicalAlignment> = {
-  top: ALIGNMENTS.start,
-  bottom: ALIGNMENTS.end,
-};
-
-export function normalizePosition(raw: string): Position {
-  if (raw in POSITIONS) {
-    return raw as Position;
-  }
-
-  return POSITION_ALIASES[raw] ?? POSITIONS.above;
-}
-
-export function normalizeAlign(raw: string): LogicalAlignment {
-  if (raw === ALIGNMENTS.start || raw === ALIGNMENTS.center || raw === ALIGNMENTS.end) {
-    return raw;
-  }
-
-  return ALIGN_ALIASES[raw] ?? ALIGNMENTS.center;
-}
-
-/**
- * Maps (position, align) into the human-readable placement string used for the
- * `data-placement` attribute. Center alignment renders as the bare position.
- */
-export function getPlacementString(position: Position, align: LogicalAlignment): string {
-  return align === ALIGNMENTS.center ? position : `${position}-${align}`;
-}
-
-/**
- * Normalizes a shorthand (string or object) into a full `PositioningProps`.
- * Strings like `'below-start'` become `{ position: 'below', align: 'start' }`;
- * objects pass through unchanged.
- *
- */
-export function resolvePositioningShorthand(value: PositioningShorthand | undefined): PositioningProps {
-  if (!value) {
-    return {};
-  }
-
-  if (typeof value !== 'string') {
-    return {
-      ...value,
-      position: value.position !== undefined ? normalizePosition(value.position) : undefined,
-      align: value.align !== undefined ? normalizeAlign(value.align) : undefined,
-    };
-  }
-
-  const dash = value.indexOf('-');
-
-  if (dash === -1) {
-    return { position: normalizePosition(value) };
-  }
-
-  return {
-    position: normalizePosition(value.slice(0, dash)),
-    align: normalizeAlign(value.slice(dash + 1)),
-  };
-}
-
-export function shorthandToPositionArea(shorthand: PositioningShorthandValue): string {
-  const { position = POSITIONS.above, align = ALIGNMENTS.center } = resolvePositioningShorthand(shorthand);
-  return POSITION_AREA_MAP[position][normalizeAlign(align)];
-}
-
-export function getCoverSelfAlignment(
-  position: Position,
-  align: LogicalAlignment,
-): { alignSelf: string; justifySelf: string } {
-  if (position === POSITIONS.above) {
-    return { alignSelf: ALIGNMENTS.end, justifySelf: align };
-  }
-
-  if (position === POSITIONS.below) {
-    return { alignSelf: ALIGNMENTS.start, justifySelf: align };
-  }
-
-  if (position === POSITIONS.before) {
-    return { alignSelf: align, justifySelf: ALIGNMENTS.end };
-  }
-
-  return { alignSelf: align, justifySelf: ALIGNMENTS.start };
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts
deleted file mode 100644
index d002f9601823f2..00000000000000
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/hooks/usePositioning/utils/resolveElementRef.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import type * as React from 'react';
-
-/**
- * Normalizes an `HTMLElement | RefObject | null | undefined` to a plain
- * element (or null). Safe across realms — checks for the `current` property
- * rather than doing `instanceof HTMLElement`.
- */
-export function resolveElementRef(
-  source: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined,
-): HTMLElement | null {
-  if (!source) {
-    return null;
-  }
-  return 'current' in source ? source.current : source;
-}
diff --git a/packages/react-components/react-headless-components-preview/library/src/index.ts b/packages/react-components/react-headless-components-preview/library/src/index.ts
index f65285b35b0b8c..cb0ff5c3b541f6 100644
--- a/packages/react-components/react-headless-components-preview/library/src/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/index.ts
@@ -1,454 +1 @@
-<<<<<<< HEAD
 export {};
-||||||| parent of 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
-export {
-  Accordion,
-  renderAccordion,
-  useAccordion,
-  useAccordionContext,
-  useAccordionContextValues,
-  AccordionHeader,
-  renderAccordionHeader,
-  useAccordionHeader,
-  AccordionItem,
-  renderAccordionItem,
-  useAccordionItem,
-  AccordionPanel,
-  renderAccordionPanel,
-  useAccordionPanel,
-} from './Accordion';
-export type {
-  AccordionSlots,
-  AccordionProps,
-  AccordionState,
-  AccordionContextValues,
-  AccordionHeaderSlots,
-  AccordionHeaderProps,
-  AccordionHeaderState,
-  AccordionItemSlots,
-  AccordionItemProps,
-  AccordionItemState,
-  AccordionPanelSlots,
-  AccordionPanelProps,
-  AccordionPanelState,
-} from './Accordion';
-
-export {
-  MessageBar,
-  renderMessageBar,
-  useMessageBar,
-  useMessageBarContext,
-  useMessageBarContextValues,
-  MessageBarActions,
-  renderMessageBarActions,
-  useMessageBarActions,
-  useMessageBarActionsContextValues,
-  MessageBarBody,
-  renderMessageBarBody,
-  useMessageBarBody,
-  useMessageBarBodyContextValues,
-  MessageBarTitle,
-  renderMessageBarTitle,
-  useMessageBarTitle,
-} from './MessageBar';
-export type {
-  MessageBarSlots,
-  MessageBarProps,
-  MessageBarState,
-  MessageBarContextValues,
-  MessageBarIntent,
-  MessageBarActionsSlots,
-  MessageBarActionsProps,
-  MessageBarActionsState,
-  MessageBarActionsContextValues,
-  MessageBarBodySlots,
-  MessageBarBodyProps,
-  MessageBarBodyState,
-  MessageBarBodyContextValues,
-  MessageBarTitleSlots,
-  MessageBarTitleProps,
-  MessageBarTitleState,
-} from './MessageBar';
-
-export { Avatar, renderAvatar, useAvatar } from './Avatar';
-export type { AvatarProps, AvatarState } from './Avatar';
-
-export { Badge, renderBadge, useBadge } from './Badge';
-export type { BadgeProps, BadgeState } from './Badge';
-
-export {
-  Breadcrumb,
-  renderBreadcrumb,
-  useBreadcrumb,
-  useBreadcrumbContext,
-  useBreadcrumbContextValues,
-  BreadcrumbDivider,
-  renderBreadcrumbDivider,
-  useBreadcrumbDivider,
-  BreadcrumbItem,
-  renderBreadcrumbItem,
-  useBreadcrumbItem,
-  BreadcrumbButton,
-  renderBreadcrumbButton,
-  useBreadcrumbButton,
-} from './Breadcrumb';
-export type {
-  BreadcrumbSlots,
-  BreadcrumbProps,
-  BreadcrumbState,
-  BreadcrumbContextValues,
-  BreadcrumbDividerSlots,
-  BreadcrumbDividerProps,
-  BreadcrumbDividerState,
-  BreadcrumbItemSlots,
-  BreadcrumbItemProps,
-  BreadcrumbItemState,
-  BreadcrumbButtonSlots,
-  BreadcrumbButtonProps,
-  BreadcrumbButtonState,
-} from './Breadcrumb';
-
-export { Button, renderButton, useButton } from './Button';
-export type { ButtonSlots, ButtonProps, ButtonState } from './Button';
-
-export { Checkbox, renderCheckbox, useCheckbox } from './Checkbox';
-export type { CheckboxSlots, CheckboxProps, CheckboxState } from './Checkbox';
-
-export { Divider, renderDivider, useDivider } from './Divider';
-export type { DividerSlots, DividerProps, DividerState } from './Divider';
-
-export { Field, renderField, useField } from './Field';
-export type { FieldSlots, FieldProps, FieldState } from './Field';
-
-export { Input, renderInput, useInput } from './Input';
-export type { InputSlots, InputProps, InputState } from './Input';
-
-export { Link, renderLink, useLink } from './Link';
-export type { LinkSlots, LinkProps, LinkState } from './Link';
-
-export { ProgressBar, renderProgressBar, useProgressBar } from './ProgressBar';
-export type { ProgressBarSlots, ProgressBarProps, ProgressBarState } from './ProgressBar';
-
-export { Radio, renderRadio, useRadio, RadioGroup, renderRadioGroup, useRadioGroup } from './RadioGroup';
-export type {
-  RadioSlots,
-  RadioProps,
-  RadioState,
-  RadioGroupSlots,
-  RadioGroupProps,
-  RadioGroupState,
-} from './RadioGroup';
-
-export { RatingItem, renderRatingItem, useRatingItem, Rating, renderRating, useRating } from './Rating';
-export type {
-  RatingItemSlots,
-  RatingItemProps,
-  RatingItemState,
-  RatingSlots,
-  RatingProps,
-  RatingState,
-} from './Rating';
-
-export { RatingDisplay, renderRatingDisplay, useRatingDisplay } from './RatingDisplay';
-export type { RatingDisplaySlots, RatingDisplayProps, RatingDisplayState } from './RatingDisplay';
-
-export { SearchBox, renderSearchBox, useSearchBox } from './SearchBox';
-export type { SearchBoxSlots, SearchBoxProps, SearchBoxState } from './SearchBox';
-
-export { Select, renderSelect, useSelect } from './Select';
-export type { SelectSlots, SelectProps, SelectState } from './Select';
-
-export { SkeletonItem, renderSkeletonItem, useSkeletonItem, Skeleton, renderSkeleton, useSkeleton } from './Skeleton';
-export type {
-  SkeletonItemSlots,
-  SkeletonItemProps,
-  SkeletonItemState,
-  SkeletonSlots,
-  SkeletonProps,
-  SkeletonState,
-} from './Skeleton';
-
-export { Slider, renderSlider, useSlider } from './Slider';
-export type { SliderSlots, SliderProps, SliderState } from './Slider';
-
-export { SpinButton, renderSpinButton, useSpinButton } from './SpinButton';
-export type { SpinButtonSlots, SpinButtonProps, SpinButtonState } from './SpinButton';
-
-export { Spinner, renderSpinner, useSpinner } from './Spinner';
-export type { SpinnerSlots, SpinnerProps, SpinnerState } from './Spinner';
-
-export { Switch, renderSwitch, useSwitch } from './Switch';
-export type { SwitchSlots, SwitchProps, SwitchState } from './Switch';
-
-export { Tab, renderTab, useTab, TabList, renderTabList, useTabList } from './TabList';
-export type { TabSlots, TabValue, TabProps, TabState, TabListSlots, TabListProps, TabListState } from './TabList';
-
-export { Textarea, renderTextarea, useTextarea } from './Textarea';
-export type { TextareaSlots, TextareaProps, TextareaState } from './Textarea';
-
-export { ToggleButton, renderToggleButton, useToggleButton } from './ToggleButton';
-export type { ToggleButtonSlots, ToggleButtonProps, ToggleButtonState } from './ToggleButton';
-
-export {
-  Popover,
-  renderPopover,
-  usePopover,
-  usePopoverContext,
-  usePopoverContextValues,
-  PopoverTrigger,
-  usePopoverTrigger,
-  renderPopoverTrigger,
-  PopoverSurface,
-  usePopoverSurface,
-  renderPopoverSurface,
-} from './Popover';
-
-export type {
-  PopoverProps,
-  PopoverState,
-  PopoverContextValue,
-  OpenPopoverEvents,
-  OnOpenChangeData,
-  PopoverTriggerProps,
-  PopoverTriggerState,
-  PopoverSurfaceSlots,
-  PopoverSurfaceProps,
-  PopoverSurfaceState,
-} from './Popover';
-
-export type {
-  PositioningProps,
-  PositioningReturn,
-  PositioningImperativeRef,
-  PositioningShorthandValue,
-  PositioningShorthand,
-  PositioningBoundaryPadding,
-  Position,
-  Alignment,
-} from './hooks/usePositioning';
-=======
-export {
-  Accordion,
-  renderAccordion,
-  useAccordion,
-  useAccordionContext,
-  useAccordionContextValues,
-  AccordionHeader,
-  renderAccordionHeader,
-  useAccordionHeader,
-  AccordionItem,
-  renderAccordionItem,
-  useAccordionItem,
-  AccordionPanel,
-  renderAccordionPanel,
-  useAccordionPanel,
-} from './Accordion';
-export type {
-  AccordionSlots,
-  AccordionProps,
-  AccordionState,
-  AccordionContextValues,
-  AccordionHeaderSlots,
-  AccordionHeaderProps,
-  AccordionHeaderState,
-  AccordionItemSlots,
-  AccordionItemProps,
-  AccordionItemState,
-  AccordionPanelSlots,
-  AccordionPanelProps,
-  AccordionPanelState,
-} from './Accordion';
-
-export {
-  MessageBar,
-  renderMessageBar,
-  useMessageBar,
-  useMessageBarContext,
-  useMessageBarContextValues,
-  MessageBarActions,
-  renderMessageBarActions,
-  useMessageBarActions,
-  useMessageBarActionsContextValues,
-  MessageBarBody,
-  renderMessageBarBody,
-  useMessageBarBody,
-  useMessageBarBodyContextValues,
-  MessageBarTitle,
-  renderMessageBarTitle,
-  useMessageBarTitle,
-} from './MessageBar';
-export type {
-  MessageBarSlots,
-  MessageBarProps,
-  MessageBarState,
-  MessageBarContextValues,
-  MessageBarIntent,
-  MessageBarActionsSlots,
-  MessageBarActionsProps,
-  MessageBarActionsState,
-  MessageBarActionsContextValues,
-  MessageBarBodySlots,
-  MessageBarBodyProps,
-  MessageBarBodyState,
-  MessageBarBodyContextValues,
-  MessageBarTitleSlots,
-  MessageBarTitleProps,
-  MessageBarTitleState,
-} from './MessageBar';
-
-export { Avatar, renderAvatar, useAvatar } from './Avatar';
-export type { AvatarProps, AvatarState } from './Avatar';
-
-export { Badge, renderBadge, useBadge } from './Badge';
-export type { BadgeProps, BadgeState } from './Badge';
-
-export {
-  Breadcrumb,
-  renderBreadcrumb,
-  useBreadcrumb,
-  useBreadcrumbContext,
-  useBreadcrumbContextValues,
-  BreadcrumbDivider,
-  renderBreadcrumbDivider,
-  useBreadcrumbDivider,
-  BreadcrumbItem,
-  renderBreadcrumbItem,
-  useBreadcrumbItem,
-  BreadcrumbButton,
-  renderBreadcrumbButton,
-  useBreadcrumbButton,
-} from './Breadcrumb';
-export type {
-  BreadcrumbSlots,
-  BreadcrumbProps,
-  BreadcrumbState,
-  BreadcrumbContextValues,
-  BreadcrumbDividerSlots,
-  BreadcrumbDividerProps,
-  BreadcrumbDividerState,
-  BreadcrumbItemSlots,
-  BreadcrumbItemProps,
-  BreadcrumbItemState,
-  BreadcrumbButtonSlots,
-  BreadcrumbButtonProps,
-  BreadcrumbButtonState,
-} from './Breadcrumb';
-
-export { Button, renderButton, useButton } from './Button';
-export type { ButtonSlots, ButtonProps, ButtonState } from './Button';
-
-export { Checkbox, renderCheckbox, useCheckbox } from './Checkbox';
-export type { CheckboxSlots, CheckboxProps, CheckboxState } from './Checkbox';
-
-export { Divider, renderDivider, useDivider } from './Divider';
-export type { DividerSlots, DividerProps, DividerState } from './Divider';
-
-export { Field, renderField, useField } from './Field';
-export type { FieldSlots, FieldProps, FieldState } from './Field';
-
-export { Input, renderInput, useInput } from './Input';
-export type { InputSlots, InputProps, InputState } from './Input';
-
-export { Link, renderLink, useLink } from './Link';
-export type { LinkSlots, LinkProps, LinkState } from './Link';
-
-export { ProgressBar, renderProgressBar, useProgressBar } from './ProgressBar';
-export type { ProgressBarSlots, ProgressBarProps, ProgressBarState } from './ProgressBar';
-
-export { Radio, renderRadio, useRadio, RadioGroup, renderRadioGroup, useRadioGroup } from './RadioGroup';
-export type {
-  RadioSlots,
-  RadioProps,
-  RadioState,
-  RadioGroupSlots,
-  RadioGroupProps,
-  RadioGroupState,
-} from './RadioGroup';
-
-export { RatingItem, renderRatingItem, useRatingItem, Rating, renderRating, useRating } from './Rating';
-export type {
-  RatingItemSlots,
-  RatingItemProps,
-  RatingItemState,
-  RatingSlots,
-  RatingProps,
-  RatingState,
-} from './Rating';
-
-export { RatingDisplay, renderRatingDisplay, useRatingDisplay } from './RatingDisplay';
-export type { RatingDisplaySlots, RatingDisplayProps, RatingDisplayState } from './RatingDisplay';
-
-export { SearchBox, renderSearchBox, useSearchBox } from './SearchBox';
-export type { SearchBoxSlots, SearchBoxProps, SearchBoxState } from './SearchBox';
-
-export { Select, renderSelect, useSelect } from './Select';
-export type { SelectSlots, SelectProps, SelectState } from './Select';
-
-export { SkeletonItem, renderSkeletonItem, useSkeletonItem, Skeleton, renderSkeleton, useSkeleton } from './Skeleton';
-export type {
-  SkeletonItemSlots,
-  SkeletonItemProps,
-  SkeletonItemState,
-  SkeletonSlots,
-  SkeletonProps,
-  SkeletonState,
-} from './Skeleton';
-
-export { Slider, renderSlider, useSlider } from './Slider';
-export type { SliderSlots, SliderProps, SliderState } from './Slider';
-
-export { SpinButton, renderSpinButton, useSpinButton } from './SpinButton';
-export type { SpinButtonSlots, SpinButtonProps, SpinButtonState } from './SpinButton';
-
-export { Spinner, renderSpinner, useSpinner } from './Spinner';
-export type { SpinnerSlots, SpinnerProps, SpinnerState } from './Spinner';
-
-export { Switch, renderSwitch, useSwitch } from './Switch';
-export type { SwitchSlots, SwitchProps, SwitchState } from './Switch';
-
-export { Tab, renderTab, useTab, TabList, renderTabList, useTabList } from './TabList';
-export type { TabSlots, TabValue, TabProps, TabState, TabListSlots, TabListProps, TabListState } from './TabList';
-
-export { Textarea, renderTextarea, useTextarea } from './Textarea';
-export type { TextareaSlots, TextareaProps, TextareaState } from './Textarea';
-
-export { ToggleButton, renderToggleButton, useToggleButton } from './ToggleButton';
-export type { ToggleButtonSlots, ToggleButtonProps, ToggleButtonState } from './ToggleButton';
-
-export {
-  Popover,
-  renderPopover,
-  usePopover,
-  usePopoverContext,
-  usePopoverContextValues,
-  PopoverTrigger,
-  usePopoverTrigger,
-  renderPopoverTrigger,
-  PopoverSurface,
-  usePopoverSurface,
-  renderPopoverSurface,
-} from './Popover';
-
-export type {
-  PopoverProps,
-  PopoverState,
-  PopoverContextValue,
-  OpenPopoverEvents,
-  OnOpenChangeData,
-  PopoverTriggerProps,
-  PopoverTriggerState,
-  PopoverSurfaceSlots,
-  PopoverSurfaceProps,
-  PopoverSurfaceState,
-} from './Popover';
-
-export type {
-  PositioningProps,
-  PositioningReturn,
-  PositioningImperativeRef,
-  PositioningShorthandValue,
-  PositioningShorthand,
-  Position,
-  Alignment,
-} from './hooks/usePositioning';
->>>>>>> 6911c57198 (refactor(react-headless-components-preview): remove custom trapFocus and unsupported positioning props)
diff --git a/packages/react-components/react-headless-components-preview/library/src/popover.ts b/packages/react-components/react-headless-components-preview/library/src/popover.ts
index 0935588213760e..b4ffbc99a65968 100644
--- a/packages/react-components/react-headless-components-preview/library/src/popover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/popover.ts
@@ -23,13 +23,3 @@ export type {
   PopoverSurfaceProps,
   PopoverSurfaceState,
 } from './components/Popover';
-
-export type {
-  PositioningProps,
-  PositioningReturn,
-  PositioningImperativeRef,
-  PositioningShorthandValue,
-  PositioningShorthand,
-  Position,
-  Alignment,
-} from './hooks/usePositioning';
diff --git a/packages/react-components/react-headless-components-preview/library/src/positioning.ts b/packages/react-components/react-headless-components-preview/library/src/positioning.ts
index e69de29bb2d1d6..04b9191e89b66c 100644
--- a/packages/react-components/react-headless-components-preview/library/src/positioning.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/positioning.ts
@@ -0,0 +1,10 @@
+export type {
+  Position,
+  Alignment,
+  PositioningProps,
+  PositioningReturn,
+  PositioningImperativeRef,
+  PositioningShorthand,
+  PositioningShorthandValue,
+} from './hooks/usePositioning';
+export { usePositioning, POSITIONS, ALIGNMENTS, getPlacementString, resolvePositioningShorthand } from './hooks/usePositioning';

From 1de9ff5b5a6b9b2312de32776768be339ac68bfe Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 17:41:54 +0200
Subject: [PATCH 09/17] chore: adjust stories popover paths to use sub-paths

---
 .../Positioning/PositioningCoverTarget.stories.tsx        | 4 ++--
 .../Concepts/Positioning/PositioningDefault.stories.tsx   | 8 ++------
 .../Positioning/PositioningFallbackPositions.stories.tsx  | 2 +-
 .../Positioning/PositioningFlippingBlock.stories.tsx      | 2 +-
 .../Positioning/PositioningFlippingCorner.stories.tsx     | 2 +-
 .../Positioning/PositioningFlippingInline.stories.tsx     | 2 +-
 .../Positioning/PositioningMatchTargetSize.stories.tsx    | 2 +-
 .../Concepts/Positioning/PositioningOffset.stories.tsx    | 2 +-
 .../Positioning/PositioningShorthandPositions.stories.tsx | 4 ++--
 .../stories/src/Concepts/Positioning/utils.stories.tsx    | 2 +-
 .../src/Popover/PopoverAnchorToCustomTarget.stories.tsx   | 2 +-
 .../stories/src/Popover/PopoverControlled.stories.tsx     | 2 +-
 .../stories/src/Popover/PopoverCustomTrigger.stories.tsx  | 2 +-
 .../stories/src/Popover/PopoverDefault.stories.tsx        | 2 +-
 .../stories/src/Popover/PopoverInline.stories.tsx         | 2 +-
 .../src/Popover/PopoverInternalUpdateContent.stories.tsx  | 2 +-
 .../stories/src/Popover/PopoverNested.stories.tsx         | 2 +-
 .../stories/src/Popover/PopoverOpenOnContext.stories.tsx  | 2 +-
 .../stories/src/Popover/PopoverOpenOnHover.stories.tsx    | 2 +-
 .../stories/src/Popover/PopoverWithArrow.stories.tsx      | 2 +-
 .../stories/src/Popover/PopoverWithoutTrigger.stories.tsx | 2 +-
 .../stories/src/Popover/index.stories.tsx                 | 2 +-
 22 files changed, 25 insertions(+), 29 deletions(-)

diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
index cdd933922eb60e..6ecac5e95d9534 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningCoverTarget.stories.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview/positioning';
 
 const classes = {
   outer: 'w-full overflow-auto',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
index f9c63d7cf87a5d..39994731f56813 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningDefault.stories.tsx
@@ -1,10 +1,6 @@
 import * as React from 'react';
-import {
-  Popover,
-  PopoverTrigger,
-  PopoverSurface,
-  type PositioningProps,
-} from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview/positioning';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
index e536b3f675f342..8390a8a4437a6b 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFallbackPositions.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
 
 const classes = {
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
index d5a8c9d1baf80c..c6810fc719d9c3 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingBlock.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
 
 import descriptionMd from './PositioningFlippingBlockDescription.md';
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
index 21c3063daee75f..f9e6be3252ad0c 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingCorner.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
 
 import descriptionMd from './PositioningFlippingCornerDescription.md';
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
index 67983522ede239..2efe6ad7c5b4fb 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningFlippingInline.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import { demoBoxClass, demoBoxStyle, flipDemoSurfaceCss } from './demoBox';
 
 import descriptionMd from './PositioningFlippingInlineDescription.md';
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
index a6c2731b7e6437..337b98b8a2fb6e 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningMatchTargetSize.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 import descriptionMd from './PositioningMatchTargetSizeDescription.md';
 
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
index 6df415cf2b34c2..3d4c2afe951fe2 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningOffset.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   outer: 'w-full overflow-auto',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
index 11842c897f5a5c..d2ff0921bb9864 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/PositioningShorthandPositions.stories.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
-import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview/positioning';
 
 const classes = {
   outer: 'w-full overflow-auto',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx
index 500f0973c70adb..626ff14279ff61 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/utils.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { PositioningProps } from '@fluentui/react-headless-components-preview';
+import type { PositioningProps } from '@fluentui/react-headless-components-preview/positioning';
 
 /**
  * Helper component used by Storybook to auto-generate the positioning props args table.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
index 2921b972f22131..25abec496644ba 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverAnchorToCustomTarget.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   outer: 'p-16 min-h-[320px]',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
index 74fb75b85f316d..65d8fac2b65ee8 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverControlled.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
index 3de26b3cbff5ad..f3707950e20aca 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverCustomTrigger.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
index 284b6a3ce92b59..1ed9aa40c50dab 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverDefault.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
index 1bcd0ff909604b..cc0dee05a44f7c 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInline.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
index 1a2143d008e7cd..afb359fd4ec696 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverInternalUpdateContent.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index 46a63cbcd1ab3f..f92014ce1a81e5 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import type { JSXElement } from '@fluentui/react-components';
 
 const classes = {
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
index 8184dfc95c47e6..e42b0567b4d8bf 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnContext.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
index de9a53e3bf8ecf..e25fe7a5b5df99 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverOpenOnHover.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   trigger:
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
index 04117cf9ea10d7..9507b31cd9d931 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithArrow.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   wrapper: 'flex flex-col items-start gap-4 p-16',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
index bfb6d197bc4a6f..9e07e940bcf8c6 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverWithoutTrigger.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 const classes = {
   container: 'flex flex-col items-start gap-4 p-4',
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
index 8f4aea88130a60..2f2003a23f5e58 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
@@ -1,4 +1,4 @@
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 
 import descriptionMd from './PopoverDescription.md';
 import bestPracticesMd from './PopoverBestPractices.md';

From dde2f6aafa78fbc808ffe9e92aa710e6d45caf77 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 18:00:46 +0200
Subject: [PATCH 10/17] test(react-headless-components-preview): switch
 usePositioning style assertions to toHaveStyle

---
 .../usePositioning/usePositioning.test.tsx    | 29 +++++++------------
 1 file changed, 10 insertions(+), 19 deletions(-)

diff --git a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
index 31018f373c2d63..96d47c2b666e42 100644
--- a/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/usePositioning.test.tsx
@@ -40,7 +40,7 @@ describe('usePositioning', () => {
     result.current.containerRef(node);
 
     expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
-    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
+    expect(node).toHaveStyle({ positionArea: 'block-end span-inline-end' });
   });
 
   it('containerRef writes position: absolute by default and clears the UA inset/margin defaults', () => {
@@ -48,9 +48,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.position).toBe('absolute');
-    expect(node.style.inset).toBe('auto');
-    expect(node.style.margin).toBe('0px');
+    expect(node).toHaveStyle({ position: 'absolute', inset: 'auto', margin: '0px' });
   });
 
   it('containerRef honors strategy: "fixed"', () => {
@@ -58,7 +56,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.position).toBe('fixed');
+    expect(node).toHaveStyle({ position: 'fixed' });
   });
 
   it('containerRef writes data-placement matching (position, align)', () => {
@@ -66,7 +64,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.getAttribute('data-placement')).toBe('below-start');
+    expect(node).toHaveAttribute('data-placement', 'below-start');
   });
 
   it('containerRef sets position-try-fallbacks to the three-try flip chain by default', () => {
@@ -74,9 +72,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe(
-      'flip-block, flip-inline, flip-block flip-inline',
-    );
+    expect(node).toHaveStyle({ positionTryFallbacks: 'flip-block, flip-inline, flip-block flip-inline' });
   });
 
   it('containerRef uses custom fallbackPositions verbatim when provided', () => {
@@ -84,7 +80,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.getPropertyValue('position-try-fallbacks')).toBe('block-end span-inline-end, inline-end');
+    expect(node).toHaveStyle({ positionTryFallbacks: 'block-end span-inline-end, inline-end' });
   });
 
   it('containerRef removes position-try-fallbacks when pinned', () => {
@@ -101,9 +97,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.getPropertyValue('position-area')).toBe('center');
-    expect(node.style.getPropertyValue('align-self')).toBe('end');
-    expect(node.style.getPropertyValue('justify-self')).toBe('start');
+    expect(node).toHaveStyle({ positionArea: 'center', alignSelf: 'end', justifySelf: 'start' });
   });
 
   it('containerRef writes place-self: anchor-center for center alignment (crbug 438334710 workaround)', () => {
@@ -111,7 +105,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.getPropertyValue('place-self')).toBe('anchor-center');
+    expect(node).toHaveStyle({ placeSelf: 'anchor-center' });
   });
 
   it('containerRef does not write place-self for non-center alignments', () => {
@@ -127,11 +121,9 @@ describe('usePositioning', () => {
   it('containerRef writes matchTargetSize width via anchor-size()', () => {
     const result = mountHook({ matchTargetSize: 'width' });
     const node = document.createElement('div');
-    const spy = jest.spyOn(node.style, 'setProperty');
     result.current.containerRef(node);
 
-    expect(spy).toHaveBeenCalledWith('width', 'anchor-size(width)');
-    spy.mockRestore();
+    expect(node).toHaveStyle({ width: 'anchor-size(width)' });
   });
 
   it('containerRef applies offset as logical margins', () => {
@@ -139,8 +131,7 @@ describe('usePositioning', () => {
     const node = document.createElement('div');
     result.current.containerRef(node);
 
-    expect(node.style.marginBlockStart).toBe('8px');
-    expect(node.style.marginInlineStart).toBe('4px');
+    expect(node).toHaveStyle({ marginBlockStart: '8px', marginInlineStart: '4px' });
   });
 });
 

From c05836bb19fb2732e0ce23873111820be67070cb Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 18:31:02 +0200
Subject: [PATCH 11/17] chore: format

---
 .../library/src/positioning.ts                            | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/react-components/react-headless-components-preview/library/src/positioning.ts b/packages/react-components/react-headless-components-preview/library/src/positioning.ts
index 04b9191e89b66c..3c24fa062d54bf 100644
--- a/packages/react-components/react-headless-components-preview/library/src/positioning.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/positioning.ts
@@ -7,4 +7,10 @@ export type {
   PositioningShorthand,
   PositioningShorthandValue,
 } from './hooks/usePositioning';
-export { usePositioning, POSITIONS, ALIGNMENTS, getPlacementString, resolvePositioningShorthand } from './hooks/usePositioning';
+export {
+  usePositioning,
+  POSITIONS,
+  ALIGNMENTS,
+  getPlacementString,
+  resolvePositioningShorthand,
+} from './hooks/usePositioning';

From be4f4ed0f139c9b09268dcc18e3c2039fef399d4 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 18:34:12 +0200
Subject: [PATCH 12/17] chore: change files

---
 ...nents-preview-b4355b45-2078-49a5-85ef-8914bb5b16e2.json | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 change/@fluentui-react-headless-components-preview-b4355b45-2078-49a5-85ef-8914bb5b16e2.json

diff --git a/change/@fluentui-react-headless-components-preview-b4355b45-2078-49a5-85ef-8914bb5b16e2.json b/change/@fluentui-react-headless-components-preview-b4355b45-2078-49a5-85ef-8914bb5b16e2.json
new file mode 100644
index 00000000000000..b95ceff2239ea8
--- /dev/null
+++ b/change/@fluentui-react-headless-components-preview-b4355b45-2078-49a5-85ef-8914bb5b16e2.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add headless Popover'",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "vgenaev@gmail.com",
+  "dependentChangeType": "patch"
+}

From abb7b0b8b162ee3958061007a5f55f8acb7009dc Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 18:54:26 +0200
Subject: [PATCH 13/17] feat(react-headless-components-preview): add
 PopoverAuto sub-component

Adds a PopoverAuto component that renders its surface with
`popover="auto"` instead of `popover="manual"`, so light dismiss
(Escape, click-outside, popover-stack peer dismissal) is handled by
the browser rather than React.

Implementation:
- Extracts a shared internal hook `useInternalPopover(props, popoverType)`
  in usePopover.ts. Both the existing `usePopover` (manual) and a new
  `usePopoverAuto` are thin wrappers that fix the popoverType.
- Sets the `popover` attribute to the actual mode value when calling
  `showPopover()`.
- In auto mode: disables `useOnClickOutside` / `useOnScrollOutside` and
  attaches a `toggle` event listener on the surface to mirror the
  browser's open/closed state into React and fire onOpenChange.
- Plumbs `popoverType` through PopoverContextValue so PopoverSurface
  can skip its own Escape handler in auto mode (the browser owns it).
- Exports `PopoverAuto` and `usePopoverAuto` from the popover subpath.
- Updates the Nested Storybook story to use PopoverAuto, where browser
  popover-stack semantics keep ancestor surfaces open when a descendant
  popover opens, and dismiss the ancestor chain on outside interaction.

Tests, type-check, lint, and api-report all pass.
---
 .../library/etc/popover.api.md                | 17 ++++-
 .../src/components/Popover/Popover.types.ts   |  9 +++
 .../src/components/Popover/PopoverAuto.tsx    | 26 +++++++
 .../PopoverSurface/usePopoverSurface.ts       |  8 ++-
 .../library/src/components/Popover/index.ts   |  4 +-
 .../src/components/Popover/popoverContext.ts  |  1 +
 .../src/components/Popover/usePopover.ts      | 70 ++++++++++++++++---
 .../library/src/popover.ts                    |  3 +
 .../src/Popover/PopoverNested.stories.tsx     | 14 ++--
 .../stories/src/Popover/index.stories.tsx     |  9 ++-
 10 files changed, 137 insertions(+), 24 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx

diff --git a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
index 21504e7194bce0..53a4f66a9e0eb1 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
@@ -29,7 +29,13 @@ export const Popover: {
 };
 
 // @public
-export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+export const PopoverAuto: {
+    (props: PopoverProps): JSXElement;
+    displayName: string;
+};
+
+// @public
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode' | 'popoverType'> & {
     positioning: {
         targetRef: React_2.RefCallback<HTMLElement>;
         containerRef: React_2.RefCallback<HTMLElement>;
@@ -72,6 +78,7 @@ export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> & Pic
         y: number;
     } | undefined) => void;
     positioning: PositioningReturn;
+    popoverType: PopoverType;
 };
 
 // @public
@@ -108,6 +115,9 @@ export type PopoverTriggerState = {
     children: React_2.ReactElement | null;
 };
 
+// @public
+export type PopoverType = 'manual' | 'auto';
+
 // @public
 export const renderPopover: (state: PopoverState, contextValues: {
     popover: PopoverContextValue;
@@ -120,7 +130,10 @@ export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
 export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
 
 // @public
-export const usePopover: (props: PopoverProps, ref: React_2.Ref<HTMLElement>) => PopoverState;
+export const usePopover: (props: PopoverProps, _ref: React_2.Ref<HTMLElement>) => PopoverState;
+
+// @public
+export const usePopoverAuto: (props: PopoverProps, _ref: React_2.Ref<HTMLElement>) => PopoverState;
 
 // @public
 export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
index 31bbe9baa36430..84356b645111fc 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts
@@ -113,6 +113,13 @@ export type PopoverProps = {
   mountNode?: HTMLElement | null;
 };
 
+/**
+ * Native HTML Popover API mode for the surface.
+ * - `'manual'` — React drives all dismissal (click-outside, scroll-outside, Escape).
+ * - `'auto'` — browser drives light dismiss; React mirrors the surface's `toggle` event into state.
+ */
+export type PopoverType = 'manual' | 'auto';
+
 /**
  * Popover State
  */
@@ -131,6 +138,7 @@ export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> &
     contextTarget: { x: number; y: number } | undefined;
     setContextTarget: (target: { x: number; y: number } | undefined) => void;
     positioning: PositioningReturn;
+    popoverType: PopoverType;
   };
 
 /**
@@ -186,6 +194,7 @@ export type PopoverContextValue = Pick<
   | 'withArrow'
   | 'inline'
   | 'mountNode'
+  | 'popoverType'
 > & {
   positioning: {
     targetRef: React.RefCallback<HTMLElement>;
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
new file mode 100644
index 00000000000000..cb2d0e6bb49d3b
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import type { PopoverProps } from './Popover.types';
+import type { JSXElement } from '@fluentui/react-utilities';
+import { usePopoverAuto, usePopoverContextValues } from './usePopover';
+import { renderPopover } from './renderPopover';
+
+/**
+ * Headless Popover with `popover="auto"` semantics.
+ *
+ * Same composition as `Popover`, but defers light dismiss (Escape,
+ * click-outside) and popover-stack interactions to the browser. Browser
+ * `toggle` events are mirrored back into React state and `onOpenChange`.
+ *
+ * Use this when you want native nested-popover behaviour: opening a
+ * descendant popover keeps its ancestors open, while opening an unrelated
+ * popover dismisses any peers — both delegated to the browser's stack.
+ */
+export const PopoverAuto = (props: PopoverProps): JSXElement => {
+  const state = usePopoverAuto(props, null);
+  const contextValues = usePopoverContextValues(state);
+
+  return renderPopover(state, contextValues);
+};
+
+PopoverAuto.displayName = 'PopoverAuto';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
index 74a0075ba5e4dd..6cf2c70a267393 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
@@ -18,8 +18,14 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   const inline = usePopoverContext(context => context.inline);
   const open = usePopoverContext(context => context.open);
   const mountNode = usePopoverContext(context => context.mountNode);
+  const popoverType = usePopoverContext(context => context.popoverType);
   const positioningCtx = usePopoverContext(context => context.positioning);
 
+  // In `auto` mode the browser handles Escape dismiss natively (and emits a
+  // `toggle` event we already mirror in usePopover). Adding our own Escape
+  // handler would race with the browser and the popover-stack semantics.
+  const browserHandlesDismiss = popoverType === 'auto' && !inline;
+
   const state: PopoverSurfaceState = {
     inline,
     withArrow,
@@ -60,7 +66,7 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   });
 
   state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
-    if (e.key === 'Escape') {
+    if (!browserHandlesDismiss && e.key === 'Escape') {
       const target = e.target as HTMLElement;
       const surface = contentRef.current;
       if (surface && target.closest('[data-popover-surface]') === surface) {
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
index eb77fa652f7646..8330fac9c5d8bf 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
@@ -1,11 +1,13 @@
 export { Popover } from './Popover';
+export { PopoverAuto } from './PopoverAuto';
 export { renderPopover } from './renderPopover';
-export { usePopover, usePopoverContextValues } from './usePopover';
+export { usePopover, usePopoverAuto, usePopoverContextValues } from './usePopover';
 export { usePopoverContext } from './popoverContext';
 export type {
   PopoverProps,
   PopoverState,
   PopoverContextValue,
+  PopoverType,
   OpenPopoverEvents,
   OnOpenChangeData,
 } from './Popover.types';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
index 63d5073a3890e4..63c3c27d1f93ee 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts
@@ -21,6 +21,7 @@ const popoverContextDefaultValue: PopoverContextValue = {
   withArrow: false,
   inline: false,
   mountNode: null,
+  popoverType: 'manual',
   positioning: {
     targetRef: () => undefined,
     containerRef: () => undefined,
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index c593089dc1900b..0797f45f6bea65 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -11,15 +11,14 @@ import {
 } from '@fluentui/react-utilities';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
 import { usePositioning, resolvePositioningShorthand } from '../../hooks';
-import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents } from './Popover.types';
+import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents, PopoverType } from './Popover.types';
 
 const SUPPORTS_POPOVER_OPEN_SELECTOR =
   typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
 
-/**
- * Returns the state for a Popover component, given its props and ref.
- */
-export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): PopoverState => {
+type ToggleEventLike = Event & { newState?: 'open' | 'closed' };
+
+function useInternalPopover(props: PopoverProps, popoverType: PopoverType): PopoverState {
   const {
     openOnHover = false,
     openOnContext = false,
@@ -83,12 +82,16 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
 
   const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
 
+  // In `auto` mode the browser owns light dismiss (click-outside, scroll, Escape)
+  // and emits `toggle` events we mirror back into React state.
+  const isAutoMode = popoverType === 'auto' && !inline;
+
   useOnClickOutside({
     contains: elementContains,
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open,
+    disabled: !open || isAutoMode,
     disabledFocusOnIframe: !closeOnIframeFocus,
   });
 
@@ -97,7 +100,7 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open || !(openOnContext || closeOnScroll),
+    disabled: !open || !(openOnContext || closeOnScroll) || isAutoMode,
   });
 
   React.useEffect(() => {
@@ -111,8 +114,8 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
       return;
     }
 
-    if (!surface.hasAttribute('popover')) {
-      surface.setAttribute('popover', 'manual');
+    if (!surface.hasAttribute('popover') || surface.getAttribute('popover') !== popoverType) {
+      surface.setAttribute('popover', popoverType);
     }
 
     if (SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open')) {
@@ -120,7 +123,29 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     }
 
     surface.showPopover();
-  }, [open, inline]);
+  }, [open, inline, popoverType]);
+
+  // Mirror the browser-driven toggle events into React state when in auto mode.
+  // Covers Escape, click-outside, and the popover-stack dismissal that happens
+  // when an unrelated `popover="auto"` opens.
+  const onSurfaceToggle = useEventCallback((event: Event) => {
+    const toggle = event as ToggleEventLike;
+    const nextOpen = toggle.newState === 'open';
+    setOpenState(nextOpen);
+    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
+  });
+
+  React.useEffect(() => {
+    if (!isAutoMode) {
+      return;
+    }
+    const surface = contentRef.current;
+    if (!surface) {
+      return;
+    }
+    surface.addEventListener('toggle', onSurfaceToggle);
+    return () => surface.removeEventListener('toggle', onSurfaceToggle);
+  }, [isAutoMode, onSurfaceToggle]);
 
   const children = React.Children.toArray(props.children) as React.ReactElement[];
 
@@ -165,8 +190,29 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     contextTarget,
     setContextTarget,
     positioning,
+    popoverType,
   };
-};
+}
+
+/**
+ * Returns the state for a Popover component.
+ *
+ * Renders the surface with `popover="manual"`, leaving dismiss behaviour
+ * (click-outside, scroll, Escape) under React's control.
+ */
+export const usePopover = (props: PopoverProps, _ref: React.Ref<HTMLElement>): PopoverState =>
+  useInternalPopover(props, 'manual');
+
+/**
+ * Returns the state for a PopoverAuto component.
+ *
+ * Renders the surface with `popover="auto"`, deferring light-dismiss
+ * (Escape, click-outside, popover-stack peer dismissal) to the browser.
+ * Browser `toggle` events are mirrored back into React state and
+ * `onOpenChange`. The library's own dismiss hooks are disabled.
+ */
+export const usePopoverAuto = (props: PopoverProps, _ref: React.Ref<HTMLElement>): PopoverState =>
+  useInternalPopover(props, 'auto');
 
 export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
   const {
@@ -183,6 +229,7 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
     inline,
     mountNode,
     positioning,
+    popoverType,
   } = state;
 
   return {
@@ -199,6 +246,7 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
       withArrow,
       inline,
       mountNode,
+      popoverType,
       positioning: {
         targetRef: positioning.targetRef,
         containerRef: positioning.containerRef,
diff --git a/packages/react-components/react-headless-components-preview/library/src/popover.ts b/packages/react-components/react-headless-components-preview/library/src/popover.ts
index b4ffbc99a65968..9e5d05951c58c1 100644
--- a/packages/react-components/react-headless-components-preview/library/src/popover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/popover.ts
@@ -1,7 +1,9 @@
 export {
   Popover,
+  PopoverAuto,
   renderPopover,
   usePopover,
+  usePopoverAuto,
   usePopoverContext,
   usePopoverContextValues,
   PopoverTrigger,
@@ -15,6 +17,7 @@ export type {
   PopoverProps,
   PopoverState,
   PopoverContextValue,
+  PopoverType,
   OpenPopoverEvents,
   OnOpenChangeData,
   PopoverTriggerProps,
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index f92014ce1a81e5..7874c8990ac503 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import { PopoverAuto, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import type { JSXElement } from '@fluentui/react-components';
 
 const classes = {
@@ -18,7 +18,7 @@ const classes = {
 };
 
 const SecondNestedPopover = (): JSXElement => (
-  <Popover>
+  <PopoverAuto>
     <PopoverTrigger>
       <button className={classes.deepTrigger}>Second nested trigger</button>
     </PopoverTrigger>
@@ -27,11 +27,11 @@ const SecondNestedPopover = (): JSXElement => (
       <div className={classes.body}>This is some popover content.</div>
       <button className={classes.actionButton}>Second nested button</button>
     </PopoverSurface>
-  </Popover>
+  </PopoverAuto>
 );
 
 const FirstNestedPopover = (): JSXElement => (
-  <Popover>
+  <PopoverAuto>
     <PopoverTrigger>
       <button className={classes.nestedTrigger}>First nested trigger</button>
     </PopoverTrigger>
@@ -43,11 +43,11 @@ const FirstNestedPopover = (): JSXElement => (
         <SecondNestedPopover />
       </div>
     </PopoverSurface>
-  </Popover>
+  </PopoverAuto>
 );
 
 export const Nested = (): React.ReactNode => (
-  <Popover>
+  <PopoverAuto>
     <PopoverTrigger>
       <button className={classes.rootTrigger}>Root trigger</button>
     </PopoverTrigger>
@@ -59,5 +59,5 @@ export const Nested = (): React.ReactNode => (
         <FirstNestedPopover />
       </div>
     </PopoverSurface>
-  </Popover>
+  </PopoverAuto>
 );
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
index 2f2003a23f5e58..cd22d3a8baf36b 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
@@ -1,4 +1,9 @@
-import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import {
+  Popover,
+  PopoverAuto,
+  PopoverTrigger,
+  PopoverSurface,
+} from '@fluentui/react-headless-components-preview/popover';
 
 import descriptionMd from './PopoverDescription.md';
 import bestPracticesMd from './PopoverBestPractices.md';
@@ -18,7 +23,7 @@ export { Inline } from './PopoverInline.stories';
 export default {
   title: 'Headless Components/Popover',
   component: Popover,
-  subcomponents: { PopoverTrigger, PopoverSurface },
+  subcomponents: { PopoverAuto, PopoverTrigger, PopoverSurface },
   parameters: {
     docs: {
       description: {

From 90a044de02b44d5b343233480ce2401102db06a8 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 19:03:03 +0200
Subject: [PATCH 14/17] refactor(react-headless-components-preview): drop
 unused ref param from usePopover/usePopoverAuto

---
 .../library/etc/popover.api.md                |  8 +++---
 .../src/components/Popover/Popover.tsx        |  2 +-
 .../src/components/Popover/PopoverAuto.tsx    |  2 +-
 .../src/components/Popover/usePopover.ts      | 27 +++++--------------
 4 files changed, 12 insertions(+), 27 deletions(-)

diff --git a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
index 53a4f66a9e0eb1..78815c00921d4e 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
@@ -129,11 +129,11 @@ export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
 // @public
 export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
 
-// @public
-export const usePopover: (props: PopoverProps, _ref: React_2.Ref<HTMLElement>) => PopoverState;
+// @public (undocumented)
+export const usePopover: (props: PopoverProps) => PopoverState;
 
-// @public
-export const usePopoverAuto: (props: PopoverProps, _ref: React_2.Ref<HTMLElement>) => PopoverState;
+// @public (undocumented)
+export const usePopoverAuto: (props: PopoverProps) => PopoverState;
 
 // @public
 export const usePopoverContext: <T>(selector: ContextSelector<PopoverContextValue, T>) => T;
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
index 563b7fe586b650..43b3e110046150 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
@@ -13,7 +13,7 @@ import { renderPopover } from './renderPopover';
  * CSS anchor positioning for placement.
  */
 export const Popover = (props: PopoverProps): JSXElement => {
-  const state = usePopover(props, null);
+  const state = usePopover(props);
   const contextValues = usePopoverContextValues(state);
 
   return renderPopover(state, contextValues);
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
index cb2d0e6bb49d3b..a467fd6292ce00 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
@@ -17,7 +17,7 @@ import { renderPopover } from './renderPopover';
  * popover dismisses any peers — both delegated to the browser's stack.
  */
 export const PopoverAuto = (props: PopoverProps): JSXElement => {
-  const state = usePopoverAuto(props, null);
+  const state = usePopoverAuto(props);
   const contextValues = usePopoverContextValues(state);
 
   return renderPopover(state, contextValues);
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index 0797f45f6bea65..ef1be72a7f3d71 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -82,8 +82,6 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
 
   const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
 
-  // In `auto` mode the browser owns light dismiss (click-outside, scroll, Escape)
-  // and emits `toggle` events we mirror back into React state.
   const isAutoMode = popoverType === 'auto' && !inline;
 
   useOnClickOutside({
@@ -139,10 +137,13 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
     if (!isAutoMode) {
       return;
     }
+
     const surface = contentRef.current;
+
     if (!surface) {
       return;
     }
+
     surface.addEventListener('toggle', onSurfaceToggle);
     return () => surface.removeEventListener('toggle', onSurfaceToggle);
   }, [isAutoMode, onSurfaceToggle]);
@@ -194,25 +195,9 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
   };
 }
 
-/**
- * Returns the state for a Popover component.
- *
- * Renders the surface with `popover="manual"`, leaving dismiss behaviour
- * (click-outside, scroll, Escape) under React's control.
- */
-export const usePopover = (props: PopoverProps, _ref: React.Ref<HTMLElement>): PopoverState =>
-  useInternalPopover(props, 'manual');
-
-/**
- * Returns the state for a PopoverAuto component.
- *
- * Renders the surface with `popover="auto"`, deferring light-dismiss
- * (Escape, click-outside, popover-stack peer dismissal) to the browser.
- * Browser `toggle` events are mirrored back into React state and
- * `onOpenChange`. The library's own dismiss hooks are disabled.
- */
-export const usePopoverAuto = (props: PopoverProps, _ref: React.Ref<HTMLElement>): PopoverState =>
-  useInternalPopover(props, 'auto');
+export const usePopover = (props: PopoverProps): PopoverState => useInternalPopover(props, 'manual');
+
+export const usePopoverAuto = (props: PopoverProps): PopoverState => useInternalPopover(props, 'auto');
 
 export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
   const {

From 17152a238960ff88dcfa3d5659629a312f5042bd Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 19:21:18 +0200
Subject: [PATCH 15/17] fix(react-headless-components-preview): attach toggle
 listener whenever the auto Popover surface (re)mounts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The toggle effect was gated on `[isAutoMode, onSurfaceToggle]` only, so it
never re-ran when `state.open` flipped and the surface JSX (`state.open ?
popoverSurface : null`) mounted a fresh DOM element. After the first
auto-mode dismiss the listener was orphaned on the old element and React
state silently drifted from the browser — Escape closed the popover
visually but `open` stayed `true`, the next click decremented it to
`false`, and the click *after that* finally re-opened it. From the
outside it looked like a laggy click and a spurious auto-open.

Folds the toggle listener into the same effect that calls `showPopover()`:
both are now bound to the surface lifecycle via `[open, inline,
popoverType, onSurfaceToggle]`, so a fresh listener attaches every time
the surface mounts and is torn down on unmount.

Also skips `setOpenState` when the toggle event reports a state we
already hold — avoids the redundant update fired by the browser's own
`toggle({newState:'open'})` after our `showPopover()` call.

Adds a parallel `NestedManual` Storybook story and a description doc that
contrasts manual vs auto nesting (light dismiss source, stack ancestry,
multiple-peer support, focus restoration). The existing `Nested` story
gains a description doc too.
---
 .../src/components/Popover/usePopover.ts      | 46 ++++++------
 .../src/Popover/PopoverNested.stories.tsx     | 10 +++
 .../src/Popover/PopoverNestedDescription.md   | 17 +++++
 .../Popover/PopoverNestedManual.stories.tsx   | 73 +++++++++++++++++++
 .../Popover/PopoverNestedManualDescription.md | 42 +++++++++++
 .../stories/src/Popover/index.stories.tsx     |  1 +
 6 files changed, 165 insertions(+), 24 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedDescription.md
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManual.stories.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md

diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index ef1be72a7f3d71..f7ce2be751f8a3 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -101,6 +101,24 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
     disabled: !open || !(openOnContext || closeOnScroll) || isAutoMode,
   });
 
+  // Mirror the browser-driven toggle events into React state when in auto mode.
+  // Covers Escape, click-outside, and the popover-stack dismissal that happens
+  // when an unrelated `popover="auto"` opens. Skip the no-op transition the
+  // browser fires for our own `showPopover()` call (newState='open' while
+  // React already has `open=true`).
+  const onSurfaceToggle = useEventCallback((event: Event) => {
+    const toggle = event as ToggleEventLike;
+    const nextOpen = toggle.newState === 'open';
+    if (nextOpen === open) {
+      return;
+    }
+    setOpenState(nextOpen);
+    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
+  });
+
+  // The surface is unmounted while closed (`state.open ? popoverSurface : null`),
+  // so this effect must re-run when `open` flips so we attach `showPopover()`
+  // and the `toggle` listener to the freshly-mounted surface element.
   React.useEffect(() => {
     const surface = contentRef.current;
 
@@ -116,37 +134,17 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
       surface.setAttribute('popover', popoverType);
     }
 
-    if (SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open')) {
-      return;
-    }
-
-    surface.showPopover();
-  }, [open, inline, popoverType]);
-
-  // Mirror the browser-driven toggle events into React state when in auto mode.
-  // Covers Escape, click-outside, and the popover-stack dismissal that happens
-  // when an unrelated `popover="auto"` opens.
-  const onSurfaceToggle = useEventCallback((event: Event) => {
-    const toggle = event as ToggleEventLike;
-    const nextOpen = toggle.newState === 'open';
-    setOpenState(nextOpen);
-    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
-  });
-
-  React.useEffect(() => {
-    if (!isAutoMode) {
-      return;
+    if (!(SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open'))) {
+      surface.showPopover();
     }
 
-    const surface = contentRef.current;
-
-    if (!surface) {
+    if (popoverType !== 'auto') {
       return;
     }
 
     surface.addEventListener('toggle', onSurfaceToggle);
     return () => surface.removeEventListener('toggle', onSurfaceToggle);
-  }, [isAutoMode, onSurfaceToggle]);
+  }, [open, inline, popoverType, onSurfaceToggle]);
 
   const children = React.Children.toArray(props.children) as React.ReactElement[];
 
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
index 7874c8990ac503..932d5863305428 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNested.stories.tsx
@@ -2,6 +2,8 @@ import * as React from 'react';
 import { PopoverAuto, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
 import type { JSXElement } from '@fluentui/react-components';
 
+import descriptionMd from './PopoverNestedDescription.md';
+
 const classes = {
   rootTrigger:
     'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
@@ -61,3 +63,11 @@ export const Nested = (): React.ReactNode => (
     </PopoverSurface>
   </PopoverAuto>
 );
+
+Nested.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedDescription.md
new file mode 100644
index 00000000000000..cc16e8bc4ac7a6
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedDescription.md
@@ -0,0 +1,17 @@
+Three popovers nested as JSX descendants using `PopoverAuto`. The browser's
+popover-stack semantics keep ancestors open while a descendant is open and
+dismiss the entire chain on light-dismiss interactions.
+
+**Behaviour:**
+
+- **Open inner** — outer surfaces stay open. The inner trigger is a DOM
+  descendant of the outer surface, so the browser places the inner popover
+  on top of the outer one in the popover stack.
+- **Escape** — closes only the topmost popover. Each press unwinds the stack
+  one level.
+- **Click outside** — closes the entire chain at once.
+- **Open an unrelated peer** — the browser's auto-popover stack dismisses any
+  current root popover; a sibling chain replaces it.
+
+Compare with the **NestedManual** story, which achieves the same nesting with
+React-driven dismiss instead of browser-driven dismiss.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManual.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManual.stories.tsx
new file mode 100644
index 00000000000000..0ea5a381ff95b7
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManual.stories.tsx
@@ -0,0 +1,73 @@
+import * as React from 'react';
+import { Popover, PopoverTrigger, PopoverSurface } from '@fluentui/react-headless-components-preview/popover';
+import type { JSXElement } from '@fluentui/react-components';
+
+import descriptionMd from './PopoverNestedManualDescription.md';
+
+const classes = {
+  rootTrigger:
+    'px-4 py-2 rounded-md bg-blue-600 text-white font-medium hover:bg-blue-700 data-[open]:bg-blue-700 focus-visible:outline-2 focus-visible:outline-blue-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  nestedTrigger:
+    'px-3 py-1.5 rounded-md bg-indigo-600 text-white text-sm font-medium hover:bg-indigo-700 data-[open]:bg-indigo-700 focus-visible:outline-2 focus-visible:outline-indigo-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  deepTrigger:
+    'px-3 py-1.5 rounded-md bg-purple-600 text-white text-sm font-medium hover:bg-purple-700 data-[open]:bg-purple-700 focus-visible:outline-2 focus-visible:outline-purple-500 focus-visible:outline-offset-2 cursor-pointer border-none',
+  actionButton:
+    'px-3 py-1.5 rounded-md bg-gray-200 text-gray-900 text-sm font-medium hover:bg-gray-300 cursor-pointer border-none',
+  surface: 'bg-white rounded-lg shadow-lg border border-gray-200 p-4 min-w-[240px] max-w-xs flex flex-col gap-3',
+  heading: 'text-sm font-semibold text-gray-900 m-0',
+  body: 'text-sm text-gray-600',
+  row: 'flex flex-wrap items-center gap-2',
+};
+
+const SecondNestedPopover = (): JSXElement => (
+  <Popover>
+    <PopoverTrigger>
+      <button className={classes.deepTrigger}>Second nested trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <button className={classes.actionButton}>Second nested button</button>
+    </PopoverSurface>
+  </Popover>
+);
+
+const FirstNestedPopover = (): JSXElement => (
+  <Popover>
+    <PopoverTrigger>
+      <button className={classes.nestedTrigger}>First nested trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <button className={classes.actionButton}>First nested button</button>
+      <div className={classes.row}>
+        <SecondNestedPopover />
+      </div>
+    </PopoverSurface>
+  </Popover>
+);
+
+export const NestedManual = (): React.ReactNode => (
+  <Popover>
+    <PopoverTrigger>
+      <button className={classes.rootTrigger}>Root trigger</button>
+    </PopoverTrigger>
+    <PopoverSurface className={classes.surface}>
+      <h3 className={classes.heading}>Popover content</h3>
+      <div className={classes.body}>This is some popover content.</div>
+      <div className={classes.row}>
+        <button className={classes.actionButton}>Root button</button>
+        <FirstNestedPopover />
+      </div>
+    </PopoverSurface>
+  </Popover>
+);
+
+NestedManual.parameters = {
+  docs: {
+    description: {
+      story: descriptionMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md
new file mode 100644
index 00000000000000..320d0f4202da17
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md
@@ -0,0 +1,42 @@
+Three popovers nested as JSX descendants using `Popover` (manual mode). All
+dismiss behaviour runs through React handlers — the browser is just a
+top-layer painter for the surface, not a state authority.
+
+**Behaviour:**
+
+- **Open inner** — `useOnClickOutside` on each Popover treats clicks on its
+  own `triggerRef` and `contentRef` as "inside". Because the inner trigger
+  and surface are JSX descendants of the outer surface, opening the inner
+  doesn't fire the outer's outside-click dismiss. Outers stay open.
+- **Escape** — `PopoverSurface.onKeyDown` filters via
+  `e.target.closest('[data-popover-surface]') === ownSurface`, so the
+  Escape keydown event bubbles through every ancestor surface but only the
+  innermost surface (the closest one) matches and closes. Outers stay open.
+- **Click outside** — every popover's `useOnClickOutside` fires
+  independently; the entire chain closes.
+- **Open an unrelated peer** — manual popovers do **not** auto-dismiss each
+  other. Two unrelated chains can be open at the same time.
+
+## How this differs from `Nested` (auto mode)
+
+| Aspect                | `Popover` (manual)                                   | `PopoverAuto` (auto)                                         |
+| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
+| Source of truth       | React state                                          | React state mirrored from browser `toggle` events            |
+| Light dismiss         | `useOnClickOutside`, `useOnScrollOutside`, React Esc | Browser-driven (Escape, click-outside, popover stack)        |
+| Esc filter            | `closest('[data-popover-surface]') === self`         | Browser closes only the topmost popover in its stack         |
+| Stack ancestry        | DOM nesting + React click/Escape filters             | DOM nesting (or `popovertarget` linkage) per HTML spec       |
+| Multiple open peers   | ✅ Allowed — any number of unrelated popovers open   | ❌ Browser dismisses non-ancestor popovers when a peer opens |
+| `popover` attribute   | `popover="manual"`                                   | `popover="auto"`                                             |
+| Hover / context modes | Fully supported (`openOnHover`, `openOnContext`)     | Open paths still React-driven; close paths defer to browser  |
+| Focus restoration     | None built in                                        | Browser restores focus to the invoker on dismiss             |
+| Predictability        | Behaviour is whatever React handlers say             | Behaviour follows the HTML Popover spec across all browsers  |
+
+**When to pick which:**
+
+- Reach for `PopoverAuto` when the popover is a single, modal-ish surface and
+  you want the browser's dismiss timing, focus restoration, and stack
+  semantics for free.
+- Reach for `Popover` when you need multiple unrelated popovers open at once,
+  hover/context-driven open with custom dismiss timing
+  (`mouseLeaveDelay`, `closeOnScroll`), or precise control over which event
+  closes which surface.
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
index cd22d3a8baf36b..4f859742a588f5 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/index.stories.tsx
@@ -17,6 +17,7 @@ export { CustomTrigger } from './PopoverCustomTrigger.stories';
 export { WithoutTrigger } from './PopoverWithoutTrigger.stories';
 export { AnchorToCustomTarget } from './PopoverAnchorToCustomTarget.stories';
 export { Nested } from './PopoverNested.stories';
+export { NestedManual } from './PopoverNestedManual.stories';
 export { InternalUpdateContent } from './PopoverInternalUpdateContent.stories';
 export { Inline } from './PopoverInline.stories';
 

From 578d74fddfa2283e4f0d73b51e0f8f72e4f08da0 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 19:28:44 +0200
Subject: [PATCH 16/17] refactor(react-headless-components-preview): split
 usePopover and usePopoverAuto for tree-shaking

No behaviour change. Tests, type-check, lint, and api-report all pass.
---
 .../library/etc/popover.api.md                |   4 +-
 .../src/components/Popover/Popover.tsx        |   3 +-
 .../src/components/Popover/PopoverAuto.tsx    |   3 +-
 .../PopoverSurface/usePopoverSurface.ts       |  11 +-
 .../library/src/components/Popover/index.ts   |   4 +-
 .../src/components/Popover/usePopover.ts      | 230 ++----------------
 .../src/components/Popover/usePopoverAuto.ts  |  52 ++++
 .../src/components/Popover/usePopoverBase.ts  | 202 +++++++++++++++
 8 files changed, 295 insertions(+), 214 deletions(-)
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverAuto.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverBase.ts

diff --git a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
index 78815c00921d4e..80e1b00b4aba06 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/popover.api.md
@@ -129,10 +129,10 @@ export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
 // @public
 export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
 
-// @public (undocumented)
+// @public
 export const usePopover: (props: PopoverProps) => PopoverState;
 
-// @public (undocumented)
+// @public
 export const usePopoverAuto: (props: PopoverProps) => PopoverState;
 
 // @public
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
index 43b3e110046150..ff6254b6f363fb 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.tsx
@@ -2,7 +2,8 @@
 
 import type { PopoverProps } from './Popover.types';
 import type { JSXElement } from '@fluentui/react-utilities';
-import { usePopover, usePopoverContextValues } from './usePopover';
+import { usePopover } from './usePopover';
+import { usePopoverContextValues } from './usePopoverBase';
 import { renderPopover } from './renderPopover';
 
 /**
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
index a467fd6292ce00..1ebbc4cf49ce37 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverAuto.tsx
@@ -2,7 +2,8 @@
 
 import type { PopoverProps } from './Popover.types';
 import type { JSXElement } from '@fluentui/react-utilities';
-import { usePopoverAuto, usePopoverContextValues } from './usePopover';
+import { usePopoverAuto } from './usePopoverAuto';
+import { usePopoverContextValues } from './usePopoverBase';
 import { renderPopover } from './renderPopover';
 
 /**
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
index 6cf2c70a267393..4a3dcf77bd04e4 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts
@@ -11,6 +11,7 @@ import type { PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.
  */
 export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTMLDivElement>): PopoverSurfaceState => {
   const contentRef = usePopoverContext(context => context.contentRef);
+  const triggerRef = usePopoverContext(context => context.triggerRef);
   const openOnHover = usePopoverContext(context => context.openOnHover);
   const setOpen = usePopoverContext(context => context.setOpen);
   const arrowRef = usePopoverContext(context => context.arrowRef);
@@ -66,12 +67,20 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   });
 
   state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
-    if (!browserHandlesDismiss && e.key === 'Escape') {
+    // `isDefaultPrevented` lets a nested trigger / inner surface close itself
+    // first and tell ancestors the Escape is already handled — without it,
+    // a single Escape would walk up the React tree and close every surface
+    // whose `data-popover-surface` ancestry happens to enclose `e.target`.
+    if (!browserHandlesDismiss && e.key === 'Escape' && !e.isDefaultPrevented()) {
       const target = e.target as HTMLElement;
       const surface = contentRef.current;
       if (surface && target.closest('[data-popover-surface]') === surface) {
         e.preventDefault();
         setOpen(e, false);
+        // Native `popover="manual"` does not restore focus; do it ourselves so
+        // Escape inside the surface lands back on the trigger (matches the
+        // chained Escape behaviour in nested popovers).
+        triggerRef.current?.focus();
       }
     }
 
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
index 8330fac9c5d8bf..d20eee762248ea 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/index.ts
@@ -1,7 +1,9 @@
 export { Popover } from './Popover';
 export { PopoverAuto } from './PopoverAuto';
 export { renderPopover } from './renderPopover';
-export { usePopover, usePopoverAuto, usePopoverContextValues } from './usePopover';
+export { usePopover } from './usePopover';
+export { usePopoverAuto } from './usePopoverAuto';
+export { usePopoverContextValues } from './usePopoverBase';
 export { usePopoverContext } from './popoverContext';
 export type {
   PopoverProps,
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
index f7ce2be751f8a3..0d01c533c52288 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts
@@ -1,95 +1,33 @@
 'use client';
 
 import * as React from 'react';
-import {
-  useControllableState,
-  useEventCallback,
-  useOnClickOutside,
-  useOnScrollOutside,
-  elementContains,
-  useTimeout,
-} from '@fluentui/react-utilities';
+import { useOnClickOutside, useOnScrollOutside, elementContains } from '@fluentui/react-utilities';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
-import { usePositioning, resolvePositioningShorthand } from '../../hooks';
-import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents, PopoverType } from './Popover.types';
+import type { PopoverProps, PopoverState } from './Popover.types';
+import { usePopoverBase, ensureNativePopoverShown } from './usePopoverBase';
+
+export { usePopoverContextValues } from './usePopoverBase';
+
+/**
+ * Returns the state for a Popover component.
+ *
+ * Renders the surface with `popover="manual"`, leaving dismiss behaviour
+ * (click-outside, scroll, Escape) under React's control. Open state is
+ * the React state — the surface is in the top layer for painting only,
+ * never owns visibility decisions.
+ */
+export const usePopover = (props: PopoverProps): PopoverState => {
+  const base = usePopoverBase(props);
+  const { open, setOpen, triggerRef, contentRef, inline, openOnContext, closeOnScroll, closeOnIframeFocus } = base;
 
-const SUPPORTS_POPOVER_OPEN_SELECTOR =
-  typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
-
-type ToggleEventLike = Event & { newState?: 'open' | 'closed' };
-
-function useInternalPopover(props: PopoverProps, popoverType: PopoverType): PopoverState {
-  const {
-    openOnHover = false,
-    openOnContext = false,
-    mouseLeaveDelay = 500,
-    withArrow = false,
-    disableAutoFocus = false,
-    closeOnScroll = false,
-    closeOnIframeFocus = true,
-    inline = false,
-    mountNode,
-  } = props;
-
-  const [open, setOpenState] = useControllableState({
-    state: props.open,
-    defaultState: props.defaultOpen,
-    initialState: false,
-  });
-
-  const [contextTarget, setContextTarget] = React.useState<{ x: number; y: number } | undefined>(undefined);
   const { targetDocument } = useFluent();
 
-  const onOpenChange = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
-    props.onOpenChange?.(e, { event: e, type: e.type, open: shouldOpen });
-  });
-
-  const [setOpenTimeout, clearOpenTimeout] = useTimeout();
-
-  const setOpen = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
-    clearOpenTimeout();
-
-    if (shouldOpen && e.type === 'contextmenu') {
-      const mouseEvent = e as React.MouseEvent<HTMLElement>;
-      setContextTarget({ x: mouseEvent.clientX, y: mouseEvent.clientY });
-    }
-
-    if (!shouldOpen) {
-      setContextTarget(undefined);
-    }
-
-    if (e.type === 'mouseleave') {
-      setOpenTimeout(() => {
-        setOpenState(shouldOpen);
-        onOpenChange(e, shouldOpen);
-      }, mouseLeaveDelay);
-    } else {
-      setOpenState(shouldOpen);
-      onOpenChange(e, shouldOpen);
-    }
-  });
-
-  const toggleOpen = React.useCallback(
-    (e: OpenPopoverEvents) => {
-      setOpen(e, !open);
-    },
-    [setOpen, open],
-  );
-
-  const triggerRef = React.useRef<HTMLElement>(null);
-  const contentRef = React.useRef<HTMLElement>(null);
-  const arrowRef = React.useRef<HTMLDivElement>(null);
-
-  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
-
-  const isAutoMode = popoverType === 'auto' && !inline;
-
   useOnClickOutside({
     contains: elementContains,
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open || isAutoMode,
+    disabled: !open,
     disabledFocusOnIframe: !closeOnIframeFocus,
   });
 
@@ -98,27 +36,9 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open || !(openOnContext || closeOnScroll) || isAutoMode,
+    disabled: !open || !(openOnContext || closeOnScroll),
   });
 
-  // Mirror the browser-driven toggle events into React state when in auto mode.
-  // Covers Escape, click-outside, and the popover-stack dismissal that happens
-  // when an unrelated `popover="auto"` opens. Skip the no-op transition the
-  // browser fires for our own `showPopover()` call (newState='open' while
-  // React already has `open=true`).
-  const onSurfaceToggle = useEventCallback((event: Event) => {
-    const toggle = event as ToggleEventLike;
-    const nextOpen = toggle.newState === 'open';
-    if (nextOpen === open) {
-      return;
-    }
-    setOpenState(nextOpen);
-    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
-  });
-
-  // The surface is unmounted while closed (`state.open ? popoverSurface : null`),
-  // so this effect must re-run when `open` flips so we attach `showPopover()`
-  // and the `toggle` listener to the freshly-mounted surface element.
   React.useEffect(() => {
     const surface = contentRef.current;
 
@@ -126,114 +46,8 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
       return;
     }
 
-    if (typeof surface.showPopover !== 'function') {
-      return;
-    }
-
-    if (!surface.hasAttribute('popover') || surface.getAttribute('popover') !== popoverType) {
-      surface.setAttribute('popover', popoverType);
-    }
-
-    if (!(SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open'))) {
-      surface.showPopover();
-    }
-
-    if (popoverType !== 'auto') {
-      return;
-    }
-
-    surface.addEventListener('toggle', onSurfaceToggle);
-    return () => surface.removeEventListener('toggle', onSurfaceToggle);
-  }, [open, inline, popoverType, onSurfaceToggle]);
-
-  const children = React.Children.toArray(props.children) as React.ReactElement[];
-
-  if (process.env.NODE_ENV !== 'production') {
-    if (children.length === 0) {
-      // eslint-disable-next-line no-console
-      console.warn('Popover must contain at least one child');
-    }
-
-    if (children.length > 2) {
-      // eslint-disable-next-line no-console
-      console.warn('Popover must contain at most two children');
-    }
-  }
-
-  let popoverTrigger: React.ReactElement | undefined;
-  let popoverSurface: React.ReactElement | undefined;
-
-  if (children.length === 2) {
-    popoverTrigger = children[0];
-    popoverSurface = children[1];
-  } else if (children.length === 1) {
-    popoverSurface = children[0];
-  }
-
-  return {
-    open,
-    setOpen,
-    toggleOpen,
-    triggerRef,
-    contentRef,
-    arrowRef,
-    popoverTrigger,
-    popoverSurface,
-    openOnHover,
-    openOnContext,
-    withArrow,
-    disableAutoFocus,
-    inline,
-    mountNode,
-    onOpenChange: props.onOpenChange,
-    contextTarget,
-    setContextTarget,
-    positioning,
-    popoverType,
-  };
-}
-
-export const usePopover = (props: PopoverProps): PopoverState => useInternalPopover(props, 'manual');
-
-export const usePopoverAuto = (props: PopoverProps): PopoverState => useInternalPopover(props, 'auto');
-
-export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
-  const {
-    open,
-    setOpen,
-    toggleOpen,
-    triggerRef,
-    contentRef,
-    arrowRef,
-    openOnHover,
-    openOnContext,
-    disableAutoFocus,
-    withArrow,
-    inline,
-    mountNode,
-    positioning,
-    popoverType,
-  } = state;
+    ensureNativePopoverShown(surface, 'manual');
+  }, [open, inline, contentRef]);
 
-  return {
-    popover: {
-      open,
-      setOpen,
-      toggleOpen,
-      triggerRef,
-      contentRef,
-      arrowRef,
-      openOnHover,
-      openOnContext,
-      disableAutoFocus,
-      withArrow,
-      inline,
-      mountNode,
-      popoverType,
-      positioning: {
-        targetRef: positioning.targetRef,
-        containerRef: positioning.containerRef,
-      },
-    },
-  };
+  return { ...base, popoverType: 'manual' };
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverAuto.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverAuto.ts
new file mode 100644
index 00000000000000..b75f35a3ac5ec5
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverAuto.ts
@@ -0,0 +1,52 @@
+'use client';
+
+import * as React from 'react';
+import { useEventCallback } from '@fluentui/react-utilities';
+import type { PopoverProps, PopoverState } from './Popover.types';
+import { usePopoverBase, ensureNativePopoverShown } from './usePopoverBase';
+
+type ToggleEventLike = Event & { newState?: 'open' | 'closed' };
+
+/**
+ * Returns the state for a PopoverAuto component.
+ *
+ * Renders the surface with `popover="auto"`, deferring light-dismiss
+ * (Escape, click-outside, popover-stack peer dismissal) to the browser.
+ * Browser `toggle` events are mirrored back into React state and
+ * `onOpenChange`. The library's React-driven dismiss hooks
+ * (`useOnClickOutside`, `useOnScrollOutside`) are never imported here, so
+ * a bundle that only uses `PopoverAuto` does not pull them in.
+ */
+export const usePopoverAuto = (props: PopoverProps): PopoverState => {
+  const base = usePopoverBase(props);
+  const { open, setOpenState, contentRef, inline } = base;
+
+  // Skip the no-op transition the browser fires for our own `showPopover()`
+  // call (newState='open' while React already has `open=true`).
+  const onSurfaceToggle = useEventCallback((event: Event) => {
+    const toggle = event as ToggleEventLike;
+    const nextOpen = toggle.newState === 'open';
+    if (nextOpen === open) {
+      return;
+    }
+    setOpenState(nextOpen);
+    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
+  });
+
+  // The surface is unmounted while closed (`state.open ? popoverSurface : null`),
+  // so this effect must re-run when `open` flips so we attach `showPopover()`
+  // and the `toggle` listener to the freshly-mounted surface element.
+  React.useEffect(() => {
+    const surface = contentRef.current;
+
+    if (!surface || inline || !open) {
+      return;
+    }
+
+    ensureNativePopoverShown(surface, 'auto');
+    surface.addEventListener('toggle', onSurfaceToggle);
+    return () => surface.removeEventListener('toggle', onSurfaceToggle);
+  }, [open, inline, contentRef, onSurfaceToggle]);
+
+  return { ...base, popoverType: 'auto' };
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverBase.ts b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverBase.ts
new file mode 100644
index 00000000000000..5ac2e9c3234840
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopoverBase.ts
@@ -0,0 +1,202 @@
+'use client';
+
+import * as React from 'react';
+import { useControllableState, useEventCallback, useTimeout } from '@fluentui/react-utilities';
+import { usePositioning, resolvePositioningShorthand } from '../../hooks';
+import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents, PopoverType } from './Popover.types';
+
+/**
+ * Mode-agnostic Popover state. Shared by `usePopover` (manual) and
+ * `usePopoverAuto` (auto). Holds open state, refs, positioning, the merged
+ * `setOpen` / `toggleOpen` callbacks, and the parsed trigger / surface
+ * children. Each mode hook layers its own dismiss / show-popover effects on
+ * top.
+ */
+export type PopoverBase = Omit<PopoverState, 'popoverType'> & {
+  setOpenState: (open: boolean) => void;
+  closeOnScroll: boolean;
+  closeOnIframeFocus: boolean;
+};
+
+export function usePopoverBase(props: PopoverProps): PopoverBase {
+  const {
+    openOnHover = false,
+    openOnContext = false,
+    mouseLeaveDelay = 500,
+    withArrow = false,
+    disableAutoFocus = false,
+    closeOnScroll = false,
+    closeOnIframeFocus = true,
+    inline = false,
+    mountNode,
+  } = props;
+
+  const [open, setOpenState] = useControllableState({
+    state: props.open,
+    defaultState: props.defaultOpen,
+    initialState: false,
+  });
+
+  const [contextTarget, setContextTarget] = React.useState<{ x: number; y: number } | undefined>(undefined);
+
+  const onOpenChange = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
+    props.onOpenChange?.(e, { event: e, type: e.type, open: shouldOpen });
+  });
+
+  const [setOpenTimeout, clearOpenTimeout] = useTimeout();
+
+  const setOpen = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
+    clearOpenTimeout();
+
+    if (shouldOpen && e.type === 'contextmenu') {
+      const mouseEvent = e as React.MouseEvent<HTMLElement>;
+      setContextTarget({ x: mouseEvent.clientX, y: mouseEvent.clientY });
+    }
+
+    if (!shouldOpen) {
+      setContextTarget(undefined);
+    }
+
+    if (e.type === 'mouseleave') {
+      setOpenTimeout(() => {
+        setOpenState(shouldOpen);
+        onOpenChange(e, shouldOpen);
+      }, mouseLeaveDelay);
+    } else {
+      setOpenState(shouldOpen);
+      onOpenChange(e, shouldOpen);
+    }
+  });
+
+  const toggleOpen = React.useCallback(
+    (e: OpenPopoverEvents) => {
+      setOpen(e, !open);
+    },
+    [setOpen, open],
+  );
+
+  const triggerRef = React.useRef<HTMLElement>(null);
+  const contentRef = React.useRef<HTMLElement>(null);
+  const arrowRef = React.useRef<HTMLDivElement>(null);
+
+  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
+
+  const children = React.Children.toArray(props.children) as React.ReactElement[];
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (children.length === 0) {
+      // eslint-disable-next-line no-console
+      console.warn('Popover must contain at least one child');
+    }
+
+    if (children.length > 2) {
+      // eslint-disable-next-line no-console
+      console.warn('Popover must contain at most two children');
+    }
+  }
+
+  let popoverTrigger: React.ReactElement | undefined;
+  let popoverSurface: React.ReactElement | undefined;
+
+  if (children.length === 2) {
+    popoverTrigger = children[0];
+    popoverSurface = children[1];
+  } else if (children.length === 1) {
+    popoverSurface = children[0];
+  }
+
+  return {
+    open,
+    setOpenState,
+    setOpen,
+    toggleOpen,
+    triggerRef,
+    contentRef,
+    arrowRef,
+    popoverTrigger,
+    popoverSurface,
+    openOnHover,
+    openOnContext,
+    withArrow,
+    disableAutoFocus,
+    inline,
+    mountNode,
+    onOpenChange: props.onOpenChange,
+    contextTarget,
+    setContextTarget,
+    positioning,
+    closeOnScroll,
+    closeOnIframeFocus,
+  };
+}
+
+/**
+ * Common feature-detect for `:popover-open` selector support — used by both
+ * mode hooks to avoid double-calling `showPopover()` on an already-open
+ * surface.
+ */
+export const SUPPORTS_POPOVER_OPEN_SELECTOR =
+  typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
+
+export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
+  const {
+    open,
+    setOpen,
+    toggleOpen,
+    triggerRef,
+    contentRef,
+    arrowRef,
+    openOnHover,
+    openOnContext,
+    disableAutoFocus,
+    withArrow,
+    inline,
+    mountNode,
+    positioning,
+    popoverType,
+  } = state;
+
+  return {
+    popover: {
+      open,
+      setOpen,
+      toggleOpen,
+      triggerRef,
+      contentRef,
+      arrowRef,
+      openOnHover,
+      openOnContext,
+      disableAutoFocus,
+      withArrow,
+      inline,
+      mountNode,
+      popoverType,
+      positioning: {
+        targetRef: positioning.targetRef,
+        containerRef: positioning.containerRef,
+      },
+    },
+  };
+};
+
+/**
+ * Helper used by both mode hooks: writes `popover="<mode>"` on the surface
+ * if missing or different, and calls `showPopover()` unless the surface is
+ * already in the open state. No-op when the platform lacks the HTML Popover
+ * API.
+ */
+export function ensureNativePopoverShown(surface: HTMLElement, popoverType: PopoverType): void {
+  if (typeof surface.showPopover !== 'function') {
+    return;
+  }
+
+  if (!surface.hasAttribute('popover') || surface.getAttribute('popover') !== popoverType) {
+    surface.setAttribute('popover', popoverType);
+  }
+
+  if (SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open')) {
+    return;
+  }
+
+  surface.showPopover();
+}

From ce13da98dc7670998c40a75aa67f9654e6b1ffb5 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Mon, 27 Apr 2026 19:31:04 +0200
Subject: [PATCH 17/17] docs(react-headless-components-preview): shorten
 manual-vs-auto nested comparison

---
 .../library/docs/popover-spec.md              |  2 +-
 .../Popover/PopoverNestedManualDescription.md | 28 ++++++-------------
 2 files changed, 9 insertions(+), 21 deletions(-)

diff --git a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
index b4ff4be6b93055..e3a863157240a5 100644
--- a/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
+++ b/packages/react-components/react-headless-components-preview/library/docs/popover-spec.md
@@ -133,7 +133,7 @@ This iteration ships **no built-in focus management**:
 
 - **No auto-focus on open.** The browser handles focus naturally. Top-layer popovers (`popover="manual"`) leave focus on the trigger; consumers can call `.focus()` on the surface or a descendant if needed.
 - **No focus trap.** Tab / Shift+Tab follow the document's normal tab order. With a top-layer surface, focus may move to elements behind the surface — that's expected for a non-modal popover.
-- **No focus restore.** When the surface unmounts, focus stays wherever the dismissal interaction left it (typically the trigger after click / Escape; arbitrary after click-outside).
+- **Focus restore on Escape only.** When Escape is pressed inside the surface, focus moves back to the trigger (native `popover="manual"` does not restore focus, so the surface's Escape handler does it explicitly). All other dismissal paths (click-outside, scroll-outside, programmatic close) leave focus wherever the interaction left it.
 - **`disableAutoFocus`** is preserved on `PopoverProps` for API stability but is currently inert. It will become meaningful again together with the upcoming focus hook.
 
 ### Labeling
diff --git a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md
index 320d0f4202da17..6d0f9a5d94c86a 100644
--- a/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md
+++ b/packages/react-components/react-headless-components-preview/stories/src/Popover/PopoverNestedManualDescription.md
@@ -19,24 +19,12 @@ top-layer painter for the surface, not a state authority.
 
 ## How this differs from `Nested` (auto mode)
 
-| Aspect                | `Popover` (manual)                                   | `PopoverAuto` (auto)                                         |
-| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
-| Source of truth       | React state                                          | React state mirrored from browser `toggle` events            |
-| Light dismiss         | `useOnClickOutside`, `useOnScrollOutside`, React Esc | Browser-driven (Escape, click-outside, popover stack)        |
-| Esc filter            | `closest('[data-popover-surface]') === self`         | Browser closes only the topmost popover in its stack         |
-| Stack ancestry        | DOM nesting + React click/Escape filters             | DOM nesting (or `popovertarget` linkage) per HTML spec       |
-| Multiple open peers   | ✅ Allowed — any number of unrelated popovers open   | ❌ Browser dismisses non-ancestor popovers when a peer opens |
-| `popover` attribute   | `popover="manual"`                                   | `popover="auto"`                                             |
-| Hover / context modes | Fully supported (`openOnHover`, `openOnContext`)     | Open paths still React-driven; close paths defer to browser  |
-| Focus restoration     | None built in                                        | Browser restores focus to the invoker on dismiss             |
-| Predictability        | Behaviour is whatever React handlers say             | Behaviour follows the HTML Popover spec across all browsers  |
+`PopoverAuto` defers dismiss to the browser via `popover="auto"`, so Escape,
+click-outside, and the popover-stack peer-dismissal happen at HTML-spec
+timing and focus is restored to the invoker for free. The trade-off is
+that the browser only allows one root chain open at a time — opening an
+unrelated peer dismisses the existing root.
 
-**When to pick which:**
-
-- Reach for `PopoverAuto` when the popover is a single, modal-ish surface and
-  you want the browser's dismiss timing, focus restoration, and stack
-  semantics for free.
-- Reach for `Popover` when you need multiple unrelated popovers open at once,
-  hover/context-driven open with custom dismiss timing
-  (`mouseLeaveDelay`, `closeOnScroll`), or precise control over which event
-  closes which surface.
+Use `PopoverAuto` when you want native, single-root behaviour. Use
+`Popover` when you need multiple unrelated popovers open simultaneously
+or hover/context-driven open with custom dismiss timing.