@payfit/unity-components 2.35.4 → 2.35.5

package/skills/unity-tanstack-form/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: unity-tanstack-form
+description: >
+  Build any form in @payfit/unity-components with useTanstackUnityForm + Zod
+  (dynamic, translated). Layered wrapping: form.AppForm → form.Form →
+  form.AppField → field component. Composed API by default (TanstackTextField,
+  SelectField, NumberField, DatePickerField, CheckboxField, …); Atomic API
+  (field.Field + field.FieldLabel + field.TextInput) only when customizing
+  layout or parts. Schema adapters: StandardSchemaAdapter, ZodV3SchemaAdapter,
+  ZodV4SchemaAdapter. validators.onBlur is the default;
+  fieldRevalidateLogic for blur-then-change UX. React Hook Form
+  (useUnityForm + RHF *-field wrappers) is deprecated and will be REMOVED.
+type: core
+library: '@payfit/unity-components'
+library_version: '2.x'
+sources:
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/hooks/use-tanstack-form.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/hooks/use-form.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/form/TanstackForm.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/form-field/TanstackFormField.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/adapters/zodAdapter.ts'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/utils/field-revalidate-logic.ts'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/docs/concepts/forms/Form Architecture Overview.mdx'
+---
+
+Build a Unity form with `useTanstackUnityForm` + Zod. RHF (`useUnityForm`) is deprecated and will be removed.
+
+## Setup
+
+```tsx
+import { Button, useTanstackUnityForm } from '@payfit/unity-components'
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.email({ message: 'Invalid email' }),
+  password: z.string().min(8, { message: 'Password too short' }),
+})
+
+export function SignInForm() {
+  const form = useTanstackUnityForm({
+    defaultValues: { email: '', password: '' },
+    validators: { onBlur: schema },
+    onSubmit: async ({ value }) => {
+      await signIn(value)
+    },
+  })
+
+  return (
+    <form.AppForm>
+      <form.Form className="uy:space-y-200">
+        <form.AppField name="email">
+          {field => <field.TextField label="Email" type="email" />}
+        </form.AppField>
+        <form.AppField name="password">
+          {field => <field.PasswordField label="Password" />}
+        </form.AppField>
+        <Button variant="primary" type="submit">
+          Sign in
+        </Button>
+      </form.Form>
+    </form.AppForm>
+  )
+}
+```
+
+Wrapping order is load-bearing: `form.AppForm` provides the form context, `form.Form` renders the `<form>` element and wires `handleSubmit`, `form.AppField` provides field context, and the render-prop `field` carries every bound field component (TextField, PasswordField, SelectField, …) plus the Atomic parts (Field, FieldLabel, TextInput, FieldFeedbackText, FieldHelperText, FieldRawContextualLink).
+
+## Core Patterns
+
+### Composed API (default)
+
+Drop a single bound field component inside `<form.AppField>`. It bundles label, input, helper text, feedback, and a11y wiring.
+
+```tsx
+<form.AppField name="firstName">
+  {field => (
+    <field.TextField
+      label="First name"
+      helperText="As it appears on your ID"
+      isRequired
+    />
+  )}
+</form.AppField>
+
+<form.AppField name="country">
+  {field => (
+    <field.SelectField
+      label="Country"
+      options={[
+        { value: 'fr', label: 'France' },
+        { value: 'es', label: 'Spain' },
+      ]}
+    />
+  )}
+</form.AppField>
+```
+
+### Atomic API (only when customizing layout/parts)
+
+Reach for Atomic when you need to interleave custom content between the label and the input, or swap an input for a non-standard control. Wraps every part in `field.Field`.
+
+```tsx
+<form.AppField name="password">
+  {field => (
+    <field.Field>
+      <field.FieldLabel isRequired>Password</field.FieldLabel>
+      <field.FieldHelperText>Enter a strong password</field.FieldHelperText>
+      <field.TextInput type="password" />
+      <form.Subscribe selector={s => s.values.password}>
+        {password => (
+          <Text variant="bodySmallStrong">Length: {password.length}</Text>
+        )}
+      </form.Subscribe>
+      <field.FieldFeedbackText />
+    </field.Field>
+  )}
+</form.AppField>
+```
+
+### Validation timing
+
+`validators.onBlur` is the default; use `onChange` only for fields that need live feedback (password strength meter, search-as-you-type). `fieldRevalidateLogic` gives "blur until first error, then change" UX without polluting form-level validators.
+
+```tsx
+import { fieldRevalidateLogic, useTanstackUnityForm } from '@payfit/unity-components'
+
+const form = useTanstackUnityForm({
+  defaultValues: { email: '', password: '' },
+  validators: { onBlur: z.object({ email: z.email() }) },
+  validationLogic: fieldRevalidateLogic({
+    whenPristine: 'blur',
+    whenDirty: 'change',
+    fields: ['password'],
+  }),
+})
+
+<form.AppField
+  name="password"
+  validators={{
+    onDynamic: ({ value }) =>
+      value.length < 8 ? 'Password too short' : undefined,
+  }}
+>
+  {field => <field.PasswordField label="Password" />}
+</form.AppField>
+```
+
+Fields listed in `fieldRevalidateLogic.fields` MUST use `onDynamic`/`onDynamicAsync` as their sole validator and MUST NOT also appear in a form-level schema, or stale errors will linger.
+
+### Optimal subscription with form.Subscribe + selector
+
+Always pass a `selector` to `form.Subscribe`. A bare children-only subscription re-renders on every keystroke anywhere in the form.
+
+```tsx
+<form.Subscribe selector={s => s.values.password}>
+  {password => <Text>Length: {password.length}</Text>}
+</form.Subscribe>
+
+<form.Subscribe selector={s => [s.canSubmit, s.isSubmitting] as const}>
+  {([canSubmit, isSubmitting]) => (
+    <Button type="submit" isDisabled={!canSubmit} isLoading={isSubmitting}>
+      Submit
+    </Button>
+  )}
+</form.Subscribe>
+```
+
+## Common Mistakes
+
+### CRITICAL Import useForm (legacy RHF) instead of useTanstackUnityForm
+
+Wrong:
+
+```tsx
+import { useUnityForm } from '@payfit/unity-components'
+
+const { methods, Form, FormField } = useUnityForm(schema)
+```
+
+Correct:
+
+```tsx
+import { useTanstackUnityForm } from '@payfit/unity-components'
+
+const form = useTanstackUnityForm({ validators: { onBlur: schema } })
+```
+
+The legacy `use-form` hook is `@deprecated` but still exported; agents trained on older code reach for it and end up mixing RHF Controller with Tanstack field components, which breaks at runtime.
+
+Fixed-but-legacy-risk: the legacy hook is still exported but will be removed in the next few weeks (after or alongside the rebrand). Never author new code with it.
+
+Source: libs/shared/unity/components/src/hooks/use-form.tsx:79 (@deprecated JSDoc); maintainer interview
+
+### CRITICAL Omit form.AppForm or form.AppField wrapping
+
+Wrong:
+
+```tsx
+<form.Form>
+  <form.AppField name="email">
+    {field => <field.TextField label="Email" />}
+  </form.AppField>
+</form.Form>
+```
+
+Correct:
+
+```tsx
+<form.AppForm>
+  <form.Form>
+    <form.AppField name="email">
+      {field => <field.TextField label="Email" />}
+    </form.AppField>
+  </form.Form>
+</form.AppForm>
+```
+
+`useFormContext()` and `useFieldContext()` throw without their providers; Tanstack field components silently break (cannot read property of undefined).
+
+Source: TanstackForm.tsx:36; TanstackFormField.tsx:63 (useFormContext/useFieldContext)
+
+### CRITICAL Mix Tanstack field with react-hook-form Controller
+
+Wrong:
+
+```tsx
+const { control } = useForm()
+<Controller control={control} name="email" render={() => (
+  <TanstackTextField label="Email" />
+)} />
+```
+
+Correct:
+
+```tsx
+const form = useTanstackUnityForm({ validators: { onBlur: schema } })
+<form.AppForm><form.AppField name="email">
+  {field => <field.TextField label="Email" />}
+</form.AppField></form.AppForm>
+```
+
+RHF and Tanstack Form contexts do not interoperate; wrapping a Tanstack field in a Controller produces unmounted state and no validation.
+
+Source: conceptual; RHF and Tanstack contexts do not interoperate
+
+### HIGH Subscribe to whole form state instead of a selector
+
+Wrong:
+
+```tsx
+<form.Subscribe>
+  {state => <div>Length: {state.values.password.length}</div>}
+</form.Subscribe>
+```
+
+Correct:
+
+```tsx
+<form.Subscribe selector={s => s.values.password}>
+  {password => <div>Length: {password.length}</div>}
+</form.Subscribe>
+```
+
+A selector-less subscription re-renders the children on every keystroke anywhere in the form; pass a narrowing selector to scope to the slice you need.
+
+Source: use-tanstack-form.stories.tsx:251 (StateIntegration story)
+
+### MEDIUM Pick the wrong validation timing
+
+Wrong:
+
+```tsx
+useTanstackUnityForm({ validators: { onChange: schema } })
+```
+
+Correct:
+
+```tsx
+useTanstackUnityForm({ validators: { onBlur: schema } })
+// or with revalidation:
+// validationLogic: fieldRevalidateLogic({ fields: ['password'], whenDirty: 'change' })
+```
+
+`onChange` fires on every keystroke (jarring) and `onSubmit` waits until submit (errors arrive too late); `onBlur` is the usual default, with `fieldRevalidateLogic` reserved for "blur until first error, then change".
+
+Source: use-tanstack-form.stories.tsx:37-40; utils/field-revalidate-logic.ts
+
+### HIGH Mix Composed and Atomic APIs in one field (or reach for Atomic by default)
+
+Wrong:
+
+```tsx
+// Double-wrapping:
+<form.AppField name="email">
+  {field => (
+    <field.Field>
+      <field.FieldLabel>Email</field.FieldLabel>
+      <field.TextField label="Email" />
+    </field.Field>
+  )}
+</form.AppField>
+// Or reaching for Atomic with no customization reason:
+<form.AppField name="name">
+  {field => (
+    <field.Field>
+      <field.FieldLabel>Name</field.FieldLabel>
+      <field.TextInput />
+      <field.FieldFeedbackText />
+    </field.Field>
+  )}
+</form.AppField>
+```
+
+Correct:
+
+```tsx
+// Default (Composed):
+<form.AppField name="name">
+  {field => <field.TextField label="Name" />}
+</form.AppField>
+// Atomic only when customizing layout/parts:
+<form.AppField name="email">
+  {field => (
+    <field.Field>
+      <field.FieldLabel>Email</field.FieldLabel>
+      <CustomInline>
+        <field.TextInput />
+        <ExtraSlot />
+      </CustomInline>
+      <field.FieldFeedbackText />
+    </field.Field>
+  )}
+</form.AppField>
+```
+
+`field.TextField` is the Composed API and already includes label/input/feedback; wrapping it in `field.Field` + `field.FieldLabel` double-wraps and breaks layout + a11y. Default to Composed; reach for Atomic only when you must customize the field's layout or swap a part — never as the standard pattern.
+
+Source: TanstackTextField.tsx vs TanstackFormField.tsx + parts; maintainer interview (Composed is default)
+
+## References
+
+- [Bound field components](references/bound-field-components.md) — full inventory of `field.*` Composed components and their underlying base components.
+- [Schema adapters](references/schema-adapters.md) — StandardSchemaAdapter, ZodV3SchemaAdapter, ZodV4SchemaAdapter and how `isFieldRequired` consumes them.
+
+## See also
+
+- `unity-migrate-from-midnight` — forms migrated off Midnight typically came with React Hook Form; that skill explains the Tanstack-only replacement path.
+- `unity-layout-and-styling` — form layouts use Flex/Grid and `uy:*` utilities for spacing and responsive behavior.
+- `unity-navigation` — when a form posts via a route action or links to a sibling step, use the router-aware `Link` from `@payfit/unity-components/integrations/tanstack-router`.

package/skills/unity-tanstack-form/references/bound-field-components.md

@@ -0,0 +1,67 @@
+# Bound field components (Composed API)
+
+All 15 Tanstack-bound Composed field components, registered in `src/hooks/use-tanstack-form.tsx` via `createFormHook({ fieldComponents })`. They are exposed on the render-prop `field` object inside `<form.AppField>` WITHOUT the `Tanstack` prefix (e.g. the registered `TanstackTextField` is `field.TextField`).
+
+The form-usage pattern is identical for every component:
+
+```tsx
+<form.AppField name="fieldPath">
+  {field => <field.<Name> {...props} />}
+</form.AppField>
+```
+
+## Inventory
+
+| Registered name (in `useTanstackUnityForm`) | Source component (`Tanstack*`)                          | Wraps (non-bound base)                                                     | Notes                                                                                                                                                                                                                            |
+| ------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `field.TextField`                           | `TanstackTextField`                                     | `TextField` → `TanstackInput` / `TanstackTextArea`                         | `multiline` switches input/textarea. `type` (`text`/`password`/`email`/`tel`/`url`/`search`) only valid when `multiline !== true`.                                                                                               |
+| `field.SelectField`                         | `TanstackSelectField`                                   | `SelectField` → `TanstackSelect`                                           | Single-select with `options: { value, label }[]`.                                                                                                                                                                                |
+| `field.MultiSelectField`                    | `TanstackMultiSelectField`                              | `MultiSelectField` → `TanstackMultiSelect`                                 | Generic component; chips for selected items.                                                                                                                                                                                     |
+| `field.NumberField`                         | `TanstackNumberField`                                   | `NumberField` → `TanstackNumberInput`                                      | Locale-aware number formatting.                                                                                                                                                                                                  |
+| `field.CheckboxField`                       | `TanstackCheckboxField`                                 | `CheckboxField` → `TanstackCheckbox`                                       | Single checkbox + label + feedback.                                                                                                                                                                                              |
+| `field.CheckboxGroupField`                  | `TanstackCheckGroupField`                               | `CheckGroupField` → `TanstackCheckboxGroup`                                | Multi-checkbox group; value is `string[]`. Note the registered key is `CheckboxGroupField` even though the implementation is named `TanstackCheckGroupField`.                                                                    |
+| `field.RadioButtonGroupField`               | `TanstackRadioButtonGroupField`                         | `RadioButtonGroupField` → `TanstackRadioButtonGroup`                       | Single-select radio group.                                                                                                                                                                                                       |
+| `field.SelectableButtonGroupField`          | `TanstackSelectableButtonGroupField`                    | `SelectableButtonGroupField` → `TanstackSelectableButtonGroup`             | Pill-style segmented control.                                                                                                                                                                                                    |
+| `field.SelectableCardCheckboxGroupField`    | `TanstackSelectableCardCheckboxGroupField`              | `SelectableCardCheckboxGroupField` → `TanstackSelectableCardCheckboxGroup` | Multi-select card grid.                                                                                                                                                                                                          |
+| `field.SelectableCardRadioGroupField`       | `TanstackSelectableCardRadioGroupField`                 | `SelectableCardRadioGroupField` → `TanstackSelectableCardRadioGroup`       | Single-select card grid.                                                                                                                                                                                                         |
+| `field.DatePickerField`                     | `TanstackDatePickerField`                               | `DatePickerField` → `TanstackDatePicker`                                   | Single-date popover picker.                                                                                                                                                                                                      |
+| `field.DateRangePickerField`                | `TanstackDateRangePickerField`                          | `DateRangePickerField` → `TanstackDateRangePicker`                         | Start/end range picker.                                                                                                                                                                                                          |
+| `field.ToggleSwitchField`                   | `TanstackToggleSwitchField`                             | `ToggleSwitchField` → `TanstackToggleSwitch`                               | Single boolean switch.                                                                                                                                                                                                           |
+| `field.ToggleSwitchGroupField`              | `TanstackToggleSwitchGroupField`                        | `ToggleSwitchGroupField` → `TanstackToggleSwitchGroup`                     | Group of switches; value is a record.                                                                                                                                                                                            |
+| `field.PasswordField`                       | `TanstackPasswordField` (registered as `PasswordField`) | `PasswordField` → `TanstackInput` (`type="password"`)                      | Adds visibility toggle button. The registered key is `PasswordField` (no `Tanstack` prefix in the source) — so usage is `field.PasswordField`. Prefer this over `<field.TextField type="password" />` for the visibility toggle. |
+| `field.PhoneNumberField`                    | `TanstackPhoneNumberField`                              | `PhoneNumberField` → `TanstackPhoneNumberInput`                            | E.164-compatible phone input.                                                                                                                                                                                                    |
+
+## Atomic parts (always available on `field`)
+
+These are the Atomic API parts registered alongside the Composed components. Use them only when customizing layout:
+
+- `field.Field` — the wrapper (`TanstackFormField`). Provides a11y context.
+- `field.FieldLabel` — label slot.
+- `field.FieldHelperText` — helper text slot.
+- `field.FieldFeedbackText` — validation error slot.
+- `field.FieldRawContextualLink` — contextual link slot.
+
+And the raw inputs (use Composed instead unless customizing):
+
+- `field.TextInput` / `field.TextAreaInput`
+- `field.CheckboxInput` / `field.CheckboxGroupInput`
+- `field.NumberInput`
+- `field.SelectInput` / `field.MultiSelectInput`
+- `field.RadioButtonInput`
+- `field.SelectableButtonGroupInput`
+- `field.SelectableCardCheckboxGroupInput` / `field.SelectableCardRadioGroupInput`
+- `field.DatePickerInput` / `field.DateRangePickerInput`
+- `field.ToggleSwitchInput` / `field.ToggleSwitchGroupInput`
+- `field.PhoneNumberInput`
+
+## Form-scoped components
+
+Available on `form` (not `field`):
+
+- `<form.AppForm>` — form-context provider. Required outer wrapper.
+- `<form.Form>` — `<form>` element wired to `handleSubmit`.
+- `<form.AppField name="…">` — field-context provider; render-prop exposes `field`.
+- `<form.Subscribe selector={…}>` — selector-scoped reactive subscription. Always pass `selector`.
+- `<form.InlineFieldGroup>`, `<form.InlineFieldGroupHeader>`, `<form.InlineFieldGroupReadView>`, `<form.InlineFieldGroupEditView>` — inline edition layout (read view ↔ edit view toggling for grouped fields).
+
+For the mapping source of truth see `src/hooks/use-tanstack-form.tsx` (the `createFormHook` call). The keys in `fieldComponents` and `formComponents` are exactly the names exposed on `field` / `form`.

package/skills/unity-tanstack-form/references/schema-adapters.md

@@ -0,0 +1,108 @@
+# Schema adapters
+
+Schema adapters give the form-field organisms a uniform way to ask "is this path required?" across schemas authored in Zod 3, Zod 4, or any Standard Schema v1 implementation. Source: `src/adapters/`.
+
+## Common interface
+
+```ts
+// src/types/schema.ts
+export interface StandardSchemaField {
+  isOptional: boolean
+  type: string
+  shape?: Record<string, StandardSchemaField>
+}
+
+export interface StandardSchema {
+  getField(path: string): StandardSchemaField | null
+}
+```
+
+`getField('preferences.marketing')` returns `null` if the path does not exist, otherwise `{ isOptional, type, shape }`. `shape` is only populated when the field resolves to a nested `ZodObject` (so callers can recurse into nested forms).
+
+## Adapters
+
+### ZodV3SchemaAdapter
+
+Signature:
+
+```ts
+new ZodV3SchemaAdapter(schema: z3.ZodObject<z3.ZodRawShape>)
+```
+
+- Reads structure from `schema.shape` and `field._def.typeName`.
+- Detects optional with `field instanceof z3.ZodOptional`; unwraps via `field._def.innerType`.
+- Source: `src/adapters/zodAdapter.ts` (lines 6–60).
+
+### ZodV4SchemaAdapter
+
+Signature:
+
+```ts
+new ZodV4SchemaAdapter(schema: z4.ZodObject<z4.ZodRawShape>)
+```
+
+- Same shape traversal as v3, but uses `field.def.innerType` and `field.def.typeName` (no underscore — Zod 4 renamed `_def` to `def`).
+- `field instanceof z4.ZodOptional` for optionality detection.
+- Source: `src/adapters/zodAdapter.ts` (lines 62–117).
+
+### StandardSchemaAdapter
+
+Signature:
+
+```ts
+new StandardSchemaAdapter(standardSchema: StandardSchemaV1)
+```
+
+- Stub implementation: `getField()` returns `{ isOptional: false, type: 'unknown', shape: undefined }` for any non-null path. Standard Schema's spec does not expose enough internal structure for richer introspection.
+- Use this only for schemas that aren't Zod (e.g. Valibot, ArkType) — required-field inference will degrade to "always required".
+- Source: `src/adapters/standardSchemaAdapter.ts`.
+
+## How adapters auto-select
+
+`createSchemaAdapter(schema)` (in `src/utils/createSchemaAdapter.ts`) picks an adapter from the schema's structural fingerprint:
+
+```ts
+import { createSchemaAdapter } from '@payfit/unity-components'
+
+const adapter = createSchemaAdapter(schema)
+// schema._def && 'def' in schema           → ZodV4SchemaAdapter
+// schema._def && !('def' in schema)        → ZodV3SchemaAdapter
+// schema['~validate'] is a function        → StandardSchemaAdapter
+// otherwise                                → null
+```
+
+You rarely call this directly: every Composed field organism (e.g. `TanstackTextField`, `TanstackCheckboxField`, `TanstackToggleSwitchGroupField`) calls `createSchemaAdapter` + `isFieldRequired` internally to render the required indicator on the label.
+
+## isFieldRequired
+
+Consumer of the adapter, used inside every Composed field to decide whether to mark the label as required.
+
+```ts
+// src/components/form-field/utils/isFieldRequired.ts
+export function isFieldRequired(
+  schema: StandardSchema | null | undefined,
+  fieldPath: string,
+): boolean {
+  if (!schema) return false
+  const field = schema.getField(fieldPath)
+  return field ? !field.isOptional : false
+}
+```
+
+Behavior:
+
+- No schema → `false` (no required indicator).
+- Path not found in schema → `false` (treat as not required rather than crashing).
+- Field is `ZodOptional` → `false`.
+- Field is anything else → `true`.
+
+This is why `<form.AppField name="email">{field => <field.TextField label="Email" />}</form.AppField>` automatically gets a required asterisk when `email` is `z.email()` and no asterisk when it's `z.email().optional()` — without any prop wiring.
+
+## When to import an adapter explicitly
+
+Almost never. The Composed field components call `createSchemaAdapter(schema)` themselves. Import an adapter directly only when:
+
+- You are writing a custom field component outside the Composed inventory and need required-state inference.
+- You are introspecting a schema for non-form purposes (form-derived UI, dynamic field rendering).
+
+Even then, prefer `createSchemaAdapter(schema)` so the right version is picked at runtime.