npm - comark - Versions diffs - 0.3.2 → 0.5.0 - Mend

comark 0.3.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (78) hide show

package/README.md +25 -1
package/dist/context.d.ts +78 -0
package/dist/context.js +127 -0
package/dist/devtools/bridge.d.ts +1 -0
package/dist/devtools/bridge.js +1 -0
package/dist/devtools/constants.d.ts +1 -0
package/dist/devtools/constants.js +1 -0
package/dist/devtools/renderer/dom.d.ts +1 -0
package/dist/devtools/renderer/dom.js +1 -0
package/dist/devtools/renderer/index.d.ts +2 -0
package/dist/devtools/renderer/index.js +2 -0
package/dist/devtools/renderer/output.d.ts +1 -0
package/dist/devtools/renderer/output.js +1 -0
package/dist/devtools/renderer/panel.d.ts +1 -0
package/dist/devtools/renderer/panel.js +1 -0
package/dist/devtools/renderer/styles.d.ts +1 -0
package/dist/devtools/renderer/styles.js +1 -0
package/dist/devtools/renderer/theme.d.ts +1 -0
package/dist/devtools/renderer/theme.js +1 -0
package/dist/devtools/types.d.ts +1 -0
package/dist/devtools/types.js +1 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +2 -0
package/dist/internal/parse/auto-close/index.js +96 -31
package/dist/internal/parse/auto-unwrap.js +5 -1
package/dist/internal/parse/html/html_block_rule.js +9 -15
package/dist/internal/parse/html/index.d.ts +1 -0
package/dist/internal/parse/html/index.js +1 -1
package/dist/internal/parse/token-processor.js +70 -32
package/dist/internal/stringify/attributes.d.ts +8 -1
package/dist/internal/stringify/attributes.js +53 -0
package/dist/internal/stringify/handlers/blockquote.js +17 -0
package/dist/internal/stringify/handlers/heading.js +6 -1
package/dist/internal/stringify/handlers/html.js +8 -2
package/dist/internal/stringify/handlers/li.js +19 -9
package/dist/internal/stringify/handlers/mdc.js +1 -1
package/dist/internal/stringify/handlers/ol.js +15 -2
package/dist/internal/stringify/handlers/p.js +4 -0
package/dist/internal/stringify/handlers/pre.js +11 -2
package/dist/internal/stringify/handlers/table.js +7 -0
package/dist/internal/stringify/handlers/template.js +4 -1
package/dist/internal/stringify/handlers/ul.js +11 -1
package/dist/internal/stringify/state.js +13 -1
package/dist/parse.d.ts +4 -4
package/dist/parse.js +7 -3
package/dist/plugins/alert.d.ts +1 -1
package/dist/plugins/binding.d.ts +1 -1
package/dist/plugins/breaks.d.ts +1 -1
package/dist/plugins/emoji.d.ts +1 -1
package/dist/plugins/footnotes.d.ts +1 -1
package/dist/plugins/headings.d.ts +19 -8
package/dist/plugins/headings.js +25 -15
package/dist/plugins/highlight.d.ts +1 -1
package/dist/plugins/highlight.js +4 -2
package/dist/plugins/json-render.d.ts +1 -1
package/dist/plugins/math.d.ts +1 -1
package/dist/plugins/mermaid.d.ts +1 -1
package/dist/plugins/punctuation.d.ts +1 -1
package/dist/plugins/security.d.ts +12 -1
package/dist/plugins/security.js +13 -6
package/dist/plugins/summary.d.ts +4 -1
package/dist/plugins/syntax.d.ts +1 -1
package/dist/plugins/syntax.js +95 -36
package/dist/plugins/task-list.d.ts +1 -1
package/dist/plugins/toc.d.ts +3 -1
package/dist/render.d.ts +6 -2
package/dist/render.js +2 -2
package/dist/types.d.ts +61 -12
package/dist/utils/helpers.d.ts +16 -4
package/dist/utils/helpers.js +15 -3
package/dist/utils/index.d.ts +3 -1
package/dist/utils/index.js +30 -14
package/package.json +6 -3
package/skills/comark/references/rendering-svelte.md +51 -7
package/dist/internal/stringify/indent.d.ts +0 -1
package/dist/internal/stringify/indent.js +0 -1
package/dist/vite.d.ts +0 -1
package/dist/vite.js +0 -1

package/dist/types.d.ts CHANGED Viewed

@@ -1,6 +1,12 @@
 import type { DumpOptions } from 'js-yaml';
 import type MarkdownExit from 'markdown-exit';
 import type MarkdownIt from 'markdown-it';
+/**
+ * The `[keyof T] extends [never]` form (rather than `keyof T extends never`)
+ * is the standard trick to prevent TS from distributing the check over a
+ * union — we want to test "is T's keyset empty?" as one yes/no question.
+ */
+type Writable<T> = [keyof T] extends [never] ? Record<string, any> : T;
 /**
  * The Comark text
  * @param string - The text content
@@ -43,11 +49,14 @@ export type ComarkNode = ComarkElement | ComarkText | ComarkComment;
  * @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
+ *
+ * The `TMeta` and `TFrontmatter` type parameters allow `parse` / `createParse`
+ * to surface plugin-contributed keys with narrow types (see `MergePluginMeta`).
  */
-export interface ComarkTree {
+export interface ComarkTree<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> {
     nodes: ComarkNode[];
-    frontmatter: Record<string, any>;
-    meta: Record<string, any>;
+    frontmatter: TFrontmatter;
+    meta: TMeta;
 }
 export interface ContextBase {
     /**
@@ -234,26 +243,60 @@ export type ComarkParsePreState = {
     options: ParseOptions;
     [key: string]: any;
 };
-export type ComarkParsePostState = {
+export type ComarkParsePostState<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> = {
     markdown: string;
-    tree: ComarkTree;
+    tree: ComarkTree<TMeta, TFrontmatter>;
     options: ParseOptions;
     tokens: unknown[];
     [key: string]: any;
 };
-export type ComarkPlugin = {
+/**
+ * A Comark plugin.
+ *
+ * `TMeta` / `TFrontmatter` are phantom type parameters that record what this
+ * plugin contributes to `tree.meta` / `tree.frontmatter`. They are surfaced
+ * only via the optional `__meta` / `__frontmatter` markers — implementations
+ * never set these at runtime; they exist purely so the contribution survives
+ * `ReturnType<typeof factory>` inference and can be merged in `createParse`.
+ */
+export type ComarkPlugin<TMeta = {}, TFrontmatter = {}> = {
     name: string;
     markdownItPlugins?: MarkdownItPlugin[];
     pre?: (state: ComarkParsePreState) => Promise<void> | void;
-    post?: (state: ComarkParsePostState) => Promise<void> | void;
+    post?: (state: ComarkParsePostState<Writable<TMeta>, Writable<TFrontmatter>>) => Promise<void> | void;
+    /** Phantom — used for type inference only. Never set at runtime. */
+    __meta?: TMeta;
+    /** Phantom — used for type inference only. Never set at runtime. */
+    __frontmatter?: TFrontmatter;
 };
-export type ComarkPluginFactory<Options> = (opts?: Options) => ComarkPlugin;
-export type ComponentManifest = (name: string) => Promise<unknown> | undefined | null;
+export type ComarkPluginFactory<Options, TMeta = {}, TFrontmatter = {}> = (opts?: Options) => ComarkPlugin<TMeta, TFrontmatter>;
+type PluginMetaOf<P> = P extends ComarkPlugin<infer M, any> ? M : {};
+type PluginFrontmatterOf<P> = P extends ComarkPlugin<any, infer F> ? F : {};
+/**
+ * Walk a tuple of plugins and intersect their meta contributions.
+ * Returns `{}` when the tuple is empty or when nothing was contributed.
+ */
+export type MergePluginMeta<TPlugins extends readonly unknown[]> = TPlugins extends readonly [infer Head, ...infer Rest] ? PluginMetaOf<Head> & MergePluginMeta<Rest extends readonly unknown[] ? Rest : []> : {};
+/**
+ * Walk a tuple of plugins and intersect their frontmatter contributions.
+ */
+export type MergePluginFrontmatter<TPlugins extends readonly unknown[]> = TPlugins extends readonly [
+    infer Head,
+    ...infer Rest
+] ? PluginFrontmatterOf<Head> & MergePluginFrontmatter<Rest extends readonly unknown[] ? Rest : []> : {};
+/**
+ * When no plugin contributed meta keys, fall back to the permissive
+ * `Record<string, any>` (backwards-compatible). Otherwise, preserve narrow
+ * keys and type unknown accesses as `unknown` (safer than `any`).
+ */
+export type ResolvedMeta<T> = [keyof T] extends [never] ? Record<string, any> : T & Record<string, unknown>;
+export type ResolvedFrontmatter<T> = [keyof T] extends [never] ? Record<string, any> : T & Record<string, unknown>;
+export type ComponentManifest = (name: string) => unknown | Promise<unknown> | undefined | null;
 export interface ComarkContextProvider {
     components: Record<string, any>;
     componentManifest: ComponentManifest;
 }
-export interface ParseOptions {
+export interface ParseOptions<TPlugins extends readonly ComarkPlugin<any, any>[] = readonly ComarkPlugin<any, any>[]> {
     /**
      * Whether to automatically unwrap single paragraphs in container components.
      * When enabled, if a container component (alert, card, callout, note, warning, tip, info)
@@ -296,11 +339,16 @@ export interface ParseOptions {
      * // With html: false — HTML tags are left as raw text / ignored
      */
     html?: boolean;
+    /**
+     * Set `false` to disable autoconvert URL-like text to links.
+     * @default true
+     */
+    linkify?: boolean;
     /**
      * Additional plugins to use
      * @default []
      */
-    plugins?: ComarkPlugin[];
+    plugins?: TPlugins;
 }
 /**
  * Type signature for the options object passed to the Comark parser function returned by createParse().
@@ -312,4 +360,5 @@ export type ComarkParseFnOptions = {
  * 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 type ComarkParseFn<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> = (markdown: string, opts?: ComarkParseFnOptions) => Promise<ComarkTree<TMeta, TFrontmatter>>;
+export {};

package/dist/utils/helpers.d.ts CHANGED Viewed

@@ -5,8 +5,20 @@ import type { ComarkPluginFactory } from '../types.ts';
  */
 export declare function createSerializedTask<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
 /**
- * Define a Comark plugin
- * @param fn - The plugin factory function
- * @returns The defined plugin
+ * Define a Comark plugin.
+ *
+ * `TMeta` and `TFrontmatter` declare what the plugin contributes to
+ * `tree.meta` / `tree.frontmatter`. They are inferred from the factory's
+ * return type when set via the `__meta` / `__frontmatter` phantom markers,
+ * or can be passed explicitly. Plugins that don't contribute typed keys can
+ * omit them entirely.
+ *
+ * @example
+ * ```ts
+ * defineComarkPlugin<Options, { toc: Toc }>((opts) => ({
+ *   name: 'toc',
+ *   post(state) { state.tree.meta.toc = ... },
+ * }))
+ * ```
  */
-export declare function defineComarkPlugin<Options>(fn: ComarkPluginFactory<Options>): ComarkPluginFactory<Options>;
+export declare function defineComarkPlugin<Options, TMeta = {}, TFrontmatter = {}>(fn: ComarkPluginFactory<Options, TMeta, TFrontmatter>): ComarkPluginFactory<Options, TMeta, TFrontmatter>;

package/dist/utils/helpers.js CHANGED Viewed

@@ -11,9 +11,21 @@ export function createSerializedTask(fn) {
 }
 // #region define plugin
 /**
- * Define a Comark plugin
- * @param fn - The plugin factory function
- * @returns The defined plugin
+ * Define a Comark plugin.
+ *
+ * `TMeta` and `TFrontmatter` declare what the plugin contributes to
+ * `tree.meta` / `tree.frontmatter`. They are inferred from the factory's
+ * return type when set via the `__meta` / `__frontmatter` phantom markers,
+ * or can be passed explicitly. Plugins that don't contribute typed keys can
+ * omit them entirely.
+ *
+ * @example
+ * ```ts
+ * defineComarkPlugin<Options, { toc: Toc }>((opts) => ({
+ *   name: 'toc',
+ *   post(state) { state.tree.meta.toc = ... },
+ * }))
+ * ```
  */
 export function defineComarkPlugin(fn) {
     return fn;

package/dist/utils/index.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import type { ComarkNode, ComarkTree } from 'comark';
+type VisitResult = ComarkNode | false | undefined | void;
 /**
  * Get the text content of a Comark node
  *
@@ -17,7 +18,8 @@ export declare function textContent(node: ComarkNode, options?: {
  * @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;
+export declare function visit(tree: ComarkTree, checker: (node: ComarkNode) => boolean, visitor: (node: ComarkNode) => VisitResult): void;
+export declare function visitAsync(tree: ComarkTree, checker: (node: ComarkNode) => boolean, visitor: (node: ComarkNode) => Promise<VisitResult> | VisitResult): Promise<void>;
 export declare function indent(text: string, { ignoreFirstLine, level, width }?: {
     ignoreFirstLine?: boolean;
     level?: number;

package/dist/utils/index.js CHANGED Viewed

@@ -22,20 +22,11 @@ export function textContent(node, 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) {
+function* walkGenerator(tree, checker) {
+    function* walk(node, parent, index) {
         let currentNode = node;
         if (checker(node)) {
-            const res = visitor(node);
+            const res = yield node;
             if (res === false) {
                 // remove the node from the parent
                 ;
@@ -52,7 +43,7 @@ visitor) {
             // 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);
+                const childRemoved = yield* walk(currentNode[i], currentNode, i);
                 if (childRemoved) {
                     // If removed, i stays the same (next node is now at this index)
                     continue;
@@ -65,7 +56,7 @@ visitor) {
     // 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);
+        const removed = yield* walk(tree.nodes[i], tree.nodes, i);
         if (removed) {
             // If removed, i stays the same (next node is now at this index)
             continue;
@@ -73,6 +64,31 @@ visitor) {
         i += 1;
     }
 }
+/**
+ * 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) {
+    const iterator = walkGenerator(tree, checker);
+    let step = iterator.next();
+    while (!step.done) {
+        const res = visitor(step.value);
+        step = iterator.next(res);
+    }
+}
+export async function visitAsync(tree, checker, visitor) {
+    const iterator = walkGenerator(tree, checker);
+    let step = iterator.next();
+    while (!step.done) {
+        const res = await visitor(step.value);
+        step = iterator.next(res);
+    }
+}
 // #region String Utils
 export function indent(text, { ignoreFirstLine = false, level = 1, width } = {}) {
     const pad = width ? ' '.repeat(width) : '  '.repeat(level);

package/package.json CHANGED Viewed

@@ -1,13 +1,15 @@
 {
   "name": "comark",
-  "version": "0.3.2",
-  "description": "Components in Markdown (Comark) parser with streaming support for Vue, React, Svelte and HTML",
+  "version": "0.5.0",
+  "description": "Components in Markdown (Comark) parser with streaming support for Vue, React, Svelte, Angular and HTML",
   "keywords": [
+    "angular",
     "markdown",
     "mdc",
     "parser",
     "react",
     "streaming",
+    "svelte",
     "vue"
   ],
   "homepage": "https://comark.dev",
@@ -25,6 +27,7 @@
     "skills"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +55,7 @@
     "github-slugger": "^2.0.0",
     "hast-util-to-string": "^3.0.1",
     "minimark": "0.2.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "twoslash": "^0.3.6",
     "vitest": "^4.1.4"
   },

package/skills/comark/references/rendering-svelte.md CHANGED Viewed

@@ -48,9 +48,9 @@ Map custom Svelte components to Comark elements:
 ```svelte
 <script lang="ts">
   import { Comark } from '@comark/svelte'
-  import CustomHeading from './CustomHeading.svelte'
-  import CustomAlert from './CustomAlert.svelte'
-  import CustomCard from './CustomCard.svelte'
+  import CustomHeading from './components/comark/CustomHeading.svelte'
+  import CustomAlert from './components/comark/CustomAlert.svelte'
+  import CustomCard from './components/comark/CustomCard.svelte'
   const customComponents = {
     h1: CustomHeading,
@@ -127,9 +127,9 @@ Load components dynamically using `componentsManifest`:
   import { Comark } from '@comark/svelte'
   const componentMap: Record<string, () => Promise<any>> = {
-    'alert': () => import('./Alert.svelte'),
-    'card': () => import('./Card.svelte'),
-    'button': () => import('./Button.svelte'),
+    'alert': () => import('./components/comark/Alert.svelte'),
+    'card': () => import('./components/comark/Card.svelte'),
+    'button': () => import('./components/comark/Button.svelte'),
   }
   async function loadComponent(name: string) {
@@ -144,6 +144,50 @@ Load components dynamically using `componentsManifest`:
 <Comark markdown={content} componentsManifest={loadComponent} />
 ```
+In SvelteKit projects, keep components rendered from Markdown in a dedicated folder such as `$lib/components/comark/`. This keeps Comark-rendered components separate from normal app UI components and makes `componentsManifest` globs easier to audit.
+For SvelteKit SSR with non-eager lazy components, use `ComarkAsync` and a manifest that returns dynamic imports. An explicit map is the easiest option to audit:
+```svelte
+<script lang="ts">
+  import { ComarkAsync } from '@comark/svelte/async'
+  const componentMap: Record<string, () => Promise<any>> = {
+    'alert': () => import('$lib/components/comark/Alert.svelte'),
+    'lazy-card': () => import('$lib/components/comark/LazyCard.svelte'),
+  }
+  const componentsManifest = (name: string) => componentMap[name]?.()
+</script>
+<svelte:boundary>
+  <ComarkAsync markdown={content} {componentsManifest} />
+</svelte:boundary>
+```
+Use `import.meta.glob` when you want the manifest to cover every Svelte component in a folder:
+```svelte
+<script lang="ts">
+  import { ComarkAsync } from '@comark/svelte/async'
+  import { pascalCase } from '@comark/svelte/utils'
+  const modules = import.meta.glob('../lib/components/comark/*.svelte')
+  const componentsManifest = (name: string) => {
+    return modules[`../lib/components/comark/${pascalCase(name)}.svelte`]?.()
+  }
+</script>
+<svelte:boundary>
+  <ComarkAsync markdown={content} {componentsManifest} />
+</svelte:boundary>
+```
+Omit the boundary `pending` snippet when you want SvelteKit SSR to wait and include the resolved lazy components in the initial HTML.
+Use eager/static components with `ComarkRenderer` when you need stable SSR without Svelte's experimental async support.
 ---
 ## Slots Support
@@ -319,7 +363,7 @@ Override native HTML elements using the `Prose` prefix:
 ## Experimental Async
-The `ComarkAsync` component uses Svelte's experimental `await` in `$derived` for a declarative approach. Requires `experimental.async` in your Svelte config:
+The `ComarkAsync` component uses Svelte's experimental `await` in `$derived` for a declarative approach. It can also await async `componentsManifest` entries during SSR, so lazy dynamic imports render into SvelteKit server HTML. Requires `experimental.async` in your Svelte config:
 ```js
 // svelte.config.js

package/dist/internal/stringify/indent.d.ts DELETED Viewed

	@@ -1 +0,0 @@
1	- export * from '../../../src/internal/stringify/indent'

package/dist/internal/stringify/indent.js DELETED Viewed

	@@ -1 +0,0 @@
1	- export * from '../../../src/internal/stringify/indent.ts'

package/dist/vite.d.ts DELETED Viewed

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

package/dist/vite.js DELETED Viewed

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