@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/hooks/useAnnounce.d.ts

@@ -1,3 +1,28 @@
+/**
+ * @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 and AnnouncePoliteness type; 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), 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.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { type RefObject } from 'react';
 /**
  * Announcement urgency:
  * - `'polite'` (default): announced when the screen reader is idle. Use for
@@ -10,6 +35,13 @@ export type AnnouncePoliteness = 'polite' | 'assertive';
  * Imperative screen-reader announcement function.
  */
 export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => void;
+export declare function announceMessage(message: string, politeness: AnnouncePoliteness): void;
+/**
+ * Clear any pending announcement from a region without announcing anything new.
+ * Used when the triggering context goes away (e.g. a search query is cleared),
+ * so stale status text does not linger in the accessibility tree.
+ */
+export declare function clearRegion(politeness: AnnouncePoliteness): void;
 /**
  * Returns an imperative `announce(message, politeness?)` function that speaks a
  * message through a persistently-mounted, visually-hidden live region.
@@ -17,7 +49,8 @@ export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => v
  * The polite and assertive regions are created once on first use and kept
  * mounted, so announcements are reliable even for messages that appear
  * immediately (unlike a live region rendered together with its content).
- * Each message is automatically cleared a couple of seconds after being
+ * Messages announced in the same frame are joined, in order, into one
+ * announcement, and an identical repeat is kept once. Each message is automatically cleared a couple of seconds after being
  * announced, so users browsing the DOM later do not encounter stale status
  * text; announcing again before the clear simply resets the countdown.
  *
@@ -33,6 +66,104 @@ export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => v
  * ```
  */
 export declare function useAnnounce(): AnnounceFn;
+/**
+ * What an Astryx modal tells the hooks beneath it: where its dialog element
+ * is, and the modal above it, so a caller inside a non-modal sheet nested in
+ * a modal still finds the modal.
+ */
+export interface ModalAnnounceScope {
+    dialogRef: RefObject<HTMLDialogElement | null>;
+    isOpen: boolean;
+    parent: ModalAnnounceScope | null;
+}
+export declare const ModalAnnounceContext: import("react").Context<ModalAnnounceScope | null>;
+/** The modal route `modalAnnounce.ts` installs when a provider loads it. */
+export interface ModalRoute {
+    /** `useAnnounce` from inside `scope`: route `message` by where it is. */
+    announce(scope: ModalAnnounceScope, message: string, politeness: AnnouncePoliteness): void;
+    /** Speak inside `dialog` with the exposure, covered and hold rules. */
+    announceInModal(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness): void;
+    /** Withdraw an announcer's share, written or held. */
+    withdrawFromModalPending(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness): void;
+}
+/** Called once by `modalAnnounce.ts` as it loads. @internal */
+export declare function installModalRoute(route: ModalRoute): void;
+/** Whether `dialog` is open as a native modal right now. */
+export declare function isOpenModal(dialog: HTMLDialogElement | null | undefined): boolean;
+/**
+ * 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).
+ */
+export declare function enclosingModalDialog(element: Element | null | undefined): HTMLDialogElement | null;
+/**
+ * Speak `message` through the modal `dialog`'s own live region. With the
+ * modal route loaded (an Astryx modal is in the tree) the route applies its
+ * exposure, covered and hold rules; without it — a native modal an app
+ * renders without Astryx, and no Astryx modal anywhere — the words are
+ * written to the dialog while it is open as a modal, else to the shared
+ * channel. Internal: used by the busy-announcement hook.
+ */
+export declare function announceInModal(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
+/**
+ * Withdraw one announcer's share of `message` from `dialog` before it is
+ * exposed, written to its region or held by the route for the dialog's
+ * close, 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's settle function.
+ */
+export declare function withdrawFromModalPending(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
+/** What the route asks of the writer in the write frame. @internal */
+export interface ModalWriteGuard {
+    isExposed: () => boolean;
+    redirect: (joinedMessage: string) => void;
+}
+/** Words written to `target` that assistive technology has not had yet. */
+export declare function unexposedMessages(target: HTMLElement): string[];
+export declare function modalRegion(dialog: HTMLDialogElement, politeness: AnnouncePoliteness): HTMLElement | null;
+/**
+ * Write `message` to the modal `dialog`'s own live region for `politeness`,
+ * joining it to messages written there that are not yet exposed and saying
+ * an identical repeat once; a holder count per text lets one announcer take
+ * its share back (`withdrawFromModalPending`). The region-writing core,
+ * shared by the full modal route and by the busy-announcement hook's fallback
+ * for a native modal an app renders without Astryx. `guard`, supplied by the
+ * route, re-checks exposure in the write frame and redirects the joined words
+ * when the dialog stopped being exposed meanwhile.
+ */
+export declare function writeModalRegion(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness, guard?: ModalWriteGuard): void;
+/**
+ * Withdraw one announcer's share of `message` from `dialog`'s region before
+ * it is 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). The
+ * message stays while another announcer holds it. The region half of
+ * `withdrawFromModalPending`; the route also drops words it holds for the
+ * dialog's close.
+ */
+export declare function withdrawFromModalRegion(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
+/**
+ * Withdraw whatever the dialog's region for `politeness` holds or is about to
+ * hold, as an empty message does on the shared channel. A dialog that never
+ * announced has no region and nothing to clear.
+ */
+export declare function clearModalRegion(dialog: HTMLDialogElement, politeness: AnnouncePoliteness): void;
+/**
+ * Takes the pending message the latest announce joined, so that announcer can
+ * withdraw its own share of it later. Shared with useBusyAnnouncement; not
+ * exported from the hooks index.
+ *
+ * @internal
+ */
+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).
+ * The message stays while another announcer still holds it.
+ *
+ * @internal
+ */
+export declare function withdrawPendingAnnouncement(joined: object, politeness: AnnouncePoliteness): void;
 /**
  * Test-only helper: removes the singleton live regions and resets state so
  * each test starts clean. Not part of the public runtime API.

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAmBA;;;;;;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;AA+IV;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAaxC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAUhD"}
+{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useAnnounce.js

@@ -4,17 +4,29 @@
 
 /**
  * @file useAnnounce.ts
- * @input Uses React useCallback; DOM APIs and cancellable animation frames for a singleton live-region pair
- * @output Exports useAnnounce hook and AnnouncePoliteness type
- * @position Core a11y hook; provides imperative screen-reader announcements
- *   via persistently-mounted polite/assertive live regions; regions are
- *   auto-cleared shortly after announcing so stale status text does not
- *   linger in the accessibility tree
+ * @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 and AnnouncePoliteness type; 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), 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.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
-import { useCallback } from 'react';
+import { createContext, use, useCallback } from 'react';
 
 /**
  * Announcement urgency:
@@ -51,15 +63,32 @@ function cancelScheduledClear(politeness) {
     clearTimers[politeness] = null;
   }
 }
+
+// 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.
 const pendingFrames = {
-  polite: new Set(),
-  assertive: new Set()
+  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.
+
+const pendingMessages = {
+  polite: [],
+  assertive: []
+};
+// The pending message the latest announce joined, until its announcer takes it.
+let lastJoined = null;
 function cancelPendingFrames(politeness) {
-  for (const frame of pendingFrames[politeness]) {
+  const frame = pendingFrames[politeness];
+  if (frame != null) {
     cancelAnimationFrame(frame);
+    pendingFrames[politeness] = null;
   }
-  pendingFrames[politeness].clear();
+  pendingMessages[politeness] = [];
 }
 function scheduleClear(politeness, target) {
   cancelScheduledClear(politeness);
@@ -105,22 +134,36 @@ function getRegions() {
   };
   return regions;
 }
-function announceMessage(message, politeness) {
+export function announceMessage(message, politeness) {
   const r = getRegions();
   if (!r) {
     return;
   }
   const target = politeness === 'assertive' ? r.assertive : r.polite;
-  // Clearing first guarantees the mutation is observed even when the new
-  // message equals the current text — some AT deduplicate identical content.
-  target.textContent = '';
-  // A microtask/rAF-free re-set in the next frame is more reliable across AT
-  // than an immediate re-set, which can be coalesced with the clear.
-  const frame = requestAnimationFrame(() => {
-    pendingFrames[politeness].delete(frame);
-    target.textContent = message;
-  });
-  pendingFrames[politeness].add(frame);
+  const repeat = pendingMessages[politeness].find(pending => pending.text === message);
+  if (repeat != null) {
+    repeat.holders += 1;
+    lastJoined = repeat;
+    return;
+  }
+  const pending = {
+    text: message,
+    holders: 1
+  };
+  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.
+    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.
+    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).
@@ -132,7 +175,7 @@ function announceMessage(message, politeness) {
  * Used when the triggering context goes away (e.g. a search query is cleared),
  * so stale status text does not linger in the accessibility tree.
  */
-function clearRegion(politeness) {
+export function clearRegion(politeness) {
   cancelPendingFrames(politeness);
   cancelScheduledClear(politeness);
   if (!regions) {
@@ -149,7 +192,8 @@ function clearRegion(politeness) {
  * The polite and assertive regions are created once on first use and kept
  * mounted, so announcements are reliable even for messages that appear
  * immediately (unlike a live region rendered together with its content).
- * Each message is automatically cleared a couple of seconds after being
+ * Messages announced in the same frame are joined, in order, into one
+ * announcement, and an identical repeat is kept once. Each message is automatically cleared a couple of seconds after being
  * announced, so users browsing the DOM later do not encounter stale status
  * text; announcing again before the clear simply resets the countdown.
  *
@@ -165,15 +209,299 @@ function clearRegion(politeness) {
  * ```
  */
 export function useAnnounce() {
+  const modal = use(ModalAnnounceContext);
   return useCallback((message, politeness = 'polite') => {
+    // 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.
+    if (modal != null && modalRoute != null) {
+      modalRoute.announce(modal, message, politeness);
+      return;
+    }
     if (!message) {
-      // An empty message clears any lingering status from the region rather
-      // than announcing nothing — useful when the triggering context ends.
+      // An empty message clears any lingering status from the region,
+      // including messages joined but not yet exposed — useful when the
+      // triggering context ends.
       clearRegion(politeness);
       return;
     }
     announceMessage(message, politeness);
-  }, []);
+  }, [modal]);
+}
+
+// =============================================================================
+// Inside an Astryx modal (spec: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.
+
+const MODAL_REGION_ATTR = 'data-astryx-modal-live-region';
+
+/**
+ * What an Astryx modal tells the hooks beneath it: where its dialog element
+ * is, and the modal above it, so a caller inside a non-modal sheet nested in
+ * a modal still finds the modal.
+ */
+
+export const ModalAnnounceContext = /*#__PURE__*/createContext(null);
+ModalAnnounceContext.displayName = 'ModalAnnounceContext';
+
+/** The modal route `modalAnnounce.ts` installs when a provider loads it. */
+
+let modalRoute = null;
+
+/** Called once by `modalAnnounce.ts` as it loads. @internal */
+export function installModalRoute(route) {
+  modalRoute = route;
+}
+
+/** Whether `dialog` is open as a native modal right now. */
+export function isOpenModal(dialog) {
+  return dialog != null && dialog.open && dialog.matches(':modal');
+}
+
+/**
+ * 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).
+ */
+export function enclosingModalDialog(element) {
+  let dialog = element?.closest('dialog') ?? null;
+  while (dialog != null) {
+    if (isOpenModal(dialog)) {
+      return dialog;
+    }
+    dialog = dialog.parentElement?.closest('dialog') ?? null;
+  }
+  return null;
+}
+
+/**
+ * Speak `message` through the modal `dialog`'s own live region. With the
+ * modal route loaded (an Astryx modal is in the tree) the route applies its
+ * exposure, covered and hold rules; without it — a native modal an app
+ * renders without Astryx, and no Astryx modal anywhere — the words are
+ * written to the dialog while it is open as a modal, else to the shared
+ * channel. Internal: used by the busy-announcement hook.
+ */
+export function announceInModal(dialog, message, politeness = 'polite') {
+  if (modalRoute != null) {
+    modalRoute.announceInModal(dialog, message, politeness);
+    return;
+  }
+  if (isOpenModal(dialog)) {
+    writeModalRegion(dialog, message, politeness);
+  } else {
+    announceMessage(message, politeness);
+  }
+}
+
+/**
+ * Withdraw one announcer's share of `message` from `dialog` before it is
+ * exposed, written to its region or held by the route for the dialog's
+ * close, 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's settle function.
+ */
+export function withdrawFromModalPending(dialog, message, politeness = 'polite') {
+  if (modalRoute != null) {
+    modalRoute.withdrawFromModalPending(dialog, message, politeness);
+    return;
+  }
+  withdrawFromModalRegion(dialog, message, politeness);
+}
+
+/** 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.
+
+const pendingByRegion = new WeakMap();
+function cancelPending(pending) {
+  if (pending.frame != null) {
+    cancelAnimationFrame(pending.frame);
+  }
+  if (pending.settleFrame != null) {
+    cancelAnimationFrame(pending.settleFrame);
+  }
+  if (pending.timer != null) {
+    clearTimeout(pending.timer);
+  }
+}
+
+/** Words written to `target` that assistive technology has not had yet. */
+export function unexposedMessages(target) {
+  const pending = pendingByRegion.get(target);
+  if (pending == null) {
+    return [];
+  }
+  return pending.frame != null || pending.settleFrame != null ? pending.messages : [];
+}
+export function modalRegion(dialog, politeness) {
+  return dialog.querySelector(`:scope > [${MODAL_REGION_ATTR}="${politeness}"]`);
+}
+
+/**
+ * The dialog's own live region for one urgency, created empty on first use
+ * and kept as a direct child of the dialog so it survives the dialog's
+ * content re-rendering.
+ */
+function ensureModalRegion(dialog, politeness) {
+  let region = modalRegion(dialog, politeness);
+  if (region == null) {
+    region = document.createElement('div');
+    region.setAttribute(MODAL_REGION_ATTR, politeness);
+    region.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+    region.setAttribute('aria-live', politeness);
+    region.setAttribute('aria-atomic', 'true');
+    region.style.cssText = VISUALLY_HIDDEN_CSS;
+    dialog.appendChild(region);
+  }
+  return region;
+}
+
+/**
+ * Write `message` to the modal `dialog`'s own live region for `politeness`,
+ * joining it to messages written there that are not yet exposed and saying
+ * an identical repeat once; a holder count per text lets one announcer take
+ * its share back (`withdrawFromModalPending`). The region-writing core,
+ * shared by the full modal route and by the busy-announcement hook's fallback
+ * for a native modal an app renders without Astryx. `guard`, supplied by the
+ * route, re-checks exposure in the write frame and redirects the joined words
+ * when the dialog stopped being exposed meanwhile.
+ */
+export function writeModalRegion(dialog, message, politeness, guard) {
+  const target = ensureModalRegion(dialog, politeness);
+  const unexposed = unexposedMessages(target);
+  const messages = unexposed.includes(message) ? unexposed : [...unexposed, message];
+  const previous = pendingByRegion.get(target);
+  const holders = new Map(unexposed.length > 0 && previous != null ? previous.holders : []);
+  holders.set(message, (holders.get(message) ?? 0) + 1);
+  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.
+  target.textContent = '';
+  const pending = {
+    messages,
+    holders,
+    frame: null,
+    settleFrame: null,
+    timer: null
+  };
+  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.
+      pendingByRegion.delete(target);
+      guard.redirect(pending.messages.join(' '));
+      return;
+    }
+    target.textContent = pending.messages.join(' ');
+    pending.settleFrame = requestAnimationFrame(() => {
+      pending.settleFrame = null;
+    });
+    pending.timer = setTimeout(() => {
+      target.textContent = '';
+      pendingByRegion.delete(target);
+    }, CLEAR_DELAY_MS);
+  });
+  pendingByRegion.set(target, pending);
+}
+
+/**
+ * Withdraw one announcer's share of `message` from `dialog`'s region before
+ * it is 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). The
+ * message stays while another announcer holds it. The region half of
+ * `withdrawFromModalPending`; the route also drops words it holds for the
+ * dialog's close.
+ */
+export function withdrawFromModalRegion(dialog, message, politeness = 'polite') {
+  const region = modalRegion(dialog, politeness);
+  const pending = region == null ? undefined : pendingByRegion.get(region);
+  if (region != null && pending != null && (pending.frame != null || pending.settleFrame != null)) {
+    const count = pending.holders.get(message) ?? 0;
+    if (count > 1) {
+      pending.holders.set(message, count - 1);
+    } else if (count === 1) {
+      pending.holders.delete(message);
+      pending.messages = pending.messages.filter(text => text !== message);
+      if (pending.messages.length === 0) {
+        cancelPending(pending);
+        pendingByRegion.delete(region);
+        region.textContent = '';
+      } else if (pending.frame == null) {
+        // Already written this frame, not yet taken: show the rest.
+        region.textContent = pending.messages.join(' ');
+      }
+    }
+  }
+}
+
+/**
+ * Withdraw whatever the dialog's region for `politeness` holds or is about to
+ * hold, as an empty message does on the shared channel. A dialog that never
+ * announced has no region and nothing to clear.
+ */
+export function clearModalRegion(dialog, politeness) {
+  const region = modalRegion(dialog, politeness);
+  if (region == null) {
+    return;
+  }
+  const pending = pendingByRegion.get(region);
+  if (pending != null) {
+    cancelPending(pending);
+    pendingByRegion.delete(region);
+  }
+  region.textContent = '';
+}
+
+/**
+ * Takes the pending message the latest announce joined, so that announcer can
+ * withdraw its own share of it later. Shared with useBusyAnnouncement; not
+ * exported from the hooks index.
+ *
+ * @internal
+ */
+export function takeJoinedAnnouncement() {
+  const joined = lastJoined;
+  lastJoined = null;
+  return joined;
+}
+
+/**
+ * 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).
+ * The message stays while another announcer still holds it.
+ *
+ * @internal
+ */
+export function withdrawPendingAnnouncement(joined, politeness) {
+  const pending = pendingMessages[politeness];
+  const index = pending.indexOf(joined);
+  if (index < 0) {
+    return;
+  }
+  pending[index].holders -= 1;
+  if (pending[index].holders <= 0) {
+    pending.splice(index, 1);
+  }
 }
 
 /**
@@ -187,6 +515,7 @@ export function __resetLiveRegionsForTest() {
   cancelPendingFrames('assertive');
   cancelScheduledClear('polite');
   cancelScheduledClear('assertive');
+  lastJoined = null;
   if (regions) {
     regions.polite.remove();
     regions.assertive.remove();

package/dist/hooks/useAnnounceRenderedText.d.ts

@@ -28,7 +28,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.
@@ -39,6 +39,23 @@
  * admission. Import it by path from inside the package.
  */
 import { type RefObject } from 'react';
+import { 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).
+     */
+    skipFirstRender?: boolean;
+    /**
+     * The channel's urgency: errors and time-critical failures are assertive,
+     * every other message polite (`spec:AST-086` FR5). Defaults to polite.
+     */
+    politeness?: AnnouncePoliteness;
+}
+/** The rendered text an assistive technology would read from `element`. */
+export declare function renderedText(element: HTMLElement): string;
 /**
  * Announce the text of a rendered element through the shared polite live
  * region, once per occasion.
@@ -59,5 +76,5 @@ import { type RefObject } from 'react';
  * useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
  * ```
  */
-export declare function useAnnounceRenderedText(ref: RefObject<HTMLElement | null>, isShown: boolean, occasion: string): void;
+export declare function useAnnounceRenderedText(ref: RefObject<HTMLElement | null>, isShown: boolean, occasion: string, { skipFirstRender, politeness, }?: AnnounceRenderedTextOptions): void;
 //# sourceMappingURL=useAnnounceRenderedText.d.ts.map

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,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAcxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI,CA+BN"}
+{"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,EAAc,KAAK,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAgCnE,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;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,GACtB,GAAE,2BAAgC,GAClC,IAAI,CAqDN"}