@recursica/mui-adapter 0.4.0 → 0.6.0

package/src/components/Stepper/Stepper.module.css

@@ -0,0 +1,410 @@
+/* 
+  Recursica Stepper CSS module natively binding to Figma variables.
+  
+  HARDCODED CSS NOTE:
+  For horizontal layout, Mantine natively renders the text horizontally alongside the icon.
+  To achieve Recursica's layout where horizontal orientation stacks text below the icon, 
+  we force `.step` to be a column, `.stepBody` to remove margin and text-align center, 
+  and the `.separator`'s margin-top is dynamically calculated `calc((indicator-size / 2) - 1px)` 
+  to ensure it continues to align with the vertical center of the indicator rather than the 
+  whole step wrapper.
+*/
+
+.root {
+  /* Orientation specific gaps are mapped via data attributes */
+}
+
+.root.horizontal .steps {
+  align-items: flex-start;
+  --stepper-step-gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_step-gap
+  );
+  --stepper-max-text-width: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_max-text-width
+  );
+}
+
+.root.horizontal .step {
+  flex-direction: column;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_indicator-label-gap
+  );
+}
+
+.root.horizontal .stepBody {
+  width: var(--stepper-max-text-width);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-start;
+  margin-left: 0; /* Mantine natively applies a margin-inline-start */
+  gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_horizontal_properties_label-description-gap
+  );
+}
+
+.root.horizontal .stepLabel,
+.root.horizontal .stepDescription {
+  width: max-content;
+  max-width: var(--stepper-max-text-width);
+  text-align: center;
+  white-space: normal;
+}
+
+.root.horizontal .separator {
+  align-self: flex-start; /* Force to top regardless of container alignment */
+  margin-top: calc(var(--stepper-indicator-size) / 2 - 1px);
+  margin-left: calc(
+    -1 * (var(--stepper-max-text-width) - var(--stepper-indicator-size)) / 2
+  );
+  margin-right: calc(
+    -1 * (var(--stepper-max-text-width) - var(--stepper-indicator-size)) / 2
+  );
+}
+
+/* Vertical Orientation */
+.root.vertical {
+  --stepper-step-gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_step-gap
+  );
+  --separator-spacing: 0px; /* Force the line to touch the circle */
+  --stepper-max-text-width: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_max-text-width
+  );
+}
+
+.root.vertical .step {
+  gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_indicator-label-gap
+  );
+  margin-top: 0 !important; /* Remove Mantine's gap */
+  padding-bottom: var(
+    --stepper-step-gap
+  ); /* Move gap inside the step so the separator line can stretch through it */
+}
+
+.root.vertical .step:last-of-type {
+  padding-bottom: 0;
+}
+
+.root.vertical .stepBody {
+  gap: var(
+    --recursica_ui-kit_components_stepper_variants_orientation_vertical_properties_label-description-gap
+  );
+}
+
+/* Sizes */
+.large {
+  --stepper-icon-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_indicator-size
+  ); /* Maps to Mantine's circle size */
+  --stepper-indicator-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_indicator-size
+  );
+  --stepper-border-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_indicator-border-size
+  );
+  --stepper-border-radius: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_indicator-border-radius
+  );
+  --stepper-font-family: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_font-family
+  );
+  --stepper-font-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_font-size
+  );
+  --stepper-font-style: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_font-style
+  );
+  --stepper-font-weight: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_font-weight
+  );
+  --stepper-letter-spacing: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_letter-spacing
+  );
+  --stepper-line-height: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_line-height
+  );
+  --stepper-text-decoration: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_text-decoration
+  );
+  --stepper-text-transform: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-text_text-transform
+  );
+  --stepper-svg-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_completed-icon-size
+  );
+}
+
+.small {
+  --stepper-icon-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_indicator-size
+  ); /* Maps to Mantine's circle size */
+  --stepper-indicator-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_indicator-size
+  );
+  --stepper-border-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_indicator-border-size
+  );
+  --stepper-border-radius: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_indicator-border-radius
+  );
+  --stepper-font-family: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_font-family
+  );
+  --stepper-font-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_font-size
+  );
+  --stepper-font-style: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_font-style
+  );
+  --stepper-font-weight: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_font-weight
+  );
+  --stepper-letter-spacing: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_letter-spacing
+  );
+  --stepper-line-height: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_line-height
+  );
+  --stepper-text-decoration: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_text-decoration
+  );
+  --stepper-text-transform: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-text_text-transform
+  );
+  --stepper-svg-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_completed-icon-size
+  );
+}
+
+/* Core Element Structuring using mapped variables */
+.root .step {
+  /* Default to Mantine's native flex behavior (stretch) so the vertical separator spans the full height */
+}
+
+.root .stepBody {
+  max-width: var(--stepper-max-text-width);
+  display: flex;
+  flex-direction: column;
+}
+
+.root .stepLabel {
+  font-family: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_stepper_properties_label-text_text-transform
+  );
+}
+
+.root .stepDescription {
+  font-family: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_stepper_properties_description-text_text-transform
+  );
+}
+
+.root .stepIcon {
+  width: var(--stepper-indicator-size);
+  height: var(--stepper-indicator-size);
+  min-width: var(--stepper-indicator-size);
+  min-height: var(--stepper-indicator-size);
+  border-width: var(--stepper-border-size);
+  border-radius: 50%; /* Override Figma token to ensure perfectly circular indicators */
+
+  font-family: var(--stepper-font-family);
+  font-size: var(--stepper-font-size);
+  font-style: var(--stepper-font-style);
+  font-weight: var(--stepper-font-weight);
+  letter-spacing: var(--stepper-letter-spacing);
+  line-height: var(--stepper-line-height);
+  text-decoration: var(--stepper-text-decoration);
+  text-transform: var(--stepper-text-transform);
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Font details are implicitly mapped by sizes, but colors map to states */
+  /* Upcoming State (Pending) - Default */
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-indicator-background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-indicator-border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-indicator-text
+  );
+}
+
+/* Completed State */
+.root .stepIcon.Mui-completed,
+.root .stepIcon:has(.Mui-completed) {
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-indicator-background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-indicator-border-color
+  );
+}
+
+.root .stepCompletedIcon {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-indicator-text
+  );
+}
+
+.root .stepCompletedIcon svg {
+  width: var(--stepper-svg-size);
+  height: var(--stepper-svg-size);
+}
+
+.root .stepLabel.Mui-completed {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-label-color
+  );
+}
+
+.root .stepDescription:has(~ .Mui-completed),
+.root .MuiStepLabel-root.Mui-completed .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-description-color
+  );
+}
+
+/* Current State (Progressing) */
+.root .stepIcon.Mui-active,
+.root .stepIcon:has(.Mui-active) {
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-indicator-background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-indicator-border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-indicator-text
+  );
+}
+
+.root .stepLabel.Mui-active {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-label-color
+  );
+}
+
+.root .stepDescription:has(~ .Mui-active),
+.root .MuiStepLabel-root.Mui-active .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-description-color
+  );
+}
+
+/* Upcoming State (Pending Labels) */
+.root .stepLabel:not(.Mui-active):not(.Mui-completed) {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-label-color
+  );
+}
+
+.root .MuiStepLabel-root:not(.Mui-active):not(.Mui-completed) .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-description-color
+  );
+}
+
+/* Horizontal Separator */
+.root .separator {
+  margin: 0 var(--stepper-step-gap); /* Apply the gap logic to the separator natively */
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
+  );
+  height: var(
+    --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
+  );
+  border: none;
+  min-width: 20px;
+  flex: 1;
+}
+
+.root .separator.Mui-active,
+.root .separator.Mui-completed {
+  background-color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
+  );
+  height: var(
+    --recursica_ui-kit_components_stepper_properties_completed-connector-size
+  );
+}
+
+/* Vertical Separator */
+.root .verticalSeparator {
+  border-inline-start: var(
+      --recursica_ui-kit_components_stepper_properties_upcoming-connector-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_stepper_properties_colors_upcoming-connector-color
+    );
+  top: var(
+    --stepper-icon-size
+  ); /* Overrides Mantine's gap math to force the line to touch the icon */
+}
+
+.root .verticalSeparator.Mui-active,
+.root .verticalSeparator.Mui-completed {
+  border-inline-start: var(
+      --recursica_ui-kit_components_stepper_properties_completed-connector-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_stepper_properties_colors_completed-connector-color
+    );
+}
+
+/* Hide Content 
+   Recursica Steppers are purely navigational/structural. Content should be managed 
+   by the parent layout outside of the Stepper DOM. 
+*/
+.root .content {
+  display: none;
+}

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

@@ -1,28 +1,41 @@
+import React, { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Stepper } from "./Stepper";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Button } from "../Button/Button";
+import { Group } from "../Group/Group";
+import { Flex } from "../Flex/Flex";
 
 const meta: Meta<typeof Stepper> = {
-  title: "UI-Kit/🚧 Stepper",
+  title: "UI-Kit/Stepper",
   component: Stepper,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`Stepper\` component provides a visual progression interface strictly mapped to Recursica's UI-Kit.
+This component wraps Mantine's \`Stepper\` and natively enforces Figma tokens for sizes, colors, gaps, and states (\`completed\`, \`current\`, \`upcoming\`).
+
+### Layout & Orientation
+Orientation dictates how the steps flow:
+- **horizontal**: Steps render side-by-side. 
+- **vertical**: Steps stack vertically, mapping seamlessly to the vertical gap tokens.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: "radio",
+      options: ["small", "large"],
+    },
+    orientation: {
+      control: "radio",
+      options: ["horizontal", "vertical"],
+    },
+    defaultChecked: {
+      table: { disable: true },
     },
   },
 };
@@ -30,6 +43,106 @@ const meta: Meta<typeof Stepper> = {
 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));
+
+  return (
+    <Flex direction="column" w={600}>
+      <Stepper {...args} active={active} onStepClick={setActive}>
+        <Stepper.Step
+          label="First step"
+          description="Create an account and set up your billing profile"
+        />
+        <Stepper.Step
+          label="Second step"
+          description="Verify email and ensure all notification preferences are correct"
+        />
+        <Stepper.Step label="Final step" description="Get full access" />
+        <Stepper.Completed>
+          Completed, click back button to get to previous step
+        </Stepper.Completed>
+      </Stepper>
+
+      <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: () => <ComingSoon componentName="Stepper" />,
+  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));
+
+  return (
+    <Flex direction="column" w={600}>
+      <Stepper {...args} active={active} onStepClick={setActive}>
+        <Stepper.Step
+          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"
+        />
+        <Stepper.Step
+          label="Second step"
+          description="Verify email and ensure all notification preferences are correct"
+        />
+        <Stepper.Step label="Final step" />
+        <Stepper.Completed>
+          Completed, click back button to get to previous step
+        </Stepper.Completed>
+      </Stepper>
+
+      <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",
+  },
 };