@recursica/adapter-mui-v7 1.0.0

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

@@ -0,0 +1,346 @@
+/* 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. .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
+  );
+  --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
+  );
+}
+
+/* Track/thumb dim per selection state; label dims via its own (single, state-agnostic) token */
+/* 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)) .thumb {
+  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:has(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
+  );
+  border: none; /* HARDCODE */
+  opacity: 1; /* HARDCODE */
+  box-sizing: border-box;
+  transition: background-color 150ms ease;
+  cursor: inherit;
+}
+
+.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 {
+  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: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;
+  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
+  );
+}
+
+/* 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 {
+  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 spacing="rec-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.