@uniflowed/ui 0.1.0 → 0.3.0

package/input-otp.js

@@ -112,7 +112,7 @@ function clean(raw: string, kind: InputOtpKind, length: number): string {
  * Renders no element of its own beyond the input — see the module header. The
  * caller's props go on the input, because the input is the field.
  */
-export component InputOtpRoot(
+component InputOtpRoot(
   children: React.Node,
   defaultValue?: string = "",
   disabled?: boolean = false,
@@ -173,7 +173,7 @@ export component InputOtpRoot(
  * already been announced, and a reader told "group, 3, group, 4" is being read
  * a picture.
  */
-export component InputOtpGroup(children: React.Node, ...rest: Rest) {
+component InputOtpGroup(children: React.Node, ...rest: Rest) {
   return (
     <div {...rest} aria-hidden="true">
       {children}
@@ -188,7 +188,7 @@ export component InputOtpGroup(children: React.Node, ...rest: Rest) {
  * whether there is one in it already, so a stylesheet can draw a cursor and a
  * border without this module having an opinion about either.
  */
-export component InputOtpSlot(children?: React.Node, index: number, ...rest: Rest) {
+component InputOtpSlot(children?: React.Node, index: number, ...rest: Rest) {
   const otp = useInputOtp("InputOtp.Slot");
   const character = otp.value[index] ?? "";
   // The box the next character goes in, clamped so a full code lights its last
@@ -209,10 +209,26 @@ export component InputOtpSlot(children?: React.Node, index: number, ...rest: Res
 }
 
 /** The dash between two groups. Decoration, and it says so. */
-export component InputOtpSeparator(children?: React.Node, render?: RenderProp, ...rest: Rest) {
+component InputOtpSeparator(children?: React.Node, render?: RenderProp, ...rest: Rest) {
   const props = withProps(rest, { "aria-hidden": "true", children });
   if (render != null) {
     return render(props);
   }
   return <div {...props} />;
 }
+
+/**
+ * The parts, under the names the `InputOtp` namespace gives them.
+ *
+ * `index.js` re-exports this module whole — `export * as InputOtp from "./input-otp.js"` —
+ * so a caller writes `<InputOtp.Root>`, and the namespace is the prefix. Each
+ * part is still *declared* as `InputOtpRoot`, so React DevTools, a component
+ * stack and an error name the part a reader can find rather than one of forty
+ * `Root`s.
+ */
+export {
+  InputOtpRoot as Root,
+  InputOtpGroup as Group,
+  InputOtpSlot as Slot,
+  InputOtpSeparator as Separator,
+};

package/interactions.js

@@ -1798,7 +1798,6 @@ hook useDescription(text: string | void): string | void {
     const entry: SharedDescription = shared;
     entry.users += 1;
     // The id is state because it must render only after the shared DOM node exists.
-    // uf-lint-disable-next-line react-compiler/set-state-in-effect
     setId(entry.node.id);
     return () => {
       entry.users -= 1;

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/focus.js

@@ -52,13 +52,22 @@ export const FOCUS_STOPS: string =
  * document.
  */
 export function focusable(root: HTMLElement): Array<HTMLElement> {
-  return Array.from(root.querySelectorAll(FOCUS_STOPS)).filter(
-    (element: $FlowFixMe) =>
+  const found: Array<HTMLElement> = [];
+  for (const element of root.querySelectorAll(FOCUS_STOPS)) {
+    if (
+      // Asked rather than annotated: `querySelectorAll` answers `Element`, and
+      // what focus lands on is an HTML or SVG element, both `HTMLElement` to
+      // Flow.
+      (element instanceof HTMLElement || element instanceof SVGElement) &&
       // All three hide a whole subtree, so all three are asked of the
       // ancestors; see the module header for what reading them off the element
       // alone let through.
       element.closest("[hidden]") == null &&
       element.closest("[inert]") == null &&
-      element.closest('[aria-hidden="true"]') == null,
-  );
+      element.closest('[aria-hidden="true"]') == null
+    ) {
+      found.push(element);
+    }
+  }
+  return found;
 }

package/internal/roving-focus.js

@@ -69,9 +69,18 @@ const TYPEAHEAD_WINDOW = 500;
  * cannot see.
  */
 export function itemsOf(container: HTMLElement, item: string, owner: string): Array<HTMLElement> {
-  return Array.from(container.querySelectorAll(item)).filter(
-    (element: $FlowFixMe) => element.closest(owner) === container,
-  );
+  const found: Array<HTMLElement> = [];
+  for (const element of container.querySelectorAll(item)) {
+    // An item is an HTML or SVG element, both `HTMLElement` to Flow; asked
+    // rather than annotated, because `querySelectorAll` answers `Element`.
+    if (
+      (element instanceof HTMLElement || element instanceof SVGElement) &&
+      element.closest(owner) === container
+    ) {
+      found.push(element);
+    }
+  }
+  return found;
 }
 
 /**