@wdprlib/render 2.0.0 → 3.0.0

package/src/elements/list/no-marker.ts

@@ -0,0 +1,53 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElement, renderElements } from "../../render";
+import {
+  getParagraphIndices,
+  isLiCloseTextParagraph,
+  isParagraphElement,
+  type ParagraphElement,
+} from "./paragraphs";
+import { trimTextElements } from "./trim";
+
+export function renderNoMarkerElements(ctx: RenderContext, elements: Element[]): void {
+  const trimmed = trimTextElements(elements);
+  if (trimmed.length === 0) return;
+
+  const paragraphIndices = getParagraphIndices(trimmed);
+  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 (isParagraphElement(el)) {
+      renderNoMarkerParagraph(ctx, el, i, firstParagraphIdx, lastParagraphIdx);
+    } else {
+      renderElement(ctx, el);
+    }
+  }
+}
+
+function renderNoMarkerParagraph(
+  ctx: RenderContext,
+  element: ParagraphElement,
+  index: number,
+  firstParagraphIdx: number,
+  lastParagraphIdx: number,
+): void {
+  if (
+    index === firstParagraphIdx ||
+    (index === lastParagraphIdx && isLiCloseTextParagraph(element))
+  ) {
+    renderElements(ctx, element.data.elements);
+    return;
+  }
+
+  ctx.push("<p>");
+  renderElements(ctx, element.data.elements);
+  ctx.push("</p>");
+}

package/src/elements/list/paragraphs.ts

@@ -0,0 +1,34 @@
+import type { ContainerData, Element } from "@wdprlib/ast";
+
+export type ParagraphElement = Element & {
+  element: "container";
+  data: ContainerData & { type: "paragraph" };
+};
+
+export function getParagraphIndices(elements: Element[]): number[] {
+  const indices: number[] = [];
+
+  for (let i = 0; i < elements.length; i++) {
+    if (isParagraphElement(elements[i])) {
+      indices.push(i);
+    }
+  }
+
+  return indices;
+}
+
+export function isParagraphElement(element: Element | undefined): element is ParagraphElement {
+  return element?.element === "container" && element.data.type === "paragraph";
+}
+
+export function isLiCloseTextParagraph(element: ParagraphElement): boolean {
+  let combined = "";
+
+  for (const child of element.data.elements) {
+    if (child.element === "text") {
+      combined += child.data;
+    }
+  }
+
+  return combined.trim() === "[[/li]]";
+}

package/src/elements/list/trim.ts

@@ -0,0 +1,38 @@
+import type { Element } from "@wdprlib/ast";
+
+export function trimTextElements(elements: Element[]): Element[] {
+  if (elements.length === 0) return elements;
+
+  let start = 0;
+  let end = elements.length;
+
+  while (start < end) {
+    const el = elements[start]!;
+    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
+      start++;
+    } else {
+      break;
+    }
+  }
+
+  while (end > start) {
+    const el = elements[end - 1]!;
+    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
+      end--;
+    } else {
+      break;
+    }
+  }
+
+  if (start === 0 && end === elements.length) return elements;
+  return elements.slice(start, end);
+}
+
+export function hasNonWhitespaceElement(elements: Element[]): boolean {
+  for (const el of elements) {
+    if (el.element !== "text" || typeof el.data !== "string" || el.data.trim() !== "") {
+      return true;
+    }
+  }
+  return false;
+}

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

@@ -0,0 +1,29 @@
+/**
+ *
+ * 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";
+import { renderIndentedEmptyModuleContainer } from "./empty-container";
+
+/**
+ * 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)
+  renderIndentedEmptyModuleContainer(ctx, "backlinks-module-box");
+}

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";
+import { renderEmptyModuleContainer } from "./empty-container";
+
+/**
+ * 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 {
+  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

@@ -0,0 +1,65 @@
+/**
+ *
+ * Dispatcher for `[[module ModuleName]]` elements.
+ *
+ * Wikidot modules are server-side components that generate dynamic content.
+ * This renderer dispatches to the appropriate module-specific renderer based
+ * on the module name. Supported modules include Rate, Join, Backlinks,
+ * Categories, PageTree, ListPages, and ListUsers.
+ *
+ * Unknown module names produce a Wikidot-compatible error block with a
+ * link to the modules documentation page.
+ *
+ * @module
+ */
+
+import type { Module } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderBacklinks } from "./backlinks";
+import { renderCategories } from "./categories";
+import { renderJoin } from "./join";
+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.
+ *
+ * Each module outputs a container `<div>` with a module-specific CSS class.
+ * Some modules (like Rate and Join) render interactive UI elements; others
+ * (like Backlinks and ListPages) render empty containers that can be
+ * populated at runtime.
+ *
+ * @param ctx - The current render context.
+ * @param data - Module data with discriminated module type.
+ */
+export function renderModule(ctx: RenderContext, data: Module): void {
+  switch (data.module) {
+    case "unknown":
+      renderUnknownModule(ctx, data);
+      break;
+    case "backlinks":
+      renderBacklinks(ctx, data);
+      break;
+    case "categories":
+      renderCategories(ctx, data);
+      break;
+    case "join":
+      renderJoin(ctx, data);
+      break;
+    case "page-tree":
+      renderPageTree(ctx, data);
+      break;
+    case "rate":
+      renderRate(ctx);
+      break;
+    case "list-users":
+      renderListUsers(ctx, data);
+      break;
+    case "list-pages":
+      renderListPages(ctx, data);
+      break;
+  }
+}

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

@@ -0,0 +1,28 @@
+/**
+ *
+ * Renderer for `[[module Join]]`.
+ *
+ * The Join module displays a button that allows users to request
+ * membership in the wiki site. The button text can be customized
+ * via the `button-text` attribute; it defaults to "Join".
+ *
+ * @module
+ */
+
+import type { Module } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderJoinMarkup } from "./join-markup";
+
+/**
+ * Render a `[[module Join]]` element with a clickable join button.
+ *
+ * The button is wrapped in a `<div>` with a configurable CSS class
+ * (defaults to `"join-box"`). The runtime `join` module attaches
+ * click handling via the `onJoin` callback.
+ *
+ * @param ctx - The current render context.
+ * @param data - Join module data with optional `button-text` and CSS class.
+ */
+export function renderJoin(ctx: RenderContext, data: Extract<Module, { module: "join" }>): void {
+  ctx.push(renderJoinMarkup(data));
+}

package/src/elements/module/listpages.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for `[[module ListPages]]`.
+ *
+ * The ListPages module queries and displays a filtered list of wiki pages.
+ * Because the query results require server-side data, the renderer outputs
+ * an empty container div that can be populated at runtime.
+ *
+ * @module
+ */
+
+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.
+ *
+ * @param ctx - The current render context.
+ * @param _data - ListPages module data (unused; the container is always empty).
+ */
+export function renderListPages(
+  ctx: RenderContext,
+  _data: Extract<Module, { module: "list-pages" }>,
+): void {
+  renderEmptyModuleContainer(ctx, "list-pages-box");
+}

package/src/elements/module/listusers.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for `[[module ListUsers]]`.
+ *
+ * The ListUsers module displays a filtered list of site members.
+ * The renderer outputs an empty container div that can be populated
+ * at runtime or via server-side rendering.
+ *
+ * @module
+ */
+
+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.
+ *
+ * @param ctx - The current render context.
+ * @param _data - ListUsers module data (unused; the container is always empty).
+ */
+export function renderListUsers(
+  ctx: RenderContext,
+  _data: Extract<Module, { module: "list-users" }>,
+): void {
+  renderEmptyModuleContainer(ctx, "list-users-module-box");
+}

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

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for `[[module PageTree]]`.
+ *
+ * The PageTree module displays a hierarchical tree of child pages.
+ * The renderer outputs an empty container div; the tree structure
+ * is populated at runtime or via server-side rendering.
+ *
+ * @module
+ */
+
+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.
+ *
+ * @param ctx - The current render context.
+ * @param _data - PageTree module data (unused; the container is always empty).
+ */
+export function renderPageTree(
+  ctx: RenderContext,
+  _data: Extract<Module, { module: "page-tree" }>,
+): void {
+  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

@@ -0,0 +1,35 @@
+/**
+ *
+ * Renderer for `[[module Rate]]`.
+ *
+ * The Rate module displays a page rating widget with upvote, downvote,
+ * and cancel buttons. The initial score is rendered as 0; the runtime
+ * `rate` module handles click events and updates the display via the
+ * `onRate` callback.
+ *
+ * The widget HTML structure matches Wikidot's original output, using
+ * Bootstrap-style `btn btn-default` classes alongside Wikidot-specific
+ * class names (`rateup`, `ratedown`, `cancel`, `rate-points`).
+ *
+ * @module
+ */
+
+import type { RenderContext } from "../../context";
+import { getRateWidgetParts } from "./rate-markup";
+
+/**
+ * Render a `[[module Rate]]` page rating widget.
+ *
+ * Outputs a `<div class="page-rate-widget-box">` containing:
+ * - A score display span (`.rate-points > .number`)
+ * - An upvote button (`.rateup`)
+ * - A downvote button (`.ratedown`) using an en-dash character
+ * - A cancel button (`.cancel`)
+ *
+ * @param ctx - The current render context.
+ */
+export function renderRate(ctx: RenderContext): void {
+  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>");
+}