feat: add Stepper component with examples and documentation

apps/v4/content/docs/components/stepper.mdx

@@ -0,0 +1,171 @@
+---
+title: Stepper
+description: A composable stepper component for displaying progress through a sequence of steps.
+component: true
+---
+
+<ComponentPreview name="stepper-registration-flow" />
+
+## Installation
+
+<CodeTabs>
+
+<TabsList>
+  <TabsTrigger value="cli">CLI</TabsTrigger>
+  <TabsTrigger value="manual">Manual</TabsTrigger>
+</TabsList>
+<TabsContent value="cli">
+
+```bash
+npx shadcn@latest add stepper
+```
+
+</TabsContent>
+
+<TabsContent value="manual">
+
+<Steps>
+
+<Step>Install the following dependencies:</Step>
+
+```bash
+npm install lucide-react
+```
+
+<Step>Copy and paste the following code into your project.</Step>
+
+<ComponentSource name="stepper" title="components/ui/stepper.tsx" />
+
+<Step>Update the import paths to match your project setup.</Step>
+
+</Steps>
+
+</TabsContent>
+
+</CodeTabs>
+
+## Usage
+
+```tsx
+import { Stepper } from "@/components/ui/stepper"
+import { StepperItem } from "@/components/ui/stepper-item"
+```
+
+```tsx
+<Stepper currentStep={1}>
+  <StepperItem title="Step 1" description="First step description" />
+  <StepperItem title="Step 2" description="Second step description" />
+  <StepperItem title="Step 3" description="Third step description" />
+</Stepper>
+```
+
+## Examples
+
+### Basic Horizontal Stepper
+
+A simple horizontal stepper showing step progression.
+
+<ComponentPreview name="stepper-demo" />
+
+```tsx
+<Stepper currentStep={1}>
+  <StepperItem title="Account" description="Create your account" />
+  <StepperItem title="Profile" description="Complete your profile" />
+  <StepperItem title="Review" description="Verify your details" />
+</Stepper>
+```
+
+### Vertical
+
+Use the `orientation` prop to display the stepper vertically.
+
+<ComponentPreview name="stepper-vertical" />
+
+```tsx
+<Stepper currentStep={1} orientation="vertical">
+  <StepperItem title="Step 1" description="This step is completed" />
+  <StepperItem title="Step 2" description="This is the current step" />
+  <StepperItem title="Step 3" description="This step is upcoming" />
+</Stepper>
+```
+
+### With Custom Icons
+
+Pass custom icons to each step using the `icon` prop.
+
+<ComponentPreview name="stepper-with-icons" />
+
+```tsx
+import { FileText, Settings, User } from "lucide-react"
+
+<Stepper currentStep={1}>
+  <StepperItem title="Personal Info" icon={<User className="size-4" />} />
+  <StepperItem title="Documents" icon={<FileText className="size-4" />} />
+  <StepperItem title="Settings" icon={<Settings className="size-4" />} />
+</Stepper>
+```
+
+## Accessibility
+
+The Stepper component is built with accessibility in mind:
+
+- Uses `role="list"` on the container and `role="listitem"` on each step for proper semantic structure.
+- Active step is indicated with `aria-current="step"` for screen readers.
+- Step indicators use `aria-hidden="true"` since state is communicated via the parent listitem.
+- Connector lines are marked as `role="presentation"` and `aria-hidden="true"` since they are decorative.
+
+## API Reference
+
+### Stepper
+
+The root component that provides context to all child steps.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `currentStep` | `number` | Required | The current active step (0-based index). |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the stepper. |
+| `className` | `string` | - | Additional CSS classes. |
+
+### StepperItem
+
+Individual step component that renders the indicator, label, and connector.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | - | The title of the step. |
+| `description` | `string` | - | Optional description text. |
+| `icon` | `React.ReactNode` | - | Custom icon to display in the indicator. |
+| `className` | `string` | - | Additional CSS classes. |
+
+### StepIndicator
+
+Visual circular indicator component (used internally by StepperItem).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `index` | `number` | Required | The step index (0-based). |
+| `isCompleted` | `boolean` | Required | Whether this step is completed. |
+| `isActive` | `boolean` | Required | Whether this step is active. |
+| `isUpcoming` | `boolean` | Required | Whether this step is upcoming. |
+| `icon` | `React.ReactNode` | - | Custom icon to display. |
+| `title` | `string` | - | Step title for accessibility. |
+
+### StepLabel
+
+Renders the step title and description (used internally by StepperItem).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | - | The step title. |
+| `description` | `string` | - | Optional description. |
+| `isActive` | `boolean` | Required | Whether this step is active. |
+| `isCompleted` | `boolean` | Required | Whether this step is completed. |
+
+### StepConnector
+
+Connector line between steps (used internally by StepperItem).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isCompleted` | `boolean` | Required | Whether the preceding step is completed. |
+| `orientation` | `"horizontal" \| "vertical"` | Required | The orientation of the stepper. |

apps/v4/public/r/styles/new-york-v4/registry.json

@@ -688,6 +688,35 @@
       ],
       "type": "registry:ui"
     },
+    {
+      "name": "stepper",
+      "type": "registry:ui",
+      "dependencies": [
+        "lucide-react"
+      ],
+      "files": [
+        {
+          "path": "registry/new-york-v4/ui/stepper.tsx",
+          "type": "registry:ui"
+        },
+        {
+          "path": "registry/new-york-v4/ui/stepper-item.tsx",
+          "type": "registry:ui"
+        },
+        {
+          "path": "registry/new-york-v4/ui/step-indicator.tsx",
+          "type": "registry:ui"
+        },
+        {
+          "path": "registry/new-york-v4/ui/step-label.tsx",
+          "type": "registry:ui"
+        },
+        {
+          "path": "registry/new-york-v4/ui/step-connector.tsx",
+          "type": "registry:ui"
+        }
+      ]
+    },
     {
       "name": "switch",
       "dependencies": [
@@ -6946,6 +6975,63 @@
       ],
       "type": "registry:example"
     },
+    {
+      "name": "stepper-demo",
+      "type": "registry:example",
+      "registryDependencies": [
+        "stepper"
+      ],
+      "files": [
+        {
+          "path": "registry/new-york-v4/examples/stepper-demo.tsx",
+          "type": "registry:example"
+        }
+      ]
+    },
+    {
+      "name": "stepper-vertical",
+      "type": "registry:example",
+      "registryDependencies": [
+        "stepper"
+      ],
+      "files": [
+        {
+          "path": "registry/new-york-v4/examples/stepper-vertical.tsx",
+          "type": "registry:example"
+        }
+      ]
+    },
+    {
+      "name": "stepper-with-icons",
+      "type": "registry:example",
+      "registryDependencies": [
+        "stepper"
+      ],
+      "files": [
+        {
+          "path": "registry/new-york-v4/examples/stepper-with-icons.tsx",
+          "type": "registry:example"
+        }
+      ]
+    },
+    {
+      "name": "stepper-registration-flow",
+      "type": "registry:example",
+      "registryDependencies": [
+        "stepper",
+        "button",
+        "input",
+        "label",
+        "select",
+        "checkbox"
+      ],
+      "files": [
+        {
+          "path": "registry/new-york-v4/examples/stepper-registration-flow.tsx",
+          "type": "registry:example"
+        }
+      ]
+    },
     {
       "name": "switch-demo",
       "registryDependencies": [

apps/v4/public/r/styles/new-york-v4/stepper-demo.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "stepper-demo",
+  "type": "registry:example",
+  "registryDependencies": [
+    "stepper"
+  ],
+  "files": [
+    {
+      "path": "registry/new-york-v4/examples/stepper-demo.tsx",
+      "content": "\"use client\"\r\n\r\nimport { Stepper } from \"@/registry/new-york-v4/ui/stepper\"\r\nimport { StepperItem } from \"@/registry/new-york-v4/ui/stepper-item\"\r\n\r\nexport default function StepperDemo() {\r\n  return (\r\n    <div className=\"w-full max-w-xl space-y-8\">\r\n      <Stepper currentStep={1}>\r\n        <StepperItem title=\"Account\" description=\"Create your account\" />\r\n        <StepperItem title=\"Profile\" description=\"Complete your profile\" />\r\n        <StepperItem title=\"Review\" description=\"Verify your details\" />\r\n      </Stepper>\r\n    </div>\r\n  )\r\n}\r\n",
+      "type": "registry:example"
+    }
+  ]
+}