comark 0.2.0 → 0.3.0

package/dist/plugins/json-render.js

@@ -0,0 +1,99 @@
+import { defineComarkPlugin } from "../parse.js";
+import { textContent, visit } from "../utils/index.js";
+import { parseYaml } from "../internal/yaml.js";
+function jsonRenderToAst(jrt) {
+    if (!jrt.root) {
+        jrt = {
+            root: 'template',
+            elements: { template: jrt },
+        };
+    }
+    const tree = jrt;
+    const root = tree.elements[tree.root];
+    return jsonRenderElementToAst(root, tree.elements);
+}
+function jsonRenderElementToAst(element, elements) {
+    if (element.type === 'Text') {
+        return String(element.props.content);
+    }
+    const children = element.children?.map(childName => elements[childName])
+        .filter(Boolean) || [];
+    return [
+        element.type,
+        element.props,
+        ...children.map(child => jsonRenderElementToAst(child, elements)),
+    ];
+}
+/**
+ * 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>
+ * ```
+ */
+export default defineComarkPlugin((_config = {}) => ({
+    name: 'json-render',
+    post: async (state) => {
+        visit(state.tree, node => node[0] === 'pre' && (node[1].language === 'json-render'
+            || node[1].language === 'yaml-render'), (preNode) => {
+            const language = preNode[1].language;
+            try {
+                let spec = undefined;
+                if (language === 'json-render') {
+                    spec = JSON.parse(textContent(preNode));
+                }
+                else if (language === 'yaml-render') {
+                    spec = parseYaml(textContent(preNode));
+                }
+                if (spec) {
+                    return jsonRenderToAst(spec);
+                }
+            }
+            catch {
+                // nothing to do
+            }
+        });
+    },
+}));

package/dist/plugins/punctuation.d.ts

@@ -0,0 +1,67 @@
+export interface PunctuationOptions {
+    /**
+     * Convert straight quotes to smart (curly) quotes
+     * @default true
+     */
+    quotes?: boolean | string | [string, string, string, string];
+    /**
+     * Convert -- to en-dash and --- to em-dash
+     * @default true
+     */
+    dashes?: boolean;
+    /**
+     * Convert ... to ellipsis character and normalize trailing dots after ? and !
+     * @default true
+     */
+    ellipsis?: boolean;
+    /**
+     * Convert (c), (r), (tm), +- to ©, ®, ™, ±
+     * @default true
+     */
+    symbols?: boolean;
+    /**
+     * Normalize repeated punctuation: ???? → ???, !!!! → !!!, ,, → ,
+     * @default true
+     */
+    normalize?: boolean;
+}
+/**
+ * Punctuation plugin for comark
+ *
+ * Transforms common punctuation patterns into their typographically correct Unicode characters:
+ * - Smart (curly) quotes: "text" → \u201Ctext\u201D, 'text' → \u2018text\u2019
+ * - Dashes: -- → \u2013 (en-dash), --- → \u2014 (em-dash)
+ * - Ellipsis: ... → \u2026, ?.... → ?.., !.... → !..
+ * - Symbols: (c) → \u00A9, (r) → \u00AE, (tm) → \u2122, +- → \u00B1
+ * - Normalize: ???? → ???, !!!! → !!!, ,, → ,
+ *
+ * Does not transform text inside code, pre, math, kbd, script, or style elements.
+ *
+ * Supports locale-aware quote characters via the `quotes` option:
+ * - String of 4 characters: `'«»„"'` (open double, close double, open single, close single)
+ * - Array of 4 strings: `['«\xA0', '\xA0»', '‹\xA0', '\xA0›']` for French (with nbsp)
+ *
+ * @param options Punctuation configuration
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import punctuation from 'comark/plugins/punctuation'
+ *
+ * const result = await parse('"Hello" -- world...', {
+ *   plugins: [punctuation()]
+ * })
+ *
+ * // Locale-aware quotes (Russian)
+ * const result2 = await parse('"Hello"', {
+ *   plugins: [punctuation({ quotes: '«»„"' })]
+ * })
+ *
+ * // French quotes with non-breaking spaces
+ * const result3 = await parse('"Hello"', {
+ *   plugins: [punctuation({ quotes: ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] })]
+ * })
+ * ```
+ */
+declare const _default: import("comark").ComarkPluginFactory<PunctuationOptions>;
+export default _default;

package/dist/plugins/punctuation.js

@@ -0,0 +1,236 @@
+import { defineComarkPlugin } from "../utils/helpers.js";
+const DEFAULT_QUOTES = '\u201C\u201D\u2018\u2019'; // ""''
+/** Tags whose text content should not be transformed */
+const SKIP_TAGS = new Set(['code', 'pre', 'math', 'script', 'style', 'kbd']);
+function isWhitespaceOrOpener(ch) {
+    return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r'
+        || ch === '(' || ch === '[' || ch === '{';
+}
+function isLetter(ch) {
+    return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z');
+}
+/**
+ * Single-pass O(n) text transformation — replaces punctuation patterns
+ * (ellipsis, dashes, symbols, smart quotes, normalization) in one scan with no regex.
+ * Uses slice-based string building to minimize allocations.
+ */
+function applyPunctuation(text, enableQuotes, dashes, ellipsis, symbols, normalize, openDouble, closeDouble, openSingle, closeSingle) {
+    const len = text.length;
+    let result = '';
+    let last = 0;
+    for (let i = 0; i < len; i++) {
+        const ch = text[i];
+        // Ellipsis: two or more dots → … with special handling for ?... and !...
+        if (ellipsis && ch === '.') {
+            if (i + 1 < len && text[i + 1] === '.') {
+                // Count consecutive dots
+                let end = i + 2;
+                while (end < len && text[end] === '.')
+                    end++;
+                // Check if preceded by ? or ! → collapse to ?.. or !..
+                const prev = i > 0 ? text[i - 1] : '';
+                if (prev === '?' || prev === '!') {
+                    result += text.slice(last, i) + '..';
+                }
+                else {
+                    result += text.slice(last, i) + '\u2026';
+                }
+                i = end - 1;
+                last = i + 1;
+                continue;
+            }
+        }
+        // Dashes: --- (em-dash) or -- (en-dash)
+        if (dashes && ch === '-' && i + 1 < len && text[i + 1] === '-') {
+            if (i + 2 < len && text[i + 2] === '-') {
+                result += text.slice(last, i) + '\u2014';
+                i += 2;
+            }
+            else {
+                result += text.slice(last, i) + '\u2013';
+                i += 1;
+            }
+            last = i + 1;
+            continue;
+        }
+        // Symbols: (c), (C), (r), (R), (tm), (TM), +-
+        if (symbols && ch === '(') {
+            const remaining = len - i;
+            if (remaining >= 3 && text[i + 2] === ')') {
+                const inner = text[i + 1];
+                if (inner === 'c' || inner === 'C') {
+                    result += text.slice(last, i) + '\u00A9';
+                    i += 2;
+                    last = i + 1;
+                    continue;
+                }
+                if (inner === 'r' || inner === 'R') {
+                    result += text.slice(last, i) + '\u00AE';
+                    i += 2;
+                    last = i + 1;
+                    continue;
+                }
+            }
+            if (remaining >= 4 && text[i + 3] === ')') {
+                const c1 = text[i + 1];
+                const c2 = text[i + 2];
+                if ((c1 === 't' || c1 === 'T') && (c2 === 'm' || c2 === 'M')) {
+                    result += text.slice(last, i) + '\u2122';
+                    i += 3;
+                    last = i + 1;
+                    continue;
+                }
+            }
+        }
+        if (symbols && ch === '+' && i + 1 < len && text[i + 1] === '-') {
+            result += text.slice(last, i) + '\u00B1';
+            i += 1;
+            last = i + 1;
+            continue;
+        }
+        // Normalize repeated punctuation: ???? → ???, !!!! → !!!, ,, → ,
+        if (normalize) {
+            if (ch === '?' || ch === '!') {
+                let end = i + 1;
+                while (end < len && text[end] === ch)
+                    end++;
+                const count = end - i;
+                if (count >= 4) {
+                    result += text.slice(last, i) + ch + ch + ch;
+                    i = end - 1;
+                    last = i + 1;
+                    continue;
+                }
+            }
+            if (ch === ',' && i + 1 < len && text[i + 1] === ',') {
+                // Collapse ,, (or more) to ,
+                let end = i + 2;
+                while (end < len && text[end] === ',')
+                    end++;
+                result += text.slice(last, i) + ',';
+                i = end - 1;
+                last = i + 1;
+                continue;
+            }
+        }
+        // Smart quotes
+        if (enableQuotes) {
+            if (ch === '"') {
+                const prev = i > 0 ? text[i - 1] : ' ';
+                result += text.slice(last, i) + ((isWhitespaceOrOpener(prev) || i === 0) ? openDouble : closeDouble);
+                last = i + 1;
+                continue;
+            }
+            if (ch === '\'') {
+                const prev = i > 0 ? text[i - 1] : ' ';
+                const next = i + 1 < len ? text[i + 1] : '';
+                result += text.slice(last, i);
+                // Apostrophe in contractions: letter before AND letter after
+                if (isLetter(prev) && isLetter(next)) {
+                    result += closeSingle;
+                }
+                else {
+                    result += (isWhitespaceOrOpener(prev) || i === 0) ? openSingle : closeSingle;
+                }
+                last = i + 1;
+                continue;
+            }
+        }
+    }
+    // Fast path: no substitutions were made
+    if (last === 0)
+        return text;
+    return result + text.slice(last);
+}
+/**
+ * Punctuation plugin for comark
+ *
+ * Transforms common punctuation patterns into their typographically correct Unicode characters:
+ * - Smart (curly) quotes: "text" → \u201Ctext\u201D, 'text' → \u2018text\u2019
+ * - Dashes: -- → \u2013 (en-dash), --- → \u2014 (em-dash)
+ * - Ellipsis: ... → \u2026, ?.... → ?.., !.... → !..
+ * - Symbols: (c) → \u00A9, (r) → \u00AE, (tm) → \u2122, +- → \u00B1
+ * - Normalize: ???? → ???, !!!! → !!!, ,, → ,
+ *
+ * Does not transform text inside code, pre, math, kbd, script, or style elements.
+ *
+ * Supports locale-aware quote characters via the `quotes` option:
+ * - String of 4 characters: `'«»„"'` (open double, close double, open single, close single)
+ * - Array of 4 strings: `['«\xA0', '\xA0»', '‹\xA0', '\xA0›']` for French (with nbsp)
+ *
+ * @param options Punctuation configuration
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import punctuation from 'comark/plugins/punctuation'
+ *
+ * const result = await parse('"Hello" -- world...', {
+ *   plugins: [punctuation()]
+ * })
+ *
+ * // Locale-aware quotes (Russian)
+ * const result2 = await parse('"Hello"', {
+ *   plugins: [punctuation({ quotes: '«»„"' })]
+ * })
+ *
+ * // French quotes with non-breaking spaces
+ * const result3 = await parse('"Hello"', {
+ *   plugins: [punctuation({ quotes: ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] })]
+ * })
+ * ```
+ */
+export default defineComarkPlugin((options = {}) => {
+    const { quotes = true, dashes = true, ellipsis = true, symbols = true, normalize = true, } = options;
+    // Resolve quote characters
+    let enableQuotes;
+    let openDouble;
+    let closeDouble;
+    let openSingle;
+    let closeSingle;
+    if (quotes === false) {
+        enableQuotes = false;
+        openDouble = closeDouble = openSingle = closeSingle = '';
+    }
+    else if (Array.isArray(quotes)) {
+        enableQuotes = true;
+        openDouble = quotes[0];
+        closeDouble = quotes[1];
+        openSingle = quotes[2];
+        closeSingle = quotes[3];
+    }
+    else if (typeof quotes === 'string') {
+        enableQuotes = true;
+        openDouble = quotes[0];
+        closeDouble = quotes[1];
+        openSingle = quotes[2];
+        closeSingle = quotes[3];
+    }
+    else {
+        enableQuotes = true;
+        openDouble = DEFAULT_QUOTES[0];
+        closeDouble = DEFAULT_QUOTES[1];
+        openSingle = DEFAULT_QUOTES[2];
+        closeSingle = DEFAULT_QUOTES[3];
+    }
+    return {
+        name: 'punctuation',
+        post(state) {
+            function walkNodes(nodes, startIndex, skip) {
+                for (let i = startIndex; i < nodes.length; i++) {
+                    const node = nodes[i];
+                    if (typeof node === 'string') {
+                        if (!skip) {
+                            nodes[i] = applyPunctuation(node, enableQuotes, dashes, ellipsis, symbols, normalize, openDouble, closeDouble, openSingle, closeSingle);
+                        }
+                        continue;
+                    }
+                    if (Array.isArray(node) && node[0] != null) {
+                        walkNodes(node, 2, skip || SKIP_TAGS.has(node[0]));
+                    }
+                }
+            }
+            walkNodes(state.tree.nodes, 0, false);
+        },
+    };
+});

package/dist/plugins/security.js

@@ -1,5 +1,5 @@
 import { defineComarkPlugin } from "../utils/helpers.js";
-import { visit } from 'comark/utils';
+import { visit } from "../utils/index.js";
 import { validateProps } from "../internal/props-validation.js";
 export default defineComarkPlugin((options = {}) => {
     const { blockedTags = [], allowedLinkPrefixes, allowedImagePrefixes, allowedProtocols, defaultOrigin, allowDataImages, } = options;

package/dist/render.d.ts

@@ -1,6 +1,7 @@
 import type { ComarkTree, RenderOptions, RenderMarkdownOptions } from 'comark';
-export type { NodeHandler, State, Context, RenderOptions, RenderMarkdownOptions } from './types.ts';
+export type { NodeHandler, State, Context, RenderOptions, RenderMarkdownOptions, NodeRenderData } from './types.ts';
 export { renderFrontmatter } from './internal/frontmatter.ts';
+export { resolveAttributes, resolveAttribute } from './internal/stringify/attributes.ts';
 /**
  * Generate a string from a Comark tree
  * @param tree - The Comark tree to render

package/dist/render.js

@@ -2,6 +2,8 @@ import { renderFrontmatter } from "./internal/frontmatter.js";
 import { createState, one } from "./internal/stringify/state.js";
 // Re-export frontmatter renderer
 export { renderFrontmatter } from "./internal/frontmatter.js";
+// Re-export attribute resolvers for custom handlers that want to honor `:prefix` bindings
+export { resolveAttributes, resolveAttribute } from "./internal/stringify/attributes.js";
 /**
  * Generate a string from a Comark tree
  * @param tree - The Comark tree to render
@@ -25,5 +27,5 @@ export async function render(tree, context = {}) {
  */
 export async function renderMarkdown(tree, options) {
     const content = await render(tree, { format: 'markdown/comark', ...options });
-    return renderFrontmatter(tree.frontmatter, content);
+    return renderFrontmatter(tree.frontmatter, content, options?.frontmatterOptions);
 }

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { DumpOptions } from 'js-yaml';
 import type MarkdownExit from 'markdown-exit';
 import type MarkdownIt from 'markdown-it';
 /**
@@ -48,7 +49,19 @@ export interface ComarkTree {
     frontmatter: Record<string, any>;
     meta: Record<string, any>;
 }
-interface StringifyOptions {
+export interface ContextBase {
+    /**
+     * 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;
     /**
      * @default '\n\n'
      */
@@ -57,10 +70,6 @@ interface StringifyOptions {
      * @default 'markdown/comark'
      */
     format: 'markdown/comark' | 'markdown/html' | 'text/html' | 'text';
-    /**
-     * user defined node handlers
-     */
-    handlers: Record<string, NodeHandler>;
     /**
      * @default true
      */
@@ -72,24 +81,29 @@ interface StringifyOptions {
      */
     maxInlineAttributes?: number;
     /**
-     * Additional options
+     * Default syntax for block attributes when attributes exceed `maxInlineAttributes`.
+     * - `'codeblock'` — wraps attributes in a fenced YAML code block with `[props]` label
+     * - `'frontmatter'` — wraps attributes in `---` delimiters (frontmatter style)
+     * @default 'codeblock'
      */
+    blockAttributesStyle?: 'frontmatter' | 'codeblock';
     [key: string]: unknown;
 }
-export interface Context extends StringifyOptions {
+export interface CreateContext extends ContextBase {
     /**
-     * true if node is inside html scope
+     * user defined node handlers
      */
-    html?: boolean;
+    handlers: Record<string, NodeHandler | ConditionalNodeHandler>;
+}
+export interface Context extends ContextBase {
     /**
-     * true if node is inside a list
+     * user defined node handlers
      */
-    list?: boolean;
+    handlers: Record<string, NodeHandler>;
     /**
-     * number if node is inside an ordered list
+     * The conditional handlers of the renderer
      */
-    order?: number;
-    [key: string]: unknown;
+    conditionalHandlers: ConditionalNodeHandler[];
 }
 /**
  * The NodeHandler function
@@ -99,6 +113,14 @@ export interface Context extends StringifyOptions {
  * @returns The rendered node
  */
 export type NodeHandler = (node: ComarkElement, state: State, parent?: ComarkElement) => string | Promise<string>;
+/**
+ * A node handler rule that pairs a match predicate with a handler function.
+ * When `match` returns true for a node, the associated `handler` is used to render it.
+ */
+export type ConditionalNodeHandler = {
+    match: (node: ComarkElement) => boolean;
+    handler: NodeHandler;
+};
 /**
  * The State of the renderer
  * @param handlers - The handlers of the renderer
@@ -113,6 +135,13 @@ 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>;
+    /**
+     * Render context — `{ frontmatter, meta, data, props }` — used to
+     * resolve `:prefixed` attributes that reference dot-paths in markdown.
+     * `props` is scoped to the nearest enclosing element as it's mutated during
+     * recursion.
+     */
+    renderData: NodeRenderData;
     /**
      * The context of the renderer
      */
@@ -152,7 +181,7 @@ export interface RenderOptions {
     /**
      * Additional node handlers to pass to the renderer
      */
-    components?: Record<string, NodeHandler>;
+    components?: Record<string, NodeHandler | ConditionalNodeHandler>;
     /**
      * Additional data to pass to the renderer nodes, can be used to pass pre-fetched data to the renderer nodes
      */
@@ -169,6 +198,33 @@ export interface RenderMarkdownOptions extends RenderOptions {
      * @default 3
      */
     maxInlineAttributes?: number;
+    /**
+     * Default syntax for block attributes when attributes exceed `maxInlineAttributes`.
+     * - `'codeblock'` — wraps attributes in a fenced YAML code block with `[props]` label
+     * - `'frontmatter'` — wraps attributes in `---` delimiters (frontmatter style)
+     * @default 'codeblock'
+     */
+    blockAttributesStyle?: 'frontmatter' | 'codeblock';
+    /**
+     * Options for YAML serialization of frontmatter (js-yaml DumpOptions).
+     * Defaults: indent=2, lineWidth=-1.
+     */
+    frontmatterOptions?: DumpOptions;
+}
+export interface NodeRenderData {
+    frontmatter: Record<string, unknown>;
+    /**
+     * Meta information from Comark Tree
+     */
+    meta: Record<string, unknown>;
+    /**
+     * Additional data paased to rendere
+     */
+    data: Record<string, unknown>;
+    /**
+     * Props from parent node
+     */
+    props: Record<string, unknown>;
 }
 export type MarkdownExitPlugin = (md: MarkdownExit) => void;
 export type MarkdownItPlugin = (md: MarkdownIt) => void;
@@ -256,4 +312,3 @@ export type ComarkParseFnOptions = {
  * 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/utils/index.d.ts

@@ -36,3 +36,12 @@ export declare function kebabCase(str: string): string;
  * @returns The camel case string
  */
 export declare function camelCase(str: string): string;
+/**
+ * Retrieves a value from a nested object using a dot-separated key path.
+ * @param data - The object to retrieve the value from.
+ * @param key - The dot-separated key path to the value.
+ * @returns The value at the specified key path, or `undefined` if the key path does not exist.
+ */
+export declare function get(data: unknown, key: string): unknown;
+export { resolveAttributes, resolveAttribute } from '../internal/stringify/attributes.ts';
+export type { ResolveAttributesOptions } from '../internal/stringify/attributes.ts';

package/dist/utils/index.js

@@ -147,3 +147,27 @@ function splitByCase(str) {
     return parts;
 }
 // #endregion
+// #region Object Utils
+/**
+ * Retrieves a value from a nested object using a dot-separated key path.
+ * @param data - The object to retrieve the value from.
+ * @param key - The dot-separated key path to the value.
+ * @returns The value at the specified key path, or `undefined` if the key path does not exist.
+ */
+export function get(data, key) {
+    const keys = key.split('.');
+    let value = data;
+    for (const k of keys) {
+        if (value && typeof value === 'object' && k in value) {
+            value = value[k];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return value;
+}
+// #endregion
+// Re-export the shared attribute resolvers so framework renderers can apply the
+// same `:prefix` semantics as the HTML/ANSI handlers without duplicating logic.
+export { resolveAttributes, resolveAttribute } from "../internal/stringify/attributes.js";

package/dist/vite.d.ts

@@ -0,0 +1 @@
+export * from '../src/vite'

package/dist/vite.js

@@ -0,0 +1 @@
+export * from '../src/vite.ts'