@wdprlib/render 2.0.0 → 3.0.0

package/src/elements/embed-block/allowlist.ts

@@ -0,0 +1,60 @@
+/**
+ * Allowlist entry for embed content validation.
+ */
+export interface EmbedAllowlistEntry {
+  /** Host pattern. Supports wildcard prefix `*.` such as `*.youtube.com`. */
+  host: string;
+  /** Optional path prefix that must match, such as `/embed/`. */
+  pathPrefix?: string;
+}
+
+/**
+ * Default allowlist for embed content.
+ *
+ * Set the render option to `null` to allow any HTTP(S) iframe while still using
+ * sanitizer and scheme validation.
+ */
+export const DEFAULT_EMBED_ALLOWLIST: EmbedAllowlistEntry[] | null = [
+  { host: "*.youtube.com", pathPrefix: "/embed/" },
+  { host: "*.youtube-nocookie.com", pathPrefix: "/embed/" },
+  { host: "player.vimeo.com", pathPrefix: "/video/" },
+  { host: "*.google.com", pathPrefix: "/maps/embed" },
+  { host: "calendar.google.com", pathPrefix: "/calendar/embed" },
+  { host: "open.spotify.com", pathPrefix: "/embed/" },
+  { host: "w.soundcloud.com", pathPrefix: "/player/" },
+  { host: "codepen.io" },
+];
+
+/**
+ * Check whether a URL matches an allowlist entry's host and optional path prefix.
+ */
+export function matchesAllowlistEntry(url: URL, entry: EmbedAllowlistEntry): boolean {
+  if (!matchesHostPattern(url.hostname, entry.host)) {
+    return false;
+  }
+  if (entry.pathPrefix) {
+    const pathLower = url.pathname.toLowerCase();
+    const prefixLower = entry.pathPrefix.toLowerCase();
+    if (!pathLower.startsWith(prefixLower)) {
+      return false;
+    }
+    if (!prefixLower.endsWith("/")) {
+      const remainder = pathLower.slice(prefixLower.length);
+      if (remainder && !/^[/?#]/.test(remainder)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function matchesHostPattern(hostname: string, pattern: string): boolean {
+  const lowerHostname = hostname.toLowerCase();
+  const lowerPattern = pattern.toLowerCase();
+
+  if (lowerPattern.startsWith("*.")) {
+    const base = lowerPattern.slice(2);
+    return lowerHostname === base || lowerHostname.endsWith("." + base);
+  }
+  return lowerHostname === lowerPattern;
+}

package/src/elements/embed-block/boolean-attributes.ts

@@ -0,0 +1,38 @@
+const BOOLEAN_ATTRIBUTES = [
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "ismap",
+  "loop",
+  "multiple",
+  "muted",
+  "novalidate",
+  "open",
+  "readonly",
+  "required",
+  "reversed",
+  "selected",
+];
+
+/**
+ * Normalize HTML boolean attributes to Wikidot's `attr="attr"` format.
+ */
+export function normalizeBooleanAttributes(html: string): string {
+  let result = html;
+  for (const attr of BOOLEAN_ATTRIBUTES) {
+    const standalonePattern = new RegExp(`\\s${attr}(?=\\s|>|/>)`, "gi");
+    result = result.replace(standalonePattern, ` ${attr}="${attr}"`);
+
+    const emptyValuePattern = new RegExp(`\\s${attr}=""`, "gi");
+    result = result.replace(emptyValuePattern, ` ${attr}="${attr}"`);
+  }
+  return result;
+}

package/src/elements/embed-block/iframe.ts

@@ -0,0 +1,33 @@
+import type { Element } from "domhandler";
+import { parseDocument } from "htmlparser2";
+
+export function findIframes(html: string): Element[] {
+  const doc = parseDocument(html);
+  const iframes: Element[] = [];
+  function walk(nodes: typeof doc.children): void {
+    for (const node of nodes) {
+      if (node.type !== "tag") {
+        continue;
+      }
+      if (node.name === "iframe") {
+        iframes.push(node);
+      }
+      if (node.children) {
+        walk(node.children);
+      }
+    }
+  }
+  walk(doc.children);
+  return iframes;
+}
+
+export function parseIframeUrl(src: string, baseUrl?: string): URL | null {
+  try {
+    if (src.startsWith("//")) {
+      return new URL(src, baseUrl ?? "https://localhost");
+    }
+    return new URL(src);
+  } catch {
+    return null;
+  }
+}

package/src/elements/embed-block/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Renderer for `[[embed]]...[[/embed]]` block-level embeds.
+ *
+ * @module
+ */
+
+import type { EmbedBlockData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { DEFAULT_EMBED_ALLOWLIST, type EmbedAllowlistEntry } from "./allowlist";
+import { normalizeBooleanAttributes, validateAndSanitizeEmbed } from "./sanitize";
+
+export { DEFAULT_EMBED_ALLOWLIST, type EmbedAllowlistEntry } from "./allowlist";
+
+/**
+ * Render an `[[embed]]...[[/embed]]` block element.
+ *
+ * The raw HTML content is validated and sanitized through the full pipeline. On
+ * failure, a Wikidot-compatible error block is shown.
+ */
+export function renderEmbedBlock(ctx: RenderContext, data: EmbedBlockData): void {
+  const allowlist: EmbedAllowlistEntry[] | null =
+    ctx.options.embedAllowlist !== undefined ? ctx.options.embedAllowlist : DEFAULT_EMBED_ALLOWLIST;
+
+  const sanitized = validateAndSanitizeEmbed(data.contents, allowlist, ctx.options.baseUrl);
+  if (sanitized === null) {
+    ctx.push('<div class="error-block">Sorry, no match for the embedded content.</div>');
+    return;
+  }
+
+  ctx.push(normalizeBooleanAttributes(sanitized));
+}

package/src/elements/embed-block/sanitize-config.ts

@@ -0,0 +1,22 @@
+import sanitizeHtml from "sanitize-html";
+
+export const SANITIZE_CONFIG: sanitizeHtml.IOptions = {
+  allowedTags: ["iframe"],
+  allowedAttributes: {
+    iframe: [
+      "class",
+      "src",
+      "style",
+      "allow",
+      "allowfullscreen",
+      "frameborder",
+      "height",
+      "loading",
+      "referrerpolicy",
+      "sandbox",
+      "title",
+      "width",
+    ],
+  },
+  allowedSchemes: ["https", "http"],
+};

package/src/elements/embed-block/sanitize.ts

@@ -0,0 +1,44 @@
+import sanitizeHtml from "sanitize-html";
+import type { EmbedAllowlistEntry } from "./allowlist";
+import { matchesAllowlistEntry } from "./allowlist";
+import { findIframes, parseIframeUrl } from "./iframe";
+import { SANITIZE_CONFIG } from "./sanitize-config";
+
+export { normalizeBooleanAttributes } from "./boolean-attributes";
+
+/**
+ * Validate and sanitize embed block content through a multi-step iframe pipeline.
+ */
+export function validateAndSanitizeEmbed(
+  content: string,
+  allowlist: EmbedAllowlistEntry[] | null,
+  baseUrl?: string,
+): string | null {
+  const sanitized = sanitizeHtml(content.trim(), SANITIZE_CONFIG);
+  if (!sanitized.trim()) {
+    return null;
+  }
+
+  const iframes = findIframes(sanitized);
+  if (iframes.length !== 1) {
+    return null;
+  }
+
+  const src = iframes[0]!.attribs.src?.trim();
+  if (!src) {
+    return null;
+  }
+
+  const url = parseIframeUrl(src, baseUrl);
+  if (url === null) {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return null;
+  }
+  if (allowlist !== null && !allowlist.some((entry) => matchesAllowlistEntry(url, entry))) {
+    return null;
+  }
+
+  return sanitized;
+}

package/src/elements/expr/branch.ts

@@ -0,0 +1,29 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+
+/**
+ * Render a branch's elements, trimming trailing whitespace-only text nodes.
+ *
+ * Wikidot strips trailing whitespace from `#if` / `#ifexpr` branch output.
+ *
+ * @param ctx - The current render context.
+ * @param elements - The branch's element array.
+ */
+export function renderBranchElements(ctx: RenderContext, elements: Element[]): void {
+  renderElements(ctx, elements.slice(0, findBranchRenderLength(elements)));
+}
+
+function findBranchRenderLength(elements: Element[]): number {
+  let lastIdx = elements.length - 1;
+  while (lastIdx >= 0 && isWhitespaceText(elements[lastIdx]!)) {
+    lastIdx--;
+  }
+  return lastIdx + 1;
+}
+
+function isWhitespaceText(element: Element): boolean {
+  return (
+    element.element === "text" && typeof element.data === "string" && element.data.trim() === ""
+  );
+}

package/src/elements/expr/index.ts

@@ -0,0 +1,63 @@
+/**
+ *
+ * Renderers for Wikidot's expression and conditional constructs.
+ *
+ * @module
+ */
+
+import type { ExprData, IfCondData, IfExprData } from "@wdprlib/ast";
+import { isTruthy } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderBranchElements } from "./branch";
+import { evaluateExpressionOutput, evaluateIfExpressionValue } from "./result";
+
+/**
+ * Render a `[[#expr]]` element.
+ *
+ * Evaluates the mathematical expression and outputs the formatted numeric
+ * result. On evaluation error, a Wikidot-compatible error message is
+ * displayed. Empty expressions produce no output.
+ *
+ * @param ctx - The current render context.
+ * @param data - Expression data containing the expression string.
+ */
+export function renderExpr(ctx: RenderContext, data: ExprData): void {
+  const output = evaluateExpressionOutput(data.expression);
+  if (output !== null) {
+    ctx.pushEscaped(output);
+  }
+}
+
+/**
+ * Render a `[[#if]]` conditional element.
+ *
+ * The condition is treated as a string: values `"false"`, `"null"`,
+ * `""`, and `"0"` are falsy; everything else is truthy.
+ *
+ * @param ctx - The current render context.
+ * @param data - If-condition data with condition string and then/else branches.
+ */
+export function renderIf(ctx: RenderContext, data: IfCondData): void {
+  renderBranchElements(ctx, isTruthy(data.condition) ? data.then : data.else);
+}
+
+/**
+ * Render a `[[#ifexpr]]` conditional expression element.
+ *
+ * Evaluates the mathematical expression; a result of 0 selects the
+ * `else` branch, any non-zero result selects the `then` branch.
+ * On evaluation error, a Wikidot-compatible error message is displayed
+ * and neither branch is rendered.
+ *
+ * @param ctx - The current render context.
+ * @param data - If-expression data with expression string and then/else branches.
+ */
+export function renderIfExpr(ctx: RenderContext, data: IfExprData): void {
+  const value = evaluateIfExpressionValue(data.expression);
+  if (typeof value === "string") {
+    ctx.pushEscaped(value);
+    return;
+  }
+
+  renderBranchElements(ctx, value !== 0 ? data.then : data.else);
+}

package/src/elements/expr/result.ts

@@ -0,0 +1,19 @@
+import { evaluateExpression, formatExprValue } from "@wdprlib/ast";
+
+export function evaluateExpressionOutput(expression: string): string | null {
+  const result = evaluateExpression(expression);
+  if (result.success) {
+    return formatExprValue(result.value);
+  }
+
+  if (result.error === "empty expression") {
+    return null;
+  }
+
+  return `run-time error: ${result.error}`;
+}
+
+export function evaluateIfExpressionValue(expression: string): number | string {
+  const result = evaluateExpression(expression);
+  return result.success ? result.value : `run-time error: ${result.error}`;
+}

package/src/elements/footnote/body.ts

@@ -0,0 +1,11 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+
+export function renderFootnoteBody(ctx: RenderContext, index: number, elements: Element[]): void {
+  const fnId = ctx.generateId("footnote-", index);
+  ctx.push(`<div class="footnote-footer" id="${fnId}">`);
+  ctx.push(`<a href="javascript:;">${index}</a>. `);
+  renderElements(ctx, elements);
+  ctx.push("</div>");
+}

package/src/elements/footnote/index.ts

@@ -0,0 +1,35 @@
+/**
+ *
+ * Renderers for Wikidot footnote markup.
+ *
+ * @module
+ */
+
+import type { FootnoteBlockData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+import { renderFootnoteBody } from "./body";
+
+export { renderFootnoteRef } from "./ref";
+
+/**
+ * Render a `[[footnoteblock]]` element that lists all footnote bodies.
+ *
+ * If there are no footnotes, the block is not rendered at all.
+ *
+ * @param ctx - The current render context.
+ * @param data - Footnote block data with optional custom title.
+ */
+export function renderFootnoteBlock(ctx: RenderContext, data: FootnoteBlockData): void {
+  if (ctx.footnotes.length === 0) return;
+  const title = data.title ?? "Footnotes";
+
+  ctx.push(`<div class="footnotes-footer">`);
+  ctx.push(`<div class="title">${escapeHtml(title)}</div>`);
+
+  for (let i = 0; i < ctx.footnotes.length; i++) {
+    renderFootnoteBody(ctx, i + 1, ctx.footnotes[i] ?? []);
+  }
+
+  ctx.push("</div>");
+}

package/src/elements/footnote/ref.ts

@@ -0,0 +1,16 @@
+import type { RenderContext } from "../../context";
+
+/**
+ * Render an inline footnote reference as a superscript link.
+ *
+ * Produces `<sup class="footnoteref"><a id="footnoteref-N" ...>N</a></sup>`.
+ *
+ * @param ctx - The current render context.
+ * @param index - The 1-based footnote number.
+ */
+export function renderFootnoteRef(ctx: RenderContext, index: number): void {
+  const id = ctx.generateId("footnoteref-", index);
+  ctx.push(`<sup class="footnoteref">`);
+  ctx.push(`<a id="${id}" href="javascript:;" class="footnoteref">${index}</a>`);
+  ctx.push("</sup>");
+}

package/src/elements/html/attributes.ts

@@ -0,0 +1,24 @@
+import type { HtmlData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, sanitizeStyleValue } from "../../escape";
+
+export interface HtmlBlockAttributes {
+  sandbox: string;
+  style: string;
+}
+
+export function getHtmlBlockAttributes(ctx: RenderContext, data: HtmlData): HtmlBlockAttributes {
+  return {
+    sandbox: getSandboxAttribute(ctx),
+    style: getStyleAttribute(data),
+  };
+}
+
+function getSandboxAttribute(ctx: RenderContext): string {
+  const sandbox = ctx.options.htmlBlockSandbox;
+  return sandbox ? ` sandbox="${escapeAttr(sandbox)}"` : "";
+}
+
+function getStyleAttribute(data: HtmlData): string {
+  return data.style ? ` style="${escapeAttr(sanitizeStyleValue(data.style))}"` : "";
+}

package/src/elements/html/index.ts

@@ -0,0 +1,39 @@
+/**
+ *
+ * Renderer for `[[html]]...[[/html]]` blocks in Wikidot markup.
+ *
+ * @module
+ */
+
+import type { HtmlData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr } from "../../escape";
+import { getHtmlBlockAttributes } from "./attributes";
+import { resolveHtmlBlockUrl } from "./url";
+
+/**
+ * Render a `[[html]]` block as an iframe wrapped in a `<p>` element.
+ *
+ * The iframe uses `class="html-block-iframe"` so the runtime can
+ * identify it for auto-resize. An optional `sandbox` attribute and
+ * custom `style` attribute (from `[[html style="..."]]`) are applied.
+ *
+ * @param ctx - The current render context.
+ * @param data - HTML block data containing the raw HTML contents and optional style.
+ */
+export function renderHtmlBlock(ctx: RenderContext, data: HtmlData): void {
+  // Settings-level enforcement boundary: skip rendering entirely when
+  // `[[html]]` is disabled. Placed before any counter advance or
+  // resolver invocation so disabled AST blocks have no observable effect.
+  if (ctx.settings.allowHtmlBlocks === false) {
+    return;
+  }
+
+  const index = ctx.nextHtmlBlockIndex();
+  const src = resolveHtmlBlockUrl(ctx, data.contents, index);
+  const attrs = getHtmlBlockAttributes(ctx, data);
+
+  ctx.push(
+    `<p><iframe src="${escapeAttr(src)}"${attrs.sandbox} allowtransparency="true" frameborder="0" class="html-block-iframe"${attrs.style}></iframe></p>`,
+  );
+}

package/src/elements/html/url.ts

@@ -0,0 +1,19 @@
+import type { RenderContext } from "../../context";
+import { syncHashSha1 } from "../../hash";
+
+export function resolveHtmlBlockUrl(ctx: RenderContext, contents: string, index: number): string {
+  const callbackUrl = ctx.options.resolvers?.htmlBlockUrl?.(index);
+  return callbackUrl || generateDefaultHtmlBlockUrl(ctx.page?.pageName ?? "", contents);
+}
+
+/**
+ * Generate a default iframe `src` URL for an HTML block when no
+ * resolver callback is provided.
+ *
+ * The URL follows Wikidot's pattern: `/{pageName}/html/{hash}-{nonce}`.
+ */
+function generateDefaultHtmlBlockUrl(pageName: string, contents: string): string {
+  const hash = syncHashSha1(contents);
+  const nonce = BigInt(contents.length) * 1000000000n + BigInt(hash.charCodeAt(0)) * 100000000n;
+  return pageName ? `/${pageName}/html/${hash}-${nonce}` : `/html/${hash}-${nonce}`;
+}

package/src/elements/iframe/attributes.ts

@@ -0,0 +1,28 @@
+import type { IframeData } from "@wdprlib/ast";
+import { escapeAttr, isDangerousUrl, sanitizeStyleValue } from "../../escape";
+
+const IFRAME_ATTRIBUTES = [
+  "align",
+  "frameborder",
+  "height",
+  "scrolling",
+  "width",
+  "class",
+  "style",
+];
+
+export function getIframeAttributes(data: IframeData): string[] {
+  const url = isDangerousUrl(data.url) ? "#invalid-url" : data.url;
+  const attrs = [`src="${escapeAttr(url)}"`];
+
+  for (const attr of IFRAME_ATTRIBUTES) {
+    attrs.push(`${attr}="${escapeAttr(getIframeAttributeValue(data, attr))}"`);
+  }
+
+  return attrs;
+}
+
+function getIframeAttributeValue(data: IframeData, attr: string): string {
+  const value = data.attributes[attr] ?? "";
+  return attr === "style" ? sanitizeStyleValue(value) : value;
+}

package/src/elements/iframe/index.ts

@@ -0,0 +1,22 @@
+/**
+ *
+ * Renderer for `[[iframe URL]]` inline iframe elements.
+ *
+ * @module
+ */
+
+import type { IframeData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { getIframeAttributes } from "./attributes";
+
+/**
+ * Render an `[[iframe URL]]` element.
+ *
+ * The iframe is wrapped in a `<p>` element to match Wikidot's output.
+ *
+ * @param ctx - The current render context.
+ * @param data - Iframe data containing the URL and attribute map.
+ */
+export function renderIframe(ctx: RenderContext, data: IframeData): void {
+  ctx.push(`<p><iframe ${getIframeAttributes(data).join(" ")}></iframe></p>`);
+}

package/src/elements/iftags/condition.ts

@@ -0,0 +1,42 @@
+import { hasAnyIfTagsConditionToken, parseIfTagsConditionTokens } from "./tokens";
+
+/**
+ * Evaluate an iftags condition string against a list of page tags.
+ *
+ * The condition is a space-separated list of tokens. All required tags
+ * (`+tag`) must be present, all excluded tags (`-tag`) must be absent,
+ * and at least one optional tag (bare `tag`) must be present (if any
+ * optional tags are specified).
+ *
+ * An empty condition always evaluates to `false`.
+ *
+ * @param condition - The condition string (e.g. `"+scp -joke tale"`).
+ * @param pageTags - Array of tags currently assigned to the page.
+ * @returns `true` if the condition is satisfied.
+ */
+export function evaluateIfTagsCondition(condition: string, pageTags: string[]): boolean {
+  const pageTagSet = new Set(pageTags.map((tag) => tag.toLowerCase()));
+  const tokens = parseIfTagsConditionTokens(condition);
+
+  if (!hasAnyIfTagsConditionToken(tokens)) {
+    return false;
+  }
+
+  return (
+    hasRequiredTags(tokens.required, pageTagSet) &&
+    hasNoExcludedTags(tokens.excluded, pageTagSet) &&
+    hasOptionalTagIfNeeded(tokens.optional, pageTagSet)
+  );
+}
+
+function hasRequiredTags(required: string[], pageTags: ReadonlySet<string>): boolean {
+  return required.every((tag) => pageTags.has(tag));
+}
+
+function hasNoExcludedTags(excluded: string[], pageTags: ReadonlySet<string>): boolean {
+  return excluded.every((tag) => !pageTags.has(tag));
+}
+
+function hasOptionalTagIfNeeded(optional: string[], pageTags: ReadonlySet<string>): boolean {
+  return optional.length === 0 || optional.some((tag) => pageTags.has(tag));
+}

package/src/elements/iftags/index.ts

@@ -0,0 +1,39 @@
+/**
+ *
+ * Renderer for `[[iftags]]...[[/iftags]]` conditional blocks.
+ *
+ * @module
+ */
+
+import type { IfTagsData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { evaluateIfTagsCondition } from "./condition";
+import { withIfTagsStyleSlot } from "./style-slot";
+
+/**
+ * Render an `[[iftags]]` block.
+ *
+ * Evaluates the condition against the page's tags (from `ctx.page.tags`).
+ * If no page tags are available, an empty array is used (all conditions
+ * requiring present tags will fail).
+ *
+ * @param ctx - The current render context.
+ * @param data - IfTags data with condition string and child elements.
+ */
+export function renderIfTags(ctx: RenderContext, data: IfTagsData): void {
+  const pageTags = ctx.page?.tags ?? [];
+
+  if (!evaluateIfTagsCondition(data.condition, pageTags)) {
+    return;
+  }
+
+  const prev = ctx.renderInlineStyles;
+  ctx.renderInlineStyles = true;
+
+  withIfTagsStyleSlot(ctx, data, () => {
+    renderElements(ctx, data.elements);
+  });
+
+  ctx.renderInlineStyles = prev;
+}

package/src/elements/iftags/style-slot.ts

@@ -0,0 +1,23 @@
+import type { IfTagsData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+interface StyleSlotIfTagsData extends IfTagsData {
+  _styleSlot?: number;
+}
+
+export function withIfTagsStyleSlot(
+  ctx: RenderContext,
+  data: IfTagsData,
+  render: () => void,
+): void {
+  const slotId = (data as StyleSlotIfTagsData)._styleSlot;
+  if (slotId !== undefined) {
+    ctx.enterStyleSlot(slotId);
+  }
+
+  render();
+
+  if (slotId !== undefined) {
+    ctx.exitStyleSlot();
+  }
+}