@payfit/unity-components 2.55.14 → 2.55.16

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

@@ -4,9 +4,10 @@ description: >
   Load when building or migrating Unity forms. Use useTanstackUnityForm with
   schema validation and prefer Tanstack Form field APIs for composed fields,
   custom layouts, and validation behavior.
-type: core
-library: '@payfit/unity-components'
-library_version: '2.x'
+metadata:
+  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'
@@ -61,103 +62,14 @@ Wrapping order is load-bearing: `form.AppForm` provides the form context, `form.
 
 ## Core Patterns
 
-### Composed API (default)
+- Prefer composed `field.*Field` components for ordinary fields.
+- Use the atomic field parts only when custom layout or control composition is
+  required.
+- Default validation to blur; use dynamic validation for fields that need
+  blur-then-change behavior.
+- Narrow every `form.Subscribe` with a selector.
 
-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>
-```
+Read [references/patterns.md](references/patterns.md) for complete examples.
 
 ## Common Mistakes
 
@@ -181,9 +93,10 @@ 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.
+The legacy hook remains exported for compatibility but is deprecated. Do not
+author new code with it.
 
-Source: libs/shared/unity/components/src/hooks/use-form.tsx:79 (@deprecated JSDoc); maintainer interview
+Source: libs/shared/unity/components/src/hooks/use-form.tsx:79 (@deprecated JSDoc)
 
 ### CRITICAL Omit form.AppForm or form.AppField wrapping
 
@@ -329,7 +242,7 @@ Correct:
 
 `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)
+Source: TanstackTextField.tsx; TanstackFormField.tsx and its parts
 
 ## References
 

package/skills/unity-tanstack-form/references/patterns.md

@@ -0,0 +1,102 @@
+# Unity TanStack Form 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>
+```
+
+For fields listed in `fieldRevalidateLogic.fields`, use
+`onDynamic`/`onDynamicAsync` as the sole validator and omit those fields from
+the form-level schema; combining both leaves stale errors.
+
+### Optimal subscription with form.Subscribe + selector
+
+Pass a `selector` to `form.Subscribe` so it observes only the state needed by
+its children. A bare subscription re-renders on every form update.
+
+```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>
+```