@wdprlib/render 2.0.0 → 2.1.0

package/src/elements/html.ts

@@ -0,0 +1,79 @@
+/**
+ *
+ * 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

@@ -0,0 +1,44 @@
+/**
+ *
+ * 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

@@ -0,0 +1,118 @@
+/**
+ *
+ * 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;
+  }
+}

package/src/elements/image.ts

@@ -0,0 +1,154 @@
+/**
+ *
+ * Renderer for Wikidot image elements (`[[image source]]` and `[[f<image source]]`).
+ *
+ * Images can be sourced from URLs, page-attached files, or cross-site
+ * files. The renderer resolves the source to a URL, sanitizes all
+ * attributes, optionally wraps the image in a link (`link` attribute),
+ * and optionally wraps everything in an alignment container div.
+ *
+ * @module
+ */
+
+import type { ImageSource, ImageData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr, isDangerousUrl, sanitizeAttributes } from "../escape";
+
+/**
+ * Render an image element with optional link wrapper and alignment container.
+ *
+ * Processing steps:
+ * 1. Resolve the image source to a URL via `ctx.resolveImageSource()`.
+ * 2. Sanitize user-supplied attributes.
+ * 3. Build the `<img>` tag with safe attributes.
+ * 4. Optionally wrap in an `<a>` tag if a link target is specified.
+ * 5. Optionally wrap in a `<div class="image-container ...">` for alignment.
+ *
+ * Dangerous URLs are replaced with `#invalid-url`. Local paths blocked
+ * by settings cause the entire image to be silently dropped.
+ *
+ * @param ctx - The current render context.
+ * @param data - Image element data with source, attributes, optional link, and alignment.
+ */
+export function renderImage(ctx: RenderContext, data: ImageData): void {
+  let src = ctx.resolveImageSource(data.source);
+  if (src === null) return; // Local path blocked by settings
+  if (isDangerousUrl(src)) {
+    src = "#invalid-url";
+  }
+  const safeAttrs = sanitizeAttributes(data.attributes);
+  const alt = safeAttrs.alt ?? getFilenameFromSource(data.source);
+  const className = safeAttrs.class ?? "image";
+
+  // Build img attributes
+  const imgAttrs: string[] = [`src="${escapeAttr(src)}"`];
+
+  // Custom attributes (title, style, etc.) before alt/class
+  // Skip src/srcset to prevent override of resolved source
+  for (const [key, value] of Object.entries(safeAttrs)) {
+    if (key === "alt" || key === "class" || key === "src" || key === "srcset") continue;
+    imgAttrs.push(`${key}="${escapeAttr(value)}"`);
+  }
+
+  imgAttrs.push(`alt="${escapeAttr(alt)}"`);
+
+  // Only override class if not custom
+  if (!safeAttrs.class) {
+    imgAttrs.push(`class="${escapeAttr(className)}"`);
+  } else {
+    imgAttrs.push(`class="${escapeAttr(safeAttrs.class)}"`);
+  }
+
+  const imgTag = `<img ${imgAttrs.join(" ")} />`;
+
+  // Wrap in link if needed
+  let output = imgTag;
+  if (data.link) {
+    let href: string;
+    if (typeof data.link === "string") {
+      // Add leading slash for page links (not URLs or anchors)
+      if (
+        !data.link.startsWith("/") &&
+        !data.link.startsWith("#") &&
+        !data.link.startsWith("http://") &&
+        !data.link.startsWith("https://")
+      ) {
+        href = `/${data.link}`;
+      } else {
+        href = data.link;
+      }
+    } else {
+      href = `/${data.link.page}`;
+    }
+    if (isDangerousUrl(href)) {
+      href = "#invalid-url";
+    }
+    output = `<a href="${escapeAttr(href)}">${imgTag}</a>`;
+  }
+
+  // Wrap in alignment container if needed
+  if (data.alignment) {
+    const alignClass = getAlignmentClass(data.alignment.align, data.alignment.float);
+    ctx.push(`<div class="image-container ${alignClass}">`);
+    ctx.push(output);
+    ctx.push("</div>");
+  } else {
+    ctx.push(output);
+  }
+}
+
+/**
+ * Map an alignment direction and float flag to a Wikidot CSS class name.
+ *
+ * @param align - Alignment direction (`"left"`, `"right"`, `"center"`).
+ * @param isFloat - Whether the image uses float positioning.
+ * @returns CSS class name (e.g. `"floatleft"`, `"aligncenter"`).
+ */
+function getAlignmentClass(align: string, isFloat: boolean): string {
+  if (isFloat) {
+    switch (align) {
+      case "left":
+        return "floatleft";
+      case "right":
+        return "floatright";
+      case "center":
+        return "floatcenter";
+      default:
+        return `float${align}`;
+    }
+  }
+  switch (align) {
+    case "left":
+      return "alignleft";
+    case "right":
+      return "alignright";
+    case "center":
+      return "aligncenter";
+    default:
+      return `align${align}`;
+  }
+}
+
+/**
+ * Extract a filename from an image source for use as the default `alt` text.
+ *
+ * For URL sources, the last path segment is returned. For file-type sources,
+ * the file name field is returned directly.
+ *
+ * @param source - The image source descriptor.
+ * @returns The extracted filename string.
+ */
+function getFilenameFromSource(source: ImageSource): string {
+  switch (source.type) {
+    case "url": {
+      const parts = source.data.split("/");
+      return parts[parts.length - 1] ?? source.data;
+    }
+    case "file1":
+      return source.data.file;
+    case "file2":
+      return source.data.file;
+    case "file3":
+      return source.data.file;
+  }
+}

package/src/elements/include.ts

@@ -0,0 +1,43 @@
+/**
+ *
+ * Renderer for `[[include page-name]]` transclusion elements.
+ *
+ * Includes are resolved by the parser before rendering: if the target
+ * page exists, its parsed elements are injected into the AST. At render
+ * time, the renderer either outputs the pre-resolved elements or shows
+ * a Wikidot-compatible error message with a "create it now" link.
+ *
+ * @module
+ */
+
+import type { IncludeData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr, escapeHtml } from "../escape";
+import { renderElements } from "../render";
+
+/**
+ * Render an `[[include]]` element.
+ *
+ * If the include was resolved by the parser (i.e., `data.elements` is
+ * non-empty), the resolved elements are rendered directly. Otherwise,
+ * a Wikidot-compatible error block with a "create it now" link is shown.
+ *
+ * @param ctx - The current render context.
+ * @param data - Include data with the target page location and resolved elements.
+ */
+export function renderInclude(ctx: RenderContext, data: IncludeData): void {
+  // If elements is empty, the include was not resolved - show error
+  if (data.elements.length === 0) {
+    // Wikidot normalizes page names to lowercase
+    const pageName = data.location.page.toLowerCase();
+    // Encode page name for URL path (/ should not be encoded, but special chars should)
+    const encodedPageName = pageName.replace(/[^a-z0-9\-_:/]/g, (c) => encodeURIComponent(c));
+    // Prevent protocol-relative URLs
+    const safePath = encodedPageName.startsWith("/") ? encodedPageName.slice(1) : encodedPageName;
+    ctx.push(
+      `<div class="error-block"><p>Included page "${escapeHtml(pageName)}" does not exist (<a href="/${escapeAttr(safePath)}/edit/true">create it now</a>)</p></div>`,
+    );
+    return;
+  }
+  renderElements(ctx, data.elements);
+}

package/src/elements/index.ts

@@ -0,0 +1,35 @@
+/**
+ *
+ * Barrel export for all Wikidot element renderers.
+ *
+ * Each renderer function accepts a `RenderContext` and the
+ * element-specific AST data, then pushes the resulting HTML fragments
+ * into the context's output buffer.
+ *
+ * @module
+ */
+
+export { renderContainer } from "./container";
+export { renderText, renderRaw, renderEmail } from "./text";
+export { renderLink, renderAnchor, renderAnchorName } from "./link";
+export { renderImage } from "./image";
+export { renderList, renderDefinitionList } from "./list";
+export { renderTable } from "./table";
+export { renderCollapsible } from "./collapsible";
+export { renderCode } from "./code";
+export { renderTabView } from "./tab-view";
+export { renderFootnoteRef, renderFootnoteBlock } from "./footnote";
+export { renderMath, renderMathInline } from "./math";
+export { renderModule } from "./module/index";
+export { renderEmbed } from "./embed";
+export { renderUser } from "./user";
+export { renderBibliographyCite, renderBibliographyBlock } from "./bibliography";
+export { renderTableOfContents } from "./toc";
+export { renderLineBreaks } from "./line-break";
+export { renderClearFloat } from "./clear-float";
+export { renderIframe } from "./iframe";
+export { renderHtmlBlock } from "./html";
+export { renderInclude } from "./include";
+export { renderIfTags } from "./iftags";
+export { renderColor } from "./color";
+export { renderDate } from "./date";

package/src/elements/line-break.ts

@@ -0,0 +1,22 @@
+/**
+ *
+ * Renderer for explicit line breaks (`_` at end of line in Wikidot markup).
+ *
+ * Multiple consecutive line-break elements produce multiple `<br />` tags.
+ *
+ * @module
+ */
+
+import type { RenderContext } from "../context";
+
+/**
+ * Render one or more consecutive line breaks as `<br />` tags.
+ *
+ * @param ctx - The current render context.
+ * @param count - Number of `<br />` tags to emit.
+ */
+export function renderLineBreaks(ctx: RenderContext, count: number): void {
+  for (let i = 0; i < count; i++) {
+    ctx.push("<br />");
+  }
+}