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

package/docs/dashboard-grid.json

@@ -0,0 +1,680 @@
+{
+  "family": "dashboard-grid",
+  "ui": "dashboard-grid",
+  "binding": "angular",
+  "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  SlDashboardGrid,\n  SlDashboardWidget,\n  SlDashboardWidgetActions,\n  SlDashboardWidgetEmptyAction,\n  SlDashboardWidgetFooter,\n  SlDashboardWidgetSkeleton,\n  persistedDashboardLayout,\n  provideDashboardGridDefaults,\n} from '@slotted/angular/dashboard-grid';",
+        "selector": "[slDashboardGrid], sl-dashboard-widget, [slDashboardWidgetActions], [slDashboardWidgetSkeleton], [slDashboardWidgetEmptyAction], [slDashboardWidgetFooter]",
+        "exportAs": "slDashboardGrid · slDashboardWidget"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element slDashboardGrid is on",
+          "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[slButton][slMenuTriggerFor]",
+          "required": false,
+          "purpose": "A menu of the hidden widgets by title. Present only while a widget is hidden."
+        },
+        {
+          "part": "reset",
+          "element": "button[slButton]",
+          "required": false,
+          "purpose": "Asks for the empty layout: every widget at its defaults, in the order of the children."
+        },
+        {
+          "part": "cancel",
+          "element": "button[slButton]",
+          "required": false,
+          "purpose": "Asks for the layout editing began from, then leaves editing."
+        },
+        {
+          "part": "done",
+          "element": "button[slButton]",
+          "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 the host, which the host itself then drops."
+        },
+        {
+          "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[slIconButton]",
+          "required": false,
+          "purpose": "The external glyph and “Open {title}”: an a for detailHref, a button under detailable, which emits detail."
+        },
+        {
+          "part": "handle",
+          "element": "button[slMenuTriggerFor]",
+          "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 section[slResultState]",
+          "required": false,
+          "purpose": "status=\"empty\" or \"error\", centred in the body; the error draws Try again under retryable."
+        },
+        {
+          "part": "retry",
+          "element": "button[slButton]",
+          "required": false,
+          "purpose": "Try again under the error message; emits retry."
+        },
+        {
+          "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 section[slResultState]",
+          "required": false,
+          "purpose": "In place of the grid when no widget is visible."
+        }
+      ],
+      "api": [
+        {
+          "name": "layout",
+          "type": "DashboardLayout",
+          "defaultValue": "—",
+          "appliesTo": "[slDashboardGrid]",
+          "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": "[slDashboardGrid]",
+          "description": "The uncontrolled start. 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": "[slDashboardGrid]",
+          "description": "The edit mode. Present means controlled"
+        },
+        {
+          "name": "defaultEditing",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slDashboardGrid]",
+          "description": "The uncontrolled mode, read once"
+        },
+        {
+          "name": "columns",
+          "type": "number | { expanded, medium, compact }",
+          "defaultValue": "12",
+          "appliesTo": "[slDashboardGrid], provideDashboardGridDefaults",
+          "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": "[slDashboardGrid], provideDashboardGridDefaults",
+          "description": "Whether the family draws Add, Reset, Cancel and Done while editing"
+        },
+        {
+          "name": "headingLevel",
+          "type": "2 | 3 | 4 | 5 | 6",
+          "defaultValue": "3",
+          "appliesTo": "[slDashboardGrid], sl-dashboard-widget, provideDashboardGridDefaults",
+          "description": "The level of each widget’s title"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<DashboardGridMessages>",
+          "defaultValue": "—",
+          "appliesTo": "[slDashboardGrid]",
+          "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": "exportAs slDashboardGrid",
+          "type": "SlDashboardGrid",
+          "defaultValue": "—",
+          "appliesTo": "[slDashboardGrid]",
+          "description": "focusWidget(key), commitEditing(), cancelEditing(), currentLayout(), isEditing()"
+        },
+        {
+          "name": "host attributes",
+          "type": "the element slDashboardGrid is on",
+          "defaultValue": "—",
+          "appliesTo": "[slDashboardGrid]",
+          "description": "id, class, style, data-* and events stay on the host; aria-label and aria-labelledby name the list"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The widget’s key in the layout. Required"
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The heading, the article’s name, the handle’s name and the entry in Add widget. Required"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The line under the title"
+        },
+        {
+          "name": "defaultColumns",
+          "type": "number",
+          "defaultValue": "4",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "Expanded columns of a widget the layout does not name"
+        },
+        {
+          "name": "defaultRows",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "Rows of a widget the layout does not name"
+        },
+        {
+          "name": "minColumns",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The fewest expanded columns a resize leaves"
+        },
+        {
+          "name": "maxColumns",
+          "type": "number",
+          "defaultValue": "columns",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The most expanded columns a resize gives"
+        },
+        {
+          "name": "minRows",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The fewest rows a resize leaves"
+        },
+        {
+          "name": "maxRows",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The most rows a resize gives"
+        },
+        {
+          "name": "movable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "false fixes the widget at its cell; the others flow around it"
+        },
+        {
+          "name": "resizable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "false removes the edges, Shift+Arrow and the size items"
+        },
+        {
+          "name": "removable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "false removes Delete and Hide"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-dashboard-widget",
+          "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": "sl-dashboard-widget",
+          "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": "sl-dashboard-widget",
+          "description": "What the body says when it is not the content"
+        },
+        {
+          "name": "[slDashboardWidgetSkeleton]",
+          "type": "projected content",
+          "defaultValue": "one block",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The skeleton of the body’s own anatomy"
+        },
+        {
+          "name": "emptyTitle / emptyDescription",
+          "type": "string",
+          "defaultValue": "messages.emptyTitle / —",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The empty message; [slDashboardWidgetEmptyAction] is the action under it"
+        },
+        {
+          "name": "errorTitle / errorDescription",
+          "type": "string",
+          "defaultValue": "messages.errorTitle / —",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The error message"
+        },
+        {
+          "name": "retryable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "Draws Try again, which emits retry"
+        },
+        {
+          "name": "detailable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "Draws the detail action as a button, which emits detail"
+        },
+        {
+          "name": "detailHref",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The widget’s own page, as a link in the corner"
+        },
+        {
+          "name": "[slDashboardWidgetActions]",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The consumer’s controls in the header’s corner"
+        },
+        {
+          "name": "[slDashboardWidgetFooter]",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "Content under the body"
+        },
+        {
+          "name": "fill / size",
+          "type": "CardFill / CardSize",
+          "defaultValue": "outline / md",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The card’s own axes"
+        },
+        {
+          "name": "content",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "sl-dashboard-widget",
+          "description": "The body; kept in a template and drawn by the grid inside its own li and card, in the layout’s order"
+        },
+        {
+          "name": "provideDashboardGridDefaults",
+          "type": "{ columns, editBar, headingLevel }",
+          "defaultValue": "—",
+          "appliesTo": "providers",
+          "description": "The decisions an application takes once; an instance that states any of them wins. The words come from the language in force (provideSlotted)"
+        },
+        {
+          "name": "persistedDashboardLayout",
+          "type": "({ key, storage?, defaultLayout?, injector? }) => { layout, clear }",
+          "defaultValue": "localStorage",
+          "appliesTo": "an injection context",
+          "description": "A signal read once from the store and written after every change; bind it with [(layout)]"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "layoutChangeRequest",
+          "payload": "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; otherwise layout is set and [(layout)] hears it."
+        },
+        {
+          "name": "editingChangeRequest",
+          "payload": "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": "retry",
+          "payload": "MouseEvent",
+          "when": "On sl-dashboard-widget, when Try again under the error message is pressed; drawn under retryable."
+        },
+        {
+          "name": "detail",
+          "payload": "MouseEvent",
+          "when": "On sl-dashboard-widget, when the detail action is pressed: the link of detailHref, or the button of detailable."
+        },
+        {
+          "name": "(keydown) and the other native events",
+          "payload": "the element’s own event",
+          "when": "Reach the host. The handle’s own keys are taken in the capture phase, before its menu trigger reads them."
+        }
+      ],
+      "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": "html",
+      "source": "<div slDashboardGrid aria-label=\"Sales overview\" [(editing)]=\"editing\" [(layout)]=\"layout\">\n  <sl-dashboard-widget defaultColumns=\"3\" title=\"Revenue\" value=\"revenue\">\n    <sl-revenue-figure />\n  </sl-dashboard-widget>\n  <sl-dashboard-widget defaultColumns=\"8\" defaultRows=\"4\" title=\"Revenue by week\" value=\"trend\">\n    <sl-revenue-trend />\n  </sl-dashboard-widget>\n</div>\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": "html",
+      "source": "<sl-dashboard-widget\n  description=\"Last twelve weeks, all channels\"\n  detailHref=\"/reports/revenue\"\n  title=\"Revenue by week\"\n  value=\"trend\"\n>\n  <button slButton slDashboardWidgetActions size=\"sm\">Export</button>\n  <sl-revenue-trend />\n  <p slDashboardWidgetFooter slText size=\"sm\">Updated 4 minutes ago</p>\n</sl-dashboard-widget>\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": "html",
+      "source": "<button slButton (click)=\"editing.set(true)\">Edit layout</button>\n<div slDashboardGrid [(editing)]=\"editing\">…</div>\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": "html",
+      "source": "<div slDashboardGrid defaultEditing>…</div>\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": "html",
+      "source": "<sl-dashboard-widget [movable]=\"false\" title=\"Revenue\" value=\"revenue\" />\n<sl-dashboard-widget minColumns=\"4\" minRows=\"3\" title=\"Revenue by week\" value=\"trend\" />\n<sl-dashboard-widget [resizable]=\"false\" title=\"Conversion\" value=\"conversion\" />\n<sl-dashboard-widget [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": "html",
+      "source": "<sl-dashboard-widget [loading]=\"pending()\" title=\"Top products\" value=\"products\">\n  <div slDashboardWidgetSkeleton slSkeletonText [lines]=\"6\"></div>\n</sl-dashboard-widget>\n<sl-dashboard-widget [busy]=\"refreshing()\" title=\"Orders\" value=\"orders\" />\n<sl-dashboard-widget status=\"empty\" title=\"Refunds\" value=\"refunds\">\n  <button slButton slDashboardWidgetEmptyAction>Record a refund</button>\n</sl-dashboard-widget>\n<sl-dashboard-widget\n  retryable\n  status=\"error\"\n  title=\"Conversion\"\n  value=\"conversion\"\n  (retry)=\"refetch()\"\n/>\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": "html",
+      "source": "<div slDashboardGrid [columns]=\"{ expanded: 12, medium: 6, compact: 1 }\">…</div>\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": "ts",
+      "source": "@Component({\n  template: `<div slDashboardGrid [(layout)]=\"persisted.layout\">…</div>`,\n})\nclass SalesPage {\n  readonly persisted = persistedDashboardLayout({ key: 'trailhead-sales' });\n}\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. provideSlotted sets Portuguese here, and the defaults provider the heading level.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [\n    provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } }),\n    provideDashboardGridDefaults({ headingLevel: 2 }),\n  ],\n});\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() through exportAs.",
+      "language": "html",
+      "source": "<button slButton (click)=\"grid.commitEditing()\">Done</button>\n<div slDashboardGrid #grid=\"slDashboardGrid\" aria-label=\"Sales overview\" [editBar]=\"false\">…</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}