Wizard Development Guide

# Use the wizard template
create-spec --core hr --name leave-request-wizard --type wizard

# Or let auto-detection prompt you
create-spec --core hr --name leave-request-wizard
# → "Name contains 'wizard'. Use SPEC_TEMPLATE.md with wizard-flow snippet? (Y/n)"

validate-spec --file specs/hr/ux/HR-UX-04-leave-request-wizard.md --type wizard

generate-tasks HR-UX-04

import { trackWizardEvent } from '@/platform/wizards';

// on mount / step / completion (fire-and-forget, PHI-sanitized):
void trackWizardEvent({
  wizardKey: 'ce.lead_intake',        // '<core>.<wizard_slug>' — the ledger id, dot-form
  organizationId,
  userId,
  eventType: 'wizard_started',        // | step_completed | wizard_completed | wizard_abandoned | ...
  stepId, stepIndex,                   // optional
});

┌─────────────────────────────────────────────────────────────────┐
│                  WIZARD DEVELOPMENT LIFECYCLE                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. SPECIFICATION         2. PLANNING          3. IMPLEMENTATION │
│  ┌──────────────┐        ┌──────────────┐     ┌──────────────┐  │
│  │ Create spec  │───────▶│ Choose PF-41 │────▶│ Build steps  │  │
│  │ using wizard │        │ approach     │     │ & components │  │
│  │ template     │        │              │     │              │  │
│  └──────────────┘        └──────────────┘     └──────────────┘  │
│         │                       │                    │           │
│         ▼                       ▼                    ▼           │
│  ┌──────────────┐        ┌──────────────┐     ┌──────────────┐  │
│  │ Define steps │        │ Design data  │     │ Register     │  │
│  │ & validation │        │ model        │     │ with PF-41   │  │
│  └──────────────┘        └──────────────┘     └──────────────┘  │
│                                                      │           │
│                                                      ▼           │
│  4. TESTING               5. DEPLOYMENT        6. ANALYTICS     │
│  ┌──────────────┐        ┌──────────────┐     ┌──────────────┐  │
│  │ Unit tests   │───────▶│ Feature flag │────▶│ Track usage  │  │
│  │ E2E tests    │        │ System templ │     │ & completion │  │
│  │ RLS tests    │        │              │     │              │  │
│  └──────────────┘        └──────────────┘     └──────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

### Step N: [Step Name]

**Purpose:** [What this step accomplishes]

**Step Type:** `form` / `custom` / `review`

**Component ID (if custom):** `{core}.{feature}.{step}`

**Fields/Components:**
| Field | Type | Required | Validation |
|-------|------|----------|------------|
| field1 | text | Yes | min 2 chars |
| field2 | select | No | - |

**Help Content:**
- **Title:** [Help title]
- **Content:** [Help text]

**Tooltip Definitions:**
| Term | Tooltip Key | Content |
|------|-------------|---------|
| term1 | `wizard_term_definition` | [Text] |

**Navigation:**
- **Can Skip:** Yes/No - [Reason]
- **Can Go Back:** Yes/No
- **Next Step:** [Next step name]

**Mobile Considerations:**
- [ ] Touch targets ≥44x44px
- [ ] Form fields stack vertically on mobile
- [ ] Native pickers for date/time on mobile
- [ ] Validation errors visible without scrolling

import { WizardShell } from '@/platform/wizards';
import { User, Calendar, ClipboardCheck } from 'lucide-react';

const steps = [
  { id: 'info', title: 'Personal Info', icon: User },
  { id: 'dates', title: 'Schedule', icon: Calendar },
  { id: 'review', title: 'Review', icon: ClipboardCheck },
];

<WizardShell steps={steps} layout="timeline" /* ... */ />

// Template step definition (JSON)
{
  "id": "step-1",
  "title": "Employee Info",
  "icon": "user",
  "component_type": "form",
  // ...
}

import { resolveStepIcon } from '@/platform/wizards';

const steps = template.steps.map((step) => ({
  id: step.id,
  title: step.title,
  icon: resolveStepIcon(step.icon),
}));

Is this wizard...
│
├─ A standardized process that organizations should customize?
│   └─ YES → Use System Template approach
│
├─ Highly integrated with module-specific logic?
│   └─ YES → Use Module-Specific approach
│
└─ Both complex logic AND needs customization?
    └─ YES → Use Hybrid approach

// src/cores/{core}/pages/{Wizard}Page.tsx
import { ModuleWizardRenderer } from '@/platform/wizards';
import { useActiveWizard } from '@/platform/wizards';

export function LeaveRequestWizardPage() {
  const { data: template } = useActiveWizard({
    module: 'hr',
    wizardType: 'leave_request',
  });

  return (
    <ModuleWizardRenderer
      template={template}
      onComplete={handleComplete}
      onCancel={handleCancel}
    />
  );
}

// src/cores/{core}/wizards/{wizard}/WizardPage.tsx
import { WizardRenderer } from '@/platform/forms/components/wizard';
import { Step1, Step2, ReviewStep } from './steps';

export function LeaveRequestWizard() {
  const [step, setStep] = useState(1);
  const [data, setData] = useState({});

  const steps = [
    { component: Step1, title: 'Leave Type' },
    { component: Step2, title: 'Dates' },
    { component: ReviewStep, title: 'Review' },
  ];

  return (
    <WizardRenderer
      steps={steps}
      currentStep={step}
      data={data}
      onStepChange={setStep}
      onDataChange={setData}
    />
  );
}

// Combine PF-41 form steps with custom components
import { ModuleWizardRenderer, registerWizardStep } from '@/platform/wizards';
import { CustomValidationStep } from './steps/CustomValidationStep';

// Register custom step
registerWizardStep({
  id: 'hr.leave.validation',
  module: 'hr',
  name: 'Custom Validation',
  component: CustomValidationStep,
});

// Template uses both form steps and custom step

src/cores/{core}/
├── wizards/
│   ├── register{Core}WizardSteps.ts    # Step registration (PF-41)
│   └── {wizard-name}/
│       ├── {WizardName}Page.tsx        # Wizard page component
│       ├── steps/
│       │   ├── Step1Component.tsx      # Custom step components
│       │   ├── Step2Component.tsx
│       │   └── ReviewStep.tsx
│       ├── hooks/
│       │   ├── useWizardData.ts        # Data fetching
│       │   └── useWizardValidation.ts  # Validation logic
│       └── types.ts                    # TypeScript types

// src/cores/hr/wizards/leave-request/steps/LeaveTypeStep.tsx
import { WizardStepProps } from '@/platform/wizards';
import { FormField, FormItem, FormLabel } from '@/shared/ui/form';
import { useLeaveTypes } from '@/cores/hr/hooks/useLeaveTypes';

interface LeaveTypeStepProps extends WizardStepProps {
  // Step-specific props
}

export function LeaveTypeStep({ 
  data, 
  onDataChange, 
  onValidate 
}: LeaveTypeStepProps) {
  const { data: leaveTypes, isLoading } = useLeaveTypes();

  const handleTypeSelect = (typeId: string) => {
    onDataChange({ ...data, leaveTypeId: typeId });
  };

  return (
    <div className="space-y-4">
      <FormField
        name="leaveType"
        render={({ field }) => (
          <FormItem>
            <FormLabel>Select Leave Type</FormLabel>
            {/* ... form control */}
          </FormItem>
        )}
      />
    </div>
  );
}

// Validation function
LeaveTypeStep.validate = (data: WizardFormData) => {
  const errors: ValidationErrors = {};
  if (!data.leaveTypeId) {
    errors.leaveTypeId = 'Please select a leave type';
  }
  return errors;
};

// src/cores/hr/wizards/registerHRWizardSteps.ts
import { registerWizardStep } from '@/platform/wizards';
import { lazy } from 'react';

export function registerHRWizardSteps() {
  // Leave Request Wizard Steps
  registerWizardStep({
    id: 'hr.leave.type-selection',
    module: 'hr',
    name: 'Leave Type Selection',
    description: 'Select leave type and view balance',
    component: lazy(() => import('./leave-request/steps/LeaveTypeStep')),
  });

  registerWizardStep({
    id: 'hr.leave.date-selection',
    module: 'hr',
    name: 'Date Selection',
    description: 'Select start and end dates',
    component: lazy(() => import('./leave-request/steps/DateSelectionStep')),
  });

  // ... additional steps
}

import { useWizardDraft } from '@/platform/wizards';

function MyWizard() {
  const { 
    draft, 
    saveDraft, 
    loadDraft, 
    clearDraft 
  } = useWizardDraft({
    wizardType: 'leave_request',
    userId: user.id,
  });

  // Auto-save on step change
  const handleStepComplete = (stepData: StepData) => {
    saveDraft({
      currentStep: step,
      data: { ...data, ...stepData },
    });
  };

  return (/* ... */);
}

// tests/unit/hr/leave-request-wizard/LeaveTypeStep.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { LeaveTypeStep } from '@/cores/hr/wizards/leave-request/steps/LeaveTypeStep';

describe('LeaveTypeStep', () => {
  it('validates leave type selection', () => {
    const errors = LeaveTypeStep.validate({});
    expect(errors.leaveTypeId).toBe('Please select a leave type');
  });

  it('passes validation with leave type selected', () => {
    const errors = LeaveTypeStep.validate({ leaveTypeId: 'vacation' });
    expect(errors).toEqual({});
  });

  it('shows available leave balances', async () => {
    render(<LeaveTypeStep data={{}} onDataChange={jest.fn()} />);
    expect(await screen.findByText('Vacation')).toBeInTheDocument();
    expect(await screen.findByText('16 hours available')).toBeInTheDocument();
  });
});

// tests/e2e/hr/leave-request-wizard.spec.ts
import { test, expect } from '@chromatic-com/playwright';

test.describe('Leave Request Wizard', () => {
  test('completes full wizard flow', async ({ page }) => {
    await page.goto('/hr/leave/request');

    // Step 1: Select leave type
    await page.click('[data-testid="leave-type-vacation"]');
    await page.click('[data-testid="next-button"]');

    // Step 2: Select dates
    await page.fill('[data-testid="start-date"]', '2026-02-15');
    await page.fill('[data-testid="end-date"]', '2026-02-20');
    await page.click('[data-testid="next-button"]');

    // Step 3: Add details
    await page.fill('[data-testid="notes"]', 'Family vacation');
    await page.click('[data-testid="next-button"]');

    // Step 4: Review and submit
    await expect(page.locator('[data-testid="summary-leave-type"]'))
      .toHaveText('Vacation');
    await page.click('[data-testid="submit-button"]');

    // Verify success
    await expect(page.locator('[data-testid="success-message"]'))
      .toBeVisible();
  });

  test('saves and resumes draft', async ({ page }) => {
    await page.goto('/hr/leave/request');

    // Complete step 1
    await page.click('[data-testid="leave-type-vacation"]');
    await page.click('[data-testid="next-button"]');

    // Navigate away
    await page.goto('/hr/dashboard');

    // Return to wizard
    await page.goto('/hr/leave/request');

    // Should resume at step 2
    await expect(page.locator('[data-testid="step-indicator"]'))
      .toHaveText('Step 2 of 4');
  });
});

import { trackWizardEvent } from '@/platform/wizards';

// Wizard started
trackWizardEvent('leave_request_wizard_started', {
  wizard_id: templateId,
  user_id: userId,
  device_type: isMobile ? 'mobile' : 'desktop',
  entry_point: 'dashboard_quick_action',
});

// Step completed
trackWizardEvent('leave_request_wizard_step_completed', {
  step_id: 'date-selection',
  step_name: 'Date Selection',
  time_spent_ms: 45000,
  fields_completed: 3,
});

// Wizard completed
trackWizardEvent('leave_request_wizard_completed', {
  total_time_ms: 120000,
  steps_completed: 4,
  steps_skipped: 0,
  entity_id: leaveRequestId,
});

<ModuleWizardRenderer
  template={template}
  trackAnalytics={true}  // Default: true
  onComplete={handleComplete}
/>

import { useWizardFeatureFlags } from '@/platform/wizards';

function LeaveRequestPage() {
  const { useConfigurableWizard } = useWizardFeatureFlags('hr');

  if (useConfigurableWizard) {
    return <ConfigurableLeaveWizard />;
  }
  return <LegacyLeaveForm />;
}

-- supabase/migrations/YYYYMMDDHHMMSS_add_leave_request_wizard_template.sql
INSERT INTO pf_wizard_templates (
  module,
  wizard_type,
  name,
  description,
  wizard_config,
  steps,
  is_template,
  is_active
) VALUES (
  'hr',
  'leave_request',
  'Leave Request Wizard',
  'Guided workflow for requesting time off',
  '{"progress_style": "stepper", "validation_mode": "on_advance"}',
  '[{"id": "step-1", "title": "Leave Type", "component_type": "custom", "component_id": "hr.leave.type-selection"}, ...]'::jsonb,
  true,  -- System template
  true   -- Active
);

## PF-41 Wizard Architecture

**Approach:** Module-Specific

**Rationale:** This wizard requires complex validation logic that integrates 
deeply with HR leave policy rules. A future enhancement will migrate to 
PF-41 hybrid approach for organization customization.

recommend-wizards --core {core}
       ↓
create-wizard-spec --core {core} --name {name} --based-on {SPEC-ID}
       ↓
validate-spec --file specs/{core}/ux/{CORE}-UX-##-{name}.md --type wizard
       ↓
generate-tasks {CORE}-UX-##
       ↓
implement (using WizardShell / DialogWizardShell / ModuleWizardRenderer)
       ↓
audit-wizard-specs --core {core}

// src/bootstrap/registerModuleWizardSteps.ts
const WIZARD_MODULES = [
  { id: 'fa.wizards', load: () => import('@/cores/fa/wizards/registerFAWizardSteps') },
  { id: 'ce.screening', load: () => import('@/cores/ce/wizards/screening/registerScreeningWizardSteps') },
  { id: 'ce.partner-contract', load: () => import('@/cores/ce/wizards/partner-contract/registerPartnerContractWizardSteps') },
  { id: 'ce.sequences', load: () => import('@/cores/ce/wizards/sequences/registerCeSequenceWizardSteps') },
  { id: 'gr.wizards', load: () => import('@/cores/gr/wizards/registerGRWizardSteps') },
  { id: 'gr.training-course', load: () => import('@/cores/gr/wizards/training-course/registerTrainingCourseWizardSteps') },
  { id: 'hr.wizards', load: () => import('@/cores/hr/components/wizards/registerHRWizardSteps') },
  { id: 'hr.payroll-wizards', load: () => import('@/cores/hr/wizards/registerHRPayrollWizardSteps') },
  { id: 'rh.wizards', load: () => import('@/cores/rh/components/wizards/registerRHWizardSteps') },
] as const;

export function registerAllModuleWizardSteps(): void {
  for (const moduleSpec of WIZARD_MODULES) {
    // Load each module independently so one failure cannot block app boot.
    void moduleSpec.load();
  }
}

Need a multi-step flow?
│
├─ Parallel tab navigation (non-sequential)?
│   └─ Not a wizard — use tabs / segmented controls
│
├─ Form data capture only (no business logic)?
│   └─ Use FW-31 MultiPageFormRenderer
│
├─ Guided business process with custom logic?
│   │
│   ├─ Organizations should customize steps?
│   │   └─ PF-41 System Template + ModuleWizardRenderer
│   │
│   ├─ Tightly coupled to module internals?
│   │   └─ WizardShell + custom step components
│   │
│   └─ Both customizable AND complex?
│       └─ PF-41 Hybrid (form + custom steps via registerWizardStep)
│
└─ Short dialog-based flow (≤4 steps)?
    └─ DialogWizardShell