@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/utils/pluginFormatters.d.ts

@@ -0,0 +1,452 @@
+/**
+ * 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`.
+ */
+/** A renderable page link with href, display text, and optional styling */
+export interface PageLink {
+    href: string;
+    text: string;
+    cssClass?: string;
+    style?: string;
+    title?: string;
+    /**
+     * Font Awesome (or any) class for an icon rendered before the text (#1306).
+     * A class name, not markup — escaped into the attribute.
+     */
+    icon?: string;
+    /**
+     * A value shown at the end of the row — a count, a status (#1306). Escaped:
+     * it is data, not markup.
+     */
+    badge?: string;
+    /**
+     * Markup appended after the link — a per-item action button, typically.
+     * Inserted verbatim, so the CALLER owns escaping anything interpolated into
+     * it. This exists because MyLinksPlugin hand-rolled its whole list for one
+     * remove button, which is the vocabulary being too small rather than the
+     * plugin being wrong.
+     */
+    trailingHtml?: string;
+}
+/** Options for list/item formatting */
+export interface FormatOptions {
+    before?: string;
+    after?: string;
+    /** Classes for the `<ul>` — a plugin keeping its Bootstrap layout (#1306). */
+    listClass?: string;
+    /** Classes for each `<li>`. */
+    itemClass?: string;
+}
+/**
+ * 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 declare function parseMaxParam(value: string | number | undefined, defaultMax?: number): number;
+/**
+ * Apply a max limit to an array.
+ * max=0 means unlimited (returns all items unchanged).
+ */
+export declare function applyMax<T>(items: T[], max: number): T[];
+/**
+ * Escape HTML special characters.
+ * Accepts any primitive value; null/undefined return an empty string.
+ */
+export declare function escapeHtml(text: string | number | boolean | null | undefined): string;
+/**
+ * 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 declare function formatAsList(links: PageLink[], options?: FormatOptions): string;
+/**
+ * Format a count with locale-appropriate thousands separators (e.g. 32,227).
+ */
+export declare function formatAsCount(n: number): string;
+/**
+ * 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 declare function resolveUserParam(value: string | undefined, context: {
+    userName?: string;
+    userContext?: {
+        username?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}): string | undefined;
+/**
+ * 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 declare function resolveCurrentKeyword<T>(value: string, pageName: string, slugify: (name: string) => string, lookup: (keyword: string) => Promise<T[]>): Promise<{
+    keyword: string;
+    results: T[];
+}>;
+/**
+ * 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 declare function simpleSlug(name: string): string;
+export type SortOrder = 'asc' | 'desc';
+export interface SortOptions {
+    key: string;
+    order: SortOrder;
+}
+/**
+ * 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 declare function parseSortParam(value: string | undefined, validKeys: string[], defaultKey: string, defaultOrder?: SortOrder): SortOptions;
+export interface TableOptions {
+    /** When true, adds the "sortable" CSS class so tableSort.js activates */
+    sortable?: boolean;
+    /** 0-indexed column that is the initial sort column */
+    defaultSortColumn?: number;
+    /** Initial sort direction (default: 'asc') */
+    defaultSortOrder?: SortOrder;
+    /**
+     * Per-column callbacks that return a `data-sort` attribute value for a cell.
+     * Keyed by column index.  Needed when a cell contains HTML (e.g. links) but
+     * tableSort.js should sort on the underlying numeric/text value.
+     * Receives the cell's row data AND the 0-based row index within `rows`.
+     */
+    cellDataSort?: Record<number, (row: string[], rowIndex: number) => string>;
+    /** Shown instead of the table when there are no rows (plain text). Default: "No pages found." */
+    emptyMessage?: string;
+    /** A totals row in `<tfoot>`; cells may contain raw HTML, like body cells. */
+    footer?: string[];
+}
+/**
+ * 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 declare function formatAsTable(headers: string[], rows: string[][], options?: TableOptions): string;
+/**
+ * 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 declare function formatMoney(minorUnits: number, currency: string, locale?: string): string;
+/**
+ * Format a duration in seconds as a human-readable string.
+ * Examples: "3d 12h 45m", "5h 30m", "15m"
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Format a Date as a locale-aware date/time string.
+ * Example: "Apr 19, 2026, 10:30 AM"
+ */
+export declare function formatDateTime(date: Date, locale?: string): string;
+/**
+ * Format a Date as a relative time string.
+ * Examples: "just now", "2 hours ago", "3 days ago", "Apr 5, 2026"
+ */
+export declare function formatRelativeTime(date: Date, locale?: string): string;
+/**
+ * Split a comma-separated plugin parameter into a trimmed, non-empty array.
+ * Example: splitParam('a, b, c') → ['a', 'b', 'c']
+ */
+export declare function splitParam(value: string | number | boolean | undefined): string[];
+/**
+ * Parse a boolean plugin parameter.
+ * '0' and 'false' (case-insensitive) → false; '1' and 'true' → true; else → defaultVal.
+ */
+export declare function parseBoolParam(value: string | number | boolean | undefined, defaultVal: boolean): boolean;
+/**
+ * Where a plugin's rendered output should sit in the page flow.
+ *
+ *   - 'right'  — float right; surrounding text wraps on the left (Wikipedia infobox).
+ *   - 'left'   — float left; surrounding text wraps on the right.
+ *   - 'block'  — full-width block element below the caption text. No float.
+ *   - 'inline' — inline-block; sits next to other inline content.
+ *
+ * Plugins combine `placementClass(placement)` with their own classes, e.g.
+ * `<div class="volcano-infobox plugin-placement-right">…</div>`. The
+ * `.plugin-placement-*` CSS lives in ngdpbase core.css so every plugin gets a
+ * consistent contract whether or not its addon stylesheet has loaded.
+ */
+export type Placement = 'right' | 'left' | 'block' | 'inline';
+/**
+ * Parse a `placement=` plugin parameter to a validated `Placement` value.
+ * Falls back to `defaultPlacement` for missing or unrecognised values.
+ */
+export declare function parsePlacementParam(value: string | undefined, defaultPlacement?: Placement): Placement;
+/**
+ * Return the CSS class name for a given placement value.
+ * Always returns `plugin-placement-<placement>`.
+ */
+export declare function placementClass(placement: Placement): string;
+/**
+ * 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 declare function extractExcerpt(raw: string, maxLen: number): string;
+/**
+ * Fisher-Yates in-place shuffle. Returns the same array reference.
+ */
+export declare function shuffleArray<T>(arr: T[]): T[];
+/**
+ * Parse a `page=` plugin parameter to an integer (1-based).
+ * Returns `defaultPage` if the value is missing, empty, or non-numeric.
+ */
+export declare function parsePageParam(value: string | number | undefined, defaultPage?: number): number;
+/**
+ * Parse a `pageSize=` plugin parameter to an integer.
+ * Returns `defaultSize` (0 = disabled / use max= behaviour) for missing/invalid values.
+ */
+export declare function parsePageSizeParam(value: string | number | undefined, defaultSize?: number): number;
+export interface PaginationResult<T> {
+    items: T[];
+    totalPages: number;
+    /** Clamped to 1..totalPages */
+    currentPage: number;
+    totalItems: number;
+}
+/**
+ * Slice `items` to the requested page.
+ * When `pageSize` is 0 (disabled), returns all items as page 1 of 1.
+ */
+export declare function applyPagination<T>(items: T[], page: number, pageSize: number): PaginationResult<T>;
+/**
+ * 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 declare function formatPaginationNav(currentPage: number, totalPages: number, hrefFor: (page: number) => string, ariaLabel?: string): string;
+/** Bootstrap card tones the bar will emit. Anything else falls back to neutral. */
+declare const STAT_TONES: readonly ["primary", "success", "info", "warning", "danger", "secondary"];
+export type StatTone = typeof STAT_TONES[number];
+/** One card in a stat filter bar. */
+export interface StatFilter {
+    /** Card heading, e.g. "Active Users". */
+    label: string;
+    /** The count (or any short value) shown beneath it. */
+    value: string | number;
+    /**
+     * Server-side filter: the card becomes a link to this URL. Use on any
+     * surface whose list is paginated — see the note on `match`.
+     */
+    href?: string;
+    /**
+     * Client-side filter: `attr=value`, matched against a row's `data-<attr>`.
+     * Only correct when every row is already on the page. On a paginated list it
+     * would filter the current page while implying it filtered the set, which is
+     * the defect #1237 documents in the audit log's DataTables search box — use
+     * `href` there instead.
+     */
+    match?: string;
+    /**
+     * The card that clears the filter — "Total", and whatever a surface calls
+     * its everything card. Clickable, but selects nothing.
+     */
+    clears?: boolean;
+    /** Marks the card whose filter is currently in effect (server-side bars). */
+    active?: boolean;
+    /** Card colour. */
+    tone?: StatTone;
+    /** Tooltip / accessible description. */
+    title?: string;
+}
+export interface StatFilterOptions {
+    /** CSS selector for the rows a client-side filter hides. */
+    rowSelector?: string;
+    /** Accessible name for the group. */
+    ariaLabel?: string;
+    /** Bootstrap column class per card (default: four across). */
+    columnClass?: string;
+}
+/**
+ * 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 declare function formatStatFilters(stats: StatFilter[], options?: StatFilterOptions): string;
+/**
+ * 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 declare function formatPaginationLinks(currentPage: number, totalPages: number, pageName: string, queryParam?: string): string;
+/** Outcome of resolveManagerFetch — lets callers reproduce their own messaging. */
+export type ManagerFetchResult = {
+    status: 'ok';
+    text: string;
+} | {
+    status: 'not-found';
+} | {
+    status: 'refused';
+} | {
+    status: 'no-spec';
+};
+/** The one manager method page text may reach (#1556). */
+export declare 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 declare function resolveManagerFetch(spec: string | undefined, context: {
+    engine?: {
+        getManager(name: string): unknown;
+    };
+    userContext?: unknown;
+}): Promise<ManagerFetchResult>;
+/** One choice in a form's dropdown: the value submitted, and the text shown. */
+export interface FormOption {
+    value: string;
+    label: string;
+}
+/** Outcome of resolveManagerOptions; the statuses mean what they mean for resolveManagerFetch. */
+export type ManagerOptionsResult = {
+    status: 'ok';
+    options: FormOption[];
+} | {
+    status: 'not-found';
+} | {
+    status: 'refused';
+} | {
+    status: 'no-spec';
+};
+/** The one manager method a form's `optionsSource: "fetch:..."` may reach. */
+export declare 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 declare function resolveManagerOptions(spec: string | undefined, context: {
+    engine?: {
+        getManager(name: string): unknown;
+    };
+    userContext?: unknown;
+}): Promise<ManagerOptionsResult>;
+export {};