@wdprlib/render 2.1.0 → 3.0.0

package/src/elements/embed.ts

@@ -1,166 +0,0 @@
-/**
- *
- * Renderer for inline embed elements (`[[embed]]`) that reference
- * third-party content providers.
- *
- * Supported providers:
- * - YouTube (`[[embedvideo youtube:VIDEO_ID]]`)
- * - Vimeo (`[[embedvideo vimeo:VIDEO_ID]]`)
- * - GitHub Gist (`[[embed github-gist:USER/HASH]]`)
- * - GitLab Snippet (`[[embed gitlab-snippet:ID]]`)
- *
- * Each provider has a strict ID validation function to prevent path
- * traversal, injection, and other attacks via embed parameters.
- *
- * @module
- */
-
-import type { Embed } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr } from "../escape";
-
-// =============================================================================
-// ID Validation
-// Prevents path traversal and injection via embed parameters
-// =============================================================================
-
-/**
- * Validate a YouTube or Vimeo video ID.
- * Only alphanumeric characters, underscores, and hyphens are allowed.
- *
- * @param id - The video ID string to validate.
- * @returns `true` if the ID contains only safe characters.
- */
-function isValidVideoId(id: string): boolean {
-  return /^[a-zA-Z0-9_-]+$/.test(id);
-}
-
-/**
- * Validate a GitHub username (alphanumeric + hyphen, 1-39 characters).
- *
- * @param username - The GitHub username to validate.
- * @returns `true` if the username matches GitHub's format rules.
- */
-function isValidGithubUsername(username: string): boolean {
-  return /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(username);
-}
-
-/**
- * Validate a GitHub Gist hash (lowercase hex characters only).
- *
- * @param hash - The gist hash string to validate.
- * @returns `true` if the hash contains only hex characters.
- */
-function isValidGistHash(hash: string): boolean {
-  return /^[a-f0-9]+$/.test(hash);
-}
-
-/**
- * Validate a GitLab snippet ID (numeric digits only).
- *
- * @param id - The snippet ID string to validate.
- * @returns `true` if the ID is numeric.
- */
-function isValidGitlabSnippetId(id: string): boolean {
-  return /^[0-9]+$/.test(id);
-}
-
-// =============================================================================
-// Render Functions
-// =============================================================================
-
-/**
- * Render an inline embed element by dispatching to the appropriate
- * provider-specific renderer.
- *
- * Invalid provider parameters (e.g. a video ID containing path traversal
- * characters) result in an HTML comment instead of the embed.
- *
- * @param ctx - The current render context.
- * @param data - Embed data with provider type and provider-specific fields.
- */
-export function renderEmbed(ctx: RenderContext, data: Embed): void {
-  switch (data.embed) {
-    case "youtube":
-      renderYoutube(ctx, data.data["video-id"]);
-      break;
-    case "vimeo":
-      renderVimeo(ctx, data.data["video-id"]);
-      break;
-    case "github-gist":
-      renderGithubGist(ctx, data.data.username, data.data.hash);
-      break;
-    case "gitlab-snippet":
-      renderGitlabSnippet(ctx, data.data["snippet-id"]);
-      break;
-  }
-}
-
-/**
- * Render a YouTube embed as a responsive iframe.
- *
- * @param ctx - The current render context.
- * @param videoId - YouTube video ID (validated before use).
- */
-function renderYoutube(ctx: RenderContext, videoId: string): void {
-  if (!isValidVideoId(videoId)) {
-    ctx.push(`<!-- Invalid YouTube video ID -->`);
-    return;
-  }
-  ctx.push(`<div class="embed-youtube">`);
-  ctx.push(
-    `<iframe src="https://www.youtube.com/embed/${escapeAttr(videoId)}" ` +
-      `frameborder="0" allowfullscreen></iframe>`,
-  );
-  ctx.push("</div>");
-}
-
-/**
- * Render a Vimeo embed as a responsive iframe.
- *
- * @param ctx - The current render context.
- * @param videoId - Vimeo video ID (validated before use).
- */
-function renderVimeo(ctx: RenderContext, videoId: string): void {
-  if (!isValidVideoId(videoId)) {
-    ctx.push(`<!-- Invalid Vimeo video ID -->`);
-    return;
-  }
-  ctx.push(`<div class="embed-vimeo">`);
-  ctx.push(
-    `<iframe src="https://player.vimeo.com/video/${escapeAttr(videoId)}" ` +
-      `frameborder="0" allowfullscreen></iframe>`,
-  );
-  ctx.push("</div>");
-}
-
-/**
- * Render a GitHub Gist embed as a `<script>` tag.
- *
- * @param ctx - The current render context.
- * @param username - GitHub username owning the gist (validated before use).
- * @param hash - Gist hash identifier (validated before use).
- */
-function renderGithubGist(ctx: RenderContext, username: string, hash: string): void {
-  if (!isValidGithubUsername(username) || !isValidGistHash(hash)) {
-    ctx.push(`<!-- Invalid GitHub Gist parameters -->`);
-    return;
-  }
-  ctx.push(
-    `<script src="https://gist.github.com/${escapeAttr(username)}/${escapeAttr(hash)}.js"></script>`,
-  );
-}
-
-/**
- * Render a GitLab Snippet embed as a `<script>` tag.
- *
- * @param ctx - The current render context.
- * @param snippetId - GitLab snippet ID (validated before use).
- */
-function renderGitlabSnippet(ctx: RenderContext, snippetId: string): void {
-  if (!isValidGitlabSnippetId(snippetId)) {
-    ctx.push(`<!-- Invalid GitLab snippet ID -->`);
-    return;
-  }
-  ctx.push(`<script src="https://gitlab.com/snippets/${escapeAttr(snippetId)}.js"></script>`);
-}

package/src/elements/expr.ts

@@ -1,102 +0,0 @@
-/**
- *
- * Renderers for Wikidot's expression and conditional constructs:
- *
- * - `[[#expr EXPRESSION]]` -- evaluate a mathematical expression and
- *   display the numeric result.
- * - `[[#if VALUE | THEN | ELSE]]` -- simple string-based truthiness check.
- * - `[[#ifexpr EXPRESSION | THEN | ELSE]]` -- evaluate a math expression
- *   and branch on the numeric result (0 = false, non-zero = true).
- *
- * All error messages match Wikidot's format (`"run-time error: ..."`).
- *
- * @module
- */
-
-import type { Element, ExprData, IfCondData, IfExprData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { renderElements } from "../render";
-import { evaluateExpression, formatExprValue, isTruthy } from "@wdprlib/ast";
-
-/**
- * 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 result = evaluateExpression(data.expression);
-  if (result.success) {
-    ctx.pushEscaped(formatExprValue(result.value));
-  } else if (result.error !== "empty expression") {
-    ctx.pushEscaped(`run-time error: ${result.error}`);
-  }
-  // Empty expression outputs nothing
-}
-
-/**
- * Render a `[[#if]]` conditional element.
- *
- * The condition is treated as a string: values `"false"`, `"null"`,
- * `""`, and `"0"` are falsy; everything else is truthy. The selected
- * branch's elements are rendered with trailing whitespace trimmed.
- *
- * @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 {
-  const elements = isTruthy(data.condition) ? data.then : data.else;
-  renderBranchElements(ctx, elements);
-}
-
-/**
- * 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 result = evaluateExpression(data.expression);
-  if (!result.success) {
-    // ifexpr: error outputs error message (Wikidot-compatible)
-    ctx.pushEscaped(`run-time error: ${result.error}`);
-    return;
-  }
-  // 0 selects else branch, non-zero selects then branch
-  const elements = result.value !== 0 ? data.then : data.else;
-  renderBranchElements(ctx, elements);
-}
-
-/**
- * Render a branch's elements, trimming trailing whitespace-only text nodes.
- *
- * Wikidot strips trailing whitespace from `#if` / `#ifexpr` branch output.
- * This function finds the last non-whitespace element and renders only
- * up to that point.
- *
- * @param ctx - The current render context.
- * @param elements - The branch's element array.
- */
-function renderBranchElements(ctx: RenderContext, elements: Element[]): void {
-  // Find the last non-whitespace element
-  let lastIdx = elements.length - 1;
-  while (lastIdx >= 0) {
-    const el = elements[lastIdx]!;
-    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
-      lastIdx--;
-    } else {
-      break;
-    }
-  }
-  // Render only up to the last non-whitespace element
-  renderElements(ctx, elements.slice(0, lastIdx + 1));
-}

package/src/elements/footnote.ts

@@ -1,76 +0,0 @@
-/**
- *
- * Renderers for Wikidot footnote markup.
- *
- * - `[[footnote]]...[[/footnote]]` -- inline footnote reference that renders
- *   as a superscript number linking to the footnote body.
- * - `[[footnoteblock]]` -- block element that lists all footnote bodies
- *   collected during the render pass.
- *
- * The runtime `footnote` module adds hover tooltips and click-to-scroll
- * behavior to these elements.
- *
- * @module
- */
-
-import type { FootnoteBlockData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeHtml } from "../escape";
-import { renderElements } from "../render";
-
-/**
- * Render an inline footnote reference as a superscript link.
- *
- * Produces `<sup class="footnoteref"><a id="footnoteref-N" ...>N</a></sup>`.
- * The ID is used by the runtime module for bidirectional scroll navigation
- * between the reference and its footnote body.
- *
- * @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>");
-}
-
-/**
- * Render a `[[footnoteblock]]` element that lists all footnote bodies.
- *
- * Produces a Wikidot-compatible structure:
- * ```html
- * <div class="footnotes-footer">
- *   <div class="title">Footnotes</div>
- *   <div class="footnote-footer" id="footnote-1">
- *     <a href="javascript:;">1</a>. ...content...
- *   </div>
- * </div>
- * ```
- *
- * 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>`);
-
-  // Render each footnote
-  for (let i = 0; i < ctx.footnotes.length; i++) {
-    const index = i + 1;
-    const elements = ctx.footnotes[i] ?? [];
-
-    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>");
-  }
-
-  ctx.push("</div>");
-}

package/src/elements/html.ts

@@ -1,79 +0,0 @@
-/**
- *
- * Renderer for `[[html]]...[[/html]]` blocks in Wikidot markup.
- *
- * HTML blocks are rendered as sandboxed iframes. The iframe `src` URL
- * can be provided by a resolver callback; when absent, a deterministic
- * default URL is generated from the content hash.
- *
- * The actual HTML content is not inlined into the page -- it is served
- * separately at the iframe URL. The runtime `html-block` module handles
- * auto-resizing of the iframe via `postMessage`.
- *
- * @module
- */
-
-import type { HtmlData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, sanitizeStyleValue } from "../escape";
-import { syncHashSha1 } from "../hash";
-
-/**
- * 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}`.
- * The hash is a SHA-1-length FNV hash of the content, and the nonce
- * is derived from the content length and first hash character to
- * provide additional uniqueness.
- *
- * @param pageName - The current page name (may be empty).
- * @param contents - Raw HTML content to hash.
- * @returns A URL path string, always starting with `/`.
- */
-function generateDefaultUrl(pageName: string, contents: string): string {
-  const hash = syncHashSha1(contents);
-  const nonce = BigInt(contents.length) * 1000000000n + BigInt(hash.charCodeAt(0)) * 100000000n;
-  // Ensure leading slash even when pageName is empty (avoid protocol-relative URL)
-  const path = pageName ? `/${pageName}/html/${hash}-${nonce}` : `/html/${hash}-${nonce}`;
-  return path;
-}
-
-/**
- * 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 a disabled-but-still-in-AST block (manually
-  // built trees, cached ASTs, foreign parsers) has no observable effect.
-  if (ctx.settings.allowHtmlBlocks === false) {
-    return;
-  }
-
-  const index = ctx.nextHtmlBlockIndex();
-  const pageName = ctx.page?.pageName ?? "";
-
-  // Use callback URL if provided, otherwise generate default URL
-  const callbackUrl = ctx.options.resolvers?.htmlBlockUrl?.(index);
-  const src = callbackUrl || generateDefaultUrl(pageName, data.contents);
-
-  // Build sandbox attribute (null/undefined = no sandbox, Wikidot compatible)
-  const sandbox = ctx.options.htmlBlockSandbox;
-  const sandboxAttr = sandbox ? ` sandbox="${escapeAttr(sandbox)}"` : "";
-
-  // Build style attribute (from [[html style="..."]]) with CSS injection protection
-  const styleAttr = data.style ? ` style="${escapeAttr(sanitizeStyleValue(data.style))}"` : "";
-
-  // Wikidot wraps html block iframe in a paragraph
-  ctx.push(
-    `<p><iframe src="${escapeAttr(src)}"${sandboxAttr} allowtransparency="true" frameborder="0" class="html-block-iframe"${styleAttr}></iframe></p>`,
-  );
-}

package/src/elements/iframe.ts

@@ -1,44 +0,0 @@
-/**
- *
- * Renderer for `[[iframe URL]]` inline iframe elements.
- *
- * Unlike `[[embed]]` blocks, `[[iframe]]` directly references a URL.
- * The URL is checked for dangerous schemes, and standard iframe
- * attributes (align, frameborder, height, etc.) are extracted from the
- * AST's attribute map and rendered with proper escaping.
- *
- * @module
- */
-
-import type { IframeData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, isDangerousUrl, sanitizeStyleValue } from "../escape";
-
-/**
- * Render an `[[iframe URL]]` element.
- *
- * The iframe is wrapped in a `<p>` element to match Wikidot's output.
- * Standard iframe attributes are rendered from the AST's attribute map,
- * with the `style` attribute sanitized against CSS injection. Dangerous
- * URL schemes are replaced with `#invalid-url`.
- *
- * @param ctx - The current render context.
- * @param data - Iframe data containing the URL and attribute map.
- */
-export function renderIframe(ctx: RenderContext, data: IframeData): void {
-  const url = isDangerousUrl(data.url) ? "#invalid-url" : data.url;
-  const attrs: string[] = [`src="${escapeAttr(url)}"`];
-
-  // Standard iframe attributes from the attributes map
-  const iframeAttrs = ["align", "frameborder", "height", "scrolling", "width", "class", "style"];
-  for (const attr of iframeAttrs) {
-    let value = data.attributes[attr] ?? "";
-    // Sanitize style attribute to prevent CSS injection
-    if (attr === "style") {
-      value = sanitizeStyleValue(value);
-    }
-    attrs.push(`${attr}="${escapeAttr(value)}"`);
-  }
-
-  ctx.push(`<p><iframe ${attrs.join(" ")}></iframe></p>`);
-}

package/src/elements/iftags.ts

@@ -1,118 +0,0 @@
-/**
- *
- * Renderer for `[[iftags]]...[[/iftags]]` conditional blocks.
- *
- * Wikidot's `iftags` construct conditionally renders content based on
- * whether the current page's tags match a condition string. The condition
- * supports three kinds of tag tokens:
- *
- * - `+tag` -- required: the tag must be present
- * - `-tag` -- excluded: the tag must NOT be present
- * - `tag` (no prefix) -- optional group: at least one unprefixed tag must be present
- *
- * All three categories must independently be satisfied for the condition
- * to evaluate to true.
- *
- * @module
- */
-
-import type { IfTagsData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { renderElements } from "../render";
-
-/**
- * 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.
- */
-function evaluateIfTagsCondition(condition: string, pageTags: string[]): boolean {
-  const pageTagSet = new Set(pageTags.map((t) => t.toLowerCase()));
-  const tokens = condition.split(/\s+/).filter(Boolean);
-
-  // Empty condition = never show
-  if (tokens.length === 0) {
-    return false;
-  }
-
-  const required: string[] = [];
-  const excluded: string[] = [];
-  const optional: string[] = [];
-
-  for (const token of tokens) {
-    if (token.startsWith("+")) {
-      const tag = token.slice(1).toLowerCase();
-      if (tag) required.push(tag);
-    } else if (token.startsWith("-")) {
-      const tag = token.slice(1).toLowerCase();
-      if (tag) excluded.push(tag);
-    } else {
-      optional.push(token.toLowerCase());
-    }
-  }
-
-  // If all tokens had empty tag names (e.g. "+" or "-"), treat as empty condition
-  if (required.length === 0 && excluded.length === 0 && optional.length === 0) {
-    return false;
-  }
-
-  // All required tags must be present
-  for (const tag of required) {
-    if (!pageTagSet.has(tag)) return false;
-  }
-
-  // All excluded tags must NOT be present
-  for (const tag of excluded) {
-    if (pageTagSet.has(tag)) return false;
-  }
-
-  // If there are optional tags, at least one must be present
-  if (optional.length > 0) {
-    const hasAnyOptional = optional.some((tag) => pageTagSet.has(tag));
-    if (!hasAnyOptional) return false;
-  }
-
-  return true;
-}
-
-/**
- * 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)) {
-    const prev = ctx.renderInlineStyles;
-    ctx.renderInlineStyles = true;
-
-    // If a style slot was assigned during resolve, collect styles into
-    // it so they appear at the correct source-order position in the
-    // final output. Otherwise fall back to inline rendering.
-    const slotId = (data as IfTagsData & { _styleSlot?: number })._styleSlot;
-    if (slotId !== undefined) {
-      ctx.enterStyleSlot(slotId);
-    }
-
-    renderElements(ctx, data.elements);
-
-    if (slotId !== undefined) {
-      ctx.exitStyleSlot();
-    }
-    ctx.renderInlineStyles = prev;
-  }
-}