mardora 1.2.0

package/src/preview/context.ts

@@ -0,0 +1,45 @@
+import { SyntaxNode } from "@lezer/common";
+import { Highlighter } from "@lezer/highlight";
+import { ThemeEnum } from "../editor/utils";
+import { PreviewContext } from "./types";
+import DOMPurify from "dompurify";
+
+/**
+ * Creates a PreviewContext for rendering
+ */
+export function createPreviewContext(
+  doc: string,
+  theme: ThemeEnum,
+  renderChildren: (node: SyntaxNode) => Promise<string>,
+  sanitizeHtml: boolean = true,
+  syntaxHighlighters: readonly Highlighter[] = [],
+  headingIdForNode?: (node: SyntaxNode) => string | null
+): PreviewContext {
+  const context: PreviewContext = {
+    doc,
+    theme,
+    syntaxHighlighters,
+
+    sliceDoc(from: number, to: number): string {
+      return doc.slice(from, to);
+    },
+
+    sanitize(html: string): string {
+      if (!sanitizeHtml) return html;
+
+      // DOMPurify works in browser; in Node, it needs jsdom
+      if (typeof window !== "undefined") {
+        return DOMPurify.sanitize(html);
+      }
+
+      // Server-side: return as-is (user should sanitize at application level)
+      // or use isomorphic-dompurify in their setup
+      return html;
+    },
+
+    renderChildren,
+  };
+
+  if (headingIdForNode) context.headingIdForNode = headingIdForNode;
+  return context;
+}

package/src/preview/css-generator.ts

@@ -0,0 +1,64 @@
+import { ThemeEnum } from "../editor/utils";
+import { GenerateCSSConfig } from "./types";
+import { generateSyntaxThemeCSS } from "./syntax-theme";
+
+/**
+ * Base CSS styles for preview rendering
+ */
+const baseStyles = `.mardora-preview {
+  padding: 0 0.5rem;
+}`;
+
+/**
+ * Generate CSS for preview rendering
+ *
+ * @param config - CSS generation configuration
+ * @returns CSS string
+ *
+ * @example
+ * ```ts
+ * import { generateCSS } from 'mardora/preview';
+ * import { HeadingPlugin, ListPlugin } from 'mardora/plugins';
+ *
+ * const css = generateCSS({
+ *   plugins: [new HeadingPlugin(), new ListPlugin()],
+ *   theme: ThemeEnum.AUTO,
+ *   includeBase: true,
+ * });
+ * ```
+ */
+export function generateCSS(config: GenerateCSSConfig = {}): string {
+  const {
+    plugins = [],
+    theme = ThemeEnum.AUTO,
+    wrapperClass = "mardora-preview",
+    includeBase = true,
+    syntaxTheme,
+  } = config;
+
+  const cssChunks: string[] = [];
+
+  // Include base styles
+  if (includeBase) {
+    // Replace default wrapper class if custom one is provided
+    if (wrapperClass !== "mardora-preview") {
+      cssChunks.push(baseStyles.replace(/\.mardora-preview/g, `.${wrapperClass}`));
+    } else {
+      cssChunks.push(baseStyles);
+    }
+  }
+
+  // Collect syntax highlight styles (`tok-*` classes) from CodeMirror theme/extensions
+  const syntaxCSS = generateSyntaxThemeCSS(syntaxTheme, wrapperClass);
+  if (syntaxCSS) {
+    cssChunks.push("/* syntax-theme */\n" + syntaxCSS);
+  }
+
+  // Collect styles from plugins
+  for (const plugin of plugins) {
+    const pluginCSS = plugin.getPreviewStyles(theme, wrapperClass);
+    if (pluginCSS) cssChunks.push(`/* ${plugin.name} - ${plugin.version} */\n` + pluginCSS);
+  }
+
+  return cssChunks.join("\n\n");
+}

package/src/preview/default-renderers.ts

@@ -0,0 +1,29 @@
+import { NodeRenderer, NodeRendererMap } from "./types";
+
+/**
+ * Escape HTML special characters
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+// ============================================
+// DEFAULT RENDERERS
+// ============================================
+
+const renderDocument: NodeRenderer = (_node, children) => {
+  return children;
+};
+
+/**
+ * Default node renderers for all markdown node types
+ */
+export const defaultRenderers: NodeRendererMap = {
+  // Document structure
+  Document: renderDocument,
+};

package/src/preview/index.ts

@@ -0,0 +1,29 @@
+/**
+ * mardora/preview - Static HTML rendering for markdown
+ *
+ * @packageDocumentation
+ */
+
+// Main preview function
+export { preview } from "./preview";
+
+// CSS generation
+export { generateCSS } from "./css-generator";
+export { generateSyntaxThemeCSS } from "./syntax-theme";
+export { extractPreviewTocFromMarkdown } from "./toc";
+
+// Types
+export type {
+  PreviewConfig,
+  PreviewContext,
+  GenerateCSSConfig,
+  SyntaxThemeInput,
+  NodeRenderer,
+  NodeRendererMap,
+} from "./types";
+
+// Utilities
+export { escapeHtml, defaultRenderers } from "./default-renderers";
+
+// Renderer class (for advanced usage)
+export { PreviewRenderer } from "./renderer";

package/src/preview/preview.ts

@@ -0,0 +1,41 @@
+import { ThemeEnum } from "../editor/utils";
+import { PreviewRenderer } from "./renderer";
+import { PreviewConfig } from "./types";
+
+/**
+ * Render markdown to semantic HTML
+ *
+ * @param markdown - Markdown string to render
+ * @param config - Preview configuration
+ * @returns HTML string
+ *
+ * @example
+ * ```ts
+ * import { preview } from 'mardora/preview';
+ * import { HeadingPlugin, ListPlugin } from 'mardora/plugins';
+ *
+ * const html = preview('# Hello World', {
+ *   plugins: [new HeadingPlugin(), new ListPlugin()],
+ *   wrapperClass: 'mardora-preview',
+ * });
+ * ```
+ */
+export async function preview(markdown: string, config: PreviewConfig = {}): Promise<string> {
+  const {
+    plugins = [],
+    markdown: markdownConfig = [],
+    wrapperClass = "mardora-preview",
+    wrapperTag = "article",
+    sanitize = true,
+    theme = ThemeEnum.AUTO,
+    syntaxTheme,
+  } = config;
+
+  // Create renderer and generate HTML
+  const renderer = new PreviewRenderer(markdown, plugins, markdownConfig, theme, sanitize, syntaxTheme);
+  const content = await renderer.render();
+
+  // Wrap in container
+  const classAttr = wrapperClass ? ` class="${wrapperClass}"` : "";
+  return `<${wrapperTag}${classAttr}>\n${content}</${wrapperTag}>`;
+}

package/src/preview/renderer.ts

@@ -0,0 +1,184 @@
+import { SyntaxNode } from "@lezer/common";
+import { markdown, markdownLanguage } from "@codemirror/lang-markdown";
+import { EditorState } from "@codemirror/state";
+import { MarkdownConfig } from "@lezer/markdown";
+import { languages } from "@codemirror/language-data";
+
+import { MardoraPlugin } from "../editor/plugin";
+import { extractTocItemsFromState } from "../editor/table-of-contents";
+import { ThemeEnum } from "../editor/utils";
+import { createPreviewContext } from "./context";
+import { defaultRenderers, escapeHtml } from "./default-renderers";
+import { resolveSyntaxHighlighters } from "./syntax-theme";
+import { NodeRendererMap, PreviewContext } from "./types";
+
+/**
+ * Renderer class that walks the syntax tree and produces HTML
+ */
+export class PreviewRenderer {
+  private doc: string;
+  private theme: ThemeEnum;
+  private plugins: MardoraPlugin[];
+  private markdown: MarkdownConfig[];
+  private sanitizeHtml: boolean;
+  private syntaxTheme: import("./types").SyntaxThemeInput | import("./types").SyntaxThemeInput[] | undefined;
+  private renderers: NodeRendererMap;
+  private ctx: PreviewContext;
+  private nodeToPlugins: Map<string, MardoraPlugin[]>;
+
+  constructor(
+    doc: string,
+    plugins: MardoraPlugin[] = [],
+    markdown: MarkdownConfig[],
+    theme: ThemeEnum = ThemeEnum.AUTO,
+    sanitize: boolean = true,
+    syntaxTheme?: import("./types").SyntaxThemeInput | import("./types").SyntaxThemeInput[]
+  ) {
+    this.doc = doc;
+    this.theme = theme;
+    this.plugins = plugins;
+    this.markdown = markdown;
+    this.sanitizeHtml = sanitize;
+    this.syntaxTheme = syntaxTheme;
+    this.renderers = { ...defaultRenderers };
+
+    const syntaxHighlighters = resolveSyntaxHighlighters(this.syntaxTheme, true);
+
+    // Create context with reference to renderChildren
+    this.ctx = createPreviewContext(doc, theme, this.renderChildren.bind(this), sanitize, syntaxHighlighters);
+
+    // Build node-to-plugin map for O(1) lookup
+    this.nodeToPlugins = this.buildNodePluginMap();
+  }
+
+  /**
+   * Build a map from node names to plugins that handle them
+   */
+  private buildNodePluginMap(): Map<string, MardoraPlugin[]> {
+    const map = new Map<string, MardoraPlugin[]>();
+    for (const plugin of this.plugins) {
+      if (plugin.renderToHTML && plugin.requiredNodes.length > 0) {
+        for (const nodeName of plugin.requiredNodes) {
+          const list = map.get(nodeName) || [];
+          list.push(plugin);
+          map.set(nodeName, list);
+        }
+      }
+    }
+    return map;
+  }
+
+  /**
+   * Render the document to HTML
+   */
+  async render(): Promise<string> {
+    // Collect markdown extensions from plugins
+    const extensions = [
+      ...this.markdown,
+      ...this.plugins.map((p) => p.getMarkdownConfig()).filter((ext): ext is NonNullable<typeof ext> => ext !== null),
+    ];
+
+    // Build parser through @codemirror/lang-markdown to match editor behavior exactly
+    const markdownSupport = markdown({
+      base: markdownLanguage,
+      codeLanguages: languages,
+      extensions,
+      addKeymap: true,
+      completeHTMLTags: true,
+      pasteURLAsLink: true,
+    });
+    const parser = markdownSupport.language.parser;
+
+    // Parse the document
+    const tree = parser.parse(this.doc);
+    const state = EditorState.create({
+      doc: this.doc,
+      extensions: [markdownSupport],
+    });
+    const tocItems = extractTocItemsFromState(state);
+    const headingIds = new Map(tocItems.map((item) => [`${item.from}:${item.to}`, item.id]));
+    const syntaxHighlighters = resolveSyntaxHighlighters(this.syntaxTheme, true);
+
+    this.ctx = createPreviewContext(
+      this.doc,
+      this.theme,
+      this.renderChildren.bind(this),
+      this.sanitizeHtml,
+      syntaxHighlighters,
+      (node) => headingIds.get(`${node.from}:${node.to}`) ?? null
+    );
+
+    // Render from root
+    return await this.renderNode(tree.topNode);
+  }
+
+  /**
+   * Render a single node to HTML
+   */
+  private async renderNode(node: SyntaxNode): Promise<string> {
+    return (await this.renderNodeWithExtent(node)).html;
+  }
+
+  private async renderNodeWithExtent(node: SyntaxNode): Promise<{ html: string; to: number }> {
+    // Get plugins that handle this node type (O(1) lookup)
+    const plugins = this.nodeToPlugins.get(node.name);
+    if (plugins) {
+      for (const plugin of plugins) {
+        const children = await this.renderChildren(node);
+        const result = await plugin.renderToHTML!(node, children, this.ctx);
+        if (result !== null) {
+          return {
+            html: result,
+            to: Math.max(node.to, plugin.getPreviewConsumedTo?.(node, this.ctx) ?? node.to),
+          };
+        }
+      }
+    }
+
+    // Use default renderer
+    const renderer = this.renderers[node.name];
+    if (renderer) {
+      const children = await this.renderChildren(node);
+      return { html: renderer(node, children, this.ctx), to: node.to };
+    }
+
+    // Unknown node - render children or text
+    if (node.firstChild) {
+      return { html: await this.renderChildren(node), to: node.to };
+    }
+
+    // Leaf node - return text content
+    return { html: this.ctx.sliceDoc(node.from, node.to), to: node.to };
+  }
+
+  /**
+   * Render all children of a node, including text between nodes
+   */
+  private async renderChildren(node: SyntaxNode): Promise<string> {
+    let result = "";
+    let pos = node.from; // Track position to find text gaps
+    let child = node.firstChild;
+
+    while (child) {
+      // Add any text between the last position and this child
+      if (child.from > pos) {
+        result += escapeHtml(this.ctx.sliceDoc(pos, child.from));
+      }
+
+      // Render the child node
+      const rendered = await this.renderNodeWithExtent(child);
+      result += rendered.html;
+
+      // Update position to end of this child
+      pos = rendered.to;
+      child = child.nextSibling;
+    }
+
+    // Add any trailing text after the last child
+    if (pos < node.to) {
+      result += escapeHtml(this.ctx.sliceDoc(pos, node.to));
+    }
+
+    return result;
+  }
+}

package/src/preview/syntax-theme.ts

@@ -0,0 +1,112 @@
+import { classHighlighter, Highlighter } from "@lezer/highlight";
+import type { SyntaxThemeInput } from "./types";
+
+type HighlightSpec = {
+  tag?: unknown;
+  class?: string;
+  [key: string]: unknown;
+};
+
+type RuntimeHighlightStyle = {
+  specs?: HighlightSpec[];
+  style?: (tags: readonly import("@lezer/highlight").Tag[]) => string | null;
+  module?: { getRules(): string } | null;
+};
+
+const MAX_WALK_DEPTH = 8;
+
+/**
+ * Extract syntax highlight CSS from resolved CodeMirror HighlightStyle modules.
+ */
+export function generateSyntaxThemeCSS(
+  syntaxTheme: SyntaxThemeInput | SyntaxThemeInput[] | undefined,
+  _wrapperClass: string
+): string {
+  void _wrapperClass;
+  if (!syntaxTheme) return "";
+
+  const styles = extractRuntimeHighlightStyles(syntaxTheme);
+  if (!styles.length) return "";
+
+  const cssChunks: string[] = [];
+
+  for (const style of styles) {
+    const rules = style.module?.getRules();
+    if (!rules) continue;
+    cssChunks.push(rules);
+  }
+
+  if (!cssChunks.length) return "";
+
+  return Array.from(new Set(cssChunks)).join("\n");
+}
+
+export function resolveSyntaxHighlighters(
+  syntaxTheme: SyntaxThemeInput | SyntaxThemeInput[] | undefined,
+  includeLegacyClassHighlighter: boolean = true
+): readonly Highlighter[] {
+  const resolved: Highlighter[] = [];
+  if (includeLegacyClassHighlighter) {
+    resolved.push(classHighlighter);
+  }
+
+  const styles = extractRuntimeHighlightStyles(syntaxTheme);
+  for (const style of styles) {
+    if (typeof style.style === "function") {
+      resolved.push(style as unknown as Highlighter);
+    }
+  }
+
+  return Array.from(new Set(resolved));
+}
+
+function extractRuntimeHighlightStyles(
+  input: SyntaxThemeInput | SyntaxThemeInput[] | undefined
+): RuntimeHighlightStyle[] {
+  if (!input) return [];
+
+  const values = Array.isArray(input) ? input : [input];
+  const styles: RuntimeHighlightStyle[] = [];
+  const visited = new WeakSet<object>();
+
+  for (const value of values) {
+    walk(value, 0, visited, styles);
+  }
+
+  return styles;
+}
+
+function walk(value: unknown, depth: number, visited: WeakSet<object>, out: RuntimeHighlightStyle[]): void {
+  if (value === null || value === undefined) return;
+  if (depth > MAX_WALK_DEPTH) return;
+
+  if (isRuntimeHighlightStyle(value)) {
+    out.push(value);
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      walk(item, depth + 1, visited, out);
+    }
+    return;
+  }
+
+  if (typeof value !== "object") return;
+  if (visited.has(value)) return;
+  visited.add(value);
+
+  const keys = Object.getOwnPropertyNames(value);
+  for (const key of keys) {
+    try {
+      walk((value as Record<string, unknown>)[key], depth + 1, visited, out);
+    } catch {
+      // Ignore inaccessible properties
+    }
+  }
+}
+
+function isRuntimeHighlightStyle(value: unknown): value is RuntimeHighlightStyle {
+  if (!value || typeof value !== "object") return false;
+  const style = value as RuntimeHighlightStyle;
+  return Array.isArray(style.specs) && typeof style.style === "function";
+}

package/src/preview/toc.ts

@@ -0,0 +1,23 @@
+import { markdown, markdownLanguage } from "@codemirror/lang-markdown";
+import { EditorState } from "@codemirror/state";
+import type { MarkdownConfig } from "@lezer/markdown";
+import type { MardoraTocConfig, MardoraTocItem } from "../editor/table-of-contents";
+import { extractTocItemsFromState } from "../editor/table-of-contents";
+
+export function extractPreviewTocFromMarkdown(
+  doc: string,
+  config: MardoraTocConfig = {},
+  markdownConfig: MarkdownConfig[] = []
+): MardoraTocItem[] {
+  const state = EditorState.create({
+    doc,
+    extensions: [markdown({ base: markdownLanguage, extensions: markdownConfig })],
+  });
+
+  return extractTocItemsFromState(state, config).map((item) => ({
+    id: item.id,
+    level: item.level,
+    text: item.text,
+    active: item.active,
+  }));
+}

package/src/preview/types.ts

@@ -0,0 +1,89 @@
+import { SyntaxNode } from "@lezer/common";
+import { ThemeEnum } from "../editor/utils";
+
+export type SyntaxThemeInput =
+  | import("@codemirror/language").HighlightStyle
+  | import("@codemirror/state").Extension
+  | readonly import("@codemirror/state").Extension[];
+
+/**
+ * Context passed to plugin preview methods
+ */
+export interface PreviewContext {
+  /** Full document text */
+  readonly doc: string;
+
+  /** Current theme */
+  readonly theme: ThemeEnum;
+
+  /** Slice document text between positions */
+  sliceDoc(from: number, to: number): string;
+
+  /** Sanitize HTML content (for HTMLBlock/HTMLTag) */
+  sanitize(html: string): string;
+
+  /** Render children of a node to HTML */
+  renderChildren(node: SyntaxNode): Promise<string>;
+
+  /** Active syntax highlighters used for code rendering */
+  readonly syntaxHighlighters?: readonly import("@lezer/highlight").Highlighter[];
+
+  /** Return a stable heading id for TOC-aware heading renderers */
+  headingIdForNode?(node: SyntaxNode): string | null;
+}
+
+/**
+ * Configuration for the preview renderer
+ */
+export interface PreviewConfig {
+  /** Plugins to use for rendering */
+  plugins?: import("../editor/plugin").MardoraPlugin[];
+
+  /** Markdown extensions to use for rendering */
+  markdown?: import("@lezer/markdown").MarkdownConfig[];
+
+  /** CSS class for the wrapper element */
+  wrapperClass?: string;
+
+  /** HTML tag for the wrapper element */
+  wrapperTag?: "article" | "div" | "section";
+
+  /** Whether to sanitize HTML blocks (default: true) */
+  sanitize?: boolean;
+
+  /** Theme to use */
+  theme?: ThemeEnum;
+
+  /** CodeMirror syntax theme input used for static preview highlighting */
+  syntaxTheme?: SyntaxThemeInput | SyntaxThemeInput[];
+}
+
+/**
+ * Result of CSS generation
+ */
+export interface GenerateCSSConfig {
+  /** Plugins to extract styles from */
+  plugins?: import("../editor/plugin").MardoraPlugin[];
+
+  /** Theme to use */
+  theme?: ThemeEnum;
+
+  /** Wrapper class for scoping (default: "mardora-preview") */
+  wrapperClass?: string;
+
+  /** Include base styles */
+  includeBase?: boolean;
+
+  /** CodeMirror syntax theme input used for static preview syntax highlighting */
+  syntaxTheme?: SyntaxThemeInput | SyntaxThemeInput[];
+}
+
+/**
+ * Node renderer function type
+ */
+export type NodeRenderer = (node: SyntaxNode, children: string, ctx: PreviewContext) => string;
+
+/**
+ * Map of node names to their renderers
+ */
+export type NodeRendererMap = Record<string, NodeRenderer>;