@nimbus-ds/stepper 1.0.0

package/src/stepper.docs.json

@@ -0,0 +1,68 @@
+{
+  "id": "stepper",
+  "name": "Stepper",
+  "totalProps": 4,
+  "packageName": "@nimbus-ds/stepper",
+  "version": "0.0.0",
+  "docLink": "https://nimbus.nuvemshop.com.br/documentation/composite-components/stepper",
+  "props": [
+    {
+      "description": "The currently active step (0-based index).\nSteps before this will be marked as completed.",
+      "type": "number",
+      "title": "activeStep",
+      "required": true
+    },
+    {
+      "description": "The content of the stepper (StepperItem components).\nTotal steps will be calculated automatically based on the number of children.",
+      "type": "React.ReactNode",
+      "title": "children",
+      "required": true
+    },
+    {
+      "description": "The currently selected step (0-based index).\nThis step will be visually highlighted to show user selection.",
+      "type": "number",
+      "title": "selectedStep",
+      "required": true
+    },
+    {
+      "description": "Callback called when a step is selected.\nReceives the step number (0-based index) as parameter.",
+      "type": "object",
+      "additionalProperties": false,
+      "propertyOrder": [],
+      "title": "onSelectStep",
+      "required": true
+    }
+  ],
+  "subComponents": [
+    {
+      "name": "Stepper.Item",
+      "totalProps": 2,
+      "props": [
+        {
+          "description": "The step number (0-based index) for this item.\nThis is automatically assigned by the parent Stepper component.",
+          "type": "number",
+          "title": "step",
+          "required": true
+        },
+        {
+          "description": "The label text to display for this step",
+          "type": "string",
+          "title": "label",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "Stepper.Card",
+      "totalProps": 1,
+      "props": [
+        {
+          "description": "The content to be rendered inside the card container",
+          "type": "React.ReactNode",
+          "title": "children",
+          "required": true
+        }
+      ]
+    }
+  ]
+}

package/src/stepper.spec.tsx

@@ -0,0 +1,344 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+
+import { Stepper } from "./Stepper";
+import {
+  BaseStepperProperties,
+  ControlledStepperProperties,
+} from "./stepper.types";
+
+const makeUncontrolledSut = (props: BaseStepperProperties) => {
+  render(<Stepper {...props} data-testid="stepper-element" />);
+};
+
+const makeControlledSut = (props: ControlledStepperProperties) => {
+  render(<Stepper {...props} data-testid="stepper-element" />);
+};
+
+describe("GIVEN <Stepper />", () => {
+  describe("WHEN rendered in uncontrolled mode", () => {
+    it("THEN should correctly render the stepper container", () => {
+      makeUncontrolledSut({
+        activeStep: 2,
+        children: [
+          <Stepper.Item key="1" label="First step" />,
+          <Stepper.Item key="2" label="Second step" />,
+          <Stepper.Item key="3" label="Third step" />,
+        ],
+      });
+
+      expect(screen.getByTestId("stepper-element")).toBeDefined();
+      expect(screen.getByText("First step")).toBeDefined();
+      expect(screen.getByText("Second step")).toBeDefined();
+      expect(screen.getByText("Third step")).toBeDefined();
+    });
+
+    it("THEN should correctly set aria attributes", () => {
+      makeUncontrolledSut({
+        activeStep: 1,
+        children: [
+          <Stepper.Item key="1" label="Step 1" />,
+          <Stepper.Item key="2" label="Step 2" />,
+          <Stepper.Item key="3" label="Step 3" />,
+        ],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("role")).toBe("progressbar");
+      expect(stepper.getAttribute("aria-valuenow")).toBe("2");
+      expect(stepper.getAttribute("aria-valuemin")).toBe("1");
+      expect(stepper.getAttribute("aria-valuemax")).toBe("3");
+      expect(stepper.getAttribute("aria-label")).toBe("Multi-step process: Step 2 of 3");
+    });
+
+    it("THEN should render with single step", () => {
+      makeUncontrolledSut({
+        activeStep: 0,
+        children: [<Stepper.Item key="1" label="Only step" />],
+      });
+
+      expect(screen.getByText("Only step")).toBeDefined();
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuemax")).toBe("1");
+    });
+
+    it("THEN should handle activeStep 0", () => {
+      makeUncontrolledSut({
+        activeStep: 0,
+        children: [
+          <Stepper.Item key="1" label="Started step" />,
+          <Stepper.Item key="2" label="Pending step" />,
+        ],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuenow")).toBe("1");
+      expect(stepper.getAttribute("aria-label")).toBe("Multi-step process: Step 1 of 2");
+    });
+
+    it("THEN should handle maximum activeStep", () => {
+      makeUncontrolledSut({
+        activeStep: 2,
+        children: [
+          <Stepper.Item key="1" label="Completed" />,
+          <Stepper.Item key="2" label="Completed" />,
+          <Stepper.Item key="3" label="Started" />,
+        ],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuenow")).toBe("3");
+      expect(stepper.getAttribute("aria-valuemax")).toBe("3");
+    });
+
+    it("THEN should apply additional props to container", () => {
+      makeUncontrolledSut({
+        activeStep: 0,
+        children: [<Stepper.Item key="1" label="Step" />],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper).toHaveAttribute("role", "progressbar");
+      expect(stepper).toHaveAttribute("aria-valuenow", "1");
+      expect(stepper).toHaveAttribute("aria-valuemax", "1");
+    });
+
+    it("THEN should update internal state when activeStep changes", () => {
+      const { rerender } = render(
+        <Stepper activeStep={0} data-testid="stepper-element">
+          <Stepper.Item key="1" label="Step 1" />
+          <Stepper.Item key="2" label="Step 2" />
+        </Stepper>
+      );
+
+      let stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuenow")).toBe("1");
+
+      rerender(
+        <Stepper activeStep={1} data-testid="stepper-element">
+          <Stepper.Item key="1" label="Step 1" />
+          <Stepper.Item key="2" label="Step 2" />
+        </Stepper>
+      );
+
+      stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuenow")).toBe("2");
+    });
+
+    it("THEN should handle non-React element children gracefully", () => {
+      makeUncontrolledSut({
+        activeStep: 0,
+        children: [
+          "text node",
+          <Stepper.Item key="1" label="Valid step" />,
+          null,
+          <Stepper.Item key="2" label="Another step" />,
+        ],
+      });
+
+      expect(screen.getByText("Valid step")).toBeDefined();
+      expect(screen.getByText("Another step")).toBeDefined();
+    });
+  });
+
+  describe("WHEN rendered in controlled mode", () => {
+    const mockOnSelectStep = jest.fn();
+
+    beforeEach(() => {
+      mockOnSelectStep.mockClear();
+    });
+
+    it("THEN should correctly render with controlled state", () => {
+      makeControlledSut({
+        activeStep: 2,
+        selectedStep: 1,
+        onSelectStep: mockOnSelectStep,
+        children: [
+          <Stepper.Item key="1" label="First step" />,
+          <Stepper.Item key="2" label="Second step" />,
+          <Stepper.Item key="3" label="Third step" />,
+        ],
+      });
+
+      expect(screen.getByTestId("stepper-element")).toBeDefined();
+      expect(screen.getByText("First step")).toBeDefined();
+      expect(screen.getByText("Second step")).toBeDefined();
+      expect(screen.getByText("Third step")).toBeDefined();
+    });
+
+    it("THEN should call onSelectStep when a step is clicked", () => {
+      makeControlledSut({
+        activeStep: 2,
+        selectedStep: 1,
+        onSelectStep: mockOnSelectStep,
+        children: [
+          <Stepper.Item key="1" label="Completed step" />,
+          <Stepper.Item key="2" label="Another completed step" />,
+          <Stepper.Item key="3" label="Started step" />,
+        ],
+      });
+
+      const stepperItems = screen.getAllByRole("button");
+      fireEvent.click(stepperItems[0]);
+
+      expect(mockOnSelectStep).toHaveBeenCalledWith(0);
+    });
+
+    it("THEN should not update internal state when activeStep changes", () => {
+      const { rerender } = render(
+        <Stepper
+          activeStep={0}
+          selectedStep={0}
+          onSelectStep={mockOnSelectStep}
+          data-testid="stepper-element"
+        >
+          <Stepper.Item key="1" label="Step 1" />
+          <Stepper.Item key="2" label="Step 2" />
+        </Stepper>
+      );
+
+      rerender(
+        <Stepper
+          activeStep={1}
+          selectedStep={0}
+          onSelectStep={mockOnSelectStep}
+          data-testid="stepper-element"
+        >
+          <Stepper.Item key="1" label="Step 1" />
+          <Stepper.Item key="2" label="Step 2" />
+        </Stepper>
+      );
+
+      expect(mockOnSelectStep).not.toHaveBeenCalled();
+    });
+
+    it("THEN should filter controlled props from container", () => {
+      makeControlledSut({
+        activeStep: 0,
+        selectedStep: 0,
+        onSelectStep: mockOnSelectStep,
+        children: [<Stepper.Item key="1" label="Step" />],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper).not.toHaveAttribute("selectedStep");
+      expect(stepper).not.toHaveAttribute("onSelectStep");
+      expect(stepper).toHaveAttribute("role", "progressbar");
+    });
+
+    it("THEN should handle selectedStep equal to activeStep", () => {
+      makeControlledSut({
+        activeStep: 1,
+        selectedStep: 1,
+        onSelectStep: mockOnSelectStep,
+        children: [
+          <Stepper.Item key="1" label="Completed" />,
+          <Stepper.Item key="2" label="Selected started" />,
+        ],
+      });
+
+      const stepperItems = screen.getAllByRole("button");
+      fireEvent.click(stepperItems[1]);
+
+      expect(mockOnSelectStep).not.toHaveBeenCalled();
+    });
+
+    it("THEN should handle selectedStep beyond activeStep", () => {
+      makeControlledSut({
+        activeStep: 1,
+        selectedStep: 2,
+        onSelectStep: mockOnSelectStep,
+        children: [
+          <Stepper.Item key="1" label="Completed" />,
+          <Stepper.Item key="2" label="Started" />,
+          <Stepper.Item key="3" label="Selected pending" />,
+        ],
+      });
+
+      const stepperItems = screen.getAllByRole("button");
+      expect(stepperItems).toHaveLength(3);
+    });
+  });
+
+  describe("WHEN step states are rendered", () => {
+    it("THEN should show step numbers for started and pending steps", () => {
+      makeUncontrolledSut({
+        activeStep: 1,
+        children: [
+          <Stepper.Item key="1" label="Completed step" />,
+          <Stepper.Item key="2" label="Current step" />,
+          <Stepper.Item key="3" label="Pending step" />,
+        ],
+      });
+
+      expect(screen.getByText("2")).toBeDefined();
+      expect(screen.getByText("3")).toBeDefined();
+    });
+
+    it("THEN should show completed steps with check icons", () => {
+      makeUncontrolledSut({
+        activeStep: 2,
+        children: [
+          <Stepper.Item key="1" label="First completed" />,
+          <Stepper.Item key="2" label="Second completed" />,
+          <Stepper.Item key="3" label="Current step" />,
+        ],
+      });
+
+      expect(screen.queryByText("1")).toBeNull();
+      expect(screen.queryByText("2")).toBeNull();
+      expect(screen.getByText("3")).toBeDefined();
+    });
+  });
+
+  describe("WHEN Stepper has static properties", () => {
+    it("THEN should have correct displayName", () => {
+      expect(Stepper.displayName).toBe("Stepper");
+    });
+
+    it("THEN should have Item component with displayName", () => {
+      expect(Stepper.Item).toBeDefined();
+      expect(Stepper.Item.displayName).toBe("Stepper.Item");
+    });
+
+    it("THEN should have Card component with displayName", () => {
+      expect(Stepper.Card).toBeDefined();
+      expect(Stepper.Card.displayName).toBe("Stepper.Card");
+    });
+  });
+
+  describe("WHEN rendered with empty children", () => {
+    it("THEN should handle empty children array", () => {
+      makeUncontrolledSut({
+        activeStep: 0,
+        children: [],
+      });
+
+      const stepper = screen.getByTestId("stepper-element");
+      expect(stepper.getAttribute("aria-valuemax")).toBe("0");
+    });
+  });
+
+  describe("WHEN steps are automatically numbered", () => {
+    it("THEN should assign correct step indices to children", () => {
+      const mockOnSelect = jest.fn();
+      render(
+        <Stepper
+          activeStep={3}
+          selectedStep={0}
+          onSelectStep={mockOnSelect}
+          data-testid="stepper-element"
+        >
+          <Stepper.Item key="1" label="Step 1" />
+          <Stepper.Item key="2" label="Step 2" />
+          <Stepper.Item key="3" label="Step 3" />
+        </Stepper>
+      );
+
+      const buttons = screen.getAllByRole("button");
+      fireEvent.click(buttons[1]);
+
+      expect(mockOnSelect).toHaveBeenCalledWith(1);
+    });
+  });
+});

package/src/stepper.stories.tsx

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React, { useState } from "react";
+
+import { Button } from "@nimbus-ds/button";
+import { Box } from "@nimbus-ds/box";
+import { Text } from "@nimbus-ds/text";
+import { Stepper } from "./Stepper";
+
+const meta: Meta<typeof Stepper> = {
+  title: "Composite/Stepper",
+  component: Stepper,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A stepper component for guiding users through multi-step processes.",
+      },
+    },
+  },
+  argTypes: {
+    activeStep: {
+      control: { type: "number", min: 0, max: 4 },
+      description: "The currently active step (0-based index)",
+    },
+    selectedStep: {
+      control: { type: "number", min: 0, max: 4 },
+      description: "The currently selected step (0-based index)",
+    },
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Stepper>;
+
+const labels = [
+  "Select audience",
+  "Create content",
+  "Define budget",
+  "Review",
+  "Publish",
+];
+
+export const Controlled: Story = {
+  render: () => {
+    const [selected, setSelected] = useState(0);
+    const [activeStep, setActiveStep] = useState(0);
+
+    return (
+      <Box display="flex" flexDirection="column" gap="3">
+        <Text>Selected step: {selected + 1}</Text>
+        <Stepper
+          activeStep={activeStep}
+          selectedStep={selected}
+          onSelectStep={(step: number) => setSelected(step)}
+          justifyContent="flex-start"
+        >
+          {labels.map((label) => (
+            <Stepper.Item key={label} label={label} />
+          ))}
+        </Stepper>
+        <Button
+          onClick={() => {
+            setActiveStep(activeStep + 1);
+            setSelected(activeStep + 1);
+          }}
+          disabled={activeStep === labels.length - 1}
+        >
+          Next
+        </Button>
+      </Box>
+    );
+  },
+};
+
+export const Uncontrolled: Story = {
+  render: () => {
+    const [activeStep, setActiveStep] = useState(0);
+
+    return (
+      <Box display="flex" flexDirection="column" gap="3">
+        <Stepper activeStep={activeStep} justifyContent="flex-start">
+          {labels.map((label) => (
+            <Stepper.Item key={label} label={label} />
+          ))}
+        </Stepper>
+        <Button
+          onClick={() => setActiveStep(activeStep + 1)}
+          disabled={activeStep === labels.length - 1}
+        >
+          Next
+        </Button>
+      </Box>
+    );
+  },
+};
+
+export const WithCard: Story = {
+  render: () => (
+    <Stepper.Card>
+      <Stepper activeStep={2}>
+        <Stepper.Item label="Setup" />
+        <Stepper.Item label="Configuration" />
+        <Stepper.Item label="Review" />
+        <Stepper.Item label="Deploy" />
+      </Stepper>
+    </Stepper.Card>
+  ),
+};
+
+/**
+ * For mobile, we don't display the labels, only the icons
+ */
+export const Mobile: Story = {
+  render: () => {
+    const [activeStep, setActiveStep] = useState(0);
+    const [selected, setSelected] = useState(0);
+
+    return (
+      <Box display="flex" flexDirection="column" gap="3">
+        <Text>Step {selected + 1}: Description</Text>
+        <Stepper
+          activeStep={activeStep}
+          selectedStep={selected}
+          onSelectStep={setSelected}
+          justifyContent="flex-start"
+        >
+          {labels.map((label) => (
+            <Stepper.Item key={label} />
+          ))}
+        </Stepper>
+        <Button
+          onClick={() => {
+            setActiveStep(activeStep + 1);
+            setSelected(activeStep + 1);
+          }}
+          disabled={activeStep === labels.length - 1}
+        >
+          Next
+        </Button>
+      </Box>
+    );
+  },
+};

package/src/stepper.types.ts

@@ -0,0 +1,48 @@
+import React, { ReactNode } from "react";
+import { BoxProps } from "@nimbus-ds/box";
+import { StepperItemProps } from "./components/StepperItem";
+import { StepperCardProps } from "./components/StepperCard";
+
+export interface StepperComponents {
+  Item: React.FC<Omit<StepperItemProps, "step">>;
+  Card: React.FC<StepperCardProps>;
+}
+
+export interface BaseStepperProperties {
+  /**
+   * The currently active step (0-based index).
+   * Steps before this will be marked as completed.
+   */
+  activeStep: number;
+  /**
+   * The content of the stepper (StepperItem components).
+   * Total steps will be calculated automatically based on the number of children.
+   * @TJS-type React.ReactNode
+   */
+  children: ReactNode;
+}
+
+export interface ControlledStepperProperties extends BaseStepperProperties {
+  /**
+   * The currently selected step (0-based index).
+   * This step will be visually highlighted to show user selection.
+   */
+  selectedStep: number;
+  /**
+   * Callback called when a step is selected.
+   * Receives the step number (0-based index) as parameter.
+   */
+  onSelectStep: (step: number) => void;
+}
+
+/**
+ * Props for the Stepper component, supporting both controlled and uncontrolled modes
+ */
+export type StepperProps = (BaseStepperProperties | ControlledStepperProperties) & Omit<BoxProps, "display" | "flexWrap" | "gap">;
+
+// For docs purposes, we need to merge the two types
+export type StepperProperties = BaseStepperProperties & ControlledStepperProperties;
+
+// Re-export types from components for convenience
+export type { StepperItemProps, StepState } from "./components/StepperItem";
+export type { StepperCardProps } from "./components/StepperCard"; 

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../../../tsconfig.json",
+  "include": ["src/**/*"]
+} 

package/webpack.config.ts

@@ -0,0 +1,11 @@
+import path from "path";
+import { configuration } from "@nimbus-ds/webpack/src";
+
+const config = {
+  output: {
+    path: path.resolve(__dirname, "dist"),
+    library: "@nimbus-ds/stepper",
+  },
+};
+
+export default () => configuration.getConfiguration(config);