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

package/dist/docs/command-palette.json

@@ -0,0 +1,833 @@
+{
+  "family": "command-palette",
+  "ui": "command-palette",
+  "binding": "react",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Searchable dialog of commands and destinations."
+  },
+  "axes": {
+    "presentation": [
+      "dialog",
+      "inline"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "outsidePress": [
+      "close",
+      "none"
+    ],
+    "loop": [
+      true,
+      false
+    ],
+    "autoHighlight": [
+      true,
+      false
+    ],
+    "closeOnSelect": [
+      true,
+      false
+    ],
+    "clearOnClose": [
+      true,
+      false
+    ],
+    "highlightMatch": [
+      true,
+      false
+    ],
+    "loading": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "commandPalette": {
+      "nativeElement": "div",
+      "defaults": {
+        "presentation": "dialog",
+        "size": "md",
+        "outsidePress": "close",
+        "loop": true,
+        "autoHighlight": true,
+        "closeOnSelect": true,
+        "clearOnClose": true,
+        "highlightMatch": true,
+        "loading": false,
+        "disabled": false,
+        "hotkey": "mod+k",
+        "recentLimit": 5
+      },
+      "capabilities": [
+        "open",
+        "value",
+        "current",
+        "queue",
+        "size",
+        "appearance",
+        "disabled",
+        "loading",
+        "content",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open",
+        "disabled",
+        "loading",
+        "current"
+      ],
+      "parts": [
+        "root",
+        "trigger",
+        "header",
+        "search",
+        "busy",
+        "pages",
+        "page",
+        "input",
+        "clear",
+        "close",
+        "list",
+        "group",
+        "group-label",
+        "item",
+        "icon",
+        "label",
+        "match",
+        "description",
+        "meta",
+        "shortcut",
+        "arrow",
+        "separator",
+        "empty",
+        "status",
+        "placeholder",
+        "footer",
+        "hint"
+      ]
+    }
+  },
+  "docs": {
+    "commandPalette": {
+      "imports": {
+        "source": "import { CommandPalette, CommandPaletteDefaultsProvider, CommandPaletteTrigger } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "The panel. Carries data-ui=\"command-palette\", data-presentation, data-size, data-open, data-loading, data-disabled, data-query while something is typed and data-empty while nothing matched. Inside the dialog’s plain surface, or where it was written under presentation=\"inline\"."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": false,
+          "purpose": "The control that opens the palette, composed over the dialog family’s trigger. Rendered where it was written; render substitutes the element. Absent under presentation=\"inline\"."
+        },
+        {
+          "part": "header",
+          "element": "div",
+          "required": true,
+          "purpose": "The search row: the mark, the trail, the field and the clear."
+        },
+        {
+          "part": "search",
+          "element": "span",
+          "required": false,
+          "purpose": "The magnifier, drawn from the glyph scale. Replaced by busy while loading."
+        },
+        {
+          "part": "busy",
+          "element": "span",
+          "required": false,
+          "purpose": "The ring spinner draws, worn as data-ui=\"spinner\": in the header while loading, and at the end of a row whose handler has not answered."
+        },
+        {
+          "part": "pages",
+          "element": "ol",
+          "required": false,
+          "purpose": "The trail of open pages, oldest first, drawn only once a page is open."
+        },
+        {
+          "part": "page",
+          "element": "button",
+          "required": false,
+          "purpose": "One page in the trail. Pressing it returns to that page."
+        },
+        {
+          "part": "input",
+          "element": "input",
+          "required": true,
+          "purpose": "role=\"combobox\", aria-expanded=\"true\", aria-controls naming the list, aria-activedescendant naming the current row, aria-autocomplete=\"list\". DOM focus stays here for the whole interaction."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": true,
+          "purpose": "Empties the query. Out of the tab sequence and drawn only while there is something to clear."
+        },
+        {
+          "part": "close",
+          "element": "button",
+          "required": false,
+          "purpose": "The way out where the scrim is not: the close message at the end of the field, drawn by the stylesheet only while the dialog is full screen, asking open to be false with the reason dismiss. Absent inline."
+        },
+        {
+          "part": "list",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"listbox\". Scrolls inside the panel; aria-busy while loading."
+        },
+        {
+          "part": "group",
+          "element": "div",
+          "required": false,
+          "purpose": "role=\"group\", named by its group-label. The recents are the first group, labelled by the recent message."
+        },
+        {
+          "part": "group-label",
+          "element": "div",
+          "required": false,
+          "purpose": "The heading of a group."
+        },
+        {
+          "part": "item",
+          "element": "div | a",
+          "required": false,
+          "purpose": "role=\"option\". An anchor when the item has href. Carries aria-selected on the current row, aria-disabled, aria-busy and aria-keyshortcuts; data-current, data-disabled, data-loading and data-page."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The first column, holding the consumer’s icon. Present on every row so labels line up."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The command’s name, one line, cut with an ellipsis; the whole text is on the row’s title."
+        },
+        {
+          "part": "match",
+          "element": "mark",
+          "required": false,
+          "purpose": "The run of the label the query matched: the match part of the highlight family, whose root sits inside label."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "The second line under the label. Hidden below 360 pixels."
+        },
+        {
+          "part": "meta",
+          "element": "span",
+          "required": false,
+          "purpose": "A word at the end of the row — the kind of thing this is. Hidden from assistive technology and below 360 pixels."
+        },
+        {
+          "part": "shortcut",
+          "element": "span",
+          "required": false,
+          "purpose": "The binding, holding outline keycaps from kbd at a tenth under the row’s secondary type, with nothing drawn between them. Hidden from assistive technology; the row announces it through aria-keyshortcuts."
+        },
+        {
+          "part": "arrow",
+          "element": "span",
+          "required": false,
+          "purpose": "The chevron on a row that opens a page, mirrored in a right-to-left document."
+        },
+        {
+          "part": "separator",
+          "element": "div",
+          "required": false,
+          "purpose": "role=\"separator\", between two groups."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "The message when nothing matched: the empty message, or the empty prop."
+        },
+        {
+          "part": "status",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"status\", visually hidden: the result count, the loading sentence, the error of a rejected handler."
+        },
+        {
+          "part": "placeholder",
+          "element": "div",
+          "required": false,
+          "purpose": "Three skeleton rows while loading with nothing to show. Hidden from assistive technology."
+        },
+        {
+          "part": "footer",
+          "element": "div",
+          "required": false,
+          "purpose": "The keyboard hints. Replaced by the footer prop, removed by footer={null}."
+        },
+        {
+          "part": "hint",
+          "element": "span",
+          "required": false,
+          "purpose": "One hint: outline caps from kbd and a word."
+        }
+      ],
+      "api": [
+        {
+          "name": "items",
+          "type": "CommandPaletteItem[]",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The commands: id, label, keywords, description, group, icon, meta, shortcut, href, target, disabled, onSelect, children"
+        },
+        {
+          "name": "groups",
+          "type": "CommandGroup[]",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The headings and their order; a group not listed is drawn after them under its own id"
+        },
+        {
+          "name": "rank",
+          "type": "CommandRanker | null",
+          "defaultValue": "the core ranker",
+          "appliesTo": "CommandPalette",
+          "description": "(item, query) => number | null. Absent takes the locale-sensitive core ranker; null shows the items as they came"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "BCP 47, for the comparison the default ranker and the match mark make"
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "How many rows to draw at most, across groups in reading order"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The consumer’s value; present at all puts the layer in controlled mode"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CommandPalette",
+          "description": "The value an uncontrolled palette starts from, read once"
+        },
+        {
+          "name": "query",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The consumer’s text; present at all puts the query in controlled mode"
+        },
+        {
+          "name": "defaultQuery",
+          "type": "string",
+          "defaultValue": "''",
+          "appliesTo": "CommandPalette",
+          "description": "The text an uncontrolled palette starts from"
+        },
+        {
+          "name": "highlightedId",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The current row, controlled"
+        },
+        {
+          "name": "defaultHighlightedId",
+          "type": "string | null",
+          "defaultValue": "null",
+          "appliesTo": "CommandPalette",
+          "description": "The current row an uncontrolled palette starts from; autoHighlight moves it to the first row"
+        },
+        {
+          "name": "pages",
+          "type": "string[]",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The ids of the open pages, oldest first, controlled"
+        },
+        {
+          "name": "defaultPages",
+          "type": "string[]",
+          "defaultValue": "[]",
+          "appliesTo": "CommandPalette",
+          "description": "The pages an uncontrolled palette starts on"
+        },
+        {
+          "name": "recent",
+          "type": "string[]",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The ids the reader ran recently, newest first, controlled"
+        },
+        {
+          "name": "defaultRecent",
+          "type": "string[]",
+          "defaultValue": "[]",
+          "appliesTo": "CommandPalette",
+          "description": "The recents an uncontrolled palette starts with"
+        },
+        {
+          "name": "presentation",
+          "type": "'dialog' | 'inline'",
+          "defaultValue": "dialog",
+          "appliesTo": "CommandPalette",
+          "description": "dialog composes the dialog family; inline draws the panel where it was written"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "CommandPalette",
+          "description": "The dialog’s measure and the row’s control step"
+        },
+        {
+          "name": "outsidePress",
+          "type": "'close' | 'none'",
+          "defaultValue": "close",
+          "appliesTo": "CommandPalette",
+          "description": "Whether a press on the scrim closes the palette"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "CommandPalette",
+          "description": "Whether ArrowDown on the last row wraps to the first"
+        },
+        {
+          "name": "autoHighlight",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "CommandPalette",
+          "description": "Whether the first enabled row is current on open and after every change of the rows"
+        },
+        {
+          "name": "closeOnSelect",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "CommandPalette",
+          "description": "Whether running a row closes the palette; keepOpen() on the request holds it open once"
+        },
+        {
+          "name": "clearOnClose",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "CommandPalette",
+          "description": "Whether closing empties the query and the pages, each through its own request"
+        },
+        {
+          "name": "highlightMatch",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "CommandPalette",
+          "description": "Whether the run the query matched is marked in the label"
+        },
+        {
+          "name": "hotkey",
+          "type": "string | null",
+          "defaultValue": "mod+k",
+          "appliesTo": "CommandPalette",
+          "description": "The chord that opens the palette from anywhere; null for none. A bare key stays quiet in an editable field"
+        },
+        {
+          "name": "recentLimit",
+          "type": "number",
+          "defaultValue": "5",
+          "appliesTo": "CommandPalette",
+          "description": "How many recents are kept"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CommandPalette",
+          "description": "The ring in the header, three skeleton rows when there is nothing to show, aria-busy on the list, the loading message in the status row"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CommandPalette",
+          "description": "Disables the field, the trigger and the hotkey"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<CommandPaletteMessages>",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "Words laid over the language in force, key by key: the dialog’s name (label), the field’s name and placeholder (input, placeholder), the empty, loading, count and error sentences, the recents heading, the clear, close and back controls, and the footer’s hints"
+        }
+      ],
+      "composition": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "The trigger, rendered where it was written; the panel is the family’s and goes into the layer"
+        },
+        {
+          "name": "render",
+          "type": "(props: CommandPaletteTriggerRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CommandPaletteTrigger",
+          "description": "Substitutes the trigger’s element. Attach the ref it hands you beside your own: it is the layer’s focus origin"
+        },
+        {
+          "name": "renderItem",
+          "type": "(item, state: { current, disabled, pending, label, query }) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "Replaces the row’s content; the option element and its wiring stay the family’s. state.label is the marked label"
+        },
+        {
+          "name": "empty",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "Replaces the empty message"
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode | null",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "Replaces the footer; null removes it"
+        },
+        {
+          "name": "inputProps",
+          "type": "ComponentPropsWithRef<'input'>",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "Native props for the field, ref included; onKeyDown and onChange run before the family’s and preventDefault() skips it"
+        },
+        {
+          "name": "container",
+          "type": "Element | null",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "A parent for the layer alone, instead of the portal root made beside the trigger"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<CommandPaletteHandle>",
+          "defaultValue": "—",
+          "appliesTo": "CommandPalette",
+          "description": "open(), close(), toggle(), focus(), setQuery(), scrollToId(), and the input element"
+        },
+        {
+          "name": "CommandPaletteDefaultsProvider",
+          "type": "Partial<CommandPaletteDefaults>",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Every axis, set once; an explicit prop still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the palette opens or closes; reason is pointer, keyboard, escape, outsidePress, select, dismiss or programmatic. request.cancel() refuses it."
+        },
+        {
+          "name": "onQueryChange",
+          "payload": "(query: string, request: ChangeRequest<string>)",
+          "when": "Before the query moves: keyboard as the reader types, clear from the clear control or Escape, select when a page opens, programmatic on close and from the handle."
+        },
+        {
+          "name": "onHighlightedIdChange",
+          "payload": "(id: string | null, request: ChangeRequest<string | null>)",
+          "when": "Before the current row moves: pointer, keyboard, or programmatic when the rows changed under it."
+        },
+        {
+          "name": "onPagesChange",
+          "payload": "(pages: readonly string[], request: ChangeRequest<readonly string[]>)",
+          "when": "Before a page opens or closes: select from Enter on a row with children, pointer from a click on one or on the trail, keyboard from Backspace or Escape, programmatic on close."
+        },
+        {
+          "name": "onRecentChange",
+          "payload": "(recent: readonly string[], request: ChangeRequest<readonly string[]>)",
+          "when": "After a row ran, with its id moved to the front and the array cut at recentLimit; reason select."
+        },
+        {
+          "name": "onSelect",
+          "payload": "(item, request: { item, reason, source, keepOpen() })",
+          "when": "When a row runs, after the row’s own onSelect and after a returned promise fulfilled; reason pointer or keyboard. Never for a disabled row or a row that opens a page."
+        }
+      ],
+      "accessibility": [
+        "The field carries role=\"combobox\" with aria-expanded=\"true\", aria-controls naming the list and aria-autocomplete=\"list\"; the list carries role=\"listbox\" and each row role=\"option\". DOM focus stays on the field for the whole interaction and the current row is named by aria-activedescendant and marked aria-selected — the WAI-ARIA combobox pattern with a listbox popup, whose note says exactly this.",
+        "The layer is the dialog family’s: role=\"dialog\", aria-modal, the page inert behind the scrim, focus contained and returned to the trigger. Its name is the label message; the field’s name is the input message, and the list borrows it.",
+        "A row with a shortcut carries aria-keyshortcuts in the platform’s own words — Meta+Shift+D on a Mac, Control+Shift+D elsewhere — while the drawn keys are aria-hidden; a sequence has no syntax in the attribute and is drawn only. A disabled row is announced with aria-disabled, stays in the list, and is skipped by every movement key.",
+        "The result count, the loading sentence and the failure of a rejected handler are one visually hidden role=\"status\" row, spoken through the shared live announcer so the same sentence is never said twice in a row.",
+        "Escape is three steps in a fixed order — clear the query, return one page, close — so a reader who typed does not lose the palette on the first press; the footer draws the same keys the family answers.",
+        "The panel answers its own width: below 360 pixels the description and the meta go and the binding stays; inside a dialog on a narrow screen the panel takes the whole layer."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-command-palette-active",
+    "--slotted-command-palette-border-color",
+    "--slotted-command-palette-footer-surface",
+    "--slotted-command-palette-highlight",
+    "--slotted-command-palette-highlight-ring",
+    "--slotted-command-palette-hover",
+    "--slotted-command-palette-item-radius",
+    "--slotted-command-palette-list-max-block-size",
+    "--slotted-command-palette-list-padding",
+    "--slotted-command-palette-measure",
+    "--slotted-command-palette-page-surface",
+    "--slotted-command-palette-placeholder-fade",
+    "--slotted-command-palette-radius",
+    "--slotted-command-palette-separator-color",
+    "--slotted-command-palette-shadow",
+    "--slotted-command-palette-surface",
+    "--slotted-command-palette-text",
+    "--slotted-command-palette-text-muted",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-lg",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-line-height-xs",
+    "--slotted-radius-lg",
+    "--slotted-radius-sm",
+    "--slotted-shadow-lg",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-6",
+    "--slotted-space-8",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Press the trigger, or ⌘K, and the palette opens at the top of the layer with the first row already current. Type to rank, arrow to move, Enter to run.",
+      "language": "tsx",
+      "source": "<CommandPalette groups={groups} items={items} onSelect={(item) => run(item.id)}>\n  <CommandPaletteTrigger render={(props) => <Button {...props}>Search</Button>} />\n</CommandPalette>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, inline",
+      "note": "The same panel with no layer around it, so every part can be pointed at: the header with its mark and clear, the grouped list, the current row, a row with a description and a binding, and the footer of hints.",
+      "language": "tsx",
+      "source": "const items = [\n  {\n    id: 'deploy',\n    label: 'Deploy to production',\n    description: 'Ship the current release of api-gateway',\n    keywords: ['ship', 'release'],\n    group: 'actions',\n    icon: <RocketIcon />,\n    shortcut: 'mod+shift+d',\n    onSelect: () => deploy(),\n  },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "groups",
+      "title": "Groups, in the order the product declares",
+      "note": "groups gives each heading its label and its place; an item whose group is not listed lands under its own id, after them, and an item with no group closes the list.",
+      "language": "tsx",
+      "source": "<CommandPalette\n  groups={[\n    { id: 'nav', label: 'Go to' },\n    { id: 'actions', label: 'Actions' },\n  ]}\n  items={items}\n  presentation=\"inline\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "ranking",
+      "title": "Ranking, and the adapter",
+      "note": "Type “dep”: a label that starts with it outranks a word that starts with it, which outranks a run inside a word, which outranks a keyword; groups reorder by their best row. The third panel hands the order to a ranker of the product’s own.",
+      "language": "tsx",
+      "source": "<CommandPalette defaultQuery=\"dep\" items={items} presentation=\"inline\" />;\n\n// A server has already ranked the list: show it as it came.\n<CommandPalette items={results} presentation=\"inline\" rank={null} />;\n\n// Or score it yourself.\n<CommandPalette\n  items={items}\n  presentation=\"inline\"\n  rank={(item, query) => (item.label.toLowerCase().includes(query) ? item.weight : null)}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "pages",
+      "title": "Pages, stacked",
+      "note": "A row with children opens a page: the trail appears before the field, the children take the list, and Backspace on an empty query or Escape returns one page. pages is state the product may own.",
+      "language": "tsx",
+      "source": "const items = [\n  {\n    id: 'team',\n    label: 'Switch team…',\n    children: [\n      { id: 'acme', label: 'Acme Robotics', onSelect: () => switchTo('acme') },\n      { id: 'globex', label: 'Globex Freight', onSelect: () => switchTo('globex') },\n    ],\n  },\n];\n\n<CommandPalette defaultPages={['team']} items={items} presentation=\"inline\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "recent",
+      "title": "What the reader ran last",
+      "note": "With nothing typed, the recents open the list under their own heading; running a row moves it to the front and cuts the array at recentLimit. Persisting it is the product’s — it receives the array.",
+      "language": "tsx",
+      "source": "const [recent, setRecent] = useState(() => JSON.parse(localStorage.getItem('recent') ?? '[]'));\n\n<CommandPalette\n  items={items}\n  onRecentChange={(next) => {\n    setRecent(next);\n    localStorage.setItem('recent', JSON.stringify(next));\n  }}\n  presentation=\"inline\"\n  recent={recent}\n  recentLimit={3}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shortcuts",
+      "title": "Shortcuts, drawn for the platform",
+      "note": "One notation, mod+shift+d, becomes ⌘⇧D on a Mac and Ctrl+Shift+D elsewhere, and is announced as Meta+Shift+D or Control+Shift+D. A sequence such as g i is drawn and not announced. The palette binds none of them: the three lines below do.",
+      "language": "tsx",
+      "source": "useEffect(() => {\n  const onKey = (event: KeyboardEvent) => {\n    const hit = items.find(\n      (item) => item.shortcut && matchesShortcut(event, item.shortcut, platform),\n    );\n    if (hit) hit.onSelect?.();\n  };\n  document.addEventListener('keydown', onKey);\n  return () => document.removeEventListener('keydown', onKey);\n}, [items, platform]);\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "destinations",
+      "title": "Rows that are places",
+      "note": "A row with href renders as a link with role option: Enter follows it, ⌘Enter opens it in a new tab because the browser, not the palette, answers the modifier. meta says what kind of place it is.",
+      "language": "tsx",
+      "source": "const items = [\n  { id: 'billing', label: 'Billing', href: '/settings/billing', meta: 'Page' },\n  { id: 'invoice', label: 'Download last invoice', onSelect: () => download() },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "async",
+      "title": "A command that takes a while",
+      "note": "A handler that returns a promise keeps the palette open and the row busy, refuses a second run of the same row until it settles, then closes; a rejection keeps it open and the status row says why. Press the first row and wait two seconds.",
+      "language": "tsx",
+      "source": "const items = [\n  { id: 'restart', label: 'Restart api-gateway', onSelect: () => api.restart('api-gateway') },\n  {\n    id: 'purge',\n    label: 'Purge CDN cache',\n    onSelect: () => Promise.reject(new Error('Not allowed')),\n  },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "loading",
+      "title": "While the results travel",
+      "note": "loading swaps the magnifier for the ring, draws three skeleton rows when there is nothing to show yet, and says the loading message in the status row. The palette debounces nothing: the product does, in three lines.",
+      "language": "tsx",
+      "source": "const [query, setQuery] = useState('');\nconst [loading, setLoading] = useState(false);\nconst [results, setResults] = useState([]);\n\nuseEffect(() => {\n  setLoading(true);\n  const timer = setTimeout(\n    () =>\n      search(query)\n        .then(setResults)\n        .finally(() => setLoading(false)),\n    200,\n  );\n  return () => clearTimeout(timer);\n}, [query]);\n\n<CommandPalette\n  items={results}\n  loading={loading}\n  onQueryChange={setQuery}\n  query={query}\n  rank={null}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "empty",
+      "title": "Nothing matched",
+      "note": "The empty part takes the list, the count row says “0 results”, and the root carries data-empty. The second panel replaces the sentence with the product’s own node.",
+      "language": "tsx",
+      "source": "<CommandPalette\n  defaultQuery=\"xylophone\"\n  empty={<span>No command matches. Try a service name.</span>}\n  items={items}\n  presentation=\"inline\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "inline",
+      "title": "Without a layer",
+      "note": "presentation=\"inline\" draws the panel where it was written — here inside a popover on an “Assign to” button — with no scrim, no hotkey and no Escape to close. It is the filtered menu that menu refused.",
+      "language": "tsx",
+      "source": "<Popover>\n  <PopoverTrigger render={(props) => <Button {...props}>Assign to…</Button>} />\n  <PopoverContent>\n    <CommandPalette items={people} presentation=\"inline\" footer={null} />\n  </PopoverContent>\n</Popover>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three measures",
+      "note": "size is the dialog’s measure — 24, 32 and 42 rems — and the row’s step: sm rows read the small control geometry, lg rows the large, and the header stands one step above the rows in each.",
+      "language": "tsx",
+      "source": "<CommandPalette items={items} presentation=\"inline\" size=\"sm\" />;\n<CommandPalette items={items} presentation=\"inline\" size=\"lg\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state a row can be in",
+      "note": "At rest, current from the keyboard, busy while its handler runs, disabled but announced and kept in place, opening a page, and a link. Hover a row that is not current for the quieter wash.",
+      "language": "tsx",
+      "source": "const items = [\n  {\n    id: 'delete',\n    label: 'Delete workspace',\n    description: 'Requires the owner role',\n    disabled: true,\n  },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A German label of sixty characters, a description longer than the row, a binding of four keys and a row with no icon beside rows that have one: the label gives way, the binding never does, and the icon column keeps every label on one line.",
+      "language": "tsx",
+      "source": "const items = [\n  {\n    id: 'sync',\n    label: 'Benachrichtigungseinstellungen für alle Arbeitsbereiche synchronisieren',\n    shortcut: 'mod+shift+alt+p',\n  },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "hotkey",
+      "title": "The chord that opens it",
+      "note": "mod+k by default, matched on the document in the capture phase with preventDefault, so Firefox’s search bar does not answer first. A bare key such as / stays quiet inside a text field; hotkey={null} turns it off. Focus the page and press ⌘K or Ctrl+K.",
+      "language": "tsx",
+      "source": "<CommandPalette hotkey=\"mod+p\" items={items} />;\n<CommandPalette hotkey=\"/\" items={items} />;\n<CommandPalette hotkey={null} items={items} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "defaults",
+      "title": "Set once for the application",
+      "note": "The provider holds every axis, and SlottedProvider the language the family speaks: the panel below reads Portuguese words, a size and a hotkey it did not state itself.",
+      "language": "tsx",
+      "source": "<SlottedProvider locale=\"pt-BR\">\n  <CommandPaletteDefaultsProvider hotkey=\"mod+p\" size=\"sm\">\n    <App />\n  </CommandPaletteDefaultsProvider>\n</SlottedProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "In an application’s top bar",
+      "note": "The trigger is a search-shaped Button with a Kbd in it, rendered through render so the palette hands it the wiring and the ref; the row content is the product’s own through renderItem, with an avatar where the icon column is.",
+      "language": "tsx",
+      "source": "<CommandPalette\n  items={items}\n  renderItem={(item, state) => (\n    <>\n      <span data-part=\"icon\">\n        <Avatar name={item.label} size=\"xs\" />\n      </span>\n      <span data-part=\"label\">{state.label}</span>\n    </>\n  )}\n>\n  <CommandPaletteTrigger\n    render={(props) => (\n      <Button {...props} tone=\"secondary\" variant=\"outline\">\n        Search <Kbd size=\"sm\">⌘K</Kbd>\n      </Button>\n    )}\n  />\n</CommandPalette>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keys",
+      "note": "Arrows move and wrap, PageUp and PageDown move ten and stop, Ctrl+Home and Ctrl+End reach the ends, Home and End keep moving the caret, Enter runs, Escape clears then returns a page then closes, Backspace on an empty query returns a page.",
+      "language": "tsx",
+      "source": "<CommandPalette items={items} presentation=\"inline\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a screen reader meets",
+      "note": "The dialog is named by the label message, the field by the input message, the list by the same; the current row is aria-selected and named by aria-activedescendant; the count, the wait and a failure are one live region. Open the tree to read it.",
+      "language": "tsx",
+      "source": "<CommandPalette\n  items={items}\n  messages={{ input: 'Search deployments', label: 'Deployment commands' }}\n/>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}