first commit

docs/ui/react/react-ui/src/components/pagination/pagination.variants.md

@@ -0,0 +1,77 @@
+# Pagination Variants (cva config)
+
+## Purpose
+
+`paginationVariants`, `paginationContentVariants`, `paginationItemVariants`, `paginationLinkVariants`, `paginationPrevNextVariants`, `paginationEllipsisVariants`, and `paginationStatusVariants` are the cva (class-variance-authority) configurations powering every `<Pagination>` slot. They are split from `pagination.tsx` into their own module so an ejected source copy under `npx shadcn@latest add @suaveplan/pagination` keeps the cva configurations in a dedicated file. Theme overrides flow through `useThemedVariants("Pagination<Slot>")`.
+
+The pagination wrapper centres itself horizontally with `mx-auto justify-center` so it sits centred under a paged surface by default; consumers needing a left-aligned trail compose with `cn(...)` to override.
+
+## Features
+
+- Wrapper: `mx-auto flex w-full justify-center` so the trail centres in the available width.
+- Content: flex-row with `gap-1` between page items.
+- Link: shadcn-aligned button conventions (`h-9 px-4` default; `h-8 px-3` sm; `h-9 w-9` icon); active variant adds a border and background; focus-visible ring; smooth-easing colour transition with `motion-reduce:transition-none`.
+- PrevNext: tuned spacing (`gap-1 px-2.5`) for the chevron + label combo.
+- Ellipsis: `flex h-9 w-9` square hit-area matching icon-sized links.
+- Status: `text-sm text-muted-foreground` so the caption recedes under the page heading.
+
+## Usage: Basic Example
+
+```ts
+import {
+    paginationLinkVariants,
+} from "@suaveplan/react-ui";
+
+const className = paginationLinkVariants({ size: "icon", isActive: true });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { paginationContentVariants, cn } from "@suaveplan/react-ui";
+
+export function CompactContent({ children }: { children: React.ReactNode }) {
+    return (
+        <ul className={cn(paginationContentVariants(), "gap-0.5 text-xs")}>
+            {children}
+        </ul>
+    );
+}
+```
+
+## API Reference
+
+### `paginationVariants(): string`
+
+Wrapper class string. No arguments.
+
+### `paginationContentVariants(): string`
+
+`<ul>` class string. No arguments.
+
+### `paginationItemVariants(): string`
+
+`<li>` class string. No arguments (currently empty by design).
+
+### `paginationLinkVariants(props?: { size?: "default" | "sm" | "icon"; isActive?: boolean }): string`
+
+Page-button class string. Defaults to `{ size: "icon", isActive: false }`.
+
+### `paginationPrevNextVariants(): string`
+
+Tuned class string for previous/next combo (gap + horizontal padding).
+
+### `paginationEllipsisVariants(): string`
+
+Ellipsis hit-area class string.
+
+### `paginationStatusVariants(): string`
+
+"Page X of Y" caption class string.
+
+## Implementation Notes
+
+- The link cva uses `focus-visible` (not `focus`) so the ring only appears for keyboard users.
+- `motion-reduce:transition-none` collapses the colour transition for users with `prefers-reduced-motion: reduce`.
+- The `isActive` axis adds a border + background so the active page reads as a button-shaped indicator, matching shadcn upstream's pagination treatment.
+- Per the shadcn skill rule, no numeric `z-index` is assigned anywhere in the cva — pagination is in the document flow, not a stacking layer.