@changerawr/markdown 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,585 @@
+interface MarkdownToken {
+    type: string;
+    content: string;
+    raw: string;
+    attributes?: Record<string, string>;
+}
+interface ParseRule {
+    name: string;
+    pattern: RegExp;
+    render: (match: RegExpMatchArray) => MarkdownToken;
+}
+interface RenderRule {
+    type: string;
+    render: (token: MarkdownToken) => string;
+}
+interface Extension {
+    name: string;
+    parseRules: ParseRule[];
+    renderRules: RenderRule[];
+}
+type OutputFormat = 'html' | 'tailwind' | 'json';
+interface RendererConfig {
+    format: OutputFormat;
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}
+interface ParserConfig {
+    debugMode?: boolean;
+    maxIterations?: number;
+    validateMarkdown?: boolean;
+}
+interface EngineConfig {
+    parser?: ParserConfig;
+    renderer?: RendererConfig;
+    extensions?: Extension[];
+}
+interface DebugInfo {
+    warnings: string[];
+    parseTime: number;
+    renderTime: number;
+    tokenCount: number;
+    iterationCount: number;
+}
+interface JsonAstNode {
+    type: string;
+    content: string;
+    attributes?: Record<string, string>;
+    children?: JsonAstNode[];
+}
+interface PerformanceMetrics {
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    memoryUsed?: number;
+}
+declare class MarkdownParseError extends Error {
+    readonly position?: number | undefined;
+    readonly rule?: string | undefined;
+    constructor(message: string, position?: number | undefined, rule?: string | undefined);
+}
+declare class MarkdownRenderError extends Error {
+    readonly tokenType?: string | undefined;
+    readonly token?: MarkdownToken | undefined;
+    constructor(message: string, tokenType?: string | undefined, token?: MarkdownToken | undefined);
+}
+declare class ExtensionError extends Error {
+    readonly extensionName?: string | undefined;
+    constructor(message: string, extensionName?: string | undefined);
+}
+type TokenType = 'text' | 'heading' | 'bold' | 'italic' | 'code' | 'codeblock' | 'link' | 'image' | 'list-item' | 'task-item' | 'blockquote' | 'hr' | 'line-break' | 'paragraph-break' | 'soft-break' | 'paragraph' | 'alert' | 'button' | 'embed' | string;
+interface EngineEvents {
+    onParseStart?: (content: string) => void;
+    onParseComplete?: (tokens: MarkdownToken[], metrics: PerformanceMetrics) => void;
+    onRenderStart?: (tokens: MarkdownToken[]) => void;
+    onRenderComplete?: (html: string, metrics: PerformanceMetrics) => void;
+    onError?: (error: Error) => void;
+    onWarning?: (warning: string) => void;
+}
+interface ExtensionRegistration {
+    success: boolean;
+    extensionName: string;
+    error?: string;
+    conflictingRules?: string[];
+}
+
+declare class ChangerawrMarkdown {
+    private parser;
+    private renderer;
+    private extensions;
+    constructor(config?: EngineConfig);
+    /**
+     * Register a custom extension
+     */
+    registerExtension(extension: Extension): ExtensionRegistration;
+    /**
+     * Unregister an extension
+     */
+    unregisterExtension(name: string): boolean;
+    /**
+     * Parse markdown content into tokens
+     */
+    parse(markdown: string): MarkdownToken[];
+    /**
+     * Render tokens to HTML
+     */
+    render(tokens: MarkdownToken[]): string;
+    /**
+     * Parse and render markdown to HTML in one step
+     */
+    toHtml(markdown: string): string;
+    /**
+     * Get list of registered extensions
+     */
+    getExtensions(): string[];
+    /**
+     * Check if extension is registered
+     */
+    hasExtension(name: string): boolean;
+    /**
+     * Get parser warnings
+     */
+    getWarnings(): string[];
+    /**
+     * Get debug information from last render
+     */
+    getDebugInfo(): DebugInfo | null;
+    /**
+     * Get performance metrics for the last operation
+     */
+    getPerformanceMetrics(): PerformanceMetrics | null;
+    /**
+     * Register built-in extensions
+     */
+    private registerBuiltInExtensions;
+    /**
+     * Rebuild parser and renderer with current extensions
+     */
+    private rebuildParserAndRenderer;
+}
+declare function parseMarkdown(content: string): MarkdownToken[];
+declare function renderMarkdown(content: string): string;
+
+/**
+ * Plain HTML output renderer - no CSS framework classes
+ */
+
+/**
+ * Render markdown to plain HTML without CSS framework classes
+ */
+declare function renderToHTML(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Parse markdown and render to HTML with custom configuration
+ */
+declare function renderToHTMLWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    debugMode?: boolean;
+}): string;
+/**
+ * Render markdown to HTML without any sanitization (use with caution)
+ */
+declare function renderToHTMLUnsafe(markdown: string): string;
+
+/**
+ * JSON AST output renderer - returns structured token data
+ */
+
+/**
+ * Parse markdown and return the token array as JSON
+ */
+declare function renderToJSON(markdown: string, config?: Omit<EngineConfig, 'renderer'>): MarkdownToken[];
+/**
+ * Parse markdown and return a hierarchical AST structure
+ */
+declare function renderToAST(markdown: string, config?: Omit<EngineConfig, 'renderer'>): JsonAstNode[];
+/**
+ * Convert flat token array to hierarchical AST
+ */
+declare function tokensToAST(tokens: MarkdownToken[]): JsonAstNode[];
+/**
+ * Convert AST back to flat tokens
+ */
+declare function astToTokens(ast: JsonAstNode[]): MarkdownToken[];
+/**
+ * Serialize tokens to JSON string with formatting
+ */
+declare function tokensToJSONString(tokens: MarkdownToken[], pretty?: boolean): string;
+/**
+ * Serialize AST to JSON string with formatting
+ */
+declare function astToJSONString(ast: JsonAstNode[], pretty?: boolean): string;
+/**
+ * Parse JSON string back to tokens
+ */
+declare function parseTokensFromJSON(jsonString: string): MarkdownToken[];
+/**
+ * Parse JSON string back to AST
+ */
+declare function parseASTFromJSON(jsonString: string): JsonAstNode[];
+/**
+ * Get comprehensive statistics from parsed tokens
+ */
+declare function getTokenStats(tokens: MarkdownToken[]): TokenStatistics;
+/**
+ * Get AST-specific statistics
+ */
+declare function getASTStats(ast: JsonAstNode[]): ASTStatistics;
+/**
+ * Compare two token arrays for differences
+ */
+declare function compareTokens(tokensA: MarkdownToken[], tokensB: MarkdownToken[]): TokenComparison;
+interface TokenStatistics {
+    totalTokens: number;
+    tokenTypes: Record<string, number>;
+    extensionTokens: Record<string, number>;
+    totalContent: number;
+    totalRaw: number;
+    tokensWithAttributes: number;
+    averageContentLength: number;
+    averageRawLength: number;
+    attributeUsageRate: number;
+}
+interface ASTStatistics {
+    totalNodes: number;
+    maxDepth: number;
+    nodesWithChildren: number;
+    totalChildren: number;
+    nodeTypes: Record<string, number>;
+    averageChildrenPerParent: number;
+    hierarchyComplexity: number;
+}
+interface TokenDifference {
+    index: number;
+    type: 'added' | 'removed' | 'modified';
+    tokenA?: MarkdownToken;
+    tokenB?: MarkdownToken;
+}
+interface TokenComparison {
+    identical: boolean;
+    differences: TokenDifference[];
+    addedCount: number;
+    removedCount: number;
+    modifiedCount: number;
+}
+
+/**
+ * Tailwind CSS output renderer - HTML with Tailwind CSS classes
+ */
+
+/**
+ * Render markdown to HTML with Tailwind CSS classes (default behavior)
+ */
+declare function renderToTailwind(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Render markdown with custom Tailwind classes
+ */
+declare function renderToTailwindWithClasses(markdown: string, customClasses?: Record<string, string>): string;
+/**
+ * Render markdown to Tailwind HTML with custom configuration
+ */
+declare function renderToTailwindWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}): string;
+/**
+ * Default Tailwind configuration for common use cases
+ */
+declare const defaultTailwindClasses: {
+    'heading-1': string;
+    'heading-2': string;
+    'heading-3': string;
+    'heading-4': string;
+    'heading-5': string;
+    'heading-6': string;
+    paragraph: string;
+    blockquote: string;
+    'code-inline': string;
+    'code-block': string;
+    link: string;
+    button: string;
+    list: string;
+    'list-item': string;
+    image: string;
+    embed: string;
+    alert: string;
+    'alert-info': string;
+    'alert-warning': string;
+    'alert-error': string;
+    'alert-success': string;
+};
+/**
+ * Prose-friendly Tailwind classes for blog/article content
+ */
+declare const proseClasses: {
+    'heading-1': string;
+    'heading-2': string;
+    'heading-3': string;
+    paragraph: string;
+    blockquote: string;
+    'code-inline': string;
+    'code-block': string;
+    link: string;
+};
+/**
+ * Minimal Tailwind classes for clean, simple styling
+ */
+declare const minimalClasses: {
+    'heading-1': string;
+    'heading-2': string;
+    'heading-3': string;
+    paragraph: string;
+    blockquote: string;
+    'code-inline': string;
+    'code-block': string;
+    link: string;
+};
+
+/**
+ * Standalone version of Changerawr Markdown for vanilla JavaScript usage
+ * No React dependencies - works in browser and Node.js environments
+ */
+
+declare function renderCum(markdown: string, config?: EngineConfig): string;
+declare function parseCum(markdown: string, config?: EngineConfig): MarkdownToken[];
+declare function createCumEngine(config?: EngineConfig): ChangerawrMarkdown;
+declare function renderCumToHtml(markdown: string): string;
+declare function renderCumToTailwind(markdown: string): string;
+declare function renderCumToJson(markdown: string): MarkdownToken[];
+
+/**
+ * Utility functions for Changerawr Markdown
+ */
+/**
+ * Escape HTML special characters
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Generate URL-friendly ID from text
+ */
+declare function generateId(text: string): string;
+/**
+ * Sanitize HTML content using DOMPurify
+ */
+declare function sanitizeHtml(html: string): string;
+/**
+ * Basic HTML sanitization - removes dangerous content
+ */
+declare function basicSanitize(html: string): string;
+/**
+ * Check if code is running in browser environment
+ */
+declare function isBrowser(): boolean;
+/**
+ * Check if code is running in Node.js environment
+ */
+declare function isNode(): boolean;
+/**
+ * Debounce function for performance optimization
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Deep merge two objects
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+/**
+ * Extract domain from URL
+ */
+declare function extractDomain(url: string): string;
+/**
+ * Check if URL is valid
+ */
+declare function isValidUrl(url: string): boolean;
+/**
+ * Parse options string into key-value object
+ */
+declare function parseOptions(options: string): Record<string, string>;
+/**
+ * Performance measurement utility
+ */
+declare class PerformanceTimer {
+    private startTime;
+    private marks;
+    constructor();
+    mark(name: string): void;
+    getTime(name?: string): number;
+    getAllMarks(): Record<string, number>;
+}
+/**
+ * Simple logger with different levels
+ */
+declare class Logger {
+    private debugMode;
+    constructor(debugMode?: boolean);
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    setDebugMode(enabled: boolean): void;
+}
+
+declare class MarkdownParser {
+    private rules;
+    private warnings;
+    private config;
+    constructor(config?: ParserConfig);
+    addRule(rule: ParseRule): void;
+    setupDefaultRulesIfEmpty(): void;
+    hasRule(name: string): boolean;
+    parse(markdown: string): MarkdownToken[];
+    getWarnings(): string[];
+    getConfig(): ParserConfig;
+    updateConfig(config: Partial<ParserConfig>): void;
+    setDebugMode(enabled: boolean): void;
+    clearWarnings(): void;
+    getIterationCount(): number;
+    private preprocessMarkdown;
+    private validateMarkdown;
+    private postProcessTokens;
+    private setupDefaultRules;
+}
+
+declare class MarkdownRenderer {
+    private rules;
+    private warnings;
+    private config;
+    constructor(config?: RendererConfig);
+    addRule(rule: RenderRule): void;
+    hasRule(type: string): boolean;
+    render(tokens: MarkdownToken[]): string;
+    getWarnings(): string[];
+    getConfig(): RendererConfig;
+    updateConfig(config: Partial<RendererConfig>): void;
+    setDebugMode(enabled: boolean): void;
+    clearWarnings(): void;
+    private renderToken;
+    private createErrorBlock;
+    private createDebugBlock;
+    private setupDefaultRules;
+}
+
+declare const AlertExtension: Extension;
+
+declare const ButtonExtension: Extension;
+
+declare const EmbedExtension: Extension;
+
+/**
+ * @changerawr/markdown - Main package exports
+ *
+ * Powerful markdown renderer with custom extensions
+ * Supports HTML, Tailwind CSS, and JSON outputs
+ */
+
+/**
+ * Create a general-purpose markdown engine with default settings
+ */
+declare function createEngine(config?: EngineConfig): ChangerawrMarkdown;
+/**
+ * Create an engine optimized for HTML output (no CSS classes)
+ */
+declare function createHTMLEngine(config?: Omit<EngineConfig, 'renderer'>): ChangerawrMarkdown;
+/**
+ * Create an engine optimized for Tailwind CSS output
+ */
+declare function createTailwindEngine(config?: Omit<EngineConfig, 'renderer'>): ChangerawrMarkdown;
+/**
+ * Create an engine with debug mode enabled
+ */
+declare function createDebugEngine(config?: EngineConfig): ChangerawrMarkdown;
+/**
+ * Create an engine without built-in extensions (minimal setup)
+ */
+declare function createMinimalEngine(config?: EngineConfig): ChangerawrMarkdown;
+/**
+ * Create an engine with custom extensions only
+ */
+declare function createCustomEngine(extensions: Extension[], config?: Omit<EngineConfig, 'extensions'>): ChangerawrMarkdown;
+/**
+ * Quick access object with common functions
+ * Useful for destructuring: const { render, parse, toHtml } = markdown;
+ */
+declare const markdown: {
+    readonly render: typeof renderMarkdown;
+    readonly parse: typeof parseMarkdown;
+    readonly toHtml: typeof renderToHTML;
+    readonly toTailwind: typeof renderToTailwind;
+    readonly toJson: typeof renderToJSON;
+    readonly toAst: typeof renderToAST;
+    readonly createEngine: typeof createEngine;
+    readonly createHTMLEngine: typeof createHTMLEngine;
+    readonly createTailwindEngine: typeof createTailwindEngine;
+    readonly createDebugEngine: typeof createDebugEngine;
+    readonly createMinimalEngine: typeof createMinimalEngine;
+    readonly createCustomEngine: typeof createCustomEngine;
+    readonly renderCum: typeof renderCum;
+    readonly parseCum: typeof parseCum;
+    readonly ChangerawrMarkdown: typeof ChangerawrMarkdown;
+    readonly extensions: {
+        readonly Alert: Extension;
+        readonly Button: Extension;
+        readonly Embed: Extension;
+    };
+    readonly utils: {
+        readonly escapeHtml: typeof escapeHtml;
+        readonly generateId: typeof generateId;
+        readonly sanitizeHtml: typeof sanitizeHtml;
+        readonly extractDomain: typeof extractDomain;
+        readonly parseOptions: typeof parseOptions;
+        readonly PerformanceTimer: typeof PerformanceTimer;
+        readonly Logger: typeof Logger;
+    };
+};
+
+/**
+ * Preset configurations for common use cases
+ */
+declare const presets: {
+    /**
+     * Blog/article preset with prose-friendly styling
+     */
+    readonly blog: {
+        readonly renderer: {
+            readonly format: "tailwind";
+            readonly customClasses: {
+                readonly 'heading-1': "text-4xl font-bold tracking-tight mt-10 mb-6";
+                readonly 'heading-2': "text-3xl font-semibold tracking-tight mt-8 mb-4";
+                readonly 'heading-3': "text-2xl font-medium tracking-tight mt-6 mb-3";
+                readonly paragraph: "text-lg leading-8 mb-6";
+                readonly blockquote: "border-l-4 border-gray-300 pl-6 py-2 italic text-gray-700 my-6";
+                readonly 'code-inline': "bg-gray-100 text-gray-800 px-2 py-1 rounded text-sm font-mono";
+                readonly 'code-block': "bg-gray-900 text-gray-100 p-6 rounded-lg overflow-x-auto my-6 text-sm";
+            };
+        };
+    };
+    /**
+     * Documentation preset with clean, technical styling
+     */
+    readonly docs: {
+        readonly renderer: {
+            readonly format: "tailwind";
+            readonly customClasses: {
+                readonly 'heading-1': "text-3xl font-bold border-b border-gray-200 pb-2 mb-6";
+                readonly 'heading-2': "text-2xl font-semibold mt-8 mb-4";
+                readonly 'heading-3': "text-xl font-medium mt-6 mb-3";
+                readonly paragraph: "leading-7 mb-4";
+                readonly 'code-inline': "bg-blue-50 text-blue-800 px-2 py-1 rounded text-sm font-mono";
+                readonly 'code-block': "bg-gray-50 border border-gray-200 p-4 rounded-lg overflow-x-auto my-4 text-sm";
+                readonly alert: "border border-blue-200 bg-blue-50 text-blue-800 p-4 rounded-lg mb-4";
+            };
+        };
+    };
+    /**
+     * Minimal preset with basic styling
+     */
+    readonly minimal: {
+        readonly renderer: {
+            readonly format: "html";
+            readonly sanitize: true;
+        };
+    };
+    /**
+     * Performance preset with minimal processing
+     */
+    readonly fast: {
+        readonly parser: {
+            readonly validateMarkdown: false;
+            readonly maxIterations: 1000;
+        };
+        readonly renderer: {
+            readonly format: "html";
+            readonly sanitize: false;
+        };
+    };
+};
+/**
+ * Create engine with preset configuration
+ */
+declare function createEngineWithPreset(presetName: keyof typeof presets, additionalConfig?: EngineConfig): ChangerawrMarkdown;
+
+export { type ASTStatistics, AlertExtension, ButtonExtension, ChangerawrMarkdown, type DebugInfo, EmbedExtension, type EngineConfig, type EngineEvents, type Extension, ExtensionError, type Extension as ExtensionInterface, type ExtensionRegistration, type JsonAstNode, Logger, MarkdownParseError, MarkdownParser, MarkdownRenderError, MarkdownRenderer, type MarkdownToken, type OutputFormat, type ParseRule, type ParserConfig, type PerformanceMetrics, PerformanceTimer, type RenderRule, type RendererConfig, type TokenComparison, type TokenDifference, type TokenStatistics, type TokenType, astToJSONString, astToTokens, basicSanitize, compareTokens, createCumEngine, createCustomEngine, createDebugEngine, createEngine, createEngineWithPreset, createHTMLEngine, createMinimalEngine, createTailwindEngine, debounce, deepMerge, markdown as default, defaultTailwindClasses, escapeHtml, extractDomain, generateId, getASTStats, getTokenStats, isBrowser, isNode, isValidUrl, markdown, minimalClasses, parseASTFromJSON, parseCum, parseMarkdown, parseOptions, parseTokensFromJSON, presets, proseClasses, renderCum, renderCumToHtml, renderCumToJson, renderCumToTailwind, renderMarkdown, renderToAST, renderToHTML, renderToHTMLUnsafe, renderToHTMLWithConfig, renderToJSON, renderToTailwind, renderToTailwindWithClasses, renderToTailwindWithConfig, sanitizeHtml, tokensToAST, tokensToJSONString };