@zag-js/dismissable 2.0.0-next.0 → 2.0.0-next.2

package/dist/dismissable-layer.d.mts

@@ -1,6 +1,6 @@
 import { InteractOutsideHandlers } from '@zag-js/interact-outside';
-import { MaybeFunction } from '@zag-js/utils';
-import { LayerDismissEvent, LayerStyleTarget, LayerType } from './layer-stack.mjs';
+import { MaybeFunction, TeardownReason } from '@zag-js/utils';
+import { LayerDismissEvent, LayerSnapshot, LayerType } from './layer-stack.mjs';
 
 type MaybeElement = HTMLElement | null;
 type Container = MaybeElement | Array<MaybeElement>;
@@ -25,11 +25,9 @@ interface PersistentElementOptions {
 }
 interface DismissableElementOptions extends DismissableElementHandlers, PersistentElementOptions {
     /**
-     * Extra elements that receive the same layer stack CSS vars, `data-*`, and `--z-index`
-     * (from the primary node's computed `z-index`) as the dismissable node
-     * (e.g. dialog backdrop + positioner when the node is content).
+     * Function called when the layer's position or nesting state changes.
      */
-    layerStyleTargets?: LayerStyleTarget[] | undefined;
+    onLayerChange: (snapshot: LayerSnapshot) => void;
     /**
      * Whether to log debug information
      */
@@ -37,7 +35,7 @@ interface DismissableElementOptions extends DismissableElementHandlers, Persiste
     /**
      * Whether to block pointer events outside the dismissable element
      */
-    pointerBlocking?: boolean | undefined;
+    pointerBlocking?: boolean | (() => boolean) | undefined;
     /**
      * Function called when the dismissable element is dismissed
      */
@@ -59,7 +57,7 @@ interface DismissableElementOptions extends DismissableElementHandlers, Persiste
      */
     type?: LayerType | undefined;
 }
-declare function trackDismissableElement(nodeOrFn: NodeOrFn, options: DismissableElementOptions): () => void;
+declare function trackDismissableElement(nodeOrFn: NodeOrFn, options: DismissableElementOptions): (args_0?: TeardownReason | undefined) => void;
 declare function trackDismissableBranch(nodeOrFn: NodeOrFn, options?: {
     defer?: boolean | undefined;
 }): () => void;

package/dist/dismissable-layer.d.ts

@@ -1,6 +1,6 @@
 import { InteractOutsideHandlers } from '@zag-js/interact-outside';
-import { MaybeFunction } from '@zag-js/utils';
-import { LayerDismissEvent, LayerStyleTarget, LayerType } from './layer-stack.js';
+import { MaybeFunction, TeardownReason } from '@zag-js/utils';
+import { LayerDismissEvent, LayerSnapshot, LayerType } from './layer-stack.js';
 
 type MaybeElement = HTMLElement | null;
 type Container = MaybeElement | Array<MaybeElement>;
@@ -25,11 +25,9 @@ interface PersistentElementOptions {
 }
 interface DismissableElementOptions extends DismissableElementHandlers, PersistentElementOptions {
     /**
-     * Extra elements that receive the same layer stack CSS vars, `data-*`, and `--z-index`
-     * (from the primary node's computed `z-index`) as the dismissable node
-     * (e.g. dialog backdrop + positioner when the node is content).
+     * Function called when the layer's position or nesting state changes.
      */
-    layerStyleTargets?: LayerStyleTarget[] | undefined;
+    onLayerChange: (snapshot: LayerSnapshot) => void;
     /**
      * Whether to log debug information
      */
@@ -37,7 +35,7 @@ interface DismissableElementOptions extends DismissableElementHandlers, Persiste
     /**
      * Whether to block pointer events outside the dismissable element
      */
-    pointerBlocking?: boolean | undefined;
+    pointerBlocking?: boolean | (() => boolean) | undefined;
     /**
      * Function called when the dismissable element is dismissed
      */
@@ -59,7 +57,7 @@ interface DismissableElementOptions extends DismissableElementHandlers, Persiste
      */
     type?: LayerType | undefined;
 }
-declare function trackDismissableElement(nodeOrFn: NodeOrFn, options: DismissableElementOptions): () => void;
+declare function trackDismissableElement(nodeOrFn: NodeOrFn, options: DismissableElementOptions): (args_0?: TeardownReason | undefined) => void;
 declare function trackDismissableBranch(nodeOrFn: NodeOrFn, options?: {
     defer?: boolean | undefined;
 }): () => void;

package/dist/dismissable-layer.js

@@ -31,14 +31,6 @@ var import_escape_keydown = require("./escape-keydown.js");
 var import_layer_stack = require("./layer-stack.js");
 var import_pointer_event_outside = require("./pointer-event-outside.js");
 function trackDismissableElementImpl(node, options) {
-  const { warnOnMissingNode = true } = options;
-  if (warnOnMissingNode && !node) {
-    (0, import_utils.warn)("[@zag-js/dismissable] node is `null` or `undefined`");
-    return;
-  }
-  if (!node) {
-    return;
-  }
   const {
     onDismiss,
     onRequestDismiss,
@@ -46,7 +38,7 @@ function trackDismissableElementImpl(node, options) {
     exclude: excludeContainers,
     debug,
     type = "dialog",
-    layerStyleTargets
+    onLayerChange
   } = options;
   const layer = {
     dismiss: onDismiss,
@@ -54,10 +46,9 @@ function trackDismissableElementImpl(node, options) {
     type,
     pointerBlocking,
     requestDismiss: onRequestDismiss,
-    styleTargets: layerStyleTargets
+    onLayerChange
   };
   import_layer_stack.layerStack.add(layer);
-  (0, import_pointer_event_outside.assignPointerEventToLayers)();
   function onPointerDownOutside(event) {
     const target = (0, import_dom_query.getEventTarget)(event.detail.originalEvent);
     if (import_layer_stack.layerStack.isBelowPointerBlockingLayer(node) || import_layer_stack.layerStack.isInBranch(target)) return;
@@ -89,7 +80,6 @@ function trackDismissableElementImpl(node, options) {
     }
   }
   function exclude(target) {
-    if (!node) return false;
     const containers = typeof excludeContainers === "function" ? excludeContainers() : excludeContainers;
     const _containers = Array.isArray(containers) ? containers : [containers];
     const persistentElements = options.persistentElements?.map((fn) => fn()).filter(import_dom_query.isHTMLElement);
@@ -97,51 +87,36 @@ function trackDismissableElementImpl(node, options) {
     return _containers.some((node2) => (0, import_dom_query.contains)(node2, target)) || import_layer_stack.layerStack.isInNestedLayer(node, target);
   }
   const cleanups = [
-    pointerBlocking ? (0, import_pointer_event_outside.disablePointerEventsOutside)(node, options.persistentElements) : void 0,
+    (0, import_layer_stack.isPointerBlocking)(layer) ? (0, import_pointer_event_outside.disablePointerEventsOutside)(node, options.persistentElements) : void 0,
     (0, import_escape_keydown.trackEscapeKeydown)(node, onEscapeKeyDown),
     (0, import_interact_outside.trackInteractOutside)(node, { exclude, onFocusOutside, onPointerDownOutside, defer: options.defer })
   ];
-  return () => {
-    import_layer_stack.layerStack.remove(node);
-    (0, import_pointer_event_outside.assignPointerEventToLayers)();
-    (0, import_pointer_event_outside.clearPointerEvent)(node);
+  return (reason) => {
+    import_layer_stack.layerStack.remove(node, { reattach: reason === "restart" });
     cleanups.forEach((fn) => fn?.());
   };
 }
 function trackDismissableElement(nodeOrFn, options) {
-  const { defer } = options;
-  const func = defer ? import_dom_query.raf : (v) => v();
-  const cleanups = [];
-  cleanups.push(
-    func(() => {
-      const node = (0, import_utils.isFunction)(nodeOrFn) ? nodeOrFn() : nodeOrFn;
-      cleanups.push(trackDismissableElementImpl(node, options));
-    })
-  );
-  return () => {
-    cleanups.forEach((fn) => fn?.());
-  };
+  const { warnOnMissingNode = true } = options;
+  return (0, import_dom_query.whenNode)(nodeOrFn, (node) => trackDismissableElementImpl(node, options), {
+    defer: options.defer,
+    onMissing: warnOnMissingNode ? () => (0, import_utils.warn)("[@zag-js/dismissable] node is `null` or `undefined`") : void 0
+  });
 }
 function trackDismissableBranch(nodeOrFn, options = {}) {
-  const { defer } = options;
-  const func = defer ? import_dom_query.raf : (v) => v();
-  const cleanups = [];
-  cleanups.push(
-    func(() => {
-      const node = (0, import_utils.isFunction)(nodeOrFn) ? nodeOrFn() : nodeOrFn;
-      if (!node) {
-        (0, import_utils.warn)("[@zag-js/dismissable] branch node is `null` or `undefined`");
-        return;
-      }
+  return (0, import_dom_query.whenNode)(
+    nodeOrFn,
+    (node) => {
       import_layer_stack.layerStack.addBranch(node);
-      cleanups.push(() => {
+      return () => {
         import_layer_stack.layerStack.removeBranch(node);
-      });
-    })
+      };
+    },
+    {
+      defer: options.defer,
+      onMissing: () => (0, import_utils.warn)("[@zag-js/dismissable] branch node is `null` or `undefined`")
+    }
   );
-  return () => {
-    cleanups.forEach((fn) => fn?.());
-  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/dismissable-layer.mjs

@@ -1,21 +1,16 @@
 // src/dismissable-layer.ts
-import { contains, getEventTarget, isHTMLElement, raf } from "@zag-js/dom-query";
+import { contains, getEventTarget, isHTMLElement, whenNode } from "@zag-js/dom-query";
 import {
   trackInteractOutside
 } from "@zag-js/interact-outside";
-import { isFunction, warn } from "@zag-js/utils";
+import { warn } from "@zag-js/utils";
 import { trackEscapeKeydown } from "./escape-keydown.mjs";
-import { layerStack } from "./layer-stack.mjs";
-import { assignPointerEventToLayers, clearPointerEvent, disablePointerEventsOutside } from "./pointer-event-outside.mjs";
+import {
+  isPointerBlocking,
+  layerStack
+} from "./layer-stack.mjs";
+import { disablePointerEventsOutside } from "./pointer-event-outside.mjs";
 function trackDismissableElementImpl(node, options) {
-  const { warnOnMissingNode = true } = options;
-  if (warnOnMissingNode && !node) {
-    warn("[@zag-js/dismissable] node is `null` or `undefined`");
-    return;
-  }
-  if (!node) {
-    return;
-  }
   const {
     onDismiss,
     onRequestDismiss,
@@ -23,7 +18,7 @@ function trackDismissableElementImpl(node, options) {
     exclude: excludeContainers,
     debug,
     type = "dialog",
-    layerStyleTargets
+    onLayerChange
   } = options;
   const layer = {
     dismiss: onDismiss,
@@ -31,10 +26,9 @@ function trackDismissableElementImpl(node, options) {
     type,
     pointerBlocking,
     requestDismiss: onRequestDismiss,
-    styleTargets: layerStyleTargets
+    onLayerChange
   };
   layerStack.add(layer);
-  assignPointerEventToLayers();
   function onPointerDownOutside(event) {
     const target = getEventTarget(event.detail.originalEvent);
     if (layerStack.isBelowPointerBlockingLayer(node) || layerStack.isInBranch(target)) return;
@@ -66,7 +60,6 @@ function trackDismissableElementImpl(node, options) {
     }
   }
   function exclude(target) {
-    if (!node) return false;
     const containers = typeof excludeContainers === "function" ? excludeContainers() : excludeContainers;
     const _containers = Array.isArray(containers) ? containers : [containers];
     const persistentElements = options.persistentElements?.map((fn) => fn()).filter(isHTMLElement);
@@ -74,51 +67,36 @@ function trackDismissableElementImpl(node, options) {
     return _containers.some((node2) => contains(node2, target)) || layerStack.isInNestedLayer(node, target);
   }
   const cleanups = [
-    pointerBlocking ? disablePointerEventsOutside(node, options.persistentElements) : void 0,
+    isPointerBlocking(layer) ? disablePointerEventsOutside(node, options.persistentElements) : void 0,
     trackEscapeKeydown(node, onEscapeKeyDown),
     trackInteractOutside(node, { exclude, onFocusOutside, onPointerDownOutside, defer: options.defer })
   ];
-  return () => {
-    layerStack.remove(node);
-    assignPointerEventToLayers();
-    clearPointerEvent(node);
+  return (reason) => {
+    layerStack.remove(node, { reattach: reason === "restart" });
     cleanups.forEach((fn) => fn?.());
   };
 }
 function trackDismissableElement(nodeOrFn, options) {
-  const { defer } = options;
-  const func = defer ? raf : (v) => v();
-  const cleanups = [];
-  cleanups.push(
-    func(() => {
-      const node = isFunction(nodeOrFn) ? nodeOrFn() : nodeOrFn;
-      cleanups.push(trackDismissableElementImpl(node, options));
-    })
-  );
-  return () => {
-    cleanups.forEach((fn) => fn?.());
-  };
+  const { warnOnMissingNode = true } = options;
+  return whenNode(nodeOrFn, (node) => trackDismissableElementImpl(node, options), {
+    defer: options.defer,
+    onMissing: warnOnMissingNode ? () => warn("[@zag-js/dismissable] node is `null` or `undefined`") : void 0
+  });
 }
 function trackDismissableBranch(nodeOrFn, options = {}) {
-  const { defer } = options;
-  const func = defer ? raf : (v) => v();
-  const cleanups = [];
-  cleanups.push(
-    func(() => {
-      const node = isFunction(nodeOrFn) ? nodeOrFn() : nodeOrFn;
-      if (!node) {
-        warn("[@zag-js/dismissable] branch node is `null` or `undefined`");
-        return;
-      }
+  return whenNode(
+    nodeOrFn,
+    (node) => {
       layerStack.addBranch(node);
-      cleanups.push(() => {
+      return () => {
         layerStack.removeBranch(node);
-      });
-    })
+      };
+    },
+    {
+      defer: options.defer,
+      onMissing: () => warn("[@zag-js/dismissable] branch node is `null` or `undefined`")
+    }
   );
-  return () => {
-    cleanups.forEach((fn) => fn?.());
-  };
 }
 export {
   trackDismissableBranch,

package/dist/index.d.mts

@@ -1,4 +1,6 @@
 export { FocusOutsideEvent, InteractOutsideEvent, InteractOutsideHandlers, PointerDownOutsideEvent } from '@zag-js/interact-outside';
 export { DismissableElementHandlers, DismissableElementOptions, PersistentElementOptions, trackDismissableBranch, trackDismissableElement } from './dismissable-layer.mjs';
-export { LayerStyleTarget, LayerType } from './layer-stack.mjs';
+export { DismissableLayerStyle, DismissableLayerStyleOptions, getDismissableLayerAttrs, getDismissableLayerStyle } from './layer-props.mjs';
+export { LayerSnapshot, LayerType } from './layer-stack.mjs';
+export { syncPointerEvents } from './pointer-event-outside.mjs';
 import '@zag-js/utils';

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { FocusOutsideEvent, InteractOutsideEvent, InteractOutsideHandlers, PointerDownOutsideEvent } from '@zag-js/interact-outside';
 export { DismissableElementHandlers, DismissableElementOptions, PersistentElementOptions, trackDismissableBranch, trackDismissableElement } from './dismissable-layer.js';
-export { LayerStyleTarget, LayerType } from './layer-stack.js';
+export { DismissableLayerStyle, DismissableLayerStyleOptions, getDismissableLayerAttrs, getDismissableLayerStyle } from './layer-props.js';
+export { LayerSnapshot, LayerType } from './layer-stack.js';
+export { syncPointerEvents } from './pointer-event-outside.js';
 import '@zag-js/utils';

package/dist/index.js

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -16,9 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  syncPointerEvents: () => import_pointer_event_outside.syncPointerEvents
+});
 module.exports = __toCommonJS(index_exports);
 __reExport(index_exports, require("./dismissable-layer.js"), module.exports);
+__reExport(index_exports, require("./layer-props.js"), module.exports);
+var import_pointer_event_outside = require("./pointer-event-outside.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ...require("./dismissable-layer.js")
+  syncPointerEvents,
+  ...require("./dismissable-layer.js"),
+  ...require("./layer-props.js")
 });

package/dist/index.mjs

@@ -1,2 +1,7 @@
 // src/index.ts
 export * from "./dismissable-layer.mjs";
+export * from "./layer-props.mjs";
+import { syncPointerEvents } from "./pointer-event-outside.mjs";
+export {
+  syncPointerEvents
+};

package/dist/layer-props.d.mts

@@ -0,0 +1,30 @@
+import { LayerSnapshot, LayerType } from './layer-stack.mjs';
+
+declare function getDismissableLayerAttrs(layer: LayerSnapshot | null | undefined): {
+    "data-nested": LayerType | undefined;
+    "data-has-nested": LayerType | undefined;
+};
+interface DismissableLayerStyleOptions {
+    /**
+     * Set `--z-index: var(--layer-index)` on the element that establishes the actual
+     * stacking context (backdrop / positioner). Content parts sit inside that stacking
+     * context already, so they don't need this.
+     */
+    zIndex?: boolean;
+    /**
+     * Set `pointer-events: none` while a pointer-blocking layer sits above this one.
+     * Omit for elements (like popper positioners) that already manage their own
+     * `pointer-events`.
+     */
+    pointerEvents?: boolean;
+}
+interface DismissableLayerStyle {
+    [key: string]: string | undefined;
+    "--layer-index"?: string | undefined;
+    "--nested-layer-count"?: string | undefined;
+    "--z-index"?: string | undefined;
+    pointerEvents?: "none" | "auto" | undefined;
+}
+declare function getDismissableLayerStyle(layer: LayerSnapshot | null | undefined, options?: DismissableLayerStyleOptions): DismissableLayerStyle;
+
+export { type DismissableLayerStyle, type DismissableLayerStyleOptions, getDismissableLayerAttrs, getDismissableLayerStyle };

package/dist/layer-props.d.ts

@@ -0,0 +1,30 @@
+import { LayerSnapshot, LayerType } from './layer-stack.js';
+
+declare function getDismissableLayerAttrs(layer: LayerSnapshot | null | undefined): {
+    "data-nested": LayerType | undefined;
+    "data-has-nested": LayerType | undefined;
+};
+interface DismissableLayerStyleOptions {
+    /**
+     * Set `--z-index: var(--layer-index)` on the element that establishes the actual
+     * stacking context (backdrop / positioner). Content parts sit inside that stacking
+     * context already, so they don't need this.
+     */
+    zIndex?: boolean;
+    /**
+     * Set `pointer-events: none` while a pointer-blocking layer sits above this one.
+     * Omit for elements (like popper positioners) that already manage their own
+     * `pointer-events`.
+     */
+    pointerEvents?: boolean;
+}
+interface DismissableLayerStyle {
+    [key: string]: string | undefined;
+    "--layer-index"?: string | undefined;
+    "--nested-layer-count"?: string | undefined;
+    "--z-index"?: string | undefined;
+    pointerEvents?: "none" | "auto" | undefined;
+}
+declare function getDismissableLayerStyle(layer: LayerSnapshot | null | undefined, options?: DismissableLayerStyleOptions): DismissableLayerStyle;
+
+export { type DismissableLayerStyle, type DismissableLayerStyleOptions, getDismissableLayerAttrs, getDismissableLayerStyle };

package/dist/layer-props.js

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/layer-props.ts
+var layer_props_exports = {};
+__export(layer_props_exports, {
+  getDismissableLayerAttrs: () => getDismissableLayerAttrs,
+  getDismissableLayerStyle: () => getDismissableLayerStyle
+});
+module.exports = __toCommonJS(layer_props_exports);
+function getDismissableLayerAttrs(layer) {
+  return {
+    "data-nested": layer?.active && layer.nested ? layer.type : void 0,
+    "data-has-nested": layer?.active && layer.hasNested ? layer.type : void 0
+  };
+}
+function getDismissableLayerStyle(layer, options = {}) {
+  const active = layer?.active === true;
+  const style = {
+    "--layer-index": active ? `${layer.index}` : void 0,
+    "--nested-layer-count": active ? `${layer.nestedCount}` : void 0,
+    "--z-index": options.zIndex && active ? "var(--layer-index)" : void 0
+  };
+  if (options.pointerEvents) {
+    style.pointerEvents = active ? layer.blocked ? "none" : "auto" : void 0;
+  }
+  return style;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDismissableLayerAttrs,
+  getDismissableLayerStyle
+});

package/dist/layer-props.mjs

@@ -0,0 +1,23 @@
+// src/layer-props.ts
+function getDismissableLayerAttrs(layer) {
+  return {
+    "data-nested": layer?.active && layer.nested ? layer.type : void 0,
+    "data-has-nested": layer?.active && layer.hasNested ? layer.type : void 0
+  };
+}
+function getDismissableLayerStyle(layer, options = {}) {
+  const active = layer?.active === true;
+  const style = {
+    "--layer-index": active ? `${layer.index}` : void 0,
+    "--nested-layer-count": active ? `${layer.nestedCount}` : void 0,
+    "--z-index": options.zIndex && active ? "var(--layer-index)" : void 0
+  };
+  if (options.pointerEvents) {
+    style.pointerEvents = active ? layer.blocked ? "none" : "auto" : void 0;
+  }
+  return style;
+}
+export {
+  getDismissableLayerAttrs,
+  getDismissableLayerStyle
+};

package/dist/layer-stack.d.mts

@@ -6,25 +6,49 @@ type LayerDismissEventDetail = {
     targetIndex: number;
 };
 type LayerDismissEvent = CustomEvent<LayerDismissEventDetail>;
-type LayerStyleTarget = () => HTMLElement | null;
+interface LayerSnapshot {
+    active: boolean;
+    type: LayerType;
+    index: number;
+    nested: boolean;
+    hasNested: boolean;
+    nestedCount: number;
+    blocked: boolean;
+}
 interface Layer {
+    /** Assigned on first registration. */
+    id?: string | undefined;
+    /** The layer this one opened inside. Captured once and kept across re-registration. */
+    parentId?: string | undefined;
     dismiss: VoidFunction;
     node: HTMLElement;
     type: LayerType;
-    pointerBlocking?: boolean | undefined;
+    pointerBlocking?: boolean | (() => boolean) | undefined;
     requestDismiss?: ((event: LayerDismissEvent) => void) | undefined;
-    styleTargets?: LayerStyleTarget[] | undefined;
+    onLayerChange?: ((snapshot: LayerSnapshot) => void) | undefined;
+    snapshot?: LayerSnapshot | undefined;
 }
+/** Resolved on read, so a layer's blocking can change without re-registering it. */
+declare function isPointerBlocking(layer: Pick<Layer, "pointerBlocking">): boolean;
 declare const layerStack: {
     layers: Layer[];
     branches: HTMLElement[];
     recentlyRemoved: Set<HTMLElement>;
+    pendingReattach: Map<HTMLElement, {
+        id: string | undefined;
+        parentId: string | undefined;
+        index: number;
+    }>;
     count(): number;
     pointerBlockingLayers(): Layer[];
     topMostPointerBlockingLayer(): Layer | undefined;
     hasPointerBlockingLayer(): boolean;
     isBelowPointerBlockingLayer(node: HTMLElement): boolean;
     isTopMost(node: HTMLElement | null): boolean;
+    layerFor(node: HTMLElement | null): Layer | undefined;
+    isDescendantOf(layer: Layer, ancestorId: string | undefined): boolean;
+    depthOf(layer: Layer): number;
+    /** Descendants, shallowest first, so a cascade dismisses parents before their own children. */
     getNestedLayers(node: HTMLElement): Layer[];
     getLayersByType(type: LayerType): Layer[];
     getNestedLayersByType(node: HTMLElement, type: LayerType): Layer[];
@@ -34,7 +58,9 @@ declare const layerStack: {
     isInBranch(target: HTMLElement | EventTarget | null): boolean;
     add(layer: Layer): void;
     addBranch(node: HTMLElement): void;
-    remove(node: HTMLElement): void;
+    remove(node: HTMLElement, options?: {
+        reattach?: boolean;
+    }): void;
     removeBranch(node: HTMLElement): void;
     syncLayers(): void;
     indexOf(node: HTMLElement | undefined): number;
@@ -42,4 +68,4 @@ declare const layerStack: {
     clear(): void;
 };
 
-export { type Layer, type LayerDismissEvent, type LayerDismissEventDetail, type LayerStyleTarget, type LayerType, layerStack };
+export { type Layer, type LayerDismissEvent, type LayerDismissEventDetail, type LayerSnapshot, type LayerType, isPointerBlocking, layerStack };

package/dist/layer-stack.d.ts

@@ -6,25 +6,49 @@ type LayerDismissEventDetail = {
     targetIndex: number;
 };
 type LayerDismissEvent = CustomEvent<LayerDismissEventDetail>;
-type LayerStyleTarget = () => HTMLElement | null;
+interface LayerSnapshot {
+    active: boolean;
+    type: LayerType;
+    index: number;
+    nested: boolean;
+    hasNested: boolean;
+    nestedCount: number;
+    blocked: boolean;
+}
 interface Layer {
+    /** Assigned on first registration. */
+    id?: string | undefined;
+    /** The layer this one opened inside. Captured once and kept across re-registration. */
+    parentId?: string | undefined;
     dismiss: VoidFunction;
     node: HTMLElement;
     type: LayerType;
-    pointerBlocking?: boolean | undefined;
+    pointerBlocking?: boolean | (() => boolean) | undefined;
     requestDismiss?: ((event: LayerDismissEvent) => void) | undefined;
-    styleTargets?: LayerStyleTarget[] | undefined;
+    onLayerChange?: ((snapshot: LayerSnapshot) => void) | undefined;
+    snapshot?: LayerSnapshot | undefined;
 }
+/** Resolved on read, so a layer's blocking can change without re-registering it. */
+declare function isPointerBlocking(layer: Pick<Layer, "pointerBlocking">): boolean;
 declare const layerStack: {
     layers: Layer[];
     branches: HTMLElement[];
     recentlyRemoved: Set<HTMLElement>;
+    pendingReattach: Map<HTMLElement, {
+        id: string | undefined;
+        parentId: string | undefined;
+        index: number;
+    }>;
     count(): number;
     pointerBlockingLayers(): Layer[];
     topMostPointerBlockingLayer(): Layer | undefined;
     hasPointerBlockingLayer(): boolean;
     isBelowPointerBlockingLayer(node: HTMLElement): boolean;
     isTopMost(node: HTMLElement | null): boolean;
+    layerFor(node: HTMLElement | null): Layer | undefined;
+    isDescendantOf(layer: Layer, ancestorId: string | undefined): boolean;
+    depthOf(layer: Layer): number;
+    /** Descendants, shallowest first, so a cascade dismisses parents before their own children. */
     getNestedLayers(node: HTMLElement): Layer[];
     getLayersByType(type: LayerType): Layer[];
     getNestedLayersByType(node: HTMLElement, type: LayerType): Layer[];
@@ -34,7 +58,9 @@ declare const layerStack: {
     isInBranch(target: HTMLElement | EventTarget | null): boolean;
     add(layer: Layer): void;
     addBranch(node: HTMLElement): void;
-    remove(node: HTMLElement): void;
+    remove(node: HTMLElement, options?: {
+        reattach?: boolean;
+    }): void;
     removeBranch(node: HTMLElement): void;
     syncLayers(): void;
     indexOf(node: HTMLElement | undefined): number;
@@ -42,4 +68,4 @@ declare const layerStack: {
     clear(): void;
 };
 
-export { type Layer, type LayerDismissEvent, type LayerDismissEventDetail, type LayerStyleTarget, type LayerType, layerStack };
+export { type Layer, type LayerDismissEvent, type LayerDismissEventDetail, type LayerSnapshot, type LayerType, isPointerBlocking, layerStack };