@seed-design/react-dismissible-layer 0.0.0-alpha-20260414104312

package/lib/useDismissibleLayer-12s-D4qWttkW.cjs

@@ -0,0 +1,146 @@
+'use client';
+var react = require('react');
+var layerStack12s = require('./layer-stack-12s-Ctg3ipjW.cjs');
+var useEscapeKeydown12s = require('./use-escape-keydown-12s-CNZqs1dI.cjs');
+var usePointerDownOutside12s = require('./use-pointer-down-outside-12s-nlxC-DrD.cjs');
+var useFocusOutside12s = require('./use-focus-outside-12s-Ch-SoiiA.cjs');
+
+const NOOP = ()=>{};
+// Module-level storage for the original body pointer-events value.
+// Follows Radix's pattern: save once when the first blocking layer mounts,
+// restore when the last blocking layer unmounts. This decouples save/restore
+// from React's bottom-up cleanup order.
+let originalBodyPointerEvents;
+function useDismissibleLayer(options) {
+    const { enabled, blockPointerEvents = false, onEscapeKeyDown, onPressOutside, onFocusOutside, onCascadeDismiss, exclude, pressBehavior } = options;
+    const ctx = layerStack12s.useLayerStackContext();
+    const parentNode = layerStack12s.useDismissibleParentNode();
+    const [node, setNode] = react.useState(null);
+    const [, forceRender] = react.useState({});
+    // Callback ref — fires when element mounts/unmounts.
+    // Drives `node` state which triggers registration and event listener setup.
+    const dismissibleRef = react.useCallback((el)=>{
+        setNode(el);
+    }, []);
+    // Stable callback refs
+    const onCascadeDismissRef = react.useRef(onCascadeDismiss);
+    onCascadeDismissRef.current = onCascadeDismiss;
+    const onEscapeKeyDownRef = react.useRef(onEscapeKeyDown);
+    onEscapeKeyDownRef.current = onEscapeKeyDown;
+    // -- Layer registration --
+    react.useEffect(()=>{
+        if (!node || !enabled) return;
+        const layer = {
+            node,
+            dismiss: (detail)=>onCascadeDismissRef.current?.(detail),
+            blockPointerEvents,
+            parentNode
+        };
+        layerStack12s.addLayer(ctx, layer);
+        return ()=>{
+            layerStack12s.removeLayer(ctx, node);
+        };
+    }, [
+        node,
+        enabled,
+        blockPointerEvents,
+        ctx,
+        parentNode
+    ]);
+    // -- Pointer event blocking --
+    // Follows Radix's pattern: save original value once when the first blocking
+    // layer mounts, restore when the last unmounts. The module-level variable
+    // decouples save/restore from React's bottom-up cleanup order.
+    react.useEffect(()=>{
+        if (!node || !enabled || !blockPointerEvents) return;
+        const ownerDocument = node.ownerDocument ?? document;
+        const blockingLayers = ctx.layers.filter((l)=>l.blockPointerEvents);
+        if (blockingLayers.length === 1) {
+            // First blocking layer — save the original value and block
+            originalBodyPointerEvents = ownerDocument.body.style.pointerEvents;
+            ownerDocument.body.style.pointerEvents = "none";
+        }
+        return ()=>{
+            // Check count BEFORE this layer is removed from ctx.layers.
+            // At cleanup time, this layer is still in the array.
+            const remainingBlocking = ctx.layers.filter((l)=>l.blockPointerEvents && l.node !== node);
+            if (remainingBlocking.length === 0) {
+                ownerDocument.body.style.pointerEvents = originalBodyPointerEvents;
+            }
+        };
+    }, [
+        node,
+        enabled,
+        blockPointerEvents,
+        ctx
+    ]);
+    // -- Subscribe to layer changes for style updates --
+    react.useEffect(()=>{
+        if (!enabled) return;
+        const handler = ()=>forceRender({});
+        document.addEventListener(layerStack12s.LAYER_UPDATE_EVENT, handler);
+        return ()=>document.removeEventListener(layerStack12s.LAYER_UPDATE_EVENT, handler);
+    }, [
+        enabled
+    ]);
+    // -- Escape keydown --
+    const handleEscapeKeyDown = react.useCallback((event)=>{
+        onEscapeKeyDownRef.current?.(event);
+    }, []);
+    useEscapeKeydown12s.useEscapeKeydown(enabled ? node : null, ctx, handleEscapeKeyDown);
+    // -- Press outside --
+    const handlePressOutside = react.useCallback((event)=>{
+        onPressOutside(event);
+    }, [
+        onPressOutside
+    ]);
+    const pressOutsideProps = usePointerDownOutside12s.usePointerDownOutside(enabled ? node : null, ctx, {
+        enabled,
+        exclude,
+        onPressOutside: handlePressOutside,
+        pressBehavior
+    });
+    // -- Focus outside --
+    const handleFocusOutside = react.useCallback((event)=>{
+        onFocusOutside(event);
+    }, [
+        onFocusOutside
+    ]);
+    const focusOutsideProps = useFocusOutside12s.useFocusOutside(enabled ? node : null, ctx, {
+        enabled,
+        exclude,
+        onFocusOutside: handleFocusOutside
+    });
+    // -- Compute pointer-events style --
+    const hasBlocking = ctx.layers.some((l)=>l.blockPointerEvents);
+    const pointerEventsEnabled = node ? layerStack12s.getPointerEventsEnabled(ctx, node) : true;
+    const style = hasBlocking ? {
+        pointerEvents: pointerEventsEnabled ? "auto" : "none"
+    } : {};
+    const topLayer = node ? layerStack12s.isTopMost(ctx, node) : true;
+    if (!enabled) {
+        return {
+            dismissibleRef,
+            dismissibleProps: {
+                onPointerDownCapture: NOOP,
+                onFocusCapture: NOOP,
+                onBlurCapture: NOOP
+            },
+            isTopLayer: true,
+            /** The current layer node, for providing DismissibleParentContext to children. */ layerNode: node
+        };
+    }
+    return {
+        dismissibleRef,
+        dismissibleProps: {
+            onPointerDownCapture: pressOutsideProps.onPointerDownCapture,
+            onFocusCapture: focusOutsideProps.onFocusCapture,
+            onBlurCapture: focusOutsideProps.onBlurCapture,
+            style
+        },
+        isTopLayer: topLayer,
+        /** The current layer node, for providing DismissibleParentContext to children. */ layerNode: node
+    };
+}
+
+exports.useDismissibleLayer = useDismissibleLayer;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@seed-design/react-dismissible-layer",
+  "version": "0.0.0-alpha-20260414104312",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daangn/seed-design.git",
+    "directory": "packages/react-headless/dismissible-layer"
+  },
+  "main": "./lib/index.cjs",
+  "devDependencies": {
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "bunchee",
+    "lint:publish": "bun publint"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "dependencies": {
+    "@radix-ui/react-compose-refs": "^1.1.2",
+    "@radix-ui/react-slot": "^1.2.4"
+  }
+}

package/src/DismissibleLayer.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { Slot } from "@radix-ui/react-slot";
+import { forwardRef } from "react";
+import { useDismissibleLayer, type UseDismissibleLayerOptions } from "./useDismissibleLayer";
+import { DismissibleParentContext } from "./layer-stack";
+
+export interface DismissibleLayerProps extends UseDismissibleLayerOptions {
+  children: React.ReactNode;
+}
+
+export const DismissibleLayer = forwardRef<HTMLElement, DismissibleLayerProps>((props, ref) => {
+  const { children, ...options } = props;
+  const { dismissibleRef, dismissibleProps, layerNode } = useDismissibleLayer(options);
+
+  return (
+    <DismissibleParentContext.Provider value={layerNode}>
+      <Slot ref={composeRefs(ref, dismissibleRef)} {...dismissibleProps}>
+        {children}
+      </Slot>
+    </DismissibleParentContext.Provider>
+  );
+});
+DismissibleLayer.displayName = "DismissibleLayer";

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  useDismissibleLayer,
+  type UseDismissibleLayerOptions,
+} from "./useDismissibleLayer";
+
+export { DismissibleLayer, type DismissibleLayerProps } from "./DismissibleLayer";
+
+export {
+  LayerStackContext,
+  useLayerStackContext,
+  isTopMost,
+  addBranch,
+  removeBranch,
+  type Layer,
+  type CascadeDismissDetail,
+  type LayerStackContextValue,
+} from "./layer-stack";

package/src/layer-stack.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it, mock, beforeEach } from "bun:test";
+import {
+  addLayer,
+  removeLayer,
+  addBranch,
+  removeBranch,
+  isTopMost,
+  isInNestedLayer,
+  isInBranch,
+  isBelowPointerBlockingLayer,
+  getPointerEventsEnabled,
+  type LayerStackContextValue,
+  type Layer,
+} from "./layer-stack";
+
+function createCtx(): LayerStackContextValue {
+  return { layers: [], branches: [], recentlyRemoved: new Set() };
+}
+
+function createNode(id = "node"): HTMLElement {
+  const el = document.createElement("div");
+  el.setAttribute("data-testid", id);
+  document.body.appendChild(el);
+  return el;
+}
+
+function createLayer(node: HTMLElement, overrides: Partial<Omit<Layer, "node">> = {}): Layer {
+  return {
+    node,
+    dismiss: mock(() => {}),
+    ...overrides,
+  };
+}
+
+describe("layer-stack", () => {
+  let ctx: LayerStackContextValue;
+
+  beforeEach(() => {
+    ctx = createCtx();
+    document.body.innerHTML = "";
+  });
+  describe("addLayer", () => {
+    it("adds a layer to the stack", () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      expect(ctx.layers).toHaveLength(1);
+      expect(ctx.layers[0].node).toBe(node);
+    });
+
+    it("preserves insertion order", () => {
+      const a = createNode("a");
+      const b = createNode("b");
+      addLayer(ctx, createLayer(a));
+      addLayer(ctx, createLayer(b));
+      expect(ctx.layers[0].node).toBe(a);
+      expect(ctx.layers[1].node).toBe(b);
+    });
+
+    it("replaces existing layer when same node is added twice", () => {
+      const node = createNode();
+      const first = createLayer(node, { blockPointerEvents: false });
+      const second = createLayer(node, { blockPointerEvents: true });
+      addLayer(ctx, first);
+      addLayer(ctx, second);
+      expect(ctx.layers).toHaveLength(1);
+      expect(ctx.layers[0].blockPointerEvents).toBe(true);
+    });
+  });
+
+  describe("removeLayer", () => {
+    it("removes the specified layer", () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      removeLayer(ctx, node);
+      expect(ctx.layers).toHaveLength(0);
+    });
+
+    it("does nothing for unknown nodes", () => {
+      const node = createNode();
+      removeLayer(ctx, node);
+      expect(ctx.layers).toHaveLength(0);
+    });
+
+    it("does not cascade-dismiss sibling layers (no parentNode)", () => {
+      const a = createNode("a");
+      const b = createNode("b");
+      const c = createNode("c");
+      const dismissB = mock(() => {});
+      const dismissC = mock(() => {});
+
+      addLayer(ctx, createLayer(a));
+      addLayer(ctx, createLayer(b, { dismiss: dismissB }));
+      addLayer(ctx, createLayer(c, { dismiss: dismissC }));
+
+      removeLayer(ctx, a);
+
+      expect(dismissB).not.toHaveBeenCalled();
+      expect(dismissC).not.toHaveBeenCalled();
+      expect(ctx.layers).toHaveLength(2);
+    });
+
+    it("cascade-dismisses child layers (matching parentNode)", () => {
+      const parent = createNode("parent");
+      const child = createNode("child");
+      const grandchild = createNode("grandchild");
+      const dismissChild = mock(() => {});
+      const dismissGrandchild = mock(() => {});
+
+      addLayer(ctx, createLayer(parent));
+      addLayer(ctx, createLayer(child, { dismiss: dismissChild, parentNode: parent }));
+      addLayer(ctx, createLayer(grandchild, { dismiss: dismissGrandchild, parentNode: child }));
+
+      removeLayer(ctx, parent);
+
+      // Only direct children are dismissed; grandchild is dismissed
+      // transitively when the child's own removeLayer runs.
+      expect(dismissChild).toHaveBeenCalledTimes(1);
+      expect(dismissGrandchild).not.toHaveBeenCalled();
+      expect(ctx.layers).toHaveLength(2);
+    });
+
+    it("does not cascade-dismiss layers with a different parent", () => {
+      const dialog = createNode("dialog");
+      const menu = createNode("menu");
+      const siblingMenu = createNode("sibling-menu");
+      const dismissMenu = mock(() => {});
+      const dismissSibling = mock(() => {});
+
+      addLayer(ctx, createLayer(dialog));
+      addLayer(ctx, createLayer(menu, { dismiss: dismissMenu, parentNode: dialog }));
+      addLayer(ctx, createLayer(siblingMenu, { dismiss: dismissSibling }));
+
+      removeLayer(ctx, dialog);
+
+      expect(dismissMenu).toHaveBeenCalledTimes(1);
+      expect(dismissSibling).not.toHaveBeenCalled();
+    });
+
+    it("correctly removes parent when child dismiss triggers recursive removeLayer", () => {
+      const child = createNode("child");
+      const parent = createNode("parent");
+      const sibling = createNode("sibling");
+
+      // child is inserted BEFORE parent — possible in pure data structure usage.
+      // child.dismiss recursively calls removeLayer, shifting parent's index.
+      addLayer(
+        ctx,
+        createLayer(child, {
+          dismiss: () => removeLayer(ctx, child),
+          parentNode: parent,
+        }),
+      );
+      addLayer(ctx, createLayer(parent));
+      addLayer(ctx, createLayer(sibling));
+
+      // Before: [child, parent, sibling]. parent is at index 1.
+      // removeLayer(parent) → cascade-dismisses child → child.dismiss() → removeLayer(child)
+      // After child removal: [parent, sibling]. parent shifts to index 0.
+      // The pre-computed index (1) is now stale — must re-compute.
+      removeLayer(ctx, parent);
+
+      // Only sibling should remain
+      expect(ctx.layers).toHaveLength(1);
+      expect(ctx.layers[0].node).toBe(sibling);
+    });
+
+    it("adds node to recentlyRemoved", () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      removeLayer(ctx, node);
+      expect(ctx.recentlyRemoved.has(node)).toBe(true);
+    });
+
+    it("clears recentlyRemoved after microtask", async () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      removeLayer(ctx, node);
+      expect(ctx.recentlyRemoved.has(node)).toBe(true);
+      await new Promise((r) => queueMicrotask(r));
+      expect(ctx.recentlyRemoved.has(node)).toBe(false);
+    });
+  });
+  describe("isTopMost", () => {
+    it("returns true for the last layer", () => {
+      const a = createNode("a");
+      const b = createNode("b");
+      addLayer(ctx, createLayer(a));
+      addLayer(ctx, createLayer(b));
+      expect(isTopMost(ctx, b)).toBe(true);
+      expect(isTopMost(ctx, a)).toBe(false);
+    });
+
+    it("returns false for empty stack", () => {
+      const node = createNode();
+      expect(isTopMost(ctx, node)).toBe(false);
+    });
+  });
+
+  describe("isInNestedLayer", () => {
+    it("returns true when target is inside a nested layer", () => {
+      const dialog = createNode("dialog");
+      const menu = createNode("menu");
+      const menuChild = document.createElement("span");
+      menu.appendChild(menuChild);
+
+      addLayer(ctx, createLayer(dialog));
+      addLayer(ctx, createLayer(menu, {}));
+
+      expect(isInNestedLayer(ctx, dialog, menuChild)).toBe(true);
+    });
+
+    it("returns false when target is not in any nested layer", () => {
+      const dialog = createNode("dialog");
+      const outside = createNode("outside");
+
+      addLayer(ctx, createLayer(dialog));
+
+      expect(isInNestedLayer(ctx, dialog, outside)).toBe(false);
+    });
+
+    it("returns true when recentlyRemoved is non-empty (cascading prevention)", () => {
+      const dialog = createNode("dialog");
+      const menu = createNode("menu");
+
+      addLayer(ctx, createLayer(dialog));
+      addLayer(ctx, createLayer(menu, {}));
+
+      // Simulate removal — recentlyRemoved is populated
+      removeLayer(ctx, menu);
+
+      // Even though menu is removed, target is treated as "inside"
+      expect(isInNestedLayer(ctx, dialog, document.body)).toBe(true);
+    });
+  });
+  describe("branches", () => {
+    it("isInBranch returns true for targets inside a branch", () => {
+      const branch = createNode("branch");
+      const child = document.createElement("span");
+      branch.appendChild(child);
+
+      addBranch(ctx, branch);
+      expect(isInBranch(ctx, child)).toBe(true);
+    });
+
+    it("isInBranch returns false for targets outside branches", () => {
+      const branch = createNode("branch");
+      const outside = createNode("outside");
+
+      addBranch(ctx, branch);
+      expect(isInBranch(ctx, outside)).toBe(false);
+    });
+
+    it("removeBranch removes the branch", () => {
+      const branch = createNode("branch");
+      addBranch(ctx, branch);
+      removeBranch(ctx, branch);
+      expect(ctx.branches).toHaveLength(0);
+    });
+  });
+  describe("pointer blocking", () => {
+    it("isBelowPointerBlockingLayer returns false when no blocking layers", () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      expect(isBelowPointerBlockingLayer(ctx, node)).toBe(false);
+    });
+
+    it("isBelowPointerBlockingLayer returns true when below a blocking layer", () => {
+      const dialog = createNode("dialog");
+      const menu = createNode("menu");
+      addLayer(ctx, createLayer(dialog, { blockPointerEvents: true }));
+      addLayer(ctx, createLayer(menu, { blockPointerEvents: true }));
+      expect(isBelowPointerBlockingLayer(ctx, dialog)).toBe(true);
+      expect(isBelowPointerBlockingLayer(ctx, menu)).toBe(false);
+    });
+
+    it("getPointerEventsEnabled returns true when no blocking layers", () => {
+      const node = createNode();
+      addLayer(ctx, createLayer(node));
+      expect(getPointerEventsEnabled(ctx, node)).toBe(true);
+    });
+
+    it("getPointerEventsEnabled returns false for layers below the highest blocking layer", () => {
+      const dialog = createNode("dialog");
+      const menu = createNode("menu");
+      addLayer(ctx, createLayer(dialog, { blockPointerEvents: true }));
+      addLayer(ctx, createLayer(menu, { blockPointerEvents: true }));
+      expect(getPointerEventsEnabled(ctx, dialog)).toBe(false);
+      expect(getPointerEventsEnabled(ctx, menu)).toBe(true);
+    });
+  });
+});

package/src/layer-stack.ts

@@ -0,0 +1,169 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+export interface CascadeDismissDetail {
+  /** The layer node that was removed, causing this cascade dismiss. */
+  dismissedParent: HTMLElement;
+}
+
+export interface Layer {
+  node: HTMLElement;
+  dismiss: (detail: CascadeDismissDetail) => void;
+  blockPointerEvents?: boolean;
+  /**
+   * The parent layer's node. Used to determine cascade-dismiss scope.
+   * Only layers whose parentNode matches the removed layer's node will be
+   * cascade-dismissed. Layers without a parentNode are top-level and never
+   * cascade-dismissed by sibling layer removal.
+   */
+  parentNode?: HTMLElement | null;
+}
+
+export interface LayerStackContextValue {
+  layers: Layer[];
+  branches: HTMLElement[];
+  recentlyRemoved: Set<HTMLElement>;
+}
+
+const LAYER_UPDATE_EVENT = "seed:dismissible-update";
+
+/**
+ * Shared layer stack context. No Provider needed — all consumers share the same
+ * default value (mutable arrays/sets). This mirrors Radix's DismissibleLayerContext
+ * pattern, with the option to scope via Provider if needed.
+ */
+export const LayerStackContext = createContext<LayerStackContextValue>({
+  layers: [],
+  branches: [],
+  recentlyRemoved: new Set(),
+});
+
+export function useLayerStackContext() {
+  return useContext(LayerStackContext);
+}
+
+export function isTopMost(ctx: LayerStackContextValue, node: HTMLElement): boolean {
+  return ctx.layers.at(-1)?.node === node;
+}
+
+function contains(parent: HTMLElement | null, child: EventTarget | null): boolean {
+  if (!parent || !child) return false;
+  if (!(child instanceof Node)) return false;
+  return parent.contains(child);
+}
+
+export function isInNestedLayer(
+  ctx: LayerStackContextValue,
+  node: HTMLElement,
+  target: EventTarget | null,
+): boolean {
+  const index = ctx.layers.findIndex((l) => l.node === node);
+  if (index === -1) return false;
+
+  const nested = ctx.layers.slice(index + 1);
+  if (nested.some((layer) => contains(layer.node, target))) return true;
+
+  // During layer removal, treat all focus events as "inside" to prevent
+  // cascading dismissals from focus transitions (Zag pattern).
+  if (ctx.recentlyRemoved.size > 0) return true;
+
+  return false;
+}
+
+export function isInBranch(ctx: LayerStackContextValue, target: EventTarget | null): boolean {
+  return ctx.branches.some((branch) => contains(branch, target));
+}
+
+export function isBelowPointerBlockingLayer(
+  ctx: LayerStackContextValue,
+  node: HTMLElement,
+): boolean {
+  const index = ctx.layers.findIndex((l) => l.node === node);
+  const blockingLayers = ctx.layers.filter((l) => l.blockPointerEvents);
+  const highestBlocking = blockingLayers.at(-1);
+  if (!highestBlocking) return false;
+
+  const highestBlockingIndex = ctx.layers.indexOf(highestBlocking);
+  return index < highestBlockingIndex;
+}
+
+export function getPointerEventsEnabled(ctx: LayerStackContextValue, node: HTMLElement): boolean {
+  const hasBlocking = ctx.layers.some((l) => l.blockPointerEvents);
+  if (!hasBlocking) return true;
+
+  const index = ctx.layers.findIndex((l) => l.node === node);
+  const blockingLayers = ctx.layers.filter((l) => l.blockPointerEvents);
+  const highestBlocking = blockingLayers.at(-1);
+  if (!highestBlocking) return true;
+
+  const highestBlockingIndex = ctx.layers.indexOf(highestBlocking);
+  return index >= highestBlockingIndex;
+}
+
+export function notifyLayerChange() {
+  document.dispatchEvent(new CustomEvent(LAYER_UPDATE_EVENT));
+}
+
+export { LAYER_UPDATE_EVENT };
+
+export function addLayer(ctx: LayerStackContextValue, layer: Layer) {
+  // Guard against double-registration (e.g., React strict mode re-running effects).
+  const existing = ctx.layers.findIndex((l) => l.node === layer.node);
+  if (existing >= 0) ctx.layers.splice(existing, 1);
+
+  ctx.layers.push(layer);
+  notifyLayerChange();
+}
+
+export function removeLayer(ctx: LayerStackContextValue, node: HTMLElement) {
+  const index = ctx.layers.findIndex((l) => l.node === node);
+  if (index < 0) return;
+
+  // Track recently removed to handle focus race conditions during cleanup.
+  // This prevents parent layers from incorrectly dismissing when focus
+  // moves from a closing nested layer.
+  ctx.recentlyRemoved.add(node);
+  queueMicrotask(() => ctx.recentlyRemoved.delete(node));
+
+  // Cascade-dismiss only layers that declare this node as their parent.
+  // This prevents sibling layers (independent menus, dialogs, etc.) from
+  // being incorrectly dismissed when an unrelated layer closes.
+  // Transitive children are handled by their own removeLayer calls.
+  const children = ctx.layers.filter((l) => l.parentNode === node);
+  for (const child of children) {
+    child.dismiss({ dismissedParent: node });
+  }
+
+  // Re-compute index: cascade-dismiss may have recursively removed layers,
+  // shifting the target's position in the array. In React, parents mount
+  // before children so children are always at higher indices — but this is
+  // a pure data structure with no React dependency, so we defend against
+  // arbitrary insertion order.
+  const freshIndex = ctx.layers.findIndex((l) => l.node === node);
+  if (freshIndex >= 0) ctx.layers.splice(freshIndex, 1);
+  notifyLayerChange();
+}
+
+/**
+ * React context that propagates a parent dismissible layer's node down the
+ * React tree (including through portals). Nested dismissible layers read this
+ * to register as children of the parent, enabling correct cascade-dismiss
+ * behavior without affecting unrelated sibling layers.
+ *
+ * Follows the same pattern as base-ui's FloatingNodeContext.
+ */
+export const DismissibleParentContext = createContext<HTMLElement | null>(null);
+
+export function useDismissibleParentNode() {
+  return useContext(DismissibleParentContext);
+}
+
+export function addBranch(ctx: LayerStackContextValue, node: HTMLElement) {
+  ctx.branches.push(node);
+}
+
+export function removeBranch(ctx: LayerStackContextValue, node: HTMLElement) {
+  const index = ctx.branches.indexOf(node);
+  if (index >= 0) ctx.branches.splice(index, 1);
+}