@recursica/mantine-adapter 0.16.0 → 0.18.0

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

@@ -0,0 +1,353 @@
+/* 
+  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-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_large_properties_step-number-font-size
+  );
+  --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-size: var(
+    --recursica_ui-kit_components_stepper_variants_sizes_small_properties_step-number-font-size
+  );
+  --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-size: var(--stepper-font-size);
+  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[data-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 .step[data-progress="completed"] .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-label-color
+  );
+}
+
+.root .step[data-progress="completed"] .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-description-color
+  );
+}
+
+/* Current State (Progressing) */
+.root .stepIcon[data-progress] {
+  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 .step[data-progress="progress"] .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-label-color
+  );
+}
+
+.root .step[data-progress="progress"] .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-description-color
+  );
+}
+
+/* Upcoming State (Pending Labels) */
+.root .step[data-progress="pending"] .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-label-color
+  );
+}
+
+.root .step[data-progress="pending"] .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[data-active] {
+  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[data-active] {
+  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,17 +1,148 @@
+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: {
+    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 },
+    },
+  },
 };
 
 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",
+  },
 };

package/src/components/Stepper/Stepper.tsx

@@ -1,7 +1,70 @@
-import React from "react";
+import React, { forwardRef } from "react";
+import {
+  Stepper as MantineStepper,
+  type StepperProps as MantineStepperProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Stepper.module.css";
 
-export type StepperProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaStepperProps
+  extends Omit<
+    MantineStepperProps,
+    "size" | "color" | "radius" | "iconSize" | "contentPadding"
+  > {
+  size?: "small" | "large";
+}
 
-export const Stepper: React.FC<StepperProps> = (props) => {
-  return <div {...props}>Stepper</div>;
-};
+export type StepperProps = RecursicaOverStyled<RecursicaStepperProps>;
+
+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 (
+      <MantineStepper
+        ref={ref}
+        orientation={orientation}
+        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}
+        classNames={{
+          steps: styles.steps,
+          step: styles.step,
+          stepIcon: styles.stepIcon,
+          stepCompletedIcon: styles.stepCompletedIcon,
+          stepBody: styles.stepBody,
+          stepLabel: styles.stepLabel,
+          stepDescription: styles.stepDescription,
+          separator: styles.separator,
+          verticalSeparator: styles.verticalSeparator,
+          content: styles.content,
+        }}
+        {...(sanitizedProps as MantineStepperProps)}
+      />
+    );
+  },
+);
+
+// We need to re-export the static components Step and Completed
+export const Stepper: typeof _Stepper & {
+  Step: typeof MantineStepper.Step;
+  Completed: typeof MantineStepper.Completed;
+} = Object.assign(_Stepper, {
+  Step: MantineStepper.Step,
+  Completed: MantineStepper.Completed,
+});
+
+_Stepper.displayName = "Stepper";