feat(ui): rebuild the Mosaic Dialog on StyleX

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }

.changeset/olive-doors-tell.md

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

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

@@ -120,17 +120,22 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute | Applies To | Description |
-| --------------------------- | ---------------------------------- | ----------- |
-| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| Attribute | Applies To | Description |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state |
+| `data-nested` | Backdrop, Viewport, Popup | Opened from inside another floating element |
+
+`data-nested` is what a stacked overlay styles itself from — chiefly so backdrops don't composite
+into an ever-darker scrim as the stack grows. It reflects any floating ancestor, not strictly a
+dialog one: the `FloatingTree` a Menu or Popover establishes counts too.
 
 The headless parts are unstyled. Target a part with your own className (or `render` prop) and combine it with the `data-*` state attributes above.
 
 ## Important Notes
 
 - **`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.
+- **Nested dialogs are supported**, and covered by tests. The `FloatingTree` pattern handles it: `useDismiss` blocks both Escape and outside-press on a parent while any child is open, and `FloatingOverlay`'s scroll lock is refcounted, so the body stays locked until the last dialog closes.
 - **No positioning middleware.** Dialogs are centered via CSS, not Floating UI positioning.
 
 ## Authoring rule for new primitives

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

@@ -12,9 +12,9 @@ export type DialogBackdropProps = ComponentProps<'div'>;
 export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(
  function DialogBackdrop(props, ref) {
  const { render, ...otherProps } = props;
- const { open, mounted, transitionProps } = useDialogContext();
+ const { open, mounted, isNested, transitionProps } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -28,6 +28,7 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -14,6 +14,16 @@ export interface DialogContextValue {
  /** Where focus goes when the dialog closes, or `null` to leave focus alone. */
  returnFocusRef: React.MutableRefObject<HTMLElement | null>;
  modal: boolean;
+ /**
+ * 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
+ * an ever-darker scrim as the stack grows.
+ *
+ * True for any floating ancestor, not strictly a dialog one: the `FloatingTree` a Menu or
+ * Popover establishes counts too. That is the honest reading of what is knowable here, and the
+ * cases coincide in practice.
+ */
+ isNested: boolean;
  labelId: string;
  descriptionId: string;
  mounted: boolean;

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

@@ -18,6 +18,7 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  getFloatingProps,
  floatingContext,
  modal,
+ isNested,
  returnFocusRef,
  labelId,
  descriptionId,
@@ -30,7 +31,12 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
  'aria-describedby': descriptionId,
  } satisfies DefaultProps<'div'>;
 
- const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
+ const defaultProps = {
+ ...ownProps,
+ ...(isNested ? { 'data-nested': '' } : {}),
+ ...getFloatingProps(),
+ ...transitionProps,
+ };
 
  const element = useRender({
  defaultTagName: 'div',

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

@@ -42,9 +42,9 @@ export interface DialogProps {
  children: ReactNode;
 }
 
-function DialogInner(props: DialogProps) {
+function DialogInner(props: DialogProps & { isNested: boolean }) {
  const nodeId = useFloatingNodeId();
- const { modal = true, closedBy = 'any', children } = props;
+ const { modal = true, closedBy = 'any', isNested, children } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -87,6 +87,7 @@ function DialogInner(props: DialogProps) {
  popupRef,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -101,6 +102,7 @@ function DialogInner(props: DialogProps) {
  getFloatingProps,
  returnFocusRef,
  modal,
+ isNested,
  labelId,
  descriptionId,
  mounted,
@@ -121,10 +123,18 @@ export function DialogRoot(props: DialogProps) {
  if (parentId === null) {
  return (
  <FloatingTree>
- <DialogInner {...props} />
+ <DialogInner
+ {...props}
+ isNested={false}
+ />
  </FloatingTree>
  );
  }
 
- return <DialogInner {...props} />;
+ return (
+ <DialogInner
+ {...props}
+ isNested
+ />
+ );
 }

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

@@ -23,9 +23,9 @@ export interface DialogViewportProps extends ComponentProps<'div'> {
 export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(
  function DialogViewport(props, ref) {
  const { render, lockScroll = true, ...otherProps } = props;
- const { open, mounted, transitionProps, modal } = useDialogContext();
+ const { open, mounted, isNested, transitionProps, modal } = useDialogContext();
 
- const state = { open };
+ const state = { open, nested: isNested };
 
  const defaultProps = {
  ...transitionProps,
@@ -40,6 +40,7 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
  state,
  stateAttributesMapping: {
  open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+ nested: (v: boolean): Record<string, string> | null => (v ? { 'data-nested': '' } : null),
  },
  props: mergeProps<'div'>(defaultProps, otherProps),
  });

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

@@ -44,8 +44,6 @@ export interface DrawerContextValue extends DialogContextValue {
  snapRestOffset: number | null;
  /** Callbacks a nested child `Drawer.Root` invokes on this (parent) drawer. */
  onNested: NestedDrawerCallbacks;
- /** True when this drawer is itself nested inside another drawer. */
- isNested: boolean;
  /** How many direct nested child drawers are currently open. */
  nestedOpenCount: number;
 }