@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/utils/pluginFormatters.js

@@ -0,0 +1,714 @@
+/**
+ * Shared plugin formatting utilities for ngdpbase plugins.
+ * Implements the common output formats defined in issue #238 (Code Consolidation).
+ *
+ * All plugins should use these helpers to ensure consistent behaviour for
+ * `max`, `format`, `before`, and `after` parameters across the platform.
+ *
+ * Owned by PluginManager (#1820). Plugins use `context.formatters`; other
+ * callers use `engine.getManager('PluginManager').formatters`. Direct imports
+ * of this module are being retired; types stay importable with `import type`.
+ */
+/**
+ * Parse a `max` plugin parameter to an integer.
+ * Returns `defaultMax` if the value is missing, empty, or non-numeric.
+ * A value of 0 means unlimited.
+ */
+export function parseMaxParam(value, defaultMax = 0) {
+    if (value === undefined || value === null || value === '')
+        return defaultMax;
+    const n = parseInt(String(value), 10);
+    return isNaN(n) || n < 0 ? defaultMax : n;
+}
+/**
+ * Apply a max limit to an array.
+ * max=0 means unlimited (returns all items unchanged).
+ */
+export function applyMax(items, max) {
+    return max > 0 ? items.slice(0, max) : items;
+}
+/**
+ * Escape HTML special characters.
+ * Accepts any primitive value; null/undefined return an empty string.
+ */
+export function escapeHtml(text) {
+    if (text === null || text === undefined)
+        return '';
+    const map = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#039;'
+    };
+    return String(text).replace(/[&<>"']/g, m => map[m]);
+}
+/**
+ * Format a list of page links as an HTML bullet list.
+ * Supports optional `before`/`after` markers around each item (JSPWiki-style).
+ * Returns an informational message when the list is empty.
+ */
+export function formatAsList(links, options = {}) {
+    if (links.length === 0) {
+        return '<p><em>No pages found.</em></p>';
+    }
+    const before = options.before ?? '';
+    const after = options.after ?? '';
+    const processedBefore = before.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+    const processedAfter = after.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+    const buildAnchor = (link) => {
+        const cls = link.cssClass ? ` class="${link.cssClass}"` : '';
+        const style = link.style ? ` style="${link.style}"` : '';
+        const title = link.title ? ` title="${escapeHtml(link.title)}"` : '';
+        const icon = link.icon ? `<i class="${escapeHtml(link.icon)}"></i> ` : '';
+        return `<a href="${link.href}"${cls}${style}${title}>${icon}${escapeHtml(link.text)}</a>`;
+    };
+    // #1306: a row is the anchor plus whatever rides along with it. A link with
+    // neither a badge nor an action renders exactly the markup it always did —
+    // the eight plugins already calling this must not change.
+    const buildItem = (link) => {
+        const anchor = buildAnchor(link);
+        const badge = link.badge !== undefined
+            ? `<span class="badge bg-secondary">${escapeHtml(link.badge)}</span>`
+            : '';
+        const trailing = link.trailingHtml ?? '';
+        if (!badge && !trailing)
+            return anchor;
+        return `<span class="d-flex align-items-center justify-content-between w-100">${anchor}${badge}${trailing}</span>`;
+    };
+    const itemAttr = options.itemClass ? ` class="${options.itemClass}"` : '';
+    const listAttr = options.listClass ? ` class="${options.listClass}"` : '';
+    const renderItems = () => links.map(l => `<li${itemAttr}>${buildItem(l)}</li>`).join('\n');
+    if (processedBefore || processedAfter) {
+        const isList = processedBefore.includes('*') || processedBefore.includes('-');
+        if (isList) {
+            return `<ul${listAttr}>\n${renderItems()}\n</ul>`;
+        }
+        const safeBefore = processedBefore.replace(/\*/g, '&#42; ');
+        const safeAfter = processedAfter.replace(/\*/g, '&#42; ');
+        return links
+            .map(l => `${safeBefore}${buildAnchor(l)}${safeAfter}`)
+            .join('\n')
+            .replace(/\n/g, '<br>');
+    }
+    // Default: <ul><li> list
+    return `<ul${listAttr}>\n${renderItems()}\n</ul>`;
+}
+/**
+ * Format a count with locale-appropriate thousands separators (e.g. 32,227).
+ */
+export function formatAsCount(n) {
+    return n.toLocaleString('en-US');
+}
+// ---------------------------------------------------------------------------
+// Current-user token resolution
+// ---------------------------------------------------------------------------
+/** Usernames that represent an unauthenticated visitor */
+const ANONYMOUS_NAMES = new Set(['anonymous', '']);
+/**
+ * Resolve a plugin parameter that may contain the special token `$currentUser`
+ * (case-insensitive) to the authenticated user's username.
+ *
+ * Rules:
+ * - Non-token values are returned unchanged.
+ * - `$currentUser` resolves to the username from `context.userContext.username`
+ *   or `context.userName`, whichever is set first.
+ * - Returns `undefined` when the token was used but the visitor is anonymous
+ *   (username is "anonymous" or absent).  The caller can use this
+ *   to detect the "token present but not logged in" case and show a prompt.
+ *
+ * @example
+ * // In a plugin execute():
+ * const author = resolveUserParam(params.author, context);
+ * if (params.author?.toLowerCase() === '$currentuser' && !author) {
+ *   return '<p>Please log in.</p>';
+ * }
+ */
+export function resolveUserParam(value, context) {
+    if (!value)
+        return value;
+    if (String(value).toLowerCase() !== '$currentuser')
+        return value;
+    const username = (context.userContext?.username)
+        || (context.userName)
+        || '';
+    return ANONYMOUS_NAMES.has(username.toLowerCase()) ? undefined : username;
+}
+// ---------------------------------------------------------------------------
+// 'current' keyword resolution (page-scoped plugins)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a keyword parameter that may be the special token `current`
+ * (case-insensitive) to the page's own keyword.
+ *
+ * EXIF/media and page keywords follow no single name-vs-slug convention across
+ * a library — some content is tagged with the page NAME (`Dining`, `Travel`),
+ * some with the SLUG (`2026-trip-west`). `current` therefore adapts: it tries
+ * both the page name and its slug and keeps whichever yields more results
+ * (tie / both-empty → name form). This gives page-scoped plugins one
+ * self-scoping syntax that works regardless of how content was tagged:
+ *   [{MediaPlugin keyword='current'}]   [{Search user-keywords='current'}]
+ *
+ * Non-`current` values are looked up as-is (single lookup).
+ *
+ * @param value    Raw keyword param — `current` (any case) triggers resolution.
+ * @param pageName Current page name (from plugin context).
+ * @param slugify  Name→slug; pass `ValidationManager.generateSlug` for the
+ *                 canonical algorithm, or a simple slugifier as fallback.
+ * @param lookup   Fetch results for a keyword (e.g. `listByKeyword`, or an
+ *                 `advancedSearch`-by-keyword closure).
+ * @returns The chosen keyword string and its results (results reusable by the
+ *          caller so `current` costs at most two lookups, not three).
+ */
+export async function resolveCurrentKeyword(value, pageName, slugify, lookup) {
+    if (value.toLowerCase() !== 'current') {
+        return { keyword: value, results: value ? await lookup(value) : [] };
+    }
+    const name = pageName ?? '';
+    const slug = name ? slugify(name) : '';
+    const [byName, bySlug] = await Promise.all([
+        name ? lookup(name) : Promise.resolve([]),
+        slug && slug !== name ? lookup(slug) : Promise.resolve([])
+    ]);
+    return bySlug.length > byName.length
+        ? { keyword: slug, results: bySlug }
+        : { keyword: name, results: byName };
+}
+/**
+ * Simple ASCII slugify fallback for callers without ValidationManager access.
+ * Matches `generateSlug` for the common ASCII case (spaces/punct → single
+ * hyphens, lowercased). Non-ASCII transliteration is NOT applied — pass
+ * `ValidationManager.generateSlug` when that matters.
+ */
+export function simpleSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/**
+ * Parse a `sort=` plugin parameter.
+ * Accepts "name", "name-asc", "name-desc", "count-asc", "count-desc", etc.
+ * validKeys is the list of allowed key names.
+ * Falls back to defaultKey/defaultOrder for any unrecognised value.
+ */
+export function parseSortParam(value, validKeys, defaultKey, defaultOrder = 'asc') {
+    if (!value)
+        return { key: defaultKey, order: defaultOrder };
+    const v = String(value).toLowerCase().trim();
+    for (const key of validKeys) {
+        if (v === key)
+            return { key, order: defaultOrder };
+        if (v === `${key}-asc`)
+            return { key, order: 'asc' };
+        if (v === `${key}-desc`)
+            return { key, order: 'desc' };
+    }
+    return { key: defaultKey, order: defaultOrder };
+}
+/**
+ * Format rows of data as an HTML table.
+ * Cell values may contain raw HTML (e.g. anchor tags).
+ * Header values are plain text and will be HTML-escaped.
+ *
+ * @param headers - Column header strings (plain text)
+ * @param rows    - Array of row arrays; each element is a cell value (may be raw HTML)
+ * @param options - Optional table rendering options (sortable, pagination hints, etc.)
+ */
+export function formatAsTable(headers, rows, options) {
+    const opts = options ?? {};
+    if (rows.length === 0) {
+        return `<p><em>${escapeHtml(opts.emptyMessage ?? 'No pages found.')}</em></p>`;
+    }
+    const classes = ['plugin-table'];
+    if (opts.sortable)
+        classes.push('sortable');
+    let tableAttrs = `class="${classes.join(' ')}"`;
+    if (opts.sortable && opts.defaultSortColumn !== undefined) {
+        tableAttrs += ` data-sort-column="${opts.defaultSortColumn}" data-sort-direction="${opts.defaultSortOrder ?? 'asc'}"`;
+    }
+    const headerHtml = headers.map(h => `<th>${escapeHtml(h)}</th>`).join('');
+    const rowsHtml = rows.map((row, rowIndex) => `<tr>${row.map((cell, colIdx) => {
+        if (opts.cellDataSort?.[colIdx]) {
+            const sortVal = opts.cellDataSort[colIdx](row, rowIndex);
+            return `<td data-sort="${escapeHtml(sortVal)}">${cell}</td>`;
+        }
+        return `<td>${cell}</td>`;
+    }).join('')}</tr>`).join('\n');
+    return [
+        `<table ${tableAttrs}>`,
+        `<thead><tr>${headerHtml}</tr></thead>`,
+        '<tbody>',
+        rowsHtml,
+        '</tbody>',
+        ...(opts.footer ? [`<tfoot><tr>${opts.footer.map(cell => `<td>${cell}</td>`).join('')}</tr></tfoot>`] : []),
+        '</table>'
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Money
+// ---------------------------------------------------------------------------
+/**
+ * Show an amount kept as whole minor units (cents) in its currency:
+ * `formatMoney(125050, 'USD')` is `$1,250.50`. The number of decimals is the
+ * currency's own (JPY 0, KWD 3); an unlisted code gets two. A malformed code
+ * never throws: it is shown after the number. Plain text: escape it when
+ * putting it in HTML.
+ */
+export function formatMoney(minorUnits, currency, locale = 'en-US') {
+    try {
+        const format = new Intl.NumberFormat(locale, { style: 'currency', currency });
+        const digits = format.resolvedOptions().maximumFractionDigits ?? 2;
+        return format.format(minorUnits / 10 ** digits);
+    }
+    catch {
+        const number = new Intl.NumberFormat(locale, { minimumFractionDigits: 2, maximumFractionDigits: 2 }).format(minorUnits / 100);
+        return `${number} ${currency}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Duration and date formatting
+// ---------------------------------------------------------------------------
+/**
+ * Format a duration in seconds as a human-readable string.
+ * Examples: "3d 12h 45m", "5h 30m", "15m"
+ */
+export function formatDuration(seconds) {
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    if (days > 0)
+        return `${days}d ${hours}h ${minutes}m`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    return `${minutes}m`;
+}
+/**
+ * Format a Date as a locale-aware date/time string.
+ * Example: "Apr 19, 2026, 10:30 AM"
+ */
+export function formatDateTime(date, locale = 'en-US') {
+    const options = {
+        year: 'numeric', month: 'short', day: 'numeric',
+        hour: 'numeric', minute: '2-digit', hour12: true
+    };
+    return date.toLocaleString(locale, options);
+}
+/**
+ * Format a Date as a relative time string.
+ * Examples: "just now", "2 hours ago", "3 days ago", "Apr 5, 2026"
+ */
+export function formatRelativeTime(date, locale = 'en-US') {
+    const diffMs = Date.now() - date.getTime();
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (diffSeconds < 60)
+        return 'just now';
+    if (diffMinutes < 60)
+        return `${diffMinutes} minute${diffMinutes !== 1 ? 's' : ''} ago`;
+    if (diffHours < 24)
+        return `${diffHours} hour${diffHours !== 1 ? 's' : ''} ago`;
+    if (diffDays < 7)
+        return `${diffDays} day${diffDays !== 1 ? 's' : ''} ago`;
+    return date.toLocaleDateString(locale, { month: 'short', day: 'numeric', year: 'numeric' });
+}
+// ---------------------------------------------------------------------------
+// Plugin parameter helpers
+// ---------------------------------------------------------------------------
+/**
+ * Split a comma-separated plugin parameter into a trimmed, non-empty array.
+ * Example: splitParam('a, b, c') → ['a', 'b', 'c']
+ */
+export function splitParam(value) {
+    if (!value)
+        return [];
+    return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+/**
+ * Parse a boolean plugin parameter.
+ * '0' and 'false' (case-insensitive) → false; '1' and 'true' → true; else → defaultVal.
+ */
+export function parseBoolParam(value, defaultVal) {
+    if (value === undefined || value === null || value === '')
+        return defaultVal;
+    const s = String(value).toLowerCase().trim();
+    if (s === 'false' || s === '0')
+        return false;
+    if (s === 'true' || s === '1')
+        return true;
+    return defaultVal;
+}
+const VALID_PLACEMENTS = new Set(['right', 'left', 'block', 'inline']);
+/**
+ * Parse a `placement=` plugin parameter to a validated `Placement` value.
+ * Falls back to `defaultPlacement` for missing or unrecognised values.
+ */
+export function parsePlacementParam(value, defaultPlacement = 'right') {
+    if (value === undefined || value === null || value === '')
+        return defaultPlacement;
+    const v = String(value).toLowerCase().trim();
+    return VALID_PLACEMENTS.has(v) ? v : defaultPlacement;
+}
+/**
+ * Return the CSS class name for a given placement value.
+ * Always returns `plugin-placement-<placement>`.
+ */
+export function placementClass(placement) {
+    return `plugin-placement-${placement}`;
+}
+// ---------------------------------------------------------------------------
+// Text / content helpers
+// ---------------------------------------------------------------------------
+/**
+ * Strip frontmatter, plugin syntax, and markdown decoration from raw page
+ * content and return plain text suitable for a card excerpt, truncated at
+ * the last word boundary before maxLen characters.
+ */
+export function extractExcerpt(raw, maxLen) {
+    const text = raw
+        .replace(/^---[\s\S]*?---\n?/, '') // YAML frontmatter
+        .replace(/\[\{[^\]]*\}\]/g, '') // [{Plugin}] syntax
+        .replace(/!\[.*?\]\(.*?\)/g, '') // markdown images
+        .replace(/^#{1,6}\s+/gm, '') // markdown headings
+        .replace(/\*{1,3}([^*]+)\*{1,3}/g, '$1') // bold / italic
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // markdown links → label
+        .replace(/\[([^\]]+)\]/g, '$1') // wiki links → label
+        .replace(/`{1,3}[^`]*`{1,3}/g, '') // code spans / fences
+        .replace(/^\s*[-*+]\s+/gm, '') // list bullets
+        .replace(/\n{2,}/g, ' ') // paragraph breaks → space
+        .replace(/\n/g, ' ')
+        .trim();
+    if (text.length <= maxLen)
+        return text;
+    const cut = text.lastIndexOf(' ', maxLen);
+    return (cut > 0 ? text.slice(0, cut) : text.slice(0, maxLen)) + '…';
+}
+/**
+ * Fisher-Yates in-place shuffle. Returns the same array reference.
+ */
+export function shuffleArray(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+// ---------------------------------------------------------------------------
+// Pagination utilities
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `page=` plugin parameter to an integer (1-based).
+ * Returns `defaultPage` if the value is missing, empty, or non-numeric.
+ */
+export function parsePageParam(value, defaultPage = 1) {
+    if (value === undefined || value === null || value === '')
+        return defaultPage;
+    const n = parseInt(String(value), 10);
+    return isNaN(n) || n < 1 ? defaultPage : n;
+}
+/**
+ * Parse a `pageSize=` plugin parameter to an integer.
+ * Returns `defaultSize` (0 = disabled / use max= behaviour) for missing/invalid values.
+ */
+export function parsePageSizeParam(value, defaultSize = 0) {
+    if (value === undefined || value === null || value === '')
+        return defaultSize;
+    const n = parseInt(String(value), 10);
+    return isNaN(n) || n < 0 ? defaultSize : n;
+}
+/**
+ * Slice `items` to the requested page.
+ * When `pageSize` is 0 (disabled), returns all items as page 1 of 1.
+ */
+export function applyPagination(items, page, pageSize) {
+    if (pageSize <= 0) {
+        return { items, totalPages: 1, currentPage: 1, totalItems: items.length };
+    }
+    const totalItems = items.length;
+    const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+    const currentPage = Math.min(Math.max(1, page), totalPages);
+    const start = (currentPage - 1) * pageSize;
+    return {
+        items: items.slice(start, start + pageSize),
+        totalPages,
+        currentPage,
+        totalItems
+    };
+}
+/**
+ * How many numbered pages the sliding window shows at once.
+ *
+ * Mirrors `WikiPagination.renderNav` in public/js/wiki-pagination.js on
+ * purpose: the two layers must produce the same control, so the window they
+ * slide has to be the same width. Changing one without the other is how the
+ * application ended up with pagination that looked different depending on
+ * whether the page was rendered on the server or in the browser (#1299).
+ */
+const PAGINATION_WINDOW = 7;
+/** Prev/next glyphs, matching the client-side control's Font Awesome chevrons. */
+const PAGINATION_CHEVRON_LEFT = '<i class="fas fa-chevron-left"></i>';
+const PAGINATION_CHEVRON_RIGHT = '<i class="fas fa-chevron-right"></i>';
+/** One `<li>` of the pagination list. */
+function paginationItem(html, href, ariaLabel, active = false) {
+    const label = ariaLabel ? ` aria-label="${ariaLabel}"` : '';
+    if (active) {
+        // aria-current is how a screen reader learns which page it is on. The old
+        // plugin control said "Page 2 of 5" in visible text; a numbered pager makes
+        // that redundant for sighted users but silent for everyone else without it.
+        return `<li class="page-item active"><span class="page-link" aria-current="page"${label}>${html}</span></li>`;
+    }
+    if (href === null) {
+        return `<li class="page-item disabled"><span class="page-link"${label}>${html}</span></li>`;
+    }
+    return `<li class="page-item"><a class="page-link" href="${escapeHtml(href)}"${label}>${html}</a></li>`;
+}
+/**
+ * Render the canonical pagination control (#1300).
+ *
+ * This is the one pagination markup in the application. `WikiPagination`
+ * produces the same shape in the browser and enhances any instance it finds —
+ * clicks, arrow keys and swipe — so a surface gets the full control by emitting
+ * this and nothing else.
+ *
+ * The wrapper carries `data-current-page`, `data-total-pages` and the prev/next
+ * URLs, which is what lets the enhancer work without being told anything by the
+ * page. Everything it needs is in the markup.
+ *
+ * Returns '' for a single page: a control that can only ever show "1" is noise.
+ *
+ * @param currentPage - The current page number (1-based)
+ * @param totalPages  - Total number of pages
+ * @param hrefFor     - Builds the URL for a given 1-based page number
+ * @param ariaLabel   - Accessible name for the nav landmark
+ * @example
+ * formatPaginationNav(3, 12, (p) => `/view/Index?page=${p}`)
+ */
+export function formatPaginationNav(currentPage, totalPages, hrefFor, ariaLabel = 'Pagination') {
+    if (totalPages <= 1)
+        return '';
+    const current = Math.min(Math.max(1, Math.floor(currentPage) || 1), totalPages);
+    const items = [];
+    items.push(current > 1
+        ? paginationItem(PAGINATION_CHEVRON_LEFT, hrefFor(current - 1), 'Previous')
+        : paginationItem(PAGINATION_CHEVRON_LEFT, null, 'Previous'));
+    const half = Math.floor(PAGINATION_WINDOW / 2);
+    let startPage = Math.max(1, current - half);
+    const endPage = Math.min(totalPages, startPage + PAGINATION_WINDOW - 1);
+    if (endPage - startPage < PAGINATION_WINDOW - 1) {
+        startPage = Math.max(1, endPage - PAGINATION_WINDOW + 1);
+    }
+    if (startPage > 1) {
+        items.push(paginationItem('1', hrefFor(1)));
+        // An ellipsis standing in for a single page hides nothing and costs a
+        // click to discover that, so only draw one when it covers a gap.
+        if (startPage > 2)
+            items.push(paginationItem('&hellip;', null));
+    }
+    for (let page = startPage; page <= endPage; page++) {
+        items.push(paginationItem(String(page), hrefFor(page), undefined, page === current));
+    }
+    if (endPage < totalPages) {
+        if (endPage < totalPages - 1)
+            items.push(paginationItem('&hellip;', null));
+        items.push(paginationItem(String(totalPages), hrefFor(totalPages)));
+    }
+    items.push(current < totalPages
+        ? paginationItem(PAGINATION_CHEVRON_RIGHT, hrefFor(current + 1), 'Next')
+        : paginationItem(PAGINATION_CHEVRON_RIGHT, null, 'Next'));
+    const prevAttr = current > 1 ? ` data-prev-url="${escapeHtml(hrefFor(current - 1))}"` : '';
+    const nextAttr = current < totalPages ? ` data-next-url="${escapeHtml(hrefFor(current + 1))}"` : '';
+    return `<nav class="wiki-pagination" aria-label="${escapeHtml(ariaLabel)}" data-pagination `
+        + `data-current-page="${current}" data-total-pages="${totalPages}"${prevAttr}${nextAttr}>`
+        + `<ul class="pagination pagination-sm mb-0">${items.join('')}</ul>`
+        + '</nav>';
+}
+// ---------------------------------------------------------------------------
+// Summary-stat filter bar (#1303)
+// ---------------------------------------------------------------------------
+/** Bootstrap card tones the bar will emit. Anything else falls back to neutral. */
+const STAT_TONES = ['primary', 'success', 'info', 'warning', 'danger', 'secondary'];
+/** Card colour classes, kept in one place so a tone means one thing everywhere. */
+function statToneClass(tone) {
+    if (!tone || !STAT_TONES.includes(tone))
+        return 'bg-light';
+    return tone === 'warning' || tone === 'info' ? `bg-${tone} text-dark` : `bg-${tone} text-white`;
+}
+/**
+ * Render the canonical summary-stat filter bar (#1303).
+ *
+ * `/admin/users` had four cards that filter its table when clicked. Nine other
+ * surfaces render summary counts in five presentations and none of them filter
+ * — `admin-keywords` pixel-identical to the one that works, `admin-audit`
+ * defining a `:hover` rule on cards with no click handler. An inconsistent
+ * appearance is untidy; an inconsistent affordance is a lie.
+ *
+ * The markup is the contract, as it is for `formatPaginationNav`: a card is
+ * clickable because of what it carries, and `WikiStatFilters.enhance()` wires
+ * any bar it finds. That is what lets a plugin an admin wrote offer the same
+ * interaction as a core admin page.
+ *
+ * Three kinds of card, and the difference is the whole design:
+ *
+ * - `href` — a link. The server filters, so it is correct on a paginated list.
+ * - `match` — a client-side row filter. Correct only when every row is loaded.
+ * - `clears` — the card that puts everything back.
+ * - none of them — a card that reports a number and does not pretend to filter.
+ *
+ * Returns '' for an empty list.
+ *
+ * @param stats   - The cards, in display order
+ * @param options - Row selector, aria label, column class
+ * @example
+ * formatStatFilters(
+ *   [{ label: 'Active', value: 9, match: 'status=active', tone: 'success' }],
+ *   { rowSelector: 'tbody tr[data-username]' }
+ * )
+ */
+export function formatStatFilters(stats, options = {}) {
+    if (!stats.length)
+        return '';
+    const { rowSelector, ariaLabel = 'Summary filters', columnClass = 'col-md-3' } = options;
+    const cards = stats.map((stat) => {
+        const body = '<div class="card-body">'
+            + `<h5 class="card-title">${escapeHtml(stat.label)}</h5>`
+            + `<h3 class="mb-0">${escapeHtml(String(stat.value))}</h3>`
+            + '</div>';
+        const classes = `card stat-filter ${statToneClass(stat.tone)}`;
+        const titleAttr = stat.title ? ` title="${escapeHtml(stat.title)}"` : '';
+        const activeAttr = stat.active ? ' data-stat-active' : '';
+        let card;
+        if (stat.href) {
+            card = `<a class="${classes} text-decoration-none"${titleAttr}${activeAttr}`
+                + ` href="${escapeHtml(stat.href)}">${body}</a>`;
+        }
+        else if (stat.match || stat.clears) {
+            // A div rather than a button: the card is a block of markup, and a
+            // button element restyled to look like one loses more than role and
+            // tabindex give back here.
+            const behaviour = stat.match
+                ? ` data-stat-match="${escapeHtml(stat.match)}"`
+                : ' data-stat-clear';
+            card = `<div class="${classes}" role="button" tabindex="0"${titleAttr}${activeAttr}`
+                + `${behaviour}>${body}</div>`;
+        }
+        else {
+            card = `<div class="${classes}"${titleAttr}>${body}</div>`;
+        }
+        return `<div class="${escapeHtml(columnClass)}">${card}</div>`;
+    });
+    const rowsAttr = rowSelector ? ` data-stat-rows="${escapeHtml(rowSelector)}"` : '';
+    return `<div class="row mb-4 wiki-stat-filters" role="group" aria-label="${escapeHtml(ariaLabel)}"`
+        + ` data-stat-filters${rowsAttr}>${cards.join('')}</div>`;
+}
+/**
+ * Build pagination HTML for a plugin result set, addressed by page name.
+ *
+ * A thin wrapper over `formatPaginationNav` (#1301): it turns a page name and a
+ * query parameter into the `/view/{page}?{param}=N` URLs this application uses,
+ * and leaves the markup to the canonical control.
+ *
+ * It previously emitted its own `.plugin-pagination` div — prev/next text links
+ * with no page numbers and no styling, since that class had no CSS anywhere in
+ * the repo. Its signature and its single-page behaviour are unchanged, so the
+ * plugins calling it did not have to change; what they render did.
+ *
+ * Returns '' when there is only one page (nothing to navigate).
+ *
+ * @param currentPage - The current page number (1-based)
+ * @param totalPages  - Total number of pages
+ * @param pageName    - Wiki page name used to build `/view/{pageName}?page=N`
+ * @param queryParam  - Query string parameter name (default: 'page')
+ */
+export function formatPaginationLinks(currentPage, totalPages, pageName, queryParam = 'page') {
+    const base = `/view/${encodeURIComponent(pageName)}`;
+    return formatPaginationNav(currentPage, totalPages, (page) => `${base}?${queryParam}=${page}`);
+}
+/** The one manager method page text may reach (#1556). */
+export const FETCHABLE_METHOD = 'toMarqueeText';
+/**
+ * Resolve the `fetch='ManagerName.toMarqueeText(k=v,...)'` plugin convention to text.
+ *
+ * Extracted from MarqueePlugin (#685 slice 2). Page text names the manager and
+ * the method, so this is reachable by anyone who can edit a page and runs on
+ * every render, for every viewer (#1556). Two rules make that safe:
+ *
+ * - __Only `toMarqueeText`.__ Any other method — an index rebuild, a scan,
+ *   anything with a side effect — is refused, whatever the manager offers.
+ *   `BaseManager.toMarqueeText()` is the convention, and the only method any
+ *   shipped page or doc uses.
+ * - __The viewer's context goes with it__ (every call carries a context). The
+ *   manager decides what that viewer may see; nothing runs as the server.
+ *
+ * The raw `{k: v}` args object is passed as the first argument (the manager
+ * owns its own option parsing via `managerUtils.ts`), the viewer second.
+ *
+ * #1751: the render depends on the manager's data, so the page cache
+ * re-renders once that manager bumps its topic (its own name).
+ */
+export async function resolveManagerFetch(spec, context) {
+    const call = await callManagerMethod(spec, context, FETCHABLE_METHOD);
+    if (call.status !== 'ok')
+        return call;
+    return { status: 'ok', text: String(call.value) };
+}
+/** The one manager method a form's `optionsSource: "fetch:..."` may reach. */
+export const FORM_OPTIONS_METHOD = 'toFormOptions';
+/**
+ * Resolve `ManagerName.toFormOptions(k=v,...)` to the choices of a form
+ * dropdown, under the same two rules as resolveManagerFetch: only
+ * `toFormOptions` is reachable, and the viewer's context goes with the call,
+ * so the manager offers that viewer only what they may see.
+ *
+ * The manager may answer strings or `{ value, label }` objects; anything
+ * else is dropped, and every value comes back as a string.
+ */
+export async function resolveManagerOptions(spec, context) {
+    const call = await callManagerMethod(spec, context, FORM_OPTIONS_METHOD);
+    if (call.status !== 'ok')
+        return call;
+    return { status: 'ok', options: toFormOptionList(call.value) };
+}
+function toFormOptionList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const options = [];
+    for (const item of value) {
+        if (typeof item === 'string') {
+            options.push({ value: item, label: item });
+        }
+        else if (item && typeof item === 'object') {
+            const { value: v, label } = item;
+            if ((typeof v === 'string' || typeof v === 'number') && String(v) !== '') {
+                options.push({ value: String(v), label: typeof label === 'string' && label !== '' ? label : String(v) });
+            }
+        }
+    }
+    return options;
+}
+/**
+ * Parse `Manager.method(k=v,...)` and call it with the args and the viewer,
+ * but only when `method` is the one `allowed` method (#1556).
+ */
+async function callManagerMethod(spec, context, allowed) {
+    if (!spec || !context.engine)
+        return { status: 'no-spec' };
+    const match = String(spec).trim().match(/^([A-Za-z0-9_]+)\.([A-Za-z0-9_]+)\(([^)]*)\)$/);
+    if (!match)
+        return { status: 'no-spec' };
+    const [, managerName, methodName, argsStr] = match;
+    if (methodName !== allowed)
+        return { status: 'refused' };
+    const fetchArgs = {};
+    if (argsStr) {
+        for (const pair of argsStr.split(',')) {
+            const eq = pair.indexOf('=');
+            if (eq > 0)
+                fetchArgs[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+        }
+    }
+    const manager = context.engine.getManager(managerName);
+    const method = manager?.[allowed];
+    if (typeof method !== 'function')
+        return { status: 'not-found' };
+    const value = await method.call(manager, fetchArgs, context.userContext);
+    return { status: 'ok', value };
+}