@heroiclands/package-build 23.12.5 → 23.12.6

package/engine/event-rows.mjs

@@ -25,10 +25,19 @@
  * `resolvedDates.events`, position for position with `data.events`, and the
  * sort keys are read from it rather than parsed again here.
  *
- * **`whenText` and `untilText` are the dates as a reader sees them**: printed
- * as the `dateformat` helper prints a date, in the calendar the owning note
- * names in `data.calendar`, else the one the world note names, else in the era
- * the date itself names. A date that does not resolve keeps its authored text.
+ * **`whenText` and `untilText` are the dates as a reader of the owning note
+ * sees them**: printed as the `dateformat` helper prints a date, in the
+ * calendar the owning note resolves to — see
+ * {@link module:engine/note-calendars} — else in the era the date itself
+ * names. A date that does not resolve keeps its authored text.
+ *
+ * **`whenIn` and `untilIn` are the same dates in every calendar**: a struct
+ * keyed by each calendar note's canonical Address, every calendar the corpus
+ * holds or any note resolves to, so a query reads a date in the calendar it
+ * chooses — `e.whenIn['thalorna-note-lore-commoncal']`. Every row carries every
+ * key; a date a calendar cannot print reads there as it would in `whenText`
+ * with no calendar, and an absent date is `NULL`. The event views select the
+ * key of the page's calendar.
  *
  * @module
  */
@@ -36,6 +45,7 @@
 import { ownDocumentSystem, renderAddress } from "./address.mjs";
 import { printEventDateIn } from "./event-fields.mjs";
 import { EVENT_ENTRY_KEYS } from "./note-event-terms.mjs";
+import { calendarAddress } from "./reckoning-markers.mjs";
 
 /** The columns a row carries besides the event's own keys, before them. */
 const IDENTITY_COLUMNS = Object.freeze(["note", "address"]);
@@ -46,12 +56,16 @@ export const EVENT_SORT_COLUMNS = Object.freeze(["whenSort", "whenYear", "untilS
 /** The printed dates a row carries, after the sort keys. */
 export const EVENT_TEXT_COLUMNS = Object.freeze(["whenText", "untilText"]);
 
+/** The dates a row carries in every calendar, after the printed ones. */
+export const EVENT_CALENDAR_COLUMNS = Object.freeze(["whenIn", "untilIn"]);
+
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS = Object.freeze([
     ...IDENTITY_COLUMNS,
     ...EVENT_ENTRY_KEYS,
     ...EVENT_SORT_COLUMNS,
     ...EVENT_TEXT_COLUMNS,
+    ...EVENT_CALENDAR_COLUMNS,
 ]);
 
 /** The keys whose authored value is a date, printed as the text it was written as. */
@@ -95,18 +109,35 @@ function axisKeys(date) {
 }
 
 /**
- * The calendar the world note names, which displays every date whose own note
- * names none.
+ * Every calendar a set of records can print an event's date in: each calendar
+ * note's canonical Address, and every calendar a note resolves to.
  *
- * @param {Record<string, any>[]} records - Index records.
- * @returns {string|undefined} The calendar's Address or shortcode.
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string.
+ * @returns {string[]} The calendars, sorted.
  */
-function worldCalendar(records) {
+export function eventCalendars(records) {
+    const calendars = new Set();
     for (const record of records) {
-        if (record?.type === "place" && record.data?.year?.days && record.data.calendar)
-            return String(record.data.calendar);
+        const resolved = calendarAddress(record?.resolvedCalendar);
+        if (resolved) calendars.add(resolved);
+        if (
+            record?.type === "lore" &&
+            String(record.subType ?? "").toLowerCase() === "calendar" &&
+            record.package &&
+            record.shortcode &&
+            !record.documents
+        )
+            calendars.add(
+                renderAddress({
+                    package: String(record.package),
+                    system: "note",
+                    type: "lore",
+                    shortcode: String(record.shortcode),
+                }),
+            );
     }
-    return undefined;
+    return [...calendars].sort();
 }
 
 /**
@@ -115,12 +146,16 @@ function worldCalendar(records) {
  * @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.
+ * @param {readonly string[]} [calendars] - The calendars `whenIn` and
+ *   `untilIn` are keyed by: {@link eventCalendars} of every record of the
+ *   corpus, whatever the audience, so every surface's relation has the same
+ *   keys. Absent, those of `records`.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records, dates) {
+export function eventRows(records, dates, calendars) {
     const rows = [];
     const all = [...records];
-    const world = worldCalendar(all);
+    const keys = calendars ?? eventCalendars(all);
     for (const record of all) {
         const events = record?.data?.events;
         if (!Array.isArray(events) || !events.length) continue;
@@ -128,7 +163,7 @@ export function eventRows(records, dates) {
         if (!note) continue;
         const resolved =
             Array.isArray(record.resolvedDates?.events) ? record.resolvedDates.events : [];
-        const calendar = record.data?.calendar ? String(record.data.calendar) : world;
+        const calendar = calendarAddress(record.resolvedCalendar);
         events.forEach((entry, position) => {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
             const row = {
@@ -149,10 +184,20 @@ export function eventRows(records, dates) {
             row.untilSort = until.sort;
             row.untilYear = until.year;
             for (const key of DATE_KEYS) {
+                const date = resolved[position]?.[key];
                 row[`${key}Text`] =
-                    row[key] === null ?
-                        null
-                    :   printEventDateIn(row[key], resolved[position]?.[key], dates, calendar);
+                    row[key] === null ? null : printEventDateIn(row[key], date, dates, calendar);
+                row[`${key}In`] =
+                    keys.length ?
+                        Object.fromEntries(
+                            keys.map((each) => [
+                                each,
+                                row[key] === null ?
+                                    null
+                                :   printEventDateIn(row[key], date, dates, each),
+                            ]),
+                        )
+                    :   null;
             }
             rows.push(row);
         });

package/engine/event-views.mjs

@@ -41,6 +41,7 @@
 
 import { ownDocumentSystem, renderAddress } from "./address.mjs";
 import { authoredSection, sectionHeading } from "./generated-sections.mjs";
+import { calendarAddress } from "./reckoning-markers.mjs";
 
 /** A literal SQL string. */
 const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
@@ -48,6 +49,16 @@ const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
 /** A list of SQL string literals, for an `IN (…)`. */
 const literals = (texts) => texts.map(literal).join(", ");
 
+/**
+ * The `When` column of a view on a page whose dates print in `calendar`: the
+ * event's date in that calendar, or — on a page with no calendar — in its
+ * owning note's.
+ *
+ * @param {string} [calendar] - The page's calendar, a canonical Address.
+ * @returns {string} The column's expression.
+ */
+const whenColumn = (calendar) => (calendar ? `e.whenIn[${literal(calendar)}]` : "e.whenText");
+
 /** The order every view sorts its rows in: by date, undated last. */
 const BY_DATE = "ORDER BY e.whenSort NULLS LAST, e.address";
 
@@ -65,7 +76,7 @@ const BY_DATE = "ORDER BY e.whenSort NULLS LAST, e.address";
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean}) => {fence: string, own?: string}|null,
+ *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean, calendar?: string}) => {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>>}>>}
  */
@@ -87,13 +98,13 @@ export const EVENT_VIEWS = Object.freeze([
             (record.type === "lore" && record.subType === "culture"),
         owners: (db, selves, shape) =>
             namedOwners(db, selves, "SELECT unnest(who).ref AS ref FROM events", shape.who),
-        query: (self, shape) => {
+        query: (self, shape, columns = {}) => {
             if (!shape.who) return null;
             const named = `list_filter(e.who, w -> w.ref IN (${literals(self)}))`;
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
-                    '       e.whenText AS "When",',
+                    `       ${whenColumn(columns.calendar)} AS "When",`,
                     '       e.summary AS "What happened",',
                     `       array_to_string(list_transform(${named}, w -> w.role), ', ') AS "Role"`,
                     "FROM events e",
@@ -117,12 +128,12 @@ export const EVENT_VIEWS = Object.freeze([
                 'SELECT account."by" AS ref FROM (SELECT unnest(accounts) AS account FROM events)',
                 shape.accounts,
             ),
-        query: (self, shape) => {
+        query: (self, shape, columns = {}) => {
             if (!shape.accounts) return null;
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
-                    '       e.whenText AS "When",',
+                    `       ${whenColumn(columns.calendar)} AS "When",`,
                     '       e.summary AS "Event",',
                     '       e.account.says AS "What they say",',
                     '       e.account.agrees AS "Agrees"',
@@ -145,7 +156,7 @@ export const EVENT_VIEWS = Object.freeze([
                     "FROM (SELECT unnest(follows) AS edge FROM events)",
                 shape.follows,
             ),
-        query: (self, shape) => {
+        query: (self, shape, columns = {}) => {
             if (!shape.follows) return null;
             const edges =
                 `list_filter(e.follows, f -> split_part(f.event, '#', 1) ` +
@@ -153,7 +164,7 @@ export const EVENT_VIEWS = Object.freeze([
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
-                    '       e.whenText AS "When",',
+                    `       ${whenColumn(columns.calendar)} AS "When",`,
                     '       e.summary AS "What followed",',
                     `       array_to_string(list_transform(${edges}, f -> f.how), ', ') AS "How"`,
                     "FROM events e",
@@ -307,8 +318,9 @@ async function chronologyRoots(db, selves, shape, conditions) {
  *
  * @param {string[]} self - The place's Address, in each form.
  * @param {CorpusShape} shape - What the corpus states.
- * @param {{felt?: boolean}} [columns] - `felt: false` when no row of this
- *   place is felt there, which leaves the `Felt here` column out.
+ * @param {{felt?: boolean, calendar?: string}} [columns] - `felt: false` when
+ *   no row of this place is felt there, which leaves the `Felt here` column
+ *   out; `calendar`, the page's calendar, which the `When` column prints in.
  * @returns {{fence: string, own: string}|null} The query, and the one that
  *   counts the place's own rows.
  */
@@ -332,7 +344,7 @@ function chronologyQuery(self, shape, columns = {}) {
         ...below,
         "here AS (SELECT list(place) AS places FROM below)",
         "SELECT e.note AS _ref,",
-        '       e.whenText AS "When",',
+        `       ${whenColumn(columns.calendar)} AS "When",`,
         shape.reach && columns.felt !== false ?
             '       e.summary AS "What happened",'
         :   '       e.summary AS "What happened"',
@@ -453,11 +465,12 @@ export async function eventViewSections(db, records, fileOf, only) {
         const sections = new Map();
         for (const view of EVENT_VIEWS) {
             if (!view.applies(record) || authoredSection(record, view.slug)) continue;
-            const query = view.query(
-                self,
-                shape,
-                felt.has(view.slug) ? { felt: felt.get(view.slug).has(self[0]) } : undefined,
-            );
+            const query = view.query(self, shape, {
+                ...(felt.has(view.slug) ? { felt: felt.get(view.slug).has(self[0]) } : {}),
+                ...(calendarAddress(record.resolvedCalendar) ?
+                    { calendar: calendarAddress(record.resolvedCalendar) }
+                :   {}),
+            });
             if (!query) continue;
             const has =
                 owned.has(view.slug) ?

package/engine/index-records.mjs

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

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.
@@ -1066,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/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;
             },
     }),