themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/primitives.md

@@ -20,7 +20,7 @@ import "themelia-ui/primitives.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.
@@ -75,9 +75,9 @@ Extends: `Omit<ComponentPropsWithoutRef<"address">, "children" | "color">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `AddressParts \| null` | The address, as fields. Anything empty simply drops out. |
-| `format` | no | `"block" \| "inline"` | `block` is the envelope form across several lines; `inline` is one line for a cell. |
-| `countryCode` | no | `string \| null` | An ISO country code deciding the line order (`US`, `GB`, `DE`). Read from<br>`value.country` when that is a code; never inferred from the reader's locale. |
+| `value` | no | `AddressParts \| null` | The address, as fields — line1, line2, city, region, postalCode, country. Anything<br>empty simply drops out. |
+| `format` | no | `"block" \| "inline"` | `block` is the envelope form: an `<address>` element with a line per row. `inline` is<br>one line, in a span, for a cell or a summary. |
+| `countryCode` | no | `string \| null` | An ISO country code deciding the line order (`US`, `GB`, `DE`). Read from<br>`value.country` when that is a code; never inferred from the reader's locale — the<br>locale is a language and the address is a place. |
 | `order` | no | `AddressOrder` | Overrides the ordering outright, for a country the kit does not know. |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
@@ -101,13 +101,13 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `latitude` | no | `number \| null` |  |
-| `longitude` | no | `number \| null` |  |
-| `format` | no | `"decimal" \| "dms"` | `decimal` is "48.85837, 2.29448"; `dms` is "48°51'30.1\"N 2°17'40.1\"E". |
-| `precision` | no | `number` | Decimal places in `decimal` form. Five is about a metre. |
-| `showHemisphere` | no | `boolean` | Adds hemisphere letters to the decimal form: "48.85837°N, 2.29448°E". Off by default<br>(a signed pair pastes into a map); `dms` always shows them. |
+| `latitude` | no | `number \| null` | Signed decimal degrees. Either one missing renders the empty label — half a coordinate<br>locates nothing. |
+| `longitude` | no | `number \| null` | Signed decimal degrees. Either one missing renders the empty label — half a coordinate<br>locates nothing. |
+| `format` | no | `"decimal" \| "dms"` | `decimal` is `48.85837, 2.29448`: what an API round-trips and what a reader pastes into<br>a map. `dms` is `48°51'30.1"N 2°17'40.1"E`, still what marine, aviation and survey<br>users read. |
+| `precision` | no | `number` | Decimal places in `decimal` form. Five is about a metre, three about a building. |
+| `showHemisphere` | no | `boolean` | Adds hemisphere letters (N/S/E/W) to the decimal form: "48.85837°N, 2.29448°E". Off by<br>default because a signed pair is the portable form, the one that pastes into a map.<br>`dms` always shows them — an unsigned DMS value is ambiguous. |
 | `locale` | no | `string` |  |
-| `strings` | no | `Partial<CoordinatesStrings>` |  |
+| `strings` | no | `Partial<CoordinatesStrings>` | The four hemisphere letters. |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
 | `align` | no | `ValueProps["align"]` |  |
@@ -130,6 +130,10 @@ Kind: interface.
 
 Kind: callable.
 
+A date in the scope's pattern. Also exported as `Date`, its natural name: `DatePrimitive`
+exists because `Date` collides with the global in a file that also constructs one, so
+import whichever reads better at the call site.
+
 ```text
 ({ value, pattern, ...props }: DateBaseProps) => import("react").JSX.Element
 ```
@@ -144,8 +148,8 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `DateInput` |  |
-| `pattern` | no | `string` | date-fns pattern. Falls back to the scope's `dateFormat`. |
+| `value` | no | `DateInput` | The moment to show: whatever the API returned — a Date, an ISO string or an epoch<br>number. Parsed once, here. |
+| `pattern` | no | `string` | A date-fns pattern, when the default is not what this column needs. `DatePrimitive`<br>falls back to the scope's `dates.format`, `Time` to its `dates.timeFormat`, and<br>`DateTime` to the two joined. |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
 | `align` | no | `ValueProps["align"]` |  |
@@ -165,6 +169,10 @@ Date | string | number | null | undefined
 
 Kind: callable.
 
+A date in the scope's pattern. Also exported as `Date`, its natural name: `DatePrimitive`
+exists because `Date` collides with the global in a file that also constructs one, so
+import whichever reads better at the call site.
+
 ```text
 ({ value, pattern, ...props }: DateBaseProps) => import("react").JSX.Element
 ```
@@ -185,14 +193,18 @@ Extends: `Omit<DateBaseProps, "value">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `start` | no | `DateInput` |  |
-| `end` | no | `DateInput` |  |
-| `separator` | no | `string` |  |
+| `start` | no | `DateInput` | Where the range begins. Either end may be absent — an open range is a real state, not<br>an error. |
+| `end` | no | `DateInput` | Where the range ends. Either end may be absent — an open range is a real state, not an<br>error. |
+| `pattern` | no | `string` | A date-fns pattern for both ends, when the collapsing is not wanted: only the default<br>drops a repeated month. @default "d MMM yyyy" |
+| `separator` | no | `string` | Between the two ends. An en dash by default. |
 
 ### `DateTime`
 
 Kind: callable.
 
+The same value as a date and a time. Three components rather than a granularity prop,
+because a column shows one of them and never switches.
+
 ```text
 ({ value, pattern, ...props }: DateBaseProps) => import("react").JSX.Element
 ```
@@ -261,11 +273,11 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `width` | no | `DimensionPart` |  |
-| `height` | no | `DimensionPart` |  |
-| `depth` | no | `DimensionPart` |  |
-| `unit` | no | `ReactNode` |  |
-| `separator` | no | `ReactNode` |  |
+| `width` | no | `DimensionPart` | The first part. The parts stay separate numbers until the render joins them. |
+| `height` | no | `DimensionPart` | The second part. |
+| `depth` | no | `DimensionPart` | The third part, optional — two values render as a plane. |
+| `unit` | no | `ReactNode` | Appended once, not per part. |
+| `separator` | no | `ReactNode` | Between the parts. A multiplication sign, not the letter x. |
 | `locale` | no | `string` |  |
 | `options` | no | `Intl.NumberFormatOptions` |  |
 | `emptyLabel` | no | `ReactNode` |  |
@@ -291,11 +303,11 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
+| `value` | no | `number \| null` | The length. Seconds unless `from` says otherwise. |
 | `from` | no | `DurationUnit` | The unit the incoming value is in. |
 | `locale` | no | `string` |  |
-| `maxParts` | no | `number` | How many units to show before truncating. |
-| `unitDisplay` | no | `DurationUnitDisplay` |  |
+| `maxParts` | no | `number` | How many units to show before truncating. "2 hours 14 minutes 3 seconds" is rarely<br>useful — the reader wants the magnitude, and the tail is noise. |
+| `unitDisplay` | no | `DurationUnitDisplay` | How each unit is written. |
 | `minimumFractionDigits` | no | `number` |  |
 | `maximumFractionDigits` | no | `number` |  |
 | `emptyLabel` | no | `ReactNode` |  |
@@ -339,10 +351,10 @@ Extends: `Omit<LinkProps, "href" | "children" | "ref">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `string \| null` |  |
-| `display` | no | `ReactNode` | Shown instead of the address — a person's name, for instance. |
-| `subject` | no | `string` |  |
-| `body` | no | `string` |  |
+| `value` | no | `string \| null` | The address. Becomes both the text and the `mailto:` href. |
+| `display` | no | `ReactNode` | Shown instead of the address — a person's name, for instance. The href is still the<br>address. |
+| `subject` | no | `string` | Prefills the message's subject. Encoded into the `mailto:`, not concatenated into it. |
+| `body` | no | `string` | Prefills the message's body. Encoded into the `mailto:`, not concatenated into it. |
 | `ref` | no | `Ref<HTMLAnchorElement>` |  |
 
 ### `EmptyValue`
@@ -399,13 +411,13 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
-| `from` | no | `FileSizeUnit` |  |
-| `base` | no | `FileSizeBase` | `binary` (default), `decimal`, or `iec`. See file-size.format.ts. |
+| `value` | no | `number \| null` | The size. Bytes unless `from` says otherwise. |
+| `from` | no | `FileSizeUnit` | The unit `value` is given in. Converted with the same base, so `from="megabytes"` means<br>2^20 under `binary` and 10^6 under `decimal`. |
+| `base` | no | `FileSizeBase` | Which base and which labels. `binary` divides by 1024 and labels it MB — the pairing<br>Windows and most file managers show, chosen so a size agrees with the machine it<br>describes rather than with SI. `decimal` is SI-correct and what Apple platforms and<br>storage vendors use. `iec` is strictly correct. The default does not move, so nothing<br>already shipped changes. @default "binary" |
 | `locale` | no | `string` |  |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
-| `align` | no | `ValueProps["align"]` |  |
+| `align` | no | `ValueProps["align"]` | For a size given a box of its own. A COLUMN of sizes is aligned by the column —<br>`<TableCell align="end">` — because the primitive is a span, and blockifying it to<br>align would break the text runs it also sits in. |
 | `weight` | no | `ValueProps["weight"]` |  |
 | `type` | no | `ValueProps["type"]` |  |
 | `ref` | no | `Ref<HTMLSpanElement>` |  |
@@ -432,8 +444,9 @@ The same address on one line, for a cell or a summary row.
 
 Kind: callable.
 
-Returns the address as lines, each already joined. Empty fields drop out, and a line
-left with nothing drops with them, so a missing `line2` never leaves a blank row.
+The same ordering outside React: the address as lines, each already joined. Empty fields
+drop out, and a line left with nothing drops with them, so a missing `line2` never leaves
+a blank row.
 
 ```text
 (parts: AddressParts, { countryCode, order, separator, locale }?: FormatAddressOptions) => string[]
@@ -454,8 +467,8 @@ Kind: interface.
 
 Kind: callable.
 
-Collapses a range to its distinct parts: same day renders once, and a range within one
-month drops the repeated month from the start date.
+The same collapsing outside React: a range reduced to its distinct parts. The same day
+renders once, and a range within one month drops the repeated month from the start date.
 
 ```text
 (start: DateInput, end: DateInput, { pattern, separator, locale }?: FormatDateRangeOptions) => string | undefined
@@ -475,6 +488,8 @@ Kind: interface.
 
 Kind: callable.
 
+The same joining outside React.
+
 ```text
 (width: DimensionPart, height: DimensionPart, { depth, unit, separator, locale, options }?: FormatDimensionsOptions) => string | undefined
 ```
@@ -508,6 +523,8 @@ Kind: interface.
 
 Kind: callable.
 
+The same formatting outside React.
+
 ```text
 (value: number, { from, base, locale }?: FileSizeFormatOptions) => string
 ```
@@ -516,7 +533,8 @@ Kind: callable.
 
 Kind: callable.
 
-Derive short, Unicode-aware initials from a person or resource name.
+The same derivation outside React: short, Unicode-aware initials from a person or
+resource name.
 
 `first-last` is the identity default (`Mary Jane Smith` → `MS`). Use
 `first-words` for admin surfaces that intentionally use the first
@@ -531,6 +549,8 @@ the first N letters (`OpenAI` → `OP`).
 
 Kind: callable.
 
+The same normalisation outside React — for a sort key, an export, a document title.
+
 ```text
 (value: string, { force }?: NameFormatOptions) => string
 ```
@@ -571,8 +591,8 @@ Extends: `Omit<ValueProps, "children">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `value` | no | `string \| null` | Person, organisation, or resource name to derive initials from. |
-| `strategy` | no | `InitialsStrategy` | First + last word by default; `first-words` keeps the leading N words instead. |
-| `maxCharacters` | no | `InitialsMaxCharacters` |  |
+| `strategy` | no | `InitialsStrategy` | First + last word by default; `first-words` keeps the leading N words instead. @default "first-last" |
+| `maxCharacters` | no | `InitialsMaxCharacters` | How many characters are kept. @default 2 |
 | `locale` | no | `string` |  |
 | `fallback` | no | `string` | Returned when no usable letter or number exists. |
 | `ref` | no | `Ref<HTMLSpanElement>` |  |
@@ -601,12 +621,12 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `items` | no | `readonly string[] \| null` |  |
-| `join` | no | `"and" \| "or" \| "none"` | `and` is "A, B and C"; `or` is "A, B or C"; `none` is "A, B, C", for lists that are<br>not prose. (Not `type`, which primitives use for the text tone.) |
-| `joinStyle` | no | `"long" \| "short" \| "narrow"` | `long` is "and", `short` is "&" where the locale has one, `narrow` drops it.<br>(Not `style`, the DOM attribute.) |
+| `items` | no | `readonly string[] \| null` | Strings, not nodes: `Intl.ListFormat` formats text, and falling back to a hand join for<br>nodes would quietly lose the locale rules. A row of badges is a `Stack` with a gap. |
+| `join` | no | `"and" \| "or" \| "none"` | `and` is "A, B and C"; `or` is "A, B or C"; `none` is "A, B, C", for lists that are<br>not prose, where a trailing "and" reads as a claim the data is not making. Not called<br>`type`: every other primitive spends that word on the text tone. |
+| `joinStyle` | no | `"long" \| "short" \| "narrow"` | `long` is "and", `short` is "&" where the locale has one, `narrow` drops it. Not called<br>`style`, which is the DOM attribute and would have shadowed it. |
 | `max` | no | `number` | Shows at most this many, then a count of the rest inside the list, so the<br>conjunction still lands correctly: "Alice, Bob and 3 more". |
 | `locale` | no | `string` |  |
-| `strings` | no | `Partial<InlineListStrings>` |  |
+| `strings` | no | `Partial<InlineListStrings>` | Overrides the list's own copy: `more(count)`, which names the truncated remainder. |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
 | `align` | no | `ValueProps["align"]` |  |
@@ -626,6 +646,9 @@ Kind: interface.
 
 Kind: callable.
 
+The plain anchor the three contact primitives are built on: the kit's `TextLink`, or the
+empty mark when there is nothing to link.
+
 ```text
 ({ children, emptyLabel, className, ref, ...props }: LinkProps) => import("react").JSX.Element
 ```
@@ -658,7 +681,7 @@ Extends: `SharedProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
+| `value` | no | `number \| null` | The amount. |
 | `unit` | no | `string` | A CSS-style unit identifier — `kilogram`, `meter`, `liter`, `celsius`, `byte`.<br><br>Passed to `Intl.NumberFormat`, which owns both the abbreviation and where it goes:<br>English writes "2.5 kg" and French writes "2,5 kg", and neither is a string this<br>component should be assembling. |
 | `unitDisplay` | no | `"short" \| "narrow" \| "long"` | `short` is "2.5 kg", `narrow` is "2.5kg", `long` is "2.5 kilograms". |
 | `maximumFractionDigits` | no | `number` | Caps the decimals. The value is not rounded before formatting. |
@@ -679,17 +702,17 @@ Extends: `SpanProps`, `MoneyValue`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `locale` | no | `string` |  |
+| `locale` | no | `string` | Overrides the scope's locale for this value. |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
 | `align` | no | `ValueProps["align"]` |  |
 | `weight` | no | `ValueProps["weight"]` |  |
 | `type` | no | `ValueProps["type"]` |  |
-| `secondary` | no | `MoneyValue \| null` | A converted value shown beside the primary one. The scope's policy can hide it<br>(`displayMode="primary-only"`) but never invents one. |
-| `displayMode` | no | `MoneyDisplayMode` |  |
-| `layout` | no | `MoneyLayout` |  |
-| `secondaryEmphasis` | no | `MoneySecondaryEmphasis` |  |
-| `separator` | no | `ReactNode` | Between the two, inline. A middle dot; pass an arrow for a conversion. |
+| `secondary` | no | `MoneyValue \| null` | A converted value shown beside the primary one. Passing it is the request for the pair:<br>the scope's policy can narrow that (`displayMode="primary-only"`) but never widen it,<br>and never invents a value. |
+| `displayMode` | no | `MoneyDisplayMode` | Whether the pair shows. `dynamic` shows it only when the two codes actually differ. |
+| `layout` | no | `MoneyLayout` | Beside, or under. Falls back to the scope's `money.layout`. |
+| `secondaryEmphasis` | no | `MoneySecondaryEmphasis` | How loud the second value is against the first. |
+| `separator` | no | `ReactNode` | Between the two, inline. A middle dot; pass an arrow for a conversion. It is<br>`aria-hidden`: read aloud, the mark between two amounts is punctuation for the eye. |
 | `ref` | no | `Ref<HTMLSpanElement>` |  |
 
 ### `MoneyUnit`
@@ -708,17 +731,18 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `amount` | no | `number \| string \| null` | A number or decimal string. A single dot is decimal; grouped US/EU strings are also accepted. |
-| `currency` | no | `string` |  |
-| `unit` | no | `MoneyUnit` | Defaults to `major`. Use `minor` for APIs that store integer minor units. |
-| `minorUnitScale` | no | `number` | Minor units per major unit. Defaults to 100. |
-| `formatMode` | no | `MoneyFormatMode` | How this amount is written, overriding the scope's `formatMode`. |
+| `amount` | no | `number \| string \| null` | The amount, in a channel separate from its currency. A number or a decimal string: a<br>single dot is decimal, and a grouped US or EU string is parsed by POSITION — whichever<br>of , or . appears last is the decimal point — so a value that came back through a<br>European locale does not parse a thousand times too large. |
+| `currency` | no | `string` | The amount's ISO currency code, kept apart from the amount all the way to the render. |
+| `unit` | no | `MoneyUnit` | The unit the amount ARRIVES in. Use `minor` for APIs that store integer minor units. @default "major" |
+| `minorUnitScale` | no | `number` | Minor units per major unit, for a currency whose exponent is not two. @default 100 |
+| `formatMode` | no | `MoneyFormatMode` | How this amount is written. Falls back to the scope's `money.formatMode`, so<br>`UIProvider` defaults can change it. @default "with-symbol" |
 
 ### `MonoValue`
 
 Kind: callable.
 
-Identifiers, hashes, SKUs — fixed width so they compare down a column.
+Tabular figures and a mono face, for identifiers, hashes and SKUs — codes compared by eye,
+down a column.
 
 ```text
 ({ className, ...props }: ValueProps) => import("react").JSX.Element
@@ -728,7 +752,8 @@ Identifiers, hashes, SKUs — fixed width so they compare down a column.
 
 Kind: callable.
 
-Incidental copy — present, but not something the reader is meant to act on.
+The same value two steps quieter, for incidental copy — present, but not something the
+reader is meant to act on.
 
 ```text
 ({ type, size, ...props }: ValueProps) => import("react").JSX.Element
@@ -758,9 +783,9 @@ Extends: `Omit<ValueProps, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `string \| null` |  |
+| `value` | no | `string \| null` | The whole name, however it was stored. |
 | `children` | no | `ReactNode` |  |
-| `force` | no | `boolean` |  |
+| `force` | no | `boolean` | Title-cases a name that already looks INTENTIONALLY cased. A name arriving all-shouting<br>or all-lowercase is re-cased without it — those two carry no intent to preserve. Off by<br>default, because a name is the one field where the stored casing is usually deliberate:<br>`force` is what overrides that judgement. Hyphens and apostrophes each take a capital<br>(jean-luc → Jean-Luc, o'brien → O'Brien); an intercap does not, so mcdonald becomes<br>Mcdonald — Mc, Mac and van der have no rule that is right for every name carrying them. |
 
 ### `Number`
 
@@ -778,8 +803,8 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| string \| null` |  |
-| `locale` | no | `string` |  |
+| `value` | no | `number \| string \| null` | The number, drawn with locale grouping and tabular figures. |
+| `locale` | no | `string` | Overrides the scope's locale for this value. |
 | `options` | no | `Intl.NumberFormatOptions` |  |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
@@ -792,7 +817,8 @@ Extends: `SpanProps`.
 
 Kind: callable.
 
-Returns undefined rather than an Invalid Date, so the empty state renders instead.
+The single parse every date primitive goes through. Returns undefined rather than an
+Invalid Date, so the empty state renders instead.
 
 ```text
 (value: DateInput) => Date | undefined
@@ -814,7 +840,8 @@ Extends: `Omit<NumberProps, "options">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `scaled` | no | `boolean` | The value is already 0–100 rather than 0–1. |
+| `value` | no | `number \| string \| null` | A fraction, not a percentage — 0.214 renders as 21.4%. |
+| `scaled` | no | `boolean` | The value is already on 0–100 rather than 0–1. Needed because both conventions are in<br>the wild and neither is guessable from the number. |
 | `options` | no | `Intl.NumberFormatOptions` |  |
 
 ### `Phone`
@@ -833,8 +860,8 @@ Extends: `Omit<LinkProps, "href" | "children" | "ref">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `string \| null` |  |
-| `display` | no | `ReactNode` |  |
+| `value` | no | `string \| null` | The number as stored. Displayed with its grouping; dialled without it. |
+| `display` | no | `ReactNode` | Shown instead of the number. |
 | `ref` | no | `Ref<HTMLAnchorElement>` |  |
 
 ### `PluralForms`
@@ -869,9 +896,9 @@ Extends: `SharedProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
-| `unit` | no | `PluralForms \| string` | The noun, in the forms the locale may need. A bare string is used for every form. |
-| `zeroLabel` | no | `ReactNode` | Rendered instead when the count is zero ("no items"). Off by default. |
+| `value` | no | `number \| null` | The count. |
+| `unit` | no | `PluralForms \| string` | The noun, in the forms the locale may need — one, other, and the zero, two, few and<br>many some languages select. A bare string is used for every form. |
+| `zeroLabel` | no | `ReactNode` | Replaces the whole thing at zero — "no items" rather than "0 items". Off by default: in<br>a column the zero is the value being reported. |
 
 ### `Range`
 
@@ -889,11 +916,11 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `from` | no | `number \| null` |  |
-| `to` | no | `number \| null` |  |
-| `currency` | no | `string` | An ISO currency code. Renders the range as money. |
-| `unit` | no | `string` | A CSS-style unit identifier — `kilogram`, `day`. Renders the range with its unit. |
-| `maximumFractionDigits` | no | `number` |  |
+| `from` | no | `number \| null` | The low end. One end alone still renders — "from £10", with the caller's copy around<br>the value. |
+| `to` | no | `number \| null` | The high end. One end alone still renders, with the caller's copy around the value. |
+| `currency` | no | `string` | An ISO currency code. Renders the range as money: Intl repeats the symbol on both ends,<br>which is its considered answer to the ambiguity a single symbol creates. |
+| `unit` | no | `string` | A CSS-style unit identifier — `kilogram`, `day`. Renders the range with its unit.<br>Ignored when `currency` is set. |
+| `maximumFractionDigits` | no | `number` | Caps the decimals on both ends. |
 | `locale` | no | `string` |  |
 | `emptyLabel` | no | `ReactNode` |  |
 | `size` | no | `ValueProps["size"]` |  |
@@ -918,10 +945,10 @@ Extends: `SharedProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
+| `value` | no | `number \| null` | The score. Shown to at most one decimal, so 4 stays 4. |
 | `max` | no | `number` | The top of the scale. Five unless said otherwise, which is the common instrument. |
 | `hideMax` | no | `boolean` | Hides the scale, leaving the score alone.<br><br>For a surface that states the scale elsewhere — a column headed "Rating / 5", or a<br>row of stars that already shows it. Not the default, because "4.5" on its own is a<br>number a reader has to guess the meaning of. |
-| `strings` | no | `Partial<RatingStrings>` |  |
+| `strings` | no | `Partial<RatingStrings>` | The connector — "out of". |
 
 ### `RatingStrings`
 
@@ -947,10 +974,10 @@ Extends: `SharedProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `number \| null` |  |
+| `value` | no | `number \| null` | The count. |
 | `total` | no | `number \| null` | What the value is counted against. Without it the component renders the value alone. |
 | `format` | no | `"words" \| "fraction"` | `words` reads "3 of 10" (prose); `fraction` reads "3/10" (tables). |
-| `strings` | no | `Partial<RatioStrings>` |  |
+| `strings` | no | `Partial<RatioStrings>` | The connectors — "of", and the fraction separator. |
 
 ### `RatioStrings`
 
@@ -982,14 +1009,15 @@ Extends: `Omit<DateBaseProps, "pattern">`.
 | --- | :-: | --- | --- |
 | `now` | no | `DateInput` | The moment to measure against. Defaults to the clock.<br><br>Supply it wherever the render has to be reproducible — a server render whose<br>markup must match the client's, a test asserting the string, a visual snapshot.<br>Reading the clock inside the component makes all three of those flaky, and it<br>does not buy a live value in exchange: nothing re-renders it as time passes. |
 | `addSuffix` | no | `boolean` | "7 days ago" rather than "7 days". On by default, because a bare duration beside a<br>row of dates reads as a length rather than a moment. |
-| `includeSeconds` | no | `boolean` | Distinguishes "less than a minute" from "30 seconds". |
-| `formatRelativeTime` | no | `(date: Date, now: Date) => string` | Replaces the wording for this one value. Falls back to the scope's<br>`dates.formatRelativeTime`, and then to date-fns. |
+| `includeSeconds` | no | `boolean` | Distinguishes "less than a minute" from "30 seconds". Only worth it for a feed measured<br>in seconds. |
+| `formatRelativeTime` | no | `(date: Date, now: Date) => string` | Replaces the wording for this one value. Falls back to the scope's<br>`dates.formatRelativeTime`, and then to date-fns, whose built-in wording the scope's<br>`dates.locale` translates: a date-fns locale OBJECT, since the locales are modules and<br>cannot be looked up from a BCP-47 tag without putting every language in every bundle. |
 
 ### `SecondaryValue`
 
 Kind: callable.
 
-A value that supports the primary one — a subtitle, a unit, a qualifier.
+The same value one step quieter, for one that supports the primary value — a subtitle, a
+unit, a qualifier.
 
 ```text
 ({ type, ...props }: ValueProps) => import("react").JSX.Element
@@ -1007,6 +1035,9 @@ Omit<ComponentPropsWithoutRef<"span">, "children" | "color">
 
 Kind: callable.
 
+The same value as a time of day. Three components rather than a granularity prop, because
+a column shows one of them and never switches.
+
 ```text
 ({ value, pattern, ...props }: DateBaseProps) => import("react").JSX.Element
 ```
@@ -1027,9 +1058,9 @@ Extends: `Omit<LinkProps, "href" | "children" | "ref">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | no | `string \| null` |  |
-| `display` | no | `ReactNode` |  |
-| `external` | no | `boolean` | Opens in a new tab, with the rel hardening that requires — and with the announcement<br>it requires too. See `strings.opensInNewTab`. |
+| `value` | no | `string \| null` | The address. The host is shown; the whole thing stays in the href. |
+| `display` | no | `ReactNode` | Shown instead of the host. |
+| `external` | no | `boolean` | Opens in a new tab WITH `rel="noopener noreferrer"` — the two are not separable — and<br>with the announcement a new tab requires too. See `strings.opensInNewTab`. |
 | `strings` | no | `Partial<UrlStrings>` | Overrides the new-tab announcement. |
 | `ref` | no | `Ref<HTMLAnchorElement>` |  |
 
@@ -1049,7 +1080,7 @@ Extends: `SpanProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `children` | no | `ReactNode` |  |
+| `children` | no | `ReactNode` | The value. `null`, `undefined` or an empty string renders the empty mark. |
 | `emptyLabel` | no | `ReactNode` | Rendered when the value is absent. |
 | `size` | no | `TextSize` |  |
 | `align` | no | `TextProps["align"]` |  |
@@ -1071,288 +1102,854 @@ Extract<TextProps["type"], "inherit" | "main" | "secondary">
 
 ## Preview recipes
 
-Preview route: Addresses & places — `/primitive-address`
+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>
+	)
+}
+```
 
 ### Ordered by country
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Address value={{ line1, city, postalCode, country: "GB" }} />
+import { Grid, Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Address } from "themelia-ui/primitives"
+
+import { DE, UK, US } from "./data"
+
+export default function AddressExample() {
+	return (
+		// Captioned with the country code you pass; the name is the address's last line.
+		<Grid columns={{ base: 1, md: 3 }} gap="xl">
+			{[["GB", UK], ["US", US], ["DE", DE]].map(([label, value]) => (
+				<Stack key={label as string} gap="2xs">
+					<Text size="xs" type="secondary">country: "{label as string}"</Text>
+					<Address value={value as typeof UK} />
+				</Stack>
+			))}
+		</Grid>
+	)
+}
 ```
 
 ### Inline, for a cell
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Address value={value} format="inline" />
+import { Stack } from "themelia-ui/base/structure"
+import { Address } from "themelia-ui/primitives"
+
+import { DE, UK, US } from "./data"
+
+export default function AddressInline() {
+	return (
+		<Stack gap="xs">
+			<Address value={UK} format="inline" />
+			<Address value={US} format="inline" />
+			<Address value={DE} format="inline" />
+		</Stack>
+	)
+}
 ```
 
 ### Missing fields
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Address value={{ line1: "221B Baker Street", city: "London" }} />
+import { Grid } from "themelia-ui/base/structure"
+import { Address } from "themelia-ui/primitives"
+
+export default function AddressPartial() {
+	return (
+		<Grid columns={{ base: 1, md: 3 }} gap="xl">
+			<Address value={{ line1: "221B Baker Street", city: "London" }} />
+			<Address value={{ city: "London", postalCode: "NW1 6XE" }} />
+			<Address value={null} />
+		</Grid>
+	)
+}
 ```
 
 ### Coordinates
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Coordinates latitude={48.85837} longitude={2.29448} />
-<Coordinates latitude={48.85837} longitude={2.29448} format="dms" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Coordinates } from "themelia-ui/primitives"
+
+export default function CoordinatesExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <Coordinates latitude={48.85837} longitude={2.29448} /> },
+				{ label: "With hemispheres", value: <Coordinates latitude={48.85837} longitude={2.29448} showHemisphere /> },
+				{ label: "Degrees, minutes, seconds", value: <Coordinates latitude={48.85837} longitude={2.29448} format="dms" /> },
+				{ label: "Southern hemisphere", value: <Coordinates latitude={-33.8688} longitude={151.2093} format="dms" /> },
+				{ label: "Three decimals", value: <Coordinates latitude={48.85837} longitude={2.29448} precision={3} /> },
+				{ label: "No decimals", value: <Coordinates latitude={48.85837} longitude={2.29448} precision={0} /> },
+				{ label: "No coordinates", value: <Coordinates latitude={null} longitude={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Email
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Email value="jane@northwind.example" />
-<Email value="raj@northwind.example" display="Raj Patel" />
-<Email value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Email } from "themelia-ui/primitives"
+
+export default function EmailExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <Email value="jane@northwind.example" /> },
+				{ label: "Display name", value: <Email value="raj@northwind.example" display="Raj Patel" /> },
+				{ label: "No address", value: <Email value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Phone
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Phone value="+31 6 1234 5678" />
-<Phone value="+1 (555) 010-4417" />
-<Phone value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Phone } from "themelia-ui/primitives"
+
+export default function PhoneExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Grouped with spaces", value: <Phone value="+31 6 1234 5678" /> },
+				{ label: "Brackets and dashes", value: <Phone value="+1 (555) 010-4417" /> },
+				{ label: "No number", value: <Phone value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### URL
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Url value="https://northwind.example/invoices/4417" />
-<Url value="https://northwind.example/invoices/4417" external />
-<Url value="https://northwind.example" display="Northwind" />
-<Url value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Url } from "themelia-ui/primitives"
+
+export default function UrlExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <Url value="https://northwind.example/invoices/4417" /> },
+				{ label: "Opens in a new tab", value: <Url value="https://northwind.example/invoices/4417" external /> },
+				{ label: "Display text", value: <Url value="https://northwind.example" display="Northwind" /> },
+				{ label: "No address", value: <Url value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Dates and times
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DatePrimitive value={WHEN} />
-<Time value={WHEN} />
-<DateTime value={WHEN} />
-<DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" />
-<DatePrimitive value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { DatePrimitive, DateTime, Time } from "themelia-ui/primitives"
+
+import { WHEN } from "./data"
+
+export default function DateExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Date", value: <DatePrimitive value={WHEN} /> },
+				{ label: "Time", value: <Time value={WHEN} /> },
+				{ label: "Date and time", value: <DateTime value={WHEN} /> },
+				{ label: "Custom pattern", value: <DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" /> },
+				{ label: "No date", value: <DatePrimitive value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Localised names
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { de } from "date-fns/locale"
-
-<UIProvider config={{ formatting: { locale: "de-DE" }, dates: { locale: de } }}>
-  <DatePrimitive value={when} pattern="EEEE d MMMM yyyy" />
-</UIProvider>
-```
-
-### date-fns, not hand-rolled Date
+import { de, ja } from "date-fns/locale"
+
+import { MetadataList } from "themelia-ui/base/display"
+import { DatePrimitive } from "themelia-ui/primitives"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+import { WHEN } from "./data"
+
+export default function DateLocale() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" /> },
+				{
+					label: "German names",
+					value: (
+						<UIProvider config={{ dates: { locale: de } }}>
+							<DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" />
+						</UIProvider>
+					),
+				},
+				{
+					label: "Japanese names",
+					value: (
+						<UIProvider config={{ dates: { locale: ja } }}>
+							<DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" />
+						</UIProvider>
+					),
+				},
+			]}
+		/>
+	)
+}
+```
+
+### DateRange
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DateRange start={MARCH_3} end={MARCH_7} />
-<DateRange start={MARCH_3} end={APRIL_2} />
-<DateRange start={MARCH_3} end={NEXT_JAN} />
-<DateRange start={MARCH_3} end={APRIL_2} separator=" to " />
-<DateRange start={MARCH_3} end={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { DateRange } from "themelia-ui/primitives"
+
+import { APRIL_2, MARCH_3, MARCH_7, NEXT_JAN } from "./data"
+
+export default function DateRangeExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Same month", value: <DateRange start={MARCH_3} end={MARCH_7} /> },
+				{ label: "Same year", value: <DateRange start={MARCH_3} end={APRIL_2} /> },
+				{ label: "Across years", value: <DateRange start={MARCH_3} end={NEXT_JAN} /> },
+				{ label: "Custom separator", value: <DateRange start={MARCH_3} end={APRIL_2} separator=" to " /> },
+				{ label: "No end date", value: <DateRange start={MARCH_3} end={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### RelativeTime
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<RelativeTime value={HOURS_AGO} now={NOW} />
-<RelativeTime value={DAYS_AGO} now={NOW} />
-<RelativeTime value={MONTHS_AGO} now={NOW} />
-<RelativeTime value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { RelativeTime } from "themelia-ui/primitives"
+
+import { DAYS_AGO, HOURS_AGO, MONTHS_AGO, NOW } from "./data"
+
+export default function RelativeTimeExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Hours ago", value: <RelativeTime value={HOURS_AGO} now={NOW} /> },
+				{ label: "Days ago", value: <RelativeTime value={DAYS_AGO} now={NOW} /> },
+				{ label: "Months ago", value: <RelativeTime value={MONTHS_AGO} now={NOW} /> },
+				{ label: "No date", value: <RelativeTime value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Suffix and precision
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<RelativeTime value={date} now={now} addSuffix={false} />
-<RelativeTime value={date} now={now} includeSeconds />
+import { MetadataList } from "themelia-ui/base/display"
+import { RelativeTime } from "themelia-ui/primitives"
+
+import { DAYS_AGO, NOW, SECONDS_AGO } from "./data"
+
+export default function RelativeTimeShape() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "With suffix", value: <RelativeTime value={DAYS_AGO} now={NOW} /> },
+				{ label: "No suffix", value: <RelativeTime value={DAYS_AGO} now={NOW} addSuffix={false} /> },
+				{ label: "With seconds", value: <RelativeTime value={SECONDS_AGO} now={NOW} includeSeconds /> },
+				{ label: "Without seconds", value: <RelativeTime value={SECONDS_AGO} now={NOW} /> },
+			]}
+		/>
+	)
+}
 ```
 
-### Pass the clock in
+### In another language
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Duration value={45} />
-<Duration value={4520} />
-<Duration value={90} from="minutes" />
-<Duration value={4520} maxParts={1} />
-<Duration value={4520} unitDisplay="short" />
-<Duration value={null} />
+import { de } from "date-fns/locale"
+
+import { MetadataList } from "themelia-ui/base/display"
+import { RelativeTime } from "themelia-ui/primitives"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+import { DAYS_AGO, NOW } from "./data"
+
+export default function RelativeTimeLocale() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <RelativeTime value={DAYS_AGO} now={NOW} /> },
+				{
+					label: "German wording",
+					value: (
+						<UIProvider config={{ dates: { locale: de } }}>
+							<RelativeTime value={DAYS_AGO} now={NOW} />
+						</UIProvider>
+					),
+				},
+				{
+					label: "Custom wording",
+					value: (
+						<UIProvider
+							config={{
+								dates: {
+									formatRelativeTime: (date, now) =>
+										`${Math.round((now.getTime() - date.getTime()) / 86_400_000)}d`,
+								},
+							}}
+						>
+							<RelativeTime value={DAYS_AGO} now={NOW} />
+						</UIProvider>
+					),
+				},
+			]}
+		/>
+	)
+}
+```
+
+### Duration
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { MetadataList } from "themelia-ui/base/display"
+import { Duration } from "themelia-ui/primitives"
+
+export default function DurationExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Seconds", value: <Duration value={45} /> },
+				{ label: "Hours, minutes, seconds", value: <Duration value={4520} /> },
+				{ label: "Given in minutes", value: <Duration value={90} from="minutes" /> },
+				{ label: "Largest unit only", value: <Duration value={4520} maxParts={1} /> },
+				{ label: "Short units", value: <Duration value={4520} unitDisplay="short" /> },
+				{ label: "No duration", value: <Duration value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Money
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Money amount={1299.5} currency="EUR" />
-<Money amount={1299.5} currency="USD" />
-<Money amount={-42} currency="GBP" />
-<Money amount={0} currency="JPY" />
-<Money amount={null} currency="EUR" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Money } from "themelia-ui/primitives"
+
+export default function MoneyExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Euros", value: <Money amount={1299.5} currency="EUR" /> },
+				{ label: "US dollars", value: <Money amount={1299.5} currency="USD" /> },
+				{ label: "Negative pounds", value: <Money amount={-42} currency="GBP" /> },
+				{ label: "Yen, no decimals", value: <Money amount={0} currency="JPY" /> },
+				{ label: "No amount", value: <Money amount={null} currency="EUR" /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Minor units
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Money amount={129950} currency="EUR" unit="minor" />
-<Money amount={1299} currency="JPY" unit="minor" minorUnitScale={1} />
-<Money amount={129950} currency="KWD" unit="minor" minorUnitScale={1000} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Money } from "themelia-ui/primitives"
+
+export default function MoneyUnitExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Euros from cents", value: <Money amount={129950} currency="EUR" unit="minor" /> },
+				{ label: "Yen, no minor unit", value: <Money amount={1299} currency="JPY" unit="minor" minorUnitScale={1} /> },
+				{ label: "Dinars from fils", value: <Money amount={129950} currency="KWD" unit="minor" minorUnitScale={1000} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### How the amount is written
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Money amount={1299.5} currency="EUR" formatMode="with-symbol" />
-<Money amount={1299.5} currency="EUR" formatMode="with-code" />
-<Money amount={1299.5} currency="EUR" formatMode="decimal" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Money } from "themelia-ui/primitives"
+
+export default function MoneyFormat() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "With symbol", value: <Money amount={1299.5} currency="EUR" formatMode="with-symbol" /> },
+				{ label: "With code", value: <Money amount={1299.5} currency="EUR" formatMode="with-code" /> },
+				{ label: "Number only", value: <Money amount={1299.5} currency="EUR" formatMode="decimal" /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Two currencies
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Money
-  amount={1299.5}
-  currency="EUR"
-  secondary={{ amount: 1416.2, currency: "USD" }}
-/>
+import { MetadataList } from "themelia-ui/base/display"
+import { Money } from "themelia-ui/primitives"
+
+export default function MoneyDual() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{
+					label: "Discrete",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} />,
+				},
+				{
+					label: "Muted",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} secondaryEmphasis="muted" />,
+				},
+				{
+					label: "Matching",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} secondaryEmphasis="match" />,
+				},
+				{
+					label: "Arrow separator",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} separator="→" />,
+				},
+				{
+					label: "Stacked",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} layout="stacked" />,
+				},
+				{
+					label: "Hidden",
+					value: <Money amount={1299.5} currency="EUR" secondary={{ amount: 1416.2, currency: "USD" }} secondaryEmphasis="hidden" />,
+				},
+			]}
+		/>
+	)
+}
 ```
 
 ### Decided once, not per amount
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider
-  config={{
-    formatting: { locale: "de-DE" },
-    money: {
-      defaultCurrency: "EUR",
-      displayCurrency: "USD",
-      dualPricingEnabled: true,
-      displayMode: "dynamic",
-      layout: "stacked",
-    },
-  }}
->
-  <Money amount={1299.5} secondary={{ amount: 1416.2 }} />
-</UIProvider>
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Money } from "themelia-ui/primitives"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+export default function MoneyProviderExample() {
+	return (
+		<Stack gap="lg">
+			<UIProvider
+				config={{
+					formatting: { locale: "de-DE" },
+					money: {
+						defaultCurrency: "EUR",
+						displayCurrency: "USD",
+						dualPricingEnabled: true,
+						displayMode: "dynamic",
+						layout: "stacked",
+					},
+				}}
+			>
+				<MetadataList
+					layout="rows"
+					items={[
+						{ label: "With a conversion", value: <Money amount={1299.5} secondary={{ amount: 1416.2 }} /> },
+						{ label: "No conversion", value: <Money amount={1299.5} /> },
+						{ label: "Same currency", value: <Money amount={1299.5} secondary={{ amount: 1299.5, currency: "EUR" }} /> },
+					]}
+				/>
+			</UIProvider>
+			<Text size="xs" type="secondary">
+				German locale, so the group separator is a dot and the symbol trails the number.
+				The third row is <code>dynamic</code> at work: both codes are EUR, so the pair
+				would say the same thing twice and only one value renders.
+			</Text>
+		</Stack>
+	)
+}
 ```
 
 ### Name
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Name value="Jane McDonald" />
-<Name value="  jane   mcdonald " />
-<Name value="JANE MCDONALD" force />
-<Name value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Name } from "themelia-ui/primitives"
+
+export default function NameExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Deliberate casing", value: <Name value="Jane McDonald" /> },
+				{ label: "Lower case, extra spaces", value: <Name value="  jane   mcdonald " /> },
+				{ label: "All capitals, forced", value: <Name value="JANE MCDONALD" force /> },
+				{ label: "No name", value: <Name value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Initials
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Initials value="Jane McDonald" />
-<Initials value="Mei Chen" />
-<Initials value="Jane McDonald" maxCharacters={1} />
-<Initials value="Ana Sofia Reyes" strategy="first-words" />
-<Initials value="Ana Sofia Reyes" maxCharacters={3} />
-<Initials value="—" fallback="?" />
-<Initials value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Initials } from "themelia-ui/primitives"
+
+export default function InitialsExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "First and last", value: <Initials value="Jane McDonald" /> },
+				{ label: "Short name", value: <Initials value="Mei Chen" /> },
+				{ label: "One character", value: <Initials value="Jane McDonald" maxCharacters={1} /> },
+				{ label: "First two words", value: <Initials value="Ana Sofia Reyes" strategy="first-words" /> },
+				{ label: "Three characters", value: <Initials value="Ana Sofia Reyes" maxCharacters={3} /> },
+				{ label: "No letters, with fallback", value: <Initials value="—" fallback="?" /> },
+				{ label: "No name", value: <Initials value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Number and percent
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Number value={1234567.891} />
-<Number value={-42} />
-<Percent value={0.214} />
-<Percent value={1} />
-<Percent value={21.4} scaled />
-<Number value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Number, Percent } from "themelia-ui/primitives"
+
+export default function NumberExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Grouped digits", value: <Number value={1234567.891} /> },
+				{ label: "Negative", value: <Number value={-42} /> },
+				{ label: "Fraction as percent", value: <Percent value={0.214} /> },
+				{ label: "One as percent", value: <Percent value={1} /> },
+				{ label: "Already scaled", value: <Percent value={21.4} scaled /> },
+				{ label: "No number", value: <Number value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Range
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Range from={10} to={50} />
-<Range from={10} to={50} currency="GBP" />
-<Range from={2} to={5} unit="day" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Range } from "themelia-ui/primitives"
+
+export default function RangeExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Plain numbers", value: <Range from={10} to={50} /> },
+				{ label: "Pounds", value: <Range from={10} to={50} currency="GBP" /> },
+				{ label: "Euros", value: <Range from={10} to={50} currency="EUR" /> },
+				{ label: "Days", value: <Range from={2} to={5} unit="day" /> },
+				{ label: "Equal ends", value: <Range from={10} to={10} currency="GBP" /> },
+				{ label: "One end only", value: <Range from={10} currency="GBP" /> },
+				{ label: "Neither end", value: <Range from={null} to={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Ratio
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Ratio value={3} total={10} />
-<Ratio value={3} total={10} format="fraction" />
-<Ratio value={3} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Ratio } from "themelia-ui/primitives"
+
+export default function RatioExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "In words", value: <Ratio value={3} total={10} /> },
+				{ label: "Complete", value: <Ratio value={7} total={7} /> },
+				{ label: "Fraction", value: <Ratio value={3} total={10} format="fraction" /> },
+				{ label: "Large numbers", value: <Ratio value={1240} total={10000} /> },
+				{ label: "No total", value: <Ratio value={3} /> },
+				{ label: "No count", value: <Ratio value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Rating
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Rating value={4.5} />
-<Rating value={4} hideMax />
+import { MetadataList } from "themelia-ui/base/display"
+import { Rating } from "themelia-ui/primitives"
+
+export default function RatingExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Decimal score", value: <Rating value={4.5} /> },
+				{ label: "Whole score", value: <Rating value={4} /> },
+				{ label: "Out of ten", value: <Rating value={8.5} max={10} /> },
+				{ label: "Scale hidden", value: <Rating value={4.5} hideMax /> },
+				{ label: "No rating", value: <Rating value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Quantity
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Quantity value={1} unit={{ one: "item", other: "items" }} />
-<Quantity value={0} unit={ITEM} zeroLabel="no items" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Quantity } from "themelia-ui/primitives"
+
+import { ITEM, PERSON } from "./data"
+
+export default function QuantityExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "One", value: <Quantity value={1} unit={ITEM} /> },
+				{ label: "Several", value: <Quantity value={3} unit={ITEM} /> },
+				{ label: "Fraction", value: <Quantity value={1.5} unit={ITEM} /> },
+				{ label: "One person", value: <Quantity value={1} unit={PERSON} /> },
+				{ label: "Several people", value: <Quantity value={4} unit={PERSON} /> },
+				{ label: "Zero in words", value: <Quantity value={0} unit={ITEM} zeroLabel="no items" /> },
+				{ label: "No count", value: <Quantity value={null} unit={ITEM} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Measure
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Measure value={2.5} unit="kilogram" />
-<Measure value={2.5} unit="kilogram" unitDisplay="long" />
+import { MetadataList } from "themelia-ui/base/display"
+import { Measure } from "themelia-ui/primitives"
+
+export default function MeasureExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Kilograms", value: <Measure value={2.5} unit="kilogram" /> },
+				{ label: "Narrow", value: <Measure value={2.5} unit="kilogram" unitDisplay="narrow" /> },
+				{ label: "Long", value: <Measure value={2.5} unit="kilogram" unitDisplay="long" /> },
+				{ label: "Metres", value: <Measure value={180} unit="meter" /> },
+				{ label: "Celsius", value: <Measure value={21.5} unit="celsius" /> },
+				{ label: "Days", value: <Measure value={14} unit="day" /> },
+				{ label: "Unknown unit", value: <Measure value={2.5} unit="bananas" /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Dimensions
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Dimensions width={30} height={20} unit="cm" />
-<Dimensions width={30} height={20} depth={12} unit="cm" />
-<Dimensions width={1920} height={1080} unit="px" />
-<Dimensions width={null} height={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { Dimensions } from "themelia-ui/primitives"
+
+export default function DimensionsExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Width and height", value: <Dimensions width={30} height={20} unit="cm" /> },
+				{ label: "With depth", value: <Dimensions width={30} height={20} depth={12} unit="cm" /> },
+				{ label: "Pixels", value: <Dimensions width={1920} height={1080} unit="px" /> },
+				{ label: "No dimensions", value: <Dimensions width={null} height={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### File size
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FileSize value={512} />
-<FileSize value={1_100_000} />
-<FileSize value={85_800_000} />
-<FileSize value={4_100_000_000} />
-<FileSize value={null} />
+import { MetadataList } from "themelia-ui/base/display"
+import { FileSize } from "themelia-ui/primitives"
+
+export default function FileSizeExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Bytes", value: <FileSize value={512} /> },
+				{ label: "About a megabyte", value: <FileSize value={1_100_000} /> },
+				{ label: "Tens of megabytes", value: <FileSize value={85_800_000} /> },
+				{ label: "Gigabytes", value: <FileSize value={4_100_000_000} /> },
+				{ label: "No size", value: <FileSize value={null} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Which megabyte
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FileSize value={1_100_000} />                    {/* 1 MB */}
-<FileSize value={1_100_000} base="decimal" />    {/* 1.1 MB */}
-<FileSize value={1_100_000} base="iec" />        {/* 1 MiB */}
+import { MetadataList } from "themelia-ui/base/display"
+import { FileSize } from "themelia-ui/primitives"
+
+export default function FileSizeBaseExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Binary", value: <FileSize value={85_800_000} /> },
+				{ label: "Decimal", value: <FileSize value={85_800_000} base="decimal" /> },
+				{ label: "IEC", value: <FileSize value={85_800_000} base="iec" /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### Value
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Value>Northwind Traders</Value>
-<SecondaryValue>Supporting detail</SecondaryValue>
-<MutedValue>Quieter still</MutedValue>
-<MonoValue>req_8f21c440</MonoValue>
-<EmptyValue />
-```
-
-### Absent is a state
+import { MetadataList } from "themelia-ui/base/display"
+import { EmptyValue, MonoValue, MutedValue, SecondaryValue, Value } from "themelia-ui/primitives"
+
+export default function ValueExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <Value>Northwind Traders</Value> },
+				{ label: "Secondary", value: <SecondaryValue>Supporting detail</SecondaryValue> },
+				{ label: "Muted", value: <MutedValue>Quieter still</MutedValue> },
+				{ label: "Monospaced", value: <MonoValue>req_8f21c440</MonoValue> },
+				{ label: "Empty", value: <EmptyValue /> },
+			]}
+		/>
+	)
+}
+```
+
+### Inline list
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InlineList items={["Alice", "Bob", "Carol"]} />
-<InlineList items={["red", "green", "blue"]} join="or" />
-<InlineList items={items} max={2} />
+import { MetadataList } from "themelia-ui/base/display"
+import { InlineList } from "themelia-ui/primitives"
+
+import { THREE } from "./data"
+
+export default function InlineListExample() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "Default", value: <InlineList items={THREE} /> },
+				{ label: "Alternatives", value: <InlineList items={["red", "green", "blue"]} join="or" /> },
+				{ label: "No conjunction", value: <InlineList items={THREE} join="none" /> },
+				{ label: "At most two", value: <InlineList items={["a", "b", "c", "d"]} max={2} /> },
+				{ label: "Two items", value: <InlineList items={["Alice", "Bob"]} /> },
+				{ label: "One item", value: <InlineList items={["Alice"]} /> },
+				{ label: "No items", value: <InlineList items={[]} /> },
+			]}
+		/>
+	)
+}
 ```
 
 ### The same list, three locales
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InlineList items={names} locale="en-GB" />
-<InlineList items={names} locale="es-ES" />
-<InlineList items={names} locale="ja-JP" />
+import { MetadataList } from "themelia-ui/base/display"
+import { InlineList } from "themelia-ui/primitives"
+
+import { THREE } from "./data"
+
+export default function InlineListLocale() {
+	return (
+		<MetadataList
+			layout="rows"
+			items={[
+				{ label: "British English", value: <InlineList items={THREE} locale="en-GB" /> },
+				{ label: "American English", value: <InlineList items={THREE} locale="en-US" /> },
+				{ label: "Spanish", value: <InlineList items={THREE} locale="es-ES" /> },
+				{ label: "German", value: <InlineList items={THREE} locale="de-DE" /> },
+				{ label: "Japanese", value: <InlineList items={THREE} locale="ja-JP" /> },
+			]}
+		/>
+	)
+}
 ```