feat(ui): dialog close confirmation

A dialog holding unsaved work should ask before discarding it. Three pieces,
each with one job: `createConfirmHandle()` links a question to its answer,
`useConfirmedClose` guards the close path, and `<AlertDialog.Confirm>` is the
dialog, rendered inside the one it guards so the two share a floating tree —
escape ordering, the stacking styles and the refcounted scroll lock all read
that tree, and a globally mounted confirmation would break every one of them.

`show()` returns a promise resolving to the answer, so a confirmation reads as
`if (await confirm.show({…}))` rather than as a pair of state variables and a
callback. Calling it while one is already showing returns the IN-FLIGHT promise
instead of opening a second: holding Escape against a guarded dialog would
otherwise stack a confirmation per keypress.

The veto is the absence of a commit. `useConfirmedClose` wraps the consumer's
own `onOpenChange`, so it covers every close the dialog owns — Escape, outside
press, `Dialog.CloseButton`, `Dialog.Close`, and the `close` the wrapper hands
its children all funnel through it. A button wired to the consumer's own
`setOpen(false)` never reaches the dialog and so bypasses the question; that is
inherent, and both the hook's JSDoc and the docs page say so.

Two ordering details that are load-bearing. The action settles `true` before
closing, and `settle` is a no-op once a question is answered, so the close that
follows cannot overwrite the answer with `false`. And the hook reads `when` and
`onOpenChange` through a ref, so the callback identity is stable across the
keystrokes of the very form whose dirtiness `when` reports on.

Headless gains `handle.open(payload)` — the programmatic counterpart of a
trigger's payload, which is how the confirmation's own text reaches it. The
root holds it in a ref as well as in state: the registry lookup that runs once
the dialog is open resolves a trigger-less open to `undefined`, and would
otherwise blank the dialog a commit after it was filled.

Author: maxyinger

.changeset/dialog-close-confirmation.md

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

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

@@ -78,6 +78,17 @@ const detail = Dialog.createHandle<{ name: string }>();
 </Dialog.Root>
 ```
 
+An open with no trigger behind it can supply the payload directly: `handle.open(payload)` is the
+programmatic counterpart, for a dialog raised by something that happened rather than by an element
+— a confirmation that has to say what it is asking. A trigger-driven open supersedes it, since a
+trigger names its own payload.
+
+```tsx
+const confirmation = Dialog.createHandle<{ question: string }>();
+
+confirmation.open({ question: 'Discard changes?' });
+```
+
 In controlled mode, track which trigger is active with `triggerId` — `onOpenChange`'s second
 argument reports the trigger behind each change:
 

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

@@ -20,10 +20,10 @@ export interface DialogTriggerRegistration<Payload = unknown> {
  * requests made with no root attached are ignored, matching Base UI.
  * @internal
  */
-export interface DialogRootController {
+export interface DialogRootController<Payload = unknown> {
   openFromTrigger: (id: string, event: Event) => void;
   closeFromTrigger: (id: string, event: Event) => void;
-  setOpen: (open: boolean) => void;
+  setOpen: (open: boolean, payload?: Payload) => void;
 }
 
 /** The slice of root state a trigger renders from: its `data-open` / ARIA wiring. */
@@ -45,8 +45,16 @@ const CLOSED_STATE: DialogHandleState = { open: false, triggerId: null, popupId:
  * lets a `DialogHandle<Payload>` flow into contexts typed `DialogHandle<unknown>`.
  */
 export interface DialogHandle<Payload = unknown> {
-  /** Opens the attached root. Ignored while no root is mounted. */
-  open(): void;
+  /**
+   * Opens the attached root. Ignored while no root is mounted.
+   *
+   * The optional `payload` is the programmatic counterpart of a trigger's: it reaches the root's
+   * children-as-function as `{ payload }`, so an imperative open can carry the content the dialog
+   * is about — what a confirmation is asking, which record is being deleted — without the caller
+   * holding a second piece of state alongside `open`. A trigger-driven open supersedes it, since
+   * a trigger names its own payload.
+   */
+  open(payload?: Payload): void;
   /** Closes the attached root. Ignored while no root is mounted. */
   close(): void;
   /** Whether the attached root is open. `false` while no root is mounted. */
@@ -58,7 +66,7 @@ export interface DialogHandle<Payload = unknown> {
   /** @internal */
   getFirstTrigger(): DialogTriggerRegistration<Payload> | undefined;
   /** @internal */
-  setRoot(controller: DialogRootController): () => void;
+  setRoot(controller: DialogRootController<Payload>): () => void;
   /** @internal */
   requestOpen(id: string, event: Event): void;
   /** @internal */
@@ -79,14 +87,14 @@ export interface DialogHandle<Payload = unknown> {
 export function createDialogHandle<Payload = unknown>(): DialogHandle<Payload> {
   const triggers = new Map<string, DialogTriggerRegistration<Payload>>();
   const listeners = new Set<() => void>();
-  let root: DialogRootController | null = null;
+  let root: DialogRootController<Payload> | null = null;
   let state = CLOSED_STATE;
 
   const notify = () => listeners.forEach(listener => listener());
 
   return {
-    open() {
-      root?.setOpen(true);
+    open(payload) {
+      root?.setOpen(true, payload);
     },
     close() {
       root?.setOpen(false);

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

@@ -100,6 +100,10 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
   // consumed by the floating `onOpenChange` the request funnels into.
   const pendingDetailsRef = useRef<DialogOpenChangeDetails | null>(null);
 
+  // The payload of the most recent programmatic `handle.open(payload)`, kept so the registry
+  // lookup below has something to fall back to when no trigger is involved.
+  const directPayloadRef = useRef<Payload | undefined>(undefined);
+
   // Every open/close funnels through `floatingContext.onOpenChange` — trigger activations,
   // dismissals, and programmatic `setOpen` alike. floating-ui emits its `openchange` event
   // synchronously before invoking this callback, which is what lets listeners (`useReturnFocus`,
@@ -121,6 +125,9 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
       openFromTrigger: (id, event) => {
         const registration = store.getTrigger(id);
         setActiveTriggerId(id);
+        // A trigger names its own payload, so it supersedes anything a previous programmatic
+        // open supplied — otherwise the stale one would resurface through the effect below.
+        directPayloadRef.current = undefined;
         setActivePayload(registration?.getPayload());
         if (registration) {
           refs.setReference(registration.element);
@@ -133,7 +140,14 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
         pendingDetailsRef.current = { trigger: registration?.element ?? null, triggerId: id, event };
         floatingContext.onOpenChange(false, event, 'click');
       },
-      setOpen: nextOpen => floatingContext.onOpenChange(nextOpen),
+      setOpen: (nextOpen, payload) => {
+        // Held in a ref as well as in state because the payload effect below re-runs on `open`
+        // and would otherwise resolve a trigger-less open to `undefined`, wiping this a commit
+        // after it was set.
+        directPayloadRef.current = payload;
+        setActivePayload(payload);
+        floatingContext.onOpenChange(nextOpen);
+      },
     });
     // `floatingContext` is rebuilt on open/element changes; re-registering is an idempotent swap.
   }, [store, refs, floatingContext, setActiveTriggerId]);
@@ -159,7 +173,9 @@ function DialogInner<Payload>(props: DialogProps<Payload> & { isNested: boolean
   // the time it reads, and the pre-paint re-render delivers their payload on the first frame.
   useLayoutEffect(() => {
     if (open) {
-      setActivePayload(activeTriggerId != null ? store.getTrigger(activeTriggerId)?.getPayload() : undefined);
+      setActivePayload(
+        activeTriggerId != null ? store.getTrigger(activeTriggerId)?.getPayload() : directPayloadRef.current,
+      );
     }
   }, [store, open, activeTriggerId]);
 

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

@@ -528,6 +528,63 @@ describe('Dialog', () => {
 
       expect(screen.getByRole('dialog', { name: 'payload-b' })).toBeInTheDocument();
     });
+
+    // The programmatic counterpart of a trigger's payload, for an open that no element initiated —
+    // a confirmation raised by a close request, say, which has to say what it is asking.
+    describe('handle.open(payload)', () => {
+      function renderDetached() {
+        const handle = Dialog.createHandle<string>();
+        render(
+          <Dialog.Root handle={handle}>
+            {({ payload }) => (
+              <>
+                <Dialog.Trigger id='trigger-a'>Open A</Dialog.Trigger>
+                <Dialog.Portal>
+                  <Dialog.Viewport>
+                    <Dialog.Popup>
+                      <Dialog.Title>{payload ?? 'no payload'}</Dialog.Title>
+                    </Dialog.Popup>
+                  </Dialog.Viewport>
+                </Dialog.Portal>
+              </>
+            )}
+          </Dialog.Root>,
+        );
+        return handle;
+      }
+
+      it('delivers it to the children render function', () => {
+        const handle = renderDetached();
+
+        act(() => handle.open('from-handle'));
+
+        expect(screen.getByRole('dialog', { name: 'from-handle' })).toBeInTheDocument();
+      });
+
+      it('survives the registry lookup that runs once the dialog is open', async () => {
+        const handle = renderDetached();
+
+        act(() => handle.open('from-handle'));
+        // The lookup effect re-runs on `open`; without a fallback it would resolve to `undefined`
+        // a commit later and blank the dialog.
+        await act(async () => {
+          await Promise.resolve();
+        });
+
+        expect(screen.getByRole('dialog', { name: 'from-handle' })).toBeInTheDocument();
+      });
+
+      it('is superseded by a trigger, which names its own payload', async () => {
+        const user = userEvent.setup();
+        const handle = renderDetached();
+
+        act(() => handle.open('from-handle'));
+        act(() => handle.close());
+        await user.click(screen.getByRole('button', { name: 'Open A' }));
+
+        expect(screen.getByRole('dialog', { name: 'no payload' })).toBeInTheDocument();
+      });
+    });
   });
 
   describe('initialFocus', () => {

packages/swingset/src/stories/alert-dialog.component.mdx

@@ -79,6 +79,65 @@ the same reason: a corner X is a way out without answering.
 Every close request — Escape or `AlertDialog.Close` — routes through `onOpenChange`, so a controlled
 consumer can decline one by not committing the state.
 
+## Confirming a close
+
+A dialog holding unsaved work should ask before discarding it. That is three pieces: a handle, a
+hook that guards the close, and the confirmation itself.
+
+```tsx
+import { AlertDialog, createConfirmHandle, useConfirmedClose } from '@clerk/ui/mosaic/components/alert-dialog';
+
+const confirm = React.useMemo(() => createConfirmHandle(), []);
+
+const onOpenChange = useConfirmedClose({
+  handle: confirm,
+  when: () => value !== '',
+  onOpenChange: setOpen,
+  confirm: {
+    title: 'Discard changes?',
+    description: 'You have not finished adding this address.',
+    actionLabel: 'Discard',
+    cancelLabel: 'Keep editing',
+    destructive: true,
+  },
+});
+
+<Dialog open={open} onOpenChange={onOpenChange} closedBy='closerequest'>
+  {/* … */}
+  <AlertDialog.Confirm handle={confirm} finalFocus={inputRef} />
+</Dialog>
+```
+
+**Render `AlertDialog.Confirm` inside the dialog it guards** — anywhere in its children. That is
+what puts the two in one floating tree, and escape ordering, the stacking styles and the refcounted
+scroll lock all read that tree. A confirmation mounted app-globally would be a sibling of the dialog
+rather than a child of it, and all three would break.
+
+**The guarded dialog must be controlled.** A veto is the absence of a commit, and an uncontrolled
+dialog has already committed by the time `onOpenChange` runs.
+
+**What it covers is every close the dialog owns**: Escape, an outside press where `closedBy` allows
+one, `Dialog.CloseButton`, `Dialog.Close`, and the `close` the `Dialog` wrapper hands its children.
+A button wired to your own `setOpen(false)` never reaches the dialog, so it bypasses the question
+silently — route those through `Dialog.Close`.
+
+`when()` is evaluated at each close request, so a close that no longer needs guarding (the form has
+just been submitted, the field cleared) passes straight through.
+
+### Asking without a close
+
+`show()` is the same confirmation, awaited directly — for a decision that is not about closing:
+
+```tsx
+if (await confirm.show({ title: 'Delete this key?', description: 'Applications using it stop working.' })) {
+  await deleteKey();
+}
+```
+
+It resolves `true` for the action and `false` for cancel or any dismissal. Calling it while a
+confirmation is already showing returns the in-flight promise rather than opening a second one, so
+repeated close requests ask once.
+
 ## Parts
 
 | Part                      | Slot                   | Description                                                                                  |
@@ -93,6 +152,7 @@ consumer can decline one by not committing the state.
 | `AlertDialog.Description` | —                      | Description; wired to the popup's `aria-describedby`. Required.                              |
 | `AlertDialog.Close`       | —                      | Dismisses the alert; unstyled, accepts a `render` prop.                                      |
 | `AlertDialog.Actions`     | `alert-dialog-actions` | The response row. Cancel first.                                                              |
+| `AlertDialog.Confirm`     | `dialog-popup`         | A whole confirmation rendered from a `show()` call. See below.                               |
 
 Every part except `Popup` and `Actions` is `Dialog`'s own component, not a wrapper around it — one
 implementation, so the two cannot drift. `Title` and `Description` are unstyled passthroughs from the