@nuxtjs/mdc 0.9.2 → 0.9.3

package/README.md

@@ -19,6 +19,7 @@ MDC supercharges regular Markdown to write documents interacting deeply with any
 - Unwrap any generated content (ex: `<p>` added by each Markdown paragraph)
 - Use Vue components with named slots
 - Support inline components
+- Support asynchronous rendering of nested components
 - Add attributes and classes to inline HTML tags
 
 Learn more about the MDC syntax on https://content.nuxtjs.org/guide/writing/mdc
@@ -260,6 +261,59 @@ export default defineNuxtConfig({
 
 Checkout [`ModuleOptions` types↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/types.ts).
 
+---
+
+## Render nested async components
+
+The `MDCRenderer` also supports rendering _nested_ async components by waiting for any child component in its tree to resolve its top-level `async setup()`.
+
+This behavior allows for rendering asynchronous [MDC block components](https://content.nuxt.com/usage/markdown#block-components) (e.g. via `defineAsyncComponent`) as well as introducing components that themselves internally utilize the `MDCRenderer` to render markdown before allowing the parent component to resolve.
+
+In order for the parent `MDCRenderer` component to properly wait for the child async component(s) to resolve:
+
+1. All functionality in the child component **must** be executed within an async setup function with top-level `await` (if no async/await behavior is needed in the child, e.g. no data fetching, then the component will resolve normally).
+2. The child component's `template` content **should** be wrapped with the built-in [`Suspense` component](https://vuejs.org/guide/built-ins/suspense.html#suspense) with the [`suspensible` prop](https://vuejs.org/guide/built-ins/suspense.html#nested-suspense) set to `true`.
+
+    ```vue
+    <template>
+      <Suspense suspensible>
+        <pre>{{ data }}</pre>
+      </Suspense>
+    </template>
+
+    <script setup>
+    const { data } = await useAsyncData(..., {
+      immediate: true, // This is the default, but is required for this functionality
+    })
+    </script>
+    ```
+
+    In a Nuxt application, this means that setting `immediate: false` on any `useAsyncData` or `useFetch` calls would _prevent_ the parent `MDCRenderer` from waiting and the parent would potentially resolve before the child components have finished rendering, causing hydration errors or missing content.
+
+### Simple Example: Async Component
+
+Your nested MDC block components can utilize top-level `async setup()` as part of their lifecycle, such as awaiting data fetching before allowing the parent component to resolve.
+
+See the code in the playground [`AsyncComponent` component](/playground/components/global/AsyncComponent.vue) as an example, and to see the behavior in action, check out the playground by running `pnpm dev` and navigating to the `/async-components` route.
+
+### Advanced Example: MDC "snippets"
+
+To demonstrate how powerful these nested async block components can be, you could allow users to define a subset of markdown documents in your project that will be utilized as reusable "snippets" in a parent document.
+
+You would create a custom block component in your project that handles fetching the snippet markdown content from the API, use `parseMarkdown` to get the `ast` nodes, and render it in its own `MDC` or `MDCRenderer` component.
+
+See the code in the playground [`PageSnippet` component](/playground/components/global/PageSnippet.vue) as an example, and to see the behavior in action, check out the playground by running `pnpm dev` and navigating to the `/async-components/advanced` route.
+
+#### Handling recursion
+
+If your project implements a "reusable snippet" type of approach, you will likely want to prevent the use of recursive snippets, whereby a nested `MDCRenderer` attempts to then load another child somewhere in its component tree with the same content (meaning, importing itself) and your application would be thrown into an infinite loop.
+
+One way to get around this is to utilize Vue's [`provide/inject`](https://vuejs.org/guide/components/provide-inject.html#provide-inject) to pass down the history of rendered "snippets" so that a child can properly determine if it is being called recursively, and stop the chain. This can be used in combination with parsing the `ast` document nodes after calling the `parseMarkdown` function to strip out recursive node trees from the `ast` before rendering the content in the DOM.
+
+For an example on how to prevent infinite loops and recursion with this pattern, please see the code in the playground's [`PageSnippet` component](/playground/components/global/PageSnippet.vue).
+
+---
+
 ## Rendering in your Vue project
 
 The `<MDCRenderer>` component in combination with a few exported package utilities may also be utilized inside a normal (non-Nuxt) Vue project.
@@ -399,6 +453,8 @@ onBeforeMount(async () => {
 </template>
 ```
 
+---
+
 ## Contributing
 
 You can dive into this module online using StackBlitz:

package/dist/module.d.mts

@@ -88,11 +88,11 @@ interface ModuleOptions {
     /**
      * A map of remark plugins to be used for processing markdown.
      */
-    remarkPlugins?: Record<string, UnistPlugin>;
+    remarkPlugins?: Record<string, UnistPlugin | false>;
     /**
      * A map of remark plugins to be used for processing markdown.
      */
-    rehypePlugins?: Record<string, UnistPlugin>;
+    rehypePlugins?: Record<string, UnistPlugin | false>;
     highlight?: {
         /**
          * The highlighter to be used for highlighting code blocks.

package/dist/module.d.ts

@@ -88,11 +88,11 @@ interface ModuleOptions {
     /**
      * A map of remark plugins to be used for processing markdown.
      */
-    remarkPlugins?: Record<string, UnistPlugin>;
+    remarkPlugins?: Record<string, UnistPlugin | false>;
     /**
      * A map of remark plugins to be used for processing markdown.
      */
-    rehypePlugins?: Record<string, UnistPlugin>;
+    rehypePlugins?: Record<string, UnistPlugin | false>;
     highlight?: {
         /**
          * The highlighter to be used for highlighting code blocks.

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtjs/mdc",
   "configKey": "mdc",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -164,11 +164,15 @@ function processUnistPlugins(plugins) {
   const definitions = [];
   Object.entries(plugins).forEach(([name, plugin]) => {
     const instanceName = `_${pascalCase(name).replace(/\W/g, "")}`;
-    imports.push(`import ${instanceName} from '${plugin.src || name}'`);
-    if (Object.keys(plugin).length) {
-      definitions.push(`  '${name}': { instance: ${instanceName}, options: ${JSON.stringify(plugin.options || plugin)} },`);
+    if (plugin) {
+      imports.push(`import ${instanceName} from '${plugin.src || name}'`);
+      if (Object.keys(plugin).length) {
+        definitions.push(`  '${name}': { instance: ${instanceName}, options: ${JSON.stringify(plugin.options || plugin)} },`);
+      } else {
+        definitions.push(`  '${name}': { instance: ${instanceName} },`);
+      }
     } else {
-      definitions.push(`  '${name}': { instance: ${instanceName} },`);
+      definitions.push(`  '${name}': false,`);
     }
   });
   return { imports, definitions };
@@ -222,7 +226,9 @@ const module = defineNuxtModule({
   },
   // Default configuration options of the Nuxt module
   defaults: {
-    remarkPlugins: {},
+    remarkPlugins: {
+      "remark-emoji": {}
+    },
     rehypePlugins: {},
     highlight: false,
     headings: {

package/dist/runtime/components/MDCRenderer.vue

@@ -1,5 +1,5 @@
 <script>
-import { h, resolveComponent, Text, Comment, defineComponent, toRaw, computed, getCurrentInstance } from "vue";
+import { h, resolveComponent, reactive, watch, Text, Comment, defineAsyncComponent, defineComponent, toRaw, computed, getCurrentInstance } from "vue";
 import destr from "destr";
 import { kebabCase, pascalCase } from "scule";
 import { find, html } from "property-information";
@@ -79,15 +79,31 @@ export default defineComponent({
       const components = (props.body?.children || []).map((n) => n.tag || n.type).filter((t) => !htmlTags.includes(t));
       return Array.from(new Set(components)).sort().join(".");
     });
+    const runtimeData = reactive({
+      ...props.data
+    });
+    watch(() => props.data, (newData) => {
+      Object.assign(runtimeData, newData);
+    });
     await resolveContentComponents(props.body, { tags });
-    return { tags, contentKey, route };
+    function updateRuntimeData(code, value) {
+      const lastIndex = code.split(".").length - 1;
+      return code.split(".").reduce((o, k, i) => {
+        if (i == lastIndex && o) {
+          o[k] = value;
+          return o[k];
+        }
+        return typeof o === "object" ? o[k] : void 0;
+      }, runtimeData);
+    }
+    return { tags, contentKey, route, runtimeData, updateRuntimeData };
   },
   render(ctx) {
-    const { tags, tag, body, data, contentKey, route, unwrap } = ctx;
+    const { tags, tag, body, data, contentKey, route, unwrap, runtimeData, updateRuntimeData } = ctx;
     if (!body) {
       return null;
     }
-    const meta = { ...data, tags, $route: route };
+    const meta = { ...data, tags, $route: route, runtimeData, updateRuntimeData };
     const component = tag !== false ? resolveVueComponent(tag || meta.component?.name || meta.component || "div") : void 0;
     return component ? h(component, { ...meta.component?.props, class: ctx.class, ...this.$attrs, key: contentKey }, { default: defaultSlotRenderer }) : defaultSlotRenderer?.();
     function defaultSlotRenderer() {
@@ -126,6 +142,7 @@ function renderNode(node, h2, documentMeta, parentScope = {}) {
 }
 function renderBinding(node, h2, documentMeta, parentScope = {}) {
   const data = {
+    ...documentMeta.runtimeData,
     ...parentScope,
     $document: documentMeta,
     $doc: documentMeta
@@ -180,8 +197,8 @@ function propsToData(node, documentMeta) {
       return data;
     }
     const value = props[key];
-    if (rxModel.test(key) && !nativeInputs.includes(tag)) {
-      return propsToDataRxModel(key, value, data, documentMeta);
+    if (rxModel.test(key)) {
+      return propsToDataRxModel(key, value, data, documentMeta, { native: nativeInputs.includes(tag) });
     }
     if (key === "v-bind") {
       return propsToDataVBind(key, value, data, documentMeta);
@@ -201,20 +218,14 @@ function propsToData(node, documentMeta) {
     return data;
   }, {});
 }
-function propsToDataRxModel(key, value, data, documentMeta) {
-  const number = (d) => +d;
-  const trim = (d) => d.trim();
-  const noop = (d) => d;
-  const mods = key.replace(rxModel, "").split(".").filter((d) => d).reduce((d, k) => {
-    d[k] = true;
-    return d;
-  }, {});
-  const field = "value";
-  const event = mods.lazy ? "change" : "input";
-  const processor = mods.number ? number : mods.trim ? trim : noop;
-  data[field] = evalInContext(value, documentMeta);
-  data.on = data.on || {};
-  data.on[event] = (e) => documentMeta[value] = processor(e);
+function propsToDataRxModel(key, value, data, documentMeta, { native }) {
+  const propName = key.match(/^v-model:([^=]+)/)?.[1] || "modelValue";
+  const field = native ? "value" : propName;
+  const event = native ? "onInput" : `onUpdate:${propName}`;
+  data[field] = evalInContext(value, documentMeta.runtimeData);
+  data[event] = (e) => {
+    documentMeta.updateRuntimeData(value, native ? e.target?.value : e);
+  };
   return data;
 }
 function propsToDataVBind(_key, value, data, documentMeta) {
@@ -235,7 +246,17 @@ function propsToDataRxBind(key, value, data, documentMeta) {
 }
 const resolveVueComponent = (component) => {
   if (typeof component === "string") {
-    return htmlTags.includes(component) ? component : resolveComponent(pascalCase(component), false);
+    if (htmlTags.includes(component)) {
+      return component;
+    }
+    const _component = resolveComponent(pascalCase(component), false);
+    if (!component || _component?.name === "AsyncComponentWrapper") {
+      return _component;
+    }
+    if ("setup" in _component) {
+      return defineAsyncComponent(() => new Promise((resolve) => resolve(_component)));
+    }
+    return _component;
   }
   return component;
 };

package/dist/runtime/components/MDCRenderer.vue.d.ts

@@ -55,6 +55,12 @@ declare const _default: DefineComponent<import("vue").ExtractPropTypes<{
     tags: any;
     contentKey: import("vue").ComputedRef<string>;
     route: any;
+    runtimeData: {
+        [x: string]: any;
+    };
+    updateRuntimeData: (code: string, value: any) => {
+        [x: string]: any;
+    };
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     /**
      * Content to render
@@ -345,6 +351,10 @@ declare global {
     type __VLS_PrettifyGlobal<T> = {
         [K in keyof T]: T[K];
     } & {};
+    type __VLS_PickFunctionalComponentCtx<T, K> = NonNullable<__VLS_PickNotAny<'__ctx' extends keyof __VLS_PickNotAny<K, {}> ? K extends {
+        __ctx?: infer Ctx;
+    } ? Ctx : never : any, T extends (props: any, ctx: infer Ctx) => any ? Ctx : any>>;
+    type __VLS_UseTemplateRef<T> = Readonly<import('vue').ShallowRef<T | null>>;
     function __VLS_getVForSourceType(source: number): [number, number, number][];
     function __VLS_getVForSourceType(source: string): [string, number, number][];
     function __VLS_getVForSourceType<T extends any[]>(source: T): [
@@ -377,7 +387,7 @@ declare global {
     ][];
     function __VLS_getSlotParams<T>(slot: T): Parameters<__VLS_PickNotAny<NonNullable<T>, (...args: any[]) => any>>;
     function __VLS_getSlotParam<T>(slot: T): Parameters<__VLS_PickNotAny<NonNullable<T>, (...args: any[]) => any>>[0];
-    function __VLS_directiveAsFunction<T extends import('vue').Directive>(dir: T): T extends (...args: any) => any ? T | __VLS_unknownDirective : NonNullable<(T & Record<string, __VLS_unknownDirective>)['created' | 'beforeMount' | 'mounted' | 'beforeUpdate' | 'updated' | 'beforeUnmount' | 'unmounted']>;
+    function __VLS_asFunctionalDirective<T>(dir: T): T extends import('vue').ObjectDirective ? NonNullable<T['created' | 'beforeMount' | 'mounted' | 'beforeUpdate' | 'updated' | 'beforeUnmount' | 'unmounted']> : T extends (...args: any) => any ? T : __VLS_unknownDirective;
     function __VLS_withScope<T, K>(ctx: T, scope: K): ctx is T & K;
     function __VLS_makeOptional<T>(t: T): {
         [K in keyof T]?: T[K];
@@ -411,9 +421,6 @@ declare global {
     };
     function __VLS_elementAsFunction<T>(tag: T, endTag?: T): (_: T & Record<string, unknown>) => void;
     function __VLS_functionalComponentArgsRest<T extends (...args: any) => any>(t: T): 2 extends Parameters<T>['length'] ? [any] : [];
-    function __VLS_pickFunctionalComponentCtx<T, K>(comp: T, compInstance: K): NonNullable<__VLS_PickNotAny<'__ctx' extends keyof __VLS_PickNotAny<K, {}> ? K extends {
-        __ctx?: infer Ctx;
-    } ? Ctx : never : any, T extends (props: any, ctx: infer Ctx) => any ? Ctx : any>>;
     function __VLS_normalizeSlot<S>(s: S): S extends () => infer R ? (props: {}) => R : S;
     function __VLS_tryAsConstant<const T>(t: T): T;
 }

package/dist/runtime/parser/index.d.ts

@@ -1,6 +1,11 @@
+import type { Options as VFileOptions } from 'vfile';
 import type { MDCParseOptions, MDCParserResult, MDCRoot } from '@nuxtjs/mdc';
-export declare const createMarkdownParser: (inlineOptions?: MDCParseOptions) => Promise<(md: string) => Promise<MDCParserResult>>;
-export declare const parseMarkdown: (md: string, inlineOptions?: MDCParseOptions) => Promise<MDCParserResult>;
+export declare const createMarkdownParser: (inlineOptions?: MDCParseOptions) => Promise<(md: string, { fileOptions }?: {
+    fileOptions?: VFileOptions;
+}) => Promise<MDCParserResult>>;
+export declare const parseMarkdown: (md: string, markdownParserOptions?: MDCParseOptions, parseOptions?: {
+    fileOptions?: VFileOptions;
+}) => Promise<MDCParserResult>;
 export declare function contentHeading(body: MDCRoot): {
     title: string;
     description: string;

package/dist/runtime/parser/index.js

@@ -67,9 +67,9 @@ export const createMarkdownParser = async (inlineOptions = {}) => {
   for (const config of mdcConfigs) {
     processor = await config.unified?.post?.(processor) || processor;
   }
-  return async (md) => {
+  return async function parse(md, { fileOptions } = {}) {
     const { content, data: frontmatter } = await parseFrontMatter(md);
-    const processedFile = await processor.process({ value: content, data: frontmatter });
+    const processedFile = await processor.process({ ...fileOptions, value: content, data: frontmatter });
     const result = processedFile.result;
     const data = Object.assign(
       contentHeading(result.body),
@@ -89,9 +89,9 @@ export const createMarkdownParser = async (inlineOptions = {}) => {
     };
   };
 };
-export const parseMarkdown = async (md, inlineOptions = {}) => {
-  const parser = await createMarkdownParser(inlineOptions);
-  return parser(md);
+export const parseMarkdown = async (md, markdownParserOptions = {}, parseOptions = {}) => {
+  const parser = await createMarkdownParser(markdownParserOptions);
+  return parser(md, parseOptions);
 };
 export function contentHeading(body) {
   let title = "";

package/dist/runtime/parser/options.js

@@ -1,4 +1,3 @@
-import remarkEmoji from "remark-emoji";
 import remarkGFM from "remark-gfm";
 import remarkMDC from "remark-mdc";
 import rehypeExternalLinks from "rehype-external-links";
@@ -12,9 +11,6 @@ export const defaults = {
       "remark-mdc": {
         instance: remarkMDC
       },
-      "remark-emoji": {
-        instance: remarkEmoji
-      },
       "remark-gfm": {
         instance: remarkGFM
       }

package/dist/runtime/utils/node.js

@@ -61,7 +61,7 @@ function _flatUnwrap(vnodes, tags = []) {
 }
 export function flatUnwrap(vnodes, tags = []) {
   if (typeof tags === "string") {
-    tags = tags.split(",").map((tag) => tag.trim()).filter(Boolean);
+    tags = tags.split(/[,\s]/).map((tag) => tag.trim()).filter(Boolean);
   }
   if (!tags.length) {
     return vnodes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mdc",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Nuxt MDC module",
   "repository": "nuxt-modules/mdc",
   "license": "MIT",
@@ -71,11 +71,11 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.13.2",
-    "@shikijs/transformers": "^1.22.0",
+    "@nuxt/kit": "^3.14.159",
+    "@shikijs/transformers": "^1.23.1",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "@vue/compiler-core": "^3.5.12",
+    "@vue/compiler-core": "^3.5.13",
     "consola": "^3.2.3",
     "debug": "^4.3.7",
     "defu": "^6.1.4",
@@ -84,9 +84,9 @@
     "github-slugger": "^2.0.0",
     "hast-util-to-string": "^3.0.1",
     "mdast-util-to-hast": "^13.2.0",
-    "micromark-util-sanitize-uri": "^2.0.0",
+    "micromark-util-sanitize-uri": "^2.0.1",
     "ohash": "^1.1.4",
-    "parse5": "^7.2.0",
+    "parse5": "^7.2.1",
     "pathe": "^1.1.2",
     "property-information": "^6.5.0",
     "rehype-external-links": "^3.0.0",
@@ -96,36 +96,40 @@
     "rehype-sort-attributes": "^5.0.1",
     "remark-emoji": "^5.0.1",
     "remark-gfm": "^4.0.0",
-    "remark-mdc": "^3.2.1",
+    "remark-mdc": "^3.3.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.1",
     "scule": "^1.3.0",
-    "shiki": "^1.22.0",
+    "shiki": "^1.23.1",
     "ufo": "^1.5.4",
     "unified": "^11.0.5",
     "unist-builder": "^4.0.0",
     "unist-util-visit": "^5.0.0",
-    "unwasm": "^0.3.9"
+    "unwasm": "^0.3.9",
+    "vfile": "^6.0.3"
   },
   "devDependencies": {
     "@nuxt/devtools": "latest",
-    "@nuxt/eslint-config": "^0.6.0",
+    "@nuxt/eslint-config": "^0.7.1",
     "@nuxt/module-builder": "^0.8.4",
-    "@nuxt/schema": "^3.13.2",
-    "@nuxt/test-utils": "^3.14.3",
-    "@nuxt/ui": "^2.18.7",
+    "@nuxt/schema": "^3.14.159",
+    "@nuxt/test-utils": "^3.14.4",
+    "@nuxt/ui": "^2.19.2",
     "@nuxtjs/mdc": "link:.",
-    "@types/node": "^22.7.5",
+    "@types/node": "^22.9.0",
     "changelogen": "^0.5.7",
-    "eslint": "^9.12.0",
-    "nuxt": "^3.13.2",
+    "eslint": "^9.15.0",
+    "nuxt": "^3.14.159",
     "rehype": "^13.0.2",
-    "release-it": "^17.9.0",
+    "release-it": "^17.10.0",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.3",
-    "vue-tsc": "^2.1.6"
+    "vitest": "^2.1.5",
+    "vue-tsc": "^2.1.10"
   },
-  "packageManager": "pnpm@9.12.1",
+  "resolutions": {
+    "@nuxtjs/mdc": "workspace:*"
+  },
+  "packageManager": "pnpm@9.13.2",
   "release-it": {
     "git": {
       "commitMessage": "chore(release): release v${version}"