@payfit/unity-components
Version:
218 lines (169 loc) • 6.2 kB
Markdown
---
name: unity-navigation
description: >
Load when building Unity links, tabs, breadcrumbs, nav, or pagination. Use it
to choose router-aware Tanstack Router components versus Raw* href
primitives.
metadata:
type: core
library: '/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'
- 'PayFit/hr-apps:libs/shared/unity/components/src/components/pagination/Pagination.tsx'
- 'PayFit/hr-apps:libs/shared/unity/components/src/components/tabs/Tabs.tsx'
- 'PayFit/hr-apps:libs/shared/unity/components/src/integrations/tanstack-router/index.ts'
- 'PayFit/hr-apps:libs/shared/unity/components/src/providers/router/RouterProvider.tsx'
- 'PayFit/hr-apps:libs/shared/unity/components/src/docs/concepts/navigation/Navigation Patterns Explained.mdx'
---
Two entry points expose the same components in two flavors. The base entry
(`/unity-components`) ships router-agnostic `Raw*` primitives that take
a plain `href`. The Tanstack integration entry
(`/unity-components/integrations/tanstack-router`) ships type-safe
counterparts that take `to` and are wired via `createLink` from
`/react-router`.
## Setup
In a Tanstack Router feature plugin, import every link/nav component from the
integration entry. No `RouterProvider` is required — the integration uses
Tanstack hooks directly.
```tsx
import {
Breadcrumb,
BreadcrumbLink,
Breadcrumbs,
Link,
Tab,
TabList,
TabPanel,
Tabs,
} from '/unity-components/integrations/tanstack-router'
import { Outlet } from '@tanstack/react-router'
export function EmployeesShell() {
return (
<>
<Breadcrumbs>
<Breadcrumb>
<BreadcrumbLink to="/">Home</BreadcrumbLink>
</Breadcrumb>
<Breadcrumb>
<BreadcrumbLink to="/employees">Employees</BreadcrumbLink>
</Breadcrumb>
</Breadcrumbs>
<Tabs>
<TabList>
<Tab to="/employees/active">Active</Tab>
<Tab to="/employees/archived">Archived</Tab>
</TabList>
<TabPanel>
<Outlet />
</TabPanel>
</Tabs>
<Link to="/employees/new">New employee</Link>
</>
)
}
```
## Core Patterns
- 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.
Read [references/patterns.md](references/patterns.md) for complete compositions
and provider examples.
## Common Mistakes
### HIGH Import Link from base entry in a Tanstack Router feature
Wrong:
```tsx
import { Link } from '@payfit/unity-components'
;<Link to="/dashboard">Go</Link>
```
Correct:
```tsx
import { Link } from '@payfit/unity-components/integrations/tanstack-router'
;<Link to="/dashboard">Go</Link>
```
The base export "Link" does not exist; agents alias RawLink and pass to=. The prop is silently ignored and the link does not navigate.
Source: integrations/tanstack-router/components/link/Link.tsx (createLink wraps RawLink)
### HIGH Pass to= prop to RawLink
Wrong:
```tsx
import { RawLink } from '@payfit/unity-components'
;<RawLink to="/dashboard">Go</RawLink>
```
Correct:
```tsx
// Use the integration Link for type-safe routing:
import { Link } from '@payfit/unity-components/integrations/tanstack-router'
<Link to="/dashboard">Go</Link>
// OR keep RawLink with a plain href:
<RawLink href="/dashboard">Go</RawLink>
```
RawLink only accepts href. The to prop is silently ignored.
Source: components/link/RawLink.tsx:113-163
### HIGH Expect the v1 monolithic Pagination
Wrong:
```tsx
import { Pagination, ClientSidePagination } from '@payfit/unity-components'
// ClientSidePagination is not exported; Pagination needs children.
<Pagination currentPage={1} pageCount={10} onPageChange={…} />
```
Correct:
```tsx
import { Pagination, PaginationContent, PaginationItem, RawPaginationLink }
from '/unity-components'
<Pagination currentPage={1} pageCount={10} onPageChange={…}>
<PaginationContent>
<PaginationItem>
<RawPaginationLink value={1}>1</RawPaginationLink>
</PaginationItem>
{/* … */}
</PaginationContent>
</Pagination>
// Or, for tables, let DataTable handle pagination internally.
```
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
### MEDIUM Forget to wrap BreadcrumbLink in Breadcrumb
Wrong:
```tsx
<Breadcrumbs>
<BreadcrumbLink href="/">Home</BreadcrumbLink>
</Breadcrumbs>
```
Correct:
```tsx
<Breadcrumbs>
<Breadcrumb>
<BreadcrumbLink href="/">Home</BreadcrumbLink>
</Breadcrumb>
</Breadcrumbs>
```
Breadcrumbs filters children to Breadcrumb type; loose BreadcrumbLinks are dropped silently.
Source: components/breadcrumbs/Breadcrumbs.tsx:328-407
### MEDIUM Use Raw\* components without RouterProvider in a non-Tanstack app
Wrong:
```tsx
<App>
<RawLink href="/dashboard">Go</RawLink>
</App>
```
Correct:
```tsx
<RouterProvider
isActive={path => router.isActive(path)}
navigate={router.navigate}
>
<App>
<RawLink href="/dashboard">Go</RawLink>
</App>
</RouterProvider>
```
Raw\* components consume useRouter() context. Without RouterProvider, isActive checks return undefined and active-link styling is lost.
Source: components/link/RawLink.tsx:186; providers/router/RouterProvider.tsx
## See also
- `unity-setup-feature-plugin` — where and how to mount `RouterProvider`,
and when a feature plugin should switch from base to integration entry.
- `unity-data-table` — DataTable has pagination built in; do not compose
`Pagination` next to it.