comark 0.0.1 → 0.1.1

package/dist/plugins/toc.d.ts

@@ -0,0 +1,15 @@
+import type { ComarkPlugin, ComarkTree } from 'comark';
+export interface TocLink {
+    id: string;
+    text: string;
+    depth: number;
+    children?: TocLink[];
+}
+export interface Toc {
+    title: string;
+    depth: number;
+    searchDepth: number;
+    links: TocLink[];
+}
+export declare function generateFlatToc(body: ComarkTree, options: Toc): Toc;
+export default function toc(options?: Partial<Toc>): ComarkPlugin;

package/dist/plugins/toc.js

@@ -0,0 +1,118 @@
+const TOC_TAGS = ['h2', 'h3', 'h4', 'h5', 'h6'];
+const TOC_TAGS_DEPTH = TOC_TAGS.reduce((tags, tag) => {
+    tags[tag] = Number(tag.charAt(tag.length - 1));
+    return tags;
+}, {});
+function getTag(node) {
+    if (Array.isArray(node) && node.length >= 1) {
+        return node[0];
+    }
+    return null;
+}
+function getProps(node) {
+    if (Array.isArray(node) && node.length >= 2 && typeof node[1] === 'object' && !Array.isArray(node[1])) {
+        return node[1];
+    }
+    return {};
+}
+function getChildren(node) {
+    if (Array.isArray(node) && node.length > 2) {
+        return node.slice(2);
+    }
+    return [];
+}
+function getHeaderDepth(node) {
+    const tag = getTag(node);
+    return tag ? TOC_TAGS_DEPTH[tag] || 0 : 0;
+}
+function getTocTags(depth) {
+    if (depth < 1 || depth > 5) {
+        console.warn(`\`toc.depth\` is set to ${depth}. It should be a number between 1 and 5. `);
+        depth = 1;
+    }
+    return TOC_TAGS.slice(0, depth);
+}
+function flattenNodeText(node) {
+    if (typeof node === 'string') {
+        return node;
+    }
+    if (Array.isArray(node)) {
+        return getChildren(node).reduce((text, child) => {
+            return text + flattenNodeText(child);
+        }, '');
+    }
+    return '';
+}
+function flattenNodes(nodes, maxDepth, currentDepth = 0) {
+    if (currentDepth >= maxDepth) {
+        return nodes;
+    }
+    const result = [];
+    for (const node of nodes) {
+        result.push(node);
+        if (Array.isArray(node)) {
+            const children = getChildren(node);
+            if (children.length > 0) {
+                result.push(...flattenNodes(children, maxDepth, currentDepth + 1));
+            }
+        }
+    }
+    return result;
+}
+function nestHeaders(headers) {
+    if (headers.length <= 1) {
+        return headers;
+    }
+    const toc = [];
+    let parent;
+    headers.forEach((header) => {
+        if (!parent || header.depth <= parent.depth) {
+            header.children = [];
+            parent = header;
+            toc.push(header);
+        }
+        else {
+            parent.children.push(header);
+        }
+    });
+    toc.forEach((header) => {
+        if (header.children?.length) {
+            header.children = nestHeaders(header.children);
+        }
+        else {
+            delete header.children;
+        }
+    });
+    return toc;
+}
+export function generateFlatToc(body, options) {
+    const { searchDepth, depth, title = '' } = options;
+    const tags = getTocTags(depth);
+    const allNodes = flattenNodes(body.nodes, searchDepth);
+    const headers = allNodes.filter((node) => {
+        const tag = getTag(node);
+        return tag !== null && tags.includes(tag);
+    });
+    const links = headers.map(node => ({
+        id: getProps(node).id || '',
+        depth: getHeaderDepth(node),
+        text: flattenNodeText(node),
+    }));
+    return {
+        title,
+        searchDepth,
+        depth,
+        links,
+    };
+}
+export default function toc(options = {}) {
+    const { title = '', depth = 2, searchDepth = 2, links = [] } = options;
+    return {
+        name: 'toc',
+        post(state) {
+            const toc = generateFlatToc(state.tree, { title, depth, searchDepth, links });
+            toc.links = nestHeaders(toc.links);
+            state.tree.meta.toc = toc;
+        },
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,18 @@
+import type { ComarkTree, RenderOptions, RenderMarkdownOptions } from 'comark';
+export type { NodeHandler, State, Context, RenderOptions, RenderMarkdownOptions } from './types.ts';
+export { renderFrontmatter } from './internal/frontmatter.ts';
+/**
+ * Generate a string from a Comark tree
+ * @param tree - The Comark tree to render
+ * @param context - The context of the renderer
+ * @returns The string representation of the Comark tree
+ */
+export declare function render(tree: ComarkTree, context?: RenderOptions): Promise<string>;
+/**
+ * Render Comark tree to markdown
+ *
+ * @param tree - The Comark tree to render
+ * @param options - Optional rendering options
+ * @returns The markdown string with optional frontmatter
+ */
+export declare function renderMarkdown(tree: ComarkTree, options?: RenderMarkdownOptions): Promise<string>;

package/dist/render.js

@@ -0,0 +1,29 @@
+import { renderFrontmatter } from "./internal/frontmatter.js";
+import { createState, one } from "./internal/stringify/state.js";
+// Re-export frontmatter renderer
+export { renderFrontmatter } from "./internal/frontmatter.js";
+/**
+ * Generate a string from a Comark tree
+ * @param tree - The Comark tree to render
+ * @param context - The context of the renderer
+ * @returns The string representation of the Comark tree
+ */
+export async function render(tree, context = {}) {
+    const state = createState({ ...context, tree, handlers: context.components });
+    let result = '';
+    for (const child of tree.nodes) {
+        result += await one(child, state);
+    }
+    return result.trim() + '\n';
+}
+/**
+ * Render Comark tree to markdown
+ *
+ * @param tree - The Comark tree to render
+ * @param options - Optional rendering options
+ * @returns The markdown string with optional frontmatter
+ */
+export async function renderMarkdown(tree, options) {
+    const content = await render(tree, { format: 'markdown/comark', ...options });
+    return renderFrontmatter(tree.frontmatter, content);
+}

package/dist/types.d.ts

@@ -0,0 +1,258 @@
+import type MarkdownExit from 'markdown-exit';
+import type MarkdownIt from 'markdown-it';
+/**
+ * The Comark text
+ * @param string - The text content
+ */
+export type ComarkText = string;
+/**
+ * The Comark comment
+ * @param null - The null node
+ * @param {} - The attributes of the comment
+ * @param string - The content of the comment
+ */
+export type ComarkComment = [null, {}, string];
+/**
+ * The Comark element attributes
+ * @param [key: string]: unknown - The attributes of the element
+ */
+export type ComarkElementAttributes = {
+    [key: string]: unknown;
+    $?: {
+        line?: number;
+        html?: 0 | 1;
+        block?: 0 | 1;
+    };
+};
+/**
+ * The Comark element
+ * @param string - The tag of the element
+ * @param ComarkElementAttributes - The attributes of the element
+ * @param ...ComarkNode[] - The children of the element
+ */
+export type ComarkElement = [string, ComarkElementAttributes, ...ComarkNode[]];
+/**
+ * The Comark node
+ *
+ * `ComarkElement` | `ComarkText` | `ComarkComment` - The node can be an element, text or comment
+ */
+export type ComarkNode = ComarkElement | ComarkText | ComarkComment;
+/**
+ * The Comark tree
+ * @param nodes - The nodes of the tree
+ * @param frontmatter - The frontmatter data which is the data at the top of the file
+ * @param meta - The meta data of tree, it can be used to store additional data for the tree
+ */
+export interface ComarkTree {
+    nodes: ComarkNode[];
+    frontmatter: Record<string, any>;
+    meta: Record<string, any>;
+}
+interface StringifyOptions {
+    /**
+     * @default '\n\n'
+     */
+    blockSeparator: string;
+    /**
+     * @default 'markdown/comark'
+     */
+    format: 'markdown/comark' | 'markdown/html' | 'text/html' | 'text';
+    /**
+     * user defined node handlers
+     */
+    handlers: Record<string, NodeHandler>;
+    /**
+     * @default true
+     */
+    removeLastStyle?: boolean;
+    /**
+     * Maximum number of inline attributes before switching to YAML block syntax.
+     * Set to 0 to always use YAML block syntax.
+     * @default 3
+     */
+    maxInlineAttributes?: number;
+    /**
+     * Additional options
+     */
+    [key: string]: unknown;
+}
+export interface Context extends StringifyOptions {
+    /**
+     * true if node is inside html scope
+     */
+    html?: boolean;
+    /**
+     * true if node is inside a list
+     */
+    list?: boolean;
+    /**
+     * number if node is inside an ordered list
+     */
+    order?: number;
+    [key: string]: unknown;
+}
+/**
+ * The NodeHandler function
+ * @param node - The node to render
+ * @param state - The state of the renderer
+ * @param parent - The parent node
+ * @returns The rendered node
+ */
+export type NodeHandler = (node: ComarkElement, state: State, parent?: ComarkElement) => string | Promise<string>;
+/**
+ * The State of the renderer
+ * @param handlers - The handlers of the renderer
+ * @param context - The context of the renderer
+ * @param flow - Render children of the node
+ * @param one - Render a single node
+ * @param applyContext - The applyContext of the renderer
+ * @returns The state of the renderer
+ */
+export type State = {
+    /**
+     * Additional data to pass to the renderer nodes, can be used to pass pre-fetched data to the renderer nodes
+     */
+    data: Record<string, any>;
+    /**
+     * The context of the renderer
+     */
+    context: Context;
+    /**
+     * The handlers of the renderer
+     */
+    handlers: Record<string, NodeHandler>;
+    /**
+     * Render children of the node
+     */
+    flow: (node: ComarkElement, state: State, parent?: ComarkElement) => Promise<string>;
+    /**
+     * Render a single node
+     */
+    one: (node: ComarkNode, state: State, parent?: ComarkElement) => Promise<string>;
+    /**
+     * Render the input
+     */
+    render: (input: ComarkNode[] | ComarkElement) => Promise<string>;
+    /**
+     * Apply the context
+     * @param edit - The edit to apply to the context
+     * @returns The revert of the edit
+     */
+    applyContext: (edit: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * The depth of the node in the tree
+     */
+    nodeDepthInTree?: number;
+    [key: string]: unknown;
+};
+/**
+ * The context of the renderer
+ */
+export interface RenderOptions {
+    /**
+     * Additional node handlers to pass to the renderer
+     */
+    components?: Record<string, NodeHandler>;
+    /**
+     * Additional data to pass to the renderer nodes, can be used to pass pre-fetched data to the renderer nodes
+     */
+    data?: Record<string, any>;
+    [key: string]: unknown;
+}
+/**
+ * The options for rendering markdown
+ */
+export interface RenderMarkdownOptions extends RenderOptions {
+    /**
+     * Maximum number of inline attributes before switching to YAML block syntax.
+     * Set to 0 to always use YAML block syntax.
+     * @default 3
+     */
+    maxInlineAttributes?: number;
+}
+export type MarkdownExitPlugin = (md: MarkdownExit) => void;
+export type MarkdownItPlugin = (md: MarkdownIt) => void;
+export type ComarkParsePreState = {
+    markdown: string;
+    options: ParseOptions;
+    [key: string]: any;
+};
+export type ComarkParsePostState = {
+    markdown: string;
+    tree: ComarkTree;
+    options: ParseOptions;
+    tokens: unknown[];
+    [key: string]: any;
+};
+export type ComarkPlugin = {
+    name: string;
+    markdownItPlugins?: MarkdownItPlugin[];
+    pre?: (state: ComarkParsePreState) => Promise<void> | void;
+    post?: (state: ComarkParsePostState) => Promise<void> | void;
+};
+export type ComponentManifest = (name: string) => Promise<unknown> | undefined | null;
+export interface ComarkContextProvider {
+    components: Record<string, any>;
+    componentManifest: ComponentManifest;
+}
+export interface ParseOptions {
+    /**
+     * Whether to automatically unwrap single paragraphs in container components.
+     * When enabled, if a container component (alert, card, callout, note, warning, tip, info)
+     * has only a single paragraph child, the paragraph wrapper is removed and its children
+     * become direct children of the container. This creates cleaner HTML output.
+     *
+     * @default true
+     * @example
+     * // With autoUnwrap: true (default)
+     * // <alert><strong>Text</strong></alert>
+     *
+     * // With autoUnwrap: false
+     * // <alert><p><strong>Text</strong></p></alert>
+     */
+    autoUnwrap?: boolean;
+    /**
+     * Whether to automatically close unclosed markdown and Comark components.
+     * @default true
+     */
+    autoClose?: boolean;
+    /**
+     * Whether to parse HTML tags embedded in Comark/markdown content.
+     * When enabled, HTML block and inline elements are parsed into AST nodes and can be
+     * mixed freely with Comark components and markdown syntax.
+     *
+     * @default true
+     * @example
+     * // With html: true (default) — HTML is parsed into AST nodes
+     * // Input: `<strong class="bold">text</strong>`
+     * // AST:   ['strong', { class: 'bold' }, 'text']
+     *
+     * // HTML can be mixed with Comark components:
+     * // Input:
+     * // <div>
+     * //   ::alert
+     * //   Hello <em>world</em>
+     * //   ::
+     * // </div>
+     *
+     * // With html: false — HTML tags are left as raw text / ignored
+     */
+    html?: boolean;
+    /**
+     * Additional plugins to use
+     * @default []
+     */
+    plugins?: ComarkPlugin[];
+}
+/**
+ * Type signature for the options object passed to the Comark parser function returned by createParse().
+ */
+export type ComarkParseFnOptions = {
+    streaming?: boolean;
+};
+/**
+ * Type signature for the async Comark parser function returned by createParse().
+ * Accepts a markdown string and optional parsing options, and returns a Promise of ComarkTree.
+ */
+export type ComarkParseFn = (markdown: string, opts?: ComarkParseFnOptions) => Promise<ComarkTree>;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/caret.d.ts

@@ -0,0 +1,7 @@
+import type { ComarkElement } from '../';
+interface CaretOptions {
+    class?: string;
+}
+export declare function getCaret(options: boolean | CaretOptions): ComarkElement | null;
+export declare function findLastTextNodeAndAppendNode(parent: ComarkElement, nodeToAppend: ComarkElement): boolean;
+export {};

package/dist/utils/caret.js

@@ -0,0 +1,36 @@
+const CARET_TEXT = ' '; // thin space is used to avoid wide spaces between text and caret
+const CARET_STYLE = 'background-color: currentColor; display: inline-block; margin-left: 0.25rem; margin-right: 0.25rem; animation: pulse 0.75s cubic-bezier(0.4,0,0.6,1) infinite;';
+export function getCaret(options) {
+    if (options === true) {
+        return ['span', { key: 'stream-caret', style: CARET_STYLE }, CARET_TEXT];
+    }
+    if (typeof options === 'object') {
+        return [
+            'span',
+            {
+                key: 'stream-caret',
+                ...(options.class ? { class: options.class } : { style: CARET_STYLE }),
+            },
+            CARET_TEXT,
+        ];
+    }
+    return null;
+}
+export function findLastTextNodeAndAppendNode(parent, nodeToAppend) {
+    // Traverse nodes backwards to find the last text node
+    for (let i = parent.length - 1; i >= 2; i--) {
+        const node = parent[i];
+        if (typeof node === 'string' && parent[1]?.key !== 'stream-caret') {
+            // Found a text node - insert stream indicator after it
+            parent.push(nodeToAppend);
+            return true;
+        }
+        if (Array.isArray(node)) {
+            // This is an element node - recursively check its children
+            if (findLastTextNodeAndAppendNode(node, nodeToAppend)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,38 @@
+import type { ComarkNode, ComarkTree } from 'comark';
+/**
+ * Get the text content of a Comark node
+ *
+ * @param node - The Comark node
+ * @param options - The options
+ * @param options.decodeUnicodeEntities - Whether to decode Unicode entities
+ * @returns The text content
+ */
+export declare function textContent(node: ComarkNode, options?: {
+    decodeUnicodeEntities?: boolean;
+}): string;
+/**
+ * Visit a Comark tree and apply a visitor function to each node
+ *
+ * @param tree - The Comark tree
+ * @param checker - A function that checks if a node should be visited
+ * @param visitor - A function that visits a node
+ */
+export declare function visit(tree: ComarkTree, checker: (node: ComarkNode) => boolean, visitor: (node: ComarkNode) => ComarkNode | false | undefined | void): void;
+/**
+ * Convert a string to pascal case
+ * @param str - The string to convert
+ * @returns The pascal case string
+ */
+export declare function pascalCase(str: string): string;
+/**
+ * Convert a string to kebab case
+ * @param str - The string to convert
+ * @returns The kebab case string
+ */
+export declare function kebabCase(str: string): string;
+/**
+ * Convert a string to camel case
+ * @param str - The string to convert
+ * @returns The camel case string
+ */
+export declare function camelCase(str: string): string;

package/dist/utils/index.js

@@ -0,0 +1,149 @@
+// #region Tree Utils
+import { decodeHTML } from 'entities';
+/**
+ * Get the text content of a Comark node
+ *
+ * @param node - The Comark node
+ * @param options - The options
+ * @param options.decodeUnicodeEntities - Whether to decode Unicode entities
+ * @returns The text content
+ */
+export function textContent(node, options = {}) {
+    if (typeof node === 'string') {
+        if (options.decodeUnicodeEntities) {
+            return decodeHTML(node);
+        }
+        return node;
+    }
+    let out = '';
+    const len = node.length;
+    for (let i = 2; i < len; i++) {
+        out += textContent(node[i], options);
+    }
+    return out;
+}
+/**
+ * Visit a Comark tree and apply a visitor function to each node
+ *
+ * @param tree - The Comark tree
+ * @param checker - A function that checks if a node should be visited
+ * @param visitor - A function that visits a node
+ */
+export function visit(tree, checker, 
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+visitor) {
+    function walk(node, parent, index) {
+        let currentNode = node;
+        if (checker(node)) {
+            const res = visitor(node);
+            if (res === false) {
+                // remove the node from the parent
+                parent.splice(index, 1);
+                return true; // signal that node was removed
+            }
+            if (res !== undefined) {
+                parent[index] = res;
+                currentNode = res;
+            }
+        }
+        if (Array.isArray(currentNode) && currentNode.length > 2) {
+            // Use a while loop to handle removals correctly - don't increment if node was removed
+            let i = 2;
+            while (i < currentNode.length) {
+                const childRemoved = walk(currentNode[i], currentNode, i);
+                if (childRemoved) {
+                    // If removed, i stays the same (next node is now at this index)
+                    continue;
+                }
+                i += 1;
+            }
+        }
+        return false;
+    }
+    // Use a while loop to handle removals correctly - don't increment if node was removed
+    let i = 0;
+    while (i < tree.nodes.length) {
+        const removed = walk(tree.nodes[i], tree.nodes, i);
+        if (removed) {
+            // If removed, i stays the same (next node is now at this index)
+            continue;
+        }
+        i += 1;
+    }
+}
+// #region String Utils
+/**
+ * Convert a string to pascal case
+ * @param str - The string to convert
+ * @returns The pascal case string
+ */
+export function pascalCase(str) {
+    return str ? splitByCase(str).map(p => p[0].toUpperCase() + p.slice(1)).join('') : '';
+}
+/**
+ * Convert a string to kebab case
+ * @param str - The string to convert
+ * @returns The kebab case string
+ */
+export function kebabCase(str) {
+    return str ? splitByCase(str).map(p => p.toLowerCase()).join('-') : '';
+}
+/**
+ * Convert a string to camel case
+ * @param str - The string to convert
+ * @returns The camel case string
+ */
+export function camelCase(str) {
+    if (!str) {
+        return '';
+    }
+    str = pascalCase(str);
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+// split a string by case
+function splitByCase(str) {
+    const parts = [];
+    if (!str) {
+        return parts;
+    }
+    let buff = '';
+    let previousUpper;
+    let previousSplitter;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        // Fast splitter check using direct character comparisons
+        const isSplitter = char === '-' || char === '_' || char === '/' || char === '.';
+        if (isSplitter === true) {
+            parts.push(buff);
+            buff = '';
+            previousUpper = void 0;
+            continue;
+        }
+        // Fast number check using character codes
+        const charCode = char.charCodeAt(0);
+        const isNumber = charCode >= 48 && charCode <= 57; // '0' to '9'
+        // Fast uppercase check using character codes
+        const isUpper = isNumber ? void 0 : (charCode >= 65 && charCode <= 90); // 'A' to 'Z'
+        if (previousSplitter === false) {
+            if (previousUpper === false && isUpper === true) {
+                parts.push(buff);
+                buff = char;
+                previousUpper = isUpper;
+                continue;
+            }
+            if (previousUpper === true && isUpper === false && buff.length > 1) {
+                const lastChar = buff[buff.length - 1];
+                parts.push(buff.slice(0, buff.length - 1));
+                buff = lastChar + char;
+                previousUpper = isUpper;
+                continue;
+            }
+        }
+        buff += char;
+        previousUpper = isUpper;
+        previousSplitter = isSplitter;
+    }
+    parts.push(buff);
+    return parts;
+}
+// #endregion