@estiva-app/ui 0.15.0 → 0.16.0

package/src/eslint/raw-element-outside-a-wrapper.test.ts

@@ -0,0 +1,82 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { rawElementOutsideAWrapper } from './raw-element-outside-a-wrapper'
+
+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() {\n  return (\n${body}\n  )\n}\n`
+
+tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
+  valid: [
+    // The two shapes the package is built out of.
+    { name: "the component's own outermost element, as NavItem is an <a>", code: component('    <a href="/x">Issues</a>') },
+    { name: "the component's own element with children inside it", code: component('    <a href="/x">\n      <span>Issues</span>\n    </a>') },
+    {
+      name: 'either branch of a component that returns one element or another, as EditableText does',
+      code: 'export function Probe({ editing }: { editing: boolean }) {\n  if (editing) return <input aria-label="x" />\n  return <button type="button">x</button>\n}\n',
+    },
+    {
+      name: 'handed to a Base UI render prop, as Menu.Item does',
+      code: component('    <BaseMenu.Item render={<button type="button" />} className="row" />'),
+    },
+    {
+      name: 'handed to a render prop while nested, as a part inside a part',
+      code: component('    <BaseMenu.Positioner>\n      <BaseMenu.Item render={<button type="button" />} />\n    </BaseMenu.Positioner>'),
+    },
+    { name: 'a component, not an element', code: component('    <div>\n      <Button>Save</Button>\n    </div>') },
+    { name: 'layout inside a component', code: component('    <div>\n      <span>Issues</span>\n    </div>') },
+    {
+      name: 'a nested element with its reason on the line above',
+      code: component('    <div>\n      {/* @estiva-escape: the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
+    },
+  ],
+  invalid: [
+    {
+      name: 'an anchor buried in a component, as the breadcrumb trail had',
+      code: component('    <div>\n      <a href="/x">Issues</a>\n    </div>'),
+      errors: [{ messageId: 'nested', data: { name: 'a' } }],
+    },
+    {
+      name: 'a button buried in a component, as the toast had',
+      code: component('    <div>\n      <p>Saved</p>\n      <button type="button">Undo</button>\n    </div>'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'inside a fragment, which is several children rather than one element',
+      code: component('    <>\n      <span>x</span>\n      <input aria-label="x" />\n    </>'),
+      errors: [{ messageId: 'nested', data: { name: 'input' } }],
+    },
+    {
+      name: 'inside a component of the package, which is not a render prop',
+      code: component('    <Card>\n      <button type="button">x</button>\n    </Card>'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'nested inside an element that was itself handed to a render prop',
+      code: component('    <BaseMenu.Item render={<div><button type="button" /></div>} />'),
+      errors: [{ messageId: 'nested', data: { name: 'button' } }],
+    },
+    {
+      name: 'a reason too short to be a reason',
+      code: component('    <div>\n      {/* @estiva-escape: short */}\n      <a href="/x">Issues</a>\n    </div>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'nested', data: { name: 'a' } }],
+    },
+    {
+      name: 'an eslint-disable instead of a reason',
+      // The tester runs the rule under its bare name; in a real lint the plugin
+      // prefixes it, and `isEscaped` compares against whichever the rule has.
+      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape: the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
+      // The directive silences the rule's own report, which is exactly why it is
+      // refused: `countGates` sees the silenced report and the gate fails on it.
+      errors: [{ messageId: 'escapeInDirective' }],
+    },
+  ],
+})

package/src/eslint/raw-element-outside-a-wrapper.ts

@@ -0,0 +1,85 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+interface JSXOpeningElement {
+  type: string
+  name: { type: string; name?: string }
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+  parent?: Parent
+}
+
+interface Parent {
+  type: string
+  name?: { name?: string }
+  openingElement?: unknown
+  parent?: Parent
+}
+
+/**
+ * The elements this package writes by hand. The set the count used (UIG-1,
+ * docs/GATES.md §5 and §7): every element that carries behaviour or a role of
+ * its own. A `div` or a `span` is layout and is nobody's business here.
+ */
+export const RAW_ELEMENTS = new Set(['a', 'button', 'input', 'textarea', 'select', 'dialog', 'form', 'label'])
+
+/**
+ * A raw element nested inside another element, in the package itself (UIG-5,
+ * the inward tracer).
+ *
+ * The package is allowed to write raw elements — that is what a primitive is.
+ * Two shapes are right, and both are facts about the code rather than a
+ * judgement:
+ *
+ * - **the component's own outermost element.** `NavItem` is an `<a>`, `Link` is
+ *   an `<a>`, a `MenuItem` outside a `Menu` is a `<button>`. A primitive owning
+ *   its element is the whole point of it.
+ * - **handed to a Base UI `render` prop.** `render={<button type="button" />}`
+ *   tells a Base UI part which element to be; the behaviour stays Base UI's.
+ *
+ * Anything else is an element buried inside a bigger component, where its look
+ * and its behaviour are kept in step by nobody — the package's own version of
+ * the rule the apps get from UIG-3 and UIG-7.
+ *
+ * It keeps its reason on the line above if it stays: `// @estiva-escape: <why>`.
+ */
+export const rawElementOutsideAWrapper: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A raw element nested inside a component, rather than the component itself' },
+    schema: [],
+    messages: {
+      nested:
+        'A raw <{{name}}> inside another element. In this package a raw element is either the component\'s own outermost element or handed to a Base UI `render` prop; one buried inside belongs in a component of its own (Link, Button, MenuItem...).',
+      ...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 name = element.name.name
+        if (element.name.type !== 'JSXIdentifier' || !name || !RAW_ELEMENTS.has(name)) return
+
+        // An opening tag's own parent is its JSXElement: that is this element,
+        // not an element around it.
+        let parent = element.parent
+        if (parent?.type === 'JSXElement' && parent.openingElement === (element as unknown)) parent = parent.parent
+
+        // Whichever comes first going outward decides: an element around it
+        // means it is nested; a `render` prop means Base UI draws it.
+        for (let p = parent; p; p = p.parent) {
+          if (p.type === 'JSXAttribute') {
+            if (p.name?.name === 'render') return
+            continue
+          }
+          if (p.type !== 'JSXElement' && p.type !== 'JSXFragment') continue
+          if (isEscaped(context, element)) return
+          context.report({ loc: element.loc, messageId: 'nested', data: { name } })
+          return
+        }
+      },
+    }
+  },
+}

package/src/index.ts

@@ -18,6 +18,23 @@ export { Button, type ButtonProps, type ButtonSize, type ButtonVariant } from '.
 export { Card, type CardAttention, type CardFill, type CardHover, type CardProps } from './Card'
 export { Checkbox, type CheckboxProps } from './Checkbox'
 export { Chip, type ChipProps, type ChipType } from './Chip'
+export {
+  CommandPalette,
+  CommandPaletteAnswer,
+  CommandPaletteForm,
+  CommandPaletteQuote,
+  CommandPaletteSearch,
+  CommandPaletteWorking,
+  type CommandPaletteAnswerProps,
+  type CommandPaletteChip,
+  type CommandPaletteFormProps,
+  type CommandPaletteGroup,
+  type CommandPaletteProps,
+  type CommandPaletteQuoteProps,
+  type CommandPaletteRow,
+  type CommandPaletteSearchProps,
+  type CommandPaletteWorkingProps,
+} from './CommandPalette'
 export { ChipInput, InputChip, type ChipInputOption, type ChipInputProps, type InputChipProps } from './ChipInput'
 export {
   INLINE_CHIP_CLASSES,

package/stories/Choosing.mdx

@@ -62,6 +62,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A hint on hover or on keyboard focus | **Tooltip** / **WithTooltip** — one `TooltipProvider` at the app root shares the delay |
 | A strip of controls that act on one thing | **Toolbar** — one Tab stop for the row, arrow keys along it |
 | Reactions to choose from | **ReactionPicker** — the row; **Reaction** is the pill it produces |
+| One window to find something and act on it, opened by a shortcut | **CommandPalette** — rows, forms and written answers, one level at a time |
 | Anything with a title, body and footer | **DialogShell** |
 | "Are you sure?" | **ConfirmDialog** |