refactor(form): add useHeadlessForm and move contract details and basic information onto it

[gabrielseco]

Summary

Adds one shared, tested way for the embeddable flows to build and validate their forms, and moves the Onboarding contract details and basic information steps onto it.

Why

• Each flow builds and validates its forms with its own hand-written copy of the same logic. Each copy can break on its own, as the money-in-cents bug fixed in fix(form): restore money conversion in createHeadlessForm when options are passed  #1429 did in one of them, and no shared test notices.
• Testing every schema situation in every flow doesn't scale. With one shared piece, schema situations are tested once and each flow only needs one smoke test proving it uses that piece.
• The shared piece offers both behaviours flows use today: rebuild the form on every change (old), or build it once and resolve conditional fields through validation (new). The goal is for every form to build once.
• Contract details already uses both behaviours (older countries rebuild, jsf v1 countries build once), so moving it first proves both strategies against real flows. Basic information goes straight to building once, which shows a step can skip the in-between phase.

What changed

Toggle details

• src/common/useHeadlessForm.ts (internal, not exported): returns { form, handleValidation, onValuesChange, parseFormValues }.
  • rebuild takes values: createHeadlessForm(schema, values, options), rebuilt when values change. Validation uses isPartialValidation: false.
  • buildOnce takes optional initialValues (saved values, in API units): built once per schema/options with transformMoneyFields: false, validation with isPartialValidation: true. The first build is seeded with initialValues, so visibility is right on the first render without a mounted step or a validation effect, which is what headless useOnboarding() consumers and a read-only employment jumping to review rely on. When jsfModify changes, the form is rebuilt from the last validated values, so fields the user opened or closed stay that way. A new schema starts again from initialValues. The comment explaining why invisible values are kept moved here from hooks.tsx.
  • options and initialValues are compared by value (fast-deep-equal, as useJSONSchemaForm already does), so objects created during render don't rebuild the form on every render.
• Legacy contract details (useLegacyContractDetailsSchema in src/flows/Onboarding/api.ts, rebuild): only building moves to the hook. Validation and submit parsing for this step still go through the hand-written branches in hooks.tsx.
• jsf v1 contract details (useContractDetailsSchema, buildOnce): building, validation and submit parsing all go through the hook. It is seeded with the saved contract details (onboardingInitialValues + employment.contract_details), already in cents, so nothing is converted twice. The fieldsCount state that forced a re-render after each validation is gone, since the hook re-renders itself. The unused transformMoneyFields option on this internal hook is removed.
• Basic information (new useBasicInformationSchema, buildOnce): replaces the useJSONSchema wrapper, which no Onboarding step uses anymore. Building, validation, submit parsing and value changes all go through the hook, seeded with onboardingInitialValues + employment.basic_information. Behaviour change: like every buildOnce form, validation keeps invisible values until handleValidation resolves visibility, instead of dropping them first. The step's initialValues memos now share the same saved-values objects as the hooks.
• Contract details query keys (both steps): the schema request sends employment_id, but the keys only held country and schema version, so one employment's schema was served to every other employment of the same country in the session. The keys now include the request query.
• Rollout doc docs/USE_HEADLESS_FORM_ROLLOUT.md: phases, the per-step checklist from refactor(onboarding): build the basic information schema once #1430, and every call site with its status. Basic information is done, legacy contract details is phase 1.
• Tests
  • src/common/tests/jsfEngineContract.test.tsx renders the real useJSONSchemaForm + JSONSchemaFormFields, so ForcedValueField's setValue loop runs, with real clicks and typing. Grid: situations × engines (jsf v0, jsf v1, no meta) × strategies × options. It starts with a forced money value computed from another money field (the PRT allowance) and a radio that reveals a conditional money field (PRT signing bonus).
  • The same file's buildOnce lifecycle block runs on every engine: initialValues show the right fields on the first render and when they arrive after the schema, fields the user revealed or hid survive a jsfModify change (over initialValues), and a new schema starts from initialValues. Breaking the hook on purpose (ignoring initialValues, ignoring the last validated values, reusing them across schemas) fails the matching tests on all three engines.
  • Smoke tests per step: fix(form): restore money conversion in createHeadlessForm when options are passed  #1429's PRT extended-hours flow test fails when the hook's rebuild stops converting to cents. France's flow tests and useOnboardingJsfV1ContractDetails.test.tsx fail when the hook's buildOnce validation is broken.
  • useOnboardingJsonSchemaVersion.test.tsx: the mocked schema gains x-jsf-presentation, like every real schema (all 20 root fixture schemas have it). The hook builds during render, not inside a React Query select, so the money conversion's lookup no longer turns a malformed schema into a silent query error.

Known behaviour on the legacy (rebuild) step, unchanged by this PR and shared with #1429: on the first render of a prefilled step, server values already in cents are converted again, so a probe computed the PRT allowance as 8125770 before it settled on 81257 once the step mounted. Users never see it. Anything that reads the form before the step mounts could, and that isn't verified. It goes away once that step switches to buildOnce.

No public API change: nothing new is exported from src/index.tsx or internals. useContractDetailsSchema, useBasicInformationSchema and useJsfV1ContractDetails are internal.

Screenshots

N/A

Related Resources

• Follows fix(form): restore money conversion in createHeadlessForm when options are passed  #1429 (merged)
• Earlier build-once attempt and its pitfalls: refactor(onboarding): build the basic information schema once #1430
• Lint enforcement stacked on this PR: chore(lint): enforce useHeadlessForm over direct createHeadlessForm imports #1439

Testing

• npx vitest run src/common/tests/jsfEngineContract.test.tsx

• npx vitest run src/flows/Onboarding/tests/OnboardingFlow.test.tsx -t "extended work hours allowance" (legacy step)

• npx vitest run src/flows/Onboarding/tests/OnboardingFlowFrance.test.tsx src/flows/Onboarding/tests/useOnboardingJsfV1ContractDetails.test.tsx (jsf v1 step)

• Tested against the example/ app in a browser

• Feature flag: N/A

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches onboarding contract details and basic information validation/money handling and query caching keys; behaviour shifts for buildOnce steps (partial validation, initialValues seeding) though covered by new contract tests.

Overview
Introduces an internal useHeadlessForm hook that centralizes JSON Schema form build/validate/parse with two strategies: rebuild (re-create the form on value changes) and buildOnce (single build, partial validation for conditionals, stable initialValues/jsfModify via deep equality).

Onboarding moves onto this hook: legacy contract details use rebuild via useLegacyContractDetailsSchema; jsf v1 contract details and basic information use buildOnce with dedicated schema hooks, wiring validation/parse (and value-change for basic info) through the hook instead of duplicated hooks.tsx logic. Contract-details React Query keys now include the request query (e.g. employment_id) so schemas are not shared across employments.

Adds schema situation unit tests (jsfEngineSituations.ts + jsfEngineContract.test.tsx) run across jsf engines, strategies, and options, plus buildOnce lifecycle cases. Documents the rollout in docs/USE_HEADLESS_FORM_ROLLOUT.md and expands testing guidance in ARCHITECTURE.md, CLAUDE.md, and BUGBOT.md (form bugs need a failing situation). Tweaks a jsonSchemaVersion test mock to include x-jsf-presentation.

No new public exports from the package entry points.

^{Reviewed by Cursor Bugbot for commit 0cafa51. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

📦 Bundle Size Report

Metric	Current	Previous	Change	Status
Total (gzip)	223.31 kB	222.56 kB	+746 B (+0.3%)	🔴
Total (raw)	624.77 kB	622.83 kB	+1.94 kB (+0.3%)	🔴
CSS (gzip)	21.94 kB	21.94 kB	0 B (0%)	🟢
CSS (raw)	114.43 kB	114.43 kB	0 B (0%)	🟢

Size Limits

• ✅ Total gzipped: 223.31 kB / 350 kB (63.8%)
• ✅ Total raw: 624.77 kB / 850 kB (73.5%)
• ✅ CSS gzipped: 21.94 kB / 25 kB (87.8%)

Largest Files (Top 5)

1. index.esm-wIkXrqU6.js - 11.4 kB (0 B (0%))
2. styles.css - 10.97 kB (0 B (0%))
3. index.css - 10.97 kB (0 B (0%))
4. internals-D0_df-Qx.js - 6.14 kB (new)
5. hooks-FsZb16ry.js - 5.81 kB (new)

View All Files (283 total)

File	Size (gzip)	Change
index.esm-wIkXrqU6.js	11.4 kB	0 B (0%)
styles.css	10.97 kB	0 B (0%)
index.css	10.97 kB	0 B (0%)
internals-D0_df-Qx.js	6.14 kB	new
hooks-FsZb16ry.js	5.81 kB	new
sdk.gen-hikpofx9.js	5.48 kB	0 B (0%)
index.js	5.45 kB	0 B (0%)
flows/Onboarding/hooks.js	4.33 kB	-93 B (-2.1%)
utils-qfe-oQBs.js	4.07 kB	0 B (0%)
FieldSetField-Bds5UIuj.js	4.03 kB	0 B (0%)

✅ Bundle size check passed

[github-actions]

Deploy preview for remote-flows ready!

Project:	remote-flows
Status:	✅  Deploy successful!
Preview URL:	https://remote-flows-5s4qrezw1-remotecom.vercel.app
Latest Commit:	0cafa51

Deployed with vercel-action

[github-actions]

Deploy preview for adp-cost-calculator ready!

Project:	adp-cost-calculator
Status:	✅  Deploy successful!
Preview URL:	https://adp-cost-calculator-hbf5j7u26-remotecom.vercel.app
Latest Commit:	0cafa51

Deployed with vercel-action

[github-actions]

📊 Coverage Report

✅ Coverage increased! 🎉

Metric	Current	Previous	Change	Status
Lines	86.46%	86.41%	+0.06%	🟢
Statements	86.02%	85.97%	+0.05%	🟢
Functions	85.04%	84.92%	+0.12%	🟢
Branches	77.97%	77.95%	+0.02%	🟢

Detailed Breakdown

Lines Coverage

• Covered: 4899 / 5666
• Coverage: 86.46%
• Change: +0.06% (43 lines)

Statements Coverage

• Covered: 4985 / 5795
• Coverage: 86.02%
• Change: +0.05% (45 statements)

Functions Coverage

• Covered: 1302 / 1531
• Coverage: 85.04%
• Change: +0.12% (12 functions)

Branches Coverage

• Covered: 3040 / 3899
• Coverage: 77.97%
• Change: +0.02% (28 branches)

✅ Coverage check passed