@payfit/unity-components 2.55.14 → 2.55.15

package/skills/unity-navigation/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when building Unity links, tabs, breadcrumbs, nav, or pagination. Use it
   to choose router-aware Tanstack Router components versus Raw* href
   primitives.
-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/components/link/RawLink.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/breadcrumbs/Breadcrumbs.tsx'
@@ -73,119 +74,14 @@ export function EmployeesShell() {
 
 ## Core Patterns
 
-### Raw and integration map
+- Use router-aware integration exports in TanStack Router features and `Raw*`
+  primitives for explicit `href` navigation.
+- Preserve the required Breadcrumbs, Pagination, and Tabs composition.
+- In non-TanStack applications, provide the appropriate router adapter before
+  using `Raw*` navigation components.
 
-| Base entry (`@payfit/unity-components`) | Integration (`@payfit/unity-components/integrations/tanstack-router`) | Prop                                    |
-| --------------------------------------- | --------------------------------------------------------------------- | --------------------------------------- |
-| `RawLink`                               | `Link`                                                                | `href` (raw) / `to` (integration)       |
-| `RawNavItem`                            | `NavItem`                                                             | same                                    |
-| `RawBreadcrumbLink`                     | `BreadcrumbLink`                                                      | same                                    |
-| `RawPaginationLink`                     | `PaginationLink`                                                      | same                                    |
-| `RawTab` (+ `Tabs`)                     | `Tab` (+ `Tabs`)                                                      | route-aware `to` selects the active tab |
-| `RawLinkButton`                         | `LinkButton`                                                          | same                                    |
-
-The integration components are produced via `createLink(RawLink)`. They render
-exactly the same DOM as the raw versions but accept Tanstack's typed `to`,
-`params`, `search`, and `preload` props.
-
-### Compose Breadcrumbs / Pagination / Tabs
-
-Each navigation composite has a strict child contract. Direct children of the
-container must be the wrapper part — loose children are silently filtered.
-
-```tsx
-import {
-  Breadcrumb,
-  BreadcrumbLink,
-  Breadcrumbs,
-  Pagination,
-  PaginationContent,
-  PaginationItem,
-  RawPaginationLink,
-  RawTab,
-  TabList,
-  TabPanel,
-  Tabs,
-} from '@payfit/unity-components'
-
-export function CompositionExamples({
-  page,
-  pageCount,
-  onPageChange,
-}: {
-  page: number
-  pageCount: number
-  onPageChange: (next: number, prev: number, dir: -1 | 1) => void
-}) {
-  return (
-    <>
-      <Breadcrumbs>
-        <Breadcrumb>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </Breadcrumb>
-        <Breadcrumb>
-          <BreadcrumbLink href="/employees">Employees</BreadcrumbLink>
-        </Breadcrumb>
-      </Breadcrumbs>
-
-      <Pagination
-        currentPage={page}
-        pageCount={pageCount}
-        onPageChange={onPageChange}
-      >
-        <PaginationContent>
-          {Array.from({ length: pageCount }, (_, i) => i + 1).map(n => (
-            <PaginationItem key={n}>
-              <RawPaginationLink value={n} isActive={n === page}>
-                {n}
-              </RawPaginationLink>
-            </PaginationItem>
-          ))}
-        </PaginationContent>
-      </Pagination>
-
-      <Tabs>
-        <TabList>
-          <RawTab id="active">Active</RawTab>
-          <RawTab id="archived">Archived</RawTab>
-        </TabList>
-        <TabPanel id="active">Active rows</TabPanel>
-        <TabPanel id="archived">Archived rows</TabPanel>
-      </Tabs>
-    </>
-  )
-}
-```
-
-### RouterProvider for Raw\* in non-Tanstack apps
-
-When you use `Raw*` components in an app that uses a different router (e.g.
-React Router), wrap the app once in `RouterProvider` so `isActive` and
-client-side navigation work. The Tanstack integration entry does NOT need
-this — it reads from Tanstack hooks directly.
-
-```tsx
-import { RouterProvider } from '@payfit/unity-components'
-import { matchPath, useLocation, useNavigate } from 'react-router-dom'
-
-export function UnityRouterBridge({ children }: { children: React.ReactNode }) {
-  const navigate = useNavigate()
-  const location = useLocation()
-
-  return (
-    <RouterProvider
-      navigate={to => navigate(to)}
-      isActive={(to, isExact) =>
-        Boolean(
-          matchPath({ path: to, end: Boolean(isExact) }, location.pathname),
-        )
-      }
-    >
-      {children}
-    </RouterProvider>
-  )
-}
-```
+Read [references/patterns.md](references/patterns.md) for complete compositions
+and provider examples.
 
 ## Common Mistakes
 
@@ -260,7 +156,7 @@ import { Pagination, PaginationContent, PaginationItem, RawPaginationLink }
 
 v2 Pagination is compositional; passing currentPage/pageCount with no children renders an empty container. The old monolithic component (ClientSidePagination) now lives only inside DataTable as an internal — there is no public monolithic export. For standalone pagination, compose it yourself; for paginated tables, use DataTable which has it built in.
 
-Source: components/pagination/Pagination.tsx; index.ts; maintainer interview (ClientSidePagination is internal to DataTable)
+Source: components/pagination/Pagination.tsx; index.ts
 
 ### MEDIUM Forget to wrap BreadcrumbLink in Breadcrumb
 

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

@@ -0,0 +1,115 @@
+# Unity navigation patterns
+
+### Raw and integration map
+
+| Base entry (`@payfit/unity-components`) | Integration (`@payfit/unity-components/integrations/tanstack-router`) | Prop                                    |
+| --------------------------------------- | --------------------------------------------------------------------- | --------------------------------------- |
+| `RawLink`                               | `Link`                                                                | `href` (raw) / `to` (integration)       |
+| `RawNavItem`                            | `NavItem`                                                             | same                                    |
+| `RawBreadcrumbLink`                     | `BreadcrumbLink`                                                      | same                                    |
+| `RawPaginationLink`                     | `PaginationLink`                                                      | same                                    |
+| `RawTab` (+ `Tabs`)                     | `Tab` (+ `Tabs`)                                                      | route-aware `to` selects the active tab |
+| `RawLinkButton`                         | `LinkButton`                                                          | same                                    |
+
+The integration components are produced via `createLink(RawLink)`. They render
+exactly the same DOM as the raw versions but accept Tanstack's typed `to`,
+`params`, `search`, and `preload` props.
+
+### Compose Breadcrumbs / Pagination / Tabs
+
+Each navigation composite has a strict child contract. Direct children of the
+container must be the wrapper part — loose children are silently filtered.
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbLink,
+  Breadcrumbs,
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  RawPaginationLink,
+  RawTab,
+  TabList,
+  TabPanel,
+  Tabs,
+} from '@payfit/unity-components'
+
+export function CompositionExamples({
+  page,
+  pageCount,
+  onPageChange,
+}: {
+  page: number
+  pageCount: number
+  onPageChange: (next: number, prev: number, dir: -1 | 1) => void
+}) {
+  return (
+    <>
+      <Breadcrumbs>
+        <Breadcrumb>
+          <BreadcrumbLink href="/">Home</BreadcrumbLink>
+        </Breadcrumb>
+        <Breadcrumb>
+          <BreadcrumbLink href="/employees">Employees</BreadcrumbLink>
+        </Breadcrumb>
+      </Breadcrumbs>
+
+      <Pagination
+        currentPage={page}
+        pageCount={pageCount}
+        onPageChange={onPageChange}
+      >
+        <PaginationContent>
+          {Array.from({ length: pageCount }, (_, i) => i + 1).map(n => (
+            <PaginationItem key={n}>
+              <RawPaginationLink value={n} isActive={n === page}>
+                {n}
+              </RawPaginationLink>
+            </PaginationItem>
+          ))}
+        </PaginationContent>
+      </Pagination>
+
+      <Tabs>
+        <TabList>
+          <RawTab id="active">Active</RawTab>
+          <RawTab id="archived">Archived</RawTab>
+        </TabList>
+        <TabPanel id="active">Active rows</TabPanel>
+        <TabPanel id="archived">Archived rows</TabPanel>
+      </Tabs>
+    </>
+  )
+}
+```
+
+### RouterProvider for Raw\* in non-Tanstack apps
+
+When you use `Raw*` components in an app that uses a different router (e.g.
+React Router), wrap the app once in `RouterProvider` so `isActive` and
+client-side navigation work. The Tanstack integration entry does NOT need
+this — it reads from Tanstack hooks directly.
+
+```tsx
+import { RouterProvider } from '@payfit/unity-components'
+import { matchPath, useLocation, useNavigate } from 'react-router-dom'
+
+export function UnityRouterBridge({ children }: { children: React.ReactNode }) {
+  const navigate = useNavigate()
+  const location = useLocation()
+
+  return (
+    <RouterProvider
+      navigate={to => navigate(to)}
+      isActive={(to, isExact) =>
+        Boolean(
+          matchPath({ path: to, end: Boolean(isExact) }, location.pathname),
+        )
+      }
+    >
+      {children}
+    </RouterProvider>
+  )
+}
+```

package/skills/unity-overlays/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when adding Unity dialogs, side panels, bottom sheets, tooltips,
   popovers, or menus. Use it to choose modal versus non-modal overlays and keep
   disabled-control tooltip behavior accessible.
-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/components/dialog/Dialog.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/side-panel/SidePanel.tsx'
@@ -73,135 +74,13 @@ manage focus, restoration, scroll lock, and Escape automatically.
 
 ## Core Patterns
 
-### Dialog with DialogTrigger + DialogActions
+- Compose blocking decisions with `DialogTrigger`, `Dialog`, and
+  `DialogActions`.
+- Use `SidePanel` for side-anchored detail or editing flows.
+- Use `Popover` for focusable informational content and `Menu` for action
+  lists.
 
-```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>
-  )
-}
-```
+Read [references/patterns.md](references/patterns.md) for complete examples.
 
 ## Common Mistakes
 
@@ -224,7 +103,7 @@ Correct:
 
 Unity enforces the WCAG rule that disabled controls must not carry tooltips (the disabled element is not keyboard-focusable, so the tooltip is unreachable). This is enforced at the library level, not just policy.
 
-Source: components/tooltip/Tooltip.tsx; maintainer interview (enforced by Unity)
+Source: components/tooltip/Tooltip.tsx
 
 ### MEDIUM Use Dialog for a non-blocking hint
 

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'