@heroiclands/package-build 23.13.0 → 24.0.1

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

@@ -0,0 +1,127 @@
+/** A string with its first letter capitalised and its separators read as spaces. */
+export function humanize(value: any): string;
+/** The text of HTML: tags dropped, character references decoded, whitespace collapsed. */
+export function plainText(html: any): string;
+/** Whether a page states it is a draft. */
+export function isDraft(params?: {}): any;
+/**
+ * The subject tags of a page: every tag but the one that marks a draft.
+ *
+ * @param {object} params - The page's frontmatter.
+ * @returns {string[]} The tags.
+ */
+export function subjectTags(params?: object): string[];
+/**
+ * The headings of rendered HTML that a contents list names.
+ *
+ * @param {string} html - A page's body.
+ * @returns {Array<{level: number, id: string, text: string}>} The `h2` and `h3`
+ *   headings in document order, the footnote list's own heading left out; `id`
+ *   is empty for a heading that has none.
+ */
+export function pageHeadings(html: string): Array<{
+    level: number;
+    id: string;
+    text: string;
+}>;
+/**
+ * A contents list for a page's headings.
+ *
+ * @param {Array<{level: number, id: string, text: string}>} headings - From {@link pageHeadings}.
+ * @returns {string} A `nav` of nested lists, or `""` when there are no headings. A
+ *   heading with no id is listed without a link.
+ */
+export function tableOfContents(headings: Array<{
+    level: number;
+    id: string;
+    text: string;
+}>): string;
+/**
+ * The page before and the page after this one.
+ *
+ * `siblings` is in the order a reader walks. Where the section holds more than
+ * one catalog, the siblings are narrowed to the pages sharing this page's
+ * catalog key: `type`, or for a `doc` its `subType` or `category`. A section
+ * holding one catalog is left alone, as is a page declaring none.
+ *
+ * @param {object} page - The page.
+ * @param {boolean} [narrow] - Whether to narrow to the page's catalog.
+ * @returns {{prev?: object, next?: object}} The neighbours; `prev` is the entry
+ *   after this one in `siblings`, and `next` the entry before it.
+ */
+export function neighbours(page: object, narrow?: boolean): {
+    prev?: object;
+    next?: object;
+};
+/**
+ * @typedef {object} Finding
+ * @property {"warning"|"error"} severity
+ * @property {string} message
+ * @property {string} [page] - The address of the page the finding is about.
+ * @property {string} [file] - The file the page was written in.
+ * @property {Array<string|number>} [param] - The path of the site parameter
+ *   the finding is about, such as `["notfound", "links", 1, "url"]`.
+ */
+/**
+ * Create the layouts for one site.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.site - The site; see the module description.
+ * @param {string} [options.dir] - The directory holding `layouts/` and
+ *   `partials/`. The shipped theme by default.
+ * @param {{banners: object, kinds: object}} [options.bannerData] - The banner
+ *   inventory and kind mapping. The shipped ones by default.
+ * @param {(finding: Finding) => void} [options.report] - Receives each finding
+ *   as it is made. Every finding is also kept in `findings`.
+ * @returns {{
+ *   render: (page: object) => string,
+ *   layoutFor: (page: object) => string,
+ *   partial: (name: string, context?: object) => string,
+ *   findings: Finding[],
+ * }} The theme.
+ */
+export function createSiteTheme({ site, dir, bannerData, report }: {
+    site: object;
+    dir?: string | undefined;
+    bannerData?: {
+        banners: object;
+        kinds: object;
+    } | undefined;
+    report?: ((finding: Finding) => void) | undefined;
+}): {
+    render: (page: object) => string;
+    layoutFor: (page: object) => string;
+    partial: (name: string, context?: object) => string;
+    findings: Finding[];
+};
+/**
+ * The files the layouts link that the theme generates.
+ *
+ * @returns {Array<{path: string, content: string}>} Each file's path under the
+ *   site and its contents.
+ */
+export function siteThemeAssets(): Array<{
+    path: string;
+    content: string;
+}>;
+/** The directory the layouts and partials are read from. */
+export const SITE_THEME_DIR: string;
+/** The layouts a page can be drawn by. */
+export const LAYOUTS: readonly string[];
+export type Finding = {
+    severity: "warning" | "error";
+    message: string;
+    /**
+     * - The address of the page the finding is about.
+     */
+    page?: string | undefined;
+    /**
+     * - The file the page was written in.
+     */
+    file?: string | undefined;
+    /**
+     * - The path of the site parameter
+     * the finding is about, such as `["notfound", "links", 1, "url"]`.
+     */
+    param?: (string | number)[] | undefined;
+};

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

@@ -39,14 +39,16 @@ export function capitalNative(map: TextMap, font: string | undefined, word: stri
  *   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}>}}
+ * @returns {{text: string, pieces: Array<{at: number, from: string, to: string, row: boolean, native?: boolean, unwritten?: object}>}}
  *   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.
+ *   Under a logographic map, a word with no writing is written as typed and
+ *   carries `unwritten`, why it has none.
  */
-export function applyMap(map: TextMap | undefined, text: string, { font, native }?: MapOptions): {
+export function applyMap(map: TextMap | undefined, text: string, { font, native, writing }?: MapOptions): {
     text: string;
     pieces: Array<{
         at: number;
@@ -54,6 +56,7 @@ export function applyMap(map: TextMap | undefined, text: string, { font, native
         to: string;
         row: boolean;
         native?: boolean;
+        unwritten?: object;
     }>;
 };
 /**
@@ -78,7 +81,8 @@ export function mapRows(records: Iterable<Record<string, any>>, ownerOf: (record
 /**
  * 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
+ * empty `fonts`, a generic family in it, and a row of a logographic map that
+ * matches a letter. 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.
@@ -136,6 +140,11 @@ export type TextMap = {
      * - Its name.
      */
     name: string;
+    /**
+     * - Whether it writes words from the lexicon
+     * alone, its rows only between them.
+     */
+    logographic: boolean;
     /**
      * - The characters `before: vowel` reads.
      */
@@ -172,4 +181,9 @@ export type MapOptions = {
      * form, for the word exactly as given, or `undefined` where it states none.
      */
     native?: ((word: string) => string | undefined) | undefined;
+    /**
+     * -
+     * A word's writing under a logographic map; without one, no word has one.
+     */
+    writing?: ((word: string) => import("./logographic.mjs").Writing) | undefined;
 };

package/types/engine/typographer.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Set typographic punctuation in every inline run.
+ *
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function typographerPlugin(md: typeof import("markdown-it")): void;
+/**
+ * The token a typographic character is written as. It is a token of its own,
+ * not text, so a reader of a heading's text can tell where it stands.
+ */
+export const TYPOGRAPHIC: "typographic";

package/types/engine/verse-metre.d.mts

@@ -0,0 +1,131 @@
+/**
+ * The syllables of a word, each as the vowel group that makes it.
+ *
+ * @param {string} word - The word.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {string[]} The nuclei, in order; none for a word with no vowel.
+ */
+export function nucleiOf(word: string, pairs: Iterable<string>): string[];
+/**
+ * The index of the stressed syllable of a word.
+ *
+ * @param {string} word - The word.
+ * @param {{two: string, longer: string, mark?: string}} rule - The language's
+ *   `data.sounds.stress`.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {number} The 0-based syllable; 0 for a word of one syllable or none.
+ */
+export function stressIndex(word: string, rule: {
+    two: string;
+    longer: string;
+    mark?: string;
+}, pairs: Iterable<string>): number;
+/**
+ * Each configured language's metre book: one per language whose `note` names a
+ * language note stating a complete `data.sounds.stress`.
+ *
+ * @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, MetreBook>} The books by language name.
+ */
+export function metreBooksFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, MetreBook>;
+/**
+ * Every metre the index's `doc` notes declare, by name. The first note to
+ * declare a name keeps it.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, import("./metre-declaration.mjs").Metre>} The metres.
+ */
+export function metresFromRecords(records: Iterable<Record<string, any>> | undefined): Map<string, import("./metre-declaration.mjs").Metre>;
+/**
+ * The beats a line of verse can have.
+ *
+ * @param {string} text - The line.
+ * @param {MetreBook} book - The line's language's book.
+ * @returns {{min: number, max: number}} The beats without the second beats a
+ *   long word may take, and with all of them.
+ */
+export function lineBeats(text: string, book: MetreBook): {
+    min: number;
+    max: number;
+};
+/**
+ * The warning for a line that cannot have its metre's beats.
+ *
+ * @param {{min: number, max: number}} beats - The line's beats.
+ * @param {import("./metre-declaration.mjs").Metre} metre - The fence's metre.
+ * @returns {string} The message.
+ */
+export function metreMessage({ min, max }: {
+    min: number;
+    max: number;
+}, metre: import("./metre-declaration.mjs").Metre): string;
+/**
+ * Check the verse fences that state `scan=`.
+ *
+ * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
+ *   The fences, from {@link module:engine/content-verse.scanVerse}.
+ * @param {string[]} lines - The source's lines.
+ * @param {{metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, columnsClass: string, columnKeys: readonly string[], attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
+ *   The metres and books, and how the fence says its columns and where its
+ *   keys sit.
+ * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
+ *   positions.
+ */
+export function metreFindings(blocks: ReadonlyArray<{
+    start: number;
+    end: number;
+    indent: string;
+    attributes: Record<string, string>;
+    classes: string[];
+}>, lines: string[], ctx: {
+    metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>;
+    metreBooks?: ReadonlyMap<string, MetreBook>;
+    lexicons?: ReadonlyMap<string, unknown>;
+    columnsClass: string;
+    columnKeys: readonly string[];
+    attributeColumns: (line: string, key: string) => {
+        key: number;
+        value: number;
+    };
+}): {
+    errors: object[];
+    warnings: object[];
+};
+/** The bases whose one-syllable words carry a beat. */
+export const BEAT_BASES: readonly string[];
+/**
+ * What a language's lines are counted by.
+ */
+export type MetreBook = {
+    /**
+     * - The language's configured name.
+     */
+    language: string;
+    /**
+     * - Its stress rule.
+     */
+    rule: {
+        two: string;
+        longer: string;
+        mark?: string;
+    };
+    /**
+     * - Its vowel pairs.
+     */
+    pairs: ReadonlySet<string>;
+    /**
+     * - Each lexicon
+     * form, and each form its rules derive, folded, with the class bases of its
+     * entries.
+     */
+    classes: ReadonlyMap<string, ReadonlySet<string>>;
+};
+export { METRE_KINDS, METRE_NAME, checkMetresField } from "./metre-declaration.mjs";

package/types/engine/wikilink-syntax.d.mts

@@ -36,12 +36,8 @@ export function parseWikilink(rawInner: string, literal?: string): ParsedWikilin
  * `[[x|]]` is labelled and `[[x]]` is not, and only the first addresses
  * anything.
  *
- * Stated here because the two resolvers had already drawn the line in two
- * places and drawn it differently: the packs tested falsiness and were right,
- * the web tested `??` — which falls through on `null` only — and emitted
- * `[](/url/)`, a link with no clickable text, through every build. That
- * is the same drift this module exists to prevent, in the case its own
- * {@link ParsedWikilink} docstring calls out. One reading, one place.
+ * Read with `??`, which falls through on `null` only, an empty label would
+ * emit `[](/url/)`: a link with no clickable text. One reading, one place.
  *
  * @param {{display: string|null}} parsed - A parsed wikilink, or anything
  *   carrying its `display`.
@@ -53,7 +49,7 @@ export function authoredLabel({ display }: {
 /**
  * What an author writing an unlabelled link is told, in one place.
  *
- * Shared by the link checker, the pack compilers and the web resolver, because
+ * Shared by the link checker and the resolver, on every target, because
  * an author meets whichever runs first and they should read the same. It names
  * the form to write rather than a value to correct: there is no value that
  * makes an unlabelled link resolve.
@@ -99,7 +95,7 @@ export function isEventAnchor(hit: {
  *
  * An address naming no note is a typo or an omission: the intent of a
  * placeholder for a note nobody has written yet is spelled as a `draft`-tagged
- * note that exists, resolves and renders marked. Both want fixing, and all three builds say so.
+ * note that exists, resolves and renders marked. Both want fixing, and every build says so.
  *
  * @param {string} target - The address as authored, named in the message.
  * @returns {string} The message, unpunctuated at the end as a finding is.
@@ -143,9 +139,9 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
 /**
  * The message for one link finding, whichever resolver found it.
  *
- * The single table the checker, the pack compilers and the web resolver all
- * report through, so one authored link cannot get three different explanations
- * of the same mistake depending on which build the author ran first. Callers
+ * The single table the checker and the resolver report through, on every
+ * target, so one authored link cannot get different explanations of the same
+ * mistake depending on which build the author ran first. Callers
  * add their own context around it — the note's name, the file it sits in — and
  * never their own wording for the defect.
  *
@@ -181,8 +177,9 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *
- * `[[#some-heading]]` — no target, only an anchor. Both resolvers special-case
- * it before consulting any index, because there is nothing to look up.
+ * `[[#some-heading]]` — no target, only an anchor. The resolver and the checker
+ * special-case it before consulting any index, because there is nothing to look
+ * up.
  *
  * @param {ParsedWikilink} parsed - A parsed wikilink.
  * @returns {boolean} True when the link is same-page.
@@ -212,36 +209,23 @@ export function presentWikilink(reference: string, parsed: object, destination:
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
- * One authored link compiles to two different addresses — a Foundry `@UUID`
- * enricher for the packs, a URL for the web — and those two destinations are the
- * *only* thing that legitimately differs. The syntax is the author's, and it is
- * the same syntax whichever build is reading it.
+ * One authored link is written three ways — a Foundry `@UUID` content link for
+ * the packs, a URL for the web, a cross-reference for the book — and those
+ * forms are the *only* thing that legitimately differs. The syntax is the
+ * author's, and it is the same syntax whichever build is reading it.
  *
- * It was written twice, and the two copies had already drifted:
+ * So the parse lives here, once, and two readers take it: the link checker
+ * (`content-links.mjs`) and the resolver (`wikilinks.mjs`). Each receives the
+ * parts and decides only what it is for: which document the address names.
  *
- * | Body | `foundry` side | `web` side |
- * | --- | --- | --- |
- * | `[[weapongear-bsw` ⏎ `]]` in a table cell | not a link | a link whose target ends in a newline |
- * | a stray `[[`, a real link two paragraphs later | finds the real link | swallows both paragraphs as one target |
- *
- * The web side's pattern omitted `\n` from the excluded set, so an unclosed
- * bracket consumed everything up to the next `]]` anywhere in the document —
- * the same shape of corruption a hand-rolled code-fence regex caused on the one
- * page whose subject is link syntax. It was also internally
- * inconsistent: its *frontmatter* scan excluded newlines while its body scan did
- * not.
- *
- * So the parse lives here, once. A resolver receives the parts and decides only
- * what it is actually for: which document the address names.
- *
- * The one rule about a link's *shape* that both resolvers share also lives here
- * — **a link carries a label** ({@link unlabelledLinkMessage}) — because the
- * two state it through one message and the author reads the same words
- * whichever ran first.
+ * The one rule about a link's *shape* also lives here — **a link carries a
+ * label** ({@link unlabelledLinkMessage}) — because every build states it
+ * through one message and the author reads the same words whichever ran
+ * first.
  *
  * For the same reason, so does the **vocabulary of link findings**
  * ({@link LINK_FINDING_REASONS}) and the message each one reports through
- * ({@link linkFindingMessage}). Three builds read one authored link; an author
+ * ({@link linkFindingMessage}). Every build reads one authored link; an author
  * meets whichever ran first, and a consumer switching on a `reason` should not
  * be switching on which build produced it.
  *
@@ -258,20 +242,18 @@ export function presentWikilink(reference: string, parsed: object, destination:
  * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
  * keeps every reader from seeing one as the other. Stated here rather than in
  * each reader for the reason the rest of this module exists: the checker, the
- * pack compilers and the web resolver all match on this pattern, and three
- * copies of the exclusion is three places for it to be forgotten. An embed's
+ * resolver and the embed reader all match on this pattern, and a copy of the
+ * exclusion in each is a place for it to be forgotten. An embed's
  * own grammar is {@link module:engine/content-embeds}.
  */
 export const WIKILINK: RegExp;
 /**
- * Every way a link can fail, named once for all three resolvers.
- *
- * A link is read in three places — the checker (`content-links.mjs`), the pack
- * compilers (`wikilinks.mjs`) and the web resolver (`web-wikilinks.mjs`) — and
- * each would otherwise name the failures in its own words. `unknown` in one is
- * `unresolved` in another and `broken type/shortcode` in the third, so a
- * consumer switching on a `reason` was switching on which build had produced
- * it. The set is closed and lives here, beside the syntax the three share.
+ * Every way a link can fail, named once for every reader of a link.
+ *
+ * A link is read by the checker (`content-links.mjs`) and by the resolver
+ * (`wikilinks.mjs`) for every target, and each names a failure by one of these
+ * reasons, so a consumer switching on a `reason` never switches on which build
+ * produced it. The set is closed and lives here, beside the syntax they share.
  *
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.