@wdprlib/render 2.0.0 → 3.0.0

package/src/elements/table/attributes.ts

@@ -0,0 +1,23 @@
+import { escapeAttr, sanitizeAttributes } from "../../escape";
+
+export { renderTableCellAttrs } from "./cell-attributes";
+
+export function renderTableAttrs(attributes: Record<string, string>): string {
+  let hasRenderableAttributes = false;
+  for (const key in attributes) {
+    if (!key.startsWith("_")) {
+      hasRenderableAttributes = true;
+      break;
+    }
+  }
+  if (!hasRenderableAttributes) return "";
+
+  const safe = sanitizeAttributes(attributes);
+  let result = "";
+  for (const key in safe) {
+    if (key.startsWith("_")) continue;
+    const value = safe[key]!;
+    result += ` ${key}="${escapeAttr(value)}"`;
+  }
+  return result;
+}

package/src/elements/table/cell-attributes.ts

@@ -0,0 +1,62 @@
+import type { TableCell } from "@wdprlib/ast";
+import { escapeAttr, sanitizeAttributes } from "../../escape";
+
+export function renderTableCellAttrs(cell: TableCell): string {
+  const attrs: string[] = [];
+  const safeCellAttrs = sanitizeAttributes(cell.attributes);
+
+  appendColumnSpan(attrs, cell);
+  appendRowSpan(attrs, safeCellAttrs);
+  appendAlignmentStyle(attrs, cell, safeCellAttrs);
+  appendRemainingCellAttributes(attrs, cell, safeCellAttrs);
+
+  return attrs.length > 0 ? " " + attrs.join(" ") : "";
+}
+
+function appendColumnSpan(attrs: string[], cell: TableCell): void {
+  if (cell["column-span"] > 1) {
+    attrs.push(`colspan="${cell["column-span"]}"`);
+  }
+}
+
+function appendRowSpan(attrs: string[], safeCellAttrs: Record<string, string>): void {
+  if (!safeCellAttrs.rowspan) {
+    return;
+  }
+
+  const rowspan = parseInt(safeCellAttrs.rowspan, 10);
+  if (rowspan > 1) {
+    attrs.push(`rowspan="${rowspan}"`);
+  }
+}
+
+function appendAlignmentStyle(
+  attrs: string[],
+  cell: TableCell,
+  safeCellAttrs: Record<string, string>,
+): void {
+  if (!cell.align) {
+    return;
+  }
+
+  const existingStyle = safeCellAttrs.style ?? "";
+  const alignStyle = `text-align: ${cell.align};`;
+  if (existingStyle) {
+    attrs.push(`style="${escapeAttr(existingStyle + "; " + alignStyle)}"`);
+  } else {
+    attrs.push(`style="${alignStyle}"`);
+  }
+}
+
+function appendRemainingCellAttributes(
+  attrs: string[],
+  cell: TableCell,
+  safeCellAttrs: Record<string, string>,
+): void {
+  for (const key in safeCellAttrs) {
+    if (key === "style" && cell.align) continue;
+    if (key === "rowspan") continue;
+    const value = safeCellAttrs[key]!;
+    attrs.push(`${key}="${escapeAttr(value)}"`);
+  }
+}

package/src/elements/table/cell.ts

@@ -0,0 +1,13 @@
+import type { TableCell } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderTableCellAttrs } from "./attributes";
+
+export function renderTableCell(ctx: RenderContext, cell: TableCell): void {
+  const tag = cell.header ? "th" : "td";
+  const attrStr = renderTableCellAttrs(cell);
+
+  ctx.push(`<${tag}${attrStr}>`);
+  renderElements(ctx, cell.elements);
+  ctx.push(`</${tag}>`);
+}

package/src/elements/table/index.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for Wikidot table elements.
+ *
+ * @module
+ */
+
+import type { TableData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderTableAttrs } from "./attributes";
+import { renderTableCell } from "./cell";
+
+export function renderTable(ctx: RenderContext, data: TableData): void {
+  const isPipeTable = data.attributes._source === "pipe";
+  const classAttr = isPipeTable ? ' class="wiki-content-table"' : "";
+  ctx.push(`<table${classAttr}${renderTableAttrs(data.attributes)}>`);
+
+  for (const row of data.rows) {
+    ctx.push(`<tr${renderTableAttrs(row.attributes)}>`);
+    for (const cell of row.cells) {
+      renderTableCell(ctx, cell);
+    }
+    ctx.push("</tr>");
+  }
+
+  ctx.push("</table>");
+}

package/src/elements/text/email.ts

@@ -0,0 +1,20 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml, isValidEmail } from "../../escape";
+
+/**
+ * Render an email address element as a `mailto:` link.
+ *
+ * The email is validated before creating the link. Invalid email addresses
+ * are rendered as plain escaped text to prevent `mailto:` injection.
+ *
+ * @param ctx - The current render context.
+ * @param email - The email address string.
+ */
+export function renderEmail(ctx: RenderContext, email: string): void {
+  if (!isValidEmail(email)) {
+    ctx.pushEscaped(email);
+    return;
+  }
+
+  ctx.push(`<a href="mailto:${escapeAttr(email)}">${escapeHtml(email)}</a>`);
+}

package/src/elements/text/index.ts

@@ -0,0 +1,11 @@
+/**
+ *
+ * Renderers for text-level AST nodes: plain text, raw/literal text,
+ * and email addresses.
+ *
+ * @module
+ */
+
+export { renderEmail } from "./email";
+export { renderRaw } from "./raw";
+export { renderText } from "./plain";

package/src/elements/text/plain.ts

@@ -0,0 +1,11 @@
+import type { RenderContext } from "../../context";
+
+/**
+ * Render a plain text node by HTML-escaping and appending to the output.
+ *
+ * @param ctx - The current render context.
+ * @param data - The raw text content.
+ */
+export function renderText(ctx: RenderContext, data: string): void {
+  ctx.pushEscaped(data);
+}

package/src/elements/text/raw.ts

@@ -0,0 +1,20 @@
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+
+/**
+ * Render raw/literal text (Wikidot `@@...@@` syntax).
+ *
+ * Raw text is rendered inside a `<span style="white-space: pre-wrap;">` with
+ * spaces encoded as `&#32;` to preserve Wikidot's exact formatting. Empty
+ * strings produce no output.
+ *
+ * @param ctx - The current render context.
+ * @param data - The raw text content.
+ */
+export function renderRaw(ctx: RenderContext, data: string): void {
+  if (data === "") return;
+
+  ctx.push(`<span style="white-space: pre-wrap;">`);
+  ctx.push(escapeHtml(data).replace(/ /g, "&#32;"));
+  ctx.push("</span>");
+}

package/src/elements/toc/body.ts

@@ -0,0 +1,12 @@
+import type { RenderContext } from "../../context";
+import { renderTocEntries } from "./entries";
+
+export function renderTocBody(ctx: RenderContext): void {
+  ctx.push(
+    `<div id="toc-action-bar"><a href="javascript:;">Fold</a><a style="display: none" href="javascript:;">Unfold</a></div>`,
+  );
+  ctx.push(`<div class="title">Table of Contents</div>`);
+  ctx.push(`<div id="toc-list">`);
+  renderTocEntries(ctx, ctx.tocElements);
+  ctx.push("</div>");
+}

package/src/elements/toc/entries.ts

@@ -0,0 +1,34 @@
+import type { Element, ListData, ListItem } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml } from "../../escape";
+import { extractTocLink, rewriteTocAnchor } from "./link";
+
+export function renderTocEntries(ctx: RenderContext, elements: Element[]): void {
+  for (const element of elements) {
+    if (element.element === "list") {
+      renderTocList(ctx, element.data, 1);
+    }
+  }
+}
+
+function renderTocList(ctx: RenderContext, listData: ListData, depth: number): void {
+  for (const item of listData.items) {
+    renderTocItem(ctx, item, depth);
+  }
+}
+
+function renderTocItem(ctx: RenderContext, item: ListItem, depth: number): void {
+  if (item["item-type"] === "elements") {
+    for (const el of item.elements) {
+      const link = extractTocLink(el);
+      if (link) {
+        const href = rewriteTocAnchor(ctx, link.href);
+        ctx.push(
+          `<div style="margin-left: ${depth}em;"><a href="${escapeAttr(href)}">${escapeHtml(link.text)}</a></div>`,
+        );
+      }
+    }
+  } else if (item["item-type"] === "sub-list") {
+    renderTocList(ctx, item.data, depth + 1);
+  }
+}

package/src/elements/toc/frame.ts

@@ -0,0 +1,27 @@
+import type { Alignment } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+export function isFloatingToc(align: Alignment | null): boolean {
+  return align === "left" || align === "right";
+}
+
+export function openTocFrame(ctx: RenderContext, align: Alignment | null): void {
+  if (!isFloatingToc(align)) {
+    ctx.push(`<table style="margin:0; padding:0"><tr><td style="margin:0; padding:0">`);
+  }
+
+  if (isFloatingToc(align)) {
+    const floatClass = align === "left" ? "floatleft" : "floatright";
+    ctx.push(`<div id="toc" class="${floatClass}">`);
+  } else {
+    ctx.push(`<div id="toc">`);
+  }
+}
+
+export function closeTocFrame(ctx: RenderContext, align: Alignment | null): void {
+  ctx.push("</div>");
+
+  if (!isFloatingToc(align)) {
+    ctx.push(`</td></tr></table>`);
+  }
+}

package/src/elements/toc/index.ts

@@ -0,0 +1,17 @@
+/**
+ *
+ * Renderer for `[[toc]]` (Table of Contents) elements.
+ *
+ * @module
+ */
+
+import type { TableOfContentsData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderTocBody } from "./body";
+import { closeTocFrame, openTocFrame } from "./frame";
+
+export function renderTableOfContents(ctx: RenderContext, data: TableOfContentsData): void {
+  openTocFrame(ctx, data.align);
+  renderTocBody(ctx);
+  closeTocFrame(ctx, data.align);
+}

package/src/elements/toc/link.ts

@@ -0,0 +1,26 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+export interface TocLink {
+  href: string;
+  text: string;
+}
+
+export function extractTocLink(element: Element): TocLink | null {
+  if (element.element !== "link") return null;
+
+  const label = element.data.label;
+  let text = "";
+  if (typeof label === "object" && label !== null && "text" in label) {
+    text = label.text;
+  }
+
+  const href = typeof element.data.link === "string" ? element.data.link : "";
+  return { href, text };
+}
+
+export function rewriteTocAnchor(ctx: RenderContext, href: string): string {
+  const match = /^#toc(\d+)$/.exec(href);
+  if (!match) return href;
+  return `#${ctx.generateId("toc", Number(match[1]))}`;
+}

package/src/elements/user/index.ts

@@ -0,0 +1,40 @@
+/**
+ *
+ * Renderer for `[[user username]]` elements.
+ *
+ * @module
+ */
+
+import type { UserData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+import { getResolvedUser } from "./resolve";
+import { renderAvatarUser, renderLinkedUser } from "./markup";
+
+/**
+ * Render a `[[user username]]` element.
+ *
+ * @param ctx - The current render context.
+ * @param data - User element data with username and show-avatar flag.
+ */
+export function renderUser(ctx: RenderContext, data: UserData): void {
+  const normalized = data.name.toLowerCase().trim();
+
+  if (normalized === "anonymous") {
+    ctx.push("Anonymous");
+    return;
+  }
+
+  const resolved = getResolvedUser(ctx, data.name);
+  if (resolved === null) {
+    ctx.push(escapeHtml(data.name));
+    return;
+  }
+
+  const showAvatar = data["show-avatar"] && resolved.url && resolved.avatarUrl;
+  if (showAvatar) {
+    renderAvatarUser(ctx, data.name, resolved);
+  } else {
+    renderLinkedUser(ctx, data.name, resolved);
+  }
+}

package/src/elements/user/markup.ts

@@ -0,0 +1,34 @@
+import type { RenderContext } from "../../context";
+import type { ResolvedUser } from "../../types";
+import { escapeAttr, escapeHtml } from "../../escape";
+
+export function renderLinkedUser(ctx: RenderContext, username: string, user: ResolvedUser): void {
+  const displayName = user.name ?? username;
+  const hrefAttr = user.url ? ` href="${escapeAttr(user.url)}"` : "";
+
+  ctx.push(`<span class="printuser">`);
+  ctx.push(`<a${hrefAttr}>`);
+  ctx.push(escapeHtml(displayName));
+  ctx.push("</a>");
+  ctx.push("</span>");
+}
+
+export function renderAvatarUser(ctx: RenderContext, username: string, user: ResolvedUser): void {
+  const displayName = user.name ?? username;
+  const hrefAttr = user.url ? ` href="${escapeAttr(user.url)}"` : "";
+  const avatarUrl = user.avatarUrl ?? "";
+  const styleAttr = user.karmaUrl
+    ? ` style="background-image:url(${escapeAttr(user.karmaUrl)})"`
+    : "";
+
+  ctx.push(`<span class="printuser avatarhover">`);
+  ctx.push(`<a${hrefAttr}>`);
+  ctx.push(
+    `<img class="small" src="${escapeAttr(avatarUrl)}" alt="${escapeAttr(displayName)}"${styleAttr} />`,
+  );
+  ctx.push("</a>");
+  ctx.push(`<a${hrefAttr}>`);
+  ctx.push(escapeHtml(displayName));
+  ctx.push("</a>");
+  ctx.push("</span>");
+}

package/src/elements/user/resolve.ts

@@ -0,0 +1,6 @@
+import type { RenderContext } from "../../context";
+import type { ResolvedUser } from "../../types";
+
+export function getResolvedUser(ctx: RenderContext, username: string): ResolvedUser | null {
+  return ctx.options.resolvers?.user?.(username) ?? null;
+}

package/src/escape/attribute-allowlists.ts

@@ -0,0 +1,101 @@
+/**
+ * HTML attribute names considered safe for rendering.
+ */
+export const SAFE_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "accept",
+  "align",
+  "alt",
+  "autocapitalize",
+  "autoplay",
+  "background",
+  "bgcolor",
+  "border",
+  "buffered",
+  "checked",
+  "cite",
+  "class",
+  "cols",
+  "colspan",
+  "contenteditable",
+  "controls",
+  "coords",
+  "datetime",
+  "decoding",
+  "default",
+  "dir",
+  "dirname",
+  "disabled",
+  "download",
+  "draggable",
+  "for",
+  "form",
+  "headers",
+  "height",
+  "hidden",
+  "high",
+  "href",
+  "hreflang",
+  "id",
+  "inputmode",
+  "ismap",
+  "itemprop",
+  "kind",
+  "label",
+  "lang",
+  "list",
+  "loop",
+  "low",
+  "max",
+  "maxlength",
+  "min",
+  "minlength",
+  "multiple",
+  "muted",
+  "name",
+  "optimum",
+  "pattern",
+  "placeholder",
+  "poster",
+  "preload",
+  "readonly",
+  "required",
+  "reversed",
+  "role",
+  "rows",
+  "rowspan",
+  "scope",
+  "selected",
+  "shape",
+  "size",
+  "sizes",
+  "span",
+  "spellcheck",
+  "src",
+  "srclang",
+  "srcset",
+  "start",
+  "step",
+  "style",
+  "tabindex",
+  "target",
+  "title",
+  "translate",
+  "type",
+  "usemap",
+  "value",
+  "width",
+  "wrap",
+]);
+
+/**
+ * Attribute names whose values are interpreted as URLs by browsers.
+ */
+export const URL_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "href",
+  "src",
+  "action",
+  "formaction",
+  "srcset",
+  "poster",
+  "background",
+]);

package/src/escape/attributes.ts

@@ -0,0 +1,62 @@
+import { sanitizeStyleValue } from "./css";
+import { SAFE_ATTRIBUTES, URL_ATTRIBUTES } from "./attribute-allowlists";
+import { isDangerousUrl } from "./url";
+
+/**
+ * Check whether an HTML attribute name is safe to include in rendered output.
+ *
+ * The check applies three rules in order:
+ * 1. Block all event handlers (`on*` prefix) unconditionally
+ * 2. Allow accessibility (`aria-*`) and custom data (`data-*`) attributes
+ * 3. Allow only attributes in the `SAFE_ATTRIBUTES` allowlist
+ *
+ * @param name - The attribute name to validate (case-insensitive).
+ * @returns `true` if the attribute is safe to render.
+ */
+export function isSafeAttribute(name: string): boolean {
+  const lower = name.toLowerCase();
+  return isSafeAttributeLower(lower);
+}
+
+export function isSafeAttributeLower(lower: string): boolean {
+  // Block all event handlers
+  if (lower.startsWith("on")) return false;
+  // Allow aria-* and data-* prefixes
+  if (lower.startsWith("aria-") || lower.startsWith("data-")) return true;
+  return SAFE_ATTRIBUTES.has(lower);
+}
+
+/**
+ * Sanitize a map of HTML attributes, returning a new map containing
+ * only entries that pass all safety checks.
+ *
+ * For each attribute, this function:
+ * 1. Drops attributes that fail {@link isSafeAttribute} (event handlers, unknown names)
+ * 2. Drops URL-bearing attributes whose values fail {@link isDangerousUrl}
+ * 3. Sanitizes `style` values via {@link sanitizeStyleValue}, dropping them entirely
+ *    if the result is empty
+ * 4. Passes all other safe attributes through unchanged
+ *
+ * @param attributes - The raw attribute name-value map to sanitize.
+ * @returns A new map containing only the safe attributes and their (possibly sanitized) values.
+ */
+export function sanitizeAttributes(attributes: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const key in attributes) {
+    const value = attributes[key]!;
+    const lower = key.toLowerCase();
+    if (!isSafeAttributeLower(lower)) continue;
+    // Check URL attributes for dangerous schemes
+    if (URL_ATTRIBUTES.has(lower) && isDangerousUrl(value)) continue;
+    // Sanitize style attribute
+    if (lower === "style") {
+      const sanitized = sanitizeStyleValue(value);
+      if (sanitized) {
+        result[key] = sanitized;
+      }
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
+}

package/src/escape/css-color-functions.ts

@@ -0,0 +1,18 @@
+export function isValidCssColorFunction(color: string): boolean {
+  const fnMatch = color.match(/^(rgba?|hsla?)\(([^)]*)\)$/);
+  if (!fnMatch) {
+    return false;
+  }
+
+  const fn = fnMatch[1]!;
+  const args = fnMatch[2]!
+    .split(",")
+    .map((s) => s.trim())
+    .join(",");
+
+  if (fn.startsWith("rgb")) {
+    return /^\d{1,3},\d{1,3},\d{1,3}(,(0|1|0?\.\d+))?$/.test(args);
+  }
+
+  return /^\d{1,3},\d{1,3}%,\d{1,3}%(,(0|1|0?\.\d+))?$/.test(args);
+}