@wdprlib/render 2.0.0 → 2.1.0

package/src/elements/link.ts

@@ -0,0 +1,201 @@
+/**
+ *
+ * Renderers for Wikidot link elements.
+ *
+ * Wikidot supports several link syntaxes:
+ * - `[[[page-name]]]` -- page link with automatic label
+ * - `[[[page-name | label]]]` -- page link with custom label
+ * - `[# label]` -- anchor-type link (JavaScript void)
+ * - `[http://url label]` -- external URL link
+ * - `[[a]]...[[/a]]` -- HTML anchor element with attributes
+ * - `[[#anchor-name]]` -- named anchor (bookmark target)
+ *
+ * All link types are checked for dangerous URL schemes. Page links
+ * may receive a `class="newpage"` attribute when the target page does
+ * not exist (the standard Wikidot "red link" convention). External
+ * links opened in new tabs automatically receive `rel="noopener noreferrer"`
+ * to prevent tabnabbing.
+ *
+ * @module
+ */
+
+import type { LinkData, AnchorData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr, isDangerousUrl, sanitizeAttributes } from "../escape";
+import { renderElements } from "../render";
+
+/**
+ * Render a link element (`[[[page]]]`, `[url label]`, `[# label]`).
+ *
+ * The link's `href` is resolved via `ctx.resolvePageLink()`, with an
+ * optional `extra` suffix (anchor fragment) appended. Anchor-type links
+ * with `javascript:;` are allowed as a special case for Wikidot
+ * compatibility; all other dangerous URL schemes are blocked.
+ *
+ * For page-type links, a `class="newpage"` is added when the
+ * `pageExists` resolver indicates the target page does not exist.
+ *
+ * @param ctx - The current render context.
+ * @param data - Link data with link target, label, type, target window, and extra suffix.
+ */
+export function renderLink(ctx: RenderContext, data: LinkData): void {
+  let href = ctx.resolvePageLink(data.link);
+
+  // Append extra (anchor suffix)
+  if (data.extra) {
+    href += data.extra;
+  }
+
+  // Validate URL scheme
+  // Exception: anchor-type links with "javascript:;" are valid Wikidot syntax ([# label])
+  const isAnchorJsVoid = data.type === "anchor" && href === "javascript:;";
+  if (!isAnchorJsVoid && isDangerousUrl(href)) {
+    href = "#invalid-url";
+  }
+
+  // Build <a> tag
+  const attrs: string[] = [`href="${escapeAttr(href)}"`];
+
+  // Add "newpage" class for page links that don't exist
+  // Only for page-type links (not direct URLs, anchors, etc.)
+  if (data.type === "page" && typeof data.link === "object") {
+    const page = data.link.page;
+    // Skip newpage class for special pages:
+    // - //path (protocol-relative or special routing)
+    // - paths with #/ (hash routing like MAIN/#/page)
+    // category-prefixed pages (`category:name`) are NOT skipped — pageExists is
+    // expected to handle them (e.g. share:<ULID>, private:<ULID>, system:Recent).
+    const isSpecialPage = page.startsWith("//") || page.includes("#/");
+    if (!isSpecialPage) {
+      // For anchor links (page#anchor), check if the page part exists
+      const hashIdx = page.indexOf("#");
+      const pageToCheck = hashIdx !== -1 ? page.slice(0, hashIdx) : page;
+      const pageExists = ctx.page?.pageExists;
+      // If pageExists is not provided, assume page doesn't exist (show newpage class)
+      const exists = pageExists ? pageExists(pageToCheck) : false;
+      if (!exists) {
+        attrs.push(`class="newpage"`);
+      }
+    }
+  }
+
+  // Target attribute
+  if (data.target) {
+    const targetMap: Record<string, string> = {
+      "new-tab": "_blank",
+      parent: "_parent",
+      top: "_top",
+      same: "_self",
+    };
+    const targetValue = targetMap[data.target] ?? "_blank";
+    attrs.push(`target="${targetValue}"`);
+    // Prevent tabnabbing for _blank targets
+    if (targetValue === "_blank") {
+      attrs.push(`rel="noopener noreferrer"`);
+    }
+  }
+
+  ctx.push(`<a ${attrs.join(" ")}>`);
+
+  // Render label
+  renderLinkLabel(ctx, data);
+
+  ctx.push("</a>");
+}
+
+/**
+ * Render the label content of a link element.
+ *
+ * Label types:
+ * - `"page"` -- use the page name as the label text
+ * - `{ text: string }` -- use a custom text label
+ * - `{ url: string }` -- use the URL itself as the label
+ *
+ * @param ctx - The current render context.
+ * @param data - Link data containing the label descriptor.
+ */
+function renderLinkLabel(ctx: RenderContext, data: LinkData): void {
+  if (data.label === "page") {
+    // Use page name as label
+    if (typeof data.link === "string") {
+      ctx.pushEscaped(data.link);
+    } else {
+      ctx.pushEscaped(data.link.page);
+    }
+    return;
+  }
+
+  if ("text" in data.label) {
+    ctx.pushEscaped(data.label.text);
+    return;
+  }
+
+  if ("url" in data.label) {
+    // Use the URL itself as label
+    const href = ctx.resolvePageLink(data.link);
+    ctx.pushEscaped(data.label.url ?? href);
+  }
+}
+
+/**
+ * Render a `[[a]]...[[/a]]` anchor element with full attribute support.
+ *
+ * Unlike `renderLink`, this handles the block-level anchor syntax where
+ * arbitrary attributes can be specified. Dangerous `href` values are
+ * replaced with `#invalid-url`. The `target` attribute is mapped from
+ * Wikidot's abstract values to HTML values, with tabnabbing protection.
+ *
+ * @param ctx - The current render context.
+ * @param data - Anchor data with attributes, target, and child elements.
+ */
+export function renderAnchor(ctx: RenderContext, data: AnchorData): void {
+  const safe = sanitizeAttributes(data.attributes);
+  const attrs: string[] = [];
+
+  // Validate href for dangerous URLs
+  if (safe.href && isDangerousUrl(safe.href)) {
+    safe.href = "#invalid-url";
+  }
+
+  // Always include href attribute
+  const href = safe.href ?? "";
+  attrs.push(`href="${escapeAttr(href)}"`);
+
+  // Handle target attribute from AST data
+  if (data.target) {
+    const targetMap: Record<string, string> = {
+      "new-tab": "_blank",
+      parent: "_parent",
+      top: "_top",
+      same: "_self",
+    };
+    const targetValue = targetMap[data.target] ?? "_blank";
+    attrs.push(`target="${targetValue}"`);
+    // Prevent tabnabbing for _blank targets
+    if (targetValue === "_blank") {
+      attrs.push(`rel="noopener noreferrer"`);
+    }
+  }
+
+  for (const [key, value] of Object.entries(safe)) {
+    if (key === "href" || key === "target") continue; // already handled above
+    attrs.push(`${key}="${escapeAttr(value)}"`);
+  }
+
+  ctx.push(`<a ${attrs.join(" ")}>`);
+  renderElements(ctx, data.elements);
+  ctx.push("</a>");
+}
+
+/**
+ * Render a named anchor (bookmark target) element: `[[#anchor-name]]`.
+ *
+ * Produces `<a name="anchor-name"></a>` which serves as a link target
+ * for `#anchor-name` URL fragments.
+ *
+ * @param ctx - The current render context.
+ * @param name - The anchor name (fragment identifier).
+ */
+export function renderAnchorName(ctx: RenderContext, name: string): void {
+  ctx.push(`<a name="${escapeAttr(name)}"></a>`);
+}

package/src/elements/list.ts

@@ -0,0 +1,241 @@
+/**
+ *
+ * Renderers for Wikidot ordered/unordered lists and definition lists.
+ *
+ * Wikidot list syntax uses `*` (unordered) and `#` (ordered) prefixes
+ * with indentation controlling nesting depth. The parser produces a
+ * recursive `ListData` structure with items that can be either
+ * "elements" (content) or "sub-list" (nested list).
+ *
+ * Special behaviors replicated from Wikidot:
+ * - Empty lists are silently dropped (no output at all).
+ * - Items with `_noMarker` have `list-style: none` and the first
+ *   paragraph is unwrapped (no `<p>` tags).
+ * - Sub-lists without a preceding content item get an inline hidden `<li>`.
+ * - Leading/trailing whitespace-only text nodes are trimmed from items.
+ *
+ * @module
+ */
+
+import type { ListData, DefinitionListItem, Element, ContainerData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr, sanitizeAttributes } from "../escape";
+import { renderElements, renderElement } from "../render";
+
+/**
+ * Trim leading and trailing whitespace-only text elements from an array.
+ *
+ * @param elements - Array of AST elements.
+ * @returns A slice of the array with whitespace-only text nodes removed
+ *   from both ends.
+ */
+function trimTextElements(elements: Element[]): Element[] {
+  if (elements.length === 0) return elements;
+
+  let start = 0;
+  let end = elements.length;
+
+  // Trim leading whitespace-only text elements
+  while (start < end) {
+    const el = elements[start]!;
+    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
+      start++;
+    } else {
+      break;
+    }
+  }
+
+  // Trim trailing whitespace-only text elements
+  while (end > start) {
+    const el = elements[end - 1]!;
+    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
+      end--;
+    } else {
+      break;
+    }
+  }
+
+  return elements.slice(start, end);
+}
+
+/**
+ * Check whether a paragraph element contains only the text `[[/li]]`.
+ *
+ * The parser sometimes wraps stray `[[/li]]` closing tags in a paragraph.
+ * When found as the last paragraph in a `_noMarker` item, the paragraph
+ * wrapper is removed to match Wikidot output.
+ *
+ * @param el - An AST element to check.
+ * @returns `true` if the element is a paragraph containing only `[[/li]]`.
+ */
+function isLiCloseTextParagraph(el: Element): boolean {
+  if (el.element !== "container") return false;
+  const data = el.data as ContainerData;
+  if (data.type !== "paragraph") return false;
+  // Check if content is just [[/li]] (possibly with whitespace)
+  const texts = data.elements
+    .filter((e): e is { element: "text"; data: string } => e.element === "text")
+    .map((e) => e.data);
+  const combined = texts.join("").trim();
+  return combined === "[[/li]]";
+}
+
+/**
+ * Render elements for `_noMarker` list items with special paragraph handling.
+ *
+ * Wikidot treats bare content (without `[[li]]`) differently:
+ * - The first paragraph is unwrapped (children rendered without `<p>` tags).
+ * - Middle paragraphs retain their `<p>` wrappers.
+ * - The last paragraph is unwrapped if it contains only `[[/li]]` text.
+ *
+ * @param ctx - The current render context.
+ * @param elements - The list item's child elements.
+ */
+function renderNoMarkerElements(ctx: RenderContext, elements: Element[]): void {
+  const trimmed = trimTextElements(elements);
+  if (trimmed.length === 0) return;
+
+  // Find paragraph indices
+  const paragraphIndices: number[] = [];
+  for (let i = 0; i < trimmed.length; i++) {
+    const el = trimmed[i]!;
+    if (el.element === "container" && (el.data as ContainerData).type === "paragraph") {
+      paragraphIndices.push(i);
+    }
+  }
+
+  // If no paragraphs, render normally
+  if (paragraphIndices.length === 0) {
+    renderElements(ctx, trimmed);
+    return;
+  }
+
+  const firstParagraphIdx = paragraphIndices[0]!;
+  const lastParagraphIdx = paragraphIndices[paragraphIndices.length - 1]!;
+
+  for (let i = 0; i < trimmed.length; i++) {
+    const el = trimmed[i]!;
+    if (el.element === "container" && (el.data as ContainerData).type === "paragraph") {
+      const data = el.data as ContainerData;
+      // First paragraph: unwrap
+      if (i === firstParagraphIdx) {
+        renderElements(ctx, data.elements);
+      }
+      // Last paragraph if it's [[/li]]: unwrap
+      else if (i === lastParagraphIdx && isLiCloseTextParagraph(el)) {
+        renderElements(ctx, data.elements);
+      }
+      // Other paragraphs: keep <p> tags
+      else {
+        ctx.push("<p>");
+        renderElements(ctx, data.elements);
+        ctx.push("</p>");
+      }
+    } else {
+      renderElement(ctx, el);
+    }
+  }
+}
+
+/**
+ * Render an ordered or unordered list.
+ *
+ * Wikidot drops empty lists entirely (no HTML output). Sub-lists
+ * following a content item are rendered inside the same `<li>`.
+ * Sub-lists without a preceding content item get a hidden `<li>` wrapper.
+ *
+ * @param ctx - The current render context.
+ * @param data - List data with type (numbered/bulleted), items, and attributes.
+ */
+export function renderList(ctx: RenderContext, data: ListData): void {
+  // Wikidot behavior: empty lists or lists with only empty items are ignored
+  // and converted to <br />
+  const hasContent = data.items.some((item) => {
+    if (item["item-type"] === "sub-list") return true;
+    if (item["item-type"] === "elements") {
+      const trimmed = trimTextElements(item.elements);
+      return trimmed.length > 0;
+    }
+    return false;
+  });
+
+  if (!hasContent) {
+    // Empty list - Wikidot outputs nothing (just whitespace)
+    return;
+  }
+
+  const tag = data.type === "numbered" ? "ol" : "ul";
+  ctx.push(`<${tag}${renderListAttrs(data.attributes)}>`);
+
+  const items = data.items;
+  let i = 0;
+  while (i < items.length) {
+    const item = items[i]!;
+    if (item["item-type"] === "elements") {
+      // Check for _noMarker flag (bare content without [[li]])
+      const hasNoMarker = item.attributes._noMarker === "true";
+      const styleAttr = hasNoMarker ? ' style="list-style: none"' : "";
+      ctx.push(`<li${renderListAttrs(item.attributes)}${styleAttr}>`);
+      // Trim leading/trailing whitespace from li content (Wikidot behavior)
+      if (hasNoMarker) {
+        // Special handling for bare content paragraphs
+        renderNoMarkerElements(ctx, item.elements);
+      } else {
+        renderElements(ctx, trimTextElements(item.elements));
+      }
+      // Consume following sub-lists inside this <li>
+      while (i + 1 < items.length && items[i + 1]!["item-type"] === "sub-list") {
+        i++;
+        const subItem = items[i] as { "item-type": "sub-list"; data: ListData };
+        renderList(ctx, subItem.data);
+      }
+      ctx.push("</li>");
+    } else {
+      // Sub-list without preceding elements item - hide bullet/number
+      const subItem = item as { "item-type": "sub-list"; data: ListData };
+      ctx.push(`<li style="list-style: none; display: inline">`);
+      renderList(ctx, subItem.data);
+      ctx.push("</li>");
+    }
+    i++;
+  }
+
+  ctx.push(`</${tag}>`);
+}
+
+/**
+ * Sanitize and render list-specific 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 renderListAttrs(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;
+}
+
+/**
+ * Render a definition list (`:`-prefixed items in Wikidot markup).
+ *
+ * Produces `<dl>` with `<dt>`/`<dd>` pairs for each definition item.
+ *
+ * @param ctx - The current render context.
+ * @param items - Array of definition list items, each with key and value elements.
+ */
+export function renderDefinitionList(ctx: RenderContext, items: DefinitionListItem[]): void {
+  ctx.push("<dl>");
+  for (const item of items) {
+    ctx.push("<dt>");
+    renderElements(ctx, item.key);
+    ctx.push("</dt>");
+    ctx.push("<dd>");
+    renderElements(ctx, item.value);
+    ctx.push("</dd>");
+  }
+  ctx.push("</dl>");
+}

package/src/elements/math.ts

@@ -0,0 +1,177 @@
+/**
+ *
+ * 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/module/backlinks.ts

@@ -0,0 +1,28 @@
+/**
+ *
+ * Renderer for `[[module Backlinks]]`.
+ *
+ * The backlinks module lists all pages that link to the current page.
+ * Because backlink data requires server-side queries, the renderer only
+ * outputs an empty container div. The actual content is populated at
+ * runtime or via server-side rendering.
+ *
+ * @module
+ */
+
+import type { Module } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+/**
+ * Render a `[[module Backlinks]]` element as an empty container.
+ *
+ * @param ctx - The current render context.
+ * @param _data - Backlinks module data (unused; the container is always empty).
+ */
+export function renderBacklinks(
+  ctx: RenderContext,
+  _data: Extract<Module, { module: "backlinks" }>,
+): void {
+  // Wikidot outputs just the container div (backlinks are populated at runtime)
+  ctx.push(`<div class="backlinks-module-box">\n\t</div>`);
+}

package/src/elements/module/categories.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for `[[module Categories]]`.
+ *
+ * The categories module displays the site's page categories. The
+ * renderer outputs an empty container div; category data is populated
+ * at runtime or via server-side rendering.
+ *
+ * @module
+ */
+
+import type { Module } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+/**
+ * Render a `[[module Categories]]` element as an empty container.
+ *
+ * @param ctx - The current render context.
+ * @param _data - Categories module data (unused; the container is always empty).
+ */
+export function renderCategories(
+  ctx: RenderContext,
+  _data: Extract<Module, { module: "categories" }>,
+): void {
+  ctx.push(`<div class="categories-module-box">`);
+  ctx.push("</div>");
+}