@estiva-app/ui 0.16.1 → 0.18.0

package/package.json

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

@@ -90,7 +90,10 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
   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,
+  `onSubmit`, and the first of them takes focus. The level is the package
+  **Form** (`enterSends={false}`), so work a mark out from what is typed — a
+  field that is filled must stop saying it is missing, or the Form will not
+  send again. `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
@@ -111,7 +114,8 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 | | 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 |
+| | Enter in a text field | nothing; Enter in a text area is a new line |
+| | Ctrl+Enter, or the button | 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 |

package/src/CommandPalette.stories.tsx

@@ -155,7 +155,11 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
 
   // ── The form keeps what was typed while the palette is open.
   const [draft, setDraft] = useState({ title: '', notes: '', kind: 'one', group: '' })
-  const [missing, setMissing] = useState<{ title?: string; group?: string }>({})
+  // What a field needs is worked out from the draft once a send has been tried, so a field that is
+  // filled stops saying so at once. A mark left standing would keep the Form from ever sending.
+  const [tried, setTried] = useState(false)
+  const need = { title: draft.title.trim() ? undefined : 'Give it a title.', group: draft.group ? undefined : 'Choose a group.' }
+  const missing: { title?: string; group?: string } = tried ? need : {}
   const [working, setWorking] = useState(false)
   const [refused, setRefused] = useState(false)
   const [kind, setKind] = useState('one')
@@ -264,8 +268,7 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
   }, [frame, level, asked, recent, searching])
 
   const submitForm = async () => {
-    const need = { title: draft.title.trim() ? undefined : 'Give it a title.', group: draft.group ? undefined : 'Choose a group.' }
-    setMissing(need)
+    setTried(true)
     setRefused(false)
     if (need.title || need.group) return
     setWorking(true)

package/src/CommandPalette.test.tsx

@@ -316,6 +316,21 @@ describe('CommandPaletteForm', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  it('sends nothing on a plain Enter in a field; the button sends, through the same Form submit', async () => {
+    const onSubmit = vi.fn()
+    const user = userEvent.setup()
+    render(<Form onSubmit={onSubmit} />)
+    const title = screen.getByRole('textbox', { name: 'Title' }) as HTMLInputElement
+    await waitFor(() => expect(document.activeElement).toBe(title))
+    await user.keyboard('A{Enter}')
+    expect(onSubmit).not.toHaveBeenCalled()
+    expect(title.value).toBe('A')
+    const button = screen.getByRole('button', { name: 'Create item' })
+    expect(button.getAttribute('type')).toBe('submit')
+    await user.click(button)
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+  })
+
   it('puts focus on the first field that needs something', async () => {
     const user = userEvent.setup()
     render(<Form />)

package/src/CommandPalette.tsx

@@ -19,6 +19,7 @@ import { Button } from './Button'
 import { InputChip } from './ChipInput'
 import { EmptyState } from './EmptyState'
 import { FieldLine } from './Field'
+import { Form } from './Form'
 import { Kbd } from './Kbd'
 import { EnterHint, MenuItemBody, menuItemClassName } from './Menu'
 import { ScrollArea } from './ScrollArea'
@@ -484,15 +485,18 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   const busy = !!working
   const busyRef = useRef(busy)
   busyRef.current = busy
-  const returnTo = useRef<HTMLElement | null>(null)
 
   /** A field that says it needs something: Base UI marks the `Field` itself. */
   const firstInvalid = () => frameRef.current?.querySelector<HTMLElement>('[data-invalid]')?.querySelector<HTMLElement>(CONTROL) ?? null
 
+  /*
+    The form's one way in: its button (type="submit") and Ctrl+Enter both
+    arrive here through the package Form's submit, so Base UI's field check
+    runs for both. The guard stays: a waiting button is focusable while
+    disabled, so it is not the browser that stops it.
+  */
   const submit = () => {
     if (busyRef.current || submitWaits) return
-    const active = document.activeElement
-    returnTo.current = active instanceof HTMLElement && frameRef.current?.contains(active) ? active : null
     onSubmit()
     // If the caller marked fields instead of starting, the first of them
     // takes focus: the key list's "focus goes to the first".
@@ -502,26 +506,12 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   }
 
   /*
-    The lock must not lose focus.
-
-    Locking disables the fields, and a disabled field drops focus to the page
-    — measured in the prototype, where after Ctrl+Enter no key but Esc ever
-    worked again, even after the error came back. So while the form works,
-    focus sits on the form's own box, where its keys still arrive; when it
-    stops, focus goes to the first field that needs something, or back where
-    it was, or to the first field.
+    The lock must not lose focus — measured in the prototype, where after
+    Ctrl+Enter no key but Esc ever worked again. The package Form does it now
+    (UIG-7): while it works, focus sits on the form, where its keys still
+    arrive; when it stops, focus goes to the first field that needs something,
+    or back where it was, or to the first field.
   */
-  useLayoutEffect(() => {
-    if (busy) {
-      frameRef.current?.focus()
-      return
-    }
-    if (document.activeElement !== frameRef.current) return
-    const was = returnTo.current
-    const target = firstInvalid() ?? (was?.isConnected && !(was as HTMLButtonElement).disabled ? was : null) ?? firstControl(popupRef.current)
-    target?.focus()
-    // Runs when the lock changes, and reads the DOM it leaves behind.
-  }, [busy])
 
   /*
     Backspace goes back only where nothing typed is lost: from an empty text
@@ -541,12 +531,8 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   const measure = () => setBackNamed(backWorksFrom(document.activeElement))
   useLayoutEffect(measure)
 
+  // Ctrl+Enter is the Form's; plain Enter in a field sends nothing here (`enterSends={false}`).
   const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
-      e.preventDefault()
-      submit()
-      return
-    }
     if (e.key === 'Backspace' && !e.ctrlKey && !e.metaKey && !e.altKey && backWorksFrom(e.target as Element)) {
       e.preventDefault()
       back()
@@ -565,27 +551,29 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
         {icon != null && <span className="flex shrink-0 items-center text-text-secondary">{icon}</span>}
         <LevelChip chip={chip} onBack={back} />
       </div>
-      <ScrollArea viewportClassName="max-h-[420px]" contentClassName="flex flex-col px-5 py-4">
-        {/* `contents`: the fieldset only locks; the fields lay out as if it
-            were not there. */}
-        <fieldset data-command-palette-fields="" disabled={busy} className="contents">
+      {/* The package Form, from the fields to the button (UIG-7). The chip row
+          stays outside it, so its ✕ still goes back while the form works; the
+          button row is inside it, so focus that was on the button is held.
+          The fields are found through data-command-palette-fields. */}
+      <Form data-command-palette-fields="" busy={busy} enterSends={false} onSubmit={submit} className="flex min-h-0 flex-col">
+        <ScrollArea viewportClassName="max-h-[420px]" contentClassName="flex flex-col px-5 py-4">
           <div className="flex flex-col gap-4">{children}</div>
-        </fieldset>
-      </ScrollArea>
-      <div className="flex shrink-0 items-center gap-3 px-5 pb-4">
-        <div className="min-w-0 flex-1">
-          {working ? <FieldLine>{working.line}</FieldLine> : error ? <FieldLine tone="error">{error}</FieldLine> : null}
+        </ScrollArea>
+        <div className="flex shrink-0 items-center gap-3 px-5 pb-4">
+          <div className="min-w-0 flex-1">
+            {working ? <FieldLine>{working.line}</FieldLine> : error ? <FieldLine tone="error">{error}</FieldLine> : null}
+          </div>
+          <Button
+            type="submit"
+            variant="primary"
+            disabled={busy}
+            disabledReason={busy ? undefined : submitWaits}
+            leadingIcon={busy ? <IconLoader2 size={16} stroke={1.5} className="animate-spin" /> : undefined}
+          >
+            {working ? working.button : submitLabel}
+          </Button>
         </div>
-        <Button
-          variant="primary"
-          onClick={submit}
-          disabled={busy}
-          disabledReason={busy ? undefined : submitWaits}
-          leadingIcon={busy ? <IconLoader2 size={16} stroke={1.5} className="animate-spin" /> : undefined}
-        >
-          {working ? working.button : submitLabel}
-        </Button>
-      </div>
+      </Form>
       <Footer keys={keys} />
     </div>
   )

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