@wdprlib/render 2.1.0 → 3.0.0

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/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/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.ts → date/index.ts}

@@ -12,8 +12,9 @@
  */
 
 import type { DateData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeHtml } from "../escape";
+import type { RenderContext } from "../../context";
+import { formatDate } from "./format";
+import { renderDateOutput } from "./output";
 
 /**
  * Render a date element, optionally wrapping in an `odate` span for
@@ -29,31 +30,5 @@ import { escapeHtml } from "../escape";
 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();
-
-  if (data.hover) {
-    ctx.push(`<span class="odate">${escapeHtml(formatted)}</span>`);
-  } else {
-    ctx.push(escapeHtml(formatted));
-  }
-}
-
-/**
- * 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.
- */
-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"));
+  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);
+}

package/src/elements/embed-block/allowlist.ts

@@ -0,0 +1,60 @@
+/**
+ * Allowlist entry for embed content validation.
+ */
+export interface EmbedAllowlistEntry {
+  /** Host pattern. Supports wildcard prefix `*.` such as `*.youtube.com`. */
+  host: string;
+  /** Optional path prefix that must match, such as `/embed/`. */
+  pathPrefix?: string;
+}
+
+/**
+ * Default allowlist for embed content.
+ *
+ * Set the render option to `null` to allow any HTTP(S) iframe while still using
+ * sanitizer and scheme validation.
+ */
+export const DEFAULT_EMBED_ALLOWLIST: EmbedAllowlistEntry[] | null = [
+  { host: "*.youtube.com", pathPrefix: "/embed/" },
+  { host: "*.youtube-nocookie.com", pathPrefix: "/embed/" },
+  { host: "player.vimeo.com", pathPrefix: "/video/" },
+  { host: "*.google.com", pathPrefix: "/maps/embed" },
+  { host: "calendar.google.com", pathPrefix: "/calendar/embed" },
+  { host: "open.spotify.com", pathPrefix: "/embed/" },
+  { host: "w.soundcloud.com", pathPrefix: "/player/" },
+  { host: "codepen.io" },
+];
+
+/**
+ * Check whether a URL matches an allowlist entry's host and optional path prefix.
+ */
+export function matchesAllowlistEntry(url: URL, entry: EmbedAllowlistEntry): boolean {
+  if (!matchesHostPattern(url.hostname, entry.host)) {
+    return false;
+  }
+  if (entry.pathPrefix) {
+    const pathLower = url.pathname.toLowerCase();
+    const prefixLower = entry.pathPrefix.toLowerCase();
+    if (!pathLower.startsWith(prefixLower)) {
+      return false;
+    }
+    if (!prefixLower.endsWith("/")) {
+      const remainder = pathLower.slice(prefixLower.length);
+      if (remainder && !/^[/?#]/.test(remainder)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function matchesHostPattern(hostname: string, pattern: string): boolean {
+  const lowerHostname = hostname.toLowerCase();
+  const lowerPattern = pattern.toLowerCase();
+
+  if (lowerPattern.startsWith("*.")) {
+    const base = lowerPattern.slice(2);
+    return lowerHostname === base || lowerHostname.endsWith("." + base);
+  }
+  return lowerHostname === lowerPattern;
+}