themelia-ui 3.0.0 → 3.2.0

package/docs/generated/components/features--resource-assignment.md

@@ -8,14 +8,13 @@ A resource is shared with or assigned to principals through a dialog.
 
 - **Use when:** A resource is shared with or assigned to principals through a dialog.
 - **Avoid when:** You are displaying permissions rather than changing them.
-- **Consider instead:** `admin/patterns/access`, `features/overlays`
+- **Consider instead:** `blocks/admin/access`, `features/overlays`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { DefaultDialogContent } from "themelia-ui/features/resource-assignment"
-import "themelia-ui/features/resource-assignment.css"
 ```
 
 ## Composition
@@ -366,7 +365,7 @@ function RecoverableVenuePicker({
 	error,
 }: SharedResourceSelectorProps<VenueHit, { error: string | null }>) {
 	return (
-		<Stack gap="md">
+		<Stack gap="sm">
 			{!!error && <Alert tone="destructive">{error}</Alert>}
 			<VenuePicker selected={selected} onSelect={onSelect} inModal />
 		</Stack>

package/docs/generated/components/features--resource.md

@@ -15,7 +15,6 @@ A record's index or show page needs its standard shell — header, actions bar a
 
 ```tsx fragment — import-only example
 import { ResourceActionBar } from "themelia-ui/features/resource"
-import "themelia-ui/features/resource.css"
 ```
 
 ## Composition
@@ -317,7 +316,7 @@ export default function ResourceIndex() {
 					<Button
 						key={option}
 						tone={state === option ? "primary" : "neutral"}
-						buttonStyle={state === option ? "solid" : "outline"}
+						appearance={state === option ? "solid" : "outline"}
 						onClick={() => setState(option)}
 					>
 						{option}
@@ -330,7 +329,7 @@ export default function ResourceIndex() {
 				description="Everything billed on this account."
 				actions={
 					<>
-						<Button tone="neutral" buttonStyle="outline">
+						<Button tone="neutral" appearance="outline">
 							<DownloadIcon />
 							Export
 						</Button>
@@ -390,7 +389,7 @@ export default function ResourceShow() {
 							{ label: "Amount", value: { kind: "money", value: 48_200, currency: "USD" } },
 							{ label: "Terms", value: "Net 14" },
 						]} />}
-						actions={<Button tone="neutral" buttonStyle="outline">Send reminder</Button>}
+						actions={<Button tone="neutral" appearance="outline">Send reminder</Button>}
 					/>
 				),
 				aside: (

package/docs/generated/components/features--rich-text-editor.md

@@ -15,7 +15,6 @@ Users author formatted content with a toolbar and counts.
 
 ```tsx fragment — import-only example
 import { EditorCounts } from "themelia-ui/features/rich-text-editor"
-import "themelia-ui/features/rich-text-editor.css"
 ```
 
 ## Optional peers
@@ -35,14 +34,6 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 ## Public declarations
 
-### `createExecCommandEngine`
-
-Kind: callable.
-
-```text
-(element: HTMLElement) => RichTextEngine
-```
-
 ### `defaultRichTextEditorStrings`
 
 Kind: const.
@@ -315,6 +306,44 @@ The shape the toolbar renders. Built-ins and consumer items resolve to this.
 
 Preview route: Rich text editor — `/rich-text-editor`
 
+### Website content reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { RichText, Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog, type MediaLibraryItem } from "themelia-ui/features/media-library"
+import { RichTextEditor } from "themelia-ui/features/rich-text-editor"
+import { SAMPLE_MEDIA } from "../media-library/reference-data"
+
+export default function WebsiteContentReference() {
+	const [locale, setLocale] = useState("en")
+	const [drafts, setDrafts] = useState<Record<string, string>>({ en: "<p>Welcome to our workspace.</p>", ar: "<p>مرحباً بكم</p>" })
+	const [mediaOpen, setMediaOpen] = useState(false)
+	const [image, setImage] = useState<MediaLibraryItem>()
+	const [alt, setAlt] = useState("")
+	const [failed, setFailed] = useState(true)
+	const [pending, setPending] = useState(false)
+	const [message, setMessage] = useState("Drafts are local until saved")
+	return <Card title="Website content" description="Each locale owns a retained draft. Preview sanitizes HTML; the application also validates and sanitizes persisted content.">
+		<Stack>
+			<PillRadioGroup aria-label="Content locale" name="reference-content-locale" value={locale} onValueChange={value => value && setLocale(value)} options={[{ value: "en", label: "English" }, { value: "ar", label: "العربية" }]} />
+			<div dir={locale === "ar" ? "rtl" : "ltr"}><RichTextEditor value={drafts[locale] ?? ""} onValueChange={html => setDrafts(current => ({ ...current, [locale]: html }))} /></div>
+			<MediaLibraryDialog open={mediaOpen} trigger={<Button tone="neutral" appearance="outline">Choose hero media</Button>} onOpenChange={setMediaOpen} items={SAMPLE_MEDIA} selectionMode="single" confirmOnSelect allowUpload={false} onConfirm={items => { const item = items[0]; setImage(item); setAlt(item?.alt ?? ""); setMediaOpen(false) }} />
+			{image && <FormField label="Hero image alternative text" hint={image.name}><Input value={alt} onChange={event => setAlt(event.target.value)} /></FormField>}
+			<Stack direction="horizontal" wrap gap="sm"><Button disabled={pending} onClick={async () => { if (pending) return; setPending(true); await new Promise(resolve => setTimeout(resolve, 250)); setMessage(failed ? "Save failed. All locale drafts and image text remain here." : "Mock website save completed"); setPending(false) }}>Save website content</Button><Button tone="neutral" appearance="outline" onClick={() => setFailed(value => !value)}>Toggle save failure</Button></Stack>
+			<Text role="status">{message}</Text>
+			<RichText html={drafts[locale] ?? ""} />
+		</Stack>
+	</Card>
+}
+```
+
 ### The editor and what comes out
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -341,14 +370,14 @@ export default function Editor() {
 				maxLength={280}
 			/>
 
-			<Stack gap="xs">
+			<Stack gap="sm">
 				<DisplayLabel>Emitted HTML</DisplayLabel>
-				<Text size="xs" type="secondary" className={styles.source}>
+				<Text size="xs" type="secondary" mono className={styles.source}>
 					{body || "(empty)"}
 				</Text>
 			</Stack>
 
-			<Stack gap="xs">
+			<Stack gap="sm">
 				<DisplayLabel>Rendered through RichText</DisplayLabel>
 				<RichText html={body} />
 			</Stack>
@@ -395,7 +424,7 @@ export default function EditorCompact() {
 				},
 			]}
 			footerSlot={
-				<Stack direction="horizontal" align="center" justify="between" gap="md">
+				<Stack direction="horizontal" align="center" justify="between" gap="sm">
 					<Text size="xs" type="secondary">
 						Markdown is not parsed — use the toolbar.
 					</Text>

package/docs/generated/components/features--schema-form.md

@@ -15,12 +15,11 @@ Fields are generated from a schema at runtime rather than written by hand.
 
 ```tsx fragment — import-only example
 import { SchemaForm } from "themelia-ui/features/schema-form"
-import "themelia-ui/features/schema-form.css"
 ```
 
 ## Composition
 
-This module composes `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/structure`, `base/text-inputs`, `base/value-inputs`.
+This module composes `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/structure`, `base/text-inputs`, `base/typography`, `base/value-inputs`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.

package/docs/generated/components/features--sync.md

@@ -15,7 +15,6 @@ A synchronisation run is configured over a date range.
 
 ```tsx fragment — import-only example
 import { SyncRangeForm } from "themelia-ui/features/sync"
-import "themelia-ui/features/sync.css"
 ```
 
 ## Optional peers
@@ -143,8 +142,8 @@ export default function SyncRangeFormExample() {
 				syncOptions={SYNC_OPTIONS}
 				onSubmit={(data) => setSubmitted(`${data.hours}h · ${data.options.join(", ") || "everything"}`)}
 			/>
-			<Stack direction="horizontal" gap="md" align="center">
-				<Button type="submit" form="sync-demo" buttonStyle="outline">
+			<Stack direction="horizontal" gap="sm" align="center">
+				<Button type="submit" form="sync-demo" appearance="outline">
 					Run sync
 				</Button>
 				{!!submitted && <Text size="sm" type="secondary">submitted: {submitted}</Text>}

package/docs/generated/components/features--table.md

@@ -15,7 +15,6 @@ A table needs columns, sorting, selection, cell renderers and a toolbar.
 
 ```tsx fragment — import-only example
 import { AvatarCell } from "themelia-ui/features/table"
-import "themelia-ui/features/table.css"
 ```
 
 ## Optional peers
@@ -28,7 +27,7 @@ npm install @tanstack/react-table
 
 ## Composition
 
-This module composes `base/action-menu`, `base/avatar`, `base/badge`, `base/batch-action-bar`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/navigation`, `base/table`, `base/text-inputs`, `base/toolbar`, `base/typography`.
+This module composes `base/action-menu`, `base/avatar`, `base/badge`, `base/batch-action-bar`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/navigation`, `base/skeleton`, `base/table`, `base/text-inputs`, `base/toolbar`, `base/typography`, `features/async-preview`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -240,7 +239,7 @@ Kind: callable.
 **Alternatives:** DataView.
 
 ```text
-({ size, surface, headerTransparent, columns, data, columnGroups, enableSorting, enableFiltering, enableRowSelection, enableMultiRowSelection, enableSubRowSelection, enableColumnVisibility, manualSorting, fullscreen: controlledFullscreen, defaultFullscreen, onFullscreenChange, showFullscreenToggle, stickyHeader, stickyToolbar, stickyFirstColumn, maxBodyHeight, fillAvailableHeight, striped, emptyStateMessage, emptyStateAction, className, rowClassName, cellClassName, headerClassName, wrapperClassName, tableContainerClassName, strings: stringsOverride, filterColumn, filterPlaceholder, topbarContent, topbarEnd, topbarClassName, toolbarLabelVisibility, footerContent, selectionToolbar, bulkActions, selectionToolbarClassName, rowActions, rowActionsMenuLabel, rowActionsDisplayMode, rowActionsBreakpoint, pageCount, page, onPageChange, totalRowCount, pageSize, onRowClick, onRowSelectionChange, onSortingChange, onColumnVisibilityChange, onColumnFiltersChange, getRowId, rowSelection: controlledRowSelection, sorting: controlledSorting, defaultSorting, columnVisibility: controlledColumnVisibility, defaultColumnVisibility, initialState, storageKey, style, }: DataTableProps<TData, TValue>) => import("react").JSX.Element
+({ size, surface, headerTransparent, columns, data, columnGroups, enableSorting, enableFiltering, enableRowSelection, enableMultiRowSelection, enableSubRowSelection, enableColumnVisibility, manualSorting, fullscreen: controlledFullscreen, defaultFullscreen, onFullscreenChange, showFullscreenToggle, stickyHeader, stickyToolbar, stickyFirstColumn, maxBodyHeight, fillAvailableHeight, striped, emptyStateMessage, emptyStateAction, className, rowClassName, cellClassName, headerClassName, wrapperClassName, tableContainerClassName, strings: stringsOverride, filterColumn, filterPlaceholder, topbarContent, topbarEnd, topbarClassName, toolbarLabelVisibility, footerContent, selectionToolbar, bulkActions, selectionToolbarClassName, rowActions, rowActionsMenuLabel, rowActionsDisplayMode, rowActionsBreakpoint, pageCount, page, onPageChange, totalRowCount, pageSize, onRowClick, expandedRow, onRowSelectionChange, onSortingChange, onColumnVisibilityChange, onColumnFiltersChange, getRowId, rowSelection: controlledRowSelection, sorting: controlledSorting, defaultSorting, columnVisibility: controlledColumnVisibility, defaultColumnVisibility, initialState, storageKey, style, }: DataTableProps<TData, TValue, TDetail>) => import("react").JSX.Element
 ```
 
 ### `DataTableActions`
@@ -274,7 +273,7 @@ Kind: callable.
 The body rows, and the row that stands in for all of them when there are none.
 
 ```text
-({ table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, hasSelectionColumn, striped, strings, }: DataTableBodyProps<TData>) => import("react").JSX.Element
+({ table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, hasSelectionColumn, hasExpandColumn, expandedRow, expansionId, striped, strings, }: DataTableBodyProps<TData>) => import("react").JSX.Element
 ```
 
 ### `DataTableBodyProps`
@@ -291,9 +290,41 @@ Kind: interface.
 | `rowClassName` | no | `string \| ((row: Row<TData>, index: number) => string)` |  |
 | `stickyFirstColumn` | no | `boolean` |  |
 | `hasSelectionColumn` | no | `boolean` | Whether column 0 is the selection checkbox, so the pinned pair covers the identity column too. |
+| `hasExpandColumn` | no | `boolean` | Whether the expand toggle column leads the row (after any checkbox), for the pinned group. |
+| `expandedRow` | no | `DataTableExpandedRow<TData, unknown>` | The expanded-row config. Open rows render its panel under them. |
+| `expansionId` | no | `string` | Prefixes each panel's id and cache key, so two tables never share either. |
 | `striped` | no | `boolean` |  |
 | `strings` | no | `DataTableStrings` |  |
 
+### `DataTableExpandedRow`
+
+Kind: interface.
+
+Expandable rows: a panel under an open row, opened by a toggle at the row's start. Passing
+`expandedRow` at all turns it on; `render` is the one required field.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `render` | yes | `(row: TData, context: DataTableExpandedRowContext<TDetail>) => ReactNode` | The panel under an open row. |
+| `onLoad` | no | `(row: TData, args: { signal: AbortSignal; }) => Promise<TDetail \| null \| undefined>` | Fetches what the panel shows when its row opens. The table shows a skeleton meanwhile,<br>aborts the request (`signal`) when the row closes, offers Retry on failure and keeps the<br>result for five minutes per row. `null` or `undefined` means the row has no details.<br>Write it before `render`: TypeScript types `detail` from it, left to right. |
+| `canExpand` | no | `(row: TData) => boolean` | Rows it refuses get no toggle and never open. |
+| `multiple` | no | `boolean` | Several rows open at once. `false` closes the open row when another opens. @default true |
+| `expanded` | no | `Record<string, boolean>` | The open rows, keyed by row id. Controlled: rendered as given, even several under<br>`multiple: false`. Supply `getRowId` when `data` can reorder or page, or an open panel<br>follows a position rather than a record. |
+| `defaultExpanded` | no | `Record<string, boolean>` | The rows open at first, keyed by row id. |
+| `onExpandedChange` | no | `(expanded: Record<string, boolean>) => void` |  |
+
+### `DataTableExpandedRowContext`
+
+Kind: interface.
+
+What an open row's `render` is handed beside the row's data.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `detail` | yes | `TDetail` | What `onLoad` resolved to. `undefined` when there is no `onLoad`. |
+| `refresh` | yes | `() => void` | Loads again, skipping the cache. Does nothing without `onLoad`. |
+| `collapse` | yes | `() => void` | Closes this row's panel — after a save inside it, say. |
+
 ### `DataTableHeader`
 
 Kind: callable.
@@ -302,7 +333,7 @@ The header rows — an optional band of column groups, then the columns. Sorting
 doing the work; this only translates the column's state into it.
 
 ```text
-({ table, stickyHeader, headerClassName, cellClassName, stickyFirstColumn, hasSelectionColumn, columnGroups, headerTransparent, }: DataTableHeaderProps<TData>) => import("react").JSX.Element
+({ table, stickyHeader, headerClassName, cellClassName, stickyFirstColumn, hasSelectionColumn, hasExpandColumn, columnGroups, headerTransparent, }: DataTableHeaderProps<TData>) => import("react").JSX.Element
 ```
 
 ### `DataTableHeaderProps`
@@ -317,6 +348,7 @@ Kind: interface.
 | `cellClassName` | no | `ClassNameFor<TData>` |  |
 | `stickyFirstColumn` | no | `boolean` |  |
 | `hasSelectionColumn` | no | `boolean` | Whether column 0 is the selection checkbox, so the pinned pair covers the identity column too. |
+| `hasExpandColumn` | no | `boolean` | Whether the expand toggle column leads the row (after any checkbox), for the pinned group. |
 | `columnGroups` | no | `ColumnGroup[]` |  |
 | `headerTransparent` | no | `boolean` |  |
 
@@ -378,6 +410,7 @@ Kind: interface.
 | `totalRowCount` | no | `number` | The result-count line beside the pager. |
 | `pageSize` | no | `number` |  |
 | `onRowClick` | no | `RowClickHandler<TData>` |  |
+| `expandedRow` | no | `DataTableExpandedRow<TData, TDetail>` | Turns on expandable rows: a toggle column at the row's start AND the panel it opens,<br>with the state behind them. Without it the table has neither. |
 | `onRowSelectionChange` | no | `RowSelectionHandler` |  |
 | `onSortingChange` | no | `SortingHandler` |  |
 | `onColumnVisibilityChange` | no | `ColumnVisibilityHandler` |  |
@@ -409,7 +442,8 @@ Kind: interface.
 
 Kind: type.
 
-Density of the whole table: row spacing only, not type size.
+Row spacing for the whole table, not type size. Unset, a compact provider density picks
+`sm`.
 
 ```text
 ComponentScale
@@ -434,6 +468,7 @@ DataTable copy, nested per surface (toolbar, header, body, pager, selection bar)
 | `pagination` | yes | `{ label: string; previous: string; next: string; page: (page: number) => string; morePages: string; summary: (from: number, to: number, total: number) => string; }` |  |
 | `selection` | yes | `{ summary: (selected: number, total: number) => string; row: (index: number) => string; selectAll: string; clear: string; }` |  |
 | `accessibility` | yes | `{ scrollRegion: string; fullscreenRegion: string; }` |  |
+| `expansion` | yes | `{ column: string; show: (index: number) => string; hide: (index: number) => string; loading: string; error: string; retry: string; empty: string; }` | Expandable rows: the toggle, and the panel's loading, error and empty states. |
 
 ### `DataTableStringsOverride`
 
@@ -641,11 +676,11 @@ string | number | Date | null | undefined
 
 Kind: callable.
 
-Which cells stay put when the table scrolls sideways. With selection on, the pinned group
-is the checkbox and the identity column after it, so a row never loses its name.
+Which cells stay put when the table scrolls sideways: the leading checkbox and expand toggle,
+when there are any, and the identity column after them, so a row never loses its name.
 
 ```text
-(columnId: string, row: LegacyRow<TData> | null, cellClassName: ClassNameFor<TData> | undefined, stickyFirstColumn: boolean, cellIndex: number, hasSelectionColumn?: boolean) => string
+(columnId: string, row: LegacyRow<TData> | null, cellClassName: ClassNameFor<TData> | undefined, stickyFirstColumn: boolean, cellIndex: number, hasSelectionColumn?: boolean, hasExpandColumn?: boolean) => string
 ```
 
 ### `ResourceCell`
@@ -907,7 +942,7 @@ export default function Table() {
 					},
 				]}
 				bulkActions={({ selectedRowCount }) => (
-					<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => setNote(`archive ${selectedRowCount}`)}>
+					<Button type="button" tone="neutral" appearance="outline" onClick={() => setNote(`archive ${selectedRowCount}`)}>
 						Archive selected
 					</Button>
 				)}
@@ -1008,7 +1043,7 @@ export default function TableSelection() {
 						<Button
 							type="button"
 							tone="neutral"
-							buttonStyle="outline"
+							appearance="outline"
 							onClick={() => setNote(`archive ${selectedRowCount}`)}
 						>
 							Archive selected
@@ -1022,6 +1057,121 @@ export default function TableSelection() {
 }
 ```
 
+### Expandable rows
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { MetadataList } from "themelia-ui/base/display"
+import { DataTable } from "themelia-ui/features/table"
+import { Money } from "themelia-ui/primitives"
+
+import { tableColumns } from "./_shared"
+import { BOOKINGS } from "./data"
+
+/* Everything the panel shows is already on the row, so `render` is the whole configuration. */
+export default function TableExpandable() {
+	return (
+		<DataTable
+			columns={tableColumns}
+			data={BOOKINGS.slice(0, 4)}
+			getRowId={(row) => row.id}
+			expandedRow={{
+				defaultExpanded: { b1: true },
+				render: (booking) => (
+					<MetadataList
+						layout="grid"
+						columns={4}
+						items={[
+							{ label: "Reference", value: booking.reference },
+							{ label: "Guests", value: String(booking.guests) },
+							{ label: "Total", value: <Money amount={booking.total} currency="EUR" /> },
+							{ label: "Contact", value: booking.customerEmail },
+						]}
+					/>
+				),
+			}}
+		/>
+	)
+}
+```
+
+### Details on demand
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { DataTable } from "themelia-ui/features/table"
+
+import { tableColumns } from "./_shared"
+import { BOOKINGS, type Booking } from "./data"
+
+interface BookingDetail {
+	event: string
+	deposit: string
+	arrival: string
+	notes: string
+}
+
+const DETAILS: Record<string, BookingDetail> = {
+	b1: { event: "Autumn gala", deposit: "€2,400 paid", arrival: "17:00, main entrance", notes: "Needs step-free access to the terrace." },
+	b2: { event: "Book launch", deposit: "Awaiting payment", arrival: "18:30, side door", notes: "A signing table by the window." },
+	b3: { event: "Wedding reception", deposit: "€5,000 paid", arrival: "14:00, river gate", notes: "The band loads in through the courtyard." },
+	b5: { event: "Team offsite", deposit: "€420 paid", arrival: "09:00, main entrance", notes: "A projector and two flip charts." },
+	b6: { event: "Charity dinner", deposit: "Awaiting payment", arrival: "19:00, main entrance", notes: "Auction tables along the east wall." },
+}
+
+const attempts = new Map<string, number>()
+
+/** A stand-in API: some latency, and The Old Granary's first load fails, so Retry has something to recover. */
+function fetchBookingDetail(booking: Booking, signal: AbortSignal): Promise<BookingDetail | null> {
+	return new Promise((resolve, reject) => {
+		const timer = window.setTimeout(() => {
+			const attempt = (attempts.get(booking.id) ?? 0) + 1
+			attempts.set(booking.id, attempt)
+			if (booking.id === "b2" && attempt === 1) reject(new Error("The booking service timed out."))
+			else resolve(DETAILS[booking.id] ?? null)
+		}, 700)
+		// Closing the row aborts: the request stops, and nothing is written after it.
+		signal.addEventListener("abort", () => {
+			window.clearTimeout(timer)
+			reject(new DOMException("Aborted", "AbortError"))
+		})
+	})
+}
+
+export default function TableExpandableAsync() {
+	return (
+		<DataTable
+			columns={tableColumns}
+			data={BOOKINGS}
+			getRowId={(row) => row.id}
+			enableRowSelection
+			stickyFirstColumn
+			expandedRow={{
+				onLoad: (booking, { signal }) => fetchBookingDetail(booking, signal),
+				render: (_booking, { detail }) => (
+					<Stack gap="sm">
+						<MetadataList
+							layout="grid"
+							columns={3}
+							items={[
+								{ label: "Event", value: detail.event },
+								{ label: "Deposit", value: detail.deposit },
+								{ label: "Arrival", value: detail.arrival },
+							]}
+						/>
+						<Text size="sm" type="secondary">{detail.notes}</Text>
+					</Stack>
+				),
+				// A cancelled booking has nothing left to show.
+				canExpand: (booking) => booking.status !== "cancelled",
+				multiple: false,
+			}}
+		/>
+	)
+}
+```
+
 ### Nothing to show
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -1038,7 +1188,7 @@ export default function TableEmpty() {
 			columns={tableColumns.slice(0, 3)}
 			data={[]}
 			emptyStateMessage="No bookings match these filters."
-			emptyStateAction={<Button type="button" tone="neutral" buttonStyle="outline">Clear filters</Button>}
+			emptyStateAction={<Button type="button" tone="neutral" appearance="outline">Clear filters</Button>}
 		/>
 	)
 }

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

@@ -15,7 +15,6 @@ Users change theme, density or scale at runtime and the result must persist.
 
 ```tsx fragment — import-only example
 import { ThemeScope } from "themelia-ui/features/theme-tweaker"
-import "themelia-ui/features/theme-tweaker.css"
 ```
 
 ## Composition
@@ -31,6 +30,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+How many variables the theme changes; a colour edited in both modes counts once.
+
 ```text
 (theme: ThemeDefinition) => number
 ```
@@ -39,8 +40,7 @@ Kind: callable.
 
 Kind: callable.
 
-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).
+The selector that scopes a theme to one subtree instead of the document.
 
 ```text
 (scopeSelector: string) => ThemeSelectors
@@ -119,8 +119,8 @@ UIConfigSettingsStrings
 
 Kind: callable.
 
-The whole shadow ladder from one intensity: the default theme's geometry and
-`--shadow-ink`, with every layer's ink scaled so 0.8 reproduces it exactly.
+The two shadows from one intensity: the default theme's geometry, with every layer's ink
+scaled so 0.8 reproduces it exactly.
 
 ```text
 ({ intensity }: ThemeElevationRecipe) => ThemeOverrides
@@ -164,7 +164,8 @@ Kind: callable.
 
 Kind: callable.
 
-Shared first, then the mode's, so a mode-scoped edit wins.
+The values the theme gives in one mode: shared first, then that mode's colour halves. For
+showing a value; the element's `color-scheme` is what picks the half on the page.
 
 ```text
 (theme: ThemeDefinition, mode?: ThemeMode) => ThemeOverrides
@@ -240,6 +241,18 @@ Kind: interface.
 | `providerConfig` | yes | `UIConfig` |  |
 | `providerConfigText` | yes | `string` | TypeScript source exporting `uiConfig`. |
 
+### `themeFromConfig`
+
+Kind: callable.
+
+A provider theme, such as one of `themes` from `themelia-ui/theming`, as a definition the
+tweaker can edit and export: each `light-dark()` colour split into its two halves, a single
+colour kept for both modes, the radii and extra variables shared.
+
+```text
+(config: ThemeConfig, mode?: ThemeMode) => ThemeDefinition
+```
+
 ### `ThemeMode`
 
 Kind: type.
@@ -294,13 +307,12 @@ Extends: `Omit<HTMLAttributes<HTMLDivElement>, "children">`.
 
 Kind: interface.
 
+Where a serialised theme is declared. One selector: a colour carries both modes in its
+`light-dark()` value, and the element's `color-scheme` picks the half.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `shared` | yes | `string` | Receives the mode-independent variables. |
-| `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`. |
+| `shared` | yes | `string` | `:root` for the whole application, or a scope's own selector. |
 
 ### `ThemeStyle`
 
@@ -316,8 +328,11 @@ CSSProperties & Partial<Record<ThemeVariableName, string>>
 
 Kind: callable.
 
+The theme as an inline style: shared values and each colour's `light-dark()` pair. The
+element's `color-scheme` (set by `.light`, `.dark` or `data-theme`) picks the half.
+
 ```text
-(theme: ThemeDefinition, mode?: ThemeMode) => ThemeStyle
+(theme: ThemeDefinition) => ThemeStyle
 ```
 
 ### `ThemeTweaker`
@@ -432,7 +447,7 @@ A slider and a numeric box, for a variable with real bounds.
 Kind: type.
 
 ```text
-"surfaces-content" | "brand-actions" | "charts" | "sidebar" | "semantic-feedback" | "inverse-surfaces" | "font-families" | "type-scale" | "radius" | "elevation" | "global-scales" | "actions-controls" | "rows-surfaces" | "media" | "application-shell" | "content-widths" | "adaptive-layout"
+"surfaces-content" | "brand-actions" | "charts" | "sidebar" | "semantic-feedback" | "tints" | "font-families" | "type-scale" | "radius" | "elevation" | "spacing" | "controls" | "motion" | "application-shell"
 ```
 
 ### `ThemeTweakerStrings`
@@ -500,7 +515,7 @@ Kind: interface.
 | `providerSettings` | yes | `UIConfigSettingsStrings` |  |
 | `groups` | yes | `Record<"colors" \| "states" \| "typography" \| "shape" \| "structure" \| "defaults", string>` |  |
 | `groupDescriptions` | yes | `Record<"colors" \| "states" \| "typography" \| "shape" \| "structure" \| "defaults", string>` |  |
-| `sections` | yes | `Record<"surfaces-content" \| "brand-actions" \| "charts" \| "sidebar" \| "semantic-feedback" \| "inverse-surfaces" \| "font-families" \| "type-scale" \| "radius" \| "elevation" \| "global-scales" \| "actions-controls" \| "rows-surfaces" \| "media" \| "application-shell" \| "content-widths" \| "adaptive-layout", string>` |  |
+| `sections` | yes | `Record<"surfaces-content" \| "brand-actions" \| "charts" \| "sidebar" \| "semantic-feedback" \| "tints" \| "font-families" \| "type-scale" \| "radius" \| "elevation" \| "spacing" \| "controls" \| "motion" \| "application-shell", string>` |  |
 
 ### `ThemeTweakerTarget`
 
@@ -602,7 +617,7 @@ const SQUARE_CORNERS = createTheme({ shared: { "--radius": "0.25rem", "--radius-
 
 export default function IsolatedThemeScope() {
 	return (
-		<Grid gap="lg">
+		<Grid>
 			<Card
 				title="App theme"
 				description="The corners every other region uses."

package/docs/generated/components/forms.md

@@ -147,14 +147,14 @@ export default function FormBindingState() {
 	)
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<BoundInput name="email" label="Email" control={control} type="email" />
 			<BoundInput name="workspace" label="Workspace" control={control} />
 			<Stack direction="horizontal" gap="sm" align="center">
 				<Button onClick={() => setSubmitted(JSON.stringify(control.values))}>
 					Submit
 				</Button>
-				<Button buttonStyle="outline" onClick={() => control.reset()}>
+				<Button appearance="outline" onClick={() => control.reset()}>
 					Reset
 				</Button>
 			</Stack>