From 914e61f447c8e83fb2afe03889f87c04790be3a9 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Thu, 21 May 2026 16:08:24 +0200
Subject: [PATCH] feat(react-headless-components-preview): add Portal component
 and use it in non-modal DialogSurface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a headless Portal that renders children into a mount node (defaults
to targetDocument.body) while keeping a stable <span hidden> anchor at
the original tree location for SSR-safe hydration. Links the mount node
to the anchor via setVirtualParent so DOM-walking utilities work across
the portal boundary.

Non-modal DialogSurface now uses Portal instead of inline createPortal,
which fixes a hydration mismatch when the dialog is open during initial
render. No dependency on @fluentui/react-portal — the headless package
must stay Griffel-free per package constraints.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 ...-f9577e9e-d815-4074-9b9d-0853bf452276.json |   7 ++
 .../library/etc/dialog.api.md                 |   1 +
 .../library/etc/portal.api.md                 |  33 ++++++
 .../library/package.json                      |   6 ++
 .../DialogSurface/DialogSurface.types.ts      |   6 ++
 .../DialogSurface/renderDialogSurface.tsx     |  16 +--
 .../Dialog/DialogSurface/useDialogSurface.ts  |   1 +
 .../src/components/Portal/Portal.test.tsx     | 100 ++++++++++++++++++
 .../library/src/components/Portal/Portal.tsx  |  23 ++++
 .../src/components/Portal/Portal.types.ts     |  37 +++++++
 .../library/src/components/Portal/index.ts    |   4 +
 .../src/components/Portal/renderPortal.tsx    |  24 +++++
 .../src/components/Portal/usePortal.ts        |  54 ++++++++++
 .../library/src/portal.ts                     |   2 +
 14 files changed, 308 insertions(+), 6 deletions(-)
 create mode 100644 change/@fluentui-react-headless-components-preview-f9577e9e-d815-4074-9b9d-0853bf452276.json
 create mode 100644 packages/react-components/react-headless-components-preview/library/etc/portal.api.md
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.test.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.types.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/index.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/renderPortal.tsx
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/components/Portal/usePortal.ts
 create mode 100644 packages/react-components/react-headless-components-preview/library/src/portal.ts

diff --git a/change/@fluentui-react-headless-components-preview-f9577e9e-d815-4074-9b9d-0853bf452276.json b/change/@fluentui-react-headless-components-preview-f9577e9e-d815-4074-9b9d-0853bf452276.json
new file mode 100644
index 00000000000000..f7db6d7795ca9a
--- /dev/null
+++ b/change/@fluentui-react-headless-components-preview-f9577e9e-d815-4074-9b9d-0853bf452276.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat(react-headless-components-preview): add Portal component and use it for non-modal DialogSurface",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "dmytrokirpa@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/react-components/react-headless-components-preview/library/etc/dialog.api.md b/packages/react-components/react-headless-components-preview/library/etc/dialog.api.md
index a247dfd61f5487..1ca9d942b9920d 100644
--- a/packages/react-components/react-headless-components-preview/library/etc/dialog.api.md
+++ b/packages/react-components/react-headless-components-preview/library/etc/dialog.api.md
@@ -143,6 +143,7 @@ export type DialogSurfaceState = ComponentState<DialogSurfaceSlots> & {
     unmountOnClose: boolean;
     modalType: DialogModalType;
     shouldRender: boolean;
+    mountNode?: HTMLElement;
 };
 
 // @public
diff --git a/packages/react-components/react-headless-components-preview/library/etc/portal.api.md b/packages/react-components/react-headless-components-preview/library/etc/portal.api.md
new file mode 100644
index 00000000000000..963cf4a28a7fd3
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/etc/portal.api.md
@@ -0,0 +1,33 @@
+## 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 { JSXElement } from '@fluentui/react-utilities';
+import type * as React_2 from 'react';
+
+// @public
+export const Portal: React_2.FC<PortalProps>;
+
+// @public (undocumented)
+export type PortalProps = {
+    children?: React_2.ReactNode;
+    mountNode?: HTMLElement | null;
+};
+
+// @public (undocumented)
+export type PortalState = Pick<PortalProps, 'children'> & {
+    mountNode: HTMLElement | null | undefined;
+    anchorRef: React_2.MutableRefObject<HTMLSpanElement | null>;
+};
+
+// @public
+export const renderPortal: (state: PortalState) => JSXElement;
+
+// @public
+export const usePortal: (props: PortalProps) => PortalState;
+
+// (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 052eea0466081a..6db3f8133b87a8 100644
--- a/packages/react-components/react-headless-components-preview/library/package.json
+++ b/packages/react-components/react-headless-components-preview/library/package.json
@@ -204,6 +204,12 @@
       "import": "./lib/popover.js",
       "require": "./lib-commonjs/popover.js"
     },
+    "./portal": {
+      "types": "./dist/portal.d.ts",
+      "node": "./lib-commonjs/portal.js",
+      "import": "./lib/portal.js",
+      "require": "./lib-commonjs/portal.js"
+    },
     "./positioning": {
       "types": "./dist/positioning.d.ts",
       "node": "./lib-commonjs/positioning.js",
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/DialogSurface.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/DialogSurface.types.ts
index d9d4f400ef6179..24f6db6b4326dd 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/DialogSurface.types.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/DialogSurface.types.ts
@@ -44,4 +44,10 @@ export type DialogSurfaceState = ComponentState<DialogSurfaceSlots> & {
    * browser run its native close-the-dialog focus restoration.
    */
   shouldRender: boolean;
+
+  /**
+   * The DOM element to render the dialog into when `modalType` is `non-modal`.
+   * Ignored for modal dialogs, which are always rendered in the browser top layer.
+   */
+  mountNode?: HTMLElement;
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/renderDialogSurface.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/renderDialogSurface.tsx
index 1f81afb1b5a30a..94ee4b5566c8a8 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/renderDialogSurface.tsx
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/renderDialogSurface.tsx
@@ -1,9 +1,9 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource @fluentui/react-jsx-runtime */
 
-import { Portal } from '@fluentui/react-portal';
 import { assertSlots } from '@fluentui/react-utilities';
 import type { JSXElement } from '@fluentui/react-utilities';
+import { Portal } from '../../Portal';
 import { DialogSurfaceContext } from '../dialogContext';
 import type { DialogSurfaceSlots, DialogSurfaceState } from './DialogSurface.types';
 
@@ -12,10 +12,10 @@ import type { DialogSurfaceSlots, DialogSurfaceState } from './DialogSurface.typ
  * Returns null when the dialog is closed and unmountOnClose is true.
  * Provides DialogSurfaceContext=true so DialogTrigger inside defaults to action="close".
  *
- * Non-modal dialogs are rendered via a React portal into `document.body`.
- * Unlike `showModal()`, `dialog.show()` does not enter the browser top layer, so the
- * element is still subject to ancestor `overflow`, `clip-path`, and `transform`
- * stacking constraints. Portalling to body moves it outside any such container.
+ * Non-modal dialogs are wrapped in a `Portal` so they escape ancestor stacking
+ * constraints (`overflow`, `clip-path`, `transform`). Unlike `showModal()`,
+ * `dialog.show()` does not enter the browser top layer. Modal/alert dialogs use
+ * `showModal()` and need no portal — they live in the top layer.
  * React context (including DialogContext) is preserved across portals.
  */
 export const renderDialogSurface = (state: DialogSurfaceState): JSXElement | null => {
@@ -31,5 +31,9 @@ export const renderDialogSurface = (state: DialogSurfaceState): JSXElement | nul
     </DialogSurfaceContext.Provider>
   );
 
-  return state.modalType === 'non-modal' ? <Portal>{content}</Portal> : content;
+  if (state.modalType === 'non-modal') {
+    return <Portal mountNode={state.mountNode}>{content}</Portal>;
+  }
+
+  return content;
 };
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/useDialogSurface.ts b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/useDialogSurface.ts
index 4335bb33a1ec12..8bedd6d43dcab0 100644
--- a/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/useDialogSurface.ts
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Dialog/DialogSurface/useDialogSurface.ts
@@ -145,6 +145,7 @@ export const useDialogSurface = (props: DialogSurfaceProps, ref: React.Ref<HTMLD
     open,
     unmountOnClose,
     modalType,
+    mountNode: targetDocument?.body ?? undefined,
     shouldRender,
     root: slot.always(
       getIntrinsicElementProps('dialog', {
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.test.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.test.tsx
new file mode 100644
index 00000000000000..af98fde70c0b42
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.test.tsx
@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { render } from '@testing-library/react';
+import { getParent } from '@fluentui/react-utilities';
+import { isConformant } from '../../testing/isConformant';
+import { Portal } from './Portal';
+
+describe('Portal', () => {
+  isConformant({
+    Component: Portal,
+    displayName: 'Portal',
+    disabledTests: ['component-handles-classname', 'component-has-root-ref', 'component-handles-ref'],
+  });
+
+  it('renders children into document.body by default', () => {
+    const { getByTestId, baseElement } = render(
+      <Portal>
+        <div data-testid="portal-child">Content</div>
+      </Portal>,
+    );
+
+    const child = getByTestId('portal-child');
+    expect(child.parentElement).toBe(baseElement);
+  });
+
+  it('renders children into the provided mountNode', () => {
+    const TestComponent = () => {
+      const [el, setEl] = React.useState<HTMLDivElement | null>(null);
+      return (
+        <>
+          <div data-testid="mount" ref={setEl} />
+          {el && (
+            <Portal mountNode={el}>
+              <div data-testid="portal-child">Content</div>
+            </Portal>
+          )}
+        </>
+      );
+    };
+
+    const { getByTestId } = render(<TestComponent />);
+    expect(getByTestId('portal-child').parentElement).toBe(getByTestId('mount'));
+  });
+
+  it('renders a hidden anchor span at the original tree location', () => {
+    const { container } = render(
+      <div data-testid="parent">
+        <Portal>
+          <div>Content</div>
+        </Portal>
+      </div>,
+    );
+
+    const anchor = container.querySelector<HTMLSpanElement>('[data-testid="parent"] > span');
+    expect(anchor).not.toBeNull();
+    expect(anchor).toHaveAttribute('hidden');
+  });
+
+  it('links the portal mountNode to the anchor via setVirtualParent', () => {
+    const TestComponent = () => {
+      const [mountNode, setMountNode] = React.useState<HTMLDivElement | null>(null);
+      return (
+        <div data-testid="react-parent">
+          <Portal mountNode={mountNode}>
+            <div>Content</div>
+          </Portal>
+          <div data-testid="mount" ref={setMountNode} />
+        </div>
+      );
+    };
+
+    const { getByTestId } = render(<TestComponent />);
+    const anchor = getByTestId('react-parent').querySelector<HTMLSpanElement>(':scope > span');
+
+    // Virtual parent of the mountNode is the anchor — walking up from the
+    // mountNode reaches the anchor, then the React parent.
+    expect(getParent(getByTestId('mount'))).toBe(anchor);
+  });
+
+  it('does not link virtual parent when mountNode already contains the anchor', () => {
+    const TestComponent = () => {
+      const [el, setEl] = React.useState<HTMLDivElement | null>(null);
+      return (
+        <div data-testid="virtual-parent-cycle">
+          <div data-testid="mount-container" ref={setEl}>
+            {el && (
+              <Portal mountNode={el}>
+                <div>Content</div>
+              </Portal>
+            )}
+          </div>
+        </div>
+      );
+    };
+
+    const { getByTestId } = render(<TestComponent />);
+    // mountNode contains the anchor span, so linking would create a parent cycle.
+    // We expect no virtual parent to be set; getParent falls back to the real DOM parent.
+    expect(getParent(getByTestId('mount-container'))).toBe(getByTestId('virtual-parent-cycle'));
+  });
+});
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.tsx
new file mode 100644
index 00000000000000..dcf9653c6c78bd
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.tsx
@@ -0,0 +1,23 @@
+'use client';
+
+import type * as React from 'react';
+
+import { usePortal } from './usePortal';
+import { renderPortal } from './renderPortal';
+import type { PortalProps } from './Portal.types';
+
+/**
+ * Portal renders its children into a DOM node that exists outside the DOM
+ * hierarchy of the parent component.
+ *
+ * Defaults to mounting on `targetDocument.body` from the parent Fluent context.
+ * Links the portalled subtree to its React parent via `setVirtualParent` so
+ * DOM-walking utilities (click-outside, focus traps, `elementContains`) keep
+ * working across the portal boundary.
+ */
+export const Portal: React.FC<PortalProps> = props => {
+  const state = usePortal(props);
+  return renderPortal(state);
+};
+
+Portal.displayName = 'Portal';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.types.ts b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.types.ts
new file mode 100644
index 00000000000000..669d45ba1275e7
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/Portal.types.ts
@@ -0,0 +1,37 @@
+import type * as React from 'react';
+
+export type PortalProps = {
+  /**
+   * Content to render into the portal mount node.
+   */
+  children?: React.ReactNode;
+
+  /**
+   * The DOM element to mount portal content into.
+   *
+   * When omitted, defaults to `targetDocument.body` from the parent Fluent context,
+   * which makes the portal escape ancestor stacking constraints (`overflow`,
+   * `clip-path`, `transform`) on the original tree location.
+   */
+  mountNode?: HTMLElement | null;
+};
+
+export type PortalState = Pick<PortalProps, 'children'> & {
+  /**
+   * Resolved mount node — either the user-provided `mountNode` or
+   * `targetDocument.body` from Fluent context. `undefined` on the server
+   * (or before hydration completes) so the render stays SSR-safe.
+   */
+  mountNode: HTMLElement | null | undefined;
+
+  /**
+   * Ref to the anchor `<span hidden>` rendered at the original tree location.
+   *
+   * Used to link the mount node to its React parent via `setVirtualParent`,
+   * so utilities that walk the DOM (click-outside detection, focus traps,
+   * `elementContains`) treat the portalled subtree as logically nested under
+   * its React parent.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  anchorRef: React.MutableRefObject<HTMLSpanElement | null>;
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/index.ts b/packages/react-components/react-headless-components-preview/library/src/components/Portal/index.ts
new file mode 100644
index 00000000000000..4798665c95f0de
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/index.ts
@@ -0,0 +1,4 @@
+export { Portal } from './Portal';
+export type { PortalProps, PortalState } from './Portal.types';
+export { renderPortal } from './renderPortal';
+export { usePortal } from './usePortal';
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/renderPortal.tsx b/packages/react-components/react-headless-components-preview/library/src/components/Portal/renderPortal.tsx
new file mode 100644
index 00000000000000..7e3d9afba0911c
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/renderPortal.tsx
@@ -0,0 +1,24 @@
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import type { JSXElement } from '@fluentui/react-utilities';
+
+import type { PortalState } from './Portal.types';
+
+/**
+ * Render the final JSX of Portal.
+ *
+ * Renders a stable `<span hidden>` anchor at the original tree location and,
+ * when a `mountNode` is available, portals `children` into it.
+ *
+ * SSR safety: on the server `mountNode` is `undefined`, so only the anchor
+ * is rendered. On hydration the anchor still renders identically (the portal
+ * content lives at a different DOM location, which React doesn't compare),
+ * so no hydration mismatch is possible.
+ */
+export const renderPortal = (state: PortalState): JSXElement => {
+  return (
+    <span hidden ref={state.anchorRef}>
+      {state.mountNode && ReactDOM.createPortal(state.children, state.mountNode)}
+    </span>
+  );
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/components/Portal/usePortal.ts b/packages/react-components/react-headless-components-preview/library/src/components/Portal/usePortal.ts
new file mode 100644
index 00000000000000..e49a7d2f27cace
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/components/Portal/usePortal.ts
@@ -0,0 +1,54 @@
+'use client';
+
+import * as React from 'react';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import { setVirtualParent } from '@fluentui/react-utilities';
+
+import type { PortalProps, PortalState } from './Portal.types';
+
+/**
+ * Create the state required to render Portal.
+ *
+ * Resolves the mount node (user-provided `mountNode` falls back to
+ * `targetDocument.body` from Fluent context) and links the anchor span at the
+ * original tree location to the mount node via `setVirtualParent`.
+ *
+ * The virtual parent link is what allows DOM-walking utilities (click-outside,
+ * focus traps, `elementContains`) to treat the portalled subtree as logically
+ * nested under its React parent — without it, the portal is detached from the
+ * tree-position perspective.
+ */
+export const usePortal = (props: PortalProps): PortalState => {
+  const { children, mountNode: mountNodeProp } = props;
+
+  const { targetDocument } = useFluent();
+  const anchorRef = React.useRef<HTMLSpanElement>(null);
+
+  const mountNode = mountNodeProp ?? targetDocument?.body;
+
+  React.useEffect(() => {
+    const anchor = anchorRef.current;
+    if (!mountNode || !anchor) {
+      return;
+    }
+
+    // Skip linking when the anchor already lives inside the mount node — happens
+    // when a consumer passes a custom mountNode that is itself a descendant of
+    // the React parent. Linking would create a parent cycle.
+    if (mountNode.contains(anchor)) {
+      return;
+    }
+
+    setVirtualParent(mountNode, anchor);
+
+    return () => {
+      setVirtualParent(mountNode, undefined);
+    };
+  }, [mountNode]);
+
+  return {
+    children,
+    mountNode,
+    anchorRef,
+  };
+};
diff --git a/packages/react-components/react-headless-components-preview/library/src/portal.ts b/packages/react-components/react-headless-components-preview/library/src/portal.ts
new file mode 100644
index 00000000000000..d79fe8e941c7a1
--- /dev/null
+++ b/packages/react-components/react-headless-components-preview/library/src/portal.ts
@@ -0,0 +1,2 @@
+export { Portal, renderPortal, usePortal } from './components/Portal/index';
+export type { PortalProps, PortalState } from './components/Portal/index';