@wdprlib/render 2.1.0 → 3.0.1

package/src/libs/highlighter/engine.ts

@@ -1,352 +0,0 @@
-/**
- *
- * Tokenizer and renderer for the Text_Highlighter-compatible syntax
- * highlighting engine. This is a faithful TypeScript port of the
- * PEAR Text_Highlighter 0.5.1 PHP library's `_getToken` algorithm and
- * HTML renderer.
- *
- * The engine processes source code through a state-machine-based tokenizer
- * that assigns CSS class names to each token, then renders the tokens as
- * `<span class="hl-*">` elements.
- *
- * @module
- */
-
-import type { LanguageDefinition } from "./types";
-
-/** A single highlighted token with its CSS class and text content. */
-interface Token {
-  /** CSS class name suffix (used as `hl-{class}`). */
-  class: string;
-  /** The literal text content of this token. */
-  content: string;
-}
-
-/**
- * Tokenize source code using a language definition's state machine.
- *
- * This is a faithful port of PEAR Text_Highlighter's `_getToken` algorithm.
- * The key difference from PHP is that JavaScript lacks `PREG_OFFSET_CAPTURE`,
- * so capture group positions are computed from the match result.
- *
- * The input is preprocessed to normalize line endings, replace tabs with
- * spaces, and ensure empty lines have at least one space character
- * (matching PHP's behavior).
- *
- * @param def - The language definition describing the state machine.
- * @param input - Raw source code string to tokenize.
- * @returns Array of tokens, each with a CSS class and content string.
- */
-export function tokenize(def: LanguageDefinition, input: string): Token[] {
-  // Preprocess: same as PHP Html renderer's preprocess()
-  let str = input.replace(/\r\n/g, "\n");
-  // Replace empty lines with a space (PHP: preg_replace('~^$~m', " ", $str))
-  str = str.replace(/^$/gm, " ");
-  str = str.replace(/\t/g, "    ");
-  // rtrim
-  str = str.replace(/\s+$/, "");
-
-  const len = str.length;
-  if (len === 0) return [];
-
-  let state = -1;
-  let pos = 0;
-  let lastinner = def.defClass;
-  let lastdelim = def.defClass;
-  let endpattern: RegExp | null = null;
-  const stateStack: {
-    state: number;
-    lastdelim: string;
-    lastinner: string;
-    endpattern: RegExp | null;
-  }[] = [];
-  const tokenStack: Token[] = [];
-  const result: Token[] = [];
-
-  function getToken(): Token | null {
-    if (tokenStack.length > 0) {
-      return tokenStack.pop()!;
-    }
-    if (pos >= len) {
-      return null;
-    }
-
-    // Check for end of current state
-    let endpos = -1;
-    let endmatch = "";
-    if (state !== -1 && endpattern) {
-      endpattern.lastIndex = pos;
-      const em = endpattern.exec(str);
-      if (em) {
-        endpos = em.index;
-        endmatch = em[0];
-      }
-    }
-
-    // Try to match patterns for current state
-    const reg = def.regs[state];
-    if (reg) {
-      reg.lastIndex = pos;
-      const m = reg.exec(str);
-
-      if (m) {
-        // Find which pattern (alternative) matched by checking capture groups
-        const countsArr = def.counts[state]!;
-        const statesArr = def.states[state]!;
-        const delimArr = def.delim[state]!;
-        const innerArr = def.inner[state]!;
-        let n = 1;
-        for (let i = 0; i < countsArr.length; i++) {
-          const count = countsArr[i]!;
-          if (n >= m.length) break;
-
-          // PHP: $m[$n][1] > -1 means the group captured something at a valid position
-          // JS: m[n] != null means the group participated in the match (including empty string captures)
-          if (m[n] != null && (endpos === -1 || m.index < endpos)) {
-            const matchStart = m.index;
-            const matchStr = m[n]!;
-
-            // Find actual position of this specific group within the match
-            // For alternation patterns, the matched group starts at m.index
-            // because only one alternative matches at a time
-            const groupStart = findGroupPosition(str, m, n, matchStart);
-
-            if (statesArr[i] !== -1) {
-              // State transition - push delimiter token
-              tokenStack.push({ class: delimArr[i]!, content: matchStr });
-            } else {
-              // Non-transitioning match
-              let inner = innerArr[i]!;
-
-              // Check parts first
-              const partDef = def.parts[state]?.[i];
-              if (partDef) {
-                const parts: Token[] = [];
-                let partpos = groupStart;
-                for (let j = 1; j <= count; j++) {
-                  const subIdx = j + n;
-                  if (subIdx >= m.length || m[subIdx] == null || m[subIdx] === "") continue;
-                  const subStr = m[subIdx]!;
-                  const subStart = str.indexOf(subStr, partpos);
-                  if (subStart < 0) continue;
-                  if (partDef[j]) {
-                    if (subStart > partpos) {
-                      parts.unshift({ class: inner, content: str.substring(partpos, subStart) });
-                    }
-                    parts.unshift({ class: partDef[j]!, content: subStr });
-                  }
-                  partpos = subStart + subStr.length;
-                }
-                if (partpos < groupStart + matchStr.length) {
-                  parts.unshift({
-                    class: inner,
-                    content: str.substring(partpos, groupStart + matchStr.length),
-                  });
-                }
-                tokenStack.push(...parts);
-              } else {
-                // Check keywords (fallback to state -1 if current state has no keyword def)
-                let kwDef = def.keywords[state]?.[i];
-                if (
-                  !kwDef ||
-                  kwDef === -1 ||
-                  typeof kwDef !== "object" ||
-                  Object.keys(kwDef).length === 0
-                ) {
-                  kwDef = def.keywords[-1]?.[i];
-                }
-                if (kwDef && kwDef !== -1 && typeof kwDef === "object") {
-                  for (const [group, re] of Object.entries(kwDef)) {
-                    if ((re as RegExp).test(matchStr)) {
-                      inner = def.kwmap[group] ?? inner;
-                      break;
-                    }
-                  }
-                }
-                tokenStack.push({ class: inner, content: matchStr });
-              }
-            }
-
-            // Emit text before match (pushed after so it pops first)
-            if (groupStart > pos) {
-              tokenStack.push({ class: lastinner, content: str.substring(pos, groupStart) });
-            }
-
-            pos = groupStart + matchStr.length;
-
-            // Handle state transition
-            if (statesArr[i] !== -1) {
-              stateStack.push({ state, lastdelim, lastinner, endpattern });
-              lastinner = innerArr[i]!;
-              lastdelim = delimArr[i]!;
-              const prevState = state;
-              state = statesArr[i]!;
-
-              // Get end pattern for new state
-              const endRe = def.end[state];
-
-              // Handle substitution in end pattern (requires new RegExp)
-              if (def.subst[prevState]?.[i] && endRe) {
-                let epSource = endRe.source;
-                for (let k = 0; k <= count; k++) {
-                  const subIdx = n + k;
-                  if (subIdx >= m.length || m[subIdx] == null) break;
-                  const quoted = escapeRegex(m[subIdx]!);
-                  epSource = epSource.replace(`%${k}%`, quoted);
-                  epSource = epSource.replace(`%b${k}%`, matchingBrackets(quoted));
-                }
-                endpattern = new RegExp(epSource, endRe.flags);
-              } else {
-                // Reuse existing RegExp object (no substitution needed)
-                endpattern = endRe ?? null;
-              }
-            }
-
-            return tokenStack.pop()!;
-          }
-          n += count + 1;
-        }
-      }
-    }
-
-    // Handle end of state
-    if (endpos > -1) {
-      // Always push delimiter token (even for zero-width matches) to match PHP behavior
-      tokenStack.push({ class: lastdelim, content: endmatch });
-      if (endpos > pos) {
-        tokenStack.push({ class: lastinner, content: str.substring(pos, endpos) });
-      }
-      const prev = stateStack.pop()!;
-      state = prev.state;
-      lastdelim = prev.lastdelim;
-      lastinner = prev.lastinner;
-      endpattern = prev.endpattern;
-      pos = endpos + endmatch.length;
-      if (tokenStack.length > 0) {
-        return tokenStack.pop()!;
-      }
-      // Zero-width end pattern with no preceding content: continue to next token
-      return getToken();
-    }
-
-    // No match - consume rest as default class
-    const p = pos;
-    pos = len;
-    return { class: lastinner, content: str.substring(p) };
-  }
-
-  let token: Token | null;
-  while ((token = getToken()) !== null) {
-    result.push(token);
-  }
-
-  return result;
-}
-
-/**
- * Find the actual position of capture group `n` within the source string.
- *
- * For alternation patterns (`a|b|c`), the matched alternative starts at
- * the overall match position (`m.index`). This function locates the
- * capture group's substring within the source, searching from `matchStart`.
- *
- * @param str - The full source string.
- * @param m - The regex match result.
- * @param n - The capture group index.
- * @param matchStart - The starting position of the overall match.
- * @returns The position of the capture group within the source string.
- */
-function findGroupPosition(str: string, m: RegExpExecArray, n: number, matchStart: number): number {
-  // The overall match m[0] starts at m.index
-  // The capture group m[n] is a substring of m[0]
-  // Find where m[n] starts within the string, searching from matchStart
-  const groupStr = m[n]!;
-  const idx = str.indexOf(groupStr, matchStart);
-  return idx >= 0 ? idx : matchStart;
-}
-
-/**
- * Render an array of tokens to HTML with `hl-*` class spans.
- *
- * This is a faithful port of Text_Highlighter's HTML renderer:
- * - Adjacent tokens with the same class are merged into a single `<span>`.
- * - All text is wrapped in spans (no unwrapped text nodes).
- * - The output is wrapped in `<div class="hl-main"><pre>...</pre></div>`.
- *
- * @param tokens - Array of tokens produced by {@link tokenize}.
- * @returns Complete HTML string for the highlighted code block.
- */
-export function renderTokens(tokens: Token[]): string {
-  if (tokens.length === 0) return "";
-
-  let html = "";
-  let lastClass = "";
-
-  for (const token of tokens) {
-    if (token.content.length === 0) continue;
-    const escaped = escapeHtml(token.content);
-    if (token.class !== lastClass) {
-      if (lastClass) {
-        html += "</span>";
-      }
-      html += `<span class="hl-${token.class}">`;
-      lastClass = token.class;
-    }
-    html += escaped;
-  }
-
-  if (lastClass) {
-    html += "</span>";
-  }
-
-  return `<div class="hl-main"><pre>${html}</pre></div>`;
-}
-
-/**
- * Escape HTML special characters for use inside highlighted code spans.
- *
- * @param str - Raw text to escape.
- * @returns HTML-safe string.
- */
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-/**
- * Escape regex special characters in a string for safe use in `new RegExp()`.
- *
- * @param str - Raw string to escape.
- * @returns Regex-safe string.
- */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Swap bracket characters to their matching counterparts.
- *
- * Used for end-pattern substitution where the closing delimiter is the
- * mirror of the opening delimiter (e.g., `<` becomes `>`).
- *
- * @param str - String containing bracket characters.
- * @returns String with each bracket replaced by its counterpart.
- */
-function matchingBrackets(str: string): string {
-  return str.replace(/[()<>[\]{}]/g, (c) => {
-    const map: Record<string, string> = {
-      "(": ")",
-      ")": "(",
-      "<": ">",
-      ">": "<",
-      "[": "]",
-      "]": "[",
-      "{": "}",
-      "}": "{",
-    };
-    return map[c] ?? c;
-  });
-}

package/src/render.ts

@@ -1,231 +0,0 @@
-import type { Element, SyntaxTree } from "@wdprlib/ast";
-import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-import { RenderContext } from "./context";
-import { escapeStyleContent } from "./escape";
-import type { RenderOptions } from "./types";
-import { renderContainer } from "./elements/container";
-import { renderText, renderRaw, renderEmail } from "./elements/text";
-import { renderLink, renderAnchor, renderAnchorName } from "./elements/link";
-import { renderImage } from "./elements/image";
-import { renderList, renderDefinitionList } from "./elements/list";
-import { renderTable } from "./elements/table";
-import { renderCollapsible } from "./elements/collapsible";
-import { renderCode } from "./elements/code";
-import { renderTabView } from "./elements/tab-view";
-import { renderFootnoteRef, renderFootnoteBlock } from "./elements/footnote";
-import { renderMath, renderMathInline, renderEquationRef } from "./elements/math";
-import { renderModule } from "./elements/module/index";
-import { renderEmbed } from "./elements/embed";
-import { renderEmbedBlock } from "./elements/embed-block";
-import { renderUser } from "./elements/user";
-import { renderBibliographyCite, renderBibliographyBlock } from "./elements/bibliography";
-import { renderTableOfContents } from "./elements/toc";
-import { renderLineBreaks } from "./elements/line-break";
-import { renderClearFloat } from "./elements/clear-float";
-import { renderIframe } from "./elements/iframe";
-import { renderHtmlBlock } from "./elements/html";
-import { renderInclude } from "./elements/include";
-import { renderIfTags } from "./elements/iftags";
-import { renderColor } from "./elements/color";
-import { renderDate } from "./elements/date";
-import { renderExpr, renderIf, renderIfExpr } from "./elements/expr";
-
-/**
- * Render a {@link SyntaxTree} to an HTML string.
- *
- * This is the main entry point of `@wdprlib/render`. It walks the AST
- * produced by `@wdprlib/parser`, serialises each element to HTML, and
- * appends any collected `[[module CSS]]` styles at the end (when
- * `WikitextSettings.allowStyleElements` is `true`).
- *
- * @param tree - Parsed AST (from `parse()` or `resolveModules()`)
- * @param options - Rendering configuration
- * @returns Complete HTML string
- *
- * @group Render
- */
-export function renderToHtml(tree: SyntaxTree, options: RenderOptions = {}): string {
-  const ctx = new RenderContext(tree, options);
-  renderElements(ctx, tree.elements);
-
-  // Append styles (with tag breakout prevention).
-  // Sentinel entries (STYLE_SLOT_PREFIX) mark positions where unresolved
-  // iftags styles should be spliced in, preserving source order.
-  if (ctx.settings.allowStyleElements && tree.styles?.length) {
-    for (const style of tree.styles) {
-      if (style.startsWith(STYLE_SLOT_PREFIX)) {
-        const slotId = parseInt(style.slice(STYLE_SLOT_PREFIX.length), 10);
-        for (const css of ctx.getStyleSlotContents(slotId)) {
-          ctx.push(`<style>${escapeStyleContent(css)}</style>`);
-        }
-      } else {
-        ctx.push(`<style>${escapeStyleContent(style)}</style>`);
-      }
-    }
-  }
-
-  return ctx.getOutput();
-}
-
-/**
- * Render a list of sibling AST elements in document order.
- *
- * Used internally by container renderers that need to emit their
- * children. Not exported from the package barrel — call
- * {@link renderToHtml} instead for top-level rendering.
- */
-export function renderElements(ctx: RenderContext, elements: Element[]): void {
-  for (const element of elements) {
-    renderElement(ctx, element);
-  }
-}
-
-/**
- * Dispatch a single AST element to its type-specific renderer.
- *
- * The switch covers every `ElementName` value defined by
- * `@wdprlib/ast`. Unknown element types are silently ignored.
- */
-export function renderElement(ctx: RenderContext, element: Element): void {
-  switch (element.element) {
-    case "text":
-      ctx.pushEscaped(element.data);
-      break;
-    case "raw":
-      renderRaw(ctx, element.data);
-      break;
-    case "variable":
-      renderText(ctx, element.data);
-      break;
-    case "email":
-      renderEmail(ctx, element.data);
-      break;
-    case "container":
-      renderContainer(ctx, element.data);
-      break;
-    case "link":
-      renderLink(ctx, element.data);
-      break;
-    case "anchor":
-      renderAnchor(ctx, element.data);
-      break;
-    case "anchor-name":
-      renderAnchorName(ctx, element.data);
-      break;
-    case "image":
-      renderImage(ctx, element.data);
-      break;
-    case "list":
-      renderList(ctx, element.data);
-      break;
-    case "definition-list":
-      renderDefinitionList(ctx, element.data);
-      break;
-    case "table":
-      renderTable(ctx, element.data);
-      break;
-    case "collapsible":
-      renderCollapsible(ctx, element.data);
-      break;
-    case "code":
-      renderCode(ctx, element.data);
-      break;
-    case "tab-view":
-      renderTabView(ctx, element.data);
-      break;
-    case "footnote":
-      renderFootnoteRef(ctx, ctx.nextFootnoteIndex() + 1);
-      break;
-    case "footnote-ref":
-      renderFootnoteRef(ctx, element.data);
-      break;
-    case "footnote-block":
-      renderFootnoteBlock(ctx, element.data);
-      break;
-    case "bibliography-cite":
-      renderBibliographyCite(ctx, element.data);
-      break;
-    case "bibliography-block":
-      renderBibliographyBlock(ctx, element.data, renderElements);
-      break;
-    case "table-of-contents":
-      renderTableOfContents(ctx, element.data);
-      break;
-    case "math":
-      renderMath(ctx, element.data);
-      break;
-    case "math-inline":
-      renderMathInline(ctx, element.data);
-      break;
-    case "module":
-      renderModule(ctx, element.data);
-      break;
-    case "embed":
-      renderEmbed(ctx, element.data);
-      break;
-    case "embed-block":
-      renderEmbedBlock(ctx, element.data);
-      break;
-    case "user":
-      renderUser(ctx, element.data);
-      break;
-    case "date":
-      renderDate(ctx, element.data);
-      break;
-    case "color":
-      renderColor(ctx, element.data);
-      break;
-    case "html":
-      renderHtmlBlock(ctx, element.data);
-      break;
-    case "iframe":
-      renderIframe(ctx, element.data);
-      break;
-    case "include":
-      renderInclude(ctx, element.data);
-      break;
-    case "if-tags":
-      renderIfTags(ctx, element.data);
-      break;
-    case "style":
-      // Styles are collected into tree.styles during resolve and rendered
-      // at the end of renderToHtml. Style elements remaining in the AST
-      // (inside unresolved iftags) are either collected into a style slot
-      // (preserving source order) or rendered inline as a fallback.
-      if (ctx.renderInlineStyles && ctx.settings.allowStyleElements) {
-        if (ctx.hasActiveStyleSlot()) {
-          ctx.pushToStyleSlot(element.data);
-        } else {
-          ctx.push(`<style>${escapeStyleContent(element.data)}</style>`);
-        }
-      }
-      break;
-    case "line-break":
-      ctx.push("<br />");
-      break;
-    case "line-breaks":
-      renderLineBreaks(ctx, element.data);
-      break;
-    case "clear-float":
-      renderClearFloat(ctx, element.data);
-      break;
-    case "horizontal-rule":
-      ctx.push("<hr />");
-      break;
-    case "content-separator":
-      ctx.push(`<div class="content-separator" style="display: none:"></div>`);
-      break;
-    case "expr":
-      renderExpr(ctx, element.data);
-      break;
-    case "if":
-      renderIf(ctx, element.data);
-      break;
-    case "ifexpr":
-      renderIfExpr(ctx, element.data);
-      break;
-    case "equation-reference":
-      renderEquationRef(ctx, element.data);
-      break;
-  }
-}