@zvndev/darkmown 0.19.0 → 1.0.0

package/src/compiler/format.js

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// Format pipes — the value layer. `{ value | name:arg:arg | name2 }` runs a
+// resolved value through a whitelist of formatters; `{ list | sum:"price" }`
+// aggregates a list. The same formatter math is mirrored, compactly, in
+// src/runtime.js for the reactive path — tests/format.test.js + the compile↔
+// runtime parity test guard against drift. Nothing here is eval'd: pipe stages
+// are a fixed, compile-time-validated registry, exactly like the predicate and
+// action grammars.
+//
+// Folds at build time when the piped value is static (zero-JS); a value that
+// reads :state/:store emits `data-wd-fmt` and re-formats in the runtime.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {{ name: string, args: Array<string | number | boolean | null> }} Stage
+ */
+
+// --- shared math (kept tiny and mirrored in the runtime) -------------------
+
+/** @param {unknown} v @returns {number} */
+const toNum = (v) => {
+  const n = typeof v === "number" ? v : Number.parseFloat(String(v));
+  return Number.isFinite(n) ? n : 0;
+};
+/** @param {unknown} v @returns {any[]} */
+const toList = (v) => (Array.isArray(v) ? v : v == null ? [] : [v]);
+/** Read one shallow field off a row, or the row itself when no field is given. */
+const pick = (/** @type {any} */ row, /** @type {string} */ f) =>
+  f != null && f !== "" ? (row == null ? undefined : row[f]) : row;
+/** @param {any[]} list @param {string} f @returns {number[]} */
+const nums = (list, f) => list.map((row) => toNum(pick(row, f)));
+
+/**
+ * Coerce ISO strings, epoch milliseconds (number or numeric string), or a Date
+ * into a Date. Returns an invalid Date for unparseable input (formatters guard).
+ * @param {unknown} v
+ * @returns {Date}
+ */
+function toDate(v) {
+  if (v instanceof Date) return v;
+  if (typeof v === "number") return new Date(v);
+  const s = String(v).trim();
+  return /^-?\d+$/.test(s) ? new Date(Number(s)) : new Date(s);
+}
+
+/** @param {Date} d @param {Intl.DateTimeFormatOptions} opts @param {string} fallback */
+const fmtDate = (d, opts, fallback) =>
+  Number.isNaN(d.getTime()) ? String(fallback) : new Intl.DateTimeFormat(undefined, opts).format(d);
+
+// --- aggregates (shared by pipes and `:computed`) --------------------------
+
+/** @type {Record<string, (list: any[], field?: string) => number>} */
+export const AGGREGATES = {
+  sum: (list, f) => nums(list, f || "").reduce((a, n) => a + n, 0),
+  avg: (list, f) => (list.length ? AGGREGATES.sum(list, f) / list.length : 0),
+  min: (list, f) => (list.length ? Math.min(...nums(list, f || "")) : 0),
+  max: (list, f) => (list.length ? Math.max(...nums(list, f || "")) : 0),
+  count: (list) => list.length
+};
+
+// --- the formatter registry ------------------------------------------------
+
+/**
+ * The whitelist. Each formatter is a pure function of (value, args) — no clock,
+ * no DOM, no globals beyond `Intl` — so a static value folds deterministically at
+ * build time and a reactive value formats identically in the browser.
+ * @type {Record<string, (value: any, args: any[]) => string | number>}
+ */
+export const FORMATTERS = {
+  // numbers / money
+  money: (v, [currency = "USD", locale]) =>
+    new Intl.NumberFormat(locale || undefined, {
+      style: "currency",
+      currency: String(currency || "USD")
+    }).format(toNum(v)),
+  number: (v, [dec]) =>
+    new Intl.NumberFormat(
+      undefined,
+      dec == null ? {} : { minimumFractionDigits: +dec, maximumFractionDigits: +dec }
+    ).format(toNum(v)),
+  percent: (v, [dec = 0]) =>
+    new Intl.NumberFormat(undefined, {
+      style: "percent",
+      minimumFractionDigits: +dec,
+      maximumFractionDigits: +dec
+    }).format(toNum(v)),
+  round: (v, [dec = 0]) => {
+    const p = 10 ** +dec;
+    return Math.round(toNum(v) * p) / p;
+  },
+  // dates (format a given instant — pure, no "now")
+  date: (v, [style = "medium"]) => fmtDate(toDate(v), { dateStyle: /** @type {any} */ (style) }, v),
+  time: (v, [style = "short"]) => fmtDate(toDate(v), { timeStyle: /** @type {any} */ (style) }, v),
+  datetime: (v, [ds = "medium", ts = "short"]) =>
+    fmtDate(
+      toDate(v),
+      { dateStyle: /** @type {any} */ (ds), timeStyle: /** @type {any} */ (ts) },
+      v
+    ),
+  // text
+  upper: (v) => String(v ?? "").toUpperCase(),
+  lower: (v) => String(v ?? "").toLowerCase(),
+  capitalize: (v) => {
+    const s = String(v ?? "");
+    return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+  },
+  truncate: (v, [length = 50, suffix = "…"]) => {
+    const s = String(v ?? "");
+    return s.length > +length ? s.slice(0, +length).trimEnd() + String(suffix) : s;
+  },
+  trim: (v) => String(v ?? "").trim(),
+  pluralize: (v, [singular = "", plural]) => {
+    const n = toNum(v);
+    const word =
+      Math.abs(n) === 1 ? String(singular) : plural != null ? String(plural) : `${singular}s`;
+    return `${new Intl.NumberFormat().format(n)} ${word}`;
+  },
+  default: (v, [fallback = ""]) => {
+    const empty = v == null || v === "" || (Array.isArray(v) && v.length === 0);
+    return empty ? String(fallback) : v;
+  },
+  // aggregates (operate on a list)
+  sum: (v, [f]) => AGGREGATES.sum(toList(v), f),
+  avg: (v, [f]) => AGGREGATES.avg(toList(v), f),
+  min: (v, [f]) => AGGREGATES.min(toList(v), f),
+  max: (v, [f]) => AGGREGATES.max(toList(v), f),
+  count: (v) => AGGREGATES.count(toList(v)),
+  join: (v, [sep = ", ", f]) =>
+    toList(v)
+      .map((row) => pick(row, /** @type {string} */ (f)))
+      .join(String(sep))
+};
+
+/** Formatter names, for error messages and the runtime mirror check. */
+export const FORMATTER_NAMES = Object.keys(FORMATTERS);
+
+// --- parsing ---------------------------------------------------------------
+
+/**
+ * Split a string on a separator that is not inside a quoted run. Keeps pipe
+ * arguments like `"a | b"` or `":"` intact.
+ * @param {string} s
+ * @param {string} sep single character
+ * @returns {string[]}
+ */
+function splitTop(s, sep) {
+  /** @type {string[]} */
+  const out = [];
+  let cur = "";
+  let quote = "";
+  for (const c of s) {
+    if (quote) {
+      cur += c;
+      if (c === quote) quote = "";
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      cur += c;
+    } else if (c === sep) {
+      out.push(cur);
+      cur = "";
+    } else cur += c;
+  }
+  out.push(cur);
+  return out;
+}
+
+/** @param {string} t @returns {string | number | boolean | null} */
+function parseArg(t) {
+  const v = t.trim();
+  if (/^"[^"]*"$/.test(v) || /^'[^']*'$/.test(v)) return v.slice(1, -1);
+  if (/^-?\d+(?:\.\d+)?$/.test(v)) return Number(v);
+  if (v === "true") return true;
+  if (v === "false") return false;
+  if (v === "null") return null;
+  return v;
+}
+
+/**
+ * Parse the inside of a `{ … }` binding into its path and an ordered list of
+ * pipe stages. `{ price | money }` → `{ path: "price", stages: [{name:"money",args:[]}] }`.
+ * Stage validation (unknown formatter) happens in {@link validatePipes}.
+ * @param {string} inner
+ * @returns {{ path: string, stages: Stage[] }}
+ */
+export function parsePipes(inner) {
+  const segs = splitTop(inner, "|");
+  const path = segs[0].trim();
+  /** @type {Stage[]} */
+  const stages = [];
+  for (let i = 1; i < segs.length; i++) {
+    const raw = segs[i].trim();
+    const m = /^([A-Za-z][A-Za-z0-9_]*)\s*(?::([\s\S]*))?$/.exec(raw);
+    if (!m) return { path, stages: [{ name: raw, args: [] }] }; // malformed → flagged by validate
+    stages.push({ name: m[1], args: m[2] == null ? [] : splitTop(m[2], ":").map(parseArg) });
+  }
+  return { path, stages };
+}
+
+/**
+ * Compile-time validation: every stage must name a known formatter. Throws a
+ * corrective compile error otherwise. Returns the parsed `{ path, stages }`.
+ * @param {string} inner
+ * @param {Ctx} ctx
+ * @returns {{ path: string, stages: Stage[] }}
+ */
+export function validatePipes(inner, ctx) {
+  const parsed = parsePipes(inner);
+  for (const stage of parsed.stages) {
+    if (!Object.hasOwn(FORMATTERS, stage.name)) {
+      throw new Error(
+        `Unknown formatter "${stage.name}" in { ${inner} } (${ctx.file}). Available: ${FORMATTER_NAMES.join(", ")}.`
+      );
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Run a resolved value through a pipe chain at build time. Returns the final
+ * value (a string or number); the caller stringifies for output. Mirrors the
+ * runtime's `applyFmt`.
+ * @param {any} value
+ * @param {Stage[]} stages
+ * @returns {any}
+ */
+export function applyPipeline(value, stages) {
+  let out = value;
+  for (const stage of stages) out = FORMATTERS[stage.name](out, stage.args);
+  return out;
+}
+
+/** Serialize stages to the compact `[[name,[args]]]` form carried in data-wd-fmt. */
+export const fmtAttr = (/** @type {Stage[]} */ stages) =>
+  JSON.stringify(stages.map((s) => [s.name, s.args]));
+
+/**
+ * Parse a `data-wd-fmt` JSON payload (already HTML-decoded) back into stages.
+ * Mirrors the runtime's own parse so the initial paint and the live update agree.
+ * @param {string} json
+ * @returns {Stage[]}
+ */
+export const stagesFromAttr = (json) =>
+  /** @type {[string, any[]][]} */ (JSON.parse(json)).map(([name, args]) => ({ name, args }));

package/src/compiler/frontmatter.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// Frontmatter: split a raw file into `meta` + `body`, parse inline scalar/array
+// values, and warn when a file looks like it forgot the opening `---`.
+// ---------------------------------------------------------------------------
+
+import { stripQuotes } from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("./context.js").FrontmatterValue} FrontmatterValue
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+
+/**
+ * Split a raw file into its frontmatter `meta` and `body`.
+ * @param {string} raw Full file contents.
+ * @param {string} [file] Source path, used only for error messages.
+ * @returns {{ meta: Meta, body: string }}
+ */
+export function parseFrontmatter(raw, file) {
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end === -1) {
+    const where = file ? ` in ${file}` : "";
+    throw new Error(
+      `Unterminated frontmatter${where}: opening "---" has no closing "---". Use: --- on its own line to open and another --- to close, then the page body.`
+    );
+  }
+  const front = raw.slice(4, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+  /** @type {Meta} */
+  const meta = {};
+  for (const line of front.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
+  }
+  return { meta, body };
+}
+
+/**
+ * Warn (non-fatal) when a file looks like it MEANT to open frontmatter but forgot
+ * the leading `---`: the first content line is a `key: value` pair and a bare
+ * `---` fence appears within the opening lines. Conservative — a normal markdown
+ * body whose first line happens to contain a colon (with no early `---`) is left
+ * alone, since `---` is also a valid horizontal rule.
+ * @param {string} raw
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function warnLikelyFrontmatter(raw, file, comp) {
+  if (raw.startsWith("---\n")) return; // a real opener: parseFrontmatter handled it
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++; // skip leading blanks
+  if (i >= lines.length || !/^[A-Za-z][\w-]*:\s*\S/.test(lines[i])) return;
+  // Only warn when the run of lines up to a bare `---` is ALL `key: value` pairs:
+  // a forgotten opener, not prose that merely contains a colon and a later rule.
+  for (let j = i; j < lines.length && j < i + 12; j++) {
+    const t = lines[j].trim();
+    if (t === "---") {
+      comp.warnings.push(
+        `${file}: this looks like frontmatter missing its opening "---". Use: a "---" line before the fields (and another "---" to close) — otherwise the block renders as page text.`
+      );
+      return;
+    }
+    if (t && !/^[A-Za-z][\w-]*:\s*\S/.test(t)) return; // hit prose → not frontmatter
+  }
+}
+
+// Frontmatter values are scalars, except an inline flow array `[a, b, c]`.
+// Block sequences (`- item` on following lines) are intentionally out of scope —
+// the parser stays single-pass and line-based.
+/**
+ * @param {string} raw
+ * @returns {FrontmatterValue}
+ */
+function parseFrontmatterValue(raw) {
+  const value = raw.trim();
+  if (value.startsWith("[") && value.endsWith("]")) return parseInlineArray(value);
+  return stripQuotes(value);
+}
+
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
+function parseInlineArray(raw) {
+  const inner = raw.slice(1, -1);
+  if (inner.trim() === "") return [];
+  /** @type {string[]} */
+  const items = [];
+  let buf = "";
+  let quote = null;
+  let quoted = false;
+  const push = () => {
+    items.push(quoted ? buf : buf.trim());
+    buf = "";
+    quoted = false;
+  };
+  for (const char of inner) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else buf += char;
+    } else if ((char === '"' || char === "'") && buf.trim() === "") {
+      quote = char;
+      quoted = true;
+      buf = ""; // drop any whitespace between the comma and the opening quote
+    } else if (char === ",") {
+      push();
+    } else {
+      buf += char;
+    }
+  }
+  push();
+  return items;
+}

package/src/compiler/includes.js

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// Includes / assets: resolve `@include` (and `@loop` data) targets to absolute
+// paths inside `site/pages` or `site/_`, register colocated `.skin`/`.js`
+// siblings, and warn when a plain `.md` file uses `.wd`-only syntax.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { pageIncludeExtensions } from "./context.js";
+import { stripQuotes } from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Assets} Assets
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+
+/**
+ * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {Assets} assets
+ * @returns {void}
+ */
+export function collectColocatedAssets(file, context, assets) {
+  const ext = path.extname(file);
+  const stem = file.slice(0, -ext.length);
+  for (const [assetExt, folder] of [
+    [".skin", "styles"],
+    [".js", "scripts"]
+  ]) {
+    const candidate = `${stem}${assetExt}`;
+    if (!fs.existsSync(candidate)) continue;
+    const rel = path.relative(context.cwd, candidate).replaceAll(path.sep, "/");
+    const outputExt = assetExt === ".skin" ? ".css" : ".js";
+    const publicPath = `/__wd/${folder}/${rel.slice(0, -assetExt.length).replace(/[/.]/g, "_")}${outputExt}`;
+    assets.files.set(candidate, publicPath);
+    if (assetExt === ".skin") assets.skins.add(publicPath);
+    if (assetExt === ".js") assets.scripts.add(publicPath);
+  }
+}
+
+/**
+ * Resolve an include spec to an absolute path inside `site/pages` or `site/_`.
+ * @param {string} spec Include target (may be quoted).
+ * @param {string} fromFile File requesting the include.
+ * @param {Paths} context
+ * @param {boolean} [allowAny] Allow non-page extensions (e.g. JSON for `@loop`).
+ * @returns {string}
+ */
+export function resolveInclude(spec, fromFile, context, allowAny = false) {
+  const clean = stripQuotes(spec);
+  const candidates = [];
+  if (clean.startsWith("/")) {
+    candidates.push(path.join(context.shelfRoot, clean.slice(1)));
+  } else {
+    candidates.push(path.resolve(path.dirname(fromFile), clean));
+    candidates.push(path.join(context.shelfRoot, clean));
+  }
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (!isAllowedInclude(resolved, context)) {
+      throw new Error(`Include "${spec}" from ${fromFile} resolves outside site/pages or site/_`);
+    }
+    if (!fs.existsSync(resolved)) continue;
+    if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
+    return resolved;
+  }
+  throw new Error(`Could not resolve include "${spec}" from ${fromFile}`);
+}
+
+/**
+ * @param {string} file
+ * @param {Paths} context
+ * @returns {boolean}
+ */
+export function isAllowedInclude(file, context) {
+  const roots = [context.routesRoot, context.shelfRoot].map((root) => path.resolve(root));
+  return roots.some((root) => file === root || file.startsWith(`${root}${path.sep}`));
+}
+
+// ---------------------------------------------------------------------------
+// Plain .md hints
+// ---------------------------------------------------------------------------
+
+/**
+ * Warn when a plain `.md` file contains `.wd`-only syntax that stays inert.
+ * @param {string} body
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function scanMarkdownHints(body, file, comp) {
+  let fence = null;
+  for (const line of body.split("\n")) {
+    const fenceMatch = line.match(/^(```+|~~~+)/);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    const hit = line.match(
+      /^(@include|@loop|@repeat|:state|:button|:if|:for|:try|:note|:sprint|:::)(\s|$)/
+    );
+    if (hit) {
+      comp.warnings.push(
+        `${file}: "${hit[1]}" is .wd syntax and stays plain text in .md — rename the file to .wd to activate it.`
+      );
+      return;
+    }
+  }
+}

package/src/compiler/index.js

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// Compiler module wiring. The compiler is split across cohesive seams:
+//
+//   context.js        shared typedefs + tiny helpers (createCompilation, at, …)
+//   interpolation.js  path/value resolution, state-key lookup, escapeHtml, literals
+//   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
+//   includes.js       @include / @loop-data resolution, colocated assets, .md hints
+//   predicates.js     where / when / :if / :computed expression compilers
+//   markdown.js       markdown-it instances + plugins + prose interpolation
+//   loops.js          @loop pipeline + row-template initial-paint fill
+//   directives.js     the handle* family + :button action parser + demo directives
+//   body.js           the line-based directive dispatcher (compileBody)
+//   page.js           HTML page shell, image hardening, per-file compile
+//
+// This barrel re-exports the public API; `src/compiler.js` re-exports from here
+// so every existing `import … from "./compiler.js"` keeps working unchanged.
+// ---------------------------------------------------------------------------
+
+export { parseFrontmatter } from "./frontmatter.js";
+export { escapeHtml } from "./interpolation.js";
+export { loopKeyOf } from "./loops.js";
+export { compileDocument, compilePage, enhanceImages } from "./page.js";