@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/render.d.ts

@@ -0,0 +1,134 @@
+import { SitefileError, type SourceSpan } from './errors.js';
+import type { EscapeMode } from './language/ast.js';
+import type { Scalar } from './values.js';
+import { type TemplateTree } from './media.js';
+/** A string of a `${file …}` expression: text and `${name.key}` references. */
+export type HelperText = ReadonlyArray<{
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'ref';
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly span: SourceSpan;
+}>;
+/**
+ * Resolves a template variable to a scalar. Supplied by the executor, which
+ * throws E_UNDEFINED / E_TYPE itself for unknown names or non-scalar values.
+ */
+export type TemplateLookup = (name: string, path: readonly string[], span: SourceSpan) => Scalar;
+/**
+ * Resolves a value for `${#each}` and `${#if}`. `loose` (used by `#if`) means a
+ * missing name or key yields `undefined` instead of an error.
+ */
+export type TemplateValueLookup = (name: string, path: readonly string[], span: SourceSpan, loose: boolean) => unknown;
+/** A parsed RENDER template: text, substitutions and blocks. */
+export type TemplateNode = {
+    readonly kind: 'text';
+    readonly value: string;
+}
+/** `raw` is set (true) only for `${x|raw}`, which is never escaped. */
+ | {
+    readonly kind: 'var';
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly span: SourceSpan;
+    readonly raw?: true;
+} | {
+    readonly kind: 'each';
+    readonly list: Ref;
+    readonly as: string;
+    readonly body: readonly TemplateNode[];
+    readonly empty: readonly TemplateNode[];
+    readonly span: SourceSpan;
+}
+/** `${file "<path>" [| helper attr…]}`: markup or a value for a file of the RENDER's tree (src/media.ts). */
+ | {
+    readonly kind: 'file';
+    readonly path: HelperText;
+    readonly helper?: string;
+    readonly attrs: ReadonlyArray<{
+        readonly name: string;
+        readonly value?: HelperText;
+    }>;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'if';
+    readonly cond: Ref;
+    readonly negate: boolean;
+    readonly then: readonly TemplateNode[];
+    readonly otherwise: readonly TemplateNode[];
+    readonly span: SourceSpan;
+};
+interface Ref {
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly span: SourceSpan;
+}
+/**
+ * Parse a RENDER template.
+ *
+ * - `${name}` / `${name.seg.seg}` substitutes a value (segments may be array
+ *   indexes); `${name|raw}` substitutes it without escaping.
+ * - `${#each list as item}…${else}…${/each}` repeats for each element of a list
+ *   (the `${else}` part renders when the list is empty). A missing key such as
+ *   `post.tags` counts as an empty list; an unknown top-level name is an error.
+ * - `${#if x}…${else}…${/if}` / `${#if !x}`: false, null, missing, '', 0 and
+ *   empty lists are falsy.
+ * - A block tag alone on its line removes that whole line from the output.
+ * - `$${` writes a literal `${`; a `$` not followed by `{` is literal.
+ * - Anything else inside `${…}`, or unbalanced blocks, fails with E_TEMPLATE.
+ */
+export declare function parseRenderTemplate(text: string, file: string, firstLine?: number, firstColumn?: number): TemplateNode[];
+/** Every `${name}` reference of a `${file …}` expression, in order. */
+export declare function fileRefs(n: Extract<TemplateNode, {
+    kind: 'file';
+}>): Array<Extract<HelperText[number], {
+    kind: 'ref';
+}>>;
+/** A name a template reads from outside itself (not a `${#each}` variable of its own), in template order. */
+export interface FreeRef {
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly span: SourceSpan;
+    /** `var`: `${name…}`; `each`: the list of `${#each}`; `if`: the condition of `${#if}`; `text`: inside a `${file …}` string. */
+    readonly use: 'var' | 'each' | 'if' | 'text';
+}
+/** The names a template reads that its own `${#each}` blocks do not bind, in order. */
+export declare function freeRefs(nodes: readonly TemplateNode[]): FreeRef[];
+/** What renderTemplate needs beyond values: html fragments (`LET name: html`, `IMPORT … AS html`). */
+export interface TemplateContext {
+    /** Whether `name` is an html fragment (checked after loop variables, before `lookup`). */
+    readonly isFragment?: (name: string) => boolean;
+    /** The parsed template of fragment `name` (may throw, e.g. E_TEMPLATE for an imported partial). */
+    readonly fragment?: (name: string) => readonly TemplateNode[];
+    /** The stage's tree at this RENDER, for `${file …}`. */
+    readonly tree?: TemplateTree;
+    /** RENDER --inline-svg. */
+    readonly inlineSvg?: boolean;
+}
+/** E_TYPE for a fragment used where a value is needed. */
+export declare function fragmentNotValue(name: string, span: SourceSpan): SitefileError;
+/**
+ * Render a parsed template. `lookup` resolves scalars; `values` resolves lists
+ * and conditions for blocks (needed only if the template has blocks). Loop
+ * variables are resolved here and shadow every other name. Escaping applies to
+ * substituted values only, never to template text or `|raw` values.
+ */
+export declare function renderTemplate(nodes: readonly TemplateNode[], lookup: TemplateLookup, escape: EscapeMode, values?: TemplateValueLookup, ctx?: TemplateContext): string;
+export declare function isTruthy(v: unknown): boolean;
+/**
+ * Walk `value` along `path`. Strict mode fails like resolveJsonPath on a
+ * missing key; loose mode returns undefined. Any value type may be returned.
+ */
+export declare function walk(value: unknown, path: readonly string[], name: string, span: SourceSpan, loose: boolean): unknown;
+export declare function escapeHtml(s: string): string;
+/** Decode strict UTF-8 (E_ENCODING on invalid bytes), stripping a leading BOM. */
+export declare function decodeUtf8(bytes: Uint8Array, what: string, span?: SourceSpan): string;
+/**
+ * Walk a parsed JSON value along `path` and return the scalar found there.
+ * Missing keys/indexes fail with E_UNDEFINED; null, objects and arrays fail
+ * with E_TYPE. Messages name the full dotted path.
+ */
+export declare function resolveJsonPath(value: unknown, path: readonly string[], name: string, span: SourceSpan): Scalar;
+export {};