@estiva-app/ui 0.48.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.48.0",
+  "version": "0.49.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.48.0",
+    "packageVersion": "0.49.0",
     "exports": 104,
     "typeExports": 113,
     "files": null

package/src/DialogShell.stories.tsx

@@ -53,6 +53,24 @@ export const Default: Story = {
   },
 }
 
+/**
+ * **A long title keeps to its one line** and ends in "…", so the bar stays
+ * 48px and the ✕ stays where it is. A title that names something a person
+ * typed — a file's name in "Archive “…”?" — is the one that gets long.
+ */
+export const ALongTitle: Story = {
+  args: {
+    title: 'Archive “Interesting Claude-generated docs - Renamed 4, with notes from the second review”?',
+    footer: (
+      <>
+        <Button variant="muted">Cancel</Button>
+        <Button variant="primary">Archive topic</Button>
+      </>
+    ),
+    children: <p className="text-body-2 text-text-primary">This hides the topic from every list.</p>,
+  },
+}
+
 /**
  * **`headerContent` replaces the title text** — a back button beside it, a
  * count after it — and the ✕ stays. The dialog is then named by its `title`

package/src/DialogShell.tsx

@@ -115,11 +115,13 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
             className="bg-bg-elevated border border-border-subtle rounded-lg shadow-lg pointer-events-auto flex flex-col overflow-hidden outline-none"
             style={{ width }}
           >
-            {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22). */}
+            {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22).
+                The title keeps to its one line and ends in "…": a long name wrapped to
+                two lines in the 48px bar and lost its top (Katerina, 1 October). */}
             <ContainerHeader
               title={
                 headerContent ?? (
-                  <Parts.Title className="text-h4 text-text-primary" render={<span />}>
+                  <Parts.Title className="block truncate text-h4 text-text-primary" render={<span />}>
                     {title}
                   </Parts.Title>
                 )

package/src/Form.mdx

@@ -22,6 +22,10 @@ is switched off at once.
 - One field that saves itself as you leave it → **EditableText**.
 - A field that filters a list as you type → **SearchInput**; nothing is sent.
 
+A `Field`, `TextInput` or `Textarea` with no `Form` around it is refused by
+the gate (`estiva/no-field-outside-a-form`). A question with a field in it is
+**DialogShell** with a form, never **ConfirmDialog**.
+
 ## How
 
 ```tsx

package/src/eslint/index.test.ts

@@ -41,6 +41,7 @@ describe('the plugin object', () => {
       'no-handmade-empty-state',
       'no-native-title',
       'no-copied-look',
+      'no-field-outside-a-form',
       'raw-element-outside-a-wrapper',
       'no-hand-rolled-behaviour',
       'component-has-a-page',
@@ -58,12 +59,12 @@ describe('the plugin object', () => {
    * change it deliberately, here.
    */
   it('gives an app only the app rules, as errors, under estiva/', () => {
-    const blocking = { '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' }
+    const blocking = { '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', 'estiva/no-field-outside-a-form': 'error' }
     for (const config of [estiva.configs.recommended, estiva.configs.strict]) expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
     // The copied look warns in recommended (Katerina, 13 September), and strict makes it an error.
     expect(estiva.configs.recommended.rules).toEqual({ ...blocking, 'estiva/no-copied-look': 'warn' })
     expect(estiva.configs.strict.rules).toEqual({ ...blocking, 'estiva/no-copied-look': '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', 'estiva/no-native-title', 'estiva/no-copied-look'])
+    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', 'estiva/no-copied-look', 'estiva/no-field-outside-a-form'])
   })
 
   /**
@@ -154,8 +155,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(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 })
+    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, 'estiva/no-field-outside-a-form': 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, 'estiva/no-field-outside-a-form': none })
   })
 
   it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
@@ -180,6 +181,7 @@ describe('countGates', () => {
         'estiva/no-handmade-empty-state': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-native-title': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-copied-look': { errors: 0, warnings: 0, escapes: 0 },
+        'estiva/no-field-outside-a-form': { errors: 0, warnings: 0, escapes: 0 },
       },
       disabled: [],
     })

package/src/eslint/index.ts

@@ -23,6 +23,7 @@ import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
 import { noHandmadeEmptyState } from './no-handmade-empty-state'
 import { noHandmadeHeader } from './no-handmade-header'
 import { noCopiedLook } from './no-copied-look'
+import { noFieldOutsideAForm } from './no-field-outside-a-form'
 import { noNativeTitle } from './no-native-title'
 import { noRawElement } from './no-raw-element'
 import { noRebuiltBehaviour } from './no-rebuilt-behaviour'
@@ -35,6 +36,7 @@ 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'
 export { MIN_COVER, MIN_SHARED } from './looks-of'
+export { FIELD_PARTS } from './no-field-outside-a-form'
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
@@ -56,6 +58,7 @@ const appRules = {
   'no-handmade-empty-state': noHandmadeEmptyState,
   'no-native-title': noNativeTitle,
   'no-copied-look': noCopiedLook,
+  'no-field-outside-a-form': noFieldOutsideAForm,
 } satisfies Record<AppRuleName, unknown>
 
 /**
@@ -119,6 +122,7 @@ plugin.configs.recommended = {
     [`${PLUGIN_KEY}/no-native-title`]: 'error',
     // A warning, never an error (Katerina, 13 September): likeness is a judgement.
     [`${PLUGIN_KEY}/no-copied-look`]: 'warn',
+    [`${PLUGIN_KEY}/no-field-outside-a-form`]: 'error',
   },
 }
 plugin.configs.strict = {

package/src/eslint/no-field-outside-a-form.test.ts

@@ -0,0 +1,63 @@
+import { mkdirSync, mkdtempSync, 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, it } from 'vitest'
+import { noFieldOutsideAForm } from './no-field-outside-a-form'
+
+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 the app's re-exports are followed to their part, as Peek's are. */
+const root = mkdtempSync(join(tmpdir(), 'no-field-outside-a-form-'))
+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/Field.tsx', "export { Field } from '@estiva-app/ui'\n")
+write('app/src/components/ui/Textarea.tsx', "export { Textarea } from '@estiva-app/ui'\n")
+write('app/src/components/ui/ConfirmDialog.tsx', "export { ConfirmDialog } from '@estiva-app/ui'\n")
+const app = join(root, 'app/src/Probe.tsx')
+
+const ui = (...parts: string[]) => `import { ${parts.join(', ')} } from '@estiva-app/ui'\n`
+const component = (body: string, imports = '') => `${imports}export function Probe({ text, set }: { text: string; set: (v: string) => void }) {\n  return (\n${body}\n  )\n}\n`
+const loose = (part: string) => [{ messageId: 'loose', data: { part } }]
+
+tester.run('no-field-outside-a-form', noFieldOutsideAForm, {
+  valid: [
+    {
+      name: "Peek's ResolveDialog: a DialogShell with a Form",
+      code: component('<DialogShell title="Resolve" onClose={() => {}}>\n<Form onSubmit={() => {}}>\n<Field label="Message"><Textarea value={text} onChange={(e) => set(e.target.value)} /></Field>\n</Form>\n</DialogShell>', ui('DialogShell', 'Form', 'Field', 'Textarea')),
+    },
+    { name: 'a one-line field with its button', code: component('<Form onSubmit={() => {}}><TextInput value={text} onChange={(e) => set(e.target.value)} /></Form>', ui('Form', 'TextInput')) },
+    { name: 'fields drawn from a list, inside the form', code: component("<Form onSubmit={() => {}}>{['a', 'b'].map((k) => <Field key={k} label={k}><TextInput value={text} /></Field>)}</Form>", ui('Form', 'Field', 'TextInput')) },
+    { name: "the palette's form level is a Form (UIG-29)", code: component('<CommandPaletteForm submitLabel="Create" onSubmit={() => {}}><Field label="Title"><TextInput value={text} /></Field></CommandPaletteForm>', ui('CommandPaletteForm', 'Field', 'TextInput')) },
+    { name: 'a field that saves itself as you leave it', code: component('<EditableText value={text} onCommit={set} />', ui('EditableText')) },
+    { name: 'a field that filters a list', code: component('<SearchInput value={text} onChange={set} />', ui('SearchInput')) },
+    {
+      name: "a control handed to a Field from a function of its own: the Field is judged (Peek's ActionFormPanel)",
+      code: `${ui('Field', 'TextInput')}const control = (text: string) => <TextInput value={text} />\nexport function Probe({ text }: { text: string }) {\n  return (\n<>\n{/* @estiva-escape(no-field-outside-a-form): the launcher's CommandPaletteForm holds these fields */}\n<Field label="Title">{control(text)}</Field>\n</>\n  )\n}\n`,
+    },
+    { name: "the app's own component is its own business", code: component('<ResolutionField value={text} />', "import { ResolutionField } from './ResolutionField'\n") },
+    { name: 'an escape with its reason', code: component('<>\n{/* @estiva-escape(no-field-outside-a-form): the caller wraps this in its Form, in StartTopicDialog */}\n<Field label="Title"><TextInput value={text} /></Field>\n</>', ui('Field', 'TextInput')) },
+  ],
+  invalid: [
+    {
+      name: "Peek's ArchiveDialog at peek 3c4b799: a resolution in a ConfirmDialog",
+      filename: app,
+      code: component('<ConfirmDialog title="Archive?" confirmLabel="Archive topic" onClose={() => {}} onConfirm={() => {}}>\n<p>This hides the topic.</p>\n<Field label="Resolution (optional)">\n<Textarea value={text} rows={3} onChange={(e) => set(e.target.value)} />\n</Field>\n</ConfirmDialog>', "import { ConfirmDialog } from '@/components/ui/ConfirmDialog'\nimport { Field } from '@/components/ui/Field'\nimport { Textarea } from '@/components/ui/Textarea'\n"),
+      errors: loose('Field'),
+    },
+    { name: 'a bare text input with no form', code: component('<TextInput value={text} onChange={(e) => set(e.target.value)} />', ui('TextInput')), errors: loose('TextInput') },
+    { name: 'a textarea in a DialogShell with no form', code: component('<DialogShell title="Note" onClose={() => {}}><Textarea value={text} /></DialogShell>', ui('DialogShell', 'Textarea')), errors: loose('Textarea') },
+    { name: 'an escape with no reason is not an escape', code: component('<>\n{/* @estiva-escape(no-field-outside-a-form) */}\n<Field label="Title"><TextInput value={text} /></Field>\n</>', ui('Field', 'TextInput')), errors: [{ messageId: 'escapeWithoutReason' }, ...loose('Field')] },
+  ],
+})

package/src/eslint/no-field-outside-a-form.ts

@@ -0,0 +1,92 @@
+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 a person types into to send something. `Field` is the labelled
+ * row; `TextInput` and `Textarea` are judged on their own only in a file that
+ * draws no `Field`, so a field is reported once, at its label.
+ */
+export const FIELD_PARTS = ['Field', 'TextInput', 'Textarea'] as const
+
+/** The parts that are a `Form`: the package's own, and the palette's form level, which is one (UIG-29). */
+export const FORM_PARTS = ['Form', 'CommandPaletteForm'] 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
+
+/**
+ * A field outside a `Form` (Katerina, 1 October, after Peek's and Ship's
+ * Archive dialog: a resolution typed into a `ConfirmDialog`, sent by its
+ * button, with no form around it — Ctrl+Enter did nothing, and the field
+ * stayed open while it archived).
+ *
+ * `Form` owns what a field needs to be sent: Enter and Ctrl+Enter, `busy`
+ * switching every field off at once, and where focus goes after. A field
+ * outside one has none of it, and the dialog around it is the wrong one: a
+ * question with a field in it is a `DialogShell` with a `Form`
+ * (ConfirmDialog's page, **When not**).
+ *
+ * Judged: a `Field`, a `TextInput` or a `Textarea` of the package (or an
+ * app's re-export or wrapper of one) with no `Form` around it in the same
+ * file. Not judged, on purpose:
+ *
+ * - `EditableText` and `SearchInput`: one saves itself as you leave it, the
+ *   other filters a list, and neither is sent (Form's page, **When not**);
+ * - a `TextInput` or `Textarea` in a file that draws a `Field`: the `Field`
+ *   is reported, and a control handed to it from a function of its own (a
+ *   `switch` over field kinds) cannot be followed to it;
+ * - the app's own components: a component that draws a field for a form its
+ *   caller holds says so with an escape on the field, naming that caller.
+ */
+export const noFieldOutsideAForm: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A field with no Form around it' },
+    schema: [],
+    messages: {
+      loose:
+        '`{{part}}` has no `Form` around it, so nothing owns sending it: Enter and Ctrl+Enter, `busy`, and focus after. Put it in `Form` from @estiva-app/ui; in a dialog, that is `DialogShell` with a `Form`, never `ConfirmDialog` (Primitives/Form says how).',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    const parser = (context.languageOptions?.parser ?? {}) as Parser
+    let locals: Map<string, PartBinding | 'namespace'> | undefined
+    const loose: { opening: Node; part: string }[] = []
+    let drawsAField = false
+    const partOf = (element: Node): string | undefined => {
+      const tag = child(child(element, 'openingElement') as Node, 'name')
+      const name = nameOf(tag)
+      if (!name || /^[a-z]/.test(name)) return undefined
+      const binding = locals && bindingOfTag(tag, locals)
+      return binding && binding.props === 'all' ? binding.part : undefined
+    }
+    return {
+      Program(program) {
+        locals = partsOfFile(context.filename, program as unknown as Node, parser)
+      },
+      JSXElement(ruleNode: Rule.Node) {
+        const element = ruleNode as unknown as Node
+        const part = partOf(element)
+        if (!part || !(FIELD_PARTS as readonly string[]).includes(part)) return
+        if (part === 'Field') drawsAField = true
+        for (let up = element.parent as Node | undefined; up; up = up.parent as Node | undefined) {
+          if (up.type !== 'JSXElement') continue
+          const around = partOf(up)
+          if (around && (FORM_PARTS as readonly string[]).includes(around)) return
+          if (around === 'Field') return
+        }
+        loose.push({ opening: child(element, 'openingElement') as Node, part })
+      },
+      'Program:exit'() {
+        for (const { opening, part } of loose) {
+          if (part !== 'Field' && drawsAField) continue
+          if (isEscaped(context, opening)) continue
+          context.report({ loc: opening.loc as NonNullable<Rule.Node['loc']>, messageId: 'loose', data: { part } })
+        }
+      },
+    }
+  },
+}

package/src/eslint/rule-ids.ts

@@ -21,6 +21,7 @@ export const APP_RULE_NAMES = [
   'no-handmade-empty-state',
   'no-native-title',
   'no-copied-look',
+  'no-field-outside-a-form',
 ] as const
 
 export type AppRuleName = (typeof APP_RULE_NAMES)[number]

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

@@ -72,7 +72,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 }, { 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 }, { 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]*run: npx estiva-gates ci/)
     expect(files['docs/GATES-DEBT.md']).toContain('Nothing.')
   })

package/src/gates/gates.test.ts

@@ -194,7 +194,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', 'estiva/no-native-title', 'estiva/no-copied-look'])
+    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', 'estiva/no-copied-look', 'estiva/no-field-outside-a-form'])
 
     expect((await writeGateCount({ root: dir, repo: 'probe' })).changed).toBe(false)