npm - @sprlab/wccompiler - Versions diffs - 0.12.0 → 0.13.0 - Mend

@sprlab/wccompiler 0.12.0 → 0.13.0

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 +46 -1
package/lib/compiler.js +7 -1
package/lib/template-normalizer.js +5 -0
package/lib/tree-walker.js +91 -1
package/lib/types.js +22 -0
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

@@ -877,6 +877,7 @@ export function generateComponent(parseResult, options = {}) {
     childImports = [],
     exposeNames = [],
     modelDefs = [],
+    dynamicComponents = [],
   } = parseResult;
   const signalNames = signals.map(s => s.name);
@@ -903,7 +904,7 @@ export function generateComponent(parseResult, options = {}) {
   // ── 1. Reactive runtime (shared import or inline) ──
   if (options.comments) lines.push('// ── Runtime ──────────────────────────────────────────');
   // Determine which runtime functions this component needs
-  const needsEffect = effects.length > 0 || bindings.length > 0 || showBindings.length > 0 || modelBindings.length > 0 || modelPropBindings.length > 0 || attrBindings.length > 0 || ifBlocks.length > 0 || forBlocks.length > 0 || watchers.length > 0 || childComponents.length > 0 || slots.some(s => s.slotProps.length > 0);
+  const needsEffect = effects.length > 0 || bindings.length > 0 || showBindings.length > 0 || modelBindings.length > 0 || modelPropBindings.length > 0 || attrBindings.length > 0 || ifBlocks.length > 0 || forBlocks.length > 0 || watchers.length > 0 || childComponents.length > 0 || dynamicComponents.length > 0 || slots.some(s => s.slotProps.length > 0);
   const needsComputed = computeds.length > 0;
   const needsUntrack = watchers.length > 0;
@@ -1186,6 +1187,15 @@ export function generateComponent(parseResult, options = {}) {
     lines.push(`    this.${vn}_nodes = [];`);
   }
+  // ── dynamic component: anchor reference, state init ──
+  for (const dyn of dynamicComponents) {
+    const vn = dyn.varName;
+    lines.push(`    this.${vn}_anchor = ${pathExpr(dyn.anchorPath, '__root')};`);
+    lines.push(`    this.${vn}_current = null;`);
+    lines.push(`    this.${vn}_tag = null;`);
+    lines.push(`    this.${vn}_propDisposers = [];`);
+  }
   // ── Ref DOM reference assignments (before appendChild moves nodes) ──
   for (const rb of refBindings) {
     lines.push(`    this._ref_${rb.refName} = ${pathExpr(rb.path, '__root')};`);
@@ -1671,6 +1681,41 @@ export function generateComponent(parseResult, options = {}) {
     }
   }
+  // ── dynamic component effects ──
+  for (const dyn of dynamicComponents) {
+    const vn = dyn.varName;
+    const isExpr = transformExpr(dyn.isExpression, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, constantNames, methodNames, modelVarMap);
+    lines.push('    this.__disposers.push(__effect(() => {');
+    lines.push(`      const __tag = ${isExpr};`);
+    lines.push(`      if (__tag === this.${vn}_tag) return;`);
+    lines.push(`      if (this.${vn}_current) {`);
+    lines.push(`        this.${vn}_propDisposers.forEach(d => d());`);
+    lines.push(`        this.${vn}_propDisposers = [];`);
+    lines.push(`        this.${vn}_current.remove();`);
+    lines.push(`        this.${vn}_current = null;`);
+    lines.push('      }');
+    lines.push('      if (__tag) {');
+    lines.push('        const el = document.createElement(__tag);');
+    // Emit nested prop effects
+    for (const prop of dyn.props) {
+      const propExprTransformed = transformExpr(prop.expression, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, constantNames, methodNames, modelVarMap);
+      lines.push(`        this.${vn}_propDisposers.push(__effect(() => {`);
+      lines.push(`          el.setAttribute('${prop.attr}', ${propExprTransformed});`);
+      lines.push('        }));');
+    }
+    // Emit event listeners
+    for (const evt of dyn.events) {
+      const handlerExpr = generateEventHandler(evt.handler, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, constantNames, modelVarMap);
+      lines.push(`        el.addEventListener('${evt.event}', ${handlerExpr});`);
+    }
+    lines.push(`        this.${vn}_anchor.parentNode.insertBefore(el, this.${vn}_anchor);`);
+    lines.push('        customElements.upgrade(el);');
+    lines.push(`        this.${vn}_current = el;`);
+    lines.push('      }');
+    lines.push(`      this.${vn}_tag = __tag;`);
+    lines.push('    }));');
+  }
   // Lifecycle: onMount hooks (at the very end of connectedCallback)
   for (const hook of onMountHooks) {
     const body = transformMethodBody(hook.body, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, refVarNames, constantNames, modelVarMap);

package/lib/compiler.js CHANGED Viewed

@@ -9,7 +9,7 @@
 import { parseHTML } from 'linkedom';
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
-import { walkTree, processIfChains, processForBlocks, recomputeAnchorPath, detectRefs } from './tree-walker.js';
+import { walkTree, processIfChains, processForBlocks, processDynamicComponents, recomputeAnchorPath, detectRefs } from './tree-walker.js';
 import { generateComponent } from './codegen.js';
 import { parseSFC } from './sfc-parser.js';
 import {
@@ -290,6 +290,7 @@ async function compileSFC(filePath, config) {
     childImports: [],
     exposeNames,
     modelDefs,
+    dynamicComponents: [],
   };
   // 16. Process template through linkedom → tree-walker → codegen
@@ -307,6 +308,7 @@ async function compileSFC(filePath, config) {
   const forBlocks = processForBlocks(rootEl, [], signalNames, computedNames, propNamesSet);
   const ifBlocks = processIfChains(rootEl, [], signalNames, computedNames, propNamesSet);
+  const dynamicComponents = processDynamicComponents(rootEl, []);
   rootEl.normalize();
@@ -316,6 +318,9 @@ async function compileSFC(filePath, config) {
   for (const ib of ifBlocks) {
     ib.anchorPath = recomputeAnchorPath(rootEl, ib._anchorNode);
   }
+  for (const dc of dynamicComponents) {
+    dc.anchorPath = recomputeAnchorPath(rootEl, dc._anchorNode);
+  }
   const { bindings, events, showBindings, modelBindings, modelPropBindings, attrBindings, slots, childComponents } = walkTree(rootEl, signalNames, computedNames, propNamesSet);
@@ -412,6 +417,7 @@ async function compileSFC(filePath, config) {
   parseResult.slots = slots;
   parseResult.refBindings = refBindings;
   parseResult.childComponents = childComponents;
+  parseResult.dynamicComponents = dynamicComponents;
   parseResult.childImports = childImports;
   parseResult.processedTemplate = rootEl.innerHTML;

package/lib/template-normalizer.js CHANGED Viewed

@@ -71,6 +71,11 @@ export function normalizeTemplate(html, options) {
   const TAG_RE = /<(\/?)([A-Za-z][\w-]*)((?:\s[^>]*?)?)(\/?)>/g;
   return html.replace(TAG_RE, (match, closingSlash, tagName, attrs, selfClosing) => {
+    // Guard: preserve <component> tags as-is — this is a compiler directive, not a custom element
+    if (tagName.toLowerCase() === 'component') {
+      return match;
+    }
     let normalizedTag = tagName;
     // Step 1: Convert PascalCase to kebab-case

package/lib/tree-walker.js CHANGED Viewed

@@ -15,7 +15,7 @@
 import { parseHTML } from 'linkedom';
 import { BOOLEAN_ATTRIBUTES } from './types.js';
-/** @import { Binding, EventBinding, IfBlock, IfBranch, ShowBinding, AttrBinding, ForBlock, ModelBinding, ModelPropBinding, SlotBinding, SlotProp, RefBinding, ChildComponentBinding, ChildPropBinding } from './types.js' */
+/** @import { Binding, EventBinding, IfBlock, IfBranch, ShowBinding, AttrBinding, ForBlock, ModelBinding, ModelPropBinding, SlotBinding, SlotProp, RefBinding, ChildComponentBinding, ChildPropBinding, DynamicComponentBinding, DynPropBinding, DynEventBinding } from './types.js' */
 /**
  * Walk a DOM tree rooted at rootEl, discovering bindings and events.
@@ -871,6 +871,96 @@ export function processForBlocks(parent, parentPath, signalNames, computedNames,
 }
+// ── Dynamic component processing ────────────────────────────────────
+/**
+ * Process dynamic component elements (`<component :is="expr">`) in descendants of a parent element.
+ * Recursively detects `<component>` elements, validates the `:is` attribute,
+ * extracts prop/event bindings, and replaces them with comment anchors.
+ *
+ * @param {Element} parent - Root element to search
+ * @param {string[]} parentPath - DOM path to parent from __root
+ * @returns {DynamicComponentBinding[]}
+ */
+export function processDynamicComponents(parent, parentPath) {
+  /** @type {DynamicComponentBinding[]} */
+  const dynamicComponents = [];
+  let dynIdx = 0;
+  /**
+   * Recursively search for <component> elements in the subtree.
+   * @param {Element} node
+   * @param {string[]} currentPath
+   */
+  function findDynamicComponents(node, currentPath) {
+    const children = Array.from(node.childNodes);
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      if (child.nodeType !== 1) continue;
+      const el = /** @type {Element} */ (child);
+      if (el.tagName === 'COMPONENT') {
+        // Validate :is attribute is present
+        const isExpr = el.getAttribute(':is');
+        if (!isExpr) {
+          const error = new Error(':is attribute is required on <component> elements');
+          /** @ts-expect-error — custom error code */
+          error.code = 'MISSING_IS_ATTRIBUTE';
+          throw error;
+        }
+        // Collect prop bindings (:attr="expr", excluding :is)
+        /** @type {DynPropBinding[]} */
+        const props = [];
+        // Collect event bindings (@event="handler")
+        /** @type {DynEventBinding[]} */
+        const events = [];
+        for (const attr of Array.from(el.attributes)) {
+          if (attr.name.startsWith(':') && attr.name !== ':is') {
+            props.push({
+              attr: attr.name.slice(1),
+              expression: attr.value,
+            });
+          } else if (attr.name.startsWith('@')) {
+            events.push({
+              event: attr.name.slice(1),
+              handler: attr.value,
+            });
+          }
+        }
+        // Replace <component> with a comment node <!-- dynamic -->
+        const doc = node.ownerDocument;
+        const comment = doc.createComment(' dynamic ');
+        node.replaceChild(comment, el);
+        // Calculate anchorPath
+        const updatedChildren = Array.from(node.childNodes);
+        const commentIndex = updatedChildren.indexOf(comment);
+        const anchorPath = [...currentPath, `childNodes[${commentIndex}]`];
+        // Create DynamicComponentBinding
+        dynamicComponents.push({
+          varName: `__dyn${dynIdx++}`,
+          isExpression: isExpr,
+          props,
+          events,
+          anchorPath,
+          _anchorNode: comment,
+        });
+      } else {
+        // Recurse into non-component elements to find nested dynamic components
+        const childPath = [...currentPath, `childNodes[${i}]`];
+        findDynamicComponents(el, childPath);
+      }
+    }
+  }
+  findDynamicComponents(parent, parentPath);
+  return dynamicComponents;
+}
 // ── Ref detection ───────────────────────────────────────────────────
 /**

package/lib/types.js CHANGED Viewed

@@ -100,6 +100,7 @@
  * @property {RefBinding[]} refBindings — ref attribute bindings from template (empty array if none)
  * @property {ChildComponentBinding[]} childComponents — Child component bindings (empty array if none)
  * @property {ChildComponentImport[]} childImports — Resolved child component imports (empty array if none)
+ * @property {DynamicComponentBinding[]} dynamicComponents — Dynamic component bindings (empty array if none)
  * @property {string[]} exposeNames — Property names from defineExpose (empty array if none)
  */
@@ -227,6 +228,27 @@
  * @property {boolean} sideEffect  — true if this is a side-effect import (no identifier)
  */
+/**
+ * @typedef {Object} DynPropBinding
+ * @property {string} attr       — Attribute name (e.g., 'label', 'count')
+ * @property {string} expression — Expression string (e.g., "name()", "props.title")
+ */
+/**
+ * @typedef {Object} DynEventBinding
+ * @property {string} event   — Event name (e.g., 'click', 'change')
+ * @property {string} handler — Handler expression (e.g., "handleClick", "handleClick($event)")
+ */
+/**
+ * @typedef {Object} DynamicComponentBinding
+ * @property {string} varName         — Unique name: '__dyn0', '__dyn1', ...
+ * @property {string} isExpression    — The :is attribute expression (e.g., "currentTag()")
+ * @property {DynPropBinding[]} props — Prop bindings from :attr="expr" attributes
+ * @property {DynEventBinding[]} events — Event bindings from @event="handler" attributes
+ * @property {string[]} anchorPath    — DOM path to comment anchor from __root
+ */
 /**
  * Set of HTML attributes that use property assignment instead of setAttribute.
  * @type {Set<string>}

package/package.json CHANGED Viewed

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