@payfit/unity-components 2.55.14 → 2.55.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-components",
-  "version": "2.55.14",
+  "version": "2.55.15",
   "module": "./dist/esm/index.js",
   "type": "module",
   "sideEffects": false,
@@ -93,7 +93,7 @@
     "tailwind-variants": "3.2.2",
     "usehooks-ts": "3.1.1",
     "zod": "4.4.3",
-    "@payfit/unity-illustrations": "2.55.14"
+    "@payfit/unity-illustrations": "2.55.15"
   },
   "peerDependencies": {
     "@hookform/devtools": "^4",
@@ -105,8 +105,8 @@
     "react-hook-form": "^7",
     "react-router-dom": "^5",
     "zod": "^3 || ^4",
-    "@payfit/unity-icons": "2.55.14",
-    "@payfit/unity-themes": "2.55.14"
+    "@payfit/unity-icons": "2.55.15",
+    "@payfit/unity-themes": "2.55.15"
   },
   "devDependencies": {
     "@figma/code-connect": "1.4.8",
@@ -152,14 +152,14 @@
     "vite": "8.1.4",
     "vite-plugin-node-polyfills": "0.28.0",
     "vitest": "4.1.10",
-    "@payfit/unity-icons": "2.55.14",
-    "@payfit/unity-illustrations": "2.55.14",
-    "@payfit/unity-themes": "2.55.14",
-    "@payfit/vite-configs": "0.0.0-use.local",
     "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
     "@payfit/storybook-addon-console-errors": "0.0.0-use.local",
-    "@payfit/storybook-config": "0.0.0-use.local"
+    "@payfit/storybook-config": "0.0.0-use.local",
+    "@payfit/unity-icons": "2.55.15",
+    "@payfit/unity-illustrations": "2.55.15",
+    "@payfit/unity-themes": "2.55.15",
+    "@payfit/vite-configs": "0.0.0-use.local"
   },
   "peerDependenciesMeta": {
     "@hookform/devtools": {

package/skills/unity-data-table/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when rendering tabular data with Unity. Use it to choose DataTable for
   managed table state or primitive Table for static/custom markup, including
   filtering, pagination, virtualization, or bulk actions.
-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/data-table/DataTable.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/data-table/parts/DataTableRoot.tsx'
@@ -23,7 +24,9 @@ table state to manage.
 
 ## Setup
 
-Minimum working client-side DataTable. Columns and data MUST be memoized.
+Minimum working client-side DataTable. Keep `columns` and `data` references
+stable across renders. Define static columns outside the component or memoize
+them; memoize derived data when its source would otherwise create a new array.
 
 ```tsx
 import { useMemo, useState } from 'react'
@@ -98,241 +101,17 @@ export function EmployeeTable({ employees }: { employees: Employee[] }) {
 
 ## Core Patterns
 
-### Define columns with the column helper and ColumnMeta
+- Define columns with `createColumnHelper` and use `ColumnMeta` for row
+  headers, focus behavior, helper text, and fixed-layout widths.
+- For server pagination, pass only the current page, set `manualPagination`,
+  and derive `pageCount` from the server total.
+- Map `FilterToolbar.onChange` into TanStack Table's column/global filter
+  state.
+- Put `DataTableBulkActions` beside `DataTable` inside `DataTableRoot` and
+  drive it from row-selection state.
 
-ColumnMeta drives accessibility (`isRowHeader`), keyboard navigation
-(`isFocusable: false` for cells whose children are themselves focusable like
-checkboxes), `helperText` (renders a tooltip next to the header), and
-`headerClassName` (required when `layout="fixed"`).
-
-```tsx
-import { Badge } from '@payfit/unity-components'
-import { createColumnHelper } from '@tanstack/react-table'
-
-const columnHelper = createColumnHelper<Employee>()
-
-export const employeeColumns = [
-  columnHelper.accessor('name', {
-    id: 'employee',
-    header: 'Employee',
-    enableSorting: true,
-    meta: { isRowHeader: true, headerClassName: 'uy:w-[260px]' },
-  }),
-  columnHelper.accessor('status', {
-    header: 'Status',
-    enableColumnFilter: true,
-    filterFn: 'arrIncludesSome',
-    cell: info => {
-      const status = info.getValue()
-      return (
-        <Badge variant={status === 'active' ? 'success' : 'neutral'}>
-          {status}
-        </Badge>
-      )
-    },
-    meta: { helperText: 'Active employees can sign in.' },
-  }),
-  columnHelper.display({
-    id: 'actions',
-    header: '',
-    cell: ({ row }) => <RowMenu row={row.original} />,
-    meta: { isFocusable: false },
-  }),
-]
-```
-
-### Server-side pagination
-
-`manualPagination: true` disables Tanstack's internal slicing. Pass only the
-current page's slice as `data` and supply `pageCount`.
-
-```tsx
-import { useMemo, useState } from 'react'
-
-import { getCoreRowModel, useReactTable } from '@tanstack/react-table'
-
-export function ServerTable({ totalCount, fetchPage }: Props) {
-  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 20 })
-  const { data: pageRows = [] } = useQuery({
-    queryKey: ['employees', pagination],
-    queryFn: () => fetchPage(pagination.pageIndex, pagination.pageSize),
-  })
-
-  const columns = useMemo(() => employeeColumns, [])
-  const data = useMemo(() => pageRows, [pageRows])
-
-  const table = useReactTable({
-    data,
-    columns,
-    manualPagination: true,
-    pageCount: Math.ceil(totalCount / pagination.pageSize),
-    state: { pagination },
-    onPaginationChange: setPagination,
-    getCoreRowModel: getCoreRowModel(),
-  })
-
-  return (
-    <DataTableRoot>
-      <DataTable table={table}>
-        {row => (
-          <TableRow key={row.id}>
-            {row.getVisibleCells().map(cell => (
-              <TableCell key={cell.id}>
-                {flexRender(cell.column.columnDef.cell, cell.getContext())}
-              </TableCell>
-            ))}
-          </TableRow>
-        )}
-      </DataTable>
-    </DataTableRoot>
-  )
-}
-```
-
-### Filtering with FilterToolbar
-
-`FilterToolbar.onChange` emits `SerializableAppliedFilter[]`. Map that onto
-`table.setColumnFilters` / `table.setGlobalFilter`. `renderControl` takes any
-control — it is a render function on purpose so you can drop in date pickers,
-multi-selects, text fields, etc.
-
-```tsx
-import type { FilterDef } from '@payfit/unity-components'
-
-import { FilterToolbar, Select, SelectItem } from '@payfit/unity-components'
-import { getFilteredRowModel } from '@tanstack/react-table'
-
-const filterDefs: FilterDef[] = [
-  {
-    id: 'status',
-    label: 'Status',
-    renderControl: (value, onChange) => (
-      <Select selectedKey={value as string} onSelectionChange={onChange}>
-        <SelectItem id="active">Active</SelectItem>
-        <SelectItem id="inactive">Inactive</SelectItem>
-      </Select>
-    ),
-    renderLabel: value => String(value),
-  },
-]
-
-export function FilteredTable() {
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
-
-  const table = useReactTable({
-    data,
-    columns,
-    state: { columnFilters, pagination },
-    onColumnFiltersChange: setColumnFilters,
-    onPaginationChange: setPagination,
-    getCoreRowModel: getCoreRowModel(),
-    getFilteredRowModel: getFilteredRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
-  })
-
-  return (
-    <>
-      <FilterToolbar
-        filterDefs={filterDefs}
-        onChange={applied =>
-          setColumnFilters(applied.map(f => ({ id: f.id, value: f.value })))
-        }
-      />
-      <DataTableRoot>
-        <DataTable table={table}>
-          {row => (
-            <TableRow key={row.id}>
-              {row.getVisibleCells().map(cell => (
-                <TableCell key={cell.id}>
-                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
-                </TableCell>
-              ))}
-            </TableRow>
-          )}
-        </DataTable>
-      </DataTableRoot>
-    </>
-  )
-}
-```
-
-### Bulk actions with row selection
-
-`DataTableBulkActions` lives next to `DataTable` inside `DataTableRoot`.
-It auto-shows when rows are selected and provides the F6 focus trap. Use a
-display column with `meta.isFocusable: false` for the checkbox.
-
-```tsx
-import {
-  CheckboxStandalone,
-  DataTable,
-  DataTableBulkActions,
-  DataTableRoot,
-} from '@payfit/unity-components'
-
-const checkboxColumn = columnHelper.display({
-  id: 'select',
-  header: ({ table }) => (
-    <CheckboxStandalone
-      isSelected={table.getIsAllPageRowsSelected()}
-      isIndeterminate={table.getIsSomePageRowsSelected()}
-      onChange={value => table.toggleAllPageRowsSelected(value)}
-      slot="selection"
-    >
-      Select all
-    </CheckboxStandalone>
-  ),
-  cell: ({ row }) => (
-    <CheckboxStandalone
-      isSelected={row.getIsSelected()}
-      onChange={value => row.toggleSelected(value)}
-      slot="selection"
-    >
-      Select row
-    </CheckboxStandalone>
-  ),
-  enableSorting: false,
-  meta: { isFocusable: false },
-})
-
-export function BulkTable() {
-  const [rowSelection, setRowSelection] = useState({})
-  const columns = useMemo(() => [checkboxColumn, ...employeeColumns], [])
-  const table = useReactTable({
-    data,
-    columns,
-    state: { rowSelection, pagination },
-    onRowSelectionChange: setRowSelection,
-    onPaginationChange: setPagination,
-    enableRowSelection: true,
-    getCoreRowModel: getCoreRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
-  })
-
-  return (
-    <DataTableRoot>
-      <DataTable table={table}>
-        {row => (
-          <TableRow key={row.id} isSelected={row.getIsSelected()}>
-            {row.getVisibleCells().map(cell => (
-              <TableCell key={cell.id}>
-                {flexRender(cell.column.columnDef.cell, cell.getContext())}
-              </TableCell>
-            ))}
-          </TableRow>
-        )}
-      </DataTable>
-      <DataTableBulkActions
-        table={table}
-        actions={[
-          { id: 'archive', label: 'Archive', onAction: rows => archive(rows) },
-          { id: 'delete', label: 'Delete', onAction: rows => remove(rows) },
-        ]}
-      />
-    </DataTableRoot>
-  )
-}
-```
+Read [references/patterns.md](references/patterns.md) when implementing one of
+these patterns.
 
 ## Common Mistakes
 
@@ -435,7 +214,7 @@ const table = useReactTable({ /* … */ state: { columnFilters, globalFilter },
 
 FilterToolbar.onChange emits AppliedFilter[]. Agent stores them locally without mapping to table.setGlobalFilter / setColumnFilters, so rows do not actually filter.
 
-### CRITICAL Server-side pagination without slicing data
+### HIGH Pass every local row with manual pagination
 
 Wrong:
 
@@ -447,7 +226,7 @@ useReactTable({
 })
 ```
 
-Correct:
+Correct for locally held data:
 
 ```tsx
 const currentData = useMemo(() => {
@@ -465,6 +244,11 @@ useReactTable({
 
 manualPagination: true tells Tanstack not to slice. Agents pass the full dataset and expect TanStack to paginate anyway.
 
+For server-side pagination, fetch and pass only the current server page and
+set `pageCount` from the server's total count. When all rows are local and
+TanStack should paginate them automatically, omit `manualPagination` and use
+`getPaginationRowModel()` instead.
+
 ### MEDIUM Render large datasets without enableVirtualization
 
 Wrong:

package/skills/unity-data-table/references/patterns.md

@@ -0,0 +1,237 @@
+# Unity DataTable patterns
+
+### Define columns with the column helper and ColumnMeta
+
+ColumnMeta drives accessibility (`isRowHeader`), keyboard navigation
+(`isFocusable: false` for cells whose children are themselves focusable like
+checkboxes), `helperText` (renders a tooltip next to the header), and
+`headerClassName` (required when `layout="fixed"`).
+
+```tsx
+import { Badge } from '@payfit/unity-components'
+import { createColumnHelper } from '@tanstack/react-table'
+
+const columnHelper = createColumnHelper<Employee>()
+
+export const employeeColumns = [
+  columnHelper.accessor('name', {
+    id: 'employee',
+    header: 'Employee',
+    enableSorting: true,
+    meta: { isRowHeader: true, headerClassName: 'uy:w-[260px]' },
+  }),
+  columnHelper.accessor('status', {
+    header: 'Status',
+    enableColumnFilter: true,
+    filterFn: 'arrIncludesSome',
+    cell: info => {
+      const status = info.getValue()
+      return (
+        <Badge variant={status === 'active' ? 'success' : 'neutral'}>
+          {status}
+        </Badge>
+      )
+    },
+    meta: { helperText: 'Active employees can sign in.' },
+  }),
+  columnHelper.display({
+    id: 'actions',
+    header: '',
+    cell: ({ row }) => <RowMenu row={row.original} />,
+    meta: { isFocusable: false },
+  }),
+]
+```
+
+### Server-side pagination
+
+`manualPagination: true` disables Tanstack's internal slicing. Pass only the
+current page's slice as `data` and supply `pageCount`.
+
+```tsx
+import { useMemo, useState } from 'react'
+
+import { getCoreRowModel, useReactTable } from '@tanstack/react-table'
+
+export function ServerTable({ totalCount, fetchPage }: Props) {
+  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 20 })
+  const { data: pageRows = [] } = useQuery({
+    queryKey: ['employees', pagination],
+    queryFn: () => fetchPage(pagination.pageIndex, pagination.pageSize),
+  })
+
+  const columns = useMemo(() => employeeColumns, [])
+  const data = useMemo(() => pageRows, [pageRows])
+
+  const table = useReactTable({
+    data,
+    columns,
+    manualPagination: true,
+    pageCount: Math.ceil(totalCount / pagination.pageSize),
+    state: { pagination },
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  return (
+    <DataTableRoot>
+      <DataTable table={table}>
+        {row => (
+          <TableRow key={row.id}>
+            {row.getVisibleCells().map(cell => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        )}
+      </DataTable>
+    </DataTableRoot>
+  )
+}
+```
+
+### Filtering with FilterToolbar
+
+`FilterToolbar.onChange` emits `SerializableAppliedFilter[]`. Map that onto
+`table.setColumnFilters` / `table.setGlobalFilter`. `renderControl` takes any
+control — it is a render function on purpose so you can drop in date pickers,
+multi-selects, text fields, etc.
+
+```tsx
+import type { FilterDef } from '@payfit/unity-components'
+
+import { FilterToolbar, Select, SelectItem } from '@payfit/unity-components'
+import { getFilteredRowModel } from '@tanstack/react-table'
+
+const filterDefs: FilterDef[] = [
+  {
+    id: 'status',
+    label: 'Status',
+    renderControl: (value, onChange) => (
+      <Select selectedKey={value as string} onSelectionChange={onChange}>
+        <SelectItem id="active">Active</SelectItem>
+        <SelectItem id="inactive">Inactive</SelectItem>
+      </Select>
+    ),
+    renderLabel: value => String(value),
+  },
+]
+
+export function FilteredTable() {
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+
+  const table = useReactTable({
+    data,
+    columns,
+    state: { columnFilters, pagination },
+    onColumnFiltersChange: setColumnFilters,
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+  })
+
+  return (
+    <>
+      <FilterToolbar
+        filterDefs={filterDefs}
+        onChange={applied =>
+          setColumnFilters(applied.map(f => ({ id: f.id, value: f.value })))
+        }
+      />
+      <DataTableRoot>
+        <DataTable table={table}>
+          {row => (
+            <TableRow key={row.id}>
+              {row.getVisibleCells().map(cell => (
+                <TableCell key={cell.id}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </TableCell>
+              ))}
+            </TableRow>
+          )}
+        </DataTable>
+      </DataTableRoot>
+    </>
+  )
+}
+```
+
+### Bulk actions with row selection
+
+`DataTableBulkActions` lives next to `DataTable` inside `DataTableRoot`.
+It auto-shows when rows are selected and provides the F6 focus trap. Use a
+display column with `meta.isFocusable: false` for the checkbox.
+
+```tsx
+import {
+  CheckboxStandalone,
+  DataTable,
+  DataTableBulkActions,
+  DataTableRoot,
+} from '@payfit/unity-components'
+
+const checkboxColumn = columnHelper.display({
+  id: 'select',
+  header: ({ table }) => (
+    <CheckboxStandalone
+      isSelected={table.getIsAllPageRowsSelected()}
+      isIndeterminate={table.getIsSomePageRowsSelected()}
+      onChange={value => table.toggleAllPageRowsSelected(value)}
+      slot="selection"
+    >
+      Select all
+    </CheckboxStandalone>
+  ),
+  cell: ({ row }) => (
+    <CheckboxStandalone
+      isSelected={row.getIsSelected()}
+      onChange={value => row.toggleSelected(value)}
+      slot="selection"
+    >
+      Select row
+    </CheckboxStandalone>
+  ),
+  enableSorting: false,
+  meta: { isFocusable: false },
+})
+
+export function BulkTable() {
+  const [rowSelection, setRowSelection] = useState({})
+  const columns = useMemo(() => [checkboxColumn, ...employeeColumns], [])
+  const table = useReactTable({
+    data,
+    columns,
+    state: { rowSelection, pagination },
+    onRowSelectionChange: setRowSelection,
+    onPaginationChange: setPagination,
+    enableRowSelection: true,
+    getCoreRowModel: getCoreRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+  })
+
+  return (
+    <DataTableRoot>
+      <DataTable table={table}>
+        {row => (
+          <TableRow key={row.id} isSelected={row.getIsSelected()}>
+            {row.getVisibleCells().map(cell => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        )}
+      </DataTable>
+      <DataTableBulkActions
+        table={table}
+        actions={[
+          { id: 'archive', label: 'Archive', onAction: rows => archive(rows) },
+          { id: 'delete', label: 'Delete', onAction: rows => remove(rows) },
+        ]}
+      />
+    </DataTableRoot>
+  )
+}
+```