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

package/docs/table.md

@@ -0,0 +1,290 @@
+<!-- index: ./index.md -->
+# table
+
+`data-ui="table"` · Semantic table with sorting, filters and selection.
+
+## Import
+
+```ts
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCaption,
+  SlTableCell,
+  SlTableColumnActions,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableDetail,
+  SlTableEmpty,
+  SlTableExpander,
+  SlTableFooter,
+  SlTableHead,
+  SlTableLoader,
+  SlTableRow,
+  SlTableRowHeader,
+  SlTableSelect,
+  SlTableSelectAll,
+  SlTableSort,
+  SlTableSummary,
+  provideTableDefaults,
+} from '@slotted/angular/table';
+```
+
+Selector: `div[slTable]` · exportAs: `slTable`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCaption,
+  SlTableCell,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableHead,
+  SlTableRow,
+  SlTableRowHeader,
+} from '@slotted/angular/table';
+import { SlTag, SlTagBody } from '@slotted/angular/tag';
+
+const USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });
+
+const TONE = {
+  Delivered: 'success',
+  'On hold': 'warning',
+  Processing: 'accent',
+  Shipped: 'secondary',
+} as const;
+
+const ORDERS = [
+  {
+    id: 'SO-10421',
+    customer: 'Alfreds Futterkiste',
+    warehouse: 'Reno',
+    status: 'Shipped',
+    total: 1240,
+  },
+  {
+    id: 'SO-10422',
+    customer: "Bon app'",
+    warehouse: 'Columbus',
+    status: 'Processing',
+    total: 860.5,
+  },
+  {
+    id: 'SO-10423',
+    customer: 'Ernst Handel',
+    warehouse: 'Savannah',
+    status: 'On hold',
+    total: 3410.25,
+  },
+  {
+    id: 'SO-10424',
+    customer: 'Folk och fä HB',
+    warehouse: 'Reno',
+    status: 'Delivered',
+    total: 512,
+  },
+  {
+    id: 'SO-10425',
+    customer: 'QUICK-Stop',
+    warehouse: 'Columbus',
+    status: 'Shipped',
+    total: 2088.9,
+  },
+] as const;
+
+@Component({
+  selector: 'app-table-basic',
+  imports: [
+    SlTable,
+    SlTableBody,
+    SlTableCaption,
+    SlTableCell,
+    SlTableColumnHeader,
+    SlTableContent,
+    SlTableHead,
+    SlTableRow,
+    SlTableRowHeader,
+    SlTag,
+    SlTagBody,
+  ],
+  template: `
+    <div slTable [columns]="5">
+      <div slTableContent>
+        <caption slTableCaption>
+          Orders placed today
+        </caption>
+        <thead slTableHead>
+          <tr slTableRow>
+            <th slTableColumnHeader>Order</th>
+            <th slTableColumnHeader>Customer</th>
+            <th slTableColumnHeader>Warehouse</th>
+            <th slTableColumnHeader>Status</th>
+            <th slTableColumnHeader numeric>Total</th>
+          </tr>
+        </thead>
+        <tbody slTableBody>
+          @for (order of orders; track order.id) {
+            <tr slTableRow [value]="order.id">
+              <th slTableRowHeader text="nowrap">{{ order.id }}</th>
+              <td slTableCell>{{ order.customer }}</td>
+              <td slTableCell>{{ order.warehouse }}</td>
+              <td slTableCell>
+                <span slTag [tone]="tone[order.status]"
+                  ><span slTagBody>{{ order.status }}</span></span
+                >
+              </td>
+              <td slTableCell numeric>{{ usd.format(order.total) }}</td>
+            </tr>
+          }
+        </tbody>
+      </div>
+    </div>
+  `,
+})
+export class TableBasic {
+  readonly orders = ORDERS;
+  readonly tone = TONE;
+  readonly usd = USD;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div[slTable], exportAs="slTable" | yes |
+| `scroll` | div[slTableContent], exportAs="slTableContent" | yes |
+| `table` | table, drawn by slTableContent | yes |
+| `caption` | caption[slTableCaption] | no |
+| `head` | thead[slTableHead] | no |
+| `body` | tbody[slTableBody] | yes |
+| `summary` | tfoot[slTableSummary] | no |
+| `footer` | div[slTableFooter] | no |
+| `row` | tr[slTableRow], exportAs="slTableRow" | yes |
+| `column-header` | th[slTableColumnHeader] | no |
+| `row-header` | th[slTableRowHeader] | no |
+| `cell` | td[slTableCell] | yes |
+| `sort` | button[slTableSort] | no |
+| `column-actions` | span[slTableColumnActions] | no |
+| `filter` | button, inside span[slTableSetFilter] and its four siblings | no |
+| `filter-panel` | div | no |
+| `filter-condition` | div | no |
+| `filter-operator` | div | no |
+| `filter-operand` | div | no |
+| `filter-join` | div | no |
+| `filter-search` | div | no |
+| `filter-list` | div | no |
+| `filter-option` | div | no |
+| `filter-empty` | p | no |
+| `filter-actions` | div | no |
+| `selection` | td[slTableSelect] and th[slTableSelectAll] | no |
+| `expander` | button[slTableExpander] | no |
+| `detail` | tr[slTableDetail] | no |
+| `empty` | td[slTableEmpty] | no |
+| `loader` | tbody[slTableLoader] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `sort` | `model<TableSortDescriptor \| null>` | null | slTable | The column the rows are ordered by, two-way |
+| `defaultSort` | `model initial value` | null | slTable | The order an unbound table starts in: the model own initial value |
+| `value` | `model<readonly string[]>` | [] | slTable | The chosen rows, two-way, and the value a form control holds |
+| `defaultValue` | `model initial value` | [] | slTable | The rows an unbound table starts with |
+| `expanded` | `model<readonly string[]>` | [] | slTable | The rows whose detail is open, two-way |
+| `defaultExpanded` | `model initial value` | [] | slTable | The details an unbound table starts with |
+| `variant` | `'plain' \| 'ruled' \| 'framed'` | ruled | slTable | How much of a frame the set is given |
+| `striped` | `boolean` | false | slTable | A tinted ground on every second record |
+| `stickyHeader` | `boolean` | false | slTable | Whether the header stays while the body scrolls |
+| `stickyFooter` | `boolean` | false | slTable | Whether the summary rows stay while the body scrolls. It pins the tfoot and not the footer bar, which never scrolls. |
+| `stickyTo` | `'scroll' \| 'page'` | scroll | slTable | What the header stays inside: this table own scroller, or whatever scrolls outside it. page releases the scroller, so the table stops scrolling sideways in its frame. |
+| `options` | `readonly TableFilterOption[]` | [] | slTableSetFilter | The values the column can be filtered to, each with an optional count of its own. With operand tags they are a datalist and the set a typed value must belong to; without them any value is admitted. |
+| `operand` | `'list' \| 'tags'` | list | slTableSetFilter | How the values are chosen: the search, the covering checkbox and the list, or sl-tags-input holding the chosen values as chips. The descriptor is the same list either way. |
+| `presets` | `TemplateRef` | — | slTableDateFilter, slTableTimeFilter, slTableDateTimeFilter | A template of slDateRangePickerPreset, slTimeRangePickerPreset or slDateTimeRangePickerPreset buttons offered inside the range picker between draws. The descriptor still receives two ISO values. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | slTableTimeFilter, slTableDateTimeFilter | The last unit the picker writes, and the precision the engine compares at: a minute-precision operand matches every second of its minute. |
+| `value` | `TextFilter \| NumberFilter \| DateFilter \| TimeFilter \| DateTimeFilter \| BooleanFilter \| SetFilter \| null` | null | slTable*Filter | The descriptor the column is filtered by, typed as its own kind. Two-way through [(value)], and valueChangeRequest carries the reason; both fire once, on Apply. |
+| `operators` | `readonly string[]` | the kind own list | slTable*Filter | Narrows what the chooser offers, in the order given. defaultOperator picks the one the panel opens on. |
+| `conditions` | `number` | 2 | slTable*Filter | How many conditions the panel offers. The second appears once the first is complete. |
+| `searchThreshold` | `number` | 8 | slTableSetFilter | How many values bring a search with them. searchable states it outright. |
+| `cellAlign` | `'start' \| 'center' \| 'end'` | center | slTable | Where every cell content sits in a row as tall as its tallest cell. A cell states blockAlign to answer differently. |
+| `layout` | `'auto' \| 'fixed'` | auto | slTable | Whether the browser sizes the columns from their content or from what you state |
+| `selectionMode` | `'none' \| 'single' \| 'multiple'` | none | slTable | How many records may be chosen at once |
+| `columns` | `number` | 1 | slTable | How many columns the spanning parts span |
+| `loading` | `boolean` | false | slTable | A refresh over rows already shown: aria-busy, and nothing moves |
+| `messages` | `Partial<TableMessages>` | — | slTable | Words laid over the language in force, key by key: selection, expansion, sort and every word of the column filters |
+| `skeletonRows` | `number` | 5 | slTableLoader | How many skeleton rows a first load draws |
+| `totalRowCount` | `number` | — | slTableContent | The size of the set behind a page, written as aria-rowcount |
+| `aria-label` | `string` | — | slTableContent | The table’s name when it has no caption, written on the table element |
+| `scrollLabel` | `string` | — | slTableContent | The name the scrolling region takes while it overflows, over the catalog’s |
+| `scrollLabelledBy` | `string` | — | slTableContent | The element that names the region instead, usually the caption |
+| `value` | `string` | — | slTableRow | The record key the selection and the expansion are held by |
+| `disabled` | `boolean` | false | slTableRow | A record the reader may not choose; it leaves the set the header covers |
+| `rowIndex` | `number` | — | slTableRow | The record position in the whole set, written as aria-rowindex |
+| `column` | `string` | — | slTableColumnHeader, slTableSort | The column key the sort descriptor names |
+| `align` | `'start' \| 'center' \| 'end'` | start | the three cell parts | Which edge the value stands on, resolved logically |
+| `numeric` | `boolean` | false | the three cell parts | Tabular figures, and the end edge unless align says otherwise |
+| `blockAlign` | `'start' \| 'center' \| 'end'` | center | the three cell parts and both selection cells | Where this cell content sits in its row, overriding the table own cellAlign |
+| `text` | `'wrap' \| 'truncate' \| 'nowrap'` | wrap | the three cell parts | What a value longer than its column does |
+| `sticky` | `'start' \| 'end'` | start | the three cell parts and both selection cells | Which edge the column is pinned to while the table scrolls past it |
+| `stickyOffset` | `string` | 0 | the three cell parts and both selection cells | Where the pinned column stops, as a CSS length. Two columns pinned to the same edge need the second to state how wide the first is — beside a selection column that is --slotted-table-selection-size, which is 3rem. |
+| `colSpan` | `number` | — | slTableDetail, slTableEmpty | How many columns the part spans, defaulting to the table own count |
+| `exportAs` | `slTable, slTableRow, slTableContent` | — | every part | Reaches the instance from the template: row.expanded(), table.rows(), content.scrollToRow() |
+| `provideTableDefaults()` | `Partial<TableDefaults>` | — | Application | Sets the frame, the layout and the selection once; an input on the table still wins |
+| `ControlValueAccessor` | `readonly string[]` | — | slTable | The selection as a form value: [formControl] or [(ngModel)] on the table itself |
+| `ng-content` | `projected` | — | slTableContent | Your caption, header, body, summary and footer are projected into the table the directive draws |
+| `SL_TABLE_PARTS` | `readonly Type[]` | — | a standalone component | Every part in one import, for a template that uses most of them |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `sortChange` | `TableSortDescriptor \| null` | The two-way half of the model: the column and the direction, or null when the third press clears it. |
+| `sortChangeRequest` | `ChangeRequest<TableSortDescriptor \| null>` | The same transition with the reason — pointer, keyboard, clear or programmatic — the value it replaces and cancel(). |
+| `valueChange` | `readonly string[]` | The chosen rows, in the collection order rather than the order they were pressed. |
+| `valueChangeRequest` | `ChangeRequest<readonly string[]>` | The selection with its reason: select for a range or a select-all, clear when the set is emptied, pointer otherwise. |
+| `expandedChange` | `readonly string[]` | The rows whose detail is open, after the press that opened or closed one. |
+| `expandedChangeRequest` | `ChangeRequest<readonly string[]>` | The same transition, with the reason and the originating event. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `plain`, `ruled`, `framed` | `ruled` |
+| `striped` | `true`, `false` | `false` |
+| `stickyHeader` | `true`, `false` | `false` |
+| `stickyFooter` | `true`, `false` | `false` |
+| `stickyTo` | `scroll`, `page` | `scroll` |
+| `layout` | `auto`, `fixed` | `auto` |
+| `cellAlign` | `start`, `center`, `end` | `center` |
+| `selectionMode` | `none`, `single`, `multiple` | `none` |
+| `align` | `start`, `center`, `end` | `start` |
+| `numeric` | `true`, `false` | `false` |
+| `text` | `wrap`, `truncate`, `nowrap` | `wrap` |
+| `sticky` | `start`, `end` | `start` |
+| `blockAlign` | `start`, `center`, `end` | `center` |
+
+## Rules
+
+- The role is table and not grid, and the difference is the whole boundary with data-grid. The APG says a table "is not an interactive widget. Thus, its cells are not focusable or selectable", so every control inside is its own tab stop and the family binds no key. Column resizing, virtualisation, multi-column sort and row activation all need the grid pattern and are deferred to the family that has it.
+- Every role comes from the platform: table, thead, tbody, tfoot, tr, th and td already carry table, rowgroup, row, columnheader, rowheader and cell. The family writes none of them, and it writes no aria-labelledby either — a caption is the accessible name by the browser own rule, whether it is visible or visually hidden.
+- scope="col" on a column header and scope="row" on a row header are what make a screen reader repeat the column name and the record name in each cell. They are the two attributes §12 of the feature guide asks for by name.
+- aria-sort is written on the sorted header and removed from every other, because ARIA has no way to state a sort level and a second sorted column would be silent or a lie. The change is also announced politely with the column and the direction: a property that changes silently is a change no reader hears.
+- A row is not selectable under this role, so it carries no aria-selected. The state is painted with data-selected and announced by the checkbox that owns it, whose name is a visually hidden label rather than an aria-label on the wrapper — the wrapper is not the control.
+- aria-rowcount and aria-rowindex are written exactly when you state a total larger than the DOM, which is what the Grid and Table Properties practice requires. The practice warns that writing aria-rowindex on some rows and not others has devastating effects, so the family writes neither unless you state both.
+- The scroller becomes a region with a tab stop and a name only while the table overflows, measured after the first render rather than assumed. A wide table with no tab stop is unreachable without a pointer — a WCAG 2.2 level A failure — and a tab stop on a table that fits is one a reader presses for nothing.
+- The expander is the Disclosure pattern: a button with aria-expanded, and with aria-controls naming the detail row while it is open. Your own @if keeps a closed detail out of the DOM, because a component whose host is the tr cannot remove that tr from inside itself and an empty row is a row a screen reader still counts.
+- A selected row is said by its ground and its ink together, and by the checkbox mark. R1 of this repository forbids the rail two families reached for, and in the high-contrast scheme every tone ground is the page own white — so the mark is what survives.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-padding-inline-md`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-ground`, `--slotted-line-height-md`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-shadow-xs`, `--slotted-space-2`, `--slotted-space-5`, `--slotted-space-9`, `--slotted-surface`, `--slotted-table-border-color`, `--slotted-table-border-color-strong`, `--slotted-table-border-width`, `--slotted-table-cell-padding-block`, `--slotted-table-cell-padding-inline`, `--slotted-table-color`, `--slotted-table-color-muted`, `--slotted-table-column-actions-size`, `--slotted-table-control-radius`, `--slotted-table-font-family`, `--slotted-table-font-size`, `--slotted-table-gap`, `--slotted-table-header-surface`, `--slotted-table-header-surface-hover`, `--slotted-table-icon-size`, `--slotted-table-radius`, `--slotted-table-row-color-selected`, `--slotted-table-row-min-block-size`, `--slotted-table-row-surface-hover`, `--slotted-table-row-surface-selected`, `--slotted-table-row-surface-selected-hover`, `--slotted-table-row-surface-stripe`, `--slotted-table-selection-size`, `--slotted-table-shadow`, `--slotted-table-sticky-inset`, `--slotted-table-sticky-offset`, `--slotted-table-sticky-offset-end`, `--slotted-table-surface`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-sticky`
+
+## Examples
+
+See [table.examples.md](./table.examples.md).