@recursica/mui-adapter 0.24.0 → 0.26.0

package/src/components/Stepper/Stepper.module.css

@@ -1,13 +1,26 @@
-/* 
+/*
   Recursica Stepper CSS module natively binding to Figma variables.
-  
-  HARDCODED CSS NOTE:
-  For horizontal layout, Mantine natively renders the text horizontally alongside the icon.
-  To achieve Recursica's layout where horizontal orientation stacks text below the icon, 
-  we force `.step` to be a column, `.stepBody` to remove margin and text-align center, 
-  and the `.separator`'s margin-top is dynamically calculated `calc((indicator-size / 2) - 1px)` 
-  to ensure it continues to align with the vertical center of the indicator rather than the 
-  whole step wrapper.
+
+  ARCHITECTURE NOTES (see IMPLEMENTATION_NOTES.md for full rationale):
+  - Horizontal orientation uses MUI Stepper's own `alternativeLabel` prop (icon on
+    top, label centered below, connector absolutely positioned circle-to-circle) —
+    this is MUI's real primitive for this exact layout, not a custom column hack.
+  - The visible circle/checkmark is rendered by our own `RecursicaStepIcon`
+    (`.stepIconCircle` / `.stepCompletedIcon`) instead of MUI's default `StepIcon`,
+    which draws its own self-colored (blue) circle+check SVG that never reads
+    our tokens.
+  - Vertical orientation's connecting line is drawn as a `.stepIcon::after` rail
+    (not the `StepConnector` element — see Stepper.tsx) so its length tracks each
+    step's actual rendered height, matching mantine's absolutely-positioned
+    separator.
+
+  HARDCODED VALUES:
+  - `.stepIconCircle` sets `box-sizing: border-box` so the indicator's border is
+    included in `--stepper-indicator-size`, keeping the connector's centering math
+    (indicator-size / 2) exact.
+  - `--stepper-connector-size` is a local bridge custom property (not a design
+    token) used only to let the vertical rail's centering `calc()` reference
+    whichever connector-size token is active for the current state.
 */
 
 .root {
@@ -24,21 +37,12 @@
   );
 }
 
-.root.horizontal .step {
-  flex-direction: column;
-  align-items: center;
-  gap: var(
-    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_indicator-label-gap
-  );
-}
-
 .root.horizontal .stepBody {
   width: var(--stepper-max-text-width);
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: flex-start;
-  margin-left: 0; /* Mantine natively applies a margin-inline-start */
   gap: var(
     --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_label-description-gap
   );
@@ -52,14 +56,41 @@
   white-space: normal;
 }
 
+.root.horizontal .stepLabel {
+  /* Replaces MUI's own hardcoded `margin-top: 16px` (applied via its
+     `.Mui-alternativeLabel` state class) with the real indicator-label-gap token. */
+  margin-top: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_indicator-label-gap
+  );
+}
+
 .root.horizontal .separator {
-  align-self: flex-start; /* Force to top regardless of container alignment */
-  margin-top: calc(var(--stepper-indicator-size) / 2 - 1px);
-  margin-left: calc(
-    -1 * (var(--stepper-max-text-width) - var(--stepper-indicator-size)) / 2
+  /* Root only positions the connector; MUI's own `alternativeLabel` variant
+     already sets `position: absolute`. Centering is exact because our custom
+     StepIconComponent renders a `--stepper-indicator-size` circle flush at the
+     top of `.stepIcon`, centered horizontally within the step. */
+  top: calc(var(--stepper-indicator-size) / 2);
+  left: -50%;
+  right: 50%;
+}
+
+.root.horizontal .separatorLine {
+  border-top: none; /* replace MUI's default border-top line with a token-driven bar */
+  height: var(
+    --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
   );
-  margin-right: calc(
-    -1 * (var(--stepper-max-text-width) - var(--stepper-indicator-size)) / 2
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
+  );
+}
+
+.root.horizontal .separator:global(.Mui-active) .separatorLine,
+.root.horizontal .separator:global(.Mui-completed) .separatorLine {
+  height: var(
+    --recursica_ui-kit_components_stepper_properties_completed-connector-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
   );
 }
 
@@ -68,20 +99,15 @@
   --stepper-step-gap: var(
     --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_step-gap
   );
-  --separator-spacing: 0px; /* Force the line to touch the circle */
   --stepper-max-text-width: var(
     --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_max-text-width
   );
 }
 
 .root.vertical .step {
-  gap: var(
-    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_indicator-label-gap
-  );
-  margin-top: 0 !important; /* Remove Mantine's gap */
-  padding-bottom: var(
-    --stepper-step-gap
-  ); /* Move gap inside the step so the separator line can stretch through it */
+  /* Moves the gap inside the step (instead of a margin between steps) so the
+     `.stepIcon::after` rail can extend through it into the next step. */
+  padding-bottom: var(--stepper-step-gap);
 }
 
 .root.vertical .step:last-of-type {
@@ -94,6 +120,54 @@
   );
 }
 
+.root.vertical .stepLabelRoot {
+  /* Lets the icon column (`.stepIcon`) stretch to match the label column's
+     actual rendered height (multi-line descriptions included), so the
+     connecting rail's length always reaches the next step's icon. */
+  align-items: stretch;
+  /* Replaces MUI's own hardcoded `padding: 8px 0` for vertical orientation —
+     without zeroing this, the rail falls 16px short of the next icon (8px
+     here + 8px on the next step's own StepLabelRoot). */
+  padding: 0;
+}
+
+.root.vertical .stepIcon {
+  height: auto;
+  /* Replaces MUI's own hardcoded `padding-right: 8px` on the icon container. */
+  padding-right: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_indicator-label-gap
+  );
+  --stepper-connector-size: var(
+    --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
+  );
+}
+
+.root.vertical .step:global(.Mui-completed) .stepIcon {
+  --stepper-connector-size: var(
+    --recursica_ui-kit_components_stepper_properties_completed-connector-size
+  );
+}
+
+.root.vertical .step:not(:last-of-type) .stepIcon::after {
+  content: "";
+  position: absolute;
+  top: var(--stepper-indicator-size);
+  bottom: calc(-1 * var(--stepper-step-gap));
+  left: calc(50% - (var(--stepper-connector-size) / 2));
+  width: var(--stepper-connector-size);
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
+  );
+}
+
+.root.vertical
+  .step:global(.Mui-completed):not(:last-of-type)
+  .stepIcon::after {
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
+  );
+}
+
 /* Sizes */
 .large {
   --stepper-icon-size: var(
@@ -180,10 +254,6 @@
 }
 
 /* Core Element Structuring using mapped variables */
-.root .step {
-  /* Default to Mantine's native flex behavior (stretch) so the vertical separator spans the full height */
-}
-
 .root .stepBody {
   max-width: var(--stepper-max-text-width);
   display: flex;
@@ -244,11 +314,27 @@
   );
 }
 
+/* `.stepIcon` (MUI's `iconContainer` slot) is a layout host only — it never
+   renders the visible circle itself, so it can stretch (vertical) without
+   distorting it. The circle is `.stepIconCircle`, rendered by our own
+   `RecursicaStepIcon` (see Stepper.tsx). */
 .root .stepIcon {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-start;
+  position: relative;
+  width: var(--stepper-indicator-size);
+  flex-shrink: 0;
+}
+
+.root .stepIconCircle {
+  box-sizing: border-box; /* HARDCODE: keep indicator-size math exact incl. border */
   width: var(--stepper-indicator-size);
   height: var(--stepper-indicator-size);
   min-width: var(--stepper-indicator-size);
   min-height: var(--stepper-indicator-size);
+  border-style: solid; /* HARDCODE: plain span has no default border-style */
   border-width: var(--stepper-border-size);
   border-radius: 50%; /* Override Figma token to ensure perfectly circular indicators */
 
@@ -264,7 +350,6 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  /* Font details are implicitly mapped by sizes, but colors map to states */
   /* Upcoming State (Pending) - Default */
   background-color: var(
     --recursica_ui-kit_components_stepper_properties_colors_upcoming-indicator-background-color
@@ -278,8 +363,7 @@
 }
 
 /* Completed State */
-.root .stepIcon.Mui-completed,
-.root .stepIcon:has(.Mui-completed) {
+.root .stepIconCircle[data-completed] {
   background-color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-indicator-background-color
   );
@@ -289,32 +373,27 @@
 }
 
 .root .stepCompletedIcon {
+  width: var(--stepper-svg-size);
+  height: var(--stepper-svg-size);
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-indicator-text
   );
 }
 
-.root .stepCompletedIcon svg {
-  width: var(--stepper-svg-size);
-  height: var(--stepper-svg-size);
-}
-
-.root .stepLabel.Mui-completed {
+.root .stepLabel:global(.Mui-completed) {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-label-color
   );
 }
 
-.root .stepDescription:has(~ .Mui-completed),
-.root .MuiStepLabel-root.Mui-completed .stepDescription {
+.root .stepBody:has(.stepLabel:global(.Mui-completed)) .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_completed-description-color
   );
 }
 
 /* Current State (Progressing) */
-.root .stepIcon.Mui-active,
-.root .stepIcon:has(.Mui-active) {
+.root .stepIconCircle[data-active] {
   background-color: var(
     --recursica_ui-kit_components_stepper_properties_colors_current-indicator-background-color
   );
@@ -326,84 +405,38 @@
   );
 }
 
-.root .stepLabel.Mui-active {
+.root .stepLabel:global(.Mui-active) {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_current-label-color
   );
 }
 
-.root .stepDescription:has(~ .Mui-active),
-.root .MuiStepLabel-root.Mui-active .stepDescription {
+.root .stepBody:has(.stepLabel:global(.Mui-active)) .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_current-description-color
   );
 }
 
 /* Upcoming State (Pending Labels) */
-.root .stepLabel:not(.Mui-active):not(.Mui-completed) {
+.root .stepLabel:not(:global(.Mui-active)):not(:global(.Mui-completed)) {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_upcoming-label-color
   );
 }
 
-.root .MuiStepLabel-root:not(.Mui-active):not(.Mui-completed) .stepDescription {
+.root
+  .stepBody:not(:has(.stepLabel:global(.Mui-active))):not(
+    :has(.stepLabel:global(.Mui-completed))
+  )
+  .stepDescription {
   color: var(
     --recursica_ui-kit_components_stepper_properties_colors_upcoming-description-color
   );
 }
 
-/* Horizontal Separator */
-.root .separator {
-  margin: 0 var(--stepper-step-gap); /* Apply the gap logic to the separator natively */
-  background-color: var(
-    --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
-  );
-  height: var(
-    --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
-  );
-  border: none;
-  min-width: 20px;
-  flex: 1;
-}
-
-.root .separator.Mui-active,
-.root .separator.Mui-completed {
-  background-color: var(
-    --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
-  );
-  height: var(
-    --recursica_ui-kit_components_stepper_properties_completed-connector-size
-  );
-}
-
-/* Vertical Separator */
-.root .verticalSeparator {
-  border-inline-start: var(
-      --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
-    )
-    solid
-    var(
-      --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
-    );
-  top: var(
-    --stepper-icon-size
-  ); /* Overrides Mantine's gap math to force the line to touch the icon */
-}
-
-.root .verticalSeparator.Mui-active,
-.root .verticalSeparator.Mui-completed {
-  border-inline-start: var(
-      --recursica_ui-kit_components_stepper_properties_completed-connector-size
-    )
-    solid
-    var(
-      --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
-    );
-}
-
-/* Hide Content 
-   Recursica Steppers are purely navigational/structural. Content should be managed 
-   by the parent layout outside of the Stepper DOM. 
+/* Hide Content
+   Recursica Steppers are purely navigational/structural. Content should be managed
+   by the parent layout outside of the Stepper DOM.
 */
 .root .content {
   display: none;

package/src/components/Stepper/Stepper.tsx

@@ -10,6 +10,7 @@ import {
   type StepLabelProps as MuiStepLabelProps,
   type StepButtonProps as MuiStepButtonProps,
   type StepConnectorProps as MuiStepConnectorProps,
+  type StepIconProps as MuiStepIconProps,
 } from "@mui/material";
 import {
   filterStylingProps,
@@ -19,6 +20,49 @@ import styles from "./Stepper.module.css";
 
 import { type RecursicaStepperProps } from "@recursica/adapter-common";
 
+// Same inline check glyph used by Checkbox.tsx (fill="currentColor" so the CSS
+// module drives color via `.stepCompletedIcon`).
+function CheckIcon(props: React.ComponentProps<"svg">) {
+  return (
+    <svg
+      viewBox="0 0 10 7"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M4 4.586L1.707 2.293A1 1 0 1 0 .293 3.707l3 3a.997.997 0 0 0 1.414 0l5-5A1 1 0 1 0 8.293.293L4 4.586z"
+        fill="currentColor"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+}
+
+// MUI's default StepIcon draws its own self-contained circle+check SVG
+// (Material's `check_circle` glyph, colored via `theme.palette.primary.main`)
+// whenever `icon` is the auto-injected step number — it never defers to our
+// `.stepIcon` background/border tokens. We render the indicator ourselves so
+// the recursica-token circle (`.stepIconCircle`) is the only circle, and the
+// completed check mark is our own token-colored glyph.
+function RecursicaStepIcon(props: MuiStepIconProps) {
+  const { icon, active, completed, error } = props;
+  if (typeof icon !== "number" && typeof icon !== "string") {
+    return <>{icon}</>;
+  }
+  return (
+    <span
+      className={styles.stepIconCircle}
+      data-active={active || undefined}
+      data-completed={completed || undefined}
+      data-error={error || undefined}
+    >
+      {completed ? <CheckIcon className={styles.stepCompletedIcon} /> : icon}
+    </span>
+  );
+}
+
 export interface RecursicaStepperPropsExtended
   extends Omit<Partial<MuiStepperProps>, "size">,
     RecursicaStepperProps {}
@@ -37,10 +81,11 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
     } = props;
 
     const sanitizedProps = filterStylingProps(rest, overStyled);
+    const isHorizontal = orientation === "horizontal";
 
     return (
       <div
-        className={`${styles.root} ${orientation === "horizontal" ? styles.horizontal : styles.vertical} ${size === "large" ? styles.large : styles.small} ${className || ""}`}
+        className={`${styles.root} ${isHorizontal ? styles.horizontal : styles.vertical} ${size === "large" ? styles.large : styles.small} ${className || ""}`}
         style={style as React.CSSProperties}
         data-size={size}
         data-orientation={orientation}
@@ -50,15 +95,27 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
           ref={ref as any}
           {...(sanitizedProps as MuiStepperProps)}
           orientation={orientation}
+          // `alternativeLabel` is MUI's real primitive for "label centered under
+          // the icon" (see its own prop doc) — required for the icon/label
+          // layout and for the connector's centered absolute positioning.
+          alternativeLabel={isHorizontal}
           connector={
-            <MuiStepConnector
-              classes={{
-                root:
-                  orientation === "horizontal"
-                    ? styles.separator
-                    : styles.verticalSeparator,
-              }}
-            />
+            isHorizontal ? (
+              <MuiStepConnector
+                classes={{
+                  root: styles.separator,
+                  line: styles.separatorLine,
+                }}
+              />
+            ) : (
+              // Vertical connecting line is drawn as a `.stepIcon::after` rail
+              // (see module CSS) so its length tracks each step's actual
+              // rendered height (multi-line descriptions included) the same
+              // way mantine's absolutely-positioned separator does — MUI's
+              // own vertical `StepConnector` is a fixed-height sibling that
+              // can't do that without `StepContent`, which recursica hides.
+              <></>
+            )
           }
           classes={{
             root: styles.steps,
@@ -112,16 +169,25 @@ export type StepLabelProps = RecursicaOverStyled<
 
 export const StepLabel = forwardRef<HTMLDivElement, StepLabelProps>(
   function StepLabel(props, ref) {
-    const { overStyled = false, className, description, ...rest } = props;
+    const {
+      overStyled = false,
+      className,
+      description,
+      StepIconComponent,
+      ...rest
+    } = props;
     return (
       <MuiStepLabel
         ref={ref}
         {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
         className={className || ""}
         classes={{
+          root: styles.stepLabelRoot,
           label: styles.stepLabel,
           iconContainer: styles.stepIcon,
+          labelContainer: styles.stepBody,
         }}
+        StepIconComponent={StepIconComponent ?? RecursicaStepIcon}
         optional={
           description ? (
             <div className={styles.stepDescription}>{description}</div>

package/src/components/Stepper/USAGE.md

@@ -39,3 +39,7 @@ 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.
+> - **Default step icon**: `StepLabel` renders its own token-driven circle (with a check mark
+>   once a step is completed) by default. Pass your own `StepIconComponent` prop to `StepLabel`
+>   to override it for a given step, or pass a custom `icon` node (e.g. `<StepLabel icon={<MyIcon />}>`)
+>   to render arbitrary content in place of the circle entirely.

package/src/components/Tabs/IMPLEMENTATION_NOTES.md

@@ -12,3 +12,15 @@
 - **MUI's `TabPanel` defaults to `padding: theme.spacing(3)` (24px)**; Mantine's `Tabs.Panel` has none — the gap is already carried by `.list`'s own margin. Reset to `padding: 0`.
 - **The indicator (`classes.indicator`) is absolutely positioned against `.MuiTabs-root`, not `.list`:** `.list`'s own `margin-bottom` (the tabs-content-gap) collapses into that root's auto height instead of stopping at `.list`'s border edge, so the indicator's default `bottom: 0` lands one content-gap below the baseline. Offset it by the same content-gap token to bring it flush again.
 - **All of the above needed `!important`** to reliably beat MUI's own emotion-injected styles for the same property — plain specificity/cascade order wasn't sufficient in this build.
+
+## Follow-up parity fixes (2026-08-18)
+
+- **`MuiTouchRipple-root` gets caught by `.root .tab > *`:** that rule exists to lift real content (icon/label) above the hover overlay's `z-index`, but it also matches the ripple span MUI injects into the tab on first click. Forcing that span from its native `position: absolute` to `position: relative` turns it into a real flex item, inserting one extra `--tabs-element-gap` into the tab's flex row and permanently growing the tab's width (it never gets removed from the DOM after the ripple animation ends) — this was the cause of a layout shift where selecting a tab pushed later siblings sideways. Excluded via `:not(:global(.MuiTouchRipple-root))`.
+- **Outline's selected-tab border can't be "erased" with a same-element pseudo-element:** the open edge (0 border-width on the side touching the list's baseline) leaves the list's own `border-bottom`/`border-right` showing through, because that border is a real CSS border appended outside the tab's box, not an inset overlay sharing the tab's own bottom edge (unlike Mantine, where the list-baseline wrapper and the tab share the same reference edge, so the tab's own border naturally paints over it). A `::after` patch on the tab itself can't fix this either: MUI gives `Tab` (`ButtonBase`) `overflow: hidden` natively (to contain the ripple), which clips away anything extending past the tab's own box before it ever reaches the list's border. Fixed by repurposing the indicator element (`classes.indicator`) instead — it already lives in the scroller (a sibling of `.list`, not clipped) and MUI already keeps its position/size in sync with whichever tab is selected, so it just needed restyling into a small opaque patch instead of being `display: none`.
+- **That patch needs a real opaque color, not the tab's own token:** outline's active background-color token is `transparent` by design (it's meant to let the ambient Layer surface show through), so it can't double as the eraser — painting "transparent over transparent" does nothing. Used `--recursica_brand_layer_0_properties_surface` (the default/outermost Layer surface) instead, since that's what a Tabs instance sits on absent an explicit wrapping `<Layer>`. This is an inherent approximation, same category as Mantine's own equivalent trick (which hardcodes `--mantine-color-body`): if a consumer nests outline Tabs inside a `<Layer layer={1|2|3}>`, the patch will mismatch that surface's color. No generic "current ambient layer" token exists in the schema to fix this properly — flagged for whoever owns the token schema.
+- **Vertical `.list` doesn't stretch to the root's full height:** Mantine's vertical `.list` stretches via flex `align-items`, so its `border-right` divider runs the whole rail. MUI's scroller (the `.list`'s parent) is a plain block for vertical, not a flex container, so `.list` sizes to just its stacked tab content and the divider stopped at the last tab. Fixed with an explicit `height: 100%` on `.list` for vertical orientation.
+- **Vertical indicator needs the same content-gap offset as horizontal, rotated 90°:** the list's `margin-right` (vertical's tabs-content-gap) inflates the root's auto width past the list's own border-right edge, same mechanism as the existing horizontal `bottom` offset trick — without a matching `right` offset, the indicator renders content-gap pixels to the right of the divider instead of on it.
+
+## Ripple removal (2026-08-19)
+
+- **MUI `Tab` shows a click ripple; Mantine's has none.** `Tab` extends `ButtonBase`, which renders a `TouchRipple` on click by default. Fixed by passing `disableRipple` on `MuiTab` in `Tab` (the same official escape hatch already used by `Button`/`Switch`/`Radio`/`Checkbox`). With `disableRipple`, the `MuiTouchRipple-root` span is never rendered at all, which also makes the `.root .tab > *:not(:global(.MuiTouchRipple-root))` layout-shift workaround above moot going forward (left in place defensively).