@recursica/mui-adapter 0.26.0 → 0.27.0

package/src/components/Stepper/Stepper.tsx

@@ -14,6 +14,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Stepper.module.css";
@@ -83,6 +84,13 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const isHorizontal = orientation === "horizontal";
 
+    const mergedClassNames = mergeClassNames(
+      { root: styles.steps },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
     return (
       <div
         className={`${styles.root} ${isHorizontal ? styles.horizontal : styles.vertical} ${size === "large" ? styles.large : styles.small} ${className || ""}`}
@@ -117,9 +125,7 @@ export const Stepper = forwardRef<HTMLDivElement, StepperProps>(
               <></>
             )
           }
-          classes={{
-            root: styles.steps,
-          }}
+          classes={mergedClassNames}
         />
       </div>
     );
@@ -133,11 +139,18 @@ export type StepProps = RecursicaOverStyled<MuiStepProps>;
 export const Step = forwardRef<HTMLDivElement, StepProps>(
   function Step(props, ref) {
     const { overStyled = false, className, ...rest } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const mergedClassNames = mergeClassNames(
+      { root: styles.step },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
     return (
       <MuiStep
         ref={ref}
-        {...(filterStylingProps(rest, overStyled) as MuiStepProps)}
-        classes={{ root: styles.step }}
+        {...(sanitizedProps as MuiStepProps)}
+        classes={mergedClassNames}
         className={className || ""}
       />
     );
@@ -173,21 +186,28 @@ export const StepLabel = forwardRef<HTMLDivElement, StepLabelProps>(
       overStyled = false,
       className,
       description,
-      StepIconComponent,
+      StepIconComponent = RecursicaStepIcon,
       ...rest
     } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.stepLabelRoot,
+        label: styles.stepLabel,
+        iconContainer: styles.stepIcon,
+        labelContainer: styles.stepBody,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
     return (
       <MuiStepLabel
         ref={ref}
-        {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
+        {...(sanitizedProps as MuiStepLabelProps)}
         className={className || ""}
-        classes={{
-          root: styles.stepLabelRoot,
-          label: styles.stepLabel,
-          iconContainer: styles.stepIcon,
-          labelContainer: styles.stepBody,
-        }}
-        StepIconComponent={StepIconComponent ?? RecursicaStepIcon}
+        classes={mergedClassNames}
+        StepIconComponent={StepIconComponent}
         optional={
           description ? (
             <div className={styles.stepDescription}>{description}</div>

package/src/components/Switch/Switch.tsx

@@ -7,6 +7,8 @@ import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import {
@@ -100,14 +102,19 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       style,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above. We
+    // rely strictly on variables from Switch.module.css instead of MUI's own dimension/palette props.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+      "color", // Recursica hardcodes color="default" below; MUI's palette-driven colors are unused
+    ] as const satisfies readonly (keyof MuiSwitchProps)[];
 
-    // Actively delete dimension bindings that bypass the abstraction
-    delete restRecord["size"];
-    delete restRecord["color"];
-    delete restRecord["radius"];
-    delete restRecord["variant"];
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
     // NOTE: classes.root must stay keyed "root" (MUI's own slot name), but it targets a
     // dedicated .switchRoot CSS class, not .root — .root is this component's own outer
@@ -119,47 +126,24 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
     // replaces that slot outright (confirmed against MUI's SwitchBase/Switch source: icon and
     // checkedIcon substitute the whole default thumb, they don't add to it), so the .thumb
     // class is applied directly to our own node instead.
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.switchRoot,
-      body: styles.body,
-      track: styles.track,
-      switchBase: styles.switchBase,
-      trackLabel: styles.trackLabel,
-      labelWrapper: styles.labelWrapper,
-      label: styles.label,
-    };
-
-    // 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 note "body"/
-    // "trackLabel"/"labelWrapper"/"label" below aren't real MUI `classes` slots at all (MUI
-    // only recognizes root/switchBase/track/thumb/input/checked/disabled/colorX/sizeX/edgeX) —
-    // those four are this component's own hardcoded elements, styled directly in the JSX below,
-    // not through MUI's classes mechanism. Only root/track/switchBase actually take effect via
-    // this override path; the rest are pre-existing dead weight, unrelated to the classNames bug.
-    const classesProp = restRecord.classes;
-    if (
-      classesProp &&
-      typeof classesProp === "object" &&
-      !Array.isArray(classesProp)
-    ) {
-      const o = classesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root
-        ? `${styles.switchRoot} ${o.root}`
-        : styles.switchRoot;
-      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
-      mergedClassNames.track = o.track
-        ? `${styles.track} ${o.track}`
-        : styles.track;
-      mergedClassNames.trackLabel = o.trackLabel
-        ? `${styles.trackLabel} ${o.trackLabel}`
-        : styles.trackLabel;
-      mergedClassNames.labelWrapper = o.labelWrapper
-        ? `${styles.labelWrapper} ${o.labelWrapper}`
-        : styles.labelWrapper;
-      mergedClassNames.label = o.label
-        ? `${styles.label} ${o.label}`
-        : styles.label;
-    }
+    // NOTE: MUI's actual prop is "classes", not "classNames" (that's Mantine's naming). Also
+    // note "body"/"trackLabel"/"labelWrapper"/"label" below aren't real MUI `classes` slots at
+    // all (MUI only recognizes root/switchBase/track/thumb/input/checked/disabled/colorX/sizeX/
+    // edgeX) — those four are this component's own hardcoded elements, styled directly in the
+    // JSX below, not through MUI's classes mechanism. Only root/track/switchBase actually take
+    // effect via this merge; the rest are pre-existing dead weight, unrelated to the merge itself.
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.switchRoot,
+        body: styles.body,
+        track: styles.track,
+        switchBase: styles.switchBase,
+        trackLabel: styles.trackLabel,
+        labelWrapper: styles.labelWrapper,
+        label: styles.label,
+      },
+      restRecord.classes as Partial<Record<string, string>> | undefined,
+    );
 
     const classNameProp = restRecord.className as string | undefined;
     const finalClass = classNameProp
@@ -237,6 +221,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       <MuiSwitch
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ref={ref as any}
+        {...(sanitizedProps as unknown as MuiSwitchProps)}
         className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
         color="default"
@@ -244,7 +229,6 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
         data-disabled={isSwitchDisabled || undefined}
         icon={thumbNode}
         checkedIcon={thumbNode}
-        {...(sanitizedProps as unknown as MuiSwitchProps)}
         {...(isGrouped
           ? { checked: isChecked, onChange: handleGroupChange }
           : {})}

package/src/components/Switch/SwitchGroup.tsx

@@ -80,12 +80,12 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
       onChange,
       ...rest
     } = props;
+    // NOTE: MuiFormGroupProps has no native "size" (or other Recursica-unsupported) prop to
+    // leak through here — nothing to add to an UNSUPPORTED_PROPS list beyond what
+    // filterStylingProps already blocks.
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks from bypassing the variables
-    delete restRecord["size"];
-
     const handleChange = (
       _event: React.SyntheticEvent,
       childValue: string[],

package/src/components/Tabs/Tabs.tsx

@@ -7,6 +7,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Tabs.module.css";
@@ -32,6 +33,16 @@ export const Tabs = forwardRef<HTMLDivElement, TabsProps>(
 
     const sanitizedProps = filterStylingProps(rest, overStyled);
 
+    const mergedClassNames = mergeClassNames(
+      {
+        flexContainer: styles.list,
+        indicator: styles.indicator,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
     return (
       <MuiTabs
         ref={ref}
@@ -41,10 +52,7 @@ export const Tabs = forwardRef<HTMLDivElement, TabsProps>(
         data-variant={variant}
         data-orientation={orientation}
         data-inverted={inverted || undefined}
-        classes={{
-          flexContainer: styles.list,
-          indicator: styles.indicator,
-        }}
+        classes={mergedClassNames}
       />
     );
   },

package/src/components/TextArea/TextArea.tsx

@@ -7,6 +7,8 @@ import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 // Removed unused TextField import
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -69,13 +71,32 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
       autosize,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+      "variant", // Recursica styles the naked textarea directly; MUI's standard/filled/outlined unused
+    ] as const satisfies readonly (keyof MuiTextareaProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["variant"];
-    delete restRecord["radius"];
+    // The `slotProps` prop is NOT omitted from this component's public type, so a caller can
+    // legitimately supply it — merge it (rather than letting our own `slotProps.input` spread
+    // after theirs and clobber `disableUnderline`/`classes`/`data-autosize` wholesale).
+    const callerSlotProps = restRecord.slotProps as
+      | { input?: Record<string, unknown> }
+      | undefined;
+    const mergedInputClasses = mergeClassNames(
+      { root: styles.root, input: styles.input },
+      callerSlotProps?.input?.classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
 
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
@@ -109,6 +130,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
         activeComponent={
           /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
           <MuiTextarea
+            {...(sanitizedProps as unknown as MuiTextareaProps)}
             multiline
             variant="standard"
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -120,15 +142,16 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
             error={!!error}
             required={undefined}
             slotProps={{
+              ...callerSlotProps,
               input: {
+                ...callerSlotProps?.input,
                 disableUnderline: true,
-                classes: { root: styles.root, input: styles.input },
+                classes: mergedInputClasses,
                 ...({
                   "data-autosize": autosize ? "true" : undefined,
                 } as Record<string, unknown>),
               },
             }}
-            {...(sanitizedProps as unknown as MuiTextareaProps)}
           />
         }
       />

package/src/components/TextField/TextField.tsx

@@ -3,6 +3,8 @@ import { InputBase, type InputBaseProps } from "@mui/material";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -77,34 +79,36 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       ...rest
     } = props;
 
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
-
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["color"];
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+      "color", // Colors are token-driven; MUI's native palette isn't exposed
+    ] as const satisfies readonly (keyof InputBaseProps)[];
 
-    // Securely map core native blocks down ensuring nested CSS modules map precisely
-    const mergedClassNames: Partial<Record<string, string>> = {
-      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
-      input: styles.input,
-      section: styles.section,
-    };
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
-    const classesProp = restRecord.classes;
-    if (
-      classesProp &&
-      typeof classesProp === "object" &&
-      !Array.isArray(classesProp)
-    ) {
-      const o = classesProp as Partial<Record<string, string>>;
-      mergedClassNames.wrapper = o.root
-        ? `${styles.root} ${o.root}`
-        : styles.root;
-      mergedClassNames.input = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-    }
+    // Securely map core native blocks down ensuring nested CSS modules map precisely. The
+    // caller-facing "root"/"input" slot names (MUI's own InputBase `classes` shape) are
+    // translated to this component's internal "wrapper"/"input" naming below.
+    const callerClasses = restRecord.classes as
+      | Partial<Record<string, string>>
+      | undefined;
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+      },
+      callerClasses && {
+        wrapper: callerClasses.root,
+        input: callerClasses.input,
+      },
+    );
 
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`

package/src/components/Timeline/Timeline.tsx

@@ -4,6 +4,7 @@ import MuiTimeline, {
 } from "@mui/lab/Timeline";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Timeline.module.css";
@@ -51,6 +52,13 @@ const TimelineInner = React.forwardRef<HTMLUListElement, TimelineProps>(
   ) {
     const sanitizedProps = filterStylingProps(rest, overStyled);
 
+    const mergedClassNames = mergeClassNames(
+      { root: styles.root },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
     const items = React.Children.toArray(children);
     const decoratedItems = items.map((item, index) =>
       React.isValidElement(item)
@@ -68,7 +76,7 @@ const TimelineInner = React.forwardRef<HTMLUListElement, TimelineProps>(
           MuiTimelineProps,
           "color" | "radius" | "bulletSize" | "lineWidth"
         >)}
-        classes={{ root: styles.root }}
+        classes={mergedClassNames}
       >
         {decoratedItems}
       </MuiTimeline>

package/src/components/Timeline/TimelineItem.tsx

@@ -69,12 +69,12 @@ export const TimelineItem = React.forwardRef<HTMLLIElement, TimelineItemProps>(
     return (
       <MuiTimelineItem
         ref={ref}
-        data-variant={bulletVariant}
-        data-active={__active || undefined}
         {...(restSanitizedProps as unknown as Omit<
           MuiTimelineItemProps,
           "radius" | "color" | "lineVariant" | "title"
         >)}
+        data-variant={bulletVariant}
+        data-active={__active || undefined}
         className={
           userClassName ? `${styles.item} ${userClassName}` : styles.item
         }

package/src/components/Toast/Toast.tsx

@@ -7,6 +7,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Toast.module.css";
@@ -63,29 +64,19 @@ export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
   ) {
     const sanitizedProps = filterStylingProps(rest, overStyled);
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      message: styles.body,
-      icon: styles.icon,
-      action: styles.closeButton,
-    };
-
-    const classNamesProp = (sanitizedProps as Record<string, unknown>)
-      .classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Record<string, string>;
-      Object.keys(o).forEach((key) => {
-        if (mergedClassNames[key]) {
-          mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-        } else {
-          mergedClassNames[key] = o[key];
-        }
-      });
-    }
+    // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        message: styles.body,
+        icon: styles.icon,
+        action: styles.closeButton,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
 
     const handleClose = () => {
       if (onClose) onClose();

package/src/components/Tooltip/Tooltip.tsx

@@ -4,6 +4,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Tooltip.module.css";
@@ -48,32 +49,18 @@ const TooltipBase = function Tooltip({
   const { title, ...restProps } = rest;
   const sanitizedProps = filterStylingProps(restProps, overStyled);
 
-  // Bind CSS module classes to Mui's internal classNames API
-  const mergedClassNames: Partial<Record<string, string>> = {
-    tooltip: styles.tooltip,
-    arrow: styles.arrow,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Record<string, string>;
-    Object.keys(o).forEach((key) => {
-      if (mergedClassNames[key]) {
-        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-      } else {
-        mergedClassNames[key] = o[key];
-      }
-    });
-  }
-
-  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
-    | boolean
-    | undefined;
-  const resolvedWithArrow = withBeak ?? withArrow;
+  // Bind CSS module classes to Mui's internal classNames API. Note MUI's actual prop is
+  // "classes", not "classNames" (that's Mantine's naming) — this used to read the wrong key,
+  // silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      tooltip: styles.tooltip,
+      arrow: styles.arrow,
+    },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   return (
     <MuiTooltip
@@ -81,7 +68,7 @@ const TooltipBase = function Tooltip({
       title={label || title || ""}
       open={opened}
       placement="top" /* Recursica default; Mui defaults to "bottom" */
-      arrow={resolvedWithArrow}
+      arrow={withBeak}
       classes={mergedClassNames}
     />
   );

package/src/components/TransferList/TransferList.tsx

@@ -346,10 +346,10 @@ export const TransferList = forwardRef<HTMLDivElement, TransferListProps>(
         readOnlyNativeProps={props}
         activeComponent={
           <div
+            {...(sanitizedProps as Record<string, unknown>)}
             className={styles.root}
             data-disabled={disabled ? "true" : undefined}
             data-error={error ? "true" : undefined}
-            {...(sanitizedProps as Record<string, unknown>)}
           >
             <div className={styles.panes}>
               {renderPane(

package/src/utils/filterStylingProps.ts

@@ -58,6 +58,10 @@ export {
   type BlockedStylingKeys,
   type ForbiddenStyles,
   type WithRecursicaSpacing,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
+  mergeStyles,
 } from "@recursica/adapter-common";
 
 const LAYOUT_PROPS = new Set([