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

package/dist/docs/dashboard-grid.md

@@ -0,0 +1,272 @@
+<!-- index: ./index.md -->
+# dashboard-grid
+
+`data-ui="dashboard-grid"` · Grid of widgets that reorder and resize.
+
+## Import
+
+```tsx
+import {
+  DashboardGrid,
+  DashboardWidget,
+  DashboardGridDefaultsProvider,
+  usePersistedDashboardLayout,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+const [layout, setLayout] = useState<DashboardLayout>([]);
+const [editing, setEditing] = useState(false);
+
+<DashboardGrid
+  aria-label="Sales overview"
+  editing={editing}
+  layout={layout}
+  onEditingChange={setEditing}
+  onLayoutChange={setLayout}
+>
+  <DashboardWidget defaultColumns={3} title="Revenue" value="revenue">
+    <RevenueFigure />
+  </DashboardWidget>
+  <DashboardWidget defaultColumns={8} defaultRows={4} title="Revenue by week" value="trend">
+    <RevenueTrend />
+  </DashboardWidget>
+</DashboardGrid>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `edit-bar` | div | no |
+| `edit-status` | p | no |
+| `edit-actions` | div | no |
+| `add` | button, a Button and a Menu trigger | no |
+| `reset` | button, a Button | no |
+| `cancel` | button, a Button | no |
+| `done` | button, a Button | no |
+| `grid` | ul role="list" | yes |
+| `widget` | li | yes |
+| `title` | h2 to h6 | yes |
+| `description` | p | no |
+| `detail` | a, or button | no |
+| `handle` | button, a Menu trigger | no |
+| `skeleton` | div | no |
+| `message` | div around a ResultState | no |
+| `retry` | button, a Button | no |
+| `busy-indicator` | span | no |
+| `resize-handle` | span | no |
+| `size-readout` | span | no |
+| `placeholder` | li | no |
+| `empty` | div around a ResultState | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `DashboardLayout` | — | DashboardGrid | 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` | [] | DashboardGrid | The uncontrolled start, read once. A widget it does not name takes the first cell it fits, in the order of the children |
+| `editing` | `boolean` | false | DashboardGrid | The edit mode. Present means controlled |
+| `defaultEditing` | `boolean` | false | DashboardGrid | The uncontrolled mode, read once |
+| `columns` | `number \| { expanded, medium, compact }` | 12 | DashboardGrid, DashboardGridDefaultsProvider | 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 | DashboardGrid, DashboardGridDefaultsProvider | Whether the family draws Add, Reset, Cancel and Done while editing |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | 3 | DashboardGrid, DashboardWidget, DashboardGridDefaultsProvider | The level of each widget’s title |
+| `messages` | `Partial<DashboardGridMessages>` | — | DashboardGrid | 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 |
+| `ref` | `Ref<DashboardGridHandle>` | — | DashboardGrid | element, focusWidget(key), commitEditing(), cancelEditing() |
+| `render` | `(props: DashboardGridRootProps) => ReactElement` | a div | DashboardGrid | Substitutes the root element |
+| `native props` | `ComponentPropsWithRef<"div">` | — | DashboardGrid | id, className, style, data-* and handlers reach the root; aria-label and aria-labelledby name the list |
+| `value` | `string` | — | DashboardWidget | The widget’s key in the layout. Required |
+| `title` | `string` | — | DashboardWidget | The heading, the article’s name, the handle’s name and the entry in Add widget. Required |
+| `description` | `ReactNode` | — | DashboardWidget | The line under the title |
+| `defaultColumns` | `number` | 4 | DashboardWidget | Expanded columns of a widget the layout does not name |
+| `defaultRows` | `number` | 2 | DashboardWidget | Rows of a widget the layout does not name |
+| `minColumns` | `number` | 2 | DashboardWidget | The fewest expanded columns a resize leaves |
+| `maxColumns` | `number` | columns | DashboardWidget | The most expanded columns a resize gives |
+| `minRows` | `number` | 2 | DashboardWidget | The fewest rows a resize leaves |
+| `maxRows` | `number` | — | DashboardWidget | The most rows a resize gives |
+| `movable` | `boolean` | true | DashboardWidget | false fixes the widget at its cell; the others flow around it |
+| `resizable` | `boolean` | true | DashboardWidget | false removes the edges, Shift+Arrow and the size items |
+| `removable` | `boolean` | true | DashboardWidget | false removes Delete and Hide |
+| `loading` | `boolean` | false | DashboardWidget | The first answer has not arrived: the body shows a skeleton, with the skeleton family’s delay and minDuration |
+| `busy` | `boolean` | false | DashboardWidget | 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 | DashboardWidget | What the body says when it is not the content |
+| `skeleton` | `ReactNode` | one block | DashboardWidget | The skeleton of the body’s own anatomy |
+| `emptyTitle / emptyDescription / emptyAction` | `ReactNode` | messages.emptyTitle / — / — | DashboardWidget | The empty message and the action that creates the first entry |
+| `errorTitle / errorDescription` | `ReactNode` | messages.errorTitle / — | DashboardWidget | The error message |
+| `detailHref` | `string` | — | DashboardWidget | The widget’s own page, as a link in the corner |
+| `actions` | `ReactNode` | — | DashboardWidget | The consumer’s controls in the header’s corner |
+| `footer` | `ReactNode` | — | DashboardWidget | Content under the body |
+| `fill / size` | `CardFill / CardSize` | outline / md | DashboardWidget | The card’s own axes |
+| `render` | `(props: DashboardWidgetRootProps) => ReactElement` | an li | DashboardWidget | Substitutes the li; keep props.ref, the grid measures against it |
+| `DashboardGridDefaultsProvider` | `{ columns, editBar, headingLevel }` | — | a subtree | The decisions an application takes once; an instance that states any of them wins. The words come from the language in force (SlottedProvider) |
+| `usePersistedDashboardLayout` | `({ key, storage?, defaultLayout? }) => { layout, onLayoutChange, clear }` | localStorage | a component | Reads the stored layout once and writes every change; a store that throws reads as empty |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onLayoutChange` | `(layout: DashboardLayout, request: 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. |
+| `onEditingChange` | `(editing: boolean, request: ChangeRequest<boolean>)` | Before the mode changes: Done (submit), Cancel (the press’s pointer or keyboard, after the layout request), commitEditing() and cancelEditing() (programmatic). |
+| `onRetry` | `(event: MouseEvent)` | On DashboardWidget, when Try again under the error message is pressed. |
+| `onDetail` | `(event: MouseEvent)` | On DashboardWidget, when the detail action is pressed; it is the only handler when no detailHref is given. |
+| `onKeyDown and the other native handlers` | `the element’s own event` | Reach the root and each li. The handle’s own keys are handled before its menu reads them, and a consumer handler on the grid still runs. |
+
+## 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
+
+```tsx
+<DashboardWidget
+  actions={<Button size="sm">Export</Button>}
+  description="Last twelve weeks, all channels"
+  detailHref="/reports/revenue"
+  footer={<Text size="sm">Updated 4 minutes ago</Text>}
+  title="Revenue by week"
+  value="trend"
+>
+  <RevenueTrend />
+</DashboardWidget>;
+```
+
+### 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
+
+```tsx
+<Button onClick={() => setEditing(true)}>Edit layout</Button>;
+
+<DashboardGrid editing={editing} onEditingChange={setEditing}>
+  …
+</DashboardGrid>;
+```
+
+### 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
+
+```tsx
+<DashboardGrid defaultEditing>…</DashboardGrid>;
+```
+
+### 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
+
+```tsx
+<DashboardWidget movable={false} title="Revenue" value="revenue" />;
+<DashboardWidget minColumns={4} minRows={3} title="Revenue by week" value="trend" />;
+<DashboardWidget resizable={false} title="Conversion" value="conversion" />;
+<DashboardWidget 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
+
+```tsx
+<DashboardWidget
+  loading={pending}
+  skeleton={<TopProductsSkeleton />}
+  title="Top products"
+  value="products"
+/>;
+<DashboardWidget busy={refreshing} title="Orders" value="orders" />;
+<DashboardWidget
+  emptyAction={<Button>Record a refund</Button>}
+  status="empty"
+  title="Refunds"
+  value="refunds"
+/>;
+<DashboardWidget onRetry={() => refetch()} status="error" title="Conversion" value="conversion" />;
+```
+
+### 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
+
+```tsx
+<DashboardGrid columns={{ expanded: 12, medium: 6, compact: 1 }}>…</DashboardGrid>;
+```
+
+### 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
+
+```tsx
+const persisted = usePersistedDashboardLayout({ key: 'trailhead-sales' });
+
+<DashboardGrid layout={persisted.layout} onLayoutChange={persisted.onLayoutChange}>
+  …
+</DashboardGrid>;
+```
+
+### 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. SlottedProvider sets Portuguese here, and the defaults provider the heading level.
+
+Excerpt — not a complete module
+
+```tsx
+<SlottedProvider catalogs={{ 'pt-BR': PT_BR }} locale="pt-BR">
+  <DashboardGridDefaultsProvider headingLevel={2}>
+    <App />
+  </DashboardGridDefaultsProvider>
+</SlottedProvider>;
+```
+
+### 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.
+
+Excerpt — not a complete module
+
+```tsx
+const grid = useRef<DashboardGridHandle>(null);
+
+<Button onClick={() => grid.current?.commitEditing()}>Done</Button>;
+<DashboardGrid aria-label="Sales overview" editBar={false} ref={grid}>
+  …
+</DashboardGrid>;
+```