wip: compile to colocate props?

examples/with-markdoc/markdoc.config.mjs

@@ -1,14 +1,3 @@
 import { defineMarkdocConfig } from '@astrojs/markdoc/config';
-import Aside from './src/components/Aside.astro';
 
-export default defineMarkdocConfig({
-	tags: {
-		aside: {
-			render: Aside,
-			attributes: {
-				type: { type: String },
-				title: { type: String },
-			},
-		},
-	},
-});
+export default defineMarkdocConfig({});

examples/with-markdoc/src/embeds/aside.astro

@@ -2,11 +2,14 @@
 // Inspired by the `Aside` component from docs.astro.build
 // https://github.com/withastro/docs/blob/main/src/components/Aside.astro
 
+// TODO: InferProps util
 export interface Props {
 	type?: 'note' | 'tip' | 'caution' | 'danger';
 	title?: string;
 }
 
+export const example = true;
+
 const labelByType = {
 	note: 'Note',
 	tip: 'Tip',

examples/with-markdoc/src/embeds/aside.astro.js

@@ -0,0 +1,57 @@
+import {
+  render as $$render,
+  createAstro as $$createAstro,
+  createComponent as $$createComponent,
+  maybeRenderHead as $$maybeRenderHead,
+  renderSlot as $$renderSlot,
+  addAttribute as $$addAttribute
+} from "astro/server/index.js";
+import "/Users/benholmes/Repositories/astro/examples/with-markdoc/src/embeds/aside.astro?astro&type=style&index=0&lang.css";
+const $$Astro = $$createAstro();
+const Astro = $$Astro;
+export const example = true;
+const $$Aside = $$createComponent(async ($$result, $$props, $$slots) => {
+  const Astro2 = $$result.createAstro($$Astro, $$props, $$slots);
+  Astro2.self = $$Aside;
+  const labelByType = {
+    note: "Note",
+    tip: "Tip",
+    caution: "Caution",
+    danger: "Danger"
+  };
+  const { type = "note" } = Astro2.props;
+  const title = Astro2.props.title ?? labelByType[type] ?? "";
+  const icons = {
+    note: {
+      viewBox: "0 0 18 18",
+      d: "M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0114.25 14H1.75A1.75 1.75 0 010 12.25v-8.5zm1.75-.25a.25.25 0 00-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 00.25-.25v-8.5a.25.25 0 00-.25-.25H1.75zM3.5 6.25a.75.75 0 01.75-.75h7a.75.75 0 010 1.5h-7a.75.75 0 01-.75-.75zm.75 2.25a.75.75 0 000 1.5h4a.75.75 0 000-1.5h-4z"
+    },
+    tip: {
+      viewBox: "0 0 18 18",
+      d: "M14 0a8.8 8.8 0 0 0-6 2.6l-.5.4-.9 1H3.3a1.8 1.8 0 0 0-1.5.8L.1 7.6a.8.8 0 0 0 .4 1.1l3.1 1 .2.1 2.4 2.4.1.2 1 3a.8.8 0 0 0 1 .5l2.9-1.7a1.8 1.8 0 0 0 .8-1.5V9.5l1-1 .4-.4A8.8 8.8 0 0 0 16 2v-.1A1.8 1.8 0 0 0 14.2 0h-.1zm-3.5 10.6-.3.2L8 12.3l.5 1.8 2-1.2a.3.3 0 0 0 .1-.2v-2zM3.7 8.1l1.5-2.3.2-.3h-2a.3.3 0 0 0-.3.1l-1.2 2 1.8.5zm5.2-4.5a7.3 7.3 0 0 1 5.2-2.1h.1a.3.3 0 0 1 .3.3v.1a7.3 7.3 0 0 1-2.1 5.2l-.5.4a15.2 15.2 0 0 1-2.5 2L7.1 11 5 9l1.5-2.3a15.3 15.3 0 0 1 2-2.5l.4-.5zM12 5a1 1 0 1 1-2 0 1 1 0 0 1 2 0zm-8.4 9.6a1.5 1.5 0 1 0-2.2-2.2 7 7 0 0 0-1.1 3 .2.2 0 0 0 .3.3c.6 0 2.2-.4 3-1.1z"
+    },
+    caution: {
+      viewBox: "-1 1 18 18",
+      d: "M8.9 1.5C8.7 1.2 8.4 1 8 1s-.7.2-.9.5l-7 12a1 1 0 0 0 0 1c.2.3.6.5 1 .5H15c.4 0 .7-.2.9-.5a1 1 0 0 0 0-1l-7-12zM9 13H7v-2h2v2zm0-3H7V6h2v4z"
+    },
+    danger: {
+      viewBox: "0 1 14 17",
+      d: "M5 .3c.9 2.2.5 3.4-.5 4.3C3.5 5.6 2 6.5 1 8c-1.5 2-1.7 6.5 3.5 7.7-2.2-1.2-2.6-4.5-.3-6.6-.6 2 .6 3.3 2 2.8 1.4-.4 2.3.6 2.2 1.7 0 .8-.3 1.4-1 1.8A5.6 5.6 0 0 0 12 10c0-2.9-2.5-3.3-1.3-5.7-1.5.2-2 1.2-1.8 2.8 0 1-1 1.8-2 1.3-.6-.4-.6-1.2 0-1.8C8.2 5.3 8.7 2.5 5 .3z"
+    }
+  };
+  const { viewBox, d } = icons[type];
+  return $$render`${$$maybeRenderHead($$result)}<aside${$$addAttribute(`content ${type} astro-C6FK6RS3`, "class")}${$$addAttribute(title, "aria-label")}>
+	<p class="title astro-C6FK6RS3" aria-hidden="true">
+		<span class="icon astro-C6FK6RS3">
+			<svg xmlns="http://www.w3.org/2000/svg"${$$addAttribute(viewBox, "viewBox")}${$$addAttribute(16, "width")}${$$addAttribute(16, "height")} class="astro-C6FK6RS3">
+				<path fill-rule="evenodd"${$$addAttribute(d, "d")} class="astro-C6FK6RS3"></path>
+			</svg>
+		</span>
+		${title}
+	</p>
+	<section class="astro-C6FK6RS3">
+		${$$renderSlot($$result, $$slots["default"])}
+	</section>
+</aside>`;
+}, "/Users/benholmes/Repositories/astro/examples/with-markdoc/src/embeds/aside.astro");
+export default $$Aside;

examples/with-markdoc/src/embeds/aside.props.js

@@ -0,0 +1,6 @@
+import { defineProps, field } from '@astrojs/markdoc/props';
+
+export const props = defineProps({
+	type: field.enum(['note', 'tip', 'warning', 'danger']),
+	title: field.string().optional(),
+});

packages/integrations/markdoc/package.json

@@ -22,6 +22,7 @@
     "./prism": "./dist/extensions/prism.js",
     "./shiki": "./dist/extensions/shiki.js",
     ".": "./dist/index.js",
+    "./props": "./dist/props.js",
     "./components": "./components/index.ts",
     "./runtime": "./dist/runtime.js",
     "./config": "./dist/config.js",
@@ -41,14 +42,16 @@
     "test:match": "mocha --timeout 20000 -g"
   },
   "dependencies": {
-    "shiki": "^0.14.1",
+    "@astrojs/compiler": "^1.4.0",
     "@astrojs/prism": "^2.1.2",
     "@markdoc/markdoc": "^0.3.0",
     "esbuild": "^0.17.12",
+    "fast-glob": "^3.2.11",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "kleur": "^4.1.5",
-    "zod": "^3.17.3"
+    "shiki": "^0.14.1",
+    "zod": "^3.20.6"
   },
   "peerDependencies": {
     "astro": "workspace:^2.5.5"

packages/integrations/markdoc/src/index.ts

@@ -1,6 +1,9 @@
+import { isPropsDef, markdocAttributesFromZodProps, usedDefinePropsSymbol } from './props.js';
 /* eslint-disable no-console */
-import type { Node } from '@markdoc/markdoc';
+import type { Node, Schema } from '@markdoc/markdoc';
+import { transform, type TransformResult } from '@astrojs/compiler';
 import Markdoc from '@markdoc/markdoc';
+import glob from 'fast-glob';
 import type { AstroConfig, AstroIntegration, ContentEntryType, HookParameters } from 'astro';
 import fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -11,6 +14,8 @@ import { bold, red, yellow } from 'kleur/colors';
 import type * as rollup from 'rollup';
 import { loadMarkdocConfig, type MarkdocConfigResult } from './load-config.js';
 import { setupConfig } from './runtime.js';
+import path from 'node:path';
+import { normalizePath, transformWithEsbuild, type Plugin } from 'vite';
 
 type SetupHookParams = HookParameters<'astro:config:setup'> & {
 	// `contentEntryType` is not a public API
@@ -28,6 +33,7 @@ export default function markdocIntegration(legacyConfig?: any): AstroIntegration
 		process.exit(0);
 	}
 	let markdocConfigResult: MarkdocConfigResult | undefined;
+
 	return {
 		name: '@astrojs/markdoc',
 		hooks: {
@@ -37,12 +43,95 @@ export default function markdocIntegration(legacyConfig?: any): AstroIntegration
 					updateConfig,
 					addContentEntryType,
 				} = params as SetupHookParams;
+				const embedsVirtualModId = 'astro:markdoc-embeds';
+
+				const tagPropsModules = await glob(
+					fileURLToPath(new URL('./embeds/*.props.js', astroConfig.srcDir)),
+					{ absolute: true }
+				);
+				let componentAttrsByName: Record<string, Schema> = {};
+				let componentPathByName: Record<string, string> = {};
+				const embedsDir = new URL('embeds/', astroConfig.srcDir);
+				for (const tagPropsModule of tagPropsModules) {
+					const astroFilePath = tagPropsModule.replace(/\.props\.js$/, '.astro');
+					const astroFileContent = await fs.promises.readFile(astroFilePath, 'utf-8');
+					const compiled = await compileAstroFile({
+						astroConfig,
+						filename: astroFilePath,
+						source: astroFileContent,
+					});
+					const builtJs = await transformWithEsbuild(compiled.code, astroFilePath, {
+						loader: 'ts',
+						target: 'esnext',
+						sourcemap: 'external',
+						tsconfigRaw: {
+							compilerOptions: {
+								// Ensure client:only imports are treeshaken
+								importsNotUsedAsValues: 'remove',
+								preserveValueImports: false,
+							},
+						},
+					});
+					const compiledAstroFilePath = tagPropsModule.replace(/\.props\.js$/, '.astro.js');
+					await fs.promises.writeFile(compiledAstroFilePath, builtJs.code);
+					const mod = await import(tagPropsModule);
+					if (typeof mod !== 'object' || mod == null) {
+						throw new MarkdocError({
+							message: `${tagPropsModule} does not export a \`props\` object.`,
+						});
+					}
+					const { props } = mod;
+					if (isPropsDef(props)) {
+						const compName = path
+							.relative(fileURLToPath(embedsDir), tagPropsModule)
+							.replace('.props.js', '');
+						componentAttrsByName[compName] = markdocAttributesFromZodProps(props);
+						componentPathByName[compName] = tagPropsModule.replace(/\.props\.js$/, '.astro');
+					} else {
+						throw new MarkdocError({
+							message: `\`props\` exports must use the \`defineProps()\` helper.`,
+						});
+					}
+				}
 
 				updateConfig({
 					vite: {
 						ssr: {
 							external: ['@astrojs/markdoc/prism', '@astrojs/markdoc/shiki'],
 						},
+						plugins: [
+							{
+								name: 'astro:markdoc-embeds',
+								resolveId(id) {
+									if (id === embedsVirtualModId) {
+										return '\0' + embedsVirtualModId;
+									}
+								},
+								async load(id) {
+									if (id === '\0' + embedsVirtualModId) {
+										const code = `${Object.entries(componentPathByName)
+											.map(([name, path]) => {
+												return `import ${name} from ${JSON.stringify(
+													pathToFileURL(path).pathname
+												)}`;
+											})
+											.join('\n')}
+										export const tagConfig = {
+											${Object.entries(componentAttrsByName)
+												.map(([name, attributes]) => {
+													return `${JSON.stringify(name)}: {
+	attributes: ${JSON.stringify(attributes)},
+	render: ${name},
+}`;
+												})
+												.join(',\n')}
+									};`;
+										// console.log(code);
+										return code;
+									}
+								},
+							} as Plugin,
+						],
 					},
 				});
 
@@ -72,6 +161,7 @@ export default function markdocIntegration(legacyConfig?: any): AstroIntegration
 								// Variables can be configured at runtime,
 								// so we cannot validate them at build time.
 								e.error.id !== 'variable-undefined' &&
+								e.error.id !== 'tag-undefined' &&
 								(e.error.level === 'error' || e.error.level === 'critical')
 							);
 						});
@@ -101,8 +191,9 @@ export default function markdocIntegration(legacyConfig?: any): AstroIntegration
 						}
 
 						const res = `import { jsx as h } from 'astro/jsx-runtime';
-						import { Renderer } from '@astrojs/markdoc/components';
-						import { collectHeadings, setupConfig, setupConfigSync, Markdoc } from '@astrojs/markdoc/runtime';
+import { Renderer } from '@astrojs/markdoc/components';
+import { tagConfig } from ${JSON.stringify(embedsVirtualModId)};
+import { collectHeadings, setupConfig, setupConfigSync, Markdoc } from '@astrojs/markdoc/runtime';
 import * as entry from ${JSON.stringify(viteId + '?astroContentCollectionEntry')};
 ${
 	markdocConfigResult
@@ -134,6 +225,10 @@ export function getHeadings() {
 export async function Content (props) {
 	const config = await setupConfig({
 		...userConfig,
+		tags: {
+			...tagConfig,
+			...userConfig.tags,
+		},
 		variables: { ...userConfig.variables, ...props },
 	}, entry);
 
@@ -208,3 +303,74 @@ function shouldOptimizeImage(src: string) {
 	// Optimize anything that is NOT external or an absolute path to `public/`
 	return !isValidUrl(src) && !src.startsWith('/');
 }
+
+async function compileAstroFile({
+	astroConfig,
+	filename,
+	source,
+}: {
+	astroConfig: AstroConfig;
+	filename: string;
+	source: string;
+}): Promise<TransformResult> {
+	let transformResult: TransformResult;
+
+	try {
+		// Transform from `.astro` to valid `.ts`
+		// use `sourcemap: "both"` so that sourcemap is included in the code
+		// result passed to esbuild, but also available in the catch handler.
+		transformResult = await transform(source, {
+			compact: astroConfig.compressHTML,
+			filename,
+			normalizedFilename: normalizeFilename(filename, astroConfig.root),
+			sourcemap: 'both',
+			internalURL: 'astro/server/index.js',
+			astroGlobalArgs: JSON.stringify(astroConfig.site),
+			scopedStyleStrategy: astroConfig.scopedStyleStrategy,
+			resultScopedSlot: true,
+			async resolvePath(specifier) {
+				return resolvePath(specifier, filename);
+			},
+		});
+	} catch (err: any) {
+		// The compiler should be able to handle errors by itself, however
+		// for the rare cases where it can't let's directly throw here with as much info as possible
+		throw new MarkdocError({
+			message: 'Failed to transform embed',
+			location: {
+				file: filename,
+			},
+		});
+	}
+
+	return transformResult;
+}
+
+function normalizeFilename(filename: string, root: URL) {
+	const normalizedFilename = normalizePath(filename);
+	const normalizedRoot = normalizePath(fileURLToPath(root));
+	if (normalizedFilename.startsWith(normalizedRoot)) {
+		return normalizedFilename.slice(normalizedRoot.length - 1);
+	} else {
+		return normalizedFilename;
+	}
+}
+
+function resolvePath(specifier: string, importer: string) {
+	if (specifier.startsWith('.')) {
+		const absoluteSpecifier = path.resolve(path.dirname(importer), specifier);
+		return resolveJsToTs(normalizePath(absoluteSpecifier));
+	} else {
+		return specifier;
+	}
+}
+
+function resolveJsToTs(filePath: string) {
+	if (filePath.endsWith('.jsx') && !fs.existsSync(filePath)) {
+		const tryPath = filePath.slice(0, -4) + '.tsx';
+		if (fs.existsSync(tryPath)) {
+			return tryPath;
+		}
+	}
+	return filePath;
+}

packages/integrations/markdoc/src/props.ts

@@ -0,0 +1,55 @@
+import z from 'zod';
+import type { SchemaAttribute } from '@markdoc/markdoc';
+
+type PropFields = Record<string, ReturnType<(typeof field)[keyof typeof field]>>;
+
+export function markdocAttributesFromZodProps(
+	zodProps: PropFields
+): Record<string, SchemaAttribute> {
+	let attributes: Record<string, SchemaAttribute> = {};
+
+	for (const [key, wrappedVal] of Object.entries(zodProps)) {
+		let val = wrappedVal;
+		attributes[key] = {
+			required: true,
+		};
+		if (wrappedVal instanceof z.ZodOptional) {
+			attributes[key].required = false;
+			val = wrappedVal.unwrap();
+		}
+		if (val instanceof z.ZodString) {
+			attributes[key].type = 'String';
+		}
+		if (val instanceof z.ZodEnum) {
+			if (!isStrArray(val.options)) throw new Error('Enum values must be strings');
+			attributes[key].type = 'String';
+			attributes[key].matches = val.options;
+		}
+	}
+
+	return attributes;
+}
+
+function isStrArray(val: any): val is string[] {
+	return Array.isArray(val) && val.every((v) => typeof v === 'string');
+}
+
+export const field = {
+	boolean: z.boolean,
+	string: z.string,
+	enum: z.enum,
+};
+
+export const usedDefinePropsSymbol = Symbol.for('usedDefineProps');
+
+export function isPropsDef(props: unknown): props is ReturnType<typeof defineProps> {
+	return typeof props === 'object' && props != null && usedDefinePropsSymbol in props;
+}
+
+export function defineProps(props: PropFields): PropFields {
+	return Object.assign(props, {
+		// Used to check that `.props.js` files use our helper to define.
+		// Cheapest type check you can have!
+		[usedDefinePropsSymbol]: true,
+	});
+}

pnpm-lock.yaml

@@ -3973,6 +3973,9 @@ importers:
 
   packages/integrations/markdoc:
     dependencies:
+      '@astrojs/compiler':
+        specifier: ^1.4.0
+        version: 1.4.0
       '@astrojs/prism':
         specifier: ^2.1.2
         version: link:../../astro-prism
@@ -3982,6 +3985,9 @@ importers:
       esbuild:
         specifier: ^0.17.12
         version: 0.17.12
+      fast-glob:
+        specifier: ^3.2.11
+        version: 3.2.12
       github-slugger:
         specifier: ^2.0.0
         version: 2.0.0
@@ -3995,7 +4001,7 @@ importers:
         specifier: ^0.14.1
         version: 0.14.1
       zod:
-        specifier: ^3.17.3
+        specifier: ^3.20.6
         version: 3.20.6
     devDependencies:
       '@astrojs/markdown-remark':
@@ -12400,7 +12406,7 @@ packages:
       '@types/glob': 7.2.0
       array-union: 2.1.0
       dir-glob: 3.0.1
-      fast-glob: 3.2.11
+      fast-glob: 3.2.12
       glob: 7.2.3
       ignore: 5.2.4
       merge2: 1.4.1
@@ -12413,7 +12419,7 @@ packages:
     dependencies:
       array-union: 2.1.0
       dir-glob: 3.0.1
-      fast-glob: 3.2.11
+      fast-glob: 3.2.12
       ignore: 5.2.4
       merge2: 1.4.1
       slash: 3.0.0
@@ -12425,7 +12431,7 @@ packages:
     dependencies:
       array-union: 3.0.1
       dir-glob: 3.0.1
-      fast-glob: 3.2.11
+      fast-glob: 3.2.12
       ignore: 5.2.4
       merge2: 1.4.1
       slash: 4.0.0
@@ -12436,7 +12442,7 @@ packages:
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     dependencies:
       dir-glob: 3.0.1
-      fast-glob: 3.2.11
+      fast-glob: 3.2.12
       ignore: 5.2.4
       merge2: 1.4.1
       slash: 4.0.0