policyengine-household-wizard 0.1.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "policyengine-household-wizard",
+  "version": "0.1.0",
+  "description": "Shared wizard primitives and US household draft contract for PolicyEngine apps.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives.js",
+      "require": "./dist/primitives.cjs"
+    },
+    "./us-household": {
+      "types": "./dist/us-household/index.d.ts",
+      "import": "./dist/us-household.js",
+      "require": "./dist/us-household.cjs"
+    },
+    "./us-household/adapters": {
+      "types": "./dist/us-household/adapters/index.d.ts",
+      "import": "./dist/us-household-adapters.js",
+      "require": "./dist/us-household-adapters.cjs"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly && tsx scripts/emit-subpath-types.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "regenerate-counties": "tsx scripts/generate-counties.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.3.0",
+    "vitest": "^3.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PolicyEngine/policyengine-household-wizard.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './primitives';
+export * from './us-household';

package/src/primitives/WizardNavigation.tsx

@@ -0,0 +1,85 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+export interface WizardNavigationProps extends HTMLAttributes<HTMLDivElement> {
+  canAdvance: boolean;
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  backLabel?: ReactNode;
+  continueLabel?: ReactNode;
+  submitLabel?: ReactNode;
+  busyLabel?: ReactNode;
+  busy?: boolean;
+  onBack?: () => void;
+  onContinue?: () => void;
+  onSubmit?: () => void;
+  leadingActions?: ReactNode;
+  trailingActions?: ReactNode;
+  hideBack?: boolean;
+}
+
+export function WizardNavigation({
+  canAdvance,
+  isFirstStep,
+  isLastStep,
+  backLabel = 'Back',
+  continueLabel = 'Continue',
+  submitLabel = 'Submit',
+  busyLabel,
+  busy = false,
+  onBack,
+  onContinue,
+  onSubmit,
+  leadingActions,
+  trailingActions,
+  hideBack = false,
+  className,
+  ...rest
+}: WizardNavigationProps) {
+  const primaryDisabled = busy || !canAdvance;
+  const primaryLabel = busy && busyLabel ? busyLabel : isLastStep ? submitLabel : continueLabel;
+
+  const handlePrimary = () => {
+    if (primaryDisabled) {
+      return;
+    }
+    if (isLastStep) {
+      onSubmit?.();
+    } else {
+      onContinue?.();
+    }
+  };
+
+  return (
+    <div
+      className={['pe-wizard-nav', className].filter(Boolean).join(' ')}
+      {...rest}
+    >
+      {leadingActions ? (
+        <div className="pe-wizard-nav-leading">{leadingActions}</div>
+      ) : null}
+      {!hideBack ? (
+        <button
+          type="button"
+          className="pe-wizard-nav-back"
+          onClick={onBack}
+          disabled={isFirstStep || busy}
+          aria-label={typeof backLabel === 'string' ? backLabel : undefined}
+        >
+          {backLabel}
+        </button>
+      ) : null}
+      <button
+        type="button"
+        className="pe-wizard-nav-primary"
+        onClick={handlePrimary}
+        disabled={primaryDisabled}
+        aria-disabled={primaryDisabled}
+      >
+        {primaryLabel}
+      </button>
+      {trailingActions ? (
+        <div className="pe-wizard-nav-trailing">{trailingActions}</div>
+      ) : null}
+    </div>
+  );
+}

package/src/primitives/WizardOptionCard.tsx

@@ -0,0 +1,55 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+export interface WizardOptionCardProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'title' | 'onSelect'> {
+  selected?: boolean;
+  title: ReactNode;
+  description?: ReactNode;
+  onSelect?: () => void;
+}
+
+export function WizardOptionCard({
+  selected = false,
+  title,
+  description,
+  onSelect,
+  onClick,
+  className,
+  type,
+  disabled,
+  ...rest
+}: WizardOptionCardProps) {
+  const classes = ['pe-wizard-option-card'];
+  if (selected) {
+    classes.push('pe-wizard-option-card--selected');
+  }
+  if (className) {
+    classes.push(className);
+  }
+
+  return (
+    <button
+      type={type ?? 'button'}
+      role="radio"
+      aria-checked={selected}
+      aria-disabled={disabled ? true : undefined}
+      disabled={disabled}
+      className={classes.join(' ')}
+      onClick={(event) => {
+        if (disabled) {
+          return;
+        }
+        onClick?.(event);
+        if (!event.defaultPrevented) {
+          onSelect?.();
+        }
+      }}
+      {...rest}
+    >
+      <span className="pe-wizard-option-card-title">{title}</span>
+      {description ? (
+        <span className="pe-wizard-option-card-description">{description}</span>
+      ) : null}
+    </button>
+  );
+}

package/src/primitives/WizardProgress.tsx

@@ -0,0 +1,50 @@
+import type { CSSProperties, HTMLAttributes } from 'react';
+
+export interface WizardProgressProps extends HTMLAttributes<HTMLDivElement> {
+  totalSteps: number;
+  currentStepIndex: number;
+  currentStepLabel?: string;
+}
+
+export function WizardProgress({
+  totalSteps,
+  currentStepIndex,
+  currentStepLabel,
+  className,
+  ...rest
+}: WizardProgressProps) {
+  const safeTotal = Math.max(totalSteps, 0);
+  const clampedIndex = Math.max(0, Math.min(currentStepIndex, safeTotal - 1));
+  const progress = safeTotal > 0 ? ((clampedIndex + 1) / safeTotal) * 100 : 0;
+  const stepNumber = safeTotal > 0 ? clampedIndex + 1 : 0;
+
+  const trackStyle: CSSProperties = { width: `${progress}%` };
+
+  return (
+    <div
+      role="group"
+      aria-label={rest['aria-label'] ?? 'Wizard progress'}
+      className={['pe-wizard-progress', className].filter(Boolean).join(' ')}
+      {...rest}
+    >
+      <div className="pe-wizard-progress-topline">
+        <span data-testid="pe-wizard-progress-step">
+          Step {stepNumber} of {safeTotal}
+        </span>
+        {currentStepLabel ? (
+          <span data-testid="pe-wizard-progress-label">{currentStepLabel}</span>
+        ) : null}
+      </div>
+      <div
+        className="pe-wizard-progress-track"
+        role="progressbar"
+        aria-valuemin={0}
+        aria-valuemax={safeTotal}
+        aria-valuenow={stepNumber}
+        aria-valuetext={currentStepLabel}
+      >
+        <div className="pe-wizard-progress-bar" style={trackStyle} />
+      </div>
+    </div>
+  );
+}

package/src/primitives/WizardReviewList.tsx

@@ -0,0 +1,73 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+export interface WizardReviewItem {
+  id: string;
+  label: ReactNode;
+  value: ReactNode;
+  missing?: boolean;
+  onEdit?: () => void;
+  editLabel?: ReactNode;
+}
+
+export interface WizardReviewListProps extends HTMLAttributes<HTMLDivElement> {
+  items: WizardReviewItem[];
+}
+
+export function WizardReviewList({ items, className, ...rest }: WizardReviewListProps) {
+  return (
+    <div
+      className={['pe-wizard-review-list', className].filter(Boolean).join(' ')}
+      role="list"
+      {...rest}
+    >
+      {items.map((item) => {
+        const classes = ['pe-wizard-review-item'];
+        if (item.missing) {
+          classes.push('pe-wizard-review-item--missing');
+        }
+        const editable = typeof item.onEdit === 'function';
+        const content = (
+          <>
+            <span className="pe-wizard-review-item-label">{item.label}</span>
+            <span className="pe-wizard-review-item-value">
+              {item.missing && (item.value === null || item.value === undefined || item.value === '')
+                ? 'Missing'
+                : item.value}
+            </span>
+          </>
+        );
+
+        if (!editable) {
+          return (
+            <div
+              key={item.id}
+              role="listitem"
+              className={classes.join(' ')}
+              data-testid={`pe-wizard-review-${item.id}`}
+            >
+              {content}
+            </div>
+          );
+        }
+
+        return (
+          <button
+            key={item.id}
+            type="button"
+            role="listitem"
+            className={classes.join(' ')}
+            data-testid={`pe-wizard-review-${item.id}`}
+            onClick={item.onEdit}
+            aria-label={
+              typeof item.label === 'string'
+                ? `${item.editLabel ?? 'Edit'} ${item.label}`
+                : undefined
+            }
+          >
+            {content}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/primitives/index.ts

@@ -0,0 +1,15 @@
+export { useWizardSteps } from './useWizardSteps';
+export { WizardProgress } from './WizardProgress';
+export type { WizardProgressProps } from './WizardProgress';
+export { WizardOptionCard } from './WizardOptionCard';
+export type { WizardOptionCardProps } from './WizardOptionCard';
+export { WizardNavigation } from './WizardNavigation';
+export type { WizardNavigationProps } from './WizardNavigation';
+export { WizardReviewList } from './WizardReviewList';
+export type { WizardReviewItem, WizardReviewListProps } from './WizardReviewList';
+export type {
+  ResolvedWizardStep,
+  UseWizardStepsOptions,
+  UseWizardStepsResult,
+  WizardStepConfig,
+} from './types';

package/src/primitives/types.ts

@@ -0,0 +1,32 @@
+export interface WizardStepConfig<TState> {
+  id: string;
+  label: string;
+  isComplete?: (state: TState) => boolean;
+  isVisible?: (state: TState) => boolean;
+}
+
+export interface ResolvedWizardStep {
+  id: string;
+  label: string;
+}
+
+export interface UseWizardStepsOptions<TState> {
+  steps: ReadonlyArray<WizardStepConfig<TState>>;
+  state: TState;
+  initialStepId?: string;
+  onStepChange?: (stepId: string) => void;
+}
+
+export interface UseWizardStepsResult {
+  visibleSteps: ResolvedWizardStep[];
+  currentStep: ResolvedWizardStep | null;
+  currentStepIndex: number;
+  totalSteps: number;
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  canAdvance: boolean;
+  goNext: () => void;
+  goBack: () => void;
+  goToStep: (stepId: string) => void;
+  reset: () => void;
+}

package/src/primitives/useWizardSteps.ts

@@ -0,0 +1,150 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type {
+  ResolvedWizardStep,
+  UseWizardStepsOptions,
+  UseWizardStepsResult,
+  WizardStepConfig,
+} from './types';
+
+function resolveVisibleSteps<TState>(
+  steps: ReadonlyArray<WizardStepConfig<TState>>,
+  state: TState,
+): WizardStepConfig<TState>[] {
+  return steps.filter((step) => (step.isVisible ? step.isVisible(state) : true));
+}
+
+function toResolvedStep<TState>(step: WizardStepConfig<TState>): ResolvedWizardStep {
+  return { id: step.id, label: step.label };
+}
+
+function pickInitialStepId<TState>(
+  visibleSteps: WizardStepConfig<TState>[],
+  preferredId: string | undefined,
+): string | null {
+  if (visibleSteps.length === 0) {
+    return null;
+  }
+
+  if (preferredId && visibleSteps.some((step) => step.id === preferredId)) {
+    return preferredId;
+  }
+
+  return visibleSteps[0].id;
+}
+
+export function useWizardSteps<TState>(
+  options: UseWizardStepsOptions<TState>,
+): UseWizardStepsResult {
+  const { steps, state, initialStepId, onStepChange } = options;
+
+  const visibleStepConfigs = useMemo(
+    () => resolveVisibleSteps(steps, state),
+    [steps, state],
+  );
+
+  const visibleSteps = useMemo(
+    () => visibleStepConfigs.map(toResolvedStep),
+    [visibleStepConfigs],
+  );
+
+  const initialResolvedId = useMemo(
+    () => pickInitialStepId(visibleStepConfigs, initialStepId),
+    // Only recompute when explicit initialStepId or the set of step ids changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [initialStepId],
+  );
+
+  const [currentStepId, setCurrentStepId] = useState<string | null>(initialResolvedId);
+
+  // If the visible set changes (e.g. a conditional step is hidden), keep the
+  // currentStepId in sync. If the currently selected step is no longer visible,
+  // fall back to the first visible step.
+  useEffect(() => {
+    if (visibleStepConfigs.length === 0) {
+      if (currentStepId !== null) {
+        setCurrentStepId(null);
+      }
+      return;
+    }
+
+    const exists = visibleStepConfigs.some((step) => step.id === currentStepId);
+    if (!exists) {
+      setCurrentStepId(visibleStepConfigs[0].id);
+    }
+  }, [visibleStepConfigs, currentStepId]);
+
+  const onStepChangeRef = useRef(onStepChange);
+  useEffect(() => {
+    onStepChangeRef.current = onStepChange;
+  }, [onStepChange]);
+
+  const setStepAndNotify = useCallback((stepId: string) => {
+    setCurrentStepId((previous) => {
+      if (previous === stepId) {
+        return previous;
+      }
+      onStepChangeRef.current?.(stepId);
+      return stepId;
+    });
+  }, []);
+
+  const currentStepIndex = useMemo(
+    () => visibleStepConfigs.findIndex((step) => step.id === currentStepId),
+    [visibleStepConfigs, currentStepId],
+  );
+
+  const currentStepConfig = currentStepIndex >= 0 ? visibleStepConfigs[currentStepIndex] : null;
+  const currentStep = currentStepConfig ? toResolvedStep(currentStepConfig) : null;
+
+  const totalSteps = visibleStepConfigs.length;
+  const isFirstStep = currentStepIndex <= 0;
+  const isLastStep = totalSteps === 0 ? true : currentStepIndex === totalSteps - 1;
+
+  const canAdvance = currentStepConfig?.isComplete
+    ? currentStepConfig.isComplete(state)
+    : true;
+
+  const goNext = useCallback(() => {
+    if (currentStepIndex < 0 || currentStepIndex >= visibleStepConfigs.length - 1) {
+      return;
+    }
+    setStepAndNotify(visibleStepConfigs[currentStepIndex + 1].id);
+  }, [currentStepIndex, visibleStepConfigs, setStepAndNotify]);
+
+  const goBack = useCallback(() => {
+    if (currentStepIndex <= 0) {
+      return;
+    }
+    setStepAndNotify(visibleStepConfigs[currentStepIndex - 1].id);
+  }, [currentStepIndex, visibleStepConfigs, setStepAndNotify]);
+
+  const goToStep = useCallback(
+    (stepId: string) => {
+      if (visibleStepConfigs.some((step) => step.id === stepId)) {
+        setStepAndNotify(stepId);
+      }
+    },
+    [visibleStepConfigs, setStepAndNotify],
+  );
+
+  const reset = useCallback(() => {
+    const fallback = pickInitialStepId(visibleStepConfigs, initialStepId);
+    if (fallback) {
+      setStepAndNotify(fallback);
+    }
+  }, [visibleStepConfigs, initialStepId, setStepAndNotify]);
+
+  return {
+    visibleSteps,
+    currentStep,
+    currentStepIndex,
+    totalSteps,
+    isFirstStep,
+    isLastStep,
+    canAdvance,
+    goNext,
+    goBack,
+    goToStep,
+    reset,
+  };
+}