@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/hooks/useAnnounceRenderedText.js

@@ -32,7 +32,7 @@
  * (see `FieldStatus` and `TimeInput`): a live region that mounts together
  * with its content is not reliably announced.
  *
- * Content hidden from the accessibility tree with `aria-hidden` is excluded,
+ * Content hidden with `aria-hidden` or `hidden` is excluded,
  * so a decorative icon stays out of the announcement exactly as it stays out
  * of what a screen reader reads. An `aria-label` renaming a descendant is NOT
  * substituted — the region speaks the rendered text.
@@ -42,17 +42,40 @@
  * adding it there would ship a new public hook without `spec:AST-002`
  * admission. Import it by path from inside the package.
  */
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useAnnounce } from "./useAnnounce.js";
+import { useIsHydrating } from "./useIsHydrating.js";
+const LIVE_CONTAINER = '[role="log"], [role="status"], [role="alert"], [aria-live="polite"], [aria-live="assertive"]';
+const HIDDEN = '[aria-hidden="true"], [hidden]';
+const BLOCKS = 'p, div, li, br, h1, h2, h3, h4, h5, h6';
 
+/**
+ * Each child element's rendered text as its own block, joined by spaces. Text
+ * placed directly in the element, beside its child elements, counts as a block
+ * too (a status bar is an icon followed by its bare message).
+ */
+function blockText(element) {
+  return Array.from(element.childNodes).map(child => {
+    if (child.nodeType === Node.TEXT_NODE) {
+      return (child.textContent ?? '').replace(/\s+/g, ' ').trim();
+    }
+    // By node type, not `instanceof`: an element from another document's
+    // window (a portal into a same-origin iframe) fails this window's
+    // constructor checks.
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      const part = child;
+      return part.matches(HIDDEN) ? '' : renderedText(part);
+    }
+    return '';
+  }).filter(part => part !== '').join(' ');
+}
 /** The rendered text an assistive technology would read from `element`. */
-function renderedText(element) {
+export function renderedText(element) {
   // Clone so removing the hidden parts cannot disturb what is on screen. The
   // clone is never attached to the document.
   const copy = element.cloneNode(true);
-  for (const hidden of copy.querySelectorAll('[aria-hidden="true"]')) {
-    hidden.remove();
-  }
+  copy.querySelectorAll(HIDDEN).forEach(node => node.remove());
+  copy.querySelectorAll(BLOCKS).forEach(node => node.after(' ')); // blocks apart
   return (copy.textContent ?? '').replace(/\s+/g, ' ').trim();
 }
 
@@ -76,9 +99,17 @@ function renderedText(element) {
  * useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
  * ```
  */
-export function useAnnounceRenderedText(ref, isShown, occasion) {
+export function useAnnounceRenderedText(ref, isShown, occasion, {
+  skipFirstRender = false,
+  politeness = 'polite'
+} = {}) {
   const announce = useAnnounce();
   const spokenRef = useRef(null);
+  const isHydrating = useIsHydrating();
+  // Captured once: an owner rendered before the document finished loading, or
+  // hydrated from server HTML, is part of the page the person arrived at.
+  const [renderedWithPage] = useState(() => isHydrating || document.readyState !== 'complete');
+  const isFirstRunRef = useRef(true);
 
   // Deliberately no dependency array. The text lives in the DOM, so there is
   // no React value to depend on that changes when it does — a caller can
@@ -86,15 +117,20 @@ export function useAnnounceRenderedText(ref, isShown, occasion) {
   // one element's text per render is cheap, and the dedupe below makes every
   // render after the first a no-op.
   useEffect(() => {
-    if (!isShown) {
+    const isFirstRun = isFirstRunRef.current;
+    isFirstRunRef.current = false;
+    const element = ref.current;
+    if (!isShown || element?.closest(HIDDEN) || element?.checkVisibility?.() === false) {
       spokenRef.current = null;
       return;
     }
-    const element = ref.current;
     if (!element) {
       return;
     }
-    const text = renderedText(element);
+    if (skipFirstRender && element.parentElement?.closest(LIVE_CONTAINER)) {
+      return;
+    }
+    const text = skipFirstRender ? blockText(element) : renderedText(element);
     if (text === '') {
       // Nothing readable on screen either, so there is no announcement that
       // would match what the sighted user is seeing.
@@ -105,6 +141,11 @@ export function useAnnounceRenderedText(ref, isShown, occasion) {
       return;
     }
     spokenRef.current = spoken;
-    announce(text);
+    const isPageLoad = isFirstRun && renderedWithPage || document.readyState !== 'complete';
+    if (skipFirstRender && isPageLoad) {
+      // Part of the page the person arrived at: remember it, say nothing.
+      return;
+    }
+    announce(text, politeness);
   });
 }

package/dist/hooks/useBusyAnnouncement.d.ts

@@ -9,14 +9,18 @@
  * The busy Spinner inside a control is decorative (hidden, no live role); the
  * control announces its busy state instead (`spec:AST-086` FR8), once per busy
  * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
- * re-arms it. While a native modal is open, the body-level channel is not
- * exposed, so a control inside it announces through one persistent polite
- * region in that dialog, inserted empty and filled a frame later (Platform
- * support, FR3).
+ * re-arms it. The returned function is called by an owner announcing the
+ * busy operation's outcome: a busy start not yet announced is dropped, so it
+ * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not
+ * exposed, so a control inside it announces through that dialog's polite
+ * container, the one `useAnnounce` uses for every message from inside the
+ * modal (FR14), inserted empty and filled a frame later (FR3); the control's
+ * own element locates the modal, so a busy start inside a native modal an app
+ * renders without Astryx is heard inside it too.
  *
  * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
  * this is a shared implementation detail of Astryx's busy controls.
  */
 import { type RefObject } from 'react';
-export declare function useBusyAnnouncement(isBusy: boolean, message: string, elementRef: RefObject<Element | null>): void;
+export declare function useBusyAnnouncement(isBusy: boolean, message: string, elementRef: RefObject<Element | null>): () => void;
 //# sourceMappingURL=useBusyAnnouncement.d.ts.map

package/dist/hooks/useBusyAnnouncement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBusyAnnouncement.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusyAnnouncement.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AA+CxD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GACpC,IAAI,CAwBN"}
+{"version":3,"file":"useBusyAnnouncement.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusyAnnouncement.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GACpC,MAAM,IAAI,CAmEZ"}

package/dist/hooks/useBusyAnnouncement.js

@@ -13,59 +13,34 @@
  * The busy Spinner inside a control is decorative (hidden, no live role); the
  * control announces its busy state instead (`spec:AST-086` FR8), once per busy
  * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
- * re-arms it. While a native modal is open, the body-level channel is not
- * exposed, so a control inside it announces through one persistent polite
- * region in that dialog, inserted empty and filled a frame later (Platform
- * support, FR3).
+ * re-arms it. The returned function is called by an owner announcing the
+ * busy operation's outcome: a busy start not yet announced is dropped, so it
+ * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not
+ * exposed, so a control inside it announces through that dialog's polite
+ * container, the one `useAnnounce` uses for every message from inside the
+ * modal (FR14), inserted empty and filled a frame later (FR3); the control's
+ * own element locates the modal, so a busy start inside a native modal an app
+ * renders without Astryx is heard inside it too.
  *
  * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
  * this is a shared implementation detail of Astryx's busy controls.
  */
-import { useEffect, useRef } from 'react';
-import { useAnnounce } from "./useAnnounce.js";
-const REGION_ATTR = 'data-astryx-modal-busy-region';
-const VISUALLY_HIDDEN_CSS = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;' + 'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
-const CLEAR_DELAY_MS = 2000; // Matches useAnnounce.
-
-// The pending write and clear of each in-dialog region; a new write cancels
-// them so an earlier message can neither land late nor clear a later one.
-const pendingByRegion = new WeakMap();
-function announceInModal(dialog, message) {
-  let region = dialog.querySelector(`:scope > [${REGION_ATTR}]`);
-  if (region == null) {
-    region = document.createElement('div');
-    region.setAttribute(REGION_ATTR, '');
-    region.setAttribute('role', 'status');
-    region.setAttribute('aria-live', 'polite');
-    region.setAttribute('aria-atomic', 'true');
-    region.style.cssText = VISUALLY_HIDDEN_CSS;
-    dialog.appendChild(region);
-  }
-  const target = region;
-  const previous = pendingByRegion.get(target);
-  if (previous != null) {
-    cancelAnimationFrame(previous.frame);
-    clearTimeout(previous.timer);
-  }
-  target.textContent = '';
-  const pending = {
-    frame: 0
-  };
-  pending.frame = requestAnimationFrame(() => {
-    target.textContent = message;
-    pending.timer = setTimeout(() => {
-      target.textContent = '';
-      pendingByRegion.delete(target);
-    }, CLEAR_DELAY_MS);
-  });
-  pendingByRegion.set(target, pending);
-}
+import { useCallback, useEffect, useRef } from 'react';
+import { announceInModal, enclosingModalDialog, takeJoinedAnnouncement, useAnnounce, withdrawFromModalPending, withdrawPendingAnnouncement } from "./useAnnounce.js";
 export function useBusyAnnouncement(isBusy, message, elementRef) {
   const announce = useAnnounce();
   const hasAnnouncedRef = useRef(false);
+  const frameRef = useRef(null);
+  // This busy start's share of the shared channel's pending text, until it
+  // settles.
+  const channelMessageRef = useRef(null);
+  // Or its write inside a modal's container, until it settles.
+  const modalMessageRef = useRef(null);
   useEffect(() => {
     if (!isBusy) {
       hasAnnouncedRef.current = false;
+      channelMessageRef.current = null;
+      modalMessageRef.current = null;
       return;
     }
     if (hasAnnouncedRef.current) {
@@ -74,14 +49,51 @@ export function useBusyAnnouncement(isBusy, message, elementRef) {
     // Choose the route a frame later: a Dialog opening in the same commit
     // calls showModal() in its own Effect, which runs after this one.
     const frame = requestAnimationFrame(() => {
+      frameRef.current = null;
       hasAnnouncedRef.current = true;
-      const dialog = elementRef.current?.closest('dialog');
-      if (dialog?.open && dialog.matches(':modal')) {
+      // The nearest open native modal around the control's own element,
+      // Astryx or app-rendered, so a busy start inside a modal an app renders
+      // without Astryx is still heard inside it (`spec:AST-086` FR14); the
+      // shared `useAnnounce` route otherwise, which itself follows the
+      // nearest Astryx modal around this hook's caller.
+      const dialog = enclosingModalDialog(elementRef.current);
+      if (dialog != null) {
         announceInModal(dialog, message);
+        modalMessageRef.current = {
+          dialog,
+          message
+        };
       } else {
         announce(message, 'polite');
+        channelMessageRef.current = takeJoinedAnnouncement();
       }
     });
-    return () => cancelAnimationFrame(frame);
+    frameRef.current = frame;
+    return () => {
+      cancelAnimationFrame(frame);
+      frameRef.current = null;
+    };
   }, [announce, elementRef, isBusy, message]);
+  return useCallback(() => {
+    if (frameRef.current != null) {
+      cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+      // Still busy until the settled state commits; do not schedule again.
+      hasAnnouncedRef.current = true;
+    }
+    // Written to the channel, or inside the modal, but not yet exposed:
+    // withdraw it too.
+    if (channelMessageRef.current != null) {
+      withdrawPendingAnnouncement(channelMessageRef.current, 'polite');
+      channelMessageRef.current = null;
+    }
+    if (modalMessageRef.current != null) {
+      const {
+        dialog,
+        message
+      } = modalMessageRef.current;
+      withdrawFromModalPending(dialog, message, 'polite');
+      modalMessageRef.current = null;
+    }
+  }, []);
 }

package/dist/hooks/useFocusTrap.d.ts

@@ -54,7 +54,7 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
  * Hook for trapping focus within a container element.
  *
  * Implements the WAI-ARIA dialog focus trap pattern:
- * - Listens to focus events on the document
+ * - Listens to focus events on the container's document
  * - Redirects focus back into the container if it escapes
  * - Handles both Tab and Shift+Tab navigation
  * - Restores focus to the element that was focused before activation when the

package/dist/hooks/useFocusTrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA0CD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAkQvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CA8QvB"}

package/dist/hooks/useFocusTrap.js

@@ -98,6 +98,26 @@ export function getFocusableElements(container) {
   return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter(isVisiblyFocusable);
 }
 
+/**
+ * The document a trap lives in: its container's. An app that renders into a
+ * same-origin iframe or a Document Picture-in-Picture window through a portal
+ * puts the trap in that window's document, whose key presses and focus
+ * changes never reach this module's global `document`.
+ */
+function trapDocument(container) {
+  return container?.ownerDocument ?? document;
+}
+
+/**
+ * `instanceof HTMLElement`, asked of the node's own window: an element of a
+ * second document is an instance of that window's `HTMLElement`, not of this
+ * one's.
+ */
+function isHTMLElement(node) {
+  const view = node?.ownerDocument?.defaultView;
+  return view != null && node instanceof view.HTMLElement;
+}
+
 /**
  * Attempt to focus an element. Returns true if focus was successful.
  */
@@ -107,7 +127,7 @@ function attemptFocus(element) {
   } catch {
     // Some elements may throw on focus
   }
-  return document.activeElement === element;
+  return element.ownerDocument.activeElement === element;
 }
 
 /**
@@ -150,7 +170,7 @@ function focusLastDescendant(container) {
  * Hook for trapping focus within a container element.
  *
  * Implements the WAI-ARIA dialog focus trap pattern:
- * - Listens to focus events on the document
+ * - Listens to focus events on the container's document
  * - Redirects focus back into the container if it escapes
  * - Handles both Tab and Shift+Tab navigation
  * - Restores focus to the element that was focused before activation when the
@@ -249,28 +269,30 @@ export function useFocusTrap(options) {
     if (!isActive) {
       return;
     }
-    const previouslyFocused = document.activeElement;
+
     // Snapshot the container now; by cleanup it may be detached or unmounted.
     const container = containerRef.current;
+    const doc = trapDocument(container);
+    const previouslyFocused = doc.activeElement;
 
     // Whether focus ever entered the trap container while it was active.
     // Initialized from the current active element in case focus was already
     // inside at activation (e.g. a programmatic focus before the effect ran).
-    let hadFocusInside = container != null && container.contains(document.activeElement);
+    let hadFocusInside = container != null && container.contains(doc.activeElement);
     const markFocusInside = event => {
       const target = event.target;
       if (target != null && containerRef.current?.contains(target)) {
         hadFocusInside = true;
       }
     };
-    document.addEventListener('focusin', markFocusInside, true);
+    doc.addEventListener('focusin', markFocusInside, true);
     return () => {
-      document.removeEventListener('focusin', markFocusInside, true);
+      doc.removeEventListener('focusin', markFocusInside, true);
       if (!hadFocusInside) {
         return;
       }
-      const active = document.activeElement;
-      const focusWasLost = active == null || active === document.body || active === document.documentElement || container != null && container.contains(active);
+      const active = doc.activeElement;
+      const focusWasLost = active == null || active === doc.body || active === doc.documentElement || container != null && container.contains(active);
       if (!focusWasLost) {
         return;
       }
@@ -288,6 +310,7 @@ export function useFocusTrap(options) {
     if (!isActive) {
       return;
     }
+    const doc = trapDocument(containerRef.current);
     const handleFocus = event => {
       const container = containerRef.current;
       if (!container) {
@@ -303,15 +326,15 @@ export function useFocusTrap(options) {
 
         // If we're back at the same element (Shift+Tab from first element),
         // try focusing the last element instead
-        if (focusedFirst && lastFocusRef.current === document.activeElement) {
+        if (focusedFirst && lastFocusRef.current === doc.activeElement) {
           focusLastDescendant(container);
-        } else if (!focusedFirst && lastFocusRef.current instanceof HTMLElement && container.contains(lastFocusRef.current)) {
+        } else if (!focusedFirst && isHTMLElement(lastFocusRef.current) && container.contains(lastFocusRef.current)) {
           // A modal surface may intentionally have no tabbable controls and
           // place initial focus on a tabIndex={-1} heading or panel. Preserve
           // that programmatic focus target instead of letting Tab escape.
           attemptFocus(lastFocusRef.current);
         }
-        lastFocusRef.current = document.activeElement;
+        lastFocusRef.current = doc.activeElement;
       }
       // If focus escaped via mouse click, don't redirect - let light dismiss handle it
 
@@ -320,9 +343,9 @@ export function useFocusTrap(options) {
     };
 
     // Use capture phase to intercept focus before it settles
-    document.addEventListener('focus', handleFocus, true);
+    doc.addEventListener('focus', handleFocus, true);
     return () => {
-      document.removeEventListener('focus', handleFocus, true);
+      doc.removeEventListener('focus', handleFocus, true);
     };
   }, [isActive]);
 
@@ -339,23 +362,31 @@ export function useFocusTrap(options) {
     if (!isActive) {
       return;
     }
+    const doc = trapDocument(containerRef.current);
     const handleKeyDown = event => {
       const container = containerRef.current;
       if (!container) {
         return;
       }
       if (event.key === 'Tab') {
-        // Mark that keyboard navigation is happening
+        const active = doc.activeElement;
+        // Any focused node counts, not only HTML elements: an SVG control
+        // inside the container is still inside.
+        if (active == null || !container.contains(active)) {
+          // The trap contains focus that is inside it; it does not pull in a
+          // Tab pressed elsewhere on the page. A layer can be open while focus
+          // legitimately sits outside it — a listbox popup anchored to its own
+          // input, a non-modal popover beside the content it annotates — and
+          // capturing that Tab would take the rest of the page away from
+          // keyboard users.
+          return;
+        }
+
+        // Mark that keyboard navigation is leaving from inside the trap, so a
+        // focus that lands outside is redirected back in.
         isKeyboardNavigationRef.current = true;
         const focusable = getFocusableElements(container);
         if (focusable.length === 0) {
-          const active = document.activeElement;
-          if (!(active instanceof HTMLElement) || !container.contains(active)) {
-            // A layer can be open while focus legitimately sits outside it —
-            // a listbox popup anchored to its own input. Cancelling there
-            // would take Tab away from the whole page.
-            return;
-          }
           // There is nowhere to advance to. Keep focus on the current
           // programmatic target (for example a dialog panel with tabIndex=-1)
           // rather than allowing the browser to move into background content.
@@ -366,7 +397,7 @@ export function useFocusTrap(options) {
         }
         const first = focusable[0];
         const last = focusable[focusable.length - 1];
-        if (document.activeElement === container) {
+        if (doc.activeElement === container) {
           // Programmatic initial focus can sit on the trap container itself
           // (for example a dialog panel with no content controls). Move into
           // the tabbable cycle instead of letting Tab escape to the page.
@@ -380,22 +411,22 @@ export function useFocusTrap(options) {
         }
         if (event.shiftKey) {
           // Shift+Tab: if on first element, wrap to last
-          if (document.activeElement === first) {
+          if (doc.activeElement === first) {
             event.preventDefault();
             last.focus();
           }
         } else {
           // Tab: if on last element, wrap to first
-          if (document.activeElement === last) {
+          if (doc.activeElement === last) {
             event.preventDefault();
             first.focus();
           }
         }
       }
     };
-    document.addEventListener('keydown', handleKeyDown);
+    doc.addEventListener('keydown', handleKeyDown);
     return () => {
-      document.removeEventListener('keydown', handleKeyDown);
+      doc.removeEventListener('keydown', handleKeyDown);
     };
   }, [isActive, onEscape]);
   return {

package/dist/hooks/useMenuHover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMenuHover.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuHover.ts"],"names":[],"mappings":"AA8DA,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,QAAQ,GACf,OAAO,CAqBT;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,YAAY,EAAE;QACZ,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QAC5C,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB;;;WAGG;QACH,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,iDAAiD;QACjD,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;KAC7C,CAAC;IACF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,uEAAuE;IACvE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAmVvB"}
+{"version":3,"file":"useMenuHover.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuHover.ts"],"names":[],"mappings":"AA+DA,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,QAAQ,GACf,OAAO,CAqBT;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,YAAY,EAAE;QACZ,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QAC5C,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB;;;WAGG;QACH,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,iDAAiD;QACjD,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;KAC7C,CAAC;IACF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,uEAAuE;IACvE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAsVvB"}

package/dist/hooks/useMenuHover.js

@@ -39,6 +39,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 import { useListFocus } from "./useListFocus.js";
 import { useMediaQuery } from "./useMediaQuery.js";
+import { focusForLastInput } from "../utils/focusReturn.js";
 const DEFAULT_CLICK_GUARD_MS = 500;
 
 /**
@@ -193,8 +194,11 @@ export function useMenuHover(options) {
     // Read before hiding: closing the layer moves focus itself.
     const menuHadFocus = menuRef.current?.contains(document.activeElement) ?? false;
     hide();
-    if (menuHadFocus) {
-      triggerElRef.current?.focus();
+    const trigger = triggerElRef.current;
+    if (menuHadFocus && trigger != null) {
+      // A pointer's pick leaves no keyboard ring on the trigger; a keyboard's
+      // keeps it (`architecture:interaction-modality` INV1).
+      focusForLastInput(trigger);
     }
   }, [hide, menuRef]);
   useEffect(() => {

package/dist/hooks/useMenuPress.d.ts

@@ -14,7 +14,8 @@
  *   pointer events stay with the element it landed on (implicit capture), so a
  *   menu container never sees a finger that slid onto it — the document does.
  * - The highlight follows the pointer (DOM focus with `preventScroll` in a
- *   menu; a callback for a picker that highlights by index).
+ *   menu, its indicator following the last input; a callback for a picker
+ *   that highlights by index).
  * - The row under the RELEASE acts, the way its own click would, carrying the
  *   release's button and modifier keys.
  * - The browser's stray `click` for a tracked gesture is swallowed at the
@@ -28,7 +29,8 @@
  * - `pointercancel`, a second pointer, or the window losing focus end the
  *   gesture with nothing acting; the model never re-implements scrolling.
  * - While a press is tracked in an overflowing menu, a pointer resting near
- *   the top or bottom edge scrolls the menu toward that edge.
+ *   the top or bottom edge scrolls the menu toward that edge (the shared
+ *   timer of utils/edgeAutoscroll.ts).
  *
  * The menu root is marked `data-astryx-menu-press` so a nested flyout (a DOM
  * descendant of its parent menu) can tell which level owns a press, and so a

package/dist/hooks/useMenuPress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9E,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAG5B,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAchD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA6DD,0DAA0D;AAC1D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAMD,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAChE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACnD,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE;QACT,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,YAAY,EAAE;QACZ,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;KAC/D,CAAC;IACF;;;;OAIG;IACH,uBAAuB,EAAE,MAAM,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAkED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAojB7E"}
+{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAM5B,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAchD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA6DD,0DAA0D;AAC1D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAMD,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAChE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACnD,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE;QACT,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,YAAY,EAAE;QACZ,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;KAC/D,CAAC;IACF;;;;OAIG;IACH,uBAAuB,EAAE,MAAM,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAkED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA2kB7E"}