@heroiclands/package-build 23.13.0 → 24.0.1

package/types/engine/markdown-expressions.d.mts

@@ -48,8 +48,6 @@ export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults,
 /**
  * An inline expression, as an author writes one.
  *
- * Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
- *
  * Exported because a renderer that meets one has met a body this pass never ran
  * over, and has to be able to say so.
  *

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

@@ -0,0 +1,39 @@
+/**
+ * Check a note's `data.metres`: each name's form, that no other entry declares
+ * it, and that a beat count is a whole number above zero. The data-key check
+ * owns every key, its kind and the closed `kind` list.
+ *
+ * @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 checkMetresField(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, { index }?: {
+    index?: {
+        notes?: Iterable<object>;
+    };
+}): object[];
+/** What a metre's `kind` may be. */
+export const METRE_KINDS: readonly string[];
+/** What a metre's `name` may be. */
+export const METRE_NAME: RegExp;
+/**
+ * One declared metre.
+ */
+export type Metre = {
+    /**
+     * - What `scan=` names it by.
+     */
+    name: string;
+    /**
+     * - The beats of a line.
+     */
+    beats: number;
+    /**
+     * - How they are counted: `accentual`.
+     */
+    kind: string;
+};

package/types/engine/pdf-render.d.mts

@@ -26,12 +26,16 @@ export function escapeTypstString(text: string): string;
  */
 export function labelFor(anchor: string): string;
 /**
- * A markdown-it configured to parse, not to render.
+ * The shared parser configured for the book: the `book` target of
+ * {@link module:engine/content-render.createRenderer}, which parses and leaves
+ * the output to this module's Typst stage.
  *
  * `html: false` is the load-bearing setting: raw HTML in a note has no route to
  * Typst at all, which is why {@link module:engine/content-html} reports it. With
  * HTML disabled markdown-it emits the tag as text, so it arrives in the book
- * visibly wrong rather than invisibly missing.
+ * visibly wrong rather than invisibly missing. The one tag it reads is the
+ * emphasis a script run's convention sets, which the run's rewrite writes and
+ * the book prints in its rubric ink or under an overline.
  *
  * @param {object} [registry] - The icon registry.
  * @returns {object} A markdown-it instance.

package/types/engine/post-fields.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Whether a note's frontmatter, or a page's parameters, are a post's.
+ *
+ * @param {{type?: unknown, subType?: unknown}|null|undefined} fm - The frontmatter.
+ * @returns {boolean} Whether it is a `doc` of `subType: post`.
+ */
+export function isPost(fm: {
+    type?: unknown;
+    subType?: unknown;
+} | null | undefined): boolean;
+/**
+ * Whether a string is a calendar day, `YYYY-MM-DD`, that exists.
+ *
+ * @param {unknown} value - The value.
+ * @returns {boolean} Whether it is one.
+ */
+export function isCalendarDay(value: unknown): boolean;
+/**
+ * Scope `data.date` and `data.author` to posts, and check their values.
+ *
+ * A post with no date is an error at its `subType:` line; a date that is not a
+ * calendar day, or an author that is blank, is an error at the value. Either
+ * field on a `doc` that is not a post is an error at the key.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @returns {object[]} Findings.
+ */
+export function checkPostFields(note: object): object[];
+/** The `doc` subType a post is. */
+export const POST_SUBTYPE: "post";
+/** `data.date`, as the vocabulary declares it. */
+export const POST_DATE_FIELD: Readonly<{
+    name: "date";
+    shape: "string";
+    kind: "string";
+    describe: string;
+}>;
+/** `data.author`, as the vocabulary declares it. */
+export const POST_AUTHOR_FIELD: Readonly<{
+    name: "author";
+    shape: "string";
+    kind: "string";
+    describe: string;
+}>;

package/types/engine/preview-index.d.mts

@@ -0,0 +1,72 @@
+/**
+ * What a preview reads to render with an index.
+ *
+ * @typedef {object} PreviewIndex
+ * @property {object} runs - The package's languages, faces and maps.
+ * @property {object|undefined} icons - The package's icon registry.
+ * @property {(src: string) => ({role?: string, width?: number|"", height?: number|""}|undefined)} lookupAsset -
+ *   From a picture's address to its asset.
+ * @property {(src: string) => string} resolveSrc - From a picture's authored
+ *   pathname to the address the website serves it at.
+ * @property {(markdown: string, note: {fm: object, file?: string}) => {markdown: string, figures: object[]}} expand -
+ *   Expand a buffer's body as the website expands a page: links, embeds,
+ *   expressions and figure numbers resolved. A query, which a buffer cannot
+ *   answer, is left as written.
+ */
+/**
+ * Build the object a preview with an index renders from.
+ *
+ * @param {object} options
+ * @param {object} options.config - The resolved package configuration.
+ * @param {object[]} options.records - The content index's records: every note
+ *   and every asset.
+ * @param {object} [options.foreign] - The dependencies' indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns them.
+ *   Omitted, the package links only to itself.
+ * @returns {PreviewIndex} The index.
+ */
+export function previewIndex({ config, records, foreign }: {
+    config: object;
+    records: object[];
+    foreign?: object | undefined;
+}): PreviewIndex;
+/**
+ * What a preview reads to render with an index.
+ */
+export type PreviewIndex = {
+    /**
+     * - The package's languages, faces and maps.
+     */
+    runs: object;
+    /**
+     * - The package's icon registry.
+     */
+    icons: object | undefined;
+    /**
+     * -
+     * From a picture's address to its asset.
+     */
+    lookupAsset: (src: string) => ({
+        role?: string;
+        width?: number | "";
+        height?: number | "";
+    } | undefined);
+    /**
+     * - From a picture's authored
+     * pathname to the address the website serves it at.
+     */
+    resolveSrc: (src: string) => string;
+    /**
+     * -
+     * Expand a buffer's body as the website expands a page: links, embeds,
+     * expressions and figure numbers resolved. A query, which a buffer cannot
+     * answer, is left as written.
+     */
+    expand: (markdown: string, note: {
+        fm: object;
+        file?: string;
+    }) => {
+        markdown: string;
+        figures: object[];
+    };
+};

package/types/engine/preview-source.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Highlight a wikilink or an embed without interpreting any Markdown or HTML
+ * inside the source.
+ *
+ * @param {string} raw - The link as written, from `[[` or `![[` to its end.
+ * @returns {string} The highlighted source.
+ */
+export function wikiSource(raw: string): string;
+/**
+ * Install the preview target's rules.
+ *
+ * @param {import("markdown-it")} md - The shared parser.
+ * @param {object} [options]
+ * @param {boolean} [options.source] - The buffer has no index: show wikilinks,
+ *   embeds, spans and local expressions as authored source.
+ * @param {object} [options.fm] - The buffer's frontmatter, which a local
+ *   expression reads.
+ * @param {string} [options.file] - The buffer's name, for a finding.
+ * @param {Map<string, object>} [options.figures] - The buffer's captioned items
+ *   by id, which a local `ref` reads.
+ */
+export function previewSourcePlugin(md: typeof import("markdown-it"), { source, fm, file, figures }?: {
+    source?: boolean | undefined;
+    fm?: object | undefined;
+    file?: string | undefined;
+    figures?: Map<string, object> | undefined;
+}): void;
+/** Explicit dependency policy: a new registered helper requires a preview decision. */
+export const PREVIEW_HELPERS: Readonly<{
+    eq: "local";
+    gt: "local";
+    gte: "local";
+    lt: "local";
+    lte: "local";
+    not: "local";
+    and: "local";
+    or: "local";
+    words: "local";
+    digits: "local";
+    sql: "dependent";
+    dateformat: "dependent";
+    ref: "reference";
+}>;
+/**
+ * What stands for an authored `<` in the preview between
+ * {@link module:engine/content-render.inertHtml} and the rendered HTML, where
+ * it is written `&lt;`. A private-use character, so it can neither be read as
+ * markup nor collide with prose.
+ */
+export const INERT_BRACKET: "\uE000";
+export function colored(role: string, source: string): string;

package/types/engine/script-emphasis-terms.d.mts

@@ -0,0 +1,21 @@
+/**
+ * **The words a script note and a language note state emphasis by.** Read by
+ * the vocabulary as it is declared, so this module imports nothing; the
+ * checks and the conventions' use are in {@link module:engine/script-emphasis}.
+ *
+ * @module
+ */
+/** The conventions a script states its emphasis by. */
+export const EMPHASIS_CONVENTIONS: readonly string[];
+/** The class each convention gives an `<em>` or a `<strong>`. */
+export const EMPHASIS_CLASSES: Readonly<{
+    rubric: "emph-rubric";
+    overline: "emph-overline";
+}>;
+/**
+ * The conventions a language note states, which override its script's.
+ * `words` marks emphasis with a word, so a mark in its text is a finding.
+ */
+export const LANGUAGE_EMPHASES: readonly string[];
+/** The `subType` of a script note. */
+export const SCRIPT_SUBTYPE: "script";

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

@@ -0,0 +1,84 @@
+/**
+ * Each face's conventions, from the script notes among the index records. The
+ * first note to list a face keeps it; a second is the lint's to report, and a
+ * note whose convention is unknown gives none.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, Emphasis>} The conventions, by face slug.
+ */
+export function emphasesFromRecords(records: Iterable<Record<string, any>> | undefined): Map<string, Emphasis>;
+/**
+ * The convention each language's note states.
+ *
+ * @param {ReadonlyMap<string, Record<string, any>>} byName - Each configured
+ *   language's note record, by language name, from
+ *   {@link module:engine/map-lexicon.languageRecordsByName}.
+ * @returns {Map<string, LanguageEmphasis>} The conventions, by language name;
+ *   a language whose note states none, or one the build does not know, is
+ *   absent.
+ */
+export function languageEmphasesOf(byName: ReadonlyMap<string, Record<string, any>>): Map<string, LanguageEmphasis>;
+/**
+ * Refuse `data.emphasis` on a skill that is not a language, at its key.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageEmphasis(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}): object[];
+/**
+ * Check a note's `data.script`: that the note is a script, and that its
+ * `fonts` is not empty, names no generic family, lists no face twice, and
+ * lists no face another script note lists. The data-key check owns every key,
+ * its kind and the conventions; whether a face is installed is
+ * {@link checkScriptNoteFonts}'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 or entry.
+ */
+export function checkScriptField(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, { index }?: {
+    index?: {
+        notes?: Iterable<object>;
+    };
+}): object[];
+/**
+ * Each face a script note lists that is not installed, at its entry.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{faces?: ReadonlyMap<string, unknown>}} [ctx] - The installed faces,
+ *   from {@link module:engine/content-scripts.runContext}.
+ * @returns {object[]} The findings.
+ */
+export function checkScriptNoteFonts(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, ctx?: {
+    faces?: ReadonlyMap<string, unknown>;
+}): object[];
+/**
+ * One face's conventions, one for each level of emphasis.
+ */
+export type Emphasis = {
+    /**
+     * - What `*…*` is set by.
+     */
+    em: "rubric" | "overline";
+    /**
+     * - What `**…**` is set by.
+     */
+    strong: "rubric" | "overline";
+};
+/**
+ * A convention a language note states.
+ */
+export type LanguageEmphasis = "words" | "rubric" | "overline";
+export { EMPHASIS_CLASSES, EMPHASIS_CONVENTIONS, LANGUAGE_EMPHASES } from "./script-emphasis-terms.mjs";

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

@@ -69,10 +69,10 @@ export function checkScriptFonts(config: DeliveryConfig): {
  */
 export function siteFontsParam(config: DeliveryConfig): string | undefined;
 /**
- * The directory under the Hugo static tree that holds this version's fonts.
+ * The directory under the site's 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`.
+ * @returns {string} The POSIX path, relative to the static tree.
  */
 export function siteFontsDestination(version: string): string;
 /**
@@ -104,8 +104,8 @@ export function typstScriptFontPath(config: DeliveryConfig): string | undefined;
  */
 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.
+ * Where the files land in the site's static tree, beneath a directory per
+ * version.
  *
  * @type {string}
  */