@recursica/mui-adapter 0.21.1 → 0.22.0

package/src/components/Radio/Radio.tsx

@@ -17,6 +17,7 @@ import {
   FormControlLayout,
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 
 import styles from "./Radio.module.css";
 
@@ -78,38 +79,36 @@ export const Radio = forwardRef<HTMLInputElement, RadioProps>(
     delete restRecord["size"];
     delete restRecord["color"];
 
+    // NOTE: MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // was reading the wrong key and silently doing nothing. Fixed. Also "body"/"inner"/"radio"/
+    // "icon"/"labelWrapper"/"label" below were never real MUI `classes` slots (MUI's Radio only
+    // recognizes root/checked/disabled/colorPrimary/colorSecondary/sizeSmall, plus "input" from
+    // the underlying SwitchBase) — those slot names are Mantine's own Radio classNames API,
+    // copy-pasted over verbatim. Since none of them existed as real slots, MUI silently dropped
+    // them, so the circle (all its background/border CSS lived under `.radio`) never rendered —
+    // only the label showed. Fixed by keeping only the real slots here and drawing the circle as
+    // our own combined icon/checkedIcon node instead (see radioNode below), same pattern already
+    // used by Checkbox.
     const mergedClassNames: Partial<Record<string, string>> = {
       root: styles.root,
-      body: styles.body,
-      inner: styles.inner,
-      radio: styles.radio,
-      icon: styles.icon,
-      labelWrapper: styles.labelWrapper,
-      label: styles.label,
+      checked: styles.checked,
+      disabled: styles.disabled,
     };
 
-    const classNamesProp = restRecord.classNames;
+    const classesProp = restRecord.classes;
     if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
+      classesProp &&
+      typeof classesProp === "object" &&
+      !Array.isArray(classesProp)
     ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
+      const o = classesProp as Partial<Record<string, string>>;
       mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
-      mergedClassNames.inner = o.inner
-        ? `${styles.inner} ${o.inner}`
-        : styles.inner;
-      mergedClassNames.radio = o.radio
-        ? `${styles.radio} ${o.radio}`
-        : styles.radio;
-      mergedClassNames.icon = o.icon ? `${styles.icon} ${o.icon}` : styles.icon;
-      mergedClassNames.labelWrapper = o.labelWrapper
-        ? `${styles.labelWrapper} ${o.labelWrapper}`
-        : styles.labelWrapper;
-      mergedClassNames.label = o.label
-        ? `${styles.label} ${o.label}`
-        : styles.label;
+      mergedClassNames.checked = o.checked
+        ? `${styles.checked} ${o.checked}`
+        : styles.checked;
+      mergedClassNames.disabled = o.disabled
+        ? `${styles.disabled} ${o.disabled}`
+        : styles.disabled;
     }
 
     const classNameProp = restRecord.className as string | undefined;
@@ -144,17 +143,28 @@ export const Radio = forwardRef<HTMLInputElement, RadioProps>(
       return <>{roNode}</>;
     }
 
-    // We omit Mui's sizing/coloring so we rely strictly on variables from Radio.module.css
+    // MUI's icon/checkedIcon fully replace the visual (they're the only child SwitchBase
+    // renders alongside the invisible native input) — so the ring + dot both have to live in
+    // one combined node per state, same pattern as Checkbox's icon/checkedIcon divs.
+    // sanitizedProps spreads FIRST: these render-critical props (icon/checkedIcon/className/
+    // classes/disabled/disableRipple/sx) must win over anything of the same name coming through
+    // from the caller, or they'd silently clobber the exact rendering this component depends on.
     const radioNode = (
       <MuiRadio
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ref={ref as any}
-        icon={<RadioIcon />}
-        checkedIcon={<RadioIcon className={styles.checked} />}
-        className={finalClass}
+        {...(sanitizedProps as unknown as MuiRadioProps)}
+        icon={<div className={styles.radio} />}
+        checkedIcon={
+          <div className={`${styles.radio} ${styles.radioChecked}`}>
+            <RadioIcon className={styles.icon} />
+          </div>
+        }
+        className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
         disabled={readOnly || disabled}
-        {...(sanitizedProps as unknown as MuiRadioProps)}
+        disableRipple
+        sx={label ? { padding: 0 } : undefined}
       />
     );
 
@@ -170,27 +180,31 @@ export const Radio = forwardRef<HTMLInputElement, RadioProps>(
             >
               {label as React.ReactNode}
             </label>
-            {description && (
-              <div
-                className={styles.description}
-                data-disabled={readOnly || disabled ? true : undefined}
-              >
-                {description}
-              </div>
-            )}
-            {error && (
-              <div
-                className={styles.error}
-                data-disabled={readOnly || disabled ? 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>
       </div>
     ) : (
-      radioNode
+      <div className={finalClass} style={style as React.CSSProperties}>
+        {radioNode}
+      </div>
     );
 
     if (formLayout) {

package/src/components/Radio/RadioGroup.tsx

@@ -70,6 +70,7 @@ export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
       emptyValueComponent,
       value,
       defaultValue,
+      onChange,
       ...rest
     } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -111,6 +112,10 @@ export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
             {...(sanitizedProps as unknown as MuiRadioGroupProps)}
             value={value}
             defaultValue={defaultValue}
+            // MUI natively calls onChange(event, value); the Recursica contract is
+            // single-argument (value only), matching Mantine's native RadioGroup
+            // onChange (the cross-adapter source of truth) — normalize here.
+            onChange={onChange ? (_event, val) => onChange(val) : undefined}
             className={styles.groupRoot}
             data-layout={formLayout}
           >

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -98,13 +98,6 @@
   display: flex;
   align-items: center;
   justify-content: center;
-}
-
-/* Mantine natively wraps label contents in an innerLabel span */
-.root .label :global(.mantine-SegmentedControl-innerLabel) {
-  display: flex;
-  align-items: center;
-  justify-content: center;
   gap: var(
     --recursica_ui-kit_components_segmented-control-item_properties_item_icon-text-gap
   );

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -38,7 +38,6 @@ function useSegmentedControlClassNames(restRecord: Record<string, unknown>): {
     root: styles.root,
     control: styles.control,
     label: styles.label,
-    indicator: styles.indicator,
   };
 
   const classNamesProp = restRecord.classNames;
@@ -55,9 +54,6 @@ function useSegmentedControlClassNames(restRecord: Record<string, unknown>): {
     mergedClassNames.label = o.label
       ? `${styles.label} ${o.label}`
       : styles.label;
-    mergedClassNames.indicator = o.indicator
-      ? `${styles.indicator} ${o.indicator}`
-      : styles.indicator;
   }
 
   const classNameProp = restRecord.className as string | undefined;
@@ -101,6 +97,10 @@ const _SegmentedControl = forwardRef<HTMLDivElement, SegmentedControlProps>(
     return (
       <MuiSegmentedControl
         ref={ref}
+        {...(sanitizedProps as Omit<
+          MuiSegmentedControlProps,
+          "variant" | "size" | "value" | "onChange"
+        >)}
         className={stylingParams.className}
         classes={stylingParams.classNames}
         orientation={orientation}
@@ -113,10 +113,6 @@ const _SegmentedControl = forwardRef<HTMLDivElement, SegmentedControlProps>(
             typeof MuiSegmentedControl
           >["onChange"]
         }
-        {...(sanitizedProps as Omit<
-          MuiSegmentedControlProps,
-          "variant" | "size" | "value" | "onChange"
-        >)}
       >
         {data.map((item) => {
           const itemValue = typeof item === "string" ? item : item.value;

package/src/components/Slider/Slider.tsx

@@ -235,6 +235,7 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
 
             <div className={styles.sliderTrackWrapper}>
               <MuiSlider
+                {...(sanitizedProps as unknown as MuiSliderProps)}
                 classes={mergedClassNames}
                 disabled={disabled}
                 value={resolvedValue}
@@ -257,7 +258,6 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
                       ) => React.ReactNode)
                     : undefined
                 }
-                {...(sanitizedProps as unknown as MuiSliderProps)}
               />
             </div>
 

package/src/components/Stack/Stack.tsx

@@ -29,10 +29,10 @@ export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
   return (
     <MUIStack
       ref={ref}
+      {...safeProps}
       spacing={resolvedGap}
       alignItems={align}
       justifyContent={justify}
-      {...safeProps}
     >
       {children}
     </MUIStack>

package/src/components/Stepper/Stepper.tsx

@@ -48,6 +48,7 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
         <MuiStepper
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           ref={ref as any}
+          {...(sanitizedProps as MuiStepperProps)}
           orientation={orientation}
           connector={
             <MuiStepConnector
@@ -62,7 +63,6 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
           classes={{
             root: styles.steps,
           }}
-          {...(sanitizedProps as MuiStepperProps)}
         />
       </div>
     );
@@ -79,9 +79,9 @@ export const Step = forwardRef<HTMLDivElement, StepProps>(
     return (
       <MuiStep
         ref={ref}
+        {...(filterStylingProps(rest, overStyled) as MuiStepProps)}
         classes={{ root: styles.step }}
         className={className || ""}
-        {...(filterStylingProps(rest, overStyled) as MuiStepProps)}
       />
     );
   },
@@ -116,6 +116,7 @@ export const StepLabel = forwardRef<HTMLDivElement, StepLabelProps>(
     return (
       <MuiStepLabel
         ref={ref}
+        {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
         className={className || ""}
         classes={{
           label: styles.stepLabel,
@@ -128,7 +129,6 @@ export const StepLabel = forwardRef<HTMLDivElement, StepLabelProps>(
             rest.optional
           )
         }
-        {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
       />
     );
   },

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,123 @@
+# Switch Implementation Notes
+
+Decisions and gotchas specific to wrapping `@mui/material`'s `Switch` for the UI Kit's Switch.
+
+## Label/description/error
+
+MUI's `Switch` has no built-in label/description/error rendering — built by hand here.
+The label is a plain `<label>`; description/error render through the shared
+`AssistiveElement` component (`assistiveWithIcon={false}`) instead of local styled divs,
+so they inherit real design tokens rather than hardcoded Mantine defaults.
+
+## `Switch.Group` compound export
+
+`SwitchGroup.tsx` existed but wasn't attached as `Switch.Group`. Fixed.
+
+## `SwitchGroup` didn't control its children — now fixed
+
+MUI's `FormGroup` has no controlled-value concept — no equivalent to Mantine's real
+`Switch.Group`, which threads a `string[]` of checked values and `checked`/`onChange` to each
+child via context. This adapter's `SwitchGroup` used to destructure and discard
+`value`/`defaultValue`/`onChange` entirely — purely cosmetic.
+
+Fixed the same way this adapter's own `Checkbox`/`CheckboxGroup` already solved the identical
+problem (a closer, in-repo precedent than `Accordion`, which the notes previously pointed to
+without checking Checkbox first): a `SwitchGroupContext` provider on `SwitchGroup` carrying
+`value`/`onChange`/`name`/`readOnly`, consumed by `Switch` to compute `isChecked` from array
+membership and to translate each toggle into an add/remove against that array before calling
+the group's `onChange`. Standalone (ungrouped) `Switch` usage is untouched — the group-derived
+`checked`/`onChange` are only spread onto `<MuiSwitch>` when a `SwitchGroupContext` is present.
+Verified live: initial `value`/`defaultValue` now renders correctly, clicking a sibling
+switch toggles only its own entry in the array, and `readOnly` on the group disables every
+child — all confirmed against the existing `SwitchGroup.stories.tsx` scenarios via Playwright.
+
+## Thumb icon (check/x glyph)
+
+MUI's `icon`/`checkedIcon` props are the _same mechanism_ MUI uses internally to render its
+own default circular thumb (`icon: <the circle>, checkedIcon: <the circle>`, then
+spread-overwritten by whatever public `icon`/`checkedIcon` the caller passes) — confirmed
+against MUI's own `Switch.js`/`SwitchBase.js` source. Passing a raw glyph into them replaces
+the whole thumb circle, it doesn't add an icon inside it.
+
+Fixed the same way `Checkbox` in this adapter already solved the identical problem: build our
+own combined node — a `.thumb`-styled `<span>` wrapping `.thumbIconWrapper` with both
+`CheckIcon`/`CloseIcon` (inline SVGs, same paths as Mantine's, copied rather than imported
+since mui-adapter doesn't depend on `@mantine/core`) — and pass _that same node reference_ as
+both `icon` and `checkedIcon` (mirroring MUI's own `icon={icon} checkedIcon={icon}` pattern).
+Same reference means it never unmounts/remounts on toggle, which is what lets the two glyphs
+crossfade via CSS opacity instead of a hard swap — matching Mantine's `thumbIcon` behavior.
+Verified against a live Storybook via adapter-tester (geometry + SVG count now match Mantine
+1:1 across Default/Static Variations stories).
+
+## Track/thumb geometry, checked-state selectors, focus ring
+
+Original CSS was a copy of mantine-adapter's file, but MUI's DOM is structurally different
+(`track`/`switchBase` are siblings, not nested; MUI hardcodes its own root box, hit-area
+padding, and thumb travel distance for its own 20px default thumb). Fixed by driving
+`.switchRoot`/`.switchBase`/`.thumb` sizing entirely from our tokens, replacing
+`input:checked + .track` sibling selectors (never matched in MUI's DOM) with `:has()`-scoped
+selectors, adding an explicit focus ring from `--recursica_brand_states_focus_*` tokens, and
+hardcoding `color="default"` so MUI's own primary-blue hover/focus circle never activates.
+Verified via live measurement (adapter-tester): track/thumb box dimensions now match Mantine
+exactly (64×28 track, 20×20 thumb).
+
+Two gotchas worth flagging for future MUI adapter work:
+
+1. `classes.root` targets MUI's own switch span, but this component's outer wrapper `<div>`
+   (switch+label row) also uses `.root` — sizing one squeezes the other. Split into
+   `.switchRoot` (MUI switch only) vs `.root` (outer wrapper, cursor only).
+2. CSS Modules hashes literal MUI state classes (`Mui-checked`, `Mui-focusVisible`) unless
+   wrapped in `:global()` — same pattern already used in `Accordion`/`Button`.
+
+## Disabled-state opacity didn't reach the thumb
+
+**Found 2026-08-14, reported by Matt:** the Read Only story's thumb stayed full-color/opacity
+while Mantine's dimmed along with the track. Same root cause as the geometry work above:
+Mantine nests `.thumb` inside `.track`, so an `opacity` on `.track` visually dims the thumb for
+free; MUI has them as siblings, so the disabled-opacity selectors (which only targeted
+`.track`) never touched the thumb at all. Fixed by adding `.thumb` to both selectors alongside
+`.track`. Verified live: thumb now dims identically to Mantine in both the plain-disabled and
+disabled-checked cases.
+
+## Track opacity — MUI's own always-on defaults, unrelated to our tokens
+
+MUI's `SwitchTrack` styled component sets `opacity: 0.38` unconditionally (its own faded-pill
+baseline), and separately `.Mui-checked + .track { opacity: 0.5 }` when checked — neither has
+an equivalent in our token schema, and neither was being cancelled. Result: every enabled track
+was dimmed by MUI's own opacity, most visibly on the checked state (deep red washed out to
+pink). Fixed with an explicit `opacity: 1` in both the base `.track` rule and the
+`.root:has(input:checked) .track` rule (needed in both — MUI's checked-specific selector is
+more specific than its own base rule, so overriding only the base wasn't enough). Disabled-state
+opacity is unaffected; those selectors are already more specific than either of these.
+
+## Focus ring was on the thumb's hit-area circle, not the track
+
+`.switchBase:global(.Mui-focusVisible)` is MUI's actual focusable element, but it's sized to
+the thumb's 20×20 hit area, not the 64×28 track — so the ring drew a small circle instead of
+outlining the switch. Moved to `.switchBase:global(.Mui-focusVisible) ~ .track` (siblings under
+`.switchRoot`, switchBase first) so the ring renders on the track itself. Mantine-adapter had
+the mirror-image bug: no override at all, so Mantine's own default outline (blue) showed on the
+hidden `<input>` — fixed there with `.root input:focus-visible { outline: none }` +
+`.root input:focus-visible + .track { ... }`, drawing the same Recursica-token ring in the same
+place.
+
+## `classNames` prop-name bug — external override was silently inert
+
+The external override merge read `restRecord.classNames`, but MUI's actual prop is `classes`
+(that's Mantine's naming, copied over by mistake) — fixed. Note only `root`/`track`/
+`switchBase` are real MUI `classes` slots; `body`/`trackLabel`/`labelWrapper`/`label` are this
+component's own hardcoded elements (styled directly in JSX, not via MUI's `classes` prop) and
+remain unreachable through this override path — a separate, pre-existing gap, not something the
+prop-name fix could address.
+
+## `SwitchGroup` side-by-side layout always rendered as if stacked
+
+**Found 2026-08-14, reported by Matt:** the `SideBySideLayout` story showed the group label
+above the switches instead of beside them. Root cause: `SwitchGroup` passed the switch-item's
+own inline label max-width token (200px) as the group's `controlMaxWidth` — but the mandatory
+side-by-side label column is a fixed 224px, wider than that cap, so the label always overflowed
+onto its own line regardless of layout mode. Reproduced identically in Mantine (same code
+pattern, not a MUI-only bug). Fixed by not capping the group's control width at all — each
+switch's own label already wraps at 200px via `.labelWrapper`, so no group-level cap is needed.
+Verified live in both adapters: side-by-side now shows the label column at left with the
+switches beside it; stacked layout unaffected.