npm - @sprlab/wccompiler - Versions diffs - 0.11.12 → 0.12.1 - Mend

@sprlab/wccompiler 0.11.12 → 0.12.1

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 (8) hide show

package/README.md +46 -7
package/bin/wcc.js +53 -0
package/lib/codegen.js +13 -2
package/lib/compiler.js +38 -73
package/lib/import-resolver.js +160 -0
package/lib/template-normalizer.js +23 -3
package/lib/types.js +3 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -458,12 +458,13 @@ Consumer (receives data via template props):
 ## Nested Components
-Components can use other components in their templates. Import the child `.wcc` file and use its tag in the template:
+Components can import and use other components in their templates using PascalCase tags:
 ```html
+<!-- src/nested/wcc-profile.wcc -->
 <script>
 import { defineComponent, signal } from 'wcc'
-import './wcc-badge.wcc'
+import WccBadge from './wcc-badge.wcc'
 export default defineComponent({ tag: 'wcc-profile' })
@@ -476,15 +477,17 @@ function increment() {
 <template>
 <div class="profile">
-  <wcc-badge :count="count()" @click="increment"></wcc-badge>
+  <WccBadge :count="count()" @click="increment"></WccBadge>
 </div>
 </template>
 ```
-- **Manual import**: `import './wcc-child.wcc'` — the compiler registers the child component
-- **Auto-detect**: If a custom element tag in the template matches a `.wcc` file in the same directory, it's auto-imported
+- **Named import**: `import WccBadge from './wcc-badge.wcc'` — the PascalCase identifier becomes the tag alias in the template
+- **Side-effect import**: `import './wcc-child.wcc'` — registers the child without using it in the template (for programmatic creation)
 - **Reactive props**: Use `:prop="expr"` to pass reactive data down — updates automatically when the expression changes
 - **Event listening**: Use `@event="handler"` to listen to custom events emitted by the child
+- **Compile-time validation**: Using a PascalCase tag without a matching import throws an error at build time
+- **Hyphenated tags**: Tags like `<my-element>` without a corresponding import are treated as plain custom elements (no import generated)
 ## Lifecycle Hooks
@@ -613,12 +616,48 @@ timer.value!.start() // ✅ typed
 ## CLI
 ```bash
-wcc build    # Compile all .wcc files from input/ to output/
-wcc dev      # Build + watch + live-reload dev server
+wcc build              # Compile all .wcc files from input/ to output/
+wcc build --bundle     # Compile + produce a single bundle.js (works from file://)
+wcc build --minify     # Compile with minification
+wcc build --bundle --minify  # Production bundle (smallest output)
+wcc dev                # Build + watch + live-reload dev server
 ```
 The CLI discovers all `.wcc` files in your source directory and compiles each into a standalone `.js` file.
+### Bundle Mode
+The `--bundle` flag produces a single `bundle.js` file that includes all components and their dependencies in one IIFE (Immediately Invoked Function Expression). This file:
+- Works with `<script src="bundle.js">` (no `type="module"` needed)
+- Works from `file://` protocol (no server required)
+- Includes all child component imports resolved and inlined
+- Includes the reactive runtime
+- Supports `--minify` for production
+```html
+<!-- Works by double-clicking the HTML file — no server needed -->
+<!DOCTYPE html>
+<html>
+<body>
+  <wcc-my-app></wcc-my-app>
+  <script src="dist/bundle.js"></script>
+</body>
+</html>
+```
+**When to use `--bundle`:**
+- Static HTML files opened from disk
+- Electron apps loading local files
+- Offline-first applications
+- Quick prototyping without a dev server
+- Distributing a complete app as HTML + JS
+**When NOT to use `--bundle`:**
+- Apps served via HTTP (use ES modules for better caching)
+- When you need per-component lazy loading
+- When using a bundler like Vite/Webpack (they handle bundling themselves)
 ### Configuration
 Create `wcc.config.js` in your project root:

package/bin/wcc.js CHANGED Viewed

@@ -291,6 +291,26 @@ function discoverFiles(dir) {
   return results;
 }
+/**
+ * Discovers compiled .js entry points in the output directory.
+ * Excludes runtime files, stubs, and metadata.
+ */
+function discoverCompiledEntries(outputDir) {
+  const skip = new Set(['__wcc-signals.js', 'wcc-runtime.js', 'wcc-react.js', 'wcc-vue.js', 'bundle.js']);
+  const results = [];
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith('.js') && !skip.has(entry.name) && !entry.name.endsWith('.d.ts')) {
+        results.push(join(dir, entry.name));
+      }
+    }
+  }
+  walk(outputDir);
+  return results;
+}
 async function main() {
   const cwd = process.cwd();
   const config = await loadConfig(cwd);
@@ -298,10 +318,43 @@ async function main() {
   // CLI flags override config
   if (process.argv.includes('--minify')) config.minify = true;
   if (process.argv.includes('--comments')) config.comments = true;
+  const shouldBundle = process.argv.includes('--bundle');
   if (command === 'build') {
     const errors = await build(config, cwd);
     if (errors > 0) process.exit(1);
+    // Bundle step: produce a single IIFE file from all compiled entry points
+    if (shouldBundle) {
+      const { build: esbuild } = await import('esbuild');
+      const outputDir = resolve(cwd, config.output);
+      const entryPoints = discoverCompiledEntries(outputDir);
+      if (entryPoints.length > 0) {
+        // Generate a virtual entry that imports all components
+        const bundleEntry = join(outputDir, '__bundle-entry.js');
+        const imports = entryPoints.map(f => {
+          let rel = relative(outputDir, f).replace(/\\/g, '/');
+          if (!rel.startsWith('.')) rel = './' + rel;
+          return `import '${rel}';`;
+        }).join('\n');
+        writeFileSync(bundleEntry, imports);
+        await esbuild({
+          entryPoints: [bundleEntry],
+          bundle: true,
+          format: 'iife',
+          outfile: join(outputDir, 'bundle.js'),
+          minify: !!config.minify,
+        });
+        // Clean up temp entry
+        const { unlinkSync } = await import('node:fs');
+        unlinkSync(bundleEntry);
+        console.log(`Bundled ${entryPoints.length} components → ${config.output}/bundle.js`);
+      }
+    }
   } else if (command === 'dev') {
     await build(config, cwd);
     const outputDir = resolve(cwd, config.output);

package/lib/codegen.js CHANGED Viewed

@@ -923,7 +923,14 @@ export function generateComponent(parseResult, options = {}) {
   // ── 1b. Child component imports ──
   for (const ci of childImports) {
-    lines.push(`import '${ci.importPath}';`);
+    if (ci.sideEffect) {
+      // Side-effect import: no identifier, child self-registers
+      lines.push(`import '${ci.importPath}';`);
+    } else {
+      // Named import with guarded registration
+      lines.push(`import ${ci.identifier} from '${ci.importPath}';`);
+      lines.push(`if (!customElements.get(${ci.identifier}.__meta.tag)) customElements.define(${ci.identifier}.__meta.tag, ${ci.identifier});`);
+    }
   }
   if (childImports.length > 0) {
     lines.push('');
@@ -2012,7 +2019,11 @@ export function generateComponent(parseResult, options = {}) {
   lines.push('');
   // ── 5. Custom element registration ──
-  lines.push(`customElements.define('${tagName}', ${className});`);
+  lines.push(`if (!customElements.get('${tagName}')) customElements.define('${tagName}', ${className});`);
+  lines.push('');
+  // ── 6. Default export (enables named imports from parent components) ──
+  lines.push(`export default ${className};`);
   return lines.join('\n');
 }

package/lib/compiler.js CHANGED Viewed

@@ -7,8 +7,8 @@
  */
 import { parseHTML } from 'linkedom';
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, extname, basename, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { walkTree, processIfChains, processForBlocks, recomputeAnchorPath, detectRefs } from './tree-walker.js';
 import { generateComponent } from './codegen.js';
 import { parseSFC } from './sfc-parser.js';
@@ -43,30 +43,8 @@ import {
   validateUndeclaredEmits,
 } from './parser-extractors.js';
 import { stripTypes } from './parser.js';
-import { normalizeTemplate } from './template-normalizer.js';
-/**
- * Resolve a child component's source file path by tag name.
- *
- * Searches for a file named after the tag in the source directory,
- * trying extensions in priority order: .wcc, .js, .ts
- *
- * @param {string} tag — The custom element tag name (e.g., 'wcc-child')
- * @param {string} sourceDir — Directory of the parent component
- * @param {object} [config] — Optional config (reserved for future use)
- * @returns {string | null} Relative import path (e.g., './wcc-child.js') or null if not found
- */
-function resolveChildComponent(tag, sourceDir, config) {
-  const extensions = ['.wcc', '.js', '.ts'];
-  for (const ext of extensions) {
-    const candidate = resolve(sourceDir, `${tag}${ext}`);
-    if (existsSync(candidate)) {
-      // Return as a relative .js import path (compiled output)
-      return `./${tag}.js`;
-    }
-  }
-  return null;
-}
+import { normalizeTemplate, pascalToKebab } from './template-normalizer.js';
+import { extractWccImports } from './import-resolver.js';
 /**
  * Compile a single .wcc SFC file into a self-contained JS component.
@@ -88,14 +66,38 @@ async function compileSFC(filePath, config) {
   // 2. Process script block — mirrors parser.js logic
   let source = stripMacroImport(descriptor.script);
-  // 2b. Extract manual .wcc imports (e.g. import './child.wcc') and strip them from source
-  const manualImports = [];
-  const wccImportRe = /import\s+['"]([^'"]+\.wcc)['"]\s*;?/g;
-  let wccImportMatch;
-  while ((wccImportMatch = wccImportRe.exec(source)) !== null) {
-    manualImports.push(wccImportMatch[1].replace(/\.wcc$/, '.js'));
+  // 2b. Extract .wcc imports using the import resolver
+  const wccImports = extractWccImports(source, fileName);
+  // Build importMap: PascalCase identifier → kebab-case tag
+  /** @type {Map<string, string>} */
+  const importMap = new Map();
+  for (const imp of wccImports.named) {
+    importMap.set(imp.identifier, pascalToKebab(imp.identifier));
+  }
+  // Build childImports from extracted imports
+  /** @type {import('./types.js').ChildComponentImport[]} */
+  const childImports = [];
+  for (const imp of wccImports.named) {
+    childImports.push({
+      tag: pascalToKebab(imp.identifier),
+      identifier: imp.identifier,
+      importPath: imp.compiledPath,
+      sideEffect: false,
+    });
+  }
+  for (const imp of wccImports.sideEffect) {
+    childImports.push({
+      tag: '',
+      identifier: '',
+      importPath: imp.compiledPath,
+      sideEffect: true,
+    });
   }
-  source = source.replace(wccImportRe, '');
+  // Use strippedSource (with .wcc imports removed) for subsequent extraction steps
+  source = wccImports.strippedSource;
   // 3. Extract props/emits from generic forms BEFORE type stripping
   const propsFromGeneric = extractPropsGeneric(source);
@@ -291,7 +293,7 @@ async function compileSFC(filePath, config) {
   };
   // 16. Process template through linkedom → tree-walker → codegen
-  const normalizedTemplate = normalizeTemplate(template);
+  const normalizedTemplate = normalizeTemplate(template, { importMap, fileName });
   const { document } = parseHTML(`<div id="__root">${normalizedTemplate}</div>`);
   const rootEl = document.getElementById('__root');
@@ -395,39 +397,8 @@ async function compileSFC(filePath, config) {
     }
   }
-  // 18. Resolve child component imports (from main template + if branches + each blocks)
-  /** @type {import('./types.js').ChildComponentImport[]} */
-  const childImports = [];
-  const allChildTags = new Set(childComponents.map(c => c.tag));
-  // Collect child tags from if branches
-  for (const ifBlock of ifBlocks) {
-    for (const branch of ifBlock.branches) {
-      if (branch.childComponents) {
-        for (const cc of branch.childComponents) allChildTags.add(cc.tag);
-      }
-    }
-  }
-  // Collect child tags from each blocks
-  for (const forBlock of forBlocks) {
-    if (forBlock.childComponents) {
-      for (const cc of forBlock.childComponents) allChildTags.add(cc.tag);
-    }
-  }
-  if (allChildTags.size > 0) {
-    const sourceDir = dirname(filePath);
-    for (const tag of allChildTags) {
-      const resolved = resolveChildComponent(tag, sourceDir, config);
-      if (resolved) {
-        childImports.push({ tag, importPath: resolved });
-      } else {
-        console.warn(`Warning: child component <${tag}> used in template but source file not found`);
-      }
-    }
-  }
+  // 18. Child imports already built from extractWccImports (step 2b)
+  // No filesystem scanning needed — imports are explicit
   // 19. Merge tree-walker results into ParseResult
   parseResult.bindings = bindings;
@@ -442,12 +413,6 @@ async function compileSFC(filePath, config) {
   parseResult.refBindings = refBindings;
   parseResult.childComponents = childComponents;
-  // Add manual .wcc imports from script block
-  for (const imp of manualImports) {
-    if (!childImports.find(ci => ci.importPath === imp)) {
-      childImports.push({ tag: '', importPath: imp });
-    }
-  }
   parseResult.childImports = childImports;
   parseResult.processedTemplate = rootEl.innerHTML;

package/lib/import-resolver.js ADDED Viewed

@@ -0,0 +1,160 @@
+/**
+ * Import resolver for .wcc component imports.
+ *
+ * Extracts and validates `.wcc` import statements from the script block,
+ * producing a structured representation of named default imports and
+ * side-effect imports. Rejects invalid import forms (namespace, named exports).
+ */
+// ── Types ────────────────────────────────────────────────────────────
+/**
+ * @typedef {Object} WccNamedImport
+ * @property {string} identifier  — The import name (e.g., 'WccBadge', 'MyButton')
+ * @property {string} sourcePath  — Original .wcc path (e.g., './wcc-badge.wcc')
+ * @property {string} compiledPath — Rewritten .js path (e.g., './wcc-badge.js')
+ */
+/**
+ * @typedef {Object} WccSideEffectImport
+ * @property {string} sourcePath   — Original .wcc path (e.g., './child.wcc')
+ * @property {string} compiledPath — Rewritten .js path (e.g., './child.js')
+ */
+/**
+ * @typedef {Object} WccImportResult
+ * @property {WccNamedImport[]} named       — Named default imports
+ * @property {WccSideEffectImport[]} sideEffect — Side-effect imports
+ * @property {string} strippedSource        — Script source with .wcc imports removed
+ */
+// ── Regex patterns ───────────────────────────────────────────────────
+/**
+ * Matches any import statement that references a .wcc file.
+ * Captures the full import line for removal and classification.
+ *
+ * Groups:
+ *  - Full match: the entire import statement line
+ *
+ * We use individual patterns below for classification.
+ */
+const WCC_IMPORT_LINE_RE = /^[ \t]*import\s+.*?['"]([^'"]+\.wcc)['"]\s*;?[ \t]*$/gm;
+/**
+ * Named default import: import Identifier from './path.wcc'
+ */
+const NAMED_DEFAULT_RE = /^[ \t]*import\s+([$\w]+)\s+from\s+['"]([^'"]+\.wcc)['"]\s*;?[ \t]*$/;
+/**
+ * Side-effect import: import './path.wcc'
+ */
+const SIDE_EFFECT_RE = /^[ \t]*import\s+['"]([^'"]+\.wcc)['"]\s*;?[ \t]*$/;
+/**
+ * Namespace import: import * as Foo from './path.wcc'
+ */
+const NAMESPACE_RE = /^[ \t]*import\s+\*\s+as\s+\w+\s+from\s+['"][^'"]+\.wcc['"]\s*;?[ \t]*$/;
+/**
+ * Named exports import: import { Foo } from './path.wcc'
+ * Also matches: import { Foo, Bar } from './path.wcc'
+ * Also matches: import { Foo as Bar } from './path.wcc'
+ */
+const NAMED_EXPORTS_RE = /^[ \t]*import\s+\{[^}]*\}\s+from\s+['"][^'"]+\.wcc['"]\s*;?[ \t]*$/;
+// ── Helpers ──────────────────────────────────────────────────────────
+/**
+ * Rewrite a .wcc path to .js by replacing the extension.
+ * Preserves all relative path segments.
+ *
+ * @param {string} wccPath — e.g., '../shared/wcc-button.wcc'
+ * @returns {string} — e.g., '../shared/wcc-button.js'
+ */
+function rewriteExtension(wccPath) {
+  return wccPath.replace(/\.wcc$/, '.js');
+}
+// ── Main export ──────────────────────────────────────────────────────
+/**
+ * Extract all .wcc imports from a script source string.
+ * Validates import forms and rejects invalid patterns.
+ *
+ * @param {string} source — Script block content
+ * @param {string} fileName — Source file name for error messages
+ * @returns {WccImportResult}
+ * @throws {Error} with code 'INVALID_WCC_IMPORT' for namespace/named exports
+ */
+export function extractWccImports(source, fileName) {
+  /** @type {WccNamedImport[]} */
+  const named = [];
+  /** @type {WccSideEffectImport[]} */
+  const sideEffect = [];
+  // Collect all .wcc import lines for processing
+  const lines = source.split('\n');
+  /** @type {Set<number>} */
+  const linesToRemove = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Check if this line contains a .wcc import
+    if (!line.match(/import\s.*\.wcc['"]/) && !line.match(/import\s+['"][^'"]+\.wcc['"]/)) {
+      continue;
+    }
+    // Check for invalid forms first
+    if (NAMESPACE_RE.test(line)) {
+      const error = new Error(
+        `Invalid import form in '${fileName}': .wcc files only support default imports (import Foo from './foo.wcc') or side-effect imports (import './foo.wcc')`
+      );
+      /** @ts-expect-error — custom error code for programmatic handling */
+      error.code = 'INVALID_WCC_IMPORT';
+      throw error;
+    }
+    if (NAMED_EXPORTS_RE.test(line)) {
+      const error = new Error(
+        `Invalid import form in '${fileName}': .wcc files only support default imports (import Foo from './foo.wcc') or side-effect imports (import './foo.wcc')`
+      );
+      /** @ts-expect-error — custom error code for programmatic handling */
+      error.code = 'INVALID_WCC_IMPORT';
+      throw error;
+    }
+    // Check for named default import
+    const namedMatch = line.match(NAMED_DEFAULT_RE);
+    if (namedMatch) {
+      const identifier = namedMatch[1];
+      const sourcePath = namedMatch[2];
+      named.push({
+        identifier,
+        sourcePath,
+        compiledPath: rewriteExtension(sourcePath),
+      });
+      linesToRemove.add(i);
+      continue;
+    }
+    // Check for side-effect import
+    const sideEffectMatch = line.match(SIDE_EFFECT_RE);
+    if (sideEffectMatch) {
+      const sourcePath = sideEffectMatch[1];
+      sideEffect.push({
+        sourcePath,
+        compiledPath: rewriteExtension(sourcePath),
+      });
+      linesToRemove.add(i);
+      continue;
+    }
+  }
+  // Build stripped source by removing .wcc import lines
+  const strippedLines = lines.filter((_, i) => !linesToRemove.has(i));
+  const strippedSource = strippedLines.join('\n');
+  return { named, sideEffect, strippedSource };
+}

package/lib/template-normalizer.js CHANGED Viewed

@@ -45,13 +45,19 @@ export function isPascalCase(name) {
 /**
  * Normalize a WCC template string:
- * 1. Convert PascalCase tags to kebab-case
+ * 1. Convert PascalCase tags to kebab-case (validated against importMap if provided)
  * 2. Expand self-closing custom elements to open+close pairs
  *
  * @param {string} html — Raw template HTML
+ * @param {object} [options]
+ * @param {Map<string, string>} [options.importMap] — PascalCase identifier → kebab-case tag
+ * @param {string} [options.fileName] — Source file for error messages
  * @returns {string} — Normalized HTML ready for DOM parsing
+ * @throws {Error} with code 'UNRESOLVED_COMPONENT' if PascalCase tag has no matching import
  */
-export function normalizeTemplate(html) {
+export function normalizeTemplate(html, options) {
+  const { importMap, fileName } = options || {};
   // Match opening tags (including self-closing): <TagName ...> or <TagName ... />
   // Also match closing tags: </TagName>
   //
@@ -69,7 +75,21 @@ export function normalizeTemplate(html) {
     // Step 1: Convert PascalCase to kebab-case
     if (isPascalCase(tagName)) {
-      normalizedTag = pascalToKebab(tagName);
+      if (importMap) {
+        // Validate against the import map
+        if (importMap.has(tagName)) {
+          normalizedTag = importMap.get(tagName);
+        } else {
+          const error = new Error(
+            `Unresolved component '<${tagName}>' in '${fileName || 'unknown'}'. Did you forget to import it?`
+          );
+          error.code = 'UNRESOLVED_COMPONENT';
+          throw error;
+        }
+      } else {
+        // Backward compatible: convert all PascalCase to kebab-case
+        normalizedTag = pascalToKebab(tagName);
+      }
     }
     // Step 2: Handle self-closing tags

package/lib/types.js CHANGED Viewed

@@ -221,8 +221,10 @@
 /**
  * @typedef {Object} ChildComponentImport
- * @property {string} tag          — Child component tag name
+ * @property {string} tag          — Child component tag name (kebab-case, used in template)
+ * @property {string} identifier   — Import identifier (PascalCase, e.g., 'WccBadge')
  * @property {string} importPath   — Relative import path (e.g., './wcc-badge.js')
+ * @property {boolean} sideEffect  — true if this is a side-effect import (no identifier)
  */
 /**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@sprlab/wccompiler",
-  "version": "0.11.12",
+  "version": "0.12.1",
   "description": "Zero-runtime compiler that transforms .wcc single-file components into native web components with signals-based reactivity",
   "type": "module",
   "exports": {