@twobirds/microcomponents 0.2.5 → 0.4.0

package/dist/cli/dispatch.js

@@ -0,0 +1,251 @@
+/**
+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
+*/
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { writeScaffold, writeProject } from './writeScaffold.js';
+import { scaffoldComponent } from './scaffold.js';
+import { scaffoldProject } from './create.js';
+const USAGE = `mc — Micro Components build tools
+
+Usage:
+  mc new <tag> [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--dry-run]
+  mc create --namespace <ns> [--dir <path>] [--dry-run]
+  mc clean
+  mc check
+
+Commands:
+  new <tag>   Scaffold a micro component (e.g. mc new my-card --target-html --target-css)
+  create      Create a dev environment (e.g. mc create --namespace mc --dir mc-app)
+  clean       Remove build artifacts (dist, public, build, coverage)
+  check       Type-check every project (lib, cli, test, demo, node)
+
+Companion assets:
+  --css           document-level stylesheet (CSS custom properties / design tokens)
+  --html          unvariant light-DOM template
+  --target-html   template applied to target.innerHTML
+  --shadow-html   template applied to shadowRoot.innerHTML
+  --target-css    document-level styles scoped to the host tag
+  --shadow-css    styles injected into the shadow root
+
+Other options:
+  --js         emit plain JavaScript instead of TypeScript
+  --dir <path> scaffold root (default: src)
+  --dry-run    print what would be written; touch nothing on disk
+`;
+// Map CLI flags to the runtime's camelCase asset descriptors.
+const ASSET_FLAGS = {
+    css: 'css',
+    html: 'html',
+    'target-html': 'targetHtml',
+    'shadow-html': 'shadowHtml',
+    'target-css': 'targetCss',
+    'shadow-css': 'shadowCss',
+};
+/**
+Spawns a command and resolves with its exit code.
+
+@example
+```ts
+const code = await spawnProcess('pnpm', ['run', 'clean']);
+```
+@param command - Executable to spawn.
+@param args - Arguments to pass.
+@param cwd - Working directory (defaults to the current one).
+*/
+function spawnProcess(command, args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { stdio: 'inherit', cwd });
+        child.on('exit', (code) => resolve(code ?? 1));
+    });
+}
+/**
+Whether the package.json in the current directory declares `script` in its
+"scripts". Consumers get this check so `mc clean`/`mc check` can fall back to
+the CLI's own implementation when the project defines no such script.
+
+@example
+```ts
+const ok = await hasScript('clean');
+```
+@param script - Script name to look up.
+*/
+async function hasScript(script) {
+    try {
+        const pkg = JSON.parse(await readFile(path.join(process.cwd(), 'package.json'), 'utf8'));
+        return typeof pkg?.scripts?.[script] === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/** Build artifacts to remove, relative to the project root. */
+const CLEAN_DIRS = ['dist', 'public', 'build', 'coverage'];
+/**
+Removes build artifacts in the current project.
+
+@example
+```ts
+const code = await cleanSelf();
+```
+@param cwd - Project root (defaults to the current directory).
+*/
+async function cleanSelf(cwd = process.cwd()) {
+    await Promise.all(CLEAN_DIRS.map(async (dir) => {
+        const abs = path.join(cwd, dir);
+        if (existsSync(abs)) {
+            await rm(abs, { recursive: true, force: true });
+            console.log(`removed ${dir}/`);
+        }
+    }));
+    return 0;
+}
+/**
+Type-checks the current project with its own `tsconfig.json`.
+
+@example
+```ts
+const code = await checkSelf();
+```
+@param cwd - Project root (defaults to the current directory).
+*/
+async function checkSelf(cwd = process.cwd()) {
+    const config = path.join(cwd, 'tsconfig.json');
+    if (!existsSync(config)) {
+        console.error('mc check: no tsconfig.json in the current project');
+        return 1;
+    }
+    return spawnProcess('pnpm', ['exec', 'tsc', '--noEmit', '-p', 'tsconfig.json'], cwd);
+}
+/**
+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 async function runScript(script) {
+    if (await hasScript(script)) {
+        return spawnProcess('pnpm', ['run', script]);
+    }
+    if (script === 'clean')
+        return cleanSelf();
+    if (script === 'check')
+        return checkSelf();
+    console.error(`mc: no "${script}" script in the current project`);
+    return 1;
+}
+/**
+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 async function main(argv, run = runScript) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            css: { type: 'boolean' },
+            html: { type: 'boolean' },
+            'target-html': { type: 'boolean' },
+            'shadow-html': { type: 'boolean' },
+            'target-css': { type: 'boolean' },
+            'shadow-css': { type: 'boolean' },
+            js: { type: 'boolean' },
+            dir: { type: 'string' },
+            namespace: { type: 'string' },
+            'dry-run': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const command = positionals[0];
+    if (values.help || !command) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (command === 'new') {
+        const tag = positionals[1];
+        if (!tag) {
+            console.error('mc new: missing component tag (e.g. mc new my-card)');
+            return 1;
+        }
+        const assets = [];
+        const flags = values;
+        for (const [flag, kind] of Object.entries(ASSET_FLAGS)) {
+            if (flags[flag])
+                assets.push(kind);
+        }
+        if (values['dry-run']) {
+            const { files } = scaffoldComponent(tag, { assets, js: values.js });
+            for (const file of Object.keys(files).sort())
+                console.log(`would create ${file}`);
+            return 0;
+        }
+        const written = await writeScaffold(tag, values.dir ?? 'src', {
+            assets,
+            js: values.js,
+        });
+        for (const file of written)
+            console.log(`created ${file}`);
+        return 0;
+    }
+    if (command === 'create') {
+        const namespace = values.namespace;
+        if (!namespace) {
+            console.error('mc create: missing --namespace (e.g. mc create --namespace mc)');
+            return 1;
+        }
+        const root = values.dir ?? namespace;
+        let files;
+        try {
+            ({ files } = scaffoldProject(namespace));
+        }
+        catch (e) {
+            console.error(e.message);
+            return 1;
+        }
+        if (values['dry-run']) {
+            for (const file of Object.keys(files).sort())
+                console.log(`would create ${file}`);
+            return 0;
+        }
+        const written = await writeProject(namespace, root);
+        for (const file of written)
+            console.log(`created ${file}`);
+        console.log(`\nproject "${namespace}" created in ${root}/ — run: cd ${root} && pnpm install && pnpm dev`);
+        return 0;
+    }
+    if (command === 'clean')
+        return run('clean');
+    if (command === 'check')
+        return run('check');
+    console.error(`mc: unknown command "${command}"\n\n${USAGE}`);
+    return 1;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+Executable entry point of the `mc` CLI (package.json "bin").
+
+Deliberately thin: all parsing and routing lives in {@link main} so it can be
+unit-tested without spawning a process. This module only feeds `process.argv`
+in and pushes the resulting exit code out.
+
+@module CLI/Index
+*/
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;EAQE"}

package/dist/cli/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+Executable entry point of the `mc` CLI (package.json "bin").
+
+Deliberately thin: all parsing and routing lives in {@link main} so it can be
+unit-tested without spawning a process. This module only feeds `process.argv`
+in and pushes the resulting exit code out.
+
+@module CLI/Index
+*/
+import { main } from './dispatch.js';
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli/scaffold.d.ts

@@ -0,0 +1,68 @@
+/**
+Scaffolding for new micro components.
+
+Pure, filesystem-free logic: given a tag name it returns the files to write and
+their contents. The tag-to-path rule 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.
+
+Companion assets follow the runtime's variant convention (see `loadAssets` /
+`processAssets`): a camelCase descriptor maps to a dotted filename, e.g.
+`'targetHtml'` → `{path}.target.html`, `'shadowCss'` → `{path}.shadow.css`, and
+the unvariant `'css'` → `{path}.css` (the document-level stylesheet where CSS
+custom properties / design tokens live).
+
+@module CLI/Scaffold
+*/
+/**
+Companion asset kinds, mirroring the camelCase descriptors the runtime loads.
+
+- `css` — document-level global stylesheet (CSS custom properties / design tokens).
+- `targetCss` — document-level styles scoped to the host tag.
+- `shadowCss` — styles injected into the shadow root.
+- `html` — unvariant light-DOM template.
+- `targetHtml` — light-DOM template applied to `target.innerHTML`.
+- `shadowHtml` — template applied to `shadowRoot.innerHTML`.
+*/
+export type AssetKind = 'css' | 'targetCss' | 'shadowCss' | 'html' | 'targetHtml' | 'shadowHtml';
+/** Options controlling which files a scaffold emits. */
+export interface ScaffoldOptions {
+    /** Companion assets to emit and wire into `static assets`. */
+    assets?: AssetKind[];
+    /** Emit a plain `.js` file instead of `.ts` (rapid-prototyping path). */
+    js?: boolean;
+}
+/** Result of {@link scaffoldComponent}. */
+export interface ScaffoldResult {
+    /** Files to write, keyed by path relative to the scaffold root (e.g. `my/card.ts`). */
+    files: Record<string, string>;
+    /** The PascalCase class name derived from the tag. */
+    className: string;
+}
+/**
+Whether a string is a valid micro component tag name.
+
+@example
+```ts
+console.log(isValidComponentTag('my-card'));
+console.log(isValidComponentTag('mycard'));
+```
+*/
+export declare function isValidComponentTag(tag: string): boolean;
+/**
+Builds the files for a new micro component from its tag name.
+
+@example
+```ts
+const { className, files } = scaffoldComponent('my-card', {
+    assets: ['targetHtml', 'targetCss'],
+});
+console.log(className);
+console.log(Object.keys(files));
+```
+@param tag - Kebab-case component tag, e.g. `my-card`.
+@param options - Which companion assets to emit and whether to use `.js`.
+@throws If `tag` is not a valid custom element name.
+*/
+export declare function scaffoldComponent(tag: string, options?: ScaffoldOptions): ScaffoldResult;
+//# sourceMappingURL=scaffold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AAIF;;;;;;;;;EASE;AACF,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;AAEjG,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;CACb;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC9B,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;EAQE;AACF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;EAcE;AACF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAuB5F"}

package/dist/cli/scaffold.js

@@ -0,0 +1,109 @@
+/**
+Scaffolding for new micro components.
+
+Pure, filesystem-free logic: given a tag name it returns the files to write and
+their contents. The tag-to-path rule 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.
+
+Companion assets follow the runtime's variant convention (see `loadAssets` /
+`processAssets`): a camelCase descriptor maps to a dotted filename, e.g.
+`'targetHtml'` → `{path}.target.html`, `'shadowCss'` → `{path}.shadow.css`, and
+the unvariant `'css'` → `{path}.css` (the document-level stylesheet where CSS
+custom properties / design tokens live).
+
+@module CLI/Scaffold
+*/
+import { tagPath } from '../utils/resolveComponentPath.js';
+// Custom element names must be lowercase kebab-case and contain at least one
+// hyphen (defineCE rejects hyphenless tags), with no empty segments.
+const TAG_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+/**
+Whether a string is a valid micro component tag name.
+
+@example
+```ts
+console.log(isValidComponentTag('my-card'));
+console.log(isValidComponentTag('mycard'));
+```
+*/
+export function isValidComponentTag(tag) {
+    return TAG_RE.test(tag);
+}
+/**
+Builds the files for a new micro component from its tag name.
+
+@example
+```ts
+const { className, files } = scaffoldComponent('my-card', {
+    assets: ['targetHtml', 'targetCss'],
+});
+console.log(className);
+console.log(Object.keys(files));
+```
+@param tag - Kebab-case component tag, e.g. `my-card`.
+@param options - Which companion assets to emit and whether to use `.js`.
+@throws If `tag` is not a valid custom element name.
+*/
+export function scaffoldComponent(tag, options = {}) {
+    if (!isValidComponentTag(tag)) {
+        throw new Error(`invalid component tag "${tag}": must be kebab-case with at least one hyphen (e.g. "my-card")`);
+    }
+    const className = tag
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+    const ext = options.js ? 'js' : 'ts';
+    const ctorParam = options.js ? 'target' : 'target: HTMLElement';
+    const base = tagPath(tag);
+    const assets = [...new Set(options.assets ?? [])];
+    const files = {};
+    files[`${base}.${ext}`] = componentSource(tag, ctorParam, assets);
+    for (const kind of assets) {
+        files[assetFile(tag, kind)] = assetSource(kind, tag);
+    }
+    return { files, className };
+}
+// Mirrors loadAssets' parseAsset: camelCase variant+ext → dotted filename,
+// plain ext → single extension. Reuses tagPath so scaffold and runtime agree.
+function assetFile(tag, kind) {
+    const m = kind.match(/^([a-z]+)([A-Z][a-z]*)$/);
+    const suffix = m ? `.${m[1]}.${m[2].toLowerCase()}` : `.${kind.toLowerCase()}`;
+    return `${tagPath(tag)}${suffix}`;
+}
+function componentSource(tag, ctorParam, assets) {
+    const lines = [
+        `import { DC, defineCE } from '@twobirds/microcomponents';`,
+        ``,
+        `/**`,
+        `\`${tag}\` — describe what this micro component does.`,
+        ``,
+        `@example`,
+        '```html',
+        `<${tag}></${tag}>`,
+        '```',
+        `*/`,
+        `defineCE(`,
+        `\t'${tag}',`,
+        `\tclass extends DC {`,
+    ];
+    if (assets.length) {
+        lines.push(`\t\tstatic assets = [${assets.map((a) => `'${a}'`).join(', ')}];`);
+    }
+    lines.push(`\t\tconstructor(${ctorParam}) {`, `\t\t\tsuper(target);`, `\t\t}`, `\t}`, `);`, ``);
+    return lines.join('\n');
+}
+function assetSource(kind, tag) {
+    switch (kind) {
+        case 'css':
+            // Document-level global stylesheet — the home of CSS custom properties.
+            return [':root {', '\t/* design tokens (CSS custom properties) */', '}', ''].join('\n');
+        case 'targetCss':
+            return [`${tag} {`, '\tdisplay: block;', '}', ''].join('\n');
+        case 'shadowCss':
+            return [':host {', '\tdisplay: block;', '}', ''].join('\n');
+        default:
+            // html / targetHtml / shadowHtml
+            return '<slot></slot>\n';
+    }
+}

package/dist/cli/writeScaffold.d.ts

@@ -0,0 +1,37 @@
+/**
+Filesystem side of {@link scaffoldComponent}: writes the generated files under a
+root directory, creating nested folders as needed.
+
+@module CLI/Scaffold
+*/
+import { type ScaffoldOptions } from './scaffold.js';
+/**
+Scaffolds a component onto disk under `root`.
+
+@example
+```ts
+const written = await writeScaffold('my-card', 'src', { assets: ['css'] });
+console.log(written);
+```
+@param tag - Kebab-case component tag.
+@param root - Directory to scaffold under (e.g. `src`).
+@param options - Which companion files to emit.
+@returns The written file paths, relative to `root`.
+*/
+export declare function writeScaffold(tag: string, root: string, options?: ScaffoldOptions): Promise<string[]>;
+/**
+Filesystem side of {@link scaffoldProject}: writes a complete dev environment for a
+namespace under a project root, creating nested folders as needed.
+
+@example
+```ts
+const written = await writeProject('mc', 'mc-app');
+console.log(written);
+```
+@param namespace - 1 to 4 lowercase letters.
+@param root - Directory to create the project in (e.g. `mc-app`).
+@returns The written file paths, relative to `root`.
+@throws If `namespace` is not 1 to 4 lowercase letters.
+*/
+export declare function writeProject(namespace: string, root: string): Promise<string[]>;
+//# sourceMappingURL=writeScaffold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeScaffold.d.ts","sourceRoot":"","sources":["../../src/cli/writeScaffold.ts"],"names":[],"mappings":"AACA;;;;;EAKE;AAIF,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGxE;;;;;;;;;;;;EAYE;AACF,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB;AAED;;;;;;;;;;;;;EAaE;AACF,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrF"}

package/dist/cli/writeScaffold.js

@@ -0,0 +1,60 @@
+// oxlint-disable no-await-in-loop
+/**
+Filesystem side of {@link scaffoldComponent}: writes the generated files under a
+root directory, creating nested folders as needed.
+
+@module CLI/Scaffold
+*/
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { scaffoldComponent } from './scaffold.js';
+import { scaffoldProject } from './create.js';
+/**
+Scaffolds a component onto disk under `root`.
+
+@example
+```ts
+const written = await writeScaffold('my-card', 'src', { assets: ['css'] });
+console.log(written);
+```
+@param tag - Kebab-case component tag.
+@param root - Directory to scaffold under (e.g. `src`).
+@param options - Which companion files to emit.
+@returns The written file paths, relative to `root`.
+*/
+export async function writeScaffold(tag, root, options = {}) {
+    const { files } = scaffoldComponent(tag, options);
+    const written = [];
+    for (const [rel, contents] of Object.entries(files)) {
+        const abs = path.join(root, rel);
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, contents, 'utf8');
+        written.push(rel);
+    }
+    return written;
+}
+/**
+Filesystem side of {@link scaffoldProject}: writes a complete dev environment for a
+namespace under a project root, creating nested folders as needed.
+
+@example
+```ts
+const written = await writeProject('mc', 'mc-app');
+console.log(written);
+```
+@param namespace - 1 to 4 lowercase letters.
+@param root - Directory to create the project in (e.g. `mc-app`).
+@returns The written file paths, relative to `root`.
+@throws If `namespace` is not 1 to 4 lowercase letters.
+*/
+export async function writeProject(namespace, root) {
+    const { files } = scaffoldProject(namespace);
+    const written = [];
+    for (const [rel, contents] of Object.entries(files)) {
+        const abs = path.join(root, rel);
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, contents, 'utf8');
+        written.push(rel);
+    }
+    return written;
+}