@forgeax/app-shell 0.52.0 → 0.54.0

package/dist/react.d.ts

@@ -197,6 +197,41 @@ interface DockTabStatusSummaryProps extends HTMLAttributes<HTMLSpanElement> {
  */
 declare const DockTabStatusSummary: react.ForwardRefExoticComponent<DockTabStatusSummaryProps & react.RefAttributes<HTMLSpanElement>>;
 
+/** Stable opt-in hook for portalled controls that belong to an interaction. */
+declare const OWNED_INTERACTION_SURFACE_SELECTOR = "[data-fx-interaction-scope]";
+/**
+ * Report whether a pointer/focus target belongs to an owned or caller-exempt
+ * interaction surface. Each caller selector is isolated so one malformed host
+ * selector cannot suppress a later valid match or escape the dismissal guard.
+ */
+declare function isDismissExemptInteractionTarget(target: Element | null, additionalSelectors?: readonly string[]): boolean;
+
+type OutsideDismissReason = 'pointer' | 'focus' | 'iframe-focus';
+interface OutsideDismissEventTarget {
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+interface OutsideDismissLifecycleOptions {
+    readonly isOpen: () => boolean;
+    readonly isPinned: () => boolean;
+    readonly containsTarget: (target: Element) => boolean;
+    readonly isDismissExempt: (target: Element | null) => boolean;
+    readonly onContainedPointerDown?: (target: Element) => void;
+    readonly dismiss: (reason: OutsideDismissReason) => void;
+    readonly documentTarget?: OutsideDismissEventTarget;
+    readonly windowTarget?: OutsideDismissEventTarget;
+    readonly getActiveElement?: () => Element | null;
+    readonly requestFrame?: (callback: FrameRequestCallback) => number;
+    readonly cancelFrame?: (handle: number) => void;
+}
+/**
+ * Own the browser listener lifecycle for outside pointer/focus dismissal.
+ * Products inject live state, containment, exemptions and the close operation;
+ * App Shell only balances listeners, coalesces deferred iframe focus, and fences
+ * callbacks after disposal.
+ */
+declare function installOutsideDismissLifecycle(options: OutsideDismissLifecycleOptions): () => void;
+
 type PanelContentPadding = 'none' | 'sm' | 'md';
 type PanelContentScroll = 'none' | 'auto';
 type PanelContentTone = 'default' | 'surface' | 'tool';
@@ -338,4 +373,4 @@ interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
 /** Structural shell marker that preserves the caller's semantic element. */
 declare function ShellSlot({ as, name, ...props }: ShellSlotProps): ReactElement;
 
-export { type AnchoredResizeDirection, AnchoredResizeHandle, type AnchoredResizeHandleProps, type AnchoredResizeSession, DetachedPanelBoundary, type DetachedPanelBoundaryProps, DetachedSurfaceFrame, type DetachedSurfaceFrameProps, DetachedSurfaceStatus, type DetachedSurfaceStatusProps, type DetachedSurfaceStatusTone, type DockLayoutControlBinding, type DockLayoutControlBindingOptions, DockLayoutMenu, type DockLayoutMenuPanel, type DockLayoutMenuProps, DockTabAction, type DockTabActionProps, DockTabFrame, type DockTabFrameProps, DockTabIcon, type DockTabIconProps, DockTabStatusSummary, type DockTabStatusSummaryItem, type DockTabStatusSummaryProps, type DockTabStatusTone, DockTabTitle, type DockTabTitleProps, FloatingMenu, type FloatingMenuAnchor, type FloatingMenuPoint, type FloatingMenuProps, type LiveTabPlacement, type LiveTabPlacementSource, type LiveTabTitleSource, type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelEmptyState, type PanelEmptyStateProps, PanelSurface, type PanelSurfaceProps, type PersistentSizeStorage, type PersistentSizeStore, type PersistentSizeStoreOptions, type PersistentSizeUpdate, type PointerDragFinishReason, type PointerDragSessionOptions, type PointerReorderFinishReason, type PointerReorderSession, type PointerReorderSessionOptions, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, SurfacePlaceholder, type SurfacePlaceholderProps, SurfaceRegion, type SurfaceRegionProps, type TabCloseInteractions, type TabCloseInteractionsOptions, type TabPinnedStateSource, type ThresholdPointerDragFinishReason, type ThresholdPointerDragSession, type ThresholdPointerDragSessionOptions, applyAnchoredResizeDelta, beginAnchoredResize, createPersistentSizeStore, hashSlotHue, installPointerDragSession, installPointerReorderSession, installThresholdPointerDragSession, isSlotDebugEnabled, useDockLayoutControlBinding, useLiveTabPlacement, useLiveTabTitle, useLocalSize, usePersistentSizeStore, useTabCloseInteractions, useTabPinnedState };
+export { type AnchoredResizeDirection, AnchoredResizeHandle, type AnchoredResizeHandleProps, type AnchoredResizeSession, DetachedPanelBoundary, type DetachedPanelBoundaryProps, DetachedSurfaceFrame, type DetachedSurfaceFrameProps, DetachedSurfaceStatus, type DetachedSurfaceStatusProps, type DetachedSurfaceStatusTone, type DockLayoutControlBinding, type DockLayoutControlBindingOptions, DockLayoutMenu, type DockLayoutMenuPanel, type DockLayoutMenuProps, DockTabAction, type DockTabActionProps, DockTabFrame, type DockTabFrameProps, DockTabIcon, type DockTabIconProps, DockTabStatusSummary, type DockTabStatusSummaryItem, type DockTabStatusSummaryProps, type DockTabStatusTone, DockTabTitle, type DockTabTitleProps, FloatingMenu, type FloatingMenuAnchor, type FloatingMenuPoint, type FloatingMenuProps, type LiveTabPlacement, type LiveTabPlacementSource, type LiveTabTitleSource, OWNED_INTERACTION_SURFACE_SELECTOR, type OutsideDismissEventTarget, type OutsideDismissLifecycleOptions, type OutsideDismissReason, type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelEmptyState, type PanelEmptyStateProps, PanelSurface, type PanelSurfaceProps, type PersistentSizeStorage, type PersistentSizeStore, type PersistentSizeStoreOptions, type PersistentSizeUpdate, type PointerDragFinishReason, type PointerDragSessionOptions, type PointerReorderFinishReason, type PointerReorderSession, type PointerReorderSessionOptions, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, SurfacePlaceholder, type SurfacePlaceholderProps, SurfaceRegion, type SurfaceRegionProps, type TabCloseInteractions, type TabCloseInteractionsOptions, type TabPinnedStateSource, type ThresholdPointerDragFinishReason, type ThresholdPointerDragSession, type ThresholdPointerDragSessionOptions, applyAnchoredResizeDelta, beginAnchoredResize, createPersistentSizeStore, hashSlotHue, installOutsideDismissLifecycle, installPointerDragSession, installPointerReorderSession, installThresholdPointerDragSession, isDismissExemptInteractionTarget, isSlotDebugEnabled, useDockLayoutControlBinding, useLiveTabPlacement, useLiveTabTitle, useLocalSize, usePersistentSizeStore, useTabCloseInteractions, useTabPinnedState };

package/dist/react.js

@@ -1544,6 +1544,170 @@ var DockTabStatusSummary = forwardRef2(function DockTabStatusSummary2({ classNam
 });
 DockTabStatusSummary.displayName = "DockTabStatusSummary";
 
+// src/dismiss-exemption.ts
+var OWNED_INTERACTION_SURFACE_SELECTOR = "[data-fx-interaction-scope]";
+function isDismissExemptInteractionTarget(target, additionalSelectors = []) {
+  if (!target) return false;
+  for (const selector of [OWNED_INTERACTION_SURFACE_SELECTOR, ...additionalSelectors]) {
+    try {
+      if (target.closest(selector) !== null) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+
+// src/outside-dismiss.ts
+function installOutsideDismissLifecycle(options) {
+  const documentTarget = options.documentTarget ?? (typeof document === "undefined" ? void 0 : document);
+  const windowTarget = options.windowTarget ?? (typeof window === "undefined" ? void 0 : window);
+  const getActiveElement = options.getActiveElement ?? (() => typeof document === "undefined" ? null : document.activeElement);
+  const requestFrame = options.requestFrame ?? (typeof requestAnimationFrame === "undefined" ? void 0 : requestAnimationFrame.bind(globalThis));
+  const cancelFrame = options.cancelFrame ?? (typeof cancelAnimationFrame === "undefined" ? void 0 : cancelAnimationFrame.bind(globalThis));
+  if (!documentTarget || !windowTarget) return () => {
+  };
+  let disposed = false;
+  let dismissRequested = false;
+  let frameHandle = null;
+  let frameGeneration = 0;
+  const removeListener = (target, type, listener, options2) => {
+    try {
+      target.removeEventListener(type, listener, options2);
+    } catch {
+    }
+  };
+  const disposition = (target) => {
+    if (disposed) return "inactive";
+    let open;
+    try {
+      open = options.isOpen();
+    } catch {
+      return "inactive";
+    }
+    if (!open) {
+      dismissRequested = false;
+      return "inactive";
+    }
+    if (dismissRequested) return "inactive";
+    try {
+      if (options.isPinned()) return "inactive";
+    } catch {
+      return "inactive";
+    }
+    if (target) {
+      try {
+        if (options.containsTarget(target)) return "contained";
+      } catch {
+        return "inactive";
+      }
+    }
+    try {
+      if (options.isDismissExempt(target)) return "exempt";
+    } catch {
+      return "inactive";
+    }
+    return "outside";
+  };
+  const requestDismiss = (reason) => {
+    if (dismissRequested || disposed) return;
+    dismissRequested = true;
+    try {
+      options.dismiss(reason);
+    } catch {
+      dismissRequested = false;
+    }
+  };
+  const onPointerDown = (event) => {
+    const target = event.target;
+    const result = disposition(target);
+    if (result === "contained" && target) {
+      try {
+        options.onContainedPointerDown?.(target);
+      } catch {
+      }
+      return;
+    }
+    if (result === "outside") requestDismiss("pointer");
+  };
+  const onFocusIn = (event) => {
+    if (disposition(event.target) === "outside") {
+      requestDismiss("focus");
+    }
+  };
+  const onWindowBlur = () => {
+    if (disposed || frameHandle !== null || !requestFrame) return;
+    let open;
+    try {
+      open = options.isOpen();
+    } catch {
+      return;
+    }
+    if (!open) {
+      dismissRequested = false;
+      return;
+    }
+    const generation = ++frameGeneration;
+    let callbackRan = false;
+    let handle;
+    try {
+      handle = requestFrame(() => {
+        callbackRan = true;
+        if (disposed || generation !== frameGeneration) return;
+        frameHandle = null;
+        let active;
+        try {
+          active = getActiveElement();
+        } catch {
+          return;
+        }
+        if (!active || active.tagName !== "IFRAME") return;
+        if (disposition(active) === "outside") requestDismiss("iframe-focus");
+      });
+    } catch {
+      return;
+    }
+    if (callbackRan || disposed || generation !== frameGeneration) {
+      try {
+        cancelFrame?.(handle);
+      } catch {
+      }
+      return;
+    }
+    frameHandle = handle;
+  };
+  let pointerRegistered = false;
+  let focusRegistered = false;
+  let blurRegistered = false;
+  try {
+    documentTarget.addEventListener("pointerdown", onPointerDown, true);
+    pointerRegistered = true;
+    documentTarget.addEventListener("focusin", onFocusIn);
+    focusRegistered = true;
+    windowTarget.addEventListener("blur", onWindowBlur);
+    blurRegistered = true;
+  } catch {
+    if (pointerRegistered) removeListener(documentTarget, "pointerdown", onPointerDown, true);
+    if (focusRegistered) removeListener(documentTarget, "focusin", onFocusIn);
+    if (blurRegistered) removeListener(windowTarget, "blur", onWindowBlur);
+    disposed = true;
+  }
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    frameGeneration++;
+    if (frameHandle !== null) {
+      try {
+        cancelFrame?.(frameHandle);
+      } catch {
+      }
+      frameHandle = null;
+    }
+    if (pointerRegistered) removeListener(documentTarget, "pointerdown", onPointerDown, true);
+    if (focusRegistered) removeListener(documentTarget, "focusin", onFocusIn);
+    if (blurRegistered) removeListener(windowTarget, "blur", onWindowBlur);
+  };
+}
+
 // src/panel.tsx
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 function PanelEmptyState({
@@ -1905,6 +2069,7 @@ export {
   DockTabStatusSummary,
   DockTabTitle,
   FloatingMenu,
+  OWNED_INTERACTION_SURFACE_SELECTOR,
   PanelEmptyState,
   PanelSurface,
   ResizeHandle,
@@ -1916,9 +2081,11 @@ export {
   beginAnchoredResize,
   createPersistentSizeStore,
   hashSlotHue,
+  installOutsideDismissLifecycle,
   installPointerDragSession,
   installPointerReorderSession,
   installThresholdPointerDragSession,
+  isDismissExemptInteractionTarget,
   isSlotDebugEnabled,
   useDockLayoutControlBinding,
   useLiveTabPlacement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",