@uniflowed/ui 0.1.0 → 0.2.0

package/calendar.js

@@ -77,6 +77,7 @@ import {
   withoutComposed,
 } from "./internal/merge-props.js";
 import { directionOf } from "./internal/roving-focus.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
 import {
   firstDayOfWeekFor,
   moveDate,
@@ -321,7 +322,16 @@ export component CalendarRoot(
     <CalendarContext.Provider value={state}>
       <div {...rest}>
         {children}
-        <div aria-atomic="true" aria-live="polite" id={`${base}-status`} role="status">
+        {/* Heard and not drawn: the caption above the grid already shows the
+            month, and a second copy under it is what a sighted reader would
+            otherwise see after the first page. */}
+        <div
+          aria-atomic="true"
+          aria-live="polite"
+          id={`${base}-status`}
+          role="status"
+          style={visuallyHiddenStyle}
+        >
           {announcement}
         </div>
       </div>
@@ -343,7 +353,14 @@ export component CalendarRoot(
  * with a dot under it for an appointment is a `Calendar.Day` with a child, not a
  * fork of this component. Omitted, every day renders its own number.
  */
-export component CalendarMonth(children?: (date: PlainDate) => renders CalendarDay, ...rest: Rest) {
+export component CalendarMonth(
+  /** A class for the `<caption>`, which this part renders itself. */
+  captionClassName?: string,
+  children?: (date: PlainDate) => renders CalendarDay,
+  /** A class for each weekday heading, which this part renders itself. */
+  columnHeaderClassName?: string,
+  ...rest: Rest
+) {
   const calendar = useCalendar("Calendar.Month");
   const gridRef = useRef<HTMLElement | null>(null);
   const { focused, focusedDayRef, moveFocus, pendingFocusRef, weekStartsOn } = calendar;
@@ -406,7 +423,9 @@ export component CalendarMonth(children?: (date: PlainDate) => renders CalendarD
       })}
       role="grid"
     >
-      <caption id={`${calendar.base}-caption`}>{calendar.caption}</caption>
+      <caption className={captionClassName} id={`${calendar.base}-caption`}>
+        {calendar.caption}
+      </caption>
       <thead>
         <tr>
           {columns.map((day) => (
@@ -416,6 +435,7 @@ export component CalendarMonth(children?: (date: PlainDate) => renders CalendarD
               // header. `aria-label` wins over the contents for the announced
               // name, so a reader still hears "Wednesday" rather than "Wed".
               aria-label={day.toLocaleString(calendar.locale, COLUMN_FORMAT)}
+              className={columnHeaderClassName}
               key={day.dayOfWeek}
               scope="col"
             >
@@ -463,9 +483,14 @@ export component CalendarMonth(children?: (date: PlainDate) => renders CalendarD
 export component CalendarDay(date: PlainDate, children?: React.Node, ...rest: Rest) {
   const calendar = useCalendar("Calendar.Day");
   const disabled = calendar.isDisabled(date);
-  const chosen =
-    calendar.isDateSelected?.(date) ??
-    (calendar.selected != null && calendar.selected.equals(date));
+  const isChosen = (day: PlainDate) =>
+    calendar.isDateSelected?.(day) ?? (calendar.selected != null && calendar.selected.equals(day));
+  const chosen = isChosen(date);
+  // Where a run of chosen days opens and closes, for a stylesheet to round the
+  // ends of a range and join its middle. Markup only: nothing reads it, and a
+  // single chosen day is a run that opens and closes on itself.
+  const opensRun = chosen && !isChosen(date.subtract({ days: 1 }));
+  const closesRun = chosen && !isChosen(date.add({ days: 1 }));
   const passed = withoutComposed(rest, ["onClick", "onFocus", "onKeyDown"]);
 
   return (
@@ -481,6 +506,8 @@ export component CalendarDay(date: PlainDate, children?: React.Node, ...rest: Re
       // makes a screen reader announce "not selected" on all thirty-one.
       aria-selected={chosen ? "true" : undefined}
       data-date={date.toString()}
+      data-selection-end={closesRun ? "true" : undefined}
+      data-selection-start={opensRun ? "true" : undefined}
       onClick={composeHandlers(rest.onClick, () => calendar.select(date))}
       // The tab stop follows real focus, which is the half of a roving set that
       // is easy to leave out and impossible to see. A press on an *unavailable*

package/dialog.js

@@ -471,6 +471,11 @@ export component DialogClose(children: React.Node, render?: RenderProp, ...rest:
  * hiding body's children would hide nothing new and the outer dialog's own
  * content would stay readable behind the inner one.
  *
+ * The one sibling left alone is the live announcer `visually-hidden.js`
+ * creates, which lives in `<body>` and would otherwise go silent for as long as
+ * any dialog is open. React Aria's `ariaHideOutside` keeps its announcer for the
+ * same reason.
+ *
  * Both attributes, because they address different audiences. `aria-hidden`
  * removes the subtree from the accessibility tree; `inert` also stops clicks
  * and takes it out of the tab order, which is the browser's own enforcement of
@@ -488,7 +493,9 @@ function concealOutside(element: HTMLElement): () => void {
       break;
     }
     for (const sibling of Array.from(parent.children)) {
-      if (sibling === node) {
+      // `announce()`'s regions stay readable: a message about what the dialog
+      // just did ("Saved", "3 results") is exactly what a modal needs to say.
+      if (sibling === node || sibling.hasAttribute("data-uf-live-announcer")) {
         continue;
       }
       restore.push({

package/index.js

@@ -1872,3 +1872,21 @@ export {
 } from "./date-range-picker.js";
 export type { Locale } from "./i18n-provider.js";
 export { startsWithLocale } from "./i18n-provider.js";
+
+/**
+ * For a screen reader and nobody else.
+ *
+ * `VisuallyHidden` is text that stays in the accessibility tree and off the
+ * screen — an icon button's name, a skip link (`focusable`) that appears when a
+ * keyboard reaches it. `announce` says something through one pair of live
+ * regions shared by the whole document, from an event handler, an effect or a
+ * `catch`, without the caller rendering a region of their own:
+ *
+ *     announce(`${results.length} results`);
+ *     announce("Could not save", { politeness: "assertive" });
+ *
+ * `visually-hidden.js` says why a region rendered with its message is silent,
+ * and why these regions stay readable while a dialog hides the rest of the page.
+ */
+export { VisuallyHidden, announce, clearAnnouncements } from "./visually-hidden.js";
+export type { AnnounceOptions, Politeness } from "./visually-hidden.js";

package/internal/collection.js

@@ -1,5 +1,34 @@
 // @flow
 "use client";
+//
+// The one collection behind `ListBox`, `GridList`, `Tree` and `TagGroup`.
+//
+// Focus stays on the collection element and `aria-activedescendant` names the
+// active row, so a virtualised list of 10,000 rows needs only the rows in view
+// plus the active one in the document. What a gesture does to the selection is
+// `selection.js`'s answer; this file maps keys and pointers onto those answers
+// and keeps the anchor a Shift range grows from.
+//
+// The keyboard map (WAI-ARIA APG listbox, grid and tree patterns, with React
+// Aria's selection manager for the parts the APG leaves open):
+//
+//   ArrowUp/ArrowDown     previous/next row (TagGroup: also Left/Right,
+//                         mirrored in right-to-left text)
+//   Home/End              first/last row; End also asks for more rows
+//   PageUp/PageDown       a viewport's worth of rows
+//   Shift + any of those  extend the selection from the anchor
+//   Ctrl/Cmd + any        move without selecting (`selectionBehavior="replace"`)
+//   Space                 select (toggle or replace, per `selectionBehavior`)
+//   Ctrl/Cmd+Space        toggle one row — or lift it, when `onReorder` is set
+//   Enter                 `onAction`, or select when there is none
+//   Ctrl/Cmd+A            select every enabled row
+//   Escape                clear the selection (`escapeKeyBehavior`)
+//   Tree: Right/Left      expand, enter; collapse, go to parent (mirrored)
+//   Tree: *               expand every sibling of the active row
+//   printable characters  locale-collated typeahead
+//
+// The Escape key is only claimed when it cleared something, so a collection
+// inside a popover still lets the popover close on the Escape that follows.
 
 import * as React from "@uniflowed/react";
 import { useId, useRef, useState } from "@uniflowed/react";
@@ -7,9 +36,12 @@ import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 import { useDragAndDrop } from "../drag-drop.js";
 import { useControlled } from "./controlled-state.js";
 import { composeHandlers, composeRefs, withProps } from "./merge-props.js";
-import type { RenderProp, Rest } from "./merge-props.js";
+import type { PartEvent, RenderProp } from "./merge-props.js";
 import { directionOf } from "./roving-focus.js";
+import { clearAll, extendTo, orderedKeys, replaceWith, selectAll, toggleKey } from "./selection.js";
+import type { SelectionBehavior, SelectionMode, SelectionPolicy } from "./selection.js";
 import { startsWithLocale, useLocale } from "../i18n-provider.js";
+import { visuallyHiddenStyle } from "./visually-hidden-style.js";
 
 export type CollectionItem = {
   readonly key: string,
@@ -32,9 +64,32 @@ type Entry = {
 };
 type Kind = "listbox" | "grid" | "tree" | "tags";
 
+/**
+ * What a row's click handler reads.
+ *
+ * `detail` is the click count: `0` for a click no pointer made — a screen
+ * reader's activation, or `element.click()` — which React Aria calls a virtual
+ * click. `nativeEvent` is read for `pointerType`, which a browser puts on the
+ * `PointerEvent` a click is and happy-dom and older engines leave off.
+ */
+type RowClick = {
+  readonly detail: number,
+  readonly ctrlKey: boolean,
+  readonly metaKey: boolean,
+  readonly shiftKey: boolean,
+  readonly nativeEvent: mixed,
+  readonly stopPropagation: () => mixed,
+  ...
+};
+
+type Scroll = { readonly currentTarget: mixed, readonly defaultPrevented: boolean, ... };
+
+/** What the collection's key handler reads: `PartEvent` plus the element the key came from. */
+type KeyEvent = { ...PartEvent, readonly target: mixed, ... };
+
 function entries(
   items: $ReadOnlyArray<CollectionItem>,
-  expanded: $ReadOnlyArray<string>,
+  expanded: $ReadOnlySet<string>,
   tree: boolean,
 ): Array<Entry> {
   const result = [];
@@ -49,23 +104,39 @@ function entries(
       seen.add(item.key);
       result.push({ item, level, parent, position: index + 1, count: siblings.length });
       const children = item.children;
-      if (tree && children != null && expanded.includes(item.key))
-        visit(children, level + 1, item.key);
+      if (tree && children != null && expanded.has(item.key)) visit(children, level + 1, item.key);
     });
   };
   visit(items, 1, null);
   return result;
 }
 
+/**
+ * A touch or a virtual click toggles even under `selectionBehavior="replace"`.
+ *
+ * There is no Ctrl key on a phone and no modifier on a screen reader's
+ * activation, so a replace-only rule would leave both able to choose one row
+ * and never two. React Aria draws the same line.
+ */
+function togglesByPointer(event: RowClick): boolean {
+  if (event.detail === 0) return true;
+  const native = event.nativeEvent;
+  return typeof native === "object" && native != null && native.pointerType === "touch";
+}
+
 /** Data owns order and identity. Only visible tree descendants and virtual rows enter the DOM. */
 export component CollectionRoot(kind: Kind, options: CollectionProps) {
   const {
     items,
     children,
     selectionMode: requestedSelectionMode = "single",
+    selectionBehavior = "toggle",
+    disallowEmptySelection = false,
+    escapeKeyBehavior = "clearSelection",
     selectedKeys,
     defaultSelectedKeys = [],
     onSelectionChange,
+    onAction,
     disabledKeys = [],
     expandedKeys,
     defaultExpandedKeys = [],
@@ -80,13 +151,21 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
     render,
     ...rest
   } = options;
-  const selectionMode = kind === "tags" ? "none" : requestedSelectionMode;
+  const mode: SelectionMode = kind === "tags" ? "none" : requestedSelectionMode;
+  const policy: SelectionPolicy = {
+    mode,
+    behavior: selectionBehavior,
+    disallowEmpty: disallowEmptySelection,
+  };
   if (height <= 0 || rowHeight <= 0 || !Number.isFinite(height) || !Number.isFinite(rowHeight))
     throw new RangeError("Collection dimensions must be positive finite numbers");
   const { locale } = useLocale();
   const id = useId();
   const root = useRef<HTMLElement | null>(null);
+  // Where a Shift range starts (`anchor`) and where the last one ended (`lead`).
+  // Written only by event handlers, never read during render.
   const anchor = useRef<string | null>(null);
+  const lead = useRef<string | null>(null);
   const buffer = useRef({ text: "", time: 0 });
   const [selected, setSelected] = useControlled(
     selectedKeys,
@@ -101,60 +180,61 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
   const [active, setActive] = useState<string | null>(null);
   const [scrollTop, setScrollTop] = useState(0);
   const [announcement, announce] = useState("");
+  // Sets, because every row asks "am I selected, am I disabled" on every render
+  // and a 10,000-row collection with everything selected made that 10⁸
+  // comparisons as arrays.
+  // The React Compiler keeps each of these until its input changes.
+  const selectedSet = new Set(selected);
+  const disabledSet = new Set(disabledKeys);
+  const expandedSet = new Set(expanded);
+  const rows = entries(items, expandedSet, kind === "tree");
+  const disabled = (item: CollectionItem) => item.disabled === true || disabledSet.has(item.key);
+  const enabled = rows.filter((row) => !disabled(row.item));
+  const order = enabled.map((row) => row.item.key);
   const drag = useDragAndDrop({
     disabled: onReorder == null,
     onDrop: ({ keys, target }) => {
       const moving = keys[0];
-      if (
-        [moving, target].some(
-          (key) => disabledKeys.includes(key) || items.find((item) => item.key === key)?.disabled,
-        )
-      )
-        return;
-      if (
-        moving === target ||
-        !items.some((item) => item.key === moving) ||
-        !items.some((item) => item.key === target)
-      )
-        return;
+      const byKey = (key: string) => items.find((item) => item.key === key);
+      const from = byKey(moving);
+      const to = byKey(target);
+      if (from == null || to == null || moving === target || disabled(from) || disabled(to)) return;
       const ordered = items.filter((item) => item.key !== moving).map((item) => item.key);
       ordered.splice(ordered.indexOf(target), 0, moving);
       onReorder?.(ordered);
     },
   });
-  const rows = entries(items, expanded, kind === "tree");
-  const disabled = (item: CollectionItem) =>
-    item.disabled === true || disabledKeys.includes(item.key);
-  const enabled = rows.filter((row) => !disabled(row.item));
   const focused =
     enabled.find((row) => row.item.key === active) ??
-    enabled.find((row) => selected.includes(row.item.key)) ??
+    enabled.find((row) => selectedSet.has(row.item.key)) ??
     enabled[0];
   const activeKey = focused?.item.key;
-  const choose = (key: string, range: boolean, toggle: boolean) => {
-    const item = rows.find((row) => row.item.key === key)?.item;
-    if (item == null || disabled(item) || selectionMode === "none") return;
-    let next;
-    if (selectionMode === "single") next = [key];
-    else if (range && anchor.current != null) {
-      const from = enabled.findIndex((row) => row.item.key === anchor.current);
-      const to = enabled.findIndex((row) => row.item.key === key);
-      next = enabled
-        .slice(Math.min(Math.max(from, 0), to), Math.max(from, to) + 1)
-        .map((row) => row.item.key);
-    } else {
-      next = toggle
-        ? selected.includes(key)
-          ? selected.filter((each) => each !== key)
-          : [...selected, key]
-        : [key];
-      anchor.current = key;
-    }
-    setSelected(next);
-    announce(`${next.length} selected`);
+
+  /** Report a selection, unless the gesture changed nothing. */
+  const commit = (next: $ReadOnlySet<string>) => {
+    if (next === selectedSet) return;
+    const keys = orderedKeys(next, order);
+    setSelected(keys);
+    announce(`${keys.length} selected`);
   };
-  const land = (row: Entry, shift: boolean) => {
-    setActive(row.item.key);
+  /** A plain or Ctrl/Cmd gesture on one row: toggle or replace, and move the anchor. */
+  const selectOne = (key: string, toggle: boolean) => {
+    if (mode === "none") return;
+    commit(
+      toggle || selectionBehavior === "toggle"
+        ? toggleKey(policy, selectedSet, key)
+        : replaceWith(policy, selectedSet, key),
+    );
+    anchor.current = key;
+    lead.current = key;
+  };
+  /** A Shift gesture: grow from the anchor, which is the active row if nothing set one. */
+  const extend = (key: string, from: string | void) => {
+    if (anchor.current == null || !order.includes(anchor.current)) anchor.current = from ?? key;
+    commit(extendTo(policy, selectedSet, order, anchor.current, lead.current, key));
+    lead.current = key;
+  };
+  const scrollTo = (row: Entry) => {
     const container = root.current;
     if (virtualized && container != null) {
       const top = rows.indexOf(row) * rowHeight;
@@ -163,7 +243,33 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
         setScrollTop(top);
       }
     }
-    if (shift) choose(row.item.key, true, false);
+  };
+  /** Move the active row, and select the way the modifiers ask. */
+  const land = (
+    row: Entry,
+    event: {
+      readonly shiftKey: boolean,
+      readonly ctrlKey: boolean,
+      readonly metaKey: boolean,
+      ...
+    },
+  ) => {
+    const previous = activeKey;
+    setActive(row.item.key);
+    scrollTo(row);
+    if (mode === "none") return;
+    if (event.shiftKey && mode === "multiple") extend(row.item.key, previous);
+    else if (selectionBehavior === "replace" && !event.ctrlKey && !event.metaKey)
+      selectOne(row.item.key, false);
+  };
+  /** Rows per PageUp/PageDown: the viewport over one row, or ten when nothing is laid out. */
+  const pageSize = (): number => {
+    if (virtualized) return Math.max(1, Math.floor(height / rowHeight));
+    const container = root.current;
+    const row = container?.querySelector("[data-key]");
+    if (container != null && row instanceof HTMLElement && row.offsetHeight > 0)
+      return Math.max(1, Math.floor(container.clientHeight / row.offsetHeight));
+    return 10;
   };
   const remove = (key: string) => {
     const at = enabled.findIndex((row) => row.item.key === key);
@@ -172,12 +278,16 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
     setActive(enabled[at + 1]?.item.key ?? enabled[at - 1]?.item.key ?? null);
     announce(`Removed ${enabled[at].item.textValue}`);
   };
-  const keydown = useStableCallback((event: $FlowFixMe) => {
+  const keydown = useStableCallback((event: KeyEvent) => {
+    const { target, currentTarget } = event;
+    if (!(currentTarget instanceof HTMLElement)) return;
     if (
-      event.target !== event.currentTarget &&
-      event.target.closest("button,input,textarea,select")
+      target !== currentTarget &&
+      target instanceof Element &&
+      target.closest("button,input,textarea,select") != null
     )
       return;
+    const modifier = event.ctrlKey || event.metaKey;
     if (drag.dragging && event.key === "Escape") {
       event.preventDefault();
       drag.cancel();
@@ -188,48 +298,62 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
       drag.drop(activeKey, undefined, focused?.item.textValue);
       return;
     }
-    if (
-      onReorder != null &&
-      event.key === " " &&
-      (event.ctrlKey || event.metaKey) &&
-      focused != null
-    ) {
+    if (onReorder != null && event.key === " " && modifier && focused != null) {
       event.preventDefault();
       drag.start(focused.item.key, focused.item.textValue);
       return;
     }
+    const rtl = directionOf(currentTarget) === "rtl";
+    const inline = kind === "tags";
+    const forward =
+      event.key === "ArrowDown" || (inline && event.key === (rtl ? "ArrowLeft" : "ArrowRight"));
+    const backward =
+      event.key === "ArrowUp" || (inline && event.key === (rtl ? "ArrowRight" : "ArrowLeft"));
     const at = enabled.findIndex((row) => row.item.key === activeKey);
     let next = null;
-    if (event.key === "ArrowDown") next = enabled[Math.min(at + 1, enabled.length - 1)];
-    else if (event.key === "ArrowUp") next = enabled[Math.max(at - 1, 0)];
+    if (forward) next = enabled[Math.min(at + 1, enabled.length - 1)];
+    else if (backward) next = enabled[Math.max(at - 1, 0)];
     else if (event.key === "Home") next = enabled[0];
     else if (event.key === "End") {
       next = enabled[enabled.length - 1];
       if (!loading) onLoadMore?.();
+    } else if (event.key === "PageDown")
+      next = enabled[Math.min(Math.max(at, 0) + pageSize(), enabled.length - 1)];
+    else if (event.key === "PageUp") next = enabled[Math.max(at - pageSize(), 0)];
+    else if (kind === "tree" && focused != null && event.key === "*") {
+      const siblings = rows.filter(
+        (row) => row.parent === focused.parent && (row.item.children?.length ?? 0) > 0,
+      );
+      const missing = siblings.map((row) => row.item.key).filter((key) => !expandedSet.has(key));
+      if (missing.length > 0) setExpanded([...expanded, ...missing]);
     } else if (
       kind === "tree" &&
       focused != null &&
-      ["ArrowLeft", "ArrowRight"].includes(event.key)
+      (event.key === "ArrowLeft" || event.key === "ArrowRight")
     ) {
-      const open =
-        event.key === (directionOf(event.currentTarget) === "rtl" ? "ArrowLeft" : "ArrowRight");
+      const open = event.key === (rtl ? "ArrowLeft" : "ArrowRight");
       const key = focused.item.key;
-      if (open && focused.item.children?.length) {
-        if (!expanded.includes(key)) setExpanded([...expanded, key]);
+      if (open && (focused.item.children?.length ?? 0) > 0) {
+        if (!expandedSet.has(key)) setExpanded([...expanded, key]);
         else next = enabled[at + 1];
-      } else if (!open && expanded.includes(key))
+      } else if (!open && expandedSet.has(key))
         setExpanded(expanded.filter((each) => each !== key));
       else if (!open) next = enabled.find((row) => row.item.key === focused.parent);
+    } else if (modifier && event.key.toLowerCase() === "a" && !event.altKey) {
+      if (mode !== "multiple") return;
+      commit(selectAll(policy, selectedSet, order));
+    } else if (event.key === "Escape") {
+      if (escapeKeyBehavior !== "clearSelection") return;
+      const cleared = clearAll(policy, selectedSet);
+      // Unclaimed when nothing changed, so an enclosing popover still closes.
+      if (cleared === selectedSet) return;
+      commit(cleared);
+    } else if (event.key === "Enter" && activeKey != null && onAction != null) {
+      onAction(activeKey);
+    } else if ((event.key === " " || event.key === "Enter") && activeKey != null) {
+      if (event.shiftKey && mode === "multiple") extend(activeKey, activeKey);
+      else selectOne(activeKey, modifier);
     } else if (
-      (event.ctrlKey || event.metaKey) &&
-      event.key === "a" &&
-      selectionMode === "multiple"
-    ) {
-      setSelected(enabled.map((row) => row.item.key));
-      announce(`${enabled.length} selected`);
-    } else if ((event.key === " " || event.key === "Enter") && activeKey != null)
-      choose(activeKey, event.shiftKey, true);
-    else if (
       (event.key === "Delete" || event.key === "Backspace") &&
       kind === "tags" &&
       activeKey != null
@@ -249,10 +373,28 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
           break;
         }
       }
+      // Typeahead moves; it never extends. Under `replace` the selection follows.
+      if (next != null) {
+        event.preventDefault();
+        land(next, { shiftKey: false, ctrlKey: false, metaKey: false });
+        return;
+      }
     } else return;
     event.preventDefault();
-    if (next != null) land(next, event.shiftKey);
+    if (next != null) land(next, event);
   });
+  const rowClick = (item: CollectionItem, event: RowClick) => {
+    if (disabled(item)) return;
+    root.current?.focus();
+    setActive(item.key);
+    // With nothing to select, a click is the row's action.
+    if (mode === "none") {
+      onAction?.(item.key);
+      return;
+    }
+    if (event.shiftKey && mode === "multiple") extend(item.key, activeKey);
+    else selectOne(item.key, event.ctrlKey || event.metaKey || togglesByPointer(event));
+  };
   const start = virtualized ? Math.max(0, Math.floor(scrollTop / rowHeight) - 2) : 0;
   const end = virtualized
     ? Math.min(rows.length, start + Math.ceil(height / rowHeight) + 4)
@@ -266,7 +408,7 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
     .map((index) => {
       const row = rows[index];
       const { item } = row;
-      const chosen = selected.includes(item.key);
+      const chosen = selectedSet.has(item.key);
       const grid = kind === "grid" || kind === "tags";
       const content =
         children?.(item, {
@@ -282,10 +424,12 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
         draggable: onReorder != null && !disabled(item),
         id: `${id}-${index}`,
         role: grid ? "row" : kind === "tree" ? "treeitem" : "option",
-        "aria-selected": selectionMode === "none" ? undefined : chosen,
+        "aria-selected": mode === "none" ? undefined : chosen,
         "aria-disabled": disabled(item) || undefined,
         "aria-expanded":
-          kind === "tree" && item.children?.length ? expanded.includes(item.key) : undefined,
+          kind === "tree" && (item.children?.length ?? 0) > 0
+            ? expandedSet.has(item.key)
+            : undefined,
         "aria-level": kind === "tree" ? row.level : undefined,
         "aria-posinset": grid ? undefined : kind === "tree" ? row.position : index + 1,
         "aria-setsize": grid ? undefined : kind === "tree" ? row.count : rows.length,
@@ -295,12 +439,14 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
         style: virtualized
           ? { position: "absolute", top: index * rowHeight, height: rowHeight, width: "100%" }
           : undefined,
-        onClick: (event: $FlowFixMe) => {
-          if (disabled(item)) return;
-          root.current?.focus();
-          setActive(item.key);
-          choose(item.key, event.shiftKey, selectionMode === "multiple");
-        },
+        onClick: (event: RowClick) => rowClick(item, event),
+        // Under `replace` a click selects, so the action needs a second gesture.
+        onDoubleClick:
+          onAction != null && selectionBehavior === "replace" && mode !== "none"
+            ? () => {
+                if (!disabled(item)) onAction(item.key);
+              }
+            : undefined,
       };
       return (
         <div key={item.key} {...props}>
@@ -313,7 +459,7 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
                   tabIndex={-1}
                   disabled={disabled(item)}
                   aria-label={`Remove ${item.textValue}`}
-                  onClick={(event) => {
+                  onClick={(event: RowClick) => {
                     event.stopPropagation();
                     root.current?.focus();
                     remove(item.key);
@@ -332,27 +478,31 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
   const setRef = useStableCallback((element: HTMLElement | null) => {
     root.current = element;
   });
+  const style = rest.style;
   const props = withProps(rest, {
     ref: composeRefs(rest.ref, setRef),
     role: kind === "tags" ? "grid" : kind,
     tabIndex: 0,
     "aria-activedescendant": activeIndex < 0 ? undefined : `${id}-${activeIndex}`,
-    "aria-multiselectable": selectionMode === "multiple" || undefined,
+    "aria-multiselectable": mode === "multiple" || undefined,
     "aria-busy": loading || undefined,
     "aria-rowcount": kind === "grid" || kind === "tags" ? rows.length : undefined,
     onKeyDown: composeHandlers(rest.onKeyDown, keydown),
-    onScroll: composeHandlers(rest.onScroll, (event: $FlowFixMe) => {
-      if (virtualized) setScrollTop(event.currentTarget.scrollTop);
-      if (
-        !loading &&
-        event.currentTarget.scrollTop + event.currentTarget.clientHeight >=
-          event.currentTarget.scrollHeight
-      )
+    onScroll: composeHandlers(rest.onScroll, (event: Scroll) => {
+      const element = event.currentTarget;
+      if (!(element instanceof HTMLElement)) return;
+      if (virtualized) setScrollTop(element.scrollTop);
+      if (!loading && element.scrollTop + element.clientHeight >= element.scrollHeight)
         onLoadMore?.();
     }),
     style: virtualized
-      ? { ...(rest.style as $FlowFixMe), height, overflow: "auto", position: "relative" }
-      : rest.style,
+      ? {
+          ...(typeof style === "object" && style != null ? style : {}),
+          height,
+          overflow: "auto",
+          position: "relative",
+        }
+      : style,
     children: virtualized ? (
       <div role="presentation" style={{ height: rows.length * rowHeight, position: "relative" }}>
         {rowNodes}
@@ -364,7 +514,8 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
   return (
     <>
       {render != null ? render(props) : <div {...props} />}
-      <span role="status" aria-live="polite">
+      {/* For a screen reader; a sighted reader sees the selection itself. */}
+      <span role="status" aria-live="polite" style={visuallyHiddenStyle}>
         {drag.announcement || announcement}
       </span>
     </>
@@ -374,10 +525,26 @@ export component CollectionRoot(kind: Kind, options: CollectionProps) {
 export type CollectionProps = {
   items: $ReadOnlyArray<CollectionItem>,
   children?: (item: CollectionItem, state: CollectionItemState) => React.Node,
-  selectionMode?: "single" | "multiple" | "none",
+  selectionMode?: SelectionMode,
+  /**
+   * What a plain click or Space does: `"toggle"` flips the row (the default),
+   * `"replace"` makes it the whole selection and lets the arrow keys carry the
+   * selection with them. Ctrl/Cmd toggles and Shift extends under either.
+   */
+  selectionBehavior?: SelectionBehavior,
+  /** Refuse the gesture that would leave nothing selected. */
+  disallowEmptySelection?: boolean,
+  /** Whether Escape clears the selection. */
+  escapeKeyBehavior?: "clearSelection" | "none",
   selectedKeys?: $ReadOnlyArray<string>,
   defaultSelectedKeys?: $ReadOnlyArray<string>,
   onSelectionChange?: (keys: $ReadOnlyArray<string>) => void,
+  /**
+   * Open a row rather than select it. Enter runs it; so does a click when
+   * `selectionMode` is `"none"`, and a double click under
+   * `selectionBehavior="replace"`.
+   */
+  onAction?: (key: string) => void,
   disabledKeys?: $ReadOnlyArray<string>,
   expandedKeys?: $ReadOnlyArray<string>,
   defaultExpandedKeys?: $ReadOnlyArray<string>,

package/internal/segmented-field.js

@@ -9,6 +9,7 @@ import { composeHandlers, withProps } from "./merge-props.js";
 import type { RenderProp, Rest } from "./merge-props.js";
 import { directionOf } from "./roving-focus.js";
 import { useLocale } from "../i18n-provider.js";
+import { visuallyHiddenStyle } from "./visually-hidden-style.js";
 
 type Segment = "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod";
 type Fields = { [string]: string };
@@ -306,7 +307,7 @@ export component SegmentedField(time: boolean, options: DateFieldProps) {
     children: (
       <>
         {segments}
-        <span role="status" aria-live="polite">
+        <span role="status" aria-live="polite" style={visuallyHiddenStyle}>
           {announcement}
         </span>
       </>

package/internal/selection.js

@@ -0,0 +1,171 @@
+// @flow
+//
+// What a collection's selection becomes after one gesture, as pure functions.
+//
+// `ListBox`, `GridList`, `Tree` and `TagGroup` all ask the same four questions
+// — toggle this key, make it the only one, extend to it, take everything — and
+// the answers depend on three settings rather than on which collection is
+// asking. Keeping them here, apart from React, is what lets every rule be
+// tested without rendering and lets all four collections agree by construction.
+//
+// The rules are React Aria's selection manager (`@react-stately/selection`),
+// which is itself the WAI-ARIA APG's listbox and grid selection models made
+// precise:
+//
+//   * `mode` is what may be chosen: nothing, one key, or any number.
+//   * `behavior` is what a plain gesture does. `"toggle"` flips the key — the
+//     checkbox model, right for touch and for lists whose rows carry a
+//     checkbox. `"replace"` makes the key the whole selection — the file
+//     manager model, where Ctrl/Cmd adds one and Shift adds a range.
+//   * `disallowEmpty` refuses the gesture that would leave nothing selected,
+//     rather than accepting it and then reselecting.
+//
+// Every function returns the *same* set it was given when nothing changes, so a
+// caller can compare by identity and skip `onSelectionChange` for a gesture
+// that did nothing — a controlled parent is not told about a change that is
+// not one.
+//
+// # Why this is `internal/`
+//
+// A public selection manager would be a second way to build a collection, and
+// the point of this package is that there is one. The collections are the
+// public surface; `packages/ui/index.js` says why the internals stay internal.
+
+export type SelectionMode = "none" | "single" | "multiple";
+export type SelectionBehavior = "toggle" | "replace";
+
+/** The three settings every answer below depends on. */
+export type SelectionPolicy = {|
+  readonly mode: SelectionMode,
+  readonly behavior: SelectionBehavior,
+  readonly disallowEmpty: boolean,
+|};
+
+/**
+ * The keys a range covers, in collection order, inclusive at both ends.
+ *
+ * `order` is the selectable keys only — disabled rows are not in it — so a range
+ * dragged across a disabled row does not pick it up, which is what React Aria
+ * and every native list do. An end that is not in `order` (a key filtered out
+ * since it was chosen) contributes nothing rather than stretching the range to
+ * the start of the list.
+ */
+export function keyRange(
+  order: $ReadOnlyArray<string>,
+  from: string,
+  to: string,
+): $ReadOnlyArray<string> {
+  const start = order.indexOf(from);
+  const end = order.indexOf(to);
+  if (start < 0 || end < 0) return end < 0 ? [] : [to];
+  return order.slice(Math.min(start, end), Math.max(start, end) + 1);
+}
+
+/** Flip one key, unless that would empty a selection that must not be empty. */
+export function toggleKey(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (selected.has(key)) {
+    if (policy.disallowEmpty && selected.size === 1) return selected;
+    if (policy.mode === "single") return new Set();
+    const next = new Set(selected);
+    next.delete(key);
+    return next;
+  }
+  if (policy.mode === "single") return new Set([key]);
+  const next = new Set(selected);
+  next.add(key);
+  return next;
+}
+
+/** Make one key the whole selection. */
+export function replaceWith(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (selected.size === 1 && selected.has(key)) return selected;
+  return new Set([key]);
+}
+
+/**
+ * Extend from `anchor` to `key`, replacing the range the previous extension made.
+ *
+ * `lead` is where the last extension ended. Shift+Down, Shift+Down, Shift+Up
+ * must end with two rows selected rather than three, so the old range
+ * (`anchor`…`lead`) comes out before the new one (`anchor`…`key`) goes in —
+ * while anything selected outside both ranges, by an earlier Ctrl/Cmd+click,
+ * stays. With no anchor the extension starts at `key`.
+ */
+export function extendTo(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+  anchor: string | null,
+  lead: string | null,
+  key: string,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none") return selected;
+  if (policy.mode === "single") return replaceWith(policy, selected, key);
+  const from = anchor ?? key;
+  const next = new Set(selected);
+  if (lead != null) for (const each of keyRange(order, from, lead)) next.delete(each);
+  for (const each of keyRange(order, from, key)) next.add(each);
+  if (next.size === 0 && policy.disallowEmpty) return selected;
+  return sameKeys(next, selected) ? selected : next;
+}
+
+/** Every selectable key, when more than one may be chosen. */
+export function selectAll(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+): $ReadOnlySet<string> {
+  if (policy.mode !== "multiple" || order.length === 0) return selected;
+  const next = new Set(selected);
+  for (const key of order) next.add(key);
+  return sameKeys(next, selected) ? selected : next;
+}
+
+/** Nothing, unless nothing is not allowed. */
+export function clearAll(
+  policy: SelectionPolicy,
+  selected: $ReadOnlySet<string>,
+): $ReadOnlySet<string> {
+  if (policy.mode === "none" || policy.disallowEmpty || selected.size === 0) return selected;
+  return new Set();
+}
+
+/**
+ * A selection as the array `onSelectionChange` reports: collection order first,
+ * then any key the collection is not showing, in the order it was chosen.
+ *
+ * Keys the collection is not showing are real — a child of a collapsed tree
+ * row, a row a filter hid — and dropping them because they are out of sight
+ * would deselect something the reader chose and cannot see go.
+ */
+export function orderedKeys(
+  selected: $ReadOnlySet<string>,
+  order: $ReadOnlyArray<string>,
+): $ReadOnlyArray<string> {
+  const result = [];
+  const placed = new Set<string>();
+  for (const key of order) {
+    if (selected.has(key)) {
+      result.push(key);
+      placed.add(key);
+    }
+  }
+  for (const key of selected) if (!placed.has(key)) result.push(key);
+  return result;
+}
+
+function sameKeys(a: $ReadOnlySet<string>, b: $ReadOnlySet<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const key of a) if (!b.has(key)) return false;
+  return true;
+}

package/internal/visually-hidden-style.js

@@ -0,0 +1,41 @@
+// @flow
+//
+// The one inline style for "hidden from sight, present for a screen reader".
+//
+// Its own module, with no `"use client"`, so a part that renders on the server
+// can import it without importing `visually-hidden.js` — a client module whose
+// every export is a client reference to a Server Component. Internal for the
+// reason `packages/ui/index.js` gives about every module here: the public
+// answer is `VisuallyHidden`.
+
+/**
+ * The style that hides an element from sight and from nothing else.
+ *
+ * Shared by `VisuallyHidden` and by the parts that keep a live region of their
+ * own beside what they render — the table's sort announcement, the
+ * collections', the calendar's and the range calendar's, and the segmented
+ * fields'. Frozen, because every one of them holds the same object.
+ */
+export const visuallyHiddenStyle: {|
+  readonly border: number,
+  readonly clip: string,
+  readonly clipPath: string,
+  readonly height: number,
+  readonly margin: number,
+  readonly overflow: string,
+  readonly padding: number,
+  readonly position: string,
+  readonly whiteSpace: string,
+  readonly width: number,
+|} = 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,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -19,10 +19,10 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/core": "0.1.0",
-    "@uniflowed/hooks": "0.1.0",
-    "@uniflowed/react": "0.1.0",
-    "@uniflowed/state": "0.1.0"
+    "@uniflowed/core": "0.2.0",
+    "@uniflowed/hooks": "0.2.0",
+    "@uniflowed/react": "0.2.0",
+    "@uniflowed/state": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=19"

package/range-calendar.js

@@ -8,6 +8,7 @@ import type { Rest } from "./internal/merge-props.js";
 import type { DateRange } from "./internal/date-range.js";
 import { validateRange, unavailableInRange } from "./internal/date-range.js";
 import { CalendarRoot, CalendarMonth } from "./calendar.js";
+import { visuallyHiddenStyle } from "./internal/visually-hidden-style.js";
 export type { DateRange } from "./internal/date-range.js";
 
 export component RangeCalendarRoot(
@@ -70,7 +71,7 @@ export component RangeCalendarRoot(
       >
         {children}
       </CalendarRoot>
-      <span role="status" aria-live="polite">
+      <span role="status" aria-live="polite" style={visuallyHiddenStyle}>
         {announcement}
       </span>
     </div>

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) {
@@ -222,7 +210,7 @@ export component TableRoot(
         aria-live="polite"
         data-uf-table-status=""
         role="status"
-        style={VISUALLY_HIDDEN_STYLE}
+        style={visuallyHiddenStyle}
       >
         {message}
       </div>

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();
+}