wiki-formant 0.73.0 → 0.74.0

package/README.md

@@ -467,7 +467,7 @@ are unit-tested without a DOM.
 `FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
 `FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. A chip row above the grid and a panel beside it are the same markup laid out by different stylesheets, so the class names are what tell them apart: `letterRow`, `letterControl` and `letterControlActive` style the A–Z row apart from the facet rows (each falls back to `row`, `control` or `controlActive`); a `text` class wraps each label in its own element and gives a facet option its value as `title`, so a long value can truncate while its count stays in view; and `letterCounts="title"` keeps each letter a bare glyph with its count in the tooltip. With none of them set the markup is what it was. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
 
-`PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
+`Pager` is the "← Previous · Page 2 of 9 · Next →" line, for paged results and for a carousel. Pass `href` and the steps are links (pair it with `paginatedResponse`'s `page` and `totalPages`); pass `onPage` and they are buttons, `wrap` stepping round from either end as a snap row does. A step with nowhere to go stays in place, inert, so the count never jumps sideways, and `spread` puts the steps at the ends of the line. `noun` names what a page is ("Point 2 of 21", "Previous point"). `SnapDots` is a snap row's dots: with `onGo` (`useSnapRow`'s `go`) each is a named button, without it they only count and are hidden from assistive technology. Three sites had written the pager by hand, each stopping at the ends differently, and two had drawn their own dots around the shared hook. `base.css` lays both out; the colours are the site's, the dots' through `--snap-dot` and `--snap-dot-on`.
 
 `RailShell` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the rail's landmark, its scroll wrapper and the three collapse states — including the `--instant` class that keeps a remembered-closed rail from animating shut on first paint, and the close-on-navigate that a mobile drawer needs. Only a followed link closes it: a search field or a table-of-contents entry inside the drawer leaves it open. Compose your own rail inside it and mark the active link with `isRailLinkActive`; all three wikis do, and the pre-composed component that used to sit here had one consumer and had already lost both of those behaviours.
 

package/dist/base.css

@@ -201,6 +201,44 @@ html[data-sidebar='closed'] .wiki-sidebar { width: 0; }
 }
 .breadcrumbs .separator { user-select: none; }
 
+/* ---- Pager and SnapDots -----------------------------------------------------
+   One line that never wraps, the count in tabular figures so stepping does not
+   shift it. A step is a bare control: its colour, size and hit area are the
+   site's, set on `.pager-step`. The dots' colours are `--snap-dot` and
+   `--snap-dot-on`, defaulting to the text colour faint and full. */
+.pager {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--pager-gap, 1rem);
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+.pager[data-spread] { justify-content: space-between; gap: 0; }
+.pager-step { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
+.pager-step:is(:disabled, [aria-disabled='true']) { opacity: 0.4; cursor: default; }
+
+.snap-dots { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--snap-dot-gap, 0); }
+.snap-dots button {
+  display: grid;
+  place-items: center;
+  inline-size: var(--snap-dot-hit, 1.5rem);
+  block-size: var(--snap-dot-hit, 1.5rem);
+  padding: 0;
+  border: 0;
+  background: none;
+  cursor: pointer;
+}
+.snap-dots i {
+  display: block;
+  inline-size: var(--snap-dot-size, 0.5rem);
+  block-size: var(--snap-dot-size, 0.5rem);
+  border-radius: 9999px;
+  background: var(--snap-dot, color-mix(in srgb, currentColor 30%, transparent));
+  transition: background-color 150ms;
+}
+.snap-dots :is(i[data-on], [data-on] > i) { background: var(--snap-dot-on, currentColor); }
+
 /* ---- spinner, skeleton, empty state ----------------------------------------
    The shape and the motion; colour, size and surface are the site's. The
    spinner is a ring in currentColor sized by `--spinner-size`, the skeleton a

package/dist/react-server.d.ts

@@ -195,6 +195,58 @@ export declare function Breadcrumbs({ items, base, className, link: Link, lastAs
 export declare function BreadcrumbsRow({ actions, className, ...props }: BreadcrumbsProps & {
     actions?: ReactNode;
 }): import("react").JSX.Element;
+export interface PagerProps {
+    /** The page showing, from 1. */
+    page: number;
+    total: number;
+    /** Each page's address: the steps are links and the pager ships no JavaScript. */
+    href?: (page: number) => string;
+    /** Or what a step does: the steps are buttons. A carousel passes `go`. */
+    onPage?: (page: number) => void;
+    /** Step round from either end, as a carousel does, instead of stopping. */
+    wrap?: boolean;
+    /** Both steps inert, as while the next page loads. */
+    disabled?: boolean;
+    /** What one page is: the middle reads "<noun> 2 of 9", the steps "Previous <noun>". */
+    noun?: string;
+    prev?: ReactNode;
+    next?: ReactNode;
+    /** The steps at the ends of the line rather than beside the count. */
+    spread?: boolean;
+    /** The landmark's name, when the page has more than one pager. */
+    label?: string;
+    link?: WikiLinkComponent;
+    className?: string;
+}
+/**
+ * "← Previous · Page 2 of 9 · Next →", for search results and for a carousel.
+ *
+ * Three sites wrote this line by hand, two of them for paged results (one with
+ * links, one with buttons) and one for a snap row of points, and each stopped
+ * at the ends differently: a disabled button, an empty span, a wrap. Here a
+ * step at an end with nowhere to go stays in place, inert, so the count does
+ * not jump sideways on the first and last page.
+ */
+export declare function Pager({ page, total, href, onPage, wrap, disabled, noun, prev, next, spread, label, link: Link, className, }: PagerProps): import("react").JSX.Element | null;
+export interface SnapDotsProps {
+    count: number;
+    /** The item showing, from 0: `useSnapRow`'s `at`. */
+    at: number;
+    /** `useSnapRow`'s `go`: each dot becomes a button. Omit it for dots that only count. */
+    onGo?: (i: number) => void;
+    /** What one item is, for each button's name: "Go to <noun> 3". */
+    noun?: string;
+    className?: string;
+}
+/**
+ * A snap row's dots, one per item, the one in view marked.
+ *
+ * With `onGo` each is a button, named, its 0.5rem mark in a 1.5rem target; on a
+ * card whose whole face is already a link it is only a count, `aria-hidden`.
+ * The mark is the `<i>` either way, so one rule draws both, and `data-on`
+ * marks the current one in both.
+ */
+export declare function SnapDots({ count, at, onGo, noun, className }: SnapDotsProps): import("react").JSX.Element | null;
 export interface InfoboxAsideProps {
     /** The landmark's accessible name, e.g. `Key facts about ${title}`. */
     label: string;

package/dist/react-server.js

@@ -148,6 +148,49 @@ export function Breadcrumbs({ items, base, className = '', link: Link = Anchor,
 export function BreadcrumbsRow({ actions, className = '', ...props }) {
     return (_jsxs("div", { className: `breadcrumbs-row ${actions ? 'spread' : ''} ${className}`.trim(), children: [_jsx(Breadcrumbs, { ...props }), actions] }));
 }
+const Arrow = ({ children }) => _jsx("span", { "aria-hidden": "true", children: children });
+/**
+ * "← Previous · Page 2 of 9 · Next →", for search results and for a carousel.
+ *
+ * Three sites wrote this line by hand, two of them for paged results (one with
+ * links, one with buttons) and one for a snap row of points, and each stopped
+ * at the ends differently: a disabled button, an empty span, a wrap. Here a
+ * step at an end with nowhere to go stays in place, inert, so the count does
+ * not jump sideways on the first and last page.
+ */
+export function Pager({ page, total, href, onPage, wrap = false, disabled = false, noun = 'Page', prev = _jsxs(_Fragment, { children: [_jsx(Arrow, { children: "\u2190" }), " Previous"] }), next = _jsxs(_Fragment, { children: ["Next ", _jsx(Arrow, { children: "\u2192" })] }), spread = false, label = `${noun}s`, link: Link = Anchor, className = '', }) {
+    if (total < 2)
+        return null;
+    const to = (dir) => {
+        const p = page + dir;
+        return p >= 1 && p <= total ? p : wrap ? (p < 1 ? total : 1) : null;
+    };
+    const name = noun.toLowerCase();
+    const step = (dir, content) => {
+        const p = disabled ? null : to(dir);
+        const aria = `${dir < 0 ? 'Previous' : 'Next'} ${name}`;
+        if (onPage) {
+            return (_jsx("button", { type: "button", className: "pager-step", "aria-label": aria, disabled: p === null, onClick: () => p !== null && onPage(p), children: content }));
+        }
+        return p !== null && href ? (_jsx(Link, { href: href(p), className: "pager-step", rel: dir < 0 ? 'prev' : 'next', children: content })) : (_jsx("span", { className: "pager-step", "aria-disabled": "true", children: content }));
+    };
+    return (_jsxs("nav", { "aria-label": label, className: `pager ${className}`.trim(), "data-spread": spread || undefined, children: [step(-1, prev), _jsxs("span", { className: "pager-count", "aria-live": onPage ? 'polite' : undefined, children: [noun, " ", page, " of ", total] }), step(1, next)] }));
+}
+/**
+ * A snap row's dots, one per item, the one in view marked.
+ *
+ * With `onGo` each is a button, named, its 0.5rem mark in a 1.5rem target; on a
+ * card whose whole face is already a link it is only a count, `aria-hidden`.
+ * The mark is the `<i>` either way, so one rule draws both, and `data-on`
+ * marks the current one in both.
+ */
+export function SnapDots({ count, at, onGo, noun = 'item', className = '' }) {
+    if (count < 2)
+        return null;
+    const cls = `snap-dots ${className}`.trim();
+    const dots = Array.from({ length: count }, (_, i) => i);
+    return onGo ? (_jsx("span", { className: cls, children: dots.map(i => (_jsx("button", { type: "button", "aria-label": `Go to ${noun} ${i + 1}`, "aria-current": i === at || undefined, "data-on": i === at || undefined, onClick: () => onGo(i), children: _jsx("i", {}) }, i))) })) : (_jsx("span", { className: cls, "aria-hidden": "true", children: dots.map(i => _jsx("i", { "data-on": i === at || undefined }, i)) }));
+}
 /**
  * The facts panel beside an article. Named, because two of the three asides
  * this replaced had no accessible name, and a complementary landmark without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",