@recursica/mantine-adapter 0.38.1 → 0.40.0

package/package.json

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

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -16,8 +16,8 @@ Decisions and design tweaks strictly tailored for the UI Kit's Accordion wrapped
 
 ## 2. Default Configuration Reset (`unstyled`)
 
-**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
-**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
+**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging Mantine's own `variant="unstyled"`. That Mantine sentinel is an internal implementation detail, not something a Recursica consumer should ever set directly — `RecursicaAccordionProps.variant` is `"default" | (string & {})`: `"default"` is the only value with dedicated Recursica styling, mapped internally via `mapVariant` in `Accordion.tsx`; any other string is a caller-supplied custom variant and passes straight through to Mantine unmapped.
+**Implementation:** `AccordionBase` defaults `variant` to Recursica's `"default"`, looks it up in `mapVariant` (`{ default: "unstyled" }`), and passes the resolved value (or the original string, if it wasn't a recognized key) to `<MantineAccordion variant={...}>`. The `"default"` → `"unstyled"` mapping effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
 
 ---
 
@@ -46,3 +46,17 @@ Decisions and design tweaks strictly tailored for the UI Kit's Accordion wrapped
 
 **Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
 **Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.
+
+---
+
+## 7. Native `icon` slot is omitted on `AccordionControl`
+
+**Decision:** Mantine's `AccordionControl` has its own native `icon` prop — a distinct,
+documented slot ("icon displayed next to the label") — which the adapter reuses internally
+to render Recursica's `leftIcon`. Left unguarded, a caller could pass native `icon` directly
+and silently override the `leftIcon`-derived element (spread order would let it win).
+**Implementation:** `AccordionControlWrapperProps` omits `icon` from Mantine's native
+`AccordionControlProps` before merging in `RecursicaAccordionControlProps`, so the only way
+to set that slot is through `leftIcon`. Mantine's separate, per-control `chevron` override
+is _not_ omitted — nothing here computes it, so it still passes through safely if a caller
+wants to override the cascaded container-level chevron for a single item.

package/src/components/Accordion/Accordion.module.css

@@ -159,7 +159,7 @@
    constant background (Mantine's native :hover CSS would otherwise show through) and use an
    overlay ::after structure with the generic hover tokens for the actual hover tint; no per-item
    hover-color/hover-opacity tokens exist anymore. */
-.control:hover {
+.control:hover:not(:disabled) {
   background-color: var(
     --recursica_ui-kit_components_accordion-header_variants_appearance_closed_properties_colors_background-color
   );
@@ -179,6 +179,15 @@
   opacity: var(--recursica_brand_states_hover_opacity);
 }
 
+/* Dims the whole item — control and any currently-visible panel content alike — using the
+   generic disabled opacity token, same convention as every other disabled component in the
+   design system (no accordion-item-specific disabled token exists). The Control's own native
+   `disabled` attribute already blocks click/keyboard interaction on its own; this only
+   handles the visual dim. */
+.item[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+}
+
 /* Recursica focus ring instead of Mantine's default `.mantine-focus-auto:focus-visible` outline
    (same class+pseudo-class specificity, so !important guarantees ours wins regardless of CSS
    import order). */

package/src/components/Accordion/Accordion.stories.tsx

@@ -153,6 +153,42 @@ export const LongTitleTruncation: StoryObj<typeof Accordion> = {
   },
 };
 
+export const Disabled: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Accordion defaultValue="expanded-disabled" chevron={<ChevronIcon />}>
+        <Accordion.Item value="expanded-disabled" disabled>
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Expanded and Disabled
+          </Accordion.Control>
+          <Accordion.Panel>
+            This item starts expanded so the panel content's dimming can be
+            verified alongside the control's, not just the collapsed header.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="collapsed-disabled" disabled>
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Collapsed and Disabled
+          </Accordion.Control>
+          <Accordion.Panel>
+            Clicking or tabbing to this control should have no effect.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="enabled">
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Enabled, for Comparison
+          </Accordion.Control>
+          <Accordion.Panel>
+            A normal, interactive item alongside the disabled ones above.
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    );
+  },
+};
+
 /** Demonstrates the component nested inside a non-default layer — the one case where an
  * explicit `<Layer>` wrap belongs in a story (see COMPONENT_STORYBOOK_GUIDE.md §9). */
 export const LayerOne: StoryObj<typeof Accordion> = {

package/src/components/Accordion/Accordion.tsx

@@ -16,6 +16,7 @@ import {
   type RecursicaAccordionProps,
   type RecursicaAccordionItemProps,
   type RecursicaAccordionControlProps,
+  type RecursicaAccordionPanelProps,
 } from "@recursica/adapter-common";
 
 // ==== ACCORDION CONTAINER ====
@@ -27,11 +28,24 @@ export type AccordionProps = RecursicaOverStyled<
     RecursicaAccordionProps
 >;
 
+// Maps Recursica's public variant vocabulary to Mantine's own. `unstyled` is a Mantine
+// sentinel with no meaning to Recursica consumers — it exists only to suppress Mantine's
+// built-in variant CSS so our module CSS is the sole source of styling. Anything outside
+// this map (a caller-supplied custom variant string) passes straight through to Mantine.
+const mapVariant: Record<string, string> = {
+  default: "unstyled",
+};
+
 const AccordionBase = function Accordion({
-  variant = "unstyled",
+  variant = "default",
   overStyled = false,
   ...rest
 }: AccordionProps) {
+  const resolvedVariant =
+    typeof variant === "string" && mapVariant[variant]
+      ? mapVariant[variant]
+      : variant;
+
   const sanitizedProps = filterStylingProps(rest, overStyled);
 
   // Bind all deep CSS module references natively into the global class mapping schema
@@ -67,7 +81,7 @@ const AccordionBase = function Accordion({
 
   return (
     <MantineAccordion
-      variant={variant}
+      variant={resolvedVariant as MantineAccordionProps["variant"]}
       className={classNameProp}
       classNames={mergedClassNames}
       {...(sanitizedProps as unknown as MantineAccordionProps)}
@@ -85,7 +99,15 @@ export const AccordionItem = forwardRef<
   HTMLDivElement,
   AccordionItemWrapperProps
 >(function AccordionItem(
-  { title, leftIcon, divider = true, children, overStyled = false, ...rest },
+  {
+    title,
+    leftIcon,
+    divider = true,
+    children,
+    disabled = false,
+    overStyled = false,
+    ...rest
+  },
   ref,
 ) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -99,15 +121,22 @@ export const AccordionItem = forwardRef<
 
   // If the user utilizes the explicit 'title' prop from Recursica, we securely auto-construct the Mantine sub-hierarchy natively!
   // If not, we defer to raw composable children (meaning the integrator maps `<Accordion.Control>` manually).
+  // `disabled` has no native concept at the Item level — only Control has a real `disabled`
+  // prop (it renders a `<button>`, so the native HTML `disabled` attribute alone blocks click,
+  // focus, and keyboard activation with no extra guards needed). We forward it there in the
+  // auto-composed path; a manually-composed `<Accordion.Control>` needs it passed explicitly.
   return (
     <MantineAccordion.Item
       ref={ref}
       className={finalClass}
+      data-disabled={disabled || undefined}
       {...(sanitizedProps as unknown as AccordionItemProps)}
     >
       {title ? (
         <>
-          <AccordionControl leftIcon={leftIcon}>{title}</AccordionControl>
+          <AccordionControl leftIcon={leftIcon} disabled={disabled}>
+            {title}
+          </AccordionControl>
           <AccordionPanel>{children}</AccordionPanel>
         </>
       ) : (
@@ -120,7 +149,10 @@ AccordionItem.displayName = "AccordionItem";
 
 // ==== ACCORDION CONTROL ====
 export type AccordionControlWrapperProps = RecursicaOverStyled<
-  AccordionControlProps & RecursicaAccordionControlProps
+  // Mantine's native `icon` slot is resolved internally from `leftIcon` — omitted so a
+  // caller can't silently override it by passing `icon` directly. Mantine's per-control
+  // `chevron` override is left as-is; nothing here computes it, so it passes through safely.
+  Omit<AccordionControlProps, "icon"> & RecursicaAccordionControlProps
 >;
 
 export const AccordionControl = forwardRef<
@@ -154,8 +186,9 @@ export const AccordionControl = forwardRef<
 AccordionControl.displayName = "AccordionControl";
 
 // ==== ACCORDION PANEL ====
-export type AccordionPanelWrapperProps =
-  RecursicaOverStyled<AccordionPanelProps>;
+export type AccordionPanelWrapperProps = RecursicaOverStyled<
+  AccordionPanelProps & RecursicaAccordionPanelProps
+>;
 
 export const AccordionPanel = forwardRef<
   HTMLDivElement,

package/src/components/AssistiveElement/ASSISTIVEELEMENT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,45 @@
+# AssistiveElement – implementation notes
+
+Decisions and design tweaks specific to the UI Kit's AssistiveElement wrapped against
+`@mantine/core`.
+
+---
+
+## 1. Plain `<div>` — no underlying component wrapped
+
+**Decision:** Unlike most components in this adapter, `AssistiveElement` doesn't wrap any real
+`@mantine/core` component at all — it's a bare `<div>` with two `<span>` wrappers (icon, text).
+Mantine has no dedicated helper/error-text component to wrap in the first place (it composes
+that presentation ad hoc per-field via `TextInput`'s own `error`/`description` props instead of
+a standalone component), so there's nothing here to inherit layout or ARIA semantics from.
+**Implementation:** A `<div>` is a reasonable generic container, but it carries no semantic
+meaning of its own. `role="alert"` is now defaulted automatically for the `"error"` variant
+(see §3) — the one piece of ARIA behavior that genuinely belongs at this component's own level.
+`aria-describedby`/`aria-errormessage` association with a field is a different story: this
+component has no reference to any sibling field, so it can't wire that itself. It's already
+handled one layer up, in `FormControlWrapper` — which generates the ids, passes them down via
+this component's own `id` prop, and clones `aria-describedby`/`aria-errormessage` onto the
+field. Only a fully standalone `<AssistiveElement>` used outside `FormControlWrapper` still
+needs that wiring done by hand, via the standard HTML attributes that pass through `{...rest}`.
+
+---
+
+## 2. Fixed icon per variant, no custom icon slot
+
+**Decision:** `assistiveWithIcon` only toggles visibility — there's no prop to swap in a custom
+icon. The icon is always the one belonging to the current `assistiveVariant` (`InfoIcon` for
+`"help"`, `AlertIcon` for `"error"`).
+**Implementation:** `IconComponent = assistiveVariant === "error" ? AlertIcon : InfoIcon` is
+resolved directly in the render body; there's no icon prop in `RecursicaAssistiveElementProps`
+to intercept.
+
+---
+
+## 3. `role="alert"` defaults on for the error variant
+
+**Decision:** Error text needs to be announced by assistive tech as it appears or changes;
+static help text doesn't. Rather than requiring every integrator to remember `role="alert"`,
+`assistiveVariant="error"` defaults it automatically.
+**Implementation:** `role` is destructured out and resolved as `role ?? (assistiveVariant ===
+"error" ? "alert" : undefined)` before the spread — an explicit caller-supplied `role` always
+wins over the default, and `"help"` gets no default at all.

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -52,6 +52,7 @@ export const AssistiveElement = forwardRef<
     assistiveWithIcon = true,
     children,
     className,
+    role,
     overStyled = false,
     ...rest
   },
@@ -65,13 +66,19 @@ export const AssistiveElement = forwardRef<
 
   const IconComponent = assistiveVariant === "error" ? AlertIcon : InfoIcon;
 
+  // Announce error text as it appears/changes; a caller-supplied `role` always wins. No
+  // default for `help` — static descriptive text doesn't need a live region.
+  const resolvedRole =
+    role ?? (assistiveVariant === "error" ? "alert" : undefined);
+
   return (
     <div
       ref={ref}
       className={finalClass}
       data-variant={assistiveVariant}
+      role={resolvedRole}
       style={restRecord.style as React.CSSProperties}
-      {...restRecord} // Spread standard HTML attributes (like id, aria-*, role) natively.
+      {...restRecord} // Spread standard HTML attributes (like id, aria-*) natively.
     >
       {assistiveWithIcon && (
         <span className={styles.iconWrapper}>

package/src/components/AutoComplete/AutoComplete.tsx

@@ -151,10 +151,7 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
             disabled={disabled}
             value={value as string | undefined}
             defaultValue={defaultValue as string | undefined}
-            wrapperProps={{
-              "data-disabled": disabled ? "true" : undefined,
-              "data-error": error ? "true" : undefined,
-            }}
+            error={!!error}
             {...(sanitizedProps as unknown as MantineAutocompleteProps)}
           />
         }

package/src/components/Avatar/AVATAR_IMPLEMENTATION_NOTES.md

@@ -22,3 +22,13 @@ Since Avatar children (icons or initials) require robust centering that might di
 ### CSS Reset Hacks
 
 Noticeable `/* HARDCODE: ... */` hacks are deployed within `.root` to completely zero-out Mantine's `--avatar-bg` and internal variables statically since Recursica handles background-colors inherently via the CSS variants cascade.
+
+### `variant` mapping is a genuine match here (unlike MUI's)
+
+Mantine's native `Avatar.variant` (`'filled'|'light'|'gradient'|'outline'|'transparent'|...`)
+really is the same color-treatment concept Recursica's own `variant` is, so `mapVariant`
+(`solid→filled, outline→outline, ghost→transparent`) is a correct, meaningful mapping — even
+though the CSS reset hack above means it's visually inert either way. Worth noting only because
+the MUI adapter's `Avatar.variant` means something completely different (shape) and had a real
+bug from assuming the same word meant the same thing there; see mui-adapter's own
+`AVATAR_IMPLEMENTATION_NOTES.md`.

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.