@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/organisms/forms/subscribe-form.pidl.json

@@ -0,0 +1,188 @@
+{
+    "kind": "component",
+    "id": "ui.subscribe-form",
+    "name": "SubscribeForm",
+    "displayName": "Subscribe Form",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "forms",
+    "bidi": true,
+    "studioReady": false,
+    "description": "Backend-agnostic email-capture form for landing pages, waitlists, and newsletter signups. Composes an email Input and submit Button, manages an idle/submitting/success/error state machine, validates email format client-side, and includes a honeypot spam trap. Delivers submissions via a custom onSubmit handler or by POSTing JSON to an action URL — never hardcodes a specific email provider.",
+    "props": [
+        {
+            "name": "emailLabel",
+            "label": "Email label",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "default": "Email",
+            "description": "Accessible label for the email field."
+        },
+        {
+            "name": "placeholder",
+            "label": "Placeholder",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "default": "you@example.com",
+            "description": "Email input placeholder text."
+        },
+        {
+            "name": "buttonLabel",
+            "label": "Button label",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "default": "Subscribe",
+            "description": "Submit button label — static string or signal accessor."
+        },
+        {
+            "name": "successMessage",
+            "label": "Success message",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "default": "Thanks for subscribing!",
+            "description": "Message shown and announced after a successful submission."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "default": "Something went wrong. Please try again.",
+            "description": "Message shown and announced when submission fails, and used as the email field's error text."
+        },
+        {
+            "name": "disclaimer",
+            "label": "Disclaimer",
+            "editor": { "tab": "content" },
+            "type": "string",
+            "description": "Optional small print rendered below the form (e.g. privacy note)."
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "default": "primary",
+            "description": "Semantic color forwarded to the submit Button."
+        },
+        {
+            "name": "size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size forwarded to the Input and Button."
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit id for the root <form> element."
+        },
+        {
+            "name": "action",
+            "label": "Action URL",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Endpoint to POST { email } as JSON when submitted. Ignored when onSubmit is also provided."
+        },
+        {
+            "name": "onSubmit",
+            "type": "(email: string) => void | Promise<void>",
+            "required": false,
+            "description": "Custom submit handler, called with the validated email address. Takes precedence over action when both are set."
+        }
+    ],
+    "events": ["submit"],
+    "slots": [],
+    "tokens": {
+        "fields.gap": "--space-md",
+        "disclaimer.margin-top": "--space-sm"
+    },
+    "spacing": {
+        "internal": {
+            "input-to-button": { "relationship": "friends", "token": "md" },
+            "form-to-disclaimer": { "relationship": "close-friends", "token": "sm" }
+        }
+    },
+    "constraints": [
+        "Composes the Input and Button atoms — never renders a raw <input>/<button>",
+        "State machine is idle → submitting → success | error, exposed as a reactive `state` accessor on the returned handle",
+        "onSubmit takes precedence over action when both are provided",
+        "When neither action nor onSubmit is provided, submit is a no-op and a DEV warning is logged at construction time",
+        "Client-side email format validation runs before submission; invalid/empty email blocks submit and marks the Input invalid without entering the submitting state",
+        "Honeypot field (name=_honey) is checked before validation; a filled honeypot silently aborts submission with no error or state change",
+        "action mode POSTs JSON: fetch(action, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email }) }); a non-2xx response is treated as an error",
+        "On success, the email/button fields are hidden and replaced with the successMessage; on error, the fields remain visible and enabled for retry",
+        "All CSS uses design system tokens"
+    ],
+    "a11y": [
+        "Native <form novalidate> element",
+        "Email field is named via aria-label (Input renders a visible <label> only in floatingLabel mode, which SubscribeForm does not use); aria-invalid and aria-describedby wire the error text. Sighted users rely on the placeholder plus the adjacent submit button for context — pass a visible heading/disclaimer alongside the form when more context is needed",
+        "Focus is managed across every terminal state: validation failure and submission failure return focus to the email field (native disabled blurs it during submit), success moves focus to the message that replaces the row",
+        "Exactly one announcement per outcome — the field error is announced by the Input's role=alert span and the success text by the focus move, so the sr-only status region is intentionally left empty rather than duplicating either string",
+        "Error state (validation or submission failure) is driven by passing a reactive error/errorMessage into the Input",
+        "An aria-live='polite' status region is present for outcome announcements but is deliberately kept empty — see the single-announcement rule above; it exists so a future summary (e.g. an error count) has somewhere to go without re-introducing duplicate announcements",
+        "Honeypot input is aria-hidden, tabindex=-1, autocomplete=off, and wrapped in a display:none container so it is invisible to sighted users and skipped by autofill, while still catching bots that scrape the DOM",
+        "Submit button shows a loading state (via Button) during async submit"
+    ],
+    "ai": {
+        "synonyms": [
+            "newsletter",
+            "waitlist",
+            "email signup",
+            "subscribe",
+            "mailing list"
+        ],
+        "avoid": [
+            "Using SubscribeForm for multi-field forms — use DynamicForm instead",
+            "Hardcoding a specific email provider — SubscribeForm is backend-agnostic via action/onSubmit",
+            "Putting custom validation logic in onSubmit — email format validation is built in"
+        ],
+        "patterns": [
+            "Waitlist: SubscribeForm({ buttonLabel: 'Join waitlist', successMessage: \"You're on the list!\" })",
+            "Newsletter with custom handler: SubscribeForm({ onSubmit: async (email) => api.subscribe(email) })",
+            "Zero-backend export: SubscribeForm({ action: 'https://api.example.com/subscribe' })",
+            "With disclaimer: SubscribeForm({ disclaimer: 'No spam, unsubscribe anytime.' })"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic subscribe form with onSubmit",
+            "code": "SubscribeForm({ successMessage: \"You're on the list!\", onSubmit: async (email) => api.subscribe(email) })",
+            "assertions": [
+                "renders email Input and submit Button",
+                "invalid email blocks submit",
+                "onSubmit called with the validated email on submit",
+                "shows successMessage and hides fields after success"
+            ]
+        },
+        {
+            "id": "action",
+            "title": "Zero-backend export via action URL",
+            "code": "SubscribeForm({ action: 'https://api.example.com/subscribe', disclaimer: 'No spam, unsubscribe anytime.' })",
+            "assertions": [
+                "POSTs { email } as JSON to the action URL",
+                "non-2xx response transitions to error state",
+                "disclaimer rendered below the form"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No surface styling on the form itself — Input and Button provide all visual feedback.",
+        "depth": "None — transparent container.",
+        "borders": "None.",
+        "interactivity": "Submit button uses Button solid variant with loading state during async submit; both Input and Button are disabled while submitting.",
+        "bestPractices": "Use SubscribeForm for single-purpose email capture (newsletter, waitlist). Use DynamicForm when you need more than one field. Always provide either action or onSubmit — an unconfigured form is a dead end for visitors."
+    }
+}

package/dist/specs/organisms/navigation/command-palette.pidl.json

@@ -0,0 +1,263 @@
+{
+    "kind": "component",
+    "id": "ui.command-palette",
+    "name": "CommandPalette",
+    "displayName": "Command palette",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "navigation",
+    "studioReady": false,
+    "bidi": true,
+    "description": "⌘K command palette — a modal search field over a filtered command list. Composes <Modal> for the dialog (focus trap, Escape, backdrop) and <SearchInput> for the field, and adds the WAI-ARIA combobox-with-listbox-popup semantics on top: aria-expanded / aria-controls / aria-activedescendant on the field, a role=\"listbox\" of role=\"option\" items, real role=\"group\" sections for grouped commands, and a polite live region announcing the result count. SHELL ONLY — it owns no index. The default filter is a case-insensitive substring test over label + description + keywords, replaceable via the filter prop; the real search engine (Pagefind / Fuse over the codex index) is R3. studioReady is FALSE on purpose: the palette is driven by an open signal and an items array supplied in code, so there is nothing meaningful to author or preview on a canvas.",
+    "props": [
+        {
+            "name": "open",
+            "label": "Open",
+            "required": true,
+            "reactive": true,
+            "editor": { "tab": "settings", "type": "boolean" },
+            "type": "boolean | Signal<boolean>",
+            "description": "Whether the palette is showing. The palette never opens itself — pair this with onRequestOpen for the ⌘K binding."
+        },
+        {
+            "name": "items",
+            "label": "Commands",
+            "required": true,
+            "reactive": true,
+            "editor": { "tab": "content", "type": "array" },
+            "type": "CommandPaletteItem[] | Signal<CommandPaletteItem[]>",
+            "itemSchema": {
+                "id": { "type": "string", "required": true },
+                "label": { "type": "string", "required": true },
+                "description": { "type": "string" },
+                "group": { "type": "string" },
+                "icon": { "type": "string", "editor": { "type": "icon" } },
+                "href": { "type": "string" },
+                "keywords": { "type": "array" },
+                "disabled": { "type": "boolean" }
+            },
+            "placeholder": [
+                { "id": "home", "label": "Go home", "group": "Navigate", "href": "/" },
+                {
+                    "id": "docs",
+                    "label": "Open docs",
+                    "group": "Navigate",
+                    "href": "/docs",
+                    "keywords": ["guide", "reference"]
+                },
+                {
+                    "id": "theme",
+                    "label": "Toggle theme",
+                    "group": "Actions",
+                    "description": "Switch between light and dark"
+                }
+            ],
+            "description": "The full command list, in the order it should appear. Grouping follows list order — a new role=\"group\" section is opened whenever `group` changes — so sort the array the way you want it read. Each item's `id` is surfaced on the rendered option as data-command-id (a stable hook for tests and analytics); it is NOT the option's id attribute, which must be document-unique for aria-activedescendant."
+        },
+        {
+            "name": "placeholder",
+            "label": "Placeholder",
+            "type": "string",
+            "default": "Type a command or search…",
+            "placeholder": "Type a command or search…",
+            "description": "Placeholder for the search field."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "default": "Command palette",
+            "placeholder": "Command palette",
+            "description": "Accessible name for the dialog. The search field and the results listbox get their OWN names ('Search commands' and 'Results') rather than reusing this one — three nested regions sharing a name makes a screen reader announce it three times before the reader reaches the first command."
+        },
+        {
+            "name": "emptyMessage",
+            "label": "Empty message",
+            "type": "string",
+            "default": "No results found",
+            "placeholder": "No results found",
+            "description": "Shown in place of the list when nothing matches — and announced through the live region, so the empty state is not silent."
+        },
+        {
+            "name": "hotkey",
+            "label": "Hotkey",
+            "editor": { "tab": "settings", "type": "string" },
+            "type": "string | false",
+            "default": "k",
+            "placeholder": "k",
+            "description": "Letter bound alongside the platform modifier (Meta or Control — both are accepted, so ⌘K and Ctrl+K each work). Modifiers must match exactly: Alt and Shift are excluded, so Cmd/Ctrl+Shift+K does not hijack the browser console shortcut. false binds nothing. The binding only exists when onRequestOpen is supplied."
+        },
+        {
+            "name": "maxResults",
+            "label": "Max results",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "default": 50,
+            "description": "Cap on rendered options. A palette is a shortlist — beyond a few dozen rows the reader should be typing, not scrolling, and every extra row is a DOM node rebuilt on each keystroke."
+        },
+        {
+            "name": "onClose",
+            "label": "On close",
+            "required": true,
+            "type": "() => void",
+            "description": "Called when the palette should close — Escape, a backdrop click, or a selection. The component does not own `open`; this is how it asks to be closed."
+        },
+        {
+            "name": "onSelect",
+            "label": "On select",
+            "type": "(item: CommandPaletteItem) => void",
+            "description": "Called for EVERY activation, after the item's own onSelect and before onClose. A pure observer: unlike an item's own onSelect it does NOT suppress href navigation, so adding analytics here cannot silently turn every link in the list into a no-op."
+        },
+        {
+            "name": "onRequestOpen",
+            "label": "On request open",
+            "type": "() => void",
+            "description": "Called when the hotkey fires. Supplying it is what enables the document-level binding — a palette with no way to open itself has no business owning a global shortcut."
+        },
+        {
+            "name": "filter",
+            "label": "Filter",
+            "type": "(items: CommandPaletteItem[], query: string) => CommandPaletteItem[]",
+            "description": "Replace the matcher. The default is a case-insensitive substring test over label, description and keywords; an empty query returns everything. This is the seam a real ranking engine drops into."
+        },
+        {
+            "name": "navigate",
+            "label": "Navigate",
+            "type": "(href: string) => void",
+            "description": "How an href-only item is followed. Defaults to a full page navigation; pass the router's navigate to keep it client-side."
+        }
+    ],
+    "tokens": {
+        "typography": "--font-size-body (option label), --font-size-sm (description, empty state), --font-size-xs + --font-weight-semibold (group heading), --line-height-body",
+        "color": "--color-text (options), --color-text-muted (group headings, descriptions, icons, empty state), --color-primary via --_option-accent (active row tint + icon), --color-divider (rule under the field)",
+        "spacing": "--space-xs (icon ↔ label, list padding, option block padding), --space-sm (option inline padding, group heading inline padding), --space-lg (empty-state block padding), --space-xl (dialog offset from the top of the viewport)",
+        "radius": "--radius-sm (option row); the dialog radius comes from modal.scss",
+        "border": "--border-width-hairline + --border-style-solid (the rule separating the query from its results)",
+        "state": "--state-selected-opacity via the a11y state-background mixin (active row), --state-disabled-opacity (disabled row)",
+        "motion": "--motion-transition-background / --motion-transition-color on the option row, inside prefers-reduced-motion: no-preference; the dialog entrance belongs to modal.scss"
+    },
+    "spacing": {
+        "icon-to-label": "--space-xs (Lovers) — the glyph and its command are one unit",
+        "option-padding": "--space-xs block / --space-sm inline — enough hit area without turning the list into a button stack",
+        "group-heading": "--space-xs block (Lovers) — a heading sits tight against the options it owns, not floating between two groups",
+        "dialog-offset": "--space-xl from the top of the viewport (Strangers) — the palette is anchored, not centred, so it grows downward without drifting under the cursor"
+    },
+    "constraints": [
+        "SHELL ONLY. No search backend, no fuzzy matching, no index. The default filter is a substring test; anything smarter arrives through the `filter` prop",
+        "The dialog, focus trap, Escape handling and backdrop come from <Modal>; the field comes from <SearchInput> with landmark=false. This component owns only the combobox semantics, the roving highlight and the filter state",
+        "The panel is rebuilt from scratch on every open (Modal re-invokes its content factory), which is what resets the query to '' and the active option to the first match — a stale query and a stale highlight are the two things that make a palette feel broken",
+        "Escape always closes; it never merely clears. <Modal> listens on window in the CAPTURE phase with stopImmediatePropagation, so it wins the key before the field's own Escape-to-clear can run. That is deliberate — one Escape, one outcome",
+        "The active option is tracked as an index into the rendered (filtered, capped) list, never into the source array — the two diverge the moment a query is typed",
+        "The active index is clamped at BOTH ends on every render. -1 (the value left behind when a render found no selectable option) is not 'before the list' to the wrapping step function: its modulo maps -1 to the LAST index, so a reactive items update arriving while a no-match query is showing would otherwise highlight the bottom row and make Enter fire the wrong command",
+        "Grouped commands use the APG grouped-listbox shape: a role=\"presentation\" <li> (present only because a <ul> may not hold a bare <ul>) wrapping a visible heading plus a real <ul role=\"group\" aria-label>. A bare role=\"presentation\" heading <li> — the obvious shortcut — is dropped from the accessibility tree entirely: it labels nothing, and listbox owns only option and group children, so grouping would be sighted-only",
+        "A heading is emitted only when its group actually has a surviving item, so filtering never leaves an orphan heading",
+        "Disabled items render but are unreachable: arrow keys step over them, Home/End land past them, click and Enter refuse them",
+        "An item's href is followed ONLY when the item carries no onSelect of its own. A palette-level onSelect does NOT suppress it: a cross-cutting observer (analytics, a recents list) disabling every link in the list would be silent action at a distance. The href is validated with isSafeHref() first, so a javascript: URL in a command list goes nowhere",
+        "The hotkey listener exists only when onRequestOpen is supplied, and is removed on destroy",
+        "The hotkey is ignored while focus is in an editable element (input, textarea, select, contenteditable) unless the palette is already open — otherwise ⌘K would fire out from under someone typing",
+        "maxResults caps rendering, not filtering — the filter still sees every item, so a custom ranking filter can order the whole set before the cap applies"
+    ],
+    "a11y": [
+        "Implements the WAI-ARIA combobox-with-listbox-popup pattern in full. Partial ARIA is worse than none, so the entire keyboard model ships with the roles",
+        "The field carries role=\"combobox\", aria-autocomplete=\"list\", aria-controls pointing at the listbox, aria-expanded tracking whether there are results, and aria-activedescendant naming the active option",
+        "DOM focus never leaves the field. The highlight moves through aria-activedescendant, which is what keeps typing and navigating in the same control",
+        "Exactly one option carries aria-selected=\"true\" at a time; aria-activedescendant is REMOVED when nothing matches, not set to the empty string — an empty string is not a valid IDREF, and omission is the conformant way to say 'nothing is active'",
+        "Keyboard: ArrowDown/ArrowUp rove and WRAP, skipping disabled options; Home/End jump to the first/last enabled option; Enter activates; Escape closes the dialog",
+        "Disabled options are aria-disabled=\"true\" and are skipped by every one of those keys — an option that can be reached but not chosen is a dead end",
+        "The active option is scrolled into view with block: 'nearest', guarded for environments without layout",
+        "Grouped commands sit inside a real <ul role=\"group\" aria-label>, so the group name is announced on entry and the options stay countable. The visible heading is aria-hidden because the group's aria-label already carries the same string",
+        "A visually-hidden role=\"status\" aria-live=\"polite\" region announces the result count as the query changes — otherwise a sighted-only list update is silent. It stays silent until the reader actually types, so opening the palette does not immediately talk over the field",
+        "The dialog is role=\"dialog\" aria-modal=\"true\" with an accessible name, and takes initial focus on the search field rather than the first focusable element",
+        "The dialog, the field and the listbox carry three DISTINCT accessible names ('Command palette', 'Search commands', 'Results'). Reusing one name across all three makes a screen reader announce it three times before the reader reaches the first command",
+        "Escape always closes the palette and never merely clears the query: <Modal> listens on window in the CAPTURE phase with stopImmediatePropagation(), so it wins the key before <SearchInput>'s own Escape-to-clear can run. One Escape, one outcome",
+        "The field is rendered with landmark=false: a role=\"search\" landmark nested inside a modal is not something a reader can navigate to as a landmark",
+        "The active row's tint is redrawn with Highlight/HighlightText under forced colours, and disabled rows with GrayText, because the author colours are discarded there",
+        "Row transitions are wrapped in prefers-reduced-motion: no-preference"
+    ],
+    "ai": {
+        "synonyms": [
+            "command palette",
+            "cmd k",
+            "command k",
+            "⌘K",
+            "quick open",
+            "quick actions",
+            "spotlight",
+            "omnibox",
+            "action search",
+            "fuzzy finder",
+            "command menu"
+        ],
+        "avoid": [
+            "expecting it to search anything — it filters the array you hand it. The docs search backend is R3",
+            "putting a <SearchInput landmark=\"true\"> inside it — the palette already supplies the field, with the landmark correctly dropped",
+            "hand-rolling the combobox ARIA on a <Modal> — aria-activedescendant, wrapping arrow keys, disabled-skipping and the live region are exactly what this component exists to own",
+            "using it as a navigation menu — a palette is a keyboard accelerator for people who already know what they want. Ship <Navbar> for people who are browsing",
+            "listing hundreds of commands and raising maxResults to match — the fix for a long list is a better filter, not a longer scroll",
+            "relying on href for items that need to run code: give the item an onSelect, and note that a handler suppresses href navigation entirely"
+        ],
+        "patterns": [
+            "With the ⌘K binding: <CommandPalette open=\"isOpen\" onClose=\"close\" onRequestOpen=\"open\" items=\"commands\" />",
+            "Grouped commands: items sorted so every 'Navigate' entry precedes every 'Actions' entry",
+            "Client-side routing: <CommandPalette navigate=\"router.navigate\" ... />",
+            "Custom ranking: <CommandPalette filter=\"fuzzyRank\" ... />",
+            "Advertise the shortcut in the navbar with <SearchInput shortcutHint=\"'⌘K'\" /> or the .ui-navbar-search-hint trigger shell"
+        ]
+    },
+    "designGuidance": {
+        "surface": "The <Modal> surface, re-shaped: anchored --space-xl from the top of the viewport rather than centred (a palette grows downward as the reader types, and a centred one would drift under the cursor), widened to 40rem, and stripped of its padding so the search field can run edge to edge across the head of the panel. The field gives up its own border and background; the dialog edge is the only frame, and a hairline --color-divider rule is what separates the query from its results.",
+        "depth": "The Modal's own elevation over a dimmed backdrop, and nothing more. Inside the panel everything is flat — the active row is a tint, not a raised card.",
+        "borders": "Exactly one: the rule under the search field. Option rows have no borders at all; grouping is carried by headings and whitespace, which is what lets a long list stay quiet.",
+        "interactivity": "One highlight, driven entirely by aria-selected so the visual state and the ARIA state cannot drift apart. It follows both the arrow keys and the pointer, so moving the mouse across the list does not fight the keyboard. Disabled rows dim and take the not-allowed cursor.",
+        "motion": "Background and colour on the rows, inside prefers-reduced-motion: no-preference. The dialog's entrance comes from modal.scss. Nothing animates on filter — rows appearing and disappearing under a fast typist is motion the reader did not ask for.",
+        "darkMode": "Nothing to do — every value is a --color-* token or a design-system state opacity, so the muted/active relationship inverts with the theme. The forced-colours block is the separate case: there the active row is redrawn with Highlight/HighlightText because author colours are discarded outright.",
+        "bestPractices": "Keep the command list short and the labels imperative ('Toggle theme', not 'Theme'). Use groups once you pass about six commands, and order them by how often they are wanted, not alphabetically. Put keywords on anything whose label does not contain the word people will type. Advertise the shortcut somewhere visible — a palette nobody knows about is dead weight. Give items an icon only if every item in a group has one; a half-iconed list reads as broken alignment."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "⌘K palette",
+            "pithy": "<CommandPalette open=\"isOpen\" onClose=\"close\" onRequestOpen=\"open\" items=\"commands\" />",
+            "assertions": [
+                "renders role='dialog' aria-modal='true' with an accessible name",
+                "the field is role='combobox' with aria-controls pointing at the listbox",
+                "initial focus lands on the search field",
+                "Meta+K and Ctrl+K both call onRequestOpen"
+            ]
+        },
+        {
+            "id": "filtering",
+            "title": "Filtering",
+            "pithy": "<CommandPalette items=\"commands\" />",
+            "assertions": [
+                "matches label, description and keywords, case-insensitively",
+                "a role=\"group\" section disappears once its whole group is filtered away",
+                "the empty state renders and is announced when nothing matches",
+                "the active option resets to the first match on every query change"
+            ]
+        },
+        {
+            "id": "keyboard",
+            "title": "Keyboard model",
+            "pithy": "<CommandPalette items=\"commands\" />",
+            "assertions": [
+                "ArrowDown/ArrowUp rove and wrap, skipping disabled options",
+                "Home/End jump to the first/last enabled option",
+                "aria-activedescendant tracks the active option and is removed outright when there are none",
+                "Enter runs item.onSelect, then onSelect, then onClose"
+            ]
+        },
+        {
+            "id": "hotkey-guard",
+            "title": "Hotkey guard",
+            "pithy": "<CommandPalette onRequestOpen=\"open\" hotkey=\"'k'\" items=\"commands\" />",
+            "assertions": [
+                "nothing is bound unless onRequestOpen is supplied",
+                "the keystroke is ignored while focus is in an input, textarea, select or contenteditable",
+                "Shift and Alt are excluded, so Cmd/Ctrl+Shift+K does not open it",
+                "it still fires while the palette itself is open",
+                "destroy() removes the document listener"
+            ]
+        }
+    ]
+}