@heroiclands/package-build 23.12.3 → 23.12.5

package/types/engine/event-views.d.mts

@@ -34,18 +34,22 @@ export function eventViewSections(db: object, records: Iterable<object>, fileOf:
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null,
- *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
+ *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean}) => {fence: string, own?: string}|null,
+ *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>,
+ *   felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
 export const EVENT_VIEWS: ReadonlyArray<Readonly<{
     slug: string;
     heading: string;
     applies: (record: object) => boolean;
-    query: (self: string[], shape: CorpusShape) => {
+    query: (self: string[], shape: CorpusShape, columns?: {
+        felt?: boolean;
+    }) => {
         fence: string;
         own?: string;
     } | null;
     owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>;
+    felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>;
 }>>;
 export type CorpusShape = {
     /**

package/types/engine/generated-sections.d.mts

@@ -110,6 +110,12 @@ export function splitGenerated(markdown: string): {
  *
  * @module
  */
+/**
+ * The anchor of the Chronology section, which the book sets across the page.
+ *
+ * @type {string}
+ */
+export const CHRONOLOGY_SLUG: string;
 /**
  * Every generated section, in the order it follows the author's text: where a
  * place sits and who governs it, then what happened, then what was written

package/types/engine/holdings.d.mts

@@ -1,10 +1,11 @@
-/** @typedef {{title:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
+/** @typedef {{title:string,sort?:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
 /**
  * @typedef {object} HoldingsNode
  * @property {string} shortcode
  * @property {"place"|"affiliation"} type
  * @property {string} [subType]
  * @property {string} title
+ * @property {string} [sort] The note's `name.sort`; the list files by it in place of `title`.
  * @property {string} [url]
  * @property {string} [package] Owning content package.
  * @property {string} [system] Own document system.
@@ -60,6 +61,7 @@ export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { government
 export function checkGovernment(note: object): object[];
 export type HoldingsEntry = {
     title: string;
+    sort?: string;
     url?: string;
     address: string;
     type: string;
@@ -70,6 +72,10 @@ export type HoldingsNode = {
     type: "place" | "affiliation";
     subType?: string | undefined;
     title: string;
+    /**
+     * The note's `name.sort`; the list files by it in place of `title`.
+     */
+    sort?: string | undefined;
     url?: string | undefined;
     /**
      * Owning content package.

package/types/engine/infobox.d.mts

@@ -94,6 +94,17 @@ export function hasRenderableValue(kind: string, value: unknown): boolean;
  * @returns {string} One of {@link INFOBOX_VALUE_KINDS}.
  */
 export function valueKindOf(field: object, value: unknown): string;
+/**
+ * A number as a reader reads it in a profile: under a million in full with
+ * thousands separators (`850`, `12,500`), and from a million up in words with
+ * at most one decimal (`11 million`, `1.2 million`, `3 billion`). Every figure
+ * the setting gives at that scale is an estimate, and the words say so.
+ * Decimals below a million keep the digits they were written with.
+ *
+ * @param {number} value - The number.
+ * @returns {string} The text the row shows.
+ */
+export function formatQuantity(value: number): string;
 /**
  * One row, with its unit on it.
  *

package/types/engine/literature-works.d.mts

@@ -38,6 +38,7 @@ export function worksPages(nodes: Iterable<WorksNode | null>, { types }: {
 }>;
 export type WorkEntry = {
     title: string;
+    sort?: string;
     url?: string;
     address: string;
     form?: string;
@@ -48,6 +49,10 @@ export type WorksNode = {
      */
     key: string;
     title: string;
+    /**
+     * The note's `name.sort`; the list files by it in place of `title`.
+     */
+    sort?: string | undefined;
     /**
      * Absent for a note that publishes no page.
      */

package/types/engine/name-sort.d.mts

@@ -0,0 +1,49 @@
+/**
+ * A note's display name reduced to printable 7-bit ASCII.
+ *
+ * Content names carry the setting's orthography — `Kûrbúl Helm`, `Hârn`,
+ * `Kèthîra` — and nobody types them. A reader searching the index, or an editor
+ * completing a wikilink, needs a form that matches what a keyboard produces, so
+ * the record states one rather than leaving every consumer to invent it (and to
+ * invent a *different* one, which is how two searches over the same data come
+ * to disagree).
+ *
+ * **Transliterated, not stripped.** `unidecode` — the same table
+ * {@link slugify} already runs, so an ASCII name and a slug can never disagree
+ * about a character — carries a letter across rather than deleting it:
+ * diacritics fold (`â`→`a`, `è`→`e`), ligatures expand (`æ`→`ae`, `Œ`→`OE`,
+ * `ß`→`ss`), the runic letters spell out (`þ`→`th`, `Þ`→`Th`, `ð`→`d`), and
+ * even a vulgar fraction becomes readable (`¾`→`3/4`). Deleting them instead
+ * would collapse `Kûrbúl` to `Krbl`, which is worse than the original.
+ *
+ * Anything still outside printable ASCII after that becomes a space, and runs
+ * of whitespace collapse — a space rather than nothing, so a character that
+ * transliterates away cannot silently weld two words together.
+ *
+ * The value is emitted even when it equals the name, so a consumer matching on
+ * it never has to branch on whether the name happened to be ASCII already.
+ *
+ * @param {unknown} name - The note's `name.full`.
+ * @returns {string|null} The ASCII form, or `null` when there is no name, or
+ *   nothing printable survives.
+ */
+export function asciiName(name: unknown): string | null;
+/**
+ * The name a note files under: its `name.sort` when it declares one, otherwise
+ * its `name.full`.
+ *
+ * @param {unknown} record - An index record or a note's frontmatter.
+ * @returns {string|undefined} The unfolded key, or `undefined` for a record
+ *   with no name.
+ */
+export function nameSortOf(record: unknown): string | undefined;
+/**
+ * The key a name-ordered list compares notes on: {@link nameSortOf} folded to
+ * printable ASCII by {@link asciiName}, so an accented sort key files beside
+ * its base letters. Case is left for the caller, which decides whether its
+ * comparison ignores it.
+ *
+ * @param {unknown} record - An index record or a note's frontmatter.
+ * @returns {string} The key, or "" for a record with no name.
+ */
+export function nameSortKey(record: unknown): string;

package/types/engine/pdf-index.d.mts

@@ -20,11 +20,13 @@ export function indexMarker(slug: string, main?: boolean): string;
  * @param {string[]} [opts.heads] - Leading words (`pdf.indexHeads`) matched
  *   literally against the start of a name; a name that opens with one is also
  *   listed as `<rest>, <head>`, the head without its trailing space or colon. None when absent.
- * @param {Array<{slug: string, name: string, title: string, page: string|number}>} [opts.foreign] -
+ * @param {Array<{slug: string, name: string, title: string, abbreviation?: string,
+ *   page: string|number}>} [opts.foreign] -
  *   Notes another book prints, listed as `Name: Book title, p. N` once this
- *   book mentions them.
+ *   book mentions them, or `Name: Aelw. p12` when the home book has an
+ *   abbreviation.
  * @returns {Array<{letter: string, name: string, slug: string, see?: string,
- *   foreign?: {title: string, page: string}}>} Terms with `see` set for a
+ *   foreign?: {title: string, abbreviation?: string, page: string}}>} Terms with `see` set for a
  *   cross-reference to the main name it points at.
  */
 export function indexTerms(entries: object[], { owns, foreign, heads }?: {
@@ -34,6 +36,7 @@ export function indexTerms(entries: object[], { owns, foreign, heads }?: {
         slug: string;
         name: string;
         title: string;
+        abbreviation?: string;
         page: string | number;
     }[] | undefined;
 }): Array<{
@@ -43,6 +46,7 @@ export function indexTerms(entries: object[], { owns, foreign, heads }?: {
     see?: string;
     foreign?: {
         title: string;
+        abbreviation?: string;
         page: string;
     };
 }>;

package/types/engine/pdf-pages.d.mts

@@ -57,7 +57,7 @@ export function readEntryPages(typPath: string, fontArgs: string[], binary?: str
  *   The books that render, in configuration order.
  * @param {Map<string, string>} input.homes - Each note's key → its home book's
  *   id, from {@link module:engine/pdf-coverage.coverage}.
- * @returns {Array<{key: string, book: string, title: string, anchor: string,
+ * @returns {Array<{key: string, book: string, title: string, abbreviation?: string, anchor: string,
  *   record: object, slug: string, aliases: string[]}>} One per homed note, in book order and
  *   then entry order.
  */
@@ -74,6 +74,7 @@ export function homeEntries({ books, homes }: {
     key: string;
     book: string;
     title: string;
+    abbreviation?: string;
     anchor: string;
     record: object;
     slug: string;

package/types/engine/pdf-render.d.mts

@@ -166,19 +166,30 @@ export function markdownToTypst(markdown: string, opts?: {
 export function absolutePageUrl(url: string, site?: string): string;
 /**
  * A reference to a note another book prints, as Typst: the words the link
- * carried, then the book and the page, `Name (_Book title_, p. 12)`.
+ * carried, then the book and the page. A book with an abbreviation reads
+ * `Name (Aelw. p12)`; one without reads `Name (_Book title_, p. 12)`.
  *
- * The space before the page number does not break, so a number never starts a
- * line of its own.
+ * A link the text already closes a bracket on, as in `(see Name)`, takes the
+ * reference inside that bracket after a comma, `(see Name, Aelw. p12)`, so the
+ * brackets never nest.
+ *
+ * The space before the page number, or between the abbreviation and the page,
+ * does not break, so a number never starts a line of its own.
  *
  * @param {string} inner - The already-rendered link text.
- * @param {{title: string, page: string|number}} away - The home book's title
- *   and the page the entry starts on.
+ * @param {{title: string, abbreviation?: string, page: string|number}} away -
+ *   The home book's title, its abbreviation when it declares one, and the page
+ *   the entry starts on.
+ * @param {{bracketed?: boolean}} [opts] - `bracketed` when the text closes a
+ *   bracket right after the link.
  * @returns {string} Typst markup.
  */
 export function crossBookReference(inner: string, away: {
     title: string;
+    abbreviation?: string;
     page: string | number;
+}, { bracketed }?: {
+    bracketed?: boolean;
 }): string;
 /**
  * The Typst definitions the book's page furniture is drawn with.

package/types/engine/pdf-toc.d.mts

@@ -72,7 +72,7 @@ export function runTreeFilters(nodes: object[], db: {
  * without a renderer or a PDF. Only how the result *looks* needs eyes.
  *
  * **Notes are sorted, prose is not.** A section's entries come out in
- * `nameAscii` order — the ASCII fold `buildIndexRecord` already derives, so a
+ * name-sort order (`name.sort`, else `name.full`, folded to ASCII), so a
  * circumflex sorts with its letter instead of after `Z` as a raw codepoint
  * comparison would put it. Prose keeps the position it was written in, because
  * its place in the sequence is the author's statement.

package/types/engine/related-pages.d.mts

@@ -59,6 +59,11 @@ export type RelatedEntry = {
      * The note's `type`, which the theme groups by.
      */
     type: string;
+    /**
+     * The note's `name.sort`. It orders the list in place
+     * of `title` and is not published.
+     */
+    sort?: string | undefined;
 };
 /**
  * The `related` block one page publishes.

package/ci/confirm-npm-version.mjs

@@ -1,135 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * Asserts that npm serves an exact package version.
- *
- * `npm publish` returns before the registry serves the new version, and a
- * version that is accepted but never served is indistinguishable from success
- * by the publish alone. This polls `npm view <name>@<version> version` until
- * it prints the version, then exits 0. When the time budget runs out it exits 1
- * with an `::error::` annotation naming the package, the version and the last
- * registry answer.
- *
- * Usage: `node ci/confirm-npm-version.mjs <name> <version> [--interval <s>]
- * [--timeout <s>]`. The defaults are 15 seconds between queries and 600 seconds
- * overall.
- */
-
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
-/** Seconds between registry queries. */
-export const DEFAULT_INTERVAL_SECONDS = 15;
-/** Seconds the registry has to serve the version. */
-export const DEFAULT_TIMEOUT_SECONDS = 600;
-
-/**
- * Ask the registry which version `name@version` resolves to.
- *
- * @param {string} spec - `<name>@<version>`.
- * @returns {string} The version npm printed, or its error text when the query
- *   fails (an unpublished version answers E404).
- */
-export function queryNpm(spec) {
-    const result = spawnSync("npm", ["view", spec, "version"], { encoding: "utf8" });
-    if (result.error) return result.error.message;
-    const out = (result.stdout ?? "").trim();
-    if (result.status === 0) return out;
-    const err = (result.stderr ?? "").trim().replace(/\s*\n\s*/g, " | ");
-    return err || out || `npm exited ${result.status}`;
-}
-
-/**
- * Poll until the registry serves `version` of `name`.
- *
- * @param {object} options
- * @param {string} options.name - Package name.
- * @param {string} options.version - Exact version expected.
- * @param {(spec: string) => string} [options.query] - Registry query; returns
- *   the registry's answer for `<name>@<version>`.
- * @param {(ms: number) => Promise<void>} [options.sleep] - Waits between queries.
- * @param {number} [options.intervalSeconds] - Seconds between queries.
- * @param {number} [options.timeoutSeconds] - Seconds before giving up.
- * @param {(line: string) => void} [options.log] - Progress output.
- * @returns {Promise<{ok: true, attempts: number} | {ok: false, attempts: number, last: string}>}
- */
-export async function confirmNpmVersion({
-    name,
-    version,
-    query = queryNpm,
-    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    intervalSeconds = DEFAULT_INTERVAL_SECONDS,
-    timeoutSeconds = DEFAULT_TIMEOUT_SECONDS,
-    log = () => {},
-}) {
-    const spec = `${name}@${version}`;
-    const attemptLimit = Math.floor(timeoutSeconds / intervalSeconds) + 1;
-    let last = "";
-    for (let attempts = 1; attempts <= attemptLimit; attempts++) {
-        last = query(spec);
-        if (last === version) {
-            log(`${spec} is served by npm.`);
-            return { ok: true, attempts };
-        }
-        log(`${spec} is not served yet (${last || "empty answer"}).`);
-        if (attempts < attemptLimit) await sleep(intervalSeconds * 1000);
-    }
-    return { ok: false, attempts: attemptLimit, last };
-}
-
-function parseArguments(argv) {
-    const positional = [];
-    const options = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "--interval" || arg === "--timeout") {
-            const value = Number(argv[++i]);
-            if (!Number.isFinite(value) || value <= 0) {
-                throw new Error(`${arg} takes a positive number of seconds.`);
-            }
-            options[arg === "--interval" ? "intervalSeconds" : "timeoutSeconds"] = value;
-        } else if (arg.startsWith("--")) {
-            throw new Error(`Unknown option ${arg}.`);
-        } else {
-            positional.push(arg);
-        }
-    }
-    if (positional.length !== 2) {
-        throw new Error(
-            "Usage: confirm-npm-version.mjs <name> <version> [--interval <s>] [--timeout <s>]",
-        );
-    }
-    return { name: positional[0], version: positional[1], ...options };
-}
-
-async function main(argv) {
-    let options;
-    try {
-        options = parseArguments(argv);
-    } catch (error) {
-        console.error(`::error::${error.message}`);
-        return 2;
-    }
-    const outcome = await confirmNpmVersion({ ...options, log: (line) => console.log(line) });
-    if (outcome.ok) return 0;
-    const timeout = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
-    console.error(
-        `::error::npm does not serve ${options.name}@${options.version} after ${timeout}s and ${outcome.attempts} queries. Last registry answer: ${outcome.last || "(empty)"}`,
-    );
-    return 1;
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exitCode = await main(process.argv.slice(2));
-}