@estiva-app/ui 0.32.0 → 0.33.0

package/dist/eslint/no-native-title.d.ts

@@ -0,0 +1,31 @@
+import type { Rule } from 'eslint';
+/**
+ * The parts whose `title` is their own: the words of a heading or a dialog,
+ * drawn on the page. Every other part hands a `title` on to its element, and
+ * the browser shows it as its tooltip. `no-native-title.test.ts` holds this
+ * list to the catalogue: a part that gains a `title` of its own joins it.
+ */
+export declare const PARTS_WITH_A_TITLE: readonly ["CollapsibleSection", "ConfirmDialog", "ContainerHeader", "DialogShell", "ListColumn", "SectionHeader"];
+/**
+ * UIG-24: the browser's tooltip where ours belongs.
+ *
+ * A `title` on an element is the browser's hover box: grey, in the system's
+ * font, after a delay nobody chose, and never on a touch screen. The package's
+ * `WithTooltip` is the tooltip here (and `IconButton`'s `tooltip`, which draws
+ * it). The rule reads the attribute, never the page: a tooltip's words are not
+ * on the page until it opens.
+ *
+ * Judged: a `title` on a plain element, and on a part of the package (or an
+ * app's wrapper that hands all its props on to one) whose `title` is not its
+ * own — `<Button title>` reaches the `<button>`. Not judged, on purpose:
+ *
+ * - the `<title>` **element**, in an `<svg>` (a label for a screen reader) or
+ *   a document's head: an element, not an attribute, so the rule never sees it;
+ * - a part whose `title` is its own heading (`PARTS_WITH_A_TITLE`);
+ * - the app's own components: what one does with a `title` is its own business,
+ *   and its elements are judged where it draws them;
+ * - a story's `title` (`meta = { title: 'Group/Name' }`): an object key, not an
+ *   attribute.
+ */
+export declare const noNativeTitle: Rule.RuleModule;
+//# sourceMappingURL=no-native-title.d.ts.map

package/dist/eslint/no-native-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-native-title.d.ts","sourceRoot":"","sources":["../../src/eslint/no-native-title.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAIlC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,mHAAoH,CAAA;AAMnJ;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,EAAE,IAAI,CAAC,UAkChC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,7 +4,7 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.32.0",
+    "packageVersion": "0.33.0",
     "exports": 87,
     "typeExports": 96,
     "files": null

package/src/Tooltip.mdx

@@ -104,6 +104,7 @@ It does these by itself. Write none of them around it.
 | Floats on top of the page | a portal, or a `z-index` to win | ✓ |
 | Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
 | Says what it is to assistive technology: a tooltip | `role="tooltip"` | ✓ |
+| Is the tooltip: our look, our 300ms, one shared delay | a `title` attribute, the browser's grey box | ✓ (`estiva/no-native-title`) |
 | Opens after the pointer rests, and at once on keyboard focus | a timer, or hover and focus handlers |  |
 | Closes on Escape, on a click of its control, and when the pointer leaves | close handlers |  |
 

package/src/eslint/index.test.ts

@@ -39,6 +39,7 @@ describe('the plugin object', () => {
       'no-restyled-part',
       'no-handmade-header',
       'no-handmade-empty-state',
+      'no-native-title',
       'raw-element-outside-a-wrapper',
       'no-hand-rolled-behaviour',
       'component-has-a-page',
@@ -58,14 +59,14 @@ describe('the plugin object', () => {
   it('gives an app only the app rules, as errors, under estiva/', () => {
     for (const config of [estiva.configs.recommended, estiva.configs.strict]) {
       expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
-      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error', 'estiva/no-restyled-part': 'error', 'estiva/no-handmade-header': 'error', 'estiva/no-handmade-empty-state': 'error' })
+      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error', 'estiva/no-restyled-part': 'error', 'estiva/no-handmade-header': 'error', 'estiva/no-handmade-empty-state': 'error', 'estiva/no-native-title': 'error' })
     }
-    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state'])
+    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'])
   })
 
   /**
    * `no-restyled-part` (UIG-9), `no-handmade-header` (UIG-22) and
-   * `no-handmade-empty-state` (UIG-23) are in both sets: the package restyles
+   * `no-handmade-empty-state` (UIG-23) and `no-native-title` (UIG-24) are in both sets: the package restyles
    * none of its own parts either (Katerina, 17 September), and draws no header
    * bar or empty state by hand ("my review isn't enough", 23 September). Every
    * other inward rule still reaches no app.
@@ -80,9 +81,10 @@ describe('the plugin object', () => {
       'estiva/no-restyled-part': 'error',
       'estiva/no-handmade-header': 'error',
       'estiva/no-handmade-empty-state': 'error',
+      'estiva/no-native-title': 'error',
     })
     expect(PACKAGE_RULE_IDS).toEqual(Object.keys(estiva.configs.package.rules ?? {}))
-    for (const id of PACKAGE_RULE_IDS.filter((id) => !['estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state'].includes(id))) {
+    for (const id of PACKAGE_RULE_IDS.filter((id) => !['estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'].includes(id))) {
       expect(estiva.configs.recommended.rules?.[id]).toBeUndefined()
       expect(estiva.configs.strict.rules?.[id]).toBeUndefined()
     }
@@ -149,8 +151,8 @@ 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 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 })
-    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 })
+    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 })
+    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 })
   })
 
   it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
@@ -173,6 +175,7 @@ describe('countGates', () => {
         'estiva/no-restyled-part': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-handmade-header': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-handmade-empty-state': { errors: 0, warnings: 0, escapes: 0 },
+        'estiva/no-native-title': { errors: 0, warnings: 0, escapes: 0 },
       },
       disabled: [],
     })

package/src/eslint/index.ts

@@ -22,6 +22,7 @@ import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
 import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
 import { noHandmadeEmptyState } from './no-handmade-empty-state'
 import { noHandmadeHeader } from './no-handmade-header'
+import { noNativeTitle } from './no-native-title'
 import { noRawElement } from './no-raw-element'
 import { noRebuiltBehaviour } from './no-rebuilt-behaviour'
 import { noRestyledPart } from './no-restyled-part'
@@ -30,6 +31,7 @@ import { rawElementOutsideAWrapper } from './raw-element-outside-a-wrapper'
 export { ESCAPE_MARKER, MIN_REASON, SETTINGS_KEY, isEscaped, type EstivaSettings } from './escape'
 export { OWNED_BEHAVIOURS, type OwnedBehaviour } from './no-rebuilt-behaviour'
 export { PART_LOOK_PROPS, PLACEMENT } from './no-restyled-part'
+export { PARTS_WITH_A_TITLE } from './no-native-title'
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
@@ -48,6 +50,7 @@ const appRules = {
   'no-restyled-part': noRestyledPart,
   'no-handmade-header': noHandmadeHeader,
   'no-handmade-empty-state': noHandmadeEmptyState,
+  'no-native-title': noNativeTitle,
 }
 
 /**
@@ -62,9 +65,9 @@ const appRules = {
  * app's version, UIG-7), and an app has no `.mdx` pages at all. `index.test.ts` holds the
  * apps' list to exactly the app rules.
  *
- * Three rules are in both sets: `no-restyled-part` (UIG-9), and the
- * fingerprints `no-handmade-header` (UIG-22) and `no-handmade-empty-state`
- * (UIG-23). The package restyles none of its own parts either (Katerina, 17
+ * Four rules are in both sets: `no-restyled-part` (UIG-9), and the
+ * fingerprints `no-handmade-header` (UIG-22), `no-handmade-empty-state`
+ * (UIG-23) and `no-native-title` (UIG-24). The package restyles none of its own parts either (Katerina, 17
  * September), and "my review isn't enough" (23 September).
  */
 const packageRules = {
@@ -75,6 +78,7 @@ const packageRules = {
   'no-restyled-part': noRestyledPart,
   'no-handmade-header': noHandmadeHeader,
   'no-handmade-empty-state': noHandmadeEmptyState,
+  'no-native-title': noNativeTitle,
 }
 
 const rules = { ...appRules, ...packageRules }
@@ -107,6 +111,7 @@ plugin.configs.recommended = {
     [`${PLUGIN_KEY}/no-restyled-part`]: 'error',
     [`${PLUGIN_KEY}/no-handmade-header`]: 'error',
     [`${PLUGIN_KEY}/no-handmade-empty-state`]: 'error',
+    [`${PLUGIN_KEY}/no-native-title`]: 'error',
   },
 }
 plugin.configs.strict = {

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

@@ -0,0 +1,67 @@
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import { noNativeTitle, PARTS_WITH_A_TITLE } from './no-native-title'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+/** An app on disk, so a wrapper of the app's own is followed to its part, as Peek's are. */
+const root = mkdtempSync(join(tmpdir(), 'no-native-title-'))
+const write = (path: string, text: string) => {
+  mkdirSync(dirname(join(root, path)), { recursive: true })
+  writeFileSync(join(root, path), text)
+}
+write('app/package.json', '{ "name": "app" }')
+write('app/src/components/ui/IconButton.tsx', "export { IconButton } from '@estiva-app/ui'\n")
+write('app/src/components/ui/Button.tsx', "import { Button as UiButton, type ButtonProps } from '@estiva-app/ui'\nexport function Button(props: ButtonProps) {\n  return <UiButton {...props} />\n}\n")
+write('app/src/components/Banner.tsx', 'export function NewTopicBanner({ title }: { title: string }) {\n  return <p>{title}</p>\n}\n')
+const app = join(root, 'app/src/Probe.tsx')
+
+const component = (body: string, imports = '') => `${imports}export function Probe({ at, name }: { at: string; name: string }) {\n  return (\n${body}\n  )\n}\n`
+const native = [{ messageId: 'native' }]
+
+tester.run('no-native-title', noNativeTitle, {
+  valid: [
+    { name: 'the part: WithTooltip', code: component('<WithTooltip label={at}><time>{at}</time></WithTooltip>', "import { WithTooltip } from '@estiva-app/ui'\n") },
+    { name: "IconButton's own tooltip", code: component('<IconButton tooltip="Close" aria-label="Close">x</IconButton>', "import { IconButton } from '@estiva-app/ui'\n") },
+    { name: 'a <title> inside an <svg> is a label for a screen reader, not a tooltip', code: component('<svg viewBox="0 0 16 16"><title>Unread</title><circle r="4" /></svg>') },
+    { name: "a <title> in a document's head", code: component('<html><head><title>Estiva</title></head><body /></html>') },
+    ...PARTS_WITH_A_TITLE.map((part) => ({ name: `${part}'s title is its own heading`, code: component(`<${part} title="Files" />`, `import { ${part} } from '@estiva-app/ui'\n`) })),
+    { 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</>') },
+  ],
+  invalid: [
+    {
+      name: 'the file conversation timestamp at peek 3dc663b~1 (ForeignConversationView.tsx:106)',
+      code: component('<time\n  dateTime={at}\n  title={new Date(at).toLocaleString()}\n  className="text-caption text-text-muted"\n>\n  {at}\n</time>'),
+      errors: native,
+    },
+    { name: "a reference chip's cut-short title (Reference.tsx at UIG-1's commits)", code: component('<span className="truncate" title={name}>{name}</span>'), errors: native },
+    { name: 'a title that is only there sometimes (MentionChip.tsx)', code: component('<span title={name ? undefined : at}>{name}</span>'), errors: native },
+    { name: 'a string', code: component('<div title="online presence" />'), errors: native },
+    { 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] },
+  ],
+})
+
+describe('PARTS_WITH_A_TITLE', () => {
+  it('is every part the catalogue says takes a title of its own, and no other', () => {
+    const registry = JSON.parse(readFileSync(new URL('../../registry.json', import.meta.url), 'utf8')) as { entries: { name: string; props?: { name: string }[] | null }[] }
+    const declared = registry.entries.filter((entry) => entry.props?.some((prop) => prop.name === 'title')).map((entry) => entry.name).sort()
+    expect([...PARTS_WITH_A_TITLE].sort()).toEqual(declared)
+  })
+})

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

@@ -0,0 +1,72 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+import { bindingOfTag, partsOfFile, type Node, type Parser, type PartBinding } from './no-restyled-part'
+
+/**
+ * The parts whose `title` is their own: the words of a heading or a dialog,
+ * drawn on the page. Every other part hands a `title` on to its element, and
+ * the browser shows it as its tooltip. `no-native-title.test.ts` holds this
+ * list to the catalogue: a part that gains a `title` of its own joins it.
+ */
+export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'DialogShell', 'ListColumn', 'SectionHeader'] as const
+
+const child = (node: Node, key: string) => node[key] as Node | null | undefined
+const nameOf = (node: Node | null | undefined): string | undefined =>
+  node?.type === 'JSXIdentifier' || node?.type === 'Identifier' ? (node.name as string) : undefined
+
+/**
+ * UIG-24: the browser's tooltip where ours belongs.
+ *
+ * A `title` on an element is the browser's hover box: grey, in the system's
+ * font, after a delay nobody chose, and never on a touch screen. The package's
+ * `WithTooltip` is the tooltip here (and `IconButton`'s `tooltip`, which draws
+ * it). The rule reads the attribute, never the page: a tooltip's words are not
+ * on the page until it opens.
+ *
+ * Judged: a `title` on a plain element, and on a part of the package (or an
+ * app's wrapper that hands all its props on to one) whose `title` is not its
+ * own — `<Button title>` reaches the `<button>`. Not judged, on purpose:
+ *
+ * - the `<title>` **element**, in an `<svg>` (a label for a screen reader) or
+ *   a document's head: an element, not an attribute, so the rule never sees it;
+ * - a part whose `title` is its own heading (`PARTS_WITH_A_TITLE`);
+ * - the app's own components: what one does with a `title` is its own business,
+ *   and its elements are judged where it draws them;
+ * - a story's `title` (`meta = { title: 'Group/Name' }`): an object key, not an
+ *   attribute.
+ */
+export const noNativeTitle: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: "A title attribute: the browser's tooltip where WithTooltip is the part" },
+    schema: [],
+    messages: {
+      native:
+        "`title` is the browser's tooltip, not ours. Wrap it in `WithTooltip` from @estiva-app/ui, or use `IconButton`'s `tooltip`: its page (Primitives/Tooltip) says when it shows and how.",
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    const parser = (context.languageOptions?.parser ?? {}) as Parser
+    let locals: Map<string, PartBinding | 'namespace'> | undefined
+    return {
+      Program(program) {
+        locals = partsOfFile(context.filename, program as unknown as Node, parser)
+      },
+      JSXAttribute(ruleNode: Rule.Node) {
+        const attribute = ruleNode as unknown as Node
+        if (nameOf(child(attribute, 'name')) !== 'title') return
+        const opening = attribute.parent as Node
+        const tag = child(opening, 'name')
+        const name = nameOf(tag)
+        if (!(name && /^[a-z]/.test(name))) {
+          const binding = locals && bindingOfTag(tag, locals)
+          if (!binding || binding.props !== 'all') return
+          if ((PARTS_WITH_A_TITLE as readonly string[]).includes(binding.part)) return
+        }
+        if (isEscaped(context, opening)) return
+        context.report({ loc: attribute.loc as NonNullable<Rule.Node['loc']>, messageId: 'native' })
+      },
+    }
+  },
+}

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 }, { 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 }, { 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.')
   })

package/src/gates/gates.test.ts

@@ -153,7 +153,7 @@ describe('writeGateCount', () => {
     const written = JSON.parse(readFileSync(join(dir, '.gates-count.json'), 'utf8'))
     expect(written).toMatchObject({ schemaVersion: 1, repo: 'probe' })
     expect(written.rules['estiva/no-raw-element']).toEqual({ errors: 0, warnings: 0, escapes: 1 })
-    expect(Object.keys(written.rules)).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state'])
+    expect(Object.keys(written.rules)).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'])
 
     expect((await writeGateCount({ root: dir, repo: 'probe' })).changed).toBe(false)