feat(ui): collapse AlertDialog into Dialog and simplify its API

.changeset/mosaic-dialog-role-inline.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/dialog/README.md

@@ -192,9 +192,14 @@ When `root` is provided, the dialog is portaled into that container instead of `
 
 ### `Dialog.Viewport`
 
-| Prop         | Type      | Default | Description                     |
-| ------------ | --------- | ------- | ------------------------------- |
-| `lockScroll` | `boolean` | `true`  | Prevents body scroll while open |
+| Prop         | Type      | Default | Description                                                                  |
+| ------------ | --------- | ------- | ---------------------------------------------------------------------------- |
+| `lockScroll` | `boolean` | `true`  | Prevents body scroll while open                                              |
+| `overlay`    | `boolean` | `true`  | Wraps the viewport in a fixed overlay. `false` renders it in flow, unlocked. |
+
+`overlay={false}` is for a dialog presented inline in its host rather than over the page — an
+account panel mounted in a page slot. Pair it with `modal={false}` and `closedBy='none'` on the
+root, and `initialFocus={false}` on the popup so mounting does not steal focus.
 
 ### `Dialog.Trigger`
 
@@ -213,6 +218,10 @@ When `root` is provided, the dialog is portaled into that container instead of `
 
 `DialogFocusTarget` is `boolean | RefObject | (interactionType) => boolean | void | HTMLElement | null`.
 
+The popup's children are held at their last committed frame while it exits (`Freeze`), so state
+that resets on close — a machine returning to its initial state — does not flash through the
+fade. The popup element itself stays live for `data-closed` / `data-ending-style`.
+
 ### `Dialog.Backdrop`, `Dialog.Title`, `Dialog.Description`, `Dialog.Close`
 
 No additional props beyond standard HTML attributes and the `render` prop.

packages/headless/src/primitives/dialog/dialog-context.ts

@@ -3,6 +3,7 @@ import { createContext, useContext } from 'react';
 
 import type { TransitionProps } from '../../hooks/use-transition';
 import type { DialogHandle } from './dialog-handle';
+import type { DialogRole } from './dialog-root';
 
 export interface DialogContextValue {
   open: boolean;
@@ -21,6 +22,8 @@ export interface DialogContextValue {
    */
   store: DialogHandle;
   modal: boolean;
+  /** The popup's ARIA role, as the root was told. Lets a styled layer branch on alert-dialog behaviour. */
+  role: DialogRole;
   /**
    * Whether this dialog opened from inside another floating element, so a stacked overlay can
    * style itself differently from the one beneath it — chiefly so backdrops don't composite into

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -3,7 +3,7 @@
 import { type FloatingContext, FloatingFocusManager } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, type DefaultProps, Freeze, mergeProps, useRender } from '../../utils';
 import { type InteractionType, interactionTypeFromEvent } from '../../utils/interaction-modality';
 import { useDialogContext } from './dialog-context';
 
@@ -128,7 +128,7 @@ export interface DialogPopupProps extends ComponentProps<'div'> {
 
 /** The dialog content container. Manages focus trapping via `FloatingFocusManager` and wires ARIA attributes from `Dialog.Title` and `Dialog.Description`. */
 export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
-  const { render, initialFocus, finalFocus, ...otherProps } = props;
+  const { render, initialFocus, finalFocus, children, ...otherProps } = props;
   const {
     open,
     popupRef,
@@ -164,6 +164,11 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
     ...(stackedChildCount > 0 ? { 'data-stack-base': '' } : {}),
     ...getFloatingProps(),
     ...transitionProps,
+    // The popup outlives `open` by the length of its exit animation, and whatever closed it has
+    // usually reset the state behind it — a machine returning to `idle`, a form clearing. The
+    // contents hold their last frame on the way out instead of snapping back under the fade. The
+    // popup element itself stays live, so `data-closed` / `data-ending-style` still land.
+    children: <Freeze frozen={!open}>{children}</Freeze>,
   };
 
   const element = useRender({

packages/headless/src/primitives/dialog/dialog-root.tsx

@@ -238,6 +238,7 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
       returnFocusRef,
       store,
       modal,
+      role: ariaRole,
       isNested,
       isStacked: nesting.isStacked,
       stackedChildCount: nesting.stackedChildCount,
@@ -255,6 +256,7 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
       returnFocusRef,
       store,
       modal,
+      ariaRole,
       isNested,
       nesting.isStacked,
       nesting.stackedChildCount,

packages/headless/src/primitives/dialog/dialog-viewport.tsx

@@ -10,6 +10,11 @@ import { useDialogContext } from './dialog-context';
 export interface DialogViewportProps extends ComponentProps<'div'> {
   /** When true, locks body scroll while the dialog is open. Default: true */
   lockScroll?: boolean;
+  /**
+   * When false, renders the viewport in flow — no fixed overlay, no scroll lock — for a dialog
+   * presented inline in its host rather than over the page. Default: true
+   */
+  overlay?: boolean;
 }
 
 /**
@@ -22,14 +27,14 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
  */
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
   function DialogViewport(props, ref) {
-    const { render, lockScroll = true, ...otherProps } = props;
+    const { render, lockScroll = true, overlay = true, ...otherProps } = props;
     const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
     const state = { open, nested: isNested };
 
     const defaultProps = {
       ...transitionProps,
-      style: modal ? undefined : { pointerEvents: 'auto' as const },
+      style: overlay && !modal ? { pointerEvents: 'auto' as const } : undefined,
     } satisfies DefaultProps<'div'>;
 
     const element = useRender({
@@ -49,6 +54,10 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
       return null;
     }
 
+    if (!overlay) {
+      return element;
+    }
+
     return (
       <FloatingOverlay
         lockScroll={lockScroll}

packages/headless/src/primitives/dialog/dialog.test.tsx

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { axe } from '../../test-utils/axe';
 import { Popover } from '../popover';
+import { useDialogContext } from './dialog-context';
 import { Dialog } from './index';
 
 afterEach(() => cleanup());
@@ -782,6 +783,95 @@ describe('Dialog', () => {
       expect(screen.getByRole('alertdialog')).toBeInTheDocument();
       expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
     });
+
+    // A styled layer branches on the role — pinning a size, demanding a description — and the
+    // parts are where it branches, so the role has to reach them through the context.
+    it('publishes the role on the context', () => {
+      const seen: string[] = [];
+      function Probe() {
+        seen.push(useDialogContext().role);
+        return null;
+      }
+      render(
+        <Dialog.Root
+          defaultOpen
+          role='alertdialog'
+        >
+          <Probe />
+        </Dialog.Root>,
+      );
+
+      expect(seen).toContain('alertdialog');
+    });
+  });
+
+  describe('viewport overlay', () => {
+    it('renders in flow without a fixed overlay or a scroll lock when overlay is false', () => {
+      render(
+        <Dialog.Root
+          open
+          modal={false}
+        >
+          <Dialog.Viewport
+            data-testid='dialog-viewport'
+            overlay={false}
+          >
+            <Dialog.Popup initialFocus={false}>Body</Dialog.Popup>
+          </Dialog.Viewport>
+        </Dialog.Root>,
+      );
+
+      const viewport = screen.getByTestId('dialog-viewport');
+      expect(viewport.parentElement).toBe(document.body.firstElementChild);
+      expect(viewport.parentElement?.style.position).not.toBe('fixed');
+      expect(document.body.style.overflow).toBe('');
+    });
+  });
+
+  describe('exit', () => {
+    // A machine driving the dialog resets to its initial state on close, in the same commit that
+    // starts the exit. Without holding the frame, the dialog would repaint that reset state and
+    // fade out showing the wrong thing.
+    it('holds the contents at their last frame while the popup exits', () => {
+      const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+      (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+        { finished: new Promise<void>(() => {}) },
+      ];
+      try {
+        function Fixture({ open, label }: { open: boolean; label: string }) {
+          return (
+            <Dialog.Root open={open}>
+              <Dialog.Viewport>
+                <Dialog.Popup>{label}</Dialog.Popup>
+              </Dialog.Viewport>
+            </Dialog.Root>
+          );
+        }
+        const { rerender } = render(
+          <Fixture
+            open
+            label='Confirming'
+          />,
+        );
+
+        rerender(
+          <Fixture
+            open={false}
+            label='Idle'
+          />,
+        );
+
+        const popup = screen.getByRole('dialog', { hidden: true });
+        expect(popup).toHaveAttribute('data-closed', '');
+        expect(popup).toHaveTextContent('Confirming');
+      } finally {
+        if (original) {
+          (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+        } else {
+          delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+        }
+      }
+    });
   });
 
   describe('stacking', () => {

packages/headless/src/primitives/drawer/drawer-context.ts

@@ -35,7 +35,10 @@ export interface NestedDrawerCallbacks {
 // `nestedOpenCount` / `onNested`, which is a different question from the dialog's: `isStacked`
 // asks whether a DIALOG sits above, and a drawer's stacked-child styling has nothing to read it
 // from. Inheriting them would oblige every drawer root to publish two values no drawer part uses.
-export interface DrawerContextValue extends Omit<DialogContextValue, 'isStacked' | 'stackedChildCount' | 'store'> {
+export interface DrawerContextValue extends Omit<
+  DialogContextValue,
+  'isStacked' | 'stackedChildCount' | 'store' | 'role'
+> {
   getReferenceProps: UseInteractionsReturn['getReferenceProps'];
   backdropRef: React.RefObject<HTMLDivElement | null>;
   drag: DrawerDrag;

packages/swingset/next.config.mjs

@@ -1,9 +1,10 @@
-import stylexPlugin from '@stylexjs/unplugin/webpack';
 import createMDX from '@next/mdx';
-import remarkGfm from 'remark-gfm';
-import rehypeRaw from 'rehype-raw';
+import stylexPlugin from '@stylexjs/unplugin/webpack';
 import { resolve } from 'path';
+import rehypeRaw from 'rehype-raw';
+import remarkGfm from 'remark-gfm';
 import { fileURLToPath } from 'url';
+
 import { mosaicLightningCssTargets } from '../ui/stylex-lightningcss.config.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -82,6 +83,15 @@ const nextConfig = {
       }),
     );
 
+    // Dev-only: StyleX's runtime injector drops named `@container` rules after the first per
+    // query — see the loader for the bug. Scoped to that one module.
+    if (isDev) {
+      config.module.rules.push({
+        test: /[\\/]@stylexjs[\\/]stylex[\\/]lib[\\/](es|cjs)[\\/]inject\.(mjs|js)$/,
+        use: [{ loader: resolve(__dirname, 'src/lib/loaders/stylex-inject-named-container.cjs') }],
+      });
+    }
+
     config.resolve.alias['@clerk/ui/mosaic'] = resolve(__dirname, '../ui/src/mosaic');
     // Consume @clerk/headless primitives from source (no dist build needed), mirroring Mosaic.
     // `/hooks` and `/utils` live outside `primitives/`, so alias them first (more specific wins).

packages/swingset/src/components/DocsViewer.tsx

@@ -55,7 +55,6 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     input: dynamic(() => import('../stories/input.mdx')),
     item: dynamic(() => import('../stories/item.mdx')),
     dialog: dynamic(() => import('../stories/dialog.component.mdx')),
-    'alert-dialog': dynamic(() => import('../stories/alert-dialog.component.mdx')),
     heading: dynamic(() => import('../stories/heading.mdx')),
     icon: dynamic(() => import('../stories/icon.mdx')),
     'icon-frame': dynamic(() => import('../stories/icon-frame.mdx')),

packages/swingset/src/lib/loaders/stylex-inject-named-container.cjs

@@ -0,0 +1,27 @@
+/**
+ * Corrects a regex in StyleX's dev runtime injector so named container queries survive.
+ *
+ * `@stylexjs/stylex@0.19.0`'s `getSeenRuleKey` recognises `@container (…)` but not
+ * `@container name (…)`. A named query falls through to the plain-selector branch, whose key
+ * is the text before the first `{` — the at-rule prelude — so every rule under the same named
+ * query shares one key and all but the first are dropped as duplicates. The injected default
+ * (carrying the `:not(#\#)` bumps) then beats the container rule in the extracted sheet, and
+ * the query silently never applies. Dev only: production uses the extracted CSS.
+ *
+ * Applied at bundle time to the one module rather than as a package patch, so it stays inside
+ * this private dev tool. Delete once upstream's `conditionalRulePattern` accepts a name.
+ */
+const BROKEN = String.raw`/^@(media|supports|container)\s*\([^)]+\)\s*{/`;
+const FIXED = String.raw`/^@(media|supports|container)\b[^{]*{/`;
+
+module.exports = function stylexInjectNamedContainer(source) {
+  if (!source.includes(BROKEN)) {
+    this.emitWarning(
+      new Error(
+        `stylex-inject-named-container: pattern not found in ${this.resourcePath}; StyleX may have fixed it — remove this loader.`,
+      ),
+    );
+    return source;
+  }
+  return source.replace(BROKEN, FIXED);
+};

packages/swingset/src/lib/registry.ts

@@ -1,10 +1,5 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
-import {
-  Default as AlertDialogDefault,
-  DiscardChanges as AlertDialogDiscardChanges,
-  meta as alertDialogComponentMeta,
-} from '../stories/alert-dialog.component.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
   Fallback as AvatarFallbackStory,
@@ -241,12 +236,6 @@ const sectionModule: StoryModule = {
 };
 const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default: DialogDefault };
 
-const alertDialogComponentModule: StoryModule = {
-  meta: alertDialogComponentMeta,
-  Default: AlertDialogDefault,
-  DiscardChanges: AlertDialogDiscardChanges,
-};
-
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault };
 
 const avatarModule: StoryModule = {
@@ -519,7 +508,6 @@ export const registry: StoryModule[] = [
   inputModule,
   itemModule,
   dialogComponentModule,
-  alertDialogComponentModule,
   headingModule,
   iconModule,
   iconFrameModule,