simple-customize-markdown-converter 1.1.0 → 1.2.1

package/dist/types/options/renderOptions.d.ts

@@ -1,32 +1,56 @@
-import { Node } from "../node";
+import { ASTNode, NodeType } from '../parser';
 /**
- * Function type for rendering an AST node to HTML.
+ * A strategy function type for rendering a specific AST node.
+ * @template TOutput - The resulting type after rendered.
+ * @template TNode - The specific `ASTNode` processed.
  *
- * @template T - A subtype of `Node` corresponding to the render node
- * @param node - The AST node to render
- * @param children - Rendered HTML strings of the node's children
- * @returns A HTML string representation of the node
+ * @param node - The `ASTNode` object containing its properties.
+ * @param children - An array of already rendered `TOutput` of this node's childrens.
+ * @returns The rendered result for the given node.
+ *
+ * @since v.1.2.0 - Introduced `GenericNodeRenderer` for defining `RenderElement`
  */
-type NodeRenderer<T extends Node = Node> = (node: T, children: string[]) => string;
+type GenericNodeRenderer<TOutput, TNode extends ASTNode = ASTNode> = (node: TNode, children: TOutput[]) => TOutput;
 /**
- * A mapping of AST node types to custom render functions.
- *
- * - The key is a `Node["type"]` string literal (e.g. `"Header"`, `"Paragraph"`)
- * - The value is a function `(node, children) => string`:
- *      - `node` is a `Node` with its attribute depending on its `type`.
- *      (e.g. `"Header"` nodes include `level`, `"CodeBlock"` nodes include `lang` and `content`, etc)
- *      - `children` is the array of rendered strings of its children.
+ * A mapping of `ASTNode` types to their coressponding rendering functions.
+ * @template TOutput - The target output type of the renderer.
  */
-export type RenderElements = {
-    [K in Node["type"]]?: NodeRenderer<Extract<Node, {
-        type: K;
-    }>>;
+export type GenericRenderElements<TOutput> = {
+    [K in ASTNode["type"]]?: GenericNodeRenderer<TOutput, ASTNode>;
+} & {
+    [key: string]: GenericNodeRenderer<TOutput, any> | undefined;
 };
+/**
+ * Options for customizing the rendering process for a specific output type.
+ * @template TOutput - The output type.
+ * @property className - Customize classname for one or more ASTNode types.
+ * @property elements - Optional custom rendered for one or more ASTNode types
+ */
+export interface RenderOption<TOutput> {
+    /**
+     * Use "Header" for all levels
+     * Use additional "Header1", "Header2"... "Header6" for specific header level
+     */
+    className?: Partial<Record<NodeType | "Header1" | "Header2" | "Header3" | "Header4" | "Header5" | "Header6", string>>;
+    elements?: GenericRenderElements<TOutput>;
+}
+/**
+ * An utilities type alias for render `ASTNode` to `HTML string`
+ * Equivalent to `GenericRenderElements<string>`.
+ * @alias DefaultRenderElements
+ */
+export type DefaultRenderElements = GenericRenderElements<string>;
+/**
+ * An utilities type alias for render `ASTNode` to `React.ReactNode`
+ * Equivalent to `GenericRenderElements<React.ReactNode>`.
+ * @alias ReactRenderElements
+ */
+export type ReactRenderElements = GenericRenderElements<React.ReactNode>;
 /**
  * Options to customize how AST nodes are renderes into HTML
+ * @deprecated Use {@link RenderOption<string>} instead to use newer options.
  *
  * @property elements - Optional custom rendered for one or more node types
- *
  * @example
  * ```ts
  * const renderOptions: RenderOption = {
@@ -38,7 +62,32 @@ export type RenderElements = {
  * ```
  *
  */
-export type RenderOption = {
-    elements?: RenderElements;
+export type DefaultRenderOption = {
+    elements?: DefaultRenderElements;
+};
+/**
+ * Options to customize how AST nodes are renderes into ReactNode elements
+ * @deprecated Use {@link RenderOption<React.ReactNode>} instead to use newer options.
+ *
+ * @property elements - Optional custom rendered for one or more node types
+ * @example
+ * ```tsx
+ * // Using JSX (Recommended for most users)
+ * const renderOptions: ReactRenderOption = {
+ *  elements: {
+ *    Paragraph: (_node, children) => <p className="paragraph">{children}</p>,
+ *    Bold: (_node, children) => <strong className="bold-text">{children}</strong>,
+ *  }
+ * }
+ * // Or using React.createElement (Common in library core or without JSX)
+ * const renderOptions: ReactRenderOption = {
+ *  elements: {
+ *    Bold: (_node, children) => React.createElement("b", { className: "bold" }, ...children),
+ *   }
+ * }
+ * ```
+ */
+export type ReactRenderOption = {
+    elements?: ReactRenderElements;
 };
 export {};

package/dist/types/parser.d.ts

@@ -0,0 +1,132 @@
+import { IParser } from '../core/parser/index';
+import { Token } from './token';
+/**
+ * AST (Abstract Syntax Tree) node definition.
+ *
+ * Each node represents a Markdown construct and some special nodes (Document, Paragraph).
+ * Some nodes are containers (have `children`), while others are leaf nodes (contain text).
+ *
+ * Variants:
+ * - Document: Root node, contains all other nodes.
+ * - Paragraph: A block of text, contain inline nodes.
+ * - Header: A header with given `level` (1-6)
+ * - Bold: Bold text
+ * - Italic: Italic text
+ * - Strikethrough: Strilethrough text
+ * - InlineCode: Inline code snippet, with it's `content`
+ * - Quote: A quote block
+ * - CodeBlock: A code block, with it's `lang` and `content`
+ * - List: A list, with it's level and children
+ * - ListItem: An item of a list, with it's children
+ * - TaskItem: An item for tasklist, with it's checked state
+ * - Link: A link, with it's `text` and `href`
+ * - Image: An image, with it's `src` and `alt`
+ * - HorizontalLine: A horizontal line
+ * - Text: Raw text content.
+ * - Table: A table, with it's rows
+ * - HTMLBlock: A HTML block element, with it's `value`
+ * - HTMLInline: An inline HTML element, with it's `value`
+ * - FootnoteRef: A refernce with it's `id`
+ *
+ * {@link ASTNode} for each variant's attribute listed detail
+ */
+export type DefaultNodeType = "Document" | "Paragraph" | "Header" | "Bold" | "Italic" | "Strikethrough" | "InlineCode" | "CodeBlock" | "Quote" | "List" | "ListItem" | "TaskItem" | "Link" | "Image" | "HorizontalLine" | "Text" | "Table" | "HTMLBlock" | "HTMLInline" | "FootnoteRef";
+export type NodeType = DefaultNodeType | (string & {});
+export interface TableCell {
+    align: "left" | "center" | "right";
+    children: ASTNode[];
+}
+export interface TableRow {
+    isHeader: boolean;
+    cells: TableCell[];
+}
+/**
+ * AST (Abstract Syntax Tree) node definition. It representing all possible Markdown constructs and its possible properties.
+ *
+ * Use the `type` property to determine which other properties are available.
+ */
+export interface ASTNode {
+    /**
+     * The type of the node, determining its structure and purpose.
+     * @see {@link DefaultNodeType} for standard types.
+     */
+    type: NodeType;
+    /**
+     * Nested nodes within this container.
+     * Applicable for: `Document`, `Paragraph`, `Header`, `Bold`, `Italic`, `Strikethrough`, `Quote`, `List`, `ListItem`, `TaskItem`.
+     */
+    children?: ASTNode[];
+    /**
+     * Raw string content.
+     * Applicable for: `Text` (the plain text), `HTMLBlock` & `HTMLInline` (the raw HTML code).
+     */
+    value?: string;
+    /**
+     * The internal content of a code element.
+     * Applicable for: `InlineCode`, `CodeBlock`.
+     */
+    content?: string;
+    /**
+     * The level of importance/depth.
+     * Applicable for: `Header` (1-6).
+     */
+    level?: number;
+    /**
+     * Programming language identifier for syntax highlighting.
+     * Applicable for: `CodeBlock` (e.g., "javascript", "python").
+     */
+    lang?: string;
+    /**
+     * URL or path for external resources.
+     * Applicable for: `Link` (destination), `Image` (source).
+     */
+    href?: string;
+    /**
+     * The clickable text label for a link.
+     * Applicable for: `Link`.
+     */
+    text?: string;
+    /**
+     * Source URL of an image.
+     * Applicable for: `Image`.
+     */
+    src?: string;
+    /**
+     * Alternative text for accessibility.
+     * Applicable for: `Image`.
+     */
+    alt?: string;
+    /**
+     * Indicates if a list is numbered (true) or bulleted (false).
+     * Applicable for: `List`.
+     */
+    ordered?: boolean;
+    /**
+     * The completion status of a task.
+     * Applicable for: `TaskItem`.
+     */
+    checked?: boolean;
+    /**
+     * Array of rows defining the table structure.
+     * Applicable for: `Table`.
+     */
+    rows?: TableRow[];
+    /**
+     * Unique identifier for referencing.
+     * Applicable for: `FootnoteRef`.
+     */
+    id?: string;
+    /**
+     * Allows custom properties for extensions or plugin-specific data.
+     */
+    [key: string]: any;
+}
+/**
+ * A Strategy pattern for handle parsing process for each Token.
+ * @property type - Strategy's type
+ * @property execute - A function handle parsing a `Token` to `ASTNode`
+ */
+export interface ParsingStrategy {
+    type: string;
+    execute: (parser: IParser, token: Token) => ASTNode | ASTNode[] | void;
+}

package/dist/types/parser.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/renderer.d.ts

@@ -0,0 +1,12 @@
+import { IRenderer } from "../renderers";
+import { ASTNode } from "./parser";
+/**
+ * A Strategy pattern for handle parsing process for each ASTNode.
+ * @template TOutput - Output result after rendered by `render` property.
+ * @property type - Strategy's type
+ * @property execute - A function handle rendering a `ASTNode` to `TOutput`
+ */
+export interface RenderStrategy<TOutput> {
+    type: string;
+    render: (node: ASTNode, children: TOutput[], context: IRenderer<TOutput>) => TOutput;
+}

package/dist/types/renderer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/token.d.ts

@@ -1,3 +1,4 @@
+import { ILexer } from "../core/lexer";
 /**
  * Token produced by the Markdown lexer.
  *
@@ -33,77 +34,96 @@
  * - FootnodeRef: The reference of a footnote
  * - EOF: A special token, this is the end of input.
  */
-export type Token = {
-    type: "Header";
-    level: number;
-} | {
-    type: "CodeBlock";
-    lang: string;
-    content: string;
-} | {
-    type: "NewLine";
-} | {
-    type: "Bold";
-} | {
-    type: "Italic";
-} | {
-    type: "Strikethrough";
-} | {
-    type: "InlineCode";
-    content: string;
-} | {
-    type: "Quote";
-} | {
-    type: "ListStart";
-    ordered: boolean;
-    level: number;
-} | {
-    type: "ListItem";
-} | {
-    type: "TaskItem";
-    checked: boolean;
-} | {
-    type: "ListEnd";
-} | {
-    type: "Link";
-    text: string;
-    href: string;
-} | {
-    type: "Image";
-    src: string;
-    alt: string;
-} | {
-    type: "HorizontalLine";
-} | {
-    type: "Text";
-    value: string;
-} | {
-    type: "TableStart";
-} | {
-    type: "TableEnd";
-} | {
-    type: "RowStart";
-    isHeader: boolean;
-} | {
-    type: "RowEnd";
-} | {
-    type: "CellStart";
-    align: "left" | "center" | "right";
-} | {
-    type: "CellEnd";
-} | {
-    type: "HTMLBlock";
-    value: string;
-} | {
-    type: "HTMLInline";
-    value: string;
-} | {
-    type: "FootnoteDef";
-    id: string;
-    content: string;
-} | {
-    type: "FootnoteRef";
-    id: string;
-} | {
-    type: "EOF";
-};
+export type DefaultTokenType = "Header" | "CodeBlock" | "NewLine" | "Bold" | "Italic" | "Strikethrough" | "InlineCode" | "Quote" | "ListStart" | "ListItem" | "TaskItem" | "ListEnd" | "Link" | "Image" | "HorizontalLine" | "Text" | "TableStart" | "TableEnd" | "RowStart" | "RowEnd" | "CellStart" | "CellEnd" | "HTMLBlock" | "HTMLInline" | "FootnoteDef" | "FootnoteRef" | "EOF";
+export type TokenType = DefaultTokenType | (string & {});
+/**
+ * Token produced by the Markdown lexer.
+ *
+ * Tokens are the intermediate representation between raw text and the AST.
+ */
+export interface Token {
+    /**
+     * The category of the token.
+     * @see {@link DefaultTokenType} for the list of built-in types.
+     */
+    type: TokenType;
+    /**
+     * Raw text or value associated with the token.
+     * Commonly used in: `Text`, `HTMLBlock`, `HTMLInline`.
+     */
+    value?: string;
+    /**
+     * The nesting level or importance.
+     * Commonly used in: `Header` (level 1-6).
+     */
+    level?: number;
+    /**
+     * Language identifier for code fences.
+     * Commonly used in: `CodeBlock`.
+     */
+    lang?: string;
+    /**
+     * The main body of text within a token.
+     * Commonly used in: `CodeBlock`, `InlineCode`.
+     */
+    content?: string;
+    /**
+     * Destination URL for links or images.
+     * Commonly used in: `Link`, `Image`.
+     */
+    href?: string;
+    /**
+     * Display text for links.
+     * Commonly used in: `Link`.
+     */
+    text?: string;
+    /**
+     * Source path/URL for images.
+     * Commonly used in: `Image`.
+     */
+    src?: string;
+    /**
+     * Accessible alternative text.
+     * Commonly used in: `Image`.
+     */
+    alt?: string;
+    /**
+     * Alignment for table cells.
+     * Commonly used in: `CellStart` ("left", "center", "right").
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * For task lists, indicates completion.
+     * Commonly used in: `TaskItem` (true if `[x]`).
+     */
+    checked?: boolean;
+    /**
+     * Unique identifier for footnotes.
+     * Commonly used in: `FootnoteDef`, `FootnoteRef`.
+     */
+    id?: string;
+    /**
+     * All other properties used by custom `Token`.
+     */
+    [key: string]: any;
+}
+/**
+ * A Strategy pattern for handle tokenizing input.
+ * @property type - Strategy's type.
+ * @property match - A function check current cursor position matched the syntax to be processed by `emit` function.
+ * @property emit - A function handle tokenizing input to `Token`.
+ */
+export interface TokenizerStrategy {
+    name: string;
+    /**
+     * Checks if the current cursor position in the Lexer matches this syntax
+     * @param lex The current `ILexer` instance providing access to the input string and cursor.
+     * @returns True if this strategy should handle the current input.
+     */
+    match: (lex: ILexer) => boolean;
+    /**
+     * Consumes the input and produce Tokens added in ILexer implementation class.
+     * @param lex The `ILexer` instance to advance the cursor and store results.
+     */
+    emit: (lex: ILexer) => void;
+}

package/dist/utilities/parser-utils.d.ts

@@ -0,0 +1,5 @@
+import { IParser } from "../core/parser";
+import { ASTNode } from "../types/parser";
+declare function parseList(parser: IParser): ASTNode;
+declare function parseListItem(parser: IParser): ASTNode;
+export { parseList, parseListItem };

package/dist/utilities/parser-utils.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseList = parseList;
+exports.parseListItem = parseListItem;
+function parseList(parser) {
+    const tok = parser.peek(0);
+    if (tok?.type === "ListStart") {
+        parser.next(1); //skip marker
+        const result = {
+            type: "List",
+            level: tok.level,
+            ordered: tok.ordered,
+            children: [],
+        };
+        let nextToken = parser.peek(0);
+        while (!parser.isEnd()) {
+            if (nextToken?.type === "ListItem" || nextToken?.type === "TaskItem") {
+                result.children?.push(parseListItem(parser));
+                nextToken = parser.peek(0);
+            }
+            else if (nextToken?.type === "ListEnd") {
+                parser.next(1);
+                break;
+            }
+            else
+                break;
+        }
+        return result;
+    }
+    //Temp return
+    return {
+        type: "Text",
+        value: ""
+    };
+}
+function parseListItem(parser) {
+    const currentToken = parser.peek(0);
+    parser.next(1); // skip marker   
+    const children = [];
+    while (!parser.isEnd()) {
+        const tok = parser.peek(0);
+        if (!tok)
+            break;
+        if (tok.type === "NewLine") {
+            parser.next(1);
+            break;
+        }
+        if (tok.type === "ListStart") {
+            children.push(parseList(parser));
+            continue;
+        }
+        if (["ListItem", "TaskItem", "ListEnd"].includes(tok.type)) {
+            break;
+        }
+        children.push(...parser.parseInlineUntil("NewLine", true));
+    }
+    return currentToken?.type === "TaskItem" ? {
+        type: "TaskItem",
+        checked: currentToken.type === "TaskItem" ? currentToken.checked : false,
+        children: children
+    } : {
+        type: "ListItem",
+        children: children
+    };
+}

package/dist/utilities/renderer-utils.d.ts

@@ -0,0 +1,4 @@
+import { IRenderer } from "../renderers";
+import { ASTNode } from "../types/parser";
+export declare function escapeHtml(str: string): string;
+export declare function getClassName<TOutput>(renderer: IRenderer<TOutput>, node: ASTNode, defaultClass?: string): string | undefined;

package/dist/utilities/renderer-utils.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtml = escapeHtml;
+exports.getClassName = getClassName;
+function escapeHtml(str) {
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function getClassName(renderer, node, defaultClass = "") {
+    const { type, level } = node;
+    const classNames = renderer.options.renderOptions?.className;
+    if (!classNames)
+        return defaultClass || undefined;
+    if (type === "Header" && level) {
+        const levelClass = classNames[`Header${level}`];
+        if (levelClass)
+            return `${defaultClass} ${levelClass}`.trim();
+    }
+    const typeClass = classNames[type];
+    return [defaultClass, typeClass].filter(Boolean).join(" ") || undefined;
+}

package/dist/utilities/tokenizer-utils.d.ts

@@ -0,0 +1,11 @@
+import { ILexer } from "../core/lexer";
+declare function handleTextBlock(lex: ILexer): void;
+declare function handleHtmlBlock(lex: ILexer): void;
+declare function handleHtmlInline(lex: ILexer): void;
+declare function handleList(lex: ILexer, isOrdered: boolean, isTask: boolean): void;
+declare function handleStartList(lex: ILexer, isOrder: boolean): void;
+declare function handleListItem(lex: ILexer): void;
+declare function handleTaskItem(lex: ILexer, isChecked: boolean): void;
+declare function handleEndList(lex: ILexer): void;
+declare function handleTable(lex: ILexer): void;
+export { handleEndList, handleHtmlBlock, handleHtmlInline, handleList, handleListItem, handleStartList, handleTable, handleTaskItem, handleTextBlock, };