@leadertechie/md2html 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/index.d.ts

@@ -43,6 +43,51 @@ export declare class CodeHandler implements TokenHandler {
     };
 }
 
+/**
+ * Built-in visitor: collect all nodes of a specific type.
+ */
+export declare function collectByType(root: ContentNode, type: string): ContentNode[];
+
+/**
+ * Walk a ContentNode tree and collect results from the visitor.
+ * The collector function is called for each node and returns a value or null.
+ */
+export declare function collectFromTree<T>(root: ContentNode, collector: (node: ContentNode, parent: ContentNode | null, depth: number) => T | null): T[];
+
+/**
+ * Built-in visitor: collect all headings with their levels.
+ */
+export declare function collectHeadings(root: ContentNode): Array<{
+    level: string;
+    text: string;
+    id?: string;
+}>;
+
+/**
+ * Built-in visitor: collect all images with their src/alt.
+ */
+export declare function collectImages(root: ContentNode): Array<{
+    src: string;
+    alt: string;
+}>;
+
+/**
+ * ContainerBlockHandler — handles custom :::tag#id.class container blocks.
+ *
+ * These are produced by the MarkdownParser's preprocessor which converts
+ * the ::: syntax into marked tokens before lexing, then reconstructs
+ * containerBlock tokens after lexing.
+ *
+ * The handler parses the specifier (e.g. "section#header.content") into
+ * tag name, id, and class(es), then recursively parses the inner tokens
+ * as normal markdown content, producing a container node with the
+ * specified HTML wrapper.
+ */
+export declare class ContainerBlockHandler implements TokenHandler {
+    readonly type = "containerBlock";
+    handle(token: Record<string, unknown>, ctx: ParseContext): ContentNode | null;
+}
+
 export declare interface ContentNode {
     type: ContentNodeType;
     content?: string;
@@ -63,6 +108,22 @@ export declare type ContentNodeType = 'text' | 'heading' | 'paragraph' | 'list'
 /** Default allowed HTML tags for preserveRawHTML mode */
 export declare const defaultAllowedHTMLTags: string[];
 
+/**
+ * FrontmatterHandler — consumes YAML-ish frontmatter tokens produced by marked.lexer().
+ * Parses the raw YAML and stores key-value pairs onto ctx.metadata.
+ * Returns null so no HTML is emitted for frontmatter blocks.
+ *
+ * Handles both formats:
+ *   key: value
+ *   key:
+ *     - item1
+ *     - item2
+ */
+export declare class FrontmatterHandler implements TokenHandler {
+    readonly type = "frontmatter";
+    handle(token: Record<string, unknown>, ctx: ParseContext): null;
+}
+
 /**
  * Handles 'heading' tokens (h1-h6).
  */
@@ -110,7 +171,10 @@ export declare class HtmlHandler implements TokenHandler {
 
 export declare class HTMLRenderer {
     private config;
+    private strategyRegistry;
     constructor(config?: StyleConfigV2);
+    /** Access the strategy registry for customization. */
+    get strategies(): RendererStrategyRegistry;
     private hasClassConfig;
     private getClass;
     private generateHeadingId;
@@ -119,7 +183,12 @@ export declare class HTMLRenderer {
      * Returns empty string if emitScopeAnchors is disabled.
      */
     private getScopeAttr;
-    private renderWithClass;
+    /**
+     * Get the CSS class for a container's tag-based rendering.
+     * Returns just the tag name since renderWithClass applies the prefix.
+     */
+    private getContainerClass;
+    private buildRenderContext;
     renderNode(node: ContentNode): string;
     renderNodes(nodes: ContentNode[]): string;
     renderToHTMLString(nodes: ContentNode[]): string;
@@ -169,6 +238,7 @@ export declare class MarkdownParser {
     private errorRecovery;
     private maxRecursionDepth;
     private allowedHTMLTags;
+    private allowedAttributes;
     private handlerRegistry;
     private onUnhandledToken?;
     constructor(options?: ParserOptions);
@@ -177,13 +247,57 @@ export declare class MarkdownParser {
     private processImagePath;
     private processInlineFormatting;
     private processSlots;
+    /**
+     * Check if an attribute name is allowed for a given tag.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    private isAttributeAllowed;
+    /**
+     * Check if an attribute name matches a list of allowed patterns.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    private matchesAttributeList;
+    /**
+     * Filter attributes on an HTML tag, keeping only allowed ones.
+     */
+    private filterTagAttributes;
     private processRawHTML;
     /**
      * Build the ParseContext that is passed to every token handler.
      * This is the bridge between the parser's private services and the handlers.
      */
     private createContext;
+    /**
+     * Process an array of marked tokens into ContentNodes.
+     * When depth === 0 (root), creates a shared context that accumulates metadata.
+     * For recursive calls (depth > 0), creates a fresh context for each level.
+     */
     private parseTokens;
+    /**
+     * Pre-process markdown: convert `:::tag#id.class` container syntax
+     * into HTML comment markers that marked will preserve as html tokens,
+     * but won't affect markdown parsing of the inner content.
+     *
+     * Example:
+     *   :::section#header
+     *   # Heading inside container
+     *   Some text
+     *   :::
+     *
+     * Becomes:
+     *   <!-- md-container:section#header -->
+     *   # Heading inside container
+     *   Some text
+     *   <!-- /md-container -->
+     */
+    private preprocessContainerBlocks;
+    /**
+     * Post-process marked tokens to collapse container block markers
+     * into structured containerBlock tokens with proper nesting.
+     *
+     * This handles nesting depth up to maxRecursionDepth.
+     */
+    private postprocessTokens;
     parse(markdown: string, options?: ParseOptions): MarkdownContent;
     parseToNodes(markdown: string, options?: ParseOptions): ContentNode[];
 }
@@ -205,9 +319,75 @@ export declare class MarkdownPipeline {
     getCustomCSS(): string;
 }
 
+/**
+ * ContentNode factory — a builder API for creating ContentNode instances
+ * consistently across the codebase. Eliminates scattered object literals
+ * and provides type-safe construction with sensible defaults.
+ *
+ * Usage:
+ *   NodeFactory.heading('Hello', { level: '1' })
+ *   NodeFactory.paragraph('Some text')
+ *   NodeFactory.container({ tag: 'section', id: 'main' }, [children...])
+ */
+export declare class NodeFactory {
+    static heading(content: string, attributes?: Record<string, unknown>): ContentNode;
+    static paragraph(contentOrChildren: string | ContentNode[], children?: ContentNode[]): ContentNode;
+    static list(items: ContentNode[], ordered?: boolean, attributes?: Record<string, unknown>): ContentNode;
+    static listItem(content: string): ContentNode;
+    static image(src: string, alt?: string, className?: string): ContentNode;
+    static code(content: string, lang?: string): ContentNode;
+    static container(children?: ContentNode[], config?: {
+        tag?: string;
+        id?: string;
+        className?: string;
+        rawHTML?: string;
+        scope?: string;
+    }): ContentNode;
+    static text(content: string): ContentNode;
+    static strong(content: string): ContentNode;
+    static emphasis(content: string): ContentNode;
+    static link(href: string, content: string): ContentNode;
+}
+
+/**
+ * Strategy interface for rendering a specific ContentNode type to HTML.
+ * This is the renderer-side equivalent of TokenHandler — each node type
+ * gets its own strategy, eliminating the large switch statement.
+ *
+ * To add support for a new node type:
+ * 1. Create a class implementing NodeRendererStrategy
+ * 2. Register it with the RendererStrategyRegistry
+ */
+export declare interface NodeRendererStrategy {
+    /** The node type this strategy handles */
+    readonly type: string;
+    /** Render a node of this type to an HTML string */
+    render(node: ContentNode, renderChild: (child: ContentNode) => string, ctx: RenderContext): string;
+}
+
 /** Maps ContentNodeType to ScopeValue */
 export declare const nodeTypeToScope: Record<ContentNodeType, ScopeValue>;
 
+/**
+ * Visitor interface for traversing/walking a ContentNode AST.
+ *
+ * Implement this interface to inspect, collect, or transform nodes.
+ * Each method returns a ContentNode or null — returning null removes the node.
+ *
+ * Use cases:
+ *  - Collect all images for preloading
+ *  - Transform link URLs
+ *  - Validate AST structure
+ *  - Extract headings for ToC
+ *  - Inject attributes
+ */
+export declare interface NodeVisitor {
+    /** Called when entering a node, before visiting its children. */
+    enter?(node: ContentNode, parent: ContentNode | null, depth: number): ContentNode | null;
+    /** Called after visiting all children of the node. */
+    exit?(node: ContentNode, parent: ContentNode | null, depth: number): ContentNode | null;
+}
+
 /**
  * Handles 'paragraph' tokens, including inline images and raw HTML.
  */
@@ -238,6 +418,11 @@ export declare interface ParseContext {
     maxRecursionDepth: number;
     /** Report an unhandled token type so callers can be notified */
     reportUnhandled(type: string, token: Record<string, unknown>): void;
+    /**
+     * Shared metadata store populated by token handlers (e.g. FrontmatterHandler).
+     * After parsing, this object contains all frontmatter key-value pairs.
+     */
+    metadata: Record<string, unknown>;
 }
 
 export declare interface ParseOptions {
@@ -255,8 +440,15 @@ export declare interface ParserOptions {
     errorRecovery?: 'throw' | 'warn' | 'silent';
     maxRecursionDepth?: number;
     allowedHTMLTags?: string[];
+    /**
+     * Allowed HTML attributes per tag for preserveRawHTML mode.
+     * Key "*" applies to all tags. Key "tag" applies to specific tags.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    allowedAttributes?: Record<string, string[]>;
     /**
      * Callback invoked when a token type has no dedicated handler.
+
      * The catch-all handler will still produce a container node for the content,
      * but this callback allows callers to log, warn, or track unhandled types.
      *
@@ -290,6 +482,56 @@ export declare interface PipelineConfigV2 extends PipelineConfig {
     maxRecursionDepth?: number;
     /** Additional allowed HTML tags for preserveRawHTML mode */
     allowedHTMLTags?: string[];
+    /**
+     * Allowed HTML attributes per tag for preserveRawHTML mode.
+     * Key "*" applies to all tags. Key "tag" applies to specific tags.
+     * Supports "data-*" wildcard prefix matching.
+     * Example: { "*": ["id", "class"], "script": ["type", "src"] }
+     */
+    allowedAttributes?: Record<string, string[]>;
+}
+
+/**
+ * Context passed to every render strategy, providing access to
+ * shared rendering services and configuration.
+ */
+export declare interface RenderContext {
+    classPrefix: string;
+    addHeadingIds: boolean;
+    emitScopeAnchors: boolean;
+    customCSS: string;
+    getClass(baseClass: string, nodeClass?: string): string;
+    getScopeAttr(node: ContentNode): string;
+    generateHeadingId(content?: string): string;
+    getContainerClass(tag: string): string;
+    hasClassConfig(): boolean;
+}
+
+/**
+ * Registry of renderer strategies. Maps ContentNode types to their
+ * rendering strategy. This is the renderer-side equivalent of
+ * TokenHandlerRegistry.
+ *
+ * The registry uses a two-tier lookup:
+ * 1. Check for a dedicated strategy by node type
+ * 2. Fall back to the catch-all strategy (registered as '*')
+ */
+export declare class RendererStrategyRegistry {
+    private strategies;
+    private fallback;
+    constructor();
+    /** Register a strategy for a node type. Overrides any existing strategy. */
+    register(strategy: NodeRendererStrategy): void;
+    /** Unregister a strategy by node type. */
+    unregister(type: string): void;
+    /** Get a strategy for the given node type, falling back to catch-all. */
+    get(type: string): NodeRendererStrategy;
+    /** Check if a dedicated strategy exists for the given node type. */
+    has(type: string): boolean;
+    /** Get all registered dedicated strategy types. */
+    get types(): string[];
+    /** Replace the fallback strategy. */
+    setFallback(strategy: NodeRendererStrategy): void;
 }
 
 /** Scope hierarchy values for data-md-scope */
@@ -354,4 +596,10 @@ export declare class TokenHandlerRegistry {
     getCatchAll(): TokenHandler;
 }
 
+/**
+ * Walk a ContentNode tree, applying a visitor at each node.
+ * Returns a new tree (immutable) — does not mutate the original.
+ */
+export declare function walkTree(root: ContentNode, visitor: NodeVisitor): ContentNode;
+
 export { }