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

package/docs/description-list.md

@@ -0,0 +1,268 @@
+<!-- index: ./index.md -->
+# description-list
+
+`data-ui="description-list"` · Term and value pairs for record details.
+
+## Import
+
+```ts
+import {
+  SlDescriptionList,
+  SlDescriptionListAction,
+  SlDescriptionListDescription,
+  SlDescriptionListHint,
+  SlDescriptionListItem,
+  SlDescriptionListTerm,
+  provideDescriptionListDefaults,
+} from '@slotted/angular/description-list';
+```
+
+Selector: `div[slDescriptionList]` · exportAs: `slDescriptionList`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList>
+  <div slDescriptionListItem>
+    <dt slDescriptionListTerm>Environment</dt>
+    <dd slDescriptionListDescription>Production</dd>
+  </div>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div[slDescriptionList], exportAs="slDescriptionList" | yes |
+| `list` | dl, drawn by the component | yes |
+| `item` | div[slDescriptionListItem], exportAs="slDescriptionListItem" | yes |
+| `term` | dt[slDescriptionListTerm], exportAs="slDescriptionListTerm" | yes |
+| `hint` | [slDescriptionListHint], exportAs="slDescriptionListHint" | no |
+| `description` | dd[slDescriptionListDescription], exportAs="slDescriptionListDescription" | yes |
+| `value` | span, drawn by the component | yes |
+| `placeholder` | span, drawn by the component | no |
+| `copy` | button, drawn by the component | no |
+| `toggle` | button, drawn by the component | no |
+| `action` | dd[slDescriptionListAction], exportAs="slDescriptionListAction" | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `'row' \| 'stack'` | row | slDescriptionList | The term beside its value, or above it |
+| `columns` | `1 \| 2 \| 3` | 1 | slDescriptionList | How many pairs stand side by side |
+| `variant` | `'plain' \| 'ruled' \| 'framed'` | plain | slDescriptionList | Nothing between pairs, a rule between them, or a framed table |
+| `termWidth` | `string` | 14rem | slDescriptionList | The maximum width of the term column; the terms share one track sized to the widest of them, up to this |
+| `messages` | `PartialMessages<DescriptionListMessages>` | — | slDescriptionList | Words laid over the language in force, key by key: copy, copied, copyBlocked, reveal, collapse, placeholder |
+| `span` | `1 \| 2 \| 3` | 1 | slDescriptionListItem | How many columns the pair takes, clamped to the count the list has |
+| `clamp` | `number` | 0 | slDescriptionListDescription | Lines the value is held to before it is revealed; 0 never clamps |
+| `copy` | `boolean` | false | slDescriptionListDescription | Draws the control that puts the value on the clipboard |
+| `copyValue` | `string` | — | slDescriptionListDescription | The text that control copies. Absent, the rendered text is read at the moment of the press |
+| `empty` | `boolean` | false | slDescriptionListDescription | Draws the placeholder. Angular cannot read projected content without reading the DOM, so the absence is stated here where React reads nullish children |
+| `placeholder` | `string` | — | slDescriptionListDescription | Words shown in place of a value that is missing. Unset, the mark is drawn and the placeholder message is read instead |
+| `revealed` | `boolean` | — | slDescriptionListDescription | Present means controlled, for the life of the component |
+| `defaultRevealed` | `boolean` | false | slDescriptionListDescription | What an uncontrolled description starts from, read once |
+| `ng-content` | `projection` | — | slDescriptionList, slDescriptionListDescription | Pairs are projected into the dl the component draws, and a value into the span that holds it |
+| `exportAs` | `string` | — | every directive | Reaches the instance from the template: slDescriptionList, slDescriptionListItem, slDescriptionListTerm, slDescriptionListHint, slDescriptionListDescription, slDescriptionListAction |
+| `provideDescriptionListDefaults()` | `DescriptionListDefaults` | — | Application | Sets layout, columns, variant and termWidth once for everything below it; an input on the list still wins |
+| `id / aria-describedby` | `string` | — | slDescriptionListTerm, slDescriptionListAction | A static attribute you wrote survives the host binding: the term keeps your id, and the action composes your description with the term’s |
+| `content` | `projection` | — | slDescriptionListDescription | A tag, a status indicator, a link or a skeleton — the value slot takes what the row needs |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `revealedChange` | `ChangeRequest<boolean>` | 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. |
+| `copied` | `DescriptionListCopyRequest` | 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. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `layout` | `row`, `stack` | `row` |
+| `columns` | `1`, `2`, `3` | `1` |
+| `variant` | `plain`, `ruled`, `framed` | `plain` |
+
+## Rules
+
+- 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
+
+### Beside the term, or under it
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList layout="row"></div>
+<div slDescriptionList layout="stack"></div>
+```
+
+### More than one pair to a row
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList [columns]="2">
+  <!-- pairs -->
+</div>
+```
+
+### Nothing, a rule, or a frame
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList variant="plain"></div>
+<div slDescriptionList variant="ruled"></div>
+<div slDescriptionList variant="framed"></div>
+```
+
+### A pair that needs the whole row
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList [columns]="2">
+  <div slDescriptionListItem [span]="2">
+    <dt slDescriptionListTerm>Endpoint</dt>
+    <dd slDescriptionListDescription>db.eu-west-2.example.com:5432</dd>
+  </div>
+</div>
+```
+
+### A row you can go back and change
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionListItem>
+  <dt slDescriptionListTerm>Name</dt>
+  <dd slDescriptionListDescription>Sarah Phillips</dd>
+  <dd slDescriptionListAction><a slLink href="/name">Change</a></dd>
+</div>
+```
+
+### A value that is not there
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<dd slDescriptionListDescription [empty]="!account.owner">{{ account.owner }}</dd>
+
+<dd slDescriptionListDescription empty placeholder="Not set yet"></dd>
+```
+
+### A term that explains itself
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<dt slDescriptionListTerm>
+  Retention
+  <span slDescriptionListHint>How long a deleted object stays recoverable.</span>
+</dt>
+```
+
+### A value worth taking away
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<dd slDescriptionListDescription copy (copied)="log($event.copied)">
+  arn:aws:iam::421900075512:role/billing-reconciler
+</dd>
+
+<dd slDescriptionListDescription copy [copyValue]="account.iban">
+  {{ account.iban | iban }}
+</dd>
+```
+
+### A value longer than its row
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<dd slDescriptionListDescription [clamp]="2">{{ note }}</dd>
+
+<dd
+  slDescriptionListDescription
+  [clamp]="2"
+  [revealed]="revealed()"
+  (revealedChange)="revealed.set($event.value)"
+>
+  {{ note }}
+</dd>
+```
+
+### Inside a card, and beside the families it sits with
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideDescriptionListDefaults({ variant: 'ruled' })],
+});
+```
+
+### Content the list did not choose
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slDescriptionList termWidth="10rem">
+  <div slDescriptionListItem>
+    <dt slDescriptionListTerm>Rechnungsempfängeradresse</dt>
+    <dd slDescriptionListDescription>Friedrichstraße 12, 10117 Berlin</dd>
+  </div>
+</div>
+```
+
+### Keyboard and announcement
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<dd slDescriptionListDescription copy [clamp]="2" (revealedChange)="log($event.reason)">
+  {{ note }}
+</dd>
+```