@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,404 @@
+/* 
+  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-color
+  );
+  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-color
+  );
+  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-completed] .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_completed-label-color
+  );
+}
+
+.root .step[data-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-color
+  );
+  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] .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-label-color
+  );
+}
+
+.root .step[data-progress] .stepDescription {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_current-description-color
+  );
+}
+
+/* Upcoming State (Pending Labels) */
+.root .step:not([data-completed]):not([data-progress]) .stepLabel {
+  color: var(
+    --recursica_ui-kit_components_stepper_properties_colors_upcoming-label-color
+  );
+}
+
+.root .step:not([data-completed]):not([data-progress]) .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

@@ -0,0 +1,148 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stepper } from "./Stepper";
+import { Button } from "../Button/Button";
+import { Group } from "../Group/Group";
+import { Flex } from "../Flex/Flex";
+
+const meta: Meta<typeof 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: (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.test.tsx

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

package/src/components/Stepper/Stepper.tsx

@@ -0,0 +1,93 @@
+import React, { forwardRef } from "react";
+import {
+  Stepper as MantineStepper,
+  type StepperProps as MantineStepperProps,
+  type StepperStepProps as MantineStepperStepProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Stepper.module.css";
+
+import { type RecursicaStepperProps } from "@recursica/adapter-common";
+
+export interface RecursicaStepperPropsExtended
+  extends Omit<MantineStepperProps, "size">,
+    RecursicaStepperProps {}
+
+export type StepperProps = RecursicaOverStyled<RecursicaStepperPropsExtended>;
+
+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);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const mergedClassNames = mergeClassNames(
+      {
+        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,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    return (
+      <MantineStepper
+        ref={ref}
+        {...(sanitizedProps as MantineStepperProps)}
+        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={mergedClassNames}
+      />
+    );
+  },
+);
+
+export type StepperStepProps = RecursicaOverStyled<MantineStepperStepProps>;
+
+const _StepperStep = forwardRef<HTMLButtonElement, StepperStepProps>(
+  function StepperStep({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineStepper.Step
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineStepperStepProps)}
+      />
+    );
+  },
+);
+_StepperStep.displayName = "Stepper.Step";
+
+// We need to re-export the static components Step and Completed
+export const Stepper: typeof _Stepper & {
+  Step: typeof _StepperStep;
+  Completed: typeof MantineStepper.Completed;
+} = Object.assign(_Stepper, {
+  Step: _StepperStep,
+  // Stepper.Completed only accepts `children` — no styling props to strip,
+  // so re-exporting Mantine's implementation directly is not a gap.
+  Completed: MantineStepper.Completed,
+});
+
+_Stepper.displayName = "Stepper";

package/src/components/Stepper/USAGE.md

@@ -0,0 +1,41 @@
+# Stepper - Usage Guide
+
+This document describes how to integrate and use the `Stepper` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stepper } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stepper } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Stepper active={1}>
+      <Stepper.Step label="First step" description="Create account" />
+      <Stepper.Step label="Second step" description="Verify email" />
+    </Stepper>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.