@heroiclands/package-build 22.7.0 → 22.9.0

package/engine/calendars.mjs

@@ -0,0 +1,233 @@
+/*
+ * 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 axis every date normalises onto, and the one function that puts a
+ * reckoning on it.**
+ *
+ * A setting keeps several counts of years at once, each proclaimed by a body
+ * that has a note — a founding, a first occasion, a reign. A date either names
+ * one of them or names none, in which case it sits on the **canonical axis**.
+ *
+ * ## The canonical axis is an authoring device, not a calendar
+ *
+ * The axis is the line of integers dates written by peoples who never met are
+ * compared on. Nobody in a setting keeps it, no body stands behind it, and no
+ * shortcode addresses it: a date is on the axis exactly when it names no era.
+ * A reckoning whose year 1 happens to sit where the axis's year 1 sits
+ * coincides with it numerically and is still that people's own count.
+ *
+ * ## There is no year zero, and one function converts
+ *
+ * The authored numbering skips zero — `-1` sits immediately before `1` — while
+ * the normalised value does not, so that arithmetic across an epoch is one
+ * subtraction rather than a special case somebody forgets.
+ *
+ * ```text
+ * authored        …  -3   -2   -1    1    2    3  …
+ * canonicalYear   …  -2   -1    0    1    2    3  …
+ * ```
+ *
+ * ```text
+ * canonicalYear(y, E) = E + (y > 0 ? y - 1 : y)
+ * ```
+ *
+ * `E` is where a reckoning's year 1 sits on the axis — the `canonicalYear` of
+ * an era's own `start`. The axis is the same function with `E` of
+ * {@link CANONICAL_EPOCH}, which holds by definition: the axis's year 1 is the
+ * axis's year 1.
+ *
+ * **The conversion is piecewise on the sign**, and that is the property worth
+ * guarding. Collapsed to a single branch it is correct on one side of an epoch
+ * and off by one on the other, which is invisible in any list that does not
+ * span it.
+ *
+ * ## The month structure is the calendar's, and an absent list bounds nothing
+ *
+ * An era moves where year 1 sits; it does not divide the year differently. The
+ * division belongs to the calendar, which is a note declaring an **ordered
+ * list** of months, each with a name and a day count. Position in the list is
+ * position in the year, so a five-day month sits wherever its people put it and
+ * needs no rule of its own.
+ *
+ * A date is bounded by the calendar it is written in, and a calendar whose list
+ * nobody has written down bounds nothing — a toolchain that invented twelve
+ * Gregorian months would refuse `667/2/30`, an ordinary date in a year of
+ * twelve thirty-day months.
+ *
+ * ## The lunar phase takes a floored modulo, not JavaScript's
+ *
+ * `%` takes the dividend's sign, so a day before the epoch yields `-7` where
+ * the phase is 23. {@link lunarPhase} is the one place that is written.
+ *
+ * @module
+ */
+
+/**
+ * Where the canonical axis's own year 1 sits — on itself.
+ *
+ * It takes no configuration entry and no era row, because it is true by
+ * definition rather than by declaration.
+ *
+ * @type {number}
+ */
+export const CANONICAL_EPOCH = 1;
+
+/**
+ * The year on the canonical axis that a written year lands on.
+ *
+ * The whole of the conversion. A reckoning differs from its neighbours in
+ * where its year 1 sits and in nothing else, so an era states one number and
+ * this states what to do with it.
+ *
+ * The two branches are the year-zero hole: the authored numbering has no year
+ * 0, so a positive year is one place closer to the epoch than its magnitude
+ * suggests and a negative year is exactly its magnitude below it.
+ *
+ * @param {number} year - The year as authored, signed, within its own
+ *   reckoning. Never 0 — the authored numbering has no such year.
+ * @param {number} [epoch] - Where that reckoning's year 1 sits on the axis.
+ *   Omitted, the axis itself.
+ * @returns {number} The signed year on the axis — authored `-1` is `0`.
+ */
+export function canonicalYear(year, epoch = CANONICAL_EPOCH) {
+    return epoch + (year > 0 ? year - 1 : year);
+}
+
+/**
+ * The total-order key a date sorts on.
+ *
+ * Month and day fold into the fraction, so a mixed-precision list sorts stably
+ * against a single number instead of a three-key comparator. The arithmetic is
+ * done in ten-thousandths and divided once, because `year + 6 / 100 + 19 /
+ * 10000` accumulates a rounding error and `689.0619` is a value a reader
+ * compares against by eye.
+ *
+ * A coarser value sorts **before** the finer values inside it: `689` precedes
+ * `689/1`, which is the ordering a reader expects of a year whose month nobody
+ * wrote.
+ *
+ * @param {number} year - The year on the canonical axis.
+ * @param {number|null} month - The month, or `null`.
+ * @param {number|null} day - The day, or `null`.
+ * @returns {number} The sort key.
+ */
+export function dateSortKey(year, month, day) {
+    return (year * 10000 + (month ?? 0) * 100 + (day ?? 0)) / 10000;
+}
+
+/**
+ * One month of a calendar, as the note declares it.
+ *
+ * @typedef {object} CalendarMonth
+ * @property {string} name - What the month is called.
+ * @property {string} [abbreviation] - A short form, where the note gives one.
+ * @property {number} days - How many days it holds.
+ */
+
+/**
+ * The months a calendar keeps, or `null` where it declares none.
+ *
+ * Separate from the check that reads it so a caller can ask what a calendar
+ * divides its year into without phrasing a finding about it. An empty list
+ * reads as no list: a calendar that declares nothing and one that declares
+ * nothing in a pair of brackets divide the year identically.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar
+ *   the date is written in, as its note declares it.
+ * @returns {{months: readonly CalendarMonth[]|null}} What it divides the year
+ *   into.
+ */
+export function calendarStructure(calendar) {
+    const written = calendar?.months;
+    if (!Array.isArray(written) || written.length === 0) return { months: null };
+    return { months: written };
+}
+
+/**
+ * How long one month of a calendar is, or `null` where the calendar is silent.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar.
+ * @param {number} month - The month, numbered from 1.
+ * @returns {number|null} Its length in days, or `null`.
+ */
+export function daysInMonth(calendar, month) {
+    const { months } = calendarStructure(calendar);
+    if (!months || month < 1 || month > months.length) return null;
+    const days = months[month - 1]?.days;
+    return typeof days === "number" ? days : null;
+}
+
+/**
+ * How many days the months add up to.
+ *
+ * The number a calendar's list claims the year is. Whether that is the year the
+ * world keeps is a question about the world, and is asked elsewhere.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number} The sum of their day counts.
+ */
+export function daysInYear(months) {
+    return months.reduce((sum, month) => sum + (Number(month?.days) || 0), 0);
+}
+
+/**
+ * The day of the year each month opens on, in order, numbered from 1.
+ *
+ * The sum read as a sequence rather than as a total. Two lists holding the same
+ * numbers in a different order sum alike and open their months on different
+ * days, which is the error a total cannot see.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number[]} One entry per month: the day of the year it begins on.
+ */
+export function monthStarts(months) {
+    const starts = [];
+    let day = 1;
+    for (const month of months) {
+        starts.push(day);
+        day += Number(month?.days) || 0;
+    }
+    return starts;
+}
+
+/**
+ * Which day of the year a written month and day land on, numbered from 1.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @param {number} month - The month, numbered from 1.
+ * @param {number} day - The day within it, numbered from 1.
+ * @returns {number} The day of the year.
+ */
+export function dayOfYear(months, month, day) {
+    return monthStarts(months)[month - 1] + day - 1;
+}
+
+/**
+ * How far into its cycle a moon is on a given day.
+ *
+ * **Floored, not truncated.** JavaScript's `%` takes the dividend's sign, so a
+ * day seven before the epoch yields `-7` where the phase is 23 — a value that
+ * is right on one side of the epoch and wrong on the other, which is invisible
+ * in any list that does not span it.
+ *
+ * @param {number} dayNumber - The day, on whatever continuous day count the
+ *   caller keeps.
+ * @param {number} epochDay - The day of that same count on which the moon was
+ *   new.
+ * @param {number} cycle - The cycle's length in days.
+ * @returns {number} Days into the cycle, `0` to `cycle - 1`.
+ */
+export function lunarPhase(dayNumber, epochDay, cycle) {
+    return (((dayNumber - epochDay) % cycle) + cycle) % cycle;
+}

package/engine/content-format-check.mjs

@@ -102,6 +102,7 @@ import { currentType } from "./ids.mjs";
 import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -357,8 +358,16 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
 
     // `data:` is closed: every key it carries must be one the type declares.
     const data = isBlock(fm.data) ? fm.data : undefined;
+    // The retired spelling of a key the format states is measured as the key it
+    // will be written as, exactly as a note still on a renamed *type* is
+    // measured against the section it will move to. The rename itself is the
+    // frontmatter lint's finding, and reporting it here as well would count one
+    // note twice in a migration whose counts are the point.
+    const renamedDataKeys = new Set(
+        [...spec.dataKeys].map((key) => RETIRED_FIELD_ALIASES[key]).filter(Boolean),
+    );
     for (const key of Object.keys(data ?? {})) {
-        if (spec.dataKeys.has(key)) continue;
+        if (spec.dataKeys.has(key) || renamedDataKeys.has(key)) continue;
         const guess = nearest(key, spec.dataKeys);
         add(
             "unknown-data-key",

package/engine/draft-notice.mjs

@@ -33,6 +33,14 @@
  * is the floor each surface is built to, because each of them can lose
  * everything around it.
  *
+ * **The label is bold roman and the sentence is italic**, on every surface. The
+ * words around it are the world describing itself; this one sentence is the
+ * text speaking about its own state, and italic is how a reader is told the
+ * voice has changed. It is the one typographic mark the sentence carries:
+ * smaller or lighter type would say the reader may skip it, which is the
+ * opposite of what it is for, and a bold italic beside the mark would be one
+ * emphasis too many.
+ *
  * ## What each surface can rely on
  *
  * - **Foundry** renders a JournalEntry's own HTML inside a sheet, so the floor
@@ -87,7 +95,8 @@ export const BOOK_DRAFT_NOTICE = "book-draft-notice";
  * `body.game .app blockquote` carries a left rule and an indent — so the
  * treatment survives with no stylesheet of this package's own. The mark is a
  * Font Awesome element, which Foundry bundles; `aria-hidden` keeps it out of a
- * screen reader, where the label reads it.
+ * screen reader, where the label reads it. The sentence is an `em`, which every
+ * renderer of HTML sets in italic with no stylesheet to ask.
  *
  * @returns {string} The notice's HTML.
  */
@@ -95,7 +104,7 @@ export function draftNoticeHtml() {
     return (
         `<blockquote class="${DRAFT_NOTICE_CLASS}">` +
         `<p><i class="fa-solid ${DRAFT_NOTICE_ICON}" aria-hidden="true"></i> ` +
-        `<strong>${DRAFT_NOTICE_LABEL}</strong> ${DRAFT_NOTICE}</p>` +
+        `<strong>${DRAFT_NOTICE_LABEL}</strong> <em>${DRAFT_NOTICE}</em></p>` +
         `</blockquote>`
     );
 }
@@ -139,9 +148,30 @@ export function withDraftNotice(fm, html) {
 /**
  * The `#let` the book's notice is drawn by.
  *
- * Emitted with the rest of the book's preamble. The mark is a circle with an
- * exclamation set inside it: two primitives and the face already setting the
- * page, so there is no font to resolve and nothing that can come out as a box.
+ * Emitted with the rest of the book's preamble. The mark is a disc with an
+ * exclamation knocked out of it: two primitives and the face already setting
+ * the page, so there is no font to resolve and nothing that can come out as a
+ * box. It is filled in the accent the book rules its headings with and the
+ * glyph is the colour of the paper, so the mark carries against the running
+ * face rather than reading as a character of it.
+ *
+ * **The mark is a column, not a word.** A two-column grid puts it beside the
+ * sentence rather than inside it, so a notice that takes two lines sets its
+ * second line against the first and never under the disc; the grid centres the
+ * mark's cell on the block, so it holds the middle of one line or two. The rule
+ * is the block's own left stroke and spans whatever height the sentence takes.
+ *
+ * **The sentence sets in the book's body face, size and ink**, because it is
+ * the one thing in the entry a reader has to read before trusting the rest. The
+ * rule and the mark set the block apart; nothing else has to, and type set
+ * smaller or lighter than the prose around it reads as apparatus a reader may
+ * skip. The mark scales with that text, so a consumer setting the book larger
+ * or smaller carries the disc with it.
+ *
+ * **One number sets the mark.** The glyph is a multiple of the disc's radius
+ * rather than a size of its own, so the exclamation keeps its share of the disc
+ * however large the disc is drawn and resizing the mark is one edit. Both are
+ * `em`, so the mark still follows the body text.
  *
  * @returns {string} The Typst definition.
  */
@@ -152,14 +182,16 @@ export function bookDraftNoticePreamble() {
         "  inset: (left: 0.7em, top: 0.35em, bottom: 0.35em),\n" +
         "  stroke: (left: 1.6pt + book-faint))[\n" +
         "  #set par(justify: false, first-line-indent: 0em)\n" +
-        "  #set text(size: 8.6pt, fill: book-faint)\n" +
-        "  #box(baseline: 0.18em, circle(radius: 0.42em, stroke: 0.6pt + book-faint)[\n" +
-        '    #align(center + horizon)[#text(size: 6.4pt, weight: "bold")[!]]\n' +
-        "  ])\n" +
-        "  #h(0.4em)\n" +
-        '  #text(weight: "bold")[#label]\n' +
-        "  #h(0.25em)\n" +
-        "  #body\n" +
+        "  #let radius = 0.69em\n" +
+        "  #grid(columns: (auto, 1fr), column-gutter: 0.5em,\n" +
+        "    align: (center + horizon, horizon),\n" +
+        "    circle(radius: radius, fill: book-accent)[\n" +
+        "      #align(center + horizon)[\n" +
+        '        #text(size: 1.6 * radius, weight: "bold", fill: book-paper)[!]\n' +
+        "      ]\n" +
+        "    ],\n" +
+        '    [#text(weight: "bold")[#label]#h(0.25em)#emph[#body]],\n' +
+        "  )\n" +
         "]"
     );
 }

package/engine/frontmatter-lint.mjs

@@ -455,8 +455,34 @@ function checkDataContainer(note, { type, fields, packs }) {
     /** First segment of each declared name — `charges.value` is authored as `charges`. */
     const declared = new Set(fields.map((f) => f.name.split(".")[0]));
 
+    // The retired spelling of a key this type declares → what to write now.
+    // Built from the type's own declaration, so a renamed `data:` key is
+    // retired exactly where its replacement exists and stays an unrecognised
+    // key on every other type.
+    const renamed = new Map();
+    for (const name of declared) {
+        const retired = RETIRED_FIELD_ALIASES[name];
+        if (retired) renamed.set(retired, name);
+    }
+
     for (const key of Object.keys(entries)) {
         if (declared.has(key)) continue;
+        const current = renamed.get(key);
+        if (current) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
+                // A warning, as every retired spelling is: the note compiles to
+                // the correct document, so failing a build over it would red a
+                // tree that has done nothing wrong yet. The refusal comes once
+                // no tree writes the key, and needs no code — with the alias
+                // gone the spelling is an unrecognised key again, which the
+                // loop below already refuses.
+                severity: "warning",
+                message: retiredAliasMessage(key, current),
+            });
+            continue;
+        }
         const guess = nearest(key, declared);
         findings.push({
             file: note.file,

package/engine/index.mjs

@@ -124,6 +124,15 @@ export * as siteMaps from "./site-maps.mjs";
 /** The closed registry of system ids, and the `none` that stands for no system. */
 export * as systems from "./systems.mjs";
 
+/** The reckonings a package dates by, and the arithmetic that puts them on one line. */
+export * as calendars from "./calendars.mjs";
+
+/** A note's dates: one authored string, one grammar, one record shape. */
+export * as noteDates from "./note-dates.mjs";
+
+/** Calendars as notes: what one may declare, and the definition emitted from it. */
+export * as calendarNotes from "./calendar-notes.mjs";
+
 /** The one normalisation this build makes: prose to a URL-safe token. */
 export * as contentSlug from "./content-slug.mjs";
 

package/engine/infobox.mjs

@@ -115,6 +115,7 @@
 import { getFrontmatter } from "./frontmatter.mjs";
 import { currentType } from "./ids.mjs";
 import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
+import { readAliasedField } from "./retired-fields.mjs";
 import { subtypeRow } from "./document-subtypes.mjs";
 
 /**
@@ -272,7 +273,6 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     banner: Object.freeze({ withheld: "an image, which the box never carries" }),
     overlay: Object.freeze({ withheld: "an image, which the box never carries" }),
 
-    birthday: Object.freeze({ label: "Born" }),
     assocSkill: Object.freeze({ label: "Skill" }),
     assocAffiliation: Object.freeze({ label: "Affiliation" }),
     parentSkill: Object.freeze({ label: "Specialises" }),
@@ -637,7 +637,12 @@ function noteBox(
     for (const field of dataFields(fm?.type, vocabulary) ?? []) {
         const overlay = overlayFor(presentation, fm?.type, field.name);
         if (overlay.withheld) continue;
-        const raw = getFrontmatter(data, field.name, undefined);
+        // The retired spelling underneath, so a note part-way through a rename
+        // still shows its value rather than losing the row with nothing said.
+        // The current name wins, which is the whole of the retirement window's
+        // behaviour and is `readAliasedField`'s answer, not a second one.
+        const own = getFrontmatter(data, field.name, undefined);
+        const raw = hasValue(own) ? own : readAliasedField(fm, field.name, { inData: true });
         if (!hasValue(raw)) continue;
 
         if (overlay.group) {