themelia-ui 1.0.3 → 2.0.0

package/docs/generated/components/features--theme-tweaker.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/theme-tweaker.css"
 
 ## Composition
 
-This family composes `base/accordion`, `base/badge`, `base/buttons`, `base/choice-inputs`, `base/dialog`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/item`, `base/navigation`, `base/structure`, `base/text-inputs`, `base/typography`, `base/value-inputs`, `features/overlays`.
+This family composes `base/accordion`, `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/item`, `base/navigation`, `base/overlay`, `base/structure`, `base/text-inputs`, `base/typography`, `base/value-inputs`, `features/overlays`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -39,11 +39,8 @@ Kind: callable.
 
 Kind: callable.
 
-Selectors that scope a theme to one subtree rather than the document.
-
-Each mode gets TWO forms — the scope carrying the class itself, and the scope inside an
-element that carries it — because a themed panel can be the thing that switches mode or
-can sit inside one.
+Selectors that scope a theme to one subtree. Each mode gets two forms (the scope carrying
+the class, and the scope inside an element that carries it).
 
 ```text
 (scopeSelector: string) => ThemeSelectors
@@ -53,11 +50,8 @@ can sit inside one.
 
 Kind: callable.
 
-The provider config minus everything that cannot survive `JSON.stringify`.
-
-`dates.locale` is a date-fns MODULE and `dates.formatRelativeTime` is a function; both
-are consumer-owned and are dropped rather than serialised into `{}`, which is what
-JSON would make of them.
+The provider config minus what cannot survive `JSON.stringify`: `dates.locale` (a
+date-fns module) and `dates.formatRelativeTime` (a function) are dropped.
 
 ```text
 (config?: UIConfig) => UIConfig
@@ -169,7 +163,7 @@ Kind: callable.
 
 Kind: callable.
 
-Shared first, then the mode's — so a mode-scoped edit wins over a shared one.
+Shared first, then the mode's, so a mode-scoped edit wins.
 
 ```text
 (theme: ThemeDefinition, mode?: ThemeMode) => ThemeOverrides
@@ -217,7 +211,7 @@ Serializable, and the only state ThemeScope and ThemeTweaker share.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `mode` | yes | `ThemeMode` | Which bucket the mode-scoped edits go to, and which the preview shows. |
-| `shared` | yes | `ThemeOverrides` | Typography, density, structure, radius — everything both themes share. |
+| `shared` | yes | `ThemeOverrides` | Typography, density, structure, radius: everything both themes share. |
 | `light` | yes | `ThemeOverrides` |  |
 | `dark` | yes | `ThemeOverrides` |  |
 
@@ -236,7 +230,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `fileName` | yes | `string` |  |
-| `cssText` | yes | `string` | Every public variable, resolved — a standalone theme. |
+| `cssText` | yes | `string` | Every public variable, resolved: a standalone theme. |
 | `overrideCssText` | yes | `string` | Only what was explicitly changed. |
 | `theme` | yes | `ThemeDefinition` |  |
 | `resolvedTheme` | yes | `ThemeDefinition` |  |
@@ -249,12 +243,8 @@ Kind: interface.
 
 Kind: type.
 
-The vocabulary theme synthesis works in.
-
-These three lived in `features/theme-tweaker` because that is where they were first
-needed. They describe the TOKEN CONTRACT rather than a control panel, and a build script
-synthesising a theme has no business importing a React feature to name its own output —
-so they live here, and the feature re-exports them unchanged.
+The vocabulary theme synthesis works in. Part of the token contract, so build scripts
+need not import a React feature; `features/theme-tweaker` re-exports them.
 
 ```text
 "light" | "dark"
@@ -306,8 +296,10 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `shared` | yes | `string` | Receives the mode-independent variables. |
-| `light` | yes | `string` |  |
-| `dark` | yes | `string` |  |
+| `light` | yes | `string` | Explicit light: a `.light` or `data-theme="light"` element and the boundaries inside it. |
+| `dark` | yes | `string` | Explicit dark: a `.dark` or `data-theme="dark"` element and the boundaries inside it. |
+| `systemLight` | no | `string` | Light by OS preference (no explicit theme), emitted under `prefers-color-scheme: light`. |
+| `systemDark` | no | `string` | Dark by OS preference (no explicit theme), emitted under `prefers-color-scheme: dark`. |
 
 ### `ThemeStyle`
 
@@ -432,6 +424,7 @@ A slider and a numeric box, for a variable with real bounds.
 | `step` | yes | `number` |  |
 | `unit` | no | `string` | Appended to committed values. Omit for a unitless token. |
 | `decimalPlaces` | no | `number` |  |
+| `fallback` | no | `number` | Shown while the variable is unset — a factor that falls back to another reads as empty. |
 
 ### `ThemeTweakerSection`
 
@@ -566,7 +559,8 @@ Kind: interface.
 | `boundaryDescription` | yes | `string` | Says why these settings behave differently from the CSS ones. |
 | `summary` | yes | `{ locale: string; currency: string; density: string; textSize: string; }` |  |
 | `sections` | yes | `{ regional: { title: string; description: string; }; presentation: { title: string; description: string; }; money: { title: string; description: string; }; }` |  |
-| `labels` | yes | `Record<"locale" \| "defaultCurrency" \| "displayCurrency" \| "moneyFormat" \| "firstDay" \| "dateFormat" \| "textSize" \| "density" \| "scale" \| "typographyScale" \| "colorScheme" \| "dualPricing" \| "dualPricingMode" \| "dualPricingLayout" \| "secondaryEmphasis", string>` |  |
+| `labels` | yes | `Record<"locale" \| "defaultCurrency" \| "displayCurrency" \| "moneyFormat" \| "firstDay" \| "dateFormat" \| "textSize" \| "density" \| "scale" \| "typographyScale" \| "colorScheme" \| "darkMenus" \| "dualPricing" \| "dualPricingMode" \| "dualPricingLayout" \| "secondaryEmphasis", string>` |  |
+| `darkMenusDescription` | yes | `string` |  |
 | `dualPricingDescription` | yes | `string` |  |
 | `displayCurrencyPlaceholder` | yes | `string` |  |
 | `options` | yes | `Record<string, string>` | Display names for enum values, keyed by the value itself. |
@@ -586,7 +580,7 @@ Preview route: Theme tweaker — `/theme-tweaker`
 ### Isolated theme scopes
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ThemeScope theme={createTheme({ shared: { "--radius": "1rem" } })}>
+<ThemeScope theme={createTheme({ shared: { "--radius": "0.875rem" } })}>
   <Button>Scoped radius</Button>
 </ThemeScope>
 ```

package/docs/generated/components/forms-rhf.md

@@ -38,10 +38,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-Wraps an RHF `control` in the kit's headless contract.
-
-`useField` delegates to `useController`, so registration, validation and dirty tracking
-all keep working — this adds a shape, not a second source of truth.
+Wraps an RHF `control` in the kit's headless contract. `useField` delegates to
+`useController`, so registration, validation and dirty tracking keep working.
 
 ```text
 (control: Control<TValues>) => FormControl<TValues>

package/docs/generated/components/forms.md

@@ -60,11 +60,8 @@ One field's state, as an adapter reports it.
 
 Kind: interface.
 
-The adapter contract.
-
-`useField` IS a hook — it is called once per bound field, unconditionally, during
-render. That is what lets an RHF adapter delegate to `useController`, which is
-per-field by design and cannot be expressed as a plain lookup.
+The adapter contract. `useField` is a hook, called once per bound field during render,
+so an RHF adapter can delegate to `useController`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -86,9 +83,6 @@ Kind: callable.
 
 A `FormControl` over plain React state — the zero-dependency default.
 
-Enough for the common case of a handful of fields, and it means the headless contract
-is usable without installing a form library at all.
-
 ```text
 (initialValues: TValues, options?: { errors?: Partial<Record<keyof TValues, string>>; }) => FormControl<TValues> & { values: TValues; reset: (next?: TValues) => void; }
 ```

package/docs/generated/components/layout--app-shell.md

@@ -54,7 +54,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Configure controlled state, persistence, shortcuts and translated sidebar controls. |
 | `toolbarClassName` | no | `string` |  |
 | `contentClassName` | no | `string` |  |
-| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as. It is a `<main>` by default.<br><br>A page may hold exactly one main landmark, so a shell embedded in a host page — a<br>documentation example, a widget inside someone else's layout — needs to say that the<br>host owns that role: `contentRender={<div />}`. |
+| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `ruledToolbar` | no | `boolean` | `false` when the content below sits on its own plane — an inset sidebar. |
 
 ### `StackedLayout`
@@ -80,7 +80,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `children` | yes | `ReactNode` |  |
 | `headerClassName` | no | `string` |  |
 | `contentClassName` | no | `string` |  |
-| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as. It is a `<main>` by default.<br><br>A page may hold exactly one main landmark, so a shell embedded in a host page — a<br>documentation example, a widget inside someone else's layout — needs to say that the<br>host owns that role: `contentRender={<div />}`. |
+| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 
 ### `TopbarSidebarLayout`
 
@@ -108,7 +108,7 @@ Extends: `Omit<ComponentProps<"div">, "children" | "title">`.
 | `headerActions` | no | `ReactNode` |  |
 | `sidebar` | no | `ReactNode` |  |
 | `slots` | no | `TopbarSidebarLayoutSlots` |  |
-| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the content column's element, which is a `<main>` by default.<br><br>A page holds one main landmark, so a shell embedded in a host page that owns that<br>role says `contentRender={<div />}`. Spelled `render`, like every other polymorphic<br>seam in the kit — this one shipped as `contentAs` first, which was the same idea in<br>a second vocabulary. |
+| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the content column's element (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `defaultOpen` | no | `boolean` | The sidebar's initial uncontrolled open state. |
 | `contained` | no | `boolean` | Fit the height of a parent instead of owning the viewport. |
 | `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Configure controlled state, persistence, shortcuts and translated sidebar controls. |

package/docs/generated/components/layout--auth.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/auth.css"
 
 ## Composition
 
-This family composes `base/typography`.
+This family composes `base/cards`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -129,7 +129,7 @@ Extends: `LayoutNavigationAdapter`, `Omit<ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the shell is drawn as. It is a `<main>` by default.<br><br>A page may hold exactly one main landmark, so an auth shell embedded in a host page —<br>a documentation example, a screen inside someone else's frame — needs to say that the<br>host owns that role: `contentRender={<div />}`. |
+| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the shell is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `brand` | no | `AuthBrand` | A rendered mark, or the parts for the shell to arrange. |
 | `eyebrow` | no | `ReactNode` |  |
 | `title` | no | `ReactNode` |  |
@@ -145,7 +145,7 @@ Extends: `LayoutNavigationAdapter`, `Omit<ComponentProps<"div">, "title">`.
 | `languageLinks` | no | `AuthLink[]` |  |
 | `languageSwitcher` | no | `ReactNode` | A rendered control, when a link row is not the right shape for it. |
 | `size` | no | `AuthShellSize` |  |
-| `variant` | no | `AuthShellVariant` | `card` puts the content on a raised surface; `bare` does not; `split` puts a panel<br>beside it.<br><br>`card` is the default because a form floating on a plain background reads as<br>unfinished — the surface is what makes it look like something to fill in. |
+| `variant` | no | `AuthShellVariant` | `card` (default) puts the content on a raised surface; `bare` does not; `split` puts<br>a panel beside it. |
 | `align` | no | `"center" \| "start"` | `center` uses spare height and lets tall content grow; `start` keeps the form at the top. |
 | `splitPanel` | no | `ReactNode` | The panel, for `variant="split"`. |
 | `splitSide` | no | `AuthSplitSide` | Which side the panel is drawn on. The form stays first in the DOM either way. |
@@ -167,7 +167,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `languageLabel` | yes | `string` | Captions for the three link rows below the card.<br><br>Each row is its own `<nav>` so a screen reader can skip one, and a nav needs a name<br>to be worth skipping — these were the three English words that gave them one. |
+| `languageLabel` | yes | `string` | Names for the three link rows below the card; each row is its own named `<nav>`. |
 | `helpLabel` | yes | `string` |  |
 | `legalLabel` | yes | `string` |  |
 
@@ -193,10 +193,8 @@ What the panel does below 56rem of available width: disappear, or fall under the
 
 Kind: callable.
 
-Form beside a panel, for a caller composing the two halves itself.
-
-`AuthShell variant="split"` is the same arrangement with the shell's own card inside it;
-this one takes both halves as given, for a page whose form is not an AuthCard at all.
+Form beside a panel, for a caller composing both halves itself. `AuthShell
+variant="split"` is the same arrangement with the shell's own card.
 
 ```text
 ({ form, panel, panelPosition, panelMobile, className, ...props }: AuthSplitPanelProps) => import("react").JSX.Element

package/docs/generated/components/layout--containers.md

@@ -114,8 +114,8 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 | `main` | yes | `React.ReactNode` | Primary detail, form, or index content. |
 | `aside` | yes | `React.ReactNode` | Secondary summary, support, or action rail. |
 | `footer` | no | `React.ReactNode` | Spans both columns, after the work regions. |
-| `stickyAside` | no | `boolean` | Keeps the aside in view while the page scrolls.<br><br>Opt-in, because an aside taller than the viewport must be allowed to scroll away —<br>pinned, its own overflow becomes unreachable. |
-| `asidePosition` | no | `"start" \| "end"` | Which side the aside is DRAWN on. Default `end`.<br><br>Only the grid columns move. The aside stays second in the DOM at every setting, so a<br>reader tabbing through still meets the primary content first — reordering by moving<br>the element would trade a layout preference for an accessibility regression, which is<br>precisely the trade this component exists to refuse. |
+| `stickyAside` | no | `boolean` | Keeps the aside in view while the page scrolls. Opt-in: an aside taller than the<br>viewport must be able to scroll away. |
+| `asidePosition` | no | `"start" \| "end"` | Which side the aside is drawn on. Default `end`. Only the grid columns move; the<br>aside stays second in the DOM. |
 
 ## Preview recipes
 

package/docs/generated/components/layout--header.md

@@ -96,17 +96,14 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `label` | yes | `string` | Names the trail, which is a navigation landmark.<br><br>It was fixed at "Breadcrumb" with no way through, so a page carrying two headers — a<br>page header and an embedded panel's — produced two landmarks a reader could not tell<br>apart. Every other accessible string in the kit is overridable; `Breadcrumbs` itself<br>has taken a `label` all along and the header that wraps it never passed one. |
+| `label` | yes | `string` | Names the trail's navigation landmark; override it when a page carries two headers. |
 
 ### `HeaderGlobalSearchTrigger`
 
 Kind: callable.
 
-The same trigger, reporting into a controlled `open`.
-
-Two components rather than one with an optional prop, because the palette this opens is
-usually controlled from elsewhere entirely — and a trigger that sometimes owns the state
-and sometimes does not is the shape that produces two palettes on one page.
+The same trigger, reporting into a controlled `open`. A separate component so a trigger
+never half-owns the palette's state.
 
 ```text
 ({ onOpen, onOpenChange, ...props }: HeaderGlobalSearchTriggerProps) => import("react").JSX.Element
@@ -132,7 +129,7 @@ Kind: interface.
 | `id` | yes | `string \| number` |  |
 | `title` | yes | `ReactNode` |  |
 | `description` | no | `ReactNode` |  |
-| `time` | no | `ReactNode` | Already formatted — the shell does not decide whether this is a date or "2h ago". |
+| `time` | no | `ReactNode` | Already formatted: a date or "2h ago". |
 | `read` | no | `boolean` |  |
 | `tone` | no | `NotificationTone` |  |
 | `href` | no | `string` | Makes the row a link. Without it the row is a button. |
@@ -153,8 +150,8 @@ Extends: `LayoutNavigationAdapter`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `notifications` | no | `HeaderNotification[]` | Newest first. The shell does not sort — the order it is given is the order shown. |
-| `unreadCount` | no | `number` | Shown on the trigger.<br><br>Separate from `notifications.filter(n => !n.read).length` on purpose: the list here<br>is a page of the most recent, and the count is of everything. |
+| `notifications` | no | `HeaderNotification[]` | Newest first; shown in the order given, never sorted. |
+| `unreadCount` | no | `number` | Shown on the trigger. Separate from the unread entries in `notifications`, which are<br>only the most recent page. |
 | `onNotificationClick` | no | `(notification: HeaderNotification) => void` |  |
 | `onMarkAllRead` | no | `() => void` |  |
 | `onViewAll` | no | `() => void` |  |
@@ -178,7 +175,7 @@ Kind: interface.
 | `empty` | yes | `string` |  |
 | `viewAll` | yes | `string` |  |
 | `unread` | yes | `(count: number) => string` | Announced count on the trigger, so the badge is not read as a bare number. |
-| `unreadItem` | yes | `string` | Said on an unread ROW.<br><br>Unread is drawn as a tint and a dot, and neither reaches a screen reader — colour<br>alone is not a state. This was a literal `<VisuallyHidden>Unread</VisuallyHidden>`,<br>which no `strings` override could reach and no consumer could translate. |
+| `unreadItem` | yes | `string` | Announced on an unread row, whose tint and dot are visual only. |
 
 ### `HeaderProps`
 
@@ -191,7 +188,7 @@ Extends: `React.ComponentProps<"header">`, `LayoutNavigationAdapter`.
 | `showBreadcrumbs` | no | `boolean` |  |
 | `showSidebarTrigger` | no | `boolean` | Renders the sidebar collapse control before the trail. |
 | `breadcrumbs` | no | `Crumb[]` |  |
-| `homeCrumb` | no | `Crumb \| null` | Prepended to the trail, for a root that is not part of the route.<br><br>`null` omits it, which is different from not passing it: a product whose shell has no<br>home destination should say so rather than get a default one. |
+| `homeCrumb` | no | `Crumb \| null` | Prepended to the trail, for a root that is not part of the route. `null` omits it;<br>leaving it undefined keeps the default. |
 | `breadcrumbsStrings` | no | `Partial<HeaderBreadcrumbsStrings>` | Overrides the trail's copy — its landmark name, for a page carrying two headers. |
 | `slots` | no | `HeaderSlots` |  |
 | `contentClassName` | no | `string` |  |
@@ -211,7 +208,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `onOpen` | no | `() => void` |  |
-| `shortcutModifier` | no | `"meta" \| "control"` | Which modifier the hint names. Detected from the platform when omitted.<br><br>Detection runs in an effect rather than during render: the server has no navigator,<br>and guessing there produces markup the client then has to correct. |
+| `shortcutModifier` | no | `"meta" \| "control"` | Which modifier the hint names. Detected from the platform on the client when omitted<br>(the server renders the non-Mac hint). |
 | `enableShortcut` | no | `boolean` | Binds ⌘/Ctrl+K. Off for a page that already uses it. |
 | `strings` | no | `Partial<HeaderSearchStrings>` |  |
 | `className` | no | `string` |  |
@@ -307,7 +304,7 @@ Kind: interface.
 | `user` | yes | `LayoutUser` |  |
 | `showIdentity` | no | `boolean` | Shows the name and email beside the avatar. Off leaves an avatar-only trigger. |
 | `showEmail` | no | `boolean` |  |
-| `customContent` | no | `ReactNode` | Replaces the menu body wholesale.<br><br>The three callbacks build a command menu; anything else — a workspace switcher, a<br>theme row — is not a list of commands, so it goes in as content instead of being<br>bent into one. |
+| `customContent` | no | `ReactNode` | Replaces the menu body wholesale, for content that is not a list of commands (a<br>workspace switcher, a theme row). Otherwise the three callbacks build the menu. |
 | `onProfile` | no | `() => void` |  |
 | `onSettings` | no | `() => void` |  |
 | `onLogout` | no | `() => void` |  |

package/docs/generated/components/layout--navigation.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/navigation.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/item`, `base/typography`.
+This family composes `base/badge`, `base/item`, `base/timeline`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -45,7 +45,7 @@ Extends: `Omit<ComponentProps<"div">, "onSelect">`.
 | --- | :-: | --- | --- |
 | `steps` | yes | `BreadcrumbProgressStep[]` |  |
 | `currentIndex` | yes | `number` | Zero-based. |
-| `onStepClick` | no | `(id: string, index: number) => void` | Supplying it makes completed steps reachable.<br><br>Only completed ones and the current one: a wizard that lets you jump forward past a<br>step you have not filled in is not a wizard. |
+| `onStepClick` | no | `(id: string, index: number) => void` | Makes completed steps and the current one reachable, never later ones. Without it the<br>steps are plain list items. |
 | `strings` | no | `Partial<BreadcrumbProgressStrings>` |  |
 
 ### `BreadcrumbProgressStep`
@@ -64,7 +64,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `step` | yes | `(index: number, label: string) => string` | Names each step control — "Step 2: Billing". |
+| `step` | yes | `(index: number, label: string, status?: "completed" \| "current" \| "upcoming") => string` | Names each step — "Step 2: Billing", and "Step 1: Account, completed" for one already<br>walked past. The current step is marked by `aria-current`, so it needs no word here. |
 | `position` | yes | `(current: number, total: number) => string` | The summary above the trail — "Step 2 of 4". |
 
 ### `CategoryNav`
@@ -151,7 +151,7 @@ Extends: `Omit<React.ComponentProps<"nav">, "children" | "onSelect">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `items` | yes | `SectionNavItem[]` |  |
-| `rootMargin` | no | `string` | Which part of the viewport counts as "here".<br><br>The default keeps the active band near the top: a heading is current from the moment<br>it reaches the upper quarter, rather than only once it is centred — which is what<br>makes the marker feel like it lags behind the scroll. |
+| `rootMargin` | no | `string` | Which part of the viewport counts as "here". The default makes a heading current once<br>it reaches the upper quarter. |
 | `onSelect` | no | `(id: string) => void` |  |
 | `strings` | no | `StringsProp<SectionNavStrings>` |  |
 
@@ -192,7 +192,7 @@ Kind: interface.
 | `label` | yes | `React.ReactNode` |  |
 | `href` | yes | `string` | Destination. |
 | `icon` | no | `LucideIcon` |  |
-| `badge` | no | `React.ReactNode` | A chip beside the label — a count, a status.<br>A count or a status beside the label.<br><br>A string or a number is wrapped in a `Badge` for you; pass a node to choose the<br>tone. Left raw, a bare "12" beside a nav row reads as part of the label — and one<br>page's rail ends up with a chip where the next has plain text. |
+| `badge` | no | `React.ReactNode` | A count or a status beside the label. A string or number is wrapped in a neutral<br>`Badge`; pass a node to choose the tone. |
 | `disabled` | no | `boolean` |  |
 
 ### `SideNavProps`
@@ -205,8 +205,8 @@ Extends: `Omit<React.ComponentProps<"nav">, "children">`.
 | --- | :-: | --- | --- |
 | `items` | no | `SideNavItem[]` | Flat entries. Mutually exclusive with `groups`. |
 | `groups` | no | `SideNavGroup[]` | Captioned blocks of entries. Mutually exclusive with `items`. |
-| `currentPath` | no | `string` | The path considered current.<br><br>Matched by longest prefix, so `/settings/members` marks the members entry rather than<br>the `/settings` index that also prefixes it — an index entry otherwise lights up on<br>every page beneath it. |
-| `renderLink` | no | `(props: { href: string; className: string; children: React.ReactNode; "aria-current"?: "page"; "aria-disabled"?: boolean; }) => React.ReactElement` | Renders each entry.<br><br>The escape hatch for a router: return the framework's link element and the nav will<br>clone it with the right props. Without it, entries are plain anchors — which is why<br>this library never imports a router. |
+| `currentPath` | no | `string` | The path considered current. Matched by longest prefix, so `/settings/members` marks<br>the members entry, not the `/settings` index. |
+| `renderLink` | no | `(props: { href: string; className: string; children: React.ReactNode; "aria-current"?: "page"; "aria-disabled"?: boolean; }) => React.ReactElement` | Renders each entry: receives the link props and returns the router's link element.<br>Without it, entries are plain anchors. |
 | `strings` | no | `StringsProp<SideNavStrings>` |  |
 
 ### `SideNavStrings`
@@ -237,3 +237,13 @@ Preview route: Side nav & section nav — `/side-nav`
   ]}
 />
 ```
+
+### One component, named for its shape
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<BreadcrumbProgress
+  steps={[{ id: "account", label: "Account" }, { id: "billing", label: "Billing" }, …]}
+  currentIndex={current}
+  onStepClick={(_id, index) => setCurrent(index)}
+/>
+```

package/docs/generated/components/layout--page.md

@@ -69,7 +69,7 @@ Extends: `ActionDefinition`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `placement` | no | `"auto" \| "inline" \| "menu"` | Forces one entry to a side of the split.<br><br>`menu` keeps a rarely-wanted or destructive command out of the button row however<br>much room there is; `inline` pins the primary action even when everything else<br>collapses. `auto` lets `maxInlineActions` decide. |
+| `placement` | no | `ActionPlacement` | Forces one entry to a side of the split: `menu` always overflows, `inline` is pinned<br>as a button, `auto` lets `maxInlineActions` decide. |
 
 ### `PageActions`
 
@@ -99,7 +99,7 @@ Extends: `LayoutNavigationAdapter`.
 | --- | :-: | --- | --- |
 | `actions` | no | `readonly PageAction[]` |  |
 | `display` | no | `PageActionsDisplay` | `auto` watches the width and collapses everything into a menu below `breakpoint`;<br>`inline` and `menu` are the two fixed ends. |
-| `breakpoint` | no | `number` | Width at or below which `auto` collapses to a menu. |
+| `breakpoint` | no | `number` | Viewport width, in px, below which `auto` collapses to a menu. Defaults to the `lg` breakpoint. |
 | `maxInlineActions` | no | `number` | How many entries render as buttons before the rest overflow. |
 | `strings` | no | `Partial<PageActionsStrings>` |  |
 | `className` | no | `string` |  |
@@ -132,7 +132,7 @@ Extends: `LayoutNavigationAdapter`, `Pick<PageHeadingProps, "eyebrow" | "descrip
 | `titleIcon` | no | `ComponentType<{ className?: string; }>` | Decorative glyph before the title. Centred on the title line, never on the block. |
 | `titleIconHref` | no | `string` | Makes the title icon a link. Routed through `renderLink` like everything else. |
 | `onTitleIconClick` | no | `() => void` | Makes the title icon a button. Takes precedence over `titleIconHref`. |
-| `strings` | no | `Partial<PageHeaderStrings>` | Accessible name for a linked or clickable title icon.<br>Overrides this header's own copy — the back control and the title icon link. |
+| `strings` | no | `Partial<PageHeaderStrings>` | Overrides this header's own copy: the back control's and the title icon's accessible names. |
 | `backHref` | no | `string` | Destination for the back control. Either this or `onBack` makes it appear. |
 | `onBack` | no | `() => void` |  |
 | `titleBadges` | no | `PageHeadingBadge[]` | Status marks beside the title, as data — the tone comes from the kit's vocabulary. |
@@ -158,7 +158,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `back` | yes | `string` | Names the back control, which is icon-only when it has no visible text. |
-| `titleIcon` | yes | `string` | Names the control the title icon becomes when it is given an href. |
+| `titleIcon` | yes | `string` | Names the title icon when it is a link or a button. |
 
 ### `PageProps`
 
@@ -168,7 +168,7 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `header` | no | `PageHeaderProps` | The title block. Omit for a page that supplies its own header.<br><br>A `PageHeaderProps`, not a `PageHeadingProps`: a page in an application gets the<br>back control, the title icon and the routing seam, not just the visual block. |
+| `header` | no | `PageHeaderProps` | The title block, as `PageHeader` props. Omit for a page that supplies its own header. |
 | `maxWidth` | no | `ContainerMaxWidth` |  |
 | `gutter` | no | `ContainerGutter` |  |
 | `bodyProps` | no | `React.ComponentProps<"div">` | Attributes for the body region, for a page that needs to address it. |
@@ -208,7 +208,7 @@ Preview route: Page & page header — `/page`
 </Page>
 ```
 
-### Why a factor and not a size prop
+### Why two factors, and no third
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <UIProvider config={{ scale: 1.125 }}>

package/docs/generated/components/layout--settings.md

@@ -48,7 +48,7 @@ Kind: interface.
 | `label` | yes | `React.ReactNode` |  |
 | `href` | yes | `string` | Destination. |
 | `icon` | no | `LucideIcon` |  |
-| `badge` | no | `React.ReactNode` | A chip beside the label — a count, a status.<br>A count or a status beside the label.<br><br>A string or a number is wrapped in a `Badge` for you; pass a node to choose the<br>tone. Left raw, a bare "12" beside a nav row reads as part of the label — and one<br>page's rail ends up with a chip where the next has plain text. |
+| `badge` | no | `React.ReactNode` | A count or a status beside the label. A string or number is wrapped in a neutral<br>`Badge`; pass a node to choose the tone. |
 | `disabled` | no | `boolean` |  |
 
 ### `AsideNavShell`
@@ -77,36 +77,14 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `actions` | no | `React.ReactNode` | Actions for the heading row. |
 | `stickyAside` | no | `boolean` |  |
 
-### `SettingsShell`
-
-Kind: const.
-
-```text
-typeof AsideNavShell
-```
-
-### `SettingsShellProps`
-
-Kind: type.
-
-The same props. Named separately so a settings screen can say what it is typing.
-
-```text
-AsideNavShellProps
-```
-
 ## Preview recipes
 
-Preview route: Settings shell — `/settings-shell`
+Preview route: Side nav & section nav — `/side-nav`
 
-### SettingsShell
+### The rail beside its content: AsideNavShell
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<SettingsShell
-  title="Settings"
-  groups={settingsNav}
-  currentPath="/settings/members"
->
+<AsideNavShell title="Settings" groups={settingsNav} currentPath="/settings/members">
   <Card title="Members" />
-</SettingsShell>
+</AsideNavShell>
 ```

package/docs/generated/components/layout--sidebar.md

@@ -46,11 +46,11 @@ Extends: `LayoutNavigationAdapter`.
 | `navigationGroups` | no | `Record<string, SidebarNavItem[]>` | Navigation grouped by section heading. An empty key renders an untitled group. |
 | `footerNavItems` | no | `SidebarFlatNavItem[]` | Entries pinned to the footer — support, settings, sign out. |
 | `currentUrl` | no | `string` | The current route. Everything active follows from this. |
-| `iconMap` | no | `Record<string, ComponentType<{ className?: string; }>>` | Resolves an icon NAME to a component, so navigation data can stay serialisable —<br>which it has to be when it comes from a server or a config file. |
+| `iconMap` | no | `Record<string, ComponentType<{ className?: string; }>>` | Resolves an icon name to a component, so navigation data can stay serialisable. |
 | `liveBadges` | no | `Record<string, string \| number>` | Counts keyed by `handle`, for values that change after the nav was defined. |
 | `loading` | no | `boolean` |  |
 | `loadingRows` | no | `number` | Rows shown while loading. |
-| `logo` | no | `ReactNode` | The product mark, and the compact one for the collapsed rail.<br><br>Supplying `workspaceLinks` alongside turns the header into a switcher; on its own<br>the mark is just the mark. Both go through the same header row either way, so the<br>rail's top does not change height when a product gains a second workspace. |
+| `logo` | no | `ReactNode` | The product mark, and the compact one for the collapsed rail. With `workspaceLinks`<br>the header becomes a switcher, in the same row height. |
 | `collapsedLogo` | no | `ReactNode` |  |
 | `workspaceLinks` | no | `WorkspaceLink[]` |  |
 | `workspaceStrings` | no | `Partial<SidebarWorkspaceStrings>` |  |
@@ -89,13 +89,8 @@ SidebarWorkspaceStrings
 
 Kind: callable.
 
-True when `currentUrl` is at `path` or inside it.
-
-The prefix rule is what keeps "Settings" lit while the reader is on
-`/settings/members`. The trailing separator matters: a bare `startsWith` would light
-"/invoice" up on "/invoices", which is a different page.
-
-On its own this is NOT enough to decide which row is current — see `resolveActiveHref`.
+True when `currentUrl` is at `path` or below it (`/invoice` does not match `/invoices`).
+Matches every ancestor, so use `resolveActiveHref` to pick the current row.
 
 ```text
 (currentUrl: string, path: string) => boolean
@@ -105,16 +100,8 @@ On its own this is NOT enough to decide which row is current — see `resolveAct
 
 Kind: callable.
 
-The single entry that is actually current: the LONGEST href that matches.
-
-Prefix matching alone lights up every ancestor, and an index entry is an ancestor of
-all its siblings — an "Overview" at `/app` matches `/app/settings/members` just as
-surely as "Settings" at `/app/settings` does, so three rows highlight at once and none
-of them is the page you are on. Picking the longest match is what routers do, and it
-leaves exactly one leaf current with its ancestors known.
-
-Returns `undefined` when nothing matches, which is a real answer: a route with no
-navigation entry should light nothing rather than fall back to the shortest one.
+The single current entry: the longest matching href, so an index entry does not light
+up beside its children. `undefined` when nothing matches.
 
 ```text
 (currentUrl: string, hrefs: (string | undefined)[]) => string | undefined
@@ -132,11 +119,8 @@ Omit<SidebarNavItem, "children">
 
 Kind: callable.
 
-Resolves an icon that may be a NAME.
-
-Exported because a caller supplying `renderItem` still wants the same resolution — a
-row rendered by hand should not need its own copy of "string means look it up in the
-iconMap, component means render it, node means use it".
+Resolves an icon that may be a name (looked up in `iconMap`), a component or a node.
+Exported for `renderItem` callers.
 
 ```text
 ({ icon, iconMap, }: { icon?: LayoutIconSource; iconMap?: Record<string, ComponentType<{ className?: string; }>>; }) => import("react").JSX.Element | null
@@ -150,9 +134,10 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `depth` | yes | `number` |  |
 | `active` | yes | `boolean` |  |
-| `expanded` | yes | `boolean` |  |
+| `expanded` | yes | `boolean` | Whether the row's children are shown: the reader's toggle if they used it, else derived from the current URL. |
 | `badge` | no | `string \| number` |  |
 | `renderLink` | yes | `LayoutLinkRenderer` |  |
+| `toggle` | no | `() => void` | Flips `expanded` for a row with children; wire it to a custom parent row's click.<br>AppSidebar always supplies it; optional for hand-built contexts. |
 
 ### `SidebarLogo`
 
@@ -202,7 +187,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `user` | yes | `LayoutUser` |  |
-| `customContent` | no | `ReactNode` | Replaces the menu body. See HeaderUserMenu — the same reasoning. |
+| `customContent` | no | `ReactNode` | Replaces the menu body, as in HeaderUserMenu. |
 | `onProfile` | no | `() => void` |  |
 | `onSettings` | no | `() => void` |  |
 | `onLogout` | no | `() => void` |  |
@@ -255,11 +240,6 @@ Kind: interface.
 
 Kind: callable.
 
-Path matching for navigation.
-
-Deliberately not a router's matcher: this layer never imports one. These are the two
-rules a sidebar actually needs — reduce anything link-shaped to a path, and treat a
-parent as current when a child route is.
 Reduces an href to a comparable path. Handles hash routing, queries, and fragments.
 
 ```text

package/docs/generated/components/layout--workspace.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/workspace.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/display`, `base/feedback`, `base/item`, `base/typography`.
+This family composes `base/badge`, `base/display`, `base/feedback`, `base/item`, `base/navigation`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -89,7 +89,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `bodyClassName` | no | `string` |  |
 | `sidebarClassName` | no | `string` |  |
 | `contentClassName` | no | `string` |  |
-| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as. It is a `<main>` by default.<br><br>A page may hold exactly one main landmark, so a workspace embedded in a host page — a<br>documentation example, a pane inside someone else's frame — needs to say that the host<br>owns that role: `contentRender={<div />}`. |
+| `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `railClassName` | no | `string` |  |
 
 ### `WorkspaceLocaleItem`
@@ -236,7 +236,7 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `media` | no | `React.ReactNode` | An avatar, an icon medallion, a thumbnail. |
 | `badges` | no | `React.ReactNode` | Status marks beside the title. Short — the title is what gives way, not these. |
 | `status` | no | `React.ReactNode` | A single prominent status, rendered after the badges. |
-| `metadata` | no | `WorkspaceRecordMetadataItem[]` | Key/value pairs. A real description list, so each pair is announced as one. |
+| `metadata` | no | `WorkspaceRecordMetadataItem[]` | Key/value pairs, drawn inline: each label and its value are one item, read as one fact. |
 | `strings` | no | `Partial<WorkspaceRecordHeaderStrings>` | Overrides this header's own copy — the names of its two unlabelled regions. |
 | `actions` | no | `React.ReactNode` | Primary actions, pinned to the end of the title row. |
 | `secondaryActions` | no | `React.ReactNode` | A second, quieter row beneath — filters, tabs, bulk controls. |