@seekalfred/primitives 0.5.0 → 0.6.0

package/README.md

@@ -61,6 +61,29 @@ Two deliberate behaviour differences:
   `hidden` attribute (`display: none`), which CSS cannot transition out of.
   The chevron still rotates.
 
+### Motion (Accordion)
+
+A panel opens and closes in place with plain CSS: height follows the content on the smooth spring, opacity eases over 240ms on the way open and 160ms on the way shut, and the answer settles down from 6px up with a little blur. The chevron turns on the snappy spring. React Aria marks a collapsed panel `hidden`, which cannot transition, so the CSS keeps it as a box of no height and takes it out of the accessibility tree with `content-visibility: hidden`. Height needs `interpolate-size` (Chromium); elsewhere it snaps open, still correct. The panel's children now sit in an `accordion-panel-content` wrapper. Nothing animates at mount; reduced motion is instant.
+
+## ActionButton
+
+```tsx
+<ActionButton onAction={save} pendingLabel="Saving" successLabel="Saved">
+  Save changes
+</ActionButton>
+```
+
+A button for one async commit. Its label morphs letter by letter, from the
+resting text to a pending one to a success one: letters both share keep their
+place, new ones rise in from a soft blur, removed ones lift away, and the width
+springs to fit. The arrow becomes a spinner and then a tick that draws itself.
+
+`onAction` is awaited. A rejection returns the button to rest and goes to
+`onActionError` (without it the error is dropped, because the button has
+already returned to rest). It stays focusable while pending (`aria-disabled`,
+`aria-busy`), a live region announces the pending and success labels, and the
+accessible name is always the resting label. `variant` and `size` are Button's.
+
 ## Alert
 
 ```tsx
@@ -86,6 +109,10 @@ No `success` / `warning` / `info` variants yet — one faked call site is b
 the Rule of Two. Until then, a `className` override is the supported route;
 consumer CSS always wins.
 
+### Motion (Alert)
+
+A string `title` or description swaps as a whole when its text changes (the new text rises in, the old lifts away); a different `icon` grows in from small and blurred; the copy column springs to its new height. New optional `open` and `onDismiss` props make the alert come and go: hiding it collapses its height with the fade (the spring, opacity 240ms in and 160ms out), and `onDismiss` adds a Dismiss button (`dismissLabel`). An uncontrolled alert (`onDismiss` without `open`) collapses first and then reports; with `open`, the owner decides. An alert open on first render does not animate, and one with neither prop is the same DOM as before.
+
 ## AlertDialog
 
 ```tsx
@@ -138,6 +165,10 @@ Sizes: `xs` (20px) · `sm` (24px) · `md` (32px, default) · `lg` (40px)
 | `className="h-10 w-10"`                            | `size="lg"`                   | six ad-hoc sizes became five named ones                             |
 | `<AvatarImage src />` with no `alt`                | `alt` is **required**         | `""` for decorative; 15 of 38 legacy uses had none, which fails axe |
 
+### Motion (Avatar)
+
+A photo that is still downloading after mount fades in and un-blurs over 240ms; one already decoded shows at once. The initials fade in over 240ms while a photo loads or after it fails. New optional `presence` (`"online" | "offline"`) draws a dot on the corner that grows in on the snappy spring, swaps when it changes and shrinks away; its word is read beside the name. The root no longer clips (the dot sits on its edge); the photo clips itself to the circle.
+
 ## Badge
 
 ```tsx
@@ -184,6 +215,10 @@ the product's `--primary-*` scale, value for value — `periwinkle.50` is
 No `asChild` — zero call sites, and the legacy `[a&]:hover:` rules existed only
 for the anchor it produced.
 
+### Motion (Badge)
+
+A new string label swaps as a whole and the pill's width springs to the new size on the morph spring; colour, border and fill ease over 240ms. New optional `icon` swaps in place when it changes. The label now sits in a wrapper inside the badge, so query the root through `[data-slot="badge"]`, not through its text. The reference's hover tint is not ported.
+
 ## Breadcrumbs
 
 ```tsx
@@ -224,6 +259,11 @@ Two smaller deliberate changes: the separator is `/` rather than a lucide
 separators were the default), and hovering a crumb underlines it as well as
 darkening it — colour alone disappears under forced-colors.
 
+
+### Motion
+
+A crumb added after the first render slides in 8px from the left over 240ms and the crumbs that stay slide to their new place; link colour eases over 160ms. The trail present at first render is still. A removed crumb disappears at once (it would need a leaving copy), and the reference's underline fade is not ported: Alfred's links carry no underline at rest by design.
+
 ## Button
 
 | variant             |                                         |
@@ -246,17 +286,54 @@ Sizes: `sm` (32px) · `md` (36px, default) · `lg` (40px) · `icon` (36px
 one it has no accessible name and fails axe's `button-name` rule — the
 `IconOnly` story exists to keep that true.
 
-`buttonVariants` is exported. Use it when you need button styling on an element
-this component cannot render:
+Give it an `href` and it is a link: a real `<a>`, announced as a link, with the
+same classes and the same hover, press and focus-ring states. Use it whenever
+activating the control navigates.
 
 ```tsx
-import { buttonVariants } from "@seekalfred/primitives";
-
-<a href="/reports" className={buttonVariants({ variant: "outline" })}>
+<Button href="/reports" variant="outlineNeutral">
   View reports
-</a>;
+</Button>
 ```
 
+For client-side routing, mount React Aria's `RouterProvider` once above it;
+without one an `href` is an ordinary page load, which is what an external or
+download link wants anyway. `target`, `rel` and `download` pass through.
+
+`buttonVariants` is still exported, but it is no longer the way to style a
+link. On your own `<a>` its hover, press and focus classes never apply: they key
+on React Aria data attributes a plain anchor never receives, so keyboard focus
+is invisible.
+
+### Motion
+
+A Button moves, and every motion is pure CSS plus a little plain React where CSS
+cannot reach (no animation library):
+
+- **Press.** It scales down while pressed (0.97; 0.96 for an icon button; 0.985
+  above 220px wide) and springs back. Menu and popover triggers
+  (`aria-haspopup`, `role="combobox"`, `data-state`), disabled and pending
+  buttons never scale.
+- **A changing label.** A different text, or a different icon, crossfades: the
+  old one is popped out of flow where it was, `aria-hidden`, and lifts away
+  while the new one rises in, and the width springs to fit. Nothing animates on
+  first render. While it runs the OUTGOING label is still in the DOM, so read a
+  button's text after the change settles, and keep `id`s, inputs and anything
+  stateful out of a label that changes.
+- **`isPending`.** A spinner scales in over a label that fades; the button
+  stays focusable (`aria-disabled`) and announces itself (`aria-busy`).
+- **Hover and press** on `primary` step its opacity (0.91, 0.84) and every
+  filled and outlined variant gains a resting shadow on hover. A disabled
+  `primary` fades; the other variants stay opaque and mute their colours.
+
+Reduced motion keeps the opacity change and drops the movement and blur. The
+spring easings are `linear()` curves (Chrome 113, Safari 17.2, Firefox 112);
+older browsers get a cubic-bezier with the same overshoot.
+
+The `@seekalfred/styles` motion tokens behind it are `--ease-*` and
+`--duration-*` (`settle`, `enter`, `snappy`, `morph`, `gentle`, `calm`,
+`smooth`, `quick`, `instant`, …).
+
 ## Migrating from the legacy shadcn Button
 
 The variant and size vocabulary is unchanged, so most call sites move by
@@ -269,7 +346,7 @@ React Aria Components rather than a bare `<button>`:
 | `disabled`                       | `isDisabled`                                  |                                                                                                                  |
 | `variant="default"`              | `variant="primary"`                           | `default` named nothing.                                                                                         |
 | `size="default"`                 | `size="md"`                                   | Same 36px height.                                                                                                |
-| `<Button asChild><a /></Button>` | `<a className={buttonVariants({ variant })}>` | React Aria's Button never renders an anchor. A real `Link` primitive lands in Phase 1.                           |
+| `<Button asChild><a /></Button>` | `<Button href>`                               | Renders React Aria's Link, so the states still work. Needs `RouterProvider` for client-side routes.              |
 
 The first four are mechanical. `asChild` is not — each site needs a decision
 about whether it wanted a link or a button.
@@ -287,6 +364,34 @@ Two things that changed on purpose:
   `[data-theme="dark"]`. Every `dark:` class in the original is gone, not
   reimplemented.
 
+## ButtonGroup
+
+```tsx
+<ButtonGroup
+  label="Document actions"
+  items={[
+    { id: "edit", label: "Edit", icon: <PencilIcon aria-hidden /> },
+    { id: "share", label: "Share", reserve: ["Copied"], onSelect: copyLink },
+  ]}
+  menu={{ label: "More actions", items: [{ id: "del", label: "Delete", destructive: true }] }}
+/>
+```
+
+Related actions joined into one surface: a shared border and radius, hairline
+dividers, no gaps. One soft highlight glides between segments under the pointer or
+keyboard focus (it appears in place, and only moves between segments travel), the
+pressed segment answers inside itself, and an optional chevron segment opens more
+actions in a menu that grows from the group's edge.
+
+A segment's label can change in place without resizing it: `reserve` lists the
+other labels it can show and the segment sizes to the widest. A label that
+changes right after its segment is pressed (`Share` to `Copied`) is announced
+once. When the row does not fit, segments with an icon drop their label and keep
+the icon (`collapseLabels`). Tab visits every segment; the arrow keys along the
+orientation, Home and End move between them. `variant` is `outline` or
+`solid`, `size` is `sm` or `md`, `orientation` is `horizontal` or
+`vertical`.
+
 ## Calendar
 
 **Maturity: `experimental`.** The API may still move; `DateRangePicker` is its
@@ -328,6 +433,18 @@ so a September-focused window opens on August. Range pickers usually want
 `"start"`. It is inherited from React Aria rather than defaulted here, because
 either alignment is legitimate.
 
+### Motion
+
+Built in plain CSS and a little plain React, with no animation library.
+
+- A one-month calendar shows its month on a strip with the neighbours beside it. Moving by a month slides the strip on a spring; the other months are faded back and `inert`. A jump of more than a month (Shift + Page Down) brings the new month in from one month away instead of scrolling through the ones between. The window follows the height of the month in view.
+- The month title, now in the header beside the buttons, crosses in place: the new month arrives from the side the strip travels to while the old one leaves toward the other. React Aria's own heading stays, visually hidden, as the text.
+- In a single-date `Calendar`, the selected day's fill is one disc that glides on a straight line between days, grows in when a selection appears in a month and fades out when it leaves. Each number flips colour as the disc passes it: the day it lands on waits longer on long hops, the day it leaves waits longer on short ones.
+- Day and header buttons fill on hover, press to .94 and .96 and spring back. Nothing animates on first render. `CalendarRange` and calendars with several months keep their layout and get the press and hover motion; the range band has no motion yet.
+- Reduced motion swaps the slides and glides for plain fades or nothing.
+
+**`DatePicker`** rolls its value part by part (a later date rises in, an earlier one drops in, a part that did not change holds still, and parts after a wider or narrower one slide along). The chevron turns while the list is open, the list grows from the field and leaves quicker, and the trigger fills muted while it is open. A pick is seen for 300ms (the disc glides, the footer confirms it) before the list closes; Clear closes at once. The footer gains a status line (`selectedStatusLabel`, `emptyStatusLabel`) and takes Clear (`clearable`, `clearLabel`) out of the calendar. Reduced motion closes at once and fades.
+
 ### Loading the tokens is not optional
 
 `@seekalfred/primitives/styles.css` defines **no** token values — not
@@ -346,6 +463,54 @@ not — and the two that hurt are `--focus-ring-width` and `--focus-ring-offset`
 because their absence removes the focus indicator rather than merely shifting a
 colour. `apps/smoke` is the worked example of a correct consumer.
 
+
+## DateRangePicker
+
+```tsx
+<DateRangePicker label="Invoice dates" value={range} onChange={setRange} />
+```
+
+A trigger that **grows into the panel it opens**: one surface whose width, height,
+corners and offset ride springs from the trigger's box to the panel's and back,
+while the panel's content arrives just behind it and leaves just ahead of it. The
+panel holds a rail of presets (`presets`, with `defaultDateRangePresets` from today
+back to the start of the year), the typed start and end, and two months side by side
+(one month under a scrolling row of presets when there is no room; `months` forces
+either). **Nothing is applied until Apply**: the panel edits a draft, `onChange`
+fires on Apply, and Cancel or Escape throws the draft away. Values are `DateValue`
+objects, either end may be `null`, and `messages` renames every string.
+
+**Motion** (plain CSS and a little plain React, no animation library; the five
+springs are sampled from the reference solver):
+
+- The surface springs open on the grow spring and shrinks on a slower one; the
+  trigger's icons and its value step aside as it grows (120ms, a little blur) and
+  come back after it has shrunk; the root stays on top for half a second after
+  closing so the shrinking box never slips under a neighbour.
+- The formatted range **flies** from the trigger into the footer as the surface
+  grows and back into the trigger as it shrinks; its words roll one by one (a later
+  date rises, an earlier one drops, a word that did not change holds still).
+- Months slide together in the direction you travel: the new pair arrives from the
+  side you travel to with a little blur while the old one is kept where it stood and
+  slides away, `inert`.
+- The highlight is one bar per week under the days, which stretches from the edge the
+  range arrives from as you hover or arrow to the end day, plus a solid end at each
+  side which glides from day to day. A month that has just arrived shows its
+  highlight in place; only a change after that animates.
+- One highlight glides between the presets, and the compact row scrolls to keep the
+  active one in view. Days press to .9, buttons to .97 and the header arrows to .96.
+
+The calendar is React Aria's `RangeCalendar`, so keyboard, locale and calendar-system
+behaviour are its own; the bars and ends are measured from the cells it renders.
+`clearable` adds a Clear button in the footer. Reduced motion jumps the surface and
+swaps the slides and rolls for plain fades.
+
+**Breaking from the earlier DateRangePicker:** the panel now edits a draft that
+Apply commits (it used to commit when the second day was pressed), the calendar and
+the typed fields sit beside a preset rail, and `DateRangePicker` is its own module
+(still exported from `/date-picker`). It reads the viewer's local today for the
+presets, so `@internationalized/date` (a peer dependency) is imported at runtime.
+
 ## Card
 
 ```tsx
@@ -385,6 +550,10 @@ so `onClick` works exactly as it did — and a `div` with a click handler i
 focusable and has no role. One legacy call site does this. Use a `Button` or a
 link inside the card instead.
 
+### Motion (Card)
+
+`interactive` makes a card respond to a mouse or pen: it floats 2px on the snappy spring while pointed at, its border darkens (160ms) and its shadow deepens (240ms). Touch never lifts, reduced motion does not lift, and a card without `interactive` never moves. Not ported: a media zoom, a status line and the quick-look morph, which need slots Alfred's card does not have.
+
 ## Checkbox
 
 ```tsx
@@ -413,6 +582,45 @@ other form controls will take.
 | *(no way to set it)*  | `isIndeterminate` | `indeterminate` is a DOM property, not an attribute |
 | *(no label at all)*   | `children`        | the legacy control had no accessible name        |
 
+### Motion (Checkbox)
+
+The chosen colour grows in from small on the snappy spring while it fades in, the mark draws itself, and the check morphs into the dash and back on the morph spring (the `d` property transitions in Chromium; elsewhere it swaps). The square (not the hit area) presses to .95 in 100ms and springs back; its border eases over 160ms and darkens on hover while unchosen. **DOM:** the two glyph svgs are now one `checkbox-mark` (with `data-mark` of `check` or `indeterminate`) and a `checkbox-fill` element carries the colour, so the box's own background no longer turns primary.
+
+## ConfirmMorph
+
+```tsx
+<ConfirmMorph label="Delete project" onConfirm={deleteProject} onUndo={restoreProject} />
+<ConfirmMorph label="Delete project" confirmMode="hold" onConfirm={deleteProject} />
+```
+
+A button for destructive or important actions that asks in place. The same pill
+morphs into a question with Cancel and Confirm, then a spinner, then a result with
+Undo; its width springs to each face while the faces crossfade at their natural
+width. Use it where a dialog would be heavy.
+
+`confirmMode` is `press`, `hold` (a press held for `holdDuration` fills the
+button, and drains back if let go early) or `countdown` (a draining ring and
+ticking seconds that Cancel or Escape can still stop). Escape, a press outside,
+or `confirmTimeout` answer no; resting the pointer on it, or a hidden tab,
+pauses the clock. A press right after the question appears is the tail of the
+opening press, not an answer. A rejection shows an error face with Retry.
+Controlled with `state` and `onStateChange`. A live region announces each step,
+and focus follows the control between faces only when it was already inside.
+
+## CopyButton
+
+```tsx
+<CopyButton value={token} />
+<CopyButton value={url} iconOnly variant="plain" />
+```
+
+Copies a value and says so, calmly: the icon trades places in one soft breath
+(copy, then a tick that draws itself, or an alert if the clipboard refused), the
+label's changed letters rise in, and the button never changes width because its
+label cell reserves the widest of `Copy`, `Copied` and `Failed`. It returns to
+rest by itself, a live region announces the result, and the accessible name is
+always the resting label.
+
 ## Dialog
 
 ```tsx
@@ -458,6 +666,128 @@ Two legacy behaviours are deliberately not carried: the enter/exit animation
 and `data-exiting` for whoever adds it), and the footer's `flex-col-reverse`,
 which put DOM order and visual order in disagreement below `sm` — WCAG 1.3.2.
 
+### Motion (Dialog)
+
+The overlay fades in over 240ms and out over 160ms and blurs the page a little; the panel rises 8px and grows from .96 on the smooth spring while it fades in, and leaves over 160ms. A string `title` or `description` swaps as a whole when its text changes. The close button fills on hover and presses to .96. While the dialog leaves, the overlay lets clicks through. New `entrance` prop (`"rise"` or `"none"`) lets an edge-anchored preset opt out; Sheet does. Reduced motion is a plain fade.
+
+## EmptyState
+
+```tsx
+<EmptyState action={<Button size="sm">Clear filters</Button>}>
+  No invoices match these filters.
+</EmptyState>
+```
+
+What a list shows when it has nothing to show: one muted line, centred in a
+bordered box the width of the list. `action` is an optional next step under the
+text and is omitted from the DOM when absent.
+
+### Motion (EmptyState)
+
+New optional `icon` settles in once when the state first appears (small and transparent to rest over 480ms); a different icon component later swaps in place. A string message swaps as a whole when it changes and the message column follows its height on the smooth spring. The message now sits in an `empty-state-copy` frame.
+
+## ExpandingButtonGroup
+
+```tsx
+<ExpandingButtonGroup
+  label="Message actions"
+  items={[
+    { id: "reply", label: "Reply", icon: <ReplyIcon aria-hidden /> },
+    { id: "archive", label: "Archive", doneLabel: "Archived", icon: <ArchiveIcon aria-hidden /> },
+    { id: "delete", label: "Delete", tone: "danger", icon: <TrashIcon aria-hidden /> },
+  ]}
+/>
+```
+
+A compact pill of icon buttons. One action always shows its label; the one you
+point at or focus takes over the label while its neighbours slide aside, on a
+spring. Moving between actions needs the pointer a few pixels inside the next one,
+so resting on a boundary never flips between them. An action can confirm in place
+(`doneLabel`): the icon draws a check and the label becomes a past tense word
+without the width changing. A promise from `onSelect` keeps the button busy.
+
+On touch, the first tap reveals the label and a second tap runs the action. A
+disabled action stays focusable and still reveals its label. Arrow keys, Home and
+End rove focus.
+
+## FileDropZone
+
+```tsx
+<FileDropZone
+  label="Contract"
+  prompt="Drop a contract here"
+  hint="PDF only, up to 20 MB."
+  acceptedFileTypes={["application/pdf"]}
+  onFiles={(files) => upload(files[0])}
+/>
+```
+
+A dashed drop area with a "Choose file" button, on React Aria's `DropZone` and
+`FileTrigger`. The browser's own file control ("Choose Files / No file chosen")
+is never shown: the real input is visually hidden and the button opens it, so
+Tab reaches the button and Enter or Space opens the dialog. `hint` is where the
+accepted types and the size limit go, stated before a file is chosen.
+`acceptedFileTypes` and `allowsMultiple` reach the dialog; a drop is not
+filtered, so the consumer decides what it can read. Without `allowsMultiple`
+only the first file is handed over.
+
+### Motion (FileDropZone)
+
+The surface eases its fill over 240ms and its edge over 160ms. With a file over it, the zone breathes (swells 1.2% and settles over 2.2s, repeating) and light follows the file: a wash inside and a brighter stretch of the edge nearest it, which lean toward the pointer on a short ease (React Aria's `onDropMove` gives the position). New optional `dropPrompt` swaps in for the prompt while a file is over. Reduced motion does not breathe. Not ported: the upload list, progress bars, retry, thumbnails, paste, the compact prompt, the sheets illustration and the dashes closing into a solid edge.
+
+## FilterBar
+
+```tsx
+<FilterBar filters={filters} inline={<Input aria-label="Search" />} />
+```
+
+A list toolbar: every dropdown filter sits behind one Filters button with a count badge, and each set filter shows as a removable chip with Clear all.
+
+### Motion
+
+A chip added after the first render opens its slot from nothing while it fades up from a blur and scales in, so the chips beside it glide over; a removed chip stays while it fades and shrinks over 120ms and its slot collapses on a spring; a changed value swaps its text and the chip's width springs to it; Clear all comes and goes in its own slot; and the row follows its height when a chip makes a line wrap. Nothing animates at first render, and a removed chip is `aria-hidden` and `inert` while it leaves. The slot widths animate from and to `auto`, which needs `interpolate-size` (Chromium); elsewhere they snap, still correct. Not ported: the Add-filter button that grows into a field-and-value menu (Alfred's Filters button opens a popover of selects, which gets the Popover motion below).
+
+## FloatingButtonGroup
+
+```tsx
+<FloatingButtonGroup
+  label="Board actions"
+  items={[
+    { id: "undo", label: "Undo", icon: <UndoIcon aria-hidden />, iconOnly: true, shortcut: "⌘Z" },
+    { type: "separator" },
+    { id: "present", label: "Present", isPressed: presenting, onSelect: toggle },
+  ]}
+/>
+```
+
+Separate soft buttons in a quiet tray (a `role="toolbar"`). One shared highlight
+morphs, in position and size, to whichever button the pointer or keyboard focus is
+on, fades when the pointer leaves, and settles darker and a touch smaller while a
+button is pressed. Arrow keys move focus (skipping disabled buttons), Home and End
+jump to the ends, and only one button is a tab stop.
+
+`reserveLabels` lists the other labels an item can show, so a label change
+(`Share` to `Copied`) never moves anything. Icon-only items put their label,
+and any `shortcut` hint, in a tooltip. `isPressed` marks a mode toggle.
+`variant` is `muted` or `floating` (raised, for an overlay).
+
+## IconMorph
+
+```tsx
+<Button aria-label="Menu" aria-pressed={open} onPress={toggle}>
+  <IconMorph name="menu" state={open} />
+</Button>
+```
+
+Icons that morph between two states instead of swapping: `menu` to close, `play`
+to pause, `plus` to check, `copy` to check, `theme` (sun to moon), `chevron`
+(turned), `bell` (notifications on) and `heart` (liked). Lines rotate and slide,
+shapes interpolate their outlines, and two carry a moment of their own: the bell
+rings when it turns on, and the heart bursts when liked. Every morph rides an
+interruptible spring, so toggling quickly reverses from wherever the icon is. The
+icons are decorative: put them in a button that carries the name and
+`aria-pressed`. Each is also exported on its own (`MenuIcon`, `HeartIcon`, …).
+
 ## Input and Textarea
 
 ```tsx
@@ -483,6 +813,7 @@ invalid styling on only one of them.
 | `value` / `onChange`   | unchanged         | still a real DOM event                                      |
 | `disabled`             | unchanged         | native                                                      |
 | `aria-invalid`         | unchanged         | drives the invalid border with no prop of our own           |
+| hand-rolled `<label>` + helper + error text | `label` / `description` / `error` | optional; see below |
 | `h-9` (36px)           | density scale     | **46px at the default**, matching Button                    |
 | `text-base md:text-sm` | `text-base`       | one size; 16px avoids iOS Safari zooming on focus           |
 | `min-h-[80px]`         | `min-h-20`        | same 80px, from the spacing scale                           |
@@ -537,7 +868,90 @@ second name source makes it announce twice.
 
 **An invalid field needs a message.** The border changes colour, and colour
 alone is not a state cue (WCAG 1.4.1). Pair `aria-invalid` with
-`aria-describedby` pointing at the error text.
+`aria-describedby` pointing at the error text, or use the `error` prop below,
+which does both for you.
+
+### Label, description and error
+
+```tsx
+<Input
+  label="Email"
+  description="We only use it to send receipts."
+  error={touched && !valid ? "Enter a valid email address." : undefined}
+  value={v}
+  onChange={(e) => set(e.target.value)}
+/>
+```
+
+`Input` and `Textarea` take three optional props. `label` is a `ReactNode`
+shown above the control. `description` (helper text) and `error` are plain
+**strings**, because the library animates their copy word by word. An empty or
+`undefined` `error` closes the error row.
+
+**Passing any of the three wraps the control in a field wrapper, even when the
+value is `undefined`. Passing none leaves the DOM exactly what it was before
+these props existed:** the bare control, with no generated `id`. The wrapper is
+decided by whether the prop is present, not by its value. That is deliberate:
+`error={maybeMessage}` is the common shape, and if the wrapper came and went
+with the message, the input would move in the tree every time validation
+changed. React would remount it, losing focus and any uncontrolled value.
+Toggling `error` never remounts the input.
+
+The wiring, done for you:
+
+- `label` is tied to the control with `htmlFor`. The control keeps your `id`, or
+  gets a generated one.
+- `description` and `error` are named in `aria-describedby`, after any value
+  you passed yourself.
+- A non-empty `error` sets `aria-invalid`, so the field takes its invalid border
+  with no extra prop. Without `error`, your own `aria-invalid` still applies.
+- The error row has `role="alert"`.
+- Screen readers get the plain copy. The animated words are `aria-hidden`.
+
+Limits worth knowing:
+
+- **Do not pass `aria-label` together with `label`.** `aria-label` wins, so the
+  visible name is no longer the accessible one (WCAG 2.5.3).
+- **Inside a React Aria `TextField` the three props are ignored.** The
+  `TextField` supplies its own label and messages.
+- The alert node is inserted together with its text. Whether a given screen
+  reader announces it on insertion is not tested here, so check your own
+  combinations if announcement timing matters.
+
+### Motion
+
+The rows move, in pure CSS plus a little plain React (no animation library):
+
+- **A row opens on a spring** when `description` or `error` appears after the
+  field has mounted, and **closes the same way** when it goes away, still
+  showing its last text while it shuts. A row present on first render is just
+  there: nothing animates on mount.
+- **Changed words rise in** from a soft blur, and the old ones lift away from
+  where they stood. Words are matched by position, so changing a word near the
+  front replaces every word after it.
+- **Numbers roll digit by digit.** In copy such as "12 characters", only the
+  digits that changed move. They arrive from below when the number grew and from
+  above when it shrank. A gained digit opens its width and a lost one closes it.
+- **The row follows the copy's height**, so text that wraps opens its next line
+  instead of being clipped.
+- **Reduced motion swaps instantly.** There is no movement and no collapsed
+  frame.
+
+The `Textarea` lifts replaced words away slightly faster than `Input` (160ms
+against 180ms).
+
+### The look of a field
+
+These changes are shared by `Input`, `Textarea`, `Select` and `DatePicker`,
+because they all use `fieldSurfaceVariants`:
+
+- The border and background transition in 160ms on the settle curve. Only those
+  two properties animate; the focus outline switches without a transition.
+- **Hover and keyboard focus darken the border** to the text colour. The focus
+  ring stays, because forced-colors drops border colours and the ring is the
+  visible focus indicator.
+- A disabled field takes the muted background and does not darken on hover.
+- An invalid field always keeps its invalid border, hovered or focused.
 
 ## Label
 
@@ -589,6 +1003,91 @@ the dropped nine turns out to be wanted.
 from `useLocale()`, so `dir` on the document does **not** reach a portalled
 menu.
 
+## PageHeader
+
+```tsx
+<PageHeader
+  title="Projects"
+  description="Everything your team is working on."
+  meta="updated 14 Oct 2026"
+  actions={<Button>New project</Button>}
+/>
+```
+
+The page's single `<h1>`, in the display face at the `h3` step of the scale.
+`description` sits under it, muted and capped at a readable measure. `actions`
+share the title's row at its end and wrap below it on a narrow screen. `meta`
+sits inline after the title on its baseline. `back` is a slot above the title
+for a detail page's way back: pass your router's link, the header only sizes
+and colours it. Every slot is omitted from the DOM when its prop is absent.
+
+## PasswordField
+
+```tsx
+<PasswordField label="Password" description="At least eight characters." />
+<PasswordField
+  label="Contraseña"
+  messages={{ showPassword: "Mostrar contraseña", hidePassword: "Ocultar contraseña" }}
+/>
+```
+
+A password input with a show and hide toggle inside the field's border. Switching
+resolves the text in place (the dots or characters settle in from a soft blur, on
+every toggle but never on mount), and the eye is one outline that a slash draws
+across and undraws, cutting the outline beneath it, instead of swapping two
+icons. The toggle presses to 0.96 and springs back; the helper text opens and
+changes the way `Input`'s does (words only, so a count in it does not roll).
+
+`label` is required and visible. `description` is optional helper text.
+`messages` renames the toggle (`showPassword`, `hidePassword`, English by
+default). Native input props apply to the input, and `className` goes to the
+input; `disabled` also disables the toggle, and `aria-invalid` gives the box its
+invalid border. The box shares the field look of `Input` and `Textarea`.
+
+**The toggle's name changes with its state and it is also `aria-pressed`**, so a
+screen reader may announce both ("Hide password, pressed"); this is not tested
+with a screen reader. Reduced motion drops every transition and the press.
+
+## PasswordStrength
+
+```tsx
+<PasswordStrength label="New password" onValueChange={(value, strength) => setLevel(strength.level)} />
+<PasswordStrength label="Account password" rules={createPasswordRules({ minLength: 10 })} error={error} />
+```
+
+A new-password field that shows how strong the password is while it is typed.
+Use it when creating or changing a password; use `PasswordField` for sign in.
+Scoring happens on the device and nothing is sent anywhere.
+
+It is the `PasswordField` box and eye toggle plus three things: a four-segment
+meter, the strength word beside it, and a checklist. The segments slide in on a
+spring and change tone with the level (`destructive-strong`, `warning-strong`,
+`success-strong`); a pasted password fills left to right in a short wave and
+clearing empties right to left. The word swaps in place, rising when strength
+improves and dropping when it falls. Each rule checks off with a tick that draws
+itself and a tint that grows under it (rules that change together check off in a
+wave), and the length rule shows a rolling "N more" count while it is unmet. A
+new `error` opens its row on a spring, swaps as a whole when it changes, and
+shakes the field once.
+
+Strength is the share of rules met, spread over four steps, held at the first
+step while the password is shorter than `shortLength` (8). `rules` takes your own
+list, or `createPasswordRules({ minLength, labels })` for the built-in four
+(length, mixed case, number, symbol); `estimateStrength` scores a password
+without the component. `value` and `defaultValue` work as on an input, and
+`onValueChange` receives the new value and its strength. `revealed` and
+`onRevealedChange` control the toggle. `messages` renames every string (the
+strength words, the toggle, the meter, the list, the "N more" words and the
+summary) and merges with the English defaults.
+
+Native input props apply to the input, and `className` goes to the input;
+`disabled` also disables the toggle, and `aria-invalid` gives the box its invalid
+border. The error is an alert and is named in `aria-describedby` together with the
+requirements list. The toggle is a pressed button whose name does not change. A
+polite live region reads a summary when the level or the count of met rules
+changes. Reduced motion drops the transitions, the shake and the press, and the
+swapped text fades instead of moving. Screen-reader behaviour is not tested.
+
 ## Popover
 
 ```tsx
@@ -608,6 +1107,10 @@ dialog. React Aria labels it from the trigger.
 | `<PopoverContent align side>` | `<Popover placement>` | `align="start"` → `"bottom start"`   |
 | `<PopoverAnchor>`             | *no equivalent*     | zero call sites                        |
 
+### Motion (Popover)
+
+The panel grows out of its trigger: it starts 5px toward it (the side it opened on) and a little small, and settles on the gentle spring while it fades in over 160ms; it leaves in 160ms, half the offset and a hair smaller, with clicks passing through. A close that interrupts an open reverses from where the panel is. New `entrance` prop (`"rise"` default, `"none"`) lets a picker that animates its own popover opt out; DatePicker does. Reduced motion is a plain fade.
+
 ## Progress
 
 ```tsx
@@ -632,6 +1135,10 @@ and no number. `formatOptions` reaches it too, so a currency or "3 of 7" needs n
 second prop. `trackClassName` and `fillClassName` are escape hatches for a colour
 no tone covers.
 
+### Motion (Progress)
+
+The fill follows the value on the smooth spring (it was a 200ms ease) and the printed percentage counts to the new number on the same spring, so the number always matches the bar. When a default-toned bar completes it eases to the success colour (after 200ms) and a check lands beside the count; an explicit `tone` is never overridden, and a bar that is full at mount shows its check with no motion. A value that is not a percentage (a price) is shown as it is. A changed string label swaps as a whole.
+
 ## RadioGroup
 
 ```tsx
@@ -651,6 +1158,10 @@ no tone covers.
 **The label moves inside the item.** That is the one rename a call site
 makes, and it removes the id bookkeeping Radix required.
 
+### Motion (RadioGroup)
+
+The chosen dot springs in from small on the snappy spring (opacity 160ms in, 120ms out) while the old one shrinks away, and the mark's colours ease over 160ms. A press dips the mark to .88 in 100ms and it springs back on the gentle spring. **DOM:** the `radio-indicator` is always rendered (with `data-selected`), not only while chosen. The reference's travelling highlight between bordered rows is not ported: Alfred's radios are not row cards.
+
 ## ScrollArea
 
 ```tsx
@@ -673,6 +1184,33 @@ name — the three go together.
 pixel width, radius, hover state or margins. Those need `::-webkit-scrollbar`,
 which Firefox has never supported.
 
+### Motion (ScrollArea)
+
+New opt-in `fade` (px, default `0` = off, so an area is unchanged) fades the content out at an edge by exactly as much as there is content hidden past it, up to that many pixels: the fade grows in with the first pixels of scroll and is gone at the ends. It is written on each scroll frame straight to the element, so scrolling never re-renders. Not ported: the overlay scrollbars that fade in and out and thicken on hover (they replace the native scrollbar with a script-drawn one).
+
+## SearchField
+
+```tsx
+<SearchField label="Search contacts" value={query} onValueChange={setQuery} />
+```
+
+A search input with a clear button. It is controlled: `value` and
+`onValueChange(text)`, which is called with every edit and with `""` when the
+clear button is pressed (so there is no `onChange`). The clear button has a
+reserved box, so the field never changes width as it comes and goes; it scales
+in on the snappy spring while it fades and unblurs, leaves a little smaller,
+presses to 0.96, and pressing it clears the text and returns focus to the
+input. A field that is filled on first render shows the button with no
+animation, and while the button leaves it cannot be pressed or focused. The
+magnifier is muted at rest and takes full contrast while the field has focus or
+a value.
+
+`label` is required and visible; `clearLabel` renames the button (default "Clear
+search"). Native input props apply to the input, `className` goes to the input,
+and `disabled` also disables the clear button. The browser's own clear button
+and search decoration are hidden. The box shares the field look of `Input`.
+Reduced motion fades the button in over 120ms and removes it at once.
+
 ## Select
 
 ```tsx
@@ -686,7 +1224,20 @@ which Firefox has never supported.
 Four legacy parts collapse into one. The trigger shares
 `fieldSurfaceVariants` with `Input`, so a select and a text field in the
 same form row are the same box — the legacy had `h-10` here against
-`h-9` on the input.
+`h-9` on the input. Its label uses `Label`'s classes, so a Select and a
+labelled `Input` in one form show one label style. The trigger also shares the
+field look described under Input and Textarea (border transition, darker border
+on hover and keyboard focus, muted background when disabled).
+
+### Motion
+
+Built in plain CSS and a little plain React, with no animation library.
+
+- The shown value rolls when the selection changes: a later option rises in from below and an earlier one drops in from above (the direction is the option's place in the list), while the old value lifts away. A value that is already chosen on first mount does not animate. The visible copy is `aria-hidden`; React Aria's own value, visually hidden beside it, is what a screen reader reads.
+- The chevron turns half a turn on a spring while the list is open.
+- The list grows from the trigger edge (offset 6px toward it, scaled to 0.97, 240ms) and leaves faster (120ms), and a selected option's tick pops in. An option's highlight fades in over 120ms.
+- Hover, press and an open list fill the trigger muted as well as darkening its border. An invalid or disabled trigger is not repainted.
+- Reduced motion replaces the roll, the list's grow and the tick's pop with plain fades, and the chevron turns without a transition.
 
 ### Migrating from the legacy Select
 
@@ -793,6 +1344,10 @@ replaced.
 
 The pulse is gated behind `motion-safe:`.
 
+### Motion (Skeleton)
+
+The pulse dims a block to about half and back over 1.8s, 11 times (about 20 seconds), then rests, so a stalled load does not pulse forever. The new optional `index` prop starts a block's pulse 90ms after the one above it (`<Skeleton index={2} />`), so a stack dims in a wave. Reduced motion shows the still block. The reference's placeholder-to-content crossfade is not ported: it needs a wrapper with a `loading` prop, which Alfred does not have.
+
 ## Slider
 
 ```tsx
@@ -804,6 +1359,47 @@ The pulse is gated behind `motion-safe:`.
 The thumb is 24×24 (WCAG 2.5.8); the legacy's was 16. `aria-valuetext` comes
 free, so a scrubber can announce a time instead of a raw second count.
 
+### Motion (Slider)
+
+A value that arrives from outside a drag (a key, a prop, a click on the track) moves the thumb and the fill on the snappy spring; while dragging they stay under the pointer. The thumb swells to 1.16 while held. A bubble with the value rises in over the thumb (from small and blurred) while it is dragged or keyboard focused, and drops away in 120ms; the readout and the bubble roll their value up or down as it changes. The bubble is `aria-hidden`: the output beside the label carries the value. Reduced motion keeps opacity changes only. Not ported: marks, range, the springing catch-up on a click of the track (React Aria starts a drag at once), rubber-banding past the limits and release momentum.
+
+## SplitButton
+
+```tsx
+<SplitButton
+  onPress={save}
+  actions={[{ label: "Save as draft", onSelect: draft }, { label: "Delete", destructive: true }]}
+>
+  Save
+</SplitButton>
+```
+
+One pill, two actions: a main action and a menu of nearby alternatives. Change
+`children` (or `icon`) and the main half morphs in place: the letters that differ
+rise in while the old ones lift away, the icon swaps by scaling, and the width
+springs. The whole pill presses in for the main action; the menu half answers in
+colour only, so the menu opens from a still anchor, growing from its trigger with
+its items arriving one after another. `variant` is `primary` or `secondary`.
+
+## StatCard
+
+```tsx
+<div className="grid gap-4 sm:grid-cols-3">
+  <StatCard label="Open" value="$12,400" sub="18 invoices" />
+  <StatCard label="Overdue" value="$3,100" sub="4 invoices" tone="negative" />
+  <StatCard label="Unmapped" value="$1,200" isSelected={filter === "unmapped"} onPress={() => setFilter("unmapped")} />
+</div>
+```
+
+One headline figure. The label is one line (an ellipsis, the full text on
+hover), so a row's numbers sit level and cards in a row share one height.
+`tone` is a meaning, not a colour: `neutral` (default, and right for every
+zero), `positive`, `negative`, `warning`, `attention`. `href` makes the card a
+link, `onPress` a button, and `isSelected` with `onPress` a filter toggle with
+`aria-pressed` and one selected border. For a status pill next to the figure,
+use `Badge`, whose `tone` already covers success, warning, danger, info,
+primary and neutral.
+
 ## Switch
 
 ```tsx
@@ -811,6 +1407,10 @@ free, so a scrubber can announce a time instead of a raw second count.
 <Switch aria-label="Mute" isSelected={muted} onChange={setMuted} />
 ```
 
+### Motion (Switch)
+
+The thumb travels on a no-overshoot spring (559ms), stretches 5px toward its travel while pressed, and swells once (`scaleX` 1.16, 340ms) when the user changes the state; a switch that mounts on, or whose controlled value changes from outside, does not swell. Reduced motion keeps the colour change only.
+
 ### Migrating from the legacy Switch
 
 | legacy             | Alfred        |                                                       |
@@ -970,6 +1570,10 @@ one consumer or none across the six legacy tables, and they belong to a future
 </Tabs>
 ```
 
+### Motion (Tabs)
+
+One selection highlight (a pseudo-element of the tab list) glides to the selected tab on the morph spring; it is placed without a transition at first. The panel arrives fading in over 240ms while it travels 8px from the side the new tab sits on (it flips in RTL). **DOM:** none added, but once the row has placed its highlight (`data-hl` on the list) the selected tab no longer paints its own fill, border or shadow; the list's `::before` does. Reduced motion jumps the highlight and fades the panel. Not ported: the outgoing panel's exit, the panel height morph, and scroll buttons.
+
 ### Migrating from the legacy Tabs
 
 | legacy            | Alfred                  |                                            |
@@ -991,6 +1595,48 @@ The selected tab carries a **border**, not just a fill: `bg-background` on
 a `bg-muted` list is 1.13:1, and WCAG 1.4.11 wants 3:1 for the thing
 telling you which tab is active.
 
+## ThemeSwitch
+
+```tsx
+<ThemeSwitch theme={theme} variant="eclipse" onThemeChange={(next, variant, trigger) => setTheme(next)} />
+```
+
+A light/dark switch whose sun and moon turn the same way (clockwise into dark and
+back out of it), so the swap reads as one rotation. The icon is nudged the way the
+page transition travels (`variant`: `reveal`, `eclipse`, `split`, `rise`) and
+eases back when the theme returns. A page that loads in dark mode never spins its
+switches: only changes after the first painted frames animate.
+
+It is controlled: it shows `theme` and calls `onThemeChange` with the theme to
+move to, the variant and the button (the origin a page transition can grow from).
+The page transition itself, and the theme, are the caller's.
+
+## TimePicker
+
+```tsx
+import { Time } from "@internationalized/date";
+
+<TimePicker label="Start time" value={time} onChange={setTime} minuteStep={30} />
+```
+
+A field that shows a time and opens a list of times to pick from. It is a React
+Aria `Select` underneath (a listbox with typeahead, arrow keys and a roving
+highlight), so it reads and behaves as one. **Values are `TimeValue`**, from
+`@internationalized/date` like `Calendar`'s and `DatePicker`'s dates (ADR 0006),
+not `"HH:MM"` strings; `onChange` hands back a `Time`. Unlike `Calendar`, this one
+builds a `Time` at runtime, so the peer dependency is a real import here.
+`label` is required. `minuteStep` sets the gap between the times in the list
+(1, 5, 10, 15 or 30; a time between steps is added to the list so it is never lost),
+and `hourCycle` chooses 12 or 24 hour times.
+
+**Motion** (plain CSS and a little plain React, no animation library): the shown
+time rolls like a clock face (a later time rises in from below, an earlier one
+drops in from above, and the old one lifts away); the chevron turns half a turn on
+a spring while the list is open; the list grows from the field and leaves quicker;
+it opens already centred on the chosen time, with no scroll to watch; the
+highlight follows the arrows in 80ms; the trigger fills muted while open. Nothing
+animates on first render, and reduced motion swaps the grow for a plain fade.
+
 ## Toast
 
 ```tsx
@@ -1022,6 +1668,10 @@ user must act on.
 `tone` matches Badge's vocabulary. The legacy had `default` and `destructive`
 only, so 38 of 67 calls passed a variant that could not say "this worked".
 
+### Motion (Toast)
+
+A toast rises 16px from below and grows from .96 on the morph spring while it fades in over 240ms. Pressing its close control sinks it out (8px, .97, 180ms) before it leaves the queue; the control dips to .96 under a press and springs back. Reduced motion fades only. React Aria 1.21 unmounts a closed toast at once and has no exit of its own, so a toast that leaves by its timeout or by `toastQueue.close` still leaves without the exit. Not ported: swipe-to-dismiss, the status icon.
+
 ## Tooltip
 
 ```tsx
@@ -1044,3 +1694,8 @@ tooltip in the app. Focus opens it immediately regardless.
 **RTL differs between the two.** Popover stamps its own `dir` from
 `useLocale()`, so it needs an `I18nProvider`. Tooltip sets no `dir` at all and
 inherits from the document. Set both if you support RTL.
+
+### Motion (Tooltip)
+
+A tooltip rises 3px from its trigger and settles from .97 over 160ms (offset follows the side it opens on), and leaves in 120ms. While any tooltip is open, and for 300ms after the last one closes, the next one only fades in (no travel). The open delay stays 0. Reduced motion fades only. **DOM:** an empty hidden `span` inside the tooltip marks the warm case. Not ported: the crossfade and size spring when a string tooltip's text changes while open.
+