@estiva-app/ui 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.16.1",
+  "version": "0.17.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/Button.tsx

@@ -1,6 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
 import { cn } from './cn'
+import { useFormBusy } from './formBusy'
 import { TooltipTrigger } from './Tooltip'
 
 /**
@@ -59,10 +60,12 @@ export function Button({
   ...props
 }: ButtonProps) {
   const hasLeadingIcon = !!leadingIcon
+  // Inside a busy Form: switched off, and looking it (formBusy.ts).
+  const formBusy = useFormBusy()
   const button = (
     <BaseButton
       type={type}
-      disabled={disabled || !!disabledReason}
+      disabled={disabled || !!disabledReason || formBusy}
       focusableWhenDisabled={!!disabledReason}
       className={(state) =>
         cn(

package/src/Checkbox.mdx

@@ -21,6 +21,12 @@ the parent owns the state.
 
 <Canvas of={CheckboxStories.InsideARow} />
 
+- With words beside it: pass **`label`**. The words are part of the
+  target — clicking them toggles the box — and they name it, so no
+  `aria-label` is needed.
+
+<Canvas of={CheckboxStories.WithLabel} />
+
 ## When not
 
 - One choice out of several → **Select** (a value) or **Tabs** (a view).
@@ -38,7 +44,19 @@ import { Checkbox } from '@estiva-app/ui'
 - Built on Base UI Checkbox, as Base UI renders it: a `<span>` with
   `role="checkbox"` and `aria-checked`, and a hidden `<input>` beside it
   for forms. Its click never reaches the row around it.
-- Give it an `aria-label` unless visible text right beside it names it.
+- Give it an `aria-label`, or words of its own with `label`. Words written
+  beside it by hand name nothing and toggle nothing; `label` does both.
+
+```tsx
+<Checkbox checked={on} onChange={setOn} label="Label" />
+```
+
+- With `label` it is Base UI's `Field`, its `Field.Label` around the box and
+  the words: the box, 8px, then the words in `body-2`. `className` stays on
+  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**.
+- 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.
 

package/src/Checkbox.stories.tsx

@@ -20,6 +20,18 @@ export const Checked: Story = { args: { checked: true } }
 export const Disabled: Story = { args: { disabled: true } }
 export const DisabledChecked: Story = { args: { checked: true, disabled: true } }
 
+/** Words beside the box. Clicking them toggles it too, and they name it. */
+export const WithLabel: Story = {
+  args: { label: 'Label', 'aria-label': undefined },
+  render: (args) => {
+    const [checked, setChecked] = useState(args.checked)
+    return <Checkbox {...args} checked={checked} onChange={setChecked} />
+  },
+}
+
+/** 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 } }
+
 /** Controlled, as always — the parent owns the state. */
 export const Toggles: Story = {
   parameters: { controls: { disable: true } },

package/src/Checkbox.test.tsx

@@ -70,4 +70,58 @@ describe('Checkbox', () => {
     await user.click(square as HTMLElement)
     expect(onRow).toHaveBeenCalledTimes(1)
   })
+
+  describe('with label', () => {
+    it('is named by its words, and clicking the words toggles it', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      render(<Checkbox checked={false} onChange={onChange} label="Compare every time" />)
+      const box = screen.getByRole('checkbox', { name: 'Compare every time' })
+      await user.click(screen.getByText('Compare every time'))
+      expect(onChange).toHaveBeenCalledTimes(1)
+      expect(onChange).toHaveBeenCalledWith(true)
+      expect(box.getAttribute('aria-checked')).toBe('false')
+    })
+
+    it('toggles once, not twice, when the box itself is clicked inside its words', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      render(<Checkbox checked onChange={onChange} label="Label" />)
+      await user.click(screen.getByRole('checkbox', { name: 'Label' }))
+      expect(onChange).toHaveBeenCalledTimes(1)
+      expect(onChange).toHaveBeenCalledWith(false)
+    })
+
+    it('keeps Space on the box', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      render(<Checkbox checked={false} onChange={onChange} label="Label" />)
+      await user.tab()
+      expect(document.activeElement).toBe(screen.getByRole('checkbox', { name: 'Label' }))
+      await user.keyboard(' ')
+      expect(onChange).toHaveBeenCalledWith(true)
+    })
+
+    it('does nothing from its words when disabled, and shows no pointer over them', async () => {
+      const user = userEvent.setup()
+      const onChange = vi.fn()
+      const { container } = render(<Checkbox checked={false} disabled onChange={onChange} label="Label" />)
+      await user.click(screen.getByText('Label'))
+      expect(onChange).not.toHaveBeenCalled()
+      expect(container.querySelector('label')?.className).not.toContain('cursor-pointer')
+    })
+
+    it('keeps className on the box', () => {
+      const { container } = render(<Checkbox checked={false} onChange={() => {}} label="Label" className="mt-1" />)
+      expect(container.querySelector('label')?.className).not.toContain('mt-1')
+      expect(screen.getByRole('checkbox', { name: 'Label' }).className).toContain('mt-1')
+    })
+
+    it('with no onChange draws the words beside the picture, and is still not a control', () => {
+      const { container } = render(<Checkbox checked label="Label" />)
+      expect(screen.queryByRole('checkbox')).toBeNull()
+      expect(container.querySelector('label')).toBeNull()
+      expect(screen.getByText('Label')).not.toBeNull()
+    })
+  })
 })

package/src/Checkbox.tsx

@@ -1,6 +1,8 @@
 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 { cn } from './cn'
+import { useFormBusy } from './formBusy'
 
 /**
  * A 16px square that fills with the accent when checked — Peek's Checkbox
@@ -24,11 +26,24 @@ import { cn } from './cn'
  * "it should be fixed"). With the tick always there, Base UI's `<span>` and
  * the `<button>` this used to be land on the same pixel, measured. In a flex
  * row nothing ever moved.
+ *
+ * With `label`, the words sit beside the box and are part of the target: Base
+ * UI's `Field`, its `Field.Label` around the box and the words — the way its
+ * Checkbox page labels a checkbox inside a form. The class list is Peek's
+ * 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").
+ *
+ * Inside a busy `Form` it is disabled, and looks it (`formBusy.ts`).
  */
 export interface CheckboxProps {
   checked: boolean
   onChange?: (checked: boolean) => void
   disabled?: boolean
+  /**
+   * Words beside the box. With `onChange`, clicking them toggles it too, and
+   * they name it, so no `aria-label` is needed. `className` stays on the box.
+   */
+  label?: string
   'aria-label'?: string
   /** Set by a `Field` with `required`; a caller inside one owes nothing. */
   'aria-required'?: boolean | 'true' | 'false'
@@ -48,17 +63,29 @@ function squareClasses(checked: boolean, disabled: boolean, interactive: boolean
 /** `flex`, so the icon is a flex item and not an inline box with a line height of its own. */
 const tickClasses = (checked: boolean) => cn('flex', !checked && 'invisible')
 
-export function Checkbox({ checked, onChange, disabled = false, className, ...aria }: CheckboxProps) {
+const WORDS_CLASSES = 'text-body-2 text-text-primary'
+
+export function Checkbox({ checked, onChange, disabled: ownDisabled = false, label, className, ...aria }: CheckboxProps) {
+  const formBusy = useFormBusy()
+  const disabled = ownDisabled || formBusy
   if (!onChange) {
-    return (
+    const picture = (
       <span aria-hidden="true" className={squareClasses(checked, disabled, false, className)}>
         <span className={tickClasses(checked)}>
           <IconCheck size={12} stroke={3} />
         </span>
       </span>
     )
+    if (label === undefined) return picture
+    // The row around it is the control and says the state; the words are only words.
+    return (
+      <span className="flex items-center gap-2">
+        {picture}
+        <span className={WORDS_CLASSES}>{label}</span>
+      </span>
+    )
   }
-  return (
+  const box = (
     <BaseCheckbox.Root
       checked={checked}
       disabled={disabled}
@@ -73,4 +100,14 @@ export function Checkbox({ checked, onChange, disabled = false, className, ...ar
       </BaseCheckbox.Indicator>
     </BaseCheckbox.Root>
   )
+  if (label === undefined) return box
+  return (
+    <BaseField.Root disabled={disabled}>
+      {/* No pointer over words that toggle nothing. */}
+      <BaseField.Label className={cn('flex items-center gap-2', !disabled && 'cursor-pointer')}>
+        {box}
+        <span className={WORDS_CLASSES}>{label}</span>
+      </BaseField.Label>
+    </BaseField.Root>
+  )
 }

package/src/FilePicker.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FilePickerStories from './FilePicker.stories'
+
+<Meta of={FilePickerStories} />
+
+# FilePicker
+
+The browser's file picker, with nothing drawn. Your own button opens it; it
+hands you the files chosen.
+
+<Canvas of={FilePickerStories.Default} />
+
+## When
+
+- A button that opens the file picker — to attach, to upload, to import.
+- **`multiple`** to allow several at once; **`accept`** to limit the kinds
+  the picker offers.
+
+## When not
+
+- Showing a file that was chosen → **AttachmentCard**.
+- Dropping files onto an area: the package has no part for that yet.
+
+## How
+
+```tsx
+import { FilePicker, IconButton } from '@estiva-app/ui'
+
+const picker = useRef<HTMLInputElement>(null)
+
+<FilePicker ref={picker} multiple onPick={(files) => attach(files)} />
+<IconButton aria-label="Attach" tooltip="Attach" onClick={() => picker.current?.click()}>
+  <IconSquareRounded size={16} stroke={1.5} />
+</IconButton>
+```
+
+- **The button is the control.** The picker is hidden from Tab and from
+  screen readers, so the button's name is the only one read out. A hidden
+  input still opens its picker when the button clicks it.
+- **`onPick` gets an array**, in the order the picker gave the files, and is
+  not called when the picker is closed with nothing chosen.
+- **The same file can be chosen again** — after an upload failed, or after
+  it was removed. The picker clears itself before `onPick` runs, so there is
+  nothing to reset afterwards.
+- `data-*` attributes pass on to the input, for a test to find it.
+
+## Props
+
+<Controls of={FilePickerStories.Default} />

package/src/FilePicker.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { useRef, useState } from 'react'
+import { Button } from './Button'
+import { FilePicker } from './FilePicker'
+import { IconButton } from './IconButton'
+
+const meta = {
+  title: 'Inputs/FilePicker',
+  component: FilePicker,
+  // The code tab shows each story's own code: building it from the rendered
+  // element reads `element.ref`, which React 19 warns about.
+  parameters: { layout: 'padded', docs: { source: { type: 'code' } } },
+  args: { onPick: () => {} },
+  argTypes: { onPick: { control: false } },
+} satisfies Meta<typeof FilePicker>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** What was chosen, one line per pick, so choosing the same file twice shows twice. */
+function Picks({ picks }: { picks: string[] }) {
+  return (
+    <ul className="flex flex-col gap-1 text-body-2 text-text-secondary">
+      {picks.length === 0 ? <li>Nothing chosen yet.</li> : picks.map((pick, i) => <li key={i}>{pick}</li>)}
+    </ul>
+  )
+}
+
+/** Opened by the caller's own button. It draws nothing itself. */
+export const Default: Story = {
+  render: (args) => {
+    const picker = useRef<HTMLInputElement>(null)
+    const [picks, setPicks] = useState<string[]>([])
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <FilePicker {...args} ref={picker} onPick={(files) => setPicks((held) => [...held, files.map((f) => f.name).join(', ')])} />
+        <Button onClick={() => picker.current?.click()}>Choose</Button>
+        <Picks picks={picks} />
+      </div>
+    )
+  },
+}
+
+/** `multiple`, opened from an icon-only button. */
+export const Several: Story = {
+  args: { multiple: true },
+  render: (args) => {
+    const picker = useRef<HTMLInputElement>(null)
+    const [picks, setPicks] = useState<string[]>([])
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <FilePicker {...args} ref={picker} onPick={(files) => setPicks((held) => [...held, files.map((f) => f.name).join(', ')])} />
+        <IconButton aria-label="Choose" tooltip="Choose" onClick={() => picker.current?.click()}>
+          <IconSquareRounded size={16} stroke={1.5} />
+        </IconButton>
+        <Picks picks={picks} />
+      </div>
+    )
+  },
+}

package/src/FilePicker.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+/**
+ * What the FilePicker page claims, pinned: it draws nothing a person or a
+ * screen reader can reach, the caller's ref opens it, it hands over an array,
+ * the same file can be chosen twice, and closing it with nothing chosen calls
+ * nothing. Opening the browser's own picker is checked in Chrome (the PR).
+ */
+import { createRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { FilePicker } from './FilePicker'
+
+afterEach(cleanup)
+
+/** A change as the browser sends one: the input's `files` set, then `change`. */
+function choose(input: HTMLInputElement, files: File[]) {
+  Object.defineProperty(input, 'files', { value: files, configurable: true })
+  fireEvent.change(input)
+}
+
+describe('FilePicker', () => {
+  it('is a hidden file input, out of the accessibility tree and out of Tab', () => {
+    const { container } = render(<FilePicker onPick={() => {}} />)
+    const input = container.querySelector('input') as HTMLInputElement
+    expect(input.type).toBe('file')
+    expect(input.className).toBe('hidden')
+    expect(input.getAttribute('aria-hidden')).toBe('true')
+    expect(input.tabIndex).toBe(-1)
+  })
+
+  it("gives the caller's ref the input, which is how a button opens it", () => {
+    const ref = createRef<HTMLInputElement>()
+    render(<FilePicker ref={ref} onPick={() => {}} />)
+    expect(ref.current?.tagName).toBe('INPUT')
+    expect(ref.current?.type).toBe('file')
+  })
+
+  it('hands over the chosen files as an array, in order', () => {
+    const onPick = vi.fn()
+    const { container } = render(<FilePicker multiple onPick={onPick} />)
+    const a = new File(['a'], 'a.txt')
+    const b = new File(['b'], 'b.txt')
+    choose(container.querySelector('input') as HTMLInputElement, [a, b])
+    expect(onPick).toHaveBeenCalledTimes(1)
+    expect(onPick.mock.calls[0][0]).toEqual([a, b])
+    expect(Array.isArray(onPick.mock.calls[0][0])).toBe(true)
+  })
+
+  it('clears itself before handing the files over, so the same file can be chosen again', () => {
+    const input = { value: 'C:\\fakepath\\a.txt' }
+    const onPick = vi.fn(() => {
+      input.value = (container.querySelector('input') as HTMLInputElement).value
+    })
+    const { container } = render(<FilePicker onPick={onPick} />)
+    const element = container.querySelector('input') as HTMLInputElement
+    const set = vi.spyOn(element, 'value', 'set')
+    const a = new File(['a'], 'a.txt')
+    choose(element, [a])
+    expect(set).toHaveBeenCalledWith('')
+    expect(input.value).toBe('')
+    choose(element, [a])
+    expect(onPick).toHaveBeenCalledTimes(2)
+  })
+
+  it('calls nothing when the picker closes with nothing chosen', () => {
+    const onPick = vi.fn()
+    const { container } = render(<FilePicker onPick={onPick} />)
+    choose(container.querySelector('input') as HTMLInputElement, [])
+    expect(onPick).not.toHaveBeenCalled()
+  })
+
+  it('passes accept, multiple and data attributes on', () => {
+    const { container } = render(<FilePicker onPick={() => {}} multiple accept="image/*" data-picker="probe" />)
+    const input = container.querySelector('input') as HTMLInputElement
+    expect(input.multiple).toBe(true)
+    expect(input.accept).toBe('image/*')
+    expect(input.getAttribute('data-picker')).toBe('probe')
+  })
+})

package/src/FilePicker.tsx

@@ -0,0 +1,40 @@
+import { forwardRef, type InputHTMLAttributes } from 'react'
+
+/**
+ * The browser's file picker, with nothing drawn: a hidden `<input type="file">`
+ * that the caller's own button opens with `ref.current.click()` (UIG-7,
+ * 16 September). Base UI has no part for it.
+ *
+ * Peek's paperclip and Ship's two wrote this by hand, each with the same two
+ * details — the files handed over as they were chosen, and the value cleared
+ * so the same file can be chosen again after a failure or after it was
+ * removed. Those are here once.
+ *
+ * Hidden from the accessibility tree and from Tab: the button that opens it is
+ * the control, and two things both named "Attach" is one more than a screen
+ * reader should find. A `display: none` input still opens its picker on a
+ * scripted click.
+ */
+export interface FilePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange' | 'value' | 'defaultValue' | 'className' | 'style' | 'children'> {
+  /** The chosen files, in the order the picker gave them. Not called when the picker is closed with nothing chosen. */
+  onPick: (files: File[]) => void
+}
+
+export const FilePicker = forwardRef<HTMLInputElement, FilePickerProps>(function FilePicker({ onPick, ...props }, ref) {
+  return (
+    <input
+      ref={ref}
+      type="file"
+      aria-hidden="true"
+      tabIndex={-1}
+      className="hidden"
+      {...props}
+      onChange={(event) => {
+        const files = Array.from(event.target.files ?? [])
+        // Cleared before anything else runs, so the same file can be chosen again.
+        event.target.value = ''
+        if (files.length > 0) onPick(files)
+      }}
+    />
+  )
+})

package/src/Form.mdx

@@ -0,0 +1,68 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FormStories from './Form.stories'
+
+<Meta of={FormStories} />
+
+# Form
+
+The fields and the button that sends them. Enter in a field, or a submit
+button, sends it; the page never reloads; while it sends, everything inside
+is switched off at once.
+
+<Canvas of={FormStories.WhileSending} />
+
+## When
+
+- Any set of fields that is sent: a dialog's fields, a one-line field with
+  its button, a composer.
+- **`busy`** while the sending is waited on.
+
+## When not
+
+- One field that saves itself as you leave it → **EditableText**.
+- A field that filters a list as you type → **SearchInput**; nothing is sent.
+
+## How
+
+```tsx
+import { Button, Field, Form, TextInput } from '@estiva-app/ui'
+
+<Form onSubmit={send} busy={sending} className="flex flex-col gap-6">
+  <Field label="Title" required error={titleError}>
+    <TextInput value={title} onChange={(e) => { setTitle(e.target.value); setTitleError(undefined) }} />
+  </Field>
+  <Button variant="primary" type="submit">Send</Button>
+</Form>
+```
+
+- **`onSubmit` takes nothing.** The page's own submit is already prevented;
+  there is no event to stop.
+- **`busy` switches off every field and button inside**, so they do not
+  each need `disabled={busy}`. A button outside the form that sends it —
+  a dialog's footer, with `form="<id>"` and the form's `id` — is outside,
+  and keeps its own `disabled`.
+- **Focus waits on the form while it is busy.** A browser drops focus to the
+  page the moment the focused field is switched off; the form holds it
+  instead. When `busy` ends, focus goes to the first field showing an error,
+  else back to what sent the form, else to the first control. If focus was
+  moved somewhere else while it waited, it stays there.
+- **A field showing its `error` stops the form from sending**, and Enter moves
+  focus to that field instead (Base UI checks every field before it sends).
+  Clear the error when the field changes, as in the example; an error left
+  standing keeps the form from ever sending.
+- The browser's own validation bubbles are off (`noValidate`). `Field`'s
+  `required` marks a field; it does not block sending by itself.
+- `className` places the fields: the form draws no box, and neither does the
+  `<fieldset>` inside it.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Enter, in a one-line field | Sends the form. |
+| Enter, in a Textarea | A new line; it does not send. |
+| Tab, while busy | Nothing inside takes focus. |
+
+## Props
+
+<Controls of={FormStories.Default} />

package/src/Form.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { fn } from 'storybook/test'
+import { Button } from './Button'
+import { Field } from './Field'
+import { Form } from './Form'
+import { TextInput } from './TextInput'
+import { Textarea } from './Textarea'
+
+const meta = {
+  title: 'Inputs/Form',
+  component: Form,
+  parameters: { layout: 'padded' },
+  args: { onSubmit: fn(), busy: false, className: 'flex flex-col gap-6', 'aria-label': 'Example', children: null },
+  argTypes: { children: { control: false }, onSubmit: { control: false } },
+  decorators: [(Story) => <div className="w-96"><Story /></div>],
+} satisfies Meta<typeof Form>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const fields = (error?: string) => (
+  <>
+    <Field label="Label" required>
+      <TextInput placeholder="Placeholder" />
+    </Field>
+    <Field label="Label" error={error}>
+      <Textarea placeholder="Placeholder" className="h-20" />
+    </Field>
+    <div className="flex justify-end">
+      <Button variant="primary" type="submit">
+        Send
+      </Button>
+    </div>
+  </>
+)
+
+export const Default: Story = { render: (args) => <Form {...args}>{fields()}</Form> }
+
+/** Sending: every field and button inside is switched off at once. */
+export const Busy: Story = { args: { busy: true }, render: (args) => <Form {...args}>{fields()}</Form> }
+
+/** A field showing its error. The form does not send while it shows. */
+export const WithError: Story = { render: (args) => <Form {...args}>{fields('That is not a valid value.')}</Form> }
+
+/**
+ * Live. Press Enter in the first field, or Send: the form is busy for a
+ * second and a half, and focus comes back to where it was.
+ */
+export const WhileSending: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [busy, setBusy] = useState(false)
+    return (
+      <Form
+        {...args}
+        busy={busy}
+        onSubmit={async () => {
+          setBusy(true)
+          await new Promise((resolve) => setTimeout(resolve, 1500))
+          setBusy(false)
+        }}
+      >
+        {fields()}
+      </Form>
+    )
+  },
+}