@uniflowed/ui 0.0.0-alpha.6 → 0.0.0-alpha.8

package/index.js

@@ -50,9 +50,27 @@
 // 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.
+// the answer, puts it in state. That is deliberately *not*
+// `useSyncExternalStore`: the DOM is not a store whose value a render may
+// read, and reading layout during a render is the thing that API exists to
+// prevent.
+//
+// One component does use it, and it is the case the API is actually for.
+// `toast("Saved")` is called from an event handler or a `catch`, so the queue
+// of notifications lives outside React — a store at module scope in
+// `toast.js`, read through `useSyncExternalStore` with the cached immutable
+// snapshots and the consistent server snapshot that requires. A queue is a
+// store; the DOM is not.
+//
+// That store should be an atom in `@uniflowed/state`, and was one. It is
+// written out by hand in `toast.js` because `@uniflowed/ui` is published to
+// npm and `@uniflowed/state` is not: its name has never been bound, and
+// binding it takes a person with an `npm login` session and a 2FA prompt —
+// ubugeeei-prod/uf#210. A published package whose dependency is missing
+// installs as nothing, `ETARGET` on the first thing a user types, so this
+// package cannot declare that dependency until the name exists. The queue
+// moves back to `@uniflowed/state` when #210 binds it. The local store is the
+// shippable design, not the better one.
 //
 // # Server and client
 //
@@ -71,26 +89,57 @@
 // - `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.
+// - `select.js` — the other half of the combobox pattern: the select-only one,
+//   with typeahead, option groups and a value a form can submit.
 // - `tabs.js` — the roving `tabindex`, and automatic versus manual activation.
+// - `toast.js` — the live region that was watching before there was anything
+//   to announce, and the countdown that stops.
 // - `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.
+// - `switch.js`, `checkbox.js` and `toggle.js` — the three two-state controls,
+//   apart because a reader is told something different by each, and because the
+//   third state and the `Enter` key genuinely differ between them.
+// - `radio-group.js` — one answer out of several, and the tab stop an
+//   unanswered group would otherwise not have.
+// - `toggle-group.js` — a row of toggle buttons as one control, whose `single`
+//   mode is a radio group and is rendered by `radio-group.js` rather than
+//   written a second time.
+// - `collapsible.js`, `accordion.js` and `navigation-menu.js` — the disclosure
+//   pattern on its own, stacked, and applied to a site's navigation. The third
+//   of those exists as much to prevent `role="menu"` from being used for a list
+//   of links as to provide anything.
+// - `slider.js`, `resizable.js` and `progress.js` — the three that report a
+//   number in a range. A window splitter is a slider wearing a separator's
+//   role, which is why it is beside one rather than with the layout.
+// - `table.js` and `pagination.js` — the sort that is announced, the selection
+//   that can be mixed, and the rows a page is not showing.
 //
 // 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
+// `internal/` holds six 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.
+// last), `controlled-state.js` (what "controlled" means here),
+// `roving-focus.js` (how a set of items is found and moved between),
+// `disclosure.js` (how a button says whether a region is showing, and how a
+// closed region stays findable), `form-value.js` (what a `<form>` submits for a
+// control the browser has never heard of), and `range.js` (the arithmetic that
+// keeps `aria-valuemin`, `aria-valuemax` and `aria-valuenow` true about each
+// other). 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 {
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from "./accordion.js";
 import { Checkbox } from "./checkbox.js";
+import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from "./collapsible.js";
 import {
   ComboboxEmpty,
   ComboboxInput,
@@ -123,12 +172,85 @@ import {
   MenuSubTrigger,
   MenuTrigger,
 } from "./menu.js";
+import {
+  NavigationMenuBody,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuRoot,
+  NavigationMenuTrigger,
+} from "./navigation-menu.js";
+import {
+  PaginationContent,
+  PaginationItem,
+  PaginationNext,
+  PaginationPrevious,
+  PaginationRoot,
+} from "./pagination.js";
+import { Progress } from "./progress.js";
+import { RadioGroupIndicator, RadioGroupItem, RadioGroupRoot } from "./radio-group.js";
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "./resizable.js";
+import {
+  SelectGroup,
+  SelectGroupLabel,
+  SelectLabel,
+  SelectList,
+  SelectOption,
+  SelectRoot,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "./select.js";
+import { SliderRange, SliderRoot, SliderThumb, SliderTrack } from "./slider.js";
 import { Switch } from "./switch.js";
+import {
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRoot,
+  TableRow,
+  TableRowHeader,
+  TableRowSelect,
+  TableSelectAll,
+} from "./table.js";
 import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./tabs.js";
+import {
+  ToastAction,
+  ToastClose,
+  ToastDescription,
+  ToastRegion,
+  ToastRoot,
+  ToastTitle,
+  dismissAllToasts,
+  dismissToast,
+  toast,
+  updateToast,
+} from "./toast.js";
+import { Toggle } from "./toggle.js";
+import { ToggleGroupItem, ToggleGroupRoot } from "./toggle-group.js";
 
+export type { AccordionType } from "./accordion.js";
 export type { ActivationMode } from "./tabs.js";
+export type { Sort } from "./table.js";
+export type { Notification, ToastChanges, ToastOptions, Urgency } from "./toast.js";
+export type { ToggleGroupType } from "./toggle-group.js";
 
-export { Checkbox, Switch };
+export { Checkbox, Progress, Switch, Toggle };
+
+/**
+ * Queueing a notification, from anywhere.
+ *
+ * Functions rather than a hook, because the places a notification comes from —
+ * an event handler, a `catch`, a Server Action's error path — do not have a
+ * component to hold state in. `Toast.Region` is what displays them.
+ *
+ *     const id = toast("Uploading…", { duration: null });
+ *     updateToast(id, { content: "Uploaded", duration: 4000 });
+ *     toast("Could not save", { urgency: "assertive" });
+ */
+export { dismissAllToasts, dismissToast, toast, updateToast };
 
 /**
  * An accessible form field.
@@ -170,6 +292,114 @@ export const Tabs = {
   Panel: TabsPanel,
 };
 
+/**
+ * A button and the region it shows, with the three attributes that say so.
+ *
+ * The content stays in the document while it is closed, so the browser's
+ * find-in-page can still reach the text in it.
+ *
+ *   <Collapsible.Root>
+ *     <Collapsible.Trigger>Details</Collapsible.Trigger>
+ *     <Collapsible.Content>…</Collapsible.Content>
+ *   </Collapsible.Root>
+ */
+export const Collapsible = {
+  Root: CollapsibleRoot,
+  Trigger: CollapsibleTrigger,
+  Content: CollapsibleContent,
+};
+
+/**
+ * A stack of disclosures that know about each other.
+ *
+ * `Accordion.Header` takes the heading `level`, because which heading an
+ * accordion's sections are depends on where the accordion sits. Each panel is a
+ * region named after the header that opens it.
+ *
+ *   <Accordion.Root type="single">
+ *     <Accordion.Item value="shipping">
+ *       <Accordion.Header level={3}>
+ *         <Accordion.Trigger>Shipping</Accordion.Trigger>
+ *       </Accordion.Header>
+ *       <Accordion.Content>…</Accordion.Content>
+ *     </Accordion.Item>
+ *   </Accordion.Root>
+ */
+export const Accordion = {
+  Root: AccordionRoot,
+  Item: AccordionItem,
+  Header: AccordionHeader,
+  Trigger: AccordionTrigger,
+  Content: AccordionContent,
+};
+
+/**
+ * Site navigation: a list of links behind buttons, and not a `menu`.
+ *
+ *   <NavigationMenu.Root aria-label="Main">
+ *     <NavigationMenu.List>
+ *       <NavigationMenu.Item value="docs">
+ *         <NavigationMenu.Trigger>Docs</NavigationMenu.Trigger>
+ *         <NavigationMenu.Body>
+ *           <NavigationMenu.Link href="/guide">Guide</NavigationMenu.Link>
+ *         </NavigationMenu.Body>
+ *       </NavigationMenu.Item>
+ *     </NavigationMenu.List>
+ *   </NavigationMenu.Root>
+ */
+export const NavigationMenu = {
+  Root: NavigationMenuRoot,
+  List: NavigationMenuList,
+  Item: NavigationMenuItem,
+  Trigger: NavigationMenuTrigger,
+  Body: NavigationMenuBody,
+  Link: NavigationMenuLink,
+};
+
+/**
+ * One answer out of several, with the arrow keys that check as they move.
+ *
+ * `Tab` reaches the chosen answer, or the first one while there is none, and
+ * leaves the whole group in one press. `name` puts the answer where a form can
+ * submit it.
+ *
+ *   <Field.Root>
+ *     <Field.Label>Plan</Field.Label>
+ *     <Field.Control
+ *       render={(props) => (
+ *         <RadioGroup.Root {...props} defaultValue="free" name="plan">
+ *           <RadioGroup.Item value="free">
+ *             Free <RadioGroup.Indicator>●</RadioGroup.Indicator>
+ *           </RadioGroup.Item>
+ *           <RadioGroup.Item value="pro">Pro</RadioGroup.Item>
+ *         </RadioGroup.Root>
+ *       )}
+ *     />
+ *   </Field.Root>
+ */
+export const RadioGroup = {
+  Root: RadioGroupRoot,
+  Item: RadioGroupItem,
+  Indicator: RadioGroupIndicator,
+};
+
+/**
+ * A row of toggle buttons that behaves as one control.
+ *
+ * `type="multiple"` is a group of toggle buttons, any number of them pressed.
+ * `type="single"` is a radio group drawn as segments, and is rendered by
+ * `RadioGroup` rather than written a second time.
+ *
+ *   <ToggleGroup.Root aria-label="Formatting" type="multiple">
+ *     <ToggleGroup.Item value="bold">B</ToggleGroup.Item>
+ *     <ToggleGroup.Item value="italic">I</ToggleGroup.Item>
+ *   </ToggleGroup.Root>
+ */
+export const ToggleGroup = {
+  Root: ToggleGroupRoot,
+  Item: ToggleGroupItem,
+};
+
 /**
  * A modal dialog: focus moved in, kept in, and given back.
  *
@@ -257,3 +487,166 @@ export const Combobox = {
   Empty: ComboboxEmpty,
   Status: ComboboxStatus,
 };
+
+/**
+ * The other half of the combobox pattern: a button, a list, and no typing.
+ *
+ * Use a native `<select>` when a native `<select>` will do — `select.js` says
+ * so first and means it. This is for the popup a `<select>` cannot draw.
+ *
+ *   <Select.Root defaultValue="GB" name="country">
+ *     <Select.Label>Country</Select.Label>
+ *     <Select.Trigger>
+ *       <Select.Value placeholder="Choose one" />
+ *     </Select.Trigger>
+ *     <Select.List>
+ *       <Select.Group>
+ *         <Select.GroupLabel>Europe</Select.GroupLabel>
+ *         <Select.Option value="GB">United Kingdom</Select.Option>
+ *         <Select.Option value="FR">France</Select.Option>
+ *       </Select.Group>
+ *       <Select.Separator />
+ *       <Select.Option value="JP">Japan</Select.Option>
+ *     </Select.List>
+ *   </Select.Root>
+ *
+ * `Select.Label` names the field and `Select.GroupLabel` names a group of
+ * options. shadcn has one `SelectLabel` and it is the second of those; a select
+ * needs both, so they are two parts here.
+ */
+export const Select = {
+  Root: SelectRoot,
+  Label: SelectLabel,
+  Trigger: SelectTrigger,
+  Value: SelectValue,
+  List: SelectList,
+  Option: SelectOption,
+  Group: SelectGroup,
+  GroupLabel: SelectGroupLabel,
+  Separator: SelectSeparator,
+};
+
+/**
+ * Notifications, in a live region that was watching before them.
+ *
+ * Render `Toast.Region` once, in the layout; `toast()` from anywhere.
+ *
+ *   <Toast.Region>
+ *     {(each) => (
+ *       <Toast.Root>
+ *         <Toast.Title>{each.content}</Toast.Title>
+ *         <Toast.Action onClick={undo}>Undo</Toast.Action>
+ *         <Toast.Close />
+ *       </Toast.Root>
+ *     )}
+ *   </Toast.Region>
+ */
+export const Toast = {
+  Region: ToastRegion,
+  Root: ToastRoot,
+  Title: ToastTitle,
+  Description: ToastDescription,
+  Action: ToastAction,
+  Close: ToastClose,
+};
+
+/**
+ * A value in a range, with `role="slider"` on the thumb where it belongs.
+ *
+ * One thumb or two; a range is the same component with a second one, each
+ * bounded by its neighbour and each needing its own name.
+ *
+ *   <Slider.Root defaultValue={[20, 60]} valueText={(each) => `£${each}`}>
+ *     <Slider.Track>
+ *       <Slider.Range />
+ *     </Slider.Track>
+ *     <Slider.Thumb aria-label="Minimum" index={0} />
+ *     <Slider.Thumb aria-label="Maximum" index={1} />
+ *   </Slider.Root>
+ */
+export const Slider = {
+  Root: SliderRoot,
+  Track: SliderTrack,
+  Range: SliderRange,
+  Thumb: SliderThumb,
+};
+
+/**
+ * Two panes and the splitter between them, operable from the keyboard.
+ *
+ *   <Resizable.PanelGroup defaultValue={30}>
+ *     <Resizable.Panel primary>Files</Resizable.Panel>
+ *     <Resizable.Handle label="Resize the file list" />
+ *     <Resizable.Panel>Editor</Resizable.Panel>
+ *   </Resizable.PanelGroup>
+ */
+export const Resizable = {
+  PanelGroup: ResizablePanelGroup,
+  Panel: ResizablePanel,
+  Handle: ResizableHandle,
+};
+
+/**
+ * A table, with the four things about one nobody gets right by hand.
+ *
+ * A real `<table>`, deliberately not a `role="grid"` — `table.js` says why —
+ * and its own live region, so a re-sort is something a reader is told about
+ * rather than something that happens silently behind them.
+ *
+ *   <Table.Root onSortChange={setSort} rowCount={500} rowOffset={90} sort={sort}>
+ *     <Table.Caption>People</Table.Caption>
+ *     <Table.Header>
+ *       <Table.Row>
+ *         <Table.Head>
+ *           <Table.SelectAll checked={all} onCheckedChange={setAll} />
+ *         </Table.Head>
+ *         <Table.Head column="name">Name</Table.Head>
+ *       </Table.Row>
+ *     </Table.Header>
+ *     <Table.Body>
+ *       {page.map((person, at) => (
+ *         <Table.Row index={at} key={person.id}>
+ *           <Table.Cell>
+ *             <Table.RowSelect
+ *               checked={chosen.has(person.id)}
+ *               label={`Select ${person.name}`}
+ *               onCheckedChange={(on) => choose(person.id, on)}
+ *             />
+ *           </Table.Cell>
+ *           <Table.RowHeader>{person.name}</Table.RowHeader>
+ *         </Table.Row>
+ *       ))}
+ *     </Table.Body>
+ *   </Table.Root>
+ */
+export const Table = {
+  Root: TableRoot,
+  Caption: TableCaption,
+  Header: TableHeader,
+  Body: TableBody,
+  Row: TableRow,
+  Head: TableHead,
+  RowHeader: TableRowHeader,
+  Cell: TableCell,
+  SelectAll: TableSelectAll,
+  RowSelect: TableRowSelect,
+};
+
+/**
+ * The navigation a paginated table needs, and the sentence that says it moved.
+ *
+ *   <Pagination.Root page={4} pageCount={25}>
+ *     <Pagination.Content>
+ *       <Pagination.Previous disabled={page === 1} href={hrefFor(page - 1)}>‹</Pagination.Previous>
+ *       <Pagination.Item current href={hrefFor(4)}>4</Pagination.Item>
+ *       <Pagination.Next href={hrefFor(page + 1)}>›</Pagination.Next>
+ *     </Pagination.Content>
+ *   </Pagination.Root>
+ */
+export const Pagination = {
+  Root: PaginationRoot,
+  Content: PaginationContent,
+  Item: PaginationItem,
+  Previous: PaginationPrevious,
+  Next: PaginationNext,
+};

package/internal/disclosure.js

@@ -0,0 +1,97 @@
+// @flow
+//
+// The other pattern every part of this package keeps writing.
+//
+// `roving-focus.js` is the keyboard half of these components. This is the
+// other half, and it is one sentence: **a button says whether a region is
+// showing, and names it.** `Dialog.Trigger` and `Menu.Trigger` are that
+// sentence, and so are a collapsible, an accordion header and an expandable
+// entry in a site's navigation — three components that look nothing alike and
+// are the same three attributes underneath.
+//
+// Two rules make it up, and both of them fail silently.
+//
+//   * **Name it only while it is there.** `aria-controls` pointing at an id
+//     nothing has tells a reader there is somewhere to go and then has nowhere
+//     to send them, and `aria-labelledby` pointing at a missing element makes a
+//     screen reader announce *nothing at all* rather than falling back to the
+//     element's own text. So a panel reports whether it is in the document, and
+//     whatever names it only claims the name while the report says yes. This is
+//     the same subscription `Tabs.Panel` makes to `Tabs.Tab`, for the same
+//     reason.
+//   * **A closed panel is hidden, not absent.** `Tabs.Panel` returns `null`
+//     when it is not selected, which is right for a tab set — the panels are
+//     alternatives, and a reader looking for text in one of them is looking at
+//     the wrong tab. It is wrong for a disclosure: the browser's find-in-page
+//     cannot find text in a section that is not in the document, so a
+//     forty-section FAQ becomes forty sections a reader has to open by hand to
+//     search. `hidden="until-found"` is the platform's answer — the browser
+//     reveals the section, fires `beforematch`, and scrolls to the match —
+//     and it works in Chrome since 102 (2022-05), Firefox since 148 (2026-02)
+//     and Safari since 26.2 (2025-12, which does not yet scroll to the match);
+//     checked 2026-09-06. Everywhere else it degrades to a plain `hidden`,
+//     which is what the panel would have been anyway.
+//
+// # Why `useUntilFound` is a hook and not a prop
+//
+// Because React 19 cannot say `hidden="until-found"`. `hidden` is on React's
+// list of boolean attributes, so `<div hidden="until-found">` renders
+// `hidden=""` — the string is truthy, and truthy is all React keeps. There is
+// no prop spelling that produces the attribute, which is a thing worth knowing
+// before spending an afternoon looking for one.
+//
+// So the panel is rendered with the ordinary boolean `hidden` — which is what
+// the server sends, and what keeps a closed section closed before any
+// JavaScript arrives — and an effect *upgrades* the attribute afterwards. It is
+// an upgrade rather than a fight: React sets `hidden=""` when it commits, this
+// runs after that commit, and the next time React changes the prop it removes
+// or re-adds the attribute and this upgrades it again. Nothing here writes an
+// attribute React believes it owns while React believes it.
+//
+// # Why this is `internal/` and not a subpath
+//
+// The same reason `roving-focus.js` gives. These are rules about markup this
+// package emits — that a trigger and its panel agree on an id, that a panel is
+// the element carrying `hidden` — and they hold because the components build
+// both halves. Exported, they would be advice.
+
+import { useEffect } from "@uniflowed/react";
+
+/**
+ * Report that this part is in the document, for as long as it is.
+ *
+ * `register` is the setter from whatever names this part; it is called with
+ * `true` on mount and `false` on unmount, and taking it as a possibly-missing
+ * function lets a part be rendered outside the thing that would name it
+ * without the caller having to care.
+ */
+export hook usePresence(register: ((present: boolean) => void) | void): void {
+  useEffect(() => {
+    if (register == null) {
+      return;
+    }
+    register(true);
+    return () => register(false);
+  }, [register]);
+}
+
+/**
+ * Keep a closed panel hidden the way the platform means it: findable.
+ *
+ * The element must be rendered with a plain boolean `hidden` as well — see the
+ * module header. This only upgrades the attribute React has already committed,
+ * so a browser that has never heard of `until-found` sees exactly the `hidden`
+ * it would have seen, and one that has can reveal the section for a
+ * find-in-page hit.
+ */
+export hook useUntilFound(ref: { current: HTMLElement | null }, open: boolean): void {
+  useEffect(() => {
+    const element = ref.current;
+    // Nothing to do while it is open: React has removed the attribute, and
+    // adding one back would hide a panel the reader just opened.
+    if (element == null || open) {
+      return;
+    }
+    element.setAttribute("hidden", "until-found");
+  }, [ref, open]);
+}

package/internal/form-value.js

@@ -0,0 +1,83 @@
+// @flow
+//
+// What a `<form>` submits for a control the browser has never heard of.
+//
+// Every widget in this package is a `button` or a `div` wearing an ARIA role,
+// which is what makes it styleable and what makes it invisible to form
+// submission: `new FormData(form)` collects the form's *listed* elements, and a
+// `<div role="listbox">` is not one. So a Select inside a form submitted
+// nothing at all, and a Combobox submitted `Combobox.Input`'s value — which is
+// the label the reader sees and not the value the application meant. A country
+// picker posted "United Kingdom" where the server was waiting for `GB`.
+//
+// The fix is one hidden `<input>` carrying the real value, rendered only when
+// the caller asked for one by giving a `name`. No `name`, no control: a Select
+// used to drive a filter has nothing to submit, and a form field the caller
+// never named is not one this package should invent.
+//
+// # Why a hidden input and not a hidden `<select>`
+//
+// Rendering a real, visually hidden `<select>` is the other answer, and it buys
+// two things: the browser autofills it, and `required` gets native constraint
+// validation. Both were tried and neither survives contact with the
+// accessibility tree.
+//
+// A `<select>` is focusable, so it is announced. A reader who tabs into the
+// widget hears the styled combobox and then a second, invisible combobox with
+// the same options — the duplicate-announcement bug that makes people describe
+// a component library as "noisy". Taking it out of the tree means
+// `aria-hidden="true"`, and `aria-hidden` on a focusable element is itself the
+// violation: it hides the element from a screen reader while leaving it in the
+// tab order, so the reader lands on something their software says is not there.
+// `tabindex="-1"` plus `aria-hidden` closes that hole and gives up the tab
+// order, which is the autofill affordance the native control was for.
+//
+// And native validation cannot work here either. The browser reports a
+// constraint failure by focusing the invalid control and drawing a bubble at
+// it; on a control with no box, Chrome logs "An invalid form control with
+// name='country' is not focusable" and refuses to submit the form at all, with
+// nothing shown to the reader. A headless select's `required` therefore belongs
+// to `@uniflowed/form` and `@uniflowed/validator`, which is where uf already
+// put every other rule, and `Field.Error` is where the message goes.
+//
+// An `<input type="hidden">` is none of those things: never focusable, never in
+// the accessibility tree, never validated, and always submitted. What it costs
+// is autofill, which is a real loss and is written down rather than hidden —
+// a browser will not fill a hidden input the way it fills `<select
+// name="country">`.
+//
+// # This is not how `@uniflowed/form` reads a value
+//
+// Worth stating because the two look like they overlap and do not.
+// `@uniflowed/form` holds values in its own store and calls `preventDefault()`
+// on submit, so it never builds a `FormData` and never sees this element. A
+// Select bound to that library is bound through `useController` — `field.value`
+// into `value`, `field.onChange` into `onValueChange` — and needs no `name`
+// here at all. This element is for the other kind of form: a plain `<form
+// action={…}>`, a Server Action, or anything else that submits the document.
+//
+// # Why this is `internal/` and not a subpath
+//
+// It is one sentence about what this package promises a form, and the failure
+// mode of writing it twice is that Select and Combobox disagree about what a
+// disabled control submits. Exported, it would be a `<HiddenInput>` a consumer
+// could reach for in a component that had not thought about any of the above.
+
+"use client";
+
+/**
+ * The control a form actually reads.
+ *
+ * `value` is the widget's value, not its label. `null` renders an empty string
+ * rather than omitting the control, so a form that submits a Select the reader
+ * left alone still carries the field — a key missing from the payload and a key
+ * present and empty are different questions to a server, and "the reader saw
+ * this field and chose nothing" is the second one.
+ *
+ * `disabled` is passed through rather than interpreted: a disabled control is
+ * omitted from the submission by the browser, which is the behaviour a native
+ * `<select disabled>` has and the one a caller who disabled the widget expects.
+ */
+export component FormValue(name: string, value: string | null, disabled?: boolean = false) {
+  return <input disabled={disabled} name={name} type="hidden" value={value ?? ""} />;
+}

package/internal/merge-props.js

@@ -75,6 +75,39 @@
  */
 export type Rest = { readonly key?: empty, readonly [string]: mixed };
 
+/**
+ * A caller's props on their way to another *part of this package*, rather than
+ * onto an intrinsic element.
+ *
+ * `Rest` names `key` out of its indexer and types it `empty`, which is a true
+ * sentence and is what stopped thirty-two intrinsics being rejected for a
+ * property that cannot be there. It has a second consequence, and it only shows
+ * up the first time one part of this package renders another —
+ * `ToggleGroup.Root` rendering a `RadioGroup.Root`, which is how `single` mode
+ * avoids being a second copy of the radio group. Creating
+ * `<RadioGroup.Root {...rest} />` has Flow check the props object against that
+ * component's own `...rest: Rest`, `key` included, and the indexer answers
+ * `mixed` for it rather than the named `empty`:
+ *
+ *     error[incompatible-type]: Cannot create RadioGroupRoot element because in
+ *     property key: unknown is incompatible with empty.
+ *
+ * So a part is spreadable onto a `<div>` and not onto a sibling part. That is a
+ * hole in the type rather than a fact about the props, and this is the one
+ * place it is papered over — a named function rather than an `as $FlowFixMe` at
+ * the call site, so there is somewhere to say what is and is not lost.
+ *
+ * What is lost is nothing that was ever checked. Every element this package
+ * renders has `any`-typed props today, for the reason `Rest` gives above: uf
+ * does not merge Flow's `jsx.js` environment, so `$JSXIntrinsics` is the
+ * bare-bones table in `lib/react.js` and `key` is the only property of an
+ * element anything verifies. On the day that changes and `Rest` becomes
+ * `React.PropsOf`, this function is what gets deleted.
+ */
+export function forwarded(rest: Rest): $FlowFixMe {
+  return rest;
+}
+
 /**
  * Call the caller's handler and then the component's.
  *