@govtech-bb/forms

Reusable form components, hooks, and utilities for Alpha Gov BB multi-step forms.

Installation

pnpm add @govtech-bb/forms

Peer Dependencies

This package requires the following peer dependencies:

{
  "@govtech-bb/design": "^1.0.0-alpha.5",
  "@govtech-bb/react": "^1.0.0-alpha.5",
  "@hookform/resolvers": "^5.2.1",
  "@tanstack/react-form": "^1.23.0",
  "@tanstack/react-store": "^0.8.0",
  "next": "^15.0.0",
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "react-hook-form": "^7.62.0",
  "zod": "^4.0.0"
}

What's Included

Components

• StepContainer - Standard step wrapper with title, description, and navigation
• SummarySection - Check-answers page sections
• ConfirmationTemplate - Success page template
• DateInput - Custom date component with day/month/year fields
• ErrorSummary - Accessible error summary display
• FormFieldError - Individual field error messages
• FormAutoSaveBanner - Auto-save status indicator
• FormRestoreBanner - Draft restoration prompt
• FormProgressIndicator - Progress visualization

Hooks

• useFormOrchestrator - Complete form setup (~130 lines of boilerplate eliminated)
• useStepValidation - Step validation with error handling
• useErrorSummary - Error mapping for accessible error summaries
• useStepFocus - Accessibility focus management
• useFormStorage - SessionStorage with versioning and expiry
• useFormNavigation - Generic step navigation with URL sync

Form Builder

• defineForm() - Define form specifications with validation
• FormSpec - Type definitions for form specifications
• FieldDefinition - Field configuration types
• StepDefinition - Step configuration types

Utilities

• Date parsing, validation, and formatting
• Field className helpers for error states

Usage Example

import {
  defineForm,
  useFormOrchestrator,
  StepContainer
} from '@govtech-bb/forms'
import { z } from 'zod'

// Define your form spec
const myFormSpec = defineForm({
  formId: 'my-form',
  formTitle: 'My Form',
  storageKey: 'govbb_my_form_draft',
  version: 'v1.0.0',
  submitEndpoint: '/api/my-form',
  fields: {
    name: {
      component: 'Input',
      label: 'Your name',
      validation: z.string().min(1, 'Enter your name')
    }
  },
  steps: [
    { id: 'name', title: 'Your Name', fields: ['name'] }
  ]
})

// Use in your form component
function MyForm() {
  const { form, currentStep, goNext, goBack } = useFormOrchestrator({
    storageKey: myFormSpec.storageKey,
    version: myFormSpec.version,
    // ... other config
  })

  return (
    <StepContainer
      title={currentStep.title}
      onNext={goNext}
      onBack={goBack}
    >
      {/* Your form fields */}
    </StepContainer>
  )
}

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch mode for development
pnpm dev

# Type check
pnpm typecheck

License

MIT