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

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @rozie-ui/pagination-lit
+
+## 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: 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: Regenerated with kebab-case attributes for multi-word props: a prop such as `idBase` is now observed as `id-base` (it was the lowercased `idbase`), matching the model props and what a Rozie consumer writes. These packages are new, so the kebab attribute (or the property) is the only form there is.
+  - @rozie/runtime-lit@0.10.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [c279a7e]
+  - @rozie/runtime-lit@0.2.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [364f4c5]
+  - @rozie/runtime-lit@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,89 @@
-# Temporary Holding Version
+# @rozie-ui/pagination-lit
 
-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 **lit** `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-lit
+```
+
+Peer dependencies: `lit + @lit-labs/preact-signals + @preact/signals-core`. Install them alongside this package.
+
+Also installed: `@rozie/runtime-lit` — 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
+
+```ts
+import '@rozie-ui/pagination-lit';
+
+// <rozie-pagination> is a custom element. Bind `modelValue`/`total`/`pageSize`
+// as properties and listen for `model-value-change` (the two-way page) +
+// `change` (the page-change event).
+const el = document.querySelector('rozie-pagination');
+el.total = 195;
+el.pageSize = 10;
+el.modelValue = 1;
+el.addEventListener('model-value-change', (e) => {
+  el.modelValue = e.detail;
+});
+el.addEventListener('change', (e) => {
+  console.log('page:', e.detail.page);
+});
+```
+
+## 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:
+
+```ts
+import '@rozie-ui/pagination-lit/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. |
+
+```ts
+// The custom element IS the handle — exposed methods are public element methods.
+const el = document.querySelector('rozie-pagination');
+el.goto(5);
+el.next();
+el.first();
+```
+
+## Slots
+
+| Slot | Params |
+| --- | --- |
+| prevControl | disabled, goto, page |
+| ellipsis | index |
+| item | page, selected, goto |
+| nextControl | disabled, goto, page |

package/custom-elements.json

@@ -0,0 +1,264 @@
+{
+  "schemaVersion": "2.1.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "dist/index.mjs",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Headless, WAI-ARIA accessible pagination control — a windowed page-item model (numbers + ellipses), prev/next bounds, roving keyboard navigation, scoped slots, and a two-way `modelValue` page binding.",
+          "name": "Pagination",
+          "tagName": "rozie-pagination",
+          "customElement": true,
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "members": [
+            {
+              "kind": "field",
+              "name": "modelValue",
+              "description": "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.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "model-value",
+              "default": "1"
+            },
+            {
+              "kind": "field",
+              "name": "totalPages",
+              "description": "Explicit total page count. When provided (> 0) it takes precedence over `total` + `pageSize`. Use it when the backend already reports the page count.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "total-pages",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "total",
+              "description": "Total item count. Combined with `pageSize` to derive the page count (`ceil(total / pageSize)`) when `totalPages` is not given.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "total",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "pageSize",
+              "description": "Items per page. Combined with `total` to derive the page count when `totalPages` is not given.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "page-size",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "siblingCount",
+              "description": "Number of page buttons shown on each side of the current page (the sibling window). Larger values show more context around the current page.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "sibling-count",
+              "default": "1"
+            },
+            {
+              "kind": "field",
+              "name": "boundaryCount",
+              "description": "Number of page buttons always shown at each boundary (the first and last `boundaryCount` pages), regardless of the current page.",
+              "type": {
+                "text": "number"
+              },
+              "attribute": "boundary-count",
+              "default": "1"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "description": "Disable the entire control — every page button and the prev/next controls become non-interactive and are marked `aria-disabled`.",
+              "type": {
+                "text": "boolean"
+              },
+              "attribute": "disabled",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "ariaLabel",
+              "description": "Accessible name for the surrounding `<nav>` landmark (its `aria-label`). Defaults to `\"Pagination\"`.",
+              "type": {
+                "text": "string"
+              },
+              "attribute": "aria-label",
+              "default": "\"Pagination\""
+            },
+            {
+              "kind": "method",
+              "name": "goto",
+              "description": "Go to a specific 1-based page; the argument is clamped into `[1, totalPages]`. Emits `change` unless the target equals the current page."
+            },
+            {
+              "kind": "method",
+              "name": "next",
+              "description": "Advance to the next page (no-op at the last page). Emits `change` on success."
+            },
+            {
+              "kind": "method",
+              "name": "prev",
+              "description": "Go back to the previous page (no-op at the first page). Emits `change` on success."
+            },
+            {
+              "kind": "method",
+              "name": "first",
+              "description": "Jump to the first page (page 1). Emits `change` unless already there."
+            },
+            {
+              "kind": "method",
+              "name": "last",
+              "description": "Jump to the last page (the effective `totalPages`). Emits `change` unless already there."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "model-value",
+              "description": "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.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "modelValue",
+              "default": "1"
+            },
+            {
+              "name": "total-pages",
+              "description": "Explicit total page count. When provided (> 0) it takes precedence over `total` + `pageSize`. Use it when the backend already reports the page count.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "totalPages",
+              "default": "null"
+            },
+            {
+              "name": "total",
+              "description": "Total item count. Combined with `pageSize` to derive the page count (`ceil(total / pageSize)`) when `totalPages` is not given.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "total",
+              "default": "null"
+            },
+            {
+              "name": "page-size",
+              "description": "Items per page. Combined with `total` to derive the page count when `totalPages` is not given.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "pageSize",
+              "default": "null"
+            },
+            {
+              "name": "sibling-count",
+              "description": "Number of page buttons shown on each side of the current page (the sibling window). Larger values show more context around the current page.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "siblingCount",
+              "default": "1"
+            },
+            {
+              "name": "boundary-count",
+              "description": "Number of page buttons always shown at each boundary (the first and last `boundaryCount` pages), regardless of the current page.",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "boundaryCount",
+              "default": "1"
+            },
+            {
+              "name": "disabled",
+              "description": "Disable the entire control — every page button and the prev/next controls become non-interactive and are marked `aria-disabled`.",
+              "type": {
+                "text": "boolean"
+              },
+              "fieldName": "disabled",
+              "default": "false"
+            },
+            {
+              "name": "aria-label",
+              "description": "Accessible name for the surrounding `<nav>` landmark (its `aria-label`). Defaults to `\"Pagination\"`.",
+              "type": {
+                "text": "string"
+              },
+              "fieldName": "ariaLabel",
+              "default": "\"Pagination\""
+            }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "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."
+            },
+            {
+              "name": "model-value-change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired with the updated `modelValue` (`event.detail`) when it changes."
+            }
+          ],
+          "slots": [
+            {
+              "name": "prevControl",
+              "description": "Scoped slot — props: disabled, goto, page."
+            },
+            {
+              "name": "ellipsis",
+              "description": "Scoped slot — props: index."
+            },
+            {
+              "name": "item",
+              "description": "Scoped slot — props: page, selected, goto."
+            },
+            {
+              "name": "nextControl",
+              "description": "Scoped slot — props: disabled, goto, page."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Pagination",
+          "declaration": {
+            "name": "Pagination",
+            "module": "dist/index.mjs"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "Pagination",
+            "module": "dist/index.mjs"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "rozie-pagination",
+          "declaration": {
+            "name": "Pagination",
+            "module": "dist/index.mjs"
+          }
+        }
+      ]
+    }
+  ]
+}