components/pagination/pagination.ts

Functions

Imports

It imports no other module of this repo. Imported by components/pagination/pagination.react.tsx.

Source

1// Pagination's behaviour. A server-rendered pager made of links needs no script at all: the
2// links are the markup. This module is for the client-side form, a nav of buttons that
3// carries its state as data attributes (data-page, data-page-count, data-total,
4// data-per-page, data-noun): a click chooses a page, the list is drawn again, the "Showing
5// 21 to 40 of 312" line (a polite live region) says where the person is, and the app is told
6// with a `cap:page-change` event so it can load that page. The React wrapper uses the same
7// pure functions.
8
9const READY = "data-cap-ready";
10
11export type PageItem = number | "gap-start" | "gap-end";
12
13// The numbers to show for `page` of `count`: always seven slots when there are more than
14// seven pages, so the list never changes width as a person moves. The first and last page
15// are always there; a gap stands for the pages between.
16export function pageItems(page: number, count: number): PageItem[] {
17  const n = Math.max(0, Math.floor(count));
18  if (n <= 7) return Array.from({ length: n }, (_, i) => i + 1);
19  const p = Math.min(Math.max(1, Math.floor(page)), n);
20  if (p <= 4) return [1, 2, 3, 4, 5, "gap-end", n];
21  if (p >= n - 3) return [1, "gap-start", n - 4, n - 3, n - 2, n - 1, n];
22  return [1, "gap-start", p - 1, p, p + 1, "gap-end", n];
23}
24
25// The first and last item on `page`, counted from 1.
26export function showingRange(page: number, perPage: number, total: number): { from: number; to: number } {
27  if (total <= 0 || perPage <= 0) return { from: 0, to: 0 };
28  const from = (page - 1) * perPage + 1;
29  return { from: Math.min(from, total), to: Math.min(page * perPage, total) };
30}
31
32// "Showing 21 to 40 of 312 posts". A page with one item says "Showing 41 of 41 posts".
33export function statusText(page: number, perPage: number, total: number, noun = "items"): string {
34  const { from, to } = showingRange(page, perPage, total);
35  if (total <= 0) return `No ${noun}`;
36  return from === to ? `Showing ${from} of ${total} ${noun}` : `Showing ${from} to ${to} of ${total} ${noun}`;
37}
38
39export function pageCountOf(total: number, perPage: number): number {
40  return perPage > 0 ? Math.max(1, Math.ceil(total / perPage)) : 1;
41}
42
43function el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string): HTMLElementTagNameMap[K] {
44  const node = document.createElement(tag);
45  if (className) node.className = className;
46  if (text !== undefined) node.textContent = text;
47  return node;
48}
49
50function numberOf(value: string | undefined, fallback: number): number {
51  const n = Number(value);
52  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
53}
54
55// Draws the nav's list and status from its data attributes: the markup in pagination.md,
56// with buttons for links.
57export function render(nav: HTMLElement): void {
58  const count = numberOf(nav.dataset.pageCount, 1);
59  const page = Math.min(numberOf(nav.dataset.page, 1), count);
60  const perPage = numberOf(nav.dataset.perPage, 0);
61  const total = Number(nav.dataset.total);
62  const noun = nav.dataset.noun || "items";
63  nav.dataset.page = String(page);
64
65  // The status line is a live region, so it is updated in place: a new node would not be announced.
66  let status = nav.querySelector<HTMLElement>(":scope > .cap-pagination-status");
67  if (perPage > 0 && Number.isFinite(total)) {
68    if (!status) {
69      status = el("p", "cap-pagination-status");
70      status.setAttribute("role", "status");
71      nav.prepend(status);
72    }
73    status.textContent = statusText(page, perPage, total, noun);
74  }
75  const list = el("ul", "cap-pagination-list");
76  const end = (kind: "prev" | "next", label: string, to: number) => {
77    const item = el("li");
78    const b = el("button", "cap-page", label);
79    b.type = "button";
80    b.dataset.kind = kind;
81    if (to < 1 || to > count) b.setAttribute("aria-disabled", "true");
82    else b.dataset.page = String(to);
83    item.append(b);
84    return item;
85  };
86  list.append(end("prev", nav.dataset.prevLabel || "Previous", page - 1));
87  for (const it of pageItems(page, count)) {
88    const item = el("li", "cap-pagination-num");
89    if (typeof it === "number") {
90      const b = el("button", "cap-page", String(it));
91      b.type = "button";
92      b.dataset.page = String(it);
93      b.setAttribute("aria-label", `Page ${it}`);
94      if (it === page) b.setAttribute("aria-current", "page");
95      item.append(b);
96    } else {
97      const gap = el("span", "cap-page-gap");
98      const dots = el("span", undefined, "…");
99      dots.setAttribute("aria-hidden", "true");
100      gap.append(dots, el("span", "cap-sr-only", "More pages"));
101      item.append(gap);
102    }
103    list.append(item);
104  }
105  list.append(el("li", "cap-pagination-where", `Page ${page} of ${count}`));
106  list.append(end("next", nav.dataset.nextLabel || "Next", page + 1));
107  const old = nav.querySelector(":scope > .cap-pagination-list");
108  if (old) old.replaceWith(list);
109  else nav.append(list);
110}
111
112// Goes to a page from script. Draws again, keeps focus on the control that had it (or on the
113// current page when that control is gone), and tells the page. Returns whether the page changed.
114export function setPage(nav: HTMLElement, page: number, options: { silent?: boolean } = {}): boolean {
115  const count = numberOf(nav.dataset.pageCount, 1);
116  const to = Math.min(Math.max(1, Math.floor(page)), count);
117  if (to === numberOf(nav.dataset.page, 1)) return false;
118  const had = nav.contains(document.activeElement);
119  const kind = (document.activeElement as HTMLElement | null)?.dataset?.kind;
120  nav.dataset.page = String(to);
121  render(nav);
122  if (had) {
123    const again = kind ? nav.querySelector<HTMLElement>(`.cap-page[data-kind="${kind}"]:not([aria-disabled="true"])`) : null;
124    (again ?? nav.querySelector<HTMLElement>('.cap-page[aria-current="page"]'))?.focus();
125  }
126  if (!options.silent) nav.dispatchEvent(new CustomEvent("cap:page-change", { bubbles: true, detail: { page: to } }));
127  return true;
128}
129
130// Attaches every [data-cap="pagination"] under root not yet attached. Returns a function
131// that detaches them.
132export function enhance(root: ParentNode = document): () => void {
133  const undo: Array<() => void> = [];
134  for (const nav of root.querySelectorAll<HTMLElement>("[data-cap='pagination']")) {
135    if (nav.hasAttribute(READY)) continue;
136    nav.setAttribute(READY, "");
137    const click = (e: MouseEvent) => {
138      const b = (e.target as HTMLElement).closest<HTMLElement>(".cap-page");
139      if (!b || !nav.contains(b)) return;
140      if (b.getAttribute("aria-disabled") === "true" || b.hasAttribute("aria-current")) {
141        e.preventDefault();
142        return;
143      }
144      if (b.tagName === "A" || !b.dataset.page) return; // links go where they go
145      setPage(nav, Number(b.dataset.page));
146    };
147    nav.addEventListener("click", click);
148    undo.push(() => {
149      nav.removeEventListener("click", click);
150      nav.removeAttribute(READY);
151    });
152  }
153  return () => undo.forEach((f) => f());
154}