@uniflowed/ui 0.0.0-alpha.2 → 0.0.0-alpha.4

package/index.js

@@ -11,44 +11,128 @@
 // That part is behaviour, and specifically keyboard and screen-reader
 // behaviour: a roving `tabindex` so a twelve-tab list does not take twelve Tab
 // presses to get past, a focus trap that actually cannot be escaped, focus
-// restored to whatever opened a dialog, `aria-describedby` pointing only at
-// elements that are in the document. None of it is visible in a screenshot and
-// all of it is what separates a component from a div that looks like one.
+// restored to whatever opened a dialog, typeahead in a menu, an
+// `aria-activedescendant` that names an option still in the document. None of
+// it is visible in a screenshot and all of it is what separates a component
+// from a `div` that looks like one.
+//
+// Each primitive implements the WAI-ARIA authoring practices pattern for it —
+// the roles, the `aria-*` wiring, the focus management and the whole keyboard
+// map — and each module's header says which interaction it exists to get right
+// and what a naive version breaks.
 //
 // # Composition is type-checked
 //
 // This is where Flow says something no other type system can. `Tabs.List`
 // declares `renders* Tabs.Tab`, so a `<button>` in a tab list is a *type
 // error* — not a review comment, not a runtime warning, not a screen reader
-// announcing "button" where the reader expected "tab, 2 of 5". A library
-// written in TypeScript can document that constraint; it cannot state it.
+// announcing "button" where the reader expected "tab, 2 of 5". `Menu.Body` and
+// `Combobox.List` state the same constraint about what may appear inside a
+// menu and a listbox, which ARIA also requires and which nothing else checks.
+// A library written in TypeScript can document those constraints; it cannot
+// state them.
+//
+// # Styling is a default, not a dependency
+//
+// Nothing here imports StyleX, and nothing here has a StyleX-shaped type. A
+// consumer styling with plain CSS, CSS Modules or anything else gets exactly
+// the same components with exactly the same behaviour; the design-system layer
+// that adds uf's default styles is built *on* these, not into them.
+//
+// # What these components promise React
+//
+// Nothing here mutates during a render, reads a ref during a render, or depends
+// on a render happening exactly once — so React Compiler's memoization and
+// ordinary `memo` are both safe, and none of it needs an escape hatch. The
+// refs that exist (`triggerRef`, `pendingFocus`, the typeahead buffer) are
+// written only from event handlers and effects, and nothing renders them.
+//
+// Where a component has to learn something the DOM knows — how many options a
+// caller filtered down to, which item the arrow key should move to — it reads
+// the document in an effect or an event handler and, if a render depends on
+// the answer, puts it in state. It is deliberately *not* `useSyncExternalStore`:
+// that is for a store whose value a render reads, and reading layout during a
+// render is the thing it exists to prevent.
+//
+// # Server and client
+//
+// Every module that manages focus, listens to the document or holds state
+// declares `"use client"`, because each of those needs a browser. That is a
+// property of the components, not of the application: an RSC page may import
+// this package from a Server Component, and only the parts that need the client
+// join the client bundle.
+//
+// # How the package is laid out
+//
+// One root module per primitive, each with its own `exports` subpath, each
+// named after the thing it implements:
+//
+// - `dialog.js` — the focus trap, focus restore, scroll lock and inert page.
+// - `menu.js` — the arrow keys, typeahead, submenus and `Escape` stacking.
+// - `combobox.js` — `aria-activedescendant` over a filtered list, and the
+//   count a screen reader is told.
+// - `tabs.js` — the roving `tabindex`, and automatic versus manual activation.
+// - `field.js` — the label, description, error and `aria-invalid` wiring.
+// - `switch.js` and `checkbox.js` — the two two-state controls, apart because
+//   the third state and the `Enter` key genuinely differ between them.
+//
+// Every name below is exported from one of those, so a consumer may import
+// `@uniflowed/ui` or `@uniflowed/ui/dialog` and get the same thing. The split
+// is by primitive because that is the unit a reader looks for, the unit a
+// bundler drops, and the unit the WAI-ARIA practices are written in.
+//
+// `internal/` holds three modules and nothing else, each a rule the primitives
+// must apply identically and a consumer must not be able to apply differently:
+// `merge-props.js` (the caller's props go on first, the component's semantics
+// last), `controlled-state.js` (what "controlled" means here), and
+// `roving-focus.js` (how a set of items is found and moved between). Each says
+// in its own header why it is unreachable rather than exported. There is no
+// `internal/props.js`-shaped bag of helpers: a module that cannot say what it
+// is about does not belong in this package.
 
+import { Checkbox } from "./checkbox.js";
 import {
-  FieldControl,
-  FieldDescription,
-  FieldError,
-  FieldLabel,
-  FieldRoot,
-} from "./internal/field.js";
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxLabel,
+  ComboboxList,
+  ComboboxOption,
+  ComboboxRoot,
+  ComboboxStatus,
+} from "./combobox.js";
 import {
+  DialogBody,
   DialogClose,
-  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
   DialogRoot,
   DialogTitle,
   DialogTrigger,
-} from "./internal/dialog.js";
-import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./internal/tabs.js";
-import { Checkbox, Switch } from "./internal/switch.js";
+} from "./dialog.js";
+import { FieldControl, FieldDescription, FieldError, FieldLabel, FieldRoot } from "./field.js";
+import {
+  MenuBody,
+  MenuGroup,
+  MenuItem,
+  MenuLabel,
+  MenuRoot,
+  MenuSeparator,
+  MenuSub,
+  MenuSubTrigger,
+  MenuTrigger,
+} from "./menu.js";
+import { Switch } from "./switch.js";
+import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./tabs.js";
+
+export type { ActivationMode } from "./tabs.js";
 
 export { Checkbox, Switch };
 
 /**
  * An accessible form field.
  *
- * `Field.Control` takes a render function rather than rendering an `<input>`,
- * because a field wraps a select, a textarea or somebody else's component just
- * as often, and each needs the same attributes.
- *
  *   <Field.Root invalid={error != null}>
  *     <Field.Label>Email</Field.Label>
  *     <Field.Control render={(props) => <input type="email" {...props} />} />
@@ -67,8 +151,11 @@ export const Field = {
 /**
  * Tabs, with the arrow-key behaviour the pattern requires.
  *
+ * `activationMode="manual"` moves focus without selecting, for panels that cost
+ * something to show.
+ *
  *   <Tabs.Root defaultValue="one">
- *     <Tabs.List>
+ *     <Tabs.List aria-label="Sections">
  *       <Tabs.Tab value="one">One</Tabs.Tab>
  *       <Tabs.Tab value="two">Two</Tabs.Tab>
  *     </Tabs.List>
@@ -87,17 +174,86 @@ export const Tabs = {
  * A modal dialog: focus moved in, kept in, and given back.
  *
  *   <Dialog.Root>
- *     <Dialog.Trigger>Open</Dialog.Trigger>
- *     <Dialog.Content>
- *       <Dialog.Title>Are you sure?</Dialog.Title>
- *       <Dialog.Close>Cancel</Dialog.Close>
- *     </Dialog.Content>
+ *     <Dialog.Trigger>Delete</Dialog.Trigger>
+ *     <Dialog.Overlay />
+ *     <Dialog.Body>
+ *       <Dialog.Header>
+ *         <Dialog.Title>Delete this project?</Dialog.Title>
+ *         <Dialog.Description>This cannot be undone.</Dialog.Description>
+ *       </Dialog.Header>
+ *       <Dialog.Footer>
+ *         <Dialog.Close>Cancel</Dialog.Close>
+ *       </Dialog.Footer>
+ *     </Dialog.Body>
  *   </Dialog.Root>
  */
 export const Dialog = {
   Root: DialogRoot,
   Trigger: DialogTrigger,
-  Content: DialogContent,
+  Overlay: DialogOverlay,
+  Body: DialogBody,
+  Header: DialogHeader,
+  Footer: DialogFooter,
   Title: DialogTitle,
+  Description: DialogDescription,
   Close: DialogClose,
 };
+
+/**
+ * A menu, with the keyboard map every native menu has had for thirty years.
+ *
+ *   <Menu.Root>
+ *     <Menu.Trigger>File</Menu.Trigger>
+ *     <Menu.Body>
+ *       <Menu.Group>
+ *         <Menu.Label>Recent</Menu.Label>
+ *         <Menu.Item onSelect={open}>Open…</Menu.Item>
+ *       </Menu.Group>
+ *       <Menu.Separator />
+ *       <Menu.Sub>
+ *         <Menu.SubTrigger>Export</Menu.SubTrigger>
+ *         <Menu.Body>
+ *           <Menu.Item onSelect={png}>PNG</Menu.Item>
+ *         </Menu.Body>
+ *       </Menu.Sub>
+ *     </Menu.Body>
+ *   </Menu.Root>
+ */
+export const Menu = {
+  Root: MenuRoot,
+  Trigger: MenuTrigger,
+  Body: MenuBody,
+  Item: MenuItem,
+  Separator: MenuSeparator,
+  Group: MenuGroup,
+  Label: MenuLabel,
+  Sub: MenuSub,
+  SubTrigger: MenuSubTrigger,
+};
+
+/**
+ * A text field with a list of options, navigated without leaving the field.
+ *
+ * The caller filters; the component keeps the ARIA wiring true while they do.
+ *
+ *   <Combobox.Root inputValue={query} onInputValueChange={setQuery}>
+ *     <Combobox.Label>Country</Combobox.Label>
+ *     <Combobox.Input />
+ *     <Combobox.List>
+ *       {matches.map((each) => (
+ *         <Combobox.Option key={each} value={each}>{each}</Combobox.Option>
+ *       ))}
+ *     </Combobox.List>
+ *     <Combobox.Empty>No matches.</Combobox.Empty>
+ *     <Combobox.Status />
+ *   </Combobox.Root>
+ */
+export const Combobox = {
+  Root: ComboboxRoot,
+  Label: ComboboxLabel,
+  Input: ComboboxInput,
+  List: ComboboxList,
+  Option: ComboboxOption,
+  Empty: ComboboxEmpty,
+  Status: ComboboxStatus,
+};

package/internal/controlled-state.js

@@ -0,0 +1,65 @@
+// @flow
+//
+// The one contract every part of this package makes about state.
+//
+// Each primitive here has a value somebody may want to own: a dialog's open,
+// a tab set's selection, a switch's checked, a combobox's text. A library that
+// only supports one of the two arrangements is unusable in the other half of
+// applications — a form library owns the value, and a page that just wants tabs
+// does not — so every one of them is uncontrolled by default and controlled the
+// moment the corresponding prop is passed.
+//
+// Written once because the failure mode of writing it six times is that five of
+// them agree and one does not, and the one that does not is a component that
+// silently ignores the parent's value on the second render. The rules it fixes:
+//
+//   * `undefined` means "not controlled", and `null` does not. A combobox with
+//     no selection is `value={null}` and is still controlled.
+//   * A controlled component never writes its internal state, so a parent that
+//     rejects a change actually rejects it, rather than the component moving
+//     and then being moved back on the next render.
+//   * `onChange` is called for both arrangements, so a caller can observe
+//     without taking ownership.
+//
+// # Why this is `internal/` and not a subpath
+//
+// A public `useControlled` would be a general-purpose hook, and general-purpose
+// React hooks are `@uniflowed/hooks`' subject, not this package's. What lives
+// here is narrower than that: the specific contract this package's components
+// promise about their props. Exporting it would publish a second, weaker copy
+// of somebody else's API.
+
+import { useCallback, useState } from "@uniflowed/react";
+
+/**
+ * A value the caller may own, and the setter that respects the answer.
+ *
+ * `controlled` is the prop; `fallback` is the `defaultValue`-shaped initial
+ * state used only while the caller owns nothing.
+ */
+export hook useControlled<T>(
+  controlled: T | void,
+  fallback: T,
+  onChange: ((next: T) => mixed) | void,
+): [T, (next: T) => void] {
+  const [internal, setInternal] = useState<T>(fallback);
+  // `=== undefined` rather than `== null`: `null` is a legitimate controlled
+  // value — a combobox with nothing selected — and treating it as "give me the
+  // uncontrolled behaviour" made a cleared selection reappear on the next
+  // render.
+  const owned = controlled === undefined;
+
+  const set = useCallback(
+    (next: T) => {
+      if (owned) {
+        setInternal(next);
+      }
+      // Both arrangements report, so a caller can watch a value it does not
+      // own without having to take it over to do so.
+      onChange?.(next);
+    },
+    [owned, onChange],
+  );
+
+  return [owned ? internal : (controlled as $FlowFixMe), set];
+}

package/internal/{props.js → merge-props.js}

@@ -1,24 +1,32 @@
 // @flow
 //
-// Merging a caller's props with the ones a component owns.
+// One rule about prop order, stated once.
 //
 // `<div {...rest} role="dialog">` and `<div role="dialog" {...rest}>` are
 // different components. The second lets a caller pass `role="button"` and get
-// it; the first does not. That sounds like a preference until you notice what
-// else is in `rest`:
+// it; the first does not. That sounds like a matter of taste until you notice
+// what else arrives in `rest`:
 //
 //   * A caller `ref` replaced the ref the dialog uses to find its focus stops,
-//     so `contentRef.current` stayed null, the Tab handler returned early, and
-//     the focus trap was *silently off* while the dialog still announced
+//     so `bodyRef.current` stayed null, the Tab handler returned early, and the
+//     focus trap was *silently off* while the dialog still announced
 //     `aria-modal="true"`.
 //   * A caller `onClick` replaced a tab's selection handler, so clicking a tab
 //     did nothing.
 //   * A caller `onKeyDown` replaced the dialog's, so Escape stopped closing it.
 //
-// None of those fail loudly. So the rule here is: the caller's props go on
-// first and the component's own semantics go on last, and for the two kinds of
-// prop where a caller legitimately wants *both* — event handlers and refs —
-// they are composed rather than one replacing the other.
+// None of those fail loudly. So the rule is: the caller's props go on first and
+// the component's own semantics go on last, and for the two kinds of prop where
+// a caller legitimately wants *both* — event handlers and refs — they are
+// composed rather than one replacing the other.
+//
+// # Why this is `internal/` and not a subpath
+//
+// It is not a "props utils" module and there is nothing else in it. It is the
+// one policy every part of this package applies, extracted so that a new
+// primitive cannot quietly apply a different one. Exporting it would invite a
+// consumer to build a part that spreads `rest` last, which is the failure this
+// exists to prevent — so it stays unreachable from outside the package.
 
 /** Anything a caller can spread onto an element. */
 export type Rest = { readonly [string]: mixed };
@@ -26,8 +34,8 @@ export type Rest = { readonly [string]: mixed };
 /**
  * Call the caller's handler and then the component's.
  *
- * The caller's runs first so it can inspect the event before the component
- * acts on it, and the component's runs unless the caller stopped the event —
+ * The caller's runs first so it can inspect the event before the component acts
+ * on it, and the component's runs unless the caller stopped the event —
  * `defaultPrevented` is the caller's way of saying "I handled this", which is
  * the same contract the DOM uses.
  */

package/internal/roving-focus.js

@@ -0,0 +1,236 @@
+// @flow
+//
+// The keyboard pattern shared by every list of things in this package.
+//
+// A tab list, a menu and a listbox look nothing alike and behave identically at
+// the keyboard, because WAI-ARIA says they must: the *set* takes one stop in the
+// page's tab order, and the arrow keys move within it. That is what makes a
+// twelve-item menu something a keyboard user passes in one Tab press instead of
+// twelve, and it is the part hand-written components leave out.
+//
+// Four rules make it up, and each one has a way of being got wrong that no
+// screenshot shows:
+//
+//   * **Document order, read from the document.** Items are found by querying
+//     the container at the moment a key is pressed, not from a registry the
+//     items push themselves into as they mount. Mount order is not document
+//     order the moment a list is filtered, reordered, or has a conditional item
+//     in the middle of it — and a registry that disagrees with the page sends
+//     the arrow keys somewhere the reader is not.
+//   * **Nesting.** A submenu's items are inside its parent menu's element, so
+//     "the items of this menu" cannot be `querySelectorAll` alone. An item
+//     belongs to the nearest container of its own kind.
+//   * **Disabled is skipped, not landed on.** And the direction to keep
+//     searching in cannot be inferred from the target index: `End` aims at the
+//     last item and, if that one is disabled, has to walk *backwards*. Guessing
+//     "forwards, because the target is ahead of us" wrapped `End` around to the
+//     first item.
+//   * **Typeahead.** Pressing `r` in a menu goes to Refresh. Without it a menu
+//     of thirty items is thirty arrow presses, and every native menu on every
+//     platform has had this since before the web.
+//
+// # Why this is `internal/` and not a subpath
+//
+// It is a description of DOM structure this package owns — that a tab lives
+// under `[role="tablist"]`, that a menu item's owner is `[role="menu"]` — and
+// those relationships are only guaranteed because the components in this
+// package build them. Handed to a consumer it would be a set of selectors that
+// happen to work today, which is a different and much weaker promise than the
+// one the components make.
+
+import { useCallback, useRef } from "@uniflowed/react";
+
+/** Which way a key asks the focus to move within a set. */
+export type Movement = "previous" | "next" | "first" | "last";
+
+/** The axis a set's arrow keys run along. */
+export type Orientation = "horizontal" | "vertical";
+
+/** How long a typeahead buffer survives without another key, in milliseconds. */
+const TYPEAHEAD_WINDOW = 500;
+
+/**
+ * The items directly belonging to `container`, in document order.
+ *
+ * `owner` names the container's own kind — `[role="menu"]` for a menu — so an
+ * item inside a *nested* container of that kind is left to the nested one. A
+ * plain `querySelectorAll` returns a submenu's items as if they were the parent
+ * menu's, which makes `ArrowDown` in the parent step into a menu the reader
+ * 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,
+  );
+}
+
+/**
+ * Whether the keyboard may land on this item.
+ *
+ * Both spellings, because the two mean different things and this package uses
+ * both: a native `disabled` takes an element out of the accessibility tree's
+ * reach, while `aria-disabled` leaves it announced — which is what a menu item
+ * or a tab wants, so a reader can tell the option exists and is unavailable
+ * rather than finding a gap where it used to be.
+ */
+export function isEnabled(element: HTMLElement): boolean {
+  return (
+    (element as $FlowFixMe).disabled !== true && element.getAttribute("aria-disabled") !== "true"
+  );
+}
+
+/**
+ * The movement a key asks for along `orientation`, or nothing if it is not ours.
+ *
+ * The unhandled keys matter as much as the handled ones. `ArrowDown` inside a
+ * *horizontal* tab list belongs to the page — it scrolls — and a component that
+ * swallows it has taken a key away from every reader who uses it to read.
+ */
+export function movementFor(key: string, orientation: Orientation): Movement | null {
+  return match (key) {
+    "Home" => "first",
+    "End" => "last",
+    "ArrowUp" => orientation === "vertical" ? "previous" : null,
+    "ArrowDown" => orientation === "vertical" ? "next" : null,
+    "ArrowLeft" => orientation === "horizontal" ? "previous" : null,
+    "ArrowRight" => orientation === "horizontal" ? "next" : null,
+    _ => null,
+  };
+}
+
+/**
+ * The item `movement` reaches from `from`, skipping disabled ones.
+ *
+ * `from` may be `-1` for "nothing is focused yet", which is what makes
+ * `ArrowDown` on a freshly opened menu land on the first item. `wrap` is false
+ * for a set where running off the end should stop rather than cycle.
+ *
+ * Returns null when every item is disabled, or when the ends are closed and
+ * there is nothing further in that direction — in both cases the caller should
+ * leave focus where it is rather than move it somewhere arbitrary.
+ */
+export function moveTo(
+  items: $ReadOnlyArray<HTMLElement>,
+  from: number,
+  movement: Movement,
+  wrap: boolean,
+): HTMLElement | null {
+  const count = items.length;
+  if (count === 0) {
+    return null;
+  }
+  // Two things this expression is careful about, each of which was a bug.
+  //
+  // The direction is part of the answer rather than derived from it: `last`
+  // aims at the end and searches *backwards* from there, and deriving
+  // "forwards" from the target being ahead of `from` sent `End` past the end
+  // and around to the first item whenever the last one was disabled.
+  //
+  // And `from` is -1 when nothing is focused yet, which the two directions read
+  // differently: "next" from nowhere is the first item, and "previous" from
+  // nowhere is the *last* one. Letting -1 fall through the arithmetic aimed
+  // `previous` at -2, which wraps to `count - 2` — so `ArrowUp` on a freshly
+  // opened list landed one short of the end, and on a two-item list landed on
+  // the first item.
+  const aim = match (movement) {
+    "previous" => [from < 0 ? count - 1 : from - 1, -1],
+    "next" => [from + 1, 1],
+    "first" => [0, 1],
+    "last" => [count - 1, -1],
+  };
+  const [target, direction] = aim;
+
+  for (let tried = 0; tried < count; tried += 1) {
+    const at = target + tried * direction;
+    if (!wrap && (at < 0 || at >= count)) {
+      return null;
+    }
+    const candidate = items[((at % count) + count) % count];
+    if (isEnabled(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** The index of the focused item, or `-1` when focus is elsewhere. */
+export function indexOfActive(items: $ReadOnlyArray<HTMLElement>, active: mixed): number {
+  return items.findIndex((item) => item === active);
+}
+
+/**
+ * Match items by the characters a reader types, the way every native menu does.
+ *
+ * The returned function is stable, so a component may pass it straight to a key
+ * handler without re-subscribing anything. The buffer lives in a ref and is only
+ * ever touched from an event handler — never during a render, where a value that
+ * depends on how many times React chose to render is a bug waiting for
+ * Strict Mode to find it.
+ *
+ * Two behaviours people notice when they are missing:
+ *
+ *   * Typing `s`, `a`, `v` within half a second looks for "sav", not for three
+ *     separate items starting with `s`, `a` and `v`.
+ *   * Pressing the *same* letter repeatedly cycles through the items starting
+ *     with it, which is how a reader reaches the second "Save as…".
+ */
+export hook useTypeahead(): (
+  items: $ReadOnlyArray<HTMLElement>,
+  from: number,
+  key: string,
+) => HTMLElement | null {
+  const buffer = useRef<{| text: string, at: number |}>({ text: "", at: 0 });
+
+  return useCallback(
+    (items: $ReadOnlyArray<HTMLElement>, from: number, key: string): HTMLElement | null => {
+      const now = Date.now();
+      const text = now - buffer.current.at > TYPEAHEAD_WINDOW ? key : buffer.current.text + key;
+      buffer.current = { text, at: now };
+
+      const repeated = text.length > 1 && text.split("").every((each) => each === text[0]);
+      const needle = (repeated ? text[0] : text).toLowerCase();
+      // A single character — or the same one again — moves on from where we
+      // are. A longer buffer starts *at* the current item, so typing "sa" after
+      // "s" can keep the item "s" already found.
+      const start = repeated || text.length === 1 ? from + 1 : Math.max(from, 0);
+
+      for (let tried = 0; tried < items.length; tried += 1) {
+        const candidate = items[(((start + tried) % items.length) + items.length) % items.length];
+        if (isEnabled(candidate) && labelOf(candidate).startsWith(needle)) {
+          return candidate;
+        }
+      }
+      return null;
+    },
+    [],
+  );
+}
+
+/**
+ * Whether a key press is a character a reader meant to type.
+ *
+ * Modifier combinations are excluded because `Ctrl+P` is the browser's, and a
+ * component that treats it as "the letter p" both steals the shortcut and jumps
+ * the selection somewhere the reader did not ask for.
+ */
+export function isTypeaheadKey(event: {
+  readonly key: string,
+  readonly altKey?: boolean,
+  readonly ctrlKey?: boolean,
+  readonly metaKey?: boolean,
+  ...
+}): boolean {
+  return (
+    event.key.length === 1 &&
+    event.key !== " " &&
+    event.altKey !== true &&
+    event.ctrlKey !== true &&
+    event.metaKey !== true
+  );
+}
+
+/** What a reader hears for this item, lower-cased for matching. */
+function labelOf(element: HTMLElement): string {
+  const spoken = element.getAttribute("aria-label") ?? element.textContent ?? "";
+  return spoken.replace(/\s+/g, " ").trim().toLowerCase();
+}