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

package/dist/docs/dashboard-grid.json

@@ -0,0 +1,671 @@
+{
+  "family": "dashboard-grid",
+  "ui": "dashboard-grid",
+  "binding": "react",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Grid of widgets that reorder and resize."
+  },
+  "axes": {
+    "editBar": [
+      true,
+      false
+    ],
+    "headingLevel": [
+      "2",
+      "3",
+      "4",
+      "5",
+      "6"
+    ],
+    "status": [
+      "ready",
+      "empty",
+      "error"
+    ]
+  },
+  "members": {
+    "dashboard-grid": {
+      "nativeElement": "div",
+      "defaults": {
+        "columns": 12,
+        "editBar": true,
+        "headingLevel": "3",
+        "editing": false,
+        "status": "ready",
+        "loading": false,
+        "busy": false,
+        "defaultColumns": 4,
+        "defaultRows": 2,
+        "minColumns": 2,
+        "minRows": 2,
+        "movable": true,
+        "resizable": true,
+        "removable": true
+      },
+      "capabilities": [
+        "layout",
+        "editing",
+        "arrangement",
+        "status",
+        "loading",
+        "live",
+        "content",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "editing",
+        "dragging",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "edit-bar",
+        "edit-status",
+        "edit-actions",
+        "add",
+        "reset",
+        "cancel",
+        "done",
+        "grid",
+        "widget",
+        "title",
+        "description",
+        "detail",
+        "handle",
+        "skeleton",
+        "message",
+        "retry",
+        "busy-indicator",
+        "resize-handle",
+        "size-readout",
+        "placeholder",
+        "empty"
+      ]
+    }
+  },
+  "docs": {
+    "dashboard-grid": {
+      "imports": {
+        "source": "import {\n  DashboardGrid,\n  DashboardWidget,\n  DashboardGridDefaultsProvider,\n  usePersistedDashboardLayout,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "data-ui=\"dashboard-grid\", data-editing while editing. The container named dashboard-grid whose inline size picks the size class; the column counts reach it as --_dg-columns-*."
+        },
+        {
+          "part": "edit-bar",
+          "element": "div",
+          "required": false,
+          "purpose": "role=\"group\" named messages.editBar, above the grid while editing and editBar is true."
+        },
+        {
+          "part": "edit-status",
+          "element": "p",
+          "required": false,
+          "purpose": "The instructions every handle is described by. Visually hidden, and still referenced, when editBar is false."
+        },
+        {
+          "part": "edit-actions",
+          "element": "div",
+          "required": false,
+          "purpose": "Add widget, Reset layout, Cancel and Done at the bar’s inline end; wraps under the status."
+        },
+        {
+          "part": "add",
+          "element": "button, a Button and a Menu trigger",
+          "required": false,
+          "purpose": "A menu of the hidden widgets by title. Present only while a widget is hidden."
+        },
+        {
+          "part": "reset",
+          "element": "button, a Button",
+          "required": false,
+          "purpose": "Asks for the empty layout: every widget at its defaults, in the order of the children."
+        },
+        {
+          "part": "cancel",
+          "element": "button, a Button",
+          "required": false,
+          "purpose": "Asks for the layout editing began from, then leaves editing."
+        },
+        {
+          "part": "done",
+          "element": "button, a Button",
+          "required": false,
+          "purpose": "Leaves editing with the reason submit."
+        },
+        {
+          "part": "grid",
+          "element": "ul role=\"list\"",
+          "required": true,
+          "purpose": "One element in from the root, so the container query can change its tracks. Named by the aria-label or aria-labelledby written on DashboardGrid."
+        },
+        {
+          "part": "widget",
+          "element": "li",
+          "required": true,
+          "purpose": "One per visible widget, placed at its cell by --_dg-x, --_dg-y, --_dg-w and --_dg-h, and by --_dg-span-medium in the medium class. data-key, data-status, data-loading, data-movable, data-resizable, data-dragging, data-resizing."
+        },
+        {
+          "part": "title",
+          "element": "h2 to h6",
+          "required": true,
+          "purpose": "The widget’s heading at headingLevel; two lines, then an ellipsis. Names the article."
+        },
+        {
+          "part": "description",
+          "element": "p",
+          "required": false,
+          "purpose": "The line under the title; describes the article."
+        },
+        {
+          "part": "detail",
+          "element": "a, or button",
+          "required": false,
+          "purpose": "The external glyph and “Open {title}”: an a for detailHref, a button for onDetail alone."
+        },
+        {
+          "part": "handle",
+          "element": "button, a Menu trigger",
+          "required": false,
+          "purpose": "While editing, a pill of six dots standing on the card’s top edge: the widget’s keyboard stop, its menu, and where a finger picks it up. Alt+Arrow moves, Shift+Arrow resizes, Delete hides."
+        },
+        {
+          "part": "skeleton",
+          "element": "div",
+          "required": false,
+          "purpose": "While loading: the consumer’s skeleton, or one Skeleton block filling the body."
+        },
+        {
+          "part": "message",
+          "element": "div around a ResultState",
+          "required": false,
+          "purpose": "status=\"empty\" or \"error\", centred in the body; the error names Try again when onRetry is given."
+        },
+        {
+          "part": "retry",
+          "element": "button, a Button",
+          "required": false,
+          "purpose": "Try again under the error message; calls onRetry."
+        },
+        {
+          "part": "busy-indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "A line along the top of the body while busy; aria-hidden, since the article carries aria-busy."
+        },
+        {
+          "part": "resize-handle",
+          "element": "span",
+          "required": false,
+          "purpose": "Five per widget while editing and resizable, data-edge start, end, bottom, bottom-start or bottom-end: a strip straddling the edge with a pill at its middle, or an arc on a bottom corner. data-active on the one being pulled. aria-hidden: the keyboard’s path is Shift+Arrow and the menu."
+        },
+        {
+          "part": "size-readout",
+          "element": "span",
+          "required": false,
+          "purpose": "“10 × 4” on a chip of the accent at the corner being pulled, while a pointer resizes the widget; aria-hidden, the change is announced."
+        },
+        {
+          "part": "placeholder",
+          "element": "li",
+          "required": false,
+          "purpose": "During a gesture: the cells the widget in hand will land in, in the accent’s lightest wash with a hairline; aria-hidden."
+        },
+        {
+          "part": "empty",
+          "element": "div around a ResultState",
+          "required": false,
+          "purpose": "In place of the grid when no widget is visible."
+        }
+      ],
+      "api": [
+        {
+          "name": "layout",
+          "type": "DashboardLayout",
+          "defaultValue": "—",
+          "appliesTo": "DashboardGrid",
+          "description": "Where each widget stands and how big it is: [{ key, x, y, w, h, hidden? }] in cells of the expanded class. Present means controlled"
+        },
+        {
+          "name": "defaultLayout",
+          "type": "DashboardLayout",
+          "defaultValue": "[]",
+          "appliesTo": "DashboardGrid",
+          "description": "The uncontrolled start, read once. A widget it does not name takes the first cell it fits, in the order of the children"
+        },
+        {
+          "name": "editing",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DashboardGrid",
+          "description": "The edit mode. Present means controlled"
+        },
+        {
+          "name": "defaultEditing",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DashboardGrid",
+          "description": "The uncontrolled mode, read once"
+        },
+        {
+          "name": "columns",
+          "type": "number | { expanded, medium, compact }",
+          "defaultValue": "12",
+          "appliesTo": "DashboardGrid, DashboardGridDefaultsProvider",
+          "description": "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"
+        },
+        {
+          "name": "editBar",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "DashboardGrid, DashboardGridDefaultsProvider",
+          "description": "Whether the family draws Add, Reset, Cancel and Done while editing"
+        },
+        {
+          "name": "headingLevel",
+          "type": "2 | 3 | 4 | 5 | 6",
+          "defaultValue": "3",
+          "appliesTo": "DashboardGrid, DashboardWidget, DashboardGridDefaultsProvider",
+          "description": "The level of each widget’s title"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<DashboardGridMessages>",
+          "defaultValue": "—",
+          "appliesTo": "DashboardGrid",
+          "description": "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"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<DashboardGridHandle>",
+          "defaultValue": "—",
+          "appliesTo": "DashboardGrid",
+          "description": "element, focusWidget(key), commitEditing(), cancelEditing()"
+        },
+        {
+          "name": "render",
+          "type": "(props: DashboardGridRootProps) => ReactElement",
+          "defaultValue": "a div",
+          "appliesTo": "DashboardGrid",
+          "description": "Substitutes the root element"
+        },
+        {
+          "name": "native props",
+          "type": "ComponentPropsWithRef<\"div\">",
+          "defaultValue": "—",
+          "appliesTo": "DashboardGrid",
+          "description": "id, className, style, data-* and handlers reach the root; aria-label and aria-labelledby name the list"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The widget’s key in the layout. Required"
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The heading, the article’s name, the handle’s name and the entry in Add widget. Required"
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The line under the title"
+        },
+        {
+          "name": "defaultColumns",
+          "type": "number",
+          "defaultValue": "4",
+          "appliesTo": "DashboardWidget",
+          "description": "Expanded columns of a widget the layout does not name"
+        },
+        {
+          "name": "defaultRows",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "DashboardWidget",
+          "description": "Rows of a widget the layout does not name"
+        },
+        {
+          "name": "minColumns",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "DashboardWidget",
+          "description": "The fewest expanded columns a resize leaves"
+        },
+        {
+          "name": "maxColumns",
+          "type": "number",
+          "defaultValue": "columns",
+          "appliesTo": "DashboardWidget",
+          "description": "The most expanded columns a resize gives"
+        },
+        {
+          "name": "minRows",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "DashboardWidget",
+          "description": "The fewest rows a resize leaves"
+        },
+        {
+          "name": "maxRows",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The most rows a resize gives"
+        },
+        {
+          "name": "movable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "DashboardWidget",
+          "description": "false fixes the widget at its cell; the others flow around it"
+        },
+        {
+          "name": "resizable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "DashboardWidget",
+          "description": "false removes the edges, Shift+Arrow and the size items"
+        },
+        {
+          "name": "removable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "DashboardWidget",
+          "description": "false removes Delete and Hide"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DashboardWidget",
+          "description": "The first answer has not arrived: the body shows a skeleton, with the skeleton family’s delay and minDuration"
+        },
+        {
+          "name": "busy",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DashboardWidget",
+          "description": "A refresh of what is shown: the content stays, the article is aria-busy, a line moves along the top"
+        },
+        {
+          "name": "status",
+          "type": "'ready' | 'empty' | 'error'",
+          "defaultValue": "ready",
+          "appliesTo": "DashboardWidget",
+          "description": "What the body says when it is not the content"
+        },
+        {
+          "name": "skeleton",
+          "type": "ReactNode",
+          "defaultValue": "one block",
+          "appliesTo": "DashboardWidget",
+          "description": "The skeleton of the body’s own anatomy"
+        },
+        {
+          "name": "emptyTitle / emptyDescription / emptyAction",
+          "type": "ReactNode",
+          "defaultValue": "messages.emptyTitle / — / —",
+          "appliesTo": "DashboardWidget",
+          "description": "The empty message and the action that creates the first entry"
+        },
+        {
+          "name": "errorTitle / errorDescription",
+          "type": "ReactNode",
+          "defaultValue": "messages.errorTitle / —",
+          "appliesTo": "DashboardWidget",
+          "description": "The error message"
+        },
+        {
+          "name": "detailHref",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The widget’s own page, as a link in the corner"
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "The consumer’s controls in the header’s corner"
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DashboardWidget",
+          "description": "Content under the body"
+        },
+        {
+          "name": "fill / size",
+          "type": "CardFill / CardSize",
+          "defaultValue": "outline / md",
+          "appliesTo": "DashboardWidget",
+          "description": "The card’s own axes"
+        },
+        {
+          "name": "render",
+          "type": "(props: DashboardWidgetRootProps) => ReactElement",
+          "defaultValue": "an li",
+          "appliesTo": "DashboardWidget",
+          "description": "Substitutes the li; keep props.ref, the grid measures against it"
+        },
+        {
+          "name": "DashboardGridDefaultsProvider",
+          "type": "{ columns, editBar, headingLevel }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once; an instance that states any of them wins. The words come from the language in force (SlottedProvider)"
+        },
+        {
+          "name": "usePersistedDashboardLayout",
+          "type": "({ key, storage?, defaultLayout? }) => { layout, onLayoutChange, clear }",
+          "defaultValue": "localStorage",
+          "appliesTo": "a component",
+          "description": "Reads the stored layout once and writes every change; a store that throws reads as empty"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "onLayoutChange",
+          "payload": "(layout: DashboardLayout, request: ChangeRequest<DashboardLayout> & { change: { kind: 'move' | 'resize' | 'hide' | 'show' | 'reset' | 'cancel'; key: string | null } })",
+          "when": "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."
+        },
+        {
+          "name": "onEditingChange",
+          "payload": "(editing: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the mode changes: Done (submit), Cancel (the press’s pointer or keyboard, after the layout request), commitEditing() and cancelEditing() (programmatic)."
+        },
+        {
+          "name": "onRetry",
+          "payload": "(event: MouseEvent)",
+          "when": "On DashboardWidget, when Try again under the error message is pressed."
+        },
+        {
+          "name": "onDetail",
+          "payload": "(event: MouseEvent)",
+          "when": "On DashboardWidget, when the detail action is pressed; it is the only handler when no detailHref is given."
+        },
+        {
+          "name": "onKeyDown and the other native handlers",
+          "payload": "the element’s own event",
+          "when": "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."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Trailhead’s sales overview on the page’s sunken ground: four figures, a chart and a table, each filling its widget. Edit layout enters the mode; every request is written under the grid with its change, its key and its reason.",
+      "language": "tsx",
+      "source": "const [layout, setLayout] = useState<DashboardLayout>([]);\nconst [editing, setEditing] = useState(false);\n\n<DashboardGrid\n  aria-label=\"Sales overview\"\n  editing={editing}\n  layout={layout}\n  onEditingChange={setEditing}\n  onLayoutChange={setLayout}\n>\n  <DashboardWidget defaultColumns={3} title=\"Revenue\" value=\"revenue\">\n    <RevenueFigure />\n  </DashboardWidget>\n  <DashboardWidget defaultColumns={8} defaultRows={4} title=\"Revenue by week\" value=\"trend\">\n    <RevenueTrend />\n  </DashboardWidget>\n</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "What a widget is made of",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<DashboardWidget\n  actions={<Button size=\"sm\">Export</Button>}\n  description=\"Last twelve weeks, all channels\"\n  detailHref=\"/reports/revenue\"\n  footer={<Text size=\"sm\">Updated 4 minutes ago</Text>}\n  title=\"Revenue by week\"\n  value=\"trend\"\n>\n  <RevenueTrend />\n</DashboardWidget>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "editing",
+      "title": "An explicit edit mode",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<Button onClick={() => setEditing(true)}>Edit layout</Button>;\n\n<DashboardGrid editing={editing} onEditingChange={setEditing}>\n  …\n</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Every change from the keyboard",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<DashboardGrid defaultEditing>…</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "constraints",
+      "title": "Sizes and places a widget allows",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<DashboardWidget movable={false} title=\"Revenue\" value=\"revenue\" />;\n<DashboardWidget minColumns={4} minRows={3} title=\"Revenue by week\" value=\"trend\" />;\n<DashboardWidget resizable={false} title=\"Conversion\" value=\"conversion\" />;\n<DashboardWidget removable={false} title=\"Top products\" value=\"products\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Waiting, refreshing, empty and failed",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<DashboardWidget\n  loading={pending}\n  skeleton={<TopProductsSkeleton />}\n  title=\"Top products\"\n  value=\"products\"\n/>;\n<DashboardWidget busy={refreshing} title=\"Orders\" value=\"orders\" />;\n<DashboardWidget\n  emptyAction={<Button>Record a refund</Button>}\n  status=\"empty\"\n  title=\"Refunds\"\n  value=\"refunds\"\n/>;\n<DashboardWidget onRetry={() => refetch()} status=\"error\" title=\"Conversion\" value=\"conversion\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "responsive",
+      "title": "One layout, three widths",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<DashboardGrid columns={{ expanded: 12, medium: 6, compact: 1 }}>…</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "persistence",
+      "title": "A layout kept across visits",
+      "note": "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.",
+      "language": "tsx",
+      "source": "const persisted = usePersistedDashboardLayout({ key: 'trailhead-sales' });\n\n<DashboardGrid layout={persisted.layout} onLayoutChange={persisted.onLayoutChange}>\n  …\n</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "labels",
+      "title": "Words for another product",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<SlottedProvider catalogs={{ 'pt-BR': PT_BR }} locale=\"pt-BR\">\n  <DashboardGridDefaultsProvider headingLevel={2}>\n    <App />\n  </DashboardGridDefaultsProvider>\n</SlottedProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Names, shortcuts and announcements",
+      "note": "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.",
+      "language": "tsx",
+      "source": "const grid = useRef<DashboardGridHandle>(null);\n\n<Button onClick={() => grid.current?.commitEditing()}>Done</Button>;\n<DashboardGrid aria-label=\"Sales overview\" editBar={false} ref={grid}>\n  …\n</DashboardGrid>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}