@estiva-app/ui 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.18.0",
+  "version": "0.19.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/src/Checkbox.mdx

@@ -27,9 +27,18 @@ the parent owns the state.
 
 <Canvas of={CheckboxStories.WithLabel} />
 
+- A list you tick several from, where the whole row is the target: pass
+  **`row`**, with `label` and, if the row has one, a `leading` picture. The
+  box sits at the end, and the row fills on hover and while checked.
+
+<Canvas of={CheckboxStories.Row} />
+
 ## When not
 
 - One choice out of several → **Select** (a value) or **Tabs** (a view).
+- A row drawn by hand with `role="option"` and a Checkbox picture inside it: it
+  tells a screen reader "an option in a list" where there is no list. That is
+  `row`.
 - Inside a **Menu** — a checkbox inside a `menuitem` is invalid HTML;
   a checkable list lives in a DialogShell.
 
@@ -56,6 +65,16 @@ import { Checkbox } from '@estiva-app/ui'
   the box. When disabled, only the box shows it; the words keep their colour
   and lose the pointer. It is a field of its own, so it does not go inside a
   **Field**.
+- With `row` it is the same `Field`, its `Field.Label` the whole row:
+  `leading`, 12px, the words in `body-2` (cut off with an ellipsis when too
+  long), the box at the end; 40px tall, 12px in from each side, 8px corners.
+  It needs `onChange`: without one, `row` is ignored. Put the rows in a
+  column with `gap-0.5`.
+
+```tsx
+<Checkbox row leading={<IconSquareRounded size={16} stroke={1.5} />} label="Item one" checked={on} onChange={setOn} />
+```
+
 - Inside a busy **Form** it is disabled, and looks it.
 - It does not move when it toggles: the tick is always in the box, hidden
   when unchecked, so both states hang on a line of text the same way.
@@ -64,7 +83,7 @@ import { Checkbox } from '@estiva-app/ui'
 
 | Key | Does |
 |---|---|
-| Tab | Onto the box. |
+| Tab | Onto the box (in a row too: the row is not a Tab stop of its own). |
 | Space | Toggles it. |
 | Enter | Nothing. As on a native checkbox, Enter is the form's key. |
 

package/src/Checkbox.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { fn } from 'storybook/test'
 import { useState } from 'react'
+import { IconSquareRounded } from '@tabler/icons-react'
 import { Checkbox } from './Checkbox'
 
 const meta = {
@@ -32,6 +33,49 @@ export const WithLabel: Story = {
 /** Disabled with words: only the box shows it; the words keep their colour. */
 export const WithLabelDisabled: Story = { args: { label: 'Label', 'aria-label': undefined, disabled: true } }
 
+/**
+ * A list you tick several from: each row is the target — a picture, the words,
+ * the box at the end — and fills on hover and while checked.
+ */
+export const Row: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [ticked, setTicked] = useState(new Set(['Item two']))
+    const toggle = (item: string) =>
+      setTicked((prev) => {
+        const next = new Set(prev)
+        if (next.has(item)) next.delete(item)
+        else next.add(item)
+        return next
+      })
+    return (
+      <div className="flex w-80 flex-col gap-0.5">
+        {['Item one', 'Item two', 'Item three'].map((item) => (
+          <Checkbox
+            key={item}
+            row
+            leading={<IconSquareRounded size={16} stroke={1.5} />}
+            label={item}
+            checked={ticked.has(item)}
+            onChange={() => toggle(item)}
+          />
+        ))}
+      </div>
+    )
+  },
+}
+
+/** A row that cannot be changed: the box shows it, and the row neither fills nor points. */
+export const RowDisabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-80 flex-col gap-0.5">
+      <Checkbox row disabled leading={<IconSquareRounded size={16} stroke={1.5} />} label="Item one" checked onChange={() => {}} />
+      <Checkbox row disabled leading={<IconSquareRounded size={16} stroke={1.5} />} label="Item two" checked={false} onChange={() => {}} />
+    </div>
+  ),
+}
+
 /** Controlled, as always — the parent owns the state. */
 export const Toggles: Story = {
   parameters: { controls: { disable: true } },

package/src/Checkbox.test.tsx

@@ -124,4 +124,67 @@ describe('Checkbox', () => {
       expect(screen.getByText('Label')).not.toBeNull()
     })
   })
+
+  describe('with row', () => {
+    const picture = <svg data-testid="picture" />
+
+    it('is named by its words, and a click anywhere on the row toggles it once', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      render(<Checkbox row leading={picture} checked={false} onChange={onChange} label="Item one" />)
+      const box = screen.getByRole('checkbox', { name: 'Item one' })
+      await user.click(screen.getByText('Item one'))
+      await user.click(screen.getByTestId('picture'))
+      await user.click(box)
+      expect(onChange).toHaveBeenCalledTimes(3)
+      expect(onChange).toHaveBeenNthCalledWith(1, true)
+    })
+
+    it('draws the picture, the words, then the box, in one row', () => {
+      const { container } = render(<Checkbox row leading={picture} checked={false} onChange={() => {}} label="Item one" />)
+      const children = [...(container.querySelector('label')?.children ?? [])]
+      expect(children[0]?.getAttribute('data-testid')).toBe('picture')
+      expect(children[1]?.textContent).toBe('Item one')
+      expect(children[2]?.getAttribute('role')).toBe('checkbox')
+      expect(container.querySelector('label')?.className).toContain('h-10')
+    })
+
+    it('fills while checked, and on hover', () => {
+      const { container, rerender } = render(<Checkbox row checked={false} onChange={() => {}} label="Item one" />)
+      const row = () => container.querySelector('label')?.className ?? ''
+      expect(row()).not.toContain('bg-bg-selected')
+      expect(row()).toContain('hover:bg-bg-hover')
+      rerender(<Checkbox row checked onChange={() => {}} label="Item one" />)
+      expect(row()).toContain('bg-bg-selected')
+    })
+
+    it('does nothing when disabled, and neither fills under the pointer nor points', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      const { container } = render(<Checkbox row disabled checked={false} onChange={onChange} label="Item one" />)
+      await user.click(screen.getByText('Item one'))
+      expect(onChange).not.toHaveBeenCalled()
+      const className = container.querySelector('label')?.className ?? ''
+      expect(className).not.toContain('cursor-pointer')
+      expect(className).not.toContain('hover:bg-bg-hover')
+    })
+
+    it('keeps Space on the box, and adds no Tab stop of its own', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      render(<Checkbox row checked={false} onChange={onChange} label="Item one" />)
+      await user.tab()
+      expect(document.activeElement).toBe(screen.getByRole('checkbox', { name: 'Item one' }))
+      await user.keyboard(' ')
+      expect(onChange).toHaveBeenCalledWith(true)
+      await user.tab()
+      expect(document.activeElement).toBe(document.body)
+    })
+
+    it('is ignored with no onChange', () => {
+      const { container } = render(<Checkbox row checked label="Item one" />)
+      expect(container.querySelector('label')).toBeNull()
+      expect(screen.queryByRole('checkbox')).toBeNull()
+    })
+  })
 })

package/src/Checkbox.tsx

@@ -1,6 +1,7 @@
 import { Checkbox as BaseCheckbox } from '@base-ui/react/checkbox'
 import { Field as BaseField } from '@base-ui/react/field'
 import { IconCheck } from '@tabler/icons-react'
+import type { ReactNode } from 'react'
 import { cn } from './cn'
 import { useFormBusy } from './formBusy'
 
@@ -33,6 +34,12 @@ import { useFormBusy } from './formBusy'
  * Read state panel's, where it was written by hand (UIG-7, 16 September). The
  * words keep their colour when the box is disabled (Katerina: "no need").
  *
+ * With `row`, the whole row is the target: an optional `leading` picture, the
+ * words, the box at the end, and the row fills on hover and while checked — a
+ * list you tick several from. The class list is Peek's "Add to Open work" rows,
+ * which drew it by hand as a `role="option"` in a list that was not one (UIG-8,
+ * Katerina's pick B, 16 September: the same pixels, on the package part).
+ *
  * Inside a busy `Form` it is disabled, and looks it (`formBusy.ts`).
  */
 export interface CheckboxProps {
@@ -44,6 +51,14 @@ export interface CheckboxProps {
    * they name it, so no `aria-label` is needed. `className` stays on the box.
    */
   label?: string
+  /**
+   * The whole row is the target: `leading`, then the words, then the box at
+   * the end; the row fills on hover and while checked. For a list you tick
+   * several from. Needs `label` and `onChange`; without `onChange` it is ignored.
+   */
+  row?: boolean
+  /** In a `row`, a picture before the words: an icon, a status. */
+  leading?: ReactNode
   'aria-label'?: string
   /** Set by a `Field` with `required`; a caller inside one owes nothing. */
   'aria-required'?: boolean | 'true' | 'false'
@@ -65,7 +80,9 @@ const tickClasses = (checked: boolean) => cn('flex', !checked && 'invisible')
 
 const WORDS_CLASSES = 'text-body-2 text-text-primary'
 
-export function Checkbox({ checked, onChange, disabled: ownDisabled = false, label, className, ...aria }: CheckboxProps) {
+const ROW_CLASSES = 'flex shrink-0 items-center gap-3 h-10 px-3 rounded-lg transition-colors'
+
+export function Checkbox({ checked, onChange, disabled: ownDisabled = false, label, row, leading, className, ...aria }: CheckboxProps) {
   const formBusy = useFormBusy()
   const disabled = ownDisabled || formBusy
   if (!onChange) {
@@ -101,6 +118,18 @@ export function Checkbox({ checked, onChange, disabled: ownDisabled = false, lab
     </BaseCheckbox.Root>
   )
   if (label === undefined) return box
+  if (row) {
+    return (
+      <BaseField.Root disabled={disabled}>
+        {/* No fill under the pointer, and no pointer, over a row that toggles nothing. */}
+        <BaseField.Label className={cn(ROW_CLASSES, checked && 'bg-bg-selected', !disabled && 'cursor-pointer hover:bg-bg-hover')}>
+          {leading}
+          <span className={cn('flex-1 min-w-0 truncate', WORDS_CLASSES)}>{label}</span>
+          {box}
+        </BaseField.Label>
+      </BaseField.Root>
+    )
+  }
   return (
     <BaseField.Root disabled={disabled}>
       {/* No pointer over words that toggle nothing. */}

package/src/ScrollArea.stories.tsx

@@ -29,6 +29,24 @@ export const Default: Story = {
   ),
 }
 
+/** Rows that stick to the top as the list moves under them. The bar stays above them. */
+export const StickyHeadings: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
+      {['Group one', 'Group two'].map((group) => (
+        <div key={group} className="flex flex-col">
+          <p className="sticky top-0 z-10 bg-bg-surface px-4 py-2 text-caption text-text-secondary">{group}</p>
+          {rows.slice(0, 8).map((row) => (
+            <p key={row} className="px-4 py-1.5 text-body-2 text-text-primary">
+              {row}
+            </p>
+          ))}
+        </div>
+      ))}
+    </ScrollArea>
+  ),
+}
+
 /** Nothing to scroll: the region draws exactly as a plain box would, and no bar. */
 export const Fits: Story = {
   render: () => (

package/src/ScrollArea.tsx

@@ -30,6 +30,12 @@ import { cn } from './cn'
  * the thin scrollbar both apps had styled by hand in their `index.css`, drawn
  * once here instead.
  *
+ * The bar sits above the content (`z-10`). A sticky row inside — a date line
+ * in a conversation, `sticky top-0 z-10` — is at the same level, and the bar
+ * comes after the content in the page, so it paints on top. Without it the
+ * row hid the bar wherever it crossed it: a gap in the thumb, in Peek's topic
+ * and direct-message lists (UIG-8, 16 September).
+ *
  * `orientation` says which way the region scrolls; a table that is wider
  * than its box scrolls `horizontal`, a list `vertical` (the default), a board
  * `both`. A vertical region keeps its content no wider than itself, so a
@@ -58,7 +64,7 @@ export interface ScrollAreaProps {
   children: ReactNode
 }
 
-const BAR = 'flex touch-none select-none rounded-full opacity-0 transition-opacity delay-300 data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[scrolling]:opacity-100 data-[scrolling]:delay-0'
+const BAR = 'z-10 flex touch-none select-none rounded-full opacity-0 transition-opacity delay-300 data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[scrolling]:opacity-100 data-[scrolling]:delay-0'
 const THUMB = 'rounded-full bg-border-strong'
 
 export function ScrollArea({ orientation = 'vertical', className, viewportClassName, contentClassName, viewportRef, onScroll, children }: ScrollAreaProps) {

package/src/eslint/index.test.ts

@@ -6,8 +6,8 @@ import estiva, { APP_RULE_IDS, countGates, PACKAGE_RULE_IDS, PLUGIN_KEY } from '
 
 /**
  * The plugin as an app uses it: a flat config with `configs.recommended`,
- * linting text the way Peek's editor hook does (`lintText`). The rule's own
- * cases are in no-raw-element.test.ts.
+ * linting text the way Peek's editor hook does (`lintText`). The rules' own
+ * cases are in no-raw-element.test.ts and no-rebuilt-behaviour.test.ts.
  */
 const tsx: Linter.Config = {
   files: ['**/*.tsx'],
@@ -35,6 +35,7 @@ describe('the plugin object', () => {
   it('carries every rule, the app ones and the inward ones', () => {
     expect(Object.keys(estiva.rules)).toEqual([
       'no-raw-element',
+      'no-rebuilt-behaviour',
       'raw-element-outside-a-wrapper',
       'no-hand-rolled-behaviour',
       'component-has-a-page',
@@ -54,9 +55,9 @@ 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' })
+      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error' })
     }
-    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element'])
+    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour'])
   })
 
   it('gives this package its own set, as errors, and it reaches no app config', () => {
@@ -90,6 +91,25 @@ describe('an app lint with configs.recommended', () => {
     ])
   })
 
+  it('reports behaviour rebuilt by hand, naming the part', async () => {
+    const [result] = await lint(component('    <div className="h-64 overflow-y-auto" />'))
+    expect(result.messages.map((m) => [m.ruleId, m.severity, m.message])).toEqual([
+      ['estiva/no-rebuilt-behaviour', 2, "`overflow-y-auto` scrolls with the browser's scrollbar. Use `ScrollArea` from @estiva-app/ui, which draws ours."],
+    ])
+  })
+
+  /**
+   * UIG-8's acceptance: a separator inside Divider is not a hand-written role.
+   * The package is exempt from the apps' rules; this runs them on Divider anyway,
+   * to show the role branch has nothing to say there (its Base UI import is the
+   * package's job, and reported only because the apps' config is not meant for it).
+   */
+  it("finds no hand-written role in Divider's own source", async () => {
+    const source = readFileSync(new URL('../Divider.tsx', import.meta.url), 'utf8')
+    const [result] = await lint(source)
+    expect(result.messages.filter((m) => m.messageId === 'role' || m.messageId === 'roleNoPart')).toEqual([])
+  })
+
   it('passes the same element under an escape', async () => {
     const [result] = await lint(component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'))
     expect(result.messages).toEqual([])
@@ -99,8 +119,9 @@ describe('an app lint with configs.recommended', () => {
 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>')
-    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 } })
-    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 } })
+    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 })
+    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none })
   })
 
   it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
@@ -118,6 +139,9 @@ describe('countGates', () => {
   })
 
   it('lists every rule of the plugin, even with nothing found', () => {
-    expect(countGates([])).toEqual({ rules: { 'estiva/no-raw-element': { errors: 0, warnings: 0, escapes: 0 } }, disabled: [] })
+    expect(countGates([])).toEqual({
+      rules: { 'estiva/no-raw-element': { errors: 0, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': { errors: 0, warnings: 0, escapes: 0 } },
+      disabled: [],
+    })
   })
 })

package/src/eslint/index.ts

@@ -21,9 +21,11 @@ import type { ESLint, Linter } from 'eslint'
 import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
 import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
 import { noRawElement } from './no-raw-element'
+import { noRebuiltBehaviour } from './no-rebuilt-behaviour'
 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'
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
@@ -32,10 +34,12 @@ export const PLUGIN_KEY = 'estiva'
 
 /**
  * The rules an **app** runs: they say an app must not build what the package
- * already has. `recommended` and `strict` carry these and only these.
+ * already has — a raw control (UIG-7), or a behaviour one of its parts owns
+ * (UIG-8). `recommended` and `strict` carry these and only these.
  */
 const appRules = {
   'no-raw-element': noRawElement,
+  'no-rebuilt-behaviour': noRebuiltBehaviour,
 }
 
 /**
@@ -73,7 +77,7 @@ export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGI
 /**
  * `recommended` switches every **app** rule on at the level it was ruled at: an
  * error blocks, a warning is reported and never blocks. `strict` makes every app
- * rule an error. With one rule, an error, the two are the same today; they part
+ * rule an error. With every app rule an error, the two are the same today; they part
  * when the first warning-level rule arrives (UIG-25).
  *
  * `package` is the inward set (UIG-5), which only this package runs.
@@ -81,7 +85,10 @@ export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGI
 plugin.configs.recommended = {
   name: '@estiva-app/ui/recommended',
   plugins: { [PLUGIN_KEY]: plugin },
-  rules: { [`${PLUGIN_KEY}/no-raw-element`]: 'error' },
+  rules: {
+    [`${PLUGIN_KEY}/no-raw-element`]: 'error',
+    [`${PLUGIN_KEY}/no-rebuilt-behaviour`]: 'error',
+  },
 }
 plugin.configs.strict = {
   name: '@estiva-app/ui/strict',