@recursica/adapter-mui-v7 1.0.0

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,294 @@
+import { forwardRef, useContext } from "react";
+import {
+  Switch as MuiSwitch,
+  type SwitchProps as MuiSwitchProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type RequireAccessibleLabel,
+  type RecursicaSwitchProps,
+} from "@recursica/adapter-common";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import styles from "./Switch.module.css";
+
+import { SwitchGroup, SwitchGroupContext } from "./SwitchGroup";
+
+// Same glyphs as mantine-adapter's Switch (re-exported from @mantine/core's CheckIcon/CloseIcon,
+// not importable here since adapter-mui-v7 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,
+  "size" | "color" | "radius" | "variant"
+> &
+  RecursicaSwitchProps &
+  ReadOnlyControlProps &
+  Pick<
+    FormControlLayoutProps,
+    "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+  >;
+
+export type RecursicaSwitchPropsAlias =
+  RequireAccessibleLabel<SwitchWrapperProps>;
+
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
+
+type SwitchComponent = React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof SwitchGroup;
+};
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
+  function Switch(props, ref) {
+    const {
+      overStyled = false,
+      readOnly,
+      readOnlyComponent,
+      disabled,
+      formLayout,
+      labelSize,
+      controlMaxWidth,
+      controlMinWidth,
+      label,
+      description,
+      error,
+      style,
+      ...rest
+    } = props;
+    // 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)[];
+
+    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
+    // 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.
+    // 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
+      ? `${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 ReadOnlyComp = readOnlyComponent;
+      const roNode = (
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={label as React.ReactNode}
+        />
+      );
+
+      if (formLayout) {
+        return (
+          <FormControlLayout
+            formLayout={formLayout}
+            labelSize={labelSize}
+            controlMaxWidth={controlMaxWidth}
+            controlMinWidth={controlMinWidth}
+          >
+            {roNode}
+          </FormControlLayout>
+        );
+      }
+
+      return <>{roNode}</>;
+    }
+
+    // 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}
+        {...(sanitizedProps as unknown as MuiSwitchProps)}
+        className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
+        classes={mergedClassNames}
+        color="default"
+        disabled={isSwitchDisabled}
+        data-disabled={isSwitchDisabled || undefined}
+        icon={thumbNode}
+        checkedIcon={thumbNode}
+        {...(isGrouped
+          ? { checked: isChecked, onChange: handleGroupChange }
+          : {})}
+        disableRipple
+      />
+    );
+
+    const finalNode = label ? (
+      <div className={finalClass} style={style as React.CSSProperties}>
+        <div className={styles.body}>
+          {switchNode}
+          <div className={styles.labelWrapper}>
+            <label
+              className={styles.label}
+              htmlFor={restRecord.id as string}
+              data-disabled={readOnly || disabled ? true : undefined}
+            >
+              {label as React.ReactNode}
+            </label>
+            {/* description/error are mutually exclusive — error takes precedence */}
+            {error ? (
+              <AssistiveElement
+                assistiveVariant="error"
+                assistiveWithIcon={false}
+              >
+                {error}
+              </AssistiveElement>
+            ) : (
+              description && (
+                <AssistiveElement
+                  assistiveVariant="help"
+                  assistiveWithIcon={false}
+                >
+                  {description}
+                </AssistiveElement>
+              )
+            )}
+          </div>
+        </div>
+      </div>
+    ) : (
+      switchNode
+    );
+
+    if (formLayout) {
+      return (
+        <FormControlLayout
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {finalNode}
+        </FormControlLayout>
+      );
+    }
+
+    return finalNode;
+  },
+) as SwitchComponent;
+
+Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;

package/src/components/Switch/SwitchGroup.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { SwitchGroup } from "./SwitchGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof SwitchGroup> = {
+  title: "UI-Kit/SwitchGroup",
+  component: SwitchGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`SwitchGroup\` component is the mandatory organizational wrapper for orchestrating \`Switch\` primitives into macro form layouts. It inherently leverages the \`FormControlWrapper\`, granting native access to structural alignments, assistive descriptions, and strict flex arrays.
+
+### Supported Layout Vectors
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked switch array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal switches cleanly alongside it horizontally.
+
+> [!IMPORTANT]  
+> If you require a solitary \`Switch\` field to natively accept an overarching form label, assistive text, or align with other side-by-side components in a form column, you must wrap it inside a \`Switch.Group\` to trigger the \`FormControlWrapper\` mapping.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Passes read-only lock natively down mapping inner switches into explicitly disabled states.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SwitchGroup>;
+
+export const Default: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Standard Group",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="1" label="Option 1" />
+        <Switch value="2" label="Option 2" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Notification Settings",
+    description: "Manage your preferences.",
+    assistiveText: "We recommend turning these on.",
+    error: "",
+    required: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...StackedLayout.args,
+    formLayout: "side-by-side",
+    labelSize: "default",
+    labelAlignment: "left",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="weekly" label="Weekly Digest" />
+        <Switch value="marketing" label="Marketing Emails" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SolitaryFormControl: Story = {
+  args: {
+    formLayout: "side-by-side",
+    label: "Enable Backups",
+    description: "Automatically back up your data nightly.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["auto"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="auto" label="Auto-backup" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    ...StackedLayout.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email", "sms"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};

package/src/components/Switch/SwitchGroup.tsx

@@ -0,0 +1,156 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  FormGroup as MuiFormGroup,
+  type FormGroupProps as MuiFormGroupProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+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
+  extends Omit<
+      MuiFormGroupProps,
+      | "size"
+      | "labelProps"
+      | "onChange"
+      | "classes"
+      | "ref"
+      | "value"
+      | "defaultValue"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "classes"
+      | "onChange"
+      | "defaultValue"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaSwitchGroupProps {
+  // MUI has no native switch-group concept to match (its own `FormGroup` is layout-only, no
+  // value/onChange) — this signature is Recursica's own, same as TransferList/Accordion/CheckboxGroup.
+  onChange?: (value: string[]) => void;
+}
+
+export type SwitchGroupProps = RecursicaOverStyled<RecursicaSwitchGroupProps>;
+
+export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
+  function SwitchGroup(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mui Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // removed withAsterisk
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      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>;
+
+    const handleChange = (
+      _event: React.SyntheticEvent,
+      childValue: string[],
+    ) => {
+      if (onChange) {
+        onChange(childValue);
+      }
+    };
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        // 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>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <SwitchGroupContext.Provider
+            value={{
+              value: value !== undefined ? value : defaultValue,
+              onChange: handleChange,
+              name: restRecord.name as string | undefined,
+              readOnly: readOnly || !!(restRecord as any).disabled,
+            }}
+          >
+            <MuiFormGroup
+              ref={ref}
+              {...(sanitizedProps as unknown as MuiFormGroupProps)}
+              className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
+              data-layout={formLayout}
+            >
+              {children}
+            </MuiFormGroup>
+          </SwitchGroupContext.Provider>
+        }
+      />
+    );
+  },
+);
+
+SwitchGroup.displayName = "SwitchGroup";

package/src/components/Switch/USAGE.md

@@ -0,0 +1,36 @@
+# Switch - Usage Guide
+
+This document describes how to integrate and use the `Switch` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Switch } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Switch } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Switch label="Enable notifications" defaultChecked />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **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.

package/src/components/Switch/index.ts

@@ -0,0 +1,2 @@
+export * from "./Switch";
+export * from "./SwitchGroup";