@skunkworksai/ui-kit 0.1.18 → 0.1.25-a

package/rules/wizard-stepper.md

@@ -0,0 +1,207 @@
+# AppWizardStepper
+
+> Docs: https://ui-kit.vercel.app/docs/blocks/wizard-stepper
+
+**This is a block — import from `blocks/AppWizardStepper`, not `primitives/`.**
+
+```tsx
+import {
+  AppWizardStepper,
+  type AppWizardStep,
+  type AppWizardStepperProps,
+} from "@skunkworks-ai/ui-kit"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `AppWizardStep[]` | required | Ordered list of steps. Each step needs a stable `id` and a `label`. |
+| `activeIndex` | `number` | required | 0-based index of the currently active step. Steps before this index are rendered as completed. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
+| `onStepClick` | `(step: AppWizardStep, index: number) => void` | — | Fires when a completed or active step is clicked. Upcoming steps are never interactive. |
+| `hideLabels` | `boolean \| undefined` | `undefined` | Controls label visibility. See tristate values below. |
+| `className` | `string` | — | Extra classes on the root `<ol>`. |
+
+### `AppWizardStep` type
+
+```ts
+type AppWizardStep = {
+  id: string          // Stable identifier used as React key and in onStepClick
+  label: string       // Displayed step name
+  description?: string // Optional sub-label shown under the main label
+}
+```
+
+### `hideLabels` tristate
+
+| Value | Behaviour |
+|-------|-----------|
+| `undefined` (default) | Labels hidden below `md`, visible on `md+` (CSS-only; screen-reader visible at all sizes) |
+| `true` | Always hidden — `sr-only` at all breakpoints |
+| `false` | Always visible — no responsive hiding |
+
+## Step states
+
+| State | Condition | Visual |
+|-------|-----------|--------|
+| `completed` | `index < activeIndex` | Filled circle with check icon (`--primary` bg) |
+| `active` | `index === activeIndex` | Outlined circle with primary ring (`--primary` border + ring) |
+| `upcoming` | `index > activeIndex` | Muted circle with number (`--muted` bg, `--border` border) |
+
+## Usage
+
+### Horizontal (default)
+
+```tsx
+const STEPS: AppWizardStep[] = [
+  { id: "details", label: "Details" },
+  { id: "review", label: "Review" },
+  { id: "confirm", label: "Confirm" },
+]
+
+function WizardPage() {
+  const [activeIndex, setActiveIndex] = React.useState(0)
+
+  const handleStepClick = React.useCallback(
+    (_step: AppWizardStep, index: number) => setActiveIndex(index),
+    []
+  )
+
+  return (
+    <AppWizardStepper
+      steps={STEPS}
+      activeIndex={activeIndex}
+      onStepClick={handleStepClick}
+    />
+  )
+}
+```
+
+### Vertical
+
+```tsx
+<AppWizardStepper
+  steps={STEPS}
+  activeIndex={1}
+  orientation="vertical"
+  onStepClick={handleStepClick}
+/>
+```
+
+### With descriptions
+
+```tsx
+const STEPS: AppWizardStep[] = [
+  { id: "account", label: "Account", description: "Basic info" },
+  { id: "profile", label: "Profile", description: "Personal details" },
+  { id: "done", label: "Done", description: "Review & submit" },
+]
+```
+
+### Always show labels
+
+```tsx
+<AppWizardStepper steps={STEPS} activeIndex={1} hideLabels={false} />
+```
+
+### Icon-only (always hidden labels)
+
+```tsx
+<AppWizardStepper steps={STEPS} activeIndex={1} hideLabels={true} />
+```
+
+### Controlled active index (full wizard flow)
+
+```tsx
+function MultiStepForm() {
+  const [activeIndex, setActiveIndex] = React.useState(0)
+
+  const handleNext = () => setActiveIndex((i) => Math.min(i + 1, STEPS.length - 1))
+  const handleBack = () => setActiveIndex((i) => Math.max(i - 1, 0))
+
+  // Gate forward nav yourself — onStepClick only fires for completed/active steps
+  const handleStepClick = React.useCallback(
+    (_step: AppWizardStep, index: number) => setActiveIndex(index),
+    []
+  )
+
+  return (
+    <div className="space-y-6">
+      <AppWizardStepper
+        steps={STEPS}
+        activeIndex={activeIndex}
+        onStepClick={handleStepClick}
+      />
+      <StepContent index={activeIndex} />
+      <div className="flex gap-2">
+        <AppButton variant="outline" onClick={handleBack} disabled={activeIndex === 0}>
+          Back
+        </AppButton>
+        <AppButton onClick={handleNext} disabled={activeIndex === STEPS.length - 1}>
+          Next
+        </AppButton>
+      </div>
+    </div>
+  )
+}
+```
+
+## Clickability gate
+
+`onStepClick` only fires for steps in `completed` or `active` state. Upcoming steps are rendered as static `<div>` elements — not `<button>` elements — so they cannot be focused or activated. This is intentional: forward navigation must be gated by the parent component.
+
+Do not try to navigate forward by clicking an upcoming step indicator — the component will not call `onStepClick` for it.
+
+## Accessibility
+
+- Root element is `<ol role="list" aria-label="Progress">`
+- Each step is `<li role="listitem">`
+- Active step carries `aria-current="step"`
+- Clickable steps are native `<button type="button">` with `aria-label="Go to step N: Label"`
+- Indicator circles are `aria-hidden="true"` — label text provides the accessible name
+- Labels are `sr-only` on mobile by default, ensuring screen readers always have access to step names regardless of the `hideLabels` setting
+
+## Performance
+
+Memoize `steps` and `onStepClick` to avoid unnecessary re-renders. `steps` is typically a module-level constant; `onStepClick` should be wrapped in `useCallback`.
+
+```tsx
+// ✅ Correct
+const STEPS = [{ id: "a", label: "A" }, { id: "b", label: "B" }] // module scope
+
+const handleStepClick = React.useCallback(
+  (_step: AppWizardStep, i: number) => setActive(i),
+  []
+)
+
+// ❌ Wrong — new array + new function every render
+<AppWizardStepper
+  steps={[{ id: "a", label: "A" }]}
+  onStepClick={(_s, i) => setActive(i)}
+  ...
+/>
+```
+
+## Token usage
+
+| Visual element | Token |
+|----------------|-------|
+| Completed circle fill | `--primary` / `--primary-foreground` |
+| Active circle border + ring | `--primary` / `ring-primary/30` |
+| Upcoming circle fill | `--muted` / `--muted-foreground` |
+| Upcoming circle border | `--border` |
+| Connector line (default) | `--border` |
+| Connector line (completed segment) | `--primary` |
+
+## Rules
+
+- ✅ Define `steps` at module scope or memoize — avoid recreating the array on every render
+- ✅ Wrap `onStepClick` in `useCallback`
+- ✅ Gate forward navigation yourself — `onStepClick` only fires for completed/active steps
+- ✅ Use `hideLabels={false}` when you always want labels visible regardless of breakpoint
+- ✅ Use `orientation="vertical"` for tall, sidebar-style step flows
+- ❌ Do not attempt to make upcoming steps clickable — the block intentionally blocks this; gate forward nav in the parent
+- ❌ Do not manage the completed/upcoming state externally — derive it from `activeIndex`; steps before it are automatically completed
+- ❌ Do not add custom color classes to the indicator circle — all step colors come from design tokens
+- ❌ If a prop you need is missing, stop and inform the design team