feat(ui): build the Pagination component

Replaces a scaffold that rendered a bare list of anchors with real page
controls: compact arrows or windowed page numbers, a range summary, and a
change output carrying the requested page. Out-of-range pages clamp rather
than rendering nothing, because page arrives as an HTML attribute and callers
compute it from data that may have shrunk.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

examples/component-showcase/scripts/showcase-profiles.mjs

@@ -253,6 +253,25 @@ const DATATABLE_ROWS =
   '[{"id": 1, "name": "Northwind", "plan": "Scale", "owner": "A. Okafor", "seats": 6, "status": "Active", "statusHtml": "<span class=\\"showcase-pill showcase-pill--success\\">Active</span>"}, {"id": 2, "name": "Acme Industrial", "plan": "Team", "owner": "R. Silva", "seats": 13, "status": "Trial", "statusHtml": "<span class=\\"showcase-pill showcase-pill--info\\">Trial</span>"}, {"id": 3, "name": "Globex", "plan": "Enterprise", "owner": "M. Chen", "seats": 20, "status": "Past due", "statusHtml": "<span class=\\"showcase-pill showcase-pill--danger\\">Past due</span>"}, {"id": 4, "name": "Initech", "plan": "Starter", "owner": "J. Dubois", "seats": 27, "status": "Active", "statusHtml": "<span class=\\"showcase-pill showcase-pill--success\\">Active</span>"}, {"id": 5, "name": "Umbrella", "plan": "Scale", "owner": "P. Novak", "seats": 34, "status": "Trial", "statusHtml": "<span class=\\"showcase-pill showcase-pill--info\\">Trial</span>"}, {"id": 6, "name": "Stark Labs", "plan": "Team", "owner": "A. Okafor", "seats": 41, "status": "Past due", "statusHtml": "<span class=\\"showcase-pill showcase-pill--danger\\">Past due</span>"}, {"id": 7, "name": "Wayne Foods", "plan": "Enterprise", "owner": "R. Silva", "seats": 48, "status": "Active", "statusHtml": "<span class=\\"showcase-pill showcase-pill--success\\">Active</span>"}, {"id": 8, "name": "Soylent", "plan": "Starter", "owner": "M. Chen", "seats": 55, "status": "Trial", "statusHtml": "<span class=\\"showcase-pill showcase-pill--info\\">Trial</span>"}, {"id": 9, "name": "Hooli", "plan": "Scale", "owner": "J. Dubois", "seats": 62, "status": "Past due", "statusHtml": "<span class=\\"showcase-pill showcase-pill--danger\\">Past due</span>"}, {"id": 10, "name": "Vehement", "plan": "Team", "owner": "P. Novak", "seats": 69, "status": "Active", "statusHtml": "<span class=\\"showcase-pill showcase-pill--success\\">Active</span>"}, {"id": 11, "name": "Massive Dynamic", "plan": "Enterprise", "owner": "A. Okafor", "seats": 76, "status": "Trial", "statusHtml": "<span class=\\"showcase-pill showcase-pill--info\\">Trial</span>"}, {"id": 12, "name": "Cyberdyne", "plan": "Starter", "owner": "R. Silva", "seats": 83, "status": "Past due", "statusHtml": "<span class=\\"showcase-pill showcase-pill--danger\\">Past due</span>"}, {"id": 13, "name": "Tyrell", "plan": "Scale", "owner": "M. Chen", "seats": 90, "status": "Active", "statusHtml": "<span class=\\"showcase-pill showcase-pill--success\\">Active</span>"}, {"id": 14, "name": "Aperture", "plan": "Team", "owner": "J. Dubois", "seats": 97, "status": "Trial", "statusHtml": "<span class=\\"showcase-pill showcase-pill--info\\">Trial</span>"}, {"id": 15, "name": "Black Mesa", "plan": "Enterprise", "owner": "P. Novak", "seats": 104, "status": "Past due", "statusHtml": "<span class=\\"showcase-pill showcase-pill--danger\\">Past due</span>"}]';
 
 export const componentProfiles = {
+  Pagination: {
+    demos: [
+      standard(
+        "Compact arrows",
+        "The default: previous and next with a page counter, and a summary of the range in view.",
+        { page: 2, pageSize: 10, total: 137, variant: "compact" },
+      ),
+      standard(
+        "Numbered pages",
+        "Page numbers windowed around the current page with ellipsis gaps, so a large set never renders hundreds of buttons.",
+        { page: 5, pageSize: 10, total: 200, variant: "numbered", siblingCount: 1 },
+      ),
+      advanced(
+        "Wider window",
+        "siblingCount widens how many pages sit either side of the current one.",
+        { page: 8, pageSize: 25, total: 900, variant: "numbered", siblingCount: 2 },
+      ),
+    ],
+  },
   DataTable: {
     demos: [
       standard(

packages/ui/components/Pagination.wrn

@@ -1,23 +1,262 @@
+// Pagination -- page controls over a known total.
+//
+//   <Pagination page={2} pageSize={10} total={137} variant="numbered" />
+//
+// The component owns no data. It reports the requested page through its
+// change output and lets the caller fetch or slice.
+//
+// NOTE: the style block uses /* */ comments only -- // is not a CSS comment
+// and silently swallows the rule that follows it.
 component Pagination {
   outputs {
-    change(payload: { value?: string | number | boolean | null; values?: Array<string | number | boolean | null | object>; sourceEvent?: Event; [key: string]: string | number | boolean | null | object } | string | number | boolean | null)
-    previous(payload: { sourceEvent?: Event; [key: string]: string | number | boolean | null | object })
-    next(payload: { sourceEvent?: Event; [key: string]: string | number | boolean | null | object })
+    change(payload: { page: number; pageSize: number })
+    previous(payload: { page: number })
+    next(payload: { page: number })
   }
 
   props {
-size: string = "default"
-    color: string = "primary"
+    page: number = 1
+    pageSize: number = 10
+    total: number = 0
+    variant: string = "compact"
+    siblingCount: number = 1
+    showSummary: boolean = true
     label: string = "Pagination"
-    items: unknown[] = []
-    active: string = ""
-    orientation: string = "horizontal"
+    previousLabel: string = "Previous"
+    nextLabel: string = "Next"
     class: string = ""
   }
+
+  functions {
+    shared function lastPage() {
+      var size = Number(pageSize) > 0 ? Number(pageSize) : 10
+      var count = Number(total) > 0 ? Number(total) : 0
+      return Math.max(1, Math.ceil(count / size))
+    }
+
+    // Out-of-range values arrive routinely: page travels as an HTML attribute
+    // and callers compute it from data that may have shrunk underneath them.
+    shared function currentPage() {
+      var value = Number(page)
+      if (!value || value < 1) {
+        return 1
+      }
+      return Math.min(value, lastPage())
+    }
+
+    shared function firstShown() {
+      if (Number(total) < 1) {
+        return 0
+      }
+      return (currentPage() - 1) * (Number(pageSize) || 10) + 1
+    }
+
+    shared function lastShown() {
+      return Math.min(currentPage() * (Number(pageSize) || 10), Number(total) || 0)
+    }
+
+    shared function pageNumbers() {
+      var last = lastPage()
+      var current = currentPage()
+      var siblings = Math.max(0, Number(siblingCount) || 0)
+      var start = Math.max(1, current - siblings)
+      var end = Math.min(last, current + siblings)
+      var pages = []
+      if (start > 1) {
+        pages.push({ value: 1, label: "1", gap: false })
+        if (start > 2) {
+          pages.push({ value: 0, label: "...", gap: true })
+        }
+      }
+      for (var index = start; index <= end; index += 1) {
+        pages.push({ value: index, label: String(index), gap: false })
+      }
+      if (end < last) {
+        if (end < last - 1) {
+          pages.push({ value: 0, label: "...", gap: true })
+        }
+        pages.push({ value: last, label: String(last), gap: false })
+      }
+      return pages
+    }
+
+    client function goToPage(target) {
+      var next = Math.min(Math.max(1, Number(target) || 1), lastPage())
+      output.change({ page: next, pageSize: Number(pageSize) || 10 })
+    }
+
+    client function goPrevious() {
+      var target = Math.max(1, currentPage() - 1)
+      output.previous({ page: target })
+      output.change({ page: target, pageSize: Number(pageSize) || 10 })
+    }
+
+    client function goNext() {
+      var target = Math.min(lastPage(), currentPage() + 1)
+      output.next({ page: target })
+      output.change({ page: target, pageSize: Number(pageSize) || 10 })
+    }
+  }
+
   view {
-    <nav class="wire-next wire-next--color-{color} wire-next--size-{size} wire-next--pagination wire-next--{orientation} {class}" aria-label="{label}">
-      {#each items as item}<a href="{item.href}" aria-current="{item.value === active ? 'page' : ''}">{item.label}</a>{/each}
+    <nav
+      {...attrs}
+      data-ui-component="Pagination"
+      class='wire-pagination {class}'
+      data-variant='{variant}'
+      role="navigation"
+      aria-label='{label}'
+    >
+      <p class="wire-pagination__summary" data-show="showSummary">
+        {firstShown()} to {lastShown()} of {total}
+      </p>
+
+      <div class="wire-pagination__controls">
+        <button
+          type="button"
+          class="wire-pagination__step"
+          aria-label='{previousLabel}'
+          @click='goPrevious()'
+        >
+          <span class="wire-pagination__step-icon" aria-hidden="true">&#8249;</span>
+          <span class="wire-pagination__step-label">{previousLabel}</span>
+        </button>
+
+        <ol class="wire-pagination__pages" data-show="variant === 'numbered'">
+          {#each pageNumbers() as entry}
+            <li class="wire-pagination__slot">
+              <span class="wire-pagination__gap" data-show="entry.gap">{entry.label}</span>
+              <button
+                type="button"
+                class="wire-pagination__page"
+                data-show="!entry.gap"
+                data-active='{entry.value === currentPage()}'
+                aria-current='{entry.value === currentPage() ? "page" : "false"}'
+                @click='goToPage(entry.value)'
+              >
+                {entry.label}
+              </button>
+            </li>
+          {/each}
+        </ol>
+
+        <p class="wire-pagination__compact" data-show="variant !== 'numbered'">
+          {currentPage()} / {lastPage()}
+        </p>
+
+        <button
+          type="button"
+          class="wire-pagination__step"
+          aria-label='{nextLabel}'
+          @click='goNext()'
+        >
+          <span class="wire-pagination__step-label">{nextLabel}</span>
+          <span class="wire-pagination__step-icon" aria-hidden="true">&#8250;</span>
+        </button>
+      </div>
+
       <slot />
     </nav>
   }
+
+  style {
+    .wire-pagination {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      gap: 0.75rem;
+      max-width: 100%;
+    }
+
+    .wire-pagination__summary {
+      margin: 0;
+      color: var(--wire-color-text-muted);
+      font-size: 0.82rem;
+    }
+
+    .wire-pagination__controls {
+      display: flex;
+      align-items: center;
+      gap: 0.35rem;
+      flex-wrap: wrap;
+    }
+
+    .wire-pagination__pages {
+      display: flex;
+      align-items: center;
+      gap: 0.25rem;
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+
+    .wire-pagination__slot {
+      display: inline-flex;
+    }
+
+    .wire-pagination__page,
+    .wire-pagination__step {
+      appearance: none;
+      display: inline-flex;
+      align-items: center;
+      gap: 0.35rem;
+      min-width: 2.25rem;
+      justify-content: center;
+      padding: 0.4rem 0.6rem;
+      border: 1px solid var(--wire-color-border);
+      border-radius: var(--wire-radius-sm);
+      background: var(--wire-color-surface);
+      color: var(--wire-color-text);
+      font: inherit;
+      font-size: 0.85rem;
+      cursor: pointer;
+    }
+
+    .wire-pagination__page:hover,
+    .wire-pagination__step:hover {
+      background: var(--wire-color-surface-soft);
+    }
+
+    .wire-pagination__page:focus-visible,
+    .wire-pagination__step:focus-visible {
+      outline: 2px solid var(--wire-color-primary);
+      outline-offset: 2px;
+    }
+
+    .wire-pagination__page[data-active="true"] {
+      border-color: var(--wire-color-primary);
+      background: var(--wire-color-primary);
+      color: var(--wire-color-primary-contrast);
+      font-weight: 700;
+    }
+
+    .wire-pagination__gap {
+      padding: 0 0.35rem;
+      color: var(--wire-color-text-muted);
+    }
+
+    .wire-pagination__compact {
+      margin: 0;
+      padding: 0 0.5rem;
+      color: var(--wire-color-text-muted);
+      font-size: 0.85rem;
+    }
+
+    /* Below the small breakpoint the word labels crowd the arrows out. */
+    @media (max-width: 639px) {
+      .wire-pagination {
+        justify-content: center;
+      }
+
+      .wire-pagination__step-label {
+        display: none;
+      }
+
+      .wire-pagination__summary {
+        width: 100%;
+        text-align: center;
+      }
+    }
+  }
 }

packages/ui/test/ui.test.ts

@@ -2458,3 +2458,38 @@ test("toggle password supports checkbox control and synchronized password fields
 
   expect(checkboxPassword.type).toBe("text");
 });
+
+test("pagination renders windowed page numbers and emits change", async () => {
+  const source = readFileSync(uiComponentPath("Pagination"), "utf8");
+  const html = await renderComponent(source, {
+    page: 5,
+    pageSize: 10,
+    total: 200,
+    variant: "numbered",
+    siblingCount: 1,
+  });
+  const dom = mountHtml(html);
+  const root = dom.querySelector(".wire-pagination") as HTMLElement;
+
+  expect(root.getAttribute("role")).toBe("navigation");
+  const current = dom.querySelector('.wire-pagination__page[aria-current="page"]');
+  expect(current!.textContent!.trim()).toBe("5");
+  expect(root.textContent).toContain("41");
+  expect(root.textContent).toContain("50");
+  expect(root.textContent).toContain("200");
+});
+
+test("pagination clamps an out-of-range page instead of rendering nothing", async () => {
+  const source = readFileSync(uiComponentPath("Pagination"), "utf8");
+  const html = await renderComponent(source, { page: 99, pageSize: 10, total: 30 });
+  const dom = mountHtml(html);
+  const current = dom.querySelector(".wire-pagination__compact");
+  expect(current!.textContent).toContain("3");
+});
+
+test("pagination survives an empty dataset", async () => {
+  const source = readFileSync(uiComponentPath("Pagination"), "utf8");
+  const html = await renderComponent(source, { page: 1, pageSize: 10, total: 0 });
+  const dom = mountHtml(html);
+  expect(dom.querySelector(".wire-pagination")).not.toBeNull();
+});