@wdprlib/render 2.0.0 → 3.0.0

package/src/elements/bibliography/cite.ts

@@ -0,0 +1,23 @@
+import type { BibliographyCiteData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml } from "../../escape";
+import { generateBibliographyIdSuffix } from "./ids";
+
+export function renderBibliographyCite(ctx: RenderContext, data: BibliographyCiteData): void {
+  const number = ctx.getBibliographyCitationNumber(data.label);
+  const counter = ctx.nextBibciteCounter();
+
+  if (number === undefined) {
+    ctx.push(escapeHtml(data.label));
+    return;
+  }
+
+  const idSuffix = generateBibliographyIdSuffix(data.label, counter);
+  const id = ctx.generateId(`bibcite-${number}-`, idSuffix);
+  const bibitemId = ctx.generateId("bibitem-", number);
+  const onclick = `WIKIDOT.page.utils.scrollToReference('${bibitemId}')`;
+
+  ctx.push(`<a href="javascript:;" class="bibcite" id="${id}" onclick="${escapeAttr(onclick)}">`);
+  ctx.push(String(number));
+  ctx.push("</a>");
+}

package/src/elements/bibliography/ids.ts

@@ -0,0 +1,9 @@
+export function generateBibliographyIdSuffix(label: string, counter: number): string {
+  let h = 0x811c9dc5;
+  const input = label + counter;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).slice(0, 6);
+}

package/src/elements/bibliography/index.ts

@@ -0,0 +1,9 @@
+/**
+ *
+ * Renderers for Wikidot bibliography markup.
+ *
+ * @module
+ */
+
+export { renderBibliographyCite } from "./cite";
+export { renderBibliographyBlock } from "./block";

package/src/elements/clear-float.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * Renderer for the Wikidot `~~~~~` (clear-float) markup.
+ *
+ * Wikidot uses `~~~~~` (five tildes) to insert a CSS float-clearing
+ * `<div>`. The direction (`left`, `right`, or `both`) is determined
+ * by the number and placement of tildes in the source markup.
+ *
+ * @module
+ */
+
+import type { ClearFloat } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+
+/**
+ * Render a clear-float element as an invisible `<div>` with the
+ * appropriate CSS `clear` property.
+ *
+ * The output matches Wikidot's rendering: a zero-height div with
+ * `font-size: 1px` to prevent layout collapse in some browsers.
+ *
+ * @param ctx - The current render context.
+ * @param direction - CSS clear direction (`"left"`, `"right"`, or `"both"`).
+ */
+export function renderClearFloat(ctx: RenderContext, direction: ClearFloat): void {
+  ctx.push(`<div style="clear:${direction}; height: 0px; font-size: 1px"></div>`);
+}

package/src/elements/code/contents.ts

@@ -0,0 +1,18 @@
+import type { CodeBlockData } from "@wdprlib/ast";
+import { escapeHtml } from "../../escape";
+import { highlight } from "../../libs/highlighter";
+
+export function renderCodeContents(data: CodeBlockData): string {
+  if (data.language) {
+    const highlighted = highlight(data.contents, data.language);
+    if (highlighted) {
+      return highlighted;
+    }
+  }
+
+  return renderPlainCode(data.contents);
+}
+
+function renderPlainCode(contents: string): string {
+  return `<pre><code>${escapeHtml(contents)}</code></pre>`;
+}

package/src/elements/code/index.ts

@@ -0,0 +1,29 @@
+/**
+ *
+ * Renderer for `[[code]]...[[/code]]` blocks in Wikidot markup.
+ *
+ * @module
+ */
+
+import type { CodeBlockData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderCodeContents } from "./contents";
+
+/**
+ * Render a `[[code]]` block.
+ *
+ * The block is wrapped in `<div class="code">`. If the block is empty,
+ * the div is closed immediately with no inner content.
+ *
+ * @param ctx - The current render context.
+ * @param data - Code block data containing contents and optional language.
+ */
+export function renderCode(ctx: RenderContext, data: CodeBlockData): void {
+  ctx.push(`<div class="code">`);
+
+  if (data.contents !== "") {
+    ctx.push(renderCodeContents(data));
+  }
+
+  ctx.push("</div>");
+}

package/src/elements/collapsible/index.ts

@@ -0,0 +1,31 @@
+/**
+ *
+ * Renderer for `[[collapsible]]...[[/collapsible]]` blocks.
+ *
+ * @module
+ */
+
+import type { CollapsibleData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { getCollapsibleLabels } from "./labels";
+import { renderFoldedSection, renderUnfoldedSection } from "./sections";
+
+/**
+ * Render a `[[collapsible]]` block with Wikidot-compatible HTML structure.
+ *
+ * The output contains both folded and unfolded states. Spaces in
+ * show/hide labels are encoded as ` ` to match Wikidot's behavior.
+ *
+ * @param ctx - The current render context.
+ * @param data - Collapsible block data with show/hide text, start-open
+ *   flag, and top/bottom link placement options.
+ */
+export function renderCollapsible(ctx: RenderContext, data: CollapsibleData): void {
+  const startOpen = data["start-open"];
+  const labels = getCollapsibleLabels(data);
+
+  ctx.push(`<div class="collapsible-block">`);
+  renderFoldedSection(ctx, startOpen, labels);
+  renderUnfoldedSection(ctx, data, labels);
+  ctx.push("</div>");
+}

package/src/elements/collapsible/labels.ts

@@ -0,0 +1,35 @@
+import type { CollapsibleData } from "@wdprlib/ast";
+import { escapeHtml } from "../../escape";
+
+export interface CollapsibleLabels {
+  show: string;
+  hide: string;
+}
+
+export function getCollapsibleLabels(data: CollapsibleData): CollapsibleLabels {
+  return {
+    show: data["show-text"]
+      ? formatLabelText(data["show-text"])
+      : formatCollapsibleText("+", "show block"),
+    hide: data["hide-text"]
+      ? formatLabelText(data["hide-text"])
+      : formatCollapsibleText("\u2013", "hide block"),
+  };
+}
+
+/**
+ * Format a default collapsible link label by prepending a prefix symbol
+ * (e.g. "+" or en-dash) with ` ` encoding for spaces.
+ */
+function formatCollapsibleText(prefix: string, text: string): string {
+  const encoded = escapeHtml(text).replace(/ /g, " ");
+  return `${prefix} ${encoded}`;
+}
+
+/**
+ * Format a custom collapsible link label by escaping HTML and
+ * replacing spaces with ` ` (matching Wikidot behavior).
+ */
+function formatLabelText(text: string): string {
+  return escapeHtml(text).replace(/ /g, " ");
+}

package/src/elements/collapsible/link.ts

@@ -0,0 +1,11 @@
+import type { RenderContext } from "../../context";
+
+export function renderCollapsibleLink(ctx: RenderContext, label: string): void {
+  ctx.push(`<a class="collapsible-block-link" href="javascript:;">${label}</a>`);
+}
+
+export function renderHideLink(ctx: RenderContext, label: string): void {
+  ctx.push(`<div class="collapsible-block-unfolded-link">`);
+  renderCollapsibleLink(ctx, label);
+  ctx.push("</div>");
+}

package/src/elements/collapsible/sections.ts

@@ -0,0 +1,39 @@
+import type { CollapsibleData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import type { CollapsibleLabels } from "./labels";
+import { renderCollapsibleLink, renderHideLink } from "./link";
+
+export function renderFoldedSection(
+  ctx: RenderContext,
+  startOpen: boolean,
+  labels: CollapsibleLabels,
+): void {
+  const foldedStyle = startOpen ? ` style="display:none"` : "";
+  ctx.push(`<div class="collapsible-block-folded"${foldedStyle}>`);
+  renderCollapsibleLink(ctx, labels.show);
+  ctx.push("</div>");
+}
+
+export function renderUnfoldedSection(
+  ctx: RenderContext,
+  data: CollapsibleData,
+  labels: CollapsibleLabels,
+): void {
+  const unfoldedStyle = data["start-open"] ? "" : ` style="display:none"`;
+  ctx.push(`<div class="collapsible-block-unfolded"${unfoldedStyle}>`);
+
+  if (data["show-top"] || (!data["show-top"] && !data["show-bottom"])) {
+    renderHideLink(ctx, labels.hide);
+  }
+
+  ctx.push(`<div class="collapsible-block-content">`);
+  renderElements(ctx, data.elements);
+  ctx.push("</div>");
+
+  if (data["show-bottom"]) {
+    renderHideLink(ctx, labels.hide);
+  }
+
+  ctx.push("</div>");
+}

package/src/elements/color.ts

@@ -0,0 +1,32 @@
+/**
+ *
+ * Renderer for `##color|text##` inline color markup in Wikidot syntax.
+ *
+ * The color value is sanitized to prevent CSS injection before being
+ * injected into an inline `style` attribute.
+ *
+ * @module
+ */
+
+import type { ColorData } from "@wdprlib/ast";
+import type { RenderContext } from "../context";
+import { escapeAttr, sanitizeCssColor } from "../escape";
+import { renderElements } from "../render";
+
+/**
+ * Render an inline color element (`##color|text##`).
+ *
+ * Wraps the child elements in a `<span>` with an inline `color` style.
+ * The user-supplied color value is validated and sanitized; invalid
+ * values fall back to `"inherit"`.
+ *
+ * @param ctx - The current render context.
+ * @param data - Color element data with the color value and child elements.
+ */
+export function renderColor(ctx: RenderContext, data: ColorData): void {
+  // Sanitize color value to prevent CSS injection
+  const safeColor = sanitizeCssColor(data.color, "inherit");
+  ctx.push(`<span style="color: ${escapeAttr(safeColor)}">`);
+  renderElements(ctx, data.elements);
+  ctx.push("</span>");
+}

package/src/elements/container/attributes.ts

@@ -0,0 +1,28 @@
+import { escapeAttr, sanitizeAttributes } from "../../escape";
+
+/**
+ * Sanitize and format an attribute map into an HTML attribute string.
+ */
+export function renderContainerAttrs(attributes: Record<string, string>): string {
+  if (!hasAttributes(attributes)) {
+    return "";
+  }
+
+  const safe = sanitizeAttributes(attributes);
+  let result = "";
+  for (const key in safe) {
+    if (key.startsWith("_")) {
+      continue;
+    }
+    const value = safe[key]!;
+    result += value !== "" ? ` ${key}="${escapeAttr(value)}"` : ` ${key}=""`;
+  }
+  return result;
+}
+
+export function hasAttributes(attributes: Record<string, string>): boolean {
+  for (const _ in attributes) {
+    return true;
+  }
+  return false;
+}

package/src/elements/container/header.ts

@@ -0,0 +1,27 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderContainerAttrs } from "./attributes";
+
+/**
+ * Render a heading element (`h1`..`h6`).
+ */
+export function renderHeader(
+  ctx: RenderContext,
+  level: number,
+  hasToc: boolean,
+  attributes: Record<string, string>,
+  elements: Element[],
+): void {
+  const tag = `h${level}`;
+  if (hasToc) {
+    const tocId = ctx.generateId("toc", ctx.nextTocIndex());
+    ctx.push(`<${tag} id="${tocId}"${renderContainerAttrs(attributes)}>`);
+  } else {
+    ctx.push(`<${tag}${renderContainerAttrs(attributes)}>`);
+  }
+  ctx.push("<span>");
+  renderElements(ctx, elements);
+  ctx.push("</span>");
+  ctx.push(`</${tag}>`);
+}

package/src/elements/container/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Renderer for general container AST elements.
+ *
+ * @module
+ */
+
+import type { ContainerData } from "@wdprlib/ast";
+import { isAlignType, isHeaderType, isStringContainerType } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderHeader } from "./header";
+import { renderStringContainer } from "./string-container";
+
+/**
+ * Render a container element by dispatching on its `type` discriminant.
+ */
+export function renderContainer(ctx: RenderContext, data: ContainerData): void {
+  const { type, attributes, elements } = data;
+
+  if (isHeaderType(type)) {
+    renderHeader(ctx, type.header.level, type.header["has-toc"], attributes, elements);
+    return;
+  }
+
+  if (isAlignType(type)) {
+    ctx.push(`<div style="text-align: ${type.align};">`);
+    renderElements(ctx, elements);
+    ctx.push("</div>");
+    return;
+  }
+
+  if (isStringContainerType(type)) {
+    renderStringContainer(ctx, type, attributes, elements);
+  }
+}

package/src/elements/container/string-container.ts

@@ -0,0 +1,40 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { hasAttributes } from "./attributes";
+import { getStringContainerRendering, isContentsOnlyStringContainer } from "./string-types";
+import { renderPlainWrapped, renderStyledSpan, renderWrapped } from "./wrappers";
+
+/**
+ * Render a container whose type is a plain string identifier.
+ */
+export function renderStringContainer(
+  ctx: RenderContext,
+  type: string,
+  attributes: Record<string, string>,
+  elements: Element[],
+): void {
+  if (type === "div" && elements.length === 0 && !hasAttributes(attributes)) {
+    return;
+  }
+
+  if (isContentsOnlyStringContainer(type)) {
+    renderElements(ctx, elements);
+    return;
+  }
+
+  const rendering = getStringContainerRendering(type);
+  switch (rendering.kind) {
+    case "wrapped":
+      renderWrapped(ctx, rendering.tag, attributes, elements);
+      return;
+    case "styled-span":
+      renderStyledSpan(ctx, rendering.style, attributes, elements);
+      return;
+    case "plain-wrapped":
+      renderPlainWrapped(ctx, rendering.tag, elements);
+      return;
+    case "contents":
+      renderElements(ctx, elements);
+  }
+}

package/src/elements/container/string-types.ts

@@ -0,0 +1,63 @@
+type StringContainerRendering =
+  | { kind: "wrapped"; tag: string }
+  | { kind: "styled-span"; style: string }
+  | { kind: "plain-wrapped"; tag: string }
+  | { kind: "contents" };
+
+const WRAPPED_TAGS: Readonly<Record<string, string>> = {
+  paragraph: "p",
+  bold: "strong",
+  italics: "em",
+  superscript: "sup",
+  subscript: "sub",
+  monospace: "tt",
+  span: "span",
+  div: "div",
+  blockquote: "blockquote",
+  mark: "mark",
+  insertion: "ins",
+  deletion: "del",
+  size: "span",
+  ruby: "ruby",
+  "ruby-text": "rt",
+  "table-row": "tr",
+  "table-cell": "td",
+};
+
+const STYLED_SPANS: Readonly<Record<string, string>> = {
+  underline: "text-decoration: underline;",
+  strikethrough: "text-decoration: line-through;",
+  hidden: "display: none",
+  invisible: "visibility: hidden",
+};
+
+const PLAIN_WRAPPED_TAGS: Readonly<Record<string, string>> = {
+  "definition-list": "dl",
+  "definition-list-key": "dt",
+  "definition-list-value": "dd",
+};
+
+const CONTENTS_ONLY_TYPES = new Set(["heading", "collapsible", "definition-list-item"]);
+
+export function getStringContainerRendering(type: string): StringContainerRendering {
+  const wrappedTag = WRAPPED_TAGS[type];
+  if (wrappedTag) {
+    return { kind: "wrapped", tag: wrappedTag };
+  }
+
+  const style = STYLED_SPANS[type];
+  if (style) {
+    return { kind: "styled-span", style };
+  }
+
+  const plainTag = PLAIN_WRAPPED_TAGS[type];
+  if (plainTag) {
+    return { kind: "plain-wrapped", tag: plainTag };
+  }
+
+  return { kind: "contents" };
+}
+
+export function isContentsOnlyStringContainer(type: string): boolean {
+  return CONTENTS_ONLY_TYPES.has(type);
+}

package/src/elements/container/wrappers.ts

@@ -0,0 +1,32 @@
+import type { Element } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderContainerAttrs } from "./attributes";
+
+export function renderWrapped(
+  ctx: RenderContext,
+  tag: string,
+  attributes: Record<string, string>,
+  elements: Element[],
+): void {
+  ctx.push(`<${tag}${renderContainerAttrs(attributes)}>`);
+  renderElements(ctx, elements);
+  ctx.push(`</${tag}>`);
+}
+
+export function renderPlainWrapped(ctx: RenderContext, tag: string, elements: Element[]): void {
+  ctx.push(`<${tag}>`);
+  renderElements(ctx, elements);
+  ctx.push(`</${tag}>`);
+}
+
+export function renderStyledSpan(
+  ctx: RenderContext,
+  style: string,
+  attributes: Record<string, string>,
+  elements: Element[],
+): void {
+  ctx.push(`<span style="${style}"${renderContainerAttrs(attributes)}>`);
+  renderElements(ctx, elements);
+  ctx.push("</span>");
+}

package/src/elements/date/format.ts

@@ -0,0 +1,20 @@
+/**
+ * Format a `Date` using a subset of `strftime` specifiers.
+ *
+ * Supported specifiers: `%Y` (4-digit year), `%m` (zero-padded month),
+ * `%d` (zero-padded day), `%H` (zero-padded hours), `%M` (zero-padded
+ * minutes), `%S` (zero-padded seconds).
+ *
+ * @param date - The date to format.
+ * @param format - A strftime-compatible format string.
+ * @returns The formatted date string.
+ */
+export function formatDate(date: Date, format: string): string {
+  return format
+    .replace(/%Y/g, String(date.getFullYear()))
+    .replace(/%m/g, String(date.getMonth() + 1).padStart(2, "0"))
+    .replace(/%d/g, String(date.getDate()).padStart(2, "0"))
+    .replace(/%H/g, String(date.getHours()).padStart(2, "0"))
+    .replace(/%M/g, String(date.getMinutes()).padStart(2, "0"))
+    .replace(/%S/g, String(date.getSeconds()).padStart(2, "0"));
+}

package/src/elements/date/index.ts

@@ -0,0 +1,34 @@
+/**
+ *
+ * Renderer for Wikidot's date/time elements.
+ *
+ * Wikidot stores dates as Unix timestamps and optionally provides a
+ * `strftime`-style format string. The renderer formats the date
+ * server-side; when the `hover` flag is set, the output is wrapped in
+ * `<span class="odate">` so that the runtime `odate` module can
+ * reformat it to the user's local timezone on the client.
+ *
+ * @module
+ */
+
+import type { DateData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { formatDate } from "./format";
+import { renderDateOutput } from "./output";
+
+/**
+ * Render a date element, optionally wrapping in an `odate` span for
+ * client-side timezone conversion.
+ *
+ * When `data.format` is provided, the date is formatted using a subset
+ * of `strftime` specifiers (`%Y`, `%m`, `%d`, `%H`, `%M`, `%S`).
+ * Otherwise, `Date.toLocaleString()` is used as a fallback.
+ *
+ * @param ctx - The current render context.
+ * @param data - Date element data with timestamp, optional format, and hover flag.
+ */
+export function renderDate(ctx: RenderContext, data: DateData): void {
+  const date = new Date(data.value.timestamp * 1000);
+  const formatted = data.format ? formatDate(date, data.format) : date.toLocaleString();
+  ctx.push(renderDateOutput(formatted, data.hover));
+}

package/src/elements/date/output.ts

@@ -0,0 +1,6 @@
+import { escapeHtml } from "../../escape";
+
+export function renderDateOutput(formatted: string, hover: boolean): string {
+  const escaped = escapeHtml(formatted);
+  return hover ? `<span class="odate">${escaped}</span>` : escaped;
+}

package/src/elements/embed/iframe.ts

@@ -0,0 +1,8 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr } from "../../escape";
+
+export function renderEmbedIframe(ctx: RenderContext, className: string, src: string): void {
+  ctx.push(`<div class="${className}">`);
+  ctx.push(`<iframe src="${escapeAttr(src)}" frameborder="0" allowfullscreen></iframe>`);
+  ctx.push("</div>");
+}

package/src/elements/embed/index.ts

@@ -0,0 +1,28 @@
+/**
+ *
+ * Renderer for inline embed elements (`[[embed]]`) that reference
+ * third-party content providers.
+ *
+ * @module
+ */
+
+import type { Embed } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderGithubGist, renderGitlabSnippet, renderVimeo, renderYoutube } from "./providers";
+
+export function renderEmbed(ctx: RenderContext, data: Embed): void {
+  switch (data.embed) {
+    case "youtube":
+      renderYoutube(ctx, data.data["video-id"]);
+      break;
+    case "vimeo":
+      renderVimeo(ctx, data.data["video-id"]);
+      break;
+    case "github-gist":
+      renderGithubGist(ctx, data.data.username, data.data.hash);
+      break;
+    case "gitlab-snippet":
+      renderGitlabSnippet(ctx, data.data["snippet-id"]);
+      break;
+  }
+}

package/src/elements/embed/providers.ts

@@ -0,0 +1,43 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr } from "../../escape";
+import { renderEmbedIframe } from "./iframe";
+import {
+  isValidGithubUsername,
+  isValidGistHash,
+  isValidGitlabSnippetId,
+  isValidVideoId,
+} from "./validation";
+
+export function renderYoutube(ctx: RenderContext, videoId: string): void {
+  if (!isValidVideoId(videoId)) {
+    ctx.push(`<!-- Invalid YouTube video ID -->`);
+    return;
+  }
+  renderEmbedIframe(ctx, "embed-youtube", `https://www.youtube.com/embed/${videoId}`);
+}
+
+export function renderVimeo(ctx: RenderContext, videoId: string): void {
+  if (!isValidVideoId(videoId)) {
+    ctx.push(`<!-- Invalid Vimeo video ID -->`);
+    return;
+  }
+  renderEmbedIframe(ctx, "embed-vimeo", `https://player.vimeo.com/video/${videoId}`);
+}
+
+export function renderGithubGist(ctx: RenderContext, username: string, hash: string): void {
+  if (!isValidGithubUsername(username) || !isValidGistHash(hash)) {
+    ctx.push(`<!-- Invalid GitHub Gist parameters -->`);
+    return;
+  }
+  ctx.push(
+    `<script src="https://gist.github.com/${escapeAttr(username)}/${escapeAttr(hash)}.js"></script>`,
+  );
+}
+
+export function renderGitlabSnippet(ctx: RenderContext, snippetId: string): void {
+  if (!isValidGitlabSnippetId(snippetId)) {
+    ctx.push(`<!-- Invalid GitLab snippet ID -->`);
+    return;
+  }
+  ctx.push(`<script src="https://gitlab.com/snippets/${escapeAttr(snippetId)}.js"></script>`);
+}

package/src/elements/embed/validation.ts

@@ -0,0 +1,15 @@
+export function isValidVideoId(id: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
+export function isValidGithubUsername(username: string): boolean {
+  return /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(username);
+}
+
+export function isValidGistHash(hash: string): boolean {
+  return /^[a-f0-9]+$/.test(hash);
+}
+
+export function isValidGitlabSnippetId(id: string): boolean {
+  return /^[0-9]+$/.test(id);
+}