@recursica/mui-adapter 0.5.0 → 0.7.0

package/src/components/Stepper/Stepper.tsx

@@ -1,8 +1,149 @@
-import React from "react";
-import "./Stepper.module.css";
+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,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Stepper.module.css";
 
-export type StepperProps = React.HTMLAttributes<HTMLDivElement>;
+import { type RecursicaStepperProps } from "@recursica/adapter-common";
 
-export const Stepper: React.FC<StepperProps> = (props) => {
-  return <div {...props}>Stepper</div>;
-};
+export type StepperProps = RecursicaOverStyled<RecursicaStepperProps>;
+
+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);
+
+    return (
+      <div
+        className={`${styles.root} ${orientation === "horizontal" ? styles.horizontal : styles.vertical} ${size === "large" ? styles.large : styles.small} ${className || ""}`}
+        style={style as React.CSSProperties}
+        data-size={size}
+        data-orientation={orientation}
+      >
+        <MuiStepper
+          ref={ref as any}
+          orientation={orientation}
+          connector={
+            <MuiStepConnector
+              classes={{
+                root:
+                  orientation === "horizontal"
+                    ? styles.separator
+                    : styles.verticalSeparator,
+              }}
+            />
+          }
+          classes={{
+            root: styles.steps,
+          }}
+          {...(sanitizedProps as MuiStepperProps)}
+        />
+      </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;
+    return (
+      <MuiStep
+        ref={ref}
+        classes={{ root: styles.step }}
+        className={className || ""}
+        {...(filterStylingProps(rest, overStyled) as MuiStepProps)}
+      />
+    );
+  },
+);
+
+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, ...rest } = props;
+    return (
+      <MuiStepLabel
+        ref={ref}
+        className={className || ""}
+        classes={{
+          label: styles.stepLabel,
+          iconContainer: styles.stepIcon,
+        }}
+        optional={
+          description ? (
+            <div className={styles.stepDescription}>{description}</div>
+          ) : (
+            rest.optional
+          )
+        }
+        {...(filterStylingProps(rest, overStyled) as MuiStepLabelProps)}
+      />
+    );
+  },
+);
+
+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/Switch/Switch.module.css

@@ -1,39 +1,259 @@
-/* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_properties_item-gap */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_properties_padding */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_gutter */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_variants_layouts_side-by-side_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_variants_layouts_stacked_properties_label-field-gap */
-/* recursica-ignore: --recursica_ui-kit_components_switch-group_variants_layouts_stacked_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_colors_disabled-text */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_disabled-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_label-gap */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_label-max-width */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_switch-item_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_icon-selected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_icon-unselected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_thumb-selected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_thumb-unselected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_track-selected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_colors_track-unselected */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_thumb-border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_thumb-elevation */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_thumb-height */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_thumb-icon-size */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_thumb-width */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_track-border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_track-elevation */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_track-inner-padding */
-/* recursica-ignore: --recursica_ui-kit_components_switch_properties_track-width */
+/* 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)
+ */
+
+.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;
+  opacity: var(
+    --recursica_ui-kit_components_switch-item_properties_disabled-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_properties_colors_track-unselected
+  );
+}
+.root input:checked + .track:hover {
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-selected
+  );
+}
+
+.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_properties_colors_track-unselected
+  );
+  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_properties_colors_track-selected
+  );
+  border-color: transparent;
+}
+
+.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_properties_colors_thumb-unselected
+  );
+  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_properties_colors_thumb-selected
+  );
+}
+
+.labelWrapper {
+  display: flex;
+  flex-direction: column;
+  max-width: var(
+    --recursica_ui-kit_components_switch-item_properties_label-max-width
+  );
+}
+
+.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);
+  cursor: inherit;
+}
+
+.root:has(input:disabled) .label {
+  color: var(
+    --recursica_ui-kit_components_switch-item_properties_colors_disabled-text
+  );
+}
+
+.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_properties_disabled-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_properties_colors_icon-selected
+  );
+}
+
+.closeIcon {
+  opacity: 1;
+  transform: scale(1);
+  color: var(
+    --recursica_ui-kit_components_switch_properties_colors_icon-unselected
+  );
+}
+
+/* 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

@@ -1,35 +1,114 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Switch } from "./Switch";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Stack } from "../Stack/Stack";
 
 const meta: Meta<typeof Switch> = {
-  title: "UI-Kit/🚧 Switch",
+  title: "UI-Kit/Switch",
   component: Switch,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    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 = {
-  render: () => <ComingSoon componentName="Switch" />,
+  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>
+      )}
+    />
+  ),
 };