@rfdtech/components 1.21.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
-# GSL Components
+# Clet Components
 
-Shared React component library for Ghana School of Law (GSL) projects.
+Shared React component library for Clet projects. The `--gsl-*` CSS tokens, `.gsl-*` class names, and the `@rfdtech/components` package name are kept unchanged for backward compatibility; every color token also has an equivalent `--clet-*` alias (see [Customize tokens](#7-customize-tokens)).
 
 Requires React 18+ and a bundler that processes CSS (Vite, Webpack, etc.).
 
@@ -26,7 +26,7 @@ Add this once to your app entry (`main.tsx` or `App.tsx`):
 import "@rfdtech/components/style.css";
 ```
 
-Components load CSS automatically from the JS bundle (the JS bundle includes `import './index.css'`), but the explicit import above ensures reliable production styling. After upgrading, clear Vite's dependency cache if styles look stale: `rm -rf node_modules/.vite`.
+Components load CSS automatically from the JS bundle (the JS bundle includes `import './index.css'`), but the explicit import above ensures reliable production styling. After upgrading, clear Vite's dependency cache if styles look stale: `rm -rf node_modules/.vite`. alright
 
 ### 3. Wrap with ThemeProvider
 
@@ -53,10 +53,10 @@ If your project uses Tailwind v4, all `--gsl-*` design tokens are automatically
 The `@theme` block ships inside `style.css`. The consumer's Tailwind build processes it and generates these utility classes:
 
 | Utility | Resolves to |
-|---------|-------------|
+| --------- | ------------- |
 | `bg-primary` / `text-primary` | `var(--gsl-primary)` |
 | `bg-primary-foreground` / `text-primary-foreground` | `var(--gsl-on-primary)` |
-| `bg-background` / `text-foreground` | `var(--gsl-page-bg)` / `var(--gsl-text)` |
+| `bg-background` / `text-foreground` | `var(--gsl-main-bg)` / `var(--gsl-text)` |
 | `bg-secondary` / `text-secondary-foreground` | `var(--gsl-surface-dark)` / `var(--gsl-text-secondary)` |
 | `bg-muted` / `text-muted-foreground` | `var(--gsl-surface-subtle)` / `var(--gsl-text-secondary)` |
 | `bg-accent` / `text-accent-foreground` | `var(--gsl-hover)` / `var(--gsl-text)` |
@@ -72,39 +72,129 @@ The `@theme` block ships inside `style.css`. The consumer's Tailwind build proce
 
 **Non-Tailwind consumers** are unaffected. Browsers silently ignore `@theme` as an unknown at-rule. All `--gsl-*` tokens continue to work as CSS custom properties.
 
-### 5. Customize tokens
+### 6. AI-assisted development (automatic)
 
-Override any `--gsl-*` token on any ancestor:
+`npm install` also wires up an MCP server + skill doc for any AI coding tool it detects in your project — **Claude Code**, **Cursor**, **Codex**, and **OpenCode** — so agents search real components, pull authoritative prop types, and follow the library's design rules instead of inventing APIs. This runs via this package's own `postinstall` script (`scripts/postinstall.mjs`) — no separate command, no action needed. It's idempotent and safe to re-run. Set `RFDUI_SKIP_SETUP=1` to opt out (e.g. in CI). See [`mcp/README.md`](./mcp/README.md) for the `rfdui` CLI (`setup`, `doctor`, `search`, `update`) if you want to run it manually or check its status.
 
-```css
-.my-app {
-  --gsl-primary: #1d4ed8;
-  --gsl-primary-light: #eff6ff;
+**If your package manager blocked the install script**, run setup manually — `npx rfdui setup` always works regardless of package manager or script-blocking config. Otherwise, to let it run automatically on the next install:
+
+- **pnpm** (v8+) blocks lifecycle scripts from dependencies by default and prints `Ignored build scripts: @rfdtech/components` after install. Approve it, then reinstall:
+  ```bash
+  pnpm approve-builds @rfdtech/components   # or: pnpm approve-builds (interactive picker)
+  pnpm install
+  ```
+  This writes `@rfdtech/components: true` under `allowBuilds` in `pnpm-workspace.yaml` (pnpm 11+; older pnpm uses `onlyBuiltDependencies` instead — same idea, different key).
+- **npm** runs `postinstall` by default — nothing to approve. If it didn't run, your project or user `.npmrc` likely sets `ignore-scripts=true` (common in locked-down CI), or you ran `npm install --ignore-scripts`. Either drop that flag/setting for a local install, or just run `npx rfdui setup` manually — that always works even with scripts globally disabled.
+
+### 7. Next.js App Router
+
+The library ships a `/next` subpath for Next.js App Router. All components and hooks work with Next.js by wrapping your app in `RouterAdapterProvider`:
+
+```tsx
+// app/providers.tsx
+"use client";
+import { RouterAdapterProvider, useNextRouterAdapter } from "@rfdtech/components/next";
+
+export function Providers({ children }) {
+  const adapter = useNextRouterAdapter();
+  return <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>;
+}
+```
+
+Then use components from `@rfdtech/components/next`:
+
+```tsx
+import { useTableState, SidebarLink } from "@rfdtech/components/next";
+```
+
+See the [RouterAdapter](/docs/router-adapter) docs page for full setup.
+
+### 7. Customize tokens
+
+Components read `--gsl-*` CSS variables. Every color token also has a
+`--clet-*` alias with the exact same value — **prefer `--clet-*` in new
+override code**; `--gsl-*` keeps working unchanged for existing overrides
+(each `--gsl-*` color token is now defined as `var(--clet-*)`, so overriding
+either name works — `--clet-*` is just the newer, preferred spelling).
+Non-color tokens (radius, shadow, font, spacing) only have a `--gsl-*` name;
+there is no `--clet-*` equivalent for those. Override any token by
+declaring a new value on the same selectors the library uses.
+
+**Step 1 — Import the library CSS** so its defaults are loaded:
+
+```ts title="src/main.tsx"
+import "@rfdtech/components/style.css";
+```
+
+**Step 2 — Create a theme override file** and import it AFTER the
+library CSS. CSS source order matters: later rules with the same
+specificity win.
+
+```ts title="src/main.tsx"
+import "@rfdtech/components/style.css";
+import "./styles/theme.css"; // imported after
+```
+
+**Step 3 — Override the tokens.** The library writes its defaults on
+these selectors:
+
+| Selector | When it matches |
+|----------|-----------------|
+| `:root` | No theme attribute is set (no `ThemeProvider` mounted) |
+| `:root[data-gsl-theme="light"]` | Light mode on `<html>` — `ThemeProvider` writes the attribute here |
+| `:root[data-gsl-theme="dark"]` | Dark mode on `<html>` |
+| `.gsl-theme` | A consumer wrapper `<div class="gsl-theme">` |
+| `.gsl-theme[data-gsl-theme="light"]` | Wrapper + light attribute |
+| `.gsl-theme[data-gsl-theme="dark"]` | Wrapper + dark attribute |
+
+A bare `:root { ... }` only matches the first row, so the library's
+default keeps winning on rows 2–6 once `ThemeProvider` mounts. To
+cover all of them, list every selector in one rule and hardcode the
+values (don't chain `var(--something)` — just write the color):
+
+```css title="src/styles/theme.css"
+:root,
+:root[data-gsl-theme="light"],
+.gsl-theme[data-gsl-theme="light"],
+:root[data-gsl-theme="dark"],
+.gsl-theme[data-gsl-theme="dark"] {
+  --clet-primary: #1d4ed8;
+  --clet-primary-light: #eff6ff;
+  --clet-focus: #1d4ed8;
+  --clet-on-primary: #ffffff;
 }
 ```
 
+That one block overrides the primary color in light mode, dark mode,
+and the unthemed fallback. The same shape works for any other color
+token — list every selector, hardcode the value, and use its `--clet-*`
+name (or the equivalent `--gsl-*` name — both work identically).
+
 ## Design tokens
 
-Quick reference of commonly used tokens and their light-mode defaults:
-
-| Token | Light default | Use |
-|-------|---------------|-----|
-| `--gsl-primary` | `#dc2626` | Buttons, focus rings, accents |
-| `--gsl-primary-light` | `#fef2f2` | Selected rows, hover fills |
-| `--gsl-bg` | `#ffffff` | Surfaces |
-| `--gsl-text` | `#3c4043` | Body text |
-| `--gsl-text-secondary` | `#5f6368` | Labels, muted UI |
-| `--gsl-border` | `#dadce0` | Borders |
-| `--gsl-hover` | `#f1f3f4` | Row/cell hover |
-| `--gsl-error` / `--gsl-error-bg` | `#dc2626` / `#fef2f2` | Errors |
-| `--gsl-success` | `#16a34a` | Success states |
-| `--gsl-warning` | `#eab308` | Warnings |
+Quick reference of commonly used color tokens and their light-mode defaults.
+Each has both a `--clet-*` (preferred) and `--gsl-*` (legacy, still works)
+name for the same value:
+
+| Token (`--clet-*` / `--gsl-*`) | Light default | Use |
+| ------- | --------------- | ----- |
+| `primary` | `#083755` | Buttons, focus rings, accents |
+| `primary-light` | `#e7ebee` | Selected rows, hover fills |
+| `secondary` | `#c8a24b` | Gold accent (e.g. active `SidebarLink`) |
+| `bg` | `#ffffff` | Surfaces |
+| `main-bg` | `#fafafa` | Page/app-layout background |
+| `text` | `#3c4043` | Body text |
+| `text-secondary` | `#5f6368` | Labels, muted UI |
+| `border` | `#dadce0` | Borders |
+| `hover` | `#f1f3f4` | Row/cell hover |
+| `error` / `error-bg` | `#dc2626` / `#fef2f2` | Errors |
+| `success` | `#16a34a` | Success states |
+| `warning` | `#eab308` | Warnings |
 
 `BulkImportModal` also accepts legacy aliases (`--gsl-bulk-import-primary`, etc.) that map to the shared tokens.
 
 See the [Theme](/docs/theme) docs page for the full token reference (radius, shadows, z-index, fonts) and controlled mode.
 
-
 ## Hooks
 
 Shared hooks for URL-driven overlay state and router integration. See the [Hooks](/docs/hooks) docs page for full API reference.
@@ -130,10 +220,9 @@ openWith({ userId: "42" });
 
 Exports: `useSearchParamOverlay`, `useDialogSearchParam`, `useModalSearchParam`, `createSearchParamAdapter`, `createBrowserSearchParamAdapter`, `readOverlayData`, `writeOverlayData`, `clearOverlayData`, `getDataPrefix`. Types: `SearchParamOverlayState`, `SearchParamOverlayData`, `SearchParamAdapter`, `UseSearchParamOverlayOptions`, `UseSearchParamOverlayReturn`.
 
-
 ## AppHeader
 
-Compound header bar with `AppHeader`, `AppHeaderSearch`, `AppHeaderActions`, `AppHeaderNotifications`, and `AppHeaderProfile`. Nest search on the left and group switcher, notifications, and profile inside `AppHeaderActions` on the right.
+Compound header bar with `AppHeader`, `AppHeaderSearch`, `AppHeaderActions`, and `AppHeaderNotifications`. Nest search on the left and group switcher, notifications, and profile inside `AppHeaderActions` on the right. The profile trigger is [`ProfilePopover`](/docs/profile-popover) itself (pass `user`/`variant` for the compact header-style trigger) — there's no separate `AppHeaderProfile` component.
 
 See the [AppHeader](/docs/app-header) docs page for props and exported types.
 
@@ -143,7 +232,8 @@ import {
   AppHeaderActions,
   AppHeaderSearch,
   AppHeaderNotifications,
-  AppHeaderProfile,
+  AppHeaderNotificationItem,
+  ProfilePopover,
   AppSwitcher,
 } from "@rfdtech/components";
 
@@ -153,21 +243,20 @@ import {
     <AppSwitcher apps={apps} />
     <AppHeaderNotifications loading={loading}>
       {notifications.map((n) => (
-        <div key={n.id} className="gsl-notif-popover__item">
-          <div className="gsl-notif-popover__body-text">{n.text}</div>
-          <div className="gsl-notif-popover__body-time">{n.time}</div>
-        </div>
+        <AppHeaderNotificationItem key={n.id} text={n.text} time={n.time} unread={n.unread} />
       ))}
     </AppHeaderNotifications>
-    <AppHeaderProfile user={{ name: "Kwame", role: "Admin", initials: "KA" }} variant="basic">
-      <button className="gsl-profile-popover__action">Settings</button>
-    </AppHeaderProfile>
+    <ProfilePopover
+      user={{ name: "Kwame", role: "Admin", initials: "KA" }}
+      variant="avatar"
+      items={[{ label: "Settings", onClick: () => navigate("/settings") }]}
+      onSignOut={signOut}
+    />
   </AppHeaderActions>
 </AppHeader>
 ```
 
-Props: `AppHeader` — `className`, `children`. `AppHeaderActions` — `className`, `children`. Exported types: `AppHeaderProps`, `AppHeaderActionsProps`, `AppHeaderSearchProps`, `AppHeaderSearchDataGroup`, `AppHeaderSearchItem`, `AppHeaderNotificationsProps`, `AppHeaderProfileProps`, `AppUser`.
-
+Props: `AppHeader` — `className`, `children`. `AppHeaderActions` — `className`, `children`. Exported types: `AppHeaderProps`, `AppHeaderActionsProps`, `AppHeaderSearchProps`, `AppHeaderSearchDataGroup`, `AppHeaderSearchItem`, `AppHeaderNotificationsProps`, `AppHeaderNotificationItemProps`. See [ProfilePopover](/docs/profile-popover) for `ProfilePopoverProps` and `AppUser`.
 
 ## AppLayout
 
@@ -189,7 +278,6 @@ import { AppLayout, AppSidebar, AppBody } from "@rfdtech/components";
 
 Props: `AppLayout` — `children`, `className`. `AppSidebar` — `children`, `className`. `AppBody` — `children`, `className`. Exported types: `AppLayoutProps`, `AppSidebarProps`, `AppBodyProps`.
 
-
 ## AppSwitcher
 
 Google Apps–style 9-dot launcher for switching between GSL systems. Drop it into your header to let users jump between products. Pass `apps` directly from your own data layer; use `loading` while data is being fetched.
@@ -215,7 +303,6 @@ Props: `apps`, `loading`, `loadingLabel`, `columns`, `open`, `onOpenChange`, `on
 
 Also exported: `AppSwitcherItem`, `GridIcon`, `SystemAppIcon`, `useAppSwitcher`.
 
-
 ## Badge
 
 Compact inline label for status, counts, and metadata with semantic color variants. See the [Badge](/docs/badge) docs page for props and exported types.
@@ -233,7 +320,6 @@ import { Badge } from "@rfdtech/components";
 
 Props: `variant`, `size`, `classNames`, `className`, and standard `span` attributes. Exported types: `BadgeProps`, `BadgeClassNames`, `BadgeVariant`, `BadgeSize`.
 
-
 ## Breadcrumb
 
 Compound breadcrumb primitives for hierarchical page trails. See the [Breadcrumb](/docs/breadcrumb) docs page for props and exported types.
@@ -263,7 +349,6 @@ import {
 
 Exported parts: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`. Exported types: `BreadcrumbProps`, `BreadcrumbLinkProps`, `BreadcrumbPageProps`, and related `*ClassNames` interfaces.
 
-
 ## BulkImportModal
 
 Four-step modal wizard for importing spreadsheet data (.xlsx, .xls, .csv). Parsing and validation run entirely in the browser.
@@ -307,7 +392,7 @@ The first worksheet is used for multi-sheet workbooks. Discarded rows are exclud
 ### Props
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+| ------ | ------ | --------- | ------------- |
 | `open` | `boolean` | required | Controlled open state |
 | `onOpenChange` | `(open: boolean) => void` | required | Open state callback |
 | `fields` | `BulkImportField[]` | required | Target field schema for column matching |
@@ -418,7 +503,6 @@ To change the gutter size, override `--gsl-bulk-import-gutter` on `.gsl-bulk-imp
 }
 ```
 
-
 ## Button
 
 Shared button with primary, secondary, outline, and ghost variants, plus loading and disabled states. See the [Button](/docs/button) docs page for props and exported types.
@@ -446,7 +530,6 @@ import { Button } from "@rfdtech/components";
 
 Props: `variant`, `size`, `loading`, `loadingLabel`, `classNames`, and standard `button` attributes. Exported types: `ButtonProps`, `ButtonClassNames`, `ButtonVariant`, `ButtonSize`.
 
-
 ## Card
 
 Surface card wrapper with optional header and design tokens for padding and background. Uses `--gsl-surface-card` for background and `--gsl-card-padding` for inner spacing. See the [Card](/docs/card) docs page for props and exported types.
@@ -461,7 +544,6 @@ import { Card } from "@rfdtech/components";
 
 Props: `header`, `children`, `classNames`, `className`, plus standard `div` attributes. Exported types: `CardProps`, `CardClassNames`.
 
-
 ## Checkbox
 
 Accessible checkbox with optional label and part-level `classNames`. See the [Checkbox](/docs/checkbox) docs page for props and exported types.
@@ -484,10 +566,23 @@ import { Checkbox } from "@rfdtech/components";
 
 Props: `checked`, `defaultChecked`, `onCheckedChange`, `label`, `disabled`, `required`, `name`, `value`, `id`, `aria-label`, `classNames`, `className`. Exported types: `CheckboxProps`, `CheckboxClassNames`.
 
+## Combobox
 
-## CountrySelector
+Searchable option list built on `cmdk`, opened from a trigger button — supports single selection, multi-selection with checkboxes, and a per-option leading icon. Unlike `Dropdown` (Radix `Select`-based), it has search built in. See the [Combobox](/docs/combobox) docs page for props and exported types.
 
-Country selector dropdown with flag emoji, country name, search filtering, and keyboard navigation. Built on `@radix-ui/react-popover`. See the [CountrySelector](/docs/country-selector) docs page for props and exported types.
+```tsx
+import { Combobox } from "@rfdtech/components";
+
+<Combobox aria-label="Field" options={options} value={value} onValueChange={setValue} clearable />
+
+<Combobox aria-label="Field" options={options} value={values} onValueChange={setValues} multiple />
+```
+
+Props: `options`, `multiple`, `value`, `onValueChange`, `placeholder`, `searchPlaceholder`, `disabled`, `invalid`, `clearable`, `emptyMessage`, `aria-label`, `classNames`, `className`, `name`. Exported types: `ComboboxProps`, `ComboboxOption`, `ComboboxClassNames`.
+
+## CountrySelector (Deprecated)
+
+**Deprecated** — use [`Combobox`](#combobox) for general country selection, or [`PhoneNumberInput`](#phonenumberinput)'s own built-in country picker for phone numbers. Country selector dropdown with flag emoji, country name, search filtering, and keyboard navigation. Built on `@radix-ui/react-popover`. See the [CountrySelector](/docs/country-selector) docs page for props and exported types.
 
 ```tsx
 import { CountrySelector } from "@rfdtech/components";
@@ -499,7 +594,6 @@ import { CountrySelector } from "@rfdtech/components";
 
 Props: `value`, `defaultValue`, `onChange`, `placeholder`, `invalid`, `disabled`, `classNames`, `className`. Exported types: `CountrySelectorProps`, `CountrySelectorClassNames`.
 
-
 ## DateRangeSelector
 
 Date range picker with a single trigger showing the selected range, a calendar popover for two-click range selection, and auto-swap to keep start before end. See the [DateRangeSelector](/docs/date-range-selector) docs page for props and exported types.
@@ -516,7 +610,6 @@ import { DateRangeSelector } from "@rfdtech/components";
 
 Props: `value`, `defaultValue`, `onChange`, `placeholder`, `formatOptions`, `invalid`, `disabled`, `min`, `max`, `classNames`, `className`. Exported types: `DateRangeSelectorProps`, `DateRangeSelectorClassNames`, `DateRangeValue`.
 
-
 ## DateSelector
 
 Date picker for choosing a single date from a calendar grid. Built on `@radix-ui/react-popover`. See the [DateSelector](/docs/date-selector) docs page for props and exported types.
@@ -535,7 +628,6 @@ import { DateSelector } from "@rfdtech/components";
 
 Props: `value`, `defaultValue`, `onChange`, `placeholder`, `formatOptions`, `invalid`, `disabled`, `min`, `max`, `classNames`, `className`. Exported types: `DateSelectorProps`, `DateSelectorClassNames`.
 
-
 ## Command
 
 Compound command menu primitives for searchable, keyboard-navigable action lists. Supports inline pickers and modal palettes via `CommandDialog`. See the [Command](/docs/command) docs page for props and exported types.
@@ -583,7 +675,6 @@ const { open, onOpenChange, openWith } = useDialogSearchParam("command-menu");
 
 Exports: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandLoading`, `CommandShortcut`, `useCommandShortcut`. Exported types: `CommandProps`, `CommandDialogProps`, `CommandItemProps`, `CommandShortcutProps`, `UseCommandShortcutOptions`, and related `*ClassNames` types.
 
-
 ## RadioGroup
 
 Single-choice radio group with optional labels and descriptions on each `Radio` item. Use `variant="card"` for bordered choice cards. See the [RadioGroup](/docs/radio-group) docs page for props and exported types.
@@ -607,7 +698,6 @@ import { Radio, RadioGroup } from "@rfdtech/components";
 
 Props: `RadioGroup` — `value`, `defaultValue`, `onValueChange`, `name`, `disabled`, `required`, `orientation`, `variant`, `classNames`, `className`, `children`. `Radio` — `value`, `label`, `description`, `disabled`, `id`, `aria-label`, `classNames`, `className`. Exported types: `RadioGroupProps`, `RadioProps`, `RadioGroupClassNames`, `RadioClassNames`, `RadioGroupVariant`.
 
-
 ## Dropdown
 
 Select-style dropdown for choosing one option from a list. See the [Dropdown](/docs/dropdown) docs page for props and exported types.
@@ -630,7 +720,6 @@ import { Dropdown } from "@rfdtech/components";
 
 Props: `value`, `onValueChange`, `options`, `placeholder`, `clearable`, `disabled`, `aria-label`, `classNames`, `className`. Exported types: `DropdownProps`, `DropdownOption`, `DropdownClassNames`.
 
-
 ## Form
 
 Field, Input, and Textarea primitives for accessible form layouts. See the [Form](/docs/form) docs page for props and exported types.
@@ -656,7 +745,6 @@ import {
 
 Exports: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `FieldControl`, `Input`, `Textarea`. Types: `FieldProps`, `FieldClassNames`, `InputProps`, `TextareaProps`.
 
-
 ## FormField
 
 react-hook-form adapters with Zod validation support. See the [FormField](/docs/form-field) docs page for props and exported types.
@@ -713,7 +801,6 @@ const form = useForm<FormValues>({
 
 Exports: `Form`, `FormField`, `useFormField`. Types: `FormProps`, `FormFieldProps`, `UseFormFieldReturn`.
 
-
 ## Dialog
 
 Compound dialog primitives for modal overlays. See the [Dialog](/docs/dialog) docs page for props and exported types.
@@ -753,7 +840,6 @@ const { open, data, onOpenChange, openWith } = useDialogSearchParam<{
 
 Props: `Dialog` — `open`, `defaultOpen`, `onOpenChange`. `DialogContent` — `showCloseButton`, `classNames`, `className`. Styled parts also support part-level `classNames`. Exported types: `DialogOverlayProps`, `DialogContentProps`, `DialogTitleProps`, `DialogDescriptionProps`, and related `*ClassNames` interfaces.
 
-
 ## Draggable
 
 Repositionable panel primitive with optional handle and bounded pointer dragging. See the [Draggable](/docs/draggable) docs page for props and exported types.
@@ -771,7 +857,6 @@ import { Draggable, DraggableHandle } from "@rfdtech/components";
 
 Exports: `Draggable`, `DraggableHandle`, `useDraggable`, `clampPosition`. Types: `DraggableProps`, `DraggableHandleProps`, `DraggablePosition`, `DraggableBounds`, `DraggableAxis`, `UseDraggableOptions`, `UseDraggableReturn`.
 
-
 ## MetricCard
 
 Compact dashboard card for displaying a metric value, label, trend indicator, and optional icon or description. Variants (`default`, `primary`, `success`, `warning`, `error`) only affect the trend color — background and text stay neutral. Use the `color` prop for custom accent colors.
@@ -792,7 +877,6 @@ import { MetricCard } from "@rfdtech/components";
 
 Props: `label`, `value`, `icon`, `description`, `trend`, `trendValue`, `variant`, `color`, `classNames`, `className`, plus standard `div` attributes. Exported types: `MetricCardProps`, `MetricCardClassNames`, `MetricCardVariant`, `MetricTrend`.
 
-
 ## Modal
 
 Centered modal with four size variants (`sm`, `md`, `lg`, `xl`), popover-style border, and optional close-prevention. Size tokens are independently customizable via `--gsl-modal-max-width-*`. See the [Modal](/docs/modal) docs page for props and exported types.
@@ -836,7 +920,6 @@ const { open, onOpenChange, openWith } = useModalSearchParam("review-changes");
 
 Props: `Modal` — `open`, `defaultOpen`, `onOpenChange`. `ModalContent` — `showCloseButton`, `size`, `preventClose`, `preventCloseTitle`, `preventCloseDescription`, `onOpenChange`, `classNames`, `className`. Layout parts (`ModalHeader`, `ModalBody`, `ModalFooter`) support part-level `classNames`. Exported types: `ModalSize`, `ModalOverlayProps`, `ModalContentProps`, `ModalHeaderProps`, `ModalTitleProps`, `ModalDescriptionProps`, `ModalBodyProps`, `ModalFooterProps`, and related `*ClassNames` interfaces.
 
-
 ## NetworkOperator
 
 Network operator selector with operator image thumbnails (MTN, Vodafone, AirtelTigo, Glo), search filtering, and keyboard navigation. Built on `@radix-ui/react-popover`. See the [NetworkOperator](/docs/network-operator) docs page for props and exported types.
@@ -851,6 +934,23 @@ import { NetworkOperator } from "@rfdtech/components";
 
 Props: `value`, `defaultValue`, `onChange`, `options`, `placeholder`, `invalid`, `disabled`, `classNames`, `className`. Exported types: `NetworkOperatorProps`, `NetworkOperatorOption`, `NetworkOperatorClassNames`.
 
+## Notice
+
+Boxed, persistent callout for scoped context, policy explanations, or a standing status message — unlike `Toast`, it renders inline and doesn't auto-dismiss. See the [Notice](/docs/notice) docs page for props and exported types.
+
+```tsx
+import { Notice } from "@rfdtech/components";
+
+<Notice variant="warning" leftBorder dashed title="Your scope for this composer">
+  <ul>
+    <li>Templates: Admissions Directorate only · Audience: 4 pre-approved groups.</li>
+  </ul>
+</Notice>
+
+<Notice variant="success">This will send directly.</Notice>
+```
+
+Props: `variant`, `color`, `title`, `icon`, `leftBorder`, `dashed`, `classNames`, `className`, `children`. Exported types: `NoticeProps`, `NoticeClassNames`, `NoticeVariant`.
 
 ## OtpInput
 
@@ -866,7 +966,6 @@ import { OtpInput } from "@rfdtech/components";
 
 Props: `length`, `value`, `onChange`, `onComplete`, `invalid`, `disabled`, `name`, `classNames`, `className`. Exported types: `OtpInputProps`, `OtpInputClassNames`.
 
-
 ## PhoneNumberInput
 
 Phone number input with a country code selector (flag + dial code prefix) that auto-detects the country from the number prefix as the user types. Built on `@radix-ui/react-popover`. See the [PhoneNumberInput](/docs/phone-number-input) docs page for props and exported types.
@@ -881,7 +980,6 @@ import { PhoneNumberInput } from "@rfdtech/components";
 
 Props: `value`, `defaultValue`, `onChange`, `invalid`, `disabled`, `classNames`, `className`. Exported types: `PhoneNumberInputProps`, `PhoneNumberInputClassNames`.
 
-
 ## Popover
 
 Compound popover primitives for floating panels. See the [Popover](/docs/popover) docs page for props and exported types.
@@ -927,7 +1025,6 @@ import {
 
 Exports: `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverPortal`, `PopoverAnchor`, `PopoverClose`. Exported types: `PopoverContentProps`, `PopoverContentClassNames`.
 
-
 ## ProgressBar
 
 Accessible progress indicator for task completion and loading states. See the [ProgressBar](/docs/progress-bar) docs page for props and exported types.
@@ -942,10 +1039,22 @@ import { ProgressBar } from "@rfdtech/components";
 
 Props: `value`, `max`, `variant`, `size`, `indeterminate`, `label`, `showValue`, `classNames`, `className`, and standard `div` attributes. Exported types: `ProgressBarProps`, `ProgressBarClassNames`, `ProgressBarVariant`, `ProgressBarSize`.
 
+## RouterAdapter
+
+Framework-agnostic router abstraction for Next.js and react-router compatibility.
+
+Seven files that previously imported `react-router-dom` directly (`useTableFilter`, `useTablePagination`, `useTableState`, `TableSearch`, `TableFilter`, `TablePagination`, `SidebarLink`, `AppLayoutInner`) now consume `RouterAdapter` from context. The library ships two entry points:
+
+- `@rfdtech/components` — default, backward compatible (react-router-dom)
+- `@rfdtech/components/next` — Next.js App Router support via `<RouterAdapterProvider>`
+
+See the [RouterAdapter](/docs/router-adapter) docs page for setup instructions.
+
+Exports: `RouterAdapterProvider`, `setRouterAdapter`, `getRouterAdapter`. Types: `RouterAdapterValue`, `RouterSearchParams`, `RouterLinkComponent`.
 
 ## Sidebar
 
-Compound sidebar primitives for app shells and section navigation. Desktop uses a sticky card-style rail with optional collapse; mobile uses an offcanvas drawer with trigger and overlay. See the [Sidebar](/docs/sidebar) docs page for props and exported types.
+Compound sidebar primitives for app shells and section navigation. Desktop uses a sticky card-style rail with optional collapse; mobile uses an offcanvas drawer with trigger and overlay. `SidebarGroup` supports a `collapsible` flag that turns the group label into a button toggle with an animated open/close for the group's content. See the [Sidebar](/docs/sidebar) docs page for props and exported types.
 
 ```tsx
 import {
@@ -992,7 +1101,6 @@ import {
 
 Exports: `SidebarProvider`, `useSidebar`, `Sidebar`, `SidebarBadge`, `SidebarCollapse`, `SidebarTrigger`, `SidebarOverlay`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarNav`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarItem`, `SidebarLink`. Exported types: `SidebarProviderProps`, `SidebarProps`, `SidebarLinkProps`, `SidebarBadgeProps`, `SidebarCollapseProps`, and related `*ClassNames` types.
 
-
 ## Sheet
 
 Compound sheet primitives for edge-sliding panels. See the [Sheet](/docs/sheet) docs page for props and exported types.
@@ -1035,7 +1143,6 @@ import {
 
 Props: `Sheet` — `open`, `defaultOpen`, `onOpenChange`. `SheetContent` — `side`, `showCloseButton`, `classNames`, `className`. Layout parts support part-level `classNames`. Exported types: `SheetSide`, `SheetOverlayProps`, `SheetContentProps`, `SheetHeaderProps`, `SheetTitleProps`, `SheetDescriptionProps`, `SheetBodyProps`, `SheetFooterProps`, and related `*ClassNames` interfaces.
 
-
 ## Sortable
 
 Reorderable list primitive with optional drag handles and keyboard support. See the [Sortable](/docs/sortable) docs page for props and exported types.
@@ -1065,6 +1172,47 @@ const [items, setItems] = useState(["alpha", "beta", "gamma"]);
 
 Exports: `Sortable`, `SortableList`, `SortableItem`, `SortableHandle`, `reorderItems`. Types: `SortableProps`, `SortableListProps`, `SortableItemProps`, `SortableHandleProps`, `SortableId`, `SortableStrategy`, `SortableClassNames`.
 
+## Stepper
+
+Horizontal step indicator for multi-step flows. `Stepper` holds the active step value and derives each `Step`'s `complete` / `active` / `upcoming` state. Each step renders a numbered circle that flips to a check when done, with a connector line that fills between completed steps. Add a `StepLabel` for the step's text. See the [Stepper](/docs/stepper) docs page for props and exported types.
+
+```tsx
+import { useState } from "react";
+import { Step, StepLabel, Stepper } from "@rfdtech/components";
+
+const [step, setStep] = useState(3);
+
+<Stepper value={step} clickable onValueChange={setStep}>
+  <Step value={1}>
+    <StepLabel>Upload Document</StepLabel>
+  </Step>
+  <Step value={2}>
+    <StepLabel>Select header row</StepLabel>
+  </Step>
+  <Step value={3}>
+    <StepLabel>Match Columns</StepLabel>
+  </Step>
+  <Step value={4}>
+    <StepLabel>Validate data</StepLabel>
+  </Step>
+</Stepper>
+```
+
+Exports: `Stepper`, `Step`, `StepLabel`. Also available as `Stepper.Step`, `Stepper.StepLabel` for compound-style imports. Props: `Stepper` — `value`, `clickable`, `onValueChange`, `classNames`, `className`, `children`. `Step` — `value`, `disabled`, `classNames`, `className`, `children`. `StepLabel` — `classNames`, `className`, `children`. Exported types: `StepperProps`, `StepProps`, `StepLabelProps`, `StepperClassNames`, `StepClassNames`, `StepLabelClassNames`, `StepperContextValue`, `StepState`, `StepInternalProps`. Retheme via `--gsl-stepper-accent` (defaults to `--gsl-primary`) and related `--gsl-stepper-*` custom properties.
+
+## Switch
+
+Binary on/off toggle built on `@radix-ui/react-switch`, with an optional label ("Switch + Text"). See the [Switch](/docs/switch) docs page for props and exported types.
+
+```tsx
+import { Switch } from "@rfdtech/components";
+
+<Switch aria-label="Notifications" checked={enabled} onCheckedChange={setEnabled} />
+
+<Switch label="Email alerts" checked={enabled} onCheckedChange={setEnabled} />
+```
+
+Props: `checked`, `defaultChecked`, `onCheckedChange`, `label`, `labelPosition`, `disabled`, `invalid`, `required`, `name`, `value`, `id`, `aria-label`, `classNames`, `className`. Exported types: `SwitchProps`, `SwitchClassNames`.
 
 ## Table
 
@@ -1113,7 +1261,6 @@ const [selected, setSelected] = useState<Set<string | number>>(new Set());
 
 Props: `paramPrefix`, `classNames`, `className`. Exports: `Table`, `TableHeader`, `TableSearch`, `TableFilter`, `TableContent`, `TableBulkActions`, `TableFooter`, `TablePagination`. Types: `TableProps`, `TableHeaderProps`, `TableContentProps`, `TableFooterProps`, `TableSearchProps`, `TableFilterProps`, `TableBulkActionsProps`, `TableBulkAction`, `TableBulkActionsClassNames`, `TableClassNames`, `PaginationControlsProps`, `TableColumn`.
 
-
 ## Tabs
 
 Compound tabs primitives for switching between related panels. See the [Tabs](/docs/tabs) docs page for props and exported types.
@@ -1131,8 +1278,36 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@rfdtech/components";
 </Tabs>
 ```
 
-Exports: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Props: `Tabs` — `value`, `defaultValue`, `onValueChange`, `orientation`, `activationMode`, `variant`, `classNames`, `className`, `children`. `TabsTrigger` — `value`, `disabled`, `classNames`, `className`. Exported types: `TabsProps`, `TabsListProps`, `TabsTriggerProps`, `TabsContentProps`, `TabsVariant`, `TabsClassNames`, `TabsListClassNames`, `TabsTriggerClassNames`, `TabsContentClassNames`.
+Exports: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Props: `Tabs` — `value`, `defaultValue`, `onValueChange`, `orientation`, `activationMode`, `variant` (`"default"`, `"line"`, `"pill"`), `classNames`, `className`, `children`. `TabsTrigger` — `value`, `disabled`, `classNames`, `className`. Exported types: `TabsProps`, `TabsListProps`, `TabsTriggerProps`, `TabsContentProps`, `TabsVariant`, `TabsClassNames`, `TabsListClassNames`, `TabsTriggerClassNames`, `TabsContentClassNames`.
+
+## Timeline
+
+Composable vertical timeline with `Timeline` and `TimelineItem` primitives. Dot color variants for past, current, warning, and error events with optional `color` override. Sub-components `TimelineTitle`, `TimelineData`, and `TimelineFooter` provide styled content slots. Connector animations with staggered draw-in. See the [Timeline](/docs/timeline) docs page for props and exported types.
+
+```tsx
+import {
+  Timeline,
+  TimelineData,
+  TimelineFooter,
+  TimelineItem,
+  TimelineTitle,
+} from "@rfdtech/components";
+import { Check, AlertTriangle } from "lucide-react";
+
+<Timeline>
+  <TimelineItem status="complete" icon={<Check size={10} strokeWidth={3} />}>
+    <TimelineTitle>Case reported</TimelineTitle>
+    <TimelineData>12 Jun 2026</TimelineData>
+    <TimelineFooter>HR Officer intake</TimelineFooter>
+  </TimelineItem>
+  <TimelineItem status="warning" icon={<AlertTriangle size={10} strokeWidth={3} />}>
+    <TimelineTitle>Response overdue</TimelineTitle>
+    <TimelineData>Since 3 Jul 2026</TimelineData>
+  </TimelineItem>
+</Timeline>
+```
 
+Exports: `Timeline`, `TimelineItem`, `TimelineTitle`, `TimelineData`, `TimelineFooter`. Exported types: `TimelineProps`, `TimelineItemProps`, `TimelineTitleProps`, `TimelineDataProps`, `TimelineFooterProps`, `TimelineClassNames`, `TimelineItemClassNames`, `TimelineTitleClassNames`, `TimelineDataClassNames`, `TimelineFooterClassNames`, `TimelineItemMode`.
 
 ## Toast
 
@@ -1159,7 +1334,6 @@ toast({
 
 Exports: `ToastProvider`, `Toaster`, `useToast`. Types: `ToastOptions`, `ToastVariant`, `ToastProviderProps`, `ToasterProps`, `UseToastReturn`, `ToastClassNames`, `ToastAction`, `ToastReturn`.
 
-
 ## Tooltip
 
 Pure-CSS hover tooltip with directional arrow (top, right, bottom, left). Used internally by SidebarLink on the collapsed icon rail. See the [Tooltip](/docs/tooltip) docs page for props and exported types.
@@ -1176,7 +1350,6 @@ import { Tooltip } from "@rfdtech/components";
 
 Props: `content`, `side`, `classNames`, `className`. Exported types: `TooltipProps`, `TooltipClassNames`.
 
-
 ## UploadField
 
 File upload with dashed-border dropzone, cloud upload icon, auto-generated file type/size support text, file cards with type icons, and a primary action button. See the [UploadField](/docs/upload-field) docs page for props and exported types.
@@ -1193,10 +1366,7 @@ import { UploadField } from "@rfdtech/components";
 <UploadField accept="image/*" maxSize={5 * 1024 * 1024} />
 ```
 
-Props: `accept`, `multiple`, `maxSize`, `value`, `onChange`, `invalid`, `disabled`, `name`, `classNames`, `className`. Exported types: `UploadFieldProps`, `UploadFieldClassNames`.
-
-Props: `accept`, `multiple`, `maxSize`, `value`, `onChange`, `invalid`, `disabled`, `placeholder`, `classNames`, `className`. Exported types: `UploadFieldProps`, `UploadFieldClassNames`.
-
+Props: `accept`, `multiple`, `maxSize`, `value`, `onChange`, `invalid`, `disabled`, `name`, `fileStatuses`, `onCancel`, `onRetry`, `classNames`, `className`. Exported types: `UploadFieldProps`, `UploadFieldClassNames`, `UploadFieldFileStatus`, `UploadFieldFileStatusKind`. Also exports `FileFormatIcon` for rendering the same file-type icon standalone.
 
 ## Development
 

package/dist/adapters/context-adapter.d.ts

@@ -0,0 +1,18 @@
+import type { RouterAdapterValue } from "../types/router-adapter";
+/**
+ * Router adapter that reads from `RouterAdapterContext` only.
+ * Throws if no provider is present.
+ *
+ * This adapter has zero dependency on `react-router-dom`.
+ * It is used by the `@rfdtech/components/next` entry point.
+ *
+ * Consumers must wrap their app in `<RouterAdapterProvider>`:
+ *
+ * ```tsx
+ * <RouterAdapterProvider value={adapter}>
+ *   <App />
+ * </RouterAdapterProvider>
+ * ```
+ */
+export declare function useContextRouterAdapter(): RouterAdapterValue;
+//# sourceMappingURL=context-adapter.d.ts.map

package/dist/adapters/context-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/context-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,CAY5D"}