@heroiclands/package-build 23.13.0 → 24.0.0

package/types/engine/content-expand.d.mts

@@ -0,0 +1,288 @@
+/**
+ * The note a body belongs to.
+ *
+ * @typedef {object} ExpandedNote
+ * @property {Record<string, any>} fm - Its frontmatter.
+ * @property {string} [file] - Its file, which findings name.
+ * @property {string} source - What a table's or a link's finding names the
+ *   note by: its path on the web, its name in Foundry.
+ * @property {number} [bodyLine] - The file line its body starts on.
+ * @property {number} [bodyColumn] - The column its body starts at on that line.
+ */
+/**
+ * How a target resolves links, beyond the index.
+ *
+ * @typedef {object} ExpandLinks
+ * @property {string|null} [pack] - `foundry`: the pack the note's own document
+ *   lands in, which a `[[#slug]]` self-link addresses.
+ * @property {string|null} [docPack] - `foundry`: the pack its journal lands in.
+ * @property {Map<string, object>} [foreign] - `web` and `book`: the merged
+ *   foreign index.
+ * @property {object} [assets] - `web` and `book`: the address space an embed
+ *   resolves against, from {@link module:engine/art-fields.assetAddressIndex}.
+ * @property {(text: string) => string} [beforeLinks] - `web` and `book`: a pass
+ *   run on the text outside code before its links resolve.
+ * @property {(text: string) => string} [afterLinks] - `web` and `book`: a pass
+ *   run on the text outside code once its links resolve.
+ */
+/**
+ * The first two steps of an expansion: the tables, and the figures of the
+ * table-expanded body.
+ *
+ * @typedef {object} ExpandedTables
+ * @property {{markdown: string, errors: object[], lineMap: object[],
+ *   generatedFrom: number|undefined}} tables - From
+ *   {@link module:engine/content-tables.expandContentTables}.
+ * @property {{figures: object[], errors: object[]}} figures - The figure scan
+ *   of `tables.markdown`. A caller numbering figures across notes replaces
+ *   `figures.figures` with its numbering before expanding the rest.
+ */
+/**
+ * Expand a note's tables and scan the result for figures — steps 1 and 2 of
+ * {@link expandContent}.
+ *
+ * @param {string} markdown - The body as authored.
+ * @param {object} options
+ * @param {string} options.source - What a table's finding names the note by.
+ * @param {{sqlTables?: object[], pageLists?: object[]}} [options.prepared] -
+ *   This note's prepared SQL tables and page lists.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - The
+ *   role an embedded picture takes, which numbers a map apart from a figure.
+ * @returns {ExpandedTables} The two steps' results.
+ */
+export function expandTables(markdown: string, { source, prepared, resolveRole }: {
+    source: string;
+    prepared?: {
+        sqlTables?: object[];
+        pageLists?: object[];
+    } | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+}): ExpandedTables;
+/**
+ * The expanded body, and what each step found.
+ *
+ * @typedef {object} Expansion
+ * @property {string} markdown - The whole body, expanded.
+ * @property {string} authored - The author's text, expanded. In Foundry it is
+ *   the whole body.
+ * @property {string} generated - The generated sections, expanded apart from
+ *   the author's text on the web; `""` in Foundry, and wherever there are none.
+ * @property {Array<{line: number, generated: boolean}>} lineMap - The authored
+ *   line, 0-based, each line of the table-expanded body came from.
+ * @property {number|undefined} generatedFrom - The 0-based line of the
+ *   table-expanded body the generated sections start on.
+ * @property {{figures: object[], errors: object[]}} figures - The figure scan
+ *   of the table-expanded body.
+ * @property {{tables: object[], captions: object[], expressions: object[], links: object[]}} findings -
+ *   Each step's findings, as the step reports them: a table's and a caption's
+ *   by expanded body line, an expression's in file coordinates, a link's by
+ *   occurrence of its literal.
+ * @property {Error|undefined} linkError - `foundry`: the error
+ *   {@link module:engine/helpers.convertNoteWikilinks} fails a note with,
+ *   carrying `file` and `position`.
+ * @property {object[]} unresolved - `foundry`: the links that did not resolve.
+ * @property {object[]} resolved - `web` and `book`: every link that resolved,
+ *   in order.
+ * @property {number} authoredLinks - `web`: how many of `resolved` the
+ *   author's text made, before the generated sections'.
+ */
+/**
+ * Expand a note's body for one target.
+ *
+ * @param {string} markdown - The body as authored.
+ * @param {object} options
+ * @param {"foundry"|"web"|"book"} options.target - What the body is expanded
+ *   for.
+ * @param {object} options.index - What links resolve against: the compile's
+ *   link index for `foundry`, the {@link module:engine/site-index.buildSiteIndex}
+ *   index for `web` and `book`.
+ * @param {ExpandedNote} options.note - The note.
+ * @param {{sqlTables?: object[], pageLists?: object[], inline?: object[]}} [options.prepared] -
+ *   This note's prepared SQL tables, page lists and inline query results.
+ * @param {object} [options.events] - Every note's events, from
+ *   {@link module:engine/event-fields.eventNoteIndex}.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - The
+ *   role an embedded picture takes, which numbers a map apart from a figure.
+ * @param {Map<string, Map<string, object>>} [options.figuresByAddress] - `web`
+ *   and `book`: every page's figures, by the address a cross-note `ref` writes.
+ * @param {ExpandedTables} [options.tables] - The note's {@link expandTables},
+ *   already run — with the figures numbered, for the book. Run here when
+ *   omitted.
+ * @param {ExpandLinks} [options.links] - How the target resolves links.
+ * @returns {Expansion} The expanded body and the findings.
+ * @throws {Error} When `target` is not one of {@link EXPANSION_TARGETS}.
+ */
+export function expandContent(markdown: string, { target, index, note, prepared, events, resolveRole, figuresByAddress, tables: staged, links, }: {
+    target: "foundry" | "web" | "book";
+    index: object;
+    note: ExpandedNote;
+    prepared?: {
+        sqlTables?: object[];
+        pageLists?: object[];
+        inline?: object[];
+    } | undefined;
+    events?: object | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+    figuresByAddress?: Map<string, Map<string, object>> | undefined;
+    tables?: ExpandedTables | undefined;
+    links?: ExpandLinks | undefined;
+}): Expansion;
+/** The targets a body is expanded for. */
+export const EXPANSION_TARGETS: readonly string[];
+/**
+ * The note a body belongs to.
+ */
+export type ExpandedNote = {
+    /**
+     * - Its frontmatter.
+     */
+    fm: Record<string, any>;
+    /**
+     * - Its file, which findings name.
+     */
+    file?: string | undefined;
+    /**
+     * - What a table's or a link's finding names the
+     * note by: its path on the web, its name in Foundry.
+     */
+    source: string;
+    /**
+     * - The file line its body starts on.
+     */
+    bodyLine?: number | undefined;
+    /**
+     * - The column its body starts at on that line.
+     */
+    bodyColumn?: number | undefined;
+};
+/**
+ * How a target resolves links, beyond the index.
+ */
+export type ExpandLinks = {
+    /**
+     * - `foundry`: the pack the note's own document
+     * lands in, which a `[[#slug]]` self-link addresses.
+     */
+    pack?: string | null | undefined;
+    /**
+     * - `foundry`: the pack its journal lands in.
+     */
+    docPack?: string | null | undefined;
+    /**
+     * - `web` and `book`: the merged
+     * foreign index.
+     */
+    foreign?: Map<string, object> | undefined;
+    /**
+     * - `web` and `book`: the address space an embed
+     * resolves against, from {@link module :engine/art-fields.assetAddressIndex}.
+     */
+    assets?: object | undefined;
+    /**
+     * - `web` and `book`: a pass
+     * run on the text outside code before its links resolve.
+     */
+    beforeLinks?: ((text: string) => string) | undefined;
+    /**
+     * - `web` and `book`: a pass
+     * run on the text outside code once its links resolve.
+     */
+    afterLinks?: ((text: string) => string) | undefined;
+};
+/**
+ * The first two steps of an expansion: the tables, and the figures of the
+ * table-expanded body.
+ */
+export type ExpandedTables = {
+    /**
+     * - From
+     * {@link module :engine/content-tables.expandContentTables}.
+     */
+    tables: {
+        markdown: string;
+        errors: object[];
+        lineMap: object[];
+        generatedFrom: number | undefined;
+    };
+    /**
+     * - The figure scan
+     * of `tables.markdown`. A caller numbering figures across notes replaces
+     * `figures.figures` with its numbering before expanding the rest.
+     */
+    figures: {
+        figures: object[];
+        errors: object[];
+    };
+};
+/**
+ * The expanded body, and what each step found.
+ */
+export type Expansion = {
+    /**
+     * - The whole body, expanded.
+     */
+    markdown: string;
+    /**
+     * - The author's text, expanded. In Foundry it is
+     * the whole body.
+     */
+    authored: string;
+    /**
+     * - The generated sections, expanded apart from
+     * the author's text on the web; `""` in Foundry, and wherever there are none.
+     */
+    generated: string;
+    /**
+     * - The authored
+     * line, 0-based, each line of the table-expanded body came from.
+     */
+    lineMap: Array<{
+        line: number;
+        generated: boolean;
+    }>;
+    /**
+     * - The 0-based line of the
+     * table-expanded body the generated sections start on.
+     */
+    generatedFrom: number | undefined;
+    /**
+     * - The figure scan
+     * of the table-expanded body.
+     */
+    figures: {
+        figures: object[];
+        errors: object[];
+    };
+    /**
+     * -
+     * Each step's findings, as the step reports them: a table's and a caption's
+     * by expanded body line, an expression's in file coordinates, a link's by
+     * occurrence of its literal.
+     */
+    findings: {
+        tables: object[];
+        captions: object[];
+        expressions: object[];
+        links: object[];
+    };
+    /**
+     * - `foundry`: the error
+     * {@link module :engine/helpers.convertNoteWikilinks} fails a note with,
+     * carrying `file` and `position`.
+     */
+    linkError: Error | undefined;
+    /**
+     * - `foundry`: the links that did not resolve.
+     */
+    unresolved: object[];
+    /**
+     * - `web` and `book`: every link that resolved,
+     * in order.
+     */
+    resolved: object[];
+    /**
+     * - `web`: how many of `resolved` the
+     * author's text made, before the generated sections'.
+     */
+    authoredLinks: number;
+};

package/types/engine/content-figures.d.mts

@@ -57,18 +57,26 @@ export function scanFigures(source: string, { resolveRole }?: {
  * @param {string} source - A note body with expanded tables.
  * @param {(markdown: string) => string} [renderMarkdown] - How to render a
  *   figure's own contents.
- * @param {Array<{id: string, label: string}>} [numbers] - Labels assigned by a
- *   surface that counts across documents, matched by id.
+ * @param {Array<{id: string, kind: string, label: string}>} [numbers] - The
+ *   figures as {@link scanFigures} numbered them, with roles, where the
+ *   surface counted them: across a note's pages, or in expansion, where a
+ *   `ref` reads the same label. They are matched in order when they are as many
+ *   as the text holds, by id otherwise, and the caption takes its number, kind
+ *   and label from them. Omitted, the text is numbered as it stands.
  * @param {object} [options] - Options.
  * @param {(address: string) => string|undefined} [options.resolveRole] - See
  *   {@link scanFigures}.
+ * @param {(markdown: string) => string} [options.renderInline] - How a caption
+ *   is rendered; omitted, a caption is plain inline Markdown.
  * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
  */
 export function renderFigureBlocks(source: string, renderMarkdown?: (markdown: string) => string, numbers?: Array<{
     id: string;
+    kind: string;
     label: string;
-}>, { resolveRole }?: {
+}>, { resolveRole, renderInline }?: {
     resolveRole?: ((address: string) => string | undefined) | undefined;
+    renderInline?: ((markdown: string) => string) | undefined;
 }): {
     markdown: string;
     errors: Array<{

package/types/engine/content-glyphs.d.mts

@@ -0,0 +1,85 @@
+/**
+ * The pathname of a glyph's picture.
+ * @param {string} slug - The glyph's slug.
+ * @returns {string} The authored pathname.
+ */
+export function glyphPathname(slug: string): string;
+/**
+ * The pathname of a cartouche's picture.
+ * @param {string} slug - The cartouche's slug.
+ * @returns {string} The authored pathname.
+ */
+export function cartouchePathname(slug: string): string;
+/**
+ * A slug as words, for the alt text of a sign whose author wrote none.
+ * @param {string} slug - The slug.
+ * @returns {string} Title-cased words.
+ */
+export function humanizeSlug(slug: string): string;
+/**
+ * What is wrong with a glyph's attributes.
+ * @param {{id: string, classes: string[], values: Record<string, string>}} parsed - The parsed attributes.
+ * @returns {string[]} One message per problem.
+ */
+export function glyphProblems(parsed: {
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+}): string[];
+/**
+ * What is wrong with a cartouche's attributes.
+ * @param {{id: string, classes: string[], values: Record<string, string>}} parsed - The parsed attributes.
+ * @returns {string[]} One message per problem.
+ */
+export function cartoucheProblems(parsed: {
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+}): string[];
+/**
+ * A cartouche's height as Typst writes a length.
+ * @param {string} height - A validated CSS length.
+ * @returns {string} The same length in a unit Typst reads.
+ */
+export function typstLength(height: string): string;
+/**
+ * A glyph as HTML.
+ * @param {{slug: string, alt: string, frame?: string, size?: string}} glyph - Its attributes.
+ * @param {string} src - The address the target serves its picture at.
+ * @returns {string} A span holding an image.
+ */
+export function glyphHtml({ slug, alt, frame, size }: {
+    slug: string;
+    alt: string;
+    frame?: string;
+    size?: string;
+}, src: string): string;
+/**
+ * A cartouche as HTML.
+ * @param {{slug: string, alt?: string, align?: string, height?: string, caption?: string}} cartouche - Its attributes.
+ * @param {string} src - The address the target serves its picture at.
+ * @returns {string} A figure holding an image and an optional caption, on one
+ *   line so that it sits inside a paragraph without ending it.
+ */
+export function cartoucheHtml({ slug, alt, align, height, caption }: {
+    slug: string;
+    alt?: string;
+    align?: string;
+    height?: string;
+    caption?: string;
+}, src: string): string;
+/** The frames a glyph may sit in. */
+export const GLYPH_FRAMES: readonly string[];
+/** The sizes a glyph may take. */
+export const GLYPH_SIZES: readonly string[];
+/** The sides a cartouche may float to; absent, it is centred. */
+export const CARTOUCHE_ALIGNS: readonly string[];
+/** The attribute keys a glyph takes. */
+export const GLYPH_KEYS: readonly string[];
+/** The attribute keys a cartouche takes. */
+export const CARTOUCHE_KEYS: readonly string[];
+/**
+ * The units a cartouche height may be written in: every one a printed page
+ * can honour as well as a screen.
+ */
+export const HEIGHT_UNITS: readonly string[];

package/types/engine/content-images.d.mts

@@ -73,7 +73,7 @@ export function escapeHtml(text: string): string;
  *
  * **The role class and the `width`/`height` attributes are what a stylesheet
  * elsewhere keys a role's size on.** This module states none — the measure a
- * `portrait` fills on a page is a Hugo theme's or a Foundry system's own
+ * `portrait` fills on a page is a site theme's or a Foundry system's own
  * decision — and emits only what the resolved asset record states: a role
  * class when the picture declares one, and the attributes whenever the
  * picture resolved to an asset record at all, blank for a vector. The
@@ -239,12 +239,11 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
 /**
  * Rewrite every block image in a body into the figure the website publishes.
  *
- * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
- * note's body through verbatim, so a `{…}` directive left in it reaches the
- * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the closed vocabularies,
- * which is the injection surface this rule exists to avoid. So the directive is
- * resolved here, into markup Goldmark passes through.
+ * **The directive is resolved before the markdown is parsed.** A `{…}`
+ * directive left in the body would reach the page as its own literal braces: a
+ * block-attribute parser would accept `style` and `id` alongside the closed
+ * vocabularies, which is the injection surface this rule exists to avoid. So
+ * the directive is resolved here, into markup the renderer passes through.
  *
  * An image whose directive does not parse is left exactly as written, so the
  * page shows the braces and the lint says why — the same visible degradation an

package/types/engine/content-links.d.mts

@@ -142,7 +142,7 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   `"unresolved"`, never `"ambiguous"`: every target here expands to one
  *   canonical address before anything is looked up, so there is no candidate
  *   set for two packages to claim — and every reason is an **error**: the
- *   three resolvers agree on severity for every class.
+ *   checker and the resolver agree on severity for every class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -0,0 +1,199 @@
+/**
+ * Highlight a fenced block's code for the language it names.
+ *
+ * @param {string} code - The block's text.
+ * @param {string} language - The fence's first word.
+ * @returns {string} The code as highlight.js's class-based markup, or `""` when
+ *   no language is named or highlight.js does not know it, which markdown-it
+ *   reads as "escape it as plain text".
+ */
+export function highlightCode(code: string, language: string): string;
+/**
+ * Make the raw HTML an author wrote inert, leaving what markdown reads as a
+ * link and anything inside code as written.
+ *
+ * The `preview` target parses with HTML on, because the stages of
+ * {@link Renderer#prepare} write HTML between blank lines. A tag the author
+ * wrote must still read as text, so its opening bracket becomes
+ * {@link INERT_BRACKET} first, before the stages run and before expansion
+ * writes its own markup; the preview renderer writes it back as `<`, and
+ * its source view as `<`.
+ *
+ * @param {string} markdown - Authored markdown.
+ * @returns {string} The same markdown with each authored `<` that opens a tag,
+ *   comment, declaration or processing instruction replaced.
+ */
+export function inertHtml(markdown: string): string;
+/**
+ * How a target's pictures resolve.
+ *
+ * @typedef {object} ImageSources
+ * @property {(src: string) => string} [resolveSrc] - From a body image's address
+ *   to the `src` the target draws.
+ * @property {(src: string) => ({role?: string, width?: number|"", height?: number|""}|undefined)} [lookupAsset] -
+ *   From an address to the asset it names.
+ */
+/**
+ * What a renderer is built with.
+ *
+ * @typedef {object} RendererOptions
+ * @property {() => (object|undefined)|object} [icons] - The icon registry, or a
+ *   function that returns it, called at each render so a configuration read
+ *   late is honoured. `foundry`, `web`, `preview` and `book`.
+ * @property {ImageSources} [images] - How body images resolve. `foundry`, `web`
+ *   and `preview`.
+ * @property {boolean} [source] - `preview`: show wikilinks, spans, expressions
+ *   and queries as highlighted authored source, for a buffer with no index.
+ * @property {object} [sourceContext] - `preview` with `source`: the buffer's
+ *   `fm`, `file` and `findings`, which the source view reads.
+ */
+/**
+ * @typedef {object} RenderEnv
+ * @property {import("./content-scripts.mjs").RunContext} [runs] - The package's
+ *   languages, faces and maps.
+ * @property {Array<object>} [figures] - The note's numbered figures, from the
+ *   figure scan expansion made: matched in order when they are as many as the
+ *   text holds, by id otherwise.
+ * @property {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, used when `figures` is
+ *   not given.
+ * @property {Map<string, number>} [footnoteNumbers] - Footnote numbers shared
+ *   across the pages of one note.
+ * @property {string} [docId] - Threaded into footnote anchors.
+ * @property {(src: string) => string} [resolveSrc] - From a glyph's or
+ *   cartouche's authored pathname to the address this render serves, taking
+ *   the place of the renderer's own image resolver.
+ */
+/**
+ * @typedef {object} Renderer
+ * @property {RendererTarget} target - The target it renders for.
+ * @property {import("markdown-it")} md - The configured parser.
+ * @property {readonly string[]} plugins - The names of the plugins installed, in
+ *   order. Targets that share a configuration share its names.
+ * @property {(markdown: string, env?: RenderEnv) => string} prepare - Write the
+ *   constructs markdown-it has no syntax for as HTML between blank lines.
+ * @property {(markdown: string, env?: RenderEnv) => string} render - Prepare,
+ *   then render to HTML.
+ * @property {(markdown: string) => string} renderInline - Render one inline run.
+ */
+/** @typedef {"foundry"|"web"|"preview"|"book"} RendererTarget */
+/**
+ * Build the renderer for one target.
+ *
+ * @param {RendererTarget} target - What the markdown is rendered for.
+ * @param {RendererOptions} [options] - Per-target inputs.
+ * @returns {Renderer} The configured parser and its stages.
+ * @throws {Error} When `target` is not one of {@link RENDER_TARGETS}.
+ */
+export function createRenderer(target: RendererTarget, options?: RendererOptions): Renderer;
+/** The targets a renderer is built for. */
+export const RENDER_TARGETS: readonly string[];
+/**
+ * How a target's pictures resolve.
+ */
+export type ImageSources = {
+    /**
+     * - From a body image's address
+     * to the `src` the target draws.
+     */
+    resolveSrc?: ((src: string) => string) | undefined;
+    /**
+     * -
+     * From an address to the asset it names.
+     */
+    lookupAsset?: ((src: string) => ({
+        role?: string;
+        width?: number | "";
+        height?: number | "";
+    } | undefined)) | undefined;
+};
+/**
+ * What a renderer is built with.
+ */
+export type RendererOptions = {
+    /**
+     * - The icon registry, or a
+     * function that returns it, called at each render so a configuration read
+     * late is honoured. `foundry`, `web`, `preview` and `book`.
+     */
+    icons?: (() => (object | undefined) | object) | undefined;
+    /**
+     * - How body images resolve. `foundry`, `web`
+     * and `preview`.
+     */
+    images?: ImageSources | undefined;
+    /**
+     * - `preview`: show wikilinks, spans, expressions
+     * and queries as highlighted authored source, for a buffer with no index.
+     */
+    source?: boolean | undefined;
+    /**
+     * - `preview` with `source`: the buffer's
+     * `fm`, `file` and `findings`, which the source view reads.
+     */
+    sourceContext?: object | undefined;
+};
+export type RenderEnv = {
+    /**
+     * - The package's
+     * languages, faces and maps.
+     */
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
+    /**
+     * - The note's numbered figures, from the
+     * figure scan expansion made: matched in order when they are as many as the
+     * text holds, by id otherwise.
+     */
+    figures?: object[] | undefined;
+    /**
+     * - From a
+     * picture's address to the role its asset declares, used when `figures` is
+     * not given.
+     */
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+    /**
+     * - Footnote numbers shared
+     * across the pages of one note.
+     */
+    footnoteNumbers?: Map<string, number> | undefined;
+    /**
+     * - Threaded into footnote anchors.
+     */
+    docId?: string | undefined;
+    /**
+     * - From a glyph's or
+     * cartouche's authored pathname to the address this render serves, taking
+     * the place of the renderer's own image resolver.
+     */
+    resolveSrc?: ((src: string) => string) | undefined;
+};
+export type Renderer = {
+    /**
+     * - The target it renders for.
+     */
+    target: RendererTarget;
+    /**
+     * - The configured parser.
+     */
+    md: typeof import("markdown-it");
+    /**
+     * - The names of the plugins installed, in
+     * order. Targets that share a configuration share its names.
+     */
+    plugins: readonly string[];
+    /**
+     * - Write the
+     * constructs markdown-it has no syntax for as HTML between blank lines.
+     */
+    prepare: (markdown: string, env?: RenderEnv) => string;
+    /**
+     * - Prepare,
+     * then render to HTML.
+     */
+    render: (markdown: string, env?: RenderEnv) => string;
+    /**
+     * - Render one inline run.
+     */
+    renderInline: (markdown: string) => string;
+};
+export type RendererTarget = "foundry" | "web" | "preview" | "book";