@uniflowed/ui 0.0.0-alpha.2

package/index.js

@@ -0,0 +1,103 @@
+// @flow
+//
+// `@uniflowed/ui`: components you own, with the behaviour you would get wrong.
+//
+// The premise is the one shadcn established and it is the right one: a
+// component library that ships styles is a library you fight, so these ship
+// none. Every part takes `className` and every other DOM prop and passes it
+// through; what they contribute is the part that is genuinely hard and
+// genuinely invisible when it is missing.
+//
+// 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.
+//
+// # 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.
+
+import {
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  FieldRoot,
+} from "./internal/field.js";
+import {
+  DialogClose,
+  DialogContent,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+} from "./internal/dialog.js";
+import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./internal/tabs.js";
+import { Checkbox, Switch } from "./internal/switch.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} />} />
+ *     <Field.Description>We will not share it.</Field.Description>
+ *     <Field.Error>{error}</Field.Error>
+ *   </Field.Root>
+ */
+export const Field = {
+  Root: FieldRoot,
+  Label: FieldLabel,
+  Control: FieldControl,
+  Description: FieldDescription,
+  Error: FieldError,
+};
+
+/**
+ * Tabs, with the arrow-key behaviour the pattern requires.
+ *
+ *   <Tabs.Root defaultValue="one">
+ *     <Tabs.List>
+ *       <Tabs.Tab value="one">One</Tabs.Tab>
+ *       <Tabs.Tab value="two">Two</Tabs.Tab>
+ *     </Tabs.List>
+ *     <Tabs.Panel value="one">…</Tabs.Panel>
+ *     <Tabs.Panel value="two">…</Tabs.Panel>
+ *   </Tabs.Root>
+ */
+export const Tabs = {
+  Root: TabsRoot,
+  List: TabsList,
+  Tab: TabsTab,
+  Panel: TabsPanel,
+};
+
+/**
+ * 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.Root>
+ */
+export const Dialog = {
+  Root: DialogRoot,
+  Trigger: DialogTrigger,
+  Content: DialogContent,
+  Title: DialogTitle,
+  Close: DialogClose,
+};

package/internal/dialog.js

@@ -0,0 +1,236 @@
+// @flow
+//
+// A modal dialog, which is the component people most often get wrong.
+//
+// Four things have to be true for a dialog to be usable by someone who is not
+// using a mouse, and a hand-written one usually has one or two of them:
+//
+//   * Focus moves into the dialog when it opens, and to the first thing worth
+//     acting on rather than to whatever happens to be first in the document.
+//   * Tab cannot leave. A dialog you can Tab out of leaves the reader
+//     somewhere in a page they cannot see, with no way back.
+//   * Escape closes it.
+//   * Focus returns to whatever opened it. Otherwise it restarts at the top of
+//     the document, and the reader has to find their place again.
+//
+// The dialog is rendered where it is declared rather than through a portal.
+// A portal solves a stacking-context problem that belongs to CSS, and it costs
+// the thing this component is for: rendered in place, the dialog is next to its
+// trigger in the accessibility tree, which is where a screen reader looks.
+
+import * as React from "@uniflowed/react";
+
+import { composeHandlers, composeRefs, withoutComposed } from "./props.js";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+type DialogState = {|
+  readonly base: string,
+  readonly open: boolean,
+  readonly setOpen: (open: boolean) => void,
+  readonly triggerRef: { current: HTMLElement | null },
+|};
+
+const DialogContext: React.Context<DialogState | null> = createContext(null);
+
+function useDialog(part: string): DialogState {
+  const state = useContext(DialogContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Dialog.Root`);
+  }
+  return state;
+}
+
+/** The dialog, open or closed. Uncontrolled unless `open` is given. */
+export component DialogRoot(
+  children: React.Node,
+  defaultOpen?: boolean = false,
+  open?: boolean,
+  onOpenChange?: (open: boolean) => void,
+) {
+  const base = useId();
+  const [internal, setInternal] = useState(defaultOpen);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const isOpen = open ?? internal;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (open == null) {
+        setInternal(next);
+      }
+      onOpenChange?.(next);
+    },
+    [open, onOpenChange],
+  );
+
+  const state = useMemo(
+    () => ({ base, open: isOpen, setOpen, triggerRef }),
+    [base, isOpen, setOpen],
+  );
+
+  return <DialogContext.Provider value={state}>{children}</DialogContext.Provider>;
+}
+
+/** What opens the dialog, and what focus comes back to when it closes. */
+export component DialogTrigger(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const dialog = useDialog("Dialog.Trigger");
+  const passed = withoutComposed(rest, ["onClick", "ref"]);
+
+  return (
+    <button
+      {...passed}
+      aria-expanded={dialog.open ? "true" : "false"}
+      aria-haspopup="dialog"
+      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(true))}
+      ref={composeRefs(rest.ref, (element) => {
+        dialog.triggerRef.current = element;
+      })}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The dialog itself: focus moved in, Tab kept inside, Escape closing it.
+ *
+ * `aria-modal` tells a screen reader that the rest of the page is not
+ * available, which is the half of "modal" that CSS cannot express.
+ */
+export component DialogContent(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const dialog = useDialog("Dialog.Content");
+  const contentRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!dialog.open) {
+      return;
+    }
+    const opener = dialog.triggerRef.current;
+    const content = contentRef.current;
+    // The first thing worth acting on, not the first thing in the document —
+    // and the dialog itself if it contains nothing focusable, so focus is
+    // inside it either way.
+    const target = content == null ? null : (focusable(content)[0] ?? content);
+    target?.focus();
+
+    return () => {
+      // Back to the trigger. Leaving focus on a removed node sends it to the
+      // top of the document, and the reader has to find their place again.
+      opener?.focus();
+    };
+  }, [dialog.open, dialog.triggerRef]);
+
+  if (!dialog.open) {
+    return null;
+  }
+
+  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+
+  return (
+    <div
+      // `passed` first. A caller `ref` used to replace `contentRef`, which
+      // left it null, made the Tab branch below return early, and turned the
+      // focus trap off while the dialog still announced `aria-modal="true"`.
+      // A caller `onKeyDown` used to replace this one, and Escape stopped
+      // closing the dialog.
+      {...passed}
+      aria-labelledby={`${dialog.base}-title`}
+      aria-modal="true"
+      id={`${dialog.base}-content`}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          dialog.setOpen(false);
+          return;
+        }
+        if (event.key !== "Tab") {
+          return;
+        }
+        const content = contentRef.current;
+        if (content == null) {
+          return;
+        }
+        const stops = focusable(content);
+        if (stops.length === 0) {
+          // Nothing to move to, so Tab must not leave either.
+          event.preventDefault();
+          return;
+        }
+        const first = stops[0];
+        const last = stops[stops.length - 1];
+        const active = content.ownerDocument?.activeElement;
+        // Wrap at the ends. This is the whole of "focus cannot leave": every
+        // other Tab press is the browser's own business.
+        if (event.shiftKey && (active === first || active === content)) {
+          event.preventDefault();
+          last.focus();
+        } else if (!event.shiftKey && active === last) {
+          event.preventDefault();
+          first.focus();
+        }
+      })}
+      ref={composeRefs(rest.ref, (element) => {
+        contentRef.current = element;
+      })}
+      role="dialog"
+      tabIndex={-1}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** The dialog's accessible name, which `aria-labelledby` points at. */
+export component DialogTitle(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const dialog = useDialog("Dialog.Title");
+  return (
+    <h2 {...rest} id={`${dialog.base}-title`}>
+      {children}
+    </h2>
+  );
+}
+
+/** A button that closes the dialog. */
+export component DialogClose(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const dialog = useDialog("Dialog.Close");
+  const passed = withoutComposed(rest, ["onClick"]);
+
+  return (
+    <button
+      {...passed}
+      onClick={composeHandlers(rest.onClick, () => dialog.setOpen(false))}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/**
+ * The focus stops inside an element, in document order.
+ *
+ * Disabled controls and `tabindex="-1"` are excluded because the browser
+ * excludes them, and anything inside `[hidden]` or `aria-hidden` is excluded
+ * because a reader cannot see it.
+ */
+function focusable(root: HTMLElement): Array<HTMLElement> {
+  const selector =
+    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  return Array.from(root.querySelectorAll(selector)).filter(
+    (element: any) =>
+      // Both attributes hide a whole subtree, so both are checked on the
+      // ancestors. Reading `aria-hidden` off the element alone returned a
+      // button inside `<div aria-hidden="true">` as a focus stop, and the trap
+      // then moved focus to a control no screen reader exposes.
+      element.closest("[hidden]") == null && element.closest('[aria-hidden="true"]') == null,
+  );
+}

package/internal/field.js

@@ -0,0 +1,161 @@
+// @flow
+//
+// An accessible form field, wired up for you.
+//
+// The hard part of a form field is not the markup, it is the wiring: the label
+// has to point at the control, the description and the error message have to be
+// named by `aria-describedby`, the control has to say `aria-invalid` when it is
+// wrong, and every id has to be unique on the page and stable across renders.
+// Doing that by hand is four attributes and two `useId` calls per field, and
+// getting one wrong is silent — the field looks right and a screen reader
+// announces nothing.
+//
+// So the parts read the ids off a context the root creates. `Field.Label` knows
+// which control it labels because there is exactly one in its root, and
+// `Field.Error` registers itself so the control can point at it only when it is
+// actually rendered — pointing `aria-describedby` at an id that is not in the
+// document makes a screen reader announce nothing at all, which is worse than
+// omitting the attribute.
+
+import * as React from "@uniflowed/react";
+import { createContext, useContext, useId, useMemo, useState } from "@uniflowed/react";
+
+type FieldState = {|
+  readonly controlId: string,
+  readonly labelId: string,
+  readonly descriptionId: string,
+  readonly errorId: string,
+  readonly invalid: boolean,
+  readonly describedBy: string | void,
+  readonly registerDescription: (present: boolean) => void,
+  readonly registerError: (present: boolean) => void,
+|};
+
+const FieldContext: React.Context<FieldState | null> = createContext(null);
+
+/**
+ * The field a part belongs to.
+ *
+ * Raising rather than returning null: a `Field.Label` outside a `Field.Root`
+ * would render a label pointing at nothing, and would look correct.
+ */
+function useField(part: string): FieldState {
+  const state = useContext(FieldContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Field.Root`);
+  }
+  return state;
+}
+
+/**
+ * The field's container, and the only place ids are made.
+ *
+ * `invalid` is the root's business rather than the control's because three
+ * parts have to agree about it: the control says `aria-invalid`, the error
+ * message is rendered or not, and the control's `aria-describedby` includes the
+ * error's id or not.
+ */
+export component FieldRoot(
+  children: React.Node,
+  invalid?: boolean = false,
+  ...rest: { readonly [string]: mixed }
+) {
+  const base = useId();
+  const [hasDescription, setHasDescription] = useState(false);
+  const [hasError, setHasError] = useState(false);
+
+  const state = useMemo(() => {
+    const descriptionId = `${base}-description`;
+    const errorId = `${base}-error`;
+    // Only ids that are in the document. `aria-describedby` naming a missing
+    // element makes a screen reader announce nothing rather than skipping it.
+    const described = [
+      hasDescription ? descriptionId : null,
+      invalid && hasError ? errorId : null,
+    ].filter(Boolean);
+
+    return {
+      controlId: `${base}-control`,
+      labelId: `${base}-label`,
+      descriptionId,
+      errorId,
+      invalid,
+      describedBy: described.length === 0 ? undefined : described.join(" "),
+      registerDescription: setHasDescription,
+      registerError: setHasError,
+    };
+  }, [base, invalid, hasDescription, hasError]);
+
+  return (
+    <FieldContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </FieldContext.Provider>
+  );
+}
+
+/** The label, pointing at the control by id rather than by nesting. */
+export component FieldLabel(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const field = useField("Field.Label");
+  // `rest` first: a caller `id` here would break the relationship the control
+  // points at, and it would break it silently.
+  return (
+    <label {...rest} htmlFor={field.controlId} id={field.labelId}>
+      {children}
+    </label>
+  );
+}
+
+/**
+ * The control, given every attribute the rest of the field implies.
+ *
+ * `render` takes the element rather than this rendering an `<input>`, because a
+ * field wraps a select, a textarea, a combobox or somebody else's component
+ * just as often, and each of those needs the same six attributes.
+ */
+export component FieldControl(render: (props: { readonly [string]: mixed }) => React.Node) {
+  const field = useField("Field.Control");
+  return render({
+    id: field.controlId,
+    "aria-labelledby": field.labelId,
+    "aria-describedby": field.describedBy,
+    "aria-invalid": field.invalid ? "true" : undefined,
+  });
+}
+
+/** Help text, which the control points at while it is rendered. */
+export component FieldDescription(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const field = useField("Field.Description");
+  React.useEffect(() => {
+    field.registerDescription(true);
+    return () => field.registerDescription(false);
+  }, [field]);
+
+  return (
+    <p {...rest} id={field.descriptionId}>
+      {children}
+    </p>
+  );
+}
+
+/**
+ * The error message, rendered only when the field is invalid.
+ *
+ * `role="alert"` so it is announced when it appears, which is the point of an
+ * error that arrives after a blur or a submit.
+ */
+export component FieldError(children: React.Node, ...rest: { readonly [string]: mixed }) {
+  const field = useField("Field.Error");
+  React.useEffect(() => {
+    field.registerError(true);
+    return () => field.registerError(false);
+  }, [field]);
+
+  if (!field.invalid) {
+    return null;
+  }
+  return (
+    <p {...rest} id={field.errorId} role="alert">
+      {children}
+    </p>
+  );
+}

package/internal/props.js

@@ -0,0 +1,78 @@
+// @flow
+//
+// Merging a caller's props with the ones a component owns.
+//
+// `<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`:
+//
+//   * 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
+//     `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.
+
+/** Anything a caller can spread onto an element. */
+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 —
+ * `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: { [string]: mixed } = {};
+  for (const key of Object.keys(rest)) {
+    if (!names.includes(key)) {
+      kept[key] = rest[key];
+    }
+  }
+  return kept;
+}

package/internal/switch.js

@@ -0,0 +1,122 @@
+// @flow
+//
+// A switch, and a checkbox that is not an `<input>`.
+//
+// Both exist because the styled version of a checkbox is almost always a `div`
+// with a tick drawn in it, and the moment it stops being an `<input>` it stops
+// being announced, stops toggling on Space, and stops being reachable by Tab.
+// These keep all three: the role, the `aria-checked` state, and the keys.
+//
+// A switch is not a checkbox. A checkbox has three states — on, off and
+// indeterminate — and a switch has two; a screen reader says "on"/"off" for one
+// and "checked"/"unchecked" for the other. Using the wrong one is the kind of
+// mistake that is invisible until somebody uses the thing.
+
+import * as React from "@uniflowed/react";
+import { useCallback, useState } from "@uniflowed/react";
+
+import { composeHandlers, withoutComposed } from "./props.js";
+
+/** Space toggles, and so does Enter, because both do on a native control. */
+function toggleKeys(event: SyntheticKeyboardEvent<HTMLElement>, toggle: () => void): void {
+  if (event.key !== " " && event.key !== "Enter") {
+    return;
+  }
+  // Space scrolls the page otherwise, which is what makes a hand-written
+  // toggle feel broken even when it works.
+  event.preventDefault();
+  toggle();
+}
+
+/** State for a control that may be controlled or not. */
+function useToggle(
+  checked: boolean | void,
+  defaultChecked: boolean,
+  onCheckedChange: ((checked: boolean) => void) | void,
+): [boolean, () => void] {
+  const [internal, setInternal] = useState(defaultChecked);
+  const current = checked ?? internal;
+
+  const toggle = useCallback(() => {
+    const next = !current;
+    if (checked == null) {
+      setInternal(next);
+    }
+    onCheckedChange?.(next);
+  }, [checked, current, onCheckedChange]);
+
+  return [current, toggle];
+}
+
+/** A two-state switch: on or off. */
+export component Switch(
+  checked?: boolean,
+  defaultChecked?: boolean = false,
+  onCheckedChange?: (checked: boolean) => void,
+  disabled?: boolean = false,
+  children?: React.Node,
+  ...rest: { readonly [string]: mixed }
+) {
+  const [on, toggle] = useToggle(checked, defaultChecked, onCheckedChange);
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <button
+      {...passed}
+      aria-checked={on ? "true" : "false"}
+      disabled={disabled}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          toggle();
+        }
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (!disabled) {
+          toggleKeys(event, toggle);
+        }
+      })}
+      role="switch"
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/** A checkbox, which may also be indeterminate. */
+export component Checkbox(
+  checked?: boolean,
+  defaultChecked?: boolean = false,
+  indeterminate?: boolean = false,
+  onCheckedChange?: (checked: boolean) => void,
+  disabled?: boolean = false,
+  children?: React.Node,
+  ...rest: { readonly [string]: mixed }
+) {
+  const [on, toggle] = useToggle(checked, defaultChecked, onCheckedChange);
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown"]);
+
+  return (
+    <button
+      {...passed}
+      // "mixed" is the third state, and it is why a checkbox cannot simply be
+      // a switch with a different label.
+      aria-checked={indeterminate ? "mixed" : on ? "true" : "false"}
+      disabled={disabled}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          toggle();
+        }
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        if (!disabled) {
+          toggleKeys(event, toggle);
+        }
+      })}
+      role="checkbox"
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}

package/internal/tabs.js

@@ -0,0 +1,270 @@
+// @flow
+//
+// Tabs, with the keyboard behaviour the pattern requires.
+//
+// A tab list is not a row of buttons. Only one tab is in the page's tab order —
+// Tab moves *into* and *out of* the list, and the arrow keys move between the
+// tabs inside it — because a list of twelve tabs that each take a Tab press
+// makes the rest of the page unreachable for anyone not using a mouse. That is
+// a roving `tabindex`, and it is the thing hand-written tabs almost always
+// leave out.
+//
+// This is also where Flow says something no other type system can. `Tabs.List`
+// takes `renders* TabsTab`, so putting a `<button>` in the list is a type
+// error rather than a screen reader announcing "button" where the user expects
+// "tab, 2 of 5".
+
+import * as React from "@uniflowed/react";
+
+import { composeHandlers, composeRefs, withoutComposed } from "./props.js";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "@uniflowed/react";
+
+type TabsState = {|
+  readonly base: string,
+  readonly selected: string,
+  readonly select: (value: string) => void,
+  readonly register: (value: string, element: HTMLElement | null, disabled: boolean) => void,
+  /**
+   * Focus the tab `pick` chooses, given where we are and how many there are.
+   *
+   * `pick` returns the index to aim for and the direction to keep searching in
+   * when that tab is disabled. The direction cannot be inferred from the
+   * index: `End` aims at the last tab and, if it is disabled, has to walk
+   * *backwards* to the last enabled one — inferring "forwards" from the target
+   * being ahead of us wrapped around to the first tab instead.
+   */
+  readonly focusBy: (from: string, pick: (at: number, count: number) => [number, 1 | -1]) => void,
+|};
+
+const TabsContext: React.Context<TabsState | null> = createContext(null);
+
+function useTabs(part: string): TabsState {
+  const state = useContext(TabsContext);
+  if (state == null) {
+    throw new Error(`${part} must be rendered inside a Tabs.Root`);
+  }
+  return state;
+}
+
+/**
+ * The tab set.
+ *
+ * Uncontrolled by default and controlled when `value` is given, which is the
+ * distinction every one of these components needs: a form library owns the
+ * value, and a page that just wants tabs does not.
+ */
+export component TabsRoot(
+  children: React.Node,
+  defaultValue: string,
+  value?: string,
+  onValueChange?: (value: string) => void,
+  ...rest: { readonly [string]: mixed }
+) {
+  const base = useId();
+  const [internal, setInternal] = useState(defaultValue);
+  const selected = value ?? internal;
+  // The order tabs were mounted in, which is document order, and is what the
+  // arrow keys move through.
+  const order = useRef<Array<string>>([]);
+  const elements = useRef<{ [string]: HTMLElement }>({});
+
+  const select = useCallback(
+    (next: string) => {
+      if (value == null) {
+        setInternal(next);
+      }
+      onValueChange?.(next);
+    },
+    [value, onValueChange],
+  );
+
+  const disabledTabs = useRef<{ [string]: boolean }>({});
+
+  const register = useCallback((tab: string, element: HTMLElement | null, disabled: boolean) => {
+    if (element == null) {
+      order.current = order.current.filter((entry) => entry !== tab);
+      delete elements.current[tab];
+      delete disabledTabs.current[tab];
+      return;
+    }
+    if (!order.current.includes(tab)) {
+      order.current.push(tab);
+    }
+    elements.current[tab] = element;
+    disabledTabs.current[tab] = disabled;
+  }, []);
+
+  /**
+   * Focus and select the first enabled tab at or after `index`.
+   *
+   * Disabled tabs are stepped over rather than landed on. Selecting one meant
+   * the panel changed to a tab that cannot take focus, so focus stayed where
+   * it was and the next arrow press started from the wrong place — after which
+   * the tabs beyond the disabled one were unreachable by keyboard.
+   */
+  const focusAt = useCallback(
+    (index: number, step: number = 1) => {
+      const tabs = order.current;
+      if (tabs.length === 0) {
+        return;
+      }
+      const wrap = (at: number) => ((at % tabs.length) + tabs.length) % tabs.length;
+      const direction = step === 0 ? 1 : step;
+
+      for (let tried = 0; tried < tabs.length; tried += 1) {
+        const tab = tabs[wrap(index + tried * direction)];
+        if (disabledTabs.current[tab] === true) {
+          continue;
+        }
+        select(tab);
+        // Selection follows focus, which is the pattern for tabs whose panels
+        // are already in the document: one key press per tab rather than an
+        // arrow and then a space.
+        elements.current[tab]?.focus();
+        return;
+      }
+      // Every tab is disabled, so there is nowhere to go.
+    },
+    [select],
+  );
+
+  const state = useMemo(
+    () => ({
+      base,
+      selected,
+      select,
+      register,
+      focusBy: (from: string, pick: (at: number, count: number) => [number, 1 | -1]) => {
+        const [target, direction] = pick(order.current.indexOf(from), order.current.length);
+        focusAt(target, direction);
+      },
+    }),
+    [base, selected, select, register, focusAt],
+  );
+
+  return (
+    <TabsContext.Provider value={state}>
+      <div {...rest}>{children}</div>
+    </TabsContext.Provider>
+  );
+}
+
+/**
+ * The row of tabs.
+ *
+ * `renders* TabsTab` is the constraint: the children have to be tabs. A
+ * `<button>` here would be announced as a button inside a tablist, which is
+ * how a keyboard user ends up unable to tell where they are.
+ */
+export component TabsList(children: renders* TabsTab, ...rest: { readonly [string]: mixed }) {
+  return (
+    <div {...rest} role="tablist">
+      {children}
+    </div>
+  );
+}
+
+/** One tab. Exactly one of them is in the page's tab order. */
+export component TabsTab(
+  value: string,
+  children: React.Node,
+  disabled?: boolean = false,
+  ...rest: { readonly [string]: mixed }
+) {
+  const tabs = useTabs("Tabs.Tab");
+  const active = tabs.selected === value;
+
+  const passed = withoutComposed(rest, ["onClick", "onKeyDown", "ref"]);
+
+  return (
+    <button
+      // `passed` first, and everything this component owns after it. A caller
+      // `ref` used to replace the registration ref, which took the tab out of
+      // the keyboard order without any sign that it had.
+      {...passed}
+      aria-controls={`${tabs.base}-panel-${value}`}
+      aria-selected={active ? "true" : "false"}
+      disabled={disabled}
+      id={`${tabs.base}-tab-${value}`}
+      onClick={composeHandlers(rest.onClick, () => {
+        if (!disabled) {
+          tabs.select(value);
+        }
+      })}
+      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
+        const intent = arrowKey(event.key);
+        if (intent == null) {
+          return;
+        }
+        // Prevent the default before moving, or the arrow also scrolls the
+        // page under the tab that just took focus.
+        event.preventDefault();
+        // `match` is an expression, so it computes the index to move to rather
+        // than performing the four movements — which also means adding a key
+        // to `arrowKey` stops compiling here until it is handled.
+        tabs.focusBy(
+          value,
+          (at, count) =>
+            match (intent) {
+              "previous" => [at - 1, -1],
+              "next" => [at + 1, 1],
+              "first" => [0, 1],
+              "last" => [count - 1, -1],
+            },
+        );
+      })}
+      ref={composeRefs(rest.ref, (element) => tabs.register(value, element, disabled))}
+      role="tab"
+      // The roving tabindex: Tab reaches the selected tab and nothing else in
+      // the list, so it moves past the whole set in one press.
+      tabIndex={active ? 0 : -1}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+/** The panel a tab controls, rendered only while its tab is selected. */
+export component TabsPanel(
+  value: string,
+  children: React.Node,
+  ...rest: { readonly [string]: mixed }
+) {
+  const tabs = useTabs("Tabs.Panel");
+  if (tabs.selected !== value) {
+    return null;
+  }
+  return (
+    <div
+      {...rest}
+      aria-labelledby={`${tabs.base}-tab-${value}`}
+      id={`${tabs.base}-panel-${value}`}
+      role="tabpanel"
+      // The panel itself is focusable so that Tab out of the tab list lands on
+      // the content the tab describes, which is where the reader expects to go.
+      tabIndex={0}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Which movement a key asks for, or nothing if the key is not ours. */
+function arrowKey(key: string): "previous" | "next" | "first" | "last" | null {
+  return match (key) {
+    "ArrowLeft" | "ArrowUp" => "previous",
+    "ArrowRight" | "ArrowDown" => "next",
+    "Home" => "first",
+    "End" => "last",
+    _ => null,
+  };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@uniflowed/ui",
+  "version": "0.0.0-alpha.2",
+  "description": "Headless, accessible React components whose composition Flow checks, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/ui"
+  },
+  "exports": {
+    "./dialog/types": "./dialog/types.js",
+    "./form/types": "./form/types.js",
+    ".": "./index.js",
+    "./types/renders": "./types/renders.js"
+  },
+  "files": [
+    "index.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@uniflowed/react": "0.0.0-alpha.2",
+    "@uniflowed/validator": "0.0.0-alpha.2"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}