@estiva-app/ui 0.14.0 → 0.16.0

package/src/Select.test.tsx

@@ -32,6 +32,23 @@ function Controlled({ initial = 'todo', ...rest }: { initial?: string } & Partia
   return <Select value={value} onChange={setValue} options={STATUSES} ariaLabel="Status" {...rest} />
 }
 
+/**
+ * The open list, once it has focus.
+ *
+ * The list is findable as soon as it opens, but Base UI moves focus into it an
+ * animation frame later. A key pressed before that frame goes to the trigger:
+ * Tab then moves focus into the list instead of closing it, and an arrow or End
+ * is lost. A person presses keys at a list that has focus, so these tests wait
+ * for it. CI failed "Tab closes the list" this way on 15 September (PR #36);
+ * with every frame 100ms late the three tests that use this failed 3 runs of 3,
+ * focus measured still on the trigger when Tab was pressed.
+ */
+async function focusedList() {
+  const list = await screen.findByRole('listbox')
+  await waitFor(() => expect(list.contains(document.activeElement)).toBe(true))
+  return list
+}
+
 describe('Select', () => {
   it('is a button naming itself, showing the chosen label', () => {
     render(<Controlled initial="in_progress" />)
@@ -65,7 +82,7 @@ describe('Select', () => {
     const trigger = screen.getByRole('combobox', { name: 'Status' })
     trigger.focus()
     await user.keyboard('{ArrowDown}')
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     await user.keyboard('{ArrowDown}{Enter}')
     expect(onChange).toHaveBeenCalledWith('in_progress')
     expect(document.activeElement).toBe(trigger)
@@ -130,7 +147,7 @@ describe('Select', () => {
     render(<Controlled initial="in_progress" />)
     screen.getByRole('combobox', { name: 'Status' }).focus()
     await user.keyboard('{ArrowDown}')
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     const highlighted = () => screen.getAllByRole('option').find((o) => o.getAttribute('data-highlighted') !== null)?.textContent
     await user.keyboard('{End}')
     expect(highlighted()).toContain('Done')
@@ -142,7 +159,7 @@ describe('Select', () => {
     const user = userEvent.setup()
     render(<Controlled />)
     await user.click(screen.getByRole('combobox', { name: 'Status' }))
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     await user.tab()
     await waitFor(() => expect(screen.queryByRole('listbox')).toBeNull())
   })

package/src/Toast.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext, useMemo, type ReactNode } from 'react'
 import { Toast as BaseToast } from '@base-ui/react/toast'
 import { IconAlertCircle, IconCircleCheck, IconCircleX } from '@tabler/icons-react'
+import { Button } from './Button'
 import { cn } from './cn'
 
 /**
@@ -78,14 +79,6 @@ const ICON_STYLES: Record<ToastType, string> = {
   error: 'signal:text-error-default',
 }
 
-const ACTION_BORDER_STYLES: Record<ToastType, string> = {
-  success: 'signal:border signal:border-border-default signal:hover:border-border-strong',
-  brand: 'signal:border signal:border-border-default signal:hover:border-border-strong',
-  neutral: 'border border-border-default',
-  warning: 'signal:border signal:border-border-default signal:hover:border-border-strong',
-  error: 'signal:border signal:border-border-default signal:hover:border-border-strong',
-}
-
 const LABEL_CLASSES = 'text-body-2 text-text-primary whitespace-nowrap'
 
 const pillClassName = (type: ToastType, hasAction: boolean, className?: string) =>
@@ -98,20 +91,11 @@ const pillClassName = (type: ToastType, hasAction: boolean, className?: string)
     className,
   )
 
-const actionClassName = (type: ToastType) =>
-  cn(
-    'h-6 flex items-center justify-center gap-1 px-1 py-1 rounded-md shrink-0 transition-colors',
-    ACTION_BORDER_STYLES[type],
-    type === 'neutral' ? 'hover:border-border-strong' : 'hover:opacity-80',
-  )
-
 function LeadingIcon({ type }: { type: ToastType }) {
   const Icon = ICONS[type]
   return <Icon size={16} stroke={1.5} className={cn('text-text-primary shrink-0', ICON_STYLES[type])} />
 }
 
-const ACTION_LABEL_CLASSES = 'text-btn-small text-text-primary whitespace-nowrap'
-
 /**
  * One toast, drawn in place. What the provider shows is this pill; draw it
  * yourself only where a page needs a toast's look without its timing — a
@@ -126,9 +110,9 @@ export function Toast({ label, type = 'neutral', leadingIcon = true, actionLabel
         <span className={LABEL_CLASSES}>{label}</span>
       </div>
       {hasAction && (
-        <button type="button" onClick={onAction} className={actionClassName(type)}>
-          <span className={ACTION_LABEL_CLASSES}>{actionLabel}</span>
-        </button>
+        <Button variant="outlined" size="small" onClick={onAction}>
+          {actionLabel}
+        </Button>
       )}
     </div>
   )
@@ -229,10 +213,14 @@ function ToastList() {
               onAction?.()
               close(toast.id)
             }}
-            className={actionClassName(type)}
-          >
-            <span className={ACTION_LABEL_CLASSES}>{actionLabel}</span>
-          </BaseToast.Action>
+            // The same Button the toast drawn in place uses, told to *be* the
+            // Base UI action rather than sit inside one (Katerina, 16 September).
+            render={
+              <Button variant="outlined" size="small">
+                {actionLabel}
+              </Button>
+            }
+          />
         )}
       </BaseToast.Root>
     )

package/src/eslint/escape.ts

@@ -0,0 +1,112 @@
+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,
+ *
+ *     // @estiva-escape: <reason>
+ *
+ * or, where the element is a JSX child, the JSX comment on the line above,
+ *
+ *     {/* @estiva-escape: <reason> *\/}
+ *
+ * with at least ten characters of reason, spaces not counted.
+ *
+ * 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
+ * marker written inside a directive that switches one of these rules off is
+ * reported for that reason.
+ *
+ * The token lint's older notes (`eslint-disable-next-line <rule> -- @estiva-escape:
+ * <reason>`, Katerina's ruling A2 of 15 September) are not read here: they
+ * escape the token lint's rules, which are not this plugin's, and they stay as
+ * they are (Katerina, 15 September).
+ */
+export const ESCAPE_MARKER = '@estiva-escape'
+
+/** Characters of reason, spaces not counted. */
+export const MIN_REASON = 10
+
+/** The key under ESLint's `settings` this plugin reads. */
+export const SETTINGS_KEY = 'estiva'
+
+/**
+ * Every rule spreads these into its `meta.messages`, because `isEscaped`
+ * 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.`,
+  escaped: 'Escaped: {{reason}}',
+} as const
+
+export interface EstivaSettings {
+  /**
+   * Report every sanctioned escape as a message with the id `escaped`, so a
+   * count can read them. Off in the lint anyone runs; on only in the count.
+   */
+  reportEscapes?: boolean
+}
+
+interface Located {
+  loc?: AST.SourceLocation | null
+  range?: [number, number]
+}
+
+const DIRECTIVE = /^\s*eslint-disable(?:-next-line|-line)?(?=\s|$)([^]*)$/
+
+/** The rules a directive names: what comes before its ` -- ` description. None means every rule. */
+function directiveRules(rest: string): string[] {
+  const dashes = rest.search(/(?:^|\s)--(?:\s|$)/)
+  return (dashes === -1 ? rest : rest.slice(0, dashes)).split(/[\s,]+/).filter(Boolean)
+}
+
+/** Only spaces and a JSX expression's closing brace between the marker and the element. */
+const BETWEEN = /^[\s}]*$/
+
+/**
+ * Whether the element at `node` carries a valid escape on the line above.
+ *
+ * Every rule of this plugin calls it before it reports. It reports, through
+ * that rule, a marker with too short a reason and a marker inside an
+ * eslint-disable directive for this rule; either way the element is not
+ * escaped, so the rule reports it too.
+ */
+export function isEscaped(context: Rule.RuleContext, node: Located): boolean {
+  const { sourceCode } = context
+  if (!node.loc || !node.range) return false
+  const line = node.loc.start.line
+  const nodeStart = node.range[0]
+
+  const comment = sourceCode
+    .getAllComments()
+    .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 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' })
+    return false
+  }
+
+  const reason = comment.value
+    .slice(at + ESCAPE_MARKER.length)
+    .replace(/^:/, '')
+    .trim()
+  if (reason.replace(/\s/g, '').length < MIN_REASON) {
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason' })
+    return false
+  }
+
+  const settings = context.settings[SETTINGS_KEY] as EstivaSettings | undefined
+  if (settings?.reportEscapes) context.report({ loc: comment.loc, messageId: 'escaped', data: { reason } })
+  return true
+}

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

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+/** 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'
+
+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', () => {
+    expect(existsSync(src('Button.mdx'))).toBe(true)
+    expect(existsSync(src('Button.stories.tsx'))).toBe(true)
+    for (const name of ['FieldLine', 'MenuItem']) {
+      expect(existsSync(src(`${name}.mdx`))).toBe(true)
+      expect(existsSync(src(`${name}.stories.tsx`))).toBe(true)
+      // The false positive to avoid: no component file of their own.
+      expect(existsSync(src(`${name}.tsx`))).toBe(false)
+    }
+  })
+})
+
+tester.run('component-has-a-page', componentHasAPage, {
+  valid: [
+    { name: 'a component with its page beside it', code, filename: src('Button.tsx') },
+    { name: 'a story file, which needs no page of its own', code, filename: src('Button.stories.tsx') },
+    { name: 'a test file', code, filename: src('Button.test.tsx') },
+    { name: 'a file that is not a component file at all', code, filename: src('index.ts') },
+    { name: 'a component with its reason at the top', code: escaped, filename: src('NoPageProbe.tsx') },
+  ],
+  invalid: [
+    { name: 'a component with no page', code, filename: src('NoPageProbe.tsx'), errors: [{ messageId: 'missing' }] },
+  ],
+})
+
+tester.run('component-has-a-story', componentHasAStory, {
+  valid: [
+    { name: 'a component with its story beside it', code, filename: src('Button.tsx') },
+    { name: 'a story file, which is not itself a component', code, filename: src('Button.stories.tsx') },
+    { name: 'a component with its reason at the top', code: escaped, filename: src('NoStoryProbe.tsx') },
+  ],
+  invalid: [
+    { name: 'a component with no story', code, filename: src('NoStoryProbe.tsx'), errors: [{ messageId: 'missing' }] },
+  ],
+})

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

@@ -0,0 +1,97 @@
+import { existsSync } from 'node:fs'
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+/**
+ * A component of the package with no page, and one with no story (UIG-5, P2 and
+ * P3).
+ *
+ * A component nobody can read about is a component nobody uses correctly, and
+ * one nobody can look at is one nobody reviews. Both were at zero when these
+ * were switched on; they are here so the next component cannot arrive without
+ * them.
+ *
+ * The pair is by file name, beside the component, which is how this package is
+ * laid out: `Button.tsx`, `Button.mdx`, `Button.stories.tsx`, `Button.test.tsx`
+ * side by side in `src/`.
+ *
+ * **The false positive to avoid** (UIG-1 confirmed it is real): `FieldLine` and
+ * `MenuItem` have a page and a story but no `.tsx` of their own — they are
+ * exported from a sibling. These rules read a component file and ask for its
+ * page and its story, never the other way round, so a page without a component
+ * is not this rule's business.
+ *
+ * A file that stays without one says why at its top: `// @estiva-escape: <why>`.
+ */
+interface ProgramNode {
+  body: { loc?: Rule.Node['loc']; range?: [number, number] }[]
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+}
+
+/** A component file: a `.tsx` in the package's source that is not a story or a test. */
+function componentFile(filename: string): boolean {
+  return filename.endsWith('.tsx') && !/\.(stories|test)\.tsx$/.test(filename)
+}
+
+function sibling(filename: string, extension: string): string {
+  return filename.replace(/\.tsx$/, extension)
+}
+
+/**
+ * Report on the file's first statement, so the escape is a comment at the top of
+ * the file — the only place a reason for a missing page could go.
+ */
+function reportOnFile(context: Rule.RuleContext, program: ProgramNode, messageId: string, data: Record<string, string>): void {
+  const anchor = program.body[0] ?? program
+  if (anchor.loc && anchor.range && isEscaped(context, { loc: anchor.loc, range: anchor.range })) return
+  context.report({ loc: anchor.loc ?? program.loc, messageId, data })
+}
+
+export const componentHasAPage: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Every component of the package has a usage page beside it' },
+    schema: [],
+    messages: {
+      missing: '{{name}} has no page. Write {{page}} beside it — what it is, when, when not, how, and what it owns — or say why not at the top of the file.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const filename = context.filename
+        if (!componentFile(filename)) return
+        const page = sibling(filename, '.mdx')
+        if (existsSync(page)) return
+        const name = filename.split(/[\\/]/).pop() ?? filename
+        reportOnFile(context, node as unknown as ProgramNode, 'missing', { name, page: page.split(/[\\/]/).pop() ?? page })
+      },
+    }
+  },
+}
+
+export const componentHasAStory: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Every component of the package has a story beside it' },
+    schema: [],
+    messages: {
+      missing: '{{name}} has no story. Write {{story}} beside it, so it can be seen and reviewed, or say why not at the top of the file.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      Program(node) {
+        const filename = context.filename
+        if (!componentFile(filename)) return
+        const story = sibling(filename, '.stories.tsx')
+        if (existsSync(story)) return
+        const name = filename.split(/[\\/]/).pop() ?? filename
+        reportOnFile(context, node as unknown as ProgramNode, 'missing', { name, story: story.split(/[\\/]/).pop() ?? story })
+      },
+    }
+  },
+}

package/src/eslint/index.test.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs'
+import { ESLint, type Linter } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import estiva, { APP_RULE_IDS, countGates, PACKAGE_RULE_IDS, PLUGIN_KEY } from './index'
+
+/**
+ * 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-button.test.ts.
+ */
+const tsx: Linter.Config = {
+  files: ['**/*.tsx'],
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+}
+
+async function lint(code: string, extra: Linter.Config[] = []) {
+  const eslint = new ESLint({
+    cwd: process.cwd(),
+    overrideConfigFile: true,
+    overrideConfig: [tsx, estiva.configs.recommended, ...extra],
+  })
+  return eslint.lintText(code, { filePath: 'src/Probe.tsx' })
+}
+
+const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
+const countMode: Linter.Config = { settings: { estiva: { reportEscapes: true } } }
+
+describe('the plugin object', () => {
+  it('names itself and carries the package version', () => {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+    expect(estiva.meta).toEqual({ name: '@estiva-app/ui/eslint', version: pkg.version })
+  })
+
+  it('carries every rule, the app ones and the inward ones', () => {
+    expect(Object.keys(estiva.rules)).toEqual([
+      'no-raw-button',
+      'raw-element-outside-a-wrapper',
+      'no-hand-rolled-behaviour',
+      'component-has-a-page',
+      'component-has-a-story',
+    ])
+  })
+
+  /**
+   * The apps spread `recommended`. A rule added for the package (UIG-5) must not
+   * arrive in Peek or Ship with the next version bump: an app is full of raw
+   * elements it may keep until UIG-7, and has no `.mdx` pages at all. This is
+   * the test that holds that line — if you add an app-facing rule on purpose,
+   * change it deliberately, here.
+   */
+  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-button': 'error' })
+    }
+    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-button'])
+  })
+
+  it('gives this package its own set, as errors, and it reaches no app config', () => {
+    expect(estiva.configs.package.plugins?.[PLUGIN_KEY]).toBe(estiva)
+    expect(estiva.configs.package.rules).toEqual({
+      'estiva/raw-element-outside-a-wrapper': 'error',
+      'estiva/no-hand-rolled-behaviour': 'error',
+      'estiva/component-has-a-page': 'error',
+      'estiva/component-has-a-story': 'error',
+    })
+    expect(PACKAGE_RULE_IDS).toEqual(Object.keys(estiva.configs.package.rules ?? {}))
+    for (const id of PACKAGE_RULE_IDS) {
+      expect(estiva.configs.recommended.rules?.[id]).toBeUndefined()
+      expect(estiva.configs.strict.rules?.[id]).toBeUndefined()
+    }
+  })
+})
+
+describe('an app lint with configs.recommended', () => {
+  it('reports a raw <button>, naming Button', async () => {
+    const [result] = await lint(component('    <button type="button">x</button>'))
+    expect(result.messages.map((m) => [m.ruleId, m.severity, m.message])).toEqual([
+      ['estiva/no-raw-button', 2, 'Use `Button` from @estiva-app/ui instead of a raw <button>.'],
+    ])
+  })
+
+  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([])
+  })
+})
+
+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-button': { errors: 1, warnings: 0, escapes: 0 } })
+    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-button': { errors: 1, warnings: 0, escapes: 1 } })
+  })
+
+  it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
+    const results = await lint(component('    // eslint-disable-next-line estiva/no-raw-button\n    <button>x</button>'), [countMode])
+    const count = countGates(results)
+    expect(count.rules['estiva/no-raw-button']).toEqual({ errors: 0, warnings: 0, escapes: 0 })
+    expect(count.disabled).toEqual([{ filePath: results[0].filePath, line: 4, ruleId: 'estiva/no-raw-button' }])
+  })
+
+  it('counts a marker inside that directive as an error of the rule', async () => {
+    const results = await lint(component('    // eslint-disable-next-line estiva/no-raw-button -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'), [countMode])
+    const count = countGates(results)
+    expect(count.rules['estiva/no-raw-button']).toEqual({ errors: 1, warnings: 0, escapes: 0 })
+    expect(count.disabled).toHaveLength(1)
+  })
+
+  it('lists every rule of the plugin, even with nothing found', () => {
+    expect(countGates([])).toEqual({ rules: { 'estiva/no-raw-button': { errors: 0, warnings: 0, escapes: 0 } }, disabled: [] })
+  })
+})

package/src/eslint/index.ts

@@ -0,0 +1,145 @@
+/// <reference types="node" />
+/**
+ * `@estiva-app/ui/eslint` — the UI Guardrails' lint rules, as a plugin (UIG-3,
+ * seam S1 in docs/GATES.md §16).
+ *
+ * A plugin rather than config, so every app — Peek, Ship, Leaf — gets a new
+ * rule through an ordinary version bump, and an app's editor hook runs the
+ * very rule code its CI runs.
+ *
+ *     import estiva from '@estiva-app/ui/eslint'
+ *     export default [{ files: ['src/**\/*.tsx'], ...estiva.configs.recommended }]
+ *
+ * Register it under `estiva` (the configs do): the rule ids are
+ * `estiva/<rule>`, and `countGates` counts those ids.
+ *
+ * Built on its own by build.mjs, for Node, into `dist/eslint/`; nothing here
+ * reaches the components' browser bundle.
+ */
+import { createRequire } from 'node:module'
+import type { ESLint, Linter } from 'eslint'
+import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
+import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
+import { noRawButton } from './no-raw-button'
+import { rawElementOutsideAWrapper } from './raw-element-outside-a-wrapper'
+
+export { ESCAPE_MARKER, MIN_REASON, SETTINGS_KEY, isEscaped, type EstivaSettings } from './escape'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+/** The name the configs register the plugin under, so every rule id is `estiva/<rule>`. */
+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.
+ */
+const appRules = {
+  'no-raw-button': noRawButton,
+}
+
+/**
+ * The rules the **package itself** runs, pointed inward (UIG-5): don't bury a
+ * raw element inside a component, don't rebuild what Base UI owns, don't ship a
+ * component without a page or a story.
+ *
+ * They are in `configs.package`, never in `recommended`, on purpose. Peek and
+ * Ship spread `recommended`, so a rule added here must not arrive in an app
+ * with the next version bump: an app is full of raw elements it is allowed to
+ * have until UIG-7, and has no `.mdx` pages at all. `index.test.ts` holds the
+ * apps' list to exactly the app rules.
+ */
+const packageRules = {
+  'raw-element-outside-a-wrapper': rawElementOutsideAWrapper,
+  'no-hand-rolled-behaviour': noHandRolledBehaviour,
+  'component-has-a-page': componentHasAPage,
+  'component-has-a-story': componentHasAStory,
+}
+
+const rules = { ...appRules, ...packageRules }
+
+const plugin = {
+  meta: { name: '@estiva-app/ui/eslint', version },
+  rules,
+  configs: {} as { recommended: Linter.Config; strict: Linter.Config; package: Linter.Config },
+} satisfies ESLint.Plugin
+
+/** The ids `recommended` and `strict` carry — what an app's gate runs and counts. */
+export const APP_RULE_IDS = Object.keys(appRules).map((name) => `${PLUGIN_KEY}/${name}`)
+/** The ids `package` carries — what this package's own gate runs and counts (UIG-5). */
+export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGIN_KEY}/${name}`)
+
+/**
+ * `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
+ * when the first warning-level rule arrives (UIG-25).
+ *
+ * `package` is the inward set (UIG-5), which only this package runs.
+ */
+plugin.configs.recommended = {
+  name: '@estiva-app/ui/recommended',
+  plugins: { [PLUGIN_KEY]: plugin },
+  rules: { [`${PLUGIN_KEY}/no-raw-button`]: 'error' },
+}
+plugin.configs.strict = {
+  name: '@estiva-app/ui/strict',
+  plugins: { [PLUGIN_KEY]: plugin },
+  rules: Object.fromEntries(APP_RULE_IDS.map((id) => [id, 'error'])),
+}
+plugin.configs.package = {
+  name: '@estiva-app/ui/package',
+  plugins: { [PLUGIN_KEY]: plugin },
+  rules: Object.fromEntries(PACKAGE_RULE_IDS.map((id) => [id, 'error'])),
+}
+
+export default plugin
+
+export interface GateRuleCount {
+  errors: number
+  warnings: number
+  escapes: number
+}
+
+export interface GateCount {
+  /** Per rule id, including rules with nothing to report. */
+  rules: Record<string, GateRuleCount>
+  /**
+   * Reports of these rules that an `eslint-disable` directive silenced. Not
+   * an escape: a gate fails on any of these (docs/GATES.md §16, S4).
+   */
+  disabled: { filePath: string; line: number; ruleId: string }[]
+}
+
+/**
+ * Count what a lint of these rules found, for `.gates-count.json` (seam S3).
+ *
+ * Run the lint with `settings: { estiva: { reportEscapes: true } }` for the
+ * escapes to be counted; without it they are silent and count 0. A marker
+ * with no reason, or inside a directive, counts as an error of its rule.
+ *
+ * `seed` is which rules the count lists when they found nothing, and it is the
+ * app rules unless a caller says otherwise: an app's count file must not gain
+ * rows for the inward rules (UIG-5) that its gate does not run. This package's
+ * own count script passes `PACKAGE_RULE_IDS`.
+ */
+export function countGates(results: ESLint.LintResult[], seed: readonly string[] = APP_RULE_IDS): GateCount {
+  const counts: Record<string, GateRuleCount> = Object.fromEntries(seed.map((id) => [id, { errors: 0, warnings: 0, escapes: 0 }]))
+  const disabled: GateCount['disabled'] = []
+  const ours = (ruleId: string | null | undefined): ruleId is string => typeof ruleId === 'string' && ruleId.startsWith(`${PLUGIN_KEY}/`)
+  for (const result of results) {
+    for (const message of result.messages) {
+      // Seeded or not: every rule of this plugin that reported is counted, so a
+      // lint of a set the caller did not name is still counted in full.
+      if (!ours(message.ruleId)) continue
+      const count = (counts[message.ruleId] ??= { errors: 0, warnings: 0, escapes: 0 })
+      if (message.messageId === 'escaped') count.escapes += 1
+      else if (message.severity === 2) count.errors += 1
+      else count.warnings += 1
+    }
+    for (const message of result.suppressedMessages ?? []) {
+      if (ours(message.ruleId)) disabled.push({ filePath: result.filePath, line: message.line, ruleId: message.ruleId })
+    }
+  }
+  return { rules: counts, disabled }
+}