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

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/merge-props.js

@@ -0,0 +1,136 @@
+// @flow
+//
+// 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 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 `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 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.
+
+/**
+ * Props on their way onto an element: what a caller hands a part, and what
+ * `Field.Control` hands back for a caller to spread.
+ *
+ * `key` is named out of the indexer rather than left to it, and that one
+ * property is the whole subtlety of this type. React takes `key` off the
+ * attributes before a component is called, so a part's props never contain
+ * one — but an indexer does not know that, and `{ readonly [string]: mixed }`
+ * answers `mixed` for every name, `key` included. React's `key` is
+ * `string | number`, so every intrinsic this package rendered was rejected for
+ * a property that cannot be there:
+ *
+ *     error[incompatible-type]: Cannot create button element because in
+ *     property key: Either unknown is incompatible with string. Or unknown is
+ *     incompatible with number.
+ *
+ * thirty-two times, one per element, which was 32 of `@uniflowed/ui`'s 73 type
+ * errors. `key?: empty` states what React already guarantees, and the errors
+ * are the checker agreeing.
+ *
+ * # Two answers that look better than they are
+ *
+ * **`readonly key?: string | number`** — React's own type for the property —
+ * also silences the error, and is a lie in the shape of a fix. It says a
+ * caller may pass a `key` here; a part would then spread it onto its element,
+ * which is the "spreading a key into JSX" mistake React 19 added a warning
+ * for. `empty` is the same repair and a true sentence. It reads oddly for
+ * about a second and then reads as exactly what it is: there is no value you
+ * can pass under this name.
+ *
+ * **`React.PropsOf<"button">`** — the props of the element actually being
+ * rendered, which is what this type would like to say — cannot be written
+ * here. uf does not merge Flow's `jsx.js` environment, deliberately and for
+ * reasons `crates/uf_check/src/upstream/environments.rs` gives, so
+ * `$JSXIntrinsics` is the bare-bones table in `lib/react.js`, every
+ * intrinsic's `props` is `any`, and `React.PropsOf` itself reads as an
+ * any-typed value. Nothing about an element is checked here except its `key`:
+ * `<button className={5} nonsenseAttr={{}} />` is not an error today. A named
+ * type per element would therefore not be React's contract but a hand-written
+ * copy of `jsx.js` living in a UI package, drifting from the DOM on its own
+ * schedule — and it would still need an indexer for `data-*` and `aria-*`,
+ * which is where this started. So it stays one `Rest`, and the day
+ * `$JSXIntrinsics` is real is the day this becomes `React.PropsOf` and the
+ * parts say which element they render.
+ */
+export type Rest = { readonly key?: empty, 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 —
+ * `defaultPrevented` is the caller's way of saying "I handled this", which is
+ * the same contract the DOM uses.
+ */
+export function composeHandlers<TEvent extends { readonly defaultPrevented?: boolean }>(
+  theirs: mixed,
+  ours: (event: TEvent) => mixed,
+): (event: TEvent) => mixed {
+  if (typeof theirs !== "function") {
+    return ours;
+  }
+  return (event: TEvent) => {
+    (theirs as $FlowFixMe)(event);
+    if (event.defaultPrevented !== true) {
+      ours(event);
+    }
+  };
+}
+
+/** Set both refs, whichever kinds they are. */
+export function composeRefs<T>(
+  theirs: mixed,
+  ours: (value: T | null) => mixed,
+): (value: T | null) => void {
+  return (value: T | null) => {
+    ours(value);
+    if (typeof theirs === "function") {
+      (theirs as $FlowFixMe)(value);
+    } else if (theirs != null && typeof theirs === "object") {
+      (theirs as $FlowFixMe).current = value;
+    }
+  };
+}
+
+/**
+ * A caller's props with the handlers and ref removed.
+ *
+ * They are pulled out because they have to be composed rather than spread, and
+ * leaving them in would put the caller's copy back on top of the composed one.
+ */
+export function withoutComposed(rest: Rest, names: $ReadOnlyArray<string>): Rest {
+  const kept: { key?: empty, [string]: mixed } = {};
+  for (const name of Object.keys(rest)) {
+    // `key` is dropped whatever the caller asked to compose, because it is the
+    // one name the indexer does not speak for: writing `rest[name]` under it
+    // would put a `mixed` back where `Rest` promises nothing can be, and Flow
+    // says so. Nothing is lost — React removed the `key` long before this ran,
+    // so this is the type-level statement made at runtime rather than a filter
+    // that ever has work to do.
+    if (name !== "key" && !names.includes(name)) {
+      kept[name] = rest[name];
+    }
+  }
+  return kept;
+}