@wdprlib/render 2.1.0 → 3.0.0

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);
+}

package/src/escape/css-colors.ts

@@ -0,0 +1,183 @@
+/**
+ * Complete set of CSS Level 4 named colors plus CSS-wide keywords
+ * (`transparent`, `currentcolor`, `inherit`, `initial`, `unset`).
+ */
+import { isValidCssColorFunction } from "./css-color-functions";
+
+const CSS_NAMED_COLORS = new Set([
+  "aliceblue",
+  "antiquewhite",
+  "aqua",
+  "aquamarine",
+  "azure",
+  "beige",
+  "bisque",
+  "black",
+  "blanchedalmond",
+  "blue",
+  "blueviolet",
+  "brown",
+  "burlywood",
+  "cadetblue",
+  "chartreuse",
+  "chocolate",
+  "coral",
+  "cornflowerblue",
+  "cornsilk",
+  "crimson",
+  "cyan",
+  "darkblue",
+  "darkcyan",
+  "darkgoldenrod",
+  "darkgray",
+  "darkgreen",
+  "darkgrey",
+  "darkkhaki",
+  "darkmagenta",
+  "darkolivegreen",
+  "darkorange",
+  "darkorchid",
+  "darkred",
+  "darksalmon",
+  "darkseagreen",
+  "darkslateblue",
+  "darkslategray",
+  "darkslategrey",
+  "darkturquoise",
+  "darkviolet",
+  "deeppink",
+  "deepskyblue",
+  "dimgray",
+  "dimgrey",
+  "dodgerblue",
+  "firebrick",
+  "floralwhite",
+  "forestgreen",
+  "fuchsia",
+  "gainsboro",
+  "ghostwhite",
+  "gold",
+  "goldenrod",
+  "gray",
+  "green",
+  "greenyellow",
+  "grey",
+  "honeydew",
+  "hotpink",
+  "indianred",
+  "indigo",
+  "ivory",
+  "khaki",
+  "lavender",
+  "lavenderblush",
+  "lawngreen",
+  "lemonchiffon",
+  "lightblue",
+  "lightcoral",
+  "lightcyan",
+  "lightgoldenrodyellow",
+  "lightgray",
+  "lightgreen",
+  "lightgrey",
+  "lightpink",
+  "lightsalmon",
+  "lightseagreen",
+  "lightskyblue",
+  "lightslategray",
+  "lightslategrey",
+  "lightsteelblue",
+  "lightyellow",
+  "lime",
+  "limegreen",
+  "linen",
+  "magenta",
+  "maroon",
+  "mediumaquamarine",
+  "mediumblue",
+  "mediumorchid",
+  "mediumpurple",
+  "mediumseagreen",
+  "mediumslateblue",
+  "mediumspringgreen",
+  "mediumturquoise",
+  "mediumvioletred",
+  "midnightblue",
+  "mintcream",
+  "mistyrose",
+  "moccasin",
+  "navajowhite",
+  "navy",
+  "oldlace",
+  "olive",
+  "olivedrab",
+  "orange",
+  "orangered",
+  "orchid",
+  "palegoldenrod",
+  "palegreen",
+  "paleturquoise",
+  "palevioletred",
+  "papayawhip",
+  "peachpuff",
+  "peru",
+  "pink",
+  "plum",
+  "powderblue",
+  "purple",
+  "rebeccapurple",
+  "red",
+  "rosybrown",
+  "royalblue",
+  "saddlebrown",
+  "salmon",
+  "sandybrown",
+  "seagreen",
+  "seashell",
+  "sienna",
+  "silver",
+  "skyblue",
+  "slateblue",
+  "slategray",
+  "slategrey",
+  "snow",
+  "springgreen",
+  "steelblue",
+  "tan",
+  "teal",
+  "thistle",
+  "tomato",
+  "turquoise",
+  "violet",
+  "wheat",
+  "white",
+  "whitesmoke",
+  "yellow",
+  "yellowgreen",
+  "transparent",
+  "currentcolor",
+  "inherit",
+  "initial",
+  "unset",
+]);
+
+/**
+ * Validate that a string is a safe CSS color value.
+ */
+export function isValidCssColor(color: string): boolean {
+  const trimmed = color.trim().toLowerCase();
+
+  if (!trimmed) return false;
+  if (CSS_NAMED_COLORS.has(trimmed)) return true;
+
+  if (/^#[0-9a-f]{3}([0-9a-f])?$/.test(trimmed) || /^#[0-9a-f]{6}([0-9a-f]{2})?$/.test(trimmed)) {
+    return true;
+  }
+
+  if (isValidCssColorFunction(trimmed)) return true;
+
+  return false;
+}
+
+export function sanitizeCssColor(color: string, fallback = "inherit"): string {
+  return isValidCssColor(color) ? color : fallback;
+}

package/src/escape/css-danger.ts

@@ -0,0 +1,22 @@
+import { normalizeCssValue } from "./css-normalize";
+import { isCssUrlAllowed, iterateCssUrls } from "./css-urls";
+
+/**
+ * Check whether a CSS property value contains dangerous patterns that
+ * could enable script execution or disallowed external resource loading.
+ */
+export function isDangerousCssValue(value: string): boolean {
+  const normalized = normalizeCssValue(value);
+
+  for (const { inner, malformed } of iterateCssUrls(normalized)) {
+    if (malformed) return true;
+    if (!isCssUrlAllowed(inner)) return true;
+  }
+
+  if (normalized.includes("expression(")) return true;
+  if (normalized.includes("-moz-binding")) return true;
+  if (normalized.includes("behavior:")) return true;
+  if (normalized.includes("@import")) return true;
+
+  return false;
+}

package/src/escape/css-normalize.ts

@@ -0,0 +1,54 @@
+/**
+ * Normalize a CSS value by resolving escape sequences, removing comments,
+ * stripping whitespace and control characters, and lowercasing.
+ */
+export function normalizeCssValue(value: string): string {
+  let result = value;
+
+  result = stripCssComments(result);
+  result = result.replace(/\\(?:\r\n|[\n\r\f])/g, "");
+  result = result.replace(/\\([0-9a-f]{1,6})\s?/gi, (_, hex) => {
+    const code = Number.parseInt(hex, 16);
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : "";
+  });
+  result = result.replace(/\\(.)/g, "$1");
+  result = stripControlAndWhitespace(result);
+
+  return result.toLowerCase();
+}
+
+const WHITESPACE = /\s/;
+
+function stripCssComments(value: string): string {
+  let result = "";
+  let cursor = 0;
+
+  while (cursor < value.length) {
+    const start = value.indexOf("/*", cursor);
+    if (start === -1) {
+      result += value.slice(cursor);
+      break;
+    }
+
+    result += value.slice(cursor, start);
+    const end = value.indexOf("*/", start + 2);
+    if (end === -1) {
+      break;
+    }
+    cursor = end + 2;
+  }
+
+  return result;
+}
+
+function stripControlAndWhitespace(value: string): string {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (WHITESPACE.test(char) || code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}