@estiva-app/ui 0.30.0 → 0.32.0

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

@@ -0,0 +1,344 @@
+import { statSync } from 'node:fs'
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+import {
+  bindingOfTag,
+  classesOf,
+  functionComponents,
+  parseFile,
+  partsOfFile,
+  resolveModule,
+  walk,
+  type Node,
+  type Parser,
+  type PartBinding,
+} from './no-restyled-part'
+
+type Locals = Map<string, PartBinding | 'namespace'>
+
+const child = (node: Node, key: string) => node[key] as Node | null | undefined
+const children = (node: Node, key: string) => ((node[key] as (Node | null)[] | undefined) ?? []).filter((n): n is Node => !!n)
+const nameOf = (node: Node | null | undefined): string | undefined =>
+  node?.type === 'Identifier' || node?.type === 'JSXIdentifier' ? (node.name as string) : undefined
+const tagName = (element: Node) => nameOf(child(child(element, 'openingElement') as Node, 'name'))
+/**
+ * Whether a name is the part itself: imported, re-exported, or an app wrapper
+ * that hands everything on (Peek's `EmptyState`). A component that only hands
+ * its `className` to one (Ship's `Activity`) is the app's own, and is followed.
+ */
+const isPart = (binding: PartBinding | undefined, part: string) => binding?.part === part && binding.props === 'all'
+const attributeOf = (opening: Node, name: string) => children(opening, 'attributes').find((a) => a.type === 'JSXAttribute' && nameOf(child(a, 'name')) === name)
+
+// ---------------------------------------------------------------- shape 1: a line drawn by hand
+
+/**
+ * An empty state is a line, not a paragraph of prose. The words are not read:
+ * UIG-1's pass on words alone fired on a hint and a status note, and words
+ * missed four of Peek's dialogs ("There is nowhere else to move it…", "Every
+ * topic is already in your Open work."). Where the line sits decides.
+ */
+const SHORT = 120
+
+/**
+ * The element's words, when words are all it holds: text, a string, a name
+ * dropped into a sentence ("There is nowhere else in {teamName} to put it.").
+ * A line with no words of its own — a count, a message's body — is not one.
+ */
+function onlyWords(element: Node): string | undefined {
+  let line = ''
+  let own = ''
+  for (const kid of children(element, 'children')) {
+    let piece: string
+    if (kid.type === 'JSXText') piece = String(kid.value)
+    else if (kid.type === 'JSXExpressionContainer') {
+      const e = child(kid, 'expression') as Node
+      if (e.type === 'JSXEmptyExpression') continue
+      if (e.type === 'Literal' && typeof e.value === 'string') piece = e.value
+      else if (e.type === 'TemplateLiteral' && children(e, 'expressions').length === 0) piece = children(e, 'quasis').map((q) => (q.value as { cooked: string }).cooked).join('')
+      else if (e.type === 'Identifier' || e.type === 'MemberExpression') {
+        line += 'x'
+        continue
+      } else return undefined
+    } else return undefined
+    own += piece
+    line += piece
+  }
+  if (!/[a-z]{2,}/i.test(own)) return undefined
+  return line.replace(/\s+/g, ' ').trim()
+}
+
+const isCount = (node: Node | null | undefined): boolean => {
+  if (node?.type === 'ChainExpression') return isCount(child(node, 'expression'))
+  return node?.type === 'MemberExpression' && !node.computed && /^(?:length|size)$/.test(nameOf(child(node, 'property')) ?? '')
+}
+const isNumber = (node: Node | null | undefined, n: number) => node?.type === 'Literal' && node.value === n
+
+/**
+ * What a condition says about a list: `empty` when it is true for an empty one
+ * (`rows.length === 0`, `!rows.length`, `isEmpty(rows)`), `full` when it is
+ * true for a list with rows (`rows.length > 0`, `rows.length`), nothing when it
+ * does not ask. `a && b` says what either side says.
+ */
+function whenTrue(test: Node | null | undefined): 'empty' | 'full' | undefined {
+  if (!test) return undefined
+  if (isCount(test)) return 'full'
+  switch (test.type) {
+    case 'UnaryExpression': {
+      if (test.operator !== '!') return undefined
+      const inner = whenTrue(child(test, 'argument'))
+      return inner === 'empty' ? 'full' : inner === 'full' ? 'empty' : undefined
+    }
+    case 'LogicalExpression':
+      if (test.operator !== '&&') return undefined
+      return whenTrue(child(test, 'left')) ?? whenTrue(child(test, 'right'))
+    case 'BinaryExpression': {
+      let [count, other, op] = [child(test, 'left'), child(test, 'right'), String(test.operator)]
+      if (!isCount(count)) [count, other, op] = [other, count, ({ '<': '>', '>': '<', '<=': '>=', '>=': '<=' } as Record<string, string>)[op] ?? op]
+      if (!isCount(count)) return undefined
+      if (isNumber(other, 0)) return op === '===' || op === '==' || op === '<=' ? 'empty' : op === '>' || op === '!==' || op === '!=' ? 'full' : undefined
+      if (isNumber(other, 1)) return op === '<' ? 'empty' : op === '>=' ? 'full' : undefined
+      return undefined
+    }
+    case 'CallExpression': {
+      const callee = child(test, 'callee')
+      const name = callee?.type === 'MemberExpression' ? nameOf(child(callee, 'property')) : nameOf(callee)
+      return name && /^is(?:Empty|Blank)$/.test(name) ? 'empty' : undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+const isMapCall = (node: Node | null | undefined) => {
+  const callee = node?.type === 'CallExpression' ? child(node, 'callee') : undefined
+  return callee?.type === 'MemberExpression' && nameOf(child(callee, 'property')) === 'map'
+}
+
+/**
+ * Whether a branch **is** a list: a `.map(…)`, or a box that holds only that —
+ * `<ul>{rows.map(…)}</ul>`. A branch that shows something else and lists a few
+ * things inside it (an answer with its sources) is not the list the line stands
+ * in for.
+ */
+function isAList(branch: Node | null | undefined, depth = 0): boolean {
+  if (!branch || depth > 2) return false
+  if (isMapCall(branch)) return true
+  if (branch.type !== 'JSXElement' && branch.type !== 'JSXFragment') return false
+  if (branch.type === 'JSXElement' && !/^[a-z]/.test(tagName(branch) ?? '')) return false
+  const kids = children(branch, 'children').filter((k) => !(k.type === 'JSXText' && !String(k.value).trim()) && !(k.type === 'JSXExpressionContainer' && (child(k, 'expression') as Node).type === 'JSXEmptyExpression'))
+  return kids.length === 1 && (kids[0].type === 'JSXExpressionContainer' ? isMapCall(child(kids[0], 'expression')) : isAList(kids[0], depth + 1))
+}
+
+/** A box around one thing and nothing else: a wrapper that pads or places the line. */
+function soleChildOf(parent: Node | undefined, element: Node): boolean {
+  if (parent?.type !== 'JSXElement' || !/^[a-z]/.test(tagName(parent) ?? '')) return false
+  const kids = children(parent, 'children').filter((k) => !(k.type === 'JSXText' && !String(k.value).trim()) && !(k.type === 'JSXExpressionContainer' && (child(k, 'expression') as Node).type === 'JSXEmptyExpression'))
+  return kids.length === 1 && kids[0] === element
+}
+
+/**
+ * Whether the element stands where a list's rows would be: one side of a
+ * condition whose other side maps a list, or under a condition that asks if
+ * something is empty — `cond && …`, `cond ? … : …`, `if (cond) return …`.
+ */
+function standsInForAList(element: Node): boolean {
+  let at = element
+  for (let depth = 0; depth < 3 && soleChildOf(at.parent, at); depth += 1) at = at.parent as Node
+  const parent = at.parent
+  if (!parent) return false
+  if (parent.type === 'ConditionalExpression' && parent.test !== at) {
+    const consequent = parent.consequent === at
+    const other = child(parent, consequent ? 'alternate' : 'consequent')
+    return whenTrue(child(parent, 'test')) === (consequent ? 'empty' : 'full') || isAList(other)
+  }
+  if (parent.type === 'LogicalExpression' && parent.operator === '&&' && parent.right === at) return whenTrue(child(parent, 'left')) === 'empty'
+  if (parent.type === 'ReturnStatement') {
+    let holder = parent.parent
+    if (holder?.type === 'BlockStatement' && children(holder, 'body').length === 1) holder = holder.parent
+    return holder?.type === 'IfStatement' && child(holder, 'consequent') !== undefined && whenTrue(child(holder, 'test')) === 'empty'
+  }
+  return false
+}
+
+// ---------------------------------------------------------------- shape 2: the right part at the wrong scope
+
+/** A content box that fills its viewport: `min-h-full` or `h-full` on `contentClassName`. */
+const FILLS = /^(?:min-h-full|h-full)$/
+
+function isPageScope(opening: Node): boolean {
+  const scope = attributeOf(opening, 'scope')
+  if (!scope) return true
+  const value = child(scope, 'value')
+  return value?.type === 'Literal' && value.value === 'page'
+}
+
+interface FileFacts {
+  file: string
+  locals: Locals
+  components: Map<string, Node>
+  /** A local name imported from the app's own files: where from, and under what name. */
+  imports: Map<string, { file: string; name: string }>
+}
+
+const factsCache = new Map<string, { mtime: number; facts: FileFacts | null }>()
+
+function factsOf(file: string, program: Node, parser: Parser): FileFacts {
+  const imports = new Map<string, { file: string; name: string }>()
+  for (const statement of children(program, 'body')) {
+    if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type') continue
+    const target = resolveModule(file, String((child(statement, 'source') as Node).value))
+    if (!target) continue
+    for (const specifier of children(statement, 'specifiers')) {
+      if (specifier.type !== 'ImportSpecifier' || specifier.importKind === 'type') continue
+      const local = nameOf(child(specifier, 'local'))
+      const imported = nameOf(child(specifier, 'imported'))
+      if (local && imported) imports.set(local, { file: target, name: imported })
+    }
+  }
+  return { file, locals: partsOfFile(file, program, parser), components: functionComponents(program), imports }
+}
+
+function factsOfFile(file: string, parser: Parser): FileFacts | null {
+  const mtime = statSync(file).mtimeMs
+  const cached = factsCache.get(file)
+  if (cached && cached.mtime === mtime) return cached.facts
+  factsCache.set(file, { mtime, facts: null })
+  const program = parseFile(parser, file)
+  const facts = program ? factsOf(file, program, parser) : null
+  factsCache.set(file, { mtime, facts })
+  return facts
+}
+
+interface PageState {
+  file: string
+  line: number
+}
+
+/**
+ * Every page-scope `EmptyState` a component can draw, following the app's own
+ * components it draws in turn, in its file and in the files it imports from,
+ * four deep.
+ */
+function pageStatesOf(facts: FileFacts, name: string, parser: Parser, depth: number, seen: Set<string>): PageState[] {
+  const key = `${facts.file}#${name}`
+  if (depth > 4 || seen.has(key)) return []
+  seen.add(key)
+  const local = facts.components.get(name)
+  if (!local) {
+    const from = facts.imports.get(name)
+    const there = from ? factsOfFile(from.file, parser) : null
+    return there && from ? pageStatesOf(there, from.name, parser, depth + 1, seen) : []
+  }
+  const found: PageState[] = []
+  walk(local, (node) => {
+    if (node.type !== 'JSXOpeningElement') return
+    const tag = child(node, 'name')
+    const binding = bindingOfTag(tag, facts.locals)
+    if (isPart(binding, 'EmptyState')) {
+      if (isPageScope(node)) found.push({ file: facts.file, line: node.loc?.start.line ?? 0 })
+      return
+    }
+    const component = binding?.props === 'all' ? undefined : nameOf(tag)
+    if (component && /^[A-Z]/.test(component)) found.push(...pageStatesOf(facts, component, parser, depth + 1, seen))
+  })
+  return found
+}
+
+const fileName = (file: string) => file.replace(/\\/g, '/').split('/').pop()
+
+/**
+ * UIG-23: an empty state drawn by hand, or the right part at the wrong scope.
+ *
+ * **A line drawn by hand.** A plain box whose only content is a short line
+ * saying there is nothing ("No tickets yet.") where a list's rows would be: one
+ * side of a condition whose other side maps the list, or under a condition that
+ * asks if something is empty. Both halves are needed. The words alone fire on a
+ * hint and a status note (UIG-1 measured it); the place alone fires on any
+ * line a list shows beside itself.
+ *
+ * **The wrong scope.** A `page`-scope `EmptyState` centres in the room a flex
+ * column gives it. Inside a `ScrollArea` the content box is only as tall as
+ * what is in it, so the state sits at the top of its pane. The rule looks at
+ * the `ScrollArea`'s content and at every component of the app's own placed in
+ * it, following them into their files, because that is how four of them
+ * arrived on Folders in one merge (peek `7f22e5e`): the state was drawn in one
+ * file and scrolled in another. A `contentClassName` with `min-h-full` or
+ * `h-full` gives the state its room, and passes.
+ *
+ * Not judged: the package's `EmptyState` and a part's own lines (a
+ * `FieldLine`, a palette's empty row) — a part is already a part.
+ */
+export const noHandmadeEmptyState: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'An empty state drawn by hand, or a page-scope EmptyState that cannot centre' },
+    schema: [],
+    messages: {
+      handmade:
+        'A line saying there is nothing is an EmptyState. Use `EmptyState` from @estiva-app/ui: `scope="section"` inside a section, `scope="page"` for a whole page.',
+      wrongScope:
+        'A page-scope EmptyState inside a ScrollArea sits at the top of its pane, not the middle: the ScrollArea\'s content is only as tall as what is in it. Use `scope="section"` when the pane has anything else on it; when the whole pane is empty, draw the page EmptyState in place of the ScrollArea, not inside it.',
+      wrongScopeVia:
+        '`{{component}}` draws a page-scope EmptyState ({{where}}) inside this ScrollArea, where it sits at the top of its pane, not the middle: the ScrollArea\'s content is only as tall as what is in it. Use `scope="section"` there when the pane has anything else on it; when the whole pane is empty, draw the page EmptyState in place of the ScrollArea, not inside it.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    const parser = (context.languageOptions?.parser ?? {}) as Parser
+    const file = context.filename
+    let facts: FileFacts | undefined
+    // A ScrollArea inside another is walked by both; each state is reported once.
+    const reported = new Set<Node>()
+    const scopeOf = (node: Node) => context.sourceCode.getScope(node as unknown as Parameters<typeof context.sourceCode.getScope>[0])
+
+    return {
+      Program(program) {
+        facts = factsOf(file, program as unknown as Node, parser)
+      },
+      JSXElement(ruleNode: Rule.Node) {
+        const element = ruleNode as unknown as Node
+        const opening = child(element, 'openingElement') as Node
+        const tag = tagName(element)
+
+        // Shape 1: a plain box holding only a "nothing" line, where a list would be.
+        if (tag && /^[a-z]/.test(tag)) {
+          const words = onlyWords(element)
+          if (!words || words.length > SHORT) return
+          if (!standsInForAList(element)) return
+          if (isEscaped(context, opening)) return
+          context.report({ loc: opening.loc as NonNullable<Rule.Node['loc']>, messageId: 'handmade' })
+          return
+        }
+
+        // Shape 2: a page-scope EmptyState in a ScrollArea that does not fill.
+        if (!facts || !isPart(bindingOfTag(child(opening, 'name'), facts.locals), 'ScrollArea')) return
+        const content = attributeOf(opening, 'contentClassName')
+        if (content && classesOf(child(content, 'value'), scopeOf).some((c) => FILLS.test(c.replace(/^(?:[^:\s[\]]+:)+/, '')))) return
+        const here = facts
+        for (const kid of children(element, 'children')) {
+          walk(kid, (node) => {
+            if (node.type !== 'JSXOpeningElement') return
+            const name = child(node, 'name')
+            const binding = bindingOfTag(name, here.locals)
+            if (isPart(binding, 'EmptyState')) {
+              if (!isPageScope(node) || reported.has(node) || isEscaped(context, node)) return
+              reported.add(node)
+              context.report({ loc: node.loc as NonNullable<Rule.Node['loc']>, messageId: 'wrongScope' })
+              return
+            }
+            const component = binding?.props === 'all' ? undefined : nameOf(name)
+            if (!component || !/^[A-Z]/.test(component)) return
+            const states = pageStatesOf(here, component, parser, 0, new Set())
+            if (!states.length || reported.has(node) || isEscaped(context, node)) return
+            reported.add(node)
+            // In reading order: file, then line.
+            for (const state of [...states].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)) {
+              const where = state.file === file ? `line ${state.line}` : `${fileName(state.file)}:${state.line}`
+              context.report({ loc: node.loc as NonNullable<Rule.Node['loc']>, messageId: 'wrongScopeVia', data: { component, where } })
+            }
+          })
+        }
+      },
+    }
+  },
+}

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

@@ -0,0 +1,89 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { noHandmadeHeader } from './no-handmade-header'
+
+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({ title, open }: { title: string; open: boolean }) {\n  return (\n${body}\n  )\n}\n`
+const handmade = [{ messageId: 'handmade' }]
+
+tester.run('no-handmade-header', noHandmadeHeader, {
+  valid: [
+    { name: 'the part itself', code: component('<div className="flex h-full flex-col">\n<ContainerHeader title="Files" />\n<div />\n</div>') },
+    {
+      name: "a group heading inside a list: SectionHeader's row, not a column's bar (Ship's issue groups)",
+      code: component('<section className="flex flex-col gap-px">\n<h3 className="flex h-8 items-center gap-2 px-3"><StatusLabel value="todo" /><span>{3}</span></h3>\n<div />\n</section>'),
+    },
+    {
+      name: "a label strip on a card (Peek's huddle card)",
+      code: component('<Card className="flex flex-col h-[130px]">\n<div className="h-6 bg-bg-inset px-2 flex items-center shrink-0"><span className="text-caption">Huddle</span></div>\n<div />\n</Card>'),
+    },
+    { name: 'a row a person presses is a row, not a header', code: component('<div className="flex h-full flex-col">\n<div className="flex items-center px-3 py-2" onClick={() => {}}><span>{title}</span></div>\n<div />\n</div>') },
+    { name: 'a row with no title: a toolbar, a field', code: component('<div className="flex h-full flex-col">\n<div className="flex items-center gap-1 px-3"><Button>One</Button><Button>Two</Button></div>\n<div />\n</div>') },
+    { name: 'a row with nothing after it heads nothing', code: component('<div className="flex h-full flex-col">\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n</div>') },
+    { name: 'a row with no side padding of its own', code: component('<div className="flex h-full flex-col">\n<div className="flex items-center py-2"><span>{title}</span></div>\n<div />\n</div>') },
+    { 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>'),
+    },
+  ],
+  invalid: [
+    {
+      // The Folders page's right pane, at the commit before 3dc663b.
+      name: 'a pane that heads itself around an editable name',
+      code: component('<div className="flex h-full flex-col">\n{/* ContainerHeader draws a static title, so this pane heads itself. */}\n<div className="flex items-center gap-2 px-3 py-2">\n<div className="min-w-0 flex-1"><EditableText value={title} label="Folder name" /></div>\n<IconButton icon={<IconX />} label="Close" />\n</div>\n<div className="min-h-0 flex-1" />\n</div>'),
+      errors: handmade,
+    },
+    {
+      // The Folders page's thread pane, at the commit before 3dc663b.
+      name: 'a pane that heads itself with a title and a caption',
+      code: component('<div className="flex h-full flex-col">\n<div className="flex items-center gap-2 px-3 py-2">\n<div className="min-w-0 flex-1">\n<p className="truncate text-body-2-strong text-text-primary">{title ?? "Conversation"}</p>\n{open && <p className="truncate text-caption text-text-muted">In Ship</p>}\n</div>\n</div>\n<div />\n</div>'),
+      errors: handmade,
+    },
+    {
+      name: "ContainerHeader's exact class list, typed by hand (Peek's FilesPanel and ThreadPanel)",
+      code: component('<div className="flex flex-col h-full">\n<div className="h-12 shrink-0 flex items-center justify-between pl-5 pr-4 py-2 border-b border-border-subtle">\n<span className="text-body-2-strong text-text-primary">Files</span>\n</div>\n<div />\n</div>'),
+      errors: handmade,
+    },
+    {
+      name: 'the shape, not the class names: other padding, other gap, a heading, a column that grows',
+      code: component('<aside className="flex grow flex-col">\n<header className="flex items-baseline gap-4 pl-6 pr-2 py-3"><h2>{title}</h2></header>\n<ul />\n</aside>'),
+      errors: handmade,
+    },
+    {
+      name: "a header bar's height and hairline, whatever the column is",
+      code: component('<section className="flex flex-col">\n<div className="flex h-11 items-center border-b px-4"><span>{title}</span></div>\n<div />\n</section>'),
+      errors: handmade,
+    },
+    {
+      name: 'a bar shown only while something is open',
+      code: component('<div className="flex h-full flex-col">\n{open && (\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n)}\n<div />\n</div>'),
+      errors: handmade,
+    },
+    {
+      name: 'classes put together with cn() and a variant',
+      code: component('<div className={cn("flex flex-col", "h-full")}>\n<div className={cn("flex items-center", "md:px-4 py-2")}><span>{title}</span></div>\n<div />\n</div>'),
+      errors: handmade,
+    },
+    {
+      // DialogShell's bar, before it drew ContainerHeader: a part's title, named as one.
+      name: "a bar whose title is a part's Title",
+      code: component('<div className="flex flex-col">\n<div className="h-12 flex items-center justify-between pl-5 pr-4 border-b shrink-0">\n{open ?? <Parts.Title render={<span />}>{title}</Parts.Title>}\n</div>\n<div />\n</div>'),
+      errors: handmade,
+    },
+    {
+      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>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'handmade' }],
+    },
+  ],
+})

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

@@ -0,0 +1,153 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+/** The JSX an element is made of, as far as this rule reads it. */
+interface Node {
+  type: string
+  [key: string]: unknown
+}
+
+interface JSXElement extends Node {
+  type: 'JSXElement'
+  openingElement: {
+    name: { type: string; name?: string; object?: { name?: string }; property?: { name?: string } }
+    attributes: { type: string; name?: { name?: string }; value?: Node | null }[]
+    loc: NonNullable<Rule.Node['loc']>
+    range: [number, number]
+  }
+  children: Node[]
+}
+
+const isElement = (n: unknown): n is JSXElement => typeof n === 'object' && n !== null && (n as Node).type === 'JSXElement'
+
+function tagOf(el: JSXElement): string {
+  const n = el.openingElement.name
+  if (n.type === 'JSXIdentifier') return n.name ?? ''
+  if (n.type === 'JSXMemberExpression') return `${n.object?.name ?? ''}.${n.property?.name ?? ''}`
+  return ''
+}
+
+function attribute(el: JSXElement, name: string) {
+  return el.openingElement.attributes.find((a) => a.type === 'JSXAttribute' && a.name?.name === name)
+}
+
+/** Every string literal under a node: a `cn()` call, a template, a ternary. */
+function strings(node: Node | null | undefined, out: string[] = []): string[] {
+  if (!node || typeof node !== 'object') return out
+  if (node.type === 'Literal' && typeof node.value === 'string') out.push(node.value)
+  else if (node.type === 'TemplateLiteral') for (const q of node.quasis as { value: { cooked: string | null } }[]) out.push(q.value.cooked ?? '')
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent' || key === 'loc' || key === 'range') continue
+    if (Array.isArray(value)) for (const v of value) strings(v as Node, out)
+    else if (value && typeof value === 'object' && (value as Node).type) strings(value as Node, out)
+  }
+  return out
+}
+
+/** The classes an element is given, variants taken off: `md:px-3` is `px-3`. */
+function classesOf(el: JSXElement): string[] {
+  const value = attribute(el, 'className')?.value
+  if (!value) return []
+  const text = value.type === 'Literal' ? String(value.value) : strings(value.expression as Node).join(' ')
+  return text
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((c) => c.replace(/^(?:[^:\s[\]]+:)+/, ''))
+}
+
+/**
+ * An element's children as a reader sees them: whitespace and comments gone,
+ * `{open && <X />}` read as `<X />`.
+ */
+function meaningful(el: JSXElement): Node[] {
+  const out: Node[] = []
+  for (const child of el.children) {
+    if (child.type === 'JSXText') {
+      if (String(child.value).trim()) out.push(child)
+    } else if (child.type === 'JSXExpressionContainer') {
+      const e = child.expression as Node
+      if (e.type === 'JSXEmptyExpression') continue
+      if (e.type === 'LogicalExpression' && isElement(e.right)) out.push(e.right as Node)
+      else if (isElement(e)) out.push(e)
+      else out.push(child)
+    } else if (child.type === 'JSXElement' || child.type === 'JSXFragment') out.push(child)
+  }
+  return out
+}
+
+/** Parts that draw a line of text: a title made of one is still a title. */
+const TEXT_PARTS = new Set(['EditableText', 'Person', 'Breadcrumb', 'Link', 'SectionLabel', 'InlineChip'])
+/** What a title written as an expression looks like: a name, a field, a template, a fallback. */
+const VALUE_EXPRESSIONS = new Set(['Identifier', 'MemberExpression', 'TemplateLiteral', 'Literal', 'LogicalExpression', 'ConditionalExpression', 'ChainExpression', 'CallExpression'])
+
+/** Whether the row carries a title: text, a value, a heading, or a part that draws text, three boxes deep at most. */
+function carriesTitle(el: JSXElement, depth = 0): boolean {
+  if (depth > 3) return false
+  for (const child of meaningful(el)) {
+    if (child.type === 'JSXText') return true
+    if (child.type === 'JSXExpressionContainer') {
+      if (VALUE_EXPRESSIONS.has((child.expression as Node).type)) return true
+      continue
+    }
+    if (!isElement(child)) continue
+    const tag = tagOf(child)
+    // `Dialog.Title`, `Parts.Title`: a part's title, named as one.
+    if (/^h[1-6]$/.test(tag) || TEXT_PARTS.has(tag) || /\.(?:Title|Heading)$/.test(tag)) return true
+    // A part's own words are its label, a Button's "Save": only plain boxes are looked into.
+    if (/^[a-z]/.test(tag) && carriesTitle(child, depth + 1)) return true
+  }
+  return false
+}
+
+const ROW = (c: string[]) => c.includes('flex') && !c.includes('flex-col')
+const OWN_SIDE_PADDING = (c: string[]) => c.some((x) => /^-?(?:p|px|pl|pr|ps|pe)-/.test(x))
+/** A column that takes the height it is given: the pane a header bar tops. */
+const FILLS = (c: string[]) => c.includes('flex-col') && c.some((x) => /^(?:h-full|h-screen|flex-1|grow|min-h-0|h-dvh)$/.test(x))
+/** A header bar's own geometry: a column bar's height, or the hairline under it. */
+const BAR = (c: string[]) => c.some((x) => /^(?:h|min-h)-(?:10|11|12|13|14|\[(?:4[0-9]|5[0-6])px\])$/.test(x)) || c.some((x) => /^border-b(?:-|$)/.test(x))
+/** A row a person presses is a row of its own kind, not a header. */
+const INTERACTIVE = ['onClick', 'href', 'role', 'onKeyDown', 'onPointerDown']
+
+/**
+ * UIG-22: a column's header bar built by hand.
+ *
+ * The general rules cannot see this one: a hand-made header is made entirely of
+ * legal parts, a box, some text, some padding. So this rule reads the shape.
+ * A row, first in a column, with side padding of its own and a title in it,
+ * where the column fills the height it is given, or the row has a header bar's
+ * height or the hairline under one. `ContainerHeader` is that bar: 48px, the
+ * title, the column's buttons at the right edge, a hairline under it.
+ *
+ * What it leaves alone, on purpose: a group heading inside a list (the row one
+ * section starts with), a label strip on a card, and a row a person presses.
+ * Only a lowercase element is judged: a part is already a part.
+ */
+export const noHandmadeHeader: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: "A column's header bar drawn by hand where ContainerHeader is the part" },
+    schema: [],
+    messages: {
+      handmade:
+        "A column's header bar drawn by hand. Use `ContainerHeader` from @estiva-app/ui: 48px, the title, the column's buttons at the right edge (`actions`), a hairline under it.",
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      JSXElement(node: Rule.Node) {
+        const column = node as unknown as JSXElement
+        const kids = meaningful(column)
+        const first = kids[0]
+        if (kids.length < 2 || !isElement(first) || !/^[a-z]/.test(tagOf(first))) return
+        const own = classesOf(first)
+        if (!ROW(own) || !OWN_SIDE_PADDING(own)) return
+        if (INTERACTIVE.some((name) => attribute(first, name))) return
+        if (!FILLS(classesOf(column)) && !BAR(own)) return
+        if (!carriesTitle(first)) return
+        if (isEscaped(context, first.openingElement)) return
+        context.report({ loc: first.openingElement.loc, messageId: 'handmade' })
+      },
+    }
+  },
+}

package/src/eslint/no-restyled-part.ts

@@ -399,6 +399,17 @@ function moduleParts(file: string, program: Node, parser: Parser, stack: Set<str
   return { locals, exports }
 }
 
+/**
+ * What a file's names stand for, found the way this rule finds them: for a rule
+ * that asks whether a tag is one particular part, through an app's wrapper too
+ * (UIG-23 asks for `EmptyState` and `ScrollArea`).
+ */
+export function partsOfFile(file: string, program: Node, parser: Parser): Map<string, PartBinding | 'namespace'> {
+  return moduleParts(file, program, parser, new Set([file])).locals
+}
+
+export { bindingOfTag, functionComponents, parseFile, resolveModule, walk, type Node, type Parser }
+
 function moduleExports(file: string, parser: Parser, stack: Set<string>): Map<string, PartBinding> {
   const mtime = statSync(file).mtimeMs
   const cached = moduleCache.get(file)

package/src/gates/app-checks.ts

@@ -31,7 +31,7 @@ export interface AppCheckOptions {
   chain?: { ref: string; owner: boolean }
   /** The token lint configs the app has, relative to the app. */
   tokenConfigs?: string[]
-  /** The name of the app's header component a hand-made header row should name (UIG-22's first guess). */
+  /** The part a hand-made column header should name (UIG-22): `ContainerHeader`. */
   headers?: string[]
 }
 
@@ -70,7 +70,7 @@ function all(h: GateHelpers, steps: (() => CheckResult | Promise<CheckResult>)[]
   }
 }
 
-export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['ContainerHeader', 'SectionHeader'] }: AppCheckOptions): GateTicket[] {
+export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['ContainerHeader'] }: AppCheckOptions): GateTicket[] {
   const WEB = app === '.' ? '' : `${app.replace(/\/$/, '')}/`
   const cwd = app === '.' ? undefined : app
   const PROBE = 'src/components/__gates_probe__.tsx'
@@ -219,7 +219,9 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: "a plain tailwind-merge is an error naming the package's cn()", run: tokenProbe("import { twMerge } from 'tailwind-merge'\nexport const merged = twMerge('p-2', 'p-3')\n", 'error', 'cn()', 'src/lib/__gates_probe__.ts') },
     ]),
     ticket('UIG-22', [
-      { what: 'a hand-made header row is an error naming the header part', run: all(h, headers.map((name) => probe(component(`<section className="flex flex-col"><div className="flex items-center px-3 py-2"><span>${name === 'SectionHeader' ? 'Issues' : 'Folders'}</span></div><div /></section>`), 'error', name)), 'a hand-made header row is an error naming the header part') },
+      // The Folders pane's own row, at the commit before peek 3dc663b.
+      { what: 'a hand-made column header is an error naming ContainerHeader', run: all(h, headers.map((name) => probe(component('<div className="flex h-full flex-col"><div className="flex items-center gap-2 px-3 py-2"><span>Folders</span></div><div /></div>'), 'error', name)), 'a hand-made column header is an error naming ContainerHeader') },
+      { what: 'a group heading inside a list is left alone', run: probe(component('<section className="flex flex-col gap-px"><h3 className="flex h-8 items-center gap-2 px-3"><span>Todo</span></h3><div /></section>'), 'none') },
     ]),
     ticket('UIG-23', [
       { what: 'a hand-made empty line is an error naming EmptyState', run: probe("export function Probe({ items }: { items: string[] }) {\n  return <div>{items.length === 0 ? <p className=\"text-text-secondary\">Nothing here</p> : items.map((i) => <span key={i}>{i}</span>)}</div>\n}\n", 'error', 'EmptyState') },

package/src/gates/create-app.test.ts

@@ -59,7 +59,7 @@ describe('create-estiva-app', () => {
 
   it('starts the count at zero and keeps the CI job named gate', () => {
     const count = JSON.parse(files['.gates-count.json'])
-    expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])
+    expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])
     expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run lint:rules/)
     expect(files['docs/GATES-DEBT.md']).toContain('Nothing.')
   })