feat(StateTaxes): respect applicable_if for conditional field visibility

[jeffredodd]

Summary

• Honors each TaxRequirement.applicable_if constraint when rendering the State Taxes form
• Adds isRequirementApplicable helper plus unit tests
• Drops inapplicable requirements from the submit payload so stale values aren't re-asserted
• Drops non-editable requirements from render + submit (matches legacy gws-flows prepare_requirements)
• Adds Playwright e2e coverage against the real demo backend via a new shared scenario

Fixes SDK-1057.

Context

The embedded API returns each TaxRequirement with an applicable_if: Array<{key, value}> field that gates visibility on the answers to other requirements in the same set. The SDK previously ignored it and rendered every requirement unconditionally — for example, Washington's taxrates set returns three rate inputs that are only meant to show when the user has answered "No, my agency gave me new rates" on a parent radio, but the SDK rendered them regardless. gws-flows has honored this contract via a small JS file for years, and the API rejects payloads that send answers for inapplicable requirements (QuestionNotApplicableDueToMismatchingDependentValues).

Reference impl confirmation

The shape was confirmed against three independent sources:

• API docstring (@gusto/embedded-api-v-2025-11-15/models/components/taxrequirement.d.ts): "This requirement is only applicable if all referenced requirements have values matching the corresponding value ... an empty array means the requirement is applicable."
• ZP (packs/.../tax_profiles/app/services/tax_profiles/states/core/read_api.rb:230-235): question.applicable_if.all? { |c| parent && parent.value == c.value }
• gws-flows (tax_requirements.js): same every-with-strict-equality logic, plus disabling the input so it isn't submitted.
• gws-flows edit.rb (prepare_requirements): the legacy edit-view step also filters editable == false requirements entirely; matched here.

Implementation

• New helper src/components/Company/StateTaxes/StateTaxesForm/applicableIf.ts evaluates applicableIf against the live RHF form values. Prefix-aware: constraints reference the raw API key; form values are stored under setKey.toRhfKey(reqKey).
• Form.tsx adds useWatch({ control }) and filters each requirement before rendering. Also drops editable === false requirements.
• The submit handler in StateTaxesForm.tsx reuses the helper to drop inapplicable requirements from the payload, and additionally drops non-editable ones.
• No Zod schema changes — every gated field was already .optional().

Test plan

Unit tests (always-on coverage of the conditional logic)

• isRequirementApplicable helper covers empty / single match / single mismatch / AND-logic / missing set / pipe-key round-trip (applicableIf.test.ts)
• WA 'renders tax rate fields' integration test was implicitly relying on the bug — updated to assert the rate input is hidden until the radio toggles to "No"
• New: 'does not render non-editable requirements' + 'omits non-editable requirements from the submit payload' against an editable: false row added to the WA fixture
• npm run test -- --run src/components/Company/StateTaxes/ passes (18/18)

E2E tests (Playwright, real-backend via new shared scenario)

The CI matrix runs e2e with E2E_USE_REAL_BACKEND=true, so the specs must work against the live demo backend rather than MSW. This PR introduces the infrastructure needed:

• New stateTaxes decoration in e2e/scenarios/schema/scenario.schema.json — scenarios can declare desired requirement_sets[].requirements[] answers per state.
• decorateStateTaxes in e2e/scenario/runner.ts is adaptive: GETs the current shape first, logs every discovered requirement (key, value, applicable_if gates, editable flag), and only PUTs the subset of declared answers that match a currently-applicable editable key with a different current value. Forging invariants the backend doesn't expose returns 422; the adaptive approach makes the scenario nudge the demo toward the declared state without breaking when the demo doesn't expose a question.
• Order matters: stateTaxes runs after employees because Gusto only surfaces state-tax requirement_sets once the company has nexus (an employee with a home address in the state). Locations alone are insufficient.
• New shared/state-taxes-wa-id.json scenario: fresh react_sdk_demo + WA & ID locations + two minimal employees (wa_employee, id_employee) whose home addresses establish nexus in each state.

Specs in e2e/tests/company/03-state-taxes-applicable-if.spec.ts:

• WA: asserts the form renders the demo's taxrates set with Unemployment Insurance Rate and EAF Tax Rate fields visible, plus an interactive Save button.
• ID: asserts the form renders UI Contribution Rate and the interactive Save button.

Scope note on applicable_if e2e coverage: the discovery dump from the scenario runner confirmed the demo backend's WA/ID taxrates sets surface only the resolved leaf requirements — Gusto's prepare_requirements collapses applicable_if when the underlying StateFilingRequirement has the gate already resolved, which is the demo factory's default. So the parent radios (usedefaultsuirates for WA, suireimbursable for ID) aren't in the real response, and there's no toggle to exercise here. The conditional logic itself is fully exercised by the unit tests above (which use MSW fixtures that DO carry the gating parent radio). When a future demo state exposes applicable_if-gated questions, these specs are already wired to hit it via the existing scenario decoration without further plumbing.

Run locally:

npx playwright test e2e/tests/company/03-state-taxes-applicable-if.spec.ts

Open review questions (called out in SDK-1057)

• Chained dependencies: ZP's flattened_ancestors in read_api.rb:667-674 suggests the API flattens grandparent constraints into each child's applicable_if before serializing. The helper relies on this — if the API ever ships unflattened chains, it would under-evaluate. No 3-deep fixture exists to prove it.
• null as a constraint value: The type allows value?: boolean | string | number | null. The helper uses ===, so undefined === null is false. If the API uses null to mean "matches when unanswered," this gets it wrong. Not exercised by any current fixture.

🤖 Generated with Claude Code

[kavinphan]

lgtm