@dogsbay/format-dogsbay-md 0.2.0-beta.135 → 0.2.0-beta.136

package/dist/browser.d.ts

@@ -21,5 +21,7 @@ export { transformCodeRegions, transformProseLines, transformProseSegments, fenc
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export { extractHeadings, slugifyHeadingText, type HeadingInfo } from "./headings.js";
 export { splitFrontmatter, type Frontmatter } from "./frontmatter.js";
+export { DataFiles, DataCache, DataFileError, parseDataFile, parseDelimited, DEFAULT_DATA_LIMITS, UNTRUSTED_DATA_LIMITS, DATA_EXTENSIONS, type DataLimits, type DataFilesOptions, type DataExtension, } from "./data-files.js";
+export { resolveDataDirectives, hasDataDirectives, DATA_DIRECTIVES, NO_PROJECT_MESSAGE, type DataProblem, type DataDirectivesResult, } from "./data-directives.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN, type TemplatePagesOptions } from "./template-pages.js";
 export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS, type AssetMount } from "./project.js";

package/dist/browser.js

@@ -21,5 +21,7 @@ export { transformCodeRegions, transformProseLines, transformProseSegments, fenc
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export { extractHeadings, slugifyHeadingText } from "./headings.js";
 export { splitFrontmatter } from "./frontmatter.js";
+export { DataFiles, DataCache, DataFileError, parseDataFile, parseDelimited, DEFAULT_DATA_LIMITS, UNTRUSTED_DATA_LIMITS, DATA_EXTENSIONS, } from "./data-files.js";
+export { resolveDataDirectives, hasDataDirectives, DATA_DIRECTIVES, NO_PROJECT_MESSAGE, } from "./data-directives.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN } from "./template-pages.js";
 export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS } from "./project.js";

package/dist/data-directives.d.ts

@@ -0,0 +1,43 @@
+import { type DataFiles } from "./data-files.js";
+/** The data directives' names, for editors and the directive lists. */
+export declare const DATA_DIRECTIVES: readonly ["data-table", "data-cards"];
+/** One directive that could not be resolved. `line` is 1-based, in the page as given. */
+export interface DataProblem {
+    line: number;
+    message: string;
+    /** The data file, when the problem is in it. */
+    file?: string;
+    /** The line in the data file, when known. */
+    fileLine?: number;
+}
+export interface DataDirectivesResult {
+    /** The page with every resolvable directive replaced. */
+    text: string;
+    /** Data files the page read, in the data folder, in order of first read. */
+    reads: string[];
+    /** Directives left in place, and why. */
+    problems: DataProblem[];
+}
+/** The message a host without a data folder reports, once per directive. */
+export declare const NO_PROJECT_MESSAGE = "data files need a project: this page is rendered on its own, with no data folder to read";
+/** Cheap pre-check: could this page hold a data directive? */
+export declare function hasDataDirectives(text: string): boolean;
+/**
+ * Replace every `::data-table` / `::data-cards` line outside code with the
+ * table or cards it names. Without `data`, every directive stays and is
+ * reported with NO_PROJECT_MESSAGE.
+ */
+export declare function resolveDataDirectives(text: string, data: DataFiles | undefined): Promise<DataDirectivesResult>;
+/**
+ * A value as Markdown that reads back as exactly that text, on one line: the encoding a table
+ * cell gets, for a template page's `| text` filter. `*`, `<x>`, `[a](b)`, `{{ }}`, `|`, `$`,
+ * `~~` and a leading `- ` all show as written; a list of values is joined with ", " as in a
+ * cell, and an object is an error. Its output is entity-encoded, so `text` goes last in a chain.
+ */
+export declare function literalMarkdown(value: unknown): string;
+/**
+ * `{{ value | code }}`: the value as inline code, on one line, in a fence its own backticks
+ * cannot close. Template pages never evaluate inside a code span written in the page, so this is
+ * how a value is shown as code. In a table cell, follow it with `| replace("|", "\\|")`.
+ */
+export declare function literalCode(value: unknown): string;

package/dist/data-directives.js

@@ -0,0 +1,238 @@
+import { isSafeHref } from "@dogsbay/serialize-core";
+import { createFenceTracker } from "./code-regions.js";
+import { DataFileError } from "./data-files.js";
+import { parseAttrs } from "./parse-attrs.js";
+import { treeToDogsbayMd } from "./serialize.js";
+/** The data directives' names, for editors and the directive lists. */
+export const DATA_DIRECTIVES = ["data-table", "data-cards"];
+/** The message a host without a data folder reports, once per directive. */
+export const NO_PROJECT_MESSAGE = "data files need a project: this page is rendered on its own, with no data folder to read";
+/**
+ * A directive on a line of its own: indented, in a blockquote (`> `), or as a
+ * definition-list tab body (`:   `). Group 1 is that prefix.
+ */
+const DIRECTIVE_LINE = /^((?:[ \t]*>)*[ \t]*(?::[ \t]+)?)::(data-table|data-cards)(\{.*\})?[ \t]*$/;
+/** A line with nothing but its block prefix (`>`, whitespace). */
+const isBlank = (line) => line === undefined || /^[\s>]*$/.test(line);
+/** Cheap pre-check: could this page hold a data directive? */
+export function hasDataDirectives(text) {
+    return text.includes("::data-");
+}
+/**
+ * Replace every `::data-table` / `::data-cards` line outside code with the
+ * table or cards it names. Without `data`, every directive stays and is
+ * reported with NO_PROJECT_MESSAGE.
+ */
+export async function resolveDataDirectives(text, data) {
+    const reads = [];
+    const problems = [];
+    if (!hasDataDirectives(text))
+        return { text, reads, problems };
+    const fences = createFenceTracker();
+    const lines = text.split("\n");
+    const out = [];
+    let inComment = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const kind = fences.step(line);
+        // An HTML comment is not prose: a directive commented out stays out.
+        const commented = kind === "prose" && inComment;
+        if (kind === "prose")
+            inComment = commentOpenAfter(line, inComment);
+        const m = kind === "prose" && !commented ? DIRECTIVE_LINE.exec(line.replace(/\r$/, "")) : null;
+        if (!m) {
+            out.push(line);
+            continue;
+        }
+        const [, prefix, name, block] = m;
+        if (!data) {
+            problems.push({ line: i + 1, message: `::${name}: ${NO_PROJECT_MESSAGE}` });
+            out.push(line);
+            continue;
+        }
+        try {
+            const props = parseAttrs(block ? block.slice(1, -1) : "").props;
+            const { path, value } = await data.read(stringProp(props, "src"));
+            if (!reads.includes(path))
+                reads.push(path);
+            const rows = rowsOf(value, path, props.path, name);
+            const node = name === "data-table" ? tableNode(rows, props, path) : cardsNode(rows, props, path);
+            const md = treeToDogsbayMd([node]).replace(/\n+$/, "");
+            // Later lines continue the block: a tab body's `:` becomes indentation, `>` stays.
+            const cont = prefix.replace(":", " ");
+            const blank = cont.trimEnd();
+            // Blank lines around it, so it neither interrupts a paragraph above nor takes the next line as a row.
+            if (!prefix.includes(":") && !isBlank(out[out.length - 1]) && out.length > 0)
+                out.push(blank);
+            md.split("\n").forEach((l, n) => out.push(l ? (n === 0 ? prefix : cont) + l : blank));
+            if (i + 1 < lines.length && !isBlank(lines[i + 1]))
+                out.push(blank);
+        }
+        catch (err) {
+            if (err instanceof DataFileError) {
+                problems.push({ line: i + 1, message: `::${name}: ${err.message}`, file: err.file, fileLine: err.line });
+            }
+            else if (err instanceof DirectiveError) {
+                problems.push({ line: i + 1, message: `::${name}: ${err.message}` });
+            }
+            else
+                throw err;
+            out.push(line);
+        }
+    }
+    return { text: out.join("\n"), reads, problems };
+}
+class DirectiveError extends Error {
+}
+/** Whether an HTML comment is open after this line. */
+function commentOpenAfter(line, open) {
+    let at = 0;
+    for (;;) {
+        if (open) {
+            const end = line.indexOf("-->", at);
+            if (end < 0)
+                return true;
+            open = false;
+            at = end + 3;
+        }
+        else {
+            const start = line.indexOf("<!--", at);
+            if (start < 0)
+                return false;
+            open = true;
+            at = start + 4;
+        }
+    }
+}
+function stringProp(props, key) {
+    const v = props[key];
+    if (typeof v !== "string" || v.trim() === "")
+        throw new DirectiveError(`needs ${key}="…"`);
+    return v;
+}
+const own = (o, key) => o !== null && typeof o === "object" && Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+/** The list of rows the directive reads: the file, or `path="a.b"` inside it. */
+function rowsOf(value, file, path, name) {
+    let at = value;
+    if (typeof path === "string" && path.trim()) {
+        for (const seg of path.trim().split(".")) {
+            at = Array.isArray(at) && /^\d+$/.test(seg) ? at[Number(seg)] : own(at, seg);
+            if (at === undefined)
+                throw new DirectiveError(`${file} has nothing at path "${path}"`);
+        }
+    }
+    if (!Array.isArray(at)) {
+        const what = at !== null && typeof at === "object" ? "an object" : `a ${typeof at}`;
+        throw new DirectiveError(`${file}${typeof path === "string" ? ` at "${path}"` : ""} is ${what}, not a list${what === "an object" ? `; name the list in it with path="…"` : ""}`);
+    }
+    at.forEach((row, n) => {
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new DirectiveError(`${file}: item ${n + 1} is not an object with named fields, so ::${name} cannot read columns from it`);
+        }
+    });
+    return at;
+}
+/** A value as one line of text: scalars as written, a list of scalars joined, nothing else. */
+function cellText(v, file, key) {
+    if (v === undefined || v === null)
+        return "";
+    if (typeof v === "string")
+        return v.replace(/\s+/g, " ").trim();
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (Array.isArray(v) && v.every((x) => x === null || ["string", "number", "boolean"].includes(typeof x))) {
+        return v.map((x) => (x === null ? "" : String(x).replace(/\s+/g, " ").trim())).join(", ");
+    }
+    throw new DirectiveError(`${file}: "${key}" holds ${Array.isArray(v) ? "a list of objects" : "an object"}, which a cell cannot show`);
+}
+/**
+ * A value as a text node. Characters the serializer's text escaping leaves live are written as
+ * character references: `{` and `}` (it keeps `{{ }}` / `{% %}` verbatim as authored template
+ * syntax, and a trailing `{…}` is read as attributes), `$` (math), `~` (`~~x~~` struck
+ * through) and `|` (a cell boundary wherever `| text` lands in a table row). `&` too, so the
+ * value's own `&amp;` stays those characters.
+ */
+const ENTITY = { "&": "&amp;", "{": "&#123;", "}": "&#125;", $: "&#36;", "~": "&#126;", "|": "&#124;" };
+const text = (t) => ({ type: "text", text: t.replace(/[&{}$~|]/g, (c) => ENTITY[c]) });
+/**
+ * A value as Markdown that reads back as exactly that text, on one line: the encoding a table
+ * cell gets, for a template page's `| text` filter. `*`, `<x>`, `[a](b)`, `{{ }}`, `|`, `$`,
+ * `~~` and a leading `- ` all show as written; a list of values is joined with ", " as in a
+ * cell, and an object is an error. Its output is entity-encoded, so `text` goes last in a chain.
+ */
+export function literalMarkdown(value) {
+    let s;
+    try {
+        s = cellText(value, "| text", "value");
+    }
+    catch {
+        throw new Error("`| text` shows a value, or a list of values, not an object; pick a field (`x.name | text`)");
+    }
+    if (!s)
+        return "";
+    return treeToDogsbayMd([{ type: "paragraph", inline: [text(s)] }]).replace(/\n+$/, "");
+}
+/**
+ * `{{ value | code }}`: the value as inline code, on one line, in a fence its own backticks
+ * cannot close. Template pages never evaluate inside a code span written in the page, so this is
+ * how a value is shown as code. In a table cell, follow it with `| replace("|", "\\|")`.
+ */
+export function literalCode(value) {
+    let s;
+    try {
+        s = cellText(value, "| code", "value");
+    }
+    catch {
+        throw new Error("`| code` shows a value, or a list of values, not an object; pick a field (`x.name | code`)");
+    }
+    s = s.replace(/\s*[\r\n]+\s*/g, " ");
+    if (!s)
+        return "";
+    return treeToDogsbayMd([{ type: "paragraph", inline: [{ type: "code", text: s }] }]).replace(/\n+$/, "");
+}
+const list = (v) => typeof v === "string" && v.trim() ? v.split(",").map((s) => s.trim()) : undefined;
+function tableNode(rows, props, file) {
+    const columns = list(props.columns) ?? [...new Set(rows.flatMap((r) => Object.keys(r)))];
+    if (columns.length === 0)
+        throw new DirectiveError(`${file} has no columns to show`);
+    const headers = list(props.headers) ?? columns;
+    if (headers.length !== columns.length) {
+        throw new DirectiveError(`headers names ${headers.length} column(s), columns ${columns.length}`);
+    }
+    const tr = (cells, tag) => ({
+        type: "tr",
+        children: cells.map((c) => ({ type: tag, inline: c ? [text(c)] : [] })),
+    });
+    return {
+        type: "table",
+        children: [tr(headers, "th"), ...rows.map((r) => tr(columns.map((k) => cellText(own(r, k), file, k)), "td"))],
+    };
+}
+function cardsNode(rows, props, file) {
+    const titleKey = typeof props.title === "string" ? props.title : "title";
+    const descKey = typeof props.description === "string" ? props.description : "description";
+    const hrefKey = typeof props.href === "string" ? props.href : "href";
+    const iconKey = typeof props.icon === "string" ? props.icon : "icon";
+    const cards = rows.map((r, n) => {
+        const title = cellText(own(r, titleKey), file, titleKey);
+        if (!title)
+            throw new DirectiveError(`${file}: item ${n + 1} has no "${titleKey}" for the card title`);
+        const cardProps = { title };
+        const href = cellText(own(r, hrefKey), file, hrefKey);
+        if (href) {
+            if (!isSafeHref(href))
+                throw new DirectiveError(`${file}: item ${n + 1}'s "${hrefKey}" is not a link a page may carry`);
+            cardProps.href = href;
+        }
+        const icon = cellText(own(r, iconKey), file, iconKey);
+        if (icon)
+            cardProps.icon = icon;
+        const desc = cellText(own(r, descKey), file, descKey);
+        return {
+            type: "card",
+            props: cardProps,
+            children: desc ? [{ type: "paragraph", inline: [text(desc)] }] : [],
+        };
+    });
+    return { type: "cards", children: cards };
+}

package/dist/data-files.d.ts

@@ -0,0 +1,99 @@
+/** A data file could not be read. `line` is 1-based, in the data file. */
+export declare class DataFileError extends Error {
+    readonly file: string;
+    readonly line?: number | undefined;
+    constructor(message: string, file: string, line?: number | undefined);
+}
+export interface DataLimits {
+    /** Bytes of one data file's text. */
+    maxFileBytes: number;
+    /** Bytes of all data files one `DataFiles` reads (one build). */
+    maxTotalBytes: number;
+    /** Values one file may expand to (every scalar, list and object counts one; aliases count each use). */
+    maxValues: number;
+    /** Nesting depth of one file. */
+    maxDepth: number;
+    /** Rows of a CSV/TSV file, header excluded. */
+    maxRows: number;
+    /** Columns of a CSV/TSV file. */
+    maxColumns: number;
+    /** Characters of one CSV/TSV cell. */
+    maxCellChars: number;
+}
+export declare const DEFAULT_DATA_LIMITS: DataLimits;
+/**
+ * Limits for a build of content nobody vetted (a playground link, a public
+ * repo, the Worker). A host forces these whatever the site's config says.
+ */
+export declare const UNTRUSTED_DATA_LIMITS: DataLimits;
+/** The extensions a data file may have, in the order a bare name tries them. */
+export declare const DATA_EXTENSIONS: readonly ["yml", "yaml", "json", "csv", "tsv"];
+export type DataExtension = (typeof DATA_EXTENSIONS)[number];
+/**
+ * CSV (RFC 4180) or TSV, header row first: a list of objects keyed by the
+ * header. Values stay strings (`007` is not 7). Quoted fields may hold the
+ * delimiter, `""` and newlines; CRLF and a leading BOM are read. A ragged row
+ * or an unclosed quote is an error naming its line, never a shifted column.
+ */
+export declare function parseDelimited(text: string, delimiter: "," | "\t", file: string, limits?: DataLimits): Record<string, string>[];
+/** Parse one data file by its extension. Throws DataFileError. */
+export declare function parseDataFile(path: string, text: string, limits?: DataLimits): {
+    value: unknown;
+    weight: number;
+};
+/** Parsed data files kept by weight, least recently used dropped first. */
+export declare class DataCache {
+    readonly maxBytes: number;
+    private readonly map;
+    private bytes;
+    private hits;
+    private misses;
+    constructor(maxBytes?: number);
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown, weight: number): void;
+    clear(): void;
+    stats(): {
+        entries: number;
+        bytes: number;
+        maxBytes: number;
+        hits: number;
+        misses: number;
+    };
+}
+export interface DataFilesOptions {
+    /**
+     * Read a file by path relative to the data folder (`felix/params.yml`);
+     * undefined when it does not exist. The host contains it.
+     */
+    load: (path: string) => string | undefined | Promise<string | undefined>;
+    limits?: DataLimits;
+    /** Shared between builds (a dev session, the Worker). Parses are keyed by path and text. */
+    cache?: DataCache;
+}
+/**
+ * The data files of one build. `get(name)` reads `name` (extension
+ * optional: `releases` finds `releases.yml`, `.yaml`, `.json`, `.csv` or
+ * `.tsv`, and two of them is an error). `read` also says which file it was,
+ * so a page can report the files it read and a host rebuild only those pages
+ * when one changes; the record is per call, as pages render concurrently.
+ */
+export declare class DataFiles {
+    private readonly options;
+    private readonly limits;
+    private readonly cache;
+    private total;
+    private readonly counted;
+    constructor(options: DataFilesOptions);
+    /** Resolve a name to the file it reads, without parsing it. Throws DataFileError. */
+    resolve(name: string): Promise<{
+        path: string;
+        text: string;
+    }>;
+    /** The parsed contents of a data file. Throws DataFileError. */
+    get(name: string): Promise<unknown>;
+    /** The parsed contents of a data file, and its path in the data folder. Throws DataFileError. */
+    read(name: string): Promise<{
+        path: string;
+        value: unknown;
+    }>;
+}