@heroiclands/package-build 23.12.4 → 23.12.6

package/engine/holdings.mjs

@@ -24,13 +24,14 @@ import { isAddressTuple, ownDocumentSystem, parseAddress, renderAddress } from "
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 
-/** @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.
@@ -108,6 +109,7 @@ function listed(node) {
 function entryOf(node) {
     return {
         title: node.title,
+        ...(node.sort ? { sort: node.sort } : {}),
         ...(listed(node) ? { url: node.url } : {}),
         address: ownKey(node),
         type: node.type,
@@ -118,7 +120,7 @@ function entryOf(node) {
 function bySubTypeThenTitle(a, b) {
     return (
         (a.subType ?? "").localeCompare(b.subType ?? "", "en") ||
-        a.title.localeCompare(b.title, "en")
+        (a.sort ?? a.title).localeCompare(b.sort ?? b.title, "en")
     );
 }
 
@@ -141,6 +143,7 @@ export function holdingsNode(
         type,
         subType: fm.subType == null ? undefined : String(fm.subType),
         title,
+        ...(typeof fm.name?.sort === "string" && fm.name.sort ? { sort: fm.name.sort } : {}),
         url,
         ...(pkg ? { package: pkg } : {}),
         ...(system ? { system } : {}),
@@ -173,6 +176,9 @@ export function foreignHoldingsNodes(foreignIndex) {
             type,
             subType: entry.subType == null ? undefined : String(entry.subType),
             title: String(entry.name ?? tuple.shortcode),
+            ...(typeof entry.nameSort === "string" && entry.nameSort ?
+                { sort: entry.nameSort }
+            :   {}),
             url: entry.url,
             parents:
                 type === "place" ?

package/engine/index-records.mjs

@@ -62,6 +62,7 @@ export const DERIVED_KEYS = Object.freeze([
     "documents",
     "asset",
     "resolvedDates",
+    "resolvedCalendar",
     "citations",
     "names",
 ]);

package/engine/infobox-render.mjs

@@ -296,9 +296,14 @@ function entryToTypst(entry, link) {
 }
 
 /**
- * One section as Typst, whole and unbreakable.
+ * One section as Typst.
  *
- * `lead` rides **inside** the block rather than above it. A panel breaks
+ * A stat grid is whole and unbreakable. A section of rows or run-in lists may
+ * break between its rows, so a section taller than the space left on a page
+ * continues on the next one instead of running past the page's foot; each row
+ * stays whole, and the section's label and `lead` stay with its first row.
+ *
+ * `lead` rides **inside** the section rather than above it. A panel breaks
  * between its sections, and a title sitting outside the first one is a break
  * the panel is allowed to take — which leaves the heading and a rule stranded
  * at the foot of a page with nothing under them.
@@ -309,8 +314,9 @@ function entryToTypst(entry, link) {
  * @returns {string} Typst markup.
  */
 function sectionToTypst(section, link, lead = "") {
-    const body = lead ? [lead] : [];
-    if (section.label) body.push(`#infobox-head[${escapeTypst(section.label)}]`);
+    const head = lead ? [lead] : [];
+    if (section.label) head.push(`#infobox-head[${escapeTypst(section.label)}]`);
+    const body = [];
 
     if (section.layout === "rows") {
         for (const row of section.rows ?? []) {
@@ -346,7 +352,12 @@ function sectionToTypst(section, link, lead = "") {
         }
     }
 
-    return `#block(breakable: false)[\n${body.join("\n")}\n]`;
+    if (section.layout === "grid" || body.length < 2)
+        return `#block(breakable: false)[\n${[...head, ...body].join("\n")}\n]`;
+    const [first, ...rest] = body;
+    const kept = `#block(breakable: false)[\n${[...head, first].join("\n")}\n]`;
+    const rows = rest.map((row) => `#block(breakable: false)[${row}]`);
+    return `#block(breakable: true)[\n${[kept, ...rows].join("\n")}\n]`;
 }
 
 /**

package/engine/infobox.mjs

@@ -128,6 +128,7 @@ import {
     standingLead,
 } from "./standings.mjs";
 import { AddressEntries } from "./address-values.mjs";
+import { noteCalendar } from "./note-calendars.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -593,6 +594,27 @@ export function valueKindOf(field, value) {
     return Array.isArray(value) ? "list" : "text";
 }
 
+/**
+ * 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) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return String(value);
+    const size = Math.abs(n);
+    if (size < 1e6) return n.toLocaleString("en-US", { maximumFractionDigits: 20 });
+    // A figure that rounds up to a thousand million is a billion.
+    const [scale, word] = size < 999.95e6 ? [1e6, "million"] : [1e9, "billion"];
+    const scaled = Math.round((n / scale) * 10) / 10;
+    return `${scaled.toLocaleString("en-US", { maximumFractionDigits: 1 })} ${word}`;
+}
+
 /**
  * Build one row's value, resolving whatever the kind says is a reference.
  *
@@ -616,7 +638,7 @@ function rowValue(kind, raw, resolve, hint, verbatim = false) {
     if (kind === "list") {
         return (Array.isArray(raw) ? raw : [raw]).filter(hasValue).map((v) => shown(v));
     }
-    if (kind === "number") return raw;
+    if (kind === "number") return formatQuantity(raw);
     return shown(raw);
 }
 
@@ -904,7 +926,7 @@ function declaredKeyRows(fields, raw) {
             (inner.kind === "number" || inner.kind === "integer") &&
             Number.isFinite(Number(value))
         ) {
-            rows.push({ label, kind: "number", value: Number(value) });
+            rows.push({ label, kind: "number", value: formatQuantity(Number(value)) });
         } else {
             rows.push({ label, kind: "text", value: shown(value) });
         }
@@ -1045,15 +1067,10 @@ function noteBox(
                 : parsed?.qualifier ? dates.eras?.get(parsed.qualifier)
                 : null;
             let printable = null;
-            if (parsed?.known && data.calendar) {
+            const calendar = noteCalendar(fm, dates);
+            if (parsed?.known && calendar) {
                 try {
-                    printable = formatDateInCalendar(
-                        parsed,
-                        isAddressTuple(data.calendar) ?
-                            renderAddress(data.calendar)
-                        :   data.calendar,
-                        dates,
-                    );
+                    printable = formatDateInCalendar(parsed, calendar, dates);
                 } catch {
                     // The calendar reference is checked at the authored field.
                 }

package/engine/literature-works.mjs

@@ -31,11 +31,12 @@ import { AddressLink } from "./address-values.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 import { LITERATURE_SUBTYPE } from "./literature-notes.mjs";
 
-/** @typedef {{title: string, url?: string, address: string, form?: string}} WorkEntry */
+/** @typedef {{title: string, sort?: string, url?: string, address: string, form?: string}} WorkEntry */
 /**
  * @typedef {object} WorksNode
  * @property {string} key Own Address, normalized to the `note` system.
  * @property {string} title
+ * @property {string} [sort] The note's `name.sort`; the list files by it in place of `title`.
  * @property {string} [url] Absent for a note that publishes no page.
  * @property {string} [package] Owning content package.
  * @property {string} [form] A work's `data.form`.
@@ -79,6 +80,7 @@ export function worksNode(fm, { title, url, package: pkg }) {
     return {
         key: renderAddress({ package: pkg ?? "local", system: "note", type, shortcode }),
         title,
+        ...(typeof fm.name?.sort === "string" && fm.name.sort ? { sort: fm.name.sort } : {}),
         ...(url ? { url } : {}),
         ...(pkg ? { package: pkg } : {}),
         ...(work && typeof data.form === "string" && data.form ? { form: data.form } : {}),
@@ -107,6 +109,9 @@ export function foreignWorksNodes(foreignIndex) {
         out.push({
             key: renderAddress({ ...tuple, system: "note" }),
             title: String(entry.name ?? tuple.shortcode),
+            ...(typeof entry.nameSort === "string" && entry.nameSort ?
+                { sort: entry.nameSort }
+            :   {}),
             ...(entry.url ? { url: entry.url } : {}),
             package: tuple.package,
             ...(typeof entry.form === "string" && entry.form ? { form: entry.form } : {}),
@@ -149,6 +154,7 @@ export function worksPages(nodes, { types }) {
             if (!block) lists.set(target.url, (block = { works: [] }));
             block.works.push({
                 title: work.title,
+                ...(work.sort ? { sort: work.sort } : {}),
                 ...(work.url ? { url: work.url } : {}),
                 address: work.key,
                 ...(work.form ? { form: work.form } : {}),
@@ -156,6 +162,6 @@ export function worksPages(nodes, { types }) {
         }
     }
     for (const block of lists.values())
-        block.works.sort((a, b) => a.title.localeCompare(b.title, "en"));
+        block.works.sort((a, b) => (a.sort ?? a.title).localeCompare(b.sort ?? b.title, "en"));
     return lists;
 }

package/engine/markdown-expressions.mjs

@@ -15,11 +15,12 @@ import Handlebars from "handlebars";
 
 import { isAddressTuple, renderAddress } from "./address.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
-import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
+import { calendarEras, formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
 import { numberWords, numberDigits } from "./number-words.mjs";
 import { slugify } from "./content-slug.mjs";
 import { WIKILINK, authoredLabel, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
-import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
+import { EVENT_REFERENCE_FIELDS, eventFieldText, printEventDate } from "./event-fields.mjs";
+import { noteCalendar } from "./note-calendars.mjs";
 
 /**
  * An inline expression, as an author writes one.
@@ -33,6 +34,48 @@ import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
  */
 export const EXPRESSION = /(?<![\\{])\{\{(?![{<%])([^{}\n]+)\}\}(?!\})/g;
 
+/**
+ * Which of `dateformat`'s arguments is which. Three are a calendar, a date and
+ * a format. Two are a calendar and a date, unless the first is absent — a
+ * `data.calendar` the note leaves unset is no calendar — or is a date that
+ * names no calendar, when they are a date and a format. One is a date.
+ *
+ * @param {unknown[]} given - The arguments, without Handlebars' options.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {{calendar?: unknown, authored: unknown, format?: unknown}} The roles.
+ */
+function dateformatArguments(given, dates) {
+    if (given.length >= 3) {
+        const [calendar, authored, format] = given;
+        return { calendar: calendar ?? undefined, authored, format };
+    }
+    if (given.length < 2) return { authored: given[0] };
+    const [first, second] = given;
+    if (first === undefined || first === null) return { authored: second };
+    if (typeof first === "number") return { authored: first, format: second };
+    if (typeof first === "string" && !namesCalendar(first, dates)) {
+        const parsed = parseNoteDate(first, { ...dates, allowUnknown: false });
+        if (parsed.date && !parsed.findings.some((item) => item.severity === "error"))
+            return { authored: first, format: second };
+    }
+    return { calendar: first, authored: second };
+}
+
+/**
+ * Whether a string names a calendar or one of its eras.
+ *
+ * @param {string} value - The string.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {boolean} Whether it resolves to one.
+ */
+function namesCalendar(value, dates) {
+    try {
+        return calendarEras(value, dates).length > 0;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * Every helper an expression may call, with the parameters it takes.
  *
@@ -135,30 +178,42 @@ const HELPERS = Object.freeze([
     }),
     Object.freeze({
         name: "dateformat",
-        params: 'calendar date ["format"]',
+        params: '[calendar] date ["format"]',
         summary:
-            "A date written in a calendar. The calendar is an Address or its shortcode, the date " +
-            "is the value a note carries, and the optional third argument names an output pattern.",
+            "A date written in a calendar. The calendar is an Address or its shortcode; left " +
+            "out, it is the note's own calendar — its `data.calendar`, else its culture's, " +
+            "else for a place its parents', else the configured `defaultCalendar` — and a " +
+            "note with none prints the date as written. The date is the value a note " +
+            "carries, and the optional last argument names an output pattern.",
         make:
-            ({ dates }) =>
-            (calendar, authored, formatOrOptions) => {
+            ({ dates, fm }) =>
+            (...args) => {
+                const { calendar, authored, format } = dateformatArguments(
+                    args.slice(0, -1),
+                    dates,
+                );
                 if (
-                    !(typeof calendar === "string" || isAddressTuple(calendar)) ||
-                    !["string", "number"].includes(typeof authored)
+                    !(
+                        calendar === undefined ||
+                        typeof calendar === "string" ||
+                        isAddressTuple(calendar)
+                    ) ||
+                    !["string", "number"].includes(typeof authored) ||
+                    !(format === undefined || typeof format === "string")
                 )
-                    throw new TypeError("dateformat needs a calendar Address and a date");
+                    throw new TypeError("dateformat needs a date, and takes a calendar Address");
                 const parsed = parseNoteDate(authored, { ...dates, allowUnknown: false });
                 const error = parsed.findings.find((item) => item.severity === "error");
                 if (error || !parsed.date)
                     throw new RangeError(error?.message ?? "date does not resolve");
-                const printable = formatDateInCalendar(
-                    parsed.date,
-                    isAddressTuple(calendar) ? renderAddress(calendar) : calendar,
-                    dates,
-                    typeof formatOrOptions === "string" ? formatOrOptions : undefined,
-                );
+                const reference =
+                    calendar === undefined ? noteCalendar(fm, dates)
+                    : isAddressTuple(calendar) ? renderAddress(calendar)
+                    : calendar;
+                if (reference === undefined) return printEventDate(authored, parsed.date, dates);
+                const printable = formatDateInCalendar(parsed.date, reference, dates, format);
                 if (!printable)
-                    throw new RangeError(`date cannot be printed in calendar ${calendar}`);
+                    throw new RangeError(`date cannot be printed in calendar ${reference}`);
                 return printable.prose ?? printable.text;
             },
     }),

package/engine/metadata-index.mjs

@@ -445,6 +445,9 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
             const foundry = record.foundry?.[parts.system];
             index.set(key, {
                 name: record.name?.full ?? record.name,
+                ...(typeof record.name?.sort === "string" && record.name.sort ?
+                    { nameSort: record.name.sort }
+                :   {}),
                 aliases: record.name?.aliases,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it

package/engine/name-sort.mjs

@@ -0,0 +1,91 @@
+/*
+ * 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
+ */
+
+/**
+ * The key a name-ordered list files a note under, and the ASCII fold ordering
+ * compares it on. A leaf module, so every list that orders notes by name can
+ * read the key without importing the content index.
+ *
+ * @module
+ */
+
+import unidecode from "unidecode";
+
+/**
+ * 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) {
+    if (typeof name !== "string") return null;
+    const folded = unidecode(name)
+        .replace(/[^\x20-\x7E]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return folded === "" ? null : folded;
+}
+
+/**
+ * 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) {
+    const name = /** @type {any} */ (record)?.name;
+    for (const candidate of [name?.sort, name?.full]) {
+        if (typeof candidate === "string" && candidate.trim()) return candidate;
+    }
+    return 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) {
+    const key = nameSortOf(record);
+    if (key === undefined) return "";
+    return asciiName(key) ?? key;
+}