@twobirds/microcomponents 0.3.0 → 0.4.0

package/dist/cli/create.js

@@ -0,0 +1,419 @@
+/**
+Project scaffolding for `mc create --namespace xxx`.
+
+Pure, filesystem-free logic: given a namespace it returns the files of a complete,
+working Micro Components dev environment and their contents. The starter component's
+path is not re-derived here — it comes from {@link tagPath}, the same primitive the
+runtime autoload loader uses, so the scaffold and the runtime can never disagree about
+where a component lives.
+
+The namespace is the first segment of every component tag, so `xxx` makes `src/xxx/`
+the home of tags like `<xxx-app>` (tagPath `xxx-app` → `xxx/app`). The generated
+environment mirrors the repo's own demos: a Vite dev server serving `src/` straight,
+a page shell at that root that turns on `autoload(true)`, and a starter component with
+companion `targetHtml` / `targetCss` assets. Because the page shell is the autoload
+base, `import.meta.url` + `tagPath('xxx-app')` resolves to `src/xxx/app.js` — the
+compiled starter.
+
+@module CLI/Project
+*/
+import { tagPath } from '../utils/resolveComponentPath.js';
+import { kebabToPascal } from '../utils/helpers.js';
+/** The starter component tag for a namespace: `xxx` → `xxx-app`. */
+function starterTag(namespace) {
+    return `${namespace}-app`;
+}
+/**
+Whether a string is a valid project namespace: 1 to 4 lowercase letters.
+
+@example
+```ts
+console.log(isValidNamespace('mc'));
+console.log(isValidNamespace('mcxyz'));
+console.log(isValidNamespace('toolong'));
+```
+@param ns - Candidate namespace.
+*/
+export function isValidNamespace(ns) {
+    return /^[a-z]{1,4}$/.test(ns);
+}
+/**
+Builds the files of a complete dev environment for a namespace.
+
+@example
+```ts
+const { namespace, files } = scaffoldProject('mc');
+console.log(namespace);
+console.log(Object.keys(files));
+```
+@param namespace - 1 to 4 lowercase letters; becomes the `src/<namespace>/` folder and
+the first segment of every component tag.
+@throws If `namespace` is not 1 to 4 lowercase letters.
+*/
+export function scaffoldProject(namespace) {
+    if (!isValidNamespace(namespace)) {
+        throw new Error(`invalid namespace "${namespace}": must be 1 to 4 lowercase letters (e.g. "mc")`);
+    }
+    const tag = starterTag(namespace);
+    const base = tagPath(tag);
+    const files = {};
+    files['package.json'] = packageJson(namespace);
+    files['tsconfig.json'] = tsconfig();
+    files['tsconfig.vc.json'] = tsconfigVc();
+    files['vite.config.ts'] = viteConfig(namespace);
+    files['.gitignore'] = gitignore();
+    files['README.md'] = readme(namespace, tag);
+    files['src/index.html'] = shell(namespace, tag);
+    files[`src/${base}.ts`] = appSource(namespace, tag);
+    files[`src/${base}.target.html`] = appHtml(namespace);
+    files[`src/${base}.target.css`] = appCss(tag);
+    return { files, namespace };
+}
+function packageJson(namespace) {
+    return JSON.stringify({
+        name: `${namespace}-app`,
+        private: true,
+        type: 'module',
+        scripts: {
+            dev: 'vite',
+            build: 'vite build',
+            preview: 'vite preview',
+            typecheck: 'tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.vc.json',
+        },
+        dependencies: {
+            '@twobirds/microcomponents': '^0.4.0',
+        },
+        devDependencies: {
+            vite: '^8.1.5',
+            typescript: '^6.0.3',
+            '@types/node': '^26.6.5',
+        },
+    }, null, '\t');
+}
+function tsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: 'ESNext',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            lib: ['ESNext', 'DOM', 'DOM.Iterable'],
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            noEmit: true,
+        },
+        include: ['src/**/*.ts'],
+    }, null, '\t');
+}
+function tsconfigVc() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: 'ESNext',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            lib: ['ESNext', 'DOM'],
+            types: ['node'],
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            noEmit: true,
+        },
+        files: ['vite.config.ts'],
+    }, null, '\t');
+}
+function gitignore() {
+    return `node_modules/
+dist/
+`;
+}
+function readme(namespace, tag) {
+    return `# ${namespace} App
+
+A Micro Components project scaffolded by \`mc create --namespace ${namespace}\`.
+
+## Install
+
+\`\`\`sh
+pnpm install
+\`\`\`
+
+## Dev
+
+\`\`\`sh
+pnpm dev
+\`\`\`
+
+## Build
+
+\`\`\`sh
+pnpm build
+\`\`\`
+
+Components compile to \`dist/\` at their own autoload path, and companion \`.css\`, \`.html\` and
+\`.json\` files are copied next to them, so the built output loads like the dev server.
+
+## Type-check
+
+\`\`\`sh
+pnpm typecheck
+\`\`\`
+
+\`tsconfig.json\` checks \`src/\`; \`tsconfig.vc.json\` checks \`vite.config.ts\`, which lives outside
+\`src/\` and needs node types for its \`node:\` imports.
+
+## Components
+
+Components live in \`src/${namespace}/\`. The starter is \`<${tag}>\` (\`src/${namespace}/app.ts\`).
+
+Add a component with:
+
+\`\`\`sh
+npx mc new ${namespace}-name --target-html --target-css
+\`\`\`
+`;
+}
+function viteConfig(namespace) {
+    return `/**
+ * Dev and build config for a Micro Components project.
+ *
+ * \`src/\` is the Vite root, so the page shell and every component source are
+ * served straight from source with no build step. Companion \`.css\`, \`.html\` and
+ * \`.json\` files are served as raw text — Vite would otherwise answer a \`.html\`
+ * request with its own transformed page (injecting \`/@vite/client\` into the
+ * template) and a \`.css\` request with a JS module, neither of which
+ * \`loadAssets()\` can consume. \`copyCompanions\` mirrors the same files into
+ * \`dist/\` so the built output stays autoload-ready, and every component under
+ * \`src/<namespace>/\` is a build entry, emitted at its own autoload path
+ * (\`mc/app.ts\` → \`dist/mc/app.js\`).
+ *
+ * @module ViteConfig
+ */
+
+import { defineConfig, type Plugin, type ResolvedConfig } from 'vite';
+import { cp, mkdir, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const projectRoot = import.meta.dirname;
+const sourceRoot = path.join(projectRoot, 'src');
+const namespace = '${namespace}';
+
+const pageShells = new Set(['index.html', 'index-dev.html']);
+
+/**
+ * Whether a served file is a companion asset that must stay raw text, rather
+ * than one of the page shells Vite is allowed to transform.
+ *
+ * @example
+ * \`\`\`ts
+ * isCompanionAsset('app.target.html');
+ * isCompanionAsset('index.html');
+ * \`\`\`
+ *
+ * @param name Basename of the requested file.
+ */
+function isCompanionAsset(name: string): boolean {
+	if (pageShells.has(name)) return false;
+	return name.endsWith('.css') || name.endsWith('.json') || name.endsWith('.html');
+}
+
+/**
+ * Serves companion \`.css\`, \`.html\` and \`.json\` files as raw text, ahead of the
+ * Vite transform middleware. Without it a \`.html\` request returns the transformed
+ * page shell and a \`.css\` request returns a JS module, so \`loadAssets()\` receives
+ * markup it cannot use.
+ *
+ * @example
+ * \`\`\`ts
+ * plugins: [rawAssets(sourceRoot)],
+ * \`\`\`
+ *
+ * @param root Source root that mirrors the \`src/\` tree.
+ */
+function rawAssets(root: string): Plugin {
+	return {
+		name: 'raw-assets',
+		enforce: 'pre',
+		configureServer(server) {
+			server.middlewares.use(async (req, res, next) => {
+				const url = req.url?.split('?')[0];
+				if (!url) return next();
+				const file = decodeURIComponent(url);
+				const name = file.split('/').pop() ?? '';
+				if (!isCompanionAsset(name)) return next();
+				try {
+					const text = await readFile(path.join(root, file), 'utf-8');
+					res.setHeader('Content-Type', name.endsWith('.css') ? 'text/css' : 'text/plain');
+					res.end(text);
+				} catch {
+					next();
+				}
+			});
+		},
+	};
+}
+
+/**
+ * Copies every companion asset from \`src/\` into the build output, preserving the
+ * directory tree. Autoload resolves \`<ns-app>\` to \`<ns>/app.js\` relative to the
+ * page shell, so \`dist/\` needs the compiled component *and* its companion files
+ * at the same relative path.
+ *
+ * @example
+ * \`\`\`ts
+ * plugins: [copyCompanions(sourceRoot)],
+ * \`\`\`
+ *
+ * @param root Source root to walk.
+ */
+function copyCompanions(root: string): Plugin {
+	let outDir = '';
+	return {
+		name: 'copy-companions',
+		apply: 'build',
+		configResolved(config: ResolvedConfig) {
+			outDir = path.resolve(config.root, config.build.outDir);
+		},
+		async closeBundle() {
+			async function walk(dir: string, rel: string): Promise<void> {
+				for (const entry of await readdir(dir, { withFileTypes: true })) {
+					const src = path.join(dir, entry.name);
+					if (entry.isDirectory()) {
+						await walk(src, path.join(rel, entry.name));
+					} else if (isCompanionAsset(entry.name)) {
+						const dst = path.join(outDir, rel, entry.name);
+						await mkdir(path.dirname(dst), { recursive: true });
+						await cp(src, dst);
+					}
+				}
+			}
+			await walk(root, '');
+		},
+	};
+}
+
+/**
+ * Names a build chunk after its source path, so a component lands at the autoload
+ * path (\`src/mc/app.ts\` → \`dist/mc/app.js\`). Rollup truncates chunk names at the
+ * last \`/\`, so \`info.name\` alone cannot carry a folder — the facade module id is
+ * the reliable source.
+ *
+ * @example
+ * \`\`\`ts
+ * entryName({ name: 'mc/app', facadeModuleId: '/project/src/mc/app.ts' });
+ * entryName({ name: 'index', facadeModuleId: '/project/src/index.html' });
+ * \`\`\`
+ *
+ * @param info Rollup chunk info.
+ */
+function entryName(info: { name: string; facadeModuleId: string | null }): string {
+	const facade = info.facadeModuleId;
+	if (!facade || facade.endsWith('.html')) return \`\${info.name}.js\`;
+	return path.relative(sourceRoot, facade).replace(/\\\\/g, '/').replace(/\\.(ts|js)$/, '.js');
+}
+
+/**
+ * Collects every component source as a build entry, keyed by its path relative to
+ * \`src/\`. Plain \`.js\` files count too, so the rapid-prototyping path stays
+ * buildable. New components are picked up automatically — no config edit needed.
+ *
+ * @example
+ * \`\`\`ts
+ * const entries: Record<string, string> = {};
+ * await collectEntries(path.join(sourceRoot, 'mc'), 'mc', entries);
+ * \`\`\`
+ *
+ * @param dir Directory to walk.
+ * @param rel Path of that directory relative to \`src/\`.
+ * @param entries Accumulated entries, mutated in place.
+ */
+async function collectEntries(dir: string, rel: string, entries: Record<string, string>): Promise<void> {
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await collectEntries(full, path.join(rel, entry.name), entries);
+		} else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
+			entries[path.join(rel, entry.name).replace(/\\.(ts|js)$/, '')] = full;
+		}
+	}
+}
+
+export default defineConfig(async () => {
+	const entries: Record<string, string> = {};
+	await collectEntries(path.join(sourceRoot, namespace), namespace, entries);
+	return {
+		root: sourceRoot,
+		build: {
+			outDir: path.join(projectRoot, 'dist'),
+			emptyOutDir: true,
+			rollupOptions: {
+				input: { index: path.join(sourceRoot, 'index.html'), ...entries },
+				output: { entryFileNames: (info: { name: string; facadeModuleId: string | null }) => entryName(info) },
+			},
+		},
+		plugins: [rawAssets(sourceRoot), copyCompanions(sourceRoot)],
+	};
+});
+`;
+}
+function shell(namespace, tag) {
+    return `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>${namespace} App</title>
+		<script type="module">
+			import * as m from '@twobirds/microcomponents';
+			m.autoload(true);
+			Object.assign(window, m);
+		</script>
+	</head>
+	<body>
+		<${tag}></${tag}>
+	</body>
+</html>
+`;
+}
+function appSource(namespace, tag) {
+    const className = kebabToPascal(tag);
+    return `import { DC, defineCE, parse, processAssets, type McEvent } from '@twobirds/microcomponents';
+
+/**
+\`${tag}\` — the starter micro component.
+
+@example
+\`\`\`html
+<${tag}></${tag}>
+\`\`\`
+*/
+class ${className} extends DC {
+	static assets = ['targetHtml', 'targetCss'];
+
+	data = { title: 'Micro Components' };
+
+	// Fill the template \`{key}\` tokens once, instead of binding reactive state.
+	oneAssets(ev: McEvent<Record<string, string>>): void {
+		processAssets(this, {
+			targetHtml: parse(ev.detail.data.targetHtml, this.data),
+		});
+	}
+}
+
+defineCE('${tag}', ${className});
+`;
+}
+function appHtml(namespace) {
+    return `<div class="app">
+	<h1>{title}</h1>
+	<p>Namespace scaffold ready. Edit <code>src/${namespace}/app.ts</code>.</p>
+</div>
+`;
+}
+function appCss(tag) {
+    return `${tag} {
+	display: block;
+	padding: 2rem;
+	font-family: system-ui, sans-serif;
+}
+`;
+}

package/dist/cli/dispatch.d.ts

@@ -0,0 +1,43 @@
+/**
+Command dispatcher for the `mc` CLI.
+
+Kept free of any top-level side effects so the routing can be unit-tested:
+`index.ts` is the thin executable entry that calls {@link main}, while this
+module only exports the logic. Commands that wrap a package.json script
+(`clean`, `check`) are deliberately thin — they delegate to the script so the
+script stays the single source of truth. When the current project defines no
+such script, the CLI runs its own implementation against the current project,
+so the command works in any consumer project.
+
+@module CLI/Dispatch
+*/
+export type Runner = (script: string) => Promise<number>;
+/**
+Runs a package.json script through pnpm and resolves with its exit code.
+
+Thin wrappers like `clean` and `check` delegate here so the script — not the
+CLI — remains the single source of truth for what each command does. If the
+current project defines no such script, the CLI runs its own implementation
+against the current project, so the command works in any consumer project.
+
+@example
+```ts
+const code = await runScript('check');
+```
+*/
+export declare function runScript(script: string): Promise<number>;
+/**
+Parses `argv` and routes it to the matching command, returning a process exit
+code. `run` is injectable so the script-wrapping commands can be tested without
+spawning anything.
+
+@example
+```ts
+const code = await main(['clean'], async (script) => {
+    console.log(`would run ${script}`);
+    return 0;
+});
+```
+*/
+export declare function main(argv: string[], run?: Runner): Promise<number>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/cli/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAiDF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAmFzD;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED;;;;;;;;;;;;EAYE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FnF"}