@payfit/unity-components 2.55.13 → 2.55.15

package/skills/unity-layout-and-styling/references/patterns.md

@@ -0,0 +1,139 @@
+# Unity layout and styling patterns
+
+### Flex for 1D, Grid for 2D
+
+`Flex` is for one-dimensional rows/columns; `Grid` is for the 12-column (or 6-column)
+two-dimensional layout. Each exposes layout props; everything else goes via
+`className` with `uy:` utilities.
+
+```tsx
+import { Flex, FlexItem, Grid, GridItem } from '@payfit/unity-components'
+
+// Flex props: asElement, inline, direction, isReversed, wrap,
+//             gap, gapX, gapY, justify, align, alignContent, className
+<Flex direction="row" gap="200" justify="between" align="center">
+  <FlexItem grow="1">Left</FlexItem>
+  <FlexItem>Right</FlexItem>
+</Flex>
+
+// Grid props: asElement, inline, cols (6 | 12), rows, areas, flow,
+//             justifyItems, alignItems, className
+// GridItem positions via colSpan/colStart/colEnd OR area (mutually exclusive)
+<Grid cols={12} className="uy:gap-200">
+  <GridItem colSpan={8}>Main</GridItem>
+  <GridItem colSpan={4}>Aside</GridItem>
+</Grid>
+```
+
+### Responsive classes via uy:md:
+
+There is no responsive prop-object API. Responsive behavior is driven by
+TailwindCSS v4 modifiers on `className`.
+
+```tsx
+<Flex gap="100" className="uy:md:gap-200 uy:lg:gap-300">
+  <span>Item</span>
+</Flex>
+
+<Grid cols={12} className="uy:grid-cols-1 uy:md:grid-cols-2 uy:lg:grid-cols-3" />
+```
+
+### Variants with uyTv
+
+`uyTv` from `@payfit/unity-themes` is the pre-configured tailwind-variants
+factory. It applies the Unity `twMergeConfig` so variant collisions resolve
+against Unity tokens. Export the variant function and derive its typed props
+with `VariantProps`.
+
+```tsx
+import type { VariantProps } from '@payfit/unity-themes'
+
+import { uyTv } from '@payfit/unity-themes'
+
+export const callout = uyTv({
+  base: 'uy:inline-flex uy:items-center uy:gap-100 uy:rounded-100 uy:px-200 uy:py-100',
+  variants: {
+    intent: {
+      info: 'uy:bg-surface-primary-default uy:text-content-inverted-default',
+      danger: 'uy:bg-surface-danger-default uy:text-content-inverted-default',
+      neutral: 'uy:bg-surface-neutral-default uy:text-content-neutral-default',
+    },
+    size: {
+      sm: 'uy:typography-body-small',
+      md: 'uy:typography-body',
+    },
+  },
+  defaultVariants: { intent: 'info', size: 'md' },
+})
+
+export type CalloutVariantProps = VariantProps<typeof callout>
+```
+
+### Class merging with uyMerge
+
+`uyMerge` is `tailwind-merge` configured with Unity's class groups. Use it
+whenever an external `className` may collide with internal classes.
+
+```tsx
+import { uyMerge } from '@payfit/unity-themes'
+
+uyMerge('uy:p-100', 'uy:p-200') // → 'uy:p-200'
+uyMerge('uy:bg-surface-primary-default', 'uy:bg-surface-danger-default')
+// → 'uy:bg-surface-danger-default'
+uyMerge('uy:p-100', 'uy:px-200', 'uy:py-300') // p, px, py don't collide
+```
+
+### Conditional classes with cn / classNames / clsx
+
+`cn`, `classNames`, and `clsx` are aliases for the same Unity-configured helper
+in `@payfit/unity-themes`. Use them for ad-hoc conditional strings — not for
+component-scoped variant APIs.
+
+```tsx
+import { cn } from '@payfit/unity-themes'
+
+function Row({
+  isActive,
+  className,
+}: {
+  isActive: boolean
+  className?: string
+}) {
+  return (
+    <div
+      className={cn(
+        'uy:flex uy:items-center uy:px-200 uy:py-100',
+        isActive && 'uy:bg-surface-primary-default',
+        className,
+      )}
+    />
+  )
+}
+```
+
+### Typography with `<Text>`
+
+Use `<Text variant=...>` instead of a `<div>` + typography class. `Text`
+picks a semantic element from the variant (e.g. `variant="h1"` → `<h1>`),
+applies the typography variant, and exposes `color`, `isTruncated`,
+`lineClamp`, and `maxWidthCh`.
+
+```tsx
+import { Text } from '@payfit/unity-components'
+
+<Text variant="h1" color="content.primary">Title</Text>
+<Text variant="body" color="content.neutral">Description</Text>
+// Override the semantic element when needed:
+<Text variant="h1" asElement="h2">Visual h1, semantic h2</Text>
+```
+
+### Data-attribute pseudo-states
+
+Several Unity components expose internal state via `data-hovered`,
+`data-pressed`, `data-focus-visible`, etc. Target the component-owned state
+attribute rather than the native CSS pseudo-state.
+
+```tsx
+import { ListViewItem } from '@payfit/unity-components'
+;<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
+```

package/skills/unity-migrate-from-midnight/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when replacing @payfit/midnight UI with Unity. Use it to choose Unity
   equivalents, avoid obsolete Midnight patterns, and route unclear component
   mappings to unity-find-component.
-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/components/tooltip/Tooltip.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/button/Button.tsx'
@@ -71,10 +72,9 @@ Unity enforces several WCAG rules that Midnight allowed:
 
 Midnight-era screens commonly use React Hook Form. When porting, replace
 the form with `useTanstackUnityForm` and the Tanstack-bound `*Field`
-components (`TextField`, `SelectField`, `NumberField`, etc.). The legacy
-RHF `useUnityForm` + `*Field` wrappers in the same package index are
-deprecated and will be removed after the rebrand — do not pause on the
-RHF intermediate step. See `unity-tanstack-form`.
+components (`TextField`, `SelectField`, `NumberField`, etc.). The legacy RHF
+`useUnityForm` + `*Field` wrappers in the same package index are deprecated.
+Do not pause on the RHF intermediate step. See `unity-tanstack-form`.
 
 ## Common Mistakes
 
@@ -106,7 +106,7 @@ rule that disabled controls must not have tooltips because they are not
 keyboard-focusable, so the tooltip is unreachable — Unity's `Tooltip`
 component rejects this pairing at the library level.
 
-Source: libs/shared/unity/components/src/components/tooltip/Tooltip.tsx; maintainer interview (Unity enforces)
+Source: libs/shared/unity/components/src/components/tooltip/Tooltip.tsx
 
 ### HIGH Assume Midnight props map 1:1 to Unity
 
@@ -151,7 +151,7 @@ Midnight and Unity ship divergent theme tokens — colors, spacing, and
 typography differ — so a mixed screen renders with mismatched scales and
 the visual regression lands silently because both stylesheets are valid.
 
-Source: AGENTS.md migration awareness; maintainer interview
+Source: AGENTS.md migration awareness
 
 ### MEDIUM Port Midnight transition utility instead of using uy: classes
 

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