asma-ui-core 3.110.0 → 3.112.0

package/dist/src/components/inputs/input-field/StyledInputField.d.ts

@@ -44,7 +44,10 @@ export interface StyledInputFieldProps {
     expandHelperText?: boolean;
     /** Character limit; also readable from `slotProps.htmlInput.maxLength`. */
     maxLength?: number;
-    /** Shows the count against `maxLength` as the user types, for free text with a limit. */
+    /**
+     * Count against `maxLength`, on by default whenever the field has a limit (WID-12). Pass `false`
+     * for a fixed format such as a postal code, whose length the label or hint already states.
+     */
     counter?: boolean;
     /** Language of the counter text. */
     locale?: UiCoreLocale;

package/dist/src/helpers/CharacterCounter.d.ts

@@ -11,6 +11,7 @@ export interface CharacterCounterProps {
 }
 /**
  * The count of a free-text field with a character limit, such as *12 av 100 tegn* (field width
- * pattern WID-2, Q12), so typed text is never cut without notice.
+ * pattern WID-2, WID-12), so typed text is never cut without notice.
+ * @figmaNode wXrXt5uKNNzV2DnQCgyYZH#45907-218317
  */
 export declare const CharacterCounter: ({ id, length, limit, locale, className }: CharacterCounterProps) => JSX.Element;

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

@@ -67,6 +67,17 @@ declare global {
  * {@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;
+/**
+ * Declares "overlays rendered below me in the React tree are nested inside me", which is what makes
+ * one Back press close the inner one first (BACK-2).
+ *
+ * Needed because an overlay is usually portalled out of its parent's DOM subtree, so DOM
+ * containment cannot carry the relationship — only the React tree still knows it. Wrap your
+ * surface's children in `<OverlayBackOwnerContext.Provider value={yourOwnerRef}>`, passing the same
+ * ref you gave {@link useBackCloses} as `ownerRef`. Every ui-core overlay already does this; an app
+ * wiring up an overlay of its own should too, otherwise a ui-core overlay opened inside it is
+ * ordered by registration time alone and Back may close the outer surface first.
+ */
 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
@@ -83,6 +94,16 @@ export declare function requestCloseTopOverlayBack(event?: Event): false | void
 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;
+/**
+ * `true` while the history adapter is holding a route change, waiting for the top overlay to close
+ * before it navigates (design-plan rule 1 — `push` is deferred, not cancelled).
+ *
+ * A surface that is *meant* to outlive navigation — the shell-level docked minimizable panels — tells
+ * the adapter so by returning `false` from its closer in this window. The adapter reads that as
+ * fail-open: it strips the guard, runs the navigation, and leaves the surface open. Anything that
+ * should close on navigation simply ignores this and closes as usual.
+ */
+export declare function isOverlayBackNavigationPending(): boolean;
 /** Native close-watcher events are part of the feature and must respect the host kill switch. */
 export declare function isOverlayBackEnabled(): boolean;
 /**
@@ -92,10 +113,34 @@ export declare function isOverlayBackEnabled(): boolean;
  * `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.
+ *
+ * Pass `ownerRef` wherever the surface has a stable root element: it is what places the entry
+ * relative to a nested child (`isOwnedBy`) and to an open native modal
+ * ({@link isCoveredByOpenModalDialog}).
  */
-export declare function useBackCloses({ active, requestClose, ownerRef, }: {
+export interface UseBackClosesOptions {
+    /**
+     * Register while `true`, unregister while `false` — normally the surface's own "is showing"
+     * state. Keep it off for a state that is visible but not dismissable as an overlay (a minimized
+     * panel), so Back reaches whatever is behind it instead.
+     */
     active: boolean;
+    /**
+     * The surface's existing close path — the same function its ✕ or Escape already calls. Never a
+     * synthetic key event. Return nothing for a plain dismissal; return a Promise to latch the
+     * surface while an async close runs (Back does nothing until it settles); return `false` to
+     * refuse this press, which is also how a surface that must survive navigation opts out of the
+     * adapter's deferred route change.
+     */
     requestClose: OverlayBackRequestClose;
+    /**
+     * The surface's own root element — the one that is actually painted on top. Pass it wherever
+     * there is one. It is what lets Back order this surface against an overlay nested inside it and
+     * against an open native modal `<dialog>`; without it the entry is ordered by registration
+     * time alone. For a surface promoted into the top layer via the Popover API, this must be the
+     * element carrying the `popover` attribute, not a wrapper around it.
+     */
     ownerRef?: RefObject<Element | null>;
-}): void;
+}
+export declare function useBackCloses({ active, requestClose, ownerRef }: UseBackClosesOptions): void;
 export {};

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

@@ -65,6 +65,12 @@ export declare function registerOpenModalDialog(dialog: HTMLDialogElement): () =
  * modal is open. Stale entries (a dialog torn down without its cleanup running) are skipped rather
  * than trusted, so a missed unregister can never strand an overlay in a detached subtree.
  */
+/**
+ * The newest connected modal `<dialog>` for which `accept` returns true.
+ * `getTopmostOpenModalDialog` is the `dialog.open` case. Back arbitration passes a wider accept,
+ * because a forced native close sets `open` to false before React unregisters the dialog.
+ */
+export declare function findTopmostConnectedModalDialog(accept: (dialog: HTMLDialogElement) => boolean): HTMLDialogElement | undefined;
 export declare function getTopmostOpenModalDialog(): HTMLDialogElement | undefined;
 /**
  * Reactive {@link getTopmostOpenModalDialog} — re-renders the caller when a modal `<dialog>` opens or

package/dist/src/index.d.ts

@@ -59,4 +59,5 @@ export * from './components/feedback/minimizable-dialog';
 export * from './components/custom/pathfinder-card/PathfinderCard';
 export * from './hooks/usePopupState';
 export * from './hooks/useRouteHeadingFocus';
+export { useBackCloses, OverlayBackOwnerContext, type OverlayBackRequestClose, type UseBackClosesOptions, } from './hooks/useBackCloses.hook';
 export { Paper, ClickAwayListener, Avatar, Skeleton, Container, Stack, FormLabel, Fade, Popper, } from './components/mui-compat';

package/package.json

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