feat(ui,headless): mosaic dialog foundations (#8808)

Author: alexcarpenter

.changeset/wise-types-satisfy.md

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

packages/headless/src/primitives/autocomplete/autocomplete-input.tsx

@@ -33,7 +33,7 @@ export const AutocompleteInput = React.forwardRef<HTMLInputElement, Autocomplete
 
     const defaultProps = {
       'data-cl-slot': 'autocomplete-input',
-      ...(getReferenceProps({
+      ...getReferenceProps({
         ref: combinedRef,
         value: inputValue,
         'aria-autocomplete': 'list' as const,
@@ -50,7 +50,7 @@ export const AutocompleteInput = React.forwardRef<HTMLInputElement, Autocomplete
             }
           }
         },
-      }) as React.ComponentPropsWithRef<'input'>),
+      }),
     };
 
     return renderElement({

packages/headless/src/primitives/autocomplete/autocomplete-list.tsx

@@ -3,7 +3,7 @@
 import { FloatingList, useMergeRefs } from '@floating-ui/react';
 import React, { useEffect } from 'react';
 
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useAutocompleteContext } from './autocomplete-context';
 
 export type AutocompleteListProps = ComponentProps<'div'>;
@@ -24,14 +24,15 @@ export const AutocompleteList = React.forwardRef<HTMLDivElement, AutocompleteLis
     // eslint-disable-next-line @typescript-eslint/unbound-method
     const combinedRef = useMergeRefs([refs.setFloating, ref]);
 
-    const floatingProps = getFloatingProps() as React.ComponentPropsWithRef<'div'>;
+    const floatingProps = getFloatingProps();
     const wiredId = floatingProps.id;
 
-    const defaultProps = {
+    const ownProps = {
       'data-cl-slot': 'autocomplete-list',
       ref: combinedRef,
-      ...floatingProps,
-    };
+    } satisfies DefaultProps<'div'>;
+
+    const defaultProps = { ...ownProps, ...floatingProps };
 
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not

packages/headless/src/primitives/autocomplete/autocomplete-option.tsx

@@ -3,7 +3,7 @@
 import { useListItem, useMergeRefs } from '@floating-ui/react';
 import React, { useEffect, useId } from 'react';
 
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useAutocompleteContext } from './autocomplete-context';
 
 export interface AutocompleteOptionProps extends ComponentProps<'div'> {
@@ -43,21 +43,25 @@ export const AutocompleteOption = React.forwardRef<HTMLDivElement, AutocompleteO
       disabled: !!disabled,
     };
 
-    const defaultProps = {
+    const ownProps = {
       'data-cl-slot': 'autocomplete-option',
       id,
       ref: combinedRef,
-      role: 'option' as const,
+      role: 'option',
       'aria-selected': isActive,
       'aria-disabled': disabled || undefined,
-      ...(getItemProps({
+    } satisfies DefaultProps<'div'>;
+
+    const defaultProps = {
+      ...ownProps,
+      ...getItemProps({
         onClick() {
           if (!disabled) {
             handleSelect(value, index, displayLabel);
             (refs.domReference.current as HTMLElement | null)?.focus();
           }
         },
-      }) as React.ComponentPropsWithRef<'div'>),
+      }),
     };
 
     const merged = mergeProps<'div'>(defaultProps, otherProps);

packages/headless/src/primitives/autocomplete/autocomplete-positioner.tsx

@@ -3,7 +3,7 @@
 import { FloatingFocusManager, FloatingList, useMergeRefs } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useAutocompleteContext } from './autocomplete-context';
 
 export type AutocompletePositionerProps = ComponentProps<'div'>;
@@ -22,16 +22,17 @@ export const AutocompletePositioner = React.forwardRef<HTMLDivElement, Autocompl
     // eslint-disable-next-line @typescript-eslint/unbound-method
     const combinedRef = useMergeRefs([refs.setFloating, ref]);
 
-    const floatingProps = getFloatingProps() as React.ComponentPropsWithRef<'div'>;
+    const floatingProps = getFloatingProps();
     const wiredId = floatingProps.id;
 
-    const defaultProps = {
+    const ownProps = {
       'data-cl-slot': 'autocomplete-positioner',
       'data-cl-side': side,
       ref: combinedRef,
       style: floatingStyles,
-      ...floatingProps,
-    };
+    } satisfies DefaultProps<'div'>;
+
+    const defaultProps = { ...ownProps, ...floatingProps };
 
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not

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

@@ -15,13 +15,14 @@ import { Dialog } from '@/primitives/dialog';
 
 <Dialog.Root>
   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
-  <Dialog.Backdrop>
+  <Dialog.Backdrop />
+  <Dialog.Viewport>
     <Dialog.Popup>
       <Dialog.Title>Confirm Action</Dialog.Title>
       <Dialog.Description>Are you sure you want to proceed?</Dialog.Description>
       <Dialog.Close>Cancel</Dialog.Close>
     </Dialog.Popup>
-  </Dialog.Backdrop>
+  </Dialog.Viewport>
 </Dialog.Root>;
 ```
 
@@ -51,7 +52,8 @@ const [open, setOpen] = useState(false);
 | `Dialog.Root`        | —               | Root context provider                           |
 | `Dialog.Trigger`     | `<button>`      | Opens/closes the dialog on click                |
 | `Dialog.Portal`      | —               | Portals children (defaults to `document.body`)  |
-| `Dialog.Backdrop`    | `<div>`         | Overlay + focus manager host                    |
+| `Dialog.Backdrop`    | `<div>`         | Semi-transparent overlay surface                |
+| `Dialog.Viewport`    | `<div>`         | Fixed centering container; owns scroll lock     |
 | `Dialog.Popup`       | `<div>`         | The dialog content container                    |
 | `Dialog.Title`       | `<h2>`          | Dialog heading, wired to `aria-labelledby`      |
 | `Dialog.Description` | `<p>`           | Dialog description, wired to `aria-describedby` |
@@ -74,15 +76,15 @@ const [open, setOpen] = useState(false);
 | ------ | ------------------------------------------------------------- | --------------- | -------------------------------- |
 | `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | `document.body` | Container element to portal into |
 
-When `root` is provided, the dialog is "scoped" to that container: `Dialog.Backdrop` skips `FloatingOverlay` (no fixed positioning or scroll lock), and consumers handle positioning via CSS on the container.
+When `root` is provided, the dialog is portaled into that container instead of `document.body`. Consumers handle layout via CSS on the container (or by omitting `Dialog.Viewport` and styling their own).
 
-### `Dialog.Backdrop`
+### `Dialog.Viewport`
 
-| Prop         | Type      | Default | Description                                           |
-| ------------ | --------- | ------- | ----------------------------------------------------- |
-| `lockScroll` | `boolean` | `true`  | Prevents body scroll while open (skipped when scoped) |
+| Prop         | Type      | Default | Description                     |
+| ------------ | --------- | ------- | ------------------------------- |
+| `lockScroll` | `boolean` | `true`  | Prevents body scroll while open |
 
-### `Dialog.Trigger`, `Dialog.Popup`, `Dialog.Title`, `Dialog.Description`, `Dialog.Close`
+### `Dialog.Backdrop`, `Dialog.Trigger`, `Dialog.Popup`, `Dialog.Title`, `Dialog.Description`, `Dialog.Close`
 
 No additional props beyond standard HTML attributes and the `render` prop.
 
@@ -95,18 +97,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute                         | Applies To        | Description                             |
-| --------------------------------- | ----------------- | --------------------------------------- |
-| `data-cl-slot`                    | All parts         | Part identifier (e.g. `"dialog-popup"`) |
-| `data-cl-open` / `data-cl-closed` | Trigger, Backdrop | Open state                              |
+| Attribute                         | Applies To                         | Description                             |
+| --------------------------------- | ---------------------------------- | --------------------------------------- |
+| `data-cl-slot`                    | All parts                          | Part identifier (e.g. `"dialog-popup"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger, Backdrop, Viewport, Popup | Open state                              |
 
 ## Important Notes
 
-- **`Dialog.Popup` must be a child of `Dialog.Backdrop`.** The backdrop hosts the portal, overlay, and focus manager — the popup alone does not handle these.
+- **`Dialog.Popup` should be a child of `Dialog.Viewport`** for centered, scroll-locked modal behavior. The viewport hosts the fixed overlay container; the popup alone does not handle positioning or scroll lock.
 - **Title and Description are optional but recommended.** If omitted, `aria-labelledby` / `aria-describedby` are simply absent from the popup.
 - **Nested dialogs are supported.** The `FloatingTree` pattern handles nesting automatically.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
+## Authoring rule for new primitives
+
+Each styleable surface = one part. Layout infrastructure (overlay, scroll lock, focus manager, portal) wraps a `renderElement` call rather than fusing with it. The dialog split — `Backdrop` (semi-transparent surface) vs. `Viewport` (fixed centering + scroll lock) — exists because mosaic needs to style each layer independently. Apply the same decomposition to future primitives that combine positioning with a styled surface.
+
 ## ARIA
 
 - Popup: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)

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

@@ -1,46 +1,39 @@
 'use client';
 
-import { FloatingOverlay } from '@floating-ui/react';
-import { useContext } from 'react';
-
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
-import { DialogScopedContext, useDialogContext } from './dialog-context';
-
-export interface DialogBackdropProps extends ComponentProps<'div'> {
-  /** When true, locks body scroll while the dialog is open. Default: true */
-  lockScroll?: boolean;
-}
-
-export function DialogBackdrop(props: DialogBackdropProps) {
-  const { render, lockScroll = true, ...otherProps } = props;
-  const { open, mounted, transitionProps } = useDialogContext();
-  const scoped = useContext(DialogScopedContext);
-
-  const state = { open };
-
-  const defaultProps = {
-    'data-cl-slot': 'dialog-backdrop',
-    ...transitionProps,
-  } as React.ComponentPropsWithRef<'div'>;
-
-  const backdropElement = renderElement({
-    defaultTagName: 'div',
-    render,
-    enabled: mounted,
-    state,
-    stateAttributesMapping: {
-      open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
-    },
-    props: mergeProps<'div'>(defaultProps, otherProps),
-  });
-
-  if (scoped) {
-    return backdropElement;
-  }
-
-  if (!mounted) {
-    return null;
-  }
-
-  return <FloatingOverlay lockScroll={lockScroll}>{backdropElement}</FloatingOverlay>;
-}
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils';
+import { useDialogContext } from './dialog-context';
+
+/** Props for {@link DialogBackdrop}. */
+export type DialogBackdropProps = ComponentProps<'div'>;
+
+/** Semi-transparent overlay surface rendered behind the dialog. Does not own scroll-lock or positioning — use `Dialog.Viewport` for those. */
+export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
+  function DialogBackdrop(props, ref) {
+    const { render, ...otherProps } = props;
+    const { open, mounted, transitionProps } = useDialogContext();
+
+    if (!mounted) {
+      return null;
+    }
+
+    const state = { open };
+
+    const defaultProps = {
+      'data-cl-slot': 'dialog-backdrop',
+      ref,
+      ...transitionProps,
+    } satisfies DefaultProps<'div'>;
+
+    return renderElement({
+      defaultTagName: 'div',
+      render,
+      state,
+      stateAttributesMapping: {
+        open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+      },
+      props: mergeProps<'div'>(defaultProps, otherProps),
+    });
+  },
+);

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

@@ -1,25 +1,30 @@
 'use client';
 
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils';
 import { useDialogContext } from './dialog-context';
 
+/** Props for {@link DialogClose}. */
 export type DialogCloseProps = ComponentProps<'button'>;
 
-export function DialogClose(props: DialogCloseProps) {
+/** Button that closes the dialog when clicked. Calls `setOpen(false)` from dialog context. */
+export const DialogClose = React.forwardRef<HTMLButtonElement, DialogCloseProps>(function DialogClose(props, ref) {
   const { render, ...otherProps } = props;
   const { setOpen } = useDialogContext();
 
   const defaultProps = {
     type: 'button' as const,
     'data-cl-slot': 'dialog-close',
+    ref,
     onClick() {
       setOpen(false);
     },
-  };
+  } satisfies DefaultProps<'button'>;
 
   return renderElement({
     defaultTagName: 'button',
     render,
     props: mergeProps<'button'>(defaultProps, otherProps),
   });
-}
+});

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

@@ -19,7 +19,6 @@ export interface DialogContextValue {
 }
 
 export const DialogContext = createContext<DialogContextValue | null>(null);
-export const DialogScopedContext = createContext(false);
 
 export function useDialogContext() {
   const ctx = useContext(DialogContext);

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

@@ -1,22 +1,29 @@
 'use client';
 
-import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils';
 import { useDialogContext } from './dialog-context';
 
+/** Props for {@link DialogDescription}. */
 export type DialogDescriptionProps = Omit<ComponentProps<'p'>, 'id'>;
 
-export function DialogDescription(props: DialogDescriptionProps) {
-  const { render, ...otherProps } = props;
-  const { descriptionId } = useDialogContext();
+/** Accessible dialog description. Wires its `id` to `aria-describedby` on `Dialog.Popup`. */
+export const DialogDescription = React.forwardRef<HTMLParagraphElement, DialogDescriptionProps>(
+  function DialogDescription(props, ref) {
+    const { render, ...otherProps } = props;
+    const { descriptionId } = useDialogContext();
 
-  const defaultProps = {
-    'data-cl-slot': 'dialog-description',
-    id: descriptionId,
-  };
+    const defaultProps = {
+      'data-cl-slot': 'dialog-description',
+      id: descriptionId,
+      ref,
+    } satisfies DefaultProps<'p'>;
 
-  return renderElement({
-    defaultTagName: 'p',
-    render,
-    props: mergeProps<'p'>(defaultProps, otherProps),
-  });
-}
+    return renderElement({
+      defaultTagName: 'p',
+      render,
+      props: mergeProps<'p'>(defaultProps, otherProps),
+    });
+  },
+);