@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

package/src/gestures/touchActionRule.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchActionRule.ts
+ * @input An element and the touch-action its recognizers derive
+ * @output Exports markTouchAction and unmarkTouchAction: the element carries
+ *   the derived value in TOUCH_ACTION_ATTRIBUTE, and its document or shadow
+ *   root holds one zero-specificity rule per value in the first cascade
+ *   layer (`reset`), so any author rule, in any layer or none, or inline
+ *   value outranks the host's (`spec:AST-094` FR18, DEC-8); a root's rules
+ *   go with its last marked element (FR24)
+ * @position The gesture host's touch-action writer (GestureHost.ts)
+ *
+ * The mark is set as a recognizer attaches, so a subtree that mounts with
+ * it is styled once with its touch-action: a value written after that first
+ * styling restyles every descendant (each one's effective touch-action
+ * changes). Until the host reads the element's own value, the value in
+ * force is the author's where the author sets one, and the derived value
+ * elsewhere: never wider than the author's.
+ *
+ * SYNC: When modified, update GestureHost.ts.
+ */
+
+/** The attribute that carries the host's derived touch-action. */
+export const TOUCH_ACTION_ATTRIBUTE = 'data-astryx-touch-action';
+
+/**
+ * The cascade layer the rules sit in: the first in the order every package
+ * stylesheet declares (`spec:AST-080` FR3), so an author rule in any later
+ * layer, or in none, outranks them. Unlayered, they would outrank every
+ * layered author rule.
+ */
+const RULE_LAYER = 'reset';
+
+type RuleRoot = Document | ShadowRoot;
+
+/**
+ * Per document or shadow root: the values it has a rule for, their rules'
+ * text, where that text goes (an adopted sheet, or a style element where
+ * constructable sheets are missing), and the elements marked there. The
+ * rules go with the root's last marked element (`spec:AST-094` FR24).
+ */
+const sheets = new WeakMap<
+  RuleRoot,
+  {
+    readonly values: Set<string>;
+    readonly marked: Set<Element>;
+    css: string;
+    write(css: string): void;
+    remove(): void;
+  }
+>();
+
+/** Where each marked element's rule lives, for its unmark after it leaves. */
+const markedRoots = new WeakMap<Element, RuleRoot>();
+
+function sheetOf(root: RuleRoot) {
+  let entry = sheets.get(root);
+  if (entry == null) {
+    const doc = root.nodeType === 9 ? (root as Document) : root.ownerDocument;
+    let write: ((css: string) => void) | undefined;
+    let remove: (() => void) | undefined;
+    // A constructable sheet where the engine has one; a style element only
+    // where it has none, so any other error from a sheet is not hidden.
+    const Sheet = doc?.defaultView?.CSSStyleSheet;
+    if (
+      typeof Sheet === 'function' &&
+      'replaceSync' in Sheet.prototype &&
+      'adoptedStyleSheets' in root
+    ) {
+      const sheet = new Sheet();
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+      write = css => sheet.replaceSync(css);
+      remove = () => {
+        root.adoptedStyleSheets = root.adoptedStyleSheets.filter(
+          adopted => adopted !== sheet,
+        );
+      };
+    } else {
+      const style = doc?.createElement('style');
+      const parent =
+        root.nodeType === 9 ? (doc?.head ?? doc?.documentElement) : root;
+      if (style != null && parent != null) {
+        parent.append(style);
+        write = css => {
+          style.textContent = css;
+        };
+        remove = () => style.remove();
+      }
+    }
+    if (write == null || remove == null) {
+      return null;
+    }
+    entry = {values: new Set(), marked: new Set(), css: '', write, remove};
+    sheets.set(root, entry);
+  }
+  return entry;
+}
+
+/**
+ * Give `element` the derived touch-action under a rule any author rule
+ * outranks. Returns false where no rule can hold it (a detached element):
+ * the caller writes nothing until the element is in a document.
+ */
+export function markTouchAction(element: Element, value: string): boolean {
+  const root = element.getRootNode() as RuleRoot;
+  const entry =
+    element.isConnected && (root.nodeType === 9 || 'host' in root)
+      ? sheetOf(root)
+      : null;
+  if (entry == null) {
+    return false;
+  }
+  if (!entry.values.has(value)) {
+    entry.values.add(value);
+    entry.css += `:where([${TOUCH_ACTION_ATTRIBUTE}="${value}"]){touch-action:${value}}`;
+    entry.write(`@layer ${RULE_LAYER}{${entry.css}}`);
+  }
+  if (element.getAttribute(TOUCH_ACTION_ATTRIBUTE) !== value) {
+    element.setAttribute(TOUCH_ACTION_ATTRIBUTE, value);
+  }
+  const previous = markedRoots.get(element);
+  if (previous != null && previous !== root) {
+    // Moved to another root: the old one lets it go.
+    releaseMark(element, previous);
+  }
+  entry.marked.add(element);
+  markedRoots.set(element, root);
+  return true;
+}
+
+/** `root` no longer holds `element`'s mark; its last mark takes the rules. */
+function releaseMark(element: Element, root: RuleRoot): void {
+  const entry = sheets.get(root);
+  if (entry == null) {
+    return;
+  }
+  entry.marked.delete(element);
+  if (entry.marked.size === 0) {
+    entry.remove();
+    sheets.delete(root);
+  }
+}
+
+/**
+ * Remove the host's mark; the element's own touch-action stands. The last
+ * mark in a document or shadow root takes its rules with it.
+ */
+export function unmarkTouchAction(element: Element): void {
+  element.removeAttribute(TOUCH_ACTION_ATTRIBUTE);
+  const root = markedRoots.get(element);
+  if (root == null) {
+    return;
+  }
+  markedRoots.delete(element);
+  releaseMark(element, root);
+}

package/src/gestures/types.ts

@@ -46,13 +46,6 @@ export interface NativeScrollProbe {
    * lets the browser pan that axis).
    */
   canScroll(dx: number, dy: number): boolean;
-  /**
-   * How much further (px) the scroller that would move for a finger moving
-   * by (dx, dy) can scroll before it reaches its edge; 0 when none would.
-   * Lets a reader place the point where the content runs out between two
-   * samples instead of at the next one.
-   */
-  distanceToEdge?(dx: number, dy: number): number;
   /** Whether any element under the touch can scroll natively at all. */
   readonly isInsideScroller: boolean;
   /**
@@ -127,6 +120,17 @@ export interface GestureEventContext {
 export interface GestureEnvironment {
   viewportSize(): {readonly width: number; readonly height: number};
   isRtl(view: unknown): boolean;
+  /**
+   * The box of a recognizer's view in viewport coordinates, or null when it
+   * has none to measure. A screen-edge pan reads it to tell a view within
+   * its edge band from any other.
+   */
+  viewRect?(view: unknown): {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
 }
 
 export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
@@ -136,8 +140,18 @@ export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
     }
     return {width: window.innerWidth, height: window.innerHeight};
   },
-  isRtl() {
-    return false;
+  isRtl(view) {
+    if (typeof window === 'undefined' || !(view instanceof Element)) {
+      return false;
+    }
+    return window.getComputedStyle(view).direction === 'rtl';
+  },
+  viewRect(view) {
+    if (typeof Element === 'undefined' || !(view instanceof Element)) {
+      return null;
+    }
+    const {left, top, width, height} = view.getBoundingClientRect();
+    return {left, top, width, height};
   },
 };
 
@@ -158,4 +172,11 @@ export interface TouchConsumer {
    * (attached above this consumer) from beginning for a touch on it.
    */
   allowsAncestorRecognizer?(recognizer: unknown): boolean;
+  /**
+   * Whether the consumer takes touches now (a disabled control does not).
+   * The host listens only while something enabled is attached
+   * (`spec:AST-094` FR24); after this changes, call `host.update(element)`.
+   * @default true
+   */
+  isEnabled?(): boolean;
 }

package/src/hooks/index.ts

@@ -15,7 +15,11 @@ export {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
 export {useAnnounce} from './useAnnounce';
-export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';
+export type {
+  AnnounceFn,
+  AnnouncePoliteness,
+  UseAnnounceOptions,
+} from './useAnnounce';
 
 export {useClipboard} from './useClipboard';
 export type {UseClipboardOptions, UseClipboardReturn} from './useClipboard';

package/src/hooks/modalAnnounce.ts

@@ -14,7 +14,11 @@
  *   handed to the channel exposed then, or held while an exiting modal still
  *   covers everything, and released at its real close; a covered modal is
  *   not written to; a caller inside a modal being presented in this commit
- *   waits one frame for the route. Loaded only by ModalAnnounceProvider, so
+ *   waits one frame for the route. Words move with their announcers'
+ *   receipts, one delivery per announcer, so an announcer can take back its
+ *   own share while it waits wherever it went: a `hasReplace` instance's
+ *   next message (FR9), a busy start overtaken by its outcome (FR8). Loaded
+ *   only by ModalAnnounceProvider, so
  *   a component that calls useAnnounce and renders no modal does not carry
  *   it.
  *
@@ -25,14 +29,18 @@ import {
   announceMessage,
   clearModalRegion,
   clearRegion,
+  forwardWaiting,
+  handleOf,
   installModalRoute,
   isOpenModal,
   modalRegion,
-  unexposedMessages,
-  withdrawFromModalRegion,
+  unexposedWords,
   writeModalRegion,
   type AnnouncePoliteness,
+  type AnnounceReceipt,
   type ModalAnnounceScope,
+  type WaitingWords,
+  type WithdrawAnnouncement,
 } from './useAnnounce';
 
 /**
@@ -153,20 +161,58 @@ function isAnyModalOpen(): boolean {
 // the accessibility tree for its exit but is still an open native modal, or
 // such a dialog covers the channel they would go to, so nothing is exposed
 // yet. They are delivered when a dialog closes (or theirs is exposed again).
-const held = new Map<HTMLDialogElement, Record<AnnouncePoliteness, string[]>>();
+// Each text keeps its announcers' receipts, so one taking its share back
+// leaves it for the others, and a receipt follows the words when they are
+// released; an entry is gone once delivered, so a receipt never reaches
+// equal words held later.
+interface HeldWords extends WaitingWords {
+  readonly receipts: AnnounceReceipt[];
+}
+const held = new Map<
+  HTMLDialogElement,
+  Record<AnnouncePoliteness, HeldWords[]>
+>();
 
+/** Hold `message` for `dialog`, for the announcer `receipt` stands for. */
 function hold(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness,
+  receipt: AnnounceReceipt,
 ): void {
   let slot = held.get(dialog);
   if (slot == null) {
     slot = {polite: [], assertive: []};
     held.set(dialog, slot);
   }
-  if (!slot[politeness].includes(message)) {
-    slot[politeness].push(message);
+  let words = slot[politeness].find(entry => entry.text === message);
+  if (words == null) {
+    words = {text: message, receipts: []};
+    slot[politeness].push(words);
+  }
+  words.receipts.push(receipt);
+  const entry = words;
+  receipt.withdraw = () => dropHeldShare(dialog, politeness, entry, receipt);
+}
+
+/** One announcer takes back its share of `words`, while they are held. */
+function dropHeldShare(
+  dialog: HTMLDialogElement,
+  politeness: AnnouncePoliteness,
+  words: HeldWords,
+  receipt: AnnounceReceipt,
+): void {
+  const slot = held.get(dialog);
+  const at = words.receipts.indexOf(receipt);
+  if (slot == null || !slot[politeness].includes(words) || at < 0) {
+    return;
+  }
+  words.receipts.splice(at, 1);
+  if (words.receipts.length === 0) {
+    slot[politeness] = slot[politeness].filter(entry => entry !== words);
+    if (slot.polite.length === 0 && slot.assertive.length === 0) {
+      held.delete(dialog);
+    }
   }
 }
 
@@ -193,15 +239,13 @@ function releaseHeld(dialog: HTMLDialogElement): void {
   }
   held.delete(dialog);
   for (const politeness of ['polite', 'assertive'] as const) {
-    if (slot[politeness].length > 0) {
-      const message = slot[politeness].join(' ');
-      if (isExposed(dialog)) {
-        announceInModalRouted(dialog, message, politeness);
-      } else {
-        // Holds again if still nothing is exposed.
-        deliverBeyond(dialog, message, politeness);
-      }
-    }
+    // One delivery per announcer, so each receipt follows its words.
+    forwardWaiting(slot[politeness], text =>
+      isExposed(dialog)
+        ? announceInModalRouted(dialog, text, politeness)
+        : // Holds again if still nothing is exposed.
+          deliverBeyond(dialog, text, politeness),
+    );
   }
 }
 
@@ -221,20 +265,20 @@ function deliverBeyond(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   const next = nextExposedChannel(dialog);
   if (next === 'covered' || (next == null && isAnyModalOpen())) {
     // An exiting modal — this one, or one above the next candidate — is
     // still open and covers what is beneath it: nothing is exposed until
     // it closes.
-    hold(dialog, message, politeness);
-    return;
+    const receipt: AnnounceReceipt = {withdraw: null};
+    hold(dialog, message, politeness, receipt);
+    return handleOf(receipt);
   }
   if (next != null) {
-    announceInModalRouted(next, message, politeness);
-    return;
+    return announceInModalRouted(next, message, politeness);
   }
-  announceMessage(message, politeness);
+  return announceMessage(message, politeness);
 }
 
 /**
@@ -245,10 +289,11 @@ function deliverBeyond(
  */
 export function handOffUnexposed(dialog: HTMLDialogElement): void {
   for (const politeness of ['polite', 'assertive'] as const) {
-    const waiting = takeUnexposed(dialog, politeness);
-    if (waiting.length > 0) {
-      deliverBeyond(dialog, waiting.join(' '), politeness);
-    }
+    // One delivery per announcer, so each receipt follows its words and a
+    // `hasReplace` instance's next message can still take its own back.
+    forwardWaiting(takeUnexposed(dialog, politeness), text =>
+      deliverBeyond(dialog, text, politeness),
+    );
   }
 }
 
@@ -267,16 +312,19 @@ function withdrawFromModal(
   dropHeld(dialog, politeness);
 }
 
-/** Take the unexposed messages out of a dialog's region, clearing it. */
+/**
+ * Take the unexposed words out of a dialog's region, with their receipts,
+ * clearing it.
+ */
 function takeUnexposed(
   dialog: HTMLDialogElement,
   politeness: AnnouncePoliteness,
-): string[] {
+): WaitingWords[] {
   const region = modalRegion(dialog, politeness);
   if (region == null) {
     return [];
   }
-  const waiting = unexposedMessages(region);
+  const waiting = unexposedWords(region);
   clearModalRegion(dialog, politeness);
   return waiting;
 }
@@ -285,10 +333,9 @@ function announceInModalRouted(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness = 'polite',
-): void {
+): WithdrawAnnouncement | null {
   if (!isExposed(dialog)) {
-    deliverBeyond(dialog, message, politeness);
-    return;
+    return deliverBeyond(dialog, message, politeness);
   }
   const top = topExposedModal();
   if (top != null && top !== dialog && presented.includes(dialog)) {
@@ -296,35 +343,23 @@ function announceInModalRouted(
     // one closes, and a message announced meanwhile is not heard — the
     // container is clear before this modal is on top again.
     clearModalRegion(dialog, politeness);
-    return;
+    return null;
   }
-  writeModalRegion(dialog, message, politeness, {
+  return writeModalRegion(dialog, message, politeness, {
     isExposed: () => isExposed(dialog),
-    redirect: joined => deliverBeyond(dialog, joined, politeness),
+    redirect: waiting =>
+      forwardWaiting(waiting, text => deliverBeyond(dialog, text, politeness)),
   });
 }
 
-function withdrawFromModalPendingRouted(
-  dialog: HTMLDialogElement,
-  message: string,
-  politeness: AnnouncePoliteness,
-): void {
-  withdrawFromModalRegion(dialog, message, politeness);
-  const slot = held.get(dialog);
-  if (slot != null) {
-    slot[politeness] = slot[politeness].filter(text => text !== message);
-    if (slot.polite.length === 0 && slot.assertive.length === 0) {
-      held.delete(dialog);
-    }
-  }
-}
-
 // Messages from callers whose enclosing modal is being presented in this
 // commit, waiting one frame for the route; an empty message among them
 // withdraws the earlier ones of its urgency, as it would on a channel.
+// Each message keeps a receipt per announcer: before the frame, taking it
+// back drops that announcer's share; the frame points it at its write.
 interface Deferred {
   frame: number;
-  messages: Record<AnnouncePoliteness, string[]>;
+  words: Record<AnnouncePoliteness, HeldWords[]>;
   clears: Record<AnnouncePoliteness, boolean>;
 }
 const deferredByScope = new WeakMap<ModalAnnounceScope, Deferred>();
@@ -333,7 +368,7 @@ function deferUntilPresented(
   scope: ModalAnnounceScope,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   let deferred = deferredByScope.get(scope);
   if (deferred == null) {
     const created: Deferred = {
@@ -348,29 +383,54 @@ function deferUntilPresented(
               clearRegion(urgency);
             }
           }
-          for (const text of created.messages[urgency]) {
-            if (opened != null) {
-              announceInModalRouted(opened, text, urgency);
-            } else {
-              announceMessage(text, urgency);
-            }
-          }
+          // One write per announcer, so each can take back its own share.
+          forwardWaiting(created.words[urgency], text =>
+            opened != null
+              ? announceInModalRouted(opened, text, urgency)
+              : announceMessage(text, urgency),
+          );
         }
       }),
-      messages: {polite: [], assertive: []},
+      words: {polite: [], assertive: []},
       clears: {polite: false, assertive: false},
     };
     deferred = created;
     deferredByScope.set(scope, deferred);
   }
+  const waiting = deferred;
   if (!message) {
-    deferred.messages[politeness] = [];
-    deferred.clears[politeness] = true;
-    return;
+    // Taken back: the receipts of what waited have nothing left to take.
+    for (const words of waiting.words[politeness]) {
+      for (const receipt of words.receipts) {
+        receipt.withdraw = null;
+      }
+    }
+    waiting.words[politeness] = [];
+    waiting.clears[politeness] = true;
+    return null;
   }
-  if (!deferred.messages[politeness].includes(message)) {
-    deferred.messages[politeness].push(message);
+  let words = waiting.words[politeness].find(entry => entry.text === message);
+  if (words == null) {
+    words = {text: message, receipts: []};
+    waiting.words[politeness].push(words);
   }
+  const entry = words;
+  const receipt: AnnounceReceipt = {withdraw: null};
+  receipt.withdraw = () => {
+    // Before the frame: drop this announcer's share of the waiting words.
+    const at = entry.receipts.indexOf(receipt);
+    if (at < 0) {
+      return;
+    }
+    entry.receipts.splice(at, 1);
+    if (entry.receipts.length === 0) {
+      waiting.words[politeness] = waiting.words[politeness].filter(
+        other => other !== entry,
+      );
+    }
+  };
+  entry.receipts.push(receipt);
+  return handleOf(receipt);
 }
 
 /**
@@ -400,7 +460,7 @@ function announceFromScope(
   scope: ModalAnnounceScope,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   if (isBeingPresented(scope)) {
     // Announced in the commit that opens the enclosing modal — a field error
     // inside `{isOpen && <Dialog isOpen>}`, alone or inside an already-open
@@ -411,8 +471,7 @@ function announceFromScope(
     // (FR9). A caller inside a modal that is meant to be closed (its content
     // stays mounted) is not waiting for anything: it takes the route of
     // where it is now, joined with the frame's other messages.
-    deferUntilPresented(scope, message, politeness);
-    return;
+    return deferUntilPresented(scope, message, politeness);
   }
   const dialog = enclosingOpenModal(scope);
   if (!message) {
@@ -423,17 +482,15 @@ function announceFromScope(
     } else {
       clearRegion(politeness);
     }
-    return;
+    return null;
   }
   if (dialog != null) {
-    announceInModalRouted(dialog, message, politeness);
-    return;
+    return announceInModalRouted(dialog, message, politeness);
   }
-  announceMessage(message, politeness);
+  return announceMessage(message, politeness);
 }
 
 installModalRoute({
   announce: announceFromScope,
   announceInModal: announceInModalRouted,
-  withdrawFromModalPending: withdrawFromModalPendingRouted,
 });

package/src/hooks/useAdaptivePresentation.ts

@@ -7,7 +7,10 @@
  * @input Uses React's external-store subscription over window.matchMedia
  *   and the touch presentation's compact-touch query
  * @output Resolves popover/bottom-sheet presentation policy
- * @position Internal overlay policy shared across component families
+ * @position Internal overlay policy shared across component families. A
+ *   component that also switches input modes under a finger resolves its
+ *   `presentation` with usePresentation (utils/presentation.ts), whose
+ *   surface is this one's
  */
 
 import {useCallback, useSyncExternalStore} from 'react';

package/src/hooks/useAnnounce.doc.mjs

@@ -17,14 +17,31 @@ export const docs = {
     'assertive',
     'visually hidden',
     'wcag',
+    'replace',
+    'result count',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseAnnounceOptions',
+      description: 'Configuration object.',
+      required: false,
+    },
+    {
+      name: 'options.hasReplace',
+      type: 'boolean',
+      description:
+        "The instance states one current state, such as a search's result count: each message it writes withdraws the instance's previous message while that one has not been spoken yet, whatever their politeness, and is spoken at its own politeness. A message already spoken stays. Messages from other instances, and from instances without hasReplace, still join. Give each state a component reports its own instance, for example one for the result count and one for selection changes.",
+      default: 'false',
+      required: false,
+    },
   ],
-  params: [],
   returns: [
     {
       name: 'announce',
       type: '(message: string, politeness?: "polite" | "assertive") => void',
       description:
-        'Speaks a message through the live region the caller can be heard from: the shared one on the page body, or, when the calling component is rendered inside an open Astryx modal (Dialog, modal BottomSheet, modal Drawer, Lightbox, MobileNav, CommandPalette), a persistent region inside that modal, since a native modal hides the page-body region from assistive technology. Politeness defaults to "polite"; messages announced in the same frame are joined, in order, into one announcement, and an identical repeat is kept once. An empty message clears any lingering status, including joined messages not yet spoken, instead of announcing.',
+        'Speaks a message through the live region the caller can be heard from: the shared one on the page body, or, when the calling component is rendered inside an open Astryx modal (Dialog, modal BottomSheet, modal Drawer, Lightbox, MobileNav, CommandPalette), a persistent region inside that modal, since a native modal hides the page-body region from assistive technology. Politeness defaults to "polite"; messages announced in the same frame are joined, in order, into one announcement, and an identical repeat is kept once, except that each message from a hasReplace instance replaces the previous message of that instance not yet spoken. An empty message clears any lingering status, including joined messages not yet spoken, instead of announcing.',
     },
   ],
   usage: {
@@ -46,6 +63,11 @@ export const docs = {
         description:
           'Announce the outcome, not the interaction; "12 results" rather than "search ran".',
       },
+      {
+        guidance: true,
+        description:
+          'Send a value that keeps changing, such as a result count as the user types, through its own useAnnounce({hasReplace: true}) instance, so input faster than a frame says only the latest count.',
+      },
       {
         guidance: false,
         description:
@@ -63,9 +85,14 @@ export const docs = {
 export const docsDense = {
   description:
     'Imperative screen-reader announcements via a visually-hidden live region: the page-body one, or one inside the open Astryx modal the caller is rendered in (a native modal hides the body region). Polite + assertive regions created empty on first use + kept mounted, so announcements are reliable (most AT ignore a live region inserted together w/ its content). Messages auto-clear after ~2s.',
+  paramDescriptions: {
+    options: 'config object.',
+    'options.hasReplace':
+      "instance states one current state (e.g. a search's result count): each message withdraws the instance's previous one not yet spoken, whatever politeness, spoken at its own; spoken messages stay; other instances + instances w/o hasReplace still join. Default false.",
+  },
   returnDescriptions: {
     announce:
-      'speaks message through the live region the caller is heard from: page body, or inside the open Astryx modal (Dialog, modal BottomSheet/Drawer, Lightbox, MobileNav, CommandPalette) the calling component is rendered in. politeness defaults "polite"; same-frame messages join in order, identical repeat kept once; empty message clears lingering + not-yet-spoken status.',
+      'speaks message through the live region the caller is heard from: page body, or inside the open Astryx modal (Dialog, modal BottomSheet/Drawer, Lightbox, MobileNav, CommandPalette) the calling component is rendered in. politeness defaults "polite"; same-frame messages join in order, identical repeat kept once, except a hasReplace instance replaces its own not-yet-spoken message; empty message clears lingering + not-yet-spoken status.',
   },
   usage: {
     description:
@@ -86,6 +113,11 @@ export const docsDense = {
         description:
           'Announce outcome, not interaction; "12 results", not "search ran".',
       },
+      {
+        guidance: true,
+        description:
+          'Changing value (result count while typing): own useAnnounce({hasReplace: true}) instance, so faster-than-a-frame input says only the latest.',
+      },
       {
         guidance: false,
         description: