@wdprlib/render 2.0.0 → 3.0.0

package/src/elements/iftags/tokens.ts

@@ -0,0 +1,36 @@
+export interface IfTagsConditionTokens {
+  required: string[];
+  excluded: string[];
+  optional: string[];
+}
+
+export function parseIfTagsConditionTokens(condition: string): IfTagsConditionTokens {
+  const tokens: IfTagsConditionTokens = {
+    required: [],
+    excluded: [],
+    optional: [],
+  };
+
+  for (const token of condition.split(/\s+/).filter(Boolean)) {
+    if (token.startsWith("+")) {
+      addTag(tokens.required, token.slice(1));
+    } else if (token.startsWith("-")) {
+      addTag(tokens.excluded, token.slice(1));
+    } else {
+      addTag(tokens.optional, token);
+    }
+  }
+
+  return tokens;
+}
+
+export function hasAnyIfTagsConditionToken(tokens: IfTagsConditionTokens): boolean {
+  return tokens.required.length > 0 || tokens.excluded.length > 0 || tokens.optional.length > 0;
+}
+
+function addTag(tags: string[], rawTag: string): void {
+  const tag = rawTag.toLowerCase();
+  if (tag) {
+    tags.push(tag);
+  }
+}

package/src/elements/image/alignment.ts

@@ -0,0 +1,44 @@
+import type { FloatAlignment } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+export function pushAlignedImage(
+  ctx: RenderContext,
+  output: string,
+  alignment: FloatAlignment | null,
+): void {
+  if (!alignment) {
+    ctx.push(output);
+    return;
+  }
+
+  const alignClass = getAlignmentClass(alignment.align, alignment.float);
+  ctx.push(`<div class="image-container ${alignClass}">`);
+  ctx.push(output);
+  ctx.push("</div>");
+}
+
+function getAlignmentClass(align: string, isFloat: boolean): string {
+  if (isFloat) {
+    switch (align) {
+      case "left":
+        return "floatleft";
+      case "right":
+        return "floatright";
+      case "center":
+        return "floatcenter";
+      default:
+        return `float${align}`;
+    }
+  }
+
+  switch (align) {
+    case "left":
+      return "alignleft";
+    case "right":
+      return "alignright";
+    case "center":
+      return "aligncenter";
+    default:
+      return `align${align}`;
+  }
+}

package/src/elements/image/attributes.ts

@@ -0,0 +1,10 @@
+import type { ImageSource } from "@wdprlib/ast";
+import { getImageAttributes } from "./img-attributes";
+
+export function buildImageTag(
+  src: string,
+  source: ImageSource,
+  attributes: Record<string, string>,
+): string {
+  return `<img ${getImageAttributes(src, source, attributes).join(" ")} />`;
+}

package/src/elements/image/img-attributes.ts

@@ -0,0 +1,26 @@
+import type { ImageSource } from "@wdprlib/ast";
+import { escapeAttr, sanitizeAttributes } from "../../escape";
+import { getFilenameFromSource } from "./source";
+
+export function getImageAttributes(
+  src: string,
+  source: ImageSource,
+  attributes: Record<string, string>,
+): string[] {
+  const safeAttrs = sanitizeAttributes(attributes);
+  const imgAttrs: string[] = [`src="${escapeAttr(src)}"`];
+
+  appendPassedImageAttributes(imgAttrs, safeAttrs);
+  imgAttrs.push(`alt="${escapeAttr(safeAttrs.alt ?? getFilenameFromSource(source))}"`);
+  imgAttrs.push(`class="${escapeAttr(safeAttrs.class ?? "image")}"`);
+
+  return imgAttrs;
+}
+
+function appendPassedImageAttributes(imgAttrs: string[], safeAttrs: Record<string, string>): void {
+  for (const key in safeAttrs) {
+    if (key === "alt" || key === "class" || key === "src" || key === "srcset") continue;
+    const value = safeAttrs[key]!;
+    imgAttrs.push(`${key}="${escapeAttr(value)}"`);
+  }
+}

package/src/elements/image/index.ts

@@ -0,0 +1,36 @@
+/**
+ *
+ * Renderer for Wikidot image elements (`[[image source]]` and `[[f<image source]]`).
+ *
+ * Images can be sourced from URLs, page-attached files, or cross-site
+ * files. The renderer resolves the source to a URL, sanitizes all
+ * attributes, optionally wraps the image in a link (`link` attribute),
+ * and optionally wraps everything in an alignment container div.
+ *
+ * @module
+ */
+
+import type { ImageData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { isDangerousUrl } from "../../escape";
+import { buildImageTag } from "./attributes";
+import { pushAlignedImage } from "./alignment";
+import { wrapImageLink } from "./link";
+
+/**
+ * Render an image element with optional link wrapper and alignment container.
+ *
+ * Dangerous URLs are replaced with `#invalid-url`. Local paths blocked
+ * by settings cause the entire image to be silently dropped.
+ */
+export function renderImage(ctx: RenderContext, data: ImageData): void {
+  let src = ctx.resolveImageSource(data.source);
+  if (src === null) return;
+  if (isDangerousUrl(src)) {
+    src = "#invalid-url";
+  }
+
+  const imageTag = buildImageTag(src, data.source, data.attributes);
+  const output = wrapImageLink(imageTag, data.link);
+  pushAlignedImage(ctx, output, data.alignment);
+}

package/src/elements/image/link-href.ts

@@ -0,0 +1,24 @@
+import type { LinkLocation } from "@wdprlib/ast";
+import { isDangerousUrl } from "../../escape";
+
+export function resolveSafeImageLinkHref(link: LinkLocation): string {
+  const href = resolveImageLinkHref(link);
+  return isDangerousUrl(href) ? "#invalid-url" : href;
+}
+
+function resolveImageLinkHref(link: LinkLocation): string {
+  if (typeof link !== "string") {
+    return `/${link.page}`;
+  }
+
+  if (
+    !link.startsWith("/") &&
+    !link.startsWith("#") &&
+    !link.startsWith("http://") &&
+    !link.startsWith("https://")
+  ) {
+    return `/${link}`;
+  }
+
+  return link;
+}

package/src/elements/image/link.ts

@@ -0,0 +1,13 @@
+import type { LinkLocation } from "@wdprlib/ast";
+import { escapeAttr } from "../../escape";
+import { resolveSafeImageLinkHref } from "./link-href";
+
+export function wrapImageLink(imageTag: string, link: LinkLocation | null): string {
+  if (!link) {
+    return imageTag;
+  }
+
+  const href = resolveSafeImageLinkHref(link);
+
+  return `<a href="${escapeAttr(href)}">${imageTag}</a>`;
+}

package/src/elements/image/source.ts

@@ -0,0 +1,16 @@
+import type { ImageSource } from "@wdprlib/ast";
+
+export function getFilenameFromSource(source: ImageSource): string {
+  switch (source.type) {
+    case "url": {
+      const slashIndex = source.data.lastIndexOf("/");
+      return slashIndex === -1 ? source.data : source.data.slice(slashIndex + 1);
+    }
+    case "file1":
+      return source.data.file;
+    case "file2":
+      return source.data.file;
+    case "file3":
+      return source.data.file;
+  }
+}

package/src/elements/include/index.ts

@@ -0,0 +1,35 @@
+/**
+ *
+ * Renderer for `[[include page-name]]` transclusion elements.
+ *
+ * Includes are resolved by the parser before rendering: if the target
+ * page exists, its parsed elements are injected into the AST. At render
+ * time, the renderer either outputs the pre-resolved elements or shows
+ * a Wikidot-compatible error message with a "create it now" link.
+ *
+ * @module
+ */
+
+import type { IncludeData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderMissingInclude } from "./missing";
+
+/**
+ * Render an `[[include]]` element.
+ *
+ * If the include was resolved by the parser (i.e., `data.elements` is
+ * non-empty), the resolved elements are rendered directly. Otherwise,
+ * a Wikidot-compatible error block with a "create it now" link is shown.
+ *
+ * @param ctx - The current render context.
+ * @param data - Include data with the target page location and resolved elements.
+ */
+export function renderInclude(ctx: RenderContext, data: IncludeData): void {
+  if (data.elements.length === 0) {
+    renderMissingInclude(ctx, data.location.page);
+    return;
+  }
+
+  renderElements(ctx, data.elements);
+}

package/src/elements/include/missing.ts

@@ -0,0 +1,15 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr, escapeHtml } from "../../escape";
+
+export function renderMissingInclude(ctx: RenderContext, page: string): void {
+  const pageName = page.toLowerCase();
+  const safePath = encodeIncludeEditPath(pageName);
+  ctx.push(
+    `<div class="error-block"><p>Included page "${escapeHtml(pageName)}" does not exist (<a href="/${escapeAttr(safePath)}/edit/true">create it now</a>)</p></div>`,
+  );
+}
+
+function encodeIncludeEditPath(pageName: string): string {
+  const encodedPageName = pageName.replace(/[^a-z0-9\-_:/]/g, (c) => encodeURIComponent(c));
+  return encodedPageName.startsWith("/") ? encodedPageName.slice(1) : encodedPageName;
+}

package/src/elements/index.ts

@@ -0,0 +1,35 @@
+/**
+ *
+ * Barrel export for all Wikidot element renderers.
+ *
+ * Each renderer function accepts a `RenderContext` and the
+ * element-specific AST data, then pushes the resulting HTML fragments
+ * into the context's output buffer.
+ *
+ * @module
+ */
+
+export { renderContainer } from "./container";
+export { renderText, renderRaw, renderEmail } from "./text";
+export { renderLink, renderAnchor, renderAnchorName } from "./link";
+export { renderImage } from "./image";
+export { renderList, renderDefinitionList } from "./list";
+export { renderTable } from "./table";
+export { renderCollapsible } from "./collapsible";
+export { renderCode } from "./code";
+export { renderTabView } from "./tab-view";
+export { renderFootnoteRef, renderFootnoteBlock } from "./footnote";
+export { renderMath, renderMathInline } from "./math";
+export { renderModule } from "./module/index";
+export { renderEmbed } from "./embed";
+export { renderUser } from "./user";
+export { renderBibliographyCite, renderBibliographyBlock } from "./bibliography";
+export { renderTableOfContents } from "./toc";
+export { renderLineBreaks } from "./line-break";
+export { renderClearFloat } from "./clear-float";
+export { renderIframe } from "./iframe";
+export { renderHtmlBlock } from "./html";
+export { renderInclude } from "./include";
+export { renderIfTags } from "./iftags";
+export { renderColor } from "./color";
+export { renderDate } from "./date";

package/src/elements/line-break.ts

@@ -0,0 +1,22 @@
+/**
+ *
+ * Renderer for explicit line breaks (`_` at end of line in Wikidot markup).
+ *
+ * Multiple consecutive line-break elements produce multiple `<br />` tags.
+ *
+ * @module
+ */
+
+import type { RenderContext } from "../context";
+
+/**
+ * Render one or more consecutive line breaks as `<br />` tags.
+ *
+ * @param ctx - The current render context.
+ * @param count - Number of `<br />` tags to emit.
+ */
+export function renderLineBreaks(ctx: RenderContext, count: number): void {
+  for (let i = 0; i < count; i++) {
+    ctx.push("<br />");
+  }
+}

package/src/elements/link/anchor-name.ts

@@ -0,0 +1,6 @@
+import type { RenderContext } from "../../context";
+import { escapeAttr } from "../../escape";
+
+export function renderAnchorName(ctx: RenderContext, name: string): void {
+  ctx.push(`<a name="${escapeAttr(name)}"></a>`);
+}

package/src/elements/link/anchor.ts

@@ -0,0 +1,27 @@
+import type { AnchorData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, isDangerousUrl, sanitizeAttributes } from "../../escape";
+import { renderElements } from "../../render";
+import { renderTargetAttributes } from "./target";
+
+export function renderAnchor(ctx: RenderContext, data: AnchorData): void {
+  const safe = sanitizeAttributes(data.attributes);
+  const attrs: string[] = [];
+
+  if (safe.href && isDangerousUrl(safe.href)) {
+    safe.href = "#invalid-url";
+  }
+
+  const href = safe.href ?? "";
+  attrs.push(`href="${escapeAttr(href)}"`);
+  renderTargetAttributes(attrs, data.target);
+
+  for (const [key, value] of Object.entries(safe)) {
+    if (key === "href" || key === "target") continue;
+    attrs.push(`${key}="${escapeAttr(value)}"`);
+  }
+
+  ctx.push(`<a ${attrs.join(" ")}>`);
+  renderElements(ctx, data.elements);
+  ctx.push("</a>");
+}

package/src/elements/link/attributes.ts

@@ -0,0 +1,47 @@
+import type { LinkData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { escapeAttr, isDangerousUrl } from "../../escape";
+import { renderTargetAttributes } from "./target";
+
+export function getLinkAttributes(ctx: RenderContext, data: LinkData): string[] {
+  const attrs: string[] = [`href="${escapeAttr(resolveSafeHref(ctx, data))}"`];
+
+  if (shouldAddNewPageClass(ctx, data)) {
+    attrs.push(`class="newpage"`);
+  }
+
+  renderTargetAttributes(attrs, data.target);
+  return attrs;
+}
+
+function resolveSafeHref(ctx: RenderContext, data: LinkData): string {
+  let href = ctx.resolvePageLink(data.link);
+
+  if (data.extra) {
+    href += data.extra;
+  }
+
+  const isAnchorJsVoid = data.type === "anchor" && href === "javascript:;";
+  if (!isAnchorJsVoid && isDangerousUrl(href)) {
+    return "#invalid-url";
+  }
+
+  return href;
+}
+
+function shouldAddNewPageClass(ctx: RenderContext, data: LinkData): boolean {
+  if (data.type !== "page" || typeof data.link !== "object") {
+    return false;
+  }
+
+  const page = data.link.page;
+  const isSpecialPage = page.startsWith("//") || page.includes("#/");
+  if (isSpecialPage) {
+    return false;
+  }
+
+  const hashIdx = page.indexOf("#");
+  const pageToCheck = hashIdx !== -1 ? page.slice(0, hashIdx) : page;
+  const pageExists = ctx.page?.pageExists;
+  return pageExists ? !pageExists(pageToCheck) : true;
+}

package/src/elements/link/index.ts

@@ -0,0 +1,26 @@
+/**
+ *
+ * Renderers for Wikidot link elements.
+ *
+ * Wikidot supports page links, external links, anchor-type links,
+ * `[[a]]...[[/a]]` anchors, and named anchors.
+ *
+ * @module
+ */
+
+import type { LinkData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderAnchor } from "./anchor";
+import { renderAnchorName } from "./anchor-name";
+import { getLinkAttributes } from "./attributes";
+import { renderLinkLabel } from "./label";
+
+export { renderAnchor, renderAnchorName };
+
+export function renderLink(ctx: RenderContext, data: LinkData): void {
+  const attrs = getLinkAttributes(ctx, data);
+
+  ctx.push(`<a ${attrs.join(" ")}>`);
+  renderLinkLabel(ctx, data);
+  ctx.push("</a>");
+}

package/src/elements/link/label.ts

@@ -0,0 +1,23 @@
+import type { LinkData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+
+export function renderLinkLabel(ctx: RenderContext, data: LinkData): void {
+  if (data.label === "page") {
+    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) {
+    const href = ctx.resolvePageLink(data.link);
+    ctx.pushEscaped(data.label.url ?? href);
+  }
+}

package/src/elements/link/target.ts

@@ -0,0 +1,20 @@
+import type { AnchorTarget } from "@wdprlib/ast";
+
+const TARGET_VALUES: Record<AnchorTarget, string> = {
+  "new-tab": "_blank",
+  parent: "_parent",
+  top: "_top",
+  same: "_self",
+};
+
+export function renderTargetAttributes(attrs: string[], target: AnchorTarget | null): void {
+  if (!target) {
+    return;
+  }
+
+  const targetValue = TARGET_VALUES[target] ?? "_blank";
+  attrs.push(`target="${targetValue}"`);
+  if (targetValue === "_blank") {
+    attrs.push(`rel="noopener noreferrer"`);
+  }
+}

package/src/elements/list/attributes.ts

@@ -0,0 +1,19 @@
+import { escapeAttr, sanitizeAttributes } from "../../escape";
+
+export function renderListAttrs(attributes: Record<string, string>): string {
+  let hasAttributes = false;
+  for (const _ in attributes) {
+    hasAttributes = true;
+    break;
+  }
+  if (!hasAttributes) 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/list/definition-list.ts

@@ -0,0 +1,16 @@
+import type { DefinitionListItem } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+
+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/list/index.ts

@@ -0,0 +1,48 @@
+/**
+ *
+ * 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).
+ *
+ * @module
+ */
+
+import type { ListData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderDefinitionList } from "./definition-list";
+import { renderListAttrs } from "./attributes";
+import { renderListItems } from "./items";
+import { hasNonWhitespaceElement } from "./trim";
+
+export { renderDefinitionList };
+
+/**
+ * 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.
+ */
+export function renderList(ctx: RenderContext, data: ListData): void {
+  const hasContent = data.items.some((item) => {
+    if (item["item-type"] === "sub-list") return true;
+    if (item["item-type"] === "elements") {
+      return hasNonWhitespaceElement(item.elements);
+    }
+    return false;
+  });
+
+  if (!hasContent) {
+    return;
+  }
+
+  const tag = data.type === "numbered" ? "ol" : "ul";
+  ctx.push(`<${tag}${renderListAttrs(data.attributes)}>`);
+
+  renderListItems(ctx, data.items, renderList);
+
+  ctx.push(`</${tag}>`);
+}

package/src/elements/list/item-rendering.ts

@@ -0,0 +1,38 @@
+import type { ListData } from "@wdprlib/ast";
+import { renderListAttrs } from "./attributes";
+
+type ListItem = ListData["items"][number];
+type SubListItem = Extract<ListItem, { "item-type": "sub-list" }>;
+
+export function getListItemOpenTag(attributes: Record<string, string>): string {
+  const styleAttr = hasNoMarker(attributes) ? ' style="list-style: none"' : "";
+  return `<li${renderListAttrs(attributes)}${styleAttr}>`;
+}
+
+export function hasNoMarker(attributes: Record<string, string>): boolean {
+  return attributes._noMarker === "true";
+}
+
+export function renderFollowingSubLists(
+  items: ListData["items"],
+  index: number,
+  renderNestedList: (data: ListData) => void,
+): number {
+  let nextIndex = index;
+
+  while (nextIndex + 1 < items.length) {
+    const nextItem = getSubListItem(items[nextIndex + 1]);
+    if (!nextItem) {
+      break;
+    }
+
+    nextIndex++;
+    renderNestedList(nextItem.data);
+  }
+
+  return nextIndex;
+}
+
+function getSubListItem(item: ListItem | undefined): SubListItem | null {
+  return item?.["item-type"] === "sub-list" ? item : null;
+}

package/src/elements/list/items.ts

@@ -0,0 +1,61 @@
+import type { ListData } from "@wdprlib/ast";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { getListItemOpenTag, hasNoMarker, renderFollowingSubLists } from "./item-rendering";
+import { renderNoMarkerElements } from "./no-marker";
+import { trimTextElements } from "./trim";
+
+type ListItem = ListData["items"][number];
+type ElementsListItem = Extract<ListItem, { "item-type": "elements" }>;
+type SubListItem = Extract<ListItem, { "item-type": "sub-list" }>;
+
+export type NestedListRenderer = (ctx: RenderContext, data: ListData) => void;
+
+export function renderListItems(
+  ctx: RenderContext,
+  items: ListData["items"],
+  renderNestedList: NestedListRenderer,
+): void {
+  let i = 0;
+  while (i < items.length) {
+    const item = items[i]!;
+    if (item["item-type"] === "elements") {
+      i = renderElementsListItem(ctx, item, items, i, renderNestedList);
+    } else {
+      renderOrphanSubListItem(ctx, item, renderNestedList);
+    }
+    i++;
+  }
+}
+
+function renderElementsListItem(
+  ctx: RenderContext,
+  item: ElementsListItem,
+  items: ListData["items"],
+  index: number,
+  renderNestedList: NestedListRenderer,
+): number {
+  const noMarker = hasNoMarker(item.attributes);
+  ctx.push(getListItemOpenTag(item.attributes));
+
+  if (noMarker) {
+    renderNoMarkerElements(ctx, item.elements);
+  } else {
+    renderElements(ctx, trimTextElements(item.elements));
+  }
+
+  const nextIndex = renderFollowingSubLists(items, index, (data) => renderNestedList(ctx, data));
+
+  ctx.push("</li>");
+  return nextIndex;
+}
+
+function renderOrphanSubListItem(
+  ctx: RenderContext,
+  item: SubListItem,
+  renderNestedList: NestedListRenderer,
+): void {
+  ctx.push(`<li style="list-style: none; display: inline">`);
+  renderNestedList(ctx, item.data);
+  ctx.push("</li>");
+}