@wdprlib/render 2.0.0 → 2.1.0

package/src/libs/highlighter/languages/sql.ts

@@ -0,0 +1,125 @@
+import type { LanguageDefinition } from "../types";
+
+export const sqlLang: LanguageDefinition = {
+  language: "sql",
+  defClass: "code",
+  regs: {
+    [-1]: /(`)|(\/\*)|((#|--\s).*)|([a-z_]\w*)|(")|(\()|(')|(((\d+|((\d*\.\d+)|(\d+\.\d*)))[eE][+-]?\d+))|((\d*\.\d+)|(\d+\.\d*))|(\d+l?|\b0l?\b)|(0[xX][\da-f]+l?)/gi,
+    0: null,
+    1: null,
+    2: /(\\.)/gi,
+    3: /(`)|(\/\*)|((#|--\s).*)|([a-z_]\w*)|(")|(\()|(')|(((\d+|((\d*\.\d+)|(\d+\.\d*)))[eE][+-]?\d+))|((\d*\.\d+)|(\d+\.\d*))|(\d+l?|\b0l?\b)|(0[xX][\da-f]+l?)/gi,
+    4: /(\\.)/gi,
+  },
+  counts: {
+    [-1]: [0, 0, 1, 0, 0, 0, 0, 5, 2, 0, 0],
+    0: [],
+    1: [],
+    2: [0],
+    3: [0, 0, 1, 0, 0, 0, 0, 5, 2, 0, 0],
+    4: [0],
+  },
+  delim: {
+    [-1]: ["quotes", "comment", "", "", "quotes", "brackets", "quotes", "", "", "", ""],
+    0: [],
+    1: [],
+    2: [""],
+    3: ["quotes", "comment", "", "", "quotes", "brackets", "quotes", "", "", "", ""],
+    4: [""],
+  },
+  inner: {
+    [-1]: [
+      "identifier",
+      "comment",
+      "comment",
+      "identifier",
+      "string",
+      "code",
+      "string",
+      "number",
+      "number",
+      "number",
+      "number",
+    ],
+    0: [],
+    1: [],
+    2: ["special"],
+    3: [
+      "identifier",
+      "comment",
+      "comment",
+      "identifier",
+      "string",
+      "code",
+      "string",
+      "number",
+      "number",
+      "number",
+      "number",
+    ],
+    4: ["special"],
+  },
+  end: {
+    0: /`/gi,
+    1: /\*\//gi,
+    2: /"/gi,
+    3: /\)/gi,
+    4: /'/gi,
+  },
+  states: {
+    [-1]: [0, 1, -1, -1, 2, 3, 4, -1, -1, -1, -1],
+    0: [],
+    1: [],
+    2: [-1],
+    3: [0, 1, -1, -1, 2, 3, 4, -1, -1, -1, -1],
+    4: [-1],
+  },
+  keywords: {
+    [-1]: [
+      -1,
+      -1,
+      {},
+      {
+        reserved:
+          /^(absolute|action|add|admin|after|aggregate|alias|all|allocate|alter|and|any|are|array|as|asc|assertion|at|authorization|before|begin|binary|bit|blob|boolean|both|breadth|by|call|cascade|cascaded|case|cast|catalog|char|character|check|class|clob|close|collate|collation|column|commit|completion|connect|connection|constraint|constraints|constructor|continue|corresponding|create|cross|cube|current|current_date|current_path|current_role|current_time|current_timestamp|current_user|cursor|cycle|data|date|day|deallocate|dec|decimal|declare|default|deferrable|deferred|delete|depth|deref|desc|describe|descriptor|destroy|destructor|deterministic|diagnostics|dictionary|disconnect|distinct|domain|double|drop|dynamic|each|else|end|end-exec|equals|escape|every|except|exception|exec|execute|external|false|fetch|first|float|for|foreign|found|free|from|full|function|general|get|global|go|goto|grant|group|grouping|having|host|hour|identity|ignore|immediate|in|indicator|initialize|initially|inner|inout|input|insert|int|integer|intersect|interval|into|is|isolation|iterate|join|key|language|large|last|lateral|leading|left|less|level|like|limit|local|localtime|localtimestamp|locator|map|match|minute|modifies|modify|module|month|names|national|natural|nchar|nclob|new|next|no|none|not|null|numeric|object|of|off|old|on|only|open|operation|option|or|order|ordinality|out|outer|output|pad|parameter|parameters|partial|path|postfix|precision|prefix|preorder|prepare|preserve|primary|prior|privileges|procedure|public|read|reads|real|recursive|ref|references|referencing|relative|restrict|result|return|returns|revoke|right|role|rollback|rollup|routine|row|rows|savepoint|schema|scope|scroll|search|second|section|select|sequence|session|session_user|set|sets|size|smallint|some|space|specific|specifictype|sql|sqlexception|sqlstate|sqlwarning|start|state|statement|static|structure|system_user|table|temporary|terminate|than|then|time|timestamp|timezone_hour|timezone_minute|to|trailing|transaction|translation|treat|trigger|true|under|union|unique|unknown|unnest|update|usage|user|using|value|values|varchar|variable|varying|view|when|whenever|where|with|without|work|write|year|zone)$/i,
+        keyword:
+          /^(abs|ada|asensitive|assignment|asymmetric|atomic|avg|between|bitvar|bit_length|c|called|cardinality|catalog_name|chain|character_length|character_set_catalog|character_set_name|character_set_schema|char_length|checked|class_origin|coalesce|cobol|collation_catalog|collation_name|collation_schema|column_name|command_function|command_function_code|committed|condition_number|connection_name|constraint_catalog|constraint_name|constraint_schema|contains|convert|count|cursor_name|datetime_interval_code|datetime_interval_precision|defined|definer|dispatch|dynamic_function|dynamic_function_code|existing|exists|extract|final|fortran|g|generated|granted|hierarchy|hold|implementation|infix|insensitive|instance|instantiable|invoker|k|key_member|key_type|length|lower|m|max|message_length|message_octet_length|message_text|method|min|mod|more|mumps|name|nullable|nullif|number|octet_length|options|overlaps|overlay|overriding|parameter_mode|parameter_name|parameter_ordinal_position|parameter_specific_catalog|parameter_specific_name|parameter_specific_schema|pascal|pli|position|repeatable|returned_length|returned_octet_length|returned_sqlstate|routine_catalog|routine_name|routine_schema|row_count|scale|schema_name|security|self|sensitive|serializable|server_name|similar|simple|source|specific_name|style|subclass_origin|sublist|substring|sum|symmetric|system|table_name|transactions_committed|transactions_rolled_back|transaction_active|transform|transforms|translate|trigger_catalog|trigger_name|trigger_schema|trim|type|uncommitted|unnamed|upper|user_defined_type_catalog|user_defined_type_name|user_defined_type_schema)$/i,
+      },
+      -1,
+      -1,
+      -1,
+      {},
+      {},
+      {},
+      {},
+    ],
+    0: [],
+    1: [],
+    2: [],
+    3: [],
+    4: [{}],
+    7: [],
+    8: [],
+    9: [],
+    10: [],
+  },
+  kwmap: {
+    reserved: "reserved",
+    keyword: "var",
+  },
+  parts: {
+    0: [],
+    1: [],
+    2: [null],
+    3: [null, null, null, null, null, null, null, null, null, null, null],
+    4: [null],
+  },
+  subst: {
+    [-1]: [false, false, false, false, false, false, false, false, false, false, false],
+    0: [],
+    1: [],
+    2: [false],
+    3: [false, false, false, false, false, false, false, false, false, false, false],
+    4: [false],
+  },
+};

package/src/libs/highlighter/languages/xml.ts

@@ -0,0 +1,68 @@
+import type { LanguageDefinition } from "../types";
+
+export const xmlLang: LanguageDefinition = {
+  language: "xml",
+  defClass: "code",
+  regs: {
+    [-1]: /(<!\[CDATA\[)|(<!--)|(<[?/]?)|((&|%)[\w\-.]+;)/gi,
+    0: null,
+    1: null,
+    2: /((?<=[</?])[\w\-:]+)|([\w\-:]+)|(")/gi,
+    3: /((&|%)[\w\-.]+;)/gi,
+  },
+  counts: {
+    [-1]: [0, 0, 0, 1],
+    0: [],
+    1: [],
+    2: [0, 0, 0],
+    3: [1],
+  },
+  delim: {
+    [-1]: ["comment", "comment", "brackets", ""],
+    0: [],
+    1: [],
+    2: ["", "", "quotes"],
+    3: [""],
+  },
+  inner: {
+    [-1]: ["comment", "comment", "code", "special"],
+    0: [],
+    1: [],
+    2: ["reserved", "var", "string"],
+    3: ["special"],
+  },
+  end: {
+    0: /\]\]>/gi,
+    1: /-->/gi,
+    2: /[/?]?>/gi,
+    3: /"/gi,
+  },
+  states: {
+    [-1]: [0, 1, 2, -1],
+    0: [],
+    1: [],
+    2: [-1, -1, 3],
+    3: [-1],
+  },
+  keywords: {
+    [-1]: [-1, -1, -1, {}],
+    0: [],
+    1: [],
+    2: [{}, {}, -1],
+    3: [{}],
+  },
+  kwmap: {},
+  parts: {
+    0: [],
+    1: [],
+    2: [null, null, null],
+    3: [null],
+  },
+  subst: {
+    [-1]: [false, false, false, false],
+    0: [],
+    1: [],
+    2: [false, false, false],
+    3: [false],
+  },
+};

package/src/libs/highlighter/types.ts

@@ -0,0 +1,44 @@
+/**
+ *
+ * Type definitions for the Text_Highlighter-compatible syntax highlighting
+ * engine. These interfaces mirror the data structures used by the original
+ * PEAR Text_Highlighter PHP library, adapted for TypeScript.
+ *
+ * @module
+ */
+
+/**
+ * Complete language definition for the Text_Highlighter-compatible engine.
+ *
+ * Each language definition describes a state machine where:
+ * - States are identified by numeric IDs (-1 for the root state).
+ * - Each state has a combined regex pattern that matches tokens.
+ * - Matched tokens may trigger state transitions (e.g., entering a string literal).
+ * - Keywords within certain states are highlighted with special CSS classes.
+ */
+export interface LanguageDefinition {
+  /** Language name */
+  language: string;
+  /** Default CSS class for unmatched text */
+  defClass: string;
+  /** Regex patterns per state: state → combined regex (null = no pattern for this state) */
+  regs: Record<number, RegExp | null>;
+  /** Number of capture groups per pattern per state */
+  counts: Record<number, number[]>;
+  /** Delimiter classes per state per pattern */
+  delim: Record<number, string[]>;
+  /** Inner (token) classes per state per pattern */
+  inner: Record<number, string[]>;
+  /** End patterns per state (regex that ends the state, null = no end pattern) */
+  end: Record<number, RegExp | null>;
+  /** State transitions: state → pattern_index → next_state (-1 = no transition) */
+  states: Record<number, number[]>;
+  /** Keywords: state → pattern_index → {group_name: regex} */
+  keywords: Record<number, (Record<string, RegExp> | -1)[]>;
+  /** Keyword group → CSS class mapping */
+  kwmap: Record<string, string>;
+  /** Parts: state → pattern_index → {subgroup: class} | null */
+  parts: Record<number, (Record<number, string> | null)[]>;
+  /** Substitution flags */
+  subst: Record<number, boolean[]>;
+}

package/src/render.ts

@@ -0,0 +1,231 @@
+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;
+  }
+}

package/src/types.ts

@@ -0,0 +1,140 @@
+import type { Element, WikitextSettings } from "@wdprlib/ast";
+import type { EmbedAllowlistEntry } from "./elements/embed-block";
+
+/**
+ * Contextual information about the wiki page being rendered.
+ *
+ * The renderer uses this to resolve relative links, local file paths,
+ * page-existence checks (adding a `"newpage"` CSS class to links
+ * targeting non-existent pages), and `[[iftags]]` evaluation.
+ *
+ * @group Render Options
+ */
+export interface PageContext {
+  /** Full page name including category prefix (e.g. `"secret:test2"`) */
+  pageName: string;
+  /** Site slug used to build inter-site URLs (e.g. `"scp-wiki"`) */
+  site?: string;
+  /** Site domain used for absolute URL generation (e.g. `"scp-wiki.wikidot.com"`) */
+  domain?: string;
+  /**
+   * Returns whether a page exists on the site.
+   * When a target page does not exist, the renderer adds `class="newpage"`
+   * to the link element — the standard Wikidot convention for red-links.
+   */
+  pageExists?: (page: string) => boolean;
+  /** Page tags used for client-side `[[iftags]]` evaluation during rendering */
+  tags?: string[];
+}
+
+/**
+ * User profile data returned by a user-resolver callback.
+ *
+ * Passed to the renderer to produce the Wikidot user-info markup
+ * (`[[user username]]`). When a field is omitted the corresponding
+ * UI element is simply not emitted.
+ *
+ * @group Render Options
+ */
+export interface ResolvedUser {
+  /** Display name shown in the rendered output (falls back to the raw username) */
+  name?: string;
+  /** Profile URL. When omitted the username is rendered as a non-navigable `<span>` */
+  url?: string;
+  /** Avatar image URL. When omitted no avatar `<img>` is rendered */
+  avatarUrl?: string;
+  /** Karma-badge image URL shown behind the avatar (Wikidot-specific feature) */
+  karmaUrl?: string;
+}
+
+/**
+ * Async/sync resolver callbacks for content that depends on external data.
+ *
+ * Unlike the parser's `DataProvider` (which fetches bulk data for
+ * module expansion), these resolvers are called per-element during the
+ * rendering pass.
+ *
+ * @group Render Options
+ */
+export interface RenderResolvers {
+  /**
+   * Look up a user profile by username.
+   *
+   * @param username - The raw username from `[[user username]]`
+   * @returns Profile data for rendering, or `null` if the user is unknown.
+   *          When `null` or when the resolver is omitted, the username is
+   *          rendered as plain text.
+   */
+  user?: (username: string) => ResolvedUser | null;
+
+  /**
+   * Build an iframe `src` URL for an `[[html]]` block.
+   *
+   * @param index - Zero-based index matching `SyntaxTree["html-blocks"]`
+   * @returns The URL string. When empty or when the resolver is omitted,
+   *          the default pattern `/{pageName}/html/{hash}-{nonce}` is used.
+   *
+   * @security The returned URL is injected directly into the iframe `src`
+   * attribute. The caller must validate the scheme to reject `javascript:`,
+   * `data:`, and other dangerous protocols.
+   */
+  htmlBlockUrl?: (index: number) => string;
+}
+
+/**
+ * Full configuration for `renderToHtml()`.
+ *
+ * Every field is optional; defaults produce safe, standalone HTML output
+ * suitable for a full wiki page.
+ *
+ * @group Render Options
+ */
+export interface RenderOptions {
+  /**
+   * Base URL for resolving protocol-relative URLs (e.g. `"//example.com/path"`).
+   *
+   * The scheme of this URL (`http:` or `https:`) is prepended to
+   * protocol-relative references. When omitted, HTTPS is assumed.
+   *
+   * @example "https://scp-wiki.wikidot.com"
+   */
+  baseUrl?: string;
+
+  /**
+   * Context-dependent feature flags.
+   * Defaults to page-mode settings when omitted.
+   */
+  settings?: WikitextSettings;
+
+  /** Page context for resolving relative links, local file paths, etc. */
+  page?: PageContext;
+
+  /**
+   * Pre-collected footnote element arrays from `SyntaxTree.footnotes`.
+   * Passed through so the renderer can emit footnote bodies in the
+   * `[[footnoteblock]]` section.
+   */
+  footnotes?: Element[][];
+
+  /** Callbacks for resolving users, HTML-block URLs, etc. */
+  resolvers?: RenderResolvers;
+  /**
+   * Sandbox attribute value for htmlBlock iframes.
+   * - undefined/null: No sandbox attribute (Wikidot compatible, scripts can run)
+   * - string: Use as sandbox attribute value (e.g., "allow-scripts allow-same-origin")
+   *
+   * Examples:
+   * - No sandbox (Wikidot compatible): htmlBlockSandbox: null
+   * - Block scripts: htmlBlockSandbox: "allow-same-origin"
+   * - Allow scripts: htmlBlockSandbox: "allow-scripts allow-same-origin"
+   */
+  htmlBlockSandbox?: string | null;
+  /**
+   * Allowlist for [[embed]] content with host and optional path validation.
+   * - undefined: Uses default allowlist (YouTube, Vimeo, etc. with path restrictions)
+   * - EmbedAllowlistEntry[]: Custom allowlist with host patterns and optional path prefixes
+   * - []: Block all embeds
+   * - null: Allow any HTTPS iframe (Wikidot's 'anyiframe' behavior)
+   */
+  embedAllowlist?: EmbedAllowlistEntry[] | null;
+}