@recursica/adapter-mantine-v8 1.0.0

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -0,0 +1,252 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Dropdown } from "./Dropdown";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOption } from "../../utils/renderRichOption";
+import styles from "./Dropdown.module.css";
+
+type DropdownStoryProps = React.ComponentProps<typeof Dropdown>;
+
+const meta: Meta<DropdownStoryProps> = {
+  title: "UI-Kit/Dropdown",
+  component: Dropdown,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Dropdown provides a selectable list of options, mapping natively over Mantine's Select component encapsulated within the standardized FormControlWrapper.",
+      },
+    },
+  },
+  args: {
+    label: "Country Selection",
+    assistiveText: "Select your country of origin.",
+    placeholder: "Pick value",
+    data: ["United States", "Canada", "Mexico", "United Kingdom", "France"],
+    disabled: false,
+    required: false,
+    readOnly: false,
+    clearable: false,
+  },
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+    },
+    clearable: {
+      control: "boolean",
+    },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
+    containerWidth: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<DropdownStoryProps>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Clearable: Story = {
+  args: {
+    label: "Clearable Options",
+    clearable: true,
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Destination",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z"></path>
+        <circle cx="12" cy="10" r="3"></circle>
+      </svg>
+    ),
+  },
+};
+
+const UserIcon = (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"></path>
+    <circle cx="12" cy="7" r="4"></circle>
+  </svg>
+);
+
+export const WithRichOptions: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Pick a team member",
+    assistiveText:
+      "Each option can show a leading icon and supporting text — see MANTINE_ADAPTER_RICH_OPTION_DATA.md.",
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: UserIcon,
+        supportingText: "jane.doe@example.com",
+      },
+      {
+        value: "asmith",
+        label: "Alex Smith",
+        leadingIcon: UserIcon,
+        supportingText: "alex.smith@example.com",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+  },
+};
+
+export const WithRichOptionsWrapped: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Pick a team member",
+    wrapItemText: true,
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe, Senior Staff Engineer, Platform Infrastructure",
+        leadingIcon: UserIcon,
+        supportingText:
+          "jane.doe@example.com — Platform Infrastructure team, on-call rotation lead",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+    assistiveText:
+      "wrapItemText=true — long label/supportingText wrap instead of truncating.",
+  },
+};
+
+const optionRowPreviewClassNames = {
+  optionContent: styles.optionContent,
+  optionIcon: styles.optionIcon,
+  optionText: styles.optionText,
+  optionTextWrap: styles.optionTextWrap,
+  optionSupportingText: styles.optionSupportingText,
+};
+
+const OPTION_ROW_PREVIEW_ITEMS = [
+  {
+    value: "icon-and-supporting",
+    label: "Jane Doe",
+    leadingIcon: UserIcon,
+    supportingText: "jane.doe@example.com",
+  },
+  {
+    value: "no-icon",
+    label: "Alex Smith",
+    supportingText:
+      "No leadingIcon — label/supportingText shift left, no reserved icon space",
+  },
+  {
+    value: "no-supporting-text",
+    label: "Taylor Rivera",
+    leadingIcon: UserIcon,
+  },
+  {
+    value: "plain",
+    label: "Plain option — no leadingIcon, no supportingText",
+  },
+  {
+    value: "long-text",
+    label:
+      "A very long option label that, with wrapItemText, wraps onto a second line instead of overflowing the fixed-width dropdown — otherwise it truncates with an ellipsis",
+    leadingIcon: UserIcon,
+    supportingText:
+      "A similarly long supporting text string, to confirm the same wrap-or-truncate behavior applies to it too",
+  },
+];
+
+// Renders the option row content directly — outside the floating/portal menu — inside a
+// container sized to Dropdown's own max-width token. Spacing between rows, icon/supportingText
+// presence-or-absence alignment, and long-text wrapping/truncation are all much easier to inspect
+// this way than by opening the real (portal-rendered) combobox dropdown. See
+// MANTINE_ADAPTER_RICH_OPTION_DATA.md.
+const renderOptionRowPreview = (wrapItemText: boolean) => (
+  <div
+    className={styles.dropdown}
+    style={{
+      width:
+        "var(--recursica_ui-kit_components_dropdown_variants_layouts_stacked_properties_max-width)",
+    }}
+  >
+    {OPTION_ROW_PREVIEW_ITEMS.map((item) => (
+      <div key={item.value} className={styles.option}>
+        {renderRichOption(
+          { option: item },
+          optionRowPreviewClassNames,
+          wrapItemText,
+        )}
+      </div>
+    ))}
+  </div>
+);
+
+// Default: `wrapItemText` is false — label/supportingText truncate to a single line with an
+// ellipsis instead of wrapping.
+export const RichOptionRowPreview: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(false),
+};
+
+// `wrapItemText: true` — label/supportingText wrap onto additional lines instead of truncating.
+export const RichOptionRowPreviewWrapped: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(true),
+};
+
+export const StaticError: Story = {
+  args: {
+    error: "You must choose a valid destination.",
+    value: "Invalid Island",
+  },
+};
+
+export const StaticDisabled: Story = {
+  args: {
+    disabled: true,
+    value: "United States",
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Read Only View",
+    readOnly: true,
+    value: "Canada",
+  },
+};

package/src/components/Dropdown/Dropdown.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Dropdown component tests. Add tests here if/when needed.

package/src/components/Dropdown/Dropdown.tsx

@@ -0,0 +1,213 @@
+import React, { forwardRef } from "react";
+import {
+  Select as MantineSelect,
+  type SelectProps as MantineSelectProps,
+} from "@mantine/core";
+import {
+  type ReadOnlyControlProps,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOption } from "../../utils/renderRichOption";
+import styles from "./Dropdown.module.css";
+
+import { type RecursicaDropdownProps as BaseRecursicaDropdownProps } from "@recursica/adapter-common";
+
+export interface RecursicaDropdownProps
+  extends Omit<
+      MantineSelectProps,
+      "size" | "variant" | "radius" | "wrapperProps" | "data" | "searchable"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaDropdownProps {}
+
+export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
+
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+  "searchable", // Not a supported Dropdown feature — that's what makes it an AutoComplete.
+] as const satisfies readonly (keyof MantineSelectProps)[];
+
+export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
+  function Dropdown(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+      containerWidth,
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      data,
+      clearButtonProps,
+      renderOption,
+      wrapItemText = false,
+      ...rest
+    } = props;
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Mantine's own data parser only preserves extra fields (`leadingIcon`/`supportingText`) when
+    // an item already has both `value` and `label` — an item with `value` only is rebuilt into a
+    // bare `{value, label: value, disabled}` object, silently dropping them (see
+    // get-parsed-combobox-data.mjs, and AutoComplete.tsx's identical use of this). Matters here
+    // too now that `label` is optional (shared `RecursicaComboboxItem` — see adapter-common).
+    const normalizedData = normalizeComboboxData(data);
+
+    // Mantine's own clear button (rendered when `clearable` + a value are both present) otherwise
+    // renders unstyled — bare `CloseButton` defaults, no Recursica icon-button treatment. Merge in
+    // our own class (see `.clearButton` in Dropdown.module.css) alongside anything the caller
+    // already passed, same merge shape as `mergeClassNames` but for a single `className` string
+    // rather than a per-slot classNames map.
+    const consumerClearButtonProps = clearButtonProps as
+      | Record<string, unknown>
+      | undefined;
+    const mergedClearButtonProps = {
+      ...consumerClearButtonProps,
+      className: consumerClearButtonProps?.className
+        ? `${styles.clearButton} ${consumerClearButtonProps.className as string}`
+        : styles.clearButton,
+    };
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        dropdown: styles.dropdown,
+        option: styles.option,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    const optionClassNames = {
+      optionContent: styles.optionContent,
+      optionIcon: styles.optionIcon,
+      optionText: styles.optionText,
+      optionTextWrap: styles.optionTextWrap,
+      optionSupportingText: styles.optionSupportingText,
+    };
+
+    const injectedStyles = {
+      ...((style as React.CSSProperties) || {}),
+      width: containerWidth || "100%",
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={injectedStyles}
+        controlMaxWidth="var(--dropdown-control-max-width)"
+        controlMinWidth="var(--dropdown-control-min-width)"
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={
+          value !== undefined
+            ? String(value)
+            : defaultValue
+              ? String(defaultValue)
+              : undefined
+        }
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Select execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
+          <MantineSelect
+            ref={ref}
+            {...(sanitizedProps as unknown as MantineSelectProps)}
+            classNames={mergedClassNames}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            data={
+              (normalizedData as unknown as MantineSelectProps["data"]) || []
+            }
+            renderOption={
+              renderOption ??
+              ((input) =>
+                renderRichOption(input, optionClassNames, wrapItemText))
+            }
+            clearButtonProps={mergedClearButtonProps}
+            label={undefined}
+            description={undefined}
+            error={undefined}
+            required={undefined}
+            withAsterisk={undefined}
+            // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+            // stacking element) — a different, ancestor element from the "wrapper" styles-api slot
+            // that actually carries `styles.root`'s border/background. Dropdown.module.css's error/
+            // disabled rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that
+            // inner element, so `attributes.wrapper` (which targets the same slot as
+            // `classNames.wrapper`) is the correct hook — `wrapperProps` here meant the error state
+            // never actually applied a border color.
+            attributes={{
+              wrapper: {
+                "data-disabled": disabled ? "true" : undefined,
+                "data-error": error ? "true" : undefined,
+              },
+            }}
+          />
+        }
+      />
+    );
+  },
+);
+
+Dropdown.displayName = "Dropdown";

package/src/components/Dropdown/USAGE.md

@@ -0,0 +1,69 @@
+# Dropdown - Usage Guide
+
+This document describes how to integrate and use the `Dropdown` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Dropdown } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Dropdown } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Dropdown placeholder="Select an option">
+      <Dropdown.Item value="1">Option 1</Dropdown.Item>
+      <Dropdown.Item value="2">Option 2</Dropdown.Item>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **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. Notes
+
+- `Dropdown` is styled independently from `TextField`; even though they look similar, they are themed using separate design tokens.
+- Pass `leftSection` for a leading icon, and `clearable` (with a value present) to show a clear button — both render using the dropdown's own icon-color tokens.
+- `data` items can carry a `leadingIcon` and `supportingText`, rendered inside each option row:
+
+  ```tsx
+  <Dropdown
+    label="Assignee"
+    data={[
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: <UserIcon />,
+        supportingText: "jane.doe@example.com",
+      },
+      { value: "asmith", label: "Alex Smith" },
+    ]}
+  />
+  ```
+
+  Pass your own `renderOption` to opt out of this default rendering for a given instance.
+
+  By default `label`/`supportingText` truncate to a single line with an ellipsis. Set
+  `wrapItemText` to wrap them onto additional lines instead: `<Dropdown data={data} wrapItemText />`.

package/src/components/FileInput/FILEINPUT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,153 @@
+# 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, icon overridable via `clearIcon` (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. The icon itself defaults to the
+built-in X glyph and is overridable via `clearIcon` — the same pattern as the leading `icon`,
+giving Forge's `leading-icon`/`trailing-icon` token pair a matching pair of override props.
+
+## 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`, `deleteIconRefs`,
+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. The native scrollbar itself is hidden
+(`scrollbar-width: none`, `-ms-overflow-style: none`, `::-webkit-scrollbar { display: none }`) —
+the control's `min-height` isn't tall enough to host a visible horizontal scrollbar without
+clipping the chips, and scrolling (wheel/trackpad/drag) still works with it hidden.
+
+## 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 `deleteLabel`/`onDelete` (so `Chip` itself renders no delete 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).