@recursica/mui-adapter 0.22.0 → 0.24.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.22.0",
+  "version": "0.24.0",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Button/Button.module.css

@@ -364,6 +364,19 @@
   );
 }
 
+/* Focus State Mapping (native browser focus outline replaced with the recursica focus ring).
+   Placed after every variant's own box-shadow (elevation) rule so it wins the cascade at equal
+   attribute-selector specificity regardless of variant. */
+.root:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
 /* EXEMPTIONS:
    These general button properties are redundant because visual mapping has been refactored
    to content-specific variables (_content_label_sizes_... etc.) or are handled by design defaults. */

package/src/components/Chip/CHIP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,102 @@
+# Chip Implementation Notes
+
+## Architecture decisions
+
+### MUI DOM Structure & Label/Icon Overrides
+
+MUI's `<Chip>` renders a plain `<div>` root with an optional leading `icon`, a `label`, and an
+optional `deleteIcon` — no hidden `<input>` involved (unlike Mantine's checkbox/radio-based
+`Chip`). This adapter targets MUI's own style hooks (`classes.root`/`classes.label`/`classes.icon`/
+`classes.deleteIcon`) directly via the `classes` prop, matching the same visual surface the
+mantine-adapter's `Chip` exposes.
+
+### Icon and Remove Implementations
+
+To match the mantine-adapter's internal `children` wrapper strategy, `label` is always set to a
+`<span className={styles.innerWrapper}><span className={styles.children}>{children}</span></span>`
+— any caller-supplied `label` in `sanitizedProps` is unconditionally overridden, since this
+component's real public API is `children`, not `label` (see the `Chip.tsx` type comment: MUI's own
+`ChipProps.children` is typed `null | undefined`, re-typed here as `React.ReactNode`).
+
+`deleteIcon` and `icon` are each wrapped in their own `<span>` (`styles.removeIconWrapper`/
+`styles.leadingIcon`) rather than styled as bare SVGs, so sizing/color/gap tokens have a stable
+element to target — MUI clones whatever element is passed as `deleteIcon`/`icon`, adding only its
+own `className`/`onClick`, so a `ref`/`tabIndex` set directly on that `<span>` survives the clone
+untouched.
+
+### Long-label truncation was hiding the remove icon (Matt Massey, 2026-08-17)
+
+Same root cause as mantine-adapter's `Chip` (see its `CHIP_IMPLEMENTATION_NOTES.md`): `.children`
+had ellipsis/`overflow: hidden`/`white-space: nowrap` but no `min-width: 0` on it or `.innerWrapper`,
+so a flex child never actually shrank enough to trigger the ellipsis — the label overflowed instead,
+pushing `.removeIconWrapper` outside the chip's clipped `max-width`. Fixed by adding `min-width: 0`
+to `.innerWrapper`/`.children` and `flex-shrink: 0` to `.leadingIcon`/`.removeIconWrapper`.
+
+### The remove icon had no accessible label and no real keyboard activation (Matt Massey, 2026-08-17)
+
+`removeLabel` was destructured from props and defaulted to `"Remove"`, but was never actually
+applied anywhere — dead code (`// eslint-disable-next-line @typescript-eslint/no-unused-vars`)
+since this component was first built. The `deleteIcon` `<span>` had no `aria-label`, no `role`, and
+no keyboard handler of its own: MUI's own `onDelete` wiring only reacts to `Backspace`/`Delete`,
+and only when the _root_ itself is both the event's `target` and `currentTarget` (see
+`isDeleteKeyboardEvent`/`handleKeyUp` in MUI's own `Chip.js`) — it never fires once focus moves onto
+a child span directly (which is exactly what happens once you `.focus()` the remove icon
+imperatively, as `FileUpload`'s roving-tabindex group does below). A plain `<span>` also gets no
+native Enter/Space-triggers-click behavior the way a real `<button>` would. Fixed by adding
+`role="button"`, `aria-label={removeLabel}`, and an explicit `onKeyDown` for `Enter`/`Space` that
+calls `onRemove` directly — matching the mantine-adapter `Chip`'s remove icon, which already did all
+three.
+
+### Roving tabindex support for chip groups (Matt Massey, 2026-08-17)
+
+Added two optional pass-through props — `removeTabIndex` and `removeIconRef` — purely so a parent
+managing a _group_ of chips (e.g. `FileUpload`'s file list, see its own `IMPLEMENTATION_NOTES.md`)
+can implement roving-tabindex/arrow-key navigation across them: set `removeTabIndex={-1}` on every
+chip but the currently-active one, and use `removeIconRef` to move real DOM focus there
+imperatively on arrow-key press. Both are set directly on the `<span>` passed as `deleteIcon`,
+which MUI's `Chip` preserves when it clones that element. Both are no-ops for a standalone `Chip`
+(defaults: `tabIndex={0}`, no ref) — this doesn't change any existing single-chip behavior.
+
+A group composing multiple chips also needs to pass a plain `tabIndex={-1}` directly on each
+`<Chip>` itself (not just `removeTabIndex` on the remove icon) — MUI's `Chip` silently renders its
+_root_ as a focusable `ButtonBase` (not a plain `<div>`) whenever `onDelete` is set, even with no
+`onClick` (`component = clickable || onDelete ? ButtonBase : ...`), so without this the root is a
+second, unwanted tab stop ahead of the remove icon on every chip. `FileUpload` does this; any other
+consumer building a roving-tabindex chip group needs to as well.
+
+### Descenders were being clipped on `.children` and `.root` (Matt Massey, 2026-08-18)
+
+Same root cause and fix as mantine-adapter's `Chip` (see its `CHIP_IMPLEMENTATION_NOTES.md`): a
+label with a descender (e.g. the "g" in "image.png") had its bottom clipped off, because both
+`.children` and `.root.root` set plain `overflow: hidden` — needed on the x-axis for
+`text-overflow: ellipsis`/`max-width` truncation, but clipping the y-axis too cuts off glyph ink
+that extends past a `text_line-height` token tighter than the font's natural ascent+descent. Split
+both into `overflow-x: hidden; overflow-y: visible;`; truncation is unaffected (still x-axis only).
+Unlike mantine's `Chip`, MUI's `.root.root` _is_ the visible pill (background-color/border-radius
+live there, not on a separate `.label`), but border-radius rendering doesn't depend on `overflow`,
+so opening the y-axis has no visual side effect on the rounded corners.
+
+### Removing Sizing Properties
+
+Matching mantine-adapter's `Chip`: Figma tokens export explicit height/padding vectors rather than
+string size variants (`sm`/`md`/`lg`), so `size` is omitted from `RecursicaChipProps` entirely.
+
+### A non-interactive chip still looked clickable, and had a phantom Tab stop (Matt Massey, 2026-08-18)
+
+A `Chip` with no `onRemove`/`onClick`/`onChange` (e.g. `FileUpload`'s `readOnly` file list) still
+showed a pointer cursor on hover — `.root.root` hardcoded `cursor: pointer` unconditionally, with
+no notion of whether the chip actually did anything. Added an `isInteractive` check (mirroring the
+one added to mantine-adapter's `Chip`, see its `CHIP_IMPLEMENTATION_NOTES.md`) based on
+`onRemove`/`onClick`/`onChange` — this adapter's `Chip` has no `checked`-driven native-input case to
+misread the way Mantine's did, since MUI's `Chip` has no real underlying form control. A new
+`data-interactive` attribute (set from `isInteractive`) gates `cursor: pointer` in CSS; without it,
+the chip falls back to whatever MUI's own non-clickable `Chip` renders as (no cursor override, no
+`ButtonBase`).
+
+Separately, `.children`'s `overflow-x: hidden` (added for ellipsis truncation) made it a scroll
+container, and Chromium auto-adds scroll containers with actually-overflowing content to the Tab
+order — with no `tabindex` attribute at all — so a solo Tab press could land on a chip's plain
+filename text before ever reaching a real control. Switched to `overflow-x: clip`, which doesn't
+establish a scrollport (same visual clipping, still x-axis only per the descender fix above), so
+it's no longer a focus candidate. This affected every chip with long enough content, not just
+read-only ones — see `FileUpload`'s own `IMPLEMENTATION_NOTES.md` for how it surfaced there.

package/src/components/Chip/Chip.module.css

@@ -81,12 +81,22 @@
   max-width: var(--recursica_ui-kit_components_chip_properties_max-width);
   box-shadow: var(--recursica_ui-kit_components_chip_properties_elevation);
 
-  cursor: pointer;
   user-select: none;
-  overflow: hidden;
+  overflow-x: hidden; /* HARDCODE: horizontal-only — `overflow: hidden` on both axes was clipping
+    descenders (e.g. the "g" in "image.png") whenever the line-height token is tighter than the
+    font's natural glyph extent (Matt Massey, 2026-08-18); border-radius still renders correctly
+    on this box regardless of overflow, so rounded corners are unaffected */
+  overflow-y: visible;
   transition: all 0.2s ease;
 }
 
+/* Only a chip with a real handler (onRemove/onClick/onChange — see Chip.tsx's `isInteractive`)
+   gets the pointer cursor. A display-only chip (e.g. a read-only FileUpload file list) has
+   nothing for a click to do, so it shouldn't look clickable. */
+.root.root[data-interactive] {
+  cursor: pointer;
+}
+
 /* We target the mantine label directly because that is the visible container in Mantine's Chip */
 .label.label {
   box-sizing: border-box;
@@ -209,12 +219,21 @@
   align-items: center;
   gap: var(--recursica_ui-kit_components_chip_properties_icon-text-gap);
   width: 100%;
+  min-width: 0; /* HARDCODE: lets .children actually shrink and ellipsize instead of overflowing */
 }
 
 .children {
   flex-grow: 1;
+  min-width: 0; /* HARDCODE: a flex child needs this for text-overflow: ellipsis to engage at all */
   text-overflow: ellipsis;
-  overflow: hidden;
+  overflow-x: clip; /* HARDCODE: text-overflow: ellipsis only needs the x-axis clipped — clipping
+    y too (plain `overflow: hidden`) cut off descenders (e.g. the "g" in "image.png") whenever the
+    line-height token is tighter than the font's natural glyph extent (Matt Massey, 2026-08-18).
+    `clip` rather than `hidden` because `hidden` makes this a scroll container, and Chromium
+    auto-adds scroll containers with overflowing content to the Tab order (so a browser user can
+    arrow-key-scroll them) — `clip` doesn't create a scrollport, so long/truncated chip labels
+    (e.g. a read-only FileUpload file list) don't pick up a phantom, un-styled tab stop. */
+  overflow-y: visible;
   white-space: nowrap;
 }
 
@@ -225,6 +244,7 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  flex-shrink: 0; /* HARDCODE: keep the icon from being squeezed by a long, truncating label */
   color: var(--chip-icon);
   width: var(--recursica_ui-kit_components_chip_properties_icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_icon-size);
@@ -246,6 +266,7 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  flex-shrink: 0; /* HARDCODE: keep the remove icon visible when the label truncates instead */
   color: var(--chip-close);
   width: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
@@ -257,7 +278,12 @@
 }
 
 .removeIconWrapper.removeIconWrapper:focus-visible {
-  box-shadow: 0 0 0 2px var(--chip-border); /* HARDCODE: Focus indication */
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
 }
 
 .removeIconWrapper svg {

package/src/components/Chip/Chip.tsx

@@ -9,8 +9,14 @@ import styles from "./Chip.module.css";
 import { type RecursicaChipProps } from "@recursica/adapter-common";
 
 export type ChipProps = RecursicaOverStyled<
-  Omit<MuiChipProps, "variant" | "size" | "color" | "radius"> &
-    RecursicaChipProps
+  Omit<MuiChipProps, "variant" | "size" | "color" | "radius" | "children"> &
+    RecursicaChipProps & {
+      // MUI's own ChipProps types `children` as `null | undefined` (MUI's Chip expects `label`
+      // instead) — this component's actual API is `children` (see the `label={...}` JSX below,
+      // which always wins over any caller-supplied `label` in `sanitizedProps`), so restore a
+      // real type for it here.
+      children?: React.ReactNode;
+    }
 >;
 
 function CloseIcon(props: React.ComponentPropsWithoutRef<"svg">) {
@@ -56,8 +62,9 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
     error = false,
     icon,
     onRemove,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     removeLabel = "Remove",
+    removeTabIndex,
+    removeIconRef,
     children,
     checked,
     overStyled = false,
@@ -97,6 +104,14 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   const dataError = error ? "" : undefined;
   const dataChecked = checked ? "" : undefined;
   const isIconOnly = !children && (!!icon || !!onRemove);
+  // A chip only counts as interactive when something actually responds to it — merely passing a
+  // `checked` value (e.g. to pin a display-only chip to a fixed visual state, as FileUpload's
+  // read-only file list does) isn't itself an interaction, since clicking it with no onChange/
+  // onClick wired does nothing observable.
+  const isInteractive =
+    onRemove !== undefined ||
+    restRecord.onClick !== undefined ||
+    restRecord.onChange !== undefined;
 
   return (
     <MuiChip
@@ -106,6 +121,7 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
       {...(dataError !== undefined ? { "data-error": "" } : {})}
       {...(dataChecked !== undefined ? { "data-checked": "" } : {})}
       {...(isIconOnly ? { "data-icon-only": "" } : {})}
+      {...(isInteractive ? { "data-interactive": "" } : {})}
       {...sanitizedProps}
       icon={
         checked ? (
@@ -121,7 +137,27 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
       onDelete={onRemove}
       deleteIcon={
         onRemove ? (
-          <span className={styles.removeIconWrapper}>
+          <span
+            ref={removeIconRef}
+            role="button"
+            className={styles.removeIconWrapper}
+            aria-label={removeLabel}
+            tabIndex={removeTabIndex ?? 0}
+            onKeyDown={(e) => {
+              // MUI's own `onDelete` wiring only reacts to Backspace/Delete, and only when this
+              // span itself is both the event's target and currentTarget — neither holds once a
+              // parent (e.g. FileUpload's roving-tabindex group) moves real focus onto this span
+              // directly. A plain `<span>` also gets no native Enter/Space-triggers-click behavior
+              // the way a real `<button>` would, so it's handled explicitly here instead.
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                e.stopPropagation();
+                onRemove(
+                  e as unknown as React.MouseEvent<HTMLSpanElement, MouseEvent>,
+                );
+              }
+            }}
+          >
             <CloseIcon />
           </span>
         ) : undefined

package/src/components/Chip/USAGE.md

@@ -34,3 +34,22 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Sizing
+
+Chip does not support a `size` prop; chips render at a fixed size.
+
+### Building a keyboard-navigable chip group
+
+`removeTabIndex` and `removeIconRef` are optional escape hatches for composing a _group_ of chips
+with roving-tabindex keyboard navigation (Tab reaches one chip at a time, arrow keys move between
+them) — see `FileUpload`'s file list for a working example. Ignore both for a standalone chip; they
+default to a normal `tabIndex={0}` remove icon with no ref.
+
+Also pass a plain `tabIndex={-1}` on the `<Chip>` itself in a group like this — MUI's `Chip` root
+becomes a focusable element on its own whenever `onRemove` is set, which would otherwise be a
+second, unwanted tab stop ahead of the remove icon (see `CHIP_IMPLEMENTATION_NOTES.md`).

package/src/components/FileInput/FILEINPUT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,148 @@
+# FileInput Implementation Notes
+
+## Architecture overview
+
+`FileInput` replaces the previous "coming soon" stub with a fully custom composite, the same way
+`FileUpload` was built (see `../FileUpload/FILEUPLOAD_IMPLEMENTATION_NOTES.md`). It shares
+`FileUpload`'s selection/validation contract (`accept`/`maxSize`/`maxFiles`, `onFilesRejected`,
+`readOnly`) via a common `RecursicaFileUploadItem` type and near-identical `handleFiles`/drag
+logic, but is presented as a single-line, `TextField`-shaped control rather than a dropzone —
+Forge's own `file-input` token set is shaped almost identically to `text-field`'s (border-radius,
+horizontal/vertical padding, icon-size, icon-text-gap, min-height, placeholder-opacity, a full
+`text_*` type-style block), confirming the design intent directly rather than needing to guess it
+from the reference screenshot alone.
+
+The control is one clickable, focusable `<div role="button">` containing:
+
+1. **A leading icon** — the upload icon by default, overridable via `icon`.
+2. **A content area** — placeholder text when empty, or a horizontally scrollable row of `Chip`s
+   (reusing `FileUpload`'s chip, same as its file list) once one or more files are selected —
+   single- and multiple-file mode render identically here; only the selection/replace behavior
+   differs (see "`multiple` defaults to `false`" below).
+3. **A trailing "clear" `Button`** — shown whenever a file is selected; clears the entire current
+   selection (see "Trailing clear button" below).
+4. **A hidden `<input type="file">`**, triggered programmatically — same approach as
+   `FileUpload`'s dropzone, not the "invisible overlay input" pattern some styled file inputs use
+   (that pattern would need every interactive child — chip remove icons, the clear icon — to sit
+   at a higher stacking context than the overlay just to receive its own clicks; keeping the input
+   hidden and driving it via `ref.click()` avoids that entirely).
+
+## The stub's exemption comments described a schema that no longer exists
+
+Before writing any CSS, the stub `FileInput.module.css`'s 43 `recursica-ignore` comments were
+checked against `packages/official-release/recursica_variables_scoped.css` directly, rather than
+trusted as the token inventory. They didn't match — the stub encoded a `states.default`/
+`states.focus`-shaped schema (mirroring the same stale-plugin-export drift documented in
+`docs/alignment/ALIGNMENT_2026-08-11.md` §3.2 for other components) that the current export has
+never had for `file-input`. The real schema (40 variables, matching that report's own L5 count)
+has:
+
+- **Flat, non-state-scoped base properties and colors** (`properties_border-size`,
+  `properties_colors_{background-color,border-color,leading-icon,text-color,trailing-icon}`) —
+  much closer to `TextField`'s shape than `FileUpload`'s.
+- **Only two states — `disabled` and `error`.** No `default` state (the flat properties above
+  are the default) and no `focus` state at all.
+- **`layouts.{stacked,side-by-side}` each carrying their own `max-width`/`min-width`/
+  `top-bottom-margin`** — three properties per layout, not the single flat `max-width`/
+  `min-width` an early draft of this component assumed.
+
+Every token actually referenced in `FileInput.module.css` was re-verified against this real list
+(38 applied + 2 exempted = 40, zero gap on either adapter).
+
+## No forge-defined focus state — generic ring, same fallback as TextField
+
+Since `file-input` has no `states.focus` axis, `:focus-visible` on the root falls back to the
+generic `--recursica_brand_states_focus_*` box-shadow ring, exactly like `TextField`/`DatePicker`
+already do for the same reason.
+
+## Disabled/error border-size intentionally unused
+
+Unlike `FileUpload` (which has no border-size token at all to choose from), `file-input`'s export
+does define real per-state `border-size` variables for `disabled` and `error`. They're
+`recursica-ignore`d anyway and the flat `properties_border-size` is applied uniformly instead —
+same house policy `TextField`/`DatePicker` already follow (a border that changes thickness across
+states shifts the layout), just applied here to real rather than phantom tokens.
+
+## Why the root is a focusable, clickable `<div>` (a deliberate divergence from FileUpload)
+
+`FileUpload`'s dropzone deliberately has no `onClick`/`role="button"`/`tabIndex` of its own — the
+separate "Browse files" `<Button>` is its sole click/keyboard affordance, avoiding a
+nested-interactive-element ambiguity (see `FILEUPLOAD_IMPLEMENTATION_NOTES.md`, "Not a nested
+interactive element"). `FileInput` has no separate Browse button in the reference design — the
+box itself plays that role, the same way a real `<input type="file">` is its own focusable,
+clickable, `Enter`/`Space`-activatable control. So it needs to be one directly: `role="button"`,
+`tabIndex={0}` when interactive, `onClick`/`onKeyDown` (`Enter`/`Space`) both call the same
+`openFilePicker`, and an explicit `aria-label` (`browseLabel`, defaulting to `"Choose file"`)
+since there's no native `<label for>` association available for a custom `div` the way a real
+`<input>` gets one implicitly.
+
+## `multiple` defaults to `false`, unlike `FileUpload`'s `true`
+
+The reference design shows "Single File" and "Multiple Files" as two distinct, deliberately-named
+usages, and a single-line `TextField`-shaped control reads most naturally as single-value by
+default — matching a native `<input type="file">`, which is single-file unless `multiple` is set.
+`FileUpload`'s dropzone is the opposite by design (it defaults to accepting a batch).
+
+## Single-file mode replaces; it doesn't append
+
+`onFilesAdded`/`onFileRemove` keep the exact same shape as `FileUpload`'s, but single-file mode's
+effective cap is hardcoded to 1 (`currentCount` is never read from the existing `files` prop in
+that mode) rather than counting the file already there — picking a new file is meant to replace
+the old one, not be rejected as "over the limit." This is a documentation convention, not special
+component state: see USAGE.md §2 for the "handlers typically replace, not append" note for
+single-file consumers. Dropping more than one file onto a single-file control still routes the
+extras to `onFilesRejected` via the same effective-cap-of-1 logic, with the default
+`maxFilesMessage` reading `"Only one file is allowed"` instead of `FileUpload`'s
+`"Maximum of N files allowed"` phrasing.
+
+## Trailing clear button
+
+The clear-all affordance shown whenever `files.length > 0` is a real shared `Button`
+(`variant="text" size="small"`, icon-only), not a bespoke `<span role="button">` — it gets real
+button semantics and keyboard handling for free, the same reasoning as `Tree`'s expand/collapse
+button (see `Tree.module.css`'s `.expandButton`). It's rendered through Button's own tokened
+color/disabled states, so `file-input`'s own `properties_colors_trailing-icon` token (and its
+`disabled`/`error` state variants) is `recursica-ignore`d rather than applied — it has no
+"clear button is disabled" state of its own anyway, since `disabled` already omits interactivity
+entirely. Clicking/activating it calls `onFileRemove` once per currently-selected file (reusing
+the same callback `FileUpload`'s individual chip removal uses, rather than introducing a separate
+`onClear` prop) — in single-file mode that's one call; in multiple-file mode it clears everything
+at once, distinct from a chip's own individual remove icon.
+
+## Why each chip is wrapped with its own `stopPropagation`
+
+`FileUpload`'s chip list sits _below_ its dropzone, entirely outside the click-to-browse surface,
+so a click on a chip's body never risks also opening the file picker. `FileInput`'s chip row lives
+_inside_ the same clickable root, so each chip is wrapped in a thin `<span onClick={(e) =>
+e.stopPropagation()}>` — blank space within the row (and the leading icon/placeholder/filename
+text) still bubbles up to open the picker, but clicking directly on a chip's body doesn't also
+trigger it. Chip's own remove icon already calls `stopPropagation` internally (see `Chip.tsx`), so
+it needed no changes for this.
+
+## Keyboard navigation for the chip row
+
+Same roving-tabindex model as `FileUpload`'s file list (`activeChipIndex`, `removeIconRefs`,
+Left/Right/Up/Down roving, focus-survives-removal `useEffect`) — reused rather than reinvented,
+and applies in single-file mode too (a one-chip roving group is a no-op but needs no special
+casing). The only addition specific to `FileInput` is that `Tab` reaches the root control itself
+first (since it's the click/keyboard surface for opening the picker), _then_ the chip row's
+roving group, _then_ the trailing clear button as its own stop.
+
+## The chip row scrolls horizontally instead of wrapping or clipping
+
+`.chipRow` uses `overflow-x: auto; overflow-y: hidden` rather than `FileUpload`'s file list, which
+wraps onto multiple lines below the dropzone — `FileInput` is a fixed single-line, `min-height`d
+control, so wrapping would grow it vertically. Enough chips to overflow the control's own width
+scroll horizontally within it instead (mouse wheel/trackpad or a native scrollbar), same tradeoff
+already made for `.value`'s ellipsis truncation.
+
+## Read-only vs disabled
+
+`readOnly` renders the same content (placeholder/filename/chip row) but the root loses its
+`role="button"` interactivity (no `tabIndex`, no click/keyboard/drag handlers), chips render with
+no `removeLabel`/`onRemove` (so `Chip` itself renders no remove icon, same as `FileUpload`'s
+read-only chips), and the trailing clear icon is omitted entirely. `disabled` keeps the control
+structurally the same but inert (`tabIndex={-1}`, `aria-disabled`, no handlers, native `<input>`
+disabled) — both are computed together as a single `interactive` flag used throughout, but remain
+independently toggleable props (a `readOnly` control is never simultaneously `disabled` in
+practice, but nothing enforces that at the type level, matching `FileUpload`'s own convention).