@heroiclands/package-build 23.12.4 → 23.12.5

package/engine/sql-tables.mjs

@@ -32,6 +32,7 @@ import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
 import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
 import {
     GLOSSARY_COLUMNS,
@@ -66,6 +67,7 @@ import { parseMarkdownFile } from "./helpers.mjs";
 import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
 import { authoredFrontmatter, isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
+import { nameSortOf } from "./name-sort.mjs";
 
 /** Rendered in a cell whose value is absent. */
 const EMPTY_CELL = "—";
@@ -438,11 +440,25 @@ export async function openNotesDatabase(
  */
 const WITH_STUBS_SCHEMA = "__with_stubs";
 
+/**
+ * The record with its `nameSort` stated: the declared `name.sort`, otherwise
+ * `name.full`. A record with no name has none.
+ *
+ * @param {object} record - An index record.
+ * @returns {object} The record, with `nameSort` where it has a name.
+ */
+function withNameSort(record) {
+    const key = nameSortOf(record);
+    return key === undefined ? record : { ...record, nameSort: key };
+}
+
 /**
  * Create the two relations an index is read through, and the ladder one of them
  * derives.
  *
- * **`entries` is every row**, stubs included, plus a derived `state` column:
+ * **`entries` is every row**, stubs included, plus a derived `nameSort` column
+ * (the note's `name.sort`, otherwise its `name.full`) and a derived `state`
+ * column:
  *
  * ```text
  * address IS NULL                 → stub
@@ -484,7 +500,7 @@ async function createRelations(connection, file, records, prefix = "", audience
         records
             .map((record) =>
                 JSON.stringify({
-                    record: sortKeysDeep(record),
+                    record: sortKeysDeep(withNameSort(record)),
                     visible: audience !== "public" || !isGmNote(record),
                 }),
             )
@@ -535,9 +551,8 @@ async function createRelations(connection, file, records, prefix = "", audience
  * @returns {Promise<void>}
  */
 async function createEventRelation(connection, file, records, prefix, audience) {
-    const rows = eventRows(
-        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
-    );
+    const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
+    const rows = eventRows(visible, reckoningContext({ notes: records }));
     if (!rows.length) {
         const columns = EVENT_COLUMNS.map((column) => {
             const type = EVENT_SORT_COLUMNS.includes(column) ? "DOUBLE" : "VARCHAR";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.4",
+    "version": "23.12.5",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

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

@@ -31,36 +31,6 @@ export function noteAddress(frontmatter: Record<string, any>, contentPackage: st
     slug: string;
     canonical: string;
 } | null;
-/**
- * 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;
 /**
  * A note's `name.aliases` reduced to printable 7-bit ASCII, in order.
  *
@@ -449,6 +419,7 @@ export type PreparedContentIndex = {
      */
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 };
+import { asciiName } from "./name-sort.mjs";
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";
@@ -458,4 +429,4 @@ import { isStub } from "./index-records.mjs";
 import { noteFile } from "./index-records.mjs";
 import { recordPath } from "./index-records.mjs";
 import { sortKeysDeep } from "./index-records.mjs";
-export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };
+export { asciiName, collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };

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

@@ -46,6 +46,17 @@ export function eventNoteIndex(records: Iterable<Record<string, any>>, { content
  * @returns {string} The printed date.
  */
 export function printEventDate(written: unknown, date: object | null, dates?: object): string;
+/**
+ * A date as `dateformat` prints it in a calendar, where one is named and
+ * prints it; otherwise as {@link printEventDate} prints it.
+ *
+ * @param {unknown} written - The date as the event writes it.
+ * @param {object|null} date - The resolved date.
+ * @param {object} [dates] - The reckoning context.
+ * @param {string} [calendar] - The calendar's Address or shortcode.
+ * @returns {string} The printed date; the authored text when nothing resolves.
+ */
+export function printEventDateIn(written: unknown, date: object | null, dates?: object, calendar?: string): string;
 /**
  * One field of one event, as the text a reference prints, or why it cannot.
  *

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

@@ -3,10 +3,13 @@
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
+ * @param {object} [dates] - The reckoning context the dates are printed in.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records: Iterable<Record<string, any>>): object[];
+export function eventRows(records: Iterable<Record<string, any>>, dates?: object): object[];
 /** The sort keys a row carries, after the event's own keys. */
 export const EVENT_SORT_COLUMNS: readonly string[];
+/** The printed dates a row carries, after the sort keys. */
+export const EVENT_TEXT_COLUMNS: readonly string[];
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS: any;

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-render.d.mts

@@ -169,6 +169,10 @@ export function absolutePageUrl(url: string, site?: string): string;
  * carried, then the book and the page. A book with an abbreviation reads
  * `Name (Aelw. p12)`; one without reads `Name (_Book title_, p. 12)`.
  *
+ * 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.
  *
@@ -176,12 +180,16 @@ export function absolutePageUrl(url: string, site?: string): string;
  * @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.