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

package/docs/dashboard-grid.md

@@ -0,0 +1,265 @@
+<!-- index: ./index.md -->
+# dashboard-grid
+
+`data-ui="dashboard-grid"` · Grid of widgets that reorder and resize.
+
+## Import
+
+```ts
+import {
+  SlDashboardGrid,
+  SlDashboardWidget,
+  SlDashboardWidgetActions,
+  SlDashboardWidgetEmptyAction,
+  SlDashboardWidgetFooter,
+  SlDashboardWidgetSkeleton,
+  persistedDashboardLayout,
+  provideDashboardGridDefaults,
+} from '@slotted/angular/dashboard-grid';
+```
+
+Selector: `[slDashboardGrid], sl-dashboard-widget, [slDashboardWidgetActions], [slDashboardWidgetSkeleton], [slDashboardWidgetEmptyAction], [slDashboardWidgetFooter]` · exportAs: `slDashboardGrid · slDashboardWidget`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slDashboardGrid aria-label="Sales overview" [(editing)]="editing" [(layout)]="layout">
+  <sl-dashboard-widget defaultColumns="3" title="Revenue" value="revenue">
+    <sl-revenue-figure />
+  </sl-dashboard-widget>
+  <sl-dashboard-widget defaultColumns="8" defaultRows="4" title="Revenue by week" value="trend">
+    <sl-revenue-trend />
+  </sl-dashboard-widget>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element slDashboardGrid is on | yes |
+| `edit-bar` | div | no |
+| `edit-status` | p | no |
+| `edit-actions` | div | no |
+| `add` | button[slButton][slMenuTriggerFor] | no |
+| `reset` | button[slButton] | no |
+| `cancel` | button[slButton] | no |
+| `done` | button[slButton] | no |
+| `grid` | ul role="list" | yes |
+| `widget` | li | yes |
+| `title` | h2 to h6 | yes |
+| `description` | p | no |
+| `detail` | a, or button[slIconButton] | no |
+| `handle` | button[slMenuTriggerFor] | no |
+| `skeleton` | div | no |
+| `message` | div around section[slResultState] | no |
+| `retry` | button[slButton] | no |
+| `busy-indicator` | span | no |
+| `resize-handle` | span | no |
+| `size-readout` | span | no |
+| `placeholder` | li | no |
+| `empty` | div around section[slResultState] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `DashboardLayout` | — | [slDashboardGrid] | Where each widget stands and how big it is: [{ key, x, y, w, h, hidden? }] in cells of the expanded class. Present means controlled |
+| `defaultLayout` | `DashboardLayout` | [] | [slDashboardGrid] | The uncontrolled start. A widget it does not name takes the first cell it fits, in the order of the children |
+| `editing` | `boolean` | false | [slDashboardGrid] | The edit mode. Present means controlled |
+| `defaultEditing` | `boolean` | false | [slDashboardGrid] | The uncontrolled mode, read once |
+| `columns` | `number \| { expanded, medium, compact }` | 12 | [slDashboardGrid], provideDashboardGridDefaults | Columns from 1024 pixels of the grid’s width; below it the widgets flow in halves and wholes of half as many, and below 600 in one column |
+| `editBar` | `boolean` | true | [slDashboardGrid], provideDashboardGridDefaults | Whether the family draws Add, Reset, Cancel and Done while editing |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | 3 | [slDashboardGrid], sl-dashboard-widget, provideDashboardGridDefaults | The level of each widget’s title |
+| `messages` | `Partial<DashboardGridMessages>` | — | [slDashboardGrid] | Words laid over the language in force, key by key: editBar, editStatus, add, reset, cancel, done, handle, detail, retry, emptyTitle, errorTitle, empty, emptyEditing, the eight menu items, hide, size, moved, movedInOrder, resized, hidden, shown, resetDone, cancelled |
+| `exportAs slDashboardGrid` | `SlDashboardGrid` | — | [slDashboardGrid] | focusWidget(key), commitEditing(), cancelEditing(), currentLayout(), isEditing() |
+| `host attributes` | `the element slDashboardGrid is on` | — | [slDashboardGrid] | id, class, style, data-* and events stay on the host; aria-label and aria-labelledby name the list |
+| `value` | `string` | — | sl-dashboard-widget | The widget’s key in the layout. Required |
+| `title` | `string` | — | sl-dashboard-widget | The heading, the article’s name, the handle’s name and the entry in Add widget. Required |
+| `description` | `string` | — | sl-dashboard-widget | The line under the title |
+| `defaultColumns` | `number` | 4 | sl-dashboard-widget | Expanded columns of a widget the layout does not name |
+| `defaultRows` | `number` | 2 | sl-dashboard-widget | Rows of a widget the layout does not name |
+| `minColumns` | `number` | 2 | sl-dashboard-widget | The fewest expanded columns a resize leaves |
+| `maxColumns` | `number` | columns | sl-dashboard-widget | The most expanded columns a resize gives |
+| `minRows` | `number` | 2 | sl-dashboard-widget | The fewest rows a resize leaves |
+| `maxRows` | `number` | — | sl-dashboard-widget | The most rows a resize gives |
+| `movable` | `boolean` | true | sl-dashboard-widget | false fixes the widget at its cell; the others flow around it |
+| `resizable` | `boolean` | true | sl-dashboard-widget | false removes the edges, Shift+Arrow and the size items |
+| `removable` | `boolean` | true | sl-dashboard-widget | false removes Delete and Hide |
+| `loading` | `boolean` | false | sl-dashboard-widget | The first answer has not arrived: the body shows a skeleton, with the skeleton family’s delay and minDuration |
+| `busy` | `boolean` | false | sl-dashboard-widget | A refresh of what is shown: the content stays, the article is aria-busy, a line moves along the top |
+| `status` | `'ready' \| 'empty' \| 'error'` | ready | sl-dashboard-widget | What the body says when it is not the content |
+| `[slDashboardWidgetSkeleton]` | `projected content` | one block | sl-dashboard-widget | The skeleton of the body’s own anatomy |
+| `emptyTitle / emptyDescription` | `string` | messages.emptyTitle / — | sl-dashboard-widget | The empty message; [slDashboardWidgetEmptyAction] is the action under it |
+| `errorTitle / errorDescription` | `string` | messages.errorTitle / — | sl-dashboard-widget | The error message |
+| `retryable` | `boolean` | false | sl-dashboard-widget | Draws Try again, which emits retry |
+| `detailable` | `boolean` | false | sl-dashboard-widget | Draws the detail action as a button, which emits detail |
+| `detailHref` | `string` | — | sl-dashboard-widget | The widget’s own page, as a link in the corner |
+| `[slDashboardWidgetActions]` | `projected content` | — | sl-dashboard-widget | The consumer’s controls in the header’s corner |
+| `[slDashboardWidgetFooter]` | `projected content` | — | sl-dashboard-widget | Content under the body |
+| `fill / size` | `CardFill / CardSize` | outline / md | sl-dashboard-widget | The card’s own axes |
+| `content` | `projected content` | — | sl-dashboard-widget | The body; kept in a template and drawn by the grid inside its own li and card, in the layout’s order |
+| `provideDashboardGridDefaults` | `{ columns, editBar, headingLevel }` | — | providers | The decisions an application takes once; an instance that states any of them wins. The words come from the language in force (provideSlotted) |
+| `persistedDashboardLayout` | `({ key, storage?, defaultLayout?, injector? }) => { layout, clear }` | localStorage | an injection context | A signal read once from the store and written after every change; bind it with [(layout)] |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `layoutChangeRequest` | `ChangeRequest<DashboardLayout> & { change: { kind: 'move' \| 'resize' \| 'hide' \| 'show' \| 'reset' \| 'cancel'; key: string \| null } }` | Once per gesture, at its end: a card dropped or an edge released (pointer), Alt+Arrow, Shift+Arrow or a menu item (keyboard or pointer), Delete or Hide (remove), Cancel (dismiss). The layout carries every widget at its cell, { key, x, y, w, h, hidden? }, and keeps entries no widget holds. cancel() refuses it; otherwise layout is set and [(layout)] hears it. |
+| `editingChangeRequest` | `ChangeRequest<boolean>` | Before the mode changes: Done (submit), Cancel (the press’s pointer or keyboard, after the layout request), commitEditing() and cancelEditing() (programmatic). |
+| `retry` | `MouseEvent` | On sl-dashboard-widget, when Try again under the error message is pressed; drawn under retryable. |
+| `detail` | `MouseEvent` | On sl-dashboard-widget, when the detail action is pressed: the link of detailHref, or the button of detailable. |
+| `(keydown) and the other native events` | `the element’s own event` | Reach the host. The handle’s own keys are taken in the capture phase, before its menu trigger reads them. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `editBar` | `true`, `false` | `true` |
+| `headingLevel` | `2`, `3`, `4`, `5`, `6` | `3` |
+| `status` | `ready`, `empty`, `error` | `ready` |
+
+## Rules
+
+- No WAI-ARIA pattern names a dashboard; the APG’s Listboxes with Rearrangeable Options example gives the move keys the family uses — Alt with an arrow, Delete to remove, focus kept on what moved, and a live confirmation — and each handle states its shortcuts in aria-keyshortcuts.
+- The grid is a native list with role="list" restated, since a list styled as a grid loses its role in WebKit, and each widget is an li holding an article named by its heading, so a reader hears “Sales overview, list, 6 items” and walks the widgets by heading.
+- The DOM holds the widgets by row and then column, so the order of Tab and of a screen reader is the order of the picture at every width; a gesture previews with CSS order and moves no element until it ends.
+- Everything a pointer does has a single-pointer path, as WCAG 2.2 SC 2.5.7 asks: the handle is a menu button (Enter, Space or ArrowDown) whose items move, resize and hide the widget.
+- Every change is announced once through the shared polite live region — “Orders moved to row 1, column 5”, “Revenue by week is 10 columns by 4 rows”, “Refunds hidden” — and the grid takes no key from the content inside a widget.
+- Escape cancels a carry or a pull in progress and does not leave editing: throwing a rearranged dashboard away takes Cancel. A finger picks a widget up by its handle, so a finger on a card still scrolls the page.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-card-radius`, `--slotted-control-border-color`, `--slotted-control-height-sm`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-dashboard-grid-accent`, `--slotted-dashboard-grid-description-color`, `--slotted-dashboard-grid-edit-bar-background`, `--slotted-dashboard-grid-edit-bar-border`, `--slotted-dashboard-grid-gap`, `--slotted-dashboard-grid-handle-block-size`, `--slotted-dashboard-grid-handle-block-size-coarse`, `--slotted-dashboard-grid-handle-glyph-size`, `--slotted-dashboard-grid-handle-inline-size`, `--slotted-dashboard-grid-handle-inline-size-coarse`, `--slotted-dashboard-grid-lattice-color`, `--slotted-dashboard-grid-lattice-dot`, `--slotted-dashboard-grid-resize-hit`, `--slotted-dashboard-grid-resize-pill`, `--slotted-dashboard-grid-resize-pill-active`, `--slotted-dashboard-grid-row-size`, `--slotted-dashboard-grid-title-color`, `--slotted-dashboard-grid-title-font-family`, `--slotted-dashboard-grid-title-font-size`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-shadow-lg`, `--slotted-shadow-md`, `--slotted-shadow-sm`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-12`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`
+
+## Examples
+
+### What a widget is made of
+
+While editing, a pill stands on each card’s top edge — its handle — and its sides and bottom corners take a pull. The header keeps the title, the description, the consumer’s Export and the way to the widget’s own page.
+
+Excerpt — not a complete module
+
+```html
+<sl-dashboard-widget
+  description="Last twelve weeks, all channels"
+  detailHref="/reports/revenue"
+  title="Revenue by week"
+  value="trend"
+>
+  <button slButton slDashboardWidgetActions size="sm">Export</button>
+  <sl-revenue-trend />
+  <p slDashboardWidgetFooter slText size="sm">Updated 4 minutes ago</p>
+</sl-dashboard-widget>
+```
+
+### An explicit edit mode
+
+A dot marks the middle of every free cell, the handles pop in, and the bar offers Add widget for the hidden Refunds, Reset, Cancel and Done. A card carried to another cell pushes what it covers down, and Cancel returns the layout editing started from.
+
+Excerpt — not a complete module
+
+```html
+<button slButton (click)="editing.set(true)">Edit layout</button>
+<div slDashboardGrid [(editing)]="editing">…</div>
+```
+
+### Every change from the keyboard
+
+Tab to a handle: Alt with an arrow moves the widget a column, or trades places with the widget above or below; Shift with an arrow pulls its end or bottom edge; Delete hides it; Enter opens the same choices as a menu. Focus stays on the handle.
+
+Excerpt — not a complete module
+
+```html
+<div slDashboardGrid defaultEditing>…</div>
+```
+
+### Sizes and places a widget allows
+
+Revenue is pinned: the others flow around it. Revenue by week never falls under four columns and three rows; Conversion has no edges to pull; Top products cannot be hidden, so its menu has no Hide.
+
+Excerpt — not a complete module
+
+```html
+<sl-dashboard-widget [movable]="false" title="Revenue" value="revenue" />
+<sl-dashboard-widget minColumns="4" minRows="3" title="Revenue by week" value="trend" />
+<sl-dashboard-widget [resizable]="false" title="Conversion" value="conversion" />
+<sl-dashboard-widget [removable]="false" title="Top products" value="products" />
+```
+
+### Waiting, refreshing, empty and failed
+
+The header stays painted while the body waits: one block where the anatomy is unknown, the table’s own rows where it is. A refresh keeps the figure under a moving line; empty offers the next step, and failure offers Try again.
+
+Excerpt — not a complete module
+
+```html
+<sl-dashboard-widget [loading]="pending()" title="Top products" value="products">
+  <div slDashboardWidgetSkeleton slSkeletonText [lines]="6"></div>
+</sl-dashboard-widget>
+<sl-dashboard-widget [busy]="refreshing()" title="Orders" value="orders" />
+<sl-dashboard-widget status="empty" title="Refunds" value="refunds">
+  <button slButton slDashboardWidgetEmptyAction>Record a refund</button>
+</sl-dashboard-widget>
+<sl-dashboard-widget
+  retryable
+  status="error"
+  title="Conversion"
+  value="conversion"
+  (retry)="refetch()"
+/>
+```
+
+### One layout, three widths
+
+One layout, three classes of the grid’s own width: from 1024 pixels every widget stands at its cell of twelve columns; from 600 the same order flows in halves and wholes; below 600 it is one column, each widget as tall as its content.
+
+Excerpt — not a complete module
+
+```html
+<div slDashboardGrid [columns]="{ expanded: 12, medium: 6, compact: 1 }">…</div>
+```
+
+### A layout kept across visits
+
+Carry or pull a widget and reload the page: the layout comes back from localStorage under the key trailhead-sales. Forget layout clears it. Text the store cannot read falls back to the default.
+
+Excerpt — not a complete module
+
+```ts
+@Component({
+  template: `<div slDashboardGrid [(layout)]="persisted.layout">…</div>`,
+})
+class SalesPage {
+  readonly persisted = persistedDashboardLayout({ key: 'trailhead-sales' });
+}
+```
+
+### Words for another product
+
+Every word comes from the language in force: the bar, the handle’s name, the menu, the size readout and the announcements. provideSlotted sets Portuguese here, and the defaults provider the heading level.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } }),
+    provideDashboardGridDefaults({ headingLevel: 2 }),
+  ],
+});
+```
+
+### Names, shortcuts and announcements
+
+The grid is a list named Sales overview, each widget an article named by its title. Here the page owns the controls: editBar is off, the instructions stay as the handles’ description, and Done in the page calls commitEditing() through exportAs.
+
+Excerpt — not a complete module
+
+```html
+<button slButton (click)="grid.commitEditing()">Done</button>
+<div slDashboardGrid #grid="slDashboardGrid" aria-label="Sales overview" [editBar]="false">…</div>
+```