@recursica/mantine-adapter 0.39.0 → 0.41.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.39.0",
+  "version": "0.41.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

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

@@ -401,3 +401,16 @@
     --recursica_ui-kit_components_button_variants_styles_text_variants_states_disabled_properties_elevation
   );
 }
+
+/* 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);
+}

package/src/components/Chip/CHIP_IMPLEMENTATION_NOTES.md

@@ -36,3 +36,62 @@ To accommodate this, the visual "close" icon uses a `<span>` element configured
 ### Removing Sizing Properties
 
 During implementation, the parsed Figma design tokens natively exported specific height/padding vectors dynamically (e.g., `--recursica_ui-kit_components_chip_properties_icon-size`) rather than explicit string variants (`sm`, `md`, `lg`). Therefore, we omitted `size` conceptually from the `RecursicaChipProps` wrapper to lock down size evaluation natively against the active layer variables.
+
+### Long-label truncation was hiding the remove icon (Matt Massey, 2026-08-17)
+
+`.children` already had `text-overflow: ellipsis; overflow: hidden; white-space: nowrap;`, but
+neither it nor its parent `.innerWrapper` had `min-width: 0` — a flex child without that refuses
+to shrink below its intrinsic (full, unwrapped) content width, so `text-overflow: ellipsis` never
+actually engaged. A long label overflowed the flex row instead, and since `.removeIcon` had no
+`flex-shrink: 0`, it got squeezed out of the clipped (`max-width`-bounded) chip entirely. Fixed by
+adding `min-width: 0` to `.innerWrapper`/`.children` and `flex-shrink: 0` to `.leadingIcon`/
+`.removeIcon`. Reproduces easily with `FileUpload`'s file list, since its chip `max-width`
+(`--recursica_ui-kit_components_chip_properties_max-width`, 200px) is small enough that most real
+filenames overflow it.
+
+### Descenders were being clipped on `.children` and `.root` (Matt Massey, 2026-08-18)
+
+A label with a descender (e.g. the "g" in "image.png") had its bottom clipped off. Both `.children`
+and `.root.root` set plain `overflow: hidden` — needed on the x-axis so `.children`'s
+`text-overflow: ellipsis` (and `.root`'s `max-width`) actually clip long labels, but clipping the
+y-axis too cuts off any glyph ink that extends past the line box, which happens whenever the
+`text_line-height` token is tighter than the font's natural ascent+descent. Fixed by splitting both
+into `overflow-x: hidden; overflow-y: visible;` — ellipsis/max-width truncation is unaffected (still
+x-axis only), but descenders can now paint outside a too-tight line box instead of being clipped.
+`.root` has no background/border-radius of its own to protect (that's `.label`), so opening its
+y-axis has no visual side effect.
+
+### 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 no-ops for a standalone `Chip` (defaults: `tabIndex={0}`,
+no ref) — this doesn't change any existing single-chip behavior.
+
+### `isInteractive` was measuring the wrong signal, and leaked a pointer cursor + phantom Tab stop (Matt Massey, 2026-08-18)
+
+A `Chip` rendered with `checked` but no real handler (e.g. `FileUpload`'s `readOnly` file list —
+`<Chip checked={false} tabIndex={-1}>`, no `onRemove`) still looked and behaved clickable, from two
+separate bugs:
+
+- `isInteractive` treated `checked !== undefined` (even `false`) as proof of interactivity. That's
+  the wrong signal — a `checked`-controlled chip with no `onChange` can't actually be toggled by a
+  click (Mantine's `useUncontrolled` discards the click when `value` is externally controlled), so
+  clicking it does nothing observable regardless. `isInteractive` now only looks at whether
+  something actually responds: `onRemove`, `onClick`, or `onChange`.
+- `.label.label` never set its own `cursor`, so Mantine's base style (`cursor: pointer`, hardcoded
+  on the underlying `mantine-Chip-label` class) always leaked through, independent of whether the
+  chip was actually interactive. Reset it to `cursor: default` and added a `data-interactive`
+  attribute (driven by the fixed `isInteractive` above, set via `wrapperProps` on `MantineChip` so
+  it lands on `.root`) that re-enables `pointer` via `.root[data-interactive] .label.label` only
+  when there's a real handler.
+
+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

@@ -53,9 +53,11 @@
     --recursica_ui-kit_components_chip_properties_border-radius
   );
 
-  cursor: pointer;
   user-select: none;
-  overflow: hidden;
+  overflow-x: hidden; /* HARDCODE: horizontal-only, same descender reasoning as .children below —
+    .root has no visible background of its own (that's .label), so there's nothing here that
+    needs vertical clipping */
+  overflow-y: visible;
 }
 
 /* We target the mantine label directly because that is the visible container in Mantine's Chip */
@@ -67,6 +69,10 @@
 
   /* Reset mantine styles */
   background: transparent; /* HARDCODE: Mantine forces background styling on label */
+  cursor: default; /* HARDCODE: Mantine's own base styles hardcode cursor: pointer on this class —
+    override it to plain default, then only re-enable it below for a chip with a real handler
+    (onRemove/onClick/onChange — see Chip.tsx's `isInteractive`). 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. */
   border-style: solid;
   border-width: var(--recursica_ui-kit_components_chip_properties_border-size);
   padding: var(--recursica_ui-kit_components_chip_properties_vertical-padding)
@@ -110,12 +116,22 @@
 .label.label > span:not(.mantineIconWrapper) {
   display: inline-flex;
   align-items: center;
+  flex: 1 1 auto; /* HARDCODE: let this anonymous wrapper actually fill/shrink to .label's real
+    width instead of sizing to its content — otherwise a long .children label overflows this
+    span well past .label's 200px max-width, and .children's own text-overflow: ellipsis never
+    engages because ITS box is still as wide as the unwrapped text (see CHIP_IMPLEMENTATION_NOTES.md) */
+  min-width: 0; /* HARDCODE: flex items default to min-width: auto (their content's min-content
+    size) — without this override, flex-shrink is a no-op and the span never shrinks below that */
 }
 
 .label.label:hover {
   background-color: var(--chip-bg);
 }
 
+.root[data-interactive] .label.label {
+  cursor: pointer;
+}
+
 /* Default (Unselected) hover/active interactions (Mantine overrides) */
 .label.label[data-checked] {
   --chip-bg: var(
@@ -191,12 +207,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;
 }
 
@@ -204,6 +229,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);
@@ -218,6 +244,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);
@@ -227,7 +254,12 @@
 }
 
 .removeIcon: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);
 }
 
 .removeIcon svg {

package/src/components/Chip/Chip.tsx

@@ -41,6 +41,8 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
     icon,
     onRemove,
     removeLabel = "Remove",
+    removeTabIndex,
+    removeIconRef,
     children,
     overStyled = false,
     ...rest
@@ -79,18 +81,24 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   // Determine state
   const dataError = error ? "" : 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 =
-    restRecord.checked !== undefined ||
-    restRecord.defaultChecked !== undefined ||
     onRemove !== undefined ||
-    restRecord.onClick !== undefined;
+    restRecord.onClick !== undefined ||
+    restRecord.onChange !== undefined;
 
   return (
     <MantineChip
       ref={ref}
       className={finalClass}
       classNames={mergedClassNames}
-      wrapperProps={dataError !== undefined ? { "data-error": "" } : undefined}
+      wrapperProps={{
+        ...(dataError !== undefined ? { "data-error": "" } : {}),
+        ...(isInteractive ? { "data-interactive": "" } : {}),
+      }}
       {...(isIconOnly ? { "data-icon-only": "" } : {})}
       {...(!isInteractive ? { tabIndex: -1, "aria-hidden": true } : {})}
       {...sanitizedProps}
@@ -106,6 +114,7 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
 
         {onRemove && (
           <span
+            ref={removeIconRef}
             role="button"
             className={styles.removeIcon}
             onClick={(e) => {
@@ -123,7 +132,7 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
                 );
               }
             }}
-            tabIndex={0}
+            tabIndex={removeTabIndex ?? 0}
           >
             <CloseIcon />
           </span>

package/src/components/Chip/USAGE.md

@@ -46,3 +46,10 @@ The remove/close action is keyboard accessible — it can be activated via keybo
 ### 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.

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).