@estiva-app/ui 0.35.2 → 0.36.0

package/src/CommandPalette.tsx

@@ -123,7 +123,7 @@ export function CommandPalette({ open, onOpenChange, label, where, modKey = 'Ctr
       <Dialog.Portal>
         <Dialog.Backdrop className="fixed inset-0 z-40 bg-scrim" />
         <Dialog.Viewport className="fixed inset-0 z-50 flex items-start justify-center pt-[16vh]">
-          {/* @estiva-escape: A3 (Katerina, 24 September: leave CommandPalette alone): the palette's window keeps its own border */}
+          {/* @estiva-escape(no-copied-look): A3 (Katerina, 24 September: leave CommandPalette alone): the palette's window keeps its own border */}
           <Dialog.Popup
             ref={popupRef}
             aria-label={label}
@@ -374,7 +374,7 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
       <div className="flex h-12 shrink-0 items-center gap-3 border-b border-border-subtle px-5">
         <IconSearch size={16} stroke={1.5} className="shrink-0 text-text-secondary" />
         {chip && <LevelChip chip={chip} onBack={back} />}
-        {/* @estiva-escape: A5 (Katerina, 24 September: leave CommandPalette alone): the palette's search field keeps its own classes */}
+        {/* @estiva-escape(no-copied-look): A5 (Katerina, 24 September: leave CommandPalette alone): the palette's search field keeps its own classes */}
         <Autocomplete.Input
           ref={inputRef}
           data-command-palette-field=""
@@ -555,7 +555,7 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
 
   return (
     <div ref={frameRef} tabIndex={-1} onKeyDown={onKeyDown} onFocus={measure} onBlur={measure} onInput={measure} className="flex min-h-0 flex-col outline-none">
-      {/* @estiva-escape: the palette's own input bar, the twin of its search row; the level chip stands where the field was */}
+      {/* @estiva-escape(no-handmade-header): the palette's own input bar, the twin of its search row; the level chip stands where the field was */}
       <div className="flex h-12 shrink-0 items-center gap-3 border-b border-border-subtle px-5">
         {icon != null && <span className="flex shrink-0 items-center text-text-secondary">{icon}</span>}
         <LevelChip chip={chip} onBack={back} />

package/src/DialogShell.tsx

@@ -86,7 +86,7 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
 
         {/* Dialog */}
         <div className="fixed inset-0 z-50 flex items-center justify-center pointer-events-none">
-          {/* @estiva-escape: A3 (Katerina, 24 September: leave CommandPalette alone): a dialog's window and the palette's are left as they are */}
+          {/* @estiva-escape(no-copied-look): A3 (Katerina, 24 September: leave CommandPalette alone): a dialog's window and the palette's are left as they are */}
           <Parts.Popup
             ref={popupRef}
             /*

package/src/EmptyState.mdx

@@ -36,9 +36,10 @@ need a height from the caller (`className="h-full"`).
 
 ## When not
 
-- Data is still on its way → **Skeleton**; empty and loading are different
-  truths. When the shape of what arrives is unknown, an EmptyState that says so
-  — "Opening…" — is fine.
+- Data is still on its way → **Skeleton**: **SkeletonList**, or a shape of
+  your own from **SkeletonBar**; empty and loading are different truths.
+  When the shape of what arrives is unknown, an EmptyState that says so —
+  "Opening…" — is fine.
 - Something went wrong → say what failed, in words. An EmptyState can carry
   it, in its usual look — never red. An empty state that hides a failure
   misleads.

package/src/Lightbox.tsx

@@ -74,7 +74,7 @@ export function Lightbox({ src, alt, onClose, className }: LightboxProps) {
             onClick={(e) => e.stopPropagation()}
             className={cn('max-w-full max-h-full object-contain rounded-lg', className)}
           />
-          {/* @estiva-escape: N4 (Katerina, 24 September: record only): the small round button AttachmentCard's remove also draws; a part if a third appears */}
+          {/* @estiva-escape(no-copied-look): N4 (Katerina, 24 September: record only): the small round button AttachmentCard's remove also draws; a part if a third appears */}
           <Dialog.Close
             aria-label="Close"
             className="absolute top-4 right-4 size-8 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary"

package/src/NavItem.tsx

@@ -28,7 +28,7 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
 
 export function NavItem({ label, href, count, countLabel, active = false, icon, className, ...props }: NavItemProps) {
   return (
-    // @estiva-escape: N5 (Katerina, 24 September: record only): a row that fills on hover, as PersonTrigger's row also does
+    // @estiva-escape(no-copied-look): N5 (Katerina, 24 September: record only): a row that fills on hover, as PersonTrigger's row also does
     <a
       href={href}
       aria-current={active ? 'page' : undefined}

package/src/PersonTrigger.tsx

@@ -60,7 +60,7 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
     )
   }
   return (
-    // @estiva-escape: N5 (Katerina, 24 September: record only): a row that fills on hover, as NavItem also does
+    // @estiva-escape(no-copied-look): N5 (Katerina, 24 September: record only): a row that fills on hover, as NavItem also does
     <BaseButton
       type="button"
       aria-haspopup="menu"

package/src/Reaction.tsx

@@ -63,7 +63,7 @@ export interface ReactionProps extends Omit<ButtonHTMLAttributes<HTMLButtonEleme
 
 export function Reaction({ emoji, count, pressed = false, className, ...props }: ReactionProps) {
   return (
-    // @estiva-escape: W1 (Katerina, 24 September: leave alone): a reaction pill shares four words with a field's box by coincidence
+    // @estiva-escape(no-copied-look): W1 (Katerina, 24 September: leave alone): a reaction pill shares four words with a field's box by coincidence
     <Toggle
       // Controlled: a reaction is yours when the data says so, not when the
       // pill was last pressed — a write can fail, and another client can

package/src/ScrollArea.mdx

@@ -27,6 +27,10 @@ the content is moving; nothing moves when it appears.
 - A box that never overflows. A ScrollArea around it changes nothing, and
   is one more element.
 - The page itself. The browser owns that bar.
+- A whole list column → **ListColumn**, which scrolls its rows itself.
+
+No alternative for the first two: a box that never overflows needs nothing
+around it, and the page's bar is the browser's.
 
 ## How
 

package/src/Select.tsx

@@ -74,7 +74,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
   // a native `disabled` button, which Tab skips and a tooltip cannot open on.
   const held = Boolean(disabledReason)
   const trigger = (
-      // @estiva-escape: N1 (Katerina, 24 September: record only): Select's box drops the hover while held, so it cannot take FIELD_SHELL_CLASSES as it is
+      // @estiva-escape(no-copied-look): N1 (Katerina, 24 September: record only): Select's box drops the hover while held, so it cannot take FIELD_SHELL_CLASSES as it is
       <BaseSelect.Trigger
         aria-label={ariaLabel}
         aria-required={aria['aria-required']}

package/src/TopBar.mdx

@@ -33,7 +33,7 @@ reachable.
 ## When not
 
 - Page-level headers inside the content → not this; this is the frame's
-  bar, once per app.
+  bar, once per app. The top of a column is **ContainerHeader**.
 - Anything the bar would need to know — who you are, what is searched —
   stays outside: pass composed slots.
 

package/src/eslint/escape.ts

@@ -4,15 +4,21 @@ import type { AST, Rule } from 'eslint'
  * The escape marker (UIG-3, seam S4 in docs/GATES.md §16): one written reason
  * why one element stays as it is.
  *
- * A line comment directly above the element,
+ * A line comment directly above the element, naming the rule it keeps off,
  *
- *     // @estiva-escape: <reason>
+ *     // @estiva-escape(no-raw-element): <reason>
  *
  * or, where the element is a JSX child, the JSX comment on the line above,
  *
- *     {/* @estiva-escape: <reason> *\/}
+ *     {/* @estiva-escape(no-raw-element): <reason> *\/}
  *
- * with at least ten characters of reason, spaces not counted.
+ * with at least ten characters of reason, spaces not counted. It escapes only
+ * the rules it names (Katerina's ruling B3, 25 September: one reason used to
+ * switch off every rule on the element, so a raw button that also wrote a
+ * dialog's role by hand passed under one reason). Two rules on one element are
+ * named together, `@estiva-escape(no-raw-element, no-rebuilt-behaviour)`, each
+ * on purpose. A marker that names no rule escapes nothing, and says which name
+ * to write.
  *
  * Not `eslint-disable`. A directive switches a rule off without saying it was
  * meant, and the count of escapes (`.gates-count.json`) could not see it. A
@@ -37,11 +43,29 @@ export const SETTINGS_KEY = 'estiva'
  * reports through the rule that called it.
  */
 export const ESCAPE_MESSAGES = {
-  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}: <why this stays>\`. An escape with no reason hides nothing.`,
-  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}: <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}({{rule}}): <why this stays>\`. An escape with no reason hides nothing.`,
+  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}({{rule}}): <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutRule: `Name the rule this escape keeps off: \`${ESCAPE_MARKER}({{rule}}): <reason>\`. An escape now keeps off only the rules it names.`,
   escaped: 'Escaped: {{reason}}',
 } as const
 
+/** A rule's name as a marker writes it: `no-raw-element` for `estiva/no-raw-element`. */
+export const shortRuleName = (id: string) => id.slice(id.lastIndexOf('/') + 1)
+
+/**
+ * What a marker says, read from a comment's text: the rules it names (none when
+ * it names none) and its reason. Null when the comment carries no marker.
+ */
+export function readMarker(text: string): { rules: string[]; reason: string } | null {
+  const at = text.indexOf(ESCAPE_MARKER)
+  if (at === -1) return null
+  const rest = text.slice(at + ESCAPE_MARKER.length)
+  const named = /^\s*\(([^)]*)\)/.exec(rest)
+  const rules = named ? named[1].split(/[\s,]+/).filter(Boolean).map(shortRuleName) : []
+  const reason = (named ? rest.slice(named[0].length) : rest).replace(/^\s*:/, '').trim()
+  return { rules, reason }
+}
+
 export interface EstivaSettings {
   /**
    * Report every sanctioned escape as a message with the id `escaped`, so a
@@ -85,24 +109,29 @@ export function isEscaped(context: Rule.RuleContext, node: Located): boolean {
     .find((c) => c.loc && c.range && c.loc.end.line === line - 1 && BETWEEN.test(sourceCode.text.slice(c.range[1], nodeStart)))
   if (!comment?.loc) return false
 
-  const at = comment.value.indexOf(ESCAPE_MARKER)
-  if (at === -1) return false
+  const marker = readMarker(comment.value)
+  if (!marker) return false
+  const rule = shortRuleName(context.id)
 
   const directive = DIRECTIVE.exec(comment.value)
   if (directive) {
     const rules = directiveRules(directive[1])
     // A directive for other rules (the token lint's notes) is not an escape of this one.
     if (rules.length > 0 && !rules.includes(context.id)) return false
-    context.report({ loc: comment.loc, messageId: 'escapeInDirective' })
+    context.report({ loc: comment.loc, messageId: 'escapeInDirective', data: { rule } })
+    return false
+  }
+
+  // Named, but not this rule: another rule on the element may be the one it keeps off.
+  if (marker.rules.length > 0 && !marker.rules.includes(rule)) return false
+  if (marker.rules.length === 0) {
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutRule', data: { rule } })
     return false
   }
 
-  const reason = comment.value
-    .slice(at + ESCAPE_MARKER.length)
-    .replace(/^:/, '')
-    .trim()
+  const { reason } = marker
   if (reason.replace(/\s/g, '').length < MIN_REASON) {
-    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason' })
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason', data: { rule } })
     return false
   }
 

package/src/eslint/has-a-page-and-a-story.test.ts

@@ -17,7 +17,7 @@ const tester = new RuleTester({
 /** Real files of this package, so the rules are tested against what they read. */
 const src = (name: string) => fileURLToPath(new URL(`../${name}`, import.meta.url))
 const code = 'export function Probe() {\n  return null\n}\n'
-const escaped = '// @estiva-escape: a probe file that documents itself in its own page\nexport function Probe() {\n  return null\n}\n'
+const escaped = '// @estiva-escape(component-has-a-page, component-has-a-story): a probe file that documents itself in its own page\nexport function Probe() {\n  return null\n}\n'
 
 describe('the files these rules read', () => {
   it('Button has a page and a story beside it, and FieldLine and MenuItem have both without a component file', () => {

package/src/eslint/index.test.ts

@@ -145,14 +145,14 @@ describe('an app lint with configs.recommended', () => {
   })
 
   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>'))
+    const [result] = await lint(component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button type="button">x</button>'))
     expect(result.messages).toEqual([])
   })
 })
 
 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>')
+    const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape(no-raw-element): a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
     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, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })
     expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })

package/src/eslint/no-copied-look.test.ts

@@ -65,7 +65,7 @@ tester.run('no-copied-look', noCopiedLook, {
     {
       name: 'an escape with its reason',
       filename: app,
-      code: probe(`<>\n      {/* @estiva-escape: recorded in GATES.md, a label strip Katerina left as it is */}\n      <span className="${SECTION_LABEL}">x</span>\n    </>`),
+      code: probe(`<>\n      {/* @estiva-escape(no-copied-look): recorded in GATES.md, a label strip Katerina left as it is */}\n      <span className="${SECTION_LABEL}">x</span>\n    </>`),
     },
   ],
   invalid: [

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

@@ -29,15 +29,15 @@ tester.run('no-hand-rolled-behaviour', noHandRolledBehaviour, {
     },
     {
       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",
+      code: "// @estiva-escape(no-hand-rolled-behaviour): 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',
+      code: 'export function probe(to: HTMLElement) {\n  // @estiva-escape(no-hand-rolled-behaviour): 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',
+      code: 'export function probe() {\n  // @estiva-escape(no-hand-rolled-behaviour): the frame measures the window, which no floating part owns\n  window.addEventListener("resize", () => {})\n}\n',
     },
   ],
   invalid: [

package/src/eslint/no-handmade-empty-state.test.ts

@@ -91,7 +91,7 @@ tester.run('no-handmade-empty-state', noHandmadeEmptyState, {
     { name: 'a box holding more than the line', code: jsx('<div>{rows.length === 0 ? <div className="px-3"><p>Nothing yet.</p><Button>Add one</Button></div> : rows.map((r) => <p key={r}>{r}</p>)}</div>') },
     {
       name: 'an escape with its reason',
-      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape: a printed report keeps its own empty line, set in the print style\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
+      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape(no-handmade-empty-state): a printed report keeps its own empty line, set in the print style\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
     },
 
     // the right scope
@@ -118,7 +118,7 @@ tester.run('no-handmade-empty-state', noHandmadeEmptyState, {
     },
     {
       name: 'an escape with no reason is not an escape',
-      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
+      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape(no-handmade-empty-state)\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, ...handmade],
     },
 

package/src/eslint/no-handmade-header.test.ts

@@ -33,7 +33,7 @@ tester.run('no-handmade-header', noHandmadeHeader, {
     { name: 'a column of rows', code: component('<div className="flex h-full flex-col">\n<div className="flex flex-col px-3"><span>{title}</span></div>\n<div />\n</div>') },
     {
       name: 'an escape with its reason',
-      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape: a print header that must not follow the theme */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
+      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape(no-handmade-header): a print header that must not follow the theme */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
     },
   ],
   invalid: [
@@ -82,7 +82,7 @@ tester.run('no-handmade-header', noHandmadeHeader, {
     },
     {
       name: 'an escape with no reason escapes nothing',
-      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape: */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
+      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape(no-handmade-header): */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'handmade' }],
     },
   ],

package/src/eslint/no-native-title.test.ts

@@ -40,7 +40,7 @@ tester.run('no-native-title', noNativeTitle, {
     { name: "the app's own component with a title of its own (Peek's NewTopicBanner)", filename: app, code: component('<NewTopicBanner title={name} />', "import { NewTopicBanner } from '@/components/Banner'\n") },
     { name: "a story's title is the Storybook's, an object key", code: "const meta = { title: 'Primitives/Tooltip', component: Tooltip }\nexport default meta\n" },
     { name: 'a prop of another name', code: component('<span aria-label={name} data-title={name}>{name}</span>') },
-    { name: 'an escape with its reason', code: component('<>\n{/* @estiva-escape: the print view has no pointer, and the address must survive a copy */}\n<span title={at}>{at}</span>\n</>') },
+    { name: 'an escape with its reason', code: component('<>\n{/* @estiva-escape(no-native-title): the print view has no pointer, and the address must survive a copy */}\n<span title={at}>{at}</span>\n</>') },
   ],
   invalid: [
     {
@@ -54,7 +54,7 @@ tester.run('no-native-title', noNativeTitle, {
     { name: "a part that hands it on to its element: the apps' status probe", code: component('<Button title="Delete">x</Button>', "import { Button } from '@estiva-app/ui'\n"), errors: native },
     { name: "through the app's re-export", filename: app, code: component('<IconButton title="Close" aria-label="Close">x</IconButton>', "import { IconButton } from '@/components/ui/IconButton'\n"), errors: native },
     { name: "through the app's wrapper that hands its props on", filename: app, code: component('<Button title="Delete">x</Button>', "import { Button } from '@/components/ui/Button'\n"), errors: native },
-    { name: 'an escape with no reason is not an escape', code: component('<>\n{/* @estiva-escape */}\n<span title={at}>{at}</span>\n</>'), errors: [{ messageId: 'escapeWithoutReason' }, ...native] },
+    { name: 'an escape with no reason is not an escape', code: component('<>\n{/* @estiva-escape(no-native-title) */}\n<span title={at}>{at}</span>\n</>'), errors: [{ messageId: 'escapeWithoutReason' }, ...native] },
   ],
 })
 

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

@@ -25,6 +25,10 @@ tester.run('no-raw-element', noRawElement, {
     { 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 />') },
+    // R5: a handler that only stops the click passes; a part may take one
+    { name: 'a wrapper that only stops the click', code: component('<div onClick={(e) => e.stopPropagation()} onPointerDown={(event) => { event.stopPropagation(); event.preventDefault() }}><Button>Save</Button></div>') },
+    { name: 'a press handler on a part', code: component('<Card onClick={open}>x</Card>') },
+    { name: 'a clickable element, escaped with its reason', code: component('    // @estiva-escape(no-raw-element): a surface that holds headings and lists, which a button cannot hold\n    <div onClick={edit}>x</div>') },
     {
       name: 'the elements that are not controls',
       code: component('    <section>\n      <h1>Title</h1>\n      <p>Text <strong>and</strong> <em>more</em></p>\n      <ul><li>One</li></ul>\n      <img src="x.png" alt="" />\n      <hr />\n      <kbd>Enter</kbd>\n      <svg><path d="M0 0" /></svg>\n      <time dateTime="2026-09-16">today</time>\n    </section>'),
@@ -37,31 +41,45 @@ tester.run('no-raw-element', noRawElement, {
     { name: 'controls written as false', code: component('<audio src="a.mp3" controls={false} />') },
     {
       name: 'a line comment escape directly above',
-      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'),
+      code: component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button type="button">x</button>'),
+    },
+    {
+      name: 'a marker naming two rules keeps off each of them, written with or without the plugin name',
+      code: component('    // @estiva-escape(no-rebuilt-behaviour, estiva/no-raw-element): 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>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): 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>'),
+      code: component('    <div>\n      {/*\n        @estiva-escape(no-raw-element): 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>'),
+      code: component('    // @estiva-escape(no-raw-element): 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>'),
+      code: component('    // @estiva-escape(no-raw-element): ab cd ef gh ij\n    <button>x</button>'),
     },
     {
       name: 'an element with no part, escaped',
-      code: component('    // @estiva-escape: a map from another service, until the package has a frame\n    <iframe src="https://example.com" title="Map" />'),
+      code: component('    // @estiva-escape(no-raw-element): a map from another service, until the package has a frame\n    <iframe src="https://example.com" title="Map" />'),
     },
   ],
   invalid: [
     { name: 'a raw button', code: component('    <button type="button">x</button>'), errors: [{ messageId: 'raw', line: 3 }] },
+    {
+      name: 'a clickable div names Button and Card with href (R5)',
+      code: component('    <div onClick={open}>x</div>'),
+      errors: [{ message: 'A clickable <div onClick> is a button made by hand: it takes no focus and answers no key. Use `Button` from @estiva-app/ui; for a whole card that opens something, `Card` with `href`. A handler that only stops the click (`e.stopPropagation()`) is fine.' }],
+    },
+    {
+      name: 'a press that does more than stop the click, on any plain element',
+      code: component('    <li onMouseDown={(e) => { e.preventDefault(); onSearch() }}>\n      <span onPointerDown={handle} />\n    </li>'),
+      errors: [{ messageId: 'clickable', data: { element: '<li onMouseDown>' } }, { messageId: 'clickable', data: { element: '<span onPointerDown>' } }],
+    },
     {
       name: 'an opening tag that spans lines (what grep misses)',
       code: component('    <input\n      type="text"\n      value={x}\n    />'),
@@ -106,7 +124,7 @@ tester.run('no-raw-element', noRawElement, {
 
     {
       name: 'an escape with no reason is an error, and hides nothing',
-      code: component('    // @estiva-escape:\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element):\n    <button>x</button>'),
       errors: [
         { messageId: 'escapeWithoutReason', line: 3 },
         { messageId: 'raw', line: 4 },
@@ -114,22 +132,36 @@ tester.run('no-raw-element', noRawElement, {
     },
     {
       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>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): 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>'),
+      code: component('    // @estiva-escape(no-raw-element)\n    <button>x</button>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
     },
+    // B3 (Katerina, 25 September): a marker keeps off only the rules it names.
+    {
+      name: 'a marker that names no rule escapes nothing, and says which name to write',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [
+        { line: 3, message: 'Name the rule this escape keeps off: `@estiva-escape(no-raw-element): <reason>`. An escape now keeps off only the rules it names.' },
+        { messageId: 'raw', line: 4 },
+      ],
+    },
+    {
+      name: 'a marker that names another rule does not keep this one off',
+      code: component('    // @estiva-escape(no-rebuilt-behaviour): a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 4 }],
+    },
     {
       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>'),
+      code: component('    // @estiva-escape(no-raw-element): 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>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): a preview drawn from its own palette */}\n      <span />\n      <button>x</button>\n    </div>'),
       errors: [{ messageId: 'raw', line: 6 }],
     },
     {
@@ -139,23 +171,23 @@ tester.run('no-raw-element', noRawElement, {
     },
     {
       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>'),
+      code: component('    // eslint-disable-next-line -- @estiva-escape(no-raw-element): 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-element -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      code: component('    // eslint-disable-next-line rule-to-test/no-raw-element -- @estiva-escape(no-raw-element): 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>'),
+      code: component('    // eslint-disable-next-line no-console -- @estiva-escape(no-raw-element): 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>'),
+      code: component('    // @estiva-escape(no-raw-element): 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-element.ts

@@ -111,7 +111,43 @@ function isOn(element: JSXOpeningElement, name: string): boolean {
   return attr !== undefined && literal(attr) !== false
 }
 
-type Found = { report: 'raw'; element: string; part: RawElementPart } | { report: 'noPart'; element: string } | null
+type Found = { report: 'raw'; element: string; part: RawElementPart } | { report: 'noPart'; element: string } | { report: 'clickable'; element: string } | null
+
+/** The pointer's press, as a handler on a plain element makes it a control (R5). */
+const CLICK_HANDLERS = ['onClick', 'onMouseDown', 'onMouseUp', 'onPointerDown', 'onPointerUp', 'onDoubleClick']
+
+interface Expression {
+  type: string
+  [key: string]: unknown
+}
+
+/** `e.stopPropagation()` or `e.preventDefault()`: a handler that only keeps the click from what is behind. */
+function onlyStops(handler: Expression | undefined): boolean {
+  if (!handler || (handler.type !== 'ArrowFunctionExpression' && handler.type !== 'FunctionExpression')) return false
+  const body = handler.body as Expression
+  const calls = body.type === 'BlockStatement' ? (body.body as Expression[]).map((s) => (s.type === 'ExpressionStatement' ? (s.expression as Expression) : s)) : [body]
+  return (
+    calls.length > 0 &&
+    calls.every((call) => {
+      if (call.type !== 'CallExpression') return false
+      const callee = call.callee as Expression
+      const property = callee.type === 'MemberExpression' ? (callee.property as Expression) : undefined
+      return property?.type === 'Identifier' && (property.name === 'stopPropagation' || property.name === 'preventDefault')
+    })
+  )
+}
+
+/** A plain element made clickable by hand: the first press handler that does more than stop the click. */
+function clickHandler(element: JSXOpeningElement): string | undefined {
+  for (const name of CLICK_HANDLERS) {
+    const attr = attribute(element, name)
+    if (!attr) continue
+    const value = attr.value
+    const handler = value?.type === 'JSXExpressionContainer' ? (value.expression as Expression | undefined) : undefined
+    if (!onlyStops(handler)) return name
+  }
+  return undefined
+}
 
 /** What this element is to the rule: a raw element with a part, one with none yet, or none of its business. */
 export function classify(element: JSXOpeningElement): Found {
@@ -131,7 +167,14 @@ export function classify(element: JSXOpeningElement): Found {
     return part ? { report: 'raw', element: shown, part } : { report: 'noPart', element: shown }
   }
 
-  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) return null
+  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) {
+    // A plain element with a press handler is a button drawn by hand (Katerina's ruling R5,
+    // 25 September): no focus, no keys, no look anybody keeps in step. `<option>` and
+    // `<summary>` live inside a control the rule already reads.
+    if (!/^[a-z][a-z0-9]*$/.test(name) || name === 'option' || name === 'summary') return null
+    const handler = clickHandler(element)
+    return handler ? { report: 'clickable', element: `<${name} ${handler}>` } : null
+  }
   if ((name === 'audio' || name === 'video') && !isOn(element, 'controls')) return null
   if (name === 'img' && !attribute(element, 'usemap') && !attribute(element, 'useMap')) return null
 
@@ -150,6 +193,10 @@ export function classify(element: JSXOpeningElement): Found {
  * that says so: the part is made in the package, not by hand in an app
  * (Katerina, 16 September).
  *
+ * A plain element with a press handler (`<div onClick>`) is a control too, and
+ * is refused naming `Button` (R5, 25 September); a handler that only stops the
+ * click reaching what is behind passes.
+ *
  * Only a JSX element written with a lowercase name. `<Button>`,
  * `<Foo.button>` and `createElement('button')` are not this rule's business.
  */
@@ -160,6 +207,8 @@ export const noRawElement: Rule.RuleModule = {
     schema: [],
     messages: {
       raw: 'Use `{{use}}` from @estiva-app/ui instead of a raw {{element}}.{{more}}',
+      clickable:
+        'A clickable {{element}} is a button made by hand: it takes no focus and answers no key. Use `Button` from @estiva-app/ui; for a whole card that opens something, `Card` with `href`. A handler that only stops the click (`e.stopPropagation()`) is fine.',
       noPart: '@estiva-app/ui has no part for a raw {{element}} yet. Do not build one here: ask Katerina, and it gets made in @estiva-app/ui.',
       ...ESCAPE_MESSAGES,
     },
@@ -172,7 +221,8 @@ export const noRawElement: Rule.RuleModule = {
         const found = classify(element)
         if (!found) return
         if (isEscaped(context, element)) return
-        if (found.report === 'noPart') context.report({ loc: element.loc, messageId: 'noPart', data: { element: found.element } })
+        if (found.report === 'clickable') context.report({ loc: element.loc, messageId: 'clickable', data: { element: found.element } })
+        else if (found.report === 'noPart') context.report({ loc: element.loc, messageId: 'noPart', data: { element: found.element } })
         else context.report({ loc: element.loc, messageId: 'raw', data: { element: found.element, use: found.part.use, more: found.part.more ?? '' } })
       },
     }