@heroiclands/package-build 23.12.5 → 23.12.7

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;

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

@@ -64,6 +64,12 @@ export const BORROWED_SOURCE_KIND: "borrowed";
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
 export const WORD_SOURCE_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The keys of one entry of a word's `native`.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_NATIVE_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
  * The keys one word of a language note's `data.words` carries.
  *