@heroiclands/package-build 23.12.6 → 23.12.7

package/types/engine/run-words.d.mts

@@ -0,0 +1,86 @@
+/**
+ * A word as it is compared: NFC, lowercase, `’` read as `'`.
+ *
+ * @param {string} word - The word.
+ * @returns {string} Its folded form.
+ */
+export function foldWord(word: string): string;
+/**
+ * The words a language note accepts of its own: its forms, and what its
+ * plural rows, verb pattern and replacing suffixes derive from them.
+ *
+ * @param {Record<string, any>} data - The language note's `data`.
+ * @returns {Set<string>} The words, folded.
+ */
+export function lexiconWords(data: Record<string, any>): Set<string>;
+/**
+ * The words of every name a language note registers under a tongue other than
+ * `translation`.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @returns {Set<string>} The words, folded.
+ */
+export function registeredNameWords(data: Record<string, any> | undefined): Set<string>;
+/**
+ * What a mapped run's words are checked against, for one language.
+ *
+ * @typedef {object} WordBook
+ * @property {string} language - The language's configured name, as `lang=`
+ *   writes it.
+ * @property {(word: string) => boolean} accepts - Whether a folded word is
+ *   one of the language's.
+ */
+/**
+ * Each configured language's word book: one per language whose `note` names a
+ * language note.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, WordBook>} The books by language name.
+ */
+export function wordBooksFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, WordBook>;
+/**
+ * The words of a text its book does not accept, each once, at the offset of
+ * its first character: a compound not accepted whole gives each part that is
+ * not.
+ *
+ * @param {string} text - The text, with no escapes.
+ * @param {WordBook} book - The language's book.
+ * @param {Set<string>} [said] - The folded words already reported in this
+ *   run, which are not reported again; updated.
+ * @returns {Array<{offset: number, word: string}>} The words, in order.
+ */
+export function unknownWords(text: string, book: WordBook, said?: Set<string>): Array<{
+    offset: number;
+    word: string;
+}>;
+/**
+ * The finding for a word of a mapped run that is not a word of its language.
+ *
+ * @param {string} word - The word as written.
+ * @param {string} language - The language as `lang=` names it.
+ * @returns {string} The message.
+ */
+export function unknownWordMessage(word: string, language: string): string;
+/**
+ * What a mapped run's words are checked against, for one language.
+ */
+export type WordBook = {
+    /**
+     * - The language's configured name, as `lang=`
+     * writes it.
+     */
+    language: string;
+    /**
+     * - Whether a folded word is
+     * one of the language's.
+     */
+    accepts: (word: string) => boolean;
+};

package/types/engine/script-font-delivery.d.mts

@@ -0,0 +1,134 @@
+/**
+ * The faces the package's notes set text in with `font=`, read from the
+ * notes themselves: every Markdown file under the content tree that writes
+ * `font=` is scanned for its runs.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @returns {ReadonlySet<string>} The slugs of the faces used.
+ */
+export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts): ReadonlySet<string>;
+/**
+ * The files a target receives, as paths relative to the fonts package root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @returns {{root: string, version: string, files: string[]}|undefined} The
+ *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
+ *   listed format. `undefined` when the consumer ships none.
+ */
+export function scriptFontFiles(config: DeliveryConfig, formats: string[]): {
+    root: string;
+    version: string;
+    files: string[];
+} | undefined;
+/**
+ * The fonts package's stylesheet as a target stages it: each `@font-face`
+ * `src` lists only the files staged beside it, so no browser asks for a
+ * format the target does not carry. A `local(…)` source stays, and a face
+ * left with no source is dropped.
+ *
+ * @param {string} css - The stylesheet as the package publishes it.
+ * @param {ReadonlySet<string>} staged - The staged files, relative to the
+ *   stylesheet: `fonts/SemaronKuriale-Regular.woff2`.
+ * @returns {string} The stylesheet to stage.
+ */
+export function stagedStylesheet(css: string, staged: ReadonlySet<string>): string;
+/**
+ * Copy the delivered files into a directory, keeping their relative layout so
+ * the stylesheet's `url("fonts/…")` resolves from where it lands. The
+ * stylesheet is rewritten by {@link stagedStylesheet} to name only the files
+ * copied with it.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string} dest - The directory to fill; created when there is
+ *   something to put in it.
+ * @param {string[]} formats - The font formats the target uses.
+ * @returns {number} How many files were written; 0 when the consumer ships none.
+ */
+export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[]): number;
+/**
+ * Whether the package ships what its manifest and stylesheet promise: the
+ * stylesheet, the licence and every file the manifest lists.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {{file: string, severity: "error", message: string}[]} One finding
+ *   per missing file, located at the manifest; empty when the consumer ships none.
+ */
+export function checkScriptFonts(config: DeliveryConfig): {
+    file: string;
+    severity: "error";
+    message: string;
+}[];
+/**
+ * The site param naming the stylesheet, relative to the site root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The versioned address, or `undefined` when the
+ *   site ships no fonts.
+ */
+export function siteFontsParam(config: DeliveryConfig): string | undefined;
+/**
+ * The directory under the Hugo static tree that holds this version's fonts.
+ *
+ * @param {string} version - The fonts package's version.
+ * @returns {string} The POSIX path, relative to `build/hugo/static`.
+ */
+export function siteFontsDestination(version: string): string;
+/**
+ * The manifest `styles`, with the fonts' stylesheet named after the base sheet.
+ *
+ * @param {object} options
+ * @param {unknown} options.styles - The `styles` so far, base sheet included.
+ * @param {"system"|"module"} options.artifact - Which artifact is shipped.
+ * @param {boolean} options.delivered - Whether the module carries the fonts.
+ * @returns {unknown} The `styles` to emit.
+ */
+export function withScriptFontStyle({ styles, artifact, delivered: carried }: {
+    styles: unknown;
+    artifact: "system" | "module";
+    delivered: boolean;
+}): unknown;
+/**
+ * The directory of TTFs a book's compiler searches.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The package's `fonts/` directory, or `undefined`
+ *   when the consumer ships no fonts.
+ */
+export function typstScriptFontPath(config: DeliveryConfig): string | undefined;
+/**
+ * Where the files land in the staged Foundry module, relative to its root.
+ *
+ * @type {string}
+ */
+export const STAGED_FONTS_DIR: string;
+/**
+ * Where the files land in the Hugo static tree, relative to `build/hugo/static`,
+ * beneath a directory per version.
+ *
+ * @type {string}
+ */
+export const SITE_FONTS_DIR: string;
+/**
+ * The part of a resolved configuration delivery reads.
+ */
+export type DeliveryConfig = {
+    /**
+     * - The consuming package's root.
+     */
+    rootDir?: string | undefined;
+    /**
+     * - Where its notes are; relative to
+     * `rootDir` unless absolute.
+     */
+    paths?: {
+        content?: string;
+    } | undefined;
+    /**
+     * - Its languages.
+     */
+    languages?: Readonly<Record<string, {
+        tag: string;
+    }>> | undefined;
+};

package/types/engine/script-fonts.d.mts

@@ -0,0 +1,168 @@
+/**
+ * One code point a face draws, as `fonts.json` lists it.
+ *
+ * @typedef {object} FaceCodepoint
+ * @property {string} codepoint - `U+` and the hexadecimal code point.
+ * @property {string} glyph - The glyph's name in the face.
+ * @property {string} kind - What it is: `letter`, `numeral`, `mark` and so on.
+ */
+/**
+ * One entry of `fonts.json`.
+ *
+ * @typedef {object} FontEntry
+ * @property {string} [name] - Its unique key; `family` when absent.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it, `hl-<slug>`.
+ * @property {Record<string, string>} files - Its font files, by format.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {FaceCodepoint[]} [codepoints] - Every code point it draws.
+ */
+/**
+ * A face as a run reads it.
+ *
+ * @typedef {object} Face
+ * @property {string} slug - What `font=` names it by: its class without `hl-`.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {ReadonlySet<number>} draws - Every code point it draws.
+ */
+/**
+ * The installed fonts package, as a consumer sees it.
+ *
+ * @typedef {object} ScriptFonts
+ * @property {string} root - The package's directory.
+ * @property {string} version - Its `package.json` version.
+ * @property {{families: FontEntry[]}|undefined} manifest - Its `fonts.json`,
+ *   `undefined` when the installed version ships none.
+ * @property {Map<string, Face>} faces - Each face by its slug, in manifest
+ *   order; empty without a manifest.
+ */
+/**
+ * The slug `font=` names a face by: its class without the `hl-` prefix.
+ *
+ * @param {FontEntry} entry - A `fonts.json` entry.
+ * @returns {string|undefined} The slug, or `undefined` for an entry with no class.
+ */
+export function faceSlug(entry: FontEntry): string | undefined;
+/**
+ * The fonts package the consumer at `rootDir` installed.
+ *
+ * @param {string} rootDir - The consuming package's root, holding its
+ *   `package.json`.
+ * @returns {ScriptFonts|undefined} The package, or `undefined` when the
+ *   consumer has not installed it.
+ * @throws {Error} When the installed `fonts.json` is not readable JSON, or
+ *   holds no `families` list.
+ */
+export function resolveScriptFonts(rootDir: string): ScriptFonts | undefined;
+/** The npm name of the fonts package. */
+export const FONTS_PACKAGE: "@heroiclands/fonts";
+/** The manifest the fonts package publishes at its root. */
+export const FONTS_MANIFEST: "fonts.json";
+/**
+ * One code point a face draws, as `fonts.json` lists it.
+ */
+export type FaceCodepoint = {
+    /**
+     * - `U+` and the hexadecimal code point.
+     */
+    codepoint: string;
+    /**
+     * - The glyph's name in the face.
+     */
+    glyph: string;
+    /**
+     * - What it is: `letter`, `numeral`, `mark` and so on.
+     */
+    kind: string;
+};
+/**
+ * One entry of `fonts.json`.
+ */
+export type FontEntry = {
+    /**
+     * - Its unique key; `family` when absent.
+     */
+    name?: string | undefined;
+    /**
+     * - The CSS and Typst font family.
+     */
+    family: string;
+    /**
+     * - The class that sets text in it, `hl-<slug>`.
+     */
+    class: string;
+    /**
+     * - Its font files, by format.
+     */
+    files: Record<string, string>;
+    /**
+     * - `ltr` or `rtl`.
+     */
+    direction: string;
+    /**
+     * - OpenType features it turns on.
+     */
+    features: string[];
+    /**
+     * - Every code point it draws.
+     */
+    codepoints?: FaceCodepoint[] | undefined;
+};
+/**
+ * A face as a run reads it.
+ */
+export type Face = {
+    /**
+     * - What `font=` names it by: its class without `hl-`.
+     */
+    slug: string;
+    /**
+     * - The CSS and Typst font family.
+     */
+    family: string;
+    /**
+     * - The class that sets text in it.
+     */
+    class: string;
+    /**
+     * - `ltr` or `rtl`.
+     */
+    direction: string;
+    /**
+     * - OpenType features it turns on.
+     */
+    features: string[];
+    /**
+     * - Every code point it draws.
+     */
+    draws: ReadonlySet<number>;
+};
+/**
+ * The installed fonts package, as a consumer sees it.
+ */
+export type ScriptFonts = {
+    /**
+     * - The package's directory.
+     */
+    root: string;
+    /**
+     * - Its `package.json` version.
+     */
+    version: string;
+    /**
+     * - Its `fonts.json`,
+     * `undefined` when the installed version ships none.
+     */
+    manifest: {
+        families: FontEntry[];
+    } | undefined;
+    /**
+     * - Each face by its slug, in manifest
+     * order; empty without a manifest.
+     */
+    faces: Map<string, Face>;
+};

package/types/engine/site-build.d.mts

@@ -230,7 +230,7 @@ export function pageDestination(page: {
     slug: string;
 }): string;
 /** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, }: {
+export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
     index: any;
     foreign: any;
     universe: any;
@@ -243,6 +243,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     figuresByAddress?: Map<any, any> | undefined;
     events: any;
     drawings?: Map<any, any> | undefined;
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): {
     page: any;
     body: string;

package/types/engine/site-root.d.mts

@@ -18,15 +18,23 @@
  */
 export function noindexHeaders(): string[];
 /**
- * The `_headers` file's contents: the `noindex` rules, and nothing else.
+ * The `_headers` file's contents: the `noindex` rules, and the script fonts'
+ * cache rule when the site carries them.
  *
  * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
  * lifetime on it would hold a stale copy at the most-linked address after a
- * deploy; Pages' own defaults for a page apply.
+ * deploy; Pages' own defaults for a page apply. The fonts sit under a path
+ * that names their version, so a year's lifetime never serves a stale file.
  *
+ * @param {object} [options] - Options.
+ * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers(): string;
+export function headers({ pkg, fonts }?: {
+    pkg?: string | undefined;
+    fonts?: boolean | undefined;
+}): string;
 export function indexSite(where: {
     site: string;
     output: string;

package/types/engine/text-maps.d.mts

@@ -0,0 +1,175 @@
+/**
+ * Read one authored row.
+ *
+ * @param {unknown} row - The row as YAML gave it.
+ * @returns {{row: MapRow}|{problem: string, key?: string}} The row, or what is
+ *   wrong with it and the key the fault sits at.
+ */
+export function readMapRow(row: unknown): {
+    row: MapRow;
+} | {
+    problem: string;
+    key?: string;
+};
+/**
+ * Compile a `data.map` value, keeping its well-formed rows.
+ *
+ * @param {unknown} value - The note's `data.map`.
+ * @returns {TextMap|undefined} The map, or `undefined` when it has no valid name.
+ */
+export function compileMap(value: unknown): TextMap | undefined;
+/**
+ * A native form found for a word in lowercase, given the word's capital as the
+ * rows write it: the rows map the word's first sound as written and in
+ * lowercase, and where the native form begins with the lowercase result, that
+ * beginning becomes the capital one.
+ *
+ * @param {TextMap} map - The map.
+ * @param {string|undefined} font - The face.
+ * @param {string} word - The word as written.
+ * @param {string} native - The native form of its lowercase.
+ * @returns {string|undefined} The native form, capitalised; `undefined` where
+ *   it does not begin as the rows begin the word, so the rows cannot say how.
+ */
+export function capitalNative(map: TextMap, font: string | undefined, word: string, native: string): string | undefined;
+/**
+ * Apply a map to text.
+ *
+ * @param {TextMap|undefined} map - The map; without one the text is returned
+ *   as it is.
+ * @param {string} text - The text, with no escapes in it.
+ * @param {MapOptions} [options] - The face, and the native forms of words.
+ * @returns {{text: string, pieces: Array<{at: number, from: string, to: string, row: boolean, native?: boolean}>}}
+ *   The rewritten text, and each piece of it with the UTF-16 offset in `text`
+ *   it came from: a matched row's `from` and what it wrote, a word and its
+ *   native form (`native: true`), or one character that passed through. A
+ *   capitalised word whose native form the rows cannot capitalise is written
+ *   as stated and carries `uncapitalised`, the lowercase form it was found by.
+ */
+export function applyMap(map: TextMap | undefined, text: string, { font, native }?: MapOptions): {
+    text: string;
+    pieces: Array<{
+        at: number;
+        from: string;
+        to: string;
+        row: boolean;
+        native?: boolean;
+    }>;
+};
+/**
+ * Every map the index records declare, by name. The first note to declare a
+ * name keeps it; the duplicate is the lint's to report.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, TextMap>} The maps.
+ */
+export function mapsFromRecords(records: Iterable<Record<string, any>> | undefined): Map<string, TextMap>;
+/**
+ * One row per well-formed map row, for the `maps` relation: the shared rows
+ * with no `font`, then each listed face's own rows with its slug.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @param {(record: Record<string, any>) => string|null} ownerOf - A record's
+ *   page Address.
+ * @returns {Array<Record<string, string|number|null>>} The rows, in record
+ *   then authored order; `row` is the row's 1-based place in its list.
+ */
+export function mapRows(records: Iterable<Record<string, any>>, ownerOf: (record: Record<string, any>) => string | null): Array<Record<string, string | number | null>>;
+/**
+ * Check a note's `data.map`: its name, that no other note declares it, each
+ * row written as a list, a `before` condition on a map with no `vowels`, an
+ * empty `fonts`, and a generic family in it. The data-key check owns every
+ * key, its kind and the words a condition takes; whether a listed face is
+ * installed, and draws what the map writes, is
+ * {@link module:engine/map-lexicon.checkMapFonts}'s.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index.
+ * @returns {object[]} The findings, each at its key.
+ */
+export function checkMapField(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, { index }?: {
+    index?: {
+        notes?: Iterable<object>;
+    };
+}): object[];
+/** What a map's `name` may be. */
+export const MAP_NAME: RegExp;
+/** Each condition a row may carry, and the values it takes. */
+export const MAP_CONDITIONS: Readonly<{
+    before: readonly string[];
+    at: readonly string[];
+}>;
+/** The generic families, which a map's `fonts` may not list. */
+export const GENERIC_FAMILIES: readonly string[];
+/** Every column of the `maps` relation, in order. */
+export const MAP_COLUMNS: readonly string[];
+/**
+ * One row, read.
+ */
+export type MapRow = {
+    /**
+     * - The characters it matches.
+     */
+    from: string;
+    /**
+     * - What it writes in their place.
+     */
+    to: string;
+    /**
+     * - What must follow the match.
+     */
+    before?: "vowel" | "consonant" | undefined;
+    /**
+     * - Where the match must sit.
+     */
+    at?: "end" | "start" | undefined;
+};
+/**
+ * A map ready to apply.
+ */
+export type TextMap = {
+    /**
+     * - Its name.
+     */
+    name: string;
+    /**
+     * - The characters `before: vowel` reads.
+     */
+    vowels: ReadonlySet<string>;
+    /**
+     * - Its well-formed shared rows, in authored order.
+     */
+    rows: readonly MapRow[];
+    /**
+     * - Its shared rows
+     * by the first character of `from`, longest first, conditioned before plain.
+     */
+    byFirst: ReadonlyMap<string, readonly MapRow[]>;
+    /**
+     * -
+     * Each listed face by slug, in listed order, with its own rows.
+     */
+    fonts: ReadonlyMap<string, {
+        rows: readonly MapRow[];
+        byFirst: ReadonlyMap<string, readonly MapRow[]>;
+    }>;
+};
+/**
+ * How a text is mapped beyond the rows.
+ */
+export type MapOptions = {
+    /**
+     * - The face the text is set in, whose own rows are
+     * tried first.
+     */
+    font?: string | undefined;
+    /**
+     * - A word's native
+     * form, for the word exactly as given, or `undefined` where it states none.
+     */
+    native?: ((word: string) => string | undefined) | undefined;
+};

package/types/engine/verb-pattern.d.mts

@@ -0,0 +1,65 @@
+/**
+ * A stated verb pattern, as its readers use it.
+ *
+ * @typedef {object} VerbPattern
+ * @property {boolean} invariant - Whether verbs keep the citation form for
+ *   every person.
+ * @property {string|undefined} replaces - The letters each ending takes the
+ *   place of, where the pattern states them.
+ * @property {Array<{name: string, label: string, ending: string}>} endings -
+ *   The six endings in presentation order; empty for an invariant pattern.
+ */
+/**
+ * Read a language's verb pattern.
+ *
+ * @param {unknown} verbs - The language's `data.grammar.verbs`, as authored or
+ *   as a SQL row carries it (absent fields `null`).
+ * @returns {VerbPattern|undefined} The pattern, or `undefined` where none is
+ *   stated in full.
+ */
+export function verbPattern(verbs: unknown): VerbPattern | undefined;
+/**
+ * A stem with its closing letters swapped for an ending, or with the ending
+ * added where the stem does not close on them.
+ *
+ * @param {string} stem - The stem.
+ * @param {string} ending - The ending.
+ * @param {string|undefined} letters - The closing letters the ending takes
+ *   the place of; none adds the ending.
+ * @returns {string} The form.
+ */
+export function replaceClosing(stem: string, ending: string, letters: string | undefined): string;
+/**
+ * The present form of a verb for one ending.
+ *
+ * @param {string} citation - The citation form.
+ * @param {string} ending - The person's ending; empty leaves the citation
+ *   form, less any closing `replaces`.
+ * @param {string} [replaces] - The pattern's `replaces`.
+ * @returns {string} The form.
+ */
+export function verbForm(citation: string, ending: string, replaces?: string): string;
+/**
+ * A stated verb pattern, as its readers use it.
+ */
+export type VerbPattern = {
+    /**
+     * - Whether verbs keep the citation form for
+     * every person.
+     */
+    invariant: boolean;
+    /**
+     * - The letters each ending takes the
+     * place of, where the pattern states them.
+     */
+    replaces: string | undefined;
+    /**
+     * -
+     * The six endings in presentation order; empty for an invariant pattern.
+     */
+    endings: Array<{
+        name: string;
+        label: string;
+        ending: string;
+    }>;
+};

package/types/engine/word-pattern.d.mts

@@ -0,0 +1,13 @@
+/**
+ * **What a word is in running text.** A word is a maximal run of letters,
+ * combining marks and digits, and an apostrophe (`'` or `’`), a hyphen or an
+ * en dash joins two such runs into one word: `k'aralzon`, `Arzen-Thalor`.
+ * Anything else, whitespace and punctuation included, sits between words.
+ *
+ * The name catalog reads a label's last word by it, and a mapped run reads
+ * each word it looks up in a lexicon by it.
+ *
+ * @module
+ */
+/** One word; global, so `matchAll` walks every word of a text. */
+export const WORD: RegExp;