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

package/src/useDismissibleLayer.ts

@@ -0,0 +1,234 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState, type CSSProperties } from "react";
+import {
+  addLayer,
+  removeLayer,
+  isTopMost,
+  getPointerEventsEnabled,
+  useLayerStackContext,
+  useDismissibleParentNode,
+  LAYER_UPDATE_EVENT,
+  type CascadeDismissDetail,
+} from "./layer-stack";
+import { useEscapeKeydown } from "./use-escape-keydown";
+import { usePointerDownOutside } from "./use-pointer-down-outside";
+import { useFocusOutside } from "./use-focus-outside";
+
+export interface UseDismissibleLayerOptions {
+  /**
+   * Whether the dismissible layer is active. When false, the layer is not
+   * registered in the stack and no event listeners are attached.
+   */
+  enabled: boolean;
+
+  /**
+   * When true, disables pointer events on elements outside this layer.
+   * Used for modal overlays (Dialog, BottomSheet).
+   */
+  blockPointerEvents?: boolean;
+
+  /**
+   * Called when escape key is pressed while this layer is topmost.
+   * Call `event.preventDefault()` to prevent dismiss.
+   */
+  onEscapeKeyDown: (event: KeyboardEvent) => void;
+
+  /**
+   * Called when a press occurs outside the layer.
+   * Call `event.preventDefault()` to signal that the event is handled.
+   */
+  onPressOutside: (event: PointerEvent | TouchEvent) => void;
+
+  /**
+   * Called when focus moves outside the layer.
+   * Call `event.preventDefault()` to signal that the event is handled.
+   */
+  onFocusOutside: (event: FocusEvent) => void;
+
+  /**
+   * Called when a parent layer is removed and this layer should close as a consequence.
+   * Unlike escape/outside/focus callbacks, this is not preventable.
+   */
+  onCascadeDismiss: (detail: CascadeDismissDetail) => void;
+
+  /**
+   * Custom function to determine if a target should be treated as "inside".
+   * Useful for trigger elements that are outside the layer DOM but should
+   * not trigger dismiss (e.g., Menu trigger).
+   */
+  exclude?: (target: HTMLElement) => boolean;
+
+  /**
+   * Determines when an outside press triggers dismiss.
+   *
+   * - `"confirm"` (default): Both mouse and touch defer to click.
+   * - `"eager"`: Mouse on pointerdown, touch defers to click.
+   * - `"drag"`: Mouse on pointerdown, touch on drag (>10px immediate, >5px on touchend).
+   */
+  pressBehavior?: "eager" | "confirm" | "drag";
+}
+
+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: string;
+
+export function useDismissibleLayer(options: UseDismissibleLayerOptions) {
+  const {
+    enabled,
+    blockPointerEvents = false,
+    onEscapeKeyDown,
+    onPressOutside,
+    onFocusOutside,
+    onCascadeDismiss,
+    exclude,
+    pressBehavior,
+  } = options;
+
+  const ctx = useLayerStackContext();
+  const parentNode = useDismissibleParentNode();
+  const [node, setNode] = useState<HTMLElement | null>(null);
+  const [, forceRender] = useState({});
+
+  // Callback ref — fires when element mounts/unmounts.
+  // Drives `node` state which triggers registration and event listener setup.
+  const dismissibleRef = useCallback((el: HTMLElement | null) => {
+    setNode(el);
+  }, []);
+
+  // Stable callback refs
+  const onCascadeDismissRef = useRef(onCascadeDismiss);
+  onCascadeDismissRef.current = onCascadeDismiss;
+
+  const onEscapeKeyDownRef = useRef(onEscapeKeyDown);
+  onEscapeKeyDownRef.current = onEscapeKeyDown;
+
+  // -- Layer registration --
+  useEffect(() => {
+    if (!node || !enabled) return;
+
+    const layer = {
+      node,
+      dismiss: (detail: CascadeDismissDetail) => onCascadeDismissRef.current?.(detail),
+      blockPointerEvents,
+      parentNode,
+    };
+
+    addLayer(ctx, layer);
+
+    return () => {
+      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.
+  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 --
+  useEffect(() => {
+    if (!enabled) return;
+    const handler = () => forceRender({});
+    document.addEventListener(LAYER_UPDATE_EVENT, handler);
+    return () => document.removeEventListener(LAYER_UPDATE_EVENT, handler);
+  }, [enabled]);
+
+  // -- Escape keydown --
+  const handleEscapeKeyDown = useCallback((event: KeyboardEvent) => {
+    onEscapeKeyDownRef.current?.(event);
+  }, []);
+
+  useEscapeKeydown(enabled ? node : null, ctx, handleEscapeKeyDown);
+
+  // -- Press outside --
+  const handlePressOutside = useCallback(
+    (event: PointerEvent | TouchEvent) => {
+      onPressOutside(event);
+    },
+    [onPressOutside],
+  );
+
+  const pressOutsideProps = usePointerDownOutside(enabled ? node : null, ctx, {
+    enabled,
+    exclude,
+    onPressOutside: handlePressOutside,
+    pressBehavior,
+  });
+
+  // -- Focus outside --
+  const handleFocusOutside = useCallback(
+    (event: FocusEvent) => {
+      onFocusOutside(event);
+    },
+    [onFocusOutside],
+  );
+
+  const focusOutsideProps = useFocusOutside(enabled ? node : null, ctx, {
+    enabled,
+    exclude,
+    onFocusOutside: handleFocusOutside,
+  });
+
+  // -- Compute pointer-events style --
+  const hasBlocking = ctx.layers.some((l) => l.blockPointerEvents);
+  const pointerEventsEnabled = node ? getPointerEventsEnabled(ctx, node) : true;
+
+  const style: CSSProperties = hasBlocking
+    ? { pointerEvents: pointerEventsEnabled ? "auto" : "none" }
+    : {};
+
+  const topLayer = node ? 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,
+  };
+}