@wdprlib/render 2.1.0 → 3.0.1

package/src/elements/math/block.ts

@@ -0,0 +1,29 @@
+import type { MathData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml } from "../../escape";
+import { renderLatexToMathML } from "./latex";
+import { pushHiddenLatexSource, pushMathRender } from "./source";
+
+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}>`);
+  if (data.name) {
+    ctx.push(`<span class="equation-number">(${index})</span>`);
+  }
+
+  pushHiddenLatexSource(ctx, latex);
+  pushMathRender(ctx, mathml, () => {
+    ctx.push(`<span class="math-error">`);
+    ctx.push(escapeHtml(latex));
+    ctx.push(`</span>`);
+  });
+  ctx.push("</div>");
+}

package/src/elements/math/equation-ref.ts

@@ -0,0 +1,12 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml } from "../../escape";
+
+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/math/index.ts

@@ -0,0 +1,14 @@
+/**
+ *
+ * Renderers for Wikidot mathematical notation elements.
+ *
+ * - `[[math]]...[[/math]]` -- display-mode (block) math
+ * - `[[$ ... $]]` -- inline math
+ * - `[[eref name]]` -- equation reference
+ *
+ * @module
+ */
+
+export { renderMath } from "./block";
+export { renderMathInline } from "./inline";
+export { renderEquationRef } from "./equation-ref";

package/src/elements/math/inline.ts

@@ -0,0 +1,19 @@
+import type { MathInlineData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+import { renderLatexToMathML } from "./latex";
+import { pushHiddenLatexSource, pushMathRender } from "./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">`);
+  pushHiddenLatexSource(ctx, latex);
+  pushMathRender(ctx, mathml, () => {
+    ctx.push(`<span class="math-error">$`);
+    ctx.push(escapeHtml(latex));
+    ctx.push(`$</span>`);
+  });
+  ctx.push("</span>");
+}

package/src/elements/math/latex.ts

@@ -0,0 +1,27 @@
+import temml from "temml";
+
+export function renderLatexToMathML(latex: string, displayMode: boolean): string {
+  try {
+    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 "";
+  }
+}
+
+function needsAlignedWrapper(latex: string): boolean {
+  if (/\\begin\s*\{/.test(latex)) {
+    return false;
+  }
+
+  const withoutEscaped = latex.replace(/\\&/g, "");
+  return withoutEscaped.includes("&");
+}

package/src/elements/math/source.ts

@@ -0,0 +1,18 @@
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+
+export function pushHiddenLatexSource(ctx: RenderContext, latex: string): void {
+  ctx.push(`<code class="math-source" hidden aria-hidden="true">`);
+  ctx.push(escapeHtml(latex));
+  ctx.push(`</code>`);
+}
+
+export function pushMathRender(ctx: RenderContext, mathml: string, fallback: () => void): void {
+  ctx.push(`<span class="math-render">`);
+  if (mathml) {
+    ctx.push(mathml);
+  } else {
+    fallback();
+  }
+  ctx.push(`</span>`);
+}

package/src/elements/module/backlinks.ts

@@ -12,6 +12,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
+import { renderIndentedEmptyModuleContainer } from "./empty-container";
 
 /**
  * Render a `[[module Backlinks]]` element as an empty container.
@@ -24,5 +25,5 @@ export function renderBacklinks(
   _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>`);
+  renderIndentedEmptyModuleContainer(ctx, "backlinks-module-box");
 }

package/src/elements/module/categories.ts

@@ -11,6 +11,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
+import { renderEmptyModuleContainer } from "./empty-container";
 
 /**
  * Render a `[[module Categories]]` element as an empty container.
@@ -22,6 +23,5 @@ export function renderCategories(
   ctx: RenderContext,
   _data: Extract<Module, { module: "categories" }>,
 ): void {
-  ctx.push(`<div class="categories-module-box">`);
-  ctx.push("</div>");
+  renderEmptyModuleContainer(ctx, "categories-module-box");
 }

package/src/elements/module/empty-container.ts

@@ -0,0 +1,10 @@
+import type { RenderContext } from "../../context";
+
+export function renderEmptyModuleContainer(ctx: RenderContext, className: string): void {
+  ctx.push(`<div class="${className}">`);
+  ctx.push("</div>");
+}
+
+export function renderIndentedEmptyModuleContainer(ctx: RenderContext, className: string): void {
+  ctx.push(`<div class="${className}">\n\t</div>`);
+}

package/src/elements/module/index.ts

@@ -22,6 +22,7 @@ import { renderPageTree } from "./page-tree";
 import { renderRate } from "./rate";
 import { renderListUsers } from "./listusers";
 import { renderListPages } from "./listpages";
+import { renderUnknownModule } from "./unknown";
 
 /**
  * Render a `[[module]]` element by dispatching on the module name.
@@ -37,10 +38,7 @@ import { renderListPages } from "./listpages";
 export function renderModule(ctx: RenderContext, data: Module): void {
   switch (data.module) {
     case "unknown":
-      // Render error block for unknown modules
-      ctx.push(
-        `<div class="error-block">[[module <em>${data.name}</em>]] No such module, please <a href="https://www.wikidot.com/doc:modules" target="_blank" rel="noopener noreferrer">check available modules</a> and fix this page.</div>`,
-      );
+      renderUnknownModule(ctx, data);
       break;
     case "backlinks":
       renderBacklinks(ctx, data);

package/src/elements/module/join-markup.ts

@@ -0,0 +1,10 @@
+import type { Module } from "@wdprlib/ast";
+import { escapeAttr, escapeHtml } from "../../escape";
+
+type JoinModule = Extract<Module, { module: "join" }>;
+
+export function renderJoinMarkup(data: JoinModule): string {
+  const buttonText = data["button-text"] ?? "Join";
+  const className = data.attributes?.class ?? "join-box";
+  return `<div class="${escapeAttr(className)}"><a href="javascript:;">${escapeHtml(buttonText)}</a></div>`;
+}

package/src/elements/module/join.ts

@@ -11,7 +11,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
-import { escapeAttr, escapeHtml } from "../../escape";
+import { renderJoinMarkup } from "./join-markup";
 
 /**
  * Render a `[[module Join]]` element with a clickable join button.
@@ -24,10 +24,5 @@ import { escapeAttr, escapeHtml } from "../../escape";
  * @param data - Join module data with optional `button-text` and CSS class.
  */
 export function renderJoin(ctx: RenderContext, data: Extract<Module, { module: "join" }>): void {
-  const buttonText = data["button-text"] ?? "Join";
-  const attrs = data.attributes ?? {};
-  const className = attrs.class ?? "join-box";
-  ctx.push(`<div class="${escapeAttr(className)}">`);
-  ctx.push(`<a href="javascript:;">${escapeHtml(buttonText)}</a>`);
-  ctx.push("</div>");
+  ctx.push(renderJoinMarkup(data));
 }

package/src/elements/module/listpages.ts

@@ -11,6 +11,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
+import { renderEmptyModuleContainer } from "./empty-container";
 
 /**
  * Render a `[[module ListPages]]` element as an empty container.
@@ -22,6 +23,5 @@ export function renderListPages(
   ctx: RenderContext,
   _data: Extract<Module, { module: "list-pages" }>,
 ): void {
-  ctx.push(`<div class="list-pages-box">`);
-  ctx.push("</div>");
+  renderEmptyModuleContainer(ctx, "list-pages-box");
 }

package/src/elements/module/listusers.ts

@@ -11,6 +11,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
+import { renderEmptyModuleContainer } from "./empty-container";
 
 /**
  * Render a `[[module ListUsers]]` element as an empty container.
@@ -22,6 +23,5 @@ export function renderListUsers(
   ctx: RenderContext,
   _data: Extract<Module, { module: "list-users" }>,
 ): void {
-  ctx.push(`<div class="list-users-module-box">`);
-  ctx.push("</div>");
+  renderEmptyModuleContainer(ctx, "list-users-module-box");
 }

package/src/elements/module/page-tree.ts

@@ -11,6 +11,7 @@
 
 import type { Module } from "@wdprlib/ast";
 import type { RenderContext } from "../../context";
+import { renderEmptyModuleContainer } from "./empty-container";
 
 /**
  * Render a `[[module PageTree]]` element as an empty container.
@@ -22,6 +23,5 @@ export function renderPageTree(
   ctx: RenderContext,
   _data: Extract<Module, { module: "page-tree" }>,
 ): void {
-  ctx.push(`<div class="page-tree-module-box">`);
-  ctx.push("</div>");
+  renderEmptyModuleContainer(ctx, "page-tree-module-box");
 }

package/src/elements/module/rate-markup.ts

@@ -0,0 +1,10 @@
+export function getRateWidgetParts(): string[] {
+  return [
+    `<div class="page-rate-widget-box">`,
+    `<span class="rate-points">rating:&nbsp;<span class="number prw54353">0</span></span>`,
+    `<span class="rateup btn btn-default"><a title="I like it" href="javascript:;">+</a></span>`,
+    `<span class="ratedown btn btn-default"><a title="I don't like it" href="javascript:;">&#8211;</a></span>`,
+    `<span class="cancel btn btn-default"><a title="Cancel my vote" href="javascript:;">x</a></span>`,
+    "</div>",
+  ];
+}

package/src/elements/module/rate.ts

@@ -15,6 +15,7 @@
  */
 
 import type { RenderContext } from "../../context";
+import { getRateWidgetParts } from "./rate-markup";
 
 /**
  * Render a `[[module Rate]]` page rating widget.
@@ -28,17 +29,7 @@ import type { RenderContext } from "../../context";
  * @param ctx - The current render context.
  */
 export function renderRate(ctx: RenderContext): void {
-  ctx.push(`<div class="page-rate-widget-box">`);
-  ctx.push(`<span class="rate-points">rating:&nbsp;<span class="number prw54353">0</span></span>`);
-  ctx.push(
-    `<span class="rateup btn btn-default"><a title="I like it" href="javascript:;">+</a></span>`,
-  );
-  // &#8211; is en-dash
-  ctx.push(
-    `<span class="ratedown btn btn-default"><a title="I don't like it" href="javascript:;">&#8211;</a></span>`,
-  );
-  ctx.push(
-    `<span class="cancel btn btn-default"><a title="Cancel my vote" href="javascript:;">x</a></span>`,
-  );
-  ctx.push("</div>");
+  for (const part of getRateWidgetParts()) {
+    ctx.push(part);
+  }
 }

package/src/elements/module/unknown.ts

@@ -0,0 +1,11 @@
+import type { Module } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+export function renderUnknownModule(
+  ctx: RenderContext,
+  data: Extract<Module, { module: "unknown" }>,
+): void {
+  ctx.push(
+    `<div class="error-block">[[module <em>${data.name}</em>]] No such module, please <a href="https://www.wikidot.com/doc:modules" target="_blank" rel="noopener noreferrer">check available modules</a> and fix this page.</div>`,
+  );
+}

package/src/elements/tab-view/ids.ts

@@ -0,0 +1,16 @@
+import type { TabData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { syncHashMd5 } from "../../hash";
+
+export function getTabViewWidgetId(
+  ctx: RenderContext,
+  tabs: TabData[],
+  tabViewIndex: number,
+): string {
+  const labelString = tabs.map((tab) => tab.label).join("");
+  return ctx.generateFixedId(`wiki-tabview-${tabViewIndex}-${syncHashMd5(labelString)}`);
+}
+
+export function getTabPanelId(ctx: RenderContext, tabViewIndex: number, tabIndex: number): string {
+  return ctx.generateId(`wiki-tab-${tabViewIndex}-`, tabIndex);
+}

package/src/elements/tab-view/index.ts

@@ -0,0 +1,31 @@
+/**
+ *
+ * Renderer for `[[tabview]]...[[/tabview]]` tab containers.
+ *
+ * @module
+ */
+
+import type { TabData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderTabPanels } from "./panels";
+import { renderTabNavigation } from "./navigation";
+import { getTabViewWidgetId } from "./ids";
+
+/**
+ * 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 {
+  const tabViewIndex = ctx.nextTabViewIndex();
+  const widgetId = getTabViewWidgetId(ctx, tabs, tabViewIndex);
+
+  ctx.push(`<div id="${widgetId}" class="yui-navset">`);
+  renderTabNavigation(ctx, tabs);
+  renderTabPanels(ctx, tabs, tabViewIndex);
+  ctx.push("</div>");
+}

package/src/elements/tab-view/navigation.ts

@@ -0,0 +1,15 @@
+import type { TabData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeHtml } from "../../escape";
+
+export function renderTabNavigation(ctx: RenderContext, tabs: TabData[]): void {
+  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>");
+}

package/src/elements/tab-view/panels.ts

@@ -0,0 +1,16 @@
+import type { TabData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { getTabPanelId } from "./ids";
+
+export function renderTabPanels(ctx: RenderContext, tabs: TabData[], tabViewIndex: number): void {
+  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"`;
+    ctx.push(`<div id="${getTabPanelId(ctx, tabViewIndex, i)}"${displayStyle}>`);
+    renderElements(ctx, tab.elements);
+    ctx.push("</div>");
+  }
+  ctx.push("</div>");
+}

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