@estiva-app/ui 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "default": "./dist/eslint/index.js"
+    },
     "./tailwind-preset": "./tailwind-preset.js",
     "./tokens.css": "./tokens.css",
     "./package.json": "./package.json",
@@ -32,7 +36,11 @@
     "test:watch": "vitest --project unit",
     "test:a11y": "vitest run --project storybook-signal --project storybook-ship",
     "typecheck": "tsc --noEmit",
+    "prelint": "node build.mjs",
     "lint": "eslint .",
+    "prelint:rules": "node build.mjs",
+    "lint:rules": "eslint --config eslint.gates.config.js .",
+    "postlint:rules": "node scripts/gates-count.mjs",
     "gates:status": "node scripts/gates-status.mjs",
     "prepublishOnly": "npm run build"
   },

package/src/Avatar.tsx

@@ -118,7 +118,7 @@ export function Avatar({ src, name, alt = '', size = 36, label: spoken, classNam
           */
           className="w-full h-full flex items-center justify-center font-semibold leading-none"
           style={{
-            /* eslint-disable no-restricted-syntax -- the per-person palette (the note at
+            /* eslint-disable no-restricted-syntax -- @estiva-escape: the per-person palette (the note at
                the top): eight hues picked from the name, the one ink that reads on all
                of them, and a size that follows `size`. None of it can be a token. */
             // The one ink colour that reads on all eight hues, which are a

package/src/AvatarGroup.tsx

@@ -55,7 +55,7 @@ export function AvatarGroup({ members, size = 24 }: AvatarGroupProps) {
         <span
           key={i}
           className="relative flex rounded-sm"
-          /* eslint-disable-next-line no-restricted-syntax -- the ring's width is the `ring` prop, so it cannot be a class; its colour is the surface token */
+          /* eslint-disable-next-line no-restricted-syntax -- @estiva-escape: the ring's width is the `ring` prop, so it cannot be a class; its colour is the surface token */
           style={{ marginRight: -overlap, boxShadow: `0 0 0 ${ring}px var(--bg-surface)` }}
         >
           {/* Each face says whose it is: a stack stands on its own, with no

package/src/Breadcrumb.tsx

@@ -1,5 +1,6 @@
 import { Fragment, useCallback, useLayoutEffect, useRef, useState, type MouseEventHandler, type ReactNode } from 'react'
 import { cn } from './cn'
+import { Link } from './Link'
 import { WithTooltip } from './Tooltip'
 
 /**
@@ -88,9 +89,12 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
           labelRefs.current[index] = el
         }
         const crumb = item.href ? (
-          <a ref={setLabelRef} href={item.href} onClick={item.onClick} className={cn(text, 'hover:text-text-primary')}>
+          // `plain` adds no look of its own: a crumb keeps the trail's size and
+          // tone, and brightens on hover. The package's own Link, so a trail
+          // follows whatever a link learns to do (UIG-5).
+          <Link ref={setLabelRef} variant="plain" href={item.href} onClick={item.onClick} className={cn(text, 'hover:text-text-primary')}>
             {item.label}
-          </a>
+          </Link>
         ) : (
           <span ref={setLabelRef} className={text} aria-current={last ? 'page' : undefined}>
             {item.label}

package/src/ChipInput.mdx

@@ -65,6 +65,15 @@ import { ChipInput } from '@estiva-app/ui'
 <ChipInput aria-labelledby="to-label" value={chosen} onChange={setChosen} options={directory} />
 ```
 
+- **`InputChip` on its own** names its ✕ `Remove <label>`. Where the ✕ does
+  something else, say what with `removeLabel` (a scope chip: "Leave Ship").
+- To cap a long label, give the chip a `max-w-*` and `truncate`: the label is
+  cut and the ✕ keeps its size. `truncate` is off unless asked, because
+  cutting clips a letter's soft edge by up to 4px at 1x even when the label
+  fits.
+
+<Canvas of={ChipInputStories.ALongLabelCut} />
+
 ## Keys
 
 | Input | What happens |

package/src/ChipInput.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { useState } from 'react'
+import { IconSquareRounded } from '@tabler/icons-react'
 import { Avatar } from './Avatar'
 import { ChipInput, InputChip, type ChipInputOption } from './ChipInput'
 
@@ -97,3 +98,20 @@ export const TheChipItself: Story = {
     </div>
   ),
 }
+
+/** A chip capped in width, its long label cut, and a ✕ named for what it does. */
+export const ALongLabelCut: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <InputChip
+        label="A label much longer than the chip may be"
+        leading={<IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />}
+        onRemove={() => {}}
+        removeLabel="Leave the label"
+        truncate
+        className="max-w-44"
+      />
+    </div>
+  ),
+}

package/src/ChipInput.test.tsx

@@ -215,4 +215,22 @@ describe('InputChip', () => {
     render(<InputChip label="Label" />)
     expect(screen.queryByRole('button')).toBeNull()
   })
+
+  it('names its ✕ with removeLabel when given', async () => {
+    const user = userEvent.setup()
+    const onRemove = vi.fn()
+    render(<InputChip label="Label" onRemove={onRemove} removeLabel="Leave Label" />)
+    await user.click(screen.getByRole('button', { name: 'Leave Label' }))
+    expect(onRemove).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('button', { name: 'Remove Label' })).toBeNull()
+  })
+
+  it('cuts its label only when asked, and then the ✕ never gives way', () => {
+    const { rerender } = render(<InputChip label="Label" onRemove={() => {}} />)
+    expect(screen.getByText('Label').className).not.toMatch(/\btruncate\b/)
+    expect(screen.getByRole('button').className).not.toMatch(/\bshrink-0\b/)
+    rerender(<InputChip label="Label" onRemove={() => {}} truncate className="max-w-[160px]" />)
+    expect(screen.getByText('Label').className).toMatch(/\bmin-w-0\b.*\btruncate\b/)
+    expect(screen.getByRole('button').className).toMatch(/\bshrink-0\b/)
+  })
 })

package/src/ChipInput.tsx

@@ -38,14 +38,27 @@ export interface InputChipProps {
   leading?: ReactNode
   /** Draws the ✕; absent, the chip is display-only. */
   onRemove?: () => void
+  /**
+   * The ✕'s name for a screen reader. `Remove <label>` when not given. A chip
+   * whose ✕ does something other than remove it names what it does — a
+   * launcher's scope chip leaves the scope ("Leave Ship").
+   */
+  removeLabel?: string
+  /**
+   * Cut a long label with an ellipsis once the chip is capped, by a
+   * `max-w-*` on `className`. Off unless asked: cutting clips up to 4px of a
+   * letter's soft edge at 1x even when the label fits (measured 2026-09-15),
+   * so a chip that is never capped keeps every pixel.
+   */
+  truncate?: boolean
   className?: string
 }
 
-export function InputChip({ label, leading, onRemove, className }: InputChipProps) {
+export function InputChip({ label, leading, onRemove, removeLabel, truncate, className }: InputChipProps) {
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>
       {leading && <span className="flex shrink-0 items-center">{leading}</span>}
-      <span className={CHIP_LABEL}>{label}</span>
+      <span className={cn(CHIP_LABEL, truncate && 'min-w-0 truncate')}>{label}</span>
       {/* Base UI's `Button`, as every button in the package is (D6). Base UI
           has no chip of its own — its only chips are `Combobox.Chip` and
           `ChipRemove`, which throw outside a combobox — so the ✕ is the one
@@ -57,8 +70,9 @@ export function InputChip({ label, leading, onRemove, className }: InputChipProp
             e.stopPropagation()
             onRemove()
           }}
-          className={CHIP_REMOVE}
-          aria-label={`Remove ${label}`}
+          // In a capped chip the label gives way, never the ✕.
+          className={cn(CHIP_REMOVE, truncate && 'shrink-0')}
+          aria-label={removeLabel ?? `Remove ${label}`}
         >
           <IconX size={10} stroke={1.5} />
         </BaseButton>

package/src/CommandPalette.mdx

@@ -0,0 +1,133 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as CommandPaletteStories from './CommandPalette.stories'
+
+<Meta of={CommandPaletteStories} />
+
+# CommandPalette
+
+A window that searches and runs things: a field, rows in groups, and a footer
+naming the keys that work right now. It shows one level at a time — rows, or a
+form — and the app keeps the levels.
+
+<Canvas of={CommandPaletteStories.FirstLevel} />
+
+## When
+
+- **One place to find something and act on it**, from anywhere in an app,
+  opened by a shortcut the app binds.
+- **`CommandPaletteSearch`** — a level of rows. Without a `chip` it is the
+  first level; with one, you are inside something, and the chip names it.
+- **`CommandPaletteForm`** — a level that is a form: what a row creates or
+  changes, without leaving the palette.
+- **`CommandPaletteWorking`, `CommandPaletteAnswer`, `CommandPaletteQuote`** —
+  above the rows, for a result that is written rather than listed: a line while
+  it is on its way, an answer with marks pointing at the rows it came from, and
+  text written to be used somewhere else.
+
+<Canvas of={CommandPaletteStories.Answer} />
+
+<Canvas of={CommandPaletteStories.Form} />
+
+## When not
+
+- A short list of verbs from a trigger → **Menu**.
+- One value for a field → **Select**; several → **ChipInput**.
+- A form with a title and buttons of its own, not reached from a palette →
+  **DialogShell**. The palette is not built on it: a palette has no title bar,
+  no close button and no button row, and on the shell it would be the shell with
+  every slot switched off.
+- Filtering a list that stays on the page → **SearchInput**.
+
+## How
+
+```tsx
+import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
+
+<CommandPalette open={open} onOpenChange={setOpen} label="Command palette" where="In Item one" modKey="Ctrl">
+  <CommandPaletteSearch
+    query={query}
+    onQueryChange={setQuery}
+    placeholder="Search, or choose a place"
+    groups={[
+      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: open, onForget: forget }] },
+      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon, onSelect: goIn, onGoIn: goIn }] },
+    ]}
+  />
+</CommandPalette>
+```
+
+- **The app opens it.** The palette listens to nothing outside its own window:
+  bind the shortcut in the app, pass `open`, and give `modKey` the platform's
+  spelling (`Cmd` on a Mac). The keys answer to Ctrl and Cmd either way.
+- **One level at a time, and the app keeps the stack.** Render a
+  `CommandPaletteSearch` or a `CommandPaletteForm` as the only child, and keep
+  each level's query yourself, so going back puts back the text that was there.
+  A level inside another passes `chip` — its label, and `onBack`.
+- **A row says what it can do, and the keys and the footer follow.** `onSelect`
+  is Enter and a click. `onGoIn` makes Tab, and → at the end of the text, go in,
+  and draws the chevron. `onForget` makes Ctrl+Backspace forget it — for rows
+  that are the person's own history. The footer names only what the lit row
+  answers to.
+- **`icon` sits on the row's 32px tile; `leading` takes the same 32px with no
+  tile**, for something with a look of its own — a face, a status mark.
+- **`id` is unique in the level.** The lit row is followed by it, so a caller
+  that builds its rows again on every render still runs the handler of the row
+  on screen.
+- **`pending` while rows are still on their way; `empty` only once none are.**
+  Pass `empty` while a search is running and the page says "nothing" before it
+  knows.
+- **Rows that arrive late do not take the highlight.** Base UI keeps the
+  highlight's position rather than its row, so a group arriving above the lit
+  row would hand the highlight — and Enter — to something else. The palette
+  walks it back to the row you had. Typing starts again from the first row.
+- **Home and End move the text cursor, and nothing else.** Base UI would also
+  send the highlight to the first or last row; the palette stops that.
+- **The field is named by its placeholder**, so say what it asks for.
+- **A form's fields go in `Field`s.** Mark the missing ones with `error` inside
+  `onSubmit`, and the first of them takes focus. `working` locks the fields,
+  puts its words on the button and beside it, and holds focus on the form so
+  Esc still closes it; when it clears, focus goes to the first field that needs
+  something, or back where it was. `error` is what went wrong, beside the
+  button. `submitWaits` says why there is nothing to submit yet, on the button,
+  and Ctrl+Enter does nothing until it clears.
+- **Focus never falls out of a level.** When the element that had it goes — a
+  row picked, a level swapped — focus goes to the level's first control.
+
+## Keys
+
+| Where | Input | What happens |
+|---|---|---|
+| a level of rows | ↑ / ↓ | move between rows, and stop at the ends |
+| | Enter, or a click | what the lit row does |
+| | Tab | goes in, on a row that leads somewhere; anywhere else nothing, and focus stays in the field |
+| | → at the end of the text | goes in, on a row that leads somewhere; anywhere else it moves the cursor |
+| | Ctrl+Backspace | forgets the lit row, if it can be forgotten; otherwise deletes a word |
+| | Home / End | move the text cursor; the lit row stays |
+| inside a level | Backspace at the start of the field, or the chip's ✕ | back, with focus in the field |
+| a form | Tab / Shift+Tab | between the fields, never out of the window |
+| | Ctrl+Enter | submits; if a field needs something, focus goes to the first |
+| | Backspace in an empty text field | back. In a form that is one list, Backspace anywhere; in a list inside a form with text fields, nothing |
+| | while working | nothing but Esc |
+| | Esc in an open list | closes the list first |
+| anywhere | Esc, or a click outside | closes; focus returns to whatever opened it |
+
+## Props
+
+<Controls of={CommandPaletteStories.FirstLevel} />
+
+**`CommandPaletteSearch`** — `query` and `onQueryChange` (the field, controlled),
+`placeholder` (also the field's name), `groups` (`{ label, rows }`, a group
+with no rows is not drawn), `chip?` (`{ label, leading?, onBack }`), `pending?`,
+`empty?`, and `children` for what sits above the rows.
+
+**A row** — `id`, `label`, `description?`, `icon?` or `leading?`, `onSelect`,
+`onGoIn?`, `onForget?`.
+
+**`CommandPaletteForm`** — `chip`, `icon?`, `submitLabel`, `onSubmit`,
+`submitWaits?`, `working?` (`{ button, line }`), `error?`, and the fields as
+`children`.
+
+**`CommandPaletteWorking`** — the words as `children`, `bars?` (0–3, default 2).
+**`CommandPaletteAnswer`** — the text as `children` (a blank line starts a
+paragraph; `[1]` is a mark), `note?`. **`CommandPaletteQuote`** — the text as
+`children`, line breaks kept.