@wdprlib/render 2.1.0 → 3.0.0

package/src/elements/math.ts

@@ -1,177 +0,0 @@
-/**
- *
- * Renderers for Wikidot mathematical notation elements.
- *
- * - `[[math]]...[[/math]]` -- display-mode (block) math
- * - `[[$ ... $]]` -- inline math
- * - `[[eref name]]` -- equation reference (link to named equation)
- *
- * LaTeX source is converted to MathML using the `temml` library at
- * render time. A hidden `<code class="math-source">` element preserves
- * the original LaTeX for use by the runtime `math` module's SVG polyfill
- * (for browsers without MathML support).
- *
- * Named equations receive an `(N)` equation number and can be
- * cross-referenced via `[[eref]]`.
- *
- * @module
- */
-
-import type { MathData, MathInlineData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, escapeHtml } from "../escape";
-import temml from "temml";
-
-/**
- * Determine whether a LaTeX string needs to be wrapped in an `aligned`
- * environment.
- *
- * Wikidot-style multi-line equations use `&` as alignment markers without
- * explicitly declaring an `aligned` environment. If the LaTeX contains
- * unescaped `&` characters but no `\begin{...}` environment declaration,
- * an `aligned` wrapper is added to make the alignment work correctly.
- *
- * @param latex - Raw LaTeX source string.
- * @returns `true` if the LaTeX needs an `aligned` environment wrapper.
- */
-function needsAlignedWrapper(latex: string): boolean {
-  // Already has an environment
-  if (/\\begin\s*\{/.test(latex)) {
-    return false;
-  }
-  // Has alignment marker (&) but not escaped (\&) - needs aligned environment
-  // Remove escaped ampersands first, then check for unescaped ones
-  const withoutEscaped = latex.replace(/\\&/g, "");
-  return withoutEscaped.includes("&");
-}
-
-/**
- * Render a LaTeX string to MathML using the `temml` library.
- *
- * For display-mode equations with alignment markers, the LaTeX is
- * automatically wrapped in an `aligned` environment.
- *
- * @param latex - LaTeX source string.
- * @param displayMode - Whether to render in display mode (block) or inline.
- * @returns MathML string, or `""` if rendering fails.
- */
-function renderLatexToMathML(latex: string, displayMode: boolean): string {
-  try {
-    // Wrap in aligned environment if needed for Wikidot-style alignment
-    let processedLatex = latex;
-    if (displayMode && needsAlignedWrapper(latex)) {
-      processedLatex = `\\begin{aligned}\n${latex}\n\\end{aligned}`;
-    }
-    return temml.renderToString(processedLatex, {
-      displayMode,
-      throwOnError: false,
-      annotate: false,
-    });
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Render a `[[math]]` display-mode block equation.
- *
- * Produces a `<div class="math-block">` containing:
- * - An optional equation number `<span class="equation-number">` for named equations
- * - A hidden `<code class="math-source">` with the raw LaTeX (for polyfill use)
- * - A `<span class="math-render">` with the MathML output (or error fallback)
- *
- * @param ctx - The current render context.
- * @param data - Math block data with LaTeX source and optional equation name.
- */
-export function renderMath(ctx: RenderContext, data: MathData): void {
-  const index = ctx.nextEquationIndex() + 1;
-  const latex = data["latex-source"];
-  const mathml = renderLatexToMathML(latex, true);
-
-  const id = data.name
-    ? ctx.generateId("equation-", data.name)
-    : ctx.generateId("equation-", index);
-  const dataName = data.name ? ` data-name="${escapeAttr(data.name)}"` : "";
-
-  ctx.push(`<div class="math-block" id="${escapeAttr(id)}"${dataName}>`);
-
-  // Equation number (only for named equations)
-  if (data.name) {
-    ctx.push(`<span class="equation-number">(${index})</span>`);
-  }
-
-  // Hidden LaTeX source (for polyfill)
-  ctx.push(`<code class="math-source" hidden aria-hidden="true">`);
-  ctx.push(escapeHtml(latex));
-  ctx.push(`</code>`);
-
-  // MathML output
-  ctx.push(`<span class="math-render">`);
-  if (mathml) {
-    ctx.push(mathml);
-  } else {
-    // Fallback: display error
-    ctx.push(`<span class="math-error">`);
-    ctx.push(escapeHtml(latex));
-    ctx.push(`</span>`);
-  }
-  ctx.push(`</span>`);
-
-  ctx.push("</div>");
-}
-
-/**
- * Render an inline math element (`[[$...$]]`).
- *
- * Produces a `<span class="math-inline">` containing:
- * - A hidden `<code class="math-source">` with the raw LaTeX
- * - A `<span class="math-render">` with the MathML output (or `$...$` error fallback)
- *
- * @param ctx - The current render context.
- * @param data - Inline math data with LaTeX source.
- */
-export function renderMathInline(ctx: RenderContext, data: MathInlineData): void {
-  const latex = data["latex-source"];
-  const mathml = renderLatexToMathML(latex, false);
-
-  ctx.push(`<span class="math-inline">`);
-
-  // Hidden LaTeX source (for polyfill)
-  ctx.push(`<code class="math-source" hidden aria-hidden="true">`);
-  ctx.push(escapeHtml(latex));
-  ctx.push(`</code>`);
-
-  // MathML output
-  ctx.push(`<span class="math-render">`);
-  if (mathml) {
-    ctx.push(mathml);
-  } else {
-    // Fallback: display with $ delimiters
-    ctx.push(`<span class="math-error">$`);
-    ctx.push(escapeHtml(latex));
-    ctx.push(`$</span>`);
-  }
-  ctx.push(`</span>`);
-
-  ctx.push("</span>");
-}
-
-/**
- * Render an equation reference (`[[eref name]]`) that links to a named equation.
- *
- * Produces a `<span class="eref">` containing a link to the equation's
- * `#equation-{name}` ID and an empty tooltip span that the runtime
- * `math` module populates on hover with a preview of the equation.
- *
- * @param ctx - The current render context.
- * @param name - The equation name to reference.
- */
-export function renderEquationRef(ctx: RenderContext, name: string): void {
-  const id = ctx.generateId("equation-", name);
-  ctx.push(`<span class="eref" data-target="${escapeAttr(id)}">`);
-  ctx.push(`<a class="eref-link" href="#${escapeAttr(id)}">`);
-  ctx.push(escapeHtml(name));
-  ctx.push(`</a>`);
-  ctx.push(`<span class="eref-tooltip" aria-hidden="true"></span>`);
-  ctx.push("</span>");
-}

package/src/elements/tab-view.ts

@@ -1,75 +0,0 @@
-/**
- *
- * Renderer for `[[tabview]]...[[/tabview]]` tab containers.
- *
- * Wikidot uses a YUI-compatible tabview widget. The rendered HTML follows
- * the YUI class naming convention (`yui-navset`, `yui-nav`, `yui-content`)
- * and uses inline `display` styles for tab visibility. Tab switching is
- * handled at runtime by the `tabview` runtime module.
- *
- * A deterministic widget ID is generated from an MD5-length hash of the
- * concatenated tab labels, ensuring stable IDs across renders.
- *
- * @module
- */
-
-import type { TabData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeHtml } from "../escape";
-import { syncHashMd5 } from "../hash";
-import { renderElements } from "../render";
-
-/**
- * Render a `[[tabview]]` element with YUI-compatible HTML structure.
- *
- * The first tab is selected by default (visible, with the `selected` class
- * on its nav item). All other tabs have `display:none` on their content divs.
- *
- * @param ctx - The current render context.
- * @param tabs - Array of tab data, each with a label and child elements.
- */
-export function renderTabView(ctx: RenderContext, tabs: TabData[]): void {
-  // Generate MD5 hash from tab labels
-  const labelString = tabs.map((t) => t.label).join("");
-  const hash = md5Hash(labelString);
-
-  const widgetId = ctx.generateFixedId(`wiki-tabview-${hash}`);
-
-  // Container
-  ctx.push(`<div id="${widgetId}" class="yui-navset">`);
-
-  // Navigation tabs
-  ctx.push(`<ul class="yui-nav">`);
-  for (let i = 0; i < tabs.length; i++) {
-    const tab = tabs[i]!;
-    const selectedClass = i === 0 ? ` class="selected"` : "";
-    ctx.push(`<li${selectedClass}>`);
-    ctx.push(`<a href="javascript:;"><em>${escapeHtml(tab.label)}</em></a>`);
-    ctx.push("</li>");
-  }
-  ctx.push("</ul>");
-
-  // Content panels
-  ctx.push(`<div class="yui-content">`);
-  for (let i = 0; i < tabs.length; i++) {
-    const tab = tabs[i]!;
-    const displayStyle = i === 0 ? "" : ` style="display:none"`;
-    const tabId = ctx.generateId("wiki-tab-0-", i);
-    ctx.push(`<div id="${tabId}"${displayStyle}>`);
-    renderElements(ctx, tab.elements);
-    ctx.push("</div>");
-  }
-  ctx.push("</div>");
-
-  ctx.push("</div>"); // close yui-navset
-}
-
-/**
- * Compute an MD5-length hash of the input string for widget ID generation.
- *
- * @param input - String to hash (typically concatenated tab labels).
- * @returns A 32-character hex hash string.
- */
-function md5Hash(input: string): string {
-  return syncHashMd5(input);
-}

package/src/elements/table.ts

@@ -1,101 +0,0 @@
-/**
- *
- * Renderer for Wikidot table elements.
- *
- * Wikidot supports two table syntaxes:
- * - Pipe syntax (`||cell||cell||`) -- adds `class="wiki-content-table"`
- * - Block syntax (`[[table]]...[[/table]]`) -- no default class
- *
- * Both syntaxes support cell alignment (via tildes), column/row spans,
- * header cells (marked with `~`), and custom attributes on rows and cells.
- *
- * @module
- */
-
-import type { TableData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, sanitizeAttributes } from "../escape";
-import { renderElements } from "../render";
-
-/**
- * Render a table element.
- *
- * Pipe-syntax tables receive `class="wiki-content-table"` on the `<table>`
- * element. Cell alignment is rendered as inline `text-align` styles.
- * Header cells use `<th>` instead of `<td>`. Column and row spans are
- * applied from the AST data and attributes, respectively.
- *
- * @param ctx - The current render context.
- * @param data - Table data with rows, cells, attributes, and source type.
- */
-export function renderTable(ctx: RenderContext, data: TableData): void {
-  // Only add wiki-content-table class for pipe syntax tables
-  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) {
-      const tag = cell.header ? "th" : "td";
-      const attrs: string[] = [];
-      const safeCellAttrs = sanitizeAttributes(cell.attributes);
-
-      if (cell["column-span"] > 1) {
-        attrs.push(`colspan="${cell["column-span"]}"`);
-      }
-
-      // Handle rowspan from attributes
-      if (safeCellAttrs.rowspan) {
-        const rowspan = parseInt(safeCellAttrs.rowspan, 10);
-        if (rowspan > 1) {
-          attrs.push(`rowspan="${rowspan}"`);
-        }
-      }
-
-      if (cell.align) {
-        const existingStyle = safeCellAttrs.style ?? "";
-        const alignStyle = `text-align: ${cell.align};`;
-        if (existingStyle) {
-          attrs.push(`style="${escapeAttr(existingStyle + "; " + alignStyle)}"`);
-        } else {
-          attrs.push(`style="${alignStyle}"`);
-        }
-      }
-
-      // Additional cell attributes
-      for (const [key, value] of Object.entries(safeCellAttrs)) {
-        if (key === "style" && cell.align) continue; // Already handled
-        if (key === "rowspan") continue; // Already handled
-        attrs.push(`${key}="${escapeAttr(value)}"`);
-      }
-
-      const attrStr = attrs.length > 0 ? " " + attrs.join(" ") : "";
-      ctx.push(`<${tag}${attrStr}>`);
-      renderElements(ctx, cell.elements);
-      ctx.push(`</${tag}>`);
-    }
-
-    ctx.push("</tr>");
-  }
-
-  ctx.push("</table>");
-}
-
-/**
- * Sanitize and render table-level or row-level attributes, excluding
- * internal `_`-prefixed keys.
- *
- * @param attributes - Raw attribute map from the AST.
- * @returns An HTML attribute string with leading space, or `""` if empty.
- */
-function renderTableAttrs(attributes: Record<string, string>): string {
-  const safe = sanitizeAttributes(attributes);
-  let result = "";
-  for (const [key, value] of Object.entries(safe)) {
-    if (key.startsWith("_")) continue;
-    result += ` ${key}="${escapeAttr(value)}"`;
-  }
-  return result;
-}

package/src/elements/text.ts

@@ -1,57 +0,0 @@
-/**
- *
- * Renderers for text-level AST nodes: plain text, raw/literal text,
- * and email addresses.
- *
- * @module
- */
-
-import type { RenderContext } from "../context";
-import { escapeAttr, escapeHtml, isValidEmail } from "../escape";
-
-/**
- * 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);
-}
-
-/**
- * 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;">`);
-  // Wikidot encodes spaces as &#32; in raw content
-  ctx.push(escapeHtml(data).replace(/ /g, "&#32;"));
-  ctx.push("</span>");
-}
-
-/**
- * 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 {
-  // Validate email format before creating link
-  if (!isValidEmail(email)) {
-    // Invalid email: render as plain text
-    ctx.pushEscaped(email);
-    return;
-  }
-  ctx.push(`<a href="mailto:${escapeAttr(email)}">${escapeHtml(email)}</a>`);
-}

package/src/elements/toc.ts

@@ -1,147 +0,0 @@
-/**
- *
- * Renderer for `[[toc]]` (Table of Contents) elements.
- *
- * The table of contents is built from the pre-collected `tocElements`
- * in the render context (populated from the `table-of-contents` field
- * of the syntax tree). Each entry is rendered as a `<div>` with
- * `margin-left` indentation based on heading depth, matching Wikidot's
- * flat-div TOC format.
- *
- * The TOC supports fold/unfold toggling via a `#toc-action-bar` with
- * Fold/Unfold links, handled at runtime by the `toc` runtime module.
- * Alignment options (`left`/`right`) produce a floated container.
- *
- * @module
- */
-
-import type { Element, ListData, ListItem, TableOfContentsData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, escapeHtml } from "../escape";
-
-/**
- * Extract text content and href from a link element for TOC rendering.
- *
- * @param element - An AST element (expected to be a link).
- * @returns An object with `href` and `text`, or `null` if not a link.
- */
-function extractLinkText(element: Element): { href: string; text: string } | 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 };
-}
-
-/**
- * Render TOC entries as flat `<div>` elements with `margin-left` indentation.
- *
- * @param ctx - The current render context.
- * @param elements - Top-level TOC elements (expected to contain list elements).
- */
-function renderTocEntries(ctx: RenderContext, elements: Element[]): void {
-  for (const element of elements) {
-    if (element.element === "list") {
-      renderTocList(ctx, element.data, 1);
-    }
-  }
-}
-
-/**
- * Recursively render a TOC list at a given nesting depth.
- *
- * @param ctx - The current render context.
- * @param listData - The list data representing this level of the TOC.
- * @param depth - Current nesting depth (1-based), used for `margin-left` calculation.
- */
-function renderTocList(ctx: RenderContext, listData: ListData, depth: number): void {
-  for (const item of listData.items) {
-    renderTocItem(ctx, item, depth);
-  }
-}
-
-/**
- * Rewrite a TOC anchor `href` (e.g., `"#toc0"`) so that it matches
- * the rendered heading's actual ID.
- *
- * When `useTrueIds` is false, heading IDs have a random suffix appended
- * (e.g., `toc0-a1b2c3`). This function regenerates the ID through the
- * context to ensure the TOC link targets the correct heading.
- *
- * @param ctx - The current render context.
- * @param href - The original href from the TOC link (e.g., `"#toc0"`).
- * @returns The rewritten href with the correct ID.
- */
-function rewriteTocAnchor(ctx: RenderContext, href: string): string {
-  const match = /^#toc(\d+)$/.exec(href);
-  if (!match) return href;
-  return `#${ctx.generateId("toc", Number(match[1]))}`;
-}
-
-/**
- * Render a single TOC list item as a `<div>` with indented margin.
- *
- * @param ctx - The current render context.
- * @param item - The list item (elements or sub-list).
- * @param depth - Current nesting depth for margin calculation.
- */
-function renderTocItem(ctx: RenderContext, item: ListItem, depth: number): void {
-  if (item["item-type"] === "elements") {
-    for (const el of item.elements) {
-      const link = extractLinkText(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);
-  }
-}
-
-/**
- * Render a `[[toc]]` table of contents block.
- *
- * Non-floating TOC is wrapped in a `<table>` for Wikidot layout compatibility.
- * Floating TOC (align `left` or `right`) uses a `<div>` with a float class.
- *
- * The TOC container uses fixed IDs (`#toc`, `#toc-action-bar`, `#toc-list`)
- * that the runtime `toc` module queries for fold/unfold toggling.
- *
- * @param ctx - The current render context.
- * @param data - TOC configuration data with optional alignment.
- */
-export function renderTableOfContents(ctx: RenderContext, data: TableOfContentsData): void {
-  const isFloat = data.align === "left" || data.align === "right";
-
-  // Non-float: wrap in table (Wikidot behavior)
-  if (!isFloat) {
-    ctx.push(`<table style="margin:0; padding:0"><tr><td style="margin:0; padding:0">`);
-  }
-
-  // TOC container IDs are fixed — the runtime queries them by ID (#toc, #toc-action-bar, #toc-list)
-  if (isFloat) {
-    const floatClass = data.align === "left" ? "floatleft" : "floatright";
-    ctx.push(`<div id="toc" class="${floatClass}">`);
-  } else {
-    ctx.push(`<div id="toc">`);
-  }
-
-  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>");
-  ctx.push("</div>");
-
-  if (!isFloat) {
-    ctx.push(`</td></tr></table>`);
-  }
-}

package/src/elements/user.ts

@@ -1,79 +0,0 @@
-/**
- *
- * Renderer for `[[user username]]` elements.
- *
- * User elements display a username with an optional avatar image and
- * karma badge. The user profile data is resolved via the
- * `resolvers.user` callback; when no resolver is provided or the user
- * is not found, the raw username is rendered as plain text.
- *
- * The special username `"anonymous"` is always rendered as the literal
- * text "Anonymous" without any link or avatar.
- *
- * @module
- */
-
-import type { UserData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeHtml, escapeAttr } from "../escape";
-
-/**
- * Render a `[[user username]]` element.
- *
- * Rendering modes:
- * - "anonymous" username: plain text "Anonymous"
- * - Unresolved user: plain escaped username text
- * - Resolved without avatar: `<span class="printuser"><a>name</a></span>`
- * - Resolved with avatar: `<span class="printuser avatarhover">` with
- *   avatar image, optional karma badge, and linked display name
- *
- * @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();
-
-  // Special case: "anonymous" renders as "Anonymous" text only
-  if (normalized === "anonymous") {
-    ctx.push("Anonymous");
-    return;
-  }
-
-  const resolved = ctx.options.resolvers?.user?.(data.name) ?? null;
-
-  if (resolved === null) {
-    // User not resolved - render as simple text
-    ctx.push(escapeHtml(data.name));
-    return;
-  }
-
-  const displayName = resolved.name ?? data.name;
-  const hrefAttr = resolved.url ? ` href="${escapeAttr(resolved.url)}"` : "";
-
-  // Avatar only shown when both url and avatarUrl are provided
-  const showAvatar = data["show-avatar"] && resolved.url && resolved.avatarUrl;
-
-  if (showAvatar) {
-    // With avatar
-    const styleAttr = resolved.karmaUrl
-      ? ` style="background-image:url(${escapeAttr(resolved.karmaUrl)})"`
-      : "";
-    ctx.push(`<span class="printuser avatarhover">`);
-    ctx.push(`<a${hrefAttr}>`);
-    ctx.push(
-      `<img class="small" src="${escapeAttr(resolved.avatarUrl!)}" alt="${escapeAttr(displayName)}"${styleAttr} />`,
-    );
-    ctx.push("</a>");
-    ctx.push(`<a${hrefAttr}>`);
-    ctx.push(escapeHtml(displayName));
-    ctx.push("</a>");
-    ctx.push("</span>");
-  } else {
-    // Without avatar
-    ctx.push(`<span class="printuser">`);
-    ctx.push(`<a${hrefAttr}>`);
-    ctx.push(escapeHtml(displayName));
-    ctx.push("</a>");
-    ctx.push("</span>");
-  }
-}