@estiva-app/ui 0.16.1 → 0.18.0

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

@@ -0,0 +1,180 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+interface JSXAttributeValue {
+  type: string
+  value?: unknown
+  expression?: { type: string; value?: unknown; expressions?: unknown[]; quasis?: { value: { cooked: string | null } }[] }
+}
+
+interface JSXAttribute {
+  type: 'JSXAttribute'
+  name: { type: string; name?: string }
+  value: JSXAttributeValue | null
+}
+
+interface JSXOpeningElement {
+  name: { type: string; name?: string }
+  attributes: (JSXAttribute | { type: 'JSXSpreadAttribute' })[]
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+}
+
+/**
+ * What the package has instead of one raw element: the component the message
+ * names, and where one element does more than one job, the others after it.
+ * `null` is an element the package has no part for yet.
+ */
+export interface RawElementPart {
+  use: string
+  more?: string
+}
+
+/**
+ * The mapping (UIG-7), derived from the package's exports: every interactive
+ * element in the HTML standard's list ("interactive content"), plus `<dialog>`,
+ * `<form>` and `<progress>`, which have a part here. docs/GATES.md prints it.
+ *
+ * Not here, on purpose: `<summary>` (it lives inside a `<details>`, which is
+ * reported), `<option>`, `<optgroup>` and `<datalist>` (they live inside a
+ * `<select>` or beside an input), `<fieldset>` and `<legend>` (a group's frame,
+ * no control of its own), and `<img>` without `usemap`, `<hr>`, `<kbd>`, which
+ * are not controls. An `<audio>` or `<video>` is a control only with `controls`.
+ */
+export const RAW_ELEMENT_PARTS: Record<string, RawElementPart | null> = {
+  a: { use: 'Link', more: ' For a chip, `InlineChip`; for a whole card, `Card` with `href`.' },
+  button: { use: 'Button' },
+  textarea: { use: 'Textarea' },
+  select: { use: 'Select' },
+  dialog: { use: 'DialogShell', more: ' To ask yes or no, `ConfirmDialog`.' },
+  label: { use: 'Field', more: ' For words beside a tick box, `Checkbox` with `label`.' },
+  details: { use: 'CollapsibleSection' },
+  progress: { use: 'ProgressBar' },
+  form: { use: 'Form' },
+  meter: null,
+  iframe: null,
+  embed: null,
+  object: null,
+  audio: null,
+  video: null,
+  img: null,
+}
+
+/**
+ * An `<input>` is as many controls as its `type`. A type missing from here
+ * (text, email, password, url, tel, number, or one the browser does not know)
+ * is a text box.
+ */
+export const RAW_INPUT_PARTS: Record<string, RawElementPart | null> = {
+  search: { use: 'SearchInput' },
+  checkbox: { use: 'Checkbox' },
+  file: { use: 'FilePicker' },
+  submit: { use: 'Button' },
+  button: { use: 'Button' },
+  reset: { use: 'Button' },
+  image: { use: 'Button' },
+  radio: null,
+  range: null,
+  color: null,
+  date: null,
+  'datetime-local': null,
+  month: null,
+  week: null,
+  time: null,
+}
+
+const TEXT_INPUT: RawElementPart = { use: 'TextInput' }
+const ANY_INPUT: RawElementPart = {
+  use: 'TextInput',
+  more: ' For a search, `SearchInput`; for a tick box, `Checkbox`; to pick files, `FilePicker`.',
+}
+
+function attribute(element: JSXOpeningElement, name: string): JSXAttribute | undefined {
+  return element.attributes.find((a): a is JSXAttribute => a.type === 'JSXAttribute' && a.name.name === name)
+}
+
+/** An attribute's value when the code spells it out, `undefined` when it is computed. */
+function literal(attr: JSXAttribute): string | boolean | undefined {
+  const value = attr.value
+  if (value === null) return true
+  if (value.type === 'Literal') return typeof value.value === 'string' ? value.value : undefined
+  if (value.type !== 'JSXExpressionContainer' || !value.expression) return undefined
+  const expression = value.expression
+  if (expression.type === 'Literal' && (typeof expression.value === 'string' || typeof expression.value === 'boolean')) return expression.value
+  if (expression.type === 'TemplateLiteral' && expression.expressions?.length === 0) return expression.quasis?.[0]?.value.cooked ?? undefined
+  return undefined
+}
+
+/** Present, and not written as `={false}`. */
+function isOn(element: JSXOpeningElement, name: string): boolean {
+  const attr = attribute(element, name)
+  return attr !== undefined && literal(attr) !== false
+}
+
+type Found = { report: 'raw'; element: string; part: RawElementPart } | { report: 'noPart'; element: string } | null
+
+/** What this element is to the rule: a raw element with a part, one with none yet, or none of its business. */
+export function classify(element: JSXOpeningElement): Found {
+  if (element.name.type !== 'JSXIdentifier' || !element.name.name) return null
+  const name = element.name.name
+
+  if (name === 'input') {
+    const attr = attribute(element, 'type')
+    const type = attr ? literal(attr) : 'text'
+    if (typeof type !== 'string') return { report: 'raw', element: '<input>', part: ANY_INPUT }
+    const key = type.toLowerCase()
+    // A hidden input draws nothing and takes no focus: it is data, not a control.
+    if (key === 'hidden') return null
+    if (!(key in RAW_INPUT_PARTS)) return { report: 'raw', element: '<input>', part: TEXT_INPUT }
+    const part = RAW_INPUT_PARTS[key]
+    const shown = `<input type="${key}">`
+    return part ? { report: 'raw', element: shown, part } : { report: 'noPart', element: shown }
+  }
+
+  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) return null
+  if ((name === 'audio' || name === 'video') && !isOn(element, 'controls')) return null
+  if (name === 'img' && !attribute(element, 'usemap') && !attribute(element, 'useMap')) return null
+
+  const part = RAW_ELEMENT_PARTS[name]
+  return part ? { report: 'raw', element: `<${name}>`, part } : { report: 'noPart', element: `<${name}>` }
+}
+
+/**
+ * A raw interactive element in an app, where the package has a part for it
+ * (UIG-3 began it with `<button>`; UIG-7 made it every element). A control
+ * the app writes itself has a look, a focus ring and keys that nobody else
+ * keeps in step with — and it looks nearly right, which is why nobody catches
+ * it by eye. Every message names the part to use.
+ *
+ * An element the package has no part for yet is refused too, with a message
+ * that says so: the part is made in the package, not by hand in an app
+ * (Katerina, 16 September).
+ *
+ * Only a JSX element written with a lowercase name. `<Button>`,
+ * `<Foo.button>` and `createElement('button')` are not this rule's business.
+ */
+export const noRawElement: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A raw interactive element where @estiva-app/ui has a part, or where it needs one' },
+    schema: [],
+    messages: {
+      raw: 'Use `{{use}}` from @estiva-app/ui instead of a raw {{element}}.{{more}}',
+      noPart: '@estiva-app/ui has no part for a raw {{element}} yet. Do not build one here: ask Katerina, and it gets made in @estiva-app/ui.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      // ESLint's types know ESTree's nodes, not JSX's; the parser hands this one over.
+      JSXOpeningElement(node: Rule.Node) {
+        const element = node as unknown as JSXOpeningElement
+        const found = classify(element)
+        if (!found) return
+        if (isEscaped(context, element)) return
+        if (found.report === 'noPart') context.report({ loc: element.loc, messageId: 'noPart', data: { element: found.element } })
+        else context.report({ loc: element.loc, messageId: 'raw', data: { element: found.element, use: found.part.use, more: found.part.more ?? '' } })
+      },
+    }
+  },
+}

package/src/formBusy.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Whether a `Form` around this is busy (UIG-7).
+ *
+ * `Form` switches its children off with a disabled `<fieldset>`, which the
+ * browser applies to every native control inside — but a part that draws its
+ * look from Base UI's own `disabled` (Button, IconButton, Checkbox) is not
+ * told, so it kept its normal look while it could not be pressed, and a
+ * Checkbox, which is a `<span>`, could still be ticked (Katerina saw the busy
+ * story's button unchanged, 16 September). Those parts read this and switch
+ * off the way their own `disabled` does. Not exported: it is the package's
+ * wiring between Form and its parts.
+ */
+export const FormBusyContext = createContext(false)
+
+export function useFormBusy(): boolean {
+  return useContext(FormBusyContext)
+}

package/src/index.ts

@@ -50,6 +50,8 @@ export { Kbd, type KbdProps } from './Kbd'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'
 export { Tooltip, TooltipProvider, WithTooltip, type TooltipProps, type TooltipProviderProps, type WithTooltipProps } from './Tooltip'
 export { Field, FieldLine, type FieldLineProps, type FieldLineTone, type FieldProps } from './Field'
+export { FilePicker, type FilePickerProps } from './FilePicker'
+export { Form, type FormProps } from './Form'
 export { Select, type SelectOption, type SelectProps } from './Select'
 export { TextInput, type TextInputProps } from './TextInput'
 export { Textarea, type TextareaProps } from './Textarea'

package/stories/Choosing.mdx

@@ -25,6 +25,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | One value for a form field | **Select** | a Menu — Select's trigger shows the value |
 | Several values, typed then removable | **ChipInput** | checkboxes in a Menu |
 | Yes or no | **Checkbox** | a toggle we don't have |
+| Yes or no, with words beside it that toggle it too | **Checkbox** `label` | words written beside it by hand — they name nothing and toggle nothing |
 | Switching between views of one thing | **Tabs** | a row of Buttons |
 | View options behind a `…` | **Menu**, `selected` on the current row | Select |
 | Rows of checkboxes that stay open | a list in a **DialogShell** | a Menu — a Checkbox inside a `menuitem` is invalid HTML |
@@ -39,6 +40,8 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | Typing that filters a list | **SearchInput** |
 | A title edited in place | **EditableText** |
 | Label and required-mark around any control | **Field** |
+| The fields and the button that sends them | **Form** — Enter sends; `busy` switches everything inside off while it waits |
+| A button that opens the file picker | **FilePicker**, opened by your own **Button** or **IconButton** |
 | A hint or a failure under **one** control | **Field**'s `helper` / `error` — wired to it, and announced |
 | A hint or an outcome under a **group** of controls | **FieldLine** — the same line on its own, with a `warning` tone Field has not got |
 

package/dist/eslint/no-raw-button.d.ts

@@ -1,11 +0,0 @@
-import type { Rule } from 'eslint';
-/**
- * A raw `<button>` in an app (UIG-3, the tracer). The package's `Button`,
- * `IconButton`, `MenuItem` and chips are buttons already; an app that writes
- * its own has a look and a behaviour nobody else keeps in step with.
- *
- * Only the JSX element named `button`. `<Button>`, `<Foo.button>` and
- * `createElement('button')` are not this rule's business.
- */
-export declare const noRawButton: Rule.RuleModule;
-//# sourceMappingURL=no-raw-button.d.ts.map

package/dist/eslint/no-raw-button.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"no-raw-button.d.ts","sourceRoot":"","sources":["../../src/eslint/no-raw-button.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AASlC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,IAAI,CAAC,UAqB9B,CAAA"}

package/src/eslint/no-raw-button.ts

@@ -1,39 +0,0 @@
-import type { Rule } from 'eslint'
-import { ESCAPE_MESSAGES, isEscaped } from './escape'
-
-interface JSXOpeningElement {
-  name: { type: string; name?: string }
-  loc: NonNullable<Rule.Node['loc']>
-  range: [number, number]
-}
-
-/**
- * A raw `<button>` in an app (UIG-3, the tracer). The package's `Button`,
- * `IconButton`, `MenuItem` and chips are buttons already; an app that writes
- * its own has a look and a behaviour nobody else keeps in step with.
- *
- * Only the JSX element named `button`. `<Button>`, `<Foo.button>` and
- * `createElement('button')` are not this rule's business.
- */
-export const noRawButton: Rule.RuleModule = {
-  meta: {
-    type: 'problem',
-    docs: { description: 'A raw <button> where @estiva-app/ui has one' },
-    schema: [],
-    messages: {
-      raw: 'Use `Button` from @estiva-app/ui instead of a raw <button>.',
-      ...ESCAPE_MESSAGES,
-    },
-  },
-  create(context) {
-    return {
-      // ESLint's types know ESTree's nodes, not JSX's; the parser hands this one over.
-      JSXOpeningElement(node: Rule.Node) {
-        const element = node as unknown as JSXOpeningElement
-        if (element.name.type !== 'JSXIdentifier' || element.name.name !== 'button') return
-        if (isEscaped(context, element)) return
-        context.report({ loc: element.loc, messageId: 'raw' })
-      },
-    }
-  },
-}