@recursica/adapter-mui-v7 1.0.0

package/src/components/Stepper/Stepper.stories.tsx

@@ -0,0 +1,157 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stepper, Step, StepLabel } from "./Stepper";
+import { Button } from "../Button/Button";
+import { Group } from "../Group/Group";
+import { Flex } from "../Flex/Flex";
+
+const meta: Meta<typeof Stepper> = {
+  title: "UI-Kit/Stepper",
+  component: Stepper,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    size: {
+      control: "radio",
+      options: ["small", "large"],
+    },
+    orientation: {
+      control: "radio",
+      options: ["horizontal", "vertical"],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stepper>;
+
+const InteractiveStepper = (args: React.ComponentProps<typeof Stepper>) => {
+  const [active, setActive] = useState(1);
+  const nextStep = () =>
+    setActive((current) => (current < 3 ? current + 1 : current));
+  const prevStep = () =>
+    setActive((current) => (current > 0 ? current - 1 : current));
+
+  const steps = [
+    {
+      label: "First step",
+      description: "Create an account and set up your billing profile",
+    },
+    {
+      label: "Second step",
+      description:
+        "Verify email and ensure all notification preferences are correct",
+    },
+    { label: "Final step", description: "Get full access" },
+  ];
+
+  return (
+    <Flex direction="column" style={{ width: 600 }}>
+      <Stepper {...args} activeStep={active}>
+        {steps.map((step, index) => (
+          <Step key={index} completed={active > index}>
+            <StepLabel description={step.description}>{step.label}</StepLabel>
+          </Step>
+        ))}
+      </Stepper>
+
+      {active === steps.length && (
+        <div style={{ marginTop: 24, textAlign: "center" }}>
+          Completed, click back button to get to previous step
+        </div>
+      )}
+
+      <Group mt={24} justify="center" gap={8}>
+        <Button variant="outline" onClick={prevStep} disabled={active === 0}>
+          Previous step
+        </Button>
+        <Button variant="outline" onClick={nextStep} disabled={active === 3}>
+          Next step
+        </Button>
+      </Group>
+    </Flex>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => <InteractiveStepper {...args} />,
+  args: {
+    size: "large",
+    orientation: "horizontal",
+  },
+};
+
+export const Small: Story = {
+  render: (args) => <InteractiveStepper {...args} />,
+  args: {
+    size: "small",
+    orientation: "horizontal",
+  },
+};
+
+export const Vertical: Story = {
+  render: (args) => <InteractiveStepper {...args} />,
+  args: {
+    size: "large",
+    orientation: "vertical",
+  },
+};
+
+const StressTestStepper = (args: React.ComponentProps<typeof Stepper>) => {
+  const [active, setActive] = useState(1);
+  const nextStep = () =>
+    setActive((current) => (current < 3 ? current + 1 : current));
+  const prevStep = () =>
+    setActive((current) => (current > 0 ? current - 1 : current));
+
+  const steps = [
+    {
+      label:
+        "This is an extremely long step title designed to test how the layout handles multiline text wrapping and constraints",
+      description: "Create an account and set up your billing profile",
+    },
+    {
+      label: "Second step",
+      description:
+        "Verify email and ensure all notification preferences are correct",
+    },
+    { label: "Final step", description: undefined },
+  ];
+
+  return (
+    <Flex direction="column" style={{ width: 600 }}>
+      <Stepper {...args} activeStep={active}>
+        {steps.map((step, index) => (
+          <Step key={index} completed={active > index}>
+            <StepLabel description={step.description}>{step.label}</StepLabel>
+          </Step>
+        ))}
+      </Stepper>
+
+      {active === steps.length && (
+        <div style={{ marginTop: 24, textAlign: "center" }}>
+          Completed, click back button to get to previous step
+        </div>
+      )}
+
+      <Group mt={24} justify="center" gap={8}>
+        <Button variant="outline" onClick={prevStep} disabled={active === 0}>
+          Previous step
+        </Button>
+        <Button variant="outline" onClick={nextStep} disabled={active === 3}>
+          Next step
+        </Button>
+      </Group>
+    </Flex>
+  );
+};
+
+export const LayoutStressTest: Story = {
+  render: (args) => <StressTestStepper {...args} />,
+  args: {
+    size: "large",
+    orientation: "horizontal",
+  },
+};

package/src/components/Stepper/Stepper.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Stepper component tests. Add tests here if/when needed.

package/src/components/Stepper/Stepper.tsx

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

package/src/components/Stepper/USAGE.md

@@ -0,0 +1,45 @@
+# Stepper - Usage Guide
+
+This document describes how to integrate and use the `Stepper` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stepper } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stepper } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Stepper active={1}>
+      <Stepper.Step label="First step" description="Create account" />
+      <Stepper.Step label="Second step" description="Verify email" />
+    </Stepper>
+  );
+}
+```
+
+---
+
+## 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.
+> - **Default step icon**: `StepLabel` renders its own token-driven circle (with a check mark
+>   once a step is completed) by default. Pass your own `StepIconComponent` prop to `StepLabel`
+>   to override it for a given step, or pass a custom `icon` node (e.g. `<StepLabel icon={<MyIcon />}>`)
+>   to render arbitrary content in place of the circle entirely.

package/src/components/Stepper/index.ts

@@ -0,0 +1 @@
+export * from "./Stepper";

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,147 @@
+# 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 adapter-mui-v7 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.
+
+## `CustomReadOnly` story showed no label text
+
+**Found 2026-08-30, source-of-truth audit against mantine.** `Switch.tsx` destructures `label`
+out of `props` (needed for the normal, non-read-only render path), but the `readOnly` branch
+built its `roNode` from `restRecord.label` — `restRecord` comes from `rest`, which no longer has
+`label` on it since it was already pulled off `props` separately. Result: the `readOnlyComponent`
+render prop always received `label={undefined}`, so `ui-kit-switch--custom-read-only` rendered
+just "DISABLED" instead of "Standard Switch DISABLED". Mantine's version never destructures
+`label` separately, so `restRecord.label` was always populated there — same story args on both
+sides, the bug was purely in this component's own prop plumbing. Fixed by reading the already-
+destructured `label` variable instead of `restRecord.label`.
+
+## `StaticVariations` story spacing didn't match mantine
+
+**Found 2026-08-30, source-of-truth audit against mantine.** The story used `<Stack
+spacing="xl">`, but `"xl"` isn't a key in this adapter's `SPACING_MAP` (only `"rec-*"`-prefixed
+tokens are) — MUI's `Stack` then received an unrecognized raw string as its native `spacing`
+prop, which resolves to an invalid CSS length and collapses to no gap at all, bunching every
+switch together. Fixed by using `spacing="rec-xl"` (24px via
+`--recursica_brand_dimensions_general_xl`), the closest existing token. Note this is 24px vs.
+mantine's native `gap="xl"` (32px, Mantine's own spacing scale, unrelated to Recursica tokens) —
+close enough visually and no exact rec-\* equivalent of Mantine's "xl" exists; flagged rather than
+chasing pixel-parity on an arbitrary story-only value.
+
+## `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.