@heroiclands/package-build 22.6.0 → 22.8.0

package/engine/draft-notice.mjs

@@ -0,0 +1,207 @@
+/*
+ * 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
+ */
+
+/**
+ * **What a draft note says about itself**, in one sentence, on every surface it
+ * reaches.
+ *
+ * A note tagged `draft` compiles, validates, publishes and resolves like any
+ * other. What separates it from a finished note is a judgement only its author
+ * holds — the content is not settled — and a reader who is not told assumes the
+ * opposite. So each surface states it where the reader cannot miss it: at the
+ * head of the entry, above the infobox and above the prose.
+ *
+ * **The words are the same everywhere and are stated once here.** A reader who
+ * meets the same note on a page, in a compendium and in the book should meet
+ * one statement, not three that agree approximately. {@link DRAFT_NOTICE} is
+ * that statement; every renderer below composes its own markup around it and
+ * changes none of it.
+ *
+ * **A label alone will not do.** "Draft" names the writing, so it reads as
+ * rough prose; what has to land is that the facts may change. The label and the
+ * sentence are one unit, and the sentence carries the meaning by itself — which
+ * 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
+ *   is what a journal page carries with no module and no system stylesheet
+ *   loaded. Foundry draws a left rule on a `blockquote` in any application
+ *   window and bundles Font Awesome, so the rule and the mark are the host's
+ *   and nothing here ships CSS. The class is a hook for a package that wants
+ *   one, never a requirement.
+ * - **The book** sets Typst, where a glyph missing from the face is silent and
+ *   a consumer declaring no icon family is the normal case — see {@link
+ *   module:engine/content-icons}. So the mark is **drawn**, from two
+ *   primitives, and cannot become a box.
+ * - **An Actor's prose** lands in a system's own sheet, in a field the system
+ *   styles. It gets the same HTML the journal does; what it can rely on is the
+ *   sentence.
+ *
+ * @module
+ */
+
+import { isDraftNote } from "./note-vocabulary.mjs";
+
+/** The word that opens the notice, and the only part a reader reads as a label. */
+export const DRAFT_NOTICE_LABEL = "Draft.";
+
+/**
+ * The sentence, which states the fact and stops.
+ *
+ * It says the content may change rather than that the writing is rough,
+ * because that is the difference between a reader who treats the entry as
+ * provisional and one who builds on it. It gives no instruction: a notice that
+ * reaches one page in seven wears better as a statement than as a direction,
+ * and the fact carries the consequence for anyone who can act on it.
+ *
+ * @type {string}
+ */
+export const DRAFT_NOTICE =
+    "This entry is unfinished. What it states may change, and nothing in it is settled.";
+
+/** The Font Awesome mark: a notice, not a hazard. */
+export const DRAFT_NOTICE_ICON = "fa-circle-exclamation";
+
+/** The class a package may style the HTML notice against. */
+export const DRAFT_NOTICE_CLASS = "sohl-draft-notice";
+
+/** The Typst function the book's notice calls. */
+export const BOOK_DRAFT_NOTICE = "book-draft-notice";
+
+/**
+ * The notice as HTML, for a JournalEntry page and for an Actor's prose field.
+ *
+ * A `blockquote` because that is the element Foundry already sets apart —
+ * `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. The sentence is an `em`, which every
+ * renderer of HTML sets in italic with no stylesheet to ask.
+ *
+ * @returns {string} The notice's HTML.
+ */
+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> <em>${DRAFT_NOTICE}</em></p>` +
+        `</blockquote>`
+    );
+}
+
+/**
+ * The notice a note has earned, or nothing.
+ *
+ * The one place the tag is asked about on a compiled document, so the packs and
+ * the book cannot answer it differently. It reads {@link
+ * module:engine/note-vocabulary.isDraftNote}, which is the single reader of the
+ * tag itself.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {string} The notice's HTML, or `""` for a note that is settled.
+ */
+export function draftNoticeFor(fm) {
+    return isDraftNote(fm) ? draftNoticeHtml() : "";
+}
+
+/**
+ * Prose led by the notice, where the note is a draft.
+ *
+ * **Which field a system leads is the system's decision, and it makes it
+ * once.** A referee at the table opens an actor sheet rather than the
+ * documentation beside it, so the prose a sheet draws says it too — on one
+ * field, since a document showing the same statement twice teaches a reader to
+ * skip it. Both systems put it on the dossier: SoHL's `dossier` and HM3's
+ * `biography` read the same authored section, so the notice lands on the same
+ * prose whichever system compiles it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} html - The rendered prose.
+ * @returns {string} The prose, led by the notice where one is due.
+ */
+export function withDraftNotice(fm, html) {
+    const notice = draftNoticeFor(fm);
+    if (!notice) return html;
+    return html ? `${notice}\n${html}` : notice;
+}
+
+/**
+ * The `#let` the book's notice is drawn by.
+ *
+ * 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.
+ */
+export function bookDraftNoticePreamble() {
+    return (
+        `#let ${BOOK_DRAFT_NOTICE}(label, body) = block(\n` +
+        "  width: 100%, above: 0.55em, below: 0.75em, breakable: false,\n" +
+        "  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" +
+        "  #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" +
+        "]"
+    );
+}
+
+/**
+ * The notice as Typst, for a leaf of the book.
+ *
+ * @returns {string} The call, ready to sit between the entry's plate and its
+ *   infobox panel.
+ */
+export function draftNoticeTypst() {
+    return `#${BOOK_DRAFT_NOTICE}[${DRAFT_NOTICE_LABEL}][${DRAFT_NOTICE}]`;
+}

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

@@ -87,6 +87,9 @@ export * as noteVocabulary from "./note-vocabulary.mjs";
 /** The three states of a note — stub, draft, full — and the empty body they rest on. */
 export * as noteState from "./note-state.mjs";
 
+/** What a draft note says about itself, in one sentence, on every surface. */
+export * as draftNotice from "./draft-notice.mjs";
+
 /** Whether every empty body is a stub on purpose, and how finished a tree is. */
 export * as stubLint from "./stub-lint.mjs";
 
@@ -121,6 +124,12 @@ 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";
+
 /** 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) {

package/engine/item-docs.mjs

@@ -64,10 +64,10 @@ export { itemTypes };
  * Every content type whose **prose compiles into a JournalEntry of its own**,
  * addressed by the virtual `doc<type>` qualifier.
  *
- * Every item type, plus `macro` — a macro note's body documents the script the
- * note also compiles into a Macro, which is the same shape as an item
- * and its description: one note, two documents, the prose living in the
- * journals pack.
+ * Every item type, every actor type, every map type, plus `macro` — a macro
+ * note's body documents the script the note also compiles into a Macro, which
+ * is the same shape as an item and its description: one note, two documents,
+ * the prose living in the journals pack.
  *
  * **One set, read by the compiler and the emitter alike.** The journals pass
  * decides what to compile from it, and the link manifest decides what to
@@ -76,8 +76,9 @@ export { itemTypes };
  * consumer can address. It is composed exactly once, in `defineConfig`, and
  * read from there — never recomposed at a call site.
  *
- * `doc` notes and actors are absent: each is a single document, so it has no
- * separate documentation to address.
+ * `doc` notes are absent, for the reason that applies to them alone: a `doc`
+ * note's single document *is* its prose, so there is no second document for a
+ * `doc<type>` address to name.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -93,8 +94,8 @@ export function docEntryTypes() {
  * its own.
  *
  * @param {string} type - The note's `type` frontmatter.
- * @returns {boolean} True for an item type, for `macro` and for a map type;
- *   false for `doc` and for actors.
+ * @returns {boolean} True for an item type, an actor type, a map type and
+ *   `macro`; false for `doc`.
  */
 export function hasDocEntry(type) {
     // Through {@link currentType}, because the set is derived from the item

package/engine/journals.mjs

@@ -18,14 +18,17 @@
  * The content root (`contentBase`) is walked recursively; any `.md` file
  * whose frontmatter declares either `type: doc` or a
  * **doc-carrying type** ({@link sohl.utils.packs.docEntryTypes} — every item
- * type, plus `macro`) is compiled into one JournalEntry document. Each note's
+ * type, every actor type, every map type, plus `macro`) is compiled into one
+ * JournalEntry document. Each note's
  * body is split on top-level H1 headings; the optional content before the
  * first H1 becomes a lead page, and each subsequent H1 starts a new page named
  * after its heading text. All page bodies are rendered to HTML.
  *
  * A doc-carrying note compiles into that document's **documentation** — the
- * same prose and pages, filed in the same folder as the document itself, which
- * keeps only a pointer to it. See `item-docs.mjs` for why, and for the ids the
+ * same prose and pages, filed in the same folder as the document itself. An
+ * item keeps only a pointer to it; an actor keeps its own inline prose as
+ * well, because the indirection an item pays for is bought by embedding one
+ * item across hundreds of beings and an actor is singular. See `item-docs.mjs` for why, and for the ids the
  * two passes agree on. A macro note's `{#script}` page is compiled here like
  * any other: the macro pass reads the same page independently, and withholds
  * nothing from the journal.
@@ -56,6 +59,7 @@ import { noteInfoboxes } from "./infobox-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 import { journalHasContent } from "./note-state.mjs";
+import { draftNoticeFor } from "./draft-notice.mjs";
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -287,6 +291,11 @@ export function buildPages(rawPages, entryId, noteName) {
  *   that reads. It is **not** a page of its own — a page is what a UUID
  *   addresses, and a summary a reader has to navigate to is a summary they do
  *   not see.
+ * @param {string} [params.notice] - A statement about the entry rather than
+ *   about its subject, already rendered to HTML — see {@link
+ *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   because a reader deciding whether to rely on the entry has to be told
+ *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -298,12 +307,16 @@ export function buildJournalEntry({
     flags,
     stats = defaultStats(),
     infobox = "",
+    notice = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name);
     if (infobox.trim() && pages.length) {
         pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
     }
+    if (notice.trim() && pages.length) {
+        pages[0].text.content = `${notice}\n${pages[0].text.content}`;
+    }
     return {
         name,
         pages,
@@ -407,7 +420,7 @@ export class Journals extends BasePackCompiler {
      * Compile one note into a JournalEntry.
      *
      * A `doc` note becomes the entry its frontmatter describes. A
-     * **doc-carrying note** — every item note, and every macro note — becomes
+     * **doc-carrying note** — every item, actor, map and macro note — becomes
      * that document's documentation instead: the same prose, the same pages,
      * in the same folder, under an id derived from the note's, so the pointer
      * the items pass wrote resolves to it (see
@@ -458,6 +471,12 @@ export class Journals extends BasePackCompiler {
             name,
             markdown,
             infobox: infoboxesToHtml(boxes, { link: linkToUuid }),
+            // Whether the entry is settled, asked of the tag through the one
+            // reader of it. This sits here rather than in `buildJournalEntry`
+            // for the reason `skipNote` runs first: a note with no prose
+            // compiles into nothing, and a notice composed before that test
+            // would be content enough to give it an entry.
+            notice: draftNoticeFor(fm),
             // A doc-carrying note's lead page is the document itself, not an
             // "Introduction" — see {@link splitPages}.
             leadName: ownsDoc ? name : undefined,