@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/useAnimatedLayout.js

@@ -7,8 +7,7 @@
  * @input React (useMemo), motion/animatedLayout.ts
  * @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle
  *   type
- * @position Public hook (`spec:AST-105`) over the one size-change module
- *   (`architecture:react-component-runtime` INV12)
+ * @position Public hook over the one size-change module
  *
  * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
  */
@@ -23,7 +22,7 @@ import { createAnimatedLayout } from "../motion/animatedLayout.js";
  *
  * `containerRef` names the area: an app passes the ref it already gives its
  * scroll container or panel (a ScrollableArea's ref reaches its native scroll
- * viewport). The handle has no public members (`spec:AST-105` FR1).
+ * viewport). The handle has no public members.
  *
  * @example
  * ```

package/dist/hooks/useAnnounce.d.ts

@@ -1,28 +1,11 @@
 /**
  * @file useAnnounce.ts
- * @input Uses React context and useCallback; DOM APIs and cancellable
- *   animation frames for a singleton live-region pair on the page body and
- *   one persistent polite/assertive pair inside each open Astryx modal
- * @output Exports useAnnounce hook (with its `hasReplace` option),
- *   AnnouncePoliteness and UseAnnounceOptions types; the internal modal
- *   context, the in-dialog region writer the busy-announcement hook uses, and
- *   the hook the modal route (`modalAnnounce.ts`, loaded only with an Astryx
- *   modal) installs itself through
- * @position Core a11y hook; provides imperative screen-reader announcements.
- *   A message follows the nearest open native modal enclosing its caller
- *   (`spec:AST-086` FR14): inside an Astryx modal it is written to that
- *   dialog's own containers, since the page-body channel is not exposed
- *   while a native modal is open; otherwise to the shared page-body pair.
- *   Containers are created empty (FR3), carry the two urgencies (FR5), join
- *   messages written before the previous is exposed and say an identical
- *   same-frame repeat once (FR9), except that a `hasReplace` instance's
- *   message withdraws that instance's previous one not yet exposed, and clear
- *   shortly after each announcement;
- *   the route in `modalAnnounce.ts` hands a message still unexposed when its
- *   modal stops being exposed to the channel exposed after it — the modal
- *   then on top, or the page body once no modal is open. Each write keeps a
- *   receipt per announcer beside the words, which follows them wherever
- *   they are moved, so the announcer can take back its own share.
+ * @input React context; DOM live regions; animation frames
+ * @output useAnnounce, AnnouncePoliteness, UseAnnounceOptions; the internal
+ *   modal context, in-dialog region writer, and modal route hook
+ * @position Core a11y hook for screen-reader announcements. A message goes to
+ *   the nearest open native modal around its caller, else to the shared
+ *   page-body regions. `modalAnnounce.ts` holds the modal route.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -43,13 +26,10 @@ export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => v
 /** Options for `useAnnounce`. */
 export interface UseAnnounceOptions {
     /**
-     * The instance states one current state of its owner, such as a search's
-     * result count: each message it writes withdraws the instance's previous
-     * message while that one is not yet exposed, whatever their urgencies, and
-     * is spoken in the region of its own urgency; a message already exposed has
-     * been heard and stays. Messages from other instances, and from instances
-     * without `hasReplace`, still join (`spec:AST-086` FR9). Give each state a
-     * component reports its own instance.
+     * Each message from this instance withdraws the instance's previous message
+     * if assistive technology has not exposed it yet, whatever its urgency. An
+     * exposed message stays. Messages from other instances still join. Use one
+     * instance for each state that a component reports, such as a result count.
      * @default false
      */
     hasReplace?: boolean;
@@ -82,8 +62,8 @@ export declare function handleOf(receipt: AnnounceReceipt): WithdrawAnnouncement
 /**
  * Move `waiting` words elsewhere, one delivery per announcer and in order,
  * and point each receipt at its delivery, so every announcer can still take
- * back its own share (`spec:AST-086` FR9, FR14). The deliveries join where
- * they land, so the words are spoken once. @internal
+ * back its own share. The deliveries join where they land, so the words are
+ * spoken once. @internal
  */
 export declare function forwardWaiting(waiting: ReadonlyArray<WaitingWords>, deliver: (text: string) => WithdrawAnnouncement | null): void;
 /**
@@ -112,7 +92,7 @@ export declare function clearRegion(politeness: AnnouncePoliteness): void;
  * An instance created with `hasReplace` states one current state, such as a
  * search's result count: each message it writes withdraws its previous one
  * while that one is not yet exposed, so typing faster than a frame says only
- * the latest count (`spec:AST-086` FR9).
+ * the latest count.
  *
  * @param options - `hasReplace` (default false)
  * @example
@@ -160,7 +140,7 @@ export declare function isOpenModal(dialog: HTMLDialogElement | null | undefined
  * The nearest open native modal dialog enclosing `element` in the DOM, Astryx
  * or app-rendered. Internal: the busy-announcement hook routes by its owner's
  * element so a busy start inside a native modal an app renders without Astryx
- * is still heard inside it (`spec:AST-086` FR14, last sentence).
+ * is still heard inside it.
  */
 export declare function enclosingModalDialog(element: Element | null | undefined): HTMLDialogElement | null;
 /**
@@ -171,8 +151,7 @@ export declare function enclosingModalDialog(element: Element | null | undefined
  * written to the dialog while it is open as a modal, else to the shared
  * channel. Returns how to take the words back while they wait, wherever they
  * move, so a busy start overtaken by its own outcome is never heard ahead of
- * it inside a modal (`spec:AST-086` FR8). Internal: used by the
- * busy-announcement hook.
+ * it inside a modal. Internal: used by the busy-announcement hook.
  */
 export declare function announceInModal(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): WithdrawAnnouncement | null;
 /** What the route asks of the writer in the write frame. @internal */
@@ -217,7 +196,7 @@ export declare function clearModalRegion(dialog: HTMLDialogElement, politeness:
 export declare function takeJoinedAnnouncement(): object | null;
 /**
  * Withdraws one announcer's share of a message still waiting to be exposed, so
- * a busy start overtaken by its own outcome is never spoken (spec:AST-086 FR8).
+ * a busy start overtaken by its own outcome is never spoken.
  * The message stays while another announcer still holds it.
  *
  * @internal

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,KAC5B,IAAI,CAAC;AAEV,iCAAiC;AACjC,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,IAAI,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACvC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,oBAAoB,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,GACrD,IAAI,CAMN;AAyHD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAoC7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAShE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,UAAkB,GACnB,GAAE,kBAAuB,GAAG,UAAU,CAiCtC;AAmBD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAG/C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,oBAAoB,oDAEhC,CAAC;AAGF,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CACN,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,eAAe,CACb,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAAC;CAChC;AAID,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAClC,iBAAiB,GAAG,IAAI,CAS1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,kBAA6B,GACxC,oBAAoB,GAAG,IAAI,CAQ7B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;CAC1D;AAkCD,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAE/D;AASD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,EAAE,CAQlE;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,kBAAkB,GAC7B,WAAW,GAAG,IAAI,CAIpB;AA2BD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,KAAK,CAAC,EAAE,eAAe,GACtB,oBAAoB,CA+CtB;AA4CD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,kBAAkB,GAC7B,IAAI,CAWN;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,IAAI,CAItD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,kBAAkB,GAC7B,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAWhD"}
+{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,KAC5B,IAAI,CAAC;AAEV,iCAAiC;AACjC,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,IAAI,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACvC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,oBAAoB,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,GACrD,IAAI,CAMN;AAmHD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAmC7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAShE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,UAAkB,GACnB,GAAE,kBAAuB,GAAG,UAAU,CA+BtC;AAYD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAG/C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,oBAAoB,oDAEhC,CAAC;AAGF,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CACN,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,eAAe,CACb,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,oBAAoB,GAAG,IAAI,CAAC;CAChC;AAID,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAClC,iBAAiB,GAAG,IAAI,CAS1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,kBAA6B,GACxC,oBAAoB,GAAG,IAAI,CAQ7B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;CAC1D;AA+BD,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAE/D;AASD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,EAAE,CAQlE;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,kBAAkB,GAC7B,WAAW,GAAG,IAAI,CAIpB;AA2BD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,KAAK,CAAC,EAAE,eAAe,GACtB,oBAAoB,CA+CtB;AA0CD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,kBAAkB,GAC7B,IAAI,CAWN;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,IAAI,CAItD;AAGD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,kBAAkB,GAC7B,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAWhD"}

package/dist/hooks/useAnnounce.js

@@ -4,29 +4,12 @@
 
 /**
  * @file useAnnounce.ts
- * @input Uses React context and useCallback; DOM APIs and cancellable
- *   animation frames for a singleton live-region pair on the page body and
- *   one persistent polite/assertive pair inside each open Astryx modal
- * @output Exports useAnnounce hook (with its `hasReplace` option),
- *   AnnouncePoliteness and UseAnnounceOptions types; the internal modal
- *   context, the in-dialog region writer the busy-announcement hook uses, and
- *   the hook the modal route (`modalAnnounce.ts`, loaded only with an Astryx
- *   modal) installs itself through
- * @position Core a11y hook; provides imperative screen-reader announcements.
- *   A message follows the nearest open native modal enclosing its caller
- *   (`spec:AST-086` FR14): inside an Astryx modal it is written to that
- *   dialog's own containers, since the page-body channel is not exposed
- *   while a native modal is open; otherwise to the shared page-body pair.
- *   Containers are created empty (FR3), carry the two urgencies (FR5), join
- *   messages written before the previous is exposed and say an identical
- *   same-frame repeat once (FR9), except that a `hasReplace` instance's
- *   message withdraws that instance's previous one not yet exposed, and clear
- *   shortly after each announcement;
- *   the route in `modalAnnounce.ts` hands a message still unexposed when its
- *   modal stops being exposed to the channel exposed after it — the modal
- *   then on top, or the page body once no modal is open. Each write keeps a
- *   receipt per announcer beside the words, which follows them wherever
- *   they are moved, so the announcer can take back its own share.
+ * @input React context; DOM live regions; animation frames
+ * @output useAnnounce, AnnouncePoliteness, UseAnnounceOptions; the internal
+ *   modal context, in-dialog region writer, and modal route hook
+ * @position Core a11y hook for screen-reader announcements. A message goes to
+ *   the nearest open native modal around its caller, else to the shared
+ *   page-body regions. `modalAnnounce.ts` holds the modal route.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -77,8 +60,8 @@ export function handleOf(receipt) {
 /**
  * Move `waiting` words elsewhere, one delivery per announcer and in order,
  * and point each receipt at its delivery, so every announcer can still take
- * back its own share (`spec:AST-086` FR9, FR14). The deliveries join where
- * they land, so the words are spoken once. @internal
+ * back its own share. The deliveries join where they land, so the words are
+ * spoken once. @internal
  */
 export function forwardWaiting(waiting, deliver) {
   for (const {
@@ -92,14 +75,12 @@ export function forwardWaiting(waiting, deliver) {
 }
 const CONTAINER_ATTR = 'data-astryx-live-region';
 
-// Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
-// inline so the regions work without any stylesheet being present.
+// The same clip as VisuallyHidden. It is inline, so the regions work without
+// a stylesheet.
 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;' + 'inset-block-start:0;inset-inline-start:0;pointer-events:none;' + 'user-select:none;';
 /**
- * How long an announcement stays in its region before being auto-cleared.
- * Long enough for screen readers to pick the message up and finish reading
- * it; clearing afterwards keeps stale status text out of the accessibility
- * tree for users who browse the DOM later. Each announce resets the timer.
+ * Screen readers need this time to read the message. The clear then keeps
+ * stale status text out of the accessibility tree.
  */
 const CLEAR_DELAY_MS = 2000;
 const clearTimers = {
@@ -114,17 +95,15 @@ function cancelScheduledClear(politeness) {
   }
 }
 
-// Messages announced before the region exposes them (written in the same
-// frame) wait here and are exposed together, in order, so none is dropped;
-// an identical repeat is the same message and is kept once (spec:AST-086
-// FR9). One frame per region writes them.
+// Messages written before the region exposes them wait here. One frame
+// exposes them together and in order, so none is dropped. An identical repeat
+// is kept once.
 const pendingFrames = {
   polite: null,
   assertive: null
 };
-// Each pending message counts the announcers waiting on it, so one of them
-// withdrawing it (a busy start overtaken by its outcome) leaves it in place
-// for the others.
+// Each pending message counts its waiting announcers. When one withdraws it
+// (a busy start overtaken by its outcome), the message stays for the others.
 
 const pendingMessages = {
   polite: [],
@@ -148,11 +127,9 @@ function scheduleClear(politeness, target) {
   }, CLEAR_DELAY_MS);
 }
 
-// Singleton: the live regions are created ONCE and stay mounted for the
-// lifetime of the document. This is the crux of reliable announcements — many
-// screen readers will not announce content injected into a live region that is
-// created together with its content ("born with content"). By mounting empty
-// regions up front and only mutating their text later, updates are announced.
+// The live regions are created once and stay mounted. Many screen readers do
+// not announce a live region that is created with its content. They do
+// announce a text change in an empty region that is already mounted.
 let regions = null;
 function createRegion(politeness) {
   const el = document.createElement('div');
@@ -169,7 +146,7 @@ function getRegions() {
     return null;
   }
   if (regions) {
-    // Re-attach if a region was removed from the DOM (e.g. by a test cleanup).
+    // A test cleanup can remove a region from the DOM. Attach it again.
     if (!regions.polite.isConnected) {
       document.body.appendChild(regions.polite);
     }
@@ -208,20 +185,19 @@ export function announceMessage(message, politeness) {
   pendingMessages[politeness].push(pending);
   lastJoined = pending;
   if (pendingFrames[politeness] == null) {
-    // Clearing first guarantees the mutation is observed even when the new
-    // message equals the current text — some AT deduplicate identical content.
+    // Clear first, so the change is seen when the new text equals the old
+    // text. Some assistive technology ignores identical content.
     target.textContent = '';
-    // A re-set in the next frame is more reliable across AT than an immediate
-    // re-set, which can be coalesced with the clear.
+    // Some assistive technology merges an immediate re-set with the clear. A
+    // re-set in the next frame is more reliable.
     pendingFrames[politeness] = requestAnimationFrame(() => {
       pendingFrames[politeness] = null;
       target.textContent = pendingMessages[politeness].map(pending => pending.text).join(' ');
       pendingMessages[politeness] = [];
     });
   }
-  // Auto-clear so the last message does not linger in the accessibility tree
-  // indefinitely. Scheduled per announce, so a newer announcement always
-  // resets the countdown (the delay comfortably outlasts the rAF re-set).
+  // The clear keeps the last message out of the accessibility tree. Each
+  // announce restarts the delay, which is much longer than the frame re-set.
   scheduleClear(politeness, target);
   return () => withdrawPendingAnnouncement(pending, politeness);
 }
@@ -256,7 +232,7 @@ export function clearRegion(politeness) {
  * An instance created with `hasReplace` states one current state, such as a
  * search's result count: each message it writes withdraws its previous one
  * while that one is not yet exposed, so typing faster than a frame says only
- * the latest count (`spec:AST-086` FR9).
+ * the latest count.
  *
  * @param options - `hasReplace` (default false)
  * @example
@@ -274,8 +250,8 @@ export function useAnnounce({
   hasReplace = false
 } = {}) {
   const modal = use(ModalAnnounceContext);
-  // A `hasReplace` instance's latest write, which its next message takes back
-  // if assistive technology has not had it yet.
+  // The latest write of a `hasReplace` instance. Its next message withdraws
+  // it if assistive technology has not had it yet.
   const withdrawPreviousRef = useRef(null);
   return useCallback((message, politeness = 'polite') => {
     if (hasReplace) {
@@ -284,15 +260,13 @@ export function useAnnounce({
       withdrawPrevious?.();
     }
     let written;
-    // Inside an Astryx modal's provider: the modal route decides, per call,
-    // where the caller is heard — `modal` is non-null only where a provider
-    // rendered, and rendering one loads the route.
+    // `modal` is non-null only below a provider, and a provider loads the
+    // route. The route decides where the caller is heard.
     if (modal != null && modalRoute != null) {
       written = modalRoute.announce(modal, message, politeness);
     } else if (!message) {
-      // An empty message clears any lingering status from the region,
-      // including messages joined but not yet exposed — useful when the
-      // triggering context ends.
+      // An empty message clears the region, with the messages that are
+      // not yet exposed.
       clearRegion(politeness);
       written = null;
     } else {
@@ -304,20 +278,13 @@ export function useAnnounce({
   }, [hasReplace, modal]);
 }
 
-// =============================================================================
-// Inside an Astryx modal (spec:AST-086 FR14)
-// =============================================================================
+// Inside an Astryx modal (AST-086 FR14)
 //
-// `useAnnounce` reads the nearest ModalAnnounceProvider's scope. The route a
-// scope implies — exposure, the top-layer order, hand-off and hold on close,
-// the covered rule, deferral while a modal is being presented — lives in
-// `modalAnnounce.ts`, which ModalAnnounceProvider imports and which installs
-// itself here when it loads. A context value is non-null only where a
-// provider rendered, so the route is installed before it is needed, and a
-// component that calls `useAnnounce` but renders no modal never loads it.
-// What stays in this module is what a caller without any Astryx modal still
-// needs: the region writer the busy-announcement hook uses inside a native
-// modal an app renders without Astryx, and the DOM walk that finds it.
+// The modal route lives in `modalAnnounce.ts`. ModalAnnounceProvider imports
+// it, and it installs itself here when it loads. A component that calls
+// `useAnnounce` but renders no modal never loads it. This module keeps what a
+// caller without an Astryx modal needs: the region writer for a native modal
+// that an app renders, and the DOM walk that finds that modal.
 
 const MODAL_REGION_ATTR = 'data-astryx-modal-live-region';
 
@@ -348,7 +315,7 @@ export function isOpenModal(dialog) {
  * The nearest open native modal dialog enclosing `element` in the DOM, Astryx
  * or app-rendered. Internal: the busy-announcement hook routes by its owner's
  * element so a busy start inside a native modal an app renders without Astryx
- * is still heard inside it (`spec:AST-086` FR14, last sentence).
+ * is still heard inside it.
  */
 export function enclosingModalDialog(element) {
   let dialog = element?.closest('dialog') ?? null;
@@ -369,8 +336,7 @@ export function enclosingModalDialog(element) {
  * written to the dialog while it is open as a modal, else to the shared
  * channel. Returns how to take the words back while they wait, wherever they
  * move, so a busy start overtaken by its own outcome is never heard ahead of
- * it inside a modal (`spec:AST-086` FR8). Internal: used by the
- * busy-announcement hook.
+ * it inside a modal. Internal: used by the busy-announcement hook.
  */
 export function announceInModal(dialog, message, politeness = 'polite') {
   if (modalRoute != null) {
@@ -384,11 +350,10 @@ export function announceInModal(dialog, message, politeness = 'polite') {
 
 /** What the route asks of the writer in the write frame. @internal */
 
-// Each in-dialog region's pending state: the messages written since its text
-// was last exposed, the frame that will expose them joined, the frame after
-// that (text set in one frame is not yet taken by assistive technology in
-// that same frame, so a message arriving before this frame runs still joins
-// rather than wiping the words), and the timer that clears them afterwards.
+// The pending state of each in-dialog region: the messages written since its
+// text was last exposed, the frame that exposes them, the next frame, and the
+// clear timer. Assistive technology does not take text in the frame that sets
+// it. So a message that arrives before the next frame joins the words.
 
 const pendingByRegion = new WeakMap();
 function cancelPending(pending) {
@@ -472,8 +437,8 @@ export function writeModalRegion(dialog, message, politeness, guard) {
   if (previous != null) {
     cancelPending(previous);
   }
-  // Clearing first guarantees the mutation is observed even when the new
-  // message equals the current text — some AT deduplicate identical content.
+  // Clear first, so the change is seen when the new text equals the old
+  // text. Some assistive technology ignores identical content.
   target.textContent = '';
   const pending = {
     messages,
@@ -485,8 +450,8 @@ export function writeModalRegion(dialog, message, politeness, guard) {
   pending.frame = requestAnimationFrame(() => {
     pending.frame = null;
     if (guard != null && !guard.isExposed()) {
-      // Stopped being exposed between the call and this frame: the words go
-      // where they will be heard, their receipts with them.
+      // The region stopped being exposed after the call. Send the words and
+      // their receipts to where they will be heard.
       pendingByRegion.delete(target);
       guard.redirect(waitingIn(pending));
       return;
@@ -507,12 +472,10 @@ export function writeModalRegion(dialog, message, politeness, guard) {
 
 /**
  * Withdraw one announcer's share of `message` from `target` while it is not
- * yet exposed — written but not yet spoken — so a busy start overtaken by its
- * own outcome is never heard ahead of it (`spec:AST-086` FR8), and a
- * `hasReplace` instance's next message replaces its previous one (FR9,
- * FR14). The message stays while another announcer holds it; a receipt not
- * among the waiting words (they were exposed, cleared, or moved) takes back
- * nothing.
+ * yet exposed. Then a busy start overtaken by its outcome is never heard, and
+ * a `hasReplace` instance's next message replaces its previous one. The
+ * message stays while another announcer holds it. A receipt that is not among
+ * the waiting words takes back nothing.
  */
 function withdrawFromRegion(target, message, receipt) {
   const pending = pendingByRegion.get(target);
@@ -571,9 +534,10 @@ export function takeJoinedAnnouncement() {
   return joined;
 }
 
+// A busy start overtaken by its own outcome is never spoken (AST-086 FR8).
 /**
  * Withdraws one announcer's share of a message still waiting to be exposed, so
- * a busy start overtaken by its own outcome is never spoken (spec:AST-086 FR8).
+ * a busy start overtaken by its own outcome is never spoken.
  * The message stays while another announcer still holds it.
  *
  * @internal

package/dist/hooks/useAnnounceRenderedText.d.ts

@@ -1,64 +1,33 @@
 /**
  * @file useAnnounceRenderedText.ts
- * @input A ref to a rendered element, whether it is showing, and a token that
- *   marks a new occasion to speak
- * @output Announces that element's own rendered text through the persistent
- *   polite live region, or through the announcer the owner passes
- * @position Core a11y hook; mirrors on-screen content into the shared live
- *   region by reading the DOM
- *
- * Some content reaches assistive technology only through a live region: a
- * panel message marked `role="presentation"`, for instance, because
- * `role="listbox"` permits only `option` and `group` children. When that
- * content is a caller-supplied `ReactNode`, the component must announce what
- * it actually rendered — announcing a built-in default over a caller's
- * element tells the screen-reader user something the sighted user is not
- * reading (`spec:AST-056` AR1, FR3).
- *
- * The text is read from the DOM after render, never by inspecting React
- * children. That is the whole point: by the time this runs the browser has
- * rendered the subtree, so text a child component generates inside its own
- * render announces correctly, and there is no tree walk, no depth limit, and
- * no "could not read it" fallback to get wrong.
- *
- * Announcing through the persistent `useAnnounce` region rather than putting
- * `role="status"` on the rendered element is both required here — the element
- * is a listbox child, which may only be `option` or `group` — and the
- * repository's established convention for conditionally rendered messages
- * (see `FieldStatus` and `TimeInput`): a live region that mounts together
- * with its content is not reliably announced.
- *
- * 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.
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * that barrel is re-exported wholesale from the package entry point, so
- * adding it there would ship a new public hook without `spec:AST-002`
- * admission. Import it by path from inside the package.
+ * @input A ref to a rendered element, whether it shows, and a token for each
+ *   new occasion to speak
+ * @output Announces the element's rendered text through the polite live
+ *   region, or through the owner's announcer
+ * @position Core a11y hook. It is not in hooks/index.ts, because that barrel
+ *   is public and a new public hook needs admission (AST-002). Import it by
+ *   path.
  */
 import { type RefObject } from 'react';
 import { type AnnounceFn, type AnnouncePoliteness } from './useAnnounce.js';
 export interface AnnounceRenderedTextOptions {
     /**
-     * Text present or changed while the document loads or hydrates is silent;
-     * text that appears or changes later is announced once (`spec:AST-086`
-     * FR11). A mounted live container speaks its own content (FR4); each child is
-     * a block; a reveal without a re-render is read on the next render (FR13).
+     * Text that is present or changes while the document loads or hydrates is
+     * silent. Text that appears or changes later is announced once. A mounted
+     * live container speaks its own content, and each child is a block. A
+     * reveal without a re-render is read on the next render.
      */
     skipFirstRender?: boolean;
     /**
-     * The channel's urgency: errors and time-critical failures are assertive,
-     * every other message polite (`spec:AST-086` FR5). Defaults to polite.
+     * The urgency: assertive for errors and time-critical failures, else
+     * polite. Defaults to polite.
      */
     politeness?: AnnouncePoliteness;
     /**
-     * The owner's announcer to speak through, when the rendered text states
-     * the next value of a state that announcer states: a picker's empty-panel
-     * message goes through its search's `hasReplace` instance, so the two
-     * replace each other while not yet exposed (`spec:AST-086` FR13).
-     * Defaults to this hook's own instance.
+     * The owner's announcer, when the rendered text states the next value of
+     * that announcer's state. For example, a picker's empty-panel message goes
+     * through its search's `hasReplace` instance, so the two replace each other
+     * while not yet exposed. Defaults to this hook's own instance.
      */
     announce?: AnnounceFn;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,EACrB,QAAQ,EAAE,aAAa,GACxB,GAAE,2BAAgC,GAClC,IAAI,CAsDN"}
+{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAcH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,EACrB,QAAQ,EAAE,aAAa,GACxB,GAAE,2BAAgC,GAClC,IAAI,CAoDN"}

package/dist/hooks/useAnnounceRenderedText.js

@@ -4,44 +4,26 @@
 
 /**
  * @file useAnnounceRenderedText.ts
- * @input A ref to a rendered element, whether it is showing, and a token that
- *   marks a new occasion to speak
- * @output Announces that element's own rendered text through the persistent
- *   polite live region, or through the announcer the owner passes
- * @position Core a11y hook; mirrors on-screen content into the shared live
- *   region by reading the DOM
- *
- * Some content reaches assistive technology only through a live region: a
- * panel message marked `role="presentation"`, for instance, because
- * `role="listbox"` permits only `option` and `group` children. When that
- * content is a caller-supplied `ReactNode`, the component must announce what
- * it actually rendered — announcing a built-in default over a caller's
- * element tells the screen-reader user something the sighted user is not
- * reading (`spec:AST-056` AR1, FR3).
- *
- * The text is read from the DOM after render, never by inspecting React
- * children. That is the whole point: by the time this runs the browser has
- * rendered the subtree, so text a child component generates inside its own
- * render announces correctly, and there is no tree walk, no depth limit, and
- * no "could not read it" fallback to get wrong.
- *
- * Announcing through the persistent `useAnnounce` region rather than putting
- * `role="status"` on the rendered element is both required here — the element
- * is a listbox child, which may only be `option` or `group` — and the
- * repository's established convention for conditionally rendered messages
- * (see `FieldStatus` and `TimeInput`): a live region that mounts together
- * with its content is not reliably announced.
- *
- * 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.
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * that barrel is re-exported wholesale from the package entry point, so
- * adding it there would ship a new public hook without `spec:AST-002`
- * admission. Import it by path from inside the package.
+ * @input A ref to a rendered element, whether it shows, and a token for each
+ *   new occasion to speak
+ * @output Announces the element's rendered text through the polite live
+ *   region, or through the owner's announcer
+ * @position Core a11y hook. It is not in hooks/index.ts, because that barrel
+ *   is public and a new public hook needs admission (AST-002). Import it by
+ *   path.
  */
+
+// Some content reaches assistive technology only through a live region. For
+// example, a listbox permits only `option` and `group` children, so a panel
+// message in it has `role="presentation"`. When that content is a caller's
+// `ReactNode`, announce what was rendered, not a built-in default (AST-056,
+// AST-086).
+//
+// The text comes from the DOM after render, not from React children, so text
+// that a child component generates is included. A live region that mounts
+// with its content is not reliably announced, so the persistent `useAnnounce`
+// region speaks it. Content with `aria-hidden` or `hidden` is left out. An
+// `aria-label` on a descendant is not used.
 import { useEffect, useRef, useState } from 'react';
 import { useAnnounce } from "./useAnnounce.js";
 import { useIsHydrating } from "./useIsHydrating.js";
@@ -113,11 +95,9 @@ export function useAnnounceRenderedText(ref, isShown, occasion, {
   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
-  // change the rendered message without any prop this hook can see. Reading
-  // one element's text per render is cheap, and the dedupe below makes every
-  // render after the first a no-op.
+  // No dependency array: the text lives in the DOM, and a caller can change it
+  // without a prop that this hook sees. One text read per render is cheap, and
+  // the dedupe below makes later renders no-ops.
   useEffect(() => {
     const isFirstRun = isFirstRunRef.current;
     isFirstRunRef.current = false;

package/dist/hooks/useAttachment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file useAttachment.ts
+ * @input A node ref (an element's, or the document's), an attach function
+ *   and a key
+ * @output Exports useAttachment: keeps the attach function bound to the node
+ *   the ref holds across commits
+ * @position Internal React helper, not in hooks/index.ts: the one attach
+ *   and release lifecycle of the gesture hooks (useGestureRecognizer,
+ *   usePressTracker, useFingerScroll)
+ *
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
+ * and gestures/__tests__/useFingerScroll.test.tsx.
+ */
+import { type RefObject } from 'react';
+/**
+ * Keep `attach` bound to the node `ref` holds after each commit: an element,
+ * or the document. A replaced node is released and the new one attached, a
+ * changed `key` re-attaches, and the last attachment is released on unmount;
+ * a commit that changes neither does nothing (react-component-runtime INV3).
+ */
+export declare function useAttachment<T extends Node = Element>(ref: RefObject<T | null>, attach: (element: T) => () => void, key: unknown): void;
+//# sourceMappingURL=useAttachment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAttachment.d.ts","sourceRoot":"","sources":["../../src/hooks/useAttachment.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,IAAI,GAAG,OAAO,EACpD,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACxB,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,IAAI,EAClC,GAAG,EAAE,OAAO,GACX,IAAI,CA2BN"}