@wdprlib/render 2.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdprlib/render",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "HTML renderer for Wikidot markup",
   "keywords": [
     "html",
@@ -16,7 +16,8 @@
     "directory": "packages/render"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "sideEffects": false,
@@ -25,6 +26,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -39,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@wdprlib/ast": "2.0.0",
+    "@wdprlib/ast": "2.1.0",
     "domhandler": "^5.0.3",
     "htmlparser2": "^10.0.0",
     "sanitize-html": "^2.14.0",

package/src/context/attributes.ts

@@ -0,0 +1,14 @@
+import { escapeAttr, sanitizeAttributes } from "../escape";
+
+export function renderAttributeString(attributes: Record<string, string>): string {
+  const safe = sanitizeAttributes(attributes);
+  let result = "";
+  for (const [key, value] of Object.entries(safe)) {
+    if (value !== "") {
+      result += ` ${key}="${escapeAttr(value)}"`;
+    } else {
+      result += ` ${key}=""`;
+    }
+  }
+  return result;
+}

package/src/context/bibliography.ts

@@ -0,0 +1,109 @@
+import type { BibliographyBlockData, Element, ListData, TableData, TabData } from "@wdprlib/ast";
+
+interface BibliographyState {
+  map: Map<string, number>;
+}
+
+export class BibliographyIndex {
+  private state: BibliographyState | null = null;
+
+  constructor(private readonly elements: Element[]) {}
+
+  getCitationNumber(label: string): number | undefined {
+    return this.getState().map.get(label);
+  }
+
+  private getState(): BibliographyState {
+    if (this.state === null) {
+      this.state = collectBibliographyState(this.elements);
+    }
+    return this.state;
+  }
+}
+
+function collectBibliographyState(elements: Element[]): BibliographyState {
+  const state: BibliographyState = {
+    map: new Map(),
+  };
+  collectFromElements(elements, state);
+  return state;
+}
+
+function collectFromElements(elements: Element[], state: BibliographyState): void {
+  for (const element of elements) {
+    if (element.element === "bibliography-block") {
+      addBlockEntries(element.data, state);
+    }
+
+    collectFromChildren(element, state);
+  }
+}
+
+function addBlockEntries(data: BibliographyBlockData, state: BibliographyState): void {
+  for (const entry of data.entries) {
+    if (state.map.has(entry.key_string)) continue;
+
+    state.map.set(entry.key_string, state.map.size + 1);
+  }
+}
+
+function collectFromChildren(element: Element, state: BibliographyState): void {
+  switch (element.element) {
+    case "list":
+      collectFromList(element.data, state);
+      return;
+    case "table":
+      collectFromTable(element.data, state);
+      return;
+    case "definition-list":
+      for (const item of element.data) {
+        collectFromElements(item.key, state);
+        collectFromElements(item.value, state);
+      }
+      return;
+    case "tab-view":
+      collectFromTabs(element.data, state);
+      return;
+    default:
+      break;
+  }
+
+  if (hasElementChildren(element)) {
+    collectFromElements(element.data.elements, state);
+  }
+}
+
+function collectFromList(data: ListData, state: BibliographyState): void {
+  for (const item of data.items) {
+    if (item["item-type"] === "elements") {
+      collectFromElements(item.elements, state);
+    } else {
+      collectFromList(item.data, state);
+    }
+  }
+}
+
+function collectFromTable(data: TableData, state: BibliographyState): void {
+  for (const row of data.rows) {
+    for (const cell of row.cells) {
+      collectFromElements(cell.elements, state);
+    }
+  }
+}
+
+function collectFromTabs(tabs: TabData[], state: BibliographyState): void {
+  for (const tab of tabs) {
+    collectFromElements(tab.elements, state);
+  }
+}
+
+function hasElementChildren(
+  element: Element,
+): element is Element & { data: { elements: Element[] } } {
+  if (!("data" in element)) return false;
+
+  const data: unknown = element.data;
+  return (
+    data !== null && typeof data === "object" && "elements" in data && Array.isArray(data.elements)
+  );
+}

package/src/context/counters.ts

@@ -0,0 +1,51 @@
+export class RenderCounters {
+  private tocIndex = 0;
+  private footnoteIndex = 0;
+  private equationIndex = 0;
+  private htmlBlockIndex = 0;
+  private bibciteCounter = 0;
+  private tabViewIndex = 0;
+  private readonly idSuffix: string | null;
+
+  constructor(useTrueIds: boolean) {
+    this.idSuffix = useTrueIds ? null : Math.random().toString(16).slice(2, 8);
+  }
+
+  nextTocIndex(): number {
+    return this.tocIndex++;
+  }
+
+  nextFootnoteIndex(): number {
+    return this.footnoteIndex++;
+  }
+
+  nextEquationIndex(): number {
+    return this.equationIndex++;
+  }
+
+  nextHtmlBlockIndex(): number {
+    return this.htmlBlockIndex++;
+  }
+
+  nextBibciteCounter(): number {
+    return ++this.bibciteCounter;
+  }
+
+  nextTabViewIndex(): number {
+    return this.tabViewIndex++;
+  }
+
+  generateId(prefix: string, index: number | string): string {
+    if (this.idSuffix === null) {
+      return `${prefix}${index}`;
+    }
+    return `${prefix}${index}-${this.idSuffix}`;
+  }
+
+  generateFixedId(name: string): string {
+    if (this.idSuffix === null) {
+      return name;
+    }
+    return `${name}-${this.idSuffix}`;
+  }
+}

package/src/context/image-urls.ts

@@ -0,0 +1,31 @@
+import type { ImageSource, WikitextSettings } from "@wdprlib/ast";
+import type { PageContext } from "../types";
+
+export function resolveImageSource(
+  source: ImageSource,
+  settings: WikitextSettings,
+  page: PageContext | undefined,
+): string | null {
+  const pageName = page?.pageName;
+  switch (source.type) {
+    case "url": {
+      const url = source.data;
+      if (url.startsWith("/") && !url.startsWith("//")) {
+        if (!settings.allowLocalPaths) return null;
+        return `/local--files${url}`;
+      }
+      return url;
+    }
+    case "file1":
+      if (!settings.allowLocalPaths) return null;
+      return pageName
+        ? `/local--files/${pageName}/${source.data.file}`
+        : `/local--files/${source.data.file}`;
+    case "file2":
+      if (!settings.allowLocalPaths) return null;
+      return `/local--files/${source.data.page}/${source.data.file}`;
+    case "file3":
+      if (!settings.allowLocalPaths) return null;
+      return `/local--files/${source.data.site}/${source.data.page}/${source.data.file}`;
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,285 @@
+/**
+ *
+ * Central rendering context that tracks state during a single HTML render pass.
+ *
+ * Every render invocation creates one {@link RenderContext} instance, which serves
+ * as both an output buffer and a registry for sequential counters (footnotes,
+ * TOC headings, equations, HTML blocks, bibliography citations). The context
+ * also exposes helpers for resolving image sources, page links, and
+ * HTML attribute maps -- operations that depend on the current
+ * {@link WikitextSettings} and {@link PageContext}.
+ *
+ * @module
+ */
+
+import type {
+  Element,
+  ImageSource,
+  LinkLocation,
+  SyntaxTree,
+  WikitextSettings,
+} from "@wdprlib/ast";
+import { DEFAULT_SETTINGS } from "@wdprlib/ast";
+import type { RenderOptions, PageContext } from "../types";
+import { renderAttributeString } from "./attributes";
+import { BibliographyIndex } from "./bibliography";
+import { RenderCounters } from "./counters";
+import { RenderOutputBuffer } from "./output";
+import { StyleSlotState } from "./style-slots";
+import {
+  resolveImageSource as resolveImageSourceUrl,
+  resolvePageLink as resolvePageLinkUrl,
+} from "./urls";
+
+/**
+ * Manages rendering state and accumulates HTML output for a single render pass.
+ *
+ * The context is created once per call to `renderToHtml` and threaded through
+ * every element renderer. It provides:
+ *
+ * - An HTML output buffer ({@link push}, {@link pushEscaped}, {@link getOutput})
+ * - Sequential counters for footnotes, TOC entries, equations, etc.
+ * - ID generation that optionally appends a random suffix to avoid collisions
+ *   when multiple rendered fragments coexist on the same page
+ * - Resolution of {@link ImageSource} and {@link LinkLocation} values into
+ *   concrete URLs, applying Wikidot page-name normalization rules
+ * - Attribute rendering with XSS sanitization
+ * - A lazy bibliography citation index built from `bibliography-block`
+ *   elements when a citation is rendered
+ */
+export class RenderContext {
+  /** Accumulated HTML fragments; joined by {@link getOutput}. */
+  private output = new RenderOutputBuffer();
+  /**
+   * When true, style elements in the AST are rendered rather than
+   * silently skipped. Set while rendering children of unresolved
+   * `[[iftags]]` blocks whose styles were not collected during resolve.
+   */
+  renderInlineStyles = false;
+  /** State for style slots collected while rendering unresolved `[[iftags]]` blocks. */
+  private _styleSlots = new StyleSlotState();
+  /** Sequential counters and ID suffix state for this render pass. */
+  private counters: RenderCounters;
+
+  /** Merged wikitext settings (page-mode defaults when omitted). */
+  readonly settings: WikitextSettings;
+  /** Full render options supplied by the caller. */
+  readonly options: RenderOptions;
+  /** Footnote element arrays collected from the syntax tree. */
+  readonly footnotes: Element[][];
+  /** CSS `<style>` blocks extracted from the syntax tree. */
+  readonly styles: string[];
+  /** Raw HTML strings for `[[html]]` blocks, indexed by insertion order. */
+  readonly htmlBlocks: string[];
+  /** Pre-built TOC element tree for `[[toc]]` rendering. */
+  readonly tocElements: Element[];
+  /** Lazily built bibliography lookup data. */
+  private readonly bibliography: BibliographyIndex;
+
+  /**
+   * Create a new render context from a parsed syntax tree.
+   *
+   * @param tree - The syntax tree produced by the parser. Footnotes,
+   *   styles, html-blocks, and table-of-contents data are extracted from
+   *   the tree and stored for later use by element renderers.
+   * @param options - Caller-supplied render configuration. Missing fields
+   *   fall back to safe defaults.
+   */
+  constructor(tree: SyntaxTree, options: RenderOptions = {}) {
+    this.settings = options.settings ?? DEFAULT_SETTINGS;
+    this.counters = new RenderCounters(this.settings.useTrueIds);
+    this.options = options;
+    this.footnotes = options.footnotes ?? tree.footnotes ?? [];
+    this.styles = tree.styles ?? [];
+    this.htmlBlocks = tree["html-blocks"] ?? [];
+    this.tocElements = tree["table-of-contents"] ?? [];
+
+    this.bibliography = new BibliographyIndex(tree.elements);
+  }
+
+  /** Return the 1-indexed bibliography citation number for a label, if defined. */
+  getBibliographyCitationNumber(label: string): number | undefined {
+    return this.bibliography.getCitationNumber(label);
+  }
+
+  /**
+   * Append a raw HTML string to the output buffer without escaping.
+   *
+   * @param html - Trusted HTML fragment to append.
+   */
+  push(html: string): void {
+    this.output.push(html);
+  }
+
+  /**
+   * HTML-escape the given text and append it to the output buffer.
+   *
+   * @param text - Untrusted text content (will be entity-escaped).
+   */
+  pushEscaped(text: string): void {
+    this.output.pushEscaped(text);
+  }
+
+  /**
+   * Join all buffered HTML fragments and return the final HTML string.
+   *
+   * @returns The complete rendered HTML output.
+   */
+  getOutput(): string {
+    return this.output.getOutput();
+  }
+
+  /** Enter a style slot: subsequent {@link pushToStyleSlot} calls collect into this slot. */
+  enterStyleSlot(slotId: number): void {
+    this._styleSlots.enter(slotId);
+  }
+
+  /** Exit the current style slot. */
+  exitStyleSlot(): void {
+    this._styleSlots.exit();
+  }
+
+  /** Whether a style slot is currently active. */
+  hasActiveStyleSlot(): boolean {
+    return this._styleSlots.hasActiveSlot();
+  }
+
+  /** Push a CSS string into the active style slot. */
+  pushToStyleSlot(css: string): void {
+    this._styleSlots.push(css);
+  }
+
+  /** Retrieve collected CSS strings for a given style slot. */
+  getStyleSlotContents(slotId: number): string[] {
+    return this._styleSlots.getContents(slotId);
+  }
+
+  /**
+   * Return the current TOC heading index and advance the counter.
+   *
+   * @returns The index before incrementing (0-based).
+   */
+  nextTocIndex(): number {
+    return this.counters.nextTocIndex();
+  }
+
+  /**
+   * Return the current footnote index and advance the counter.
+   *
+   * @returns The index before incrementing (0-based).
+   */
+  nextFootnoteIndex(): number {
+    return this.counters.nextFootnoteIndex();
+  }
+
+  /**
+   * Return the current equation index and advance the counter.
+   *
+   * @returns The index before incrementing (0-based).
+   */
+  nextEquationIndex(): number {
+    return this.counters.nextEquationIndex();
+  }
+
+  /**
+   * Return the current HTML block index and advance the counter.
+   *
+   * @returns The index before incrementing (0-based).
+   */
+  nextHtmlBlockIndex(): number {
+    return this.counters.nextHtmlBlockIndex();
+  }
+
+  /**
+   * Advance the bibliography citation counter and return the new value.
+   * Used to generate unique `bibcite-N-XXXXX` element IDs.
+   *
+   * @returns The counter value after incrementing (1-based).
+   */
+  nextBibciteCounter(): number {
+    return this.counters.nextBibciteCounter();
+  }
+
+  /**
+   * Return the current tab-view index and advance the counter.
+   *
+   * @returns The index before incrementing (0-based).
+   */
+  nextTabViewIndex(): number {
+    return this.counters.nextTabViewIndex();
+  }
+
+  /**
+   * Generate an element ID.
+   * When useTrueIds is true, returns `${prefix}${index}`.
+   * When false, appends a random suffix to prevent collisions across fragments.
+   */
+  generateId(prefix: string, index: number | string): string {
+    return this.counters.generateId(prefix, index);
+  }
+
+  /**
+   * Generate a fixed element ID (no index).
+   * When useTrueIds is false, appends a random suffix.
+   */
+  generateFixedId(name: string): string {
+    return this.counters.generateFixedId(name);
+  }
+
+  /**
+   * The page context for the current render, if provided.
+   * Contains page name, site, tags, and a page-existence checker.
+   */
+  get page(): PageContext | undefined {
+    return this.options.page;
+  }
+
+  /**
+   * Resolve an {@link ImageSource} to a concrete `src` URL string.
+   *
+   * Wikidot supports several image source forms:
+   * - `url` -- a direct URL or local path
+   * - `file1` -- a file attached to the current page (`/local--files/{page}/{file}`)
+   * - `file2` -- a file attached to a named page
+   * - `file3` -- a file on a named site and page
+   *
+   * Local paths (starting with `/` but not `//`) and file-type sources are
+   * blocked when `allowLocalPaths` is false in the settings.
+   *
+   * @param source - The image source descriptor from the AST.
+   * @returns The resolved URL, or `null` if the source is blocked by settings.
+   */
+  resolveImageSource(source: ImageSource): string | null {
+    return resolveImageSourceUrl(source, this.settings, this.page);
+  }
+
+  /**
+   * Resolve a {@link LinkLocation} to an `href` string.
+   *
+   * Handles plain URL strings and structured `PageRef` objects. For page
+   * references the page name is normalized to lowercase, spaces are replaced
+   * with hyphens, and slashes become hyphens (Wikidot URL convention).
+   * Anchors (`#`) and cross-site references (`site` field) are handled.
+   *
+   * @param location - A raw URL string or a `PageRef` object from the AST.
+   * @returns The resolved href string, starting with `/` for local or unresolved
+   *   cross-site pages and `https://` when a cross-site domain is known.
+   */
+  resolvePageLink(location: LinkLocation): string {
+    return resolvePageLinkUrl(location, this.page);
+  }
+
+  /**
+   * Sanitize and render an attribute map to an HTML attribute string.
+   *
+   * Dangerous attributes (event handlers, unsafe URLs) are stripped by
+   * {@link sanitizeAttributes}. Each surviving key-value pair is escaped
+   * and formatted as ` key="value"`.
+   *
+   * @param attributes - Raw attribute map from the AST.
+   * @returns A string of HTML attributes with a leading space, or `""` if empty.
+   */
+  renderAttributes(attributes: Record<string, string>): string {
+    return renderAttributeString(attributes);
+  }
+}

package/src/context/output.ts

@@ -0,0 +1,17 @@
+import { escapeHtml } from "../escape";
+
+export class RenderOutputBuffer {
+  private chunks: string[] = [];
+
+  push(html: string): void {
+    this.chunks.push(html);
+  }
+
+  pushEscaped(text: string): void {
+    this.chunks.push(escapeHtml(text));
+  }
+
+  getOutput(): string {
+    return this.chunks.join("");
+  }
+}

package/src/context/page-urls.ts

@@ -0,0 +1,81 @@
+import type { LinkLocation } from "@wdprlib/ast";
+import type { PageContext } from "../types";
+
+export function resolvePageLink(
+  location: LinkLocation,
+  pageContext: PageContext | undefined,
+): string {
+  if (typeof location === "string") {
+    return location;
+  }
+
+  const page = location.page;
+  if (page.startsWith("//")) {
+    return page.toLowerCase();
+  }
+
+  const hashIdx = page.indexOf("#");
+  if (hashIdx !== -1) {
+    let pagePart = page.slice(0, hashIdx);
+    const anchor = page.slice(hashIdx);
+    if (pagePart.endsWith("/")) {
+      pagePart = pagePart.slice(0, -1);
+    }
+    return `/${pagePart.toLowerCase()}${anchor.toLowerCase()}`;
+  }
+
+  const normalizedPage = normalizePageName(page);
+  const safePage = normalizedPage.startsWith("/") ? normalizedPage.slice(1) : normalizedPage;
+
+  if (location.site) {
+    const domain = resolveSiteDomain(location.site, pageContext);
+    if (domain !== null) {
+      return `https://${domain}/${safePage}`;
+    }
+    return `/${normalizePageName(location.site)}/${safePage}`;
+  }
+  return `/${safePage}`;
+}
+
+function resolveSiteDomain(site: string, pageContext: PageContext | undefined): string | null {
+  const configuredDomain =
+    pageContext?.resolveSiteDomain?.(site) ??
+    pageContext?.siteDomains?.[site] ??
+    (pageContext?.site === site ? pageContext.domain : undefined);
+
+  if (configuredDomain) return normalizeDomain(configuredDomain);
+  if (site.includes(".")) {
+    return normalizeDomain(site);
+  }
+  return null;
+}
+
+function normalizeDomain(domain: string): string {
+  let normalized = domain;
+  const lower = normalized.toLowerCase();
+  if (lower.startsWith("https://")) {
+    normalized = normalized.slice("https://".length);
+  } else if (lower.startsWith("http://")) {
+    normalized = normalized.slice("http://".length);
+  }
+
+  let end = normalized.length;
+  while (end > 0 && normalized[end - 1] === "/") {
+    end--;
+  }
+  return end === normalized.length ? normalized : normalized.slice(0, end);
+}
+
+function normalizePageName(page: string): string {
+  let normalized = page.toLowerCase();
+  if (normalized.indexOf(":") !== -1) {
+    normalized = normalized.replace(/:\s+/g, ":");
+  }
+  if (/\s/.test(normalized)) {
+    normalized = normalized.replace(/\s+/g, "-").trim();
+  }
+  if (!normalized.startsWith("/") && normalized.indexOf("/") !== -1) {
+    normalized = normalized.replace(/\//g, "-");
+  }
+  return normalized;
+}

package/src/context/style-slots.ts

@@ -0,0 +1,29 @@
+export class StyleSlotState {
+  private activeSlotId: number | null = null;
+  private contents = new Map<number, string[]>();
+
+  enter(slotId: number): void {
+    this.activeSlotId = slotId;
+    if (!this.contents.has(slotId)) {
+      this.contents.set(slotId, []);
+    }
+  }
+
+  exit(): void {
+    this.activeSlotId = null;
+  }
+
+  hasActiveSlot(): boolean {
+    return this.activeSlotId !== null;
+  }
+
+  push(css: string): void {
+    if (this.activeSlotId !== null) {
+      this.contents.get(this.activeSlotId)!.push(css);
+    }
+  }
+
+  getContents(slotId: number): string[] {
+    return this.contents.get(slotId) ?? [];
+  }
+}

package/src/context/urls.ts

@@ -0,0 +1,2 @@
+export { resolveImageSource } from "./image-urls";
+export { resolvePageLink } from "./page-urls";

package/src/elements/bibliography/block.ts

@@ -0,0 +1,27 @@
+import type { BibliographyBlockData, Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+
+export function renderBibliographyBlock(
+  ctx: RenderContext,
+  data: BibliographyBlockData,
+  renderElements: (ctx: RenderContext, elements: Element[]) => void,
+): void {
+  if (data.hide) return;
+
+  const title = data.title ?? "Bibliography";
+  ctx.push(`<div class="bibitems">`);
+  ctx.push(`<div class="title">${escapeHtml(title)}</div>`);
+
+  let index = 1;
+  for (const entry of data.entries) {
+    const itemId = ctx.generateId("bibitem-", index);
+    ctx.push(`<div class="bibitem" id="${itemId}">`);
+    ctx.push(`${index}. `);
+    renderElements(ctx, entry.value);
+    ctx.push("</div>");
+    index++;
+  }
+
+  ctx.push("</div>");
+}