@estiva-app/ui 0.15.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,11 @@
     "test:watch": "vitest --project unit",
     "test:a11y": "vitest run --project storybook-signal --project storybook-ship",
     "typecheck": "tsc --noEmit",
+    "prelint": "node build.mjs",
     "lint": "eslint .",
+    "prelint:rules": "node build.mjs",
+    "lint:rules": "eslint --config eslint.gates.config.js .",
+    "postlint:rules": "node scripts/gates-count.mjs",
     "gates:status": "node scripts/gates-status.mjs",
     "prepublishOnly": "npm run build"
   },

package/src/Breadcrumb.tsx

@@ -1,5 +1,6 @@
 import { Fragment, useCallback, useLayoutEffect, useRef, useState, type MouseEventHandler, type ReactNode } from 'react'
 import { cn } from './cn'
+import { Link } from './Link'
 import { WithTooltip } from './Tooltip'
 
 /**
@@ -88,9 +89,12 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
           labelRefs.current[index] = el
         }
         const crumb = item.href ? (
-          <a ref={setLabelRef} href={item.href} onClick={item.onClick} className={cn(text, 'hover:text-text-primary')}>
+          // `plain` adds no look of its own: a crumb keeps the trail's size and
+          // tone, and brightens on hover. The package's own Link, so a trail
+          // follows whatever a link learns to do (UIG-5).
+          <Link ref={setLabelRef} variant="plain" href={item.href} onClick={item.onClick} className={cn(text, 'hover:text-text-primary')}>
             {item.label}
-          </a>
+          </Link>
         ) : (
           <span ref={setLabelRef} className={text} aria-current={last ? 'page' : undefined}>
             {item.label}

package/src/CommandPalette.mdx

@@ -0,0 +1,139 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as CommandPaletteStories from './CommandPalette.stories'
+
+<Meta of={CommandPaletteStories} />
+
+# CommandPalette
+
+A window that searches and runs things: a field, rows in groups, and a footer
+naming the keys that work right now. It shows one level at a time — rows, or a
+form — and the app keeps the levels.
+
+<Canvas of={CommandPaletteStories.FirstLevel} />
+
+## When
+
+- **One place to find something and act on it**, from anywhere in an app,
+  opened by a shortcut the app binds.
+- **`CommandPaletteSearch`** — a level of rows. Without a `chip` it is the
+  first level; with one, you are inside something, and the chip names it.
+- **`CommandPaletteForm`** — a level that is a form: what a row creates or
+  changes, without leaving the palette.
+- **`CommandPaletteWorking`, `CommandPaletteAnswer`, `CommandPaletteQuote`** —
+  above the rows, for a result that is written rather than listed: a line while
+  it is on its way, an answer with marks pointing at the rows it came from, and
+  text written to be used somewhere else.
+
+<Canvas of={CommandPaletteStories.Answer} />
+
+<Canvas of={CommandPaletteStories.Form} />
+
+## When not
+
+- A short list of verbs from a trigger → **Menu**.
+- One value for a field → **Select**; several → **ChipInput**.
+- A form with a title and buttons of its own, not reached from a palette →
+  **DialogShell**. The palette is not built on it: a palette has no title bar,
+  no close button and no button row, and on the shell it would be the shell with
+  every slot switched off.
+- Filtering a list that stays on the page → **SearchInput**.
+
+## How
+
+```tsx
+import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
+
+<CommandPalette open={open} onOpenChange={setOpen} label="Command palette" where="In Item one" modKey="Ctrl">
+  <CommandPaletteSearch
+    query={query}
+    onQueryChange={setQuery}
+    placeholder="Search, or choose a place"
+    groups={[
+      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: open, onForget: forget }] },
+      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon, onSelect: goIn, onGoIn: goIn }] },
+    ]}
+  />
+</CommandPalette>
+```
+
+- **The app opens it.** The palette listens to nothing outside its own window:
+  bind the shortcut in the app, pass `open`, and give `modKey` the platform's
+  spelling (`Cmd` on a Mac). The keys answer to Ctrl and Cmd either way.
+- **One level at a time, and the app keeps the stack.** Render a
+  `CommandPaletteSearch` or a `CommandPaletteForm` as the only child, and keep
+  each level's query yourself, so going back puts back the text that was there.
+  A level inside another passes `chip` — its label, and `onBack`.
+- **A row says what it can do, and the keys and the footer follow.** `onSelect`
+  is Enter and a click. `onGoIn` makes Tab, and → at the end of the text, go in,
+  and draws the chevron. `onForget` makes Ctrl+Backspace forget it — for rows
+  that are the person's own history. The footer names only what the lit row
+  answers to.
+- **`icon` sits on the row's 32px tile; `leading` takes the same 32px with no
+  tile**, for something with a look of its own — a face, a status mark.
+- **`id` is unique in the level.** The lit row is followed by it, so a caller
+  that builds its rows again on every render still runs the handler of the row
+  on screen.
+- **`pending` while rows are still on their way; `empty` only once none are.**
+  Pass `empty` while a search is running and the page says "nothing" before it
+  knows.
+- **`notes` are what a person should know about the rows and cannot act on** —
+  "2 more where you cannot open them", "the search was refused, so this list
+  is incomplete". Quiet lines under the rows, never rows: the arrows do not stop
+  on them.
+- **Rows that arrive late do not take the highlight you moved to.** Base UI keeps
+  the highlight's position rather than its row, so a group arriving above the
+  lit row would hand the highlight — and Enter — to something else. Once you have
+  moved the highlight on a level, the palette walks it back to the row you had.
+  Until you have, the first row is lit, whichever row that becomes. Typing starts
+  again from the first row.
+- **Home and End move the text cursor, and nothing else.** Base UI would also
+  send the highlight to the first or last row; the palette stops that.
+- **The field is named by its placeholder**, so say what it asks for.
+- **A form's fields go in `Field`s.** Mark the missing ones with `error` inside
+  `onSubmit`, and the first of them takes focus. `working` locks the fields,
+  puts its words on the button and beside it, and holds focus on the form so
+  Esc still closes it; when it clears, focus goes to the first field that needs
+  something, or back where it was. `error` is what went wrong, beside the
+  button. `submitWaits` says why there is nothing to submit yet, on the button,
+  and Ctrl+Enter does nothing until it clears.
+- **Focus never falls out of a level.** When the element that had it goes — a
+  row picked, a level swapped — focus goes to the level's first control.
+
+## Keys
+
+| Where | Input | What happens |
+|---|---|---|
+| a level of rows | ↑ / ↓ | move between rows, and stop at the ends |
+| | Enter, or a click | what the lit row does |
+| | Tab | goes in, on a row that leads somewhere; anywhere else nothing, and focus stays in the field |
+| | → at the end of the text | goes in, on a row that leads somewhere; anywhere else it moves the cursor |
+| | Ctrl+Backspace | forgets the lit row, if it can be forgotten; otherwise deletes a word |
+| | Home / End | move the text cursor; the lit row stays |
+| inside a level | Backspace at the start of the field, or the chip's ✕ | back, with focus in the field |
+| a form | Tab / Shift+Tab | between the fields, never out of the window |
+| | Ctrl+Enter | submits; if a field needs something, focus goes to the first |
+| | Backspace in an empty text field | back. In a form that is one list, Backspace anywhere; in a list inside a form with text fields, nothing |
+| | while working | nothing but Esc |
+| | Esc in an open list | closes the list first |
+| anywhere | Esc, or a click outside | closes; focus returns to whatever opened it |
+
+## Props
+
+<Controls of={CommandPaletteStories.FirstLevel} />
+
+**`CommandPaletteSearch`** — `query` and `onQueryChange` (the field, controlled),
+`placeholder` (also the field's name), `groups` (`{ label, rows }`, a group
+with no rows is not drawn), `chip?` (`{ label, leading?, onBack }`), `pending?`, `notes?`,
+`empty?`, and `children` for what sits above the rows.
+
+**A row** — `id`, `label`, `description?`, `icon?` or `leading?`, `onSelect`,
+`onGoIn?`, `onForget?`.
+
+**`CommandPaletteForm`** — `chip`, `icon?`, `submitLabel`, `onSubmit`,
+`submitWaits?`, `working?` (`{ button, line }`), `error?`, and the fields as
+`children`.
+
+**`CommandPaletteWorking`** — the words as `children`, `bars?` (0–3, default 2).
+**`CommandPaletteAnswer`** — the text as `children` (a blank line starts a
+paragraph; `[1]` is a mark), `note?`. **`CommandPaletteQuote`** — the text as
+`children`, line breaks kept.

package/src/CommandPalette.stories.tsx

@@ -0,0 +1,418 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useEffect, useMemo, useState } from 'react'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { Button } from './Button'
+import {
+  CommandPalette,
+  CommandPaletteAnswer,
+  CommandPaletteForm,
+  CommandPaletteQuote,
+  CommandPaletteSearch,
+  CommandPaletteWorking,
+  type CommandPaletteGroup,
+  type CommandPaletteRow,
+} from './CommandPalette'
+import { Field } from './Field'
+import { Select } from './Select'
+import { TextInput } from './TextInput'
+import { Textarea } from './Textarea'
+
+/**
+ * A window that searches and runs things. It shows one level at a time — a
+ * level of rows, or a form — and the caller keeps the levels. Every story
+ * below is the same small caller, started at a different place, so every key
+ * works in all of them.
+ *
+ * Nothing here is fetched: what "arrives later" is a timer.
+ */
+const meta = {
+  title: 'Overlays/CommandPalette',
+  component: CommandPalette,
+  parameters: {
+    layout: 'fullscreen',
+    // Portals a fixed overlay to document.body — an iframe on the Docs page,
+    // so it does not escape over the docs content.
+    docs: { story: { inline: false, height: '640px' } },
+    // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the
+    // footer and the "Searching…" and empty lines are muted text, 3.49:1 on
+    // --bg-elevated in signal (AA 4.5:1), measured by CI on PR #43; ship passes.
+    a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } },
+  },
+  args: { open: true, onOpenChange: () => {}, label: 'Command palette', where: 'In Item one', modKey: 'Ctrl', children: null },
+  argTypes: { children: { control: false }, onOpenChange: { control: false }, open: { control: false } },
+} satisfies Meta<typeof CommandPalette>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const icon = <IconSquareRounded size={16} stroke={1.5} />
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+type Level =
+  | { kind: 'first' }
+  | { kind: 'place'; name: string }
+  | { kind: 'ask' }
+  | { kind: 'draft' }
+  | { kind: 'form' }
+  | { kind: 'one-list' }
+
+interface Frame {
+  level: Level
+  query: string
+}
+
+type Start = 'first' | 'arriving' | 'nothing' | 'place' | 'working' | 'answer' | 'draft' | 'form' | 'refused' | 'one-list'
+
+const PLACES = ['Place one', 'Place two']
+const ACTIONS = [
+  { id: 'action-one', label: 'Action one', description: 'Opens a form' },
+  { id: 'action-two', label: 'Action two', description: 'Opens a form' },
+]
+const LATER = ['Item one, as it was on Monday', 'Item three, where item one is named']
+const KINDS = [
+  { value: 'one', label: 'Kind one' },
+  { value: 'two', label: 'Kind two' },
+  { value: 'three', label: 'Kind three' },
+]
+const GROUPS = [
+  { value: 'first', label: 'Group one' },
+  { value: 'second', label: 'Group two' },
+]
+const ANSWER = 'Item one moved on Monday [1], and item two is waiting on a reply [2].\n\nNothing else changed this week.'
+const DRAFT = 'Thanks, both. I will look at item one today\nand reply on item two tomorrow.'
+
+function startStack(start: Start): Frame[] {
+  const first: Frame = { level: { kind: 'first' }, query: '' }
+  switch (start) {
+    case 'arriving':
+      return [{ ...first, query: 'item' }]
+    case 'nothing':
+      return [{ ...first, query: 'nothing matches this' }]
+    case 'place':
+      return [first, { level: { kind: 'place', name: 'Place one' }, query: '' }]
+    case 'working':
+    case 'answer':
+      return [first, { level: { kind: 'ask' }, query: 'What changed this week?' }]
+    case 'draft':
+      return [first, { level: { kind: 'draft' }, query: 'Say I will look today' }]
+    case 'form':
+    case 'refused':
+      return [first, { level: { kind: 'place', name: 'Place one' }, query: '' }, { level: { kind: 'form' }, query: '' }]
+    case 'one-list':
+      return [first, { level: { kind: 'one-list' }, query: '' }]
+    default:
+      return [first]
+  }
+}
+
+/** The caller every story uses: the levels, the rows, and what each one does. */
+function Demo({ start, where, modKey, label }: { start: Start; where?: string; modKey?: string; label: string }) {
+  const [open, setOpen] = useState(true)
+  const [stack, setStack] = useState<Frame[]>(() => startStack(start))
+  const [last, setLast] = useState<string>('Nothing chosen yet.')
+  const frame = stack[stack.length - 1]
+  const level = frame.level
+
+  const setQuery = (query: string) => setStack((s) => [...s.slice(0, -1), { ...s[s.length - 1], query }])
+  const push = (next: Level, query = '') => setStack((s) => [...s, { level: next, query }])
+  const back = () => setStack((s) => (s.length > 1 ? s.slice(0, -1) : s))
+  const close = (what: string) => {
+    setLast(what)
+    setOpen(false)
+  }
+  const reopen = () => {
+    setStack([{ level: { kind: 'first' }, query: '' }])
+    setOpen(true)
+  }
+
+  // ── A late group: arrives 600ms after the typing stops (slower in "arriving").
+  const term = level.kind === 'first' ? frame.query.trim().toLowerCase() : ''
+  const [searched, setSearched] = useState('')
+  useEffect(() => {
+    if (!term) return
+    const timer = setTimeout(() => setSearched(term), start === 'arriving' ? 2500 : 600)
+    return () => clearTimeout(timer)
+  }, [term, start])
+  const searching = !!term && searched !== term
+
+  // ── An answer that takes a while ("working" never finishes).
+  const [asked, setAsked] = useState<{ question: string; done: boolean } | null>(null)
+  const ask = async (question: string) => {
+    setAsked({ question, done: false })
+    if (start === 'working') return
+    await wait(1200)
+    setAsked((a) => (a?.question === question ? { question, done: true } : a))
+  }
+  useEffect(() => {
+    if (level.kind === 'ask' || level.kind === 'draft') void ask(frame.query)
+    // Once per level: the question it was opened with.
+    // (The stack's length changes exactly when a level opens.)
+  }, [stack.length])
+
+  // ── Recent rows are the person's own, and can be forgotten.
+  const [recent, setRecent] = useState(['Item one', 'Item two', 'Person one'])
+
+  // ── The form keeps what was typed while the palette is open.
+  const [draft, setDraft] = useState({ title: '', notes: '', kind: 'one', group: '' })
+  const [missing, setMissing] = useState<{ title?: string; group?: string }>({})
+  const [working, setWorking] = useState(false)
+  const [refused, setRefused] = useState(false)
+  const [kind, setKind] = useState('one')
+
+  const groups = useMemo<CommandPaletteGroup[]>(() => {
+    const q = frame.query.trim().toLowerCase()
+    if (level.kind === 'place') {
+      return [
+        {
+          label: `${level.name} actions`,
+          rows: ACTIONS.filter((a) => a.label.toLowerCase().includes(q)).map((a) => ({
+            id: a.id,
+            label: a.label,
+            description: a.description,
+            icon,
+            onSelect: () => push({ kind: 'form' }),
+          })),
+        },
+      ]
+    }
+    if (level.kind === 'ask' || level.kind === 'draft') {
+      if (!asked?.done) return []
+      const changed = frame.query.trim() !== asked.question.trim()
+      const again: CommandPaletteRow = { id: 'again', label: `Again: “${frame.query.trim()}”`, icon, onSelect: () => void ask(frame.query) }
+      if (level.kind === 'ask') {
+        return [
+          { label: 'Ask again', rows: changed ? [again] : [] },
+          {
+            label: 'Sources',
+            rows: ['Note one', 'Note two'].map((note, i) => ({
+              id: note,
+              label: note,
+              description: `[${i + 1}] Person ${i === 0 ? 'one' : 'two'} · Monday`,
+              leading: <Avatar name={`Person ${i === 0 ? 'one' : 'two'}`} size={20} />,
+              onSelect: () => close(note),
+            })),
+          },
+          { label: 'Next', rows: [{ id: 'use-answer', label: 'Use the answer', icon, onSelect: () => close('Use the answer') }] },
+        ]
+      }
+      return [
+        { label: 'Write again', rows: changed ? [again] : [] },
+        {
+          label: 'Next',
+          rows: [
+            { id: 'use-draft', label: 'Use it', description: 'Nothing is sent. Edit it first.', icon, onSelect: () => close('Use it') },
+            { id: 'draft-again', label: 'Write it again', icon, onSelect: () => void ask(asked.question) },
+          ],
+        },
+      ]
+    }
+
+    const place = (name: string): CommandPaletteRow => ({
+      id: `place-${name}`,
+      label: name,
+      description: 'Has actions',
+      icon,
+      onSelect: () => push({ kind: 'place', name }),
+      onGoIn: () => push({ kind: 'place', name }),
+    })
+    const recentRow = (name: string): CommandPaletteRow => ({
+      id: `recent-${name}`,
+      label: name,
+      description: name.startsWith('Person') ? 'Role' : 'Opened today',
+      ...(name.startsWith('Person') ? { leading: <Avatar name={name} size={24} /> } : { icon }),
+      onSelect: () => close(name),
+      onForget: () => setRecent((r) => r.filter((x) => x !== name)),
+    })
+
+    if (!q) {
+      return [
+        {
+          label: 'This page',
+          rows: [
+            { id: 'ask', label: 'Ask about this page', icon, onSelect: () => push({ kind: 'ask' }) },
+            { id: 'draft', label: 'Write a draft', icon, onSelect: () => push({ kind: 'draft' }) },
+            { id: 'one-list', label: 'Change kind', description: 'Item one', icon, onSelect: () => push({ kind: 'one-list' }) },
+          ],
+        },
+        {
+          label: 'Recent',
+          rows: recent.length ? [...recent.map(recentRow), { id: 'clear', label: 'Clear recent', icon, onSelect: () => setRecent([]) }] : [],
+        },
+        { label: 'Places', rows: PLACES.map(place) },
+      ]
+    }
+    const matches = (s: string) => s.toLowerCase().includes(q)
+    return [
+      { label: 'Places', rows: PLACES.filter(matches).map(place) },
+      { label: 'Recent', rows: recent.filter(matches).map(recentRow) },
+      {
+        label: 'Actions',
+        rows: ACTIONS.filter((a) => matches(a.label)).map((a) => ({
+          id: a.id,
+          label: a.label,
+          description: 'Place one',
+          icon,
+          onSelect: () => setStack((s) => [...s, { level: { kind: 'place', name: 'Place one' }, query: '' }, { level: { kind: 'form' }, query: '' }]),
+        })),
+      },
+      {
+        label: 'Later',
+        rows: searching ? [] : LATER.filter(matches).map((text) => ({ id: text, label: text, description: 'Person two · Monday', icon, onSelect: () => close(text) })),
+      },
+    ]
+  }, [frame, level, asked, recent, searching])
+
+  const submitForm = async () => {
+    const need = { title: draft.title.trim() ? undefined : 'Give it a title.', group: draft.group ? undefined : 'Choose a group.' }
+    setMissing(need)
+    setRefused(false)
+    if (need.title || need.group) return
+    setWorking(true)
+    await wait(1200)
+    setWorking(false)
+    if (start === 'refused') {
+      setRefused(true)
+      return
+    }
+    close(`Created “${draft.title.trim()}”`)
+  }
+
+  const submitKind = async () => {
+    setWorking(true)
+    await wait(900)
+    setWorking(false)
+    close(`Kind set to ${KINDS.find((k) => k.value === kind)?.label}`)
+  }
+
+  const body = (() => {
+    if (level.kind !== 'ask' && level.kind !== 'draft') return undefined
+    if (!asked || !asked.done) return <CommandPaletteWorking>Reading 12 notes…</CommandPaletteWorking>
+    const changed = frame.query.trim() !== asked.question.trim()
+    return level.kind === 'ask' ? (
+      <CommandPaletteAnswer note={changed ? 'You changed the question. Press Enter to ask again.' : undefined}>{ANSWER}</CommandPaletteAnswer>
+    ) : (
+      <CommandPaletteQuote>{DRAFT}</CommandPaletteQuote>
+    )
+  })()
+
+  const q = frame.query.trim()
+
+  return (
+    <div className="flex h-screen flex-col items-start gap-3 bg-bg-base p-6">
+      <Button variant="outlined" onClick={reopen}>
+        Open the palette
+      </Button>
+      <p className="text-body-2 text-text-secondary">{last}</p>
+
+      <CommandPalette open={open} onOpenChange={setOpen} label={label} where={where} modKey={modKey}>
+        {level.kind === 'form' ? (
+          <CommandPaletteForm
+            chip={{ label: 'Place one · Action one', onBack: back }}
+            icon={icon}
+            submitLabel="Create item"
+            onSubmit={() => void submitForm()}
+            working={working ? { button: 'Creating…', line: 'Creating the item…' } : undefined}
+            error={refused ? 'Group two is archived. Choose another one.' : undefined}
+          >
+            <Field label="Title" required error={missing.title}>
+              <TextInput value={draft.title} placeholder="A few words" onChange={(e) => setDraft({ ...draft, title: e.target.value })} />
+            </Field>
+            <Field label="Notes">
+              <Textarea rows={3} value={draft.notes} placeholder="Anything else" onChange={(e) => setDraft({ ...draft, notes: e.target.value })} />
+            </Field>
+            <Field label="Kind">
+              <Select value={draft.kind} onChange={(value) => setDraft({ ...draft, kind: value })} options={KINDS} />
+            </Field>
+            <Field label="Group" required error={missing.group}>
+              <Select value={draft.group} onChange={(value) => setDraft({ ...draft, group: value })} options={GROUPS} placeholder="Choose a group…" />
+            </Field>
+          </CommandPaletteForm>
+        ) : level.kind === 'one-list' ? (
+          <CommandPaletteForm
+            chip={{ label: 'Item one · Change kind', onBack: back }}
+            icon={icon}
+            submitLabel="Change kind"
+            onSubmit={() => void submitKind()}
+            submitWaits={kind === 'one' ? 'Choose a different kind first' : undefined}
+            working={working ? { button: 'Saving…', line: 'Saving the kind…' } : undefined}
+          >
+            <Field label="Kind">
+              <Select value={kind} onChange={setKind} options={KINDS} />
+            </Field>
+          </CommandPaletteForm>
+        ) : (
+          <CommandPaletteSearch
+            query={frame.query}
+            onQueryChange={setQuery}
+            placeholder={
+              level.kind === 'place'
+                ? `Search ${level.name}'s actions`
+                : level.kind === 'ask'
+                  ? 'Ask anything about this page'
+                  : level.kind === 'draft'
+                    ? 'What should it say?'
+                    : 'Search, or choose a place'
+            }
+            groups={groups}
+            chip={
+              level.kind === 'place'
+                ? { label: level.name, leading: icon, onBack: back }
+                : level.kind === 'ask'
+                  ? { label: 'Ask', onBack: back }
+                  : level.kind === 'draft'
+                    ? { label: 'Draft', onBack: back }
+                    : undefined
+            }
+            pending={level.kind === 'first' && searching ? 'Searching…' : undefined}
+            // What the later group left out: a line to read, not a row to pick.
+            notes={level.kind === 'first' && q && !searching && LATER.some((l) => l.toLowerCase().includes(q)) ? ['1 more in a place you cannot open.'] : undefined}
+            empty={
+              level.kind === 'first' && q && !searching
+                ? `Nothing is called “${q}”.`
+                : level.kind === 'place'
+                  ? `${level.name} has no action called “${q}”.`
+                  : undefined
+            }
+          >
+            {body}
+          </CommandPaletteSearch>
+        )}
+      </CommandPalette>
+    </div>
+  )
+}
+
+const story = (start: Start): Story => ({
+  render: (args) => <Demo start={start} label={args.label} where={args.where} modKey={args.modKey} />,
+})
+
+/** The first level: rows in groups, the first one lit. ↑ ↓ stop at the ends, Tab goes into a place, Ctrl+Backspace forgets a recent row. */
+export const FirstLevel: Story = story('first')
+
+/** Typing: the rows that match now, a line while a later group is on its way, that group arriving without moving the lit row, and a note about what it left out. */
+export const WhileRowsArrive: Story = story('arriving')
+
+/** Nothing matches: the empty line, where the first row would be. */
+export const NothingFound: Story = story('nothing')
+
+/** Inside a level: the chip names it. Backspace at the start of the field, or the chip's ✕, goes back with the text you had. */
+export const InsideALevel: Story = story('place')
+
+/** Something is being worked on: the line says what, the grey bars hold the place. */
+export const Working: Story = story('working')
+
+/** An answer, its marks, and the rows they point at. Change the question and an "Again" row comes first. */
+export const Answer: Story = story('answer')
+
+/** Text written to be used somewhere else, above what you can do with it. */
+export const Quote: Story = story('draft')
+
+/** A form. Ctrl+Enter creates; a missing field says so and takes focus; Backspace in an empty field goes back and keeps what was typed. */
+export const Form: Story = story('form')
+
+/** Creating is refused: the fields unlock, the reason sits beside the button, and focus is back where it was. */
+export const FormRefused: Story = story('refused')
+
+/** A form that is one list. It waits, and says why, until the value changes; Backspace goes back from the list. */
+export const FormThatWaits: Story = story('one-list')