@rozie-ui/pagination-react 0.0.0-stage → 0.1.9

package/src/Pagination.tsx

@@ -0,0 +1,279 @@
+import { Fragment, forwardRef, useCallback, useImperativeHandle, useRef } from 'react';
+import type { ReactNode } from 'react';
+import { flushSync } from 'react-dom';
+import { clsx, mergeListeners, pickListeners, rozieAttr, rozieDisplay, useControllableState } from '@rozie/runtime-react';
+import './Pagination.css';
+import { paginationItems } from './internal/paginationItems';
+
+// ---- derived view (ONE plain function, uniform x6) ---------------------
+// The whole render model in a single call: { totalPages, page, pages,
+// hasPrev, hasNext }. A PLAIN function (not $computed) so it reads uniformly
+// on all six targets and can be aliased in handlers without the Solid
+// accessor divergence. Returns a FRESH object each call — never feed it to a
+// reference-equality $watch getter.
+
+/** The `change` event payload: the page that was just navigated to. */
+export interface PaginationChangePayload {
+  /** The new, clamped, 1-based current page. */
+  page: number;
+}
+
+interface PrevControlCtx { disabled: boolean; goto: () => void; page: number; }
+
+interface EllipsisCtx { index: number; }
+
+interface ItemCtx { page: number; selected: boolean; goto: () => void; }
+
+interface NextControlCtx { disabled: boolean; goto: () => void; page: number; }
+
+interface PaginationProps extends Omit<import('react').ComponentPropsWithoutRef<'nav'>, 'modelValue' | 'defaultModelValue' | 'onModelValueChange' | 'totalPages' | 'total' | 'pageSize' | 'siblingCount' | 'boundaryCount' | 'disabled' | 'ariaLabel' | 'onChange' | 'renderPrevControl' | 'renderEllipsis' | 'renderItem' | 'renderNextControl' | 'slots' | 'children' | 'dangerouslySetInnerHTML'> {
+  /**
+   * The 1-based current page (two-way model). Clamped into `[1, totalPages]`. Bind it with `r-model:modelValue` / `v-model:modelValue` / `modelValue` + `onModelValueChange`; it is also the Angular ControlValueAccessor control value.
+   */
+  modelValue?: number;
+  defaultModelValue?: number;
+  onModelValueChange?: (modelValue: number) => void;
+  /**
+   * Explicit total page count. When provided (> 0) it takes precedence over `total` + `pageSize`. Use it when the backend already reports the page count.
+   */
+  totalPages?: (number) | null;
+  /**
+   * Total item count. Combined with `pageSize` to derive the page count (`ceil(total / pageSize)`) when `totalPages` is not given.
+   */
+  total?: (number) | null;
+  /**
+   * Items per page. Combined with `total` to derive the page count when `totalPages` is not given.
+   */
+  pageSize?: (number) | null;
+  /**
+   * Number of page buttons shown on each side of the current page (the sibling window). Larger values show more context around the current page.
+   */
+  siblingCount?: number;
+  /**
+   * Number of page buttons always shown at each boundary (the first and last `boundaryCount` pages), regardless of the current page.
+   */
+  boundaryCount?: number;
+  /**
+   * Disable the entire control — every page button and the prev/next controls become non-interactive and are marked `aria-disabled`.
+   */
+  disabled?: boolean;
+  /**
+   * Accessible name for the surrounding `<nav>` landmark (its `aria-label`). Defaults to `"Pagination"`.
+   */
+  ariaLabel?: string;
+  onChange?: (payload: PaginationChangePayload) => void;
+  renderPrevControl?: (ctx: PrevControlCtx) => ReactNode;
+  renderEllipsis?: (ctx: EllipsisCtx) => ReactNode;
+  renderItem?: (ctx: ItemCtx) => ReactNode;
+  renderNextControl?: (ctx: NextControlCtx) => ReactNode;
+  slots?: Record<string, () => import('react').ReactNode>;
+}
+
+export interface PaginationHandle {
+  goto: (page: number) => void;
+  next: () => void;
+  prev: () => void;
+  first: () => void;
+  last: () => void;
+}
+
+const Pagination = forwardRef<PaginationHandle, PaginationProps>(function Pagination(_props: PaginationProps, ref): JSX.Element {
+  const props: Omit<PaginationProps, 'totalPages' | 'total' | 'pageSize' | 'siblingCount' | 'boundaryCount' | 'disabled' | 'ariaLabel'> & { totalPages: (number) | null; total: (number) | null; pageSize: (number) | null; siblingCount: number; boundaryCount: number; disabled: boolean; ariaLabel: string } = {
+    ..._props,
+    totalPages: _props.totalPages ?? null,
+    total: _props.total ?? null,
+    pageSize: _props.pageSize ?? null,
+    siblingCount: _props.siblingCount ?? 1,
+    boundaryCount: _props.boundaryCount ?? 1,
+    disabled: _props.disabled ?? false,
+    ariaLabel: _props.ariaLabel ?? 'Pagination',
+  };
+  const attrs: Record<string, unknown> = (() => {
+    const { modelValue, totalPages, total, pageSize, siblingCount, boundaryCount, disabled, ariaLabel, defaultValue, onModelValueChange, defaultModelValue, onChange, renderPrevControl, renderEllipsis, renderItem, renderNextControl, slots, ...rest } = _props as PaginationProps & Record<string, unknown>;
+    void modelValue; void totalPages; void total; void pageSize; void siblingCount; void boundaryCount; void disabled; void ariaLabel; void defaultValue; void onModelValueChange; void defaultModelValue; void onChange; void renderPrevControl; void renderEllipsis; void renderItem; void renderNextControl; void slots;
+    return rest;
+  })();
+  const [modelValue, setModelValue] = useControllableState({
+    value: props.modelValue,
+    defaultValue: props.defaultModelValue ?? 1,
+    onValueChange: props.onModelValueChange,
+  });
+  const nav = useRef<HTMLElement | null>(null);
+
+  // ---- derived view (ONE plain function, uniform x6) ---------------------
+  // The whole render model in a single call: { totalPages, page, pages,
+  // hasPrev, hasNext }. A PLAIN function (not $computed) so it reads uniformly
+  // on all six targets and can be aliased in handlers without the Solid
+  // accessor divergence. Returns a FRESH object each call — never feed it to a
+  // reference-equality $watch getter.
+  function model() {
+    return paginationItems({
+      page: modelValue,
+      totalPages: props.totalPages,
+      total: props.total,
+      pageSize: props.pageSize,
+      siblingCount: props.siblingCount,
+      boundaryCount: props.boundaryCount
+    });
+  }
+
+  // The resolved effective total page count (read in the template + handlers).
+  // NAMED `effectivePages`, NOT `totalPages` — a `totalPages` helper would shadow
+  // the `totalPages` PROP, which on Lit becomes a class field of type `number`
+  // (hard TS2300/TS2717 against a `() => number` helper). The prop-name-collision
+  // sibling of the otp `inputMode` gotcha.
+  function effectivePages() {
+    return model().totalPages;
+  }
+  // The clamped current page (the raw prop may be out of range).
+  function currentPage() {
+    return model().page;
+  }
+  function canPrev() {
+    return model().hasPrev;
+  }
+  function canNext() {
+    return model().hasNext;
+  }
+  function isActive(page: any) {
+    return page === currentPage();
+  }
+
+  // Roving-tabindex value for a control: the active page is a tab stop (0), the
+  // other pages are -1 (arrow keys reach them). The prev/next controls always pass
+  // `true`, so they stay tab stops of their own. The return type is annotated `number | undefined` ON
+  // PURPOSE: the React emitter wraps every numeric `:attr` binding in
+  // `(expr) ?? undefined`, and a PROVABLY non-null value (a bare `0`/`-1` or a
+  // `0 : -1` ternary) trips TS2869 "right operand of ?? is unreachable". Routing
+  // every tabindex through this nullable-typed helper keeps the `?? undefined`
+  // reachable (the data-table cellTabindex precedent).
+  function tabIndexFor(active: any): number | undefined {
+    return active ? 0 : -1;
+  }
+
+  // ---- write funnel (single $emit site) ----------------------------------
+  // Clamp to [1, totalPages], write the model, and emit `change` with the new
+  // page. NOT named `setModelValue` (that collides with React's generated model
+  // setter → ROZ524) — `goToPage` is collision-safe across all six leaves.
+  const { onChange: _rozieProp_onChange } = props;
+    const goToPage = useCallback((page: any) => {
+    if (props.disabled) return;
+    const tp = effectivePages();
+    let target = typeof page === 'number' ? Math.floor(page) : 1;
+    if (target < 1) target = 1;
+    if (target > tp) target = tp;
+    if (target === currentPage()) return;
+    setModelValue(target);
+    _rozieProp_onChange && _rozieProp_onChange({
+      page: target
+    });
+  }, [_rozieProp_onChange, currentPage, effectivePages, props.disabled, setModelValue]);
+  const goNext = useCallback(() => {
+    if (canNext()) goToPage(currentPage() + 1);
+  }, [canNext, currentPage, goToPage]);
+  const goPrev = useCallback(() => {
+    if (canPrev()) goToPage(currentPage() - 1);
+  }, [canPrev, currentPage, goToPage]);
+  function goFirst() {
+    return goToPage(1);
+  }
+  function goLast() {
+    return goToPage(effectivePages());
+  }
+
+  // ---- roving focus across the page controls -----------------------------
+  // Read $refs.nav only here / in handlers (post-mount → ROZ123-safe).
+  // querySelectorAll<HTMLElement> reaches the controls inside Lit's shadow root
+  // too; the generic gives `.focus()` (Element has no `.focus`, TS2339).
+  function controls() {
+    const nav$local = nav.current;
+    if (!nav$local) return [];
+    return Array.from(nav$local.querySelectorAll('[data-page-control]')) as HTMLElement[];
+  }
+  function focusControlAt(idx: any) {
+    const els = controls();
+    if (els.length === 0) return;
+    let i = idx;
+    if (i < 0) i = 0;
+    if (i >= els.length) i = els.length - 1;
+    const el = els[i];
+    if (el && el.focus) el.focus();
+  }
+  function focusedIndex() {
+    const els = controls();
+    const nav$local = nav.current;
+    // The focused element within the nav's OWN root (the document, or the shadow
+    // root on Lit): `ownerDocument.activeElement` stops at the shadow host there and
+    // would never match a control.
+    const root = nav$local ? nav$local.getRootNode() as Document | ShadowRoot : null;
+    const active = root ? root.activeElement : null;
+    return els.indexOf(active as HTMLElement);
+  }
+
+  // Roving keyboard navigation: arrows move focus between controls, Home/End jump
+  // to the ends. Each page control keeps its tabindex via the template (the active
+  // page is 0, the other pages -1), so only the active page is a tab stop among the
+  // page numbers.
+  const onControlKeydown = useCallback(($event: any) => {
+    if (props.disabled) return;
+    const key = $event.key;
+    const cur = focusedIndex();
+    if (key === 'ArrowRight' || key === 'ArrowDown') {
+      $event.preventDefault();
+      focusControlAt(cur + 1);
+    } else if (key === 'ArrowLeft' || key === 'ArrowUp') {
+      $event.preventDefault();
+      focusControlAt(cur - 1);
+    } else if (key === 'Home') {
+      $event.preventDefault();
+      focusControlAt(0);
+    } else if (key === 'End') {
+      $event.preventDefault();
+      focusControlAt(controls().length - 1);
+    }
+  }, [controls, focusControlAt, focusedIndex, props.disabled]);
+  // ---- imperative handle -------------------------------------------------
+  // Consumer-callable verbs. `goto` clamps; `next`/`prev`/`first`/`last` are the
+  // bounds-aware steppers. None collide with an emit name (`change`) or the React
+  // model setter (`setModelValue`).
+  function goto(page: any) {
+    return goToPage(page);
+  }
+  function next() {
+    return goNext();
+  }
+  function prev() {
+    return goPrev();
+  }
+  function first() {
+    return goFirst();
+  }
+  function last() {
+    return goLast();
+  }
+
+  const _rozieExposeRef = useRef({ goto, next, prev, first, last });
+  _rozieExposeRef.current = { goto, next, prev, first, last };
+  useImperativeHandle(ref, () => ({ goto: (...args: Parameters<typeof goto>): ReturnType<typeof goto> => flushSync(() => _rozieExposeRef.current.goto(...args)), next: (...args: Parameters<typeof next>): ReturnType<typeof next> => flushSync(() => _rozieExposeRef.current.next(...args)), prev: (...args: Parameters<typeof prev>): ReturnType<typeof prev> => flushSync(() => _rozieExposeRef.current.prev(...args)), first: (...args: Parameters<typeof first>): ReturnType<typeof first> => flushSync(() => _rozieExposeRef.current.first(...args)), last: (...args: Parameters<typeof last>): ReturnType<typeof last> => flushSync(() => _rozieExposeRef.current.last(...args)) }), []);
+
+  return (
+    <>
+    <nav ref={nav} aria-label={props.ariaLabel} {...attrs} className={clsx(clsx("rozie-pagination", { "rozie-pagination--disabled": props.disabled }), (attrs.className as string | undefined))} {...mergeListeners({ onKeyDown: ($event) => { onControlKeydown($event); } } satisfies import('react').ComponentPropsWithoutRef<'nav'> & Record<string, unknown>, pickListeners(attrs))} data-rozie-s-de247ae2="">
+      
+      {(props.renderPrevControl ?? props.slots?.['prevControl']) ? ((props.renderPrevControl ?? props.slots?.['prevControl']) as Function)({ disabled: !canPrev() || props.disabled, goto: goPrev, page: currentPage() - 1 }) : <button type="button" className={"rozie-pagination-control rozie-pagination-prev"} data-page-control="" tabIndex={tabIndexFor(true)} disabled={!canPrev() || props.disabled} aria-disabled={!!(!canPrev() || props.disabled)} aria-label="Previous page" onClick={goPrev} data-rozie-s-de247ae2="">‹</button>}
+
+      
+      {model().pages.map((item, index) => <Fragment key={item === 'ellipsis' ? 'ellipsis-' + index : item}>
+        {!!(item === 'ellipsis') && <span className={"rozie-pagination-ellipsis"} aria-hidden="true" data-rozie-s-de247ae2="">
+          {(props.renderEllipsis ?? props.slots?.['ellipsis']) ? ((props.renderEllipsis ?? props.slots?.['ellipsis']) as Function)({ index }) : "…"}
+        </span>}{!!(item !== 'ellipsis') && <span className={"rozie-pagination-item"} data-rozie-s-de247ae2="">
+          {(props.renderItem ?? props.slots?.['item']) ? ((props.renderItem ?? props.slots?.['item']) as Function)({ page: item, selected: isActive(item), goto: () => goToPage(item) }) : <button type="button" className={clsx("rozie-pagination-page", { "is-active": isActive(item) })} data-page-control="" tabIndex={tabIndexFor(isActive(item))} disabled={!!props.disabled} aria-disabled={!!props.disabled} aria-current={rozieAttr(isActive(item) ? 'page' : undefined)} aria-label={rozieAttr('Go to page ' + item)} onClick={($event) => { goToPage(item); }} data-rozie-s-de247ae2="">{rozieDisplay(item)}</button>}
+        </span>}</Fragment>)}
+
+      
+      {(props.renderNextControl ?? props.slots?.['nextControl']) ? ((props.renderNextControl ?? props.slots?.['nextControl']) as Function)({ disabled: !canNext() || props.disabled, goto: goNext, page: currentPage() + 1 }) : <button type="button" className={"rozie-pagination-control rozie-pagination-next"} data-page-control="" tabIndex={tabIndexFor(true)} disabled={!canNext() || props.disabled} aria-disabled={!!(!canNext() || props.disabled)} aria-label="Next page" onClick={goNext} data-rozie-s-de247ae2="">›</button>}
+    </nav>
+    </>
+  );
+});
+export default Pagination;

package/src/index.ts

@@ -0,0 +1,6 @@
+export { default as Pagination } from './Pagination';
+export { default } from './Pagination';
+
+/** The `$expose` imperative handle received via `ref` — { goto, next, prev, first, last }. */
+export type { PaginationHandle } from './Pagination';
+export type * from './Pagination';

package/src/internal/paginationItems.ts

@@ -0,0 +1,137 @@
+/**
+ * paginationItems — the pure page-item model for the Pagination family.
+ *
+ * THE branchy core of this no-engine family, extracted to `src/internal/` so it
+ * can be unit-tested in isolation (codegen vendors `src/internal/` into every
+ * leaf via copyInternal, excluding `*.test.ts`) and imported once from
+ * `Pagination.rozie`'s `<script>` as a PLAIN function — never a `$computed`,
+ * since a `$computed` is a value on React but an accessor on Solid, so aliasing
+ * the result in script logic diverges across targets. A plain function called
+ * `()` everywhere is uniform on all six.
+ *
+ * Mirrors the MUI / WAI-ARIA "windowed pager" model: a fixed number of pages at
+ * each boundary (`boundaryCount`), a window of `siblingCount` pages on each side
+ * of the current page, and an `'ellipsis'` marker wherever a gap is collapsed.
+ * The returned `pages` array is FRESH on every call (do not feed it to a
+ * reference-equality `$watch` getter — watch a primitive instead).
+ *
+ * No framework imports, no DOM — pure data in, pure data out.
+ */
+
+export type PaginationItem = number | 'ellipsis';
+
+export interface PaginationInput {
+  /** 1-based current page. Clamped into [1, totalPages]. */
+  page: number;
+  /** Explicit total page count. Wins over `total`/`pageSize` when > 0. */
+  totalPages?: number | null;
+  /** Total item count — used with `pageSize` when `totalPages` is absent. */
+  total?: number | null;
+  /** Items per page — used with `total` when `totalPages` is absent. */
+  pageSize?: number | null;
+  /** Pages shown on each side of the current page. */
+  siblingCount?: number;
+  /** Pages always shown at each boundary (start + end). */
+  boundaryCount?: number;
+}
+
+export interface PaginationModel {
+  /** The resolved effective total page count (always >= 1). */
+  totalPages: number;
+  /** The clamped 1-based current page (always in [1, totalPages]). */
+  page: number;
+  /** The ordered render model: page numbers interleaved with `'ellipsis'`. */
+  pages: PaginationItem[];
+  /** `true` when a previous page exists (page > 1). */
+  hasPrev: boolean;
+  /** `true` when a next page exists (page < totalPages). */
+  hasNext: boolean;
+}
+
+/** Inclusive integer range [start, end]; empty when start > end. */
+function range(start: number, end: number): number[] {
+  const out: number[] = [];
+  for (let i = start; i <= end; i++) out.push(i);
+  return out;
+}
+
+/**
+ * Resolve the effective total page count from either an explicit `totalPages`
+ * or `ceil(total / pageSize)`. Always at least 1 (an empty data set still has a
+ * single page).
+ */
+export function resolveTotalPages(input: PaginationInput): number {
+  const tp = input.totalPages;
+  if (typeof tp === 'number' && tp > 0) return Math.max(1, Math.floor(tp));
+  const total = typeof input.total === 'number' ? input.total : 0;
+  const size = typeof input.pageSize === 'number' && input.pageSize > 0 ? input.pageSize : 0;
+  if (total > 0 && size > 0) return Math.max(1, Math.ceil(total / size));
+  return 1;
+}
+
+/**
+ * Build the windowed page-item model. Pure: no clamping side effects, no DOM.
+ *
+ * Algorithm (MUI usePagination semantics):
+ *   - `startPages` = first `boundaryCount` pages; `endPages` = last
+ *     `boundaryCount` pages.
+ *   - a sibling window of `siblingCount` pages on each side of `page`, kept
+ *     clear of the boundary blocks.
+ *   - an `'ellipsis'` collapses a gap of 2+ pages; a gap of exactly one page is
+ *     rendered as that single bridging page (never a 1-page ellipsis).
+ */
+export function paginationItems(input: PaginationInput): PaginationModel {
+  const totalPages = resolveTotalPages(input);
+
+  const rawPage = typeof input.page === 'number' && Number.isFinite(input.page) ? Math.floor(input.page) : 1;
+  const page = Math.min(Math.max(rawPage, 1), totalPages);
+
+  const siblingCount = Math.max(0, Math.floor(input.siblingCount ?? 1));
+  const boundaryCount = Math.max(0, Math.floor(input.boundaryCount ?? 1));
+
+  // Start/end boundary blocks (clamped to the available pages).
+  const startPages = range(1, Math.min(boundaryCount, totalPages));
+  const endPages = range(Math.max(totalPages - boundaryCount + 1, boundaryCount + 1), totalPages);
+
+  // The sibling window around the current page, kept clear of the boundary
+  // blocks so a boundary page is never duplicated inside the window.
+  const siblingsStart = Math.max(
+    Math.min(page - siblingCount, totalPages - boundaryCount - siblingCount * 2 - 1),
+    boundaryCount + 2,
+  );
+  const endPagesFirst: number | undefined = endPages[0];
+  const siblingsEnd = Math.min(
+    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),
+    endPagesFirst !== undefined ? endPagesFirst - 2 : totalPages - 1,
+  );
+
+  const pages: PaginationItem[] = [];
+
+  pages.push(...startPages);
+
+  // Gap (or single bridging page) between the start block and the window.
+  if (siblingsStart > boundaryCount + 2) {
+    pages.push('ellipsis');
+  } else if (boundaryCount + 1 < totalPages - boundaryCount) {
+    pages.push(boundaryCount + 1);
+  }
+
+  pages.push(...range(siblingsStart, siblingsEnd));
+
+  // Gap (or single bridging page) between the window and the end block.
+  if (siblingsEnd < totalPages - boundaryCount - 1) {
+    pages.push('ellipsis');
+  } else if (totalPages - boundaryCount > boundaryCount) {
+    pages.push(totalPages - boundaryCount);
+  }
+
+  pages.push(...endPages);
+
+  return {
+    totalPages,
+    page,
+    pages,
+    hasPrev: page > 1,
+    hasNext: page < totalPages,
+  };
+}

package/src/themes/base.css

@@ -0,0 +1,74 @@
+/*
+ * @rozie-ui/pagination — base token reference.
+ *
+ * Every COSMETIC value the pagination control renders is a
+ * `--rozie-pagination-*` custom property. The component ships with inline
+ * `var(token, fallback)` defaults, so importing this file is OPTIONAL — it
+ * simply makes the full token surface explicit in one place so you can
+ * copy/override exactly what you need.
+ *
+ * The structural rules (the inline-flex control row, the per-button box model,
+ * the focus-ring, the active page, and the ellipsis cell) live in the
+ * component's scoped `<style>` (per-leaf, NOT consumer-overridable). Only the
+ * values below flow through tokens.
+ *
+ * Override any token at any ancestor scope (`:root`, `.dark`, a wrapper, or the
+ * `.rozie-pagination` element). See themes/shadcn.css, themes/material.css and
+ * themes/bootstrap.css for design-system bridges.
+ *
+ * WHERE THE DEFAULTS SIT. This file declares no public token that could shadow yours. Each
+ * default is the FALLBACK of a private wiring line on the document root, under `:where(:root)`
+ * (zero specificity): `--rpg-x: var(--rozie-pagination-x, <default>)`. The component reads every token
+ * public-first, `var(--rozie-pagination-x, var(--rpg-x, <inline default>))`, so a value set on ANY
+ * ancestor (`:root`, `.dark`, a wrapper) or on the component itself wins by plain inheritance,
+ * in any import order, on all six targets (Lit included: custom properties inherit into its
+ * shadow root). A value an element declares for itself always beats one it would inherit,
+ * which is why nothing on the way to the component may declare a public token.
+ * A token whose default is ANOTHER token is not declared here at all: the component reads it
+ * as `var(<token>, var(<source>, …))`, so it follows the source as resolved AT the component —
+ * declared at the root it would be computed once, against the root's value.
+ * The lines that say `inherit` / `initial` stay plain declarations: at the root such a value
+ * is "unset", so the component's own fallback applies, and it never shadows an ancestor.
+ * A design-system bridge (themes/shadcn.css, material.css, bootstrap.css) re-declares only the
+ * wiring of the tokens it maps, with the design system's variable as the fallback, on the
+ * component (`.rozie-pagination` and the Lit host `rozie-pagination`) — so that variable is resolved AT the
+ * component and follows the nearest theme scope — and on `:root`, the copy a Lit component
+ * nested in another shadow root (out of reach of every document selector) inherits. The
+ * `--rpg-*` names are internal: not a stable API.
+ */
+:where(:root) {
+  /* layout / typography */
+  --rpg-gap: var(--rozie-pagination-gap, 0.25rem);
+  --rozie-pagination-font: inherit;
+  --rpg-font-weight: var(--rozie-pagination-font-weight, 500);
+
+  /* accent — the single color most consumers will set; the active page + focus
+     ring derive from it */
+  --rpg-accent: var(--rozie-pagination-accent, #0066cc);
+
+  /* per-control box model */
+  --rpg-size: var(--rozie-pagination-size, 2.25rem);
+  --rpg-padding-x: var(--rozie-pagination-padding-x, 0.5rem);
+  --rpg-fg: var(--rozie-pagination-fg, #1a1a1a);
+  --rpg-bg: var(--rozie-pagination-bg, transparent);
+  --rpg-border-width: var(--rozie-pagination-border-width, 1px);
+  --rpg-border: var(--rozie-pagination-border, rgba(0, 0, 0, 0.18));
+  --rpg-radius: var(--rozie-pagination-radius, 6px);
+
+  /* hover */
+  --rpg-hover-bg: var(--rozie-pagination-hover-bg, rgba(0, 0, 0, 0.05));
+  --rpg-hover-border: var(--rozie-pagination-hover-border, rgba(0, 0, 0, 0.28));
+
+  /* active (current) page */
+  --rpg-active-fg: var(--rozie-pagination-active-fg, #fff);
+
+  /* focus ring */
+  --rpg-ring-width: var(--rozie-pagination-ring-width, 2px);
+  --rpg-ring-offset: var(--rozie-pagination-ring-offset, 1px);
+
+  /* ellipsis marker */
+  --rpg-ellipsis-fg: var(--rozie-pagination-ellipsis-fg, rgba(0, 0, 0, 0.5));
+
+  /* disabled */
+  --rpg-disabled-opacity: var(--rozie-pagination-disabled-opacity, 0.5);
+}

package/src/themes/bootstrap.css

@@ -0,0 +1,46 @@
+/*
+ * @rozie-ui/pagination — Bootstrap 5 bridge.
+ *
+ * Maps the pagination tokens onto Bootstrap's `--bs-*` CSS variables (Bootstrap
+ * 5.2+). Reading them live means the control follows `data-bs-theme="dark"`
+ * and any custom `$primary` build automatically. Falls back to Bootstrap's
+ * default light palette when the vars are absent.
+ *
+ *   import '@rozie-ui/pagination-react/themes/bootstrap.css';
+ *
+ * HOW IT MAPS. This bridge declares no public token: it re-declares the private wiring of
+ * each token it maps, with the design system's variable as the fallback
+ * (`--rpg-x: var(--rozie-pagination-x, <design-system variable>)`). The component reads every token
+ * public-first, so on all six targets:
+ *  - a public `--rozie-pagination-*` token set on any ancestor (or on the component) wins;
+ *  - otherwise the design system's variable applies, resolved AT the component (`.rozie-pagination`
+ *    and the Lit host `rozie-pagination`), so a `.dark` / `data-bs-theme` wrapper narrower than
+ *    <html> is followed;
+ *  - a Lit component nested in another shadow root, which no document selector reaches,
+ *    inherits the `:root` copy instead: there the design system's variables are read at
+ *    the document root.
+ * This rule outranks base.css's `:where(:root)` wiring, so import order does not matter.
+ */
+:root,
+.rozie-pagination,
+rozie-pagination {
+  --rpg-accent: var(--rozie-pagination-accent, var(--bs-primary, #0d6efd));
+
+  --rpg-fg: var(--rozie-pagination-fg, var(--bs-link-color, #0d6efd));
+  --rpg-bg: var(--rozie-pagination-bg, var(--bs-body-bg, #fff));
+  --rpg-border: var(--rozie-pagination-border, var(--bs-border-color, #dee2e6));
+  --rpg-radius: var(--rozie-pagination-radius, var(--bs-border-radius, 0.375rem));
+
+  --rpg-hover-bg: var(--rozie-pagination-hover-bg, var(--bs-tertiary-bg, #e9ecef));
+  --rpg-hover-border: var(--rozie-pagination-hover-border, var(--bs-border-color, #dee2e6));
+
+  --rpg-active-fg: var(--rozie-pagination-active-fg, #fff);
+  --rpg-active-bg: var(--rozie-pagination-active-bg, var(--bs-primary, #0d6efd));
+  --rpg-active-border: var(--rozie-pagination-active-border, var(--bs-primary, #0d6efd));
+
+  --rpg-ring: var(--rozie-pagination-ring, rgba(var(--bs-primary-rgb, 13, 110, 253), 0.5));
+
+  --rpg-ellipsis-fg: var(--rozie-pagination-ellipsis-fg, var(--bs-secondary-color, #6c757d));
+
+  --rpg-disabled-opacity: var(--rozie-pagination-disabled-opacity, 0.5);
+}

package/src/themes/material.css

@@ -0,0 +1,44 @@
+/*
+ * @rozie-ui/pagination — Material Design 3 bridge.
+ *
+ * Maps the pagination tokens onto the MD3 system color roles
+ * (`--md-sys-color-*`) emitted by material-web / @material/material-color-utilities
+ * theme builders. Falls back to the baseline M3 light palette when those vars
+ * are absent, so it renders correctly even without a generated theme.
+ *
+ *   import '@rozie-ui/pagination-react/themes/material.css';
+ *
+ * HOW IT MAPS. This bridge declares no public token: it re-declares the private wiring of
+ * each token it maps, with the design system's variable as the fallback
+ * (`--rpg-x: var(--rozie-pagination-x, <design-system variable>)`). The component reads every token
+ * public-first, so on all six targets:
+ *  - a public `--rozie-pagination-*` token set on any ancestor (or on the component) wins;
+ *  - otherwise the design system's variable applies, resolved AT the component (`.rozie-pagination`
+ *    and the Lit host `rozie-pagination`), so a `.dark` / `data-bs-theme` wrapper narrower than
+ *    <html> is followed;
+ *  - a Lit component nested in another shadow root, which no document selector reaches,
+ *    inherits the `:root` copy instead: there the design system's variables are read at
+ *    the document root.
+ * This rule outranks base.css's `:where(:root)` wiring, so import order does not matter.
+ */
+:root,
+.rozie-pagination,
+rozie-pagination {
+  --rpg-accent: var(--rozie-pagination-accent, var(--md-sys-color-primary, #6750a4));
+
+  --rpg-fg: var(--rozie-pagination-fg, var(--md-sys-color-on-surface, #1d1b20));
+  --rpg-bg: var(--rozie-pagination-bg, var(--md-sys-color-surface, #fef7ff));
+  --rpg-border: var(--rozie-pagination-border, var(--md-sys-color-outline, #79747e));
+  --rpg-radius: var(--rozie-pagination-radius, 1rem);
+
+  --rpg-hover-bg: var(--rozie-pagination-hover-bg, color-mix(in srgb, var(--md-sys-color-primary, #6750a4) 8%, transparent));
+  --rpg-hover-border: var(--rozie-pagination-hover-border, var(--md-sys-color-outline, #79747e));
+
+  --rpg-active-fg: var(--rozie-pagination-active-fg, var(--md-sys-color-on-primary, #fff));
+  --rpg-active-bg: var(--rozie-pagination-active-bg, var(--md-sys-color-primary, #6750a4));
+  --rpg-active-border: var(--rozie-pagination-active-border, var(--md-sys-color-primary, #6750a4));
+
+  --rpg-ring: var(--rozie-pagination-ring, var(--md-sys-color-primary, #6750a4));
+
+  --rpg-ellipsis-fg: var(--rozie-pagination-ellipsis-fg, var(--md-sys-color-on-surface-variant, #49454f));
+}

package/src/themes/shadcn.css

@@ -0,0 +1,48 @@
+/*
+ * @rozie-ui/pagination — shadcn/ui (Radix) bridge.
+ *
+ * Maps the pagination tokens onto the shadcn/ui CSS variables defined on
+ * `:root` / `.dark` (the classic HSL-channel convention: `--background: 0 0%
+ * 100%` consumed as `hsl(var(--background))`). Because it reads those vars live,
+ * the control automatically follows light/dark theme switches and accent
+ * changes.
+ *
+ *   import '@rozie-ui/pagination-react/themes/shadcn.css';
+ *
+ * If your shadcn setup predates the `hsl()`-wrapping convention (Tailwind v4 /
+ * oklch tokens emit pre-formed colors), drop the `hsl(...)` wrappers below.
+ *
+ * HOW IT MAPS. This bridge declares no public token: it re-declares the private wiring of
+ * each token it maps, with the design system's variable as the fallback
+ * (`--rpg-x: var(--rozie-pagination-x, <design-system variable>)`). The component reads every token
+ * public-first, so on all six targets:
+ *  - a public `--rozie-pagination-*` token set on any ancestor (or on the component) wins;
+ *  - otherwise the design system's variable applies, resolved AT the component (`.rozie-pagination`
+ *    and the Lit host `rozie-pagination`), so a `.dark` / `data-bs-theme` wrapper narrower than
+ *    <html> is followed;
+ *  - a Lit component nested in another shadow root, which no document selector reaches,
+ *    inherits the `:root` copy instead: there the design system's variables are read at
+ *    the document root.
+ * This rule outranks base.css's `:where(:root)` wiring, so import order does not matter.
+ */
+:root,
+.rozie-pagination,
+rozie-pagination {
+  --rpg-accent: var(--rozie-pagination-accent, hsl(var(--primary, 222.2 47.4% 11.2%)));
+
+  --rpg-fg: var(--rozie-pagination-fg, hsl(var(--foreground, 222.2 84% 4.9%)));
+  --rpg-bg: var(--rozie-pagination-bg, hsl(var(--background, 0 0% 100%)));
+  --rpg-border: var(--rozie-pagination-border, hsl(var(--border, 214.3 31.8% 91.4%)));
+  --rpg-radius: var(--rozie-pagination-radius, var(--radius, 0.5rem));
+
+  --rpg-hover-bg: var(--rozie-pagination-hover-bg, hsl(var(--accent, 210 40% 96.1%)));
+  --rpg-hover-border: var(--rozie-pagination-hover-border, hsl(var(--border, 214.3 31.8% 91.4%)));
+
+  --rpg-active-fg: var(--rozie-pagination-active-fg, hsl(var(--primary-foreground, 210 40% 98%)));
+  --rpg-active-bg: var(--rozie-pagination-active-bg, hsl(var(--primary, 222.2 47.4% 11.2%)));
+  --rpg-active-border: var(--rozie-pagination-active-border, hsl(var(--primary, 222.2 47.4% 11.2%)));
+
+  --rpg-ring: var(--rozie-pagination-ring, hsl(var(--ring, 222.2 84% 4.9%)));
+
+  --rpg-ellipsis-fg: var(--rozie-pagination-ellipsis-fg, hsl(var(--muted-foreground, 215.4 16.3% 46.9%)));
+}