themelia-ui 2.0.1 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/table.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.
@@ -39,6 +39,9 @@ TableStrings
 
 Kind: callable.
 
+The table, inside its own scroll container. The container becomes a tab stop only while it
+scrolls, so a wide table can be scrolled from the keyboard.
+
 ```text
 ({ className, containerClassName, strings, stickyHeader, ...props }: TableProps) => import("react").JSX.Element
 ```
@@ -65,6 +68,9 @@ Kind: callable.
 
 Kind: callable.
 
+Names the table for assistive technology, and the scroll container with it. Rendered
+below the table.
+
 ```text
 ({ className, children, id, ...props }: ComponentProps<"caption">) => import("react").JSX.Element
 ```
@@ -73,6 +79,8 @@ Kind: callable.
 
 Kind: callable.
 
+A cell. A plain string is wrapped in `Text`; a node is left exactly as passed.
+
 ```text
 ({ className, children, align, wrap, ...props }: TableCellProps) => import("react").JSX.Element
 ```
@@ -85,14 +93,15 @@ Extends: `Omit<ComponentProps<"td">, "align">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `align` | no | `TableAlign` |  |
-| `wrap` | no | `boolean` | Allows the cell to wrap. Cells are nowrap by default so columns stay readable. |
+| `align` | no | `TableAlign` | Column alignment. Numeric columns belong at the end. |
+| `wrap` | no | `boolean` | Lets the cell wrap. Cells are nowrap by default so columns stay aligned — a column that<br>holds prose opts out here rather than the whole table losing its alignment. |
 
 ### `TableEmpty`
 
 Kind: callable.
 
-The "no rows" row, spanning every column.
+The "no rows" row: it spans every column and states that there are none. A table with a
+header and no body reads as broken; this is what says it is empty on purpose.
 
 ```text
 ({ className, colSpan, children, ...props }: TableEmptyProps) => import("react").JSX.Element
@@ -121,6 +130,8 @@ Kind: callable.
 
 Kind: callable.
 
+A column's head cell, and with `sortable` its sort control.
+
 ```text
 ({ className, children, align, wrap, sortable, sortDirection, onSort, ...props }: TableHeadProps) => import("react").JSX.Element
 ```
@@ -141,11 +152,11 @@ Extends: `Omit<ComponentProps<"th">, "align">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `align` | no | `TableAlign` |  |
-| `wrap` | no | `boolean` |  |
-| `sortable` | no | `boolean` | Renders the label as a sort control. Pair with `sortDirection` and `onSort`. |
+| `align` | no | `TableAlign` | Column alignment. Numeric columns belong at the end. |
+| `wrap` | no | `boolean` | Lets the head cell wrap. Cells are nowrap by default so columns stay aligned. |
+| `sortable` | no | `boolean` | Renders the label as a sort control and puts `aria-sort` on the `<th>`. Pair with<br>`sortDirection` and `onSort`. |
 | `sortDirection` | no | `TableSortDirection` | This column's current direction, or `null` when another column is the sort. |
-| `onSort` | no | `() => void` |  |
+| `onSort` | no | `() => void` | Fires on activation. The table does not sort — the caller owns the data. |
 
 ### `TableProps`
 
@@ -163,6 +174,9 @@ Extends: `ComponentProps<"table">`.
 
 Kind: callable.
 
+A row: a plain `<tr>`. Mark a selected row with `data-state="selected"` — a data
+attribute, not a prop, because rows are plain elements.
+
 ```text
 ({ className, ...props }: ComponentProps<"tr">) => import("react").JSX.Element
 ```
@@ -190,58 +204,133 @@ Kind: interface.
 
 Preview route: Table — `/table`
 
-### Table
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Table>
-  <TableHeader>
-    <TableRow><TableHead>Invoice</TableHead>…</TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>INV-4417</TableCell>
-      <TableCell align="end"><Money amount={1299.5} /></TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-```
-
-### Selection
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TableRow data-state={isSelected ? "selected" : undefined}>
-  <TableCell><Checkbox … /></TableCell>
-  …
-</TableRow>
-```
-
-### Overflow
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Scope vars={{ "--density-scale": 0.85 }}>
-  <Table>…</Table>
-</Scope>
-```
-
 ### Sortable columns
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TableHead
-  sortable
-  sortDirection={sort.key === "amount" ? sort.direction : null}
-  onSort={() => toggleSort("amount")}
-  align="end"
->
-  Amount
-</TableHead>
+import { useState } from "react"
+
+import {
+	Table, TableBody, TableCell, TableHead, TableHeader, TableRow, type TableSortDirection,
+} from "themelia-ui/base/table"
+import { Money } from "themelia-ui/primitives"
+
+import { INVOICES } from "./data"
+
+/**
+ * Sorting is the CALLER's job — the table renders the order it is given.
+ *
+ * A table that sorted its own rows would have to own them, and then it cannot be driven by
+ * a server that paginates, or by a filter that lives above it.
+ */
+function SortableInvoiceTable() {
+	const [sort, setSort] = useState<{ key: "id" | "client" | "amount"; direction: Exclude<TableSortDirection, null> }>({
+		key: "amount",
+		direction: "descending",
+	})
+
+	const toggleSort = (key: "id" | "client" | "amount") =>
+		setSort((current) =>
+			current.key === key
+				? { key, direction: current.direction === "ascending" ? "descending" : "ascending" }
+				: { key, direction: "ascending" },
+		)
+
+	const rows = [...INVOICES].sort((a, b) => {
+		const left = a[sort.key]
+		const right = b[sort.key]
+		const order = typeof left === "number" && typeof right === "number"
+			? left - right
+			: String(left).localeCompare(String(right))
+		return sort.direction === "ascending" ? order : -order
+	})
+
+	const head = (key: "id" | "client" | "amount", label: string, align?: "end") => (
+		<TableHead
+			sortable
+			align={align}
+			sortDirection={sort.key === key ? sort.direction : null}
+			onSort={() => toggleSort(key)}
+		>
+			{label}
+		</TableHead>
+	)
+
+	return (
+		<Table>
+			<TableHeader>
+				<TableRow>
+					{head("id", "Invoice")}
+					{head("client", "Client")}
+					{head("amount", "Amount", "end")}
+				</TableRow>
+			</TableHeader>
+			<TableBody>
+				{rows.map((invoice) => (
+					<TableRow key={invoice.id}>
+						<TableCell>{invoice.id}</TableCell>
+						<TableCell>{invoice.client}</TableCell>
+						<TableCell align="end"><Money amount={invoice.amount} /></TableCell>
+					</TableRow>
+				))}
+			</TableBody>
+		</Table>
+	)
+}
+
+export default function TableSorting() {
+	return (
+		<SortableInvoiceTable />
+	)
+}
 ```
 
 ### Empty and sticky
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TableBody>
-  {rows.length === 0 ? <TableEmpty colSpan={4} /> : rows.map(…)}
-</TableBody>
-
-<Table stickyHeader containerClassName="…max-height…">
+import { Stack } from "themelia-ui/base/structure"
+import {
+	Table, TableBody, TableCell, TableEmpty, TableHead, TableHeader, TableRow,
+} from "themelia-ui/base/table"
+import { Money } from "themelia-ui/primitives"
+
+import { INVOICES } from "./data"
+import styles from "./table-empty.module.css"
+
+export default function TableEmptyExample() {
+	return (
+		<Stack gap="xl" style={{ width: "100%" }}>
+			<Table>
+				<TableHeader>
+					<TableRow>
+						<TableHead>Invoice</TableHead>
+						<TableHead>Client</TableHead>
+						<TableHead align="end">Amount</TableHead>
+					</TableRow>
+				</TableHeader>
+				<TableBody>
+					<TableEmpty colSpan={3}>No invoices match this filter.</TableEmpty>
+				</TableBody>
+			</Table>
+
+			<Table stickyHeader containerClassName={styles.bounded}>
+				<TableHeader>
+					<TableRow>
+						<TableHead>Invoice</TableHead>
+						<TableHead>Client</TableHead>
+						<TableHead align="end">Amount</TableHead>
+					</TableRow>
+				</TableHeader>
+				<TableBody>
+					{[...INVOICES, ...INVOICES, ...INVOICES].map((invoice, index) => (
+						<TableRow key={index}>
+							<TableCell>{invoice.id}</TableCell>
+							<TableCell>{invoice.client}</TableCell>
+							<TableCell align="end"><Money amount={invoice.amount} /></TableCell>
+						</TableRow>
+					))}
+				</TableBody>
+			</Table>
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--text-inputs.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/text-inputs.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.
@@ -65,6 +65,10 @@ React.ComponentType<{ className?: string; }> | React.ReactNode
 
 Kind: callable.
 
+The field surface on its own, for composing a control the kit does not ship. The shell
+wears the surface and the control inside gives up its own, so an icon or a trailing
+action reads as part of one field rather than a box inside a box.
+
 ```text
 ({ start, end, className, children, id, "aria-labelledby": ariaLabelledBy, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy, "aria-required": ariaRequired, ...props }: FieldShellProps) => React.JSX.Element
 ```
@@ -121,17 +125,18 @@ Extends: `Omit<React.ComponentProps<"input">, "size">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `startIcon` | no | `FieldIcon` | Glyph before the value. |
-| `endIcon` | no | `FieldIcon` | Glyph after the value. |
-| `startAddon` | no | `React.ReactNode` | Short text before the value — a currency symbol, a protocol, an @ . |
-| `endAddon` | no | `React.ReactNode` | Short text after the value — a unit, a domain. |
+| `startIcon` | no | `FieldIcon` | Glyph before the value, in its own lane so the text never runs under it. |
+| `endIcon` | no | `FieldIcon` | Glyph after the value, in its own lane so the text never runs under it. |
+| `startAddon` | no | `React.ReactNode` | Short text attached before the value, outside the text itself — a currency symbol, a<br>protocol, an at sign. |
+| `endAddon` | no | `React.ReactNode` | Short text attached after the value, outside the text itself — a unit, a domain. |
 | `showCharacterCount` | no | `boolean` | Shows "12 / 80" in the trailing lane. Requires `maxLength`. |
-| `clearable` | no | `boolean` | Shows a clear control once the field has a value. |
+| `maxLength` | no | `number` | Character cap, and the limit the count counts against. Input past it is refused. |
+| `clearable` | no | `boolean` | Shows a clear control once the field has a value. Clearing goes through the native<br>value setter, so React's value tracker stays in sync. |
 | `onClear` | no | `() => void` | Called after the clear control empties the field. |
-| `loading` | no | `boolean` | Replaces the trailing affordance with a spinner. |
-| `invalid` | no | `boolean` | Applies the invalid treatment. The message stays with FormField. |
-| `returnValueWithAddons` | no | `boolean` | Includes string addons in the value reported by `onChange`. Off by default (addons are presentation). |
-| `strings` | no | `StringsProp<InputStrings>` |  |
+| `loading` | no | `boolean` | Replaces the trailing affordance with a spinner, which outranks every other trailing<br>affordance. |
+| `invalid` | no | `boolean` | Applies the invalid treatment. Pair it with FormField's error for the message, so the<br>border and the announcement cannot disagree. |
+| `returnValueWithAddons` | no | `boolean` | Includes string addons in the value reported by `onChange`. Off, because an addon is<br>presentation: a caller that stores "$" and the number has to strip it again on the way<br>out. |
+| `strings` | no | `StringsProp<InputStrings>` | Overrides this field's own copy — the clear label, the character-count format. |
 
 ### `InputStrings`
 
@@ -176,7 +181,7 @@ Extends: `Omit<InputProps, "type">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `strings` | no | `Partial<PasswordInputStrings>` | Overrides this field's own copy — the reveal control's name in each state. |
+| `strings` | no | `Partial<PasswordInputStrings>` | Overrides this field's own copy — the reveal control's name in each state, which is its<br>state for a screen reader — and Input's own strings. |
 
 ### `PasswordInputStrings`
 
@@ -207,7 +212,9 @@ Extends: `Omit<InputProps, "type" | "startIcon">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `onClear` | no | `() => void` | Called when the reader clears the field. The clear control is always offered. |
+| `onClear` | no | `() => void` | Called when the reader clears the field — a notification only, because Input does the<br>clearing itself. The clear control is always present once there is a value. |
+| `strings` | no | `StringsProp<InputStrings>` | Overrides this field's own copy. It is Input's strings object with one default<br>narrowed: a search field's only copy is one word of Input's. @default { clear: "Clear search" } |
+| `placeholder` | no | `string` | Say what is being searched, not just "Search". |
 
 ### `SlugField`
 
@@ -225,9 +232,9 @@ Extends: `Omit<InputProps, "value" | "defaultValue" | "onChange" | "readOnly" |
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | yes | `string \| number \| null \| undefined` | The source value. Controlled — the slug is derived, never held. |
-| `transform` | no | `(value: string \| number \| null \| undefined) => string` | Replaces the built-in derivation entirely. |
-| `prefix` | no | `React.ReactNode` | Rendered before the slug, inside the field — a domain or a path prefix. |
+| `value` | yes | `string \| number \| null \| undefined` | The source text; the field shows its slugified form. Controlled — the slug is derived,<br>never held. |
+| `transform` | no | `(value: string \| number \| null \| undefined) => string` | Replaces the built-in derivation entirely. The default lower-cases, strips accents,<br>keeps letters and numbers in any script, and collapses every other run to a single<br>separator. |
+| `prefix` | no | `React.ReactNode` | Rendered before the slug, inside the field — a domain or a path prefix. Not part of the<br>value. |
 
 ### `slugify`
 
@@ -247,7 +254,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `separator` | no | `string` | Character joining words. |
-| `lowercase` | no | `boolean` |  |
+| `lowercase` | no | `boolean` | Lower-cases the slug. |
 | `trim` | no | `boolean` | Strips leading and trailing separators. |
 
 ### `Textarea`
@@ -269,12 +276,13 @@ Extends: `Omit<React.ComponentProps<"textarea">, "onChange">`.
 | `strings` | no | `StringsProp<InputStrings>` | Overrides the character-count and clear copy. |
 | `maxLength` | no | `number` | Character cap, also the denominator of the count. |
 | `showCharacterCount` | no | `boolean` | Shows the current and maximum character count. |
-| `clearable` | no | `boolean` | Shows an inline clear action once the field has a value. |
-| `onClear` | no | `() => void` |  |
+| `clearable` | no | `boolean` | Shows a clear control in the trailing lane once the field has a value. `strings.clear`<br>is its accessible name. |
+| `onClear` | no | `() => void` | Called after the clear control empties the field. |
 | `loading` | no | `boolean` | Replaces the trailing affordance with a loading indicator. |
-| `invalid` | no | `boolean` | Applies the invalid styling. Validation copy stays with FormField. |
-| `minRows` | no | `number` | Smallest height, in rows. |
-| `maxRows` | no | `number` | Height at which the field stops growing and starts scrolling. |
+| `invalid` | no | `boolean` | Applies the invalid styling, the same as Input. Validation copy stays with FormField. |
+| `rows` | no | `number` | Visible lines. Without `minRows` it is the floor the field grows from; `maxRows` sets<br>where it stops growing and scrolls. |
+| `minRows` | no | `number` | The floor when the field grows with its content: its smallest height, in rows. |
+| `maxRows` | no | `number` | Height at which the field stops growing and starts scrolling. Without a ceiling a long<br>note pushes the submit button off the screen. |
 | `onChange` | no | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` |  |
 | `value` | no | `string` |  |
 | `defaultValue` | no | `string` |  |
@@ -283,8 +291,9 @@ Extends: `Omit<React.ComponentProps<"textarea">, "onChange">`.
 
 Kind: callable.
 
-Value bookkeeping shared by the text controls (Input, Textarea): controlled or not, a
-generated id, the character count and the limit — one branch, so fields agree.
+Value bookkeeping shared by Input and Textarea (SearchInput wraps Input): the controlled or
+uncontrolled value, a generated id, and the character count with its limit — one branch,
+so both fields behave the same under a form library.
 
 ```text
 ({ controlledValue, defaultValue, maxLength, showCharacterCount, providedId, idPrefix, }: UseFieldValueOptions) => UseFieldValueResult
@@ -322,43 +331,230 @@ Kind: interface.
 
 ## Preview recipes
 
-Preview route: Input — `/input`
+Preview route: Form field — `/form-field`
+
+### Scale
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Stack } from "themelia-ui/base/structure"
+import { Input, NativeSelect } from "themelia-ui/base/text-inputs"
+import { MonoValue } from "themelia-ui/primitives"
+import { Scope } from "themelia-ui/ui-provider"
+
+export default function FormsScale() {
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			{[1, 0.875, 1.125].map((scale) => (
+				<Scope key={scale} vars={{ "--density-scale": scale }}>
+					<Stack direction="horizontal" gap="md" align="center" justify="start">
+						{/* Widths on the wrappers: Input's style lands on the inner control, not its frame. */}
+						<MonoValue size="xs" style={{ width: "3.5rem", flexShrink: 0, fontSize: "0.75rem" }}>
+							{scale}
+						</MonoValue>
+						{/* Named even in a geometry demo: a placeholder is not a label. */}
+						<div style={{ width: "12rem", flexShrink: 0 }}>
+							<Input placeholder="Field" aria-label={`Example field at density ${scale}`} />
+						</div>
+						<div style={{ width: "9rem", flexShrink: 0 }}>
+							<NativeSelect defaultValue="a" aria-label={`Example select at density ${scale}`}>
+								<option value="a">Option</option>
+							</NativeSelect>
+						</div>
+					</Stack>
+				</Scope>
+			))}
+		</Stack>
+	)
+}
+```
+
+### One shared surface
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input, NativeSelect, Textarea } from "themelia-ui/base/text-inputs"
+
+
+export default function SharedSurface() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Input">
+				<Input placeholder="Northwind Traders" />
+			</FormField>
+			<FormField label="Native select">
+				<NativeSelect defaultValue="">
+					<option value="" disabled>
+						Select an option
+					</option>
+					<option value="a">First option</option>
+					<option value="b">Second option</option>
+				</NativeSelect>
+			</FormField>
+			<FormField label="Textarea">
+				<Textarea placeholder="Anything worth recording." />
+			</FormField>
+		</Stack>
+	)
+}
+```
 
 ### Optional iPhone zoom prevention
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ forms: { preventIPhoneZoom: true } }}>
-  <Input aria-label="Enabled on iPhones" />
-</UIProvider>
+import { Select } from "themelia-ui/base/choice-inputs"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input, NativeSelect, Textarea } from "themelia-ui/base/text-inputs"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+
+export default function IphoneInputZoom() {
+	return (
+		<UIProvider config={{ forms: { preventIPhoneZoom: true } }}>
+			<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+				<FormField label="Enabled on iPhones"><Input placeholder="16px minimum on iPhone" /></FormField>
+				<FormField label="iPhone textarea"><Textarea /></FormField>
+				<FormField label="iPhone native select"><NativeSelect><option>First option</option></NativeSelect></FormField>
+				<FormField label="Button select"><Select options={[{ value: "a", label: "First option" }]} defaultValue="a" /></FormField>
+				<UIProvider config={{ forms: { preventIPhoneZoom: false } }}>
+					<FormField label="Nested opt-out"><Input placeholder="Normal field typography" /></FormField>
+				</UIProvider>
+			</Stack>
+		</UIProvider>
+	)
+}
 ```
 
 ### States
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Input aria-invalid="true" />
-<Input disabled />
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input, NativeSelect } from "themelia-ui/base/text-inputs"
+
+
+export default function States() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Default" helperText="The supporting line.">
+				<Input placeholder="name@example.com" />
+			</FormField>
+			<FormField label="Invalid" error="Enter a valid email address.">
+				<Input defaultValue="not-an-email" aria-invalid="true" />
+			</FormField>
+			<FormField label="Disabled">
+				<Input placeholder="Not editable" disabled />
+			</FormField>
+			<FormField label="Disabled select">
+				<NativeSelect disabled defaultValue="a">
+					<option value="a">Not editable</option>
+				</NativeSelect>
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### Inline affordances
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FieldShell start={<SearchIcon />} end={<Button>Go</Button>}>
-  <Input />
-</FieldShell>
-
-<PasswordInput />
-<SearchInput value={q} onChange={…} onClear={…} />
+import { useState } from "react"
+
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { FieldShell, Input, PasswordInput, SearchInput } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function Affordances() {
+	const [search, setSearch] = useState("shipping")
+
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Search" helperText="Clear appears once there is a value.">
+				<SearchInput
+					value={search}
+					onChange={(event) => setSearch(event.target.value)}
+					onClear={() => setSearch("")}
+					placeholder="Search orders"
+				/>
+			</FormField>
+			<FormField label="Password" helperText="Revealing is its own control, never hover or focus.">
+				<PasswordInput defaultValue="hunter2" />
+			</FormField>
+			<FormField label="Password, invalid" error="Too short.">
+				<PasswordInput defaultValue="abc" invalid />
+			</FormField>
+			<FormField label="Weight" helperText="A trailing unit, outside the text.">
+				<FieldShell end={<Text tag="span" size="xs" type="secondary">kg</Text>}>
+					<Input type="number" defaultValue="12" />
+				</FieldShell>
+			</FormField>
+			<FormField label="Character count">
+				<Input showCharacterCount maxLength={40} defaultValue="Counted" />
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### SlugField
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<SlugField value={title} prefix="acme.com/" />
+import { useState } from "react"
+
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input, SlugField } from "themelia-ui/base/text-inputs"
+
+
+function SlugFieldDemo() {
+	const [title, setTitle] = useState("Northwind Traders — Q4 Report & Notes")
+
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Title">
+				<Input value={title} onChange={(event) => setTitle(event.target.value)} />
+			</FormField>
+			<FormField label="URL" helperText="Derived from the title. Accents fold, punctuation collapses.">
+				<SlugField value={title} prefix="acme.com/" />
+			</FormField>
+		</Stack>
+	)
+}
+
+export default function SlugFieldExample() {
+	return (
+		<SlugFieldDemo />
+	)
+}
 ```
 
 ### Textarea
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Textarea rows={4} placeholder="Notes" />
-<Textarea showCharacterCount maxLength={280} />
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Textarea } from "themelia-ui/base/text-inputs"
+
+
+export default function TextareaExample() {
+	return (
+		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Notes" helperText="Plain multi-line text.">
+				<Textarea rows={4} placeholder="Anything worth recording." />
+			</FormField>
+			<FormField label="Summary" helperText="With a limit and a count.">
+				<Textarea rows={3} showCharacterCount maxLength={280} defaultValue="Quarterly summary." />
+			</FormField>
+			<FormField label="Invalid" error="Required.">
+				<Textarea rows={2} invalid />
+			</FormField>
+			<FormField label="Disabled">
+				<Textarea rows={2} disabled defaultValue="Not editable." />
+			</FormField>
+		</Stack>
+	)
+}
 ```