@recursica/mui-adapter 0.21.1 → 0.23.0

package/src/components/Checkbox/Checkbox.module.css

@@ -86,8 +86,14 @@
   );
 }
 
-/* Base explicit reset masking underlying framework defaults */
+/* Base explicit reset masking underlying framework defaults.
+   display: flex + centering: the checkmark icon renders as a nested child of this box
+   (see Checkbox.tsx — icon/checkedIcon are combined nodes, icon inside .input), so this
+   box has to center it itself rather than relying on a parent's centering. */
 .input {
+  display: flex;
+  align-items: center;
+  justify-content: center;
   cursor: pointer; /* HARDCODE: core interaction behavior */
   appearance: none; /* HARDCODE: reset native widget */
   box-sizing: border-box; /* HARDCODE: ensures size includes borders */
@@ -199,7 +205,14 @@
   );
 }
 
+/* display: flex (not the browser default block) blockifies the native inline <label>
+   child per the CSS Display spec's flex-item blockification rule — matches Mantine's
+   own labelWrapper (inline-flex), whose flex context does the same to its label.
+   Without it, the label stays inline and its line box picks up extra half-leading
+   height, visually shifting it below vertical center against the checkbox. */
 .labelWrapper {
+  display: flex;
+  flex-direction: column;
   padding: 0; /* HARDCODE: structural layout reset */
   margin: 0; /* HARDCODE: structural layout reset */
   flex: 1;
@@ -250,26 +263,9 @@
   );
 }
 
-.description {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #868e96; /* HARDCODE: mantine default dimmed */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.error {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #fa5252; /* HARDCODE: mantine default error */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.description[data-disabled="true"],
-.error[data-disabled="true"] {
-  opacity: var(
-    --recursica_ui-kit_components_checkbox-item_variants_states_disabled_properties_opacity
-  );
-}
+/* description/error text renders via AssistiveElement directly (see Checkbox.tsx) —
+   it owns its own tokenized styling. AssistiveElement has no disabled state and
+   must never dim. */
 
 /* CheckboxGroup Layouts */
 .groupRoot {

package/src/components/Checkbox/Checkbox.tsx

@@ -17,6 +17,7 @@ import {
   FormControlLayout,
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 
 import styles from "./Checkbox.module.css";
 
@@ -96,6 +97,12 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
     const isChecked = isGrouped
       ? (groupContext.value || []).includes(restRecord.value)
       : !!(restRecord.checked ?? restRecord.defaultChecked);
+    // Only force controlled mode when we actually own the source of truth (grouped) or the
+    // caller explicitly passed `checked` (controlled). A plain `defaultChecked`/neither-prop
+    // usage must stay uncontrolled — otherwise `checked` gets pinned to a value that never
+    // updates, and MUI's native input silently snaps back after every click. Mirrors Switch's
+    // identical `isGrouped ? { checked: ... } : {}` pattern (Switch never had this bug).
+    const isControlled = isGrouped || restRecord.checked !== undefined;
 
     if (readOnly && !!readOnlyComponent) {
       const ReadOnlyComp = readOnlyComponent;
@@ -166,8 +173,9 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
         classes={mergedClassNames}
         disabled={readOnly || disabled || isGroupReadOnly}
         {...(sanitizedProps as unknown as MuiCheckboxProps)}
-        checked={isChecked as boolean}
+        {...(isControlled ? { checked: isChecked as boolean } : {})}
         onChange={handleChange}
+        disableRipple
         sx={label ? { padding: 0 } : undefined}
         icon={<div className={styles.input} />}
         checkedIcon={
@@ -204,25 +212,23 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
             >
               {label as React.ReactNode}
             </label>
-            {description && (
-              <div
-                className={styles.description}
-                data-disabled={
-                  readOnly || disabled || isGroupReadOnly ? true : undefined
-                }
-              >
-                {description}
-              </div>
-            )}
-            {error && (
-              <div
-                className={styles.error}
-                data-disabled={
-                  readOnly || disabled || isGroupReadOnly ? true : undefined
-                }
+            {/* description/error are mutually exclusive — error takes precedence */}
+            {error ? (
+              <AssistiveElement
+                assistiveVariant="error"
+                assistiveWithIcon={false}
               >
                 {error}
-              </div>
+              </AssistiveElement>
+            ) : (
+              description && (
+                <AssistiveElement
+                  assistiveVariant="help"
+                  assistiveWithIcon={false}
+                >
+                  {description}
+                </AssistiveElement>
+              )
             )}
           </div>
         </div>

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;
@@ -128,8 +138,6 @@
   background-color: var(--chip-bg);
   border-color: var(--chip-border);
   color: var(--chip-text);
-  min-width: var(--recursica_ui-kit_components_chip_properties_min-width);
-  max-width: var(--recursica_ui-kit_components_chip_properties_max-width);
   box-shadow: var(--recursica_ui-kit_components_chip_properties_elevation);
 
   transition: all 0.2s ease;
@@ -195,11 +203,12 @@
   cursor: not-allowed;
 }
 
-/* Override Mantine's built-in check icon colors and size if we keep it */
-.mantineIconWrapper.mantineIconWrapper {
+/* Selected-state check icon colors and size */
+.checkIconWrapper.checkIconWrapper {
   color: var(--chip-icon);
   width: var(--recursica_ui-kit_components_chip_properties_icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  margin-left: 0;
   margin-right: var(
     --recursica_ui-kit_components_chip_properties_icon-text-gap
   );
@@ -210,22 +219,40 @@
   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;
 }
 
-.leadingIcon {
+/* Doubled selector for specificity parity with MUI's own compound
+   `.MuiChip-root .MuiChip-icon` rule, which otherwise wins outright on a
+   plain single-class selector and leaks its default margin/color. */
+.leadingIcon.leadingIcon {
   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);
+  /* Reset MUI's default icon margin, keep the icon-text gap */
+  margin-left: 0;
+  margin-right: var(
+    --recursica_ui-kit_components_chip_properties_icon-text-gap
+  );
 }
 
 .leadingIcon svg {
@@ -233,10 +260,13 @@
   height: 100%;
 }
 
-.removeIconWrapper {
+/* Doubled selector for specificity parity with MUI's own compound
+   `.MuiChip-root .MuiChip-deleteIcon` rule (same reasoning as .leadingIcon). */
+.removeIconWrapper.removeIconWrapper {
   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);
@@ -247,8 +277,13 @@
   margin: 0;
 }
 
-.removeIconWrapper:focus-visible {
-  box-shadow: 0 0 0 2px var(--chip-border); /* HARDCODE: Focus indication */
+.removeIconWrapper.removeIconWrapper:focus-visible {
+  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,10 +121,11 @@ 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 ? (
-          <span className={styles.mantineIconWrapper} aria-hidden>
+          <span className={styles.checkIconWrapper} aria-hidden>
             <CheckIcon />
           </span>
         ) : icon ? (
@@ -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`).