@payfit/unity-components 2.55.13 → 2.55.15

package/skills/unity-overlays/references/patterns.md

@@ -0,0 +1,131 @@
+# Unity overlay patterns
+
+### Dialog with DialogTrigger + DialogActions
+
+```tsx
+import {
+  Button,
+  Dialog,
+  DialogActions,
+  DialogButton,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from '@payfit/unity-components'
+
+export function ArchiveDialog({ onArchive }: { onArchive: () => void }) {
+  return (
+    <DialogTrigger>
+      <Button>Archive</Button>
+      <Dialog size="md">
+        <DialogTitle>Archive this employee?</DialogTitle>
+        <DialogContent>
+          They will no longer appear in active lists. You can restore them
+          later.
+        </DialogContent>
+        <DialogActions>
+          <DialogButton variant="close">Cancel</DialogButton>
+          <DialogButton variant="confirm" onPress={onArchive}>
+            Archive
+          </DialogButton>
+        </DialogActions>
+      </Dialog>
+    </DialogTrigger>
+  )
+}
+```
+
+### SidePanel for detail views
+
+```tsx
+import { useState } from 'react'
+
+import {
+  Button,
+  SidePanel,
+  SidePanelContent,
+  SidePanelFooter,
+  SidePanelHeader,
+} from '@payfit/unity-components'
+
+export function EmployeeDetailPanel({ employee }: { employee: Employee }) {
+  const [isOpen, setIsOpen] = useState(false)
+
+  return (
+    <>
+      <Button onPress={() => setIsOpen(true)}>View details</Button>
+      <SidePanel isOpen={isOpen} onOpenChange={setIsOpen}>
+        <SidePanelHeader>{employee.name}</SidePanelHeader>
+        <SidePanelContent>
+          <p>{employee.position}</p>
+          <p>{employee.team}</p>
+        </SidePanelContent>
+        <SidePanelFooter>
+          <Button variant="secondary" onPress={() => setIsOpen(false)}>
+            Close
+          </Button>
+        </SidePanelFooter>
+      </SidePanel>
+    </>
+  )
+}
+```
+
+### Popover for interactive informational content
+
+`title` is required (use `isTitleSrOnly` if you don't want it visible).
+Children may be focusable; the Popover is non-modal so the page stays
+interactive behind it.
+
+```tsx
+import { Button, Popover, PopoverTrigger } from '@payfit/unity-components'
+
+export function HelpPopover() {
+  return (
+    <PopoverTrigger>
+      <Button variant="tertiary">What is a working agreement?</Button>
+      <Popover title="Working agreement">
+        <p>
+          A working agreement defines when, where and how an employee works. See
+          the <a href="/handbook/working-agreement">handbook</a> for details.
+        </p>
+      </Popover>
+    </PopoverTrigger>
+  )
+}
+```
+
+### Menu for action lists
+
+`Menu` expects exactly two children: a trigger and a content block. Use
+`MenuTrigger` / `MenuContent` / `RawMenuItem` for the standard composition.
+
+```tsx
+import {
+  IconButton,
+  Menu,
+  MenuContent,
+  MenuTrigger,
+  RawMenuItem,
+} from '@payfit/unity-components'
+
+export function RowActions({
+  onEdit,
+  onArchive,
+}: {
+  onEdit: () => void
+  onArchive: () => void
+}) {
+  return (
+    <Menu>
+      <MenuTrigger>
+        <IconButton icon="MoreFilled" title="Actions" />
+      </MenuTrigger>
+      <MenuContent>
+        <RawMenuItem onAction={onEdit}>Edit</RawMenuItem>
+        <RawMenuItem onAction={onArchive}>Archive</RawMenuItem>
+      </MenuContent>
+    </Menu>
+  )
+}
+```

package/skills/unity-setup-feature-plugin/SKILL.md

@@ -7,9 +7,10 @@ description: >
   → I18nProvider (react-aria-components) → UnityIconsProvider. Import
   @payfit/unity-themes/css/unity.css once. Merge @payfit/unity-components/i18n
   JSON into the IntlProvider messages, keyed by locale.
-type: lifecycle
-library: '@payfit/unity-components'
-library_version: '2.x'
+metadata:
+  type: lifecycle
+  library: '@payfit/unity-components'
+  library_version: '2.x'
 sources:
   - 'PayFit/hr-apps:libs/shared/unity/components/src/docs/tutorials/Getting Started.mdx'
   - 'PayFit/hr-apps:libs/shared/unity/icons/src/components/icons-provider/UnityIconsProvider.tsx'

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>
+```