themelia-ui 2.0.0 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/layout/auth.css"
 
 ## Composition
 
-This family composes `base/cards`, `base/typography`.
+This module 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.
@@ -67,14 +67,14 @@ Extends: `Omit<ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `surface` | no | `"card" \| "bare"` |  |
-| `eyebrow` | no | `ReactNode` |  |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `headerEnd` | no | `ReactNode` | A control at the end of the header row — a language switcher, a step count. |
+| `surface` | no | `"card" \| "bare"` | `bare` removes the framing and padding while keeping the header, content and footer<br>rhythm. |
+| `eyebrow` | no | `ReactNode` | Above the title, in the heading region. |
+| `title` | no | `ReactNode` | The heading region's title. |
+| `description` | no | `ReactNode` | Under the title, in the heading region. |
+| `headerEnd` | no | `ReactNode` | A control or status at the end of the header row — a language switcher, a step count. |
 | `banner` | no | `ReactNode` | A notice above the content: an expired link, a required invitation. |
 | `media` | no | `ReactNode` | A strip above the header — an illustration, a product screenshot. |
-| `footer` | no | `ReactNode` |  |
+| `footer` | no | `ReactNode` | Content in the footer band. |
 | `level` | no | `1 \| 2 \| 3` | Heading level for the title. A sign-in page's title is usually its h1. |
 
 ### `AuthFooterLinks`
@@ -93,7 +93,7 @@ Extends: `LayoutNavigationAdapter`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `links` | yes | `AuthLink[]` |  |
+| `links` | yes | `AuthLink[]` | The entries of a link row that wraps with the available width. |
 | `label` | no | `string` | Names the row for assistive technology — "Legal", "Language". |
 | `leadingIcon` | no | `ReactNode` | A glyph before the row, for a language selector. |
 | `className` | no | `string` |  |
@@ -130,21 +130,21 @@ 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 (`<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` |  |
-| `description` | no | `ReactNode` |  |
+| `brand` | no | `AuthBrand` | A rendered mark, or the parts — `{ logo, label, description, href }` — for the shell to<br>arrange. |
+| `eyebrow` | no | `ReactNode` | Above the title, in the card's heading block. |
+| `title` | no | `ReactNode` | The card's heading. |
+| `description` | no | `ReactNode` | Under the title, in the card's heading block. |
 | `headerEnd` | no | `ReactNode` | A control at the end of the card's header row — a locale switcher, a step count. |
 | `banner` | no | `ReactNode` | A notice above the form — an expired link, a required invitation. |
 | `cardMedia` | no | `ReactNode` | A strip above the card's header. |
 | `cardFooter` | no | `ReactNode` | A band under the card's content, inside the frame. |
 | `postCard` | no | `ReactNode` | Content between the card and the link rows — "Don't have an account?" |
 | `footer` | no | `ReactNode` | Free content at the very bottom, after every link row. |
-| `footerLinks` | no | `AuthLink[]` | Help, status, contact. Data, so the separators are decided once. |
-| `policyLinks` | no | `AuthLink[]` | Terms, privacy, cookies. Rendered as its own row so screen readers can skip it. |
-| `languageLinks` | no | `AuthLink[]` |  |
+| `footerLinks` | no | `AuthLink[]` | Help, status, contact: a named row of links that wraps with the available width. Data,<br>so the separators are decided once. |
+| `policyLinks` | no | `AuthLink[]` | Terms, privacy, cookies: a named row of links that wraps with the available width,<br>rendered as its own row so screen readers can skip it. |
+| `languageLinks` | no | `AuthLink[]` | The languages, as a named row of links that wraps with the available width. |
 | `languageSwitcher` | no | `ReactNode` | A rendered control, when a link row is not the right shape for it. |
-| `size` | no | `AuthShellSize` |  |
+| `size` | no | `AuthShellSize` | The surface width. |
 | `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"`. |
@@ -209,8 +209,8 @@ Extends: `ComponentProps<"div">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `form` | yes | `ReactNode` | The sign-in surface. Usually an AuthShell with `variant="bare"`. |
-| `panel` | no | `ReactNode` | Marketing copy, a testimonial, an illustration. Hidden below 56rem of available width. |
-| `panelPosition` | no | `AuthSplitSide` | Which side the panel is drawn on. The form stays first in the DOM either way. |
+| `panel` | no | `ReactNode` | Marketing copy, a testimonial, an illustration. Hidden below 56rem of available width<br>unless `panelMobile` stacks it; omitting it gives the form the full available width. |
+| `panelPosition` | no | `AuthSplitSide` | Which side the panel is drawn on. The form stays first in the DOM either way, so<br>reading and keyboard order remain form first. |
 | `panelMobile` | no | `AuthSplitMobile` | What the panel does when this container is narrower than 56rem. |
 
 ### `AuthSplitSide`
@@ -229,6 +229,45 @@ Kind: const.
 AuthShellStrings
 ```
 
+### `LinkRenderer`
+
+Kind: type.
+
+How a component renders a link: through the application's router. Every component that
+navigates takes one as `renderLink`, and without one renders a plain anchor. Return one
+element: the component may merge its own props into it, such as a menu item's role or a
+button's styling.
+
+```tsx fragment — declaration JSDoc excerpt
+const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <Link to={href} {...rest}>{children}</Link>
+```
+
+```text
+(props: LinkRenderProps) => ReactElement
+```
+
+### `LinkRenderProps`
+
+Kind: interface.
+
+What a component hands its link renderer. Spread everything but `active`, `disabled` and `external` onto the element.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | no | `string` | Destination. When absent, render non-interactive content. |
+| `children` | yes | `ReactNode` |  |
+| `className` | no | `string` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `onClick` | no | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-current"` | no | `AriaAttributes["aria-current"]` |  |
+| `"aria-disabled"` | no | `AriaAttributes["aria-disabled"]` |  |
+| `active` | no | `boolean` | Hint for active styling. A renderer may ignore it — the component styles the row itself. |
+| `disabled` | no | `boolean` | The entry goes nowhere: render non-interactive content. |
+| `external` | no | `boolean` | Opens elsewhere: the default renderer adds `target="_blank"` and `rel="noopener noreferrer"`. |
+
 ## Preview recipes
 
 Preview route: Auth shells — `/auth-shell`
@@ -236,46 +275,203 @@ Preview route: Auth shells — `/auth-shell`
 ### Card · a complete sign-in page
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AuthShell
-  brand={brand}
-  title="Welcome back"
-  description="Sign in to your Acme workspace."
-  cardFooter={<Text size="xs">Local demo · no account required</Text>}
-  policyLinks={policy}
->
-  <YourSignInForm />
-</AuthShell>
+import { Text } from "themelia-ui/base/typography"
+import { AuthShell } from "themelia-ui/layout/auth"
+
+import styles from "./auth-shell.module.css"
+import { POLICY } from "./data"
+import { BRAND } from "./_brand"
+import { SignInDemo } from "./_shared"
+
+export default function AuthShellExample() {
+	return (
+		<div className={styles.frame} data-auth-preview>
+			<AuthShell
+				className={styles.canvas}
+				contentRender={<div />}
+				level={3}
+				brand={BRAND}
+				title="Welcome back"
+				description="Sign in to your Acme workspace."
+				cardFooter={<Text size="xs" type="secondary">Local demo · no account required</Text>}
+				postCard={<Text size="sm" type="secondary">New here? Ask your administrator for an invitation.</Text>}
+				policyLinks={POLICY}
+				strings={{ legalLabel: "Legal (card example)" }}
+			>
+				<SignInDemo showFailureControl />
+			</AuthShell>
+		</div>
+	)
+}
 ```
 
 ### Bare · a quiet canvas
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AuthShell variant="bare" size="sm" brand={brand}
-  title="Make yourself at home" policyLinks={policy}>
-  <YourSignInForm />
-</AuthShell>
+import { AuthShell } from "themelia-ui/layout/auth"
+
+import styles from "./auth-shell.module.css"
+import { POLICY } from "./data"
+import { BRAND } from "./_brand"
+import { SignInDemo } from "./_shared"
+
+export default function AuthBare() {
+	return (
+		<div className={styles.frame} data-auth-preview>
+			<AuthShell
+				className={styles.canvas}
+				contentRender={<div />}
+				variant="bare"
+				size="sm"
+				level={3}
+				brand={BRAND}
+				title="Make yourself at home"
+				description="Your workspace is ready for you."
+				policyLinks={POLICY}
+				strings={{ legalLabel: "Legal (bare example)" }}
+			>
+				<SignInDemo />
+			</AuthShell>
+		</div>
+	)
+}
 ```
 
 ### Split · a story beside the form
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AuthShell variant="split" splitSide="start" splitMobile="stacked"
-  splitPanel={<WorkspaceStory />} brand={brand} title="Good to see you again">
-  <YourSignInForm />
-</AuthShell>
+import { useId, useState } from "react"
+import { GlobeIcon } from "lucide-react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Checkbox } from "themelia-ui/base/choice-inputs"
+import { DialogContent } from "themelia-ui/base/dialog"
+import {
+	Overlay, OverlayBody, OverlayDescription, OverlayHeader, OverlayTitle, OverlayTrigger,
+} from "themelia-ui/base/overlay"
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, Heading, Text } from "themelia-ui/base/typography"
+import { AuthShell } from "themelia-ui/layout/auth"
+
+import styles from "./auth-shell.module.css"
+import { POLICY } from "./data"
+import { BRAND } from "./_brand"
+import { SignInDemo } from "./_shared"
+
+function WorkspacePanel() {
+	return (
+		<>
+			<Stack gap="xl">
+				<DisplayLabel>Built for your team</DisplayLabel>
+				<Heading level={3} size="2xl">A clearer start to your working day.</Heading>
+				<Text type="secondary" lineHeight="relaxed">Bring your people, projects, and decisions into one shared workspace.</Text>
+			</Stack>
+			<Stack gap="lg">
+				<Text type="inherit" size="lg" lineHeight="relaxed">“Everything we need is ready when we sign in. We spend more time doing the work together.”</Text>
+				<Text type="secondary" size="sm">Jordan Lee · Operations at Northwind</Text>
+			</Stack>
+		</>
+	)
+}
+
+function SplitSignInDemo({ stackedPanel, legalLabel }: { stackedPanel: boolean; legalLabel: string }) {
+	return (
+		<AuthShell
+			className={styles.canvas}
+			contentRender={<div />}
+			variant="split"
+			splitSide="start"
+			splitMobile={stackedPanel ? "stacked" : "hidden"}
+			brand={BRAND}
+			level={3}
+			title="Good to see you again"
+			description="Pick up where your team left off."
+			policyLinks={POLICY}
+			strings={{ legalLabel }}
+			languageSwitcher={<Text size="xs" type="secondary"><GlobeIcon aria-hidden className={styles.inlineIcon} /> English (UK)</Text>}
+			splitPanel={<WorkspacePanel />}
+		>
+			<SignInDemo />
+		</AuthShell>
+	)
+}
+
+export default function AuthSplit() {
+	const [stackedPanel, setStackedPanel] = useState(true)
+	const expandedTitleId = useId()
+	const expandedDescriptionId = useId()
+
+	return (
+		<>
+			<Stack direction="horizontal" align="center" justify="between" gap="lg" wrap>
+				<Checkbox label="Show the panel on small screens" checked={stackedPanel} onChange={(event) => setStackedPanel(event.target.checked)} />
+				<Overlay>
+					<OverlayTrigger render={<Button tone="neutral" buttonStyle="outline" />}>Expand split preview</OverlayTrigger>
+					<DialogContent className={styles.expandedDialog} aria-labelledby={expandedTitleId} aria-describedby={expandedDescriptionId}>
+						<OverlayHeader>
+							<OverlayTitle id={expandedTitleId}>Split auth preview</OverlayTitle>
+							<OverlayDescription id={expandedDescriptionId}>The same composition adapts to the space available. This is a local sign-in demo.</OverlayDescription>
+						</OverlayHeader>
+						<OverlayBody>
+							<div className={styles.frame}>
+								<SplitSignInDemo stackedPanel={stackedPanel} legalLabel="Legal (expanded split example)" />
+							</div>
+						</OverlayBody>
+					</DialogContent>
+				</Overlay>
+			</Stack>
+			<div className={styles.frame} data-auth-preview>
+				<SplitSignInDemo stackedPanel={stackedPanel} legalLabel="Legal (split example)" />
+			</div>
+		</>
+	)
+}
 ```
 
 ### Composed · bring your own surface
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AuthSplitPanel
-  panelMobile="stacked"
-  form={<Stack gap="xl">
-    <AuthCard title="Join your team" headerEnd={<Badge>Invite</Badge>}>
-      <YourSignInForm />
-    </AuthCard>
-    <AuthFooterLinks label="Legal" links={policy} />
-  </Stack>}
-  panel={<WorkspaceInvitation />}
-/>
+import { ArrowRightIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, Heading, Text } from "themelia-ui/base/typography"
+import { AuthCard, AuthFooterLinks, AuthSplitPanel } from "themelia-ui/layout/auth"
+
+import styles from "./auth-shell.module.css"
+import { POLICY } from "./data"
+import { SignInDemo } from "./_shared"
+
+export default function AuthComposed() {
+	return (
+		<div id="auth-card" className={styles.frame} data-auth-preview>
+			<AuthSplitPanel
+				className={styles.composed}
+				panelMobile="stacked"
+				form={
+					<Stack gap="xl" className={styles.formColumn}>
+						<AuthCard
+							level={3}
+							title="Join your team"
+							description="Sign in to accept your workspace invitation."
+							headerEnd={<Badge tone="info">Invite</Badge>}
+							footer={<Text size="xs" type="secondary">Invited by alex@northwind.example</Text>}
+						>
+							<SignInDemo />
+						</AuthCard>
+						<AuthFooterLinks label="Legal (composed example)" links={POLICY} />
+					</Stack>
+				}
+				panel={
+					<Stack gap="xl">
+						<DisplayLabel>Northwind workspace</DisplayLabel>
+						<Heading level={3} size="xl">Your next chapter starts together.</Heading>
+						<Text type="secondary" lineHeight="relaxed">You have been invited to collaborate with the operations team. Your projects and conversations will be waiting.</Text>
+						<Text type="inherit" size="sm"><ArrowRightIcon aria-hidden className={styles.inlineIcon} /> One workspace for the whole team</Text>
+					</Stack>
+				}
+			/>
+		</div>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/layout/containers.css"
 
 ## Composition
 
-This family has no component-family dependencies.
+This module depends on no other module.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -111,8 +111,8 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `header` | no | `React.ReactNode` | Spans both columns, before the work regions. |
-| `main` | yes | `React.ReactNode` | Primary detail, form, or index content. |
-| `aside` | yes | `React.ReactNode` | Secondary summary, support, or action rail. |
+| `main` | yes | `React.ReactNode` | The primary work region: detail, form, or index content. |
+| `aside` | yes | `React.ReactNode` | The secondary work region: summary, support, or action rail. Always second in the DOM. |
 | `footer` | no | `React.ReactNode` | Spans both columns, after the work regions. |
 | `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. |
@@ -124,23 +124,50 @@ Preview route: Containers — `/containers`
 ### The four blocks
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<PageViewport>
-  <Container maxWidth="xl" gutter="md">
-    <Section>
-      <PageHeading title="Invoices" />
-      <Card>…</Card>
-    </Section>
-  </Container>
-</PageViewport>
+import { Card } from "themelia-ui/base/cards"
+import { Text } from "themelia-ui/base/typography"
+import { Container, Section } from "themelia-ui/layout/containers"
+
+export default function Blocks() {
+	return (
+		// Dashed on the inline edges only: the gutter is inline padding.
+		<Container maxWidth="md" gutter="sm" style={{ borderInline: "1px dashed var(--border)" }}>
+			<Section>
+				<Card surface="bordered" title="Section" description="A group, with the rhythm between its children.">
+					<Text size="sm" type="secondary">
+						Container centres this at the reading measure and owns the gutter you can
+						see as the dashed edge.
+					</Text>
+				</Card>
+				<Card surface="bordered" title="Second group" />
+			</Section>
+		</Container>
+	)
+}
 ```
 
 ### TwoColumnLayout
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TwoColumnLayout
-  main={<InvoiceForm />}
-  aside={<SummaryCard />}
-  asidePosition="end"
-  stickyAside
-/>
+import { Card } from "themelia-ui/base/cards"
+import { Text } from "themelia-ui/base/typography"
+import { TwoColumnLayout } from "themelia-ui/layout/containers"
+
+export default function TwoColumn() {
+	return (
+		<TwoColumnLayout
+			style={{ width: "100%" }}
+			main={
+				<Card surface="bordered" title="main" description="Primary detail, form, or index content.">
+					<Text size="sm" type="secondary">Takes the wider column.</Text>
+				</Card>
+			}
+			aside={
+				<Card surface="bordered" title="aside" description="Summary, support, or an action rail.">
+					<Text size="sm" type="secondary">Second in the DOM, always.</Text>
+				</Card>
+			}
+		/>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/layout/header.css"
 
 ## Composition
 
-This family composes `base/action-menu`, `base/avatar`, `base/buttons`, `base/display`, `base/dropdown-menu`, `base/navigation`, `base/popover`, `base/sidebar`, `base/typography`.
+This module composes `base/action-menu`, `base/avatar`, `base/buttons`, `base/display`, `base/dropdown-menu`, `base/navigation`, `base/popover`, `base/sidebar`, `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.
@@ -71,6 +71,11 @@ Kind: callable.
 
 Kind: callable.
 
+The sidebar trigger, a rule, and the trail. The three travel together because their
+arrangement is the part that goes wrong — a trail without the rule reads as the first
+crumb, and a trigger placed after it reads as part of the path. The trigger stays fixed
+while the trail truncates.
+
 ```text
 ({ breadcrumbs, homeCrumb, strings, showSidebarTrigger, triggerSlot, className, }: HeaderBreadcrumbsProps) => import("react").JSX.Element
 ```
@@ -102,8 +107,9 @@ Kind: interface.
 
 Kind: callable.
 
-The same trigger, reporting into a controlled `open`. A separate component so a trigger
-never half-owns the palette's state.
+The same trigger — a button shaped like a field, for a palette where the typing happens —
+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
@@ -138,6 +144,10 @@ Kind: interface.
 
 Kind: callable.
 
+The bell and its list. It renders what it is handed and reports what was clicked;
+fetching, marking read and paging belong to the app, because only the app knows what
+“read” costs.
+
 ```text
 ({ notifications, unreadCount, onNotificationClick, onMarkAllRead, onViewAll, viewAllHref, renderLink, align, side, strings, className, contentClassName, renderNotification, }: HeaderNotificationsProps) => import("react").JSX.Element
 ```
@@ -185,18 +195,22 @@ Extends: `React.ComponentProps<"header">`, `LayoutNavigationAdapter`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `showBreadcrumbs` | no | `boolean` |  |
+| `showBreadcrumbs` | no | `boolean` | Off for a shell whose pages carry their own trail. |
 | `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. `null` omits it;<br>leaving it undefined keeps the default. |
+| `breadcrumbs` | no | `Crumb[]` | The trail, rendered by the built-in Breadcrumbs. |
+| `homeCrumb` | no | `Crumb \| null` | Prepended to the trail, for a root that is not part of the route. `null` omits it<br>deliberately. |
 | `breadcrumbsStrings` | no | `Partial<HeaderBreadcrumbsStrings>` | Overrides the trail's copy — its landmark name, for a page carrying two headers. |
-| `slots` | no | `HeaderSlots` |  |
-| `contentClassName` | no | `string` |  |
+| `slots` | no | `HeaderSlots` | The regions. `brand` is hidden below `md`, where the sidebar trigger stands in for it. |
+| `contentClassName` | no | `string` | For the inner content row, when the bar itself must stay untouched. |
 
 ### `HeaderSearch`
 
 Kind: callable.
 
+The trigger for a command palette, not a search field. It LOOKS like an input and IS a
+button, which is the honest shape: typing happens in the palette, so a real field here
+would take a keystroke and then throw it away.
+
 ```text
 ({ onOpen, shortcutModifier, enableShortcut, strings, className, shortcutSlot, }: HeaderSearchProps) => import("react").JSX.Element
 ```
@@ -228,6 +242,8 @@ Kind: interface.
 
 Kind: interface.
 
+The regions `Header` arranges, passed as its `slots`.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `brand` | no | `React.ReactNode` | Product mark. Hidden below `md`, where the sidebar trigger stands in for it. |
@@ -262,7 +278,8 @@ Kind: interface.
 
 Kind: callable.
 
-The same control with a surface hanging off it.
+The same control with a surface hanging off it, in the same one shape as every icon
+control in the right cluster.
 
 ```text
 ({ label, icon, open, defaultOpen, onOpenChange, active, disabled, badge, align, side, sideOffset, className, triggerClassName, contentClassName, children, }: HeaderToolPopoverProps) => import("react").JSX.Element
@@ -291,6 +308,10 @@ Extends: `Omit<HeaderToolButtonProps, "onClick" | "className">`.
 
 Kind: callable.
 
+The account control. The three callbacks build a command menu; supplying none and
+passing `customContent` instead gives a panel, which is the escape hatch for an account
+area that is not a list of verbs.
+
 ```text
 ({ user, showIdentity, showEmail, customContent, onProfile, onSettings, onLogout, align, side, strings, className, contentClassName, renderTrigger, }: HeaderUserMenuProps) => import("react").JSX.Element
 ```
@@ -326,6 +347,45 @@ Kind: interface.
 | `logout` | yes | `string` |  |
 | `trigger` | yes | `string` | Names the trigger when the caller hides the name — an avatar alone has none. |
 
+### `LinkRenderer`
+
+Kind: type.
+
+How a component renders a link: through the application's router. Every component that
+navigates takes one as `renderLink`, and without one renders a plain anchor. Return one
+element: the component may merge its own props into it, such as a menu item's role or a
+button's styling.
+
+```tsx fragment — declaration JSDoc excerpt
+const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <Link to={href} {...rest}>{children}</Link>
+```
+
+```text
+(props: LinkRenderProps) => ReactElement
+```
+
+### `LinkRenderProps`
+
+Kind: interface.
+
+What a component hands its link renderer. Spread everything but `active`, `disabled` and `external` onto the element.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | no | `string` | Destination. When absent, render non-interactive content. |
+| `children` | yes | `ReactNode` |  |
+| `className` | no | `string` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `onClick` | no | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-current"` | no | `AriaAttributes["aria-current"]` |  |
+| `"aria-disabled"` | no | `AriaAttributes["aria-disabled"]` |  |
+| `active` | no | `boolean` | Hint for active styling. A renderer may ignore it — the component styles the row itself. |
+| `disabled` | no | `boolean` | The entry goes nowhere: render non-interactive content. |
+| `external` | no | `boolean` | Opens elsewhere: the default renderer adds `target="_blank"` and `rel="noopener noreferrer"`. |
+
 ### `NotificationTone`
 
 Kind: type.
@@ -343,20 +403,65 @@ Preview route: Header — `/header`
 ### Header
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Header
-  breadcrumbs={[{ label: "Billing", href: "/billing" }, { label: "Invoices" }]}
-  slots={{
-    center: <SearchInput />,
-    right: <><Notifications /><Account /></>,
-  }}
-/>
+import { BellIcon, PlusIcon } from "lucide-react"
+
+import { Avatar, AvatarFallback } from "themelia-ui/base/avatar"
+import { Button } from "themelia-ui/base/buttons"
+import { SearchInput } from "themelia-ui/base/text-inputs"
+import { Header } from "themelia-ui/layout/header"
+
+import { FRAME, FRAME_BODY } from "./data"
+
+export default function HeaderExample() {
+	return (
+		<div style={FRAME}>
+			<Header
+				breadcrumbs={[{ label: "Billing", href: "#/header" }, { label: "Invoices" }]}
+				slots={{
+					center: <SearchInput placeholder="Search invoices…" />,
+					right: (
+						<>
+							<Button tone="neutral" buttonStyle="outline">
+								<PlusIcon />
+								New
+							</Button>
+							<Button iconOnly tone="neutral" buttonStyle="ghost" aria-label="Notifications">
+								<BellIcon />
+							</Button>
+							<Avatar size="sm">
+								<AvatarFallback>JM</AvatarFallback>
+							</Avatar>
+						</>
+					),
+				}}
+			/>
+			<div style={FRAME_BODY} />
+		</div>
+	)
+}
 ```
 
 ### Breadcrumbs are built in
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Header
-  homeCrumb={{ label: "Home", href: "/" }}
-  breadcrumbs={[{ label: "Settings", href: "/settings" }, { label: "Members" }]}
-/>
+import { Header } from "themelia-ui/layout/header"
+
+import { FRAME, FRAME_BODY } from "./data"
+
+export default function HeaderBreadcrumbsExample() {
+	return (
+		<div style={FRAME}>
+			<Header
+				homeCrumb={{ label: "Home", href: "#/header" }}
+				/* A second trail on the page needs a distinct landmark name. */
+				breadcrumbsStrings={{ label: "Settings breadcrumb example" }}
+				breadcrumbs={[
+					{ label: "Settings", href: "#/settings-shell" },
+					{ label: "Members" },
+				]}
+			/>
+			<div style={FRAME_BODY} />
+		</div>
+	)
+}
 ```