@estiva-app/ui 0.14.0 → 0.16.0

package/src/eslint/no-hand-rolled-behaviour.test.ts

@@ -0,0 +1,70 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+tester.run('no-hand-rolled-behaviour', noHandRolledBehaviour, {
+  valid: [
+    { name: 'a Base UI part doing its own portalling', code: "import { Popover } from '@base-ui/react/popover'\nexport const Probe = () => <Popover.Portal />\n" },
+    {
+      name: "a virtual anchor handed to Base UI, as Popover's",
+      code: 'export function probe(rect: DOMRect) {\n  return { getBoundingClientRect: () => rect }\n}\n',
+    },
+    {
+      name: "an element's own handler, which is not a global listener",
+      code: 'export function probe(el: HTMLElement) {\n  el.addEventListener("keydown", () => {})\n}\n',
+    },
+    {
+      name: 'a listener for something no floating part owns',
+      code: 'export function probe() {\n  window.addEventListener("online", () => {})\n}\n',
+    },
+    {
+      name: 'the import of a portal, kept with its reason',
+      code: "// @estiva-escape: the toast keeps its own portal until migration stage 6\nimport { createPortal } from 'react-dom'\nexport const Probe = () => null\n",
+    },
+    {
+      name: 'the call, kept with its reason',
+      code: 'export function probe(to: HTMLElement) {\n  // @estiva-escape: the toast keeps its own portal until migration stage 6\n  return createPortal(null, to)\n}\n',
+    },
+    {
+      name: 'a global listener kept with its reason',
+      code: 'export function probe() {\n  // @estiva-escape: the frame measures the window, which no floating part owns\n  window.addEventListener("resize", () => {})\n}\n',
+    },
+  ],
+  invalid: [
+    {
+      name: 'importing createPortal',
+      code: "import { createPortal } from 'react-dom'\nexport const Probe = () => null\n",
+      errors: [{ messageId: 'portal' }],
+    },
+    {
+      name: 'calling createPortal',
+      code: 'export function probe(to: HTMLElement) {\n  return createPortal(null, to)\n}\n',
+      errors: [{ messageId: 'portal' }],
+    },
+    {
+      name: 'following the anchor by hand',
+      code: 'export function probe() {\n  window.addEventListener("scroll", () => {})\n}\n',
+      errors: [{ messageId: 'listener', data: { event: 'scroll', target: 'window' } }],
+    },
+    {
+      name: 'closing on an outside press by hand',
+      code: 'export function probe() {\n  document.addEventListener("mousedown", () => {})\n}\n',
+      errors: [{ messageId: 'listener', data: { event: 'mousedown', target: 'document' } }],
+    },
+    {
+      name: 'closing on Escape by hand',
+      code: 'export function probe() {\n  document.addEventListener("keydown", () => {})\n}\n',
+      errors: [{ messageId: 'listener', data: { event: 'keydown', target: 'document' } }],
+    },
+  ],
+})

package/src/eslint/no-hand-rolled-behaviour.ts

@@ -0,0 +1,116 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+/**
+ * Behaviour Base UI already owns, written by hand inside the package (UIG-5,
+ * P1 — the migration's standing rule D6 as a machine).
+ *
+ * This is the rule with the most to lose. A hand-made portal or a global
+ * listener inside `DialogShell` is inherited by every caller in every app, and
+ * nobody sees it from there.
+ *
+ * Two facts, both mechanical, both the signature of a floating part rebuilt by
+ * hand:
+ *
+ * - **`createPortal`**, or importing it from `react-dom`. Base UI's parts carry
+ *   their own portal.
+ * - **a listener on `window` or `document`** for the events a floating part
+ *   lives on — resize, scroll, an outside press, a key. Base UI's Positioner
+ *   follows the anchor and its Root closes on an outside press and on Escape.
+ *
+ * What it deliberately does not try to read: measuring arithmetic. `Popover`
+ * hands Base UI a virtual anchor with a `getBoundingClientRect`, which is the
+ * documented way to anchor to a rectangle rather than an element, and a rule
+ * that guessed at arithmetic would report it. Anything that shape is caught by
+ * a reader, not by this.
+ *
+ * A place that keeps one says why on the line above: `// @estiva-escape: <why>`.
+ */
+const FLOATING_EVENTS = new Set(['resize', 'scroll', 'mousedown', 'pointerdown', 'keydown', 'keyup', 'focusin', 'focusout', 'click'])
+
+interface Node {
+  type: string
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+}
+
+interface Identifier extends Node {
+  name: string
+}
+
+interface ImportDeclaration extends Node {
+  source: { value: unknown }
+  specifiers: { type: string; imported?: { name?: string }; local?: { name?: string }; loc?: Rule.Node['loc']; range?: [number, number] }[]
+}
+
+interface CallExpression extends Node {
+  callee: { type: string; name?: string; object?: { type: string; name?: string }; property?: { type: string; name?: string } }
+  arguments: { type: string; value?: unknown }[]
+  parent?: { type: string; loc?: Rule.Node['loc']; range?: [number, number]; parent?: CallExpression['parent'] }
+}
+
+/**
+ * The statement a call sits in, which is what an escape is written above:
+ * `return createPortal(…)` puts the call in the middle of its line, and a
+ * comment above the line is above the statement.
+ */
+function statement(node: { loc: NonNullable<Rule.Node['loc']>; range: [number, number]; parent?: CallExpression['parent'] }): {
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+} {
+  for (let p = node.parent; p; p = p.parent) {
+    if (!/(Statement|Declaration)$/.test(p.type)) continue
+    if (p.loc && p.range) return { loc: p.loc, range: p.range }
+    break
+  }
+  return { loc: node.loc, range: node.range }
+}
+
+export const noHandRolledBehaviour: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Overlay behaviour written by hand where Base UI has a part (D6)' },
+    schema: [],
+    messages: {
+      portal:
+        'A portal written by hand. Base UI\'s parts carry their own (Popover, Menu, Select, Tooltip, Dialog, Toast): use the part, or say why this one stays.',
+      listener:
+        'A `{{event}}` listener on `{{target}}`. A floating part follows its anchor and closes on an outside press and on Escape by itself (Base UI Positioner and Root): use the part, or say why this one stays.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node: Rule.Node) {
+        const declaration = node as unknown as ImportDeclaration
+        if (declaration.source.value !== 'react-dom') return
+        for (const specifier of declaration.specifiers) {
+          if (specifier.type !== 'ImportSpecifier' || specifier.imported?.name !== 'createPortal') continue
+          // The escape goes above the import line, not above the name inside it.
+          if (isEscaped(context, declaration)) return
+          context.report({ loc: declaration.loc, messageId: 'portal' })
+          return
+        }
+      },
+      CallExpression(node: Rule.Node) {
+        const call = node as unknown as CallExpression
+        const { callee } = call
+
+        if (callee.type === 'Identifier' && callee.name === 'createPortal') {
+          if (isEscaped(context, statement(call))) return
+          context.report({ loc: call.loc, messageId: 'portal' })
+          return
+        }
+
+        if (callee.type !== 'MemberExpression' || callee.property?.name !== 'addEventListener') return
+        const target = callee.object?.type === 'Identifier' ? callee.object.name : undefined
+        if (target !== 'window' && target !== 'document') return
+        const [first] = call.arguments
+        const event = first?.type === 'Literal' && typeof first.value === 'string' ? first.value : undefined
+        if (!event || !FLOATING_EVENTS.has(event)) return
+        if (isEscaped(context, statement(call))) return
+        context.report({ loc: call.loc, messageId: 'listener', data: { event, target } })
+      },
+    }
+  },
+}

package/src/eslint/no-raw-button.test.ts

@@ -0,0 +1,118 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { noRawButton } from './no-raw-button'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  // A directive for a rule these cases do not load is not what they test.
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
+
+tester.run('no-raw-button', noRawButton, {
+  valid: [
+    { name: "the package's Button", code: component('<Button>Save</Button>') },
+    { name: 'a member expression named button', code: component('<Foo.button>Save</Foo.button>') },
+    { name: 'a name that starts with button', code: component('<buttonish />') },
+    {
+      name: 'a line comment escape directly above',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'),
+    },
+    {
+      name: 'a JSX comment escape on the line above a child',
+      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button type="button">x</button>\n    </div>'),
+    },
+    {
+      name: 'a JSX comment escape over several lines',
+      code: component('    <div>\n      {/*\n        @estiva-escape: a preview drawn from its own palette\n      */}\n      <button type="button">x</button>\n    </div>'),
+    },
+    {
+      name: 'an escape above an opening tag that spans lines',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button\n      type="button"\n      onClick={() => {}}\n    >\n      x\n    </button>'),
+    },
+    {
+      name: 'exactly ten characters of reason, spaces not counted',
+      code: component('    // @estiva-escape: ab cd ef gh ij\n    <button>x</button>'),
+    },
+  ],
+  invalid: [
+    { name: 'a raw button', code: component('    <button type="button">x</button>'), errors: [{ messageId: 'raw', line: 3 }] },
+    { name: 'a self-closing raw button', code: component('    <button />'), errors: [{ messageId: 'raw' }] },
+    {
+      name: 'an opening tag that spans lines (what grep misses)',
+      code: component('    <button\n      type="button"\n    >\n      x\n    </button>'),
+      errors: [{ messageId: 'raw', line: 3 }],
+    },
+    {
+      name: 'a raw button nested in other elements',
+      code: component('    <div>\n      <span>\n        <button>x</button>\n      </span>\n    </div>'),
+      errors: [{ messageId: 'raw', line: 5 }],
+    },
+    {
+      name: 'the message names the component',
+      code: component('    <button>x</button>'),
+      errors: [{ message: 'Use `Button` from @estiva-app/ui instead of a raw <button>.' }],
+    },
+    {
+      name: 'an escape with no reason is an error, and hides nothing',
+      code: component('    // @estiva-escape:\n    <button>x</button>'),
+      errors: [
+        { messageId: 'escapeWithoutReason', line: 3 },
+        { messageId: 'raw', line: 4 },
+      ],
+    },
+    {
+      name: 'nine characters of reason is too short',
+      code: component('    <div>\n      {/* @estiva-escape: ab cd ef gh i */}\n      <button>x</button>\n    </div>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
+    },
+    {
+      name: 'a marker with no colon and no reason',
+      code: component('    // @estiva-escape\n    <button>x</button>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
+    },
+    {
+      name: 'an escape two lines above does not reach the element',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 5 }],
+    },
+    {
+      name: 'an escape above a sibling does not reach the next element',
+      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <span />\n      <button>x</button>\n    </div>'),
+      errors: [{ messageId: 'raw', line: 6 }],
+    },
+    {
+      name: 'a free comment is not an escape',
+      code: component('    // a raw button, on purpose\n    <button>x</button>'),
+      errors: [{ messageId: 'raw' }],
+    },
+    {
+      name: 'a marker inside a directive that switches every rule off is refused',
+      code: component('    // eslint-disable-next-line -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      // The directive silences the element's own report; the refusal sits on the directive's line.
+      errors: [{ messageId: 'escapeInDirective', line: 3 }],
+    },
+    {
+      name: 'a marker inside a directive that names this rule is refused',
+      code: component('    // eslint-disable-next-line rule-to-test/no-raw-button -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [{ messageId: 'escapeInDirective', line: 3 }],
+    },
+    {
+      name: "the token lint's note for another rule is not an escape of this one",
+      code: component('    // eslint-disable-next-line no-console -- @estiva-escape: its hand-written type waits for that\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 4 }],
+    },
+    {
+      name: 'with reportEscapes on, a sanctioned escape is reported for the count',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      settings: { estiva: { reportEscapes: true } },
+      errors: [{ messageId: 'escaped', data: { reason: 'a preview drawn from its own palette' }, line: 3 }],
+    },
+  ],
+})

package/src/eslint/no-raw-button.ts

@@ -0,0 +1,39 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+interface JSXOpeningElement {
+  name: { type: string; name?: string }
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+}
+
+/**
+ * A raw `<button>` in an app (UIG-3, the tracer). The package's `Button`,
+ * `IconButton`, `MenuItem` and chips are buttons already; an app that writes
+ * its own has a look and a behaviour nobody else keeps in step with.
+ *
+ * Only the JSX element named `button`. `<Button>`, `<Foo.button>` and
+ * `createElement('button')` are not this rule's business.
+ */
+export const noRawButton: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A raw <button> where @estiva-app/ui has one' },
+    schema: [],
+    messages: {
+      raw: 'Use `Button` from @estiva-app/ui instead of a raw <button>.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      // ESLint's types know ESTree's nodes, not JSX's; the parser hands this one over.
+      JSXOpeningElement(node: Rule.Node) {
+        const element = node as unknown as JSXOpeningElement
+        if (element.name.type !== 'JSXIdentifier' || element.name.name !== 'button') return
+        if (isEscaped(context, element)) return
+        context.report({ loc: element.loc, messageId: 'raw' })
+      },
+    }
+  },
+}

package/src/eslint/raw-element-outside-a-wrapper.test.ts

@@ -0,0 +1,82 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { rawElementOutsideAWrapper } from './raw-element-outside-a-wrapper'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
+
+tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
+  valid: [
+    // The two shapes the package is built out of.
+    { name: "the component's own outermost element, as NavItem is an <a>", code: component('    <a href="/x">Issues</a>') },
+    { name: "the component's own element with children inside it", code: component('    <a href="/x">\n      <span>Issues</span>\n    </a>') },
+    {
+      name: 'either branch of a component that returns one element or another, as EditableText does',
+      code: 'export function Probe({ editing }: { editing: boolean }) {\n  if (editing) return <input aria-label="x" />\n  return <button type="button">x</button>\n}\n',
+    },
+    {
+      name: 'handed to a Base UI render prop, as Menu.Item does',
+      code: component('    <BaseMenu.Item render={<button type="button" />} className="row" />'),
+    },
+    {
+      name: 'handed to a render prop while nested, as a part inside a part',
+      code: component('    <BaseMenu.Positioner>\n      <BaseMenu.Item render={<button type="button" />} />\n    </BaseMenu.Positioner>'),
+    },
+    { name: 'a component, not an element', code: component('    <div>\n      <Button>Save</Button>\n    </div>') },
+    { name: 'layout inside a component', code: component('    <div>\n      <span>Issues</span>\n    </div>') },
+    {
+      name: 'a nested element with its reason on the line above',
+      code: component('    <div>\n      {/* @estiva-escape: the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
+    },
+  ],
+  invalid: [
+    {
+      name: 'an anchor buried in a component, as the breadcrumb trail had',
+      code: component('    <div>\n      <a href="/x">Issues</a>\n    </div>'),
+      errors: [{ messageId: 'nested', data: { name: 'a' } }],
+    },
+    {
+      name: 'a button buried in a component, as the toast had',
+      code: component('    <div>\n      <p>Saved</p>\n      <button type="button">Undo</button>\n    </div>'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'inside a fragment, which is several children rather than one element',
+      code: component('    <>\n      <span>x</span>\n      <input aria-label="x" />\n    </>'),
+      errors: [{ messageId: 'nested', data: { name: 'input' } }],
+    },
+    {
+      name: 'inside a component of the package, which is not a render prop',
+      code: component('    <Card>\n      <button type="button">x</button>\n    </Card>'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'nested inside an element that was itself handed to a render prop',
+      code: component('    <BaseMenu.Item render={<div><button type="button" /></div>} />'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'a reason too short to be a reason',
+      code: component('    <div>\n      {/* @estiva-escape: short */}\n      <a href="/x">Issues</a>\n    </div>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'nested', data: { name: 'a' } }],
+    },
+    {
+      name: 'an eslint-disable instead of a reason',
+      // The tester runs the rule under its bare name; in a real lint the plugin
+      // prefixes it, and `isEscaped` compares against whichever the rule has.
+      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape: the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
+      // The directive silences the rule's own report, which is exactly why it is
+      // refused: `countGates` sees the silenced report and the gate fails on it.
+      errors: [{ messageId: 'escapeInDirective' }],
+    },
+  ],
+})

package/src/eslint/raw-element-outside-a-wrapper.ts

@@ -0,0 +1,85 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+interface JSXOpeningElement {
+  type: string
+  name: { type: string; name?: string }
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+  parent?: Parent
+}
+
+interface Parent {
+  type: string
+  name?: { name?: string }
+  openingElement?: unknown
+  parent?: Parent
+}
+
+/**
+ * The elements this package writes by hand. The set the count used (UIG-1,
+ * docs/GATES.md §5 and §7): every element that carries behaviour or a role of
+ * its own. A `div` or a `span` is layout and is nobody's business here.
+ */
+export const RAW_ELEMENTS = new Set(['a', 'button', 'input', 'textarea', 'select', 'dialog', 'form', 'label'])
+
+/**
+ * A raw element nested inside another element, in the package itself (UIG-5,
+ * the inward tracer).
+ *
+ * The package is allowed to write raw elements — that is what a primitive is.
+ * Two shapes are right, and both are facts about the code rather than a
+ * judgement:
+ *
+ * - **the component's own outermost element.** `NavItem` is an `<a>`, `Link` is
+ *   an `<a>`, a `MenuItem` outside a `Menu` is a `<button>`. A primitive owning
+ *   its element is the whole point of it.
+ * - **handed to a Base UI `render` prop.** `render={<button type="button" />}`
+ *   tells a Base UI part which element to be; the behaviour stays Base UI's.
+ *
+ * Anything else is an element buried inside a bigger component, where its look
+ * and its behaviour are kept in step by nobody — the package's own version of
+ * the rule the apps get from UIG-3 and UIG-7.
+ *
+ * It keeps its reason on the line above if it stays: `// @estiva-escape: <why>`.
+ */
+export const rawElementOutsideAWrapper: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A raw element nested inside a component, rather than the component itself' },
+    schema: [],
+    messages: {
+      nested:
+        'A raw <{{name}}> inside another element. In this package a raw element is either the component\'s own outermost element or handed to a Base UI `render` prop; one buried inside belongs in a component of its own (Link, Button, MenuItem...).',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      // ESLint's types know ESTree's nodes, not JSX's; the parser hands this one over.
+      JSXOpeningElement(node: Rule.Node) {
+        const element = node as unknown as JSXOpeningElement
+        const name = element.name.name
+        if (element.name.type !== 'JSXIdentifier' || !name || !RAW_ELEMENTS.has(name)) return
+
+        // An opening tag's own parent is its JSXElement: that is this element,
+        // not an element around it.
+        let parent = element.parent
+        if (parent?.type === 'JSXElement' && parent.openingElement === (element as unknown)) parent = parent.parent
+
+        // Whichever comes first going outward decides: an element around it
+        // means it is nested; a `render` prop means Base UI draws it.
+        for (let p = parent; p; p = p.parent) {
+          if (p.type === 'JSXAttribute') {
+            if (p.name?.name === 'render') return
+            continue
+          }
+          if (p.type !== 'JSXElement' && p.type !== 'JSXFragment') continue
+          if (isEscaped(context, element)) return
+          context.report({ loc: element.loc, messageId: 'nested', data: { name } })
+          return
+        }
+      },
+    }
+  },
+}

package/src/index.ts

@@ -18,6 +18,23 @@ export { Button, type ButtonProps, type ButtonSize, type ButtonVariant } from '.
 export { Card, type CardAttention, type CardFill, type CardHover, type CardProps } from './Card'
 export { Checkbox, type CheckboxProps } from './Checkbox'
 export { Chip, type ChipProps, type ChipType } from './Chip'
+export {
+  CommandPalette,
+  CommandPaletteAnswer,
+  CommandPaletteForm,
+  CommandPaletteQuote,
+  CommandPaletteSearch,
+  CommandPaletteWorking,
+  type CommandPaletteAnswerProps,
+  type CommandPaletteChip,
+  type CommandPaletteFormProps,
+  type CommandPaletteGroup,
+  type CommandPaletteProps,
+  type CommandPaletteQuoteProps,
+  type CommandPaletteRow,
+  type CommandPaletteSearchProps,
+  type CommandPaletteWorkingProps,
+} from './CommandPalette'
 export { ChipInput, InputChip, type ChipInputOption, type ChipInputProps, type InputChipProps } from './ChipInput'
 export {
   INLINE_CHIP_CLASSES,

package/stories/Choosing.mdx

@@ -62,6 +62,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A hint on hover or on keyboard focus | **Tooltip** / **WithTooltip** — one `TooltipProvider` at the app root shares the delay |
 | A strip of controls that act on one thing | **Toolbar** — one Tab stop for the row, arrow keys along it |
 | Reactions to choose from | **ReactionPicker** — the row; **Reaction** is the pill it produces |
+| One window to find something and act on it, opened by a shortcut | **CommandPalette** — rows, forms and written answers, one level at a time |
 | Anything with a title, body and footer | **DialogShell** |
 | "Are you sure?" | **ConfirmDialog** |
 

package/stories/TokensPage.tsx

@@ -172,7 +172,7 @@ function Users({ names }: { names: string[] }) {
 function SwatchBox({ token }: { token: Token }) {
   const v = `var(${token.cssVar})`
   const base = 'h-6 w-10 shrink-0 rounded-md'
-  /* eslint-disable no-restricted-syntax -- this page draws every token from its CSS
+  /* eslint-disable no-restricted-syntax -- @estiva-escape: this page draws every token from its CSS
      variable, so a swatch shows the value the theme holds, including a token no
      class spells yet. */
   switch (token.swatch) {