feat(ui): <Pagination> stx component (P5)

Drops a paginator from @stacksjs/orm into a layout and renders the
right UI for whichever variant comes back — full Paginator (prev /
page-numbers / next + jumps), SimplePaginator (prev / next), or
CursorPaginator (prev / next with cursor URLs).

The pure algorithms live in @stacksjs/ui/pagination so they're unit-
testable independent of the stx render pipeline:

  - buildPageSequence(current, last, window) → [1, '…', 3, 4, 5, '…', 12]
    Anchors page 1 + last_page; single-page gaps render the page
    instead of an ellipsis (UX nicety — clicking '…' does nothing, so
    showing "2" beats showing "…" when 2 is the only hidden page).
  - urlForPage(view, n) → re-templates the page= param on whichever
    paginator URL is present; preserves all other query params so
    search filters survive (status=active&page=2 → page=5&status=active).
  - paginatorVariant(p) → 'full' | 'simple' | 'cursor' | 'unknown'
    duck-typed mirror of the @stacksjs/orm guards, so the view doesn't
    need a runtime import of orm just to format page numbers.

The stx component (defaults/resources/components/Pagination.stx)
imports these helpers, picks the variant, and emits accessible markup:
<nav aria-label="Pagination">, aria-current="page" on the active, real
<a> tags, mobile breakpoint that drops the page-numbers row in favor
of prev/next, and "Showing X to Y of Z" copy on desktop. Tailwind
classes match the framework's dashboard look + dark mode.

Closes #1909. Refs umbrella #1910.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: glennmichael123

storage/framework/core/ui/src/index.ts

@@ -13,3 +13,13 @@ export {
   renderFontPreloads,
 } from './fonts'
 export type { FontEntry } from './fonts'
+
+// Pagination view helpers — pure functions consumed by the
+// <Pagination> stx component (defaults/resources/components/Pagination.stx).
+// stacksjs/stacks#1909 P5.
+export {
+  buildPageSequence,
+  paginatorVariant,
+  urlForPage,
+} from './pagination'
+export type { PaginatorView } from './pagination'

storage/framework/core/ui/src/pagination.ts

@@ -0,0 +1,115 @@
+/**
+ * Pagination view helpers (stacksjs/stacks#1909, P5 from #1910).
+ *
+ * Pure functions consumed by the `<Pagination>` stx component
+ * (`defaults/resources/components/Pagination.stx`). Extracted here so
+ * the page-sequence + URL-templating logic is unit-testable independent
+ * of the stx render pipeline, and so apps that want to roll their own
+ * pagination UI can reuse the same algorithms.
+ *
+ * The functions operate on the canonical paginator shapes from
+ * `@stacksjs/orm` (Paginator / SimplePaginator / CursorPaginator), but
+ * accept any duck-typed object with the right fields so callers don't
+ * need a runtime import dependency on the orm module just to format
+ * page numbers.
+ */
+
+/**
+ * Subset of {@link Paginator} fields that the view-side helpers actually
+ * touch. Keeping this minimal keeps the helper decoupled from the orm.
+ */
+export interface PaginatorView {
+  current_page?: number
+  last_page?: number
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  first_page_url?: string
+  last_page_url?: string
+}
+
+/**
+ * Build the page-number sequence for a full paginator, inserting an
+ * ellipsis placeholder (`'…'`) for the gap between page 1 / the
+ * current-page window / the last page.
+ *
+ * Examples (window=2):
+ *
+ *   current=5, last=12  → [1, '…', 3, 4, 5, 6, 7, '…', 12]
+ *   current=1, last=3   → [1, 2, 3]                 (window covers all)
+ *   current=1, last=1   → []                        (single page → no UI)
+ *   current=5, last=5   → [1, 2, 3, 4, 5]           (last is current, no trailing ellipsis)
+ *
+ * Always anchors the sequence with `1` and `last_page` (when they
+ * exist and differ from the current window) so users always have a
+ * "jump to start" / "jump to end" affordance.
+ *
+ * @param current   1-indexed current page
+ * @param last      1-indexed last page (`Paginator.last_page`)
+ * @param window    Number of neighbors on EACH side of `current` to
+ *                  show before the ellipsis kicks in. Default 2 gives
+ *                  the canonical compact shape.
+ */
+export function buildPageSequence(
+  current: number,
+  last: number,
+  window: number = 2,
+): Array<number | '…'> {
+  if (last <= 1) return []
+  const out: Array<number | '…'> = []
+  // Window bounds, clamped to [2, last-1] so we don't double-emit 1 or last.
+  const lo = Math.max(2, current - window)
+  const hi = Math.min(last - 1, current + window)
+  out.push(1)
+  // Only emit the leading ellipsis when the gap is >1 page wide; a gap of
+  // exactly 1 (e.g. lo=3, hiding only page 2) is just shown as the real
+  // page number — the ellipsis would be wider on screen than the digit it
+  // replaces, and clicking it does nothing.
+  if (lo === 3) out.push(2)
+  else if (lo > 3) out.push('…')
+  for (let i = lo; i <= hi; i++) out.push(i)
+  // Symmetric for the trailing side.
+  if (hi === last - 2) out.push(last - 1)
+  else if (hi < last - 2) out.push('…')
+  if (last > 1) out.push(last)
+  return out
+}
+
+/**
+ * Compute the URL for a specific page number, re-templating the
+ * `page=N` parameter on whichever existing paginator URL is present.
+ * Preserves all other query params (search filters, sort, etc.) — the
+ * URLs filled in by `enrichPaginatorUrls()` (P2) already carry them,
+ * so the re-template just swaps the page number.
+ *
+ * Falls back to `?page=N` when no template URL is available — covers
+ * the case where the paginator was built outside a request scope (CLI
+ * / queue / cron) and rendered via a non-default view; produces a
+ * relative link that still works against the active page.
+ */
+export function urlForPage(view: PaginatorView, page: number): string {
+  const template = view.next_page_url || view.prev_page_url || view.first_page_url || view.last_page_url
+  if (template) {
+    if (/[?&]page=\d+/.test(template))
+      return template.replace(/([?&])page=\d+/, `$1page=${page}`)
+    // Template has no page= param yet (rare — paginator built without P2
+    // enrichment but a URL was attached manually); append it.
+    return `${template}${template.includes('?') ? '&' : '?'}page=${page}`
+  }
+  return `?page=${page}`
+}
+
+/**
+ * Classify a paginator instance by shape so the view picks the right
+ * UI variant. Returns one of `'full'` / `'simple'` / `'cursor'` based
+ * on which fields are present. This mirrors `isPaginator` /
+ * `isSimplePaginator` / `isCursorPaginator` in `@stacksjs/orm` but
+ * lives here so the view layer doesn't need to import the orm.
+ */
+export function paginatorVariant(p: unknown): 'full' | 'simple' | 'cursor' | 'unknown' {
+  if (p === null || typeof p !== 'object') return 'unknown'
+  const v = p as Record<string, unknown>
+  if ('next_cursor' in v) return 'cursor'
+  if ('total' in v && 'last_page' in v) return 'full'
+  if ('current_page' in v && 'per_page' in v) return 'simple'
+  return 'unknown'
+}

storage/framework/core/ui/tests/pagination.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from 'bun:test'
+import { buildPageSequence, paginatorVariant, urlForPage } from '../src/pagination'
+
+// stacksjs/stacks#1909 (P5) — pagination view helpers.
+
+describe('buildPageSequence', () => {
+  test('empty when there is only one page (no pagination UI needed)', () => {
+    expect(buildPageSequence(1, 1, 2)).toEqual([])
+  })
+
+  test('current page far from both ends: [1, …, lo..hi, …, last]', () => {
+    // current=8 in last=20, window=2 → 6..10 around current, both ellipses fire
+    expect(buildPageSequence(8, 20, 2)).toEqual([1, '…', 6, 7, 8, 9, 10, '…', 20])
+  })
+
+  test('single-page gap shows the page instead of ellipsis (UX nicety)', () => {
+    // current=5, last=12, window=2: pages 3..7 in window, page 2 is the only
+    // page between 1 and lo=3 → show "2" instead of "…" (one-page gap rule)
+    expect(buildPageSequence(5, 12, 2)).toEqual([1, 2, 3, 4, 5, 6, 7, '…', 12])
+  })
+
+  test('current near start: no leading ellipsis at all', () => {
+    expect(buildPageSequence(2, 12, 2)).toEqual([1, 2, 3, 4, '…', 12])
+  })
+
+  test('current near end: no trailing ellipsis', () => {
+    // current=11, last=12, window=2 → lo=9, hi=11, push 9..11, then 12.
+    // page 8 is a single-page gap on the leading side → shown, not ellipsis
+    expect(buildPageSequence(11, 12, 2)).toEqual([1, '…', 9, 10, 11, 12])
+  })
+
+  test('small last_page (window covers everything)', () => {
+    expect(buildPageSequence(2, 3, 2)).toEqual([1, 2, 3])
+  })
+
+  test('current is last page', () => {
+    expect(buildPageSequence(5, 5, 2)).toEqual([1, 2, 3, 4, 5])
+  })
+
+  test('current is first page', () => {
+    expect(buildPageSequence(1, 5, 2)).toEqual([1, 2, 3, 4, 5])
+  })
+
+  test('window=0 still anchors first and last', () => {
+    expect(buildPageSequence(5, 10, 0)).toEqual([1, '…', 5, '…', 10])
+  })
+
+  test('window=1 minimal middle', () => {
+    expect(buildPageSequence(5, 10, 1)).toEqual([1, '…', 4, 5, 6, '…', 10])
+  })
+})
+
+describe('urlForPage', () => {
+  test('re-templates page param on an existing paginator URL', () => {
+    const view = { next_page_url: '/users?page=3&status=active' }
+    expect(urlForPage(view, 5)).toBe('/users?page=5&status=active')
+  })
+
+  test('uses prev_page_url as template if next is null', () => {
+    const view = { next_page_url: null, prev_page_url: '/users?page=1&q=glenn' }
+    expect(urlForPage(view, 4)).toBe('/users?page=4&q=glenn')
+  })
+
+  test('falls back to first/last when prev+next are absent', () => {
+    const view = { first_page_url: '/users?page=1', last_page_url: '/users?page=10' }
+    // first wins because we OR through next → prev → first → last
+    expect(urlForPage(view, 5)).toBe('/users?page=5')
+  })
+
+  test('appends page= when template lacks one (rare manual-URL case)', () => {
+    const view = { first_page_url: '/users?q=glenn' }
+    expect(urlForPage(view, 3)).toBe('/users?q=glenn&page=3')
+  })
+
+  test('appends page with ? when template has no query string', () => {
+    const view = { first_page_url: '/users' }
+    expect(urlForPage(view, 3)).toBe('/users?page=3')
+  })
+
+  test('falls back to relative ?page=N when no templates at all', () => {
+    expect(urlForPage({}, 7)).toBe('?page=7')
+  })
+
+  test('handles & vs ? separators correctly', () => {
+    // Template uses & for non-first param
+    const view = { next_page_url: '/users?status=active&page=2' }
+    expect(urlForPage(view, 5)).toBe('/users?status=active&page=5')
+  })
+})
+
+describe('paginatorVariant', () => {
+  test('classifies full Paginator', () => {
+    expect(paginatorVariant({
+      data: [], current_page: 1, per_page: 10, total: 50, last_page: 5,
+      from: 1, to: 10, has_more_pages: true,
+    })).toBe('full')
+  })
+
+  test('classifies SimplePaginator (no total/last_page)', () => {
+    expect(paginatorVariant({
+      data: [], current_page: 1, per_page: 10, has_more_pages: true,
+    })).toBe('simple')
+  })
+
+  test('classifies CursorPaginator (next_cursor key)', () => {
+    expect(paginatorVariant({
+      data: [], per_page: 10, next_cursor: 'abc', prev_cursor: null, has_more_pages: true,
+    })).toBe('cursor')
+  })
+
+  test('CursorPaginator wins even if other fields happen to be present', () => {
+    // Defensive — duck-type detection priority matters
+    expect(paginatorVariant({
+      data: [], per_page: 10, next_cursor: 'abc', total: 100,
+    })).toBe('cursor')
+  })
+
+  test('non-objects → unknown', () => {
+    expect(paginatorVariant(null)).toBe('unknown')
+    expect(paginatorVariant(undefined)).toBe('unknown')
+    expect(paginatorVariant('string')).toBe('unknown')
+    expect(paginatorVariant([])).toBe('unknown') // arrays are typeof object but excluded
+  })
+})