asma-ui-core 3.108.1 → 3.108.3

package/dist/src/hooks/useBackCloses.hook.d.ts

@@ -0,0 +1,101 @@
+import { RefObject } from 'react';
+/**
+ * ASMA-8471 — native Back closes the top ui-core overlay through its own close path.
+ *
+ * This module owns ONLY the overlay side of the contract: a LIFO registry of open overlays plus the
+ * arbitration that decides which one a Back press (or a native dialog `cancel`/`close`) acts on. It
+ * never touches browser history — no `pushState`, `back()` or `go()` — that lives in
+ * `asma-core-helpers`' `getHistory()` adapter (PR #51, ASMA-8476), published at
+ * `window.__ASMA__SHELL__.overlayBack = { v, enabled, register }`. When that adapter is live (`v ===
+ * 1` and `register` is a function) this module registers ONE long-lived closer with it as soon as the
+ * stack goes from empty to non-empty, and unregisters it once the stack drains back to empty — see
+ * {@link registerOverlayBackCloser}. When the adapter is absent, or on a version this module doesn't
+ * speak, it runs registry-only and never touches `window.__ASMA__SHELL__` at all.
+ *
+ * **Window-scoped, not module-scoped** — same reasoning as `useTopLayer.hook.ts`'s
+ * `__asmaOpenModalDialogRegistry__`: a normal (non-`KERNEL_EXTERNAL`) build instantiates this module
+ * once per micro-frontend bundle, so a module-level array would give every bundle its own stack and
+ * "close only the top" would silently become "close only MY top" — and TWO bundles would each try to
+ * register their own adapter closer. `document.defaultView` (or `rawWindow` under the `asma-micro-app`
+ * sandbox) is the one object every bundle in the page shares, so the adapter registration state lives
+ * there too.
+ */
+export declare const OVERLAY_BACK_REGISTRY_VERSION = 1;
+/** Returns nothing: no latch, a repeated Back repeats the dismissal. Returns a Promise: the entry
+ *  latches until it settles, and Back on a latched top does nothing (see `requestCloseTopOverlayBack`). */
+export type OverlayBackRequestClose = (event?: Event) => false | void | Promise<unknown>;
+interface OverlayBackEntry {
+    requestClose: OverlayBackRequestClose;
+    pending: boolean;
+    owner: Element | null;
+    parentOwner: Element | null;
+    ownerRef?: RefObject<Element | null>;
+    parentOwnerRef?: RefObject<Element | null>;
+}
+interface OverlayBackAdapterState {
+    /** The adapter's own unregister for our one long-lived closer, once `register()` has been called. */
+    unregister: (() => void) | null;
+}
+interface OverlayBackRegistry {
+    version: number;
+    entries: OverlayBackEntry[];
+    adapter: OverlayBackAdapterState;
+}
+/** The `asma-core-helpers` contract (PR #51, ASMA-8476): `register` hands it the current top's close
+ *  function and gets back that registration's unregister. Absent, or `v` other than `1`, means no
+ *  history adapter is live. */
+interface OverlayBackAdapter {
+    v?: number;
+    enabled?: boolean;
+    pendingNavigation?: boolean;
+    register?: (requestClose: OverlayBackRequestClose) => () => void;
+    continuePendingNavigation?: () => void;
+    failOpenPendingNavigation?: () => void;
+}
+declare global {
+    interface Window {
+        rawWindow?: Window;
+        __asmaOverlayBackRegistry__?: OverlayBackRegistry;
+        __ASMA__SHELL__?: {
+            overlayBack?: OverlayBackAdapter;
+        };
+    }
+}
+/**
+ * Push a LIFO entry onto the overlay-back stack. The returned unregister must run when the overlay
+ * stops being eligible to receive Back (closes, or is no longer the active layer) — see
+ * {@link useBackCloses} for the React lifecycle wrapper every consumer actually uses.
+ */
+export declare function registerOverlayBackCloser(requestClose: OverlayBackRequestClose, owner?: Element | null, parentOwner?: Element | null, ownerRef?: RefObject<Element | null>, parentOwnerRef?: RefObject<Element | null>): () => void;
+export declare const OverlayBackOwnerContext: import('react').Context<RefObject<Element | null> | undefined>;
+/**
+ * Act on the topmost registered overlay, honouring the close contract's latch: a top entry whose
+ * previous `requestClose` returned a Promise that hasn't settled yet is skipped entirely (one
+ * documented dead press), never passed through to the next entry down — BACK-2 is "one press closes
+ * one layer", not "closes the nearest dismissible one".
+ *
+ * `StyledDialog`'s native `cancel`/`close` arbitration calls this directly, and it is exactly what the
+ * one closer registered with the history adapter (`asma-core-helpers`, a separate package) delegates
+ * to on an owned traversal.
+ */
+export declare function requestCloseTopOverlayBack(event?: Event): false | void | Promise<unknown>;
+/** Number of overlays currently registered. */
+export declare function getOverlayBackStackSize(): number;
+/** `true` when a live `asma-core-helpers` history adapter (PAT-002) has published `overlayBack.v === 1`. */
+export declare function hasOverlayBackAdapter(): boolean;
+/** Native close-watcher events are part of the feature and must respect the host kill switch. */
+export declare function isOverlayBackEnabled(): boolean;
+/**
+ * Register a surface onto the overlay-back stack while `active`, so native Back closes it through its
+ * own `requestClose` — see {@link requestCloseTopOverlayBack} for the arbitration. This hook never
+ * installs a `popstate`/history listener of its own, with or without a live adapter — that would race
+ * `asma-core-helpers`' own listener (CON-002/CON-009) and duplicate work the adapter already owns. The
+ * adapter registration itself (see {@link registerOverlayBackCloser}) is driven purely by the stack's
+ * empty/non-empty transitions, not by this hook.
+ */
+export declare function useBackCloses({ active, requestClose, ownerRef, }: {
+    active: boolean;
+    requestClose: OverlayBackRequestClose;
+    ownerRef?: RefObject<Element | null>;
+}): void;
+export {};

package/dist/src/hooks/useBackCloses.hook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "3.108.1",
+    "version": "3.108.3",
     "type": "module",
     "sideEffects": [
         "**/*.css",

package/dist/datetime/hooks/useBackNavigationClose.hook.js

@@ -1,10 +0,0 @@
-import { useEffect as r } from "react";
-var o = ({ open: t, onClose: e }) => (r(() => {
-  if (t)
-    return window.history.pushState({ modal: !0 }, ""), window.addEventListener("popstate", e), () => {
-      window.removeEventListener("popstate", e), window.history.state?.modal && window.history.back();
-    };
-}, [t]), null);
-export {
-  o as useBackNavigationClose
-};

package/dist/src/datetime/hooks/useBackNavigationClose.hook.d.ts

@@ -1,4 +0,0 @@
-export declare const useBackNavigationClose: ({ open, onClose }: {
-    open: boolean;
-    onClose: () => void;
-}) => null;