@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/datetime-range-picker.md

@@ -0,0 +1,158 @@
+<!-- index: ./index.md -->
+# datetime-range-picker
+
+`data-ui="datetime-range-picker"` · Start and end date-times with a picker.
+
+## Import
+
+```tsx
+import { DateTimeRangePicker, DateTimeRangePickerDefaultsProvider, DateTimeRangePickerPreset, SlottedProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Field>
+  <FieldLabel>Retirada e devolução</FieldLabel>
+  <DateTimeRangePicker
+    clearable
+    defaultValue={rental}
+    locale="pt-BR"
+    messages={{ start: 'Retirada', end: 'Devolução' }}
+  />
+</Field>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `control` | div | yes |
+| `trigger` | button | yes |
+| `summary` | span | yes |
+| `clear` | button | no |
+| `hidden-input` | input | yes |
+| `positioner` | div | no |
+| `content` | div | no |
+| `head` | div | no |
+| `tabs` | div | no |
+| `tab` | button | no |
+| `tab-label` | span | no |
+| `tab-value` | span | no |
+| `field` | div | no |
+| `now` | button | no |
+| `hint` | span | no |
+| `length` | span | no |
+| `limit` | span | no |
+| `presets` | div | no |
+| `preset` | button | no |
+| `panel` | div | no |
+| `date-panel` | div | no |
+| `list` | div | no |
+| `option` | div | no |
+| `option-duration` | span | no |
+| `empty` | div | no |
+| `footer` | div | no |
+| `done` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `DateTimeRange \| null` | — | DateTimeRangePicker | { start, end }, each end nullable. Present means the consumer owns it. Both ends null is null. |
+| `defaultValue` | `DateTimeRange \| null` | — | DateTimeRangePicker | What it starts from when nobody else writes one. Read once. |
+| `open` | `boolean` | — | DateTimeRangePicker | Whether the surface is showing. Present means the consumer owns it. |
+| `defaultOpen` | `boolean` | false | DateTimeRangePicker | Whether it opens already showing. |
+| `position` | `'start' \| 'end'` | — | DateTimeRangePicker | The end being edited: the field and the panel carrying data-current, and where focus lands when the surface opens. Present means the consumer owns it. |
+| `defaultPosition` | `'start' \| 'end'` | start | DateTimeRangePicker | Where editing starts. |
+| `highlighted` | `{ start: PlainTime \| null; end: PlainTime \| null }` | — | DateTimeRangePicker | The highlighted option of each end’s list. Present means the consumer owns it. Moving it moves no value. |
+| `defaultHighlighted` | `{ start: PlainTime \| null; end: PlainTime \| null }` | — | DateTimeRangePicker | Where the highlights start; otherwise a list opens on its end, or on the nearest offered step. |
+| `min` | `PlainDateTime` | — | DateTimeRangePicker | Where the range starts: the earliest whole value. Its time bounds the first day only, the platform’s own rule. Crossed with the work between the two fields. |
+| `max` | `PlainDateTime` | — | DateTimeRangePicker | Where the range ends; its time bounds the last day only. |
+| `minTime` | `PlainTime` | — | DateTimeRangePicker | The earliest time on every day inside the range, applied together with min — the pair MUI declines to combine. |
+| `maxTime` | `PlainTime` | — | DateTimeRangePicker | The latest time on every day inside the range. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | DateTimeRangePicker | Refuses whole days. The grid greys them and a list on such a day is empty. |
+| `isTimeUnavailable` | `(time: PlainTime, date: PlainDate) => boolean` | — | DateTimeRangePicker | Refuses one time on one day. Asked once per row of a list, on the day that list serves. |
+| `contiguous` | `boolean` | true | DateTimeRangePicker | Whether a run may cross an unavailable day. On, and with a start chosen, the days beyond the first unavailable one are refused in the grid, and on the same day the times beyond the first unavailable one in the end list. |
+| `minLength` | `number` | — | DateTimeRangePicker | The shortest run allowed, in seconds. The grid and the list refuse shorter ones and the band names the limit. |
+| `maxLength` | `number` | — | DateTimeRangePicker | The longest run allowed, in seconds. |
+| `lengthLabel` | `(seconds: number, locale?: string) => string` | durationLabel | DateTimeRangePicker | What the band and the rows say for a duration, in the product’s own words. The default writes "3 days 21 hr" in the family’s locale. |
+| `step` | `number` | 900 | DateTimeRangePicker | Seconds between two offered times, counted from min’s time on the first day and from midnight elsewhere. Ignored when options states the list. |
+| `options` | `readonly PlainTime[]` | — | DateTimeRangePicker | The times to offer, stated rather than stepped; the same list for both ends. The bounds and the predicate still refuse. |
+| `maxOptions` | `number` | 1440 | DateTimeRangePicker | How many rows a list may reach before it is cut. Cut, the list carries data-truncated and the panel’s description says the rest is typed. |
+| `unavailableOptions` | `'disable' \| 'hide'` | disable | DateTimeRangePicker | What a refused time looks like in a list: drawn muted with aria-disabled, or left out. |
+| `months` | `number` | 1 | DateTimeRangePicker | How many months the grid shows. One, because the list stands beside it; a second wraps under the first where the surface is narrow. |
+| `weekNumbers` | `boolean` | — | DateTimeRangePicker | Draws the ISO week number beside each row of the grid. |
+| `fixedWeeks` | `boolean` | true | DateTimeRangePicker | Six rows whatever the month needs, so a press of "next" moves no target. |
+| `locale` | `string` | SlottedProvider | DateTimeRangePicker | BCP 47. Decides the field order, the digits, the month names, the day-period names and the duration’s units. Unset, the language in force decides. |
+| `timeZone` | `string` | — | DateTimeRangePicker | The zone "now" is read in. |
+| `hourCycle` | `12 \| 24` | — | DateTimeRangePicker | Twelve- or twenty-four-hour times. Unset, the locale decides. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | DateTimeRangePicker | How much of a time the fields and the rows write. |
+| `calendar` | `'gregory'` | gregory | DateTimeRangePicker | The calendar system. One today. |
+| `firstDayOfWeek` | `number` | — | DateTimeRangePicker | Which day the grid’s week starts on. Unset, the locale decides. |
+| `yearPivot` | `number` | — | DateTimeRangePicker | The pivot two typed year digits are resolved through. |
+| `referenceDateTime` | `PlainDateTime` | — | DateTimeRangePicker | What "now" is, for a story or a test; the clock otherwise. Anchors now, the day the panel opens on, and the relative expression. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | DateTimeRangePicker | The control scale of the frame. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | DateTimeRangePicker | How much frame the control shows at rest. |
+| `placement` | `'bottom-start' \| 'bottom' \| 'bottom-end' \| 'top-start' \| 'top' \| 'top-end'` | bottom-start | DateTimeRangePicker | Where the surface opens, before the positioner has read the room. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | DateTimeRangePicker | auto closes when a press completes the work; always closes on any press that changes the value; never closes on none. |
+| `disabled` | `boolean` | — | DateTimeRangePicker | Nothing answers; the value stays readable. |
+| `readOnly` | `boolean` | — | DateTimeRangePicker | Legible and copyable; the trigger and the clear are out of the tab sequence. |
+| `invalid` | `boolean` | — | DateTimeRangePicker | The consumer’s own word. Set, it wins; unset, the family’s own rules and the field around it decide. |
+| `required` | `boolean` | — | DateTimeRangePicker | Reaches both fields as aria-required. |
+| `clearable` | `boolean` | false | DateTimeRangePicker | Draws one clear on the frame, which empties both ends. |
+| `relative` | `boolean` | — | DateTimeRangePicker | Whether the field in the band takes the relative expression — +2d, 1h30, = — the way a datetime-field does. |
+| `messages` | `Partial<DatetimeRangePickerMessages>` | — | DateTimeRangePicker | Words laid over the language in force, key by key: the two ends (start, end), the trigger’s names (choose; change with {start}, {end} and {length}; changeReversed), the hint (chooseDay with {end}; chooseTime with {end} and {day}; order, length, unavailable, bounds), the limit (limit.between, limit.atLeast, limit.atMost), now, done, clear, and a panel that is empty or cut short (empty, truncated). |
+| `startName` | `string` | — | DateTimeRangePicker | The name of the hidden input carrying the start. |
+| `endName` | `string` | — | DateTimeRangePicker | The name of the hidden input carrying the end. |
+| `presets` | `ReactNode` | — | DateTimeRangePicker | The consumer’s shortcuts, as DateTimeRangePickerPreset elements. |
+| `footer` | `ReactNode` | — | DateTimeRangePicker | The consumer’s own actions, under the lists. |
+| `renderOption` | `(state: DateTimeRangePickerOptionState) => ReactNode` | — | DateTimeRangePicker | What one row draws. The state carries the end, the day the list serves, the time, its label, its duration, and whether it is selected, current or unavailable. |
+| `value` | `DateTimeRange \| (() => DateTimeRange)` | — | DateTimeRangePickerPreset | The range the press writes, or a function resolving it at the press. |
+| `DateTimeRangePickerDefaultsProvider` | `component` | — | application | Sets timeZone, calendar, firstDayOfWeek, months, hourCycle, granularity, step, maxOptions, unavailableOptions, closeOnSelect, placement, size, variant and lengthLabel once for everything under it. The locale and the words come from SlottedProvider. |
+| `DateTimeRangePickerPreset` | `component` | — | presets | One shortcut inside presets. Takes every button prop, composes onClick, and takes render to substitute its element. |
+| `render` | `(props: DateTimeRangePickerRootProps) => ReactNode` | — | DateTimeRangePicker | Substitutes the element the root renders. The props carry the ref, which the positioner measures its anchor through. |
+| `ref` | `Ref<DateTimeRangePickerHandle>` | — | DateTimeRangePicker | focus() puts the reader on the trigger; open() and close() move the surface without a controlled prop. |
+| `onKeyDown` | `KeyboardEventHandler` | — | DateTimeRangePicker | Runs before the trigger, the tabs and the list read a key, and calling preventDefault stops them. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: DateTimeRange \| null, request: ChangeRequest<DateTimeRange \| null>)` | Before the value moves, and cancellable. keyboard, blur or clear when an end was typed in the band, select when a press in the grid or the list, now, done or a preset completed the work or changed a whole one, clear for the clear button. A press that leaves a half missing emits nothing. |
+| `onOpenChange` | `(open: boolean, request: ChangeRequest<boolean>)` | Before the surface opens or closes, and cancellable. pointer for the trigger and for done, keyboard for a key on the trigger, escape for the key, outsidePress for a press elsewhere, select for a press that completed the work. |
+| `onPositionChange` | `(position: 'start' \| 'end', request: ChangeRequest<'start' \| 'end'>)` | Before the current end moves. pointer for a press on a tab, keyboard for the arrows on one, select when a press in the grid, the list or a preset moved it, clear for the clear button, programmatic when the panel opened on the first end with a half missing. |
+| `onHighlightedChange` | `(value: { start; end }, request: ChangeRequest<{ start; end }>)` | Before a highlight moves in either list. keyboard for the arrows and type-ahead, pointer for a press, programmatic when a list opened or changed under it. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `placement` | `bottom-start`, `bottom`, `bottom-end`, `top-start`, `top`, `top-end` | `bottom-start` |
+| `closeOnSelect` | `auto`, `always`, `never` | `auto` |
+| `unavailableOptions` | `disable`, `hide` | `disable` |
+| `hourCycle` | `12`, `24` | — |
+| `granularity` | `hour`, `minute`, `second` | `minute` |
+| `calendar` | `gregory` | `gregory` |
+| `position` | `start`, `end` | — |
+
+## Rules
+
+- The trigger’s accessible name carries both ends in words and the duration — "Change range, 12 September 2026 at 14:00 – 16 September 2026 at 11:00, 3 days 21 hr". Focus returns to it when the surface closes; the summary’s ellipsis removes nothing a screen-reader user cannot hear.
+- The two ends are a tablist with automatic activation, and the panel is one end at a time: a grid and a listbox, the listbox named by the current tab, so "Pickup, 12 Sep, 14:00" is heard before the first option. The hint is the list’s description, so what to choose next — the day, then the time — is read with it.
+- The duration is a polite live region: a sighted reader sees it follow the pointer across the grid and beside every row of a same-day list; a screen-reader user hears it on every arrow.
+- The rule datetime-picker wrote, once per end: a press that leaves a half missing carries focus to it — the grid for a date, the list for a time, the tab moving when it is the other end’s — and the press that completes the work closes the panel. A half-drawn run never reaches a form. Done is the way out when nothing closed it.
+- Typing lives in the band: Enter on the trigger opens onto the first segment of the current end’s field, and the field keeps every key a datetime-field has. On a coarse pointer the field is not drawn and Enter opens onto the grid. Escape is staged: the field’s expression first, the calendar’s view second, the surface last.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-datetime-range-picker-action-active-background`, `--slotted-datetime-range-picker-action-color`, `--slotted-datetime-range-picker-action-hover-background`, `--slotted-datetime-range-picker-action-size`, `--slotted-datetime-range-picker-background`, `--slotted-datetime-range-picker-border-color`, `--slotted-datetime-range-picker-color`, `--slotted-datetime-range-picker-content-border-color`, `--slotted-datetime-range-picker-content-color`, `--slotted-datetime-range-picker-content-max-inline-size`, `--slotted-datetime-range-picker-content-padding`, `--slotted-datetime-range-picker-content-radius`, `--slotted-datetime-range-picker-content-shadow`, `--slotted-datetime-range-picker-current-color`, `--slotted-datetime-range-picker-current-size`, `--slotted-datetime-range-picker-disabled-background`, `--slotted-datetime-range-picker-disabled-border-color`, `--slotted-datetime-range-picker-disabled-color`, `--slotted-datetime-range-picker-done-active-background`, `--slotted-datetime-range-picker-done-background`, `--slotted-datetime-range-picker-done-color`, `--slotted-datetime-range-picker-done-hover-background`, `--slotted-datetime-range-picker-hint-color`, `--slotted-datetime-range-picker-hover-border-color`, `--slotted-datetime-range-picker-invalid-border-color`, `--slotted-datetime-range-picker-invalid-color`, `--slotted-datetime-range-picker-invalid-edge-width`, `--slotted-datetime-range-picker-invalid-focus-ring-color`, `--slotted-datetime-range-picker-label-color`, `--slotted-datetime-range-picker-length-color`, `--slotted-datetime-range-picker-limit-color`, `--slotted-datetime-range-picker-list-block-size`, `--slotted-datetime-range-picker-list-min-inline-size`, `--slotted-datetime-range-picker-now-color`, `--slotted-datetime-range-picker-option-current-background`, `--slotted-datetime-range-picker-option-hover-background`, `--slotted-datetime-range-picker-option-radius`, `--slotted-datetime-range-picker-option-selected-background`, `--slotted-datetime-range-picker-option-selected-color`, `--slotted-datetime-range-picker-option-selected-hover-background`, `--slotted-datetime-range-picker-placeholder-color`, `--slotted-datetime-range-picker-plain-hover-background`, `--slotted-datetime-range-picker-preset-active-background`, `--slotted-datetime-range-picker-preset-background`, `--slotted-datetime-range-picker-preset-hover-background`, `--slotted-datetime-range-picker-preset-radius`, `--slotted-datetime-range-picker-preset-selected-background`, `--slotted-datetime-range-picker-preset-selected-color`, `--slotted-datetime-range-picker-radius`, `--slotted-datetime-range-picker-readonly-background`, `--slotted-datetime-range-picker-shadow`, `--slotted-datetime-range-picker-sheet-inline-size`, `--slotted-datetime-range-picker-subtle-background`, `--slotted-datetime-range-picker-subtle-border-color`, `--slotted-datetime-range-picker-subtle-hover-background`, `--slotted-datetime-range-picker-surface`, `--slotted-datetime-range-picker-tab-block-size`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-letter-spacing-wide`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-radius-pill`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [datetime-range-picker.examples.md](./datetime-range-picker.examples.md).

package/dist/docs/description-list.json

@@ -0,0 +1,469 @@
+{
+  "family": "description-list",
+  "ui": "description-list",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Term and value pairs for record details."
+  },
+  "axes": {
+    "layout": [
+      "row",
+      "stack"
+    ],
+    "columns": [
+      "1",
+      "2",
+      "3"
+    ],
+    "variant": [
+      "plain",
+      "ruled",
+      "framed"
+    ]
+  },
+  "members": {
+    "descriptionList": {
+      "nativeElement": "div",
+      "defaults": {
+        "layout": "row",
+        "columns": "1",
+        "variant": "plain",
+        "termWidth": "14rem",
+        "span": 1,
+        "clamp": 0,
+        "copy": false,
+        "empty": false,
+        "defaultRevealed": false
+      },
+      "capabilities": [
+        "arrangement",
+        "appearance",
+        "revealed",
+        "copyable",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "revealed",
+        "complete"
+      ],
+      "parts": [
+        "root",
+        "list",
+        "item",
+        "term",
+        "hint",
+        "description",
+        "value",
+        "placeholder",
+        "copy",
+        "toggle",
+        "action"
+      ]
+    }
+  },
+  "docs": {
+    "descriptionList": {
+      "imports": {
+        "source": "import {\n  DescriptionList,\n  DescriptionListAction,\n  DescriptionListDefaultsProvider,\n  DescriptionListDescription,\n  DescriptionListHint,\n  DescriptionListItem,\n  DescriptionListTerm,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "The query container, and the element every axis is written on. It answers its own inline size, which is why it is not the dl: an element with container-type is a container for its descendants and not for itself."
+        },
+        {
+          "part": "list",
+          "element": "dl",
+          "required": true,
+          "purpose": "The grid, drawn by the family. It declares the term track, the value track and the action track, and every pair borrows them with subgrid."
+        },
+        {
+          "part": "item",
+          "element": "div",
+          "required": true,
+          "purpose": "One name-value pair, in the wrapper the HTML Standard permits inside a dl. It is the box a rule, a tint and a span apply to."
+        },
+        {
+          "part": "term",
+          "element": "dt",
+          "required": true,
+          "purpose": "The name. It carries the identifier the row action is described by, and a consumer id wins over it."
+        },
+        {
+          "part": "hint",
+          "element": "span",
+          "required": false,
+          "purpose": "One line explaining the term, inside the dt that names it. A list that has hints gives up the row arrangement eight rem earlier than one that does not."
+        },
+        {
+          "part": "description",
+          "element": "dd",
+          "required": true,
+          "purpose": "The value cell: the value and the controls that reach it. It carries data-clamp and data-revealed."
+        },
+        {
+          "part": "value",
+          "element": "span",
+          "required": true,
+          "purpose": "The value itself, and the one part a clamp applies to. It is always present so the clamp, the copy target and the controls have one stable place."
+        },
+        {
+          "part": "placeholder",
+          "element": "span",
+          "required": false,
+          "purpose": "A value that is missing, in one of two forms: words a consumer stated, shown as they were written, or an em dash with the reason beside it in text a screen reader reads."
+        },
+        {
+          "part": "copy",
+          "element": "button",
+          "required": false,
+          "purpose": "Puts the value on the clipboard and says it finished, by its mark as well as by its colour. Where the platform refuses the write it selects the value instead, so the reader can take it with the keyboard."
+        },
+        {
+          "part": "toggle",
+          "element": "button",
+          "required": false,
+          "purpose": "Reveals a clamped value and clamps it again, and appears only where the value wants more room than the clamp gives it. It carries aria-expanded, which is the APG Disclosure pattern."
+        },
+        {
+          "part": "action",
+          "element": "dd",
+          "required": false,
+          "purpose": "The row action, in a second dd of the same group. Named by its own term through aria-describedby."
+        }
+      ],
+      "api": [
+        {
+          "name": "layout",
+          "type": "'row' | 'stack'",
+          "defaultValue": "row",
+          "appliesTo": "DescriptionList",
+          "description": "The term beside its value, or above it"
+        },
+        {
+          "name": "columns",
+          "type": "1 | 2 | 3",
+          "defaultValue": "1",
+          "appliesTo": "DescriptionList",
+          "description": "How many pairs stand side by side"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed'",
+          "defaultValue": "plain",
+          "appliesTo": "DescriptionList",
+          "description": "Nothing between pairs, a rule between them, or a framed table"
+        },
+        {
+          "name": "termWidth",
+          "type": "string",
+          "defaultValue": "14rem",
+          "appliesTo": "DescriptionList",
+          "description": "The maximum width of the term column; the terms share one track sized to the widest of them, up to this"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<DescriptionListMessages>",
+          "defaultValue": "—",
+          "appliesTo": "DescriptionList",
+          "description": "Words laid over the language in force, key by key: copy, copied, copyBlocked, reveal, collapse, placeholder"
+        },
+        {
+          "name": "span",
+          "type": "1 | 2 | 3",
+          "defaultValue": "1",
+          "appliesTo": "DescriptionListItem",
+          "description": "How many columns the pair takes, clamped to the count the list has"
+        },
+        {
+          "name": "clamp",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "DescriptionListDescription",
+          "description": "Lines the value is held to before it is revealed; 0 never clamps"
+        },
+        {
+          "name": "copy",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DescriptionListDescription",
+          "description": "Draws the control that puts the value on the clipboard"
+        },
+        {
+          "name": "copyValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "DescriptionListDescription",
+          "description": "The text that control copies. Absent, the rendered text is read at the moment of the press"
+        },
+        {
+          "name": "empty",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DescriptionListDescription",
+          "description": "Draws the placeholder. Nullish children are empty without stating it"
+        },
+        {
+          "name": "placeholder",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DescriptionListDescription",
+          "description": "Words shown in place of a value that is missing. Unset, the mark is drawn and the placeholder message is read instead"
+        },
+        {
+          "name": "revealed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DescriptionListDescription",
+          "description": "Present means controlled, for the life of the component"
+        },
+        {
+          "name": "defaultRevealed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DescriptionListDescription",
+          "description": "What an uncontrolled description starts from, read once"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "every part but the list",
+          "description": "Substitutes the rendered element. Every data attribute is handed to it, so another component keeps them. The dl is fixed: it has no option of its own, and substituting it would take away the element every semantic here rests on."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the element, and focus() with it"
+        },
+        {
+          "name": "useDescriptionList()",
+          "type": "() => DescriptionListContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside a DescriptionList",
+          "description": "The arrangement and the translator t, for a part of your own"
+        },
+        {
+          "name": "DescriptionListDefaultsProvider",
+          "type": "layout | columns | variant | termWidth",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets those four once for everything below it; a prop on the list still wins"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DescriptionListDescription",
+          "description": "A tag, a status indicator, a link or a skeleton — the value slot takes what the row needs"
+        }
+      ],
+      "events": [
+        {
+          "name": "onRevealedChange",
+          "payload": "(revealed: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before a clamped value is revealed or clamped again. The request carries the value it replaces, the reason — pointer, keyboard or programmatic — and the originating event, and cancelling it commits nothing."
+        },
+        {
+          "name": "onCopy",
+          "payload": "(request: DescriptionListCopyRequest)",
+          "when": "After the clipboard write, whether or not the platform accepted it. It carries the exact text, the reason, copied — false where there is no clipboard or the write was refused — and selected, true where the family put the value under the reader’s own selection instead. It is not a ChangeRequest: there is nothing to cancel and no state the family holds."
+        }
+      ],
+      "accessibility": [
+        "The rendered elements are a dl, a dt and a dd, and the family writes no role at all. HTML-AAM maps them to list, term and definition already, and MDN records that authoring the ARIA term and definition roles by hand changes how VoiceOver announces the construct. The APG has no pattern for a description list — twenty-nine patterns, and none of them is this — so the platform is the specification the family follows.",
+        "The div around each pair is the second form the HTML Standard permits inside a dl, and it is what makes a pair one grid area. The row action is a second dd of the same group, because a dt may be followed by more than one dd.",
+        "A row action is named by its own term through aria-describedby pointing at the dt, so a reader who tabs to \"Change\" hears which row it changes. GOV.UK repeats the term as visually hidden text inside every action, which a template system has to do; a reference says it once and cannot drift. A consumer aria-describedby is composed with rather than replaced.",
+        "A value that is missing is drawn and said: the mark is geometry in CSS and the reason is real text in a visually hidden sibling, because colour and shape alone never carry meaning.",
+        "The reveal toggle is the APG Disclosure pattern — role button, aria-expanded true while the content is visible, Enter and Space toggling — and the copy control is a plain button, so both take their keyboard behaviour from the platform. The family adds no key of its own: a read-only list of pairs is not a composite widget, and inventing arrow navigation would take Tab away from controls that need it.",
+        "Clamping is visual only. Every character stays in the DOM, selectable, copyable and readable by a screen reader, which is what the repository means by never truncating without access.",
+        "A finished copy is announced politely through the shared live announcer rather than a region this family owns, so two copies in one update are both heard; and the control changes its mark as well as its colour, so a reader who cannot see the green still sees it finish.",
+        "A browser refuses the clipboard where the document is not focused, and inside an iframe carrying no clipboard-write permission — a Storybook page is both. A control that failed silently there would be indistinguishable from a broken one, so the family selects the value instead and announces that it did: the reader sees the selection and copies it with the keyboard.",
+        "A clamp is a maximum rather than a promise, so the reveal control appears only for a value that has more text than the clamp allows. A control that reveals nothing is one a reader presses once and learns to distrust."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-size-md",
+    "--slotted-control-gap-md",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-description-list-cell-padding-block",
+    "--slotted-description-list-cell-padding-inline",
+    "--slotted-description-list-clamp",
+    "--slotted-description-list-color",
+    "--slotted-description-list-column-gap",
+    "--slotted-description-list-control-color",
+    "--slotted-description-list-control-color-complete",
+    "--slotted-description-list-control-color-hover",
+    "--slotted-description-list-control-surface-active",
+    "--slotted-description-list-control-surface-hover",
+    "--slotted-description-list-font-family",
+    "--slotted-description-list-font-size",
+    "--slotted-description-list-frame-radius",
+    "--slotted-description-list-glyph-size",
+    "--slotted-description-list-group-gap",
+    "--slotted-description-list-hint-color",
+    "--slotted-description-list-hint-font-size",
+    "--slotted-description-list-line-height",
+    "--slotted-description-list-placeholder-color",
+    "--slotted-description-list-radius",
+    "--slotted-description-list-row-gap",
+    "--slotted-description-list-rule-color",
+    "--slotted-description-list-stack-gap",
+    "--slotted-description-list-surface",
+    "--slotted-description-list-term-color",
+    "--slotted-description-list-term-min",
+    "--slotted-description-list-term-surface",
+    "--slotted-description-list-term-weight",
+    "--slotted-description-list-term-width",
+    "--slotted-description-list-toggle-color",
+    "--slotted-description-list-underline-offset",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-line-height-md",
+    "--slotted-line-height-xs",
+    "--slotted-radius-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-surface",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-success-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Every axis on one details panel, driven by the controls below the canvas. Change columns and variant, then narrow the window and watch the arrangement answer the panel rather than the viewport.",
+      "language": "tsx",
+      "source": "<DescriptionList>\n  <DescriptionListItem>\n    <DescriptionListTerm>Environment</DescriptionListTerm>\n    <DescriptionListDescription>Production</DescriptionListDescription>\n  </DescriptionListItem>\n</DescriptionList>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layout",
+      "title": "Beside the term, or under it",
+      "note": "Row puts the value in a column of its own, and every term in the list shares one track sized to the widest of them. Stack puts the value under its term, which is what a narrow container gets whether or not you ask.",
+      "language": "tsx",
+      "source": "<DescriptionList layout=\"row\" />;\n<DescriptionList layout=\"stack\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "columns",
+      "title": "More than one pair to a row",
+      "note": "Three columns become two below 48rem of the panel, two become one below 34rem. Compare the term columns: each column group sizes its own, so two groups of unlike terms do not pretend to be a table.",
+      "language": "tsx",
+      "source": "<DescriptionList columns={2}>{pairs}</DescriptionList>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "Nothing, a rule, or a frame",
+      "note": "Plain is the form that belongs inside a card, where the card already draws the box. Ruled puts a hairline under every pair, including the last. Framed is the specification table: an outer frame and a tinted term cell.",
+      "language": "tsx",
+      "source": "<DescriptionList variant=\"plain\" />;\n<DescriptionList variant=\"ruled\" />;\n<DescriptionList variant=\"framed\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "span",
+      "title": "A pair that needs the whole row",
+      "note": "An address or an endpoint takes more than a third of a row, so it takes the row. A span wider than the list has columns is clamped to the count rather than growing the grid a column nobody declared.",
+      "language": "tsx",
+      "source": "<DescriptionList columns={2}>\n  <DescriptionListItem span={2}>\n    <DescriptionListTerm>Endpoint</DescriptionListTerm>\n    <DescriptionListDescription>db.eu-west-2.example.com:5432</DescriptionListDescription>\n  </DescriptionListItem>\n</DescriptionList>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "A row you can go back and change",
+      "note": "The action is a second dd of the same group, which is what the platform is for. Tab to one and a screen reader reads the term with it, because the action is described by the dt rather than by hidden text repeated in every row.",
+      "language": "tsx",
+      "source": "<DescriptionListItem>\n  <DescriptionListTerm>Name</DescriptionListTerm>\n  <DescriptionListDescription>Sarah Phillips</DescriptionListDescription>\n  <DescriptionListAction>\n    <Link href=\"/name\">Change</Link>\n  </DescriptionListAction>\n</DescriptionListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "empty",
+      "title": "A value that is not there",
+      "note": "An empty cell is a row a reader cannot tell from a defect. Nullish children draw the mark — a rule, not an em dash — and a screen reader hears the reason; words you state are shown as you wrote them.",
+      "language": "tsx",
+      "source": "<DescriptionListDescription>{account.owner}</DescriptionListDescription>;\n\n// Or say so, and say what is read in its place.\n<DescriptionListDescription empty placeholder=\"Not set yet\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "hint",
+      "title": "A term that explains itself",
+      "note": "One line under the name, inside the dt, so a reader who reaches the term hears the explanation with it. It costs the list eight rem of the row arrangement, which is why it is a sentence and not a paragraph.",
+      "language": "tsx",
+      "source": "<DescriptionListTerm>\n  Retention\n  <DescriptionListHint>How long a deleted object stays recoverable.</DescriptionListHint>\n</DescriptionListTerm>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "copy",
+      "title": "A value worth taking away",
+      "note": "An identifier, a key, an ARN. The control writes the rendered text unless you state another, says it finished by its mark as well as its colour for two seconds, and announces the result politely. Pressing it on this page selects the value instead: a browser refuses the clipboard inside an iframe that carries no clipboard-write permission, and the family does the part it still can.",
+      "language": "tsx",
+      "source": "<DescriptionListDescription copy onCopy={(request) => log(request.copied)}>\n  arn:aws:iam::421900075512:role/billing-reconciler\n</DescriptionListDescription>;\n\n// Where the rendered value is a formatting of the real one.\n<DescriptionListDescription copy copyValue={account.iban}>\n  {formatIban(account.iban)}\n</DescriptionListDescription>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reveal",
+      "title": "A value longer than its row",
+      "note": "Clamping is visual: every character stays in the DOM, selectable and readable by a screen reader, and the control brings the rest into view — and appears only where there is a rest to bring. Hold revealed yourself when the choice should survive a navigation.",
+      "language": "tsx",
+      "source": "<DescriptionListDescription clamp={2}>{note}</DescriptionListDescription>;\n\n// Or own the choice.\n<DescriptionListDescription\n  clamp={2}\n  revealed={revealed}\n  onRevealedChange={(next) => setRevealed(next)}\n>\n  {note}\n</DescriptionListDescription>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Inside a card, and beside the families it sits with",
+      "note": "Card owns the title and the header actions, so this family ships neither. The value slot takes a tag, a status indicator or a skeleton, and the defaults provider decides the arrangement for a whole application; the words come from the language in force.",
+      "language": "tsx",
+      "source": "<Card>\n  <CardHeader>Billing</CardHeader>\n  <CardBody>\n    <DescriptionList>{pairs}</DescriptionList>\n  </CardBody>\n</Card>;\n\n<DescriptionListDefaultsProvider variant=\"ruled\">\n  <App />\n</DescriptionListDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the list did not choose",
+      "note": "A sixty-four character hash with nowhere to break, a German compound term, and a right-to-left pair. The value breaks rather than leaving the box, and the term track stops at the width you set for it.",
+      "language": "tsx",
+      "source": "<DescriptionList termWidth=\"10rem\">\n  <DescriptionListItem>\n    <DescriptionListTerm>Rechnungsempfängeradresse</DescriptionListTerm>\n    <DescriptionListDescription>Friedrichstraße 12, 10117 Berlin</DescriptionListDescription>\n  </DescriptionListItem>\n</DescriptionList>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard and announcement",
+      "note": "The family owns no key of its own: every control is a native button or your own link, so Tab, Enter and Space are the platform. Enter and Space are told apart from a press in the reason the request carries.",
+      "language": "tsx",
+      "source": "// Copy announces politely; the toggle carries aria-expanded;\n// the action is described by its own term.\n<DescriptionListDescription\n  clamp={2}\n  copy\n  onRevealedChange={(next, request) => log(request.reason)}\n>\n  {note}\n</DescriptionListDescription>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}