feat: add useEmployeeDetailsForm hook with configurable required fields

[serikjensen]

Summary

Adds the useEmployeeDetailsForm hook and EmployeeDetailsForm component with a schema-driven approach to configurable required fields. Partners can specify which fields are required per mode via requiredFields: { create: ['email'], update: ['ssn'] }, with the schema as the single source of truth for both validation and UI metadata (isRequired indicators).

Key changes

• requiredIf utility (src/helpers/requiredIf.ts) — conditionally makes a Zod validator optional using z.preprocess, compatible with z.toJSONSchema()
• composeFormSchema utility — reusable schema builder that takes fieldValidators, applies mode-specific API defaults (requiredOnCreate), and partner requiredFields overrides via requiredIf
• deriveFieldsMetadata — updated to use z.toJSONSchema() for accurate isRequired detection, making the schema the single source of truth for UI metadata
• useEmployeeDetailsForm hook — full create/update lifecycle with self-onboarding toggle, SSN redaction (hasRedactedValue metadata), and hasSsn schema option to skip SSN requirement when already on file
• EmployeeDetailsForm component — reference implementation consuming the hook
• Compensation schema refactor — migrated stateWcCovered, rate, and startDate from z.transform/z.date()/z.nan() to z.preprocess/z.iso.date() for toJSONSchema compatibility, with types derived from a single fieldValidators object (same pattern as employee details)
• DatePickerField string mode — accepts and returns ISO date strings (YYYY-MM-DD) in addition to Date objects
• SwitchHookField — new hook-connected field component for boolean toggles

Schema pattern established

All form schemas follow a consistent pattern:

1. Define field validators once in a fieldValidators object
2. Derive FormData type from fieldValidators via mapped type
3. Build the runtime schema via composeFormSchema (for configurable fields) or spread + preprocess overrides (for type coercion)
4. Use superRefine only for cross-field validations that depend on runtime form values
5. Use schema options (like hasSsn) for static prop-based exceptions resolved at construction time

Test plan

• Unit tests for deriveFieldsMetadata with requiredIf scenarios (6 new test cases)
• Unit tests for useEmployeeDetailsForm hook (create, update, validation, self-onboarding, SSN handling — 12 test cases)
• Compensation form tests still passing (4 tests)
• TypeScript compilation clean
• Manual testing: create mode validation, self-onboarding + email cross-validation, successful create, update mode with required SSN, successful update, SSN not required when hasSsn is true

Screen.Recording.2026-03-24.at.11.52.08.PM.mov

Made with Cursor