themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/base--accordion.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/accordion.css"
 
 ## Composition
 
-This family composes `base/typography`.
+This module composes `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.
@@ -98,13 +98,13 @@ group reserves it on every row so titles align.
 
 Kind: interface.
 
-Extends: `AccordionPrimitive.Root.Props<string>`.
+Extends: `AccordionPrimitive.Root.Props<string>`, `Pick<AccordionPrimitive.Root.Props<string>, "multiple" | "defaultValue" | "value">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `surface` | no | `AccordionSurface` | Outer chrome. Resolves through the provider when omitted. |
+| `surface` | no | `AccordionSurface` | The group's chrome: one bordered shell with dividers, a panel per section, or none.<br>Resolves through the provider when omitted, so `UIProvider` defaults can change it. @default "bordered" |
 | `items` | no | `AccordionItemData[]` | Bounded sections, each rendered as the canonical icon/title/badge/description row.<br>Ignored when `children` are supplied. |
-| `media` | no | `AccordionMedia` | How leading media is framed. Only meaningful alongside `items`. |
+| `media` | no | `AccordionMedia` | How leading icons are framed. Only meaningful alongside `items`; the column is dropped<br>entirely when no item has one. `UIProvider` defaults can change it. @default "inline" |
 
 ### `AccordionSurface`
 
@@ -140,9 +140,70 @@ Preview route: Accordion — `/accordion`
 ### Accordion
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Accordion
-  items={[
-    { value: "billing", title: "Billing", description: "…", content: <…/> },
-  ]}
-/>
+import { Accordion } from "themelia-ui/base/accordion"
+import { Badge } from "themelia-ui/base/badge"
+
+
+export default function AccordionExample() {
+	return (
+		<Accordion
+			defaultValue={["billing"]}
+			style={{ maxWidth: "34rem", width: "100%" }}
+			items={[
+				{
+					value: "billing",
+					title: "Billing",
+					description: "Payment method, invoices, and tax details",
+					badge: <Badge tone="neutral">Updated</Badge>,
+					content:
+						"Invoices are issued on the first of the month and charged to the card on file. Changing the card mid-cycle does not re-issue the open invoice.",
+				},
+				{
+					value: "members",
+					title: "Members",
+					description: "Who can sign in and what they can do",
+					content:
+						"Members inherit the workspace role unless a project overrides it. Removing a member revokes their sessions immediately.",
+				},
+				{
+					value: "api",
+					title: "API access",
+					description: "Keys, scopes, and rate limits",
+					disabled: true,
+					content: "Available on the Team plan.",
+				},
+			]}
+		/>
+	)
+}
+```
+
+### Accordion surfaces
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Accordion } from "themelia-ui/base/accordion"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function AccordionSurfaces() {
+	return (
+		<Stack gap="xl" style={{ maxWidth: "34rem", width: "100%" }}>
+			{(["bordered", "card", "flat"] as const).map((surface) => (
+				<Stack key={surface} gap="sm">
+					<Text size="xs" type="secondary">
+						{surface}
+					</Text>
+					<Accordion
+						surface={surface}
+						items={[
+							{ value: "a", title: "First section", content: "Body copy." },
+							{ value: "b", title: "Second section", content: "Body copy." },
+						]}
+					/>
+				</Stack>
+			))}
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--action-menu.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/action-menu.css"
 
 ## Composition
 
-This family composes `base/buttons`, `base/dropdown-menu`, `base/typography`.
+This module composes `base/buttons`, `base/dropdown-menu`, `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.
@@ -43,22 +43,24 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `actions` | yes | `readonly ActionDefinition[]` | The same definitions, side by side rather than collapsed into a menu. |
+| `actions` | yes | `readonly ActionDefinition[]` | The same definitions `ActionMenu` takes, side by side rather than collapsed into a menu:<br>that is the point of the shape. Each entry's `tone` and `buttonStyle` carry through to<br>its button. |
 | `max` | no | `number` | How many render as buttons before the rest collapse into an overflow menu built from<br>the same array. Unset, every definition is a button. |
-| `strings` | no | `Partial<ActionMenuStrings>` | Overrides this toolbar's own copy — the overflow trigger's name. |
+| `strings` | no | `Partial<ActionMenuStrings>` | Overrides this toolbar's own copy: `strings.overflow` names the overflow menu's trigger. |
 | `className` | no | `string` |  |
-| `renderLink` | no | `ActionLinkRenderer` |  |
+| `renderLink` | no | `LinkRenderer` | Routes `href` actions through the app's router, as `ActionMenu`'s `renderLink` does. |
 
 ### `ActionDefinition`
 
 Kind: interface.
 
+One command, in the shape `ActionMenu`, `ActionButtons` and a card's `actions` all take.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `id` | no | `string` | Stable key. Falls back to a string `label`, then the index. |
-| `label` | yes | `ReactNode` |  |
+| `label` | yes | `ReactNode` | What the entry says. The only part of the row that gives way: a long label truncates<br>instead of pushing the shortcut or trailing content off. |
 | `icon` | no | `ActionIcon` |  |
-| `type` | no | `"item" \| "checkbox"` | `checkbox` renders a toggle driven by `checked` / `onCheckedChange`. |
+| `type` | no | `"item" \| "checkbox"` | `checkbox` renders a toggle driven by `checked` / `onCheckedChange`. @default "item" |
 | `href` | no | `string` | Renders the entry as a link. A native `<a href>` by default, which is a full page<br>navigation — pass `renderLink` to route it through the app's router instead. |
 | `target` | no | `string` |  |
 | `rel` | no | `string` |  |
@@ -72,7 +74,7 @@ Kind: interface.
 | `group` | no | `string \| true` | Starts a new group, ruling off above this entry. A string also captions it; `true`<br>rules off without a heading (e.g. to set apart a sign-out or delete). |
 | `tone` | no | `ButtonTone` | Semantic intent. `destructive` also moves the entry last and separates it. |
 | `buttonStyle` | no | `ButtonStyle \| "link"` | Treatment when the action renders as a button. `link` is a ghost that underlines. |
-| `visible` | no | `boolean` | `false` omits the action entirely. |
+| `visible` | no | `boolean` | `false` omits the action entirely. @default true |
 | `disabled` | no | `boolean` |  |
 | `closeOnSelect` | no | `boolean` | Overrides the menu's `closeOnSelect` for this entry. |
 | `className` | no | `string` |  |
@@ -88,27 +90,6 @@ A Lucide icon, any component taking a className, or an already-rendered node.
 ComponentType<{ className?: string; }> | ReactNode
 ```
 
-### `ActionLinkRenderer`
-
-Kind: type.
-
-```text
-(props: ActionLinkRenderProps) => ReactElement
-```
-
-### `ActionLinkRenderProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `href` | yes | `string` |  |
-| `children` | no | `ReactNode` |  |
-| `target` | no | `string` |  |
-| `rel` | no | `string` |  |
-| `external` | no | `boolean` |  |
-| `disabled` | no | `boolean` |  |
-
 ### `ActionMenu`
 
 Kind: callable.
@@ -134,22 +115,22 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `actions` | yes | `readonly ActionDefinition[]` | Commands to offer. Destructive entries move last unless `preserveOrder` is set. |
+| `actions` | yes | `readonly ActionDefinition[]` | Commands to offer; `visible: false` omits one entirely. Destructive entries move last<br>unless `preserveOrder` is set. |
 | `label` | no | `string` | Trigger text. Omit for an icon-only trigger — `strings.trigger` names it then. |
 | `icon` | no | `ActionIcon` | Trigger glyph. Defaults to the vertical ellipsis. |
-| `strings` | no | `Partial<ActionMenuStrings>` | Overrides this menu's own copy. |
-| `buttonProps` | no | `Omit<ComponentProps<typeof Button>, "children">` |  |
-| `align` | no | `"start" \| "center" \| "end"` |  |
-| `side` | no | `"top" \| "right" \| "bottom" \| "left"` |  |
-| `contentClassName` | no | `string` |  |
-| `width` | no | `string \| number \| "trigger"` | Fixed surface width, any CSS length, or `"trigger"` to match the trigger. Left<br>unset the menu sizes to its widest row. |
-| `minWidth` | no | `string \| number` |  |
-| `maxWidth` | no | `string \| number` | Ceiling for the content-sized default: a reading measure, so one long label doesn't widen every row. |
-| `closeOnSelect` | no | `boolean` |  |
-| `labelVisibility` | no | `ActionMenuLabelVisibility` |  |
-| `preserveOrder` | no | `boolean` | Keeps the incoming order instead of moving destructive entries last. |
-| `renderLink` | no | `ActionLinkRenderer` | Routes `href` actions through the app's router, keeping this framework-agnostic. |
-| `renderTrigger` | no | `ComponentProps<typeof DropdownMenuTrigger>["render"]` | Replaces the trigger entirely — an account block, a sidebar row, a tab. For different<br>words on a plain button, use `label` and `icon`. |
+| `strings` | no | `Partial<ActionMenuStrings>` | Overrides this menu's own copy: `trigger` names an icon-only trigger, which without a<br>visible label has no other name. |
+| `buttonProps` | no | `Omit<ComponentProps<typeof Button>, "children">` | Props for the default trigger button. Ignored when `renderTrigger` replaces it. |
+| `align` | no | `"start" \| "center" \| "end"` | How the surface lines up with the trigger along the side it opens on.<br>`UIProvider` defaults can change it. @default "end" |
+| `side` | no | `"top" \| "right" \| "bottom" \| "left"` | Where the surface opens relative to the trigger. |
+| `contentClassName` | no | `string` | Class for the menu surface itself: the escape hatch for styling it. |
+| `width` | no | `string \| number \| "trigger"` | Fixed surface width: any CSS length, or `"trigger"` to match the trigger, for a menu that<br>reads as the field's own list. Left unset the menu sizes to its widest row. |
+| `minWidth` | no | `string \| number` | A floor under the content-sized width. |
+| `maxWidth` | no | `string \| number` | Ceiling for the content-sized default: a reading measure rather than the viewport, so one<br>long label doesn't widen every row. Unset, the surface also stops at the space available. @default "20rem" |
+| `closeOnSelect` | no | `boolean` | Closes the menu when an entry is chosen. Turn it off for a menu of checkbox rows, where<br>the reader is setting several things at once; an entry's own `closeOnSelect` overrides<br>it. `UIProvider` defaults can change it. @default true |
+| `labelVisibility` | no | `ActionMenuLabelVisibility` | Where the trigger's `label` shows. `responsive` hides it below `sm`, leaving the glyph,<br>for a toolbar that has to survive a phone; `hidden` hides it at every width.<br>`UIProvider` defaults can change it. @default "visible" |
+| `preserveOrder` | no | `boolean` | Keeps the declared order instead of moving destructive entries last. |
+| `renderLink` | no | `LinkRenderer` | Routes `href` actions through the app's router, keeping this framework-agnostic. Return<br>an element, not a function that spreads props: the menu merges its own props onto the<br>element, so the row keeps its menu item role. |
+| `renderTrigger` | no | `ComponentProps<typeof DropdownMenuTrigger>["render"]` | Replaces the trigger entirely, for a menu hanging off something that is not a button:<br>an account block, a sidebar row, a tab. For different words on a plain button, use<br>`label` and `icon`. |
 
 ### `ActionMenuStrings`
 
@@ -192,10 +173,10 @@ Extends: `Omit<ActionDefinition, "onClick" | "visible" | "disabled">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `onClick` | no | `(context: TContext) => void` |  |
-| `visible` | no | `ActionPredicate<TContext>` | `false`, or a predicate returning false, omits the action for that subject. |
-| `disabled` | no | `ActionPredicate<TContext>` |  |
-| `placement` | no | `ActionPlacement` | Forces this entry to one side when the set is split between buttons and a menu: `menu`<br>keeps it out of the button row, `inline` pins it there, `auto` lets the renderer decide. |
+| `onClick` | no | `(context: TContext) => void` | Receives the subject the set was resolved against. |
+| `visible` | no | `ActionPredicate<TContext>` | `false`, or a predicate returning false, omits the action for that subject. @default true |
+| `disabled` | no | `ActionPredicate<TContext>` | Worked out per subject, so a locked row shows the action greyed rather than missing. @default false |
+| `placement` | no | `ActionPlacement` | Forces this entry to one side when the set is split between buttons and a menu:<br>`inline` stays a button whatever `max` is, `menu` always overflows, and `auto` fills<br>the buttons in order up to `max`. @default "auto" |
 
 ### `ContextActionSource`
 
@@ -215,6 +196,45 @@ Kind: const.
 ActionMenuStrings
 ```
 
+### `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"`. |
+
 ### `resolveContextActions`
 
 Kind: callable.
@@ -262,54 +282,217 @@ Preview route: Action menu & buttons — `/action-menu`
 ### ActionMenu
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActionMenu
-  actions={[
-    { label: "Edit", icon: PencilIcon, onClick: … },
-    { label: "Archive", icon: ArchiveIcon, onClick: …, group: true },
-    { label: "Delete", icon: TrashIcon, onClick: …, tone: "destructive" },
-  ]}
-/>
+import { useState } from "react"
+import {
+	ArchiveIcon, ChevronDownIcon, DownloadIcon, PencilIcon, SettingsIcon, ShareIcon, TrashIcon,
+} from "lucide-react"
+
+import { ActionMenu, type ActionDefinition } from "themelia-ui/base/action-menu"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function ActionMenuExample() {
+	const [showArchived, setShowArchived] = useState(false)
+
+	const actions: ActionDefinition[] = [
+		{ label: "Edit", icon: PencilIcon, onClick: () => {} },
+		{ label: "Duplicate", icon: ShareIcon, onClick: () => {} },
+		{
+			group: "View",
+			label: "Show archived",
+			type: "checkbox",
+			checked: showArchived,
+			onCheckedChange: setShowArchived,
+		},
+		{ label: "Export as CSV", icon: DownloadIcon, onClick: () => {} },
+		{ label: "Archive", icon: ArchiveIcon, onClick: () => {}, group: true },
+		{ label: "Delete", icon: TrashIcon, onClick: () => {}, tone: "destructive" },
+	]
+
+	return (
+		<Stack direction="horizontal" gap="xl" align="center">
+			<ActionMenu actions={actions} />
+			<ActionMenu actions={actions} label="Actions" icon={SettingsIcon} />
+			<ActionMenu
+				actions={actions}
+				renderTrigger={
+					<Button buttonStyle="outline" tone="neutral">
+						Custom trigger
+						<ChevronDownIcon />
+					</Button>
+				}
+			/>
+		</Stack>
+	)
+}
 ```
 
 ### Destructive last
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-const declared = [
-  { label: "Delete", tone: "destructive", onClick: … },
-  { label: "Edit", onClick: … },
-  { label: "Duplicate", onClick: … },
+import { PencilIcon, ShareIcon, TrashIcon } from "lucide-react"
+
+import { ActionMenu, type ActionDefinition } from "themelia-ui/base/action-menu"
+import { Stack } from "themelia-ui/base/structure"
+
+/* Delete declared first on purpose: the example shows it moving last. */
+const DESTRUCTIVE_FIRST: ActionDefinition[] = [
+	{ label: "Delete", icon: TrashIcon, onClick: () => {}, tone: "destructive" },
+	{ label: "Edit", icon: PencilIcon, onClick: () => {} },
+	{ label: "Duplicate", icon: ShareIcon, onClick: () => {} },
 ]
 
-<ActionMenu actions={declared} />
-<ActionMenu actions={declared} preserveOrder />
+export default function ActionMenuOrder() {
+	return (
+		// The same delete-first array: default ordering on the left, `preserveOrder` on the right.
+		<Stack direction="horizontal" gap="lg" align="center">
+			<ActionMenu
+				actions={DESTRUCTIVE_FIRST}
+				label="Sorted"
+				buttonProps={{ tone: "neutral", buttonStyle: "outline" }}
+			/>
+			<ActionMenu
+				actions={DESTRUCTIVE_FIRST}
+				preserveOrder
+				label="preserveOrder"
+				buttonProps={{ tone: "neutral", buttonStyle: "outline" }}
+			/>
+		</Stack>
+	)
+}
 ```
 
 ### Width and row slots
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActionMenu actions={actions} maxWidth="18rem" />
-<ActionMenu actions={actions} width={280} />
-<ActionMenu actions={actions} width="trigger" label="Matches trigger" />
-
-// Rows take slots, so the label is the only part that gives way:
-{ label: "Duplicate", icon: CopyIcon, shortcut: "⌘D" }
-{ label: "Export", description: "CSV, one row per invoice" }
+import {
+	ArchiveIcon, ChevronDownIcon, DownloadIcon, PencilIcon, ShareIcon, TrashIcon,
+} from "lucide-react"
+
+import { ActionMenu } from "themelia-ui/base/action-menu"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function ActionMenuWidth() {
+	return (
+		<Stack direction="horizontal" gap="xl" align="center" wrap>
+			<ActionMenu
+				label="Shortcuts"
+				actions={[
+					{ label: "Edit", icon: PencilIcon, shortcut: "⌘E", onClick: () => {} },
+					{ label: "Duplicate", icon: ShareIcon, shortcut: "⌘D", onClick: () => {} },
+					{ label: "Export as CSV", icon: DownloadIcon, shortcut: "⌘⇧E", onClick: () => {} },
+					{ label: "Delete", icon: TrashIcon, shortcut: "⌫", onClick: () => {}, tone: "destructive" },
+				]}
+			/>
+			<ActionMenu
+				label="Descriptions"
+				actions={[
+					{ label: "Edit", icon: PencilIcon, description: "Change the name and the billing address.", onClick: () => {} },
+					{ label: "Export", icon: DownloadIcon, description: "CSV, one row per invoice.", onClick: () => {} },
+					{ label: "Delete", icon: TrashIcon, description: "Permanent. Invoices are kept for seven years.", onClick: () => {}, tone: "destructive" },
+				]}
+				maxWidth="20rem"
+			/>
+			<ActionMenu
+				label="Fixed 280px"
+				width={280}
+				actions={[
+					{ label: "A short one", onClick: () => {} },
+					{ label: "A considerably longer label that would otherwise set the width", onClick: () => {} },
+				]}
+			/>
+			<ActionMenu
+				renderTrigger={
+					<Button buttonStyle="outline" tone="neutral" style={{ width: "16rem" }}>
+						Matches the trigger
+						<ChevronDownIcon />
+					</Button>
+				}
+				width="trigger"
+				actions={[
+					{ label: "Edit", icon: PencilIcon, onClick: () => {} },
+					{ label: "Archive", icon: ArchiveIcon, onClick: () => {} },
+				]}
+			/>
+		</Stack>
+	)
+}
 ```
 
-### In a card header
+### The same definitions, as buttons
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActionButtons actions={toolbar} max={2} />
+import { ArchiveIcon, DownloadIcon, PencilIcon, ShareIcon, TrashIcon } from "lucide-react"
+
+import { ActionButtons, type ActionDefinition } from "themelia-ui/base/action-menu"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+import { QUIET } from "./data"
+
+const TOOLBAR: ActionDefinition[] = [
+	{ label: "Edit", icon: PencilIcon, onClick: () => {} },
+	{ label: "Duplicate", icon: ShareIcon, ...QUIET, onClick: () => {} },
+	{ label: "Export", icon: DownloadIcon, ...QUIET, onClick: () => {} },
+	{ label: "Archive", icon: ArchiveIcon, ...QUIET, onClick: () => {} },
+	{ label: "Delete", icon: TrashIcon, buttonStyle: "outline", tone: "destructive", onClick: () => {} },
+]
+
+export default function ActionButtonsExample() {
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			{[5, 3, 1].map((max) => (
+				<Stack key={max} gap="xs">
+					<Text size="xs" type="secondary">max={max}</Text>
+					<ActionButtons actions={TOOLBAR} max={max} />
+				</Stack>
+			))}
+		</Stack>
+	)
+}
 ```
 
 ### Actions that depend on a record
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-const actions: ContextAction<Invoice>[] = [
-  { id: "send", label: "Send reminder", visible: (i) => !i.paid, placement: "inline" },
-  { id: "edit", label: "Edit", disabled: (i) => i.locked },
-  { id: "delete", label: "Delete", tone: "destructive", placement: "menu" },
+import { ArchiveIcon, SendIcon, PencilIcon, TrashIcon } from "lucide-react"
+
+import {
+	ActionButtons, resolveContextActions, type ContextAction,
+} from "themelia-ui/base/action-menu"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+import { QUIET } from "./data"
+
+interface Invoice { number: string; paid: boolean; locked: boolean }
+
+/* Declared once against the record type; predicates run per record and handlers receive it. */
+const INVOICE_ACTIONS: ContextAction<Invoice>[] = [
+	{ id: "send", label: "Send reminder", icon: SendIcon, visible: (invoice) => !invoice.paid, placement: "inline" },
+	{ id: "edit", label: "Edit", icon: PencilIcon, disabled: (invoice) => invoice.locked, ...QUIET },
+	{ id: "archive", label: "Archive", icon: ArchiveIcon, ...QUIET },
+	{ id: "delete", label: "Delete", icon: TrashIcon, tone: "destructive", placement: "menu" },
+]
+
+const INVOICES: Invoice[] = [
+	{ number: "INV-1042", paid: false, locked: false },
+	{ number: "INV-1038", paid: true, locked: true },
 ]
 
-<ActionButtons actions={resolveContextActions(actions, invoice)} max={2} />
+export default function ContextActions() {
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			{INVOICES.map((invoice) => (
+				<Stack key={invoice.number} gap="xs">
+					<Text size="xs" type="secondary">
+						{invoice.number} · {invoice.paid ? "paid, locked" : "unpaid"}
+					</Text>
+					<ActionButtons actions={resolveContextActions(INVOICE_ACTIONS, invoice)} max={2} />
+				</Stack>
+			))}
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--alert-dialog.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/alert-dialog.css"
 
 ## Composition
 
-This family composes `base/overlay`.
+This module composes `base/overlay`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -41,6 +41,9 @@ The affirmative answer. Closes on click unless the handler prevents it.
 
 Kind: callable.
 
+The answer that backs out. Both answers close the dialog; `AlertDialogAction` is the one
+that commits. With no dismissal and no corner close, they are the only ways out.
+
 ```text
 ({ className, ...props }: AnswerProps) => React.JSX.Element
 ```
@@ -49,6 +52,11 @@ Kind: callable.
 
 Kind: callable.
 
+A centred surface that demands an answer. It fixes `placement` to centre and announces as
+`alertdialog`; both dismissal routes are fixed off and the corner close is off by
+default, so the backdrop and Escape never decide for the reader. `modality`, `surface`
+and `initialFocusRef` are OverlayContent's props.
+
 ```text
 ({ className, ...props }: Omit<OverlayContentProps, "placement" | "dismissal">) => React.JSX.Element
 ```
@@ -70,21 +78,44 @@ Preview route: Overlay, dialog & sheet — `/overlay`
 ### Alert dialog
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Overlay>
-  <OverlayTrigger render={<Button tone="destructive">Delete account</Button>} />
-  <AlertDialogContent>
-    <OverlayHeader><OverlayTitle>Delete this account?</OverlayTitle></OverlayHeader>
-    <OverlayFooter>
-      <AlertDialogCancel render={<Button tone="neutral" buttonStyle="outline" />}>Cancel</AlertDialogCancel>
-      <AlertDialogAction render={<Button tone="destructive" />}>Delete</AlertDialogAction>
-    </OverlayFooter>
-  </AlertDialogContent>
-</Overlay>
-
-{/* AlertDialogContent is exactly */}
-<OverlayContent
-  role="alertdialog"
-  dismissal={{ backdrop: false, escape: false }}
-  showCloseButton={false}
-/>
+import {
+	AlertDialogAction, AlertDialogCancel, AlertDialogContent,
+} from "themelia-ui/base/alert-dialog"
+import { Button } from "themelia-ui/base/buttons"
+import {
+	Overlay, OverlayBody, OverlayDescription, OverlayFooter, OverlayHeader, OverlayTitle,
+	OverlayTrigger,
+} from "themelia-ui/base/overlay"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function AlertDialog() {
+	return (
+		<Stack direction="horizontal">
+			<Overlay>
+				<OverlayTrigger render={<Button tone="destructive" buttonStyle="outline" />}>
+					Delete account
+				</OverlayTrigger>
+				<AlertDialogContent>
+					<OverlayHeader>
+						<OverlayTitle>Delete this account?</OverlayTitle>
+						<OverlayDescription>This cannot be undone.</OverlayDescription>
+					</OverlayHeader>
+					<OverlayBody>
+						<Text type="secondary">Every project and invoice is removed permanently.</Text>
+					</OverlayBody>
+					<OverlayFooter>
+						<AlertDialogCancel render={<Button tone="neutral" buttonStyle="outline" />}>
+							Cancel
+						</AlertDialogCancel>
+						{/* The answer is an Action, not a second Cancel: they read the same only until a caller hooks the one that commits. */}
+						<AlertDialogAction render={<Button tone="destructive" />}>
+							Delete
+						</AlertDialogAction>
+					</OverlayFooter>
+				</AlertDialogContent>
+			</Overlay>
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--aspect-ratio.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/aspect-ratio.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.
@@ -44,7 +44,7 @@ Extends: `ComponentProps<"div">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `ratio` | no | `ResponsiveValue<number>` | Width divided by height — `16 / 9`, `1`, `4 / 3` — as a number, never parsed. |
-| `fit` | no | `"cover" \| "contain"` | How a media child fills the box: `cover` crops to fill (the usual frame); `contain` fits<br>inside, for artwork whose edges matter (a logo, a diagram, a screenshot). |
+| `fit` | no | `"cover" \| "contain"` | How a media child fills the box: `cover` crops to fill it (the usual frame); `contain`<br>fits the whole image inside and leaves the rest of the box empty, for artwork whose edges<br>matter (a logo, a diagram, a screenshot). |
 
 ## Preview recipes
 
@@ -53,7 +53,27 @@ Preview route: Aspect ratio — `/aspect-ratio`
 ### AspectRatio
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AspectRatio ratio={16 / 9}>
-  <img src={cover} alt="" />
-</AspectRatio>
+import { AspectRatio } from "themelia-ui/base/aspect-ratio"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function AspectRatioExample() {
+	return (
+		<Stack direction="horizontal" gap="lg" style={{ width: "100%" }}>
+			{[
+				{ ratio: 16 / 9, label: "16 / 9" },
+				{ ratio: 1, label: "1 / 1" },
+				{ ratio: 3 / 4, label: "3 / 4" },
+			].map((entry) => (
+				<Stack key={entry.label} gap="2xs" style={{ flex: 1 }}>
+					<AspectRatio ratio={entry.ratio}>
+						<div style={{ display: "grid", placeItems: "center", background: "var(--muted-40)", borderRadius: "var(--radius)" }}>
+							<Text size="xs" type="secondary">{entry.label}</Text>
+						</div>
+					</AspectRatio>
+				</Stack>
+			))}
+		</Stack>
+	)
+}
 ```