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

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# @rozie-ui/pagination-react
+
+## 0.1.9
+
+### Patch Changes
+
+- 3c4b293: README fixes: Angular examples use the component's `<rozie-pagination>` selector (the PascalCase tag they showed fails to compile with NG8001); the Svelte theming import is shown as a TypeScript snippet.
+
+## 0.1.8
+
+### Patch Changes
+
+- 05cb9db: Regenerated with the compiler fixes found while building `@rozie-ui/select`. Depending on the target and the component:
+  - Angular: a two-way (`model: true`) prop is now controlled while the consumer binds a value — a write by the component only emits `<name>Change`, so a consumer that refuses the change keeps the control on its value. The prop keeps its `ModelSignal` type. `$onUpdate` hooks now run (after every render); they never ran before. An output named like a native bubbling event (`change`, `submit`, `reset`, `select`) no longer also delivers the native event to a consumer's binding.
+  - Vue: a two-way prop bound one-way (`:value` without `v-model`) is now controlled too: the component's write emits `update:value` and the control keeps the consumer's value.
+  - React: an `$expose` verb now runs in `flushSync`, so calls made in one tick each see what the call before left; primitive script constants are plain `const`s; a body statement no longer reads a binding declared after it on the first render.
+  - Svelte, Solid: a `$watch` now sees a `$data` write made in `$onMount`.
+  - Lit: a `$watch` whose getter reads both props and `$data` re-runs when only the prop changes; duplicated comments in lifecycle bodies are gone.
+
+- 05cb9db: First release of `@rozie-ui/pagination` on React, Vue, Svelte, Angular and Lit. The Solid leaf has been on npm since the 2026-09-26 wave; all six targets of the family now ship at the same version, so one version number means one component revision everywhere.
+
+  The headless, WAI-ARIA pagination control has a windowed page-item model (page numbers and ellipses with `siblingCount` / `boundaryCount`), a page count from either `totalPages` or `total` + `pageSize`, prev/next bounds, roving keyboard navigation, four scoped slots (`item`, `ellipsis`, `prevControl`, `nextControl`), a two-way `modelValue` (a `ControlValueAccessor` on Angular), a typed `change` event (`{ page }`), `goto` / `next` / `prev` / `first` / `last` handle verbs, and design-system token bridges for shadcn/ui, Material 3 and Bootstrap 5.
+
+  The Vue leaf ships a `web-types.json` and the Lit leaf a `custom-elements.json`, so JetBrains IDEs and `lit-plugin` complete the props, events and slots.
+
+- 05cb9db: Pagination fixes found by the pre-release audit (all six targets):
+  - Activating a page from the keyboard (`Enter` on a page button) dropped focus to `<body>` on React, Vue, Svelte, Angular and Lit, because the list key included the item's position and every window shift re-created the button. Page numbers are now keyed by value, so focus stays on the page just chosen.
+  - Lit: the arrow keys always jumped to "Previous page", because the focused control was read from the document, which stops at the shadow host. It is read from the pager's own root now.
+  - `change` now has a declared payload, `PaginationChangePayload` (`{ page: number }`, exported from the package entry). Before, the Angular output was `unknown` (so `p.page` failed to compile) and Lit had no typed `addEventListener('change')`. A handler written against a different payload shape may now be rejected by the type checker.
+  - The four slot contexts and the handle are typed: `item` / `ellipsis` / `prevControl` / `nextControl` receive `page: number`, `selected: boolean`, `disabled: boolean`, `index: number` and `goto: () => void`; `goto(page: number)`, `next()`, `prev()`, `first()` and `last()` are typed on the handle (they were `any`). A call with a wrong argument is now a type error.
+
+- 05cb9db: React and Solid: slot props passed to the component are no longer part of the attribute pass-through spread onto its root element. On Solid a slot render function passed as `<name>Slot` (or a `slots` record) was written to the DOM as an attribute holding the function source; on React the slot members (`render<Name>`, `children`, `slots`) were left in the rest bucket. Regenerated with the compiler fix; no API change.
+- 05cb9db: Props types now accept the root element's HTML attributes when a component passes attributes through to a single root element (typed public surface, phase 3).
+  - React: `interface XProps extends Omit<React.ComponentPropsWithoutRef<'<tag>'>, …>` — `className`, `style`, `id`, `aria-*`, `data-*`, element-specific attributes (`disabled` on a `<button>` root, …) and DOM listeners typecheck without a cast.
+  - Solid: the same with `ComponentProps<'<tag>'>`.
+  - Svelte: `interface Props extends Omit<SvelteHTMLElements['<tag>'], …>`; an attribute the root element does not support is a type error.
+  - The component's own props win on a name collision. `children` stays rejected when the component has no default slot, as do the content-replacing `dangerouslySetInnerHTML` (React) and `innerHTML` / `innerText` / `textContent` (Solid).
+  - An `<svg>` root gets the SVG element's attributes (`fill`, `stroke`, `viewBox`, …). Any other non-HTML root (a custom element) gets the generic `HTMLAttributes<HTMLElement>` on React and Solid, and Svelte's permissive custom-element entry.
+  - Components with `inherit-attrs="false"`, an `r-if` root or a component root are unchanged. Vue, Angular and Lit are unchanged; they already accepted pass-through attributes.
+
+  The `.d.rozie.ts` sidecars (React, Solid, Svelte) carry the same types. Types only — no runtime change.
+
+- 05cb9db: React: a consumer's DOM listener now fires alongside the component's own handler when the component's root element binds its own `@event` and passes attributes through (the default). Before, the root emitted `<el {...attrs} onClick={own}>`, and JSX's last-wins rule silently dropped the consumer's `onClick` — while Vue, Svelte, Solid and Lit already fired both. The root now emits `{...mergeListeners({ onClick: own }, pickListeners(attrs))}` after its merged `className`, so both handlers fire (own first) and the merged class is never re-applied.
+
+  `@rozie/runtime-react` gains `pickListeners`, the React port of the Solid helper: it filters the pass-through bucket down to function-valued `on*` keys before the merge.
+
+  Every React `mergeListeners(...)` events partial is now typed with `satisfies <element props> & Record<string, unknown>`, so its handlers get the same `$event` type they would have as JSX props — previously the listener-merge partial (e.g. `r-on="$listeners"` plus a local `@click` with `inherit-attrs="false"`) emitted an untyped `$event`, an implicit-`any` error under a strict consumer tsconfig.
+
+- Updated dependencies [b52bd14]
+  - @rozie/runtime-react@0.10.1
+
+## 0.1.2
+
+### Patch Changes
+
+- @rozie/runtime-react@0.2.1
+
+## 0.1.1
+
+### Patch Changes
+
+- @rozie/runtime-react@0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 One Learning Community LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @rozie-ui/pagination-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Idiomatic **react** `Pagination` — a headless, fully-accessible (WAI-ARIA) pagination control (a windowed page-item model with ellipses, sibling/boundary windowing, prev/next bounds, roving keyboard navigation, and a `<nav>` landmark) compiled from one [Rozie](https://github.com/One-Learning-Community/rozie.js) source. It is HEADLESS: expose the page-item model and render each control yourself via the scoped slots, or accept the default token-themed buttons. Every visual value is a CSS custom property, so it re-skins to any design system. This package is generated; do not edit `src/` by hand.
+
+## Install
+
+```bash
+npm i @rozie-ui/pagination-react
+```
+
+Peer dependencies: `react + react-dom`. Install them alongside this package.
+
+Also installed: `@rozie/runtime-react` — Rozie's small, tree-shaken runtime helper package (controllable state, keyboard navigation, event modifiers, and safe interpolation). It arrives as a regular dependency, so npm pulls it for you. Your bundler keeps only the helpers this component actually uses — typically a few hundred bytes to a few KB, minified and gzipped. [What's in it and what it costs](https://github.com/One-Learning-Community/rozie.js/blob/main/docs/guide/output-and-runtime.md).
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Pagination } from '@rozie-ui/pagination-react';
+
+export function Demo() {
+  const [page, setPage] = useState(1);
+  return (
+    <Pagination
+      modelValue={page}
+      onModelValueChange={setPage}
+      total={195}
+      pageSize={10}
+      onChange={(e) => console.log('page:', e.page)}
+    />
+  );
+}
+
+// Headless: render your own page buttons via the renderItem render-prop (a
+// self-closing element — React's scoped slots are props, not children; the
+// equivalent form is slots={{ item: ... }}).
+export function CustomDemo() {
+  const [page, setPage] = useState(1);
+  return (
+    <Pagination
+      modelValue={page}
+      onModelValueChange={setPage}
+      totalPages={20}
+      siblingCount={2}
+      renderItem={({ page, selected, goto }) => (
+        <button aria-current={selected ? 'page' : undefined} onClick={goto}>
+          {page}
+        </button>
+      )}
+    />
+  );
+}
+```
+
+## Theming
+
+Every visual value is a `--rozie-pagination-*` CSS custom property — override any of them at any ancestor scope. Ready-made design-system bridges ship in the package:
+
+```tsx
+import '@rozie-ui/pagination-react/themes/shadcn.css';    // or material.css, bootstrap.css, base.css
+```
+
+## Props
+
+| Name | Type | Default | Two-way (model) | Required | Description |
+| --- | --- | --- | :---: | :---: | --- |
+| `modelValue` | `Number` | `1` | ✓ |  | 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. |
+| `totalPages` | `Number` | `null` |  |  | Explicit total page count. When provided (> 0) it takes precedence over `total` + `pageSize`. Use it when the backend already reports the page count. |
+| `total` | `Number` | `null` |  |  | Total item count. Combined with `pageSize` to derive the page count (`ceil(total / pageSize)`) when `totalPages` is not given. |
+| `pageSize` | `Number` | `null` |  |  | Items per page. Combined with `total` to derive the page count when `totalPages` is not given. |
+| `siblingCount` | `Number` | `1` |  |  | Number of page buttons shown on each side of the current page (the sibling window). Larger values show more context around the current page. |
+| `boundaryCount` | `Number` | `1` |  |  | Number of page buttons always shown at each boundary (the first and last `boundaryCount` pages), regardless of the current page. |
+| `disabled` | `Boolean` | `false` |  |  | Disable the entire control — every page button and the prev/next controls become non-interactive and are marked `aria-disabled`. |
+| `ariaLabel` | `String` | `"Pagination"` |  |  | Accessible name for the surrounding `<nav>` landmark (its `aria-label`). Defaults to `"Pagination"`. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | Fired whenever the current page changes (a page button, prev/next, or a programmatic `goto`/`next`/`prev`/`first`/`last`). Payload `{ page }` — the new clamped 1-based page. Not fired when the target page equals the current page. |
+
+## Imperative handle
+
+Beyond props, the component exposes imperative methods (declared once in the Rozie source via `$expose`). Grab a handle with the native ref mechanism and call them directly:
+
+| Method | Description |
+| --- | --- |
+| `goto` | Go to a specific 1-based page; the argument is clamped into `[1, totalPages]`. Emits `change` unless the target equals the current page. |
+| `next` | Advance to the next page (no-op at the last page). Emits `change` on success. |
+| `prev` | Go back to the previous page (no-op at the first page). Emits `change` on success. |
+| `first` | Jump to the first page (page 1). Emits `change` unless already there. |
+| `last` | Jump to the last page (the effective `totalPages`). Emits `change` unless already there. |
+
+```tsx
+import { useRef } from 'react';
+import { Pagination, type PaginationHandle } from '@rozie-ui/pagination-react';
+
+const pager = useRef<PaginationHandle>(null);
+// <Pagination ref={pager} ... />
+pager.current?.goto(5);
+pager.current?.next();
+pager.current?.first();
+```
+
+## Slots
+
+| Slot | Params |
+| --- | --- |
+| prevControl | disabled, goto, page |
+| ellipsis | index |
+| item | page, selected, goto |
+| nextControl | disabled, goto, page |

package/dist/Pagination.css

@@ -0,0 +1,59 @@
+.rozie-pagination[data-rozie-s-de247ae2] {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--rozie-pagination-gap, var(--rpg-gap, 0.25rem));
+  font: var(--rozie-pagination-font, inherit);
+}
+.rozie-pagination-page[data-rozie-s-de247ae2],
+.rozie-pagination-control[data-rozie-s-de247ae2] {
+  box-sizing: border-box;
+  min-width: var(--rozie-pagination-size, var(--rpg-size, 2.25rem));
+  height: var(--rozie-pagination-size, var(--rpg-size, 2.25rem));
+  padding: 0 var(--rozie-pagination-padding-x, var(--rpg-padding-x, 0.5rem));
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font: inherit;
+  font-weight: var(--rozie-pagination-font-weight, var(--rpg-font-weight, 500));
+  color: var(--rozie-pagination-fg, var(--rpg-fg, #1a1a1a));
+  background: var(--rozie-pagination-bg, var(--rpg-bg, transparent));
+  border: var(--rozie-pagination-border-width, var(--rpg-border-width, 1px)) solid var(--rozie-pagination-border, var(--rpg-border, rgba(0, 0, 0, 0.18)));
+  border-radius: var(--rozie-pagination-radius, var(--rpg-radius, 6px));
+  cursor: pointer;
+  user-select: none;
+  transition: background 0.12s, border-color 0.12s, color 0.12s;
+}
+.rozie-pagination-page[data-rozie-s-de247ae2]:hover,
+.rozie-pagination-control[data-rozie-s-de247ae2]:hover {
+  background: var(--rozie-pagination-hover-bg, var(--rpg-hover-bg, rgba(0, 0, 0, 0.05)));
+  border-color: var(--rozie-pagination-hover-border, var(--rpg-hover-border, rgba(0, 0, 0, 0.28)));
+}
+.rozie-pagination-page[data-rozie-s-de247ae2]:focus-visible,
+.rozie-pagination-control[data-rozie-s-de247ae2]:focus-visible {
+  outline: var(--rozie-pagination-ring-width, var(--rpg-ring-width, 2px)) solid var(--rozie-pagination-ring, var(--rozie-pagination-accent, var(--rpg-ring, var(--rpg-accent, #0066cc))));
+  outline-offset: var(--rozie-pagination-ring-offset, var(--rpg-ring-offset, 1px));
+}
+.rozie-pagination-page.is-active[data-rozie-s-de247ae2] {
+  color: var(--rozie-pagination-active-fg, var(--rpg-active-fg, #fff));
+  background: var(--rozie-pagination-active-bg, var(--rozie-pagination-accent, var(--rpg-active-bg, var(--rpg-accent, #0066cc))));
+  border-color: var(--rozie-pagination-active-border, var(--rozie-pagination-accent, var(--rpg-active-border, var(--rpg-accent, #0066cc))));
+}
+.rozie-pagination-page[data-rozie-s-de247ae2]:disabled,
+.rozie-pagination-control[data-rozie-s-de247ae2]:disabled {
+  cursor: not-allowed;
+  opacity: var(--rozie-pagination-disabled-opacity, var(--rpg-disabled-opacity, 0.5));
+  pointer-events: none;
+}
+.rozie-pagination--disabled[data-rozie-s-de247ae2] {
+  opacity: var(--rozie-pagination-disabled-opacity, var(--rpg-disabled-opacity, 0.5));
+  pointer-events: none;
+}
+.rozie-pagination-ellipsis[data-rozie-s-de247ae2] {
+  min-width: var(--rozie-pagination-size, var(--rpg-size, 2.25rem));
+  height: var(--rozie-pagination-size, var(--rpg-size, 2.25rem));
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--rozie-pagination-ellipsis-fg, var(--rpg-ellipsis-fg, rgba(0, 0, 0, 0.5)));
+  user-select: none;
+}

package/dist/index.cjs

@@ -0,0 +1,311 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let react = require("react");
+let react_dom = require("react-dom");
+let _rozie_runtime_react = require("@rozie/runtime-react");
+require("./Pagination.css");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/internal/paginationItems.ts
+/** Inclusive integer range [start, end]; empty when start > end. */
+function range(start, end) {
+	const out = [];
+	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).
+*/
+function resolveTotalPages(input) {
+	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).
+*/
+function paginationItems(input) {
+	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));
+	const startPages = range(1, Math.min(boundaryCount, totalPages));
+	const endPages = range(Math.max(totalPages - boundaryCount + 1, boundaryCount + 1), totalPages);
+	const siblingsStart = Math.max(Math.min(page - siblingCount, totalPages - boundaryCount - siblingCount * 2 - 1), boundaryCount + 2);
+	const endPagesFirst = endPages[0];
+	const siblingsEnd = Math.min(Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2), endPagesFirst !== void 0 ? endPagesFirst - 2 : totalPages - 1);
+	const pages = [];
+	pages.push(...startPages);
+	if (siblingsStart > boundaryCount + 2) pages.push("ellipsis");
+	else if (boundaryCount + 1 < totalPages - boundaryCount) pages.push(boundaryCount + 1);
+	pages.push(...range(siblingsStart, siblingsEnd));
+	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
+	};
+}
+//#endregion
+//#region src/Pagination.tsx
+const Pagination = (0, react.forwardRef)(function Pagination(_props, ref) {
+	const props = {
+		..._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 = (() => {
+		const { modelValue, totalPages, total, pageSize, siblingCount, boundaryCount, disabled, ariaLabel, defaultValue, onModelValueChange, defaultModelValue, onChange, renderPrevControl, renderEllipsis, renderItem, renderNextControl, slots, ...rest } = _props;
+		return rest;
+	})();
+	const [modelValue, setModelValue] = (0, _rozie_runtime_react.useControllableState)({
+		value: props.modelValue,
+		defaultValue: props.defaultModelValue ?? 1,
+		onValueChange: props.onModelValueChange
+	});
+	const nav = (0, react.useRef)(null);
+	function model() {
+		return paginationItems({
+			page: modelValue,
+			totalPages: props.totalPages,
+			total: props.total,
+			pageSize: props.pageSize,
+			siblingCount: props.siblingCount,
+			boundaryCount: props.boundaryCount
+		});
+	}
+	function effectivePages() {
+		return model().totalPages;
+	}
+	function currentPage() {
+		return model().page;
+	}
+	function canPrev() {
+		return model().hasPrev;
+	}
+	function canNext() {
+		return model().hasNext;
+	}
+	function isActive(page) {
+		return page === currentPage();
+	}
+	function tabIndexFor(active) {
+		return active ? 0 : -1;
+	}
+	const { onChange: _rozieProp_onChange } = props;
+	const goToPage = (0, react.useCallback)((page) => {
+		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 = (0, react.useCallback)(() => {
+		if (canNext()) goToPage(currentPage() + 1);
+	}, [
+		canNext,
+		currentPage,
+		goToPage
+	]);
+	const goPrev = (0, react.useCallback)(() => {
+		if (canPrev()) goToPage(currentPage() - 1);
+	}, [
+		canPrev,
+		currentPage,
+		goToPage
+	]);
+	function goFirst() {
+		return goToPage(1);
+	}
+	function goLast() {
+		return goToPage(effectivePages());
+	}
+	function controls() {
+		const nav$local = nav.current;
+		if (!nav$local) return [];
+		return Array.from(nav$local.querySelectorAll("[data-page-control]"));
+	}
+	function focusControlAt(idx) {
+		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;
+		const root = nav$local ? nav$local.getRootNode() : null;
+		const active = root ? root.activeElement : null;
+		return els.indexOf(active);
+	}
+	const onControlKeydown = (0, react.useCallback)(($event) => {
+		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
+	]);
+	function goto(page) {
+		return goToPage(page);
+	}
+	function next() {
+		return goNext();
+	}
+	function prev() {
+		return goPrev();
+	}
+	function first() {
+		return goFirst();
+	}
+	function last() {
+		return goLast();
+	}
+	const _rozieExposeRef = (0, react.useRef)({
+		goto,
+		next,
+		prev,
+		first,
+		last
+	});
+	_rozieExposeRef.current = {
+		goto,
+		next,
+		prev,
+		first,
+		last
+	};
+	(0, react.useImperativeHandle)(ref, () => ({
+		goto: (...args) => (0, react_dom.flushSync)(() => _rozieExposeRef.current.goto(...args)),
+		next: (...args) => (0, react_dom.flushSync)(() => _rozieExposeRef.current.next(...args)),
+		prev: (...args) => (0, react_dom.flushSync)(() => _rozieExposeRef.current.prev(...args)),
+		first: (...args) => (0, react_dom.flushSync)(() => _rozieExposeRef.current.first(...args)),
+		last: (...args) => (0, react_dom.flushSync)(() => _rozieExposeRef.current.last(...args))
+	}), []);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("nav", {
+		ref: nav,
+		"aria-label": props.ariaLabel,
+		...attrs,
+		className: (0, _rozie_runtime_react.clsx)((0, _rozie_runtime_react.clsx)("rozie-pagination", { "rozie-pagination--disabled": props.disabled }), attrs.className),
+		...(0, _rozie_runtime_react.mergeListeners)({ onKeyDown: ($event) => {
+			onControlKeydown($event);
+		} }, (0, _rozie_runtime_react.pickListeners)(attrs)),
+		"data-rozie-s-de247ae2": "",
+		children: [
+			props.renderPrevControl ?? props.slots?.["prevControl"] ? (props.renderPrevControl ?? props.slots?.["prevControl"])({
+				disabled: !canPrev() || props.disabled,
+				goto: goPrev,
+				page: currentPage() - 1
+			}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("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": "",
+				children: "‹"
+			}),
+			model().pages.map((item, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [!!(item === "ellipsis") && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "rozie-pagination-ellipsis",
+				"aria-hidden": "true",
+				"data-rozie-s-de247ae2": "",
+				children: props.renderEllipsis ?? props.slots?.["ellipsis"] ? (props.renderEllipsis ?? props.slots?.["ellipsis"])({ index }) : "…"
+			}), !!(item !== "ellipsis") && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "rozie-pagination-item",
+				"data-rozie-s-de247ae2": "",
+				children: props.renderItem ?? props.slots?.["item"] ? (props.renderItem ?? props.slots?.["item"])({
+					page: item,
+					selected: isActive(item),
+					goto: () => goToPage(item)
+				}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					className: (0, _rozie_runtime_react.clsx)("rozie-pagination-page", { "is-active": isActive(item) }),
+					"data-page-control": "",
+					tabIndex: tabIndexFor(isActive(item)),
+					disabled: !!props.disabled,
+					"aria-disabled": !!props.disabled,
+					"aria-current": (0, _rozie_runtime_react.rozieAttr)(isActive(item) ? "page" : void 0),
+					"aria-label": (0, _rozie_runtime_react.rozieAttr)("Go to page " + item),
+					onClick: ($event) => {
+						goToPage(item);
+					},
+					"data-rozie-s-de247ae2": "",
+					children: (0, _rozie_runtime_react.rozieDisplay)(item)
+				})
+			})] }, item === "ellipsis" ? "ellipsis-" + index : item)),
+			props.renderNextControl ?? props.slots?.["nextControl"] ? (props.renderNextControl ?? props.slots?.["nextControl"])({
+				disabled: !canNext() || props.disabled,
+				goto: goNext,
+				page: currentPage() + 1
+			}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("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": "",
+				children: "›"
+			})
+		]
+	}) });
+});
+//#endregion
+exports.Pagination = Pagination;
+exports.default = Pagination;

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+import * as _$react from "react";
+import { ReactNode } from "react";
+
+//#region src/Pagination.d.ts
+/** The `change` event payload: the page that was just navigated to. */
+interface PaginationChangePayload {
+  /** The new, clamped, 1-based current page. */
+  page: number;
+}
+interface PaginationProps extends Omit<_$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?: (next: 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?: (params: {
+    disabled: boolean;
+    goto: () => void;
+    page: number;
+  }) => ReactNode;
+  renderEllipsis?: (params: {
+    index: number;
+  }) => ReactNode;
+  renderItem?: (params: {
+    page: number;
+    selected: boolean;
+    goto: () => void;
+  }) => ReactNode;
+  renderNextControl?: (params: {
+    disabled: boolean;
+    goto: () => void;
+    page: number;
+  }) => ReactNode;
+  slots?: Record<string, () => ReactNode>;
+}
+interface PaginationHandle {
+  goto: (page: number) => void;
+  next: () => void;
+  prev: () => void;
+  first: () => void;
+  last: () => void;
+}
+declare const Pagination: _$react.ForwardRefExoticComponent<PaginationProps & _$react.RefAttributes<PaginationHandle>>;
+//#endregion
+export { Pagination, Pagination as default, PaginationChangePayload, type PaginationHandle, PaginationProps };