@payfit/unity-components 2.35.4 → 2.35.5

package/skills/unity-overlays/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: unity-overlays
+description: >
+  Use the right overlay in @payfit/unity-components. Modal (Dialog,
+  SidePanel, BottomSheet, PromoDialog) — focus trap, scroll lock, backdrop,
+  Escape closes. Non-modal (Tooltip, Popover, DefinitionTooltip, Menu) —
+  no focus trap, can coexist with page. Unity ENFORCES "no tooltip on
+  disabled control" at the library level (a11y rule that Midnight allowed).
+  PromoDialog asserts PromoDialogHero; Popover requires title; Tooltip
+  children must accept ref.
+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'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/tooltip/Tooltip.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/popover/Popover.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/menu/Menu.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/promo-dialog/PromoDialog.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/bottom-sheet/BottomSheet.tsx'
+---
+
+## Setup
+
+Overlays do not require a global provider. Each overlay owns its open state
+through its own trigger (`DialogTrigger`, `PopoverTrigger`, `MenuTrigger`,
+`TooltipTrigger`) or via the controlled `isOpen` / `onOpenChange` pair. Mount
+the trigger and the overlay side-by-side as siblings — `DialogTrigger` reads
+exactly two children: the trigger element and the overlay.
+
+```tsx
+import {
+  Button,
+  Dialog,
+  DialogActions,
+  DialogButton,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from '@payfit/unity-components'
+
+export function ConfirmDelete({ onConfirm }: { onConfirm: () => void }) {
+  return (
+    <DialogTrigger>
+      <Button variant="danger">Delete</Button>
+      <Dialog>
+        <DialogTitle>Delete employee?</DialogTitle>
+        <DialogContent>This cannot be undone.</DialogContent>
+        <DialogActions>
+          <DialogButton variant="close">Cancel</DialogButton>
+          <DialogButton variant="danger" onPress={onConfirm}>
+            Delete
+          </DialogButton>
+        </DialogActions>
+      </Dialog>
+    </DialogTrigger>
+  )
+}
+```
+
+## Modal vs non-modal — picking the right one
+
+| Need                                              | Component                                            | Reason                                                       |
+| ------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
+| Confirmation, blocking form, decision required    | `Dialog`                                             | modal: focus trap, scroll lock, backdrop, Escape closes      |
+| Detail view that should not interrupt page flow   | `SidePanel`                                          | modal but side-anchored; same focus trap and Escape behavior |
+| Mobile-first sheet, edit on small screens         | `BottomSheet`                                        | modal anchored to viewport bottom                            |
+| Feature announcement with hero illustration       | `PromoDialog`                                        | modal with required `PromoDialogHero` slot                   |
+| Hover/focus hint on an enabled control            | `Tooltip`                                            | non-interactive, hover/focus activated, single string        |
+| Interactive informational content (links, fields) | `Popover`                                            | non-modal, focusable content, requires `title`               |
+| Dropdown list of actions                          | `Menu` (+ `MenuTrigger`/`MenuContent`/`RawMenuItem`) | non-modal, keyboard-navigable list                           |
+| Inline term definition                            | `DefinitionTooltip`                                  | non-modal, inline anchor                                     |
+
+Modal overlays all build on `react-aria-components`' `ModalOverlay` — they
+manage focus, restoration, scroll lock, and Escape automatically.
+
+## Core 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>
+  )
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Wrap a disabled control in Tooltip
+
+Wrong:
+
+```tsx
+<Tooltip title="Disabled because …">
+  <Button isDisabled>Submit</Button>
+</Tooltip>
+```
+
+Correct:
+
+```tsx
+<Button isDisabled>Submit</Button>
+<Text variant="bodySmall" color="content.neutral.low">Disabled because …</Text>
+```
+
+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)
+
+### MEDIUM Use Dialog for a non-blocking hint
+
+Wrong:
+
+```tsx
+<DialogTrigger>
+  <Button>Info</Button>
+  <Dialog>
+    <DialogContent>FYI…</DialogContent>
+  </Dialog>
+</DialogTrigger>
+```
+
+Correct:
+
+```tsx
+<PopoverTrigger>
+  <Button>Info</Button>
+  <Popover title="Info">FYI…</Popover>
+</PopoverTrigger>
+// or, for hover-only:
+<Tooltip title="FYI…"><Button>Info</Button></Tooltip>
+```
+
+Dialog is modal (focus trap, scroll lock, backdrop) — heavy for a simple informational popover.
+
+Source: components/dialog/Dialog.tsx:162-196 (ModalOverlay)
+
+### MEDIUM Use Tooltip for interactive content
+
+Wrong:
+
+```tsx
+<Tooltip
+  title={
+    <>
+      <Button>Delete</Button>
+      <Button>Edit</Button>
+    </>
+  }
+>
+  <IconButton icon={MoreFilled} />
+</Tooltip>
+```
+
+Correct:
+
+```tsx
+<Menu>
+  <MenuTrigger>
+    <IconButton icon={MoreFilled} />
+  </MenuTrigger>
+  <MenuContent>
+    <RawMenuItem>Delete</RawMenuItem>
+    <RawMenuItem>Edit</RawMenuItem>
+  </MenuContent>
+</Menu>
+```
+
+Tooltip is display-only; placing interactive elements inside breaks focus and event handling.
+
+Source: components/tooltip/Tooltip.tsx (no interactive support); components/menu/Menu.tsx
+
+### MEDIUM Fight the modal focus trap with custom useEffect focus moves
+
+Wrong:
+
+```tsx
+useEffect(() => {
+  if (open) triggerRef.current?.focus()
+}, [open])
+```
+
+Correct:
+
+```tsx
+// Let Dialog manage focus; use autoFocus on a specific element inside if needed:
+<Dialog isOpen={open} onOpenChange={setOpen}>
+  <input autoFocus />
+</Dialog>
+```
+
+Dialog manages focus and restoration via React Aria. Calling triggerRef.focus() inside a useEffect produces unpredictable jumps.
+
+Source: components/dialog/Dialog.tsx:162-196
+
+### MEDIUM PromoDialog without PromoDialogHero
+
+Wrong:
+
+```tsx
+<PromoDialog>
+  <PromoDialogTitle>Feature</PromoDialogTitle>
+  <PromoDialogContent>…</PromoDialogContent>
+</PromoDialog>
+```
+
+Correct:
+
+```tsx
+<PromoDialog>
+  <PromoDialogHero>
+    <Illustration src={MyIllustration} />
+  </PromoDialogHero>
+  <PromoDialogTitle>Feature</PromoDialogTitle>
+  <PromoDialogContent>…</PromoDialogContent>
+</PromoDialog>
+```
+
+PromoDialog validates at render and console.errors if the hero is missing; dialog still renders but the layout breaks.
+
+Source: components/promo-dialog/PromoDialog.tsx:230-236 (console.error guard)
+
+## See also
+
+- `unity-migrate-from-midnight` — the disabled+tooltip trap is the most
+  common Midnight-era pattern that Unity blocks; the migration skill covers
+  the rewrite.
+- `unity-layout-and-styling` — overlay content uses the same `uy:` utility
+  classes (Flex/Grid, spacing, `uy:data-[hovered=true]:…`).

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

@@ -0,0 +1,55 @@
+---
+name: unity-setup-feature-plugin
+description: >
+  Wire Unity into a feature plugin in the hr-apps monorepo. Run the
+  setup-unity nx generator (installs packages, configures TailwindCSS 4,
+  sets up TS types, adds providers). Provider order at app root: IntlProvider
+  → 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'
+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'
+  - 'PayFit/hr-apps:libs/shared/unity/themes/docs/files/MIGRATION-v1.md'
+  - 'PayFit/hr-apps:libs/shared/unity/components/i18n/'
+---
+
+Bootstrap Unity for a feature plugin once. After this skill completes you
+can import any export from `@payfit/unity-components` without further
+wiring.
+
+## If in hr-apps, use this generator
+
+```bash
+pnpm nx g @payfit/nx-tools:setup-unity \
+  --project=<YOUR_PROJECT> \
+  --withIcons --withIllustrations
+```
+
+The generator installs `@payfit/unity-components`, `@payfit/unity-themes`,
+`@payfit/unity-icons`, and (with `--withIllustrations`)
+`@payfit/unity-illustrations` from the workspace catalog; wires the
+TailwindCSS 4 plugin with the Unity theme preset; adds the
+`@payfit/unity-themes` reference to the project `tsconfig`; and
+mounts the providers in the correct order at the project entry. Do not
+hand-edit those files afterwards — re-run the generator.
+
+Companion generators:
+
+```bash
+# Component dev sandbox
+pnpm nx g @payfit/nx-tools:sandbox
+
+# Storybook for the project
+pnpm nx g @payfit/nx-tools:storybook
+```
+
+## Setup (manual fallback)
+
+Use only when the generator cannot run (e.g. setting up a sample app
+outside the monorepo).
+
+All details in guide: libs/shared/unity/components/src/docs/tutorials/Getting Started.mdx