@wdprlib/render 2.1.0 → 3.0.0

package/src/elements/image.ts

@@ -1,154 +0,0 @@
-/**
- *
- * 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 { ImageSource, ImageData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, isDangerousUrl, sanitizeAttributes } from "../escape";
-
-/**
- * Render an image element with optional link wrapper and alignment container.
- *
- * Processing steps:
- * 1. Resolve the image source to a URL via `ctx.resolveImageSource()`.
- * 2. Sanitize user-supplied attributes.
- * 3. Build the `<img>` tag with safe attributes.
- * 4. Optionally wrap in an `<a>` tag if a link target is specified.
- * 5. Optionally wrap in a `<div class="image-container ...">` for alignment.
- *
- * Dangerous URLs are replaced with `#invalid-url`. Local paths blocked
- * by settings cause the entire image to be silently dropped.
- *
- * @param ctx - The current render context.
- * @param data - Image element data with source, attributes, optional link, and alignment.
- */
-export function renderImage(ctx: RenderContext, data: ImageData): void {
-  let src = ctx.resolveImageSource(data.source);
-  if (src === null) return; // Local path blocked by settings
-  if (isDangerousUrl(src)) {
-    src = "#invalid-url";
-  }
-  const safeAttrs = sanitizeAttributes(data.attributes);
-  const alt = safeAttrs.alt ?? getFilenameFromSource(data.source);
-  const className = safeAttrs.class ?? "image";
-
-  // Build img attributes
-  const imgAttrs: string[] = [`src="${escapeAttr(src)}"`];
-
-  // Custom attributes (title, style, etc.) before alt/class
-  // Skip src/srcset to prevent override of resolved source
-  for (const [key, value] of Object.entries(safeAttrs)) {
-    if (key === "alt" || key === "class" || key === "src" || key === "srcset") continue;
-    imgAttrs.push(`${key}="${escapeAttr(value)}"`);
-  }
-
-  imgAttrs.push(`alt="${escapeAttr(alt)}"`);
-
-  // Only override class if not custom
-  if (!safeAttrs.class) {
-    imgAttrs.push(`class="${escapeAttr(className)}"`);
-  } else {
-    imgAttrs.push(`class="${escapeAttr(safeAttrs.class)}"`);
-  }
-
-  const imgTag = `<img ${imgAttrs.join(" ")} />`;
-
-  // Wrap in link if needed
-  let output = imgTag;
-  if (data.link) {
-    let href: string;
-    if (typeof data.link === "string") {
-      // Add leading slash for page links (not URLs or anchors)
-      if (
-        !data.link.startsWith("/") &&
-        !data.link.startsWith("#") &&
-        !data.link.startsWith("http://") &&
-        !data.link.startsWith("https://")
-      ) {
-        href = `/${data.link}`;
-      } else {
-        href = data.link;
-      }
-    } else {
-      href = `/${data.link.page}`;
-    }
-    if (isDangerousUrl(href)) {
-      href = "#invalid-url";
-    }
-    output = `<a href="${escapeAttr(href)}">${imgTag}</a>`;
-  }
-
-  // Wrap in alignment container if needed
-  if (data.alignment) {
-    const alignClass = getAlignmentClass(data.alignment.align, data.alignment.float);
-    ctx.push(`<div class="image-container ${alignClass}">`);
-    ctx.push(output);
-    ctx.push("</div>");
-  } else {
-    ctx.push(output);
-  }
-}
-
-/**
- * Map an alignment direction and float flag to a Wikidot CSS class name.
- *
- * @param align - Alignment direction (`"left"`, `"right"`, `"center"`).
- * @param isFloat - Whether the image uses float positioning.
- * @returns CSS class name (e.g. `"floatleft"`, `"aligncenter"`).
- */
-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}`;
-  }
-}
-
-/**
- * Extract a filename from an image source for use as the default `alt` text.
- *
- * For URL sources, the last path segment is returned. For file-type sources,
- * the file name field is returned directly.
- *
- * @param source - The image source descriptor.
- * @returns The extracted filename string.
- */
-function getFilenameFromSource(source: ImageSource): string {
-  switch (source.type) {
-    case "url": {
-      const parts = source.data.split("/");
-      return parts[parts.length - 1] ?? source.data;
-    }
-    case "file1":
-      return source.data.file;
-    case "file2":
-      return source.data.file;
-    case "file3":
-      return source.data.file;
-  }
-}

package/src/elements/link.ts

@@ -1,201 +0,0 @@
-/**
- *
- * Renderers for Wikidot link elements.
- *
- * Wikidot supports several link syntaxes:
- * - `[[[page-name]]]` -- page link with automatic label
- * - `[[[page-name | label]]]` -- page link with custom label
- * - `[# label]` -- anchor-type link (JavaScript void)
- * - `[http://url label]` -- external URL link
- * - `[[a]]...[[/a]]` -- HTML anchor element with attributes
- * - `[[#anchor-name]]` -- named anchor (bookmark target)
- *
- * All link types are checked for dangerous URL schemes. Page links
- * may receive a `class="newpage"` attribute when the target page does
- * not exist (the standard Wikidot "red link" convention). External
- * links opened in new tabs automatically receive `rel="noopener noreferrer"`
- * to prevent tabnabbing.
- *
- * @module
- */
-
-import type { LinkData, AnchorData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, isDangerousUrl, sanitizeAttributes } from "../escape";
-import { renderElements } from "../render";
-
-/**
- * Render a link element (`[[[page]]]`, `[url label]`, `[# label]`).
- *
- * The link's `href` is resolved via `ctx.resolvePageLink()`, with an
- * optional `extra` suffix (anchor fragment) appended. Anchor-type links
- * with `javascript:;` are allowed as a special case for Wikidot
- * compatibility; all other dangerous URL schemes are blocked.
- *
- * For page-type links, a `class="newpage"` is added when the
- * `pageExists` resolver indicates the target page does not exist.
- *
- * @param ctx - The current render context.
- * @param data - Link data with link target, label, type, target window, and extra suffix.
- */
-export function renderLink(ctx: RenderContext, data: LinkData): void {
-  let href = ctx.resolvePageLink(data.link);
-
-  // Append extra (anchor suffix)
-  if (data.extra) {
-    href += data.extra;
-  }
-
-  // Validate URL scheme
-  // Exception: anchor-type links with "javascript:;" are valid Wikidot syntax ([# label])
-  const isAnchorJsVoid = data.type === "anchor" && href === "javascript:;";
-  if (!isAnchorJsVoid && isDangerousUrl(href)) {
-    href = "#invalid-url";
-  }
-
-  // Build <a> tag
-  const attrs: string[] = [`href="${escapeAttr(href)}"`];
-
-  // Add "newpage" class for page links that don't exist
-  // Only for page-type links (not direct URLs, anchors, etc.)
-  if (data.type === "page" && typeof data.link === "object") {
-    const page = data.link.page;
-    // Skip newpage class for special pages:
-    // - //path (protocol-relative or special routing)
-    // - paths with #/ (hash routing like MAIN/#/page)
-    // category-prefixed pages (`category:name`) are NOT skipped — pageExists is
-    // expected to handle them (e.g. share:<ULID>, private:<ULID>, system:Recent).
-    const isSpecialPage = page.startsWith("//") || page.includes("#/");
-    if (!isSpecialPage) {
-      // For anchor links (page#anchor), check if the page part exists
-      const hashIdx = page.indexOf("#");
-      const pageToCheck = hashIdx !== -1 ? page.slice(0, hashIdx) : page;
-      const pageExists = ctx.page?.pageExists;
-      // If pageExists is not provided, assume page doesn't exist (show newpage class)
-      const exists = pageExists ? pageExists(pageToCheck) : false;
-      if (!exists) {
-        attrs.push(`class="newpage"`);
-      }
-    }
-  }
-
-  // Target attribute
-  if (data.target) {
-    const targetMap: Record<string, string> = {
-      "new-tab": "_blank",
-      parent: "_parent",
-      top: "_top",
-      same: "_self",
-    };
-    const targetValue = targetMap[data.target] ?? "_blank";
-    attrs.push(`target="${targetValue}"`);
-    // Prevent tabnabbing for _blank targets
-    if (targetValue === "_blank") {
-      attrs.push(`rel="noopener noreferrer"`);
-    }
-  }
-
-  ctx.push(`<a ${attrs.join(" ")}>`);
-
-  // Render label
-  renderLinkLabel(ctx, data);
-
-  ctx.push("</a>");
-}
-
-/**
- * Render the label content of a link element.
- *
- * Label types:
- * - `"page"` -- use the page name as the label text
- * - `{ text: string }` -- use a custom text label
- * - `{ url: string }` -- use the URL itself as the label
- *
- * @param ctx - The current render context.
- * @param data - Link data containing the label descriptor.
- */
-function renderLinkLabel(ctx: RenderContext, data: LinkData): void {
-  if (data.label === "page") {
-    // Use page name as label
-    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) {
-    // Use the URL itself as label
-    const href = ctx.resolvePageLink(data.link);
-    ctx.pushEscaped(data.label.url ?? href);
-  }
-}
-
-/**
- * Render a `[[a]]...[[/a]]` anchor element with full attribute support.
- *
- * Unlike `renderLink`, this handles the block-level anchor syntax where
- * arbitrary attributes can be specified. Dangerous `href` values are
- * replaced with `#invalid-url`. The `target` attribute is mapped from
- * Wikidot's abstract values to HTML values, with tabnabbing protection.
- *
- * @param ctx - The current render context.
- * @param data - Anchor data with attributes, target, and child elements.
- */
-export function renderAnchor(ctx: RenderContext, data: AnchorData): void {
-  const safe = sanitizeAttributes(data.attributes);
-  const attrs: string[] = [];
-
-  // Validate href for dangerous URLs
-  if (safe.href && isDangerousUrl(safe.href)) {
-    safe.href = "#invalid-url";
-  }
-
-  // Always include href attribute
-  const href = safe.href ?? "";
-  attrs.push(`href="${escapeAttr(href)}"`);
-
-  // Handle target attribute from AST data
-  if (data.target) {
-    const targetMap: Record<string, string> = {
-      "new-tab": "_blank",
-      parent: "_parent",
-      top: "_top",
-      same: "_self",
-    };
-    const targetValue = targetMap[data.target] ?? "_blank";
-    attrs.push(`target="${targetValue}"`);
-    // Prevent tabnabbing for _blank targets
-    if (targetValue === "_blank") {
-      attrs.push(`rel="noopener noreferrer"`);
-    }
-  }
-
-  for (const [key, value] of Object.entries(safe)) {
-    if (key === "href" || key === "target") continue; // already handled above
-    attrs.push(`${key}="${escapeAttr(value)}"`);
-  }
-
-  ctx.push(`<a ${attrs.join(" ")}>`);
-  renderElements(ctx, data.elements);
-  ctx.push("</a>");
-}
-
-/**
- * Render a named anchor (bookmark target) element: `[[#anchor-name]]`.
- *
- * Produces `<a name="anchor-name"></a>` which serves as a link target
- * for `#anchor-name` URL fragments.
- *
- * @param ctx - The current render context.
- * @param name - The anchor name (fragment identifier).
- */
-export function renderAnchorName(ctx: RenderContext, name: string): void {
-  ctx.push(`<a name="${escapeAttr(name)}"></a>`);
-}

package/src/elements/list.ts

@@ -1,241 +0,0 @@
-/**
- *
- * 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).
- *
- * Special behaviors replicated from Wikidot:
- * - Empty lists are silently dropped (no output at all).
- * - Items with `_noMarker` have `list-style: none` and the first
- *   paragraph is unwrapped (no `<p>` tags).
- * - Sub-lists without a preceding content item get an inline hidden `<li>`.
- * - Leading/trailing whitespace-only text nodes are trimmed from items.
- *
- * @module
- */
-
-import type { ListData, DefinitionListItem, Element, ContainerData } from "@wdprlib/ast";
-import type { RenderContext } from "../context";
-import { escapeAttr, sanitizeAttributes } from "../escape";
-import { renderElements, renderElement } from "../render";
-
-/**
- * Trim leading and trailing whitespace-only text elements from an array.
- *
- * @param elements - Array of AST elements.
- * @returns A slice of the array with whitespace-only text nodes removed
- *   from both ends.
- */
-function trimTextElements(elements: Element[]): Element[] {
-  if (elements.length === 0) return elements;
-
-  let start = 0;
-  let end = elements.length;
-
-  // Trim leading whitespace-only text elements
-  while (start < end) {
-    const el = elements[start]!;
-    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
-      start++;
-    } else {
-      break;
-    }
-  }
-
-  // Trim trailing whitespace-only text elements
-  while (end > start) {
-    const el = elements[end - 1]!;
-    if (el.element === "text" && typeof el.data === "string" && el.data.trim() === "") {
-      end--;
-    } else {
-      break;
-    }
-  }
-
-  return elements.slice(start, end);
-}
-
-/**
- * Check whether a paragraph element contains only the text `[[/li]]`.
- *
- * The parser sometimes wraps stray `[[/li]]` closing tags in a paragraph.
- * When found as the last paragraph in a `_noMarker` item, the paragraph
- * wrapper is removed to match Wikidot output.
- *
- * @param el - An AST element to check.
- * @returns `true` if the element is a paragraph containing only `[[/li]]`.
- */
-function isLiCloseTextParagraph(el: Element): boolean {
-  if (el.element !== "container") return false;
-  const data = el.data as ContainerData;
-  if (data.type !== "paragraph") return false;
-  // Check if content is just [[/li]] (possibly with whitespace)
-  const texts = data.elements
-    .filter((e): e is { element: "text"; data: string } => e.element === "text")
-    .map((e) => e.data);
-  const combined = texts.join("").trim();
-  return combined === "[[/li]]";
-}
-
-/**
- * Render elements for `_noMarker` list items with special paragraph handling.
- *
- * Wikidot treats bare content (without `[[li]]`) differently:
- * - The first paragraph is unwrapped (children rendered without `<p>` tags).
- * - Middle paragraphs retain their `<p>` wrappers.
- * - The last paragraph is unwrapped if it contains only `[[/li]]` text.
- *
- * @param ctx - The current render context.
- * @param elements - The list item's child elements.
- */
-function renderNoMarkerElements(ctx: RenderContext, elements: Element[]): void {
-  const trimmed = trimTextElements(elements);
-  if (trimmed.length === 0) return;
-
-  // Find paragraph indices
-  const paragraphIndices: number[] = [];
-  for (let i = 0; i < trimmed.length; i++) {
-    const el = trimmed[i]!;
-    if (el.element === "container" && (el.data as ContainerData).type === "paragraph") {
-      paragraphIndices.push(i);
-    }
-  }
-
-  // If no paragraphs, render normally
-  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 (el.element === "container" && (el.data as ContainerData).type === "paragraph") {
-      const data = el.data as ContainerData;
-      // First paragraph: unwrap
-      if (i === firstParagraphIdx) {
-        renderElements(ctx, data.elements);
-      }
-      // Last paragraph if it's [[/li]]: unwrap
-      else if (i === lastParagraphIdx && isLiCloseTextParagraph(el)) {
-        renderElements(ctx, data.elements);
-      }
-      // Other paragraphs: keep <p> tags
-      else {
-        ctx.push("<p>");
-        renderElements(ctx, data.elements);
-        ctx.push("</p>");
-      }
-    } else {
-      renderElement(ctx, el);
-    }
-  }
-}
-
-/**
- * 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.
- *
- * @param ctx - The current render context.
- * @param data - List data with type (numbered/bulleted), items, and attributes.
- */
-export function renderList(ctx: RenderContext, data: ListData): void {
-  // Wikidot behavior: empty lists or lists with only empty items are ignored
-  // and converted to <br />
-  const hasContent = data.items.some((item) => {
-    if (item["item-type"] === "sub-list") return true;
-    if (item["item-type"] === "elements") {
-      const trimmed = trimTextElements(item.elements);
-      return trimmed.length > 0;
-    }
-    return false;
-  });
-
-  if (!hasContent) {
-    // Empty list - Wikidot outputs nothing (just whitespace)
-    return;
-  }
-
-  const tag = data.type === "numbered" ? "ol" : "ul";
-  ctx.push(`<${tag}${renderListAttrs(data.attributes)}>`);
-
-  const items = data.items;
-  let i = 0;
-  while (i < items.length) {
-    const item = items[i]!;
-    if (item["item-type"] === "elements") {
-      // Check for _noMarker flag (bare content without [[li]])
-      const hasNoMarker = item.attributes._noMarker === "true";
-      const styleAttr = hasNoMarker ? ' style="list-style: none"' : "";
-      ctx.push(`<li${renderListAttrs(item.attributes)}${styleAttr}>`);
-      // Trim leading/trailing whitespace from li content (Wikidot behavior)
-      if (hasNoMarker) {
-        // Special handling for bare content paragraphs
-        renderNoMarkerElements(ctx, item.elements);
-      } else {
-        renderElements(ctx, trimTextElements(item.elements));
-      }
-      // Consume following sub-lists inside this <li>
-      while (i + 1 < items.length && items[i + 1]!["item-type"] === "sub-list") {
-        i++;
-        const subItem = items[i] as { "item-type": "sub-list"; data: ListData };
-        renderList(ctx, subItem.data);
-      }
-      ctx.push("</li>");
-    } else {
-      // Sub-list without preceding elements item - hide bullet/number
-      const subItem = item as { "item-type": "sub-list"; data: ListData };
-      ctx.push(`<li style="list-style: none; display: inline">`);
-      renderList(ctx, subItem.data);
-      ctx.push("</li>");
-    }
-    i++;
-  }
-
-  ctx.push(`</${tag}>`);
-}
-
-/**
- * Sanitize and render list-specific attributes, excluding internal `_`-prefixed keys.
- *
- * @param attributes - Raw attribute map from the AST.
- * @returns An HTML attribute string with leading space, or `""` if empty.
- */
-function renderListAttrs(attributes: Record<string, string>): string {
-  const safe = sanitizeAttributes(attributes);
-  let result = "";
-  for (const [key, value] of Object.entries(safe)) {
-    if (key.startsWith("_")) continue;
-    result += ` ${key}="${escapeAttr(value)}"`;
-  }
-  return result;
-}
-
-/**
- * Render a definition list (`:`-prefixed items in Wikidot markup).
- *
- * Produces `<dl>` with `<dt>`/`<dd>` pairs for each definition item.
- *
- * @param ctx - The current render context.
- * @param items - Array of definition list items, each with key and value elements.
- */
-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>");
-}