@wdprlib/render 2.1.0 → 3.0.0

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

@@ -11,9 +11,9 @@
  */
 
 import type { IncludeData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, escapeHtml } from "../escape";
-import { renderElements } from "../render";
+import type { RenderContext } from "../../context";
+import { renderElements } from "../../render";
+import { renderMissingInclude } from "./missing";
 
 /**
  * Render an `[[include]]` element.
@@ -26,18 +26,10 @@ import { renderElements } from "../render";
  * @param data - Include data with the target page location and resolved elements.
  */
 export function renderInclude(ctx: RenderContext, data: IncludeData): void {
-  // If elements is empty, the include was not resolved - show error
   if (data.elements.length === 0) {
-    // Wikidot normalizes page names to lowercase
-    const pageName = data.location.page.toLowerCase();
-    // Encode page name for URL path (/ should not be encoded, but special chars should)
-    const encodedPageName = pageName.replace(/[^a-z0-9\-_:/]/g, (c) => encodeURIComponent(c));
-    // Prevent protocol-relative URLs
-    const safePath = encodedPageName.startsWith("/") ? encodedPageName.slice(1) : encodedPageName;
-    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>`,
-    );
+    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/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>");
+}

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