@estiva-app/ui 0.17.0 → 0.19.0

package/src/Form.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef, type FormHTMLAttributes, type ReactNode } from 'react'
+import { useLayoutEffect, useRef, type FormHTMLAttributes, type KeyboardEvent, type ReactNode } from 'react'
 import { Fieldset } from '@base-ui/react/fieldset'
 import { Form as BaseForm } from '@base-ui/react/form'
 import { cn } from './cn'
@@ -27,26 +27,57 @@ import { FormBusyContext, useFormBusy } from './formBusy'
  * When `busy` ends, focus goes to the first invalid field, else to what sent
  * the form, else to the first control. That is `CommandPalette`'s order
  * too, so the two read the same (UIG-29).
+ *
+ * The keys are ours, the same in every form (Katerina, 16 September): Enter in
+ * a one-line field sends; Enter in a text area is a new line; Enter in a list
+ * or a people picker picks; Ctrl+Enter (Cmd+Enter) sends from anywhere inside.
+ * The form sends on Enter itself rather than leaving it to the browser, whose
+ * implicit submission depends on whether the form has a submit button and how
+ * many fields it holds. `enterSends={false}` keeps Enter in a one-line field
+ * from sending, for a form where only Ctrl+Enter may send (`CommandPalette`).
+ * Every way of sending goes through the form's submit, so Base UI's field
+ * check runs for each.
  */
 export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'children' | 'noValidate'> {
   /** Enter in a field, or a submit button. The page's own submit is already prevented. */
   onSubmit: () => void | Promise<void>
   /** While sending: every field and button inside is switched off, and focus waits on the form. */
   busy?: boolean
+  /**
+   * Whether Enter in a one-line field sends. On by default. Off where only
+   * Ctrl+Enter may send — a form inside `CommandPalette`. Ctrl+Enter sends either way.
+   */
+  enterSends?: boolean
   children: ReactNode
 }
 
 const CONTROL = 'input:not([type="hidden"]), textarea, select, button, [role="checkbox"], [role="combobox"], [tabindex]:not([tabindex="-1"])'
 
+/** The inputs a person types one line into; a picker's input (`role="combobox"`) is not one. */
+const ONE_LINE = new Set(['', 'text', 'search', 'email', 'url', 'tel', 'password', 'number'])
+
 function usable(element: Element | null): element is HTMLElement {
   return element instanceof HTMLElement && element.isConnected && element.matches(CONTROL) && !element.matches(':disabled') && element.getAttribute('aria-disabled') !== 'true'
 }
 
-export function Form({ onSubmit, busy: ownBusy = false, className, children, ...props }: FormProps) {
+/** A marked field's own control: Base UI marks the control and the `Field` around it. */
+function firstInvalid(form: HTMLElement): HTMLElement | undefined {
+  for (const marked of form.querySelectorAll('[data-invalid]')) {
+    if (usable(marked)) return marked
+    const inside = Array.from(marked.querySelectorAll(CONTROL)).find(usable)
+    if (inside) return inside
+  }
+  return undefined
+}
+
+export function Form({ onSubmit, busy: ownBusy = false, enterSends = true, className, children, ...props }: FormProps) {
   // A form inside a busy form is busy too.
   const outerBusy = useFormBusy()
   const busy = ownBusy || outerBusy
   const form = useRef<HTMLFormElement>(null)
+  // Read at submit time: a form that is sending does not send again (Ctrl+Enter reaches it while busy).
+  const busyNow = useRef(busy)
+  busyNow.current = busy
   // What had focus when the form went busy, and whether the form took focus from it.
   const sender = useRef<Element | null>(null)
   const holding = useRef(false)
@@ -77,12 +108,39 @@ export function Form({ onSubmit, busy: ownBusy = false, className, children, ...
     holding.current = false
     // Someone who moved focus on while waiting keeps it where they put it.
     if (document.activeElement !== element && document.activeElement !== document.body) return
-    const invalid = Array.from(element.querySelectorAll('[data-invalid]')).find(usable)
-    const target = invalid ?? (usable(sender.current) ? sender.current : Array.from(element.querySelectorAll(CONTROL)).find(usable))
+    const target = firstInvalid(element) ?? (usable(sender.current) ? sender.current : Array.from(element.querySelectorAll(CONTROL)).find(usable))
     sender.current = null
     target?.focus()
   }, [busy])
 
+  /*
+    Bubble phase, after the field's own handler: a picker picks on Enter and
+    says so by preventing it, and a field that handles Enter itself does too.
+  */
+  const onKeyDown = (event: KeyboardEvent<HTMLFormElement>) => {
+    props.onKeyDown?.(event)
+    if (event.key !== 'Enter' || event.defaultPrevented || event.nativeEvent.isComposing) return
+    const target = event.target
+    const inInput = target instanceof HTMLInputElement
+    /*
+      In an input the browser sends a form on its own — on Enter with Shift or
+      Alt too (measured in Chrome: Shift+Enter sent Peek's comment box, 16
+      September) — so the form stops that every time and sends only by these
+      rules. A text area's Enter is a new line and a button's Enter presses it:
+      those are left to the browser.
+    */
+    if (inInput) event.preventDefault()
+    if (event.altKey || event.shiftKey) return
+    if (event.ctrlKey || event.metaKey) {
+      event.preventDefault()
+      form.current?.requestSubmit()
+      return
+    }
+    if (!inInput) return
+    const oneLine = ONE_LINE.has((target.getAttribute('type') ?? '').toLowerCase()) && target.getAttribute('role') !== 'combobox'
+    if (enterSends && oneLine) form.current?.requestSubmit()
+  }
+
   return (
     <BaseForm
       ref={form}
@@ -100,8 +158,10 @@ export function Form({ onSubmit, busy: ownBusy = false, className, children, ...
         if (next && !form.current?.contains(next)) lastInside.current = null
         props.onBlur?.(event)
       }}
+      onKeyDown={onKeyDown}
       onSubmit={(event) => {
         event.preventDefault()
+        if (busyNow.current) return
         void onSubmit()
       }}
     >

package/src/ScrollArea.stories.tsx

@@ -29,6 +29,24 @@ export const Default: Story = {
   ),
 }
 
+/** Rows that stick to the top as the list moves under them. The bar stays above them. */
+export const StickyHeadings: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
+      {['Group one', 'Group two'].map((group) => (
+        <div key={group} className="flex flex-col">
+          <p className="sticky top-0 z-10 bg-bg-surface px-4 py-2 text-caption text-text-secondary">{group}</p>
+          {rows.slice(0, 8).map((row) => (
+            <p key={row} className="px-4 py-1.5 text-body-2 text-text-primary">
+              {row}
+            </p>
+          ))}
+        </div>
+      ))}
+    </ScrollArea>
+  ),
+}
+
 /** Nothing to scroll: the region draws exactly as a plain box would, and no bar. */
 export const Fits: Story = {
   render: () => (

package/src/ScrollArea.tsx

@@ -30,6 +30,12 @@ import { cn } from './cn'
  * the thin scrollbar both apps had styled by hand in their `index.css`, drawn
  * once here instead.
  *
+ * The bar sits above the content (`z-10`). A sticky row inside — a date line
+ * in a conversation, `sticky top-0 z-10` — is at the same level, and the bar
+ * comes after the content in the page, so it paints on top. Without it the
+ * row hid the bar wherever it crossed it: a gap in the thumb, in Peek's topic
+ * and direct-message lists (UIG-8, 16 September).
+ *
  * `orientation` says which way the region scrolls; a table that is wider
  * than its box scrolls `horizontal`, a list `vertical` (the default), a board
  * `both`. A vertical region keeps its content no wider than itself, so a
@@ -58,7 +64,7 @@ export interface ScrollAreaProps {
   children: ReactNode
 }
 
-const BAR = 'flex touch-none select-none rounded-full opacity-0 transition-opacity delay-300 data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[scrolling]:opacity-100 data-[scrolling]:delay-0'
+const BAR = 'z-10 flex touch-none select-none rounded-full opacity-0 transition-opacity delay-300 data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[scrolling]:opacity-100 data-[scrolling]:delay-0'
 const THUMB = 'rounded-full bg-border-strong'
 
 export function ScrollArea({ orientation = 'vertical', className, viewportClassName, contentClassName, viewportRef, onScroll, children }: ScrollAreaProps) {

package/src/eslint/index.test.ts

@@ -6,8 +6,8 @@ import estiva, { APP_RULE_IDS, countGates, PACKAGE_RULE_IDS, PLUGIN_KEY } from '
 
 /**
  * The plugin as an app uses it: a flat config with `configs.recommended`,
- * linting text the way Peek's editor hook does (`lintText`). The rule's own
- * cases are in no-raw-element.test.ts.
+ * linting text the way Peek's editor hook does (`lintText`). The rules' own
+ * cases are in no-raw-element.test.ts and no-rebuilt-behaviour.test.ts.
  */
 const tsx: Linter.Config = {
   files: ['**/*.tsx'],
@@ -35,6 +35,7 @@ describe('the plugin object', () => {
   it('carries every rule, the app ones and the inward ones', () => {
     expect(Object.keys(estiva.rules)).toEqual([
       'no-raw-element',
+      'no-rebuilt-behaviour',
       'raw-element-outside-a-wrapper',
       'no-hand-rolled-behaviour',
       'component-has-a-page',
@@ -54,9 +55,9 @@ describe('the plugin object', () => {
   it('gives an app only the app rules, as errors, under estiva/', () => {
     for (const config of [estiva.configs.recommended, estiva.configs.strict]) {
       expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
-      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error' })
+      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error' })
     }
-    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element'])
+    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour'])
   })
 
   it('gives this package its own set, as errors, and it reaches no app config', () => {
@@ -90,6 +91,25 @@ describe('an app lint with configs.recommended', () => {
     ])
   })
 
+  it('reports behaviour rebuilt by hand, naming the part', async () => {
+    const [result] = await lint(component('    <div className="h-64 overflow-y-auto" />'))
+    expect(result.messages.map((m) => [m.ruleId, m.severity, m.message])).toEqual([
+      ['estiva/no-rebuilt-behaviour', 2, "`overflow-y-auto` scrolls with the browser's scrollbar. Use `ScrollArea` from @estiva-app/ui, which draws ours."],
+    ])
+  })
+
+  /**
+   * UIG-8's acceptance: a separator inside Divider is not a hand-written role.
+   * The package is exempt from the apps' rules; this runs them on Divider anyway,
+   * to show the role branch has nothing to say there (its Base UI import is the
+   * package's job, and reported only because the apps' config is not meant for it).
+   */
+  it("finds no hand-written role in Divider's own source", async () => {
+    const source = readFileSync(new URL('../Divider.tsx', import.meta.url), 'utf8')
+    const [result] = await lint(source)
+    expect(result.messages.filter((m) => m.messageId === 'role' || m.messageId === 'roleNoPart')).toEqual([])
+  })
+
   it('passes the same element under an escape', async () => {
     const [result] = await lint(component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'))
     expect(result.messages).toEqual([])
@@ -99,8 +119,9 @@ describe('an app lint with configs.recommended', () => {
 describe('countGates', () => {
   it('counts an error, and an escape only when the lint reports escapes', async () => {
     const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
-    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 } })
-    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 } })
+    const none = { errors: 0, warnings: 0, escapes: 0 }
+    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': none })
+    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none })
   })
 
   it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
@@ -118,6 +139,9 @@ describe('countGates', () => {
   })
 
   it('lists every rule of the plugin, even with nothing found', () => {
-    expect(countGates([])).toEqual({ rules: { 'estiva/no-raw-element': { errors: 0, warnings: 0, escapes: 0 } }, disabled: [] })
+    expect(countGates([])).toEqual({
+      rules: { 'estiva/no-raw-element': { errors: 0, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': { errors: 0, warnings: 0, escapes: 0 } },
+      disabled: [],
+    })
   })
 })

package/src/eslint/index.ts

@@ -21,9 +21,11 @@ import type { ESLint, Linter } from 'eslint'
 import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
 import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
 import { noRawElement } from './no-raw-element'
+import { noRebuiltBehaviour } from './no-rebuilt-behaviour'
 import { rawElementOutsideAWrapper } from './raw-element-outside-a-wrapper'
 
 export { ESCAPE_MARKER, MIN_REASON, SETTINGS_KEY, isEscaped, type EstivaSettings } from './escape'
+export { OWNED_BEHAVIOURS, type OwnedBehaviour } from './no-rebuilt-behaviour'
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
@@ -32,10 +34,12 @@ export const PLUGIN_KEY = 'estiva'
 
 /**
  * The rules an **app** runs: they say an app must not build what the package
- * already has. `recommended` and `strict` carry these and only these.
+ * already has — a raw control (UIG-7), or a behaviour one of its parts owns
+ * (UIG-8). `recommended` and `strict` carry these and only these.
  */
 const appRules = {
   'no-raw-element': noRawElement,
+  'no-rebuilt-behaviour': noRebuiltBehaviour,
 }
 
 /**
@@ -73,7 +77,7 @@ export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGI
 /**
  * `recommended` switches every **app** rule on at the level it was ruled at: an
  * error blocks, a warning is reported and never blocks. `strict` makes every app
- * rule an error. With one rule, an error, the two are the same today; they part
+ * rule an error. With every app rule an error, the two are the same today; they part
  * when the first warning-level rule arrives (UIG-25).
  *
  * `package` is the inward set (UIG-5), which only this package runs.
@@ -81,7 +85,10 @@ export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGI
 plugin.configs.recommended = {
   name: '@estiva-app/ui/recommended',
   plugins: { [PLUGIN_KEY]: plugin },
-  rules: { [`${PLUGIN_KEY}/no-raw-element`]: 'error' },
+  rules: {
+    [`${PLUGIN_KEY}/no-raw-element`]: 'error',
+    [`${PLUGIN_KEY}/no-rebuilt-behaviour`]: 'error',
+  },
 }
 plugin.configs.strict = {
   name: '@estiva-app/ui/strict',

package/src/eslint/no-rebuilt-behaviour.test.ts

@@ -0,0 +1,276 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { RuleTester } from 'eslint'
+import ts from 'typescript'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import {
+  BASE_UI_PARTS,
+  baseUiModule,
+  noRebuiltBehaviour,
+  OWNED_BEHAVIOURS,
+  ROLE_PARTS,
+  utilityOf,
+  WALKING_KEYS,
+} from './no-rebuilt-behaviour'
+
+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`
+const effect = (body: string) => `useEffect(() => {\n${body}\n}, [])\n`
+const LIST = ' To pick several, `ChipInput`; to search and act, `CommandPalette`; to tick several in a list, `Checkbox` with `row`.'
+
+tester.run('no-rebuilt-behaviour', noRebuiltBehaviour, {
+  valid: [
+    // Base UI and portals
+    { name: 'a part from the package', code: "import { Select, Popover } from '@estiva-app/ui'" },
+    { name: 'react-dom without createPortal', code: "import { flushSync } from 'react-dom'\nflushSync(() => {})" },
+    { name: 'a package whose name only starts like Base UI', code: "import x from '@base-uix/react'" },
+
+    // listeners
+    { name: 'the window coming back is not a floating part', code: effect("  window.addEventListener('focus', refresh)\n  document.addEventListener('visibilitychange', refresh)\n  window.addEventListener('storage', sync)") },
+    { name: 'a listener on an element, not the page', code: effect("  ref.current.addEventListener('keydown', onKey)") },
+    { name: 'an event the code computes', code: effect('  document.addEventListener(name, handler)') },
+    { name: "the app's own event on window", code: effect("  window.addEventListener('highlight-tag-click', open)") },
+
+    // keys
+    { name: 'Enter and Escape in a field are typing', code: "const onKeyDown = (e) => {\n  if (e.key === 'Enter') send()\n  if (e.key === 'Escape') cancel()\n}" },
+    { name: 'a shortcut letter', code: "const onKeyDown = (e) => {\n  if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') open()\n}" },
+    { name: 'the word ArrowDown that is not a key', code: "const label = 'ArrowDown'\nif (label === 'ArrowDown') go()" },
+
+    // roles
+    { name: 'role img on an svg', code: component('    <svg role="img" aria-label="Logo"><path d="M0 0" /></svg>') },
+    { name: 'the roles that describe rather than behave', code: component('    <div role="group" aria-label="Format">\n      <div role="presentation" />\n      <section role="region" aria-label="A" />\n      <span role="none" />\n    </div>') },
+    { name: 'a role the code computes', code: component('    <div role={role} />') },
+
+    // tab stops
+    { name: 'tabIndex -1 makes a box focusable by script, not a Tab stop', code: component('    <p tabIndex={-1}>measured</p>') },
+    { name: 'tabIndex on a control', code: component('    <div>\n      <button tabIndex={0}>x</button>\n      <input tabIndex={0} />\n      <a href="/x" tabIndex={0}>x</a>\n    </div>') },
+    { name: 'tabIndex passed through from a prop', code: component('    <div tabIndex={props.tabIndex} />') },
+    { name: 'tabIndex on an editable region', code: component('    <div contentEditable tabIndex={0} />') },
+    { name: 'tabIndex on a package component', code: component('    <MenuItem tabIndex={-1} label="Item" />') },
+
+    // scrolling
+    { name: 'overflow that does not scroll', code: component('    <div className="overflow-hidden overflow-x-clip overflow-visible overscroll-contain" />') },
+    { name: 'a word that only contains the class', code: "const id = 'my-overflow-auto-thing'" },
+    { name: 'a style that hides overflow', code: component("    <div style={{ overflow: 'hidden' }} />") },
+
+    // escapes
+    {
+      name: 'an escape above the statement keeps a page listener',
+      code: effect("  // @estiva-escape: an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)"),
+    },
+    {
+      name: 'an escape above the element keeps a hand-written role',
+      code: component('    // @estiva-escape: a list the editor drives from its caret\n    <MenuItem role="option" aria-selected label="Item" />'),
+    },
+    {
+      name: 'an escape above the object property keeps its arrow keys',
+      code: "useImperativeHandle(ref, () => ({\n  // @estiva-escape: a list the editor drives from its caret\n  onKeyDown: ({ event }) => {\n    if (event.key === 'ArrowDown') next()\n    if (event.key === 'ArrowUp') previous()\n    return false\n  },\n}))",
+    },
+    {
+      name: 'an escape above the call keeps a portal',
+      code: "import { createPortal } from 'react-dom'\nfunction Viewer() {\n  // @estiva-escape: becomes the package Lightbox at stage 7\n  return createPortal(<div />, document.body)\n}",
+    },
+    {
+      name: 'an escape above an array item keeps its class',
+      code: "const CLASSES = [\n  'flex',\n  // @estiva-escape: a code block the editor draws, which nothing can wrap\n  '[&_pre]:overflow-x-auto',\n]",
+    },
+    {
+      name: 'one escape above an element covers everything found on it',
+      code: component('    // @estiva-escape: a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} className="overflow-auto" />'),
+    },
+  ],
+  invalid: [
+    // Base UI
+    {
+      name: 'a Base UI import names the part built on it',
+      code: "import { Dialog } from '@base-ui/react/dialog'",
+      errors: [{ message: 'Only @estiva-app/ui imports Base UI (`@base-ui/react/dialog`). Use `DialogShell` from @estiva-app/ui. To search and act, `CommandPalette`.', line: 1 }],
+    },
+    ...Object.entries(BASE_UI_PARTS).map(([module, part]) => ({
+      name: part ? `@base-ui/react/${module} names ${part.use}` : `@base-ui/react/${module} has no part yet`,
+      code: `import * as Part from '@base-ui/react/${module}'`,
+      errors: [{ messageId: part ? 'baseUi' : 'baseUiNoPart' }],
+    })),
+    { name: 'the old package spelling', code: "import { Menu } from '@base-ui-components/react/menu'", errors: [{ message: 'Only @estiva-app/ui imports Base UI (`@base-ui-components/react/menu`). Use `Menu` from @estiva-app/ui.' }] },
+    { name: 'the package root', code: "import { Popover } from '@base-ui/react'", errors: [{ messageId: 'baseUiNoPart' }] },
+    { name: "a Base UI utility", code: "import { useRender } from '@base-ui/react/use-render'", errors: [{ messageId: 'baseUiNoPart' }] },
+    { name: 'a type-only import', code: "import type { PopoverRootProps } from '@base-ui/react/popover'", errors: [{ messageId: 'baseUi' }] },
+    { name: 're-exported', code: "export { Popover } from '@base-ui/react/popover'", errors: [{ messageId: 'baseUi' }] },
+    { name: 'imported when needed', code: "const Tabs = lazy(() => import('@base-ui/react/tabs'))", errors: [{ messageId: 'baseUi' }] },
+    { name: 'required', code: "const { Toolbar } = require('@base-ui/react/toolbar')", errors: [{ messageId: 'baseUi' }] },
+
+    // portals
+    {
+      name: 'createPortal, called: reported where it is called, once',
+      code: "import { createPortal } from 'react-dom'\nfunction Viewer() {\n  return createPortal(<div />, document.body)\n}",
+      errors: [{ messageId: 'portal', line: 3 }],
+    },
+    { name: 'createPortal imported and never called', code: "import { createPortal } from 'react-dom'\nexport function Header() {\n  return null\n}", errors: [{ messageId: 'portal', line: 1 }] },
+    { name: 'createPortal on the namespace', code: "import ReactDOM from 'react-dom'\nReactDOM.createPortal(child, node)", errors: [{ messageId: 'portal', line: 2 }] },
+
+    // listeners
+    {
+      name: 'a press outside, by hand',
+      code: effect("  document.addEventListener('mousedown', close)"),
+      errors: [{ message: 'A `mousedown` listener on `document`: closing on a press outside, by hand. `Popover`, `Menu`, `Select`, `DialogShell` and `PreviewCard` from @estiva-app/ui close themselves.', line: 2 }],
+    },
+    { name: 'keys for the whole page', code: effect("  window.addEventListener('keydown', onKey)"), errors: [{ messageId: 'key', data: { event: 'keydown', target: 'window' } }] },
+    { name: 'focus held by hand', code: effect("  document.body.addEventListener('focusin', keep, true)"), errors: [{ messageId: 'focus', data: { event: 'focusin', target: 'document.body' } }] },
+    { name: 'following an anchor by hand', code: effect("  window.addEventListener('resize', place)\n  window.addEventListener('scroll', place, true)"), errors: [{ messageId: 'follow', line: 2 }, { messageId: 'follow', line: 3 }] },
+    { name: 'a handler property on window', code: 'window.onkeydown = (e) => close(e)', errors: [{ messageId: 'key', data: { event: 'keydown', target: 'window' } }] },
+    { name: "the page's scroll locked by hand", code: "document.body.style.overflow = 'hidden'", errors: [{ messageId: 'scrollLock' }] },
+
+    // keys
+    {
+      name: 'arrow keys in one handler: one report, at the first',
+      code: "const onKeyDown = (e) => {\n  if (e.key === 'ArrowDown') next()\n  if (e.key === 'ArrowUp') previous()\n}",
+      errors: [{ message: 'Arrow keys handled by hand (`ArrowDown`). `Menu`, `Select`, `ChipInput`, `CommandPalette`, `Tabs` and `Toolbar` from @estiva-app/ui move through their items themselves.', line: 2 }],
+    },
+    ...WALKING_KEYS.map((key) => ({ name: `${key} is a walking key`, code: `function onKey(event) {\n  if (event.code == '${key}') go()\n}`, errors: [{ messageId: 'walking', data: { key } }] })),
+    { name: 'two handlers are two reports', code: "const a = (e) => e.key === 'ArrowLeft'\nconst b = (e) => e.key === 'ArrowRight'", errors: [{ messageId: 'walking', line: 1 }, { messageId: 'walking', line: 2 }] },
+    { name: 'a switch on the key', code: "function onKey(e) {\n  switch (e.key) {\n    case 'Enter': return send()\n    case 'Home': return first()\n  }\n}", errors: [{ messageId: 'walking', data: { key: 'Home' }, line: 4 }] },
+    { name: 'a list of keys', code: "const walks = (event) => ['ArrowUp', 'ArrowDown'].includes(event.key)", errors: [{ messageId: 'walking', data: { key: 'ArrowUp' } }] },
+    { name: 'a destructured key', code: "function onKey({ key }) {\n  if (key !== 'PageDown') return\n}", errors: [{ messageId: 'walking', data: { key: 'PageDown' } }] },
+    { name: 'the Tab key, by hand', code: "const trap = (e) => {\n  if (e.key === 'Tab') keepInside(e)\n}", errors: [{ messageId: 'tabKey', line: 2 }] },
+    { name: 'arrow keys in a JSX handler', code: component("    <div onKeyDown={(e) => { if (e.key === 'ArrowDown') next() }} />"), errors: [{ messageId: 'walking', line: 3 }] },
+
+    // roles
+    ...Object.entries(ROLE_PARTS).map(([role, { thing, part }]) => ({
+      name: part ? `role="${role}" names ${part.use}` : `role="${role}" has no part yet`,
+      code: component(`    <div role="${role}" />`),
+      errors: [
+        part
+          ? { message: `A hand-written \`role="${role}"\` is a hand-made ${thing}. Use \`${part.use}\` from @estiva-app/ui.${part.more ?? ''}` }
+          : { message: `A hand-written \`role="${role}"\` is a hand-made ${thing}, and @estiva-app/ui has no part for one yet. Do not build one here: ask Katerina, and it gets made in @estiva-app/ui.` },
+      ],
+    })),
+    { name: 'a hand-made option row (Peek, AddToOpenWorkDialog)', code: component('    <div role="option" aria-selected={checked} onClick={toggle} />'), errors: [{ message: `A hand-written \`role="option"\` is a hand-made list. Use \`Select\` from @estiva-app/ui.${LIST}` }] },
+    { name: 'a role on a package component', code: component('    <MenuItem role="option" label="Item" />'), errors: [{ messageId: 'role' }] },
+    { name: 'a role in braces, or one of two', code: component("    <p role={failed ? 'alert' : 'status'} />"), errors: [{ messageId: 'role', data: { role: 'alert', thing: 'message', use: 'FieldLine', more: ' For a notice, `Banner`; for a message that comes and goes, `Toast`.' } }] },
+
+    // tab stops
+    { name: 'tabIndex 0 on a div', code: component('    <div tabIndex={0} />'), errors: [{ message: '`tabIndex=0` makes a `<div>` a Tab stop by hand. Use `Button`, `IconButton` or `Link` from @estiva-app/ui, which are reachable already.' }] },
+    { name: 'tabIndex written as a string', code: component('    <span tabIndex="0" />'), errors: [{ messageId: 'tabStop' }] },
+    { name: 'tabIndex above 0', code: component('    <li tabIndex={2} />'), errors: [{ messageId: 'tabStop' }] },
+    { name: 'tabIndex 0 on one side of a condition (Ship, DescriptionEditor)', code: component('    <div tabIndex={readOnly ? undefined : 0} />'), errors: [{ messageId: 'tabStop', data: { value: 'readOnly ? undefined : 0', element: 'div' } }] },
+
+    // scrolling
+    { name: 'overflow-y-auto', code: component('    <div className="h-64 overflow-y-auto" />'), errors: [{ message: "`overflow-y-auto` scrolls with the browser's scrollbar. Use `ScrollArea` from @estiva-app/ui, which draws ours." }] },
+    { name: 'every overflow that scrolls', code: component('    <div className="overflow-auto overflow-scroll overflow-x-auto overflow-y-scroll" />'), errors: [{ messageId: 'scrollClass' }, { messageId: 'scrollClass' }, { messageId: 'scrollClass' }, { messageId: 'scrollClass' }] },
+    { name: 'behind a word-shaped variant', code: component('    <div className="md:overflow-auto" />'), errors: [{ messageId: 'scrollClass', data: { token: 'md:overflow-auto' } }] },
+    { name: 'behind an arbitrary variant (Ship, prose.ts)', code: "const PROSE_CLASSES = [\n  '[&_pre]:overflow-x-auto [&_pre]:rounded-md',\n]", errors: [{ messageId: 'scrollClass', data: { token: '[&_pre]:overflow-x-auto' }, line: 2 }] },
+    { name: 'marked important', code: "const box = cn('!overflow-y-auto')", errors: [{ messageId: 'scrollClass' }] },
+    { name: 'inside a template', code: 'const box = `flex ${open ? "a" : "b"} overflow-y-auto`', errors: [{ messageId: 'scrollClass' }] },
+    { name: 'in a style', code: component("    <div style={{ overflowY: 'auto' }} />"), errors: [{ message: "`overflowY: 'auto'` scrolls with the browser's scrollbar. Use `ScrollArea` from @estiva-app/ui, which draws ours." }] },
+
+    // escapes
+    {
+      name: 'an escape with no reason hides nothing',
+      code: effect("  // @estiva-escape:\n  document.addEventListener('mousedown', close)"),
+      errors: [{ messageId: 'escapeWithoutReason', line: 2 }, { messageId: 'press', line: 3 }],
+    },
+    {
+      name: 'an escape above one statement does not reach the next',
+      code: effect("  // @estiva-escape: an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)\n  document.addEventListener('keydown', onKey)"),
+      errors: [{ messageId: 'key', line: 4 }],
+    },
+    {
+      name: 'with reportEscapes on, one escape over two findings is counted once',
+      code: component('    // @estiva-escape: a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} />'),
+      settings: { estiva: { reportEscapes: true } },
+      errors: [{ messageId: 'escaped', line: 3 }],
+    },
+  ],
+})
+
+describe('the behaviour table is derived from the package source', () => {
+  const src = new URL('../', import.meta.url)
+  const index = readFileSync(new URL('index.ts', src), 'utf8')
+
+  /** Every name the package root exports, and the file it comes from. */
+  const exportedFrom = new Map<string, string>()
+  for (const statement of ts.createSourceFile('index.ts', index, ts.ScriptTarget.Latest, true).statements) {
+    if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+    if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue
+    for (const element of statement.exportClause.elements) exportedFrom.set(element.name.text, statement.moduleSpecifier.text.replace(/^\.\//, ''))
+  }
+
+  /** Which Base UI modules each component file imports, read with the TypeScript parser. */
+  const importsOf = new Map<string, Set<string>>()
+  for (const file of readdirSync(src).filter((f) => /\.tsx?$/.test(f) && !/\.(test|stories)\.tsx?$/.test(f))) {
+    const sourceFile = ts.createSourceFile(file, readFileSync(new URL(file, src), 'utf8'), ts.ScriptTarget.Latest, true)
+    const modules = new Set<string>()
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+      const module = baseUiModule(statement.moduleSpecifier.text)
+      if (module !== undefined) modules.add(module)
+    }
+    importsOf.set(file.replace(/\.tsx?$/, ''), modules)
+  }
+  const importedAnywhere = new Set([...importsOf.values()].flatMap((s) => [...s]))
+
+  /** Base UI's helpers, which no component is built on: an import of one says to ask. */
+  const UTILITIES = new Set(['', 'types', 'use-render', 'merge-props', 'csp-provider', 'direction-provider', 'unstable-use-media-query'])
+
+  it('names every Base UI part the package imports', () => {
+    const unnamed = [...importedAnywhere].filter((m) => !UTILITIES.has(m) && !BASE_UI_PARTS[m])
+    expect(unnamed).toEqual([])
+    expect(importedAnywhere.size).toBeGreaterThan(20)
+  })
+
+  it('names, for each part, a component whose own file imports it', () => {
+    for (const [module, part] of Object.entries(BASE_UI_PARTS)) {
+      if (!part) continue
+      const file = exportedFrom.get(part.use)
+      expect(file, `${part.use} is exported`).toBeDefined()
+      expect([...(importsOf.get(file as string) ?? [])], `${part.use} (${file}) imports @base-ui/react/${module}`).toContain(module)
+    }
+  })
+
+  it('says "no part yet" only for parts no component imports', () => {
+    const named = Object.entries(BASE_UI_PARTS).filter(([, part]) => part === null).map(([module]) => module)
+    expect(named.filter((m) => importedAnywhere.has(m))).toEqual([])
+  })
+
+  it("covers every module Base UI publishes", () => {
+    const base = createRequire(import.meta.url)('@base-ui/react/package.json') as { exports: Record<string, unknown> }
+    const published = Object.keys(base.exports)
+      .filter((key) => key.startsWith('./') && !key.startsWith('./internals/') && !key.endsWith('.json'))
+      .map((key) => key.slice(2))
+    expect(published.filter((m) => !UTILITIES.has(m) && !Object.hasOwn(BASE_UI_PARTS, m))).toEqual([])
+  })
+
+  it('names only components the package exports, everywhere it names one', () => {
+    const messages = Object.values(noRebuiltBehaviour.meta?.messages ?? {}).join(' ')
+    const tables = JSON.stringify([BASE_UI_PARTS, ROLE_PARTS, OWNED_BEHAVIOURS.map((b) => b.owners)])
+    const named = new Set([...`${messages} ${tables}`.matchAll(/`([A-Z]\w+)`|"use":"(\w+)"|"([A-Z]\w+)"/g)].map((m) => m[1] ?? m[2] ?? m[3]))
+    expect([...named].filter((name) => !exportedFrom.has(name))).toEqual([])
+  })
+
+  it('has one row per behaviour, each naming an owner and what it reads', () => {
+    expect(OWNED_BEHAVIOURS.map((b) => b.id)).toEqual(['base-ui', 'portal', 'press-outside', 'page-keys', 'focus', 'scroll-lock', 'follow', 'walking', 'role', 'tab-stop', 'scroll'])
+    for (const row of OWNED_BEHAVIOURS) {
+      expect(row.owners.length, row.id).toBeGreaterThan(0)
+      expect(row.baseUi.length, row.id).toBeGreaterThan(0)
+      expect(row.reads, row.id).not.toBe('')
+    }
+  })
+})
+
+describe('reading a class past its variants', () => {
+  it('keeps brackets whole', () => {
+    expect(utilityOf('[&_pre]:overflow-x-auto')).toBe('overflow-x-auto')
+    expect(utilityOf('md:hover:overflow-auto')).toBe('overflow-auto')
+    expect(utilityOf('[&:not(pre)>code]:overflow-y-scroll')).toBe('overflow-y-scroll')
+    expect(utilityOf('!overflow-auto')).toBe('overflow-auto')
+  })
+})