@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/datetime-range-picker.md

@@ -0,0 +1,162 @@
+<!-- index: ./index.md -->
+# datetime-range-picker
+
+`data-ui="datetime-range-picker"` · Start and end date-times with a picker.
+
+## Import
+
+```ts
+import { SlDateTimeRangePicker, SlDateTimeRangePickerPreset, SlDateTimeRangePickerPresets, SlDateTimeRangePickerFooter, SlDateTimeRangePickerOption } from '@slotted/angular/datetime-range-picker';
+```
+
+Selector: `[slDateTimeRangePicker]` · exportAs: `slDateTimeRangePicker`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Retirada e devolução</label>
+  <div
+    slDateTimeRangePicker
+    clearable
+    locale="pt-BR"
+    [messages]="{ start: 'Retirada', end: 'Devolução' }"
+    [defaultValue]="rental"
+  ></div>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element | 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` | — | SlDateTimeRangePicker | { start, end }, each end nullable. Present means the consumer owns it. Both ends null is null. |
+| `defaultValue` | `DateTimeRange \| null` | — | SlDateTimeRangePicker | What it starts from when nobody else writes one. Read once. |
+| `open` | `boolean` | — | SlDateTimeRangePicker | Whether the surface is showing. Present means the consumer owns it. |
+| `defaultOpen` | `boolean` | false | SlDateTimeRangePicker | Whether it opens already showing. |
+| `position` | `'start' \| 'end'` | — | SlDateTimeRangePicker | 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 | SlDateTimeRangePicker | Where editing starts. |
+| `highlighted` | `{ start: PlainTime \| null; end: PlainTime \| null }` | — | SlDateTimeRangePicker | 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 }` | — | SlDateTimeRangePicker | Where the highlights start; otherwise a list opens on its end, or on the nearest offered step. |
+| `min` | `PlainDateTime` | — | SlDateTimeRangePicker | 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` | — | SlDateTimeRangePicker | Where the range ends; its time bounds the last day only. |
+| `minTime` | `PlainTime` | — | SlDateTimeRangePicker | The earliest time on every day inside the range, applied together with min — the pair MUI declines to combine. |
+| `maxTime` | `PlainTime` | — | SlDateTimeRangePicker | The latest time on every day inside the range. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlDateTimeRangePicker | Refuses whole days. The grid greys them and a list on such a day is empty. |
+| `isTimeUnavailable` | `(time: PlainTime, date: PlainDate) => boolean` | — | SlDateTimeRangePicker | Refuses one time on one day. Asked once per row of a list, on the day that list serves. |
+| `contiguous` | `boolean` | true | SlDateTimeRangePicker | 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` | — | SlDateTimeRangePicker | The shortest run allowed, in seconds. The grid and the list refuse shorter ones and the band names the limit. |
+| `maxLength` | `number` | — | SlDateTimeRangePicker | The longest run allowed, in seconds. |
+| `lengthLabel` | `(seconds: number, locale?: string) => string` | durationLabel | SlDateTimeRangePicker | 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 | SlDateTimeRangePicker | 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[]` | — | SlDateTimeRangePicker | The times to offer, stated rather than stepped; the same list for both ends. The bounds and the predicate still refuse. |
+| `maxOptions` | `number` | 1440 | SlDateTimeRangePicker | 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 | SlDateTimeRangePicker | What a refused time looks like in a list: drawn muted with aria-disabled, or left out. |
+| `months` | `number` | 1 | SlDateTimeRangePicker | 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` | — | SlDateTimeRangePicker | Draws the ISO week number beside each row of the grid. |
+| `fixedWeeks` | `boolean` | true | SlDateTimeRangePicker | Six rows whatever the month needs, so a press of "next" moves no target. |
+| `locale` | `string` | provideSlotted | SlDateTimeRangePicker | 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` | — | SlDateTimeRangePicker | The zone "now" is read in. |
+| `hourCycle` | `12 \| 24` | — | SlDateTimeRangePicker | Twelve- or twenty-four-hour times. Unset, the locale decides. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | SlDateTimeRangePicker | How much of a time the fields and the rows write. |
+| `calendar` | `'gregory'` | gregory | SlDateTimeRangePicker | The calendar system. One today. |
+| `firstDayOfWeek` | `number` | — | SlDateTimeRangePicker | Which day the grid’s week starts on. Unset, the locale decides. |
+| `yearPivot` | `number` | — | SlDateTimeRangePicker | The pivot two typed year digits are resolved through. |
+| `referenceDateTime` | `PlainDateTime` | — | SlDateTimeRangePicker | 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 | SlDateTimeRangePicker | The control scale of the frame. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlDateTimeRangePicker | How much frame the control shows at rest. |
+| `placement` | `'bottom-start' \| 'bottom' \| 'bottom-end' \| 'top-start' \| 'top' \| 'top-end'` | bottom-start | SlDateTimeRangePicker | Where the surface opens, before the positioner has read the room. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | SlDateTimeRangePicker | auto closes when a press completes the work; always closes on any press that changes the value; never closes on none. |
+| `disabled` | `boolean` | — | SlDateTimeRangePicker | Nothing answers; the value stays readable. |
+| `readOnly` | `boolean` | — | SlDateTimeRangePicker | Legible and copyable; the trigger and the clear are out of the tab sequence. |
+| `invalid` | `boolean` | — | SlDateTimeRangePicker | The consumer’s own word. Set, it wins; unset, the family’s own rules and the field around it decide. |
+| `required` | `boolean` | — | SlDateTimeRangePicker | Reaches both fields as aria-required. |
+| `clearable` | `boolean` | false | SlDateTimeRangePicker | Draws one clear on the frame, which empties both ends. |
+| `relative` | `boolean` | — | SlDateTimeRangePicker | Whether the field in the band takes the relative expression — +2d, 1h30, = — the way a datetime-field does. |
+| `messages` | `Partial<DatetimeRangePickerMessages>` | — | SlDateTimeRangePicker | 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` | — | SlDateTimeRangePicker | The name of the hidden input carrying the start. |
+| `endName` | `string` | — | SlDateTimeRangePicker | The name of the hidden input carrying the end. |
+| `slDateTimeRangePickerPresets` | `Directive` | — | SlDateTimeRangePicker | The consumer’s own shortcuts, as a directive on their own element holding slDateTimeRangePickerPreset buttons. |
+| `slDateTimeRangePickerFooter` | `Directive` | — | SlDateTimeRangePicker | The consumer’s own actions, before done in the footer, as a directive on their own element. |
+| `slDateTimeRangePickerOption` | `Directive on ng-template` | — | SlDateTimeRangePicker | What one row draws. The context carries the time as $implicit, plus position, date, label, duration, selected, current and unavailable. |
+| `slDateTimeRangePickerPreset` | `DateTimeRange \| (() => DateTimeRange)` | — | SlDateTimeRangePickerPreset | The range the press writes, or a function resolving it at the press. |
+| `provideDateTimeRangePickerDefaults` | `Provider` | — | application | Sets timeZone, calendar, firstDayOfWeek, months, hourCycle, granularity, step, maxOptions, unavailableOptions, closeOnSelect, placement, size, variant and lengthLabel once for everything under the injector. The locale and the words come from provideSlotted. |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | SlDateTimeRangePicker | The whole { start, end } is the control’s value, and the family reports what no other validator can see: slottedDateTimeRangeOrder, slottedDateTimeRangeMin, slottedDateTimeRangeMax, slottedDateTimeRangeUnavailable and slottedDateTimeRangeLength. |
+| `exportAs` | `slDateTimeRangePicker` | — | SlDateTimeRangePicker | Hands a template the instance, so focus(), openSurface(), closeSurface() and choose(range) are reachable without a component of its own. |
+| `ng-content slots` | `slDateTimeRangePickerPresets, slDateTimeRangePickerFooter` | — | SlDateTimeRangePicker | The two places a consumer fills, as directives on their own elements, so a button, a list or a toolbar all keep their own semantics. |
+| `slDateTimeRangePickerOption` | `Directive on ng-template` | — | list | One row’s content, rendered once per option with the time, its label and its duration in the context; the row itself — role, states, keyboard, target size — stays the family’s. |
+| `slDateTimeRangePickerPreset` | `Directive on button` | — | presets | One shortcut on the consumer’s own button: it takes the range, writes data-part and type, and composes the click — a handler that calls preventDefault keeps the value where it was. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `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. There is no two-way [(value)]: a form control carries it instead. |
+| `openChange` | `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. |
+| `positionChange` | `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. |
+| `highlightedChange` | `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/docs/description-list.json

@@ -0,0 +1,471 @@
+{
+  "family": "description-list",
+  "ui": "description-list",
+  "binding": "angular",
+  "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  SlDescriptionList,\n  SlDescriptionListAction,\n  SlDescriptionListDescription,\n  SlDescriptionListHint,\n  SlDescriptionListItem,\n  SlDescriptionListTerm,\n  provideDescriptionListDefaults,\n} from '@slotted/angular/description-list';",
+        "selector": "div[slDescriptionList]",
+        "exportAs": "slDescriptionList"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div[slDescriptionList], exportAs=\"slDescriptionList\"",
+          "required": true,
+          "purpose": "The consumer’s own div, which is 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, drawn by the component",
+          "required": true,
+          "purpose": "The grid. It declares the term track, the value track and the action track, and every pair borrows them with subgrid. Pairs are projected into it."
+        },
+        {
+          "part": "item",
+          "element": "div[slDescriptionListItem], exportAs=\"slDescriptionListItem\"",
+          "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[slDescriptionListTerm], exportAs=\"slDescriptionListTerm\"",
+          "required": true,
+          "purpose": "The name. It carries the identifier the row action is described by, and a static id the consumer wrote wins over it."
+        },
+        {
+          "part": "hint",
+          "element": "[slDescriptionListHint], exportAs=\"slDescriptionListHint\"",
+          "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[slDescriptionListDescription], exportAs=\"slDescriptionListDescription\"",
+          "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, drawn by the component",
+          "required": true,
+          "purpose": "The value itself, and the one part a clamp applies to. Projected content lands inside it, so the clamp, the copy target and the controls have one stable place."
+        },
+        {
+          "part": "placeholder",
+          "element": "span, drawn by the component",
+          "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, drawn by the component",
+          "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, drawn by the component",
+          "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[slDescriptionListAction], exportAs=\"slDescriptionListAction\"",
+          "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": "slDescriptionList",
+          "description": "The term beside its value, or above it"
+        },
+        {
+          "name": "columns",
+          "type": "1 | 2 | 3",
+          "defaultValue": "1",
+          "appliesTo": "slDescriptionList",
+          "description": "How many pairs stand side by side"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed'",
+          "defaultValue": "plain",
+          "appliesTo": "slDescriptionList",
+          "description": "Nothing between pairs, a rule between them, or a framed table"
+        },
+        {
+          "name": "termWidth",
+          "type": "string",
+          "defaultValue": "14rem",
+          "appliesTo": "slDescriptionList",
+          "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": "slDescriptionList",
+          "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": "slDescriptionListItem",
+          "description": "How many columns the pair takes, clamped to the count the list has"
+        },
+        {
+          "name": "clamp",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "slDescriptionListDescription",
+          "description": "Lines the value is held to before it is revealed; 0 never clamps"
+        },
+        {
+          "name": "copy",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slDescriptionListDescription",
+          "description": "Draws the control that puts the value on the clipboard"
+        },
+        {
+          "name": "copyValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slDescriptionListDescription",
+          "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": "slDescriptionListDescription",
+          "description": "Draws the placeholder. Angular cannot read projected content without reading the DOM, so the absence is stated here where React reads nullish children"
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slDescriptionListDescription",
+          "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": "slDescriptionListDescription",
+          "description": "Present means controlled, for the life of the component"
+        },
+        {
+          "name": "defaultRevealed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slDescriptionListDescription",
+          "description": "What an uncontrolled description starts from, read once"
+        }
+      ],
+      "composition": [
+        {
+          "name": "ng-content",
+          "type": "projection",
+          "defaultValue": "—",
+          "appliesTo": "slDescriptionList, slDescriptionListDescription",
+          "description": "Pairs are projected into the dl the component draws, and a value into the span that holds it"
+        },
+        {
+          "name": "exportAs",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "every directive",
+          "description": "Reaches the instance from the template: slDescriptionList, slDescriptionListItem, slDescriptionListTerm, slDescriptionListHint, slDescriptionListDescription, slDescriptionListAction"
+        },
+        {
+          "name": "provideDescriptionListDefaults()",
+          "type": "DescriptionListDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets layout, columns, variant and termWidth once for everything below it; an input on the list still wins"
+        },
+        {
+          "name": "id / aria-describedby",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slDescriptionListTerm, slDescriptionListAction",
+          "description": "A static attribute you wrote survives the host binding: the term keeps your id, and the action composes your description with the term’s"
+        },
+        {
+          "name": "content",
+          "type": "projection",
+          "defaultValue": "—",
+          "appliesTo": "slDescriptionListDescription",
+          "description": "A tag, a status indicator, a link or a skeleton — the value slot takes what the row needs"
+        }
+      ],
+      "events": [
+        {
+          "name": "revealedChange",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Before a clamped value is revealed or clamped again. The request carries the value, the value it replaces, the reason — pointer, keyboard or programmatic — and the originating event, and cancelling it commits nothing. It is not the second half of a two-way binding: one slot could carry none of those."
+        },
+        {
+          "name": "copied",
+          "payload": "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 static aria-describedby you wrote is read with HostAttributeToken and 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": "html",
+      "source": "<div slDescriptionList>\n  <div slDescriptionListItem>\n    <dt slDescriptionListTerm>Environment</dt>\n    <dd slDescriptionListDescription>Production</dd>\n  </div>\n</div>\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": "html",
+      "source": "<div slDescriptionList layout=\"row\"></div>\n<div slDescriptionList layout=\"stack\"></div>\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": "html",
+      "source": "<div slDescriptionList [columns]=\"2\">\n  <!-- pairs -->\n</div>\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": "html",
+      "source": "<div slDescriptionList variant=\"plain\"></div>\n<div slDescriptionList variant=\"ruled\"></div>\n<div slDescriptionList variant=\"framed\"></div>\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": "html",
+      "source": "<div slDescriptionList [columns]=\"2\">\n  <div slDescriptionListItem [span]=\"2\">\n    <dt slDescriptionListTerm>Endpoint</dt>\n    <dd slDescriptionListDescription>db.eu-west-2.example.com:5432</dd>\n  </div>\n</div>\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": "html",
+      "source": "<div slDescriptionListItem>\n  <dt slDescriptionListTerm>Name</dt>\n  <dd slDescriptionListDescription>Sarah Phillips</dd>\n  <dd slDescriptionListAction><a slLink href=\"/name\">Change</a></dd>\n</div>\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. The empty input draws 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": "html",
+      "source": "<dd slDescriptionListDescription [empty]=\"!account.owner\">{{ account.owner }}</dd>\n\n<dd slDescriptionListDescription empty placeholder=\"Not set yet\"></dd>\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": "html",
+      "source": "<dt slDescriptionListTerm>\n  Retention\n  <span slDescriptionListHint>How long a deleted object stays recoverable.</span>\n</dt>\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": "html",
+      "source": "<dd slDescriptionListDescription copy (copied)=\"log($event.copied)\">\n  arn:aws:iam::421900075512:role/billing-reconciler\n</dd>\n\n<dd slDescriptionListDescription copy [copyValue]=\"account.iban\">\n  {{ account.iban | iban }}\n</dd>\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": "html",
+      "source": "<dd slDescriptionListDescription [clamp]=\"2\">{{ note }}</dd>\n\n<dd\n  slDescriptionListDescription\n  [clamp]=\"2\"\n  [revealed]=\"revealed()\"\n  (revealedChange)=\"revealed.set($event.value)\"\n>\n  {{ note }}\n</dd>\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 provideDescriptionListDefaults decides the arrangement for a whole application; the words come from the language in force.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideDescriptionListDefaults({ variant: 'ruled' })],\n});\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": "html",
+      "source": "<div slDescriptionList termWidth=\"10rem\">\n  <div slDescriptionListItem>\n    <dt slDescriptionListTerm>Rechnungsempfängeradresse</dt>\n    <dd slDescriptionListDescription>Friedrichstraße 12, 10117 Berlin</dd>\n  </div>\n</div>\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": "html",
+      "source": "<dd slDescriptionListDescription copy [clamp]=\"2\" (revealedChange)=\"log($event.reason)\">\n  {{ note }}\n</dd>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}