@recursica/mui-adapter 0.21.0 → 0.22.0

package/src/components/Switch/Switch.module.css

@@ -1,13 +1,46 @@
-/* HARDCODED VALUES 
+/* HARDCODED VALUES
  *
  * 1. track border: none; (we do not use border for the switch track)
  * 2. thumb border: none; (we do not use border for the thumb)
- * 3. outline: none; (focus rings handled internally by mantine)
+ * 3. .switchBase background-color: transparent; (cancels MUI's built-in primary-color
+ *    hover/focus circle so only our tokens and our own explicit focus ring show — see
+ *    SWITCH_IMPLEMENTATION_NOTES.md #5)
+ * 4. .track opacity: 1; (cancels MUI's own always-on track opacity — 0.38 unchecked, 0.5
+ *    checked, both MUI defaults with no equivalent in our tokens; our disabled-state opacity
+ *    rules below are the only intended dimming)
  */
 
 .root {
   /* Provide a stable cursor when not disabled */
   cursor: pointer;
+}
+
+.root:has(input:disabled) {
+  cursor: not-allowed;
+}
+
+/* Sizes MUI's actual switch root span (mapped via classes.root — MUI requires that exact key,
+   but the class name it points to is ours). Kept separate from .root above: when a label is
+   present, .root is applied to *this component's own outer wrapper div* (switch + label side
+   by side), not to the switch itself — giving both the same box-model rules would squeeze that
+   wrapper (and the label inside it) down to the track's own width. See
+   SWITCH_IMPLEMENTATION_NOTES.md #5. */
+.switchRoot {
+  /* Cancel MUI's own hardcoded root box (width: 58px, height: 38px, padding: 12px,
+     overflow: hidden for the medium size) — without this the track/thumb tokens below get
+     clipped/shrunk to MUI's default geometry instead of driving the real size. */
+  width: var(--recursica_ui-kit_components_switch_properties_track-width);
+  height: calc(
+    var(--recursica_ui-kit_components_switch_properties_thumb-height) +
+      (
+        var(
+            --recursica_ui-kit_components_switch_properties_track-inner-padding
+          ) *
+          2
+      )
+  );
+  padding: 0;
+  overflow: visible;
 
   --switch-track-padding: var(
     --recursica_ui-kit_components_switch_properties_track-inner-padding
@@ -23,17 +56,19 @@
   );
 }
 
-.root:has(input:disabled) {
-  cursor: not-allowed;
-}
-
 /* Track/thumb dim per selection state; label dims via its own (single, state-agnostic) token */
-.root:has(input:checked:disabled) .track {
+/* In mantine-adapter, .thumb nests inside .track, so dimming .track's opacity visually dims
+   the thumb too "for free". MUI's DOM has .track and .thumb as siblings (documented
+   structural difference, see SWITCH_IMPLEMENTATION_NOTES.md), so the same selector only dimmed
+   the track — the thumb stayed at full color/opacity. Each selector targets both explicitly. */
+.root:has(input:checked:disabled) .track,
+.root:has(input:checked:disabled) .thumb {
   opacity: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_variants_states_disabled_properties_opacity
   );
 }
-.root:has(input:disabled):not(:has(input:checked)) .track {
+.root:has(input:disabled):not(:has(input:checked)) .track,
+.root:has(input:disabled):not(:has(input:checked)) .thumb {
   opacity: var(
     --recursica_ui-kit_components_switch_variants_selection-states_unselected_variants_states_disabled_properties_opacity
   );
@@ -51,7 +86,7 @@
     --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_track-color
   );
 }
-.root input:checked + .track:hover {
+.root:has(input:checked) .track:hover {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
   );
@@ -69,28 +104,71 @@
   box-shadow: var(
     --recursica_ui-kit_components_switch_properties_track-elevation
   );
-  padding: var(--switch-track-padding);
   border: none; /* HARDCODE */
-
-  /* Mantine uses variables internally for these, but we explicitly override the CSS to ensure our dimensions */
-  --switch-width: var(--switch-track-width);
-  --switch-height: calc(
-    var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
-  );
-  --switch-thumb-size: var(--switch-thumb-width);
-
-  display: flex;
-  align-items: center;
+  opacity: 1; /* HARDCODE */
   box-sizing: border-box;
   transition: background-color 150ms ease;
   cursor: inherit;
 }
 
-.root input:checked + .track {
+.root:has(input:checked) .track {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
   );
   border-color: transparent;
+  /* HARDCODE #4: MUI's own checked-state selector (`.Mui-checked + .track { opacity: 0.5 }`)
+     is more specific than the base .track rule above, so it still wins there — needs its own
+     override here too. */
+  opacity: 1;
+}
+
+/* Positions/sizes the thumb's clickable hit area (MUI's internal SwitchBase). MUI's own
+   defaults here (padding: 9px; top/left: 0) are calibrated for its own hardcoded 20px thumb
+   and 58x38 root — meaningless against our tokens, so every dimension is replaced. The thumb
+   itself (the visible circle) renders as this element's only child, sized by .thumb below;
+   with padding: 0 and matching width/height, .switchBase and .thumb become the same box, so
+   the thumb sits flush inside the track's own inner padding. See
+   SWITCH_IMPLEMENTATION_NOTES.md #5. */
+.switchBase {
+  top: var(--switch-track-padding);
+  left: var(--switch-track-padding);
+  width: var(--switch-thumb-width);
+  height: var(--switch-thumb-height);
+  padding: 0;
+  box-sizing: border-box;
+}
+
+.switchBase:hover,
+.switchBase:global(.Mui-focusVisible) {
+  background-color: transparent; /* HARDCODE */
+}
+
+/* Focus ring reads on the whole visible track (the pill), not the thumb's small 20x20 hit-area
+   circle .switchBase actually is — .switchBase and .track are siblings under .switchRoot (in
+   that DOM order), so the ring is drawn on .track via the general sibling combinator when the
+   hit area is focus-visible. */
+.switchBase:global(.Mui-focusVisible) ~ .track {
+  outline: var(--recursica_brand_states_focus_border-size) solid
+    var(--recursica_brand_states_focus_color);
+  outline-offset: var(--recursica_brand_states_focus_margin);
+  box-shadow: 0 0 var(--recursica_brand_states_focus_blur)
+    var(--recursica_brand_states_focus_color);
+}
+
+/* Moves the thumb from resting-left to resting-right. MUI hardcodes this same transform to
+   translateX(20px) for its own default thumb; ours is calculated from our tokens instead —
+   the exact distance between the thumb's checked and unchecked resting positions inside the
+   track's inner padding. .Mui-checked is MUI's own global state class (not a CSS Modules
+   local class), so it must be wrapped in :global() — same as Accordion's .Mui-expanded and
+   Button's .Mui-disabled — or the build hashes/scopes it into a name that never matches the
+   real DOM. */
+.switchBase:global(.Mui-checked) {
+  transform: translateX(
+    calc(
+      var(--switch-track-width) - var(--switch-thumb-width) -
+        (var(--switch-track-padding) * 2)
+    )
+  );
 }
 
 .thumb {
@@ -110,12 +188,61 @@
   transition: background-color 150ms ease;
 }
 
-.root input:checked + .track .thumb {
+.root:has(input:checked) .thumb {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_thumb-color
   );
 }
 
+.thumbIconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.checkIcon,
+.closeIcon {
+  width: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
+  height: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
+  position: absolute;
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease;
+}
+
+/* Unchecked state */
+.checkIcon {
+  opacity: 0;
+  transform: scale(0.5);
+  color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_icon-color
+  );
+}
+
+.closeIcon {
+  opacity: 1;
+  transform: scale(1);
+  color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_icon-color
+  );
+}
+
+/* Checked state — same :has() scoping already used for track/thumb color above; .thumb isn't
+   a sibling of input here (MUI nests both under switchBase), but :has() only needs input:checked
+   to be a descendant of .root, so this still scopes correctly. */
+.root:has(input:checked) .thumb .checkIcon {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.root:has(input:checked) .thumb .closeIcon {
+  opacity: 0;
+  transform: scale(0.5);
+}
+
 .labelWrapper {
   display: flex;
   flex-direction: column;
@@ -166,73 +293,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_switch-item_variants_states_disabled_properties_opacity
-  );
-}
-
-.thumbIconWrapper {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-  position: relative;
-}
-
-.checkIcon,
-.closeIcon {
-  width: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
-  height: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
-  position: absolute;
-  transition:
-    opacity 150ms ease,
-    transform 150ms ease;
-}
-
-/* Unchecked state */
-.checkIcon {
-  opacity: 0;
-  transform: scale(0.5);
-  color: var(
-    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_icon-color
-  );
-}
-
-.closeIcon {
-  opacity: 1;
-  transform: scale(1);
-  color: var(
-    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_icon-color
-  );
-}
-
-/* Checked state */
-.root input:checked + .track .thumb .checkIcon {
-  opacity: 1;
-  transform: scale(1);
-}
-
-.root input:checked + .track .thumb .closeIcon {
-  opacity: 0;
-  transform: scale(0.5);
-}
+/* description/error text renders via AssistiveElement directly (see Switch.tsx) —
+   it owns its own tokenized styling. AssistiveElement has no disabled state and
+   must never dim. */
 
 /* --- GROUP STYLES --- */
 .groupRoot {

package/src/components/Switch/Switch.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, useContext } from "react";
 import {
   Switch as MuiSwitch,
   type SwitchProps as MuiSwitchProps,
@@ -17,9 +17,49 @@ import {
   FormControlLayout,
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 import styles from "./Switch.module.css";
 
-// Removed unused SwitchGroup import
+import { SwitchGroup, SwitchGroupContext } from "./SwitchGroup";
+
+// Same glyphs as mantine-adapter's Switch (re-exported from @mantine/core's CheckIcon/CloseIcon,
+// not importable here since mui-adapter doesn't depend on @mantine/core) — kept pixel-identical
+// so adapter-tester's cross-adapter diff stays clean. Same precedent as Checkbox's inline icons.
+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>
+  );
+}
+
+function CloseIcon(props: React.ComponentProps<"svg">) {
+  return (
+    <svg
+      viewBox="0 0 15 15"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M11.7816 4.03157C12.0062 3.80702 12.0062 3.44295 11.7816 3.2184C11.5571 2.99385 11.193 2.99385 10.9685 3.2184L7.50005 6.68682L4.03164 3.2184C3.80708 2.99385 3.44301 2.99385 3.21846 3.2184C2.99391 3.44295 2.99391 3.80702 3.21846 4.03157L6.68688 7.49999L3.21846 10.9684C2.99391 11.193 2.99391 11.557 3.21846 11.7816C3.44301 12.0061 3.80708 12.0061 4.03164 11.7816L7.50005 8.31316L10.9685 11.7816C11.193 12.0061 11.5571 12.0061 11.7816 11.7816C12.0062 11.557 12.0062 11.193 11.7816 10.9684L8.31322 7.49999L11.7816 4.03157Z"
+        fill="currentColor"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+}
 
 export type SwitchWrapperProps = Omit<
   MuiSwitchProps,
@@ -37,7 +77,11 @@ export type RecursicaSwitchPropsAlias =
 
 export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
 
-type SwitchComponent = React.ComponentType<SwitchProps>;
+type SwitchComponent = React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof SwitchGroup;
+};
 
 export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
   function Switch(props, ref) {
@@ -46,7 +90,6 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       readOnly,
       readOnlyComponent,
       disabled,
-      // Removed thumbIcon from destructured props since it's not supported
       formLayout,
       labelSize,
       controlMaxWidth,
@@ -66,31 +109,47 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
     delete restRecord["radius"];
     delete restRecord["variant"];
 
+    // 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
+    // wrapper class (applied separately, see finalClass below) and sizing the actual MUI
+    // switch span the same way would squeeze that wrapper down to the track's own width.
+    // See SWITCH_IMPLEMENTATION_NOTES.md #5.
+    // NOTE: no "thumb" key here — the default MuiSwitch-thumb slot classes.thumb targets is
+    // never rendered. We supply our own icon/checkedIcon node below (see thumbNode), which
+    // 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.root,
+      root: styles.switchRoot,
       body: styles.body,
       track: styles.track,
-      thumb: styles.thumb,
+      switchBase: styles.switchBase,
       trackLabel: styles.trackLabel,
       labelWrapper: styles.labelWrapper,
       label: styles.label,
     };
 
-    const classNamesProp = restRecord.classNames;
+    // 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 (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
+      classesProp &&
+      typeof classesProp === "object" &&
+      !Array.isArray(classesProp)
     ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+      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.thumb = o.thumb
-        ? `${styles.thumb} ${o.thumb}`
-        : styles.thumb;
       mergedClassNames.trackLabel = o.trackLabel
         ? `${styles.trackLabel} ${o.trackLabel}`
         : styles.trackLabel;
@@ -107,8 +166,29 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       ? `${styles.root} ${classNameProp}`
       : styles.root;
 
+    // Threads a grouped Switch's checked state through SwitchGroupContext (mirrors Checkbox's
+    // identical CheckboxGroupContext pattern) — FormGroup itself has no controlled-value
+    // concept, so this is the only place group membership is actually computed. Standalone
+    // (ungrouped) Switch usage is untouched: isChecked/isGroupReadOnly are no-ops outside a
+    // <Switch.Group>. See SWITCH_IMPLEMENTATION_NOTES.md.
+    const groupContext = useContext(SwitchGroupContext);
+    const isGrouped = groupContext !== null;
+    const isGroupReadOnly = isGrouped ? !!groupContext.readOnly : false;
+    const isChecked = isGrouped
+      ? (groupContext.value || []).includes(restRecord.value as string)
+      : !!(restRecord.checked ?? restRecord.defaultChecked);
+
+    const handleGroupChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      if (!isGrouped) return;
+      const currentValue = groupContext.value || [];
+      const thisValue = restRecord.value as string;
+      const newValue = event.target.checked
+        ? [...currentValue, thisValue]
+        : currentValue.filter((v) => v !== thisValue);
+      groupContext.onChange?.(event, newValue);
+    };
+
     if (readOnly && !!readOnlyComponent) {
-      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
       const ReadOnlyComp = readOnlyComponent;
       const roNode = (
         <ReadOnlyComp
@@ -134,17 +214,41 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       return <>{roNode}</>;
     }
 
-    // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css
+    // Same node passed as both icon and checkedIcon (mirrors MUI's own Switch.js, which does
+    // the same: `icon={icon} checkedIcon={icon}`) so it never unmounts/remounts on toggle —
+    // that's what lets the checkIcon/closeIcon crossfade via CSS opacity instead of a hard swap,
+    // matching mantine-adapter's thumbIcon (single node, both glyphs always mounted).
+    const thumbNode = (
+      <span className={styles.thumb}>
+        <span className={styles.thumbIconWrapper}>
+          <CheckIcon className={styles.checkIcon} />
+          <CloseIcon className={styles.closeIcon} />
+        </span>
+      </span>
+    );
+
+    // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css.
+    // color is hardcoded to "default" (never left to MUI's "primary" fallback) so MUI's own
+    // palette-driven blue checked/hover/focus styling never activates in the first place —
+    // see SWITCH_IMPLEMENTATION_NOTES.md #5.
+    const isSwitchDisabled = readOnly || disabled || isGroupReadOnly;
+
     const switchNode = (
       <MuiSwitch
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ref={ref as any}
         className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
-        disabled={readOnly || disabled}
-        data-disabled={readOnly || disabled || undefined}
-        // thumbIcon={thumbIcon ?? FinalThumbIcon}
+        color="default"
+        disabled={isSwitchDisabled}
+        data-disabled={isSwitchDisabled || undefined}
+        icon={thumbNode}
+        checkedIcon={thumbNode}
         {...(sanitizedProps as unknown as MuiSwitchProps)}
+        {...(isGrouped
+          ? { checked: isChecked, onChange: handleGroupChange }
+          : {})}
+        disableRipple
       />
     );
 
@@ -160,21 +264,23 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
             >
               {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>
@@ -201,3 +307,4 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
 ) as SwitchComponent;
 
 Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;

package/src/components/Switch/SwitchGroup.tsx

@@ -13,6 +13,14 @@ import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/For
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import styles from "./Switch.module.css";
 
+// eslint-disable-next-line react-refresh/only-export-components
+export const SwitchGroupContext = React.createContext<{
+  value?: string[];
+  onChange?: (event: React.SyntheticEvent, value: string[]) => void;
+  name?: string;
+  readOnly?: boolean;
+} | null>(null);
+
 import { type RecursicaSwitchGroupProps as BaseRecursicaSwitchGroupProps } from "@recursica/adapter-common";
 
 export interface RecursicaSwitchGroupProps
@@ -69,7 +77,6 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
       emptyValueComponent,
       value,
       defaultValue,
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       onChange,
       ...rest
     } = props;
@@ -79,11 +86,23 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
     // Delete prohibited sizing hooks from bypassing the variables
     delete restRecord["size"];
 
+    const handleChange = (
+      _event: React.SyntheticEvent,
+      childValue: string[],
+    ) => {
+      if (onChange) {
+        onChange(childValue);
+      }
+    };
+
     return (
       <WithReadOnlyWrapper
         className={className}
         style={style as React.CSSProperties}
-        controlMaxWidth="var(--recursica_ui-kit_components_switch-item_properties_label-max-width)"
+        // No group-level max-width: switch-item label-max-width (200px) caps a single switch's
+        // own label text, not the whole group — reusing it here made the side-by-side label
+        // column (fixed 224px) wider than its container, so it always wrapped onto its own line.
+        controlMaxWidth={undefined}
         controlMinWidth={undefined}
         overStyled={overStyled as true}
         // Strictly override. ARIA grouping prohibits interactive switches nested natively inside <label>.
@@ -107,14 +126,23 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
         readOnlyValue={value !== undefined ? value : defaultValue}
         readOnlyNativeProps={props}
         activeComponent={
-          <MuiFormGroup
-            ref={ref}
-            {...(sanitizedProps as unknown as MuiFormGroupProps)}
-            className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
-            data-layout={formLayout}
+          <SwitchGroupContext.Provider
+            value={{
+              value: value !== undefined ? value : defaultValue,
+              onChange: handleChange,
+              name: restRecord.name as string | undefined,
+              readOnly: readOnly || !!(restRecord as any).disabled,
+            }}
           >
-            {children}
-          </MuiFormGroup>
+            <MuiFormGroup
+              ref={ref}
+              {...(sanitizedProps as unknown as MuiFormGroupProps)}
+              className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
+              data-layout={formLayout}
+            >
+              {children}
+            </MuiFormGroup>
+          </SwitchGroupContext.Provider>
         }
       />
     );

package/src/components/Table/Table.tsx

@@ -44,8 +44,8 @@ const TableBase = forwardRef<HTMLTableElement, TableProps>(function Table(
   return (
     <MuiTable
       ref={ref}
-      className={finalClass}
       {...(sanitizedProps as unknown as MuiTableProps)}
+      className={finalClass}
     />
   );
 });

package/src/components/Tabs/IMPLEMENTATION_NOTES.md

@@ -2,3 +2,13 @@
 
 - **Compositional API Dropped:** Mantine uses `<Tabs.List>`, `<Tabs.Tab>`, and `<Tabs.Panel>` natively with implicit context from `<Tabs>`. MUI relies on `@mui/lab/TabContext` and separates `Tabs` and `TabPanel`.
 - **Monolithic API Adopted:** Following architectural review, we have opted to drop the broken dot-notation wrappers for `mui-adapter`. We now natively export `Tabs` (MUI List), `Tab` (MUI Item), and `TabPanel` (from `@mui/lab`). Developers must use `TabContext` (from `@mui/lab`) to manage state, just like native MUI. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.
+
+## Traps found via adapter-tester parity fixing (2026-08-15)
+
+- **`Tabs` doesn't read `TabContext`:** only `TabPanel` (from `@mui/lab`) consumes it. `Tabs` (from `@mui/material`) needs its own explicit `value` prop or every tab renders permanently unselected (no error, just silently inert). See USAGE.md's warning callout.
+- **`TabPanel` is a DOM sibling of `Tabs`, not nested inside it:** any `.root .panel`-style descendant selector in this file silently never matches. Scope panel rules off the bare class instead. Consumers must also wrap both in their own column-direction container (Storybook does this via `Flex`) — otherwise the panel renders beside the tab list, not below it, because there's nothing else establishing the block stacking.
+- **`.Mui-selected` needs `:global(...)`:** written bare in a `.module.css` file, CSS Modules locally scopes it to something like `.Tabs-module__Mui-selected___xxx`, which never matches the real MUI-applied class. Every reference to a native MUI state class in this file must be `:global(.Mui-selected)`, not `.Mui-selected`. (SegmentedControl's `.control.Mui-selected` has this exact same latent bug — not fixed as part of this pass, flagged separately.)
+- **MUI's Tab defaults to `min-height: 72px`** for icon+label tabs (48px otherwise); Mantine's tab height is purely padding/content-driven. Reset to `min-height: auto` or the whole row renders visibly taller than Mantine's.
+- **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.