@recursica/adapter-mui-v7 1.0.0

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 `onDelete` 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 `onDelete`/`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
+`onDelete`/`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

@@ -0,0 +1,283 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
+/* HARDCODED VALUES
+   border-style: solid;  (Baseline reset)
+   box-sizing: border-box; (Baseline reset)
+   display: inline-flex; (Baseline reset)
+   align-items: center; (Baseline reset)
+   outline: none; (Accessible fallback)
+   padding: 0; (Override mantine default)
+   background: transparent; (Override mantine default)
+ */
+
+.root.root {
+  /* Set preset layout variables to override mantine defaults safely */
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  /* Token properties */
+  --chip-height: max-content; /* Sizing is driven by padding and line height */
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_leading-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_close-icon-color
+  );
+
+  /* Container geometry */
+  height: var(--chip-height);
+  border-radius: var(
+    --recursica_ui-kit_components_chip_properties_border-radius
+  );
+  border-style: solid;
+  border-width: var(--recursica_ui-kit_components_chip_properties_border-size);
+  padding: var(--recursica_ui-kit_components_chip_properties_vertical-padding)
+    var(--recursica_ui-kit_components_chip_properties_horizontal-padding);
+
+  /* Gap for native MUI icons */
+  gap: var(--recursica_ui-kit_components_chip_properties_icon-text-gap);
+
+  /* Background and colors */
+  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);
+
+  user-select: none;
+  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 (onDelete/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;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  /* Reset MUI styles */
+  background: transparent;
+  padding: 0;
+  border: none;
+  border-radius: 0;
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_chip_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_chip_properties_text_font-size);
+  font-weight: var(
+    --recursica_ui-kit_components_chip_properties_text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_chip_properties_text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_chip_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_chip_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_chip_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_chip_properties_text_text-transform
+  );
+
+  /* Token evaluation */
+  background-color: var(--chip-bg);
+  border-color: var(--chip-border);
+  color: var(--chip-text);
+  box-shadow: var(--recursica_ui-kit_components_chip_properties_elevation);
+
+  transition: all 0.2s ease;
+}
+
+/* Default (Unselected) hover/active interactions (Mantine overrides) */
+.root.root[data-checked] {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_selected-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_close-icon-color
+  );
+}
+
+.root.root[data-error] {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_leading-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_close-icon-color
+  );
+}
+
+.root.root[data-error][data-checked] {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_selected-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_close-icon-color
+  );
+}
+
+.root.root[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  cursor: not-allowed;
+}
+
+/* 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
+  );
+}
+
+.innerWrapper {
+  display: inline-flex;
+  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-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;
+}
+
+/* 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 {
+  width: 100%;
+  height: 100%;
+}
+
+/* Doubled selector for specificity parity with MUI's own compound
+   `.MuiChip-root .MuiChip-deleteIcon` rule (same reasoning as .leadingIcon). */
+.deleteIconWrapper.deleteIconWrapper {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* HARDCODE: keep the delete 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);
+  cursor: pointer;
+  border-radius: 50%; /* HARDCODE: Make focus ring rounded */
+  outline: none;
+  /* Reset MUI icon defaults */
+  margin: 0;
+}
+
+.deleteIconWrapper.deleteIconWrapper: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);
+}
+
+.deleteIconWrapper svg {
+  width: 100%;
+  height: 100%;
+}
+
+.root.root[data-icon-only] {
+  padding-left: var(
+    --recursica_ui-kit_components_chip_properties_vertical-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_chip_properties_vertical-padding
+  );
+}

package/src/components/Chip/Chip.stories.tsx

@@ -0,0 +1,154 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Chip } from "./Chip";
+
+type ChipStoryProps = React.ComponentProps<typeof Chip>;
+
+const meta: Meta<ChipStoryProps> = {
+  title: "UI-Kit/Chip",
+  component: Chip,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Chip component is used to represent interactive selections, descriptive tags, or dynamic filters natively bounded to Recursica variables. It can be used as a toggleable input, can render a custom leading `icon`, and handles close constraints automatically via the `onDelete` property.",
+      },
+    },
+  },
+  argTypes: {
+    error: {
+      control: "boolean",
+      description: "Applies the error state styling dynamically.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Applies disabled token states.",
+    },
+    checked: {
+      control: "boolean",
+      description: "Forces the visual selected state.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ChipStoryProps>;
+
+// The Default story exposing native properties for the playground.
+export const Default: Story = {
+  args: {
+    children: "Default Chip",
+    error: false,
+    disabled: false,
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+// Static Stories for Regression Snapshots
+export const Unselected: Story = {
+  args: {
+    children: "Unselected",
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+export const Selected: Story = {
+  args: {
+    children: "Selected",
+    checked: true,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};
+
+export const ErrorState: Story = {
+  args: {
+    children: "Error",
+    error: true,
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+export const ErrorSelected: Story = {
+  args: {
+    children: "Error Selected",
+    error: true,
+    checked: true,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};
+
+export const Removable: Story = {
+  args: {
+    children: "Dismissible",
+    checked: false,
+    onDelete: () => console.log("Removal Action Triggered"),
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    children: "Leading Icon",
+    checked: false,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="12" cy="12" r="10"></circle>
+        <path d="M12 8v4"></path>
+        <path d="M12 16h.01"></path>
+      </svg>
+    ),
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+// Selecting a chip with a leading icon swaps in the checkmark rather than showing both — this
+// was already MUI-adapter's native behavior; the story exists to keep parity with mantine-adapter.
+export const WithLeadingIconSelected: Story = {
+  args: {
+    ...WithLeadingIcon.args,
+    children: "Leading Icon Selected",
+    checked: true,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};
+
+// A label long enough to exceed the chip's own max-width token — should stay a single line and
+// truncate with an ellipsis, never wrap, even with both a leading icon and a dismiss button
+// competing for space.
+export const MaxWidthEllipsis: Story = {
+  args: {
+    children:
+      "A very long chip label that exceeds the maximum width and should truncate with an ellipsis",
+    checked: false,
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="12" cy="12" r="10"></circle>
+        <path d="M12 8v4"></path>
+        <path d="M12 16h.01"></path>
+      </svg>
+    ),
+    onDelete: () => console.log("Removal Action Triggered"),
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};

package/src/components/Chip/Chip.test.tsx

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