@uniflowed/ui 0.1.0 → 0.3.0

package/table.js

@@ -75,6 +75,7 @@ import {
   withoutComposed,
 } from "./internal/merge-props.js";
 import { useControlled } from "./internal/controlled-state.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
 
 /** Which column a table is sorted by, and which way. */
 export type Sort = {|
@@ -104,19 +105,6 @@ const TableContext: React.Context<TableState | null> = createContext(null);
 /** Whether the rows below are header rows, which decides `th` versus `td`. */
 const HeaderContext: React.Context<boolean> = createContext(false);
 
-const VISUALLY_HIDDEN_STYLE = Object.freeze({
-  border: 0,
-  clip: "rect(0, 0, 0, 0)",
-  clipPath: "inset(50%)",
-  height: 1,
-  margin: -1,
-  overflow: "hidden",
-  padding: 0,
-  position: "absolute",
-  whiteSpace: "nowrap",
-  width: 1,
-});
-
 hook useTable(part: string): TableState {
   const state = useContext(TableContext);
   if (state == null) {
@@ -139,7 +127,7 @@ hook useTable(part: string): TableState {
  * `announceSort` is the wording of the announcement, for an application with a
  * translation table. The default is English.
  */
-export component TableRoot(
+component TableRoot(
   children: React.Node,
   sort?: Sort | null,
   defaultSort?: Sort | null = null,
@@ -222,7 +210,7 @@ export component TableRoot(
         aria-live="polite"
         data-uf-table-status=""
         role="status"
-        style={VISUALLY_HIDDEN_STYLE}
+        style={visuallyHiddenStyle}
       >
         {message}
       </div>
@@ -237,7 +225,7 @@ export component TableRoot(
  * what a screen reader reads when a reader lands on it. A heading above the
  * table looks the same and is not the table's name.
  */
-export component TableCaption(children: React.Node, render?: RenderProp, ...rest: Rest) {
+component TableCaption(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const table = useTable("Table.Caption");
   const register = table.registerCaption;
 
@@ -259,7 +247,7 @@ export component TableCaption(children: React.Node, render?: RenderProp, ...rest
  * It tells the root that it exists, because `aria-rowcount` and every row's
  * `aria-rowindex` count header rows and a table without one counts differently.
  */
-export component TableHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+component TableHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const table = useTable("Table.Header");
   const register = table.registerHeader;
 
@@ -278,7 +266,7 @@ export component TableHeader(children: React.Node, render?: RenderProp, ...rest:
 }
 
 /** The data rows. */
-export component TableBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
+component TableBody(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const props = withProps(rest, { children });
   return (
     <HeaderContext.Provider value={false}>
@@ -303,7 +291,7 @@ export component TableBody(children: React.Node, render?: RenderProp, ...rest: R
  * adding them anyway is a second source of truth that can disagree with the
  * document.
  */
-export component TableRow(
+component TableRow(
   children: React.Node,
   index?: number | null = null,
   render?: RenderProp,
@@ -344,7 +332,7 @@ export component TableRow(
  * Not `"none"` on the others: eleven headers each announcing "not sorted" is
  * eleven announcements of nothing, on every pass through the table.
  */
-export component TableHead(
+component TableHead(
   children: React.Node,
   column?: string | null = null,
   render?: RenderProp,
@@ -407,7 +395,7 @@ export component TableHead(
 }
 
 /** One cell. */
-export component TableCell(children: React.Node, render?: RenderProp, ...rest: Rest) {
+component TableCell(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const props = withProps(rest, { children });
   if (render != null) {
     return render(withProps(props, { role: "cell" }));
@@ -423,7 +411,7 @@ export component TableCell(children: React.Node, render?: RenderProp, ...rest: R
  * moves down the year column. A table of records usually has one and almost
  * never marks it.
  */
-export component TableRowHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
+component TableRowHeader(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const props = withProps(rest, { children, scope: "row" });
   if (render != null) {
     return render(withProps(props, { role: "rowheader" }));
@@ -461,7 +449,7 @@ export component TableRowHeader(children: React.Node, render?: RenderProp, ...re
  * wants a `Checkbox` of their own, which they should write — this part exists
  * for the type of `checked`, not for the markup.
  */
-export component TableSelectAll(
+component TableSelectAll(
   checked: boolean | "mixed",
   onCheckedChange: (checked: boolean) => void,
   label?: string = "Select all rows",
@@ -494,7 +482,7 @@ export component TableSelectAll(
  * Named props rather than `...rest: Rest`, for the reason `Table.SelectAll`
  * gives above.
  */
-export component TableRowSelect(
+component TableRowSelect(
   label: string,
   checked: boolean,
   onCheckedChange: (checked: boolean) => void,
@@ -518,3 +506,25 @@ export component TableRowSelect(
 function defaultAnnouncement(column: string, direction: "ascending" | "descending"): string {
   return `Sorted by ${column}, ${direction}.`;
 }
+
+/**
+ * The parts, under the names the `Table` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as Table from "./table.js"` —
+ * so a caller writes `<Table.Root>`, and the namespace is the prefix. Each
+ * part is still *declared* as `TableRoot`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Root`s.
+ */
+export {
+  TableRoot as Root,
+  TableCaption as Caption,
+  TableHeader as Header,
+  TableBody as Body,
+  TableRow as Row,
+  TableHead as Head,
+  TableRowHeader as RowHeader,
+  TableCell as Cell,
+  TableSelectAll as SelectAll,
+  TableRowSelect as RowSelect,
+};

package/tabs.js

@@ -87,7 +87,7 @@ hook useTabs(part: string): TabsState {
  * distinction every one of these components needs: a form library owns the
  * value, and a page that just wants tabs does not.
  */
-export component TabsRoot(
+component TabsRoot(
   children: React.Node,
   defaultValue: string,
   value?: string,
@@ -145,7 +145,7 @@ export component TabsRoot(
  * tabs push themselves into as they mount answers with mount order, which stops
  * being document order the first time a tab is conditional.
  */
-export component TabsList(children: renders* TabsTab, render?: RenderProp, ...rest: Rest) {
+component TabsList(children: renders* TabsTab, render?: RenderProp, ...rest: Rest) {
   const tabs = useTabs("Tabs.List");
   const props = withProps(withoutComposed(rest, ["onKeyDown"]), {
     // A screen reader announces the axis, and it is also what tells a reader
@@ -186,7 +186,7 @@ export component TabsList(children: renders* TabsTab, render?: RenderProp, ...re
  * the section exists and is unavailable, where a native `disabled` would leave a
  * gap they cannot ask about. The keyboard steps over it either way.
  */
-export component TabsTab(
+component TabsTab(
   value: string,
   children: React.Node,
   disabled?: boolean = false,
@@ -249,12 +249,7 @@ export component TabsTab(
  * subscription rather than "the selected value equals mine", because a caller
  * may render a subset of panels, or none at all until data arrives.
  */
-export component TabsPanel(
-  value: string,
-  children: React.Node,
-  render?: RenderProp,
-  ...rest: Rest
-) {
+component TabsPanel(value: string, children: React.Node, render?: RenderProp, ...rest: Rest) {
   const tabs = useTabs("Tabs.Panel");
   const register = tabs.registerPanel;
   const selected = tabs.selected === value;
@@ -287,3 +282,14 @@ export component TabsPanel(
   }
   return <div {...props} />;
 }
+
+/**
+ * The parts, under the names the `Tabs` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as Tabs from "./tabs.js"` —
+ * so a caller writes `<Tabs.Root>`, and the namespace is the prefix. Each
+ * part is still *declared* as `TabsRoot`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Root`s.
+ */
+export { TabsRoot as Root, TabsList as List, TabsTab as Tab, TabsPanel as Panel };

package/toast.js

@@ -349,7 +349,7 @@ const ToastPartsContext: React.Context<ToastParts | null> = createContext(null);
  * so a `<div>` where a notification belongs is a type error rather than a
  * stack of notifications a reader cannot dismiss.
  */
-export component ToastRegion(
+component ToastRegion(
   children: (notification: Notification) => renders ToastRoot,
   label?: string = "Notifications",
   limit?: number = 3,
@@ -427,7 +427,7 @@ export component ToastRegion(
  * an id that is not in the document makes a screen reader announce nothing at
  * all.
  */
-export component ToastRoot(children: React.Node, ...rest: Rest) {
+component ToastRoot(children: React.Node, ...rest: Rest) {
   const notification = useNotification("Toast.Root");
   const base = useId();
   const elementRef = useElementRef<HTMLElement>();
@@ -499,7 +499,7 @@ export component ToastRoot(children: React.Node, ...rest: Rest) {
 }
 
 /** What the notification is about, and the name of its group. */
-export component ToastTitle(children: React.Node, ...rest: Rest) {
+component ToastTitle(children: React.Node, ...rest: Rest) {
   const parts = useToastParts("Toast.Title");
   useRegistration(parts.registerTitle);
 
@@ -511,7 +511,7 @@ export component ToastTitle(children: React.Node, ...rest: Rest) {
 }
 
 /** The rest of it, and the group's description. */
-export component ToastDescription(children: React.Node, ...rest: Rest) {
+component ToastDescription(children: React.Node, ...rest: Rest) {
   const parts = useToastParts("Toast.Description");
   useRegistration(parts.registerDescription);
 
@@ -532,7 +532,7 @@ export component ToastDescription(children: React.Node, ...rest: Rest) {
  * countdown stopping while focus is inside is what makes the button reachable
  * at all; it is not a promise that four seconds was enough time to decide.
  */
-export component ToastAction(children: React.Node, ...rest: Rest) {
+component ToastAction(children: React.Node, ...rest: Rest) {
   const notification = useNotification("Toast.Action");
   const passed = withoutComposed(rest, ["onClick"]);
 
@@ -561,7 +561,7 @@ export component ToastAction(children: React.Node, ...rest: Rest) {
  * `aria-label` that says "Dismiss" over a button that says "Close" breaks the
  * speech reader who says "click Close" out loud.
  */
-export component ToastClose(children?: React.Node, label?: string = "Dismiss", ...rest: Rest) {
+component ToastClose(children?: React.Node, label?: string = "Dismiss", ...rest: Rest) {
   const notification = useNotification("Toast.Close");
   const passed = withoutComposed(rest, ["onClick"]);
 
@@ -592,3 +592,21 @@ hook useRegistration(register: (present: boolean) => void): void {
     return () => register(false);
   }, [register]);
 }
+
+/**
+ * The parts, under the names the `Toast` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as Toast from "./toast.js"` —
+ * so a caller writes `<Toast.Region>`, and the namespace is the prefix. Each
+ * part is still *declared* as `ToastRegion`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Region`s.
+ */
+export {
+  ToastRegion as Region,
+  ToastRoot as Root,
+  ToastTitle as Title,
+  ToastDescription as Description,
+  ToastAction as Action,
+  ToastClose as Close,
+};

package/toggle-group.js

@@ -70,7 +70,7 @@ import {
 } from "./internal/merge-props.js";
 import { moveOnKey, useFirstItem } from "./internal/roving-focus.js";
 import type { Orientation, RovingSet } from "./internal/roving-focus.js";
-import { RadioGroupItem, RadioGroupRoot } from "./radio-group.js";
+import { Item as RadioGroupItem, Root as RadioGroupRoot } from "./radio-group.js";
 import { useControlled } from "./internal/controlled-state.js";
 
 /** Whether the set holds one answer or any number of them. */
@@ -128,7 +128,7 @@ hook useToggleGroup(part: string): ToggleGroupState {
  * Uncontrolled by default and controlled the moment `value` is passed, like
  * everything else here.
  */
-export component ToggleGroupRoot(
+component ToggleGroupRoot(
   children: renders* ToggleGroupItem,
   type?: ToggleGroupType = "multiple",
   defaultValue?: $ReadOnlyArray<string> = NOTHING,
@@ -224,7 +224,7 @@ export component ToggleGroupRoot(
  * a reader is told the set has two members when it has three and cannot ask
  * where the third went. The arrow keys step over it either way.
  */
-export component ToggleGroupItem(
+component ToggleGroupItem(
   value: string,
   children?: React.Node,
   disabled?: boolean = false,
@@ -282,3 +282,14 @@ export component ToggleGroupItem(
 
   return <button {...itemProps} type="button" />;
 }
+
+/**
+ * The parts, under the names the `ToggleGroup` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as ToggleGroup from "./toggle-group.js"` —
+ * so a caller writes `<ToggleGroup.Root>`, and the namespace is the prefix. Each
+ * part is still *declared* as `ToggleGroupRoot`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Root`s.
+ */
+export { ToggleGroupRoot as Root, ToggleGroupItem as Item };

package/tooltip.js

@@ -150,7 +150,7 @@ hook useTooltip(part: string): TooltipState {
  * Renders no element: it is a context and a clock, and a `<div>` around a
  * toolbar is the caller's business.
  */
-export component TooltipProvider(
+component TooltipProvider(
   children: React.Node,
   delayDuration?: number = DEFAULT_OPEN_DELAY,
   skipDelayDuration?: number = DEFAULT_SKIP_DELAY,
@@ -168,7 +168,7 @@ export component TooltipProvider(
  * `delayDuration`, and to 700ms when there is no provider — a tooltip on its
  * own is a complete tooltip and needs nothing around it.
  */
-export component TooltipRoot(
+component TooltipRoot(
   children: React.Node,
   closeDelay?: number = DEFAULT_CLOSE_DELAY,
   defaultOpen?: boolean = false,
@@ -243,7 +243,7 @@ export component TooltipRoot(
  * `render` function that forgets to spread something still gets a working
  * tooltip; see the module header.
  */
-export component TooltipTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+component TooltipTrigger(children?: React.Node, render?: RenderProp, ...rest: Rest) {
   const tooltip = useTooltip("Tooltip.Trigger");
   const { closeDelay, dismissedRef, intent, openDelay, setOpen, triggerRef } = tooltip;
   useFocusableTrigger(triggerRef, "Tooltip.Trigger");
@@ -320,7 +320,7 @@ export component TooltipTrigger(children?: React.Node, render?: RenderProp, ...r
  * takes focus, holds no tab stop, and answers `Escape` from wherever focus
  * happens to be.
  */
-export component TooltipBody(
+component TooltipBody(
   children: React.Node,
   align?: Align = "center",
   alignOffset?: number = 0,
@@ -389,7 +389,7 @@ export component TooltipBody(
     id: `${tooltip.base}-body`,
     // React calls callback refs during commit; placement effects read it later.
     // uf-lint-disable-next-line react-compiler/refs
-    ref: composeRefs(rest.ref, (element) => {
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
       bodyRef.current = element;
     }),
     role: "tooltip",
@@ -402,3 +402,19 @@ export component TooltipBody(
   }
   return <div {...props} />;
 }
+
+/**
+ * The parts, under the names the `Tooltip` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as Tooltip from "./tooltip.js"` —
+ * so a caller writes `<Tooltip.Provider>`, and the namespace is the prefix. Each
+ * part is still *declared* as `TooltipProvider`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Provider`s.
+ */
+export {
+  TooltipProvider as Provider,
+  TooltipRoot as Root,
+  TooltipTrigger as Trigger,
+  TooltipBody as Body,
+};

package/visually-hidden.js

@@ -0,0 +1,259 @@
+// @flow
+"use client";
+//
+// Text for assistive technology and nobody else, and the announcer built on it.
+//
+// # `VisuallyHidden`
+//
+// `display: none` and `visibility: hidden` take an element out of the
+// accessibility tree as well as off the screen, which is the opposite of what a
+// visually hidden label is for. The style in `internal/visually-hidden-style.js`
+// is the one that survives every engine's accessibility mapping: a one-pixel
+// box, clipped twice (`clip` for the engines that predate `clip-path`), and
+// `white-space: nowrap` so a screen reader's virtual cursor does not read a
+// clipped paragraph one word per line.
+//
+// `focusable` is for the skip link: hidden until a keyboard lands on it, then
+// on screen while focus is anywhere inside, because a focus ring around a
+// one-pixel box is a focus ring nobody can see.
+//
+// # `announce`
+//
+// A live region only announces a *change*, and only when the region was in the
+// document before the change — so a region rendered together with its message
+// says nothing, and a component that renders its own region next to itself has
+// to exist, silent, before the thing it wants to say happens. Every component
+// that did that also put an element in the caller's layout, and three of them
+// (the collections, the range calendar and the segmented fields) left theirs
+// visible, so "3 selected" was printed on the page under the list.
+//
+// `announce()` is one pair of regions for the whole document, created on the
+// first call and kept. It follows React Aria's LiveAnnouncer, and not by
+// accident:
+//
+//   * one `role="log"` region per politeness, since a region's politeness is
+//     read when the region is first seen and cannot be changed on a live one;
+//   * each message is a new child node rather than a new text value, so the
+//     same message twice is announced twice (`aria-relevant="additions"`);
+//   * each message is removed after `timeout`, so a reader who arrives at the
+//     end of the document later does not find a transcript there;
+//   * the first message waits 100 ms after the regions are created, because a
+//     region and its first content inserted together are, again, silent.
+//
+// On the server there is no document and `announce` does nothing; there is
+// nothing to hydrate either, because the regions are never rendered by React.
+
+import * as React from "@uniflowed/react";
+import { useState } from "@uniflowed/react";
+import { composeHandlers, withProps, withoutComposed } from "./internal/merge-props.js";
+import type { RenderProp, Rest } from "./internal/merge-props.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
+
+type FocusEvent = {
+  readonly currentTarget: mixed,
+  readonly relatedTarget: mixed,
+  readonly defaultPrevented: boolean,
+  ...
+};
+
+/**
+ * Content a screen reader reads and a sighted reader does not see.
+ *
+ *     <button><Icon name="trash" /><VisuallyHidden>Delete draft</VisuallyHidden></button>
+ *     <VisuallyHidden focusable render={(props) => <a href="#main" {...props} />}>
+ *       Skip to content
+ *     </VisuallyHidden>
+ *
+ * A caller's `style` is kept, underneath the hiding, so it applies again the
+ * moment a `focusable` one is shown.
+ */
+export component VisuallyHidden(
+  children?: React.Node,
+  /** Show the content while focus is inside it: the skip-link pattern. */
+  focusable: boolean = false,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [focused, setFocused] = useState(false);
+  const style = rest.style;
+  const own = typeof style === "object" && style != null ? style : {};
+  const hidden = !(focusable && focused);
+  const props = withProps(withoutComposed(rest, ["onFocus", "onBlur"]), {
+    children,
+    style: hidden ? { ...own, ...visuallyHiddenStyle } : style,
+    onFocus: composeHandlers(rest.onFocus, () => {
+      if (focusable) setFocused(true);
+    }),
+    onBlur: composeHandlers(rest.onBlur, (event: FocusEvent) => {
+      // Moving between two links inside one skip block is not leaving it.
+      const { currentTarget, relatedTarget } = event;
+      if (
+        currentTarget instanceof Node &&
+        relatedTarget instanceof Node &&
+        currentTarget.contains(relatedTarget)
+      )
+        return;
+      setFocused(false);
+    }),
+  });
+  return render != null ? render(props) : <span {...props} />;
+}
+
+export type Politeness = "polite" | "assertive";
+
+export type AnnounceOptions = {|
+  /**
+   * `"polite"` (the default) waits for the reader to finish; `"assertive"`
+   * interrupts, and is for what cannot wait — an error that stopped a save.
+   */
+  readonly politeness?: Politeness,
+  /** Milliseconds before the message leaves the document. 7000 by default. */
+  readonly timeout?: number,
+|};
+
+type Announcer = {|
+  readonly root: HTMLElement,
+  readonly polite: HTMLElement,
+  readonly assertive: HTMLElement,
+  /** When the regions went into the document; the first message waits for them. */
+  readonly created: number,
+|};
+
+let announcer: Announcer | null = null;
+
+/** Wait this long after creating the regions, so their first content is a change. */
+const SETTLE_MS = 100;
+
+function region(document: Document, politeness: Politeness): HTMLElement {
+  const element = document.createElement("div");
+  element.setAttribute("role", "log");
+  element.setAttribute("aria-live", politeness);
+  element.setAttribute("aria-relevant", "additions");
+  return element;
+}
+
+function announcerIn(document: Document): Announcer | null {
+  const body = document.body;
+  if (body == null) return null;
+  // A test's cleanup, or an app that replaces `<body>`, can take the regions
+  // out; a region that is not in the document announces nothing.
+  if (announcer != null && announcer.root.isConnected && announcer.root.ownerDocument === document)
+    return announcer;
+  const root = document.createElement("div");
+  root.setAttribute("data-uf-live-announcer", "");
+  root.style.cssText =
+    "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;" +
+    "overflow:hidden;clip:rect(0, 0, 0, 0);clip-path:inset(50%);white-space:nowrap";
+  const assertive = region(document, "assertive");
+  const polite = region(document, "polite");
+  root.append(assertive, polite);
+  // A direct child of `<body>`, which is the level a modal's conceal walk
+  // reaches last; `dialog.js` skips it by the attribute above.
+  body.prepend(root);
+  announcer = { root, polite, assertive, created: Date.now() };
+  return announcer;
+}
+
+/**
+ * The timers `announce` has scheduled and not yet run, per politeness, so
+ * `clearAnnouncements` can take back a message that has not arrived yet as
+ * well as one that has.
+ */
+const pending: {| readonly polite: Set<TimeoutID>, readonly assertive: Set<TimeoutID> |} = {
+  polite: new Set(),
+  assertive: new Set(),
+};
+
+/**
+ * Run `work` after `ms`, unless `clearAnnouncements` cancels it first.
+ *
+ * A timer outlives whatever scheduled it: a test worker restores its globals
+ * between files, and an app can unmount, replace `<body>` or tear its window
+ * down, all while a message is still waiting to arrive or to leave. So a timer
+ * never reads the `document` global — `work` is handed the document and
+ * regions captured when the message was announced, and each timer checks they
+ * are still there before touching them.
+ */
+function schedule(politeness: Politeness, ms: number, work: () => void): void {
+  const timers = pending[politeness];
+  const timer: TimeoutID = setTimeout(() => {
+    timers.delete(timer);
+    work();
+  }, ms);
+  timers.add(timer);
+}
+
+/**
+ * Whether `document` is still the document this realm has, and `region` still
+ * in it: the one condition under which a timer may write to either.
+ */
+function stillLive(document: Document, region: HTMLElement): boolean {
+  return (
+    typeof globalThis.document !== "undefined" &&
+    globalThis.document === document &&
+    region.isConnected &&
+    region.ownerDocument === document
+  );
+}
+
+/**
+ * Say something to a screen reader, from anywhere.
+ *
+ *     announce(`${count} results`);
+ *     announce("Could not save the draft", { politeness: "assertive" });
+ *
+ * A function rather than a hook, because what needs announcing comes from
+ * event handlers, effects and `catch` blocks — `toast()` makes the same choice.
+ * An empty message is ignored rather than announced as silence. On the server
+ * it returns before scheduling anything.
+ */
+export function announce(message: string, options?: AnnounceOptions): void {
+  if (message.trim() === "" || typeof document === "undefined") return;
+  // Captured now, and the only document the timers below ever use.
+  const doc = document;
+  const current = announcerIn(doc);
+  if (current == null) return;
+  const politeness = options?.politeness ?? "polite";
+  const timeout = options?.timeout ?? 7000;
+  const target = politeness === "assertive" ? current.assertive : current.polite;
+  const insert = () => {
+    // The document went away (a worker's teardown, an unmounted frame) or the
+    // regions were taken out of it: there is nobody left to tell.
+    if (!stillLive(doc, target)) return;
+    const node = doc.createElement("div");
+    node.textContent = message;
+    target.append(node);
+    if (timeout > 0 && Number.isFinite(timeout))
+      schedule(politeness, timeout, () => {
+        // Removing a detached node is harmless; only a live one needs it.
+        if (node.isConnected) node.remove();
+      });
+  };
+  const wait = current.created + SETTLE_MS - Date.now();
+  if (wait > 0) schedule(politeness, wait, insert);
+  else insert();
+}
+
+/**
+ * Take every message out, for one politeness or both: the ones in the regions
+ * and the ones still waiting to arrive, whose timers are cancelled. After it,
+ * nothing `announce` scheduled for that politeness runs.
+ */
+export function clearAnnouncements(politeness?: Politeness): void {
+  const both: $ReadOnlyArray<Politeness> = ["assertive", "polite"];
+  for (const which of both) {
+    if (politeness != null && politeness !== which) continue;
+    const timers = pending[which];
+    for (const timer of timers) clearTimeout(timer);
+    timers.clear();
+  }
+  const current = announcer;
+  if (current == null) return;
+  // Regions a teardown took out are not reused, and need not be kept alive.
+  if (!current.root.isConnected) {
+    announcer = null;
+    return;
+  }
+  if (politeness !== "polite") current.assertive.replaceChildren();
+  if (politeness !== "assertive") current.polite.replaceChildren();
+}