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

package/docs/list.md

@@ -0,0 +1,185 @@
+<!-- index: ./index.md -->
+# list
+
+`data-ui="list"` · Vertical list of items with sections.
+
+## Import
+
+```ts
+import { SlList, SlListEmpty, SlListSection, SlListSectionLabel, SlListSectionList } from '@slotted/angular/list';
+```
+
+Selector: `ul[slList], ol[slList], li[slListSection], [slListSectionLabel], ul[slListSectionList], ol[slListSectionList], li[slListEmpty]` · exportAs: `slList, slListSection, slListSectionLabel, slListSectionList, slListEmpty`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<ul slList variant="ruled" aria-label="Folders">
+  <li slListItem>
+    <a slListItemContent href="/photos">
+      <span slListItemBody><span slListItemLabel>Photos</span></span>
+      <span slListItemEnd>128</span>
+    </a>
+  </li>
+</ul>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | ul or ol, or the element render returns | yes |
+| `section` | li | no |
+| `section-label` | h1 to h6, or a div | no |
+| `section-list` | ul or ol | no |
+| `empty` | li | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `'plain' \| 'ruled' \| 'framed' \| 'separated'` | plain | slList | How the rows are told apart: by rhythm, by a rule, by a box around them, or by a surface each |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slList | The room a row gets. Density is the application's choice; this is this list's |
+| `marker` | `'none' \| 'bullet' \| 'number'` | none | slList | What is painted in the marker column. The family draws it, so it never disappears with the semantics |
+| `ordered` | `boolean` | false | the element | Not an input: the page writes ul or ol itself, because the element is what carries the reading order |
+| `inset` | `boolean` | false | slList | Takes the rows inline padding away, for a list inside a box that already pads its content |
+| `loading` | `boolean` | false | slList | Writes aria-busy on the set. What stands in for the rows is slSkeleton, composed by the page |
+| `level` | `'none' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6'` | 3 | the element | Not an input: slListSectionLabel goes on the heading the page wrote, at whatever level the document needs |
+| `sticky` | `boolean` | false | slListSectionLabel | Keeps a group name in place while its own rows scroll past it |
+| `id` | `string` | — | slListSectionLabel | The heading own id, which the nested list is named by. Generated when the page wrote none |
+| `exportAs` | `slList \| slListSection \| slListSectionLabel \| slListSectionList \| slListEmpty` | — | every directive | Reaches the instance from a template |
+| `aria-label / aria-labelledby` | `string` | — | slList | The set own name, written on the element. The family adds no label of its own |
+| `role` | `string` | list | slList, slListSectionList | Written by the family, and never over a role the page wrote itself |
+| `provideListDefaults` | `{ variant, size, marker, inset }` | — | an injector | Sets the four once for every list under it; an explicit input still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `plain`, `ruled`, `framed`, `separated` | `plain` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `marker` | `none`, `bullet`, `number` | `none` |
+
+## Rules
+
+- The Authoring Practices publish no pattern for a static list. They name Listbox and Grid for interactive collections and nothing between those and plain content, so what governs here is HTML and the ARIA roles model.
+- role="list" is written on the root and on every nested group, and it is not redundant. The family draws its own marker — a row is a content box beside its independent targets, and CSS has no display that is both list-item and a grid — and Safari with VoiceOver drops list semantics the moment CSS removes the marker. A role the page wrote itself is read with HostAttributeToken before the host binding runs, so a menu or a listbox the page is wiring keeps its own.
+- The directive goes on the element the page wrote, ul or ol, because the element carries the reading order and that is the page decision rather than the family one. React reads the element off an ordered prop instead, because there the component owns the tag.
+- A group is an li holding a heading and a nested list, which is the grouping HTML already has, and the nested list names itself by that heading. The heading keeps whatever level the document needs, because slListSectionLabel is a directive on the page own element.
+- loading writes aria-busy on the set, which ARIA 1.2 §5.2.6 asks of a container whose rows have not arrived yet. It draws no spinner and no placeholder: slSkeleton owns that geometry and goes inside the rows.
+- The empty message is an li inside the list. Outside it, a reader hears "list, zero items" and then nothing, and the words fall outside the box a framed set paints.
+- The set binds no key. Arrows, Home, End and typeahead belong to a collection, and a role="list" that answers them is the invented keyboard the feature guide refuses — that model is Listbox and Table in wave 6.
+- The set holds no value a consumer can own, so it declares no model, emits no output and needs no ControlValueAccessor. A selection is painted by the row and announced by the slCheckbox the page composes into it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-line-height-sm`, `--slotted-list-background`, `--slotted-list-border-color`, `--slotted-list-border-width`, `--slotted-list-empty-color`, `--slotted-list-empty-padding`, `--slotted-list-empty-padding-lg`, `--slotted-list-empty-padding-sm`, `--slotted-list-gap`, `--slotted-list-gap-lg`, `--slotted-list-gap-sm`, `--slotted-list-padding-inline`, `--slotted-list-padding-inline-lg`, `--slotted-list-padding-inline-sm`, `--slotted-list-radius`, `--slotted-list-section-color`, `--slotted-list-section-font-size`, `--slotted-list-section-font-weight`, `--slotted-list-section-letter-spacing`, `--slotted-list-section-padding-block`, `--slotted-list-section-padding-block-lg`, `--slotted-list-section-padding-block-sm`, `--slotted-radius-md`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface`, `--slotted-text-muted`, `--slotted-z-index-sticky`
+
+## Examples
+
+### Telling the rows apart
+
+Four words, and they are accordion’s four so that two families cannot mean different things by one of them. Only separated spends a gap; the other three separate with a line or with nothing.
+
+Excerpt — not a complete module
+
+```html
+<ul slList variant="plain"></ul>
+<ul slList variant="ruled"></ul>
+<ul slList variant="framed"></ul>
+<ul slList variant="separated"></ul>
+```
+
+### The mark, and the order
+
+The element carries the reading order and the input carries the painted mark, which is why an ordered set can paint its own badges and still read in order. The bullet is drawn geometry rather than a character.
+
+Excerpt — not a complete module
+
+```html
+<ul slList marker="bullet"></ul>
+<ol slList marker="number"></ol>
+<ol slList></ol>
+```
+
+### Groups
+
+A group is an li holding a heading and a nested list, and the nested list names itself by that heading. The heading keeps whatever level the document needs, because the directive goes on the page own element.
+
+Excerpt — not a complete module
+
+```html
+<li slListSection>
+  <h3 slListSectionLabel sticky>Folders</h3>
+  <ul slListSectionList>
+    <ng-container [ngTemplateOutlet]="folderRows" />
+  </ul>
+</li>
+```
+
+### A set inside a padded box
+
+inset takes the rows inline padding away so the titles line up with the box around them. The rule and the hover fill still run edge to edge, which is the half disableGutters leaves out elsewhere.
+
+Excerpt — not a complete module
+
+```html
+<ul slList inset variant="ruled" aria-label="Members">
+  <ng-container [ngTemplateOutlet]="memberRows" />
+</ul>
+```
+
+### Loading, and empty
+
+loading writes aria-busy and draws nothing: slSkeleton stands in for the rows. The empty message is an li inside the set, so a reader hears it rather than hearing zero items and then silence.
+
+Excerpt — not a complete module
+
+```html
+<ul slList loading variant="ruled" aria-label="Folders"></ul>
+<ul slList variant="framed" aria-label="Results">
+  <li slListEmpty>No matches</li>
+</ul>
+```
+
+### Content the family did not choose
+
+A page of a larger set says where the reader is with position and setSize, and only then. A set in another script mirrors its marker column, its inset and its metadata, because every rule is a logical property.
+
+Excerpt — not a complete module
+
+```html
+<ul slList variant="ruled" aria-label="Results 41 to 43 of 128">
+  <li slListItem [position]="41" [setSize]="128"></li>
+</ul>
+```
+
+### The families beside it
+
+The set supplies the box and the rhythm. slCheckbox announces the selection a row paints, slBadge carries a count, and the rows answer their own width while the set does not.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideListDefaults({ size: 'sm', variant: 'ruled' })],
+});
+```
+
+### The role, and the landmark
+
+The family writes role="list" because it draws its own marker, and reads a role the page wrote with HostAttributeToken before the binding runs. A nav is the page decision, so the family writes none.
+
+Excerpt — not a complete module
+
+```html
+<nav aria-label="Sections">
+  <ul slList>
+    <li slListItem current="page">
+      <a slListItemContent href="/billing">Billing</a>
+    </li>
+  </ul>
+</nav>
+```