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

package/docs/data-list.md

@@ -0,0 +1,327 @@
+<!-- index: ./index.md -->
+# data-list
+
+`data-ui="data-list"` · Records as stacked label and value items.
+
+## Import
+
+```ts
+import {
+  SlDataList,
+  SlDataListCellTemplate,
+  SlDataListFooter,
+  SlDataListMediaTemplate,
+  provideDataListDefaults,
+} from '@slotted/angular/data-list';
+import type { GridColumn, GridQuery } from '@slotted/core/grid';
+```
+
+Selector: `sl-data-list` · exportAs: `slDataList`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list
+  label="Accounts"
+  rowKey="id"
+  selectionMode="multiple"
+  subtitle="email"
+  trailing="balance"
+  [columns]="columns"
+  [rows]="accounts"
+  [(query)]="query"
+  [(value)]="chosen"
+/>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-data-list | yes |
+| `header` | div | yes |
+| `select-all` | span holding [slCheckbox] | no |
+| `count` | output aria-live="polite" | yes |
+| `sort` | span holding button[slButton][slMenuTriggerFor] | no |
+| `selection` | span in [slListItemStart] holding [slCheckbox] | no |
+| `media` | span in [slListItemStart] | no |
+| `title` | a \| button \| span in [slListItemLabel] | yes |
+| `fields` | dl | no |
+| `field` | div | no |
+| `field-label` | dt | no |
+| `field-value` | dd | no |
+| `field-empty` | span | no |
+| `more` | button | no |
+| `trailing` | span in [slListItemEnd] | no |
+| `empty` | div holding section[slResultState] | no |
+| `loader` | div holding div[slSkeletonRegion] | no |
+| `footer` | div | no |
+| `load-more` | span holding button[slButton] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `rows` | `readonly Row[]` | — | sl-data-list | The consumer’s array |
+| `rowKey` | `keyof Row \| (row) => string` | — | sl-data-list | Names every record in every state model |
+| `columns` | `readonly GridColumn<Row>[]` | — | sl-data-list | The model sl-data-grid, sl-column-manager and sl-saved-views read |
+| `columnState` | `Partial<GridColumnState>` | — | sl-data-list | Order and hidden columns; widths and pins are ignored |
+| `title` | `string` | rowHeader column | sl-data-list | The title’s column |
+| `subtitle` | `string` | — | sl-data-list | The column under the title |
+| `trailing` | `string` | — | sl-data-list | The column at the end of the row |
+| `fields` | `number` | 4 | sl-data-list, provideDataListDefaults | How many fields a closed record shows |
+| `label` | `string` | — | sl-data-list | The list’s accessible name; an aria-label written on the host is read when label is absent |
+| `labelledBy` | `string` | — | sl-data-list | The id of the element that names the list |
+| `query` | `model<GridQuery>` | emptyQuery() | sl-data-list | Sort, filter, search, page and group; [(query)] binds it both ways |
+| `mode` | `"client" \| "server"` | client | sl-data-list | client applies the query; server draws the rows given. server when totalCount is given |
+| `totalCount` | `number` | — | sl-data-list | The server’s total, for the count and server mode |
+| `selectionMode` | `"none" \| "single" \| "multiple"` | none | sl-data-list, provideDataListDefaults | A checkbox per record in single and multiple |
+| `value` | `model<string \| null \| readonly string[]>` | null | sl-data-list | The selection; [(value)] binds it both ways |
+| `expanded` | `model<readonly string[]>` | [] | sl-data-list | Records that show every field; [(expanded)] binds it both ways |
+| `disabledKeys` | `readonly string[]` | [] | sl-data-list | Records that refuse selection and activation |
+| `loadingKeys` | `readonly string[]` | [] | sl-data-list | Records busy with an action: aria-busy, activation refused |
+| `current` | `string \| null` | — | sl-data-list | The record open beside the list; aria-current on its row |
+| `href` | `(row) => string` | — | sl-data-list | Makes the title a link |
+| `activatable` | `boolean` | false | sl-data-list | Makes the title a button that emits activate |
+| `loading` | `boolean` | false | sl-data-list | The skeleton with no rows, a dimmed refresh over rows, the load-more wait |
+| `error` | `boolean \| string \| null` | — | sl-data-list | The error state; a string replaces messages.errorTitle |
+| `hasMore` | `boolean` | false | sl-data-list | Shows load-more in the footer |
+| `variant` | `"plain" \| "ruled" \| "framed"` | ruled | sl-data-list, provideDataListDefaults | The list’s variant, handed to every record |
+| `size` | `"sm" \| "md" \| "lg"` | md | sl-data-list, provideDataListDefaults | The record’s control step |
+| `skeletonRows` | `number` | 5 | sl-data-list, provideDataListDefaults | Records the first-load skeleton draws |
+| `loadingDelay` | `number` | 200 | sl-data-list, provideDataListDefaults | Milliseconds before the skeleton appears |
+| `loadingMinDuration` | `number` | 400 | sl-data-list, provideDataListDefaults | Milliseconds the skeleton stays once drawn |
+| `messages` | `Partial<DataListMessages>` | — | sl-data-list | Words laid over the language in force, key by key; count and selectAll are plural messages |
+| `locale` | `string` | the provider’s | sl-data-list | Formats values, group counts and the sort |
+| `slDataListCell` | `ng-template` | — | content | Draws a column’s value; context { $implicit: row, row, column, key, value, text, place } |
+| `slDataListMedia` | `ng-template` | — | content | The picture at the start of a record; $implicit is the row |
+| `slDataListEmpty` | `ng-template` | — | content | Replaces empty, no-results or error; $implicit is the status |
+| `slDataListFooter` | `directive` | — | content | Content projected into the footer, beside load-more |
+| `exportAs` | `slDataList` | — | sl-data-list | focus(), focusKey(key), scrollToKey(key) |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `queryChangeRequest` | `DataListQueryRequest: { value, previous, reason, change, source, cancelled, cancel() }` | Before [(query)] moves: sort from the menu (pointer, keyboard), filter from Clear filters (clear). change names the part: sort \| filter \| search \| page \| group. cancel() keeps the query. |
+| `valueChangeRequest` | `ChangeRequest<string \| null \| readonly string[]>` | Before [(value)] moves: a checkbox (pointer, keyboard), Shift from the anchor or select-all (select), select-all clearing (clear). |
+| `expandedChangeRequest` | `DataListExpandedRequest: { value, key, reason, … }` | Before [(expanded)] moves, from a record’s more button. |
+| `activate` | `{ key, row, reason: "pointer" \| "keyboard", event }` | After the title is pressed: a button with activatable, or a link with href before it navigates. Not for a disabled or loading record. |
+| `loadMore` | `void` | The load-more button in the footer was pressed. |
+| `retry` | `void` | Try again in the error state was pressed. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `plain`, `ruled`, `framed` | `ruled` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `selectionMode` | `none`, `single`, `multiple` | `none` |
+| `mode` | `client`, `server` | — |
+| `activatable` | `true`, `false` | `false` |
+
+## Rules
+
+- No Authoring Practices pattern covers a list of records, so the family is list’s role="list" of list items, named by label or labelledBy, and every control in it is native: a checkbox, a link or a button, the disclosure pattern for more and the menu button pattern for sort.
+- The title is the record’s link or button and its name is the title alone; the fields sit outside it as a dl, because a dl may not sit inside a button and a link named by every field is a sentence. The checkbox is named “Select {title}” and announces the selection the row paints — aria-selected is not valid on listitem.
+- No arrow key is bound: role="list" admits none and the scope refuses grid navigation. Tab reaches each control in reading order; sl-data-grid is the family for a cell cursor. When the focused record is removed, focus moves to the next record, the previous one, or the empty state.
+- The count is an output announced politely; a sort announces the whole order through the shared live announcer. The first load is a skeleton region with one polite announcement and aria-busy, and an absent value reads messages.empty beside the dash a sighted reader sees.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-md`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--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-sm`, `--slotted-line-height-xs`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-8`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`
+
+## Examples
+
+### Anatomy
+
+Every part on one record: the checkbox and the avatar at the start, the title as a link, the subtitle, the balance at the end, four fields, the disclosure for more, and the row’s actions.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list label="Accounts" rowKey="id" [columns]="columns" [rows]="accounts">
+  <ng-template slDataListMedia let-account>
+    <span slAvatar size="sm" [name]="account.name"></span>
+  </ng-template>
+  <ng-template slDataListCell="status" let-row>
+    <span slBadge size="sm">{{ row.status }}</span>
+  </ng-template>
+</sl-data-list>
+```
+
+### Fields by priority, at two widths
+
+The same record at 375 and 640 pixels. Priority orders the pairs; a phone gives one pair a line with the label beside the value, a tablet two and three columns of label over value.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list label="Accounts" rowKey="id" [columns]="columns" [fields]="6" [rows]="accounts" />
+```
+
+### A link, a command, or text
+
+With href the title is a link and the whole record is its target; with activatable it is a button that emits activate; with neither the record is only read. The current record carries the neutral ground.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list activatable [current]="openId()" (activate)="openId.set($event.key)" />
+```
+
+### Selection
+
+Multiple: the checkbox in each record, Shift to extend from the anchor, select-all over every record the query left and the count saying how many are chosen. Single holds one key, as table does.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list selectionMode="multiple" [(value)]="chosen" />
+```
+
+### Sorting without a header
+
+The sort control is a menu of the sortable columns and a direction. The trigger names the first key; a query sorted by several keys in sl-data-grid shows +1 and the announcement reads the whole order.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list [(query)]="query" (queryChangeRequest)="refetch($event.change)" />
+```
+
+### Filtering with a search field
+
+The list applies query.search and query.filter; the control that writes them is the application’s own, bound to the same query. Type “lis” to keep the Lisbon accounts.
+
+Excerpt — not a complete module
+
+```html
+<input slTextFieldInput [value]="query().search" (input)="search($event)" />
+<sl-data-list [(query)]="query" />
+```
+
+### Groups
+
+query.group becomes list sections, each named by the column, the value and the count. The groups stay open: a list has no collapsible group row.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list [query]="{ sort: [], filter: null, search: '', page: null, group: ['status'] }" />
+```
+
+### The fields past the first few
+
+fields sets how many a closed record shows. Show 3 more opens the rest in the same grid, and the expansion is a set of keys bound in both directions, like the grid’s detail.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list [fields]="2" [(expanded)]="open" />
+```
+
+### Record states
+
+Selected, current, disabled and loading on four records: selected is the accent ground with its edge, current the neutral one, disabled and loading recede and refuse the activation while keeping their width.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list
+  activatable
+  current="cobalt"
+  selectionMode="multiple"
+  [disabledKeys]="['dunmore']"
+  [loadingKeys]="['borealis']"
+  [value]="['acme']"
+/>
+```
+
+### The first load, and a refresh
+
+With no rows the loader draws the record’s anatomy: title, subtitle, balance and four fields with their real labels. Over rows already shown a refresh keeps them and dims them; nothing moves.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list [loading]="fetching()" [rows]="accounts() ?? []" />
+```
+
+### Empty, no results, error
+
+Three states, each with its own next step: nothing yet, a query that left nothing and offers Clear filters, and a failure that offers Try again.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list [error]="failed()" [rows]="rows()" (retry)="refetch()" />
+```
+
+### Load more
+
+With hasMore the footer asks for the next page through loadMore; the button carries the wait and the list stays readable. The count says how many exist when the server gives totalCount.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list
+  [hasMore]="page().hasMore"
+  [loading]="fetching()"
+  [rows]="page().rows"
+  [totalCount]="page().total"
+  (loadMore)="fetchNext()"
+/>
+```
+
+### Beside table, on one state
+
+createWidthGate at COMPACT_BELOW swaps the table and the list over the same sort and selection. Choose Phone: under 600 pixels the list takes over and the chosen accounts stay chosen.
+
+Excerpt — not a complete module
+
+```html
+@if (compact()) {
+  <sl-data-list
+    [query]="asQuery(sort())"
+    [(value)]="chosen"
+    (queryChangeRequest)="fromQuery($event)"
+  />
+} @else {
+  <div slTable selectionMode="multiple" [(sort)]="sort" [(value)]="chosen"></div>
+}
+```
+
+### Content the columns did not plan for
+
+A title in two lines, an address with no break in it, labels a translation made long and a value in another script: the pairs wrap, nothing is cut, and the Arabic value takes its own direction.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];
+```
+
+### Keyboard
+
+Tab moves through select-all, the sort trigger, then each record’s checkbox, title, disclosure and actions. Space toggles a checkbox, Shift+Space extends from the anchor, Enter follows the title. No arrow key is bound.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-list #accounts="slDataList" />
+<button slButton (click)="accounts.focusKey('cobalt')">Focus Cobalt Studio</button>
+```
+
+### What a reader hears
+
+The list is named by the heading above it; each record is a list item whose title is its link; the checkbox is named Select and the title; the count and the sort order are announced politely.
+
+Excerpt — not a complete module
+
+```html
+<h2 id="accounts-heading">Accounts</h2>
+<sl-data-list labelledBy="accounts-heading" />
+```