@estiva-app/ui 0.16.0 → 0.17.0

package/package.json

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

@@ -76,10 +76,16 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 - **`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.
+- **`notes` are what a person should know about the rows and cannot act on** —
+  "2 more where you cannot open them", "the search was refused, so this list
+  is incomplete". Quiet lines under the rows, never rows: the arrows do not stop
+  on them.
+- **Rows that arrive late do not take the highlight you moved to.** 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. Once you have
+  moved the highlight on a level, the palette walks it back to the row you had.
+  Until you have, the first row is lit, whichever row that becomes. 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.
@@ -117,7 +123,7 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 
 **`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?`,
+with no rows is not drawn), `chip?` (`{ label, leading?, onBack }`), `pending?`, `notes?`,
 `empty?`, and `children` for what sits above the rows.
 
 **A row** — `id`, `label`, `description?`, `icon?` or `leading?`, `onSelect`,

package/src/CommandPalette.stories.tsx

@@ -365,6 +365,8 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
                     : undefined
             }
             pending={level.kind === 'first' && searching ? 'Searching…' : undefined}
+            // What the later group left out: a line to read, not a row to pick.
+            notes={level.kind === 'first' && q && !searching && LATER.some((l) => l.toLowerCase().includes(q)) ? ['1 more in a place you cannot open.'] : undefined}
             empty={
               level.kind === 'first' && q && !searching
                 ? `Nothing is called “${q}”.`
@@ -388,7 +390,7 @@ const story = (start: Start): Story => ({
 /** The first level: rows in groups, the first one lit. ↑ ↓ stop at the ends, Tab goes into a place, Ctrl+Backspace forgets a recent row. */
 export const FirstLevel: Story = story('first')
 
-/** Typing: the rows that match now, a line while a later group is on its way, and that group arriving without moving the lit row. */
+/** Typing: the rows that match now, a line while a later group is on its way, that group arriving without moving the lit row, and a note about what it left out. */
 export const WhileRowsArrive: Story = story('arriving')
 
 /** Nothing matches: the empty line, where the first row would be. */

package/src/CommandPalette.test.tsx

@@ -39,6 +39,7 @@ function Search({
   onOpenChange = () => {},
   modKey,
   pending,
+  notes,
   empty,
 }: {
   groups: CommandPaletteGroup[]
@@ -47,12 +48,13 @@ function Search({
   onOpenChange?: (open: boolean) => void
   modKey?: string
   pending?: string
+  notes?: string[]
   empty?: string
 }) {
   const [query, setQuery] = useState(initialQuery)
   return (
     <CommandPalette open onOpenChange={onOpenChange} label="Palette" where="In Item one" modKey={modKey}>
-      <CommandPaletteSearch query={query} onQueryChange={setQuery} placeholder="Search" groups={groups} chip={chip} pending={pending} empty={empty} />
+      <CommandPaletteSearch query={query} onQueryChange={setQuery} placeholder="Search" groups={groups} chip={chip} pending={pending} notes={notes} empty={empty} />
     </CommandPalette>
   )
 }
@@ -201,6 +203,17 @@ describe('CommandPaletteSearch — rows', () => {
     await waitFor(() => expect(lit()).toBe('Two'))
   })
 
+  it('lets rows arriving above take the first place while the highlight has not been moved', async () => {
+    const early: CommandPaletteGroup = { label: 'Early', rows: [row('One'), row('Two')] }
+    const late: CommandPaletteGroup = { label: 'Late', rows: [row('Late one')] }
+    const { rerender } = render(<Search groups={[early]} />)
+    await focusedField()
+    await waitFor(() => expect(lit()).toBe('One'))
+    rerender(<Search groups={[late, early]} />)
+    await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(3))
+    await waitFor(() => expect(lit()).toBe('Late one'))
+  })
+
   it('names in the footer only the keys that work on the lit row', async () => {
     const user = userEvent.setup()
     render(
@@ -232,6 +245,16 @@ describe('CommandPaletteSearch — rows', () => {
     expect(await screen.findByText('Nothing here yet.')).toBeTruthy()
   })
 
+  it('draws notes as lines under the rows, which the arrows do not stop on', async () => {
+    const user = userEvent.setup()
+    render(<Search groups={[{ label: 'Group', rows: [row('One'), row('Two')] }]} notes={['2 more you cannot open.']} />)
+    await focusedField()
+    expect(await screen.findByText('2 more you cannot open.')).toBeTruthy()
+    expect(screen.getAllByRole('option')).toHaveLength(2)
+    await user.keyboard('{ArrowDown}{ArrowDown}{ArrowDown}')
+    expect(lit()).toBe('Two')
+  })
+
   it('says rows are on their way', async () => {
     render(<Search groups={[{ label: 'Group', rows: [row('One')] }]} pending="Searching…" />)
     expect(await screen.findByText('Searching…')).toBeTruthy()

package/src/CommandPalette.tsx

@@ -221,6 +221,13 @@ export interface CommandPaletteSearchProps {
   chip?: CommandPaletteChip
   /** A line under the rows while more are on their way — "Searching…". */
   pending?: string
+  /**
+   * Quiet lines under the rows, for what a person should know about them and
+   * cannot act on — "2 more where you cannot open them", "the search was
+   * refused, so this list is incomplete". Plain lines, never rows: the arrows
+   * do not stop on them.
+   */
+  notes?: string[]
   /** The line when there are no rows. Leave it out while rows are still on their way. */
   empty?: string
   /** Above the rows: a `CommandPaletteWorking`, `CommandPaletteAnswer` or `CommandPaletteQuote`. */
@@ -229,7 +236,7 @@ export interface CommandPaletteSearchProps {
 
 type ListGroup = { value: string; items: CommandPaletteRow[] }
 
-export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, empty, children }: CommandPaletteSearchProps) {
+export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, notes = [], empty, children }: CommandPaletteSearchProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteSearch')
   const back = useBack(chip, popupRef)
   const items = useMemo<ListGroup[]>(() => groups.filter((g) => g.rows.length > 0).map((g) => ({ value: g.label, items: g.rows })), [groups])
@@ -254,14 +261,22 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
     arrow keys, exactly as a person would. It does so only when Base UI moved
     the highlight by itself ("none") — never after an arrow, the pointer, or
     typing, which starts again from the first row.
+
+    And only once the person has moved the highlight on this level. Until then
+    the lit row is simply the first one, and a row that arrives above it — a
+    thread's own rows, a moment after opening — becomes the first one.
   */
   const inputRef = useRef<HTMLInputElement>(null)
   const reported = useRef<{ id?: string; reason?: string }>({})
   const settled = useRef<{ id?: string; query: string; level?: string } | null>(null)
+  /** The person has moved the highlight since the text or the level last changed. */
+  const moved = useRef(false)
   useLayoutEffect(() => {
     const before = settled.current
     const now = reported.current
-    if (before?.id && now.reason === 'none' && now.id !== before.id && before.query === query && before.level === chip?.label) {
+    const sameLevel = before?.query === query && before?.level === chip?.label
+    if (!sameLevel) moved.current = false
+    if (moved.current && before?.id && now.reason === 'none' && now.id !== before.id && sameLevel) {
       const ids = rows.map((r) => r.id)
       const want = ids.indexOf(before.id)
       const at = now.id === undefined ? -1 : ids.indexOf(now.id)
@@ -347,6 +362,7 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
       onItemHighlighted={(row, details) => {
         const id = (row as CommandPaletteRow | undefined)?.id
         reported.current = { id, reason: details.reason }
+        if (details.reason !== 'none') moved.current = true
         setLitId(id)
       }}
     >
@@ -410,6 +426,11 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
             </>
           )}
         </Autocomplete.Status>
+        {notes.map((note) => (
+          <div key={note} className="flex min-h-8 items-center px-3">
+            <FieldLine>{note}</FieldLine>
+          </div>
+        ))}
         <Autocomplete.Empty className="flex items-center px-3 [&:not(:empty)]:min-h-10">
           {empty && <EmptyState scope="section" message={empty} />}
         </Autocomplete.Empty>

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)
+      }}
+    />
+  )
+})