@jonmilner/ui 0.0.0-stage → 0.1.1

package/dist/docs/Menu.md

@@ -0,0 +1,181 @@
+# Menu
+
+## Purpose
+
+A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a toolbar's overflow. Built on Base UI's Menu, which owns the keyboard and focus: arrow keys, Home and End move through the items, typing jumps to a matching item, Esc and an outside click close it, and focus returns to the trigger. The parts add the look: a raised surface with a border and shadow, a highlighted item, a zoom-and-fade that is a plain fade under reduced motion.
+
+## When to use
+
+- Several actions on one object that would crowd the layout as buttons.
+- Actions that need no input of their own; each item runs one thing.
+
+## When not to use
+
+- Picking a value for a form field: use a select (v0.2 forms) or radio buttons; for several values from a long list, use `MultiSelect`.
+- Navigation between pages: use links; a menu of links hides where they go.
+- One or two actions: show them as buttons.
+- Content a user reads, or anything interactive inside the list (fields, toggles): use a popover or a dialog.
+
+## Rules
+
+- Compose the parts: `Menu` > `Menu.Trigger` + `Menu.Popup` > `Menu.Item`, `Menu.Separator`, `Menu.Group`. `Menu` holds the open state and renders no element, so it takes no `className` or `style`; every other part does, plus style props.
+- `Menu.Trigger` is a bare `Clickable`: give it its look with style props (or your own class), and an accessible name. An icon-only trigger needs `aria-label`.
+- For a trigger that reads as a button ("Actions", "New"), pass Button's `variant`, `size`, `iconStart` or `iconEnd` (a `ChevronDownIcon` for "Actions ▾"): it renders a `Button`, with its fill, border and height, and keeps the trigger's behavior and `aria-disabled`. While the menu is open it shows Button's open look, a held tint and an inset ring (ADR 0063); a bare trigger has none, so style it yourself off `aria-expanded`. Style props still override the defaults.
+- `Menu.Item` runs its `onClick` on click, Enter and Space, then the menu closes. Pass `closeOnClick={false}` to keep it open.
+- `variant="danger"` marks a destructive item. It still runs on one click, so open a confirm dialog from it (Cancel focused first) before anything irreversible happens.
+- `disabled` on an item renders `aria-disabled`: it stays announced and reachable with the arrow keys, and does nothing. On the trigger it keeps the button focusable and stops it opening.
+- `Menu.Group` takes a `label` that is shown and names the group. Separate groups with `Menu.Separator`.
+- The popup portals into the trigger's nearest `ThemeProvider`, so it keeps the brand and mode. That provider must not clip or stack its content: wrap the app root, and keep a nested provider off elements with `overflow: hidden`, a `transform` or their own `z-index`, or the popup is clipped or drawn under siblings. It sits on `zIndex` `popover`. A menu opened only through `open`, with no `Menu.Trigger`, has no provider to find and portals to `<body>`.
+- Item text is wrapped in `Text` for you; an `Icon` beside it is spaced by the item's `gap`.
+- `side` (`bottom` by default) and `align` (`start`) place the popup against the trigger; it flips when it would overflow the viewport.
+- Never add key handlers or `tabIndex` to the parts; Base UI handles the keyboard.
+- The module has no hooks, so a server component can render the parts; `onClick` and other functions must come from a client component.
+
+## Do
+
+```tsx
+<Menu>
+  <Menu.Trigger aria-label="Actions for Invoice 42" paddingInline="8" borderRadius="sm">
+    <MoreIcon />
+  </Menu.Trigger>
+  <Menu.Popup>
+    <Menu.Item onClick={edit}>Edit</Menu.Item>
+    <Menu.Item onClick={duplicate}>Duplicate</Menu.Item>
+    <Menu.Separator />
+    <Menu.Item variant="danger" onClick={() => setConfirming(true)}>
+      Delete
+    </Menu.Item>
+  </Menu.Popup>
+</Menu>
+```
+
+```tsx
+<Menu.Popup>
+  <Menu.Group label="Sort by">
+    <Menu.Item onClick={() => sort("newest")}>Newest</Menu.Item>
+    <Menu.Item onClick={() => sort("oldest")}>Oldest</Menu.Item>
+  </Menu.Group>
+</Menu.Popup>
+```
+
+```tsx
+<Menu>
+  <Menu.Trigger variant="secondary" size="sm">
+    Actions
+  </Menu.Trigger>
+  <Menu.Popup>
+    <Menu.Item onClick={archive}>Archive</Menu.Item>
+  </Menu.Popup>
+</Menu>
+```
+
+## Don't
+
+```tsx
+// Deletes on one click with no way back: confirm it in a dialog first.
+<Menu.Item variant="danger" onClick={deleteForever}>
+  Delete
+</Menu.Item>
+```
+
+```tsx
+// Base UI already moves focus with the arrow keys; this fights it.
+<Menu.Item onKeyDown={(event) => event.key === "ArrowDown" && next()}>Edit</Menu.Item>
+```
+
+```tsx
+// A link list is navigation, not a menu of actions.
+<Menu.Item onClick={() => navigate("/settings")}>Settings</Menu.Item>
+```
+
+## Accessibility
+
+- The trigger has `aria-haspopup="menu"` and `aria-expanded`; the popup is `role="menu"` labelled by the trigger, items are `role="menuitem"`, groups are `role="group"` named by their label.
+- Opening from the keyboard focuses the first item; from the pointer, the popup. Focus stays in the menu until it closes, then returns to the trigger.
+- The highlighted item gets a fill (`bgMuted` in light mode; in dark mode `bgRaised` with 10% `fg` mixed in, since `bgMuted` sits too close to the popup there), and the shared focus ring when reached from the keyboard. Under forced colors it is `Highlight` with `HighlightText`, disabled items are `GrayText`, and the popup keeps its border.
+- The danger item's `danger` color passes 4.5:1 on the popup and on the highlight fill in every preset (`Menu.test.tsx` checks it, with `fg` and `fgMuted`); the word ("Delete") carries the meaning, not the color.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Menu
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `defaultOpen` | `boolean` | no | Whether the menu is initially open.  To render a controlled menu, use the `open` prop instead. |
+| `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
+| `loopFocus` | `boolean` | no | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
+| `modal` | `boolean` | no | Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed.  On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.  Nested menus ignore this prop, and menus opened by hover are never modal. |
+| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | no | Event handler called when the menu is opened or closed. |
+| `open` | `boolean` | no | Whether the menu is currently open. |
+
+### Menu.Group
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no | The content of the component. |
+| `className` | `string` | no |  |
+| `label` | `ReactNode` | yes |  |
+| `style` | `CSSProperties` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Menu.Item
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | no |  |
+| `closeOnClick` | `boolean` | no | Whether to close the menu when the item is clicked. |
+| `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
+| `id` | `string` | no |  |
+| `label` | `string` | no | Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided. |
+| `nativeButton` | `boolean` | no | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
+| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | no | The click handler for the menu item. |
+| `style` | `CSSProperties` | no |  |
+| `variant` | `"danger" \| "neutral"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Menu.Popup
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `align` | `"center" \| "end" \| "start"` | no | How to align the popup relative to the specified side.  Submenus and menubars default to `'start'`. |
+| `children` | `ReactNode` | no |  |
+| `className` | `string` | no |  |
+| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` | no | Determines the element to focus when the menu is closed.  - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
+| `id` | `string` | no |  |
+| `side` | `"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"` | no | Which side of the anchor element to align the popup against. May automatically change to avoid collisions.  Submenus and vertical menubars default to `'inline-end'`. |
+| `style` | `CSSProperties` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Menu.Separator
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | no |  |
+| `orientation` | `"horizontal" \| "vertical"` | no | The orientation of the separator. |
+| `style` | `CSSProperties` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Menu.Trigger
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `closeDelay` | `number` | no | How long to wait before closing the menu that was opened on hover. Specified in milliseconds.  Requires the `openOnHover` prop. |
+| `delay` | `number` | no | How long to wait before the menu may be opened on hover. Specified in milliseconds.  Requires the `openOnHover` prop. |
+| `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
+| `handle` | `MenuHandle<unknown>` | no | A handle to associate the trigger with a menu. |
+| `iconEnd` | `ComponentType` | no |  |
+| `iconStart` | `ComponentType` | no |  |
+| `openOnHover` | `boolean` | no | Whether the menu should also open when the trigger is hovered. |
+| `payload` | `unknown` | no | A payload to pass to the menu when it is opened. |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `variant` | `"primary" \| "secondary"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/MultiSelect.md

@@ -0,0 +1,120 @@
+# MultiSelect
+
+## Purpose
+
+A form field for picking any number of values from a list too long to show at once. A trigger styled as Button's secondary look opens a listbox of options; each selected option shows a check mark, and the trigger summarises the selection as the joined labels, or a count ("3 selected") once the labels would not fit. Built on Base UI's `Select` in multiple mode (ADR 0003), which owns the keyboard and focus: arrow keys, Home and End move through the options, typing jumps to a match, Esc and an outside click close it, and focus returns to the trigger. It composes `Field` for its label, description and error (ADR 0026).
+
+## When to use
+
+- Choosing several values from a list of roughly more than five to seven options in a form or a filter ("Regions", "Labels", "Assignees").
+- A field where the list is too long to lay out as checkboxes but every option is a plain label.
+
+## When not to use
+
+- A few options, all visible on the page: use `ChipGroup multiple`.
+- A short list shown inline, each with its own label: use a `Checkbox` group in a `Field`.
+- Actions: use `Menu`; a multi-select picks values and runs nothing.
+- One choice out of several: use a radio group or a single select.
+- Search, filtering or async options: wait for Select and Combobox (v0.2, ADR 0026).
+- Users who need to see every selected value at once: use `Chip` or `ChipGroup`, or show the selection beside the field.
+
+## Rules
+
+- `label` is required and names the field. `description` and `error` render below the trigger through `Field`; a non-empty `error` marks the field invalid and joins the trigger's `aria-describedby`.
+- `options` is a list of `{ value, label, disabled? }`. `label` is plain text: it is shown in the list and in the trigger summary.
+- `value` with `onValueChange` controls it; `defaultValue` leaves it uncontrolled. Both are arrays of option values, and `onValueChange` gets the new array.
+- `name` makes each selected value submit as its own `name=value` pair, as a `<select multiple>` does; read them with `formData.getAll(name)`. Nothing selected submits nothing.
+- `placeholder` (`"Select"`) shows while nothing is selected. `countLabel` (`"{count} selected"`) is the summary once the joined labels do not fit; `{count}` is replaced with the number selected. Translate both. One selected label that does not fit is truncated, not replaced by a count.
+- `disabled` takes the trigger out of the tab order and mutes the label. `required` sets `aria-required` on the trigger; report a missing value through `error`.
+- The trigger and the open listbox are both named by `label`.
+- Style props, `className` and `style` go to the `Field` around the label, trigger and messages, not to the trigger or the popup.
+- The popup portals into the trigger's nearest `ThemeProvider`, so it keeps the brand and mode. That provider must not clip or stack its content: wrap the app root, and keep a nested provider off elements with `overflow: hidden`, a `transform` or their own `z-index`. It sits on `zIndex` `popover`, below the trigger by default, and flips when it would overflow the viewport.
+- Never add key handlers or `tabIndex`; Base UI handles the keyboard.
+- The module has no hooks, so a server component can render it; `onValueChange` must come from a client component.
+
+## Do
+
+```tsx
+<MultiSelect
+  label="Regions"
+  name="regions"
+  options={[
+    { value: "eu-west", label: "Europe West" },
+    { value: "us-east", label: "US East" },
+    { value: "ap-south", label: "Asia Pacific South" },
+  ]}
+  defaultValue={["eu-west"]}
+/>
+```
+
+```tsx
+<MultiSelect
+  label="Labels"
+  description="Filters apply as you pick."
+  options={labels}
+  value={selected}
+  onValueChange={setSelected}
+  placeholder="All labels"
+  countLabel="{count} labels"
+/>
+```
+
+```tsx
+<MultiSelect
+  label="Assignees"
+  name="assignees"
+  options={people}
+  required
+  error={missing ? "Pick at least one assignee." : undefined}
+/>
+```
+
+## Don't
+
+```tsx
+// Three options fit on screen: a checkbox group shows every choice without a click.
+<MultiSelect label="Notify me by" options={[email, sms, push]} />
+```
+
+```tsx
+// Picking one value is not a multi-select; the trigger would read "1 selected" for no reason.
+<MultiSelect label="Country" options={countries} onValueChange={([first]) => setCountry(first)} />
+```
+
+```tsx
+// A menu runs actions; MultiSelect keeps a selection.
+<MultiSelect label="Actions" options={[{ value: "delete", label: "Delete" }]} />
+```
+
+## Accessibility
+
+- The trigger is a button with `aria-haspopup="listbox"` and `aria-expanded`, labelled by the `Field` label and described by the description and error. The popup is `role="listbox"` with `aria-multiselectable="true"`, options are `role="option"` with `aria-selected`.
+- Opening from the keyboard focuses an option; focus stays in the list until it closes, then returns to the trigger. Choosing an option toggles it and leaves the list open, so several can be picked in one visit.
+- Selection is a check mark on the option as well as its highlight, so it is not color alone. The check's space is always in the row, so the text never shifts.
+- The trigger summary is text: the joined labels, or the count. When the count replaces the labels, the labels are hidden from assistive technology so the count is read once.
+- The shared focus ring shows on the trigger and, from the keyboard, on the highlighted option. Under forced colors the highlighted option is `Highlight` with `HighlightText`, and the popup keeps its border.
+
+## Props
+
+Generated from the TypeScript types.
+
+### MultiSelect
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | no |  |
+| `countLabel` | `string` | no |  |
+| `defaultValue` | `readonly string[]` | no |  |
+| `description` | `ReactNode` | no |  |
+| `disabled` | `boolean` | no |  |
+| `error` | `ReactNode` | no |  |
+| `label` | `ReactNode` | yes |  |
+| `name` | `string` | no |  |
+| `onValueChange` | `((value: string[]) => void)` | no |  |
+| `options` | `readonly Option[]` | yes |  |
+| `placeholder` | `string` | no |  |
+| `required` | `boolean` | no |  |
+| `style` | `CSSProperties` | no |  |
+| `value` | `readonly string[]` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/SearchField.md

@@ -0,0 +1,127 @@
+# SearchField
+
+## Purpose
+
+A form field for a search query: an `<input type="search">` (role `searchbox`) with a search icon at its inline start and, while it holds a value, a clear button at its inline end. Escape empties a field that has a value, and the clear button empties it and puts focus back in the input, so a keyboard user never loses their place (ADR 0087). Built on Base UI's `Input` (ADR 0003); it composes `Field` for its label, description and error (ADR 0026). Three sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
+
+## When to use
+
+- A query that searches or filters a list, a table or a page: "Search issues", "Filter accounts".
+- A toolbar or page header search, with `hideLabel` when the design shows no label. Like every `Field` control it reserves a line below the input for its error, so align it to a Button by the input's top, not its center.
+
+## When not to use
+
+- Any other single-line text: use a text field (planned); a search field announces itself as a search.
+- Picking from a known list as the user types: wait for Combobox (v0.2, ADR 0026).
+- Picking several values from a list: use `MultiSelect` or `ChipGroup`.
+
+## Rules
+
+- `label` is required and names the input, even when the design shows none: pass `hideLabel` to keep it for assistive technology and hide it from sight. Never pass an empty label, and never let `placeholder` stand in for one.
+- `value` with `onValueChange` controls it; `defaultValue` leaves it uncontrolled. `onValueChange` gets the new string on each keystroke, on Escape and on clear. Debounce a slow search in the consumer.
+- Escape on a field with a value empties it and goes no further, so a surrounding `Dialog` stays open; a second Escape on the empty field reaches the Dialog. Escape during IME composition belongs to the IME.
+- The clear button shows only while the field holds a value and is not disabled. Its name is `clearLabel` (`"Clear search"`); translate it. The input always reserves its room, so the first keystroke moves nothing.
+- `description` and `error` render below the input through `Field`; a non-empty `error` marks the field invalid (`aria-invalid`, a danger border) and joins the input's `aria-describedby`.
+- `disabled` uses the native `disabled`: the input leaves the tab order and does not submit, with a dashed border. `required` sets the native `required`.
+- `name` submits the query with its form. An uncontrolled field does not follow a native form reset; control it if the form resets.
+- Style props, `className` and `style` go to the `Field` around the label, input and messages, not to the input.
+- `inputProps` reach the input: `ref`, `id`, `autoFocus`, `autoComplete`, `spellCheck`, `enterKeyHint`, `maxLength`, `onKeyDown` and `aria-*` such as `aria-controls` (ADR 0093). `label` owns the name, Field owns `aria-invalid`, `aria-describedby` and `aria-errormessage`, and `disabled` and `required` own their state, so those, `aria-readonly` and `aria-hidden` are not among them.
+- A consumer `onKeyDown` runs before the field's own. Escape still clears unless that handler called `event.preventDefault()`. A prevented Escape also propagates, so a surrounding Dialog closes on it.
+- A consumer `ref` gets the input, and the clear button still returns focus to it. A consumer `id` takes over from Field's generated one at hydration, and the label follows it.
+- Wrapping the field in a search landmark (`<search>` or `role="search"`, with the form around it) is the page's job, not the field's.
+- The module has no hooks, so a server component can render it; `onValueChange`, and an `inputProps` `ref` or `onKeyDown`, must come from a client component.
+
+## Do
+
+```tsx
+<SearchField label="Search issues" hideLabel placeholder="Title or number" name="q" />
+```
+
+```tsx
+<SearchField
+  label="Filter accounts"
+  description="Matches the name or the last four digits."
+  value={query}
+  onValueChange={setQuery}
+/>
+```
+
+```tsx
+<search>
+  <form action="/search">
+    <SearchField label="Search the docs" hideLabel name="q" size="lg" />
+  </form>
+</search>
+```
+
+```tsx
+// A "/" shortcut focuses the field; the results list is the input's `aria-controls`.
+const ref = useRef<HTMLInputElement>(null);
+<SearchField
+  label="Search issues"
+  hideLabel
+  value={query}
+  onValueChange={setQuery}
+  inputProps={{ ref, autoComplete: "off", "aria-controls": "issue-results" }}
+/>;
+```
+
+## Don't
+
+```tsx
+// Another name for the input: `label` names it, visible or not.
+<SearchField label="Search issues" inputProps={{ "aria-label": "Find" }} />
+```
+
+```tsx
+// The placeholder is not a name: it disappears on the first keystroke.
+<SearchField label="" placeholder="Search" />
+```
+
+```tsx
+// A search field for plain text input: it is announced as a search.
+<SearchField label="Your name" />
+```
+
+```tsx
+// Another clear button: the field has its own.
+<Inline gap="8">
+  <SearchField label="Search" value={q} onValueChange={setQ} />
+  <IconButton label="Clear" icon={XIcon} onClick={() => setQ("")} />
+</Inline>
+```
+
+## Accessibility
+
+- The input is a `searchbox` named by the label, visible or not; the search icon is hidden from assistive technology.
+- The clear button is a named button in the tab order after the input. Activating it, by pointer or keyboard, empties the field and moves focus to the input, never to `body`.
+- Escape clears without closing a surrounding Dialog; on an empty field it passes through.
+- Showing and hiding the clear button shifts nothing: the input's inline-end padding always holds it.
+- Invalid adds a danger border and the error message with its icon, never color alone; disabled adds a dashed border. Every size is at least 24 px tall, and the clear button meets the 24 by 24 CSS px target size. Under forced colors the border, text and disabled state use system colors.
+
+## Props
+
+Generated from the TypeScript types.
+
+### SearchField
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | no |  |
+| `clearLabel` | `string` | no |  |
+| `defaultValue` | `string` | no |  |
+| `description` | `ReactNode` | no |  |
+| `disabled` | `boolean` | no |  |
+| `error` | `ReactNode` | no |  |
+| `hideLabel` | `boolean` | no |  |
+| `inputProps` | `SearchFieldInputProps` | no |  |
+| `label` | `ReactNode` | yes |  |
+| `name` | `string` | no |  |
+| `onValueChange` | `((value: string) => void)` | no |  |
+| `placeholder` | `string` | no |  |
+| `required` | `boolean` | no |  |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `style` | `CSSProperties` | no |  |
+| `value` | `string` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Stack.md

@@ -0,0 +1,79 @@
+# Stack
+
+## Purpose
+
+A vertical column of children with even space between them. `Stack` is a `Box` with `display="flex"` and `flexDirection="column"` as default style props, spaced by a required `gap`. Children render as they are: no wrapper per child.
+
+## When to use
+
+- Vertical rhythm inside a panel, card, form or page section: `<Stack gap="16">`.
+- A list whose items sit apart by a fixed step: `<Stack as="ul" gap="8">`.
+- A column that becomes a row at a breakpoint: `flexDirection={{ base: "column", med: "row" }}`.
+
+## When not to use
+
+- A row of items that wraps (buttons, tags, metadata): use `Inline`.
+- A two-dimensional layout: use `Box` with `display="grid"`.
+- One child, or spacing only on one side: use `Box` with padding or margin.
+
+## Rules
+
+- `gap` is required and takes spacing tokens only: px keys (`"16"`) or a responsive object (`{ base: "8", med: "16" }`). No raw lengths, no `md`.
+- Space comes from `gap`, never from margins on the children.
+- It takes every `Box` prop, and the layout defaults are style props, so `display`, `flexDirection` and `alignItems` override them.
+- Children are not wrapped, so each child is a flex item: it stretches to the column's width unless `alignItems` says otherwise.
+- The consumer's `className` comes last and `style` is passed through; `ref` is a plain prop typed for the `as` element.
+
+## Do
+
+```tsx
+<Stack gap="24">
+  <Heading>Settings</Heading>
+  <Text>Choose how the app looks.</Text>
+</Stack>
+```
+
+```tsx
+<Stack as="ul" gap="8" aria-label="Recent files">
+  <li>…</li>
+</Stack>
+```
+
+## Don't
+
+```tsx
+// Margins on children instead of gap; and `gap` is required.
+<Stack>
+  <Box marginBlockEnd="16">…</Box>
+</Stack>
+```
+
+```tsx
+// A wrapper only to space children adds a needless element; Stack spaces them directly.
+<Stack gap="16">
+  <div>
+    <Text>Name</Text>
+  </div>
+  <div>
+    <Text>Email</Text>
+  </div>
+</Stack>
+```
+
+## Accessibility
+
+- Stack adds no role or ARIA. Pick the element with `as`: `ul` with `li` children for a list, `section` with a label for a region.
+- Visual order is source order; do not use `flexDirection="column-reverse"` to reorder meaningful content, since reading and focus order follow the source.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Stack
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+| `gap` | `"0" \| "1" \| "2" \| "4" \| "6" \| "8" \| "12" \| "16" \| "20" \| "24" \| "32" \| "40" \| "48" \| "64" \| "80" \| "96"` (responsive) | yes |  |
+
+Also accepts every `<div>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Tabs.md

@@ -0,0 +1,130 @@
+# Tabs
+
+## Purpose
+
+Switches between views that share one place on the page. The parts are `Tabs` (the root, a flex column; a row when vertical), `Tabs.List` (the `tablist`), `Tabs.Tab` (a `tab` button on `Clickable`) and `Tabs.Panel` (the `tabpanel`). Built on Base UI `Tabs` (ADR 0003, 0046): it owns the selection, one tab stop with arrow-key roving, `aria-selected`, and the ids that tie each tab to its panel. The selected tab shows an accent bar that fades and grows in (ADR 0049).
+
+## When to use
+
+- Peer views of one thing (a message's Details, Activity and Files), where one shows at a time and switching keeps the page.
+- Filtering one list into a few fixed buckets (Inbox, Archive, Sent).
+
+## When not to use
+
+- Moving between pages or routes: use links (`Clickable as="a"`) in a `nav`. Tabs do not change the URL and the panels are not separate pages.
+- A sequence the user must go through in order: use a stepper.
+- Two or three options that set a value in a form: use a radio group.
+- Content that should be readable at once, or compared side by side: show it all, or use sections with headings.
+
+## Rules
+
+- Name the list: `aria-label` or `aria-labelledby` on `Tabs.List`.
+- Every `Tabs.Tab` has a `value`, and the `Tabs.Panel` with the same `value` is its panel. Values are any type; strings read best.
+- Uncontrolled: `defaultValue` (Base UI's default is `0`, so set it). Controlled: `value` with `onValueChange`. `onValueChange` is a function, so a server component cannot pass it; control the tabs from a client component.
+- Arrow keys move focus (Up and Down when `orientation="vertical"`), looping at the ends; Home and End jump; Enter or Space selects. Set `activateOnFocus` on the list to select on arrow keys too, only when panels render without a wait. Tab moves from the list into the panel, which is focusable.
+- `disabled` on a tab renders `aria-disabled`: the tab stays focusable and announced but cannot be selected. Set `value` or `defaultValue` to an enabled tab; on the server Base UI cannot skip a disabled first tab.
+- Hidden panels unmount. Set `keepMounted` on a panel to keep its state (a form, a scroll position) while hidden; it renders with `hidden`.
+- Tab labels are text: the tab wraps its children in `Text` (`sm`, the `label` font, `medium`); pass `size`, `font`, `weight` or `leading` on the tab to change it. Do not put a `Text` inside. Labels are short and never truncated.
+- Every part takes style props. The root's `display`, `flexDirection`, `flexWrap` (`wrap` when vertical, so the panel drops below the list when there is no room; `nowrap` when horizontal) and `gap` (`"16"`), the panel's `flexGrow` (`1`), the list's `display`, `flexWrap` (`wrap`, so tabs wrap rather than overlap at 320px or 200% text), `gap` (`"4"`) and `position` (`relative`, which the indicator needs), and the tab's `paddingInline` (`"12"`), `justifyContent` (`start`), `minBlockSize` (`"med"`, 40px), `position` and `color` (`fgMuted`) are defaults you can replace. `color` sets the resting tab; a selected or hovered tab is always `fg`. A vertical list is a column with its hairline on the inline end; that follows `orientation`, not style props. When horizontal tabs wrap onto a second row, a selected tab on the first row has its bar between the rows; keep tab sets short enough for one row where you can. Keep padding off the list's block end (inline end when vertical): the indicator sits on the hairline at the tab's edge. Never set a tab below `"xs"` (24px). `className` is a string and `style` an object (not Base UI's state functions), and the consumer's come last.
+- The module has no hooks: a server component can render `Tabs` and its parts (the Base UI parts inside are client components). `render` is not accepted on the parts.
+- Style off the ARIA state (`[aria-selected='true']`, `[aria-disabled='true']`, `[aria-orientation='vertical']`), never a class.
+
+## Do
+
+```tsx
+<Tabs defaultValue="details">
+  <Tabs.List aria-label="Message">
+    <Tabs.Tab value="details">Details</Tabs.Tab>
+    <Tabs.Tab value="activity">Activity</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="details">
+    <Details />
+  </Tabs.Panel>
+  <Tabs.Panel value="activity">
+    <Activity />
+  </Tabs.Panel>
+</Tabs>
+```
+
+```tsx
+// Controlled, from a client component.
+<Tabs value={tab} onValueChange={setTab}>
+  …
+</Tabs>
+```
+
+## Don't
+
+```tsx
+// An unnamed tablist.
+<Tabs.List>…</Tabs.List>
+```
+
+```tsx
+// Tabs as site navigation: each "tab" is a page. Use links in a nav.
+<Tabs.Tab value="/settings" onClick={() => navigate("/settings")}>
+  Settings
+</Tabs.Tab>
+```
+
+```tsx
+// Text is already there; this nests a second one.
+<Tabs.Tab value="inbox">
+  <Text>Inbox</Text>
+</Tabs.Tab>
+```
+
+## Accessibility
+
+- Follows the WAI-ARIA tabs pattern: `tablist`, `tab` with `aria-selected` and `aria-controls`, `tabpanel` with `aria-labelledby`. Before hydration the tabs have `tabindex="-1"` and no `aria-controls`; Base UI fills them in on the client.
+- The selected tab is shown by a 2px accent bar (3:1 on `bg` in both modes, `Highlight` under forced colors) and by its text turning `fg`, never by color alone.
+- The bar fades and grows in; reduced motion leaves the fade (ADR 0019, 0049).
+- Tabs and the panel take the library's focus ring. Tabs are at least 24px tall (WCAG 2.2 target size).
+- A disabled tab is reduced to half opacity (`GrayText` under forced colors) and stays discoverable; say why it is disabled nearby when it is not obvious.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Tabs
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `defaultValue` | `any` | no | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
+| `onValueChange` | `((value: any, eventDetails: TabsRootChangeEventDetails) => void)` | no | Callback invoked when new value is being set.  The event `reason` is `'none'` for user-initiated changes, such as a click or keyboard navigation; `'initial'` for the first automatic selection or fallback in uncontrolled roots when `defaultValue` is omitted or `undefined`, including when the implicit initial value is disabled or missing; `'disabled'` for automatic fallback when the selected tab becomes disabled in uncontrolled roots; or `'missing'` for automatic fallback when the selected tab is removed, or when an explicit `defaultValue` never matches a mounted tab in uncontrolled roots.  For automatic changes, the selected value can be `null` when no enabled Tab is available as a fallback.  Automatic changes cannot be canceled; calling `eventDetails.cancel()` for `'initial'`, `'disabled'`, or `'missing'` has no effect. |
+| `orientation` | `"horizontal" \| "vertical"` | no | The component orientation (layout flow direction). |
+| `value` | `any` | no | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Tabs.List
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `activateOnFocus` | `boolean` | no | Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press. |
+| `loopFocus` | `boolean` | no | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Tabs.Panel
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `keepMounted` | `boolean` | no | Whether to keep the HTML element in the DOM while the panel is hidden. |
+| `value` | `any` | yes | The value of the TabPanel. It will be shown when the Tab with the corresponding value is active. |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Tabs.Tab
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | no | Whether the Tab is disabled.  If a first Tab on a `<Tabs.List>` is disabled, it won't initially be selected. Instead, the next enabled Tab will be selected. However, it does not work like this during server-side rendering, as it is not known during pre-rendering which Tabs are disabled. To work around it, ensure that `defaultValue` or `value` on `<Tabs.Root>` is set to an enabled Tab's value. |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `nativeButton` | `boolean` | no | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `value` | `any` | yes | The value of the Tab. |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).