comark 0.2.0 → 0.3.0

package/dist/internal/stringify/state.js

@@ -1,5 +1,18 @@
-import { handlers } from "./handlers/index.js";
+import { handlers as defaultHandlers } from "./handlers/index.js";
 import { pascalCase } from "../../utils/index.js";
+import { resolveAttributes } from "./attributes.js";
+function findHandler(ctx, node) {
+    const userHandler = ctx.handlers[node[0]] || ctx.handlers[pascalCase(node[0])];
+    if (typeof userHandler === 'function') {
+        return userHandler;
+    }
+    for (const handler of ctx.conditionalHandlers) {
+        if (handler?.match(node)) {
+            return handler.handler;
+        }
+    }
+    return userHandler;
+}
 /**
  * Render a single node
  * @param node - The node to render
@@ -17,20 +30,39 @@ export async function one(node, state, parent) {
     if (node[0] === null) {
         return await state.handlers.comment(node, state);
     }
-    const userHandler = state.context.handlers[node[0]] || state.context.handlers[pascalCase(node[0])];
-    if (userHandler) {
-        return await userHandler(node, state, parent);
+    // Scope `renderData.props` to the current element's resolved attributes so
+    // nested bindings like `:prop="props.x"` resolve against the enclosing
+    // element's values, regardless of which handler (html / ansi / user) runs.
+    // Elements with no attributes (e.g. an auto-generated `<p>` wrapper) must
+    // NOT shadow the parent's scope, otherwise `{{ props.* }}` inside them would
+    // resolve to nothing.
+    const prevRenderData = state.renderData;
+    if (state.renderData && node[1]) {
+        const resolved = resolveAttributes(node[1], prevRenderData);
+        if (Object.keys(resolved).length > 0) {
+            state.renderData = { ...prevRenderData, props: resolved };
+        }
     }
-    if (state.context.html || node[1].$?.html === 1) {
-        return await state.handlers.html(node, state, parent);
+    try {
+        const userHandler = findHandler(state.context, node);
+        if (userHandler) {
+            return await userHandler(node, state, parent);
+        }
+        if (state.context.html || node[1].$?.html === 1) {
+            return await state.handlers.html(node, state, parent);
+        }
+        // fallback to default handlers
+        const nodeHandler = state.handlers[node[0]];
+        if (nodeHandler) {
+            return await nodeHandler(node, state, parent);
+        }
+        return state.context.format === 'markdown/comark'
+            ? await state.handlers.mdc(node, state, parent)
+            : await state.handlers.html(node, state, parent);
     }
-    const nodeHandler = state.handlers[node[0]];
-    if (nodeHandler) {
-        return await nodeHandler(node, state, parent);
+    finally {
+        state.renderData = prevRenderData;
     }
-    return state.context.format === 'markdown/comark'
-        ? await state.handlers.mdc(node, state, parent)
-        : await state.handlers.html(node, state, parent);
 }
 export async function flow(node, state, parent) {
     const children = node.slice(2);
@@ -41,20 +73,40 @@ export async function flow(node, state, parent) {
     return result;
 }
 export function createState(ctx = {}) {
+    const conditionalHandlers = [];
+    const handlers = {};
+    for (const [key, value] of Object.entries(ctx.handlers || {})) {
+        if (typeof value === 'function') {
+            handlers[key] = value;
+        }
+        else {
+            conditionalHandlers.push(value);
+        }
+    }
     const context = {
         ...ctx,
         blockSeparator: ctx.blockSeparator || '\n\n',
         format: ctx.format || 'markdown/comark',
-        handlers: ctx.handlers || {}, // user defined node handlers
+        handlers, // user defined node handlers
+        conditionalHandlers,
+        blockAttributesStyle: ctx.blockAttributesStyle || 'codeblock',
         // Enable html mode for text/html format
         html: ctx.format === 'text/html',
     };
+    const tree = ctx.tree;
+    const renderData = {
+        frontmatter: (tree?.frontmatter || {}),
+        meta: (tree?.meta || {}),
+        data: (ctx.data || {}),
+        props: {},
+    };
     const state = {
-        handlers,
+        handlers: defaultHandlers,
         context,
         one,
         flow,
         data: ctx.data || {},
+        renderData,
         render: async (input) => {
             if (Array.isArray(input) && typeof input[0] === 'string' && input.length > 1) {
                 return state.one(input, state);
@@ -77,12 +129,16 @@ export function createState(ctx = {}) {
     return state;
 }
 export const state = {
-    handlers,
+    handlers: defaultHandlers,
+    conditionalHandlers: [],
     data: {},
+    renderData: { frontmatter: {}, meta: {}, data: {}, props: {} },
     context: {
         blockSeparator: '\n\n',
         format: 'markdown/comark',
         handlers: {}, // user defined node handlers
+        conditionalHandlers: [], // user defined conditional handlers
+        blockAttributesStyle: 'codeblock',
     },
     flow,
     one,

package/dist/internal/yaml.d.ts

@@ -1,3 +1,4 @@
+import { type DumpOptions } from 'js-yaml';
 /**
  * Parse YAML content
  * @param content - The content to parse
@@ -9,4 +10,4 @@ export declare function parseYaml(content: string): Record<string, unknown>;
  * @param data - The data to stringify
  * @returns The stringified data
  */
-export declare function stringifyYaml(data: Record<string, unknown>): string;
+export declare function stringifyYaml(data: Record<string, unknown>, options?: DumpOptions): string;

package/dist/internal/yaml.js

@@ -12,9 +12,11 @@ export function parseYaml(content) {
  * @param data - The data to stringify
  * @returns The stringified data
  */
-export function stringifyYaml(data) {
+export function stringifyYaml(data, options) {
     const yamlOutput = dump(data, {
         indent: 2,
+        lineWidth: -1,
+        ...options,
         replacer: (_key, value) => {
             if (value === 'true')
                 return true;

package/dist/parse.js

@@ -91,8 +91,19 @@ export function createParse(options = {}) {
         for (const plugin of options.plugins || []) {
             await plugin.pre?.(state);
         }
-        const { content, data } = await parseFrontmatter(state.markdown);
-        state.tokens = parser.parse(content, {});
+        const { content, data } = parseFrontmatter(state.markdown);
+        try {
+            state.tokens = parser.parse(content, {});
+        }
+        catch (e) {
+            // in case of streaming, return the previous output if parsing fails
+            // This is to avoid resetting the tree to an empty state on failure
+            // resetting the tree will re-redner whole tree
+            if (opts.streaming && prevOutput) {
+                return prevOutput;
+            }
+            throw e;
+        }
         // Convert tokens to Comark structure
         let nodes = marmdownItTokensToComarkTree(state.tokens, {
             startLine: state.parsedLines,

package/dist/plugins/alert.js

@@ -1,4 +1,4 @@
-import { visit } from 'comark/utils';
+import { visit } from "../utils/index.js";
 import { defineComarkPlugin } from "../utils/helpers.js";
 const markers = {
     '!TIP': {

package/dist/plugins/binding.d.ts

@@ -0,0 +1,20 @@
+import type { NodeHandler } from '../types';
+export interface MdcInlineBindingOptions {
+    /**
+     * The tag name used to render a binding.
+     *
+     * @default 'binding'
+     */
+    tag?: string;
+}
+declare const _default: import("../types").ComarkPluginFactory<MdcInlineBindingOptions>;
+export default _default;
+/**
+ * Markdown-format handler that renders a `binding` node back to the
+ * `{{ path || default }}` source form.
+ *
+ * Wire it via `renderMarkdown(tree, { components: { Binding } })`
+ * to round-trip faithfully to the authored shorthand instead of the generic
+ * `:binding{:value="..."}` component form.
+ */
+export declare const Binding: NodeHandler;

package/dist/plugins/binding.js

@@ -0,0 +1,61 @@
+import { defineComarkPlugin } from "../utils/helpers.js";
+const markdownItInlineBinding = (md, options = {}) => {
+    const tag = options.tag || 'binding';
+    md.inline.ruler.after('entity', 'mdc_inline_binding', (state, silent) => {
+        const start = state.pos;
+        if (state.src[start] !== '{' || state.src[start + 1] !== '{')
+            return false;
+        // Find the closing `}}`
+        let end = start + 2;
+        while (end < state.posMax - 1) {
+            if (state.src[end] === '}' && state.src[end + 1] === '}')
+                break;
+            end += 1;
+        }
+        if (end >= state.posMax - 1)
+            return false;
+        const inner = state.src.slice(start + 2, end).trim();
+        if (!inner)
+            return false;
+        // Split on the first `||` to separate value and default
+        const separator = inner.indexOf('||');
+        const value = separator === -1 ? inner : inner.slice(0, separator).trim();
+        const defaultValue = separator === -1 ? '' : inner.slice(separator + 2).trim();
+        if (!value)
+            return false;
+        state.pos = end + 2;
+        if (silent)
+            return true;
+        const token = state.push('mdc_inline_component', tag, 0);
+        token.attrSet(':value', value);
+        if (defaultValue)
+            token.attrSet('defaultValue', defaultValue);
+        return true;
+    });
+};
+export default defineComarkPlugin((opts = {}) => {
+    return {
+        name: 'binding',
+        markdownItPlugins: [
+            ((md) => markdownItInlineBinding(md, opts)),
+        ],
+    };
+});
+/**
+ * Markdown-format handler that renders a `binding` node back to the
+ * `{{ path || default }}` source form.
+ *
+ * Wire it via `renderMarkdown(tree, { components: { Binding } })`
+ * to round-trip faithfully to the authored shorthand instead of the generic
+ * `:binding{:value="..."}` component form.
+ */
+export const Binding = (node) => {
+    const attrs = (node[1] || {});
+    const path = attrs[':value'];
+    if (typeof path !== 'string' || !path)
+        return '';
+    const defaultValue = attrs.defaultValue;
+    return typeof defaultValue === 'string' && defaultValue.length > 0
+        ? `{{ ${path} || ${defaultValue} }}`
+        : `{{ ${path} }}`;
+};

package/dist/plugins/breaks.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../types.ts").ComarkPluginFactory<unknown>;
+export default _default;

package/dist/plugins/breaks.js

@@ -0,0 +1,34 @@
+import { defineComarkPlugin } from "../utils/helpers.js";
+import { visit } from "../utils/index.js";
+export default defineComarkPlugin(() => ({
+    name: 'breaks',
+    post(state) {
+        visit(state.tree, node => Array.isArray(node) && node.length > 2, (node) => {
+            const parent = node;
+            const newParent = [parent[0], parent[1]];
+            let hasModified = false;
+            for (let i = 2; i < parent.length; i++) {
+                const child = parent[i];
+                if (typeof child === 'string' && child.includes('\n')) {
+                    hasModified = true;
+                    const lines = child.split('\n');
+                    lines.forEach((line, index) => {
+                        if (line.length > 0) {
+                            newParent.push(line);
+                        }
+                        if (index < lines.length - 1) {
+                            newParent.push(['br', {}]);
+                        }
+                    });
+                }
+                else {
+                    newParent.push(child);
+                }
+            }
+            if (hasModified) {
+                parent.length = 0;
+                parent.push(...newParent);
+            }
+        });
+    },
+}));

package/dist/plugins/footnotes.d.ts

@@ -0,0 +1,61 @@
+import type { ConditionalNodeHandler } from 'comark';
+export interface FootnotesConfig {
+    /**
+     * The label for the footnotes section
+     * @default 'Footnotes'
+     */
+    label?: string;
+    /**
+     * Whether to add a horizontal rule before the footnotes section
+     * @default true
+     */
+    hr?: boolean;
+    /**
+     * Back-reference symbol
+     * @default '↩'
+     */
+    backRef?: string;
+}
+/**
+ * Create footnotes plugin for comark
+ *
+ * This plugin adds support for footnote references `[^label]` and
+ * footnote definitions `[^label]: content`. Footnotes are collected
+ * and rendered as a numbered list at the end of the document.
+ *
+ * @param config Footnotes configuration
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import footnotes from 'comark/plugins/footnotes'
+ *
+ * const result = await parse('Hello[^1]\n\n[^1]: World', {
+ *   plugins: [footnotes()]
+ * })
+ * ```
+ */
+declare const _default: import("comark").ComarkPluginFactory<FootnotesConfig>;
+export default _default;
+/**
+ * Conditional stringify handler for footnotes.
+ *
+ * Converts footnote AST nodes back to standard markdown footnote syntax
+ * (`[^key]` for references, `[^key]: content` for definitions).
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import { renderMarkdown } from 'comark/render'
+ * import footnotes, { Footnote } from 'comark/plugins/footnotes'
+ *
+ * const tree = await parse('Hello[^1]\n\n[^1]: World', {
+ *   plugins: [footnotes()]
+ * })
+ *
+ * const md = await renderMarkdown(tree, {
+ *   components: { footnotes: Footnote },
+ * })
+ * ```
+ */
+export declare const Footnote: ConditionalNodeHandler;

package/dist/plugins/footnotes.js

@@ -0,0 +1,187 @@
+import { defineComarkPlugin } from "../utils/helpers.js";
+import { visit } from "../utils/index.js";
+// Regex to match footnote definitions at the start of a line:
+// [^label]: content
+const FOOTNOTE_DEF_RE = /^\[\^([^\s\]]+)\]:[ \t]?(.*)$/gm;
+/**
+ * Quick structural check: is this a ['span', {…}, string] tuple?
+ * Used as the visit() checker to avoid running the full extraction
+ * on every node in the tree.
+ */
+function maybeFootnoteRef(node) {
+    return Array.isArray(node)
+        && node[0] === 'span'
+        && node.length === 3
+        && typeof node[2] === 'string';
+}
+/**
+ * Check if a node is a footnote reference: ['span', {}, '^label']
+ * The MDC parser converts [^label] into ['span', {}, '^label']
+ * Returns the label string or null.
+ */
+function isFootnoteRef(node) {
+    // Caller should pre-check with maybeFootnoteRef for fast rejection
+    const attrs = node[1];
+    // Check attrs has no keys other than '$' — avoid Object.keys() allocation
+    for (const k in attrs) {
+        if (k !== '$')
+            return null;
+    }
+    const child = node[2];
+    // Must start with '^' and have at least one label char
+    if (child.charCodeAt(0) !== 0x5E /* ^ */ || child.length < 2)
+        return null;
+    // Check for whitespace using charCode scanning (avoid regex)
+    for (let i = 1; i < child.length; i++) {
+        const c = child.charCodeAt(i);
+        if (c === 0x20 || c === 0x09 || c === 0x0A || c === 0x0D)
+            return null;
+    }
+    return child.slice(1);
+}
+/**
+ * Create footnotes plugin for comark
+ *
+ * This plugin adds support for footnote references `[^label]` and
+ * footnote definitions `[^label]: content`. Footnotes are collected
+ * and rendered as a numbered list at the end of the document.
+ *
+ * @param config Footnotes configuration
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import footnotes from 'comark/plugins/footnotes'
+ *
+ * const result = await parse('Hello[^1]\n\n[^1]: World', {
+ *   plugins: [footnotes()]
+ * })
+ * ```
+ */
+export default defineComarkPlugin((config = {}) => {
+    const { label = 'Footnotes', hr = true, backRef = '↩', } = config;
+    return {
+        name: 'footnotes',
+        // extract footnote definitions from markdown before MDC parsing
+        pre(state) {
+            const definitions = new Map();
+            // Extract and remove footnote definitions from the source
+            state.markdown = state.markdown.replace(FOOTNOTE_DEF_RE, (_match, defLabel, content) => {
+                definitions.set(defLabel, content.trim());
+                return ''; // Remove the definition line
+            });
+            // Store on state to avoid mixing definitions across parallel parses
+            state.footnote = definitions;
+        },
+        // replace [^ref] spans and build footnotes section
+        post(state) {
+            const definitions = state.footnote;
+            if (!definitions || definitions.size === 0)
+                return;
+            const refIndexMap = new Map();
+            // Replace footnote reference spans with sup > a elements
+            visit(state.tree, maybeFootnoteRef, (node) => {
+                const refLabel = isFootnoteRef(node);
+                if (!refLabel || !definitions.has(refLabel))
+                    return;
+                if (!refIndexMap.has(refLabel)) {
+                    refIndexMap.set(refLabel, refIndexMap.size + 1);
+                }
+                const refIndex = refIndexMap.get(refLabel);
+                return ['sup', { class: 'footnote-ref' },
+                    ['a', {
+                            href: `#fn-${refLabel}`,
+                            id: `fnref-${refLabel}`,
+                        }, `[${refIndex}]`],
+                ];
+            });
+            let nodes = state.tree.nodes;
+            // Remove empty paragraphs left after definition removal
+            nodes = nodes.filter((node) => {
+                if (!Array.isArray(node) || node[0] !== 'p')
+                    return true;
+                // A paragraph with only whitespace children is considered empty
+                for (let i = 2; i < node.length; i++) {
+                    const child = node[i];
+                    if (typeof child === 'string') {
+                        if (child.trim().length > 0)
+                            return true;
+                    }
+                    else if (Array.isArray(child) && child[0] != null) {
+                        return true;
+                    }
+                }
+                return false;
+            });
+            // Build the footnotes section
+            if (refIndexMap.size === 0) {
+                state.tree.nodes = nodes;
+                return;
+            }
+            const footnoteItems = [];
+            for (const [refLabel] of refIndexMap) {
+                const content = definitions.get(refLabel);
+                footnoteItems.push(['li', { id: `fn-${refLabel}` },
+                    content, ' ',
+                    ['a', { href: `#fnref-${refLabel}`, class: 'footnote-backref' }, backRef],
+                ]);
+            }
+            const sectionChildren = [];
+            if (hr) {
+                sectionChildren.push(['hr', {}]);
+            }
+            if (label) {
+                sectionChildren.push(['h2', { id: 'footnotes' }, label]);
+            }
+            sectionChildren.push(['ol', { class: 'footnotes-list' }, ...footnoteItems]);
+            nodes.push(['section', { class: 'footnotes' }, ...sectionChildren]);
+            state.tree.nodes = nodes;
+        },
+    };
+});
+/**
+ * Conditional stringify handler for footnotes.
+ *
+ * Converts footnote AST nodes back to standard markdown footnote syntax
+ * (`[^key]` for references, `[^key]: content` for definitions).
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import { renderMarkdown } from 'comark/render'
+ * import footnotes, { Footnote } from 'comark/plugins/footnotes'
+ *
+ * const tree = await parse('Hello[^1]\n\n[^1]: World', {
+ *   plugins: [footnotes()]
+ * })
+ *
+ * const md = await renderMarkdown(tree, {
+ *   components: { footnotes: Footnote },
+ * })
+ * ```
+ */
+export const Footnote = {
+    match: (node) => {
+        return node[1].class === 'footnotes' || node[1].class === 'footnote-ref';
+    },
+    handler: (node) => {
+        if (node[1].class === 'footnotes') {
+            const ol = node.find(n => Array.isArray(n) && n[0] === 'ol');
+            if (!ol)
+                return '';
+            let result = '';
+            for (let i = 2; i < ol.length; i++) {
+                const key = String(ol[i][1]?.id)?.replace('fn-', '');
+                const value = ol[i][2];
+                result += `[^${key}]: ${value}\n`;
+            }
+            return result;
+        }
+        if (node[1].class === 'footnote-ref') {
+            const link = node[2];
+            const key = String(link[1]?.id)?.replace('fnref-', '');
+            return `[^${key}]`;
+        }
+        return '';
+    },
+};

package/dist/plugins/highlight.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageRegistration, ShikiTransformer, ShikiInternal, ThemeRegistration } from 'shiki';
+import type { LanguageRegistration, ShikiTransformer, ShikiPrimitive, ThemeRegistration } from 'shiki';
 import type { ComarkNode, ComarkTree } from 'comark';
 export interface HighlightOptions {
     /**
@@ -45,7 +45,7 @@ export interface CodeBlockAttributes {
  * Get or create the Shiki highlighter instance
  * Uses a singleton pattern to avoid creating multiple highlighters
  */
-export declare function getHighlighter(options?: HighlightOptions): Promise<ShikiInternal>;
+export declare function getHighlighter(options?: HighlightOptions): Promise<ShikiPrimitive>;
 /**
  * Highlight code using Shiki with codeToTokens
  * Returns comark nodes built from hast

package/dist/plugins/highlight.js

@@ -1,5 +1,5 @@
 import { defineComarkPlugin } from "../utils/helpers.js";
-import { createShikiInternal } from 'shiki';
+import { createShikiPrimitive } from 'shiki';
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
 import { codeToHast } from 'shiki/core';
 let highlighter = null;
@@ -24,13 +24,15 @@ export async function getHighlighter(options = {}) {
     try {
         highlighterPromise = (async () => {
             const { themes, languages } = await registerDefaults(options);
-            const hl = await createShikiInternal({
+            const hl = createShikiPrimitive({
                 themes: themes,
                 langs: languages,
                 langAlias: {
-                    md: 'mdc',
-                    markdown: 'mdc',
-                    comark: 'mdc',
+                    'md': 'mdc',
+                    'markdown': 'mdc',
+                    'comark': 'mdc',
+                    'json-render': 'json',
+                    'yaml-render': 'yaml',
                 },
                 engine: createJavaScriptRegexEngine({ forgiving: true }),
             });

package/dist/plugins/json-render.d.ts

@@ -0,0 +1,53 @@
+interface JsonRenderConfig {
+}
+/**
+ * Plugin for rendering [JSON Render](https://json-render.dev/) specs as UI components.
+ *
+ * Transforms `json-render` fenced code blocks into Comark AST nodes at parse time.
+ * Supports both full specs (with `root` and `elements`) and single-element shorthand.
+ *
+ * @param config - Plugin configuration options
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import jsonRender from 'comark/plugins/json-render'
+ *
+ * const result = await parse(`
+ * \`\`\`json-render
+ * {
+ *   "root": "card",
+ *   "elements": {
+ *     "card": {
+ *       "type": "Card",
+ *       "props": { "title": "Hello" },
+ *       "children": ["text"]
+ *     },
+ *     "text": {
+ *       "type": "Text",
+ *       "props": { "content": "World" }
+ *     }
+ *   }
+ * }
+ * \`\`\`
+ * `, {
+ *   plugins: [jsonRender()]
+ * })
+ * ```
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { Comark } from '@comark/vue'
+ * import jsonRender from '@comark/vue/plugins/json-render'
+ * </script>
+ *
+ * <template>
+ *   <Suspense>
+ *     <Comark :plugins="[jsonRender()]">{{ content }}</Comark>
+ *   </Suspense>
+ * </template>
+ * ```
+ */
+declare const _default: import("../types").ComarkPluginFactory<JsonRenderConfig>;
+export default _default;