@recursica/adapter-mantine-v8 1.0.0

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,64 @@
+# Switch Implementation Notes
+
+This document acts as a living record tracking the layout decisions, architectural tradeoffs, and structural hacks explicitly applied to the `Switch` component wrapper to bridge Mantine's defaults with the Recursica UI Kit's rigid requirements.
+
+## 1. Stripping Mantine's Size Engine
+
+Mantine uses properties like `size`, `color`, and `radius` to dynamically map CSS layout values across its `.track` and `.thumb` nodes. We proactively strip and delete these properties using `filterStylingProps` to entirely neutralize this native behavior.
+
+## 2. Hardcoded Values & Transitions
+
+Mantine injects dynamic width/height attributes into its switch through inline CSS variables (e.g. `--switch-height`). To strictly enforce the UI Kit tokens without breaking Mantine's internal math, our `Switch.module.css` structurally remaps Mantine's internal variables explicitly:
+
+```css
+--switch-width: var(--switch-track-width);
+--switch-height: calc(
+  var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
+);
+```
+
+We also hardcode `border: none` since the UI kit designs rely purely on box-shadow elevations and background color tracking. Mantine’s default border logic is entirely disabled.
+
+## 3. ReadOnly Behavior
+
+Similar to `Checkbox`, the `Switch` component handles `readOnly` presentation by dropping the entire underlying node tree and falling back structurally onto `<FormControlWrapper>` when `readOnly: true`. This strictly preserves exact baseline alignment across all primitives without trying to hack disabled CSS to look like read-only text.
+
+## 4. Hover State Reset
+
+Mantine forcefully triggers track hover color states globally. Since Recursica currently does not map specific hover states to switch backgrounds across themes (falling back to standard unselected tokens or simply providing a cursor), we structurally wipe out Mantine's `.track:hover` class block inside `Switch.module.css`.
+
+## 5. `RecursicaSwitchGroupProps.value`/`onChange` shape
+
+Tightened to `string[]`/`(value: string[]) => void` to match Mantine's real `Switch.Group` value
+type exactly (previously `unknown[]`, which was accurate but forced `as any` casts everywhere
+this component's `value`/`defaultValue` were handed to `<MantineSwitch.Group>`). Now a genuine
+"Shared" prop — same name and shape as native, no reshaping needed.
+
+## 6. `onChange` shape mismatch (Forge's report) doesn't apply
+
+Neither `Switch` nor `SwitchGroup` reshapes native `onChange` — it flows straight through as
+Mantine's real event-based signature (`(event: ChangeEvent<HTMLInputElement>) => void` for
+`Switch`, `(value: string[]) => void` for `SwitchGroup`). Forge's report flagged an
+event-vs-boolean mismatch, but that's Forge's own dispatcher typing against the old deleted
+local components — our contract never claimed a boolean shape to begin with.
+
+## 7. Focus ring was Mantine's own default blue, not a Recursica color
+
+**Found 2026-08-14:** the hidden `<input>` was left with Mantine's own default focus outline
+(no override existed despite this file previously claiming "focus rings handled internally by
+Mantine" as an intentional decision — verified live, it renders Mantine's theme blue, not a
+Recursica token). Fixed: `.root input:focus-visible { outline: none }` suppresses the native
+outline on the input, and `.root input:focus-visible + .track { ... }` draws the real ring
+(same `--recursica_brand_states_focus_*` tokens used elsewhere) on the visible track instead —
+matching the fix made to `mui-adapter`'s Switch for parity.
+
+## `SwitchGroup` side-by-side layout always rendered as if stacked
+
+**Found 2026-08-14, reported by Matt (against mui-adapter, reproduced here too):** `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. Not a
+mui-only bug: same code pattern, same result, here. 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.

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

@@ -0,0 +1,279 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
+/* 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. input outline: none; (the real ring is drawn on .track instead, below, from Recursica
+ *    focus tokens — previously left to Mantine's own internal default outline, which renders
+ *    Mantine's theme blue, not a Recursica color)
+ */
+
+.root {
+  /* Provide a stable cursor when not disabled */
+  cursor: pointer;
+
+  --switch-track-padding: var(
+    --recursica_ui-kit_components_switch_properties_track-inner-padding
+  );
+  --switch-thumb-width: var(
+    --recursica_ui-kit_components_switch_properties_thumb-width
+  );
+  --switch-thumb-height: var(
+    --recursica_ui-kit_components_switch_properties_thumb-height
+  );
+  --switch-track-width: var(
+    --recursica_ui-kit_components_switch_properties_track-width
+  );
+}
+
+.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 {
+  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 {
+  opacity: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_variants_states_disabled_properties_opacity
+  );
+}
+
+.body {
+  display: flex;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_switch-item_properties_label-gap);
+}
+
+/* HARDCODE: disable native hover color transitions applied by Mantine */
+.track:hover {
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_track-color
+  );
+}
+.root input:checked + .track:hover {
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
+  );
+}
+
+.track {
+  width: var(--switch-track-width);
+  height: calc(var(--switch-thumb-height) + (var(--switch-track-padding) * 2));
+  border-radius: var(
+    --recursica_ui-kit_components_switch_properties_track-border-radius
+  );
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_track-color
+  );
+  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;
+  box-sizing: border-box;
+  transition: background-color 150ms ease;
+  cursor: inherit;
+}
+
+.root input:checked + .track {
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
+  );
+  border-color: transparent;
+}
+
+/* HARDCODE #3: the input itself is visually hidden (Mantine's usual pattern) but still
+   receives real keyboard focus and Mantine's own default focus outline — suppressed here so
+   the ring below (drawn on .track, the visible pill) is the only one that shows. */
+.root input:focus-visible {
+  outline: none;
+}
+
+.root input:focus-visible + .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);
+}
+
+.thumb {
+  width: var(--switch-thumb-width);
+  height: var(--switch-thumb-height);
+  border-radius: var(
+    --recursica_ui-kit_components_switch_properties_thumb-border-radius
+  );
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_thumb-color
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_switch_properties_thumb-elevation
+  );
+  border: none; /* HARDCODE */
+
+  transition: background-color 150ms ease;
+}
+
+.root input:checked + .track .thumb {
+  background-color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_thumb-color
+  );
+}
+
+.labelWrapper {
+  display: flex;
+  flex-direction: column;
+  max-width: var(
+    --recursica_ui-kit_components_switch-item_properties_label-max-width
+  );
+}
+.root:has(input:disabled) .labelWrapper {
+  opacity: var(
+    --recursica_ui-kit_components_switch-item_variants_states_disabled_properties_opacity
+  );
+}
+
+.label {
+  font-family: var(
+    --recursica_ui-kit_components_switch-item_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_switch-item_properties_text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_switch-item_properties_text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_switch-item_properties_text_font-style
+  );
+  line-height: var(
+    --recursica_ui-kit_components_switch-item_properties_text_line-height
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_switch-item_properties_text_letter-spacing
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_switch-item_properties_text_text-transform
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_switch-item_properties_text_text-decoration
+  );
+  color: var(
+    --recursica_ui-kit_components_switch-item_properties_colors_text-color
+  );
+  cursor: inherit;
+}
+
+.root:has(input:disabled) .label {
+  color: var(
+    --recursica_ui-kit_components_switch-item_properties_colors_disabled-text
+  );
+}
+
+.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);
+}
+
+/* --- GROUP STYLES --- */
+.groupRoot {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: var(--recursica_ui-kit_components_switch-group_properties_padding);
+  gap: var(--recursica_ui-kit_components_switch-group_properties_item-gap);
+}
+
+/* SideBySide Variant */
+.groupRoot[data-layout="side-by-side"] {
+  flex-direction: column;
+  gap: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_gutter
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  margin-top: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* Stacked Variant */
+.groupRoot[data-layout="stacked"] {
+  flex-direction: column;
+  margin-top: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_stacked_properties_label-field-gap
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_switch-group_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}

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

@@ -0,0 +1,114 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { Stack } from "../Stack/Stack";
+
+const meta: Meta<typeof Switch> = {
+  title: "UI-Kit/Switch",
+  component: Switch,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Switch\` component is an atomic form primitive representing boolean states, natively aligned to the Recursica design system.
+
+> [!IMPORTANT]  
+> Unlike \`Checkbox\`, the \`Switch\` is typically used for standalone settings toggles. It fully supports the universal \`ReadOnlyField\` boundaries when passed the \`readOnly\` attribute.
+
+### Usage
+To render a standard switch:
+\`\`\`tsx
+<Switch label="Enable Notifications" defaultChecked />
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    checked: {
+      control: "boolean",
+    },
+    disabled: {
+      control: "boolean",
+    },
+    required: {
+      control: "boolean",
+    },
+    error: {
+      control: "boolean",
+    },
+    defaultChecked: {
+      control: "boolean",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+    controlMaxWidth: { table: { disable: true } },
+    controlMinWidth: { table: { disable: true } },
+    emptyValueComponent: { table: { disable: true } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Standard Switch",
+  },
+  // We explicitly destructure global Storybook injected arguments so they do not leak into the DOM natively.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    label: "Opt-in form alignment",
+    formLayout: "side-by-side",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <Stack gap="xl">
+      <Switch label="Default Unchecked State" />
+      <Switch label="Checked State" defaultChecked />
+      <Switch label="Disabled Unchecked" disabled />
+      <Switch label="Disabled Checked" defaultChecked disabled />
+    </Stack>
+  ),
+};
+
+export const ReadOnly: Story = {
+  args: {
+    ...Default.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const CustomReadOnly: Story = {
+  args: {
+    ...Default.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Switch
+      {...args}
+      readOnlyComponent={({ checked, label }) => (
+        <span style={{ fontWeight: "bold", color: checked ? "green" : "red" }}>
+          {label} {checked ? "ENABLED" : "DISABLED"}
+        </span>
+      )}
+    />
+  ),
+};

package/src/components/Switch/Switch.test.tsx

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

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,177 @@
+import { forwardRef, type CSSProperties } from "react";
+import {
+  Switch as MantineSwitch,
+  type SwitchProps as MantineSwitchProps,
+  CheckIcon,
+  CloseIcon,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
+  mergeStyles,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type RequireAccessibleLabel,
+  type RecursicaSwitchProps,
+} from "@recursica/adapter-common";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+import styles from "./Switch.module.css";
+
+import { SwitchGroup } from "./SwitchGroup";
+
+export type SwitchWrapperProps = Omit<
+  MantineSwitchProps,
+  "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,
+      thumbIcon,
+      formLayout,
+      labelSize,
+      controlMaxWidth,
+      controlMinWidth,
+      ...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.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via Switch.module.css variables, not Mantine's native size scale.
+      "color", // Colors are token-driven via Switch.module.css; Mantine's native palette isn't exposed.
+      "radius", // Corner radius is fixed by Recursica tokens in Switch.module.css, not caller-configurable.
+      "variant", // Switch has a single Recursica-defined visual treatment; Mantine's variant isn't exposed.
+    ] as const satisfies readonly (keyof MantineSwitchProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        body: styles.body,
+        track: styles.track,
+        thumb: styles.thumb,
+        trackLabel: styles.trackLabel,
+        labelWrapper: styles.labelWrapper,
+        label: styles.label,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    // Recursica has no default per-slot inline styles here (all default styling comes from
+    // Switch.module.css above) — this only exists so a caller-supplied `styles` prop (permitted
+    // once overStyled=true clears filterStylingProps) merges in per-slot instead of needing its
+    // own passthrough path.
+    const mergedStyles = mergeStyles(
+      {} as Record<string, CSSProperties | undefined>,
+      restRecord.styles as Partial<Record<string, CSSProperties>> | undefined,
+    );
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    if (readOnly && !!readOnlyComponent) {
+      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
+      const ReadOnlyComp = readOnlyComponent;
+      const roNode = (
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={restRecord.label as React.ReactNode}
+        />
+      );
+
+      if (formLayout) {
+        return (
+          <FormControlLayout
+            formLayout={formLayout}
+            labelSize={labelSize}
+            controlMaxWidth={controlMaxWidth}
+            controlMinWidth={controlMinWidth}
+          >
+            {roNode}
+          </FormControlLayout>
+        );
+      }
+
+      return <>{roNode}</>;
+    }
+
+    const FinalThumbIcon = (
+      <div className={styles.thumbIconWrapper}>
+        <CheckIcon className={styles.checkIcon} />
+        <CloseIcon className={styles.closeIcon} />
+      </div>
+    );
+
+    // We omit Mantine's sizing/coloring so we rely strictly on variables from Switch.module.css
+    const switchNode = (
+      <MantineSwitch
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineSwitchProps)}
+        className={finalClass}
+        classNames={mergedClassNames}
+        styles={mergedStyles}
+        disabled={readOnly || disabled}
+        data-disabled={readOnly || disabled || undefined}
+        thumbIcon={withCallerOverride<React.ReactNode>(
+          FinalThumbIcon,
+          thumbIcon,
+        )}
+      />
+    );
+
+    if (formLayout) {
+      return (
+        <FormControlLayout
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {switchNode}
+        </FormControlLayout>
+      );
+    }
+
+    return switchNode;
+  },
+) as SwitchComponent;
+
+Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;