simple-customize-markdown-converter 1.0.6 → 1.1.0

package/dist/renderers/react.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+class ReactRenderer {
+    constructor(footNoteResolver, options) {
+        this.footNoteResolver = footNoteResolver;
+        this.options = options;
+    }
+    /**
+     * Render a Node (AST) to a ReactNode according renderer options
+     *
+     * @param node - The abstract syntax tree (AST) from the Parser
+     * @returns The ReactNode representing the rendered Markdown element.
+     */
+    render(node) {
+        //Get proper handler type
+        const handler = this.handleRender(node.type);
+        //If node have children, recursive to handle all node's children
+        const children = "children" in node ? node.children.map((ele) => this.render(ele)) : [];
+        return handler(node, children);
+    }
+    /**
+     * Select the appropriate rendering handler for a specific node type
+     * @param type - The type of AST Note
+     * @returns A function take a node and its children to procude a ReactNode.
+     */
+    handleRender(type) {
+        const defaultRender = {
+            //Base structural nodes
+            Document: (_node, children) => react_1.default.createElement(react_1.default.Fragment, null, ...children, this.renderFootnotes()),
+            Paragraph: (_node, children) => react_1.default.createElement("p", null, ...children),
+            //Container nodes
+            CodeBlock: (node) => react_1.default.createElement("pre", null, react_1.default.createElement("code", { className: `lang-${node.lang}` }, node.content)),
+            Header: (node, children) => react_1.default.createElement(`h${node.level}`, { style: { borderBottom: node.level <= 2 ? "1px solid #d1d9e0b3" : undefined } }, ...children),
+            Quote: (_node, children) => react_1.default.createElement("blockquote", { style: { margin: "0", padding: "0 1em", color: "#59636e", borderLeft: ".25em solid #d1d9e0" } }, ...children),
+            //For list nodes
+            List: (node, children) => node.ordered ?
+                react_1.default.createElement("ol", null, ...children) :
+                react_1.default.createElement("ul", null, ...children),
+            ListItem: (_node, children) => react_1.default.createElement("li", null, ...children),
+            TaskItem: (node, children) => react_1.default.createElement("li", null, react_1.default.createElement("input", {
+                type: "checkbox",
+                disabled: true,
+                checked: !!node.checked,
+                readOnly: true
+            }), ...children),
+            //Styling nodes
+            Bold: (_node, children) => react_1.default.createElement("strong", null, ...children),
+            Italic: (_node, children) => react_1.default.createElement("em", null, ...children),
+            Strikethrough: (_node, children) => react_1.default.createElement("s", null, ...children),
+            InlineCode: (node) => react_1.default.createElement("code", null, node.content),
+            //Media nodes
+            Link: (node) => react_1.default.createElement("a", {
+                href: node.href,
+                //Security reason
+                target: "_blank",
+                rel: "noopener"
+            }, node.text),
+            Image: (node) => react_1.default.createElement("img", {
+                src: node.src,
+                alt: node.alt,
+            }, null),
+            //Leaf nodes
+            HorizontalLine: (_node) => react_1.default.createElement("hr"),
+            Text: (node) => node.value || "",
+            //For table nodes
+            Table: (node, children) => this.renderTable(node, children),
+            //For HTML
+            HTMLBlock: (node) => this.options.converterOptions?.allowDangerousHtml
+                ? react_1.default.createElement("div", { dangerouslySetInnerHTML: { __html: node.value } })
+                : react_1.default.createElement("code", null, node.value),
+            HTMLInline: (node) => this.options.converterOptions?.allowDangerousHtml
+                ? react_1.default.createElement("span", { dangerouslySetInnerHTML: { __html: node.value } })
+                : react_1.default.createElement("code", null, node.value),
+            //For footnote
+            FootnoteRef: (node) => {
+                const idx = this.footNoteResolver.getUsedRefById(node.id);
+                return react_1.default.createElement("sup", { id: `fnref:${idx}` }, react_1.default.createElement("a", { href: `#fn:${idx}`, className: "footnote-ref" }, `[${idx}]`));
+            }
+        };
+        return (this.options.renderOptions?.elements?.[type] ?? defaultRender[type]);
+    }
+    renderTable(node, children) {
+        if (node.type === "Table") {
+            const header = node.rows.filter(row => row.isHeader);
+            const body = node.rows.filter(row => !row.isHeader);
+            const renderRows = (row, rowIndex) => {
+                return react_1.default.createElement("tr", { key: rowIndex }, row.cells.map((cell, cellIndex) => {
+                    const tag = row.isHeader ? "th" : "td";
+                    return react_1.default.createElement(tag, { key: cellIndex, style: { textAlign: cell.align } }, ...cell.children.map(c => this.render(c)));
+                }));
+            };
+            const tHead = header.length
+                ? react_1.default.createElement("thead", null, header.map((row, i) => renderRows(row, i)))
+                : null;
+            const tBody = body.length
+                ? react_1.default.createElement("tbody", null, body.map((row, i) => renderRows(row, i)))
+                : null;
+            return react_1.default.createElement("table", null, tHead, tBody);
+        }
+        else
+            return react_1.default.createElement("p", null, ...children);
+    }
+    renderFootnotes() {
+        if (this.footNoteResolver.isResolverValid()) {
+            const used = this.footNoteResolver.getUsedRef();
+            if (used.length === 0)
+                return null;
+            const items = used.map((id, i) => {
+                const def = this.footNoteResolver.getDef(id) ?? "";
+                const idx = i + 1;
+                return react_1.default.createElement("li", { id: `fn:${idx}` }, react_1.default.createElement("p", null, def + " ", react_1.default.createElement("a", { href: `#fnref:${idx}`, className: "footnote-backref" }, "↩")));
+            });
+            return react_1.default.createElement("section", { className: "footnotes" }, react_1.default.createElement("ol", null, ...items));
+        }
+        else
+            return null;
+    }
+}
+exports.default = ReactRenderer;

package/dist/resolver.d.ts

@@ -0,0 +1,15 @@
+declare abstract class Resolver {
+    abstract isResolverValid(): boolean;
+}
+export declare class FootnoteResolver extends Resolver {
+    private defs;
+    private usedRef;
+    addDef(id: string, content: string): void;
+    addUsedRef(id: string): void;
+    resolve(id: string): string | undefined;
+    getUsedRef(): string[];
+    getUsedRefById(id: string): number;
+    getDef(id: string): string | undefined;
+    isResolverValid(): boolean;
+}
+export {};

package/dist/resolver.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FootnoteResolver = void 0;
+class Resolver {
+}
+class FootnoteResolver extends Resolver {
+    constructor() {
+        super(...arguments);
+        this.defs = new Map();
+        this.usedRef = [];
+    }
+    addDef(id, content) {
+        this.defs.set(id, content);
+    }
+    addUsedRef(id) {
+        if (!this.usedRef.includes(id)) {
+            this.usedRef.push(id);
+        }
+    }
+    resolve(id) {
+        return this.defs.get(id);
+    }
+    getUsedRef() {
+        return this.usedRef;
+    }
+    getUsedRefById(id) {
+        return this.usedRef.indexOf(id) + 1;
+    }
+    getDef(id) {
+        return this.defs.get(id);
+    }
+    isResolverValid() {
+        return this.defs.size !== 0 && this.usedRef.length !== 0;
+    }
+}
+exports.FootnoteResolver = FootnoteResolver;

package/dist/types/node.d.ts

@@ -21,6 +21,10 @@
  * - 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`
  */
 export type Node = {
     type: "Document";
@@ -79,11 +83,30 @@ export type Node = {
 } | {
     type: "Table";
     rows: TableRow[];
+} | {
+    type: "HTMLBlock";
+    value: string;
+} | {
+    type: "HTMLInline";
+    value: string;
+} | {
+    type: "FootnoteRef";
+    id: string;
 };
+/**
+ * A subtype represent a row of table
+ * @property isHeader - If this row is header
+ * @property cells: List cells of this row
+ */
 export type TableRow = {
     isHeader: boolean;
     cells: TableCell[];
 };
+/**
+ * A subtype represent a table cell
+ * @property align - Cell's align
+ * @property children - Cell's children nodes
+ */
 export type TableCell = {
     align: "left" | "center" | "right";
     children: Node[];

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

@@ -0,0 +1,11 @@
+/**
+ * General option for the render process,
+ * These rules define high-level behavior for render process.
+ */
+export type ConvertOption = {
+    /**
+     * Allow raw HTML rendered in the Markdown input.
+     * When false (default), HTML tags are escaped for security
+     */
+    allowDangerousHtml: boolean;
+};

package/dist/types/options/converterOptions.js

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

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

@@ -0,0 +1,17 @@
+import { ConvertOption } from "./converterOptions";
+import { ReactRenderOption } from "./reactRenderOptions";
+import { RenderOption } from "./renderOptions";
+/**
+ * General option for rendering Markdown into HTML strings
+ */
+export type MarkdownDefaultOptions = {
+    renderOptions?: RenderOption;
+    converterOptions?: ConvertOption;
+};
+/**
+ * General option for rendering Markdown into `React.ReactNode` elements
+ */
+export type MarkdownReactOptions = {
+    renderOptions?: ReactRenderOption;
+    converterOptions?: ConvertOption;
+};

package/dist/types/options/index.js

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

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

@@ -0,0 +1,50 @@
+import { Node } from "../node";
+/**
+ * Function type for rendering an AST node to a ReactNode.
+ *
+ * @template T - A subtype of `Node` corresponding to the render node
+ * @param node - The AST node to render
+ * @param children - An array of rendered `ReactNode` from the node's children
+ * @returns A `React.ReactNode` representation of the node
+ */
+type ReactNodeRenderer<T extends Node = Node> = (node: T, children: React.ReactNode[]) => React.ReactNode;
+/**
+ * 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 `ReactNodeRenderer` function:
+ *      - `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 `ReactNode` of its children.
+ */
+export type ReactRenderElements = {
+    [K in Node["type"]]?: ReactNodeRenderer<Extract<Node, {
+        type: K;
+    }>>;
+};
+/**
+ * Options to customize how AST nodes are renderes into ReactNode elements
+ *
+ * @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/options/reactRenderOptions.js

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

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

@@ -0,0 +1,44 @@
+import { Node } from "../node";
+/**
+ * Function type for rendering an AST node to HTML.
+ *
+ * @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
+ */
+type NodeRenderer<T extends Node = Node> = (node: T, children: string[]) => string;
+/**
+ * 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.
+ */
+export type RenderElements = {
+    [K in Node["type"]]?: NodeRenderer<Extract<Node, {
+        type: K;
+    }>>;
+};
+/**
+ * Options to customize how AST nodes are renderes into HTML
+ *
+ * @property elements - Optional custom rendered for one or more node types
+ *
+ * @example
+ * ```ts
+ * const renderOptions: RenderOption = {
+ *   elements: {
+ *     Paragraph: (_node, children) => `<div class="paragraph">${children.join("")}</div>`,
+ *     Bold: (_node, children) => `<b class="bold-text">${children.join("")}</b>`,
+ *   }
+ * }
+ * ```
+ *
+ */
+export type RenderOption = {
+    elements?: RenderElements;
+};
+export {};

package/dist/types/options/renderOptions.js

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

package/dist/types/token.d.ts

@@ -21,6 +21,16 @@
  * - Image: An image (`![alt](url)`)
  * - HorizontalLine: A horizontal line (`---` or `___` or `***`)
  * - Text: Plain text content.
+ * - TableStart: Start of a table
+ * - TableEnd: End of a table
+ * - RowStart: Start of a table row
+ * - RowEnd: End of a table row
+ * - CellStart: Start of a table cell, with it's align accroding to it's row
+ * - CellEnd: End of a table cell
+ * - HTMLBlock: A HTML block element
+ * - HTMLInline: An inline HTML element
+ * - FootnodeDef: Definition of a footnote
+ * - FootnodeRef: The reference of a footnote
  * - EOF: A special token, this is the end of input.
  */
 export type Token = {
@@ -67,8 +77,6 @@ export type Token = {
 } | {
     type: "Text";
     value: string;
-} | {
-    type: "EOF";
 } | {
     type: "TableStart";
 } | {
@@ -83,4 +91,19 @@ export type Token = {
     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";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-customize-markdown-converter",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Convert Markdown to your customize HTML",
   "keywords": [
     "markdown",
@@ -17,15 +17,34 @@
     "LICENSE",
     "README.md"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
   "scripts": {
     "test": "jest",
     "build": "tsc",
     "start": "ts-node src/index.ts"
   },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.2.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.2.0"
+  },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^24.3.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "jest": "^30.1.3",
+    "jest-environment-jsdom": "^30.2.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2"