@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.14

package/src/components/stepper/stepper.stories.tsx

@@ -1,102 +1,464 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { RectangleEllipsis, Settings, User } from "lucide-react";
 import {
-  Button,
-  Input,
+  CheckIcon,
+  CreditCardIcon,
+  LoaderCircleIcon,
+  PackageCheckIcon,
+  TruckIcon,
+  UserIcon,
+} from "lucide-react";
+import { type ComponentType, useState } from "react";
+
+import { useStep } from "../../hooks";
+import { Button } from "../button/button";
+import { Field } from "../field/field";
+import { Input } from "../input/input";
+import { toast } from "../toast/toast";
+import {
   Stepper,
-  StepperContainer,
   StepperContent,
-  StepperList,
+  StepperDescription,
+  StepperIndicator,
+  StepperItem,
+  StepperNav,
+  StepperPanel,
+  StepperRoot,
+  StepperSeparator,
+  StepperTitle,
   StepperTrigger,
-} from "../../components";
-import { useStep } from "../../hooks";
+} from "./stepper";
 
+/**
+ * Accessible stepper that highlights progress across an ordered list of steps.
+ * Use the composite `Stepper` for items-driven setups, or compose the primitives
+ * (`StepperRoot`, `StepperNav`, `StepperItem`, `StepperTrigger`, `StepperIndicator`,
+ * `StepperSeparator`, `StepperTitle`, `StepperDescription`, `StepperPanel`,
+ * `StepperContent`) for full control over markup and layout.
+ *
+ * Key behaviors:
+ * - Steps are **1-indexed**. `defaultValue` / `value` is the active step number,
+ *   matching the `step` prop of `StepperItem`. Items with `step < activeStep`
+ *   render as `completed`; the equal one as `active`; the rest as `inactive`.
+ * - Pass `loading` on an item to render the active step in a `loading` state
+ *   (sets `data-loading` on item, trigger, and indicator).
+ * - The composite renders `StepperPanel` automatically when any item carries
+ *   `content`. For custom panel layouts, drop the composite and use the
+ *   primitives directly (see the `Primitive` story).
+ * - `indicators` on the root acts as a global override map: any matching
+ *   `state` (active / completed / inactive / loading) replaces the indicator's
+ *   children. Useful to swap numbers for icons across the whole stepper.
+ * - `triggerMode` on the root controls which triggers respond to click and
+ *   keyboard activation. `"both"` (default) is free navigation; `"backward-only"`
+ *   blocks jumping ahead (typical wizard); `"forward-only"` locks out reviewing
+ *   past steps; `"none"` makes the stepper display-only. Non-navigable triggers
+ *   get `aria-disabled="true"`, lose pointer cursor, and are skipped by Arrow
+ *   keys.
+ * - Keyboard nav (Arrow / Home / End) is wired on `StepperTrigger` and skips
+ *   both `disabled` and `aria-disabled` triggers.
+ *
+ * Reference: [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
+ */
 const meta: Meta<typeof Stepper> = {
-  title: "Data display/Stepper",
+  title: "Components/Stepper",
   component: Stepper,
-  args: {},
+  parameters: {
+    layout: "centered",
+  },
+  subcomponents: {
+    StepperRoot: StepperRoot as ComponentType<unknown>,
+    StepperNav: StepperNav as ComponentType<unknown>,
+    StepperItem: StepperItem as ComponentType<unknown>,
+    StepperTrigger: StepperTrigger as ComponentType<unknown>,
+    StepperIndicator: StepperIndicator as ComponentType<unknown>,
+    StepperSeparator: StepperSeparator as ComponentType<unknown>,
+    StepperTitle: StepperTitle as ComponentType<unknown>,
+    StepperDescription: StepperDescription as ComponentType<unknown>,
+    StepperPanel: StepperPanel as ComponentType<unknown>,
+    StepperContent: StepperContent as ComponentType<unknown>,
+  },
+  args: {
+    defaultValue: 2,
+    items: [
+      { title: "Account", description: "Your details" },
+      { title: "Shipping", description: "Where to send it" },
+      { title: "Payment", description: "How to pay" },
+      { title: "Review", description: "Confirm order" },
+    ],
+  },
+  argTypes: {
+    items: { control: false },
+    onValueChange: { control: false },
+    classNames: { control: false },
+  },
+  tags: ["beta"],
 };
 
 export default meta;
 type Story = StoryObj<typeof Stepper>;
 
-const AccountStep = () => {
-  return (
-    <>
-      <Input name="name" />
-      <Input name="lastname" />
-    </>
-  );
-};
-
-const PasswordStep = () => {
-  return (
-    <>
-      <Input name="password" type="password" />
-      <Input name="confirmation" type="password" />
-    </>
-  );
-};
-
-const FileStep = () => {
-  return (
-    <>
-      <Input name="file" type="file" />
-    </>
-  );
-};
-
-const steps = [
-  { title: "Cuenta", content: <AccountStep />, indicator: <User /> },
-  { title: "Configuracón", content: <FileStep />, indicator: <Settings /> },
-  {
-    title: "Contraseña",
-    content: <PasswordStep />,
-    indicator: <RectangleEllipsis />,
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
+
+/**
+ * `className` estila el root del Stepper. `classNames` expone los slots
+ * `nav`, `item`, `trigger`, `indicator`, `title`, `description`, `separator`,
+ * `panel` y `content` para personalizar cada parte interna.
+ */
+export const WithClassNames: Story = {
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper
+        {...args}
+        classNames={{
+          indicator: "size-8",
+          title: "text-primary",
+          separator: "h-1",
+        }}
+      />
+    </div>
+  ),
+};
+
+/**
+ * Vertical orientation places the nav as a column with the panel rendered
+ * side-by-side. Pass `content` on each item so the active step's panel shows
+ * up next to the nav.
+ */
+export const Vertical: Story = {
+  args: {
+    orientation: "vertical",
+    defaultValue: 2,
+    indicators: { completed: <CheckIcon className="size-3.5" /> },
+    items: [
+      {
+        title: "Account",
+        description: "Your details",
+        content: (
+          <div className="rounded-lg border p-4">
+            <p className="font-medium text-sm">Account information</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Name, email, and password to access your workspace.
+            </p>
+          </div>
+        ),
+      },
+      {
+        title: "Shipping",
+        description: "Where to send it",
+        content: (
+          <div className="rounded-lg border p-4">
+            <p className="font-medium text-sm">Shipping address</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Pick an existing address or add a new one for this order.
+            </p>
+          </div>
+        ),
+      },
+      {
+        title: "Payment",
+        description: "How to pay",
+        content: (
+          <div className="rounded-lg border p-4">
+            <p className="font-medium text-sm">Payment method</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Use a saved card or add a new one before checkout.
+            </p>
+          </div>
+        ),
+      },
+      {
+        title: "Review",
+        description: "Confirm order",
+        content: (
+          <div className="rounded-lg border p-4">
+            <p className="font-medium text-sm">Review your order</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Double-check the details and place the order.
+            </p>
+          </div>
+        ),
+      },
+    ],
   },
-];
+  render: (args) => (
+    <div className="w-[720px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
 
-export const Default: Story = {
-  render: () => {
-    return <Stepper items={steps} />;
+/**
+ * Per-item `indicator` replaces the default step number. Pair with icons to
+ * communicate intent at a glance.
+ */
+export const WithIcons: Story = {
+  args: {
+    defaultValue: 3,
+    items: [
+      { title: "Account", indicator: <UserIcon className="size-3.5" /> },
+      { title: "Shipping", indicator: <TruckIcon className="size-3.5" /> },
+      { title: "Payment", indicator: <CreditCardIcon className="size-3.5" /> },
+      { title: "Done", indicator: <PackageCheckIcon className="size-3.5" /> },
+    ],
   },
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
 };
 
+/**
+ * `indicators` on the root replaces the children of every indicator whose
+ * `state` matches a key in the map. Use it to apply a consistent icon set
+ * (✓ for completed, spinner for loading) without touching each item.
+ */
+export const GlobalIndicators: Story = {
+  args: {
+    defaultValue: 3,
+    indicators: {
+      completed: <CheckIcon className="size-3.5" />,
+      loading: <LoaderCircleIcon className="size-3.5 animate-spin" />,
+    },
+    items: [
+      { title: "Account" },
+      { title: "Shipping" },
+      { title: "Payment" },
+      { title: "Review" },
+    ],
+  },
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
+
+/**
+ * `loading: true` on an item only takes effect when that item is the active
+ * step — it switches the item from `active` to `loading` and sets
+ * `data-loading` on the trigger and indicator. Combine with the `loading`
+ * entry in `indicators` to render a spinner.
+ */
+export const Loading: Story = {
+  args: {
+    defaultValue: 2,
+    indicators: {
+      loading: <LoaderCircleIcon className="size-3.5 animate-spin" />,
+      completed: <CheckIcon className="size-3.5" />,
+    },
+    items: [
+      { title: "Account", description: "Saved" },
+      { title: "Shipping", description: "Validating address…", loading: true },
+      { title: "Payment", description: "Pending" },
+      { title: "Review", description: "Pending" },
+    ],
+  },
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
+
+/**
+ * `disabled: true` on an item blocks click and keyboard activation. Arrow-key
+ * navigation skips disabled triggers and lands on the next enabled one.
+ */
 export const Disabled: Story = {
+  args: {
+    defaultValue: 1,
+    items: [
+      { title: "Account", description: "Available" },
+      { title: "Shipping", description: "Locked", disabled: true },
+      { title: "Payment", description: "Locked", disabled: true },
+      { title: "Review", description: "Locked", disabled: true },
+    ],
+  },
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
+
+/**
+ * `triggerMode` is a shortcut for restricting which triggers respond to click
+ * and keyboard activation, without having to set `disabled` on individual
+ * items.
+ *
+ * - `"both"` (default) — every trigger is clickable.
+ * - `"backward-only"` — only past + current steps. The typical wizard guard:
+ *   the user can revisit but cannot jump ahead.
+ * - `"forward-only"` — only current + upcoming steps. Past steps lock out,
+ *   useful for irreversible flows.
+ * - `"none"` — nothing is clickable. The stepper becomes a display-only
+ *   progress indicator (e.g. an order tracker).
+ *
+ * Composes with `disabled` per item: both layers apply independently.
+ */
+export const TriggerMode: Story = {
   render: () => {
+    const variants: {
+      label: string;
+      value: "both" | "backward-only" | "forward-only" | "none";
+    }[] = [
+      { label: "both (default)", value: "both" },
+      { label: "backward-only", value: "backward-only" },
+      { label: "forward-only", value: "forward-only" },
+      { label: "none (read-only)", value: "none" },
+    ];
+    const items = [
+      { title: "Account" },
+      { title: "Shipping" },
+      { title: "Payment" },
+      { title: "Review" },
+    ];
+
     return (
-      <Stepper
-        items={[
-          { title: "Cuenta", content: <AccountStep /> },
-          { title: "Configuracón", content: <FileStep /> },
-          { title: "Contraseña", content: <PasswordStep />, disabled: true },
-        ]}
-      />
+      <div className="w-[840px] space-y-8">
+        {variants.map(({ label, value }) => (
+          <div key={value} className="space-y-2">
+            <p className="font-medium text-muted-foreground text-xs uppercase tracking-wide">
+              {label}
+            </p>
+            <Stepper
+              defaultValue={2}
+              triggerMode={value}
+              indicators={{ completed: <CheckIcon className="size-3.5" /> }}
+              items={items}
+            />
+          </div>
+        ))}
+      </div>
     );
   },
 };
 
 /**
- * Se puede utilizar el hook `useStep` para facilitar el manejo de estado y validaciones
+ * Give every item a `content` and the composite wires the `StepperPanel`
+ * for you: one `StepperContent` per step, mount/unmount + ARIA on each
+ * change, no external state. Use this when the contents are static and
+ * you don't need controlled navigation.
+ *
+ * Rule of thumb: **all items have `content`, or none do**. Mixing leaves
+ * an empty panel on the steps that lack content.
+ *
+ * For custom panel layouts (animations, conditional rendering, async
+ * loading), skip `content` and use the primitives directly — see the
+ * `Primitive`, `Wizard`, and `Controlled` stories.
  */
-export const Steps: Story = {
+export const WithPanels: Story = {
+  args: {
+    defaultValue: 1,
+    indicators: { completed: <CheckIcon className="size-3.5" /> },
+    items: [
+      {
+        title: "Account",
+        description: "Your details",
+        content: (
+          <div className="mt-6 rounded-lg border p-4">
+            <p className="font-medium text-sm">Account details</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Add your name and email to continue.
+            </p>
+          </div>
+        ),
+      },
+      {
+        title: "Shipping",
+        description: "Where to send it",
+        content: (
+          <div className="mt-6 rounded-lg border p-4">
+            <p className="font-medium text-sm">Shipping address</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Pick a saved address or add a new one.
+            </p>
+          </div>
+        ),
+      },
+      {
+        title: "Payment",
+        description: "How to pay",
+        content: (
+          <div className="mt-6 rounded-lg border p-4">
+            <p className="font-medium text-sm">Payment method</p>
+            <p className="mt-1 text-muted-foreground text-sm">
+              Add a credit card or use a saved one.
+            </p>
+          </div>
+        ),
+      },
+    ],
+  },
+  render: (args) => (
+    <div className="w-[840px]">
+      <Stepper {...args} />
+    </div>
+  ),
+};
+
+const wizardSteps = [
+  { value: "account", title: "Account", description: "Your details" },
+  { value: "shipping", title: "Shipping", description: "Where to send it" },
+  { value: "payment", title: "Payment", description: "How to pay" },
+  { value: "review", title: "Review", description: "Confirm order" },
+];
+
+/**
+ * Linear wizard driven by `useStep`. Note the index translation: `useStep` is
+ * **0-indexed**, the stepper is **1-indexed**. Feed it `currentStepIndex + 1`
+ * and bridge `onValueChange` back with `goTo(value - 1)`.
+ *
+ * ```tsx
+ * const { currentStepIndex, goTo, next, back } = useStep(steps);
+ * <Stepper
+ *   value={currentStepIndex + 1}
+ *   onValueChange={(value) => goTo(value - 1)}
+ *   items={steps}
+ * />
+ * ```
+ */
+export const Wizard: Story = {
   render: () => {
-    const { currentStepIndex, isFirstStep, isLastStep, next, back, goTo } =
-      useStep(steps);
+    const {
+      currentStepIndex,
+      step,
+      isFirstStep,
+      isLastStep,
+      next,
+      back,
+      goTo,
+    } = useStep(wizardSteps);
 
     return (
-      <div>
+      <div className="w-[840px] space-y-6">
         <Stepper
-          items={steps}
-          current={currentStepIndex}
-          onChange={(step: number) => goTo(step)}
+          value={currentStepIndex + 1}
+          onValueChange={(value) => goTo(value - 1)}
+          indicators={{ completed: <CheckIcon className="size-3.5" /> }}
+          items={wizardSteps.map((s) => ({
+            title: s.title,
+            description: s.description,
+          }))}
         />
-        <div className="flex justify-end gap-x-2 mt-2">
-          <Button variant="ghost" disabled={isFirstStep} onClick={back}>
-            Prev
+        <div className="rounded-lg border p-6">
+          <p className="font-medium text-sm">{step.title}</p>
+          <p className="mt-1 text-muted-foreground text-sm">
+            {step.description}
+          </p>
+        </div>
+        <div className="flex justify-between">
+          <Button variant="outline" disabled={isFirstStep} onClick={back}>
+            Back
           </Button>
           <Button disabled={isLastStep} onClick={next}>
-            Next
+            {isLastStep ? "Finish" : "Next"}
           </Button>
         </div>
       </div>
@@ -104,27 +466,349 @@ export const Steps: Story = {
   },
 };
 
-export const StepperWithPrimitives: Story = {
+/**
+ * Controlled mode — `value` + `onValueChange` drive the active step. Steps are
+ * 1-indexed.
+ *
+ * When the user reaches the last step the `Go to` buttons hide and a `Finish`
+ * action takes over. Clicking it sets `value` to `items.length + 1`, which
+ * pushes every item past the active threshold and flips the last one to the
+ * `completed` state.
+ */
+export const Controlled: Story = {
   render: () => {
+    const items = [
+      { title: "Account" },
+      { title: "Shipping" },
+      { title: "Payment" },
+      { title: "Review" },
+    ];
+    const [value, setValue] = useState(1);
+    const isLastStep = value === items.length;
+    const isFinished = value > items.length;
+
     return (
-      <StepperContainer>
-        <StepperList>
-          {steps?.map((item, i) => (
-            <StepperTrigger
-              key={i}
-              value={i}
-              title={item?.title}
-              indicator={item?.indicator}
-            />
-          ))}
-        </StepperList>
+      <div className="w-[840px] space-y-4">
+        <Stepper
+          value={value}
+          onValueChange={setValue}
+          indicators={{ completed: <CheckIcon className="size-3.5" /> }}
+          items={items}
+        />
+        {isFinished ? (
+          <div className="flex items-center justify-between rounded-md border bg-accent/40 px-4 py-2 text-sm">
+            <span className="inline-flex items-center gap-2 font-medium">
+              <CheckIcon className="size-4" />
+              All steps completed
+            </span>
+            <button
+              type="button"
+              onClick={() => setValue(1)}
+              className="cursor-pointer rounded-md border px-3 py-1 text-sm hover:bg-accent"
+            >
+              Reset
+            </button>
+          </div>
+        ) : isLastStep ? (
+          <div className="flex justify-end">
+            <Button onClick={() => setValue(items.length + 1)}>Finish</Button>
+          </div>
+        ) : (
+          <div className="flex gap-2">
+            {items.map((_, i) => (
+              <button
+                key={i}
+                type="button"
+                onClick={() => setValue(i + 1)}
+                className="cursor-pointer rounded-md border px-3 py-1 text-sm hover:bg-accent"
+              >
+                Go to {i + 1}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  },
+};
 
-        {steps?.map((item, i) => (
-          <StepperContent key={i} value={i}>
-            {item?.content}
-          </StepperContent>
-        ))}
-      </StepperContainer>
+type CheckoutForm = {
+  email: string;
+  name: string;
+  address: string;
+  city: string;
+  card: string;
+};
+
+const emptyForm: CheckoutForm = {
+  email: "",
+  name: "",
+  address: "",
+  city: "",
+  card: "",
+};
+
+const isEmail = (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+
+/**
+ * Multi-step form with **persistent state** across steps, **per-step validation
+ * gating**, and a simulated async submit that ends in `toast.success`.
+ *
+ * The recipe:
+ * - One `formData` state holds every field — inputs read and write to the
+ *   same object regardless of which step is active, so navigating back keeps
+ *   the previous values.
+ * - `maxReached` tracks how far the user has progressed. Items with
+ *   `step > maxReached` get `disabled: true`, which blocks both click and
+ *   keyboard nav to future steps. Visited steps stay clickable so the user
+ *   can review.
+ * - `canAdvance` derives from the current step's required fields. The Next
+ *   button is disabled until those fields are valid; the user cannot bypass
+ *   it via the stepper triggers because of the rule above.
+ * - On Finish, a fake 1.2s promise simulates the backend call. The button
+ *   shows `loading`, and on resolve a `toast.success` fires.
+ */
+export const WithValidation: Story = {
+  render: () => {
+    const [activeStep, setActiveStep] = useState(1);
+    const [maxReached, setMaxReached] = useState(1);
+    const [formData, setFormData] = useState<CheckoutForm>(emptyForm);
+    const [isFinishing, setIsFinishing] = useState(false);
+
+    const update = (field: keyof CheckoutForm) => (value: string) =>
+      setFormData((prev) => ({ ...prev, [field]: value }));
+
+    const validators = {
+      1: isEmail(formData.email) && formData.name.trim().length > 0,
+      2: formData.address.trim().length > 0 && formData.city.trim().length > 0,
+      3: formData.card.replace(/\s/g, "").length >= 12,
+    } as const;
+    const canAdvance = validators[activeStep as 1 | 2 | 3];
+
+    const handleNext = () => {
+      if (!canAdvance) return;
+      const next = activeStep + 1;
+      setActiveStep(next);
+      setMaxReached((m) => Math.max(m, next));
+    };
+
+    const handleBack = () => setActiveStep((s) => Math.max(1, s - 1));
+
+    const handleReset = () => {
+      setFormData(emptyForm);
+      setActiveStep(1);
+      setMaxReached(1);
+    };
+
+    const handleFinish = async () => {
+      if (!canAdvance) return;
+      setIsFinishing(true);
+      await new Promise((resolve) => setTimeout(resolve, 1200));
+      setIsFinishing(false);
+      setActiveStep(4);
+      setMaxReached(4);
+      toast.success("Order placed successfully");
+    };
+
+    const items = [
+      { title: "Account", description: "Your details" },
+      { title: "Shipping", description: "Where to send it" },
+      { title: "Payment", description: "How to pay" },
+    ];
+
+    const isLastStep = activeStep === items.length;
+    const isFinished = activeStep > items.length;
+
+    return (
+      <div className="w-[840px] space-y-6">
+        <Stepper
+          value={activeStep}
+          onValueChange={setActiveStep}
+          indicators={{ completed: <CheckIcon className="size-3.5" /> }}
+          items={items.map((item, i) => ({
+            ...item,
+            disabled: i + 1 > maxReached,
+          }))}
+        />
+
+        <div className="rounded-lg border p-6">
+          {activeStep === 1 && (
+            <div className="space-y-4">
+              <Field
+                label="Email"
+                required
+                error={
+                  formData.email && !isEmail(formData.email)
+                    ? "Enter a valid email address"
+                    : undefined
+                }
+              >
+                <Input
+                  value={formData.email}
+                  onChange={update("email")}
+                  placeholder="you@example.com"
+                />
+              </Field>
+              <Field label="Full name" required>
+                <Input
+                  value={formData.name}
+                  onChange={update("name")}
+                  placeholder="Jane Doe"
+                />
+              </Field>
+            </div>
+          )}
+
+          {activeStep === 2 && (
+            <div className="space-y-4">
+              <Field label="Address" required>
+                <Input
+                  value={formData.address}
+                  onChange={update("address")}
+                  placeholder="221B Baker Street"
+                />
+              </Field>
+              <Field label="City" required>
+                <Input
+                  value={formData.city}
+                  onChange={update("city")}
+                  placeholder="London"
+                />
+              </Field>
+            </div>
+          )}
+
+          {activeStep === 3 && (
+            <Field
+              label="Card number"
+              required
+              description="At least 12 digits."
+              error={
+                formData.card && formData.card.replace(/\s/g, "").length < 12
+                  ? "Card number is too short"
+                  : undefined
+              }
+            >
+              <Input
+                value={formData.card}
+                onChange={update("card")}
+                placeholder="4242 4242 4242 4242"
+                inputMode="numeric"
+              />
+            </Field>
+          )}
+
+          {isFinished && (
+            <div className="flex flex-col items-center gap-2 py-4 text-center">
+              <CheckIcon className="size-8 text-success" />
+              <p className="font-medium">All set</p>
+              <p className="text-muted-foreground text-sm">
+                We've sent a receipt to{" "}
+                <span className="font-medium text-foreground">
+                  {formData.email}
+                </span>
+                .
+              </p>
+            </div>
+          )}
+        </div>
+
+        {isFinished ? (
+          <div className="flex justify-center">
+            <Button variant="outline" onClick={handleReset}>
+              Start over
+            </Button>
+          </div>
+        ) : (
+          <div className="flex justify-between">
+            <Button
+              variant="outline"
+              onClick={handleBack}
+              disabled={activeStep === 1 || isFinishing}
+            >
+              Back
+            </Button>
+            {isLastStep ? (
+              <Button
+                onClick={handleFinish}
+                disabled={!canAdvance || isFinishing}
+                loading={isFinishing}
+              >
+                {isFinishing ? "Processing…" : "Finish"}
+              </Button>
+            ) : (
+              <Button onClick={handleNext} disabled={!canAdvance}>
+                Next
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
     );
   },
 };
+
+/**
+ * Compose the primitives directly when the items API isn't enough — custom
+ * markup between steps, dynamic indicator rendering, extra slots, etc.
+ *
+ * ```tsx
+ * <StepperRoot defaultValue={2}>
+ *   <StepperNav>
+ *     <StepperItem step={1}>
+ *       <StepperTrigger>
+ *         <StepperIndicator>1</StepperIndicator>
+ *         <StepperTitle>Account</StepperTitle>
+ *       </StepperTrigger>
+ *       <StepperSeparator />
+ *     </StepperItem>
+ *   </StepperNav>
+ *   <StepperPanel>
+ *     <StepperContent value={1}>Account form…</StepperContent>
+ *   </StepperPanel>
+ * </StepperRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <div className="w-[840px]">
+      <StepperRoot defaultValue={2}>
+        <StepperNav>
+          {[
+            { step: 1, title: "Account" },
+            { step: 2, title: "Shipping" },
+            { step: 3, title: "Payment" },
+            { step: 4, title: "Review" },
+          ].map(({ step, title }, i, arr) => (
+            <StepperItem key={step} step={step}>
+              <StepperTrigger>
+                <StepperIndicator>
+                  <CheckIcon className="hidden size-3.5 group-data-[state=completed]/step:block" />
+                  <span className="group-data-[state=completed]/step:hidden">
+                    {step}
+                  </span>
+                </StepperIndicator>
+                <div className="flex flex-col gap-0.5 text-left">
+                  <StepperTitle>{title}</StepperTitle>
+                </div>
+              </StepperTrigger>
+              {i < arr.length - 1 ? <StepperSeparator /> : null}
+            </StepperItem>
+          ))}
+        </StepperNav>
+        <StepperPanel className="mt-6">
+          {[1, 2, 3, 4].map((step) => (
+            <StepperContent key={step} value={step}>
+              <div className="rounded-lg border p-4">
+                <p className="font-medium text-sm">Step {step}</p>
+                <p className="mt-1 text-muted-foreground text-sm">
+                  Custom panel content for step {step}.
+                </p>
+              </div>
+            </StepperContent>
+          ))}
+        </StepperPanel>
+      </StepperRoot>
+    </div>
+  ),
+};