@sprlab/wccompiler 0.6.1 → 0.6.4

package/README.md

@@ -55,6 +55,23 @@ npx wcc build
 
 The compiled output is a single `.js` file with zero dependencies — works in any browser that supports custom elements.
 
+## How It Works
+
+```
+  src/wcc-counter.wcc          dist/wcc-counter.js
+  ┌──────────────────┐         ┌──────────────────────────┐
+  │ <script>         │         │ // Reactive runtime       │
+  │   signal, effect │  ───►   │ // (inline or imported)   │
+  │ <template>       │  build  │ class WccCounter extends  │
+  │   {{count()}}    │         │   HTMLElement { ... }     │
+  │ <style>          │         │ customElements.define(...) │
+  └──────────────────┘         └──────────────────────────┘
+                                         +
+                               dist/__wcc-signals.js (shared mode)
+```
+
+The compiler reads your `.wcc` source, extracts script/template/style blocks, analyzes reactive declarations, walks the template DOM for bindings and directives, and generates a self-contained custom element class. CSS is automatically scoped by tag name.
+
 ## Single File Component (.wcc)
 
 wcCompiler uses a single-file component format with the `.wcc` extension. Each file contains three blocks:
@@ -85,6 +102,31 @@ p { color: steelblue; }
 
 Use `<script lang="ts">` for TypeScript support. The CLI discovers and compiles all `.wcc` files in your source directory.
 
+## Coming from Vue?
+
+If you're familiar with Vue, here's how wcCompiler maps:
+
+| Vue | wcCompiler |
+|-----|------------|
+| `ref(0)` | `signal(0)` |
+| `computed(() => ...)` | `computed(() => ...)` |
+| `watch(source, cb)` | `watch(source, cb)` |
+| `v-if` | `if` |
+| `v-else-if` | `else-if` |
+| `v-else` | `else` |
+| `v-for="item in items"` | `each="item in items()"` |
+| `v-show` | `show` |
+| `v-model` | `model` |
+| `@click` | `@click` |
+| `:prop` | `:prop` |
+| `defineProps()` | `defineProps()` |
+| `defineEmits()` | `defineEmits()` |
+| `onMounted()` | `onMount()` |
+| `onUnmounted()` | `onDestroy()` |
+| `<slot>` | `<slot>` |
+
+Key differences: signals use `.set()` to write and `()` to read. Template directives have no `v-` prefix. Output is vanilla JS with no runtime framework.
+
 ## Reactivity
 
 ### Signals
@@ -95,6 +137,8 @@ count()                        // read → 0
 count.set(5)                   // write → 5
 ```
 
+> **Note:** `.set()` is the public API for writing signals. The compiled output uses direct invocation (`count(5)`) as an internal optimization — both forms are equivalent, but `.set()` is the recommended way to write signals in your source code.
+
 ### Computed
 
 ```js
@@ -119,6 +163,23 @@ effect(() => {
 })
 ```
 
+### Batch
+
+Group multiple signal writes into a single update pass:
+
+```js
+import { batch } from 'wcc'
+
+batch(() => {
+  firstName.set('John')
+  lastName.set('Doe')
+  age.set(30)
+})
+// Effects run once after all three writes, not three times
+```
+
+Nested batches are supported — effects flush only when the outermost batch completes.
+
 ### Watch
 
 ```js
@@ -235,7 +296,32 @@ Event handlers support expressions and inline arguments:
 <li each="(item, index) in items()">{{index}}: {{item.name}}</li>
 ```
 
-The source expression calls the signal (`items()`) to read the current array.
+The source expression calls the signal (`items()`) to read the current array. Supports keyed rendering with `:key`:
+
+```html
+<li each="item in items()" :key="item.id">{{item.name}}</li>
+```
+
+Numeric ranges are also supported:
+
+```html
+<li each="n in 5">Item {{n}}</li>
+```
+
+#### Nested Directives in `each`
+
+Directives work inside `each` blocks — including conditionals and nested loops:
+
+```html
+<div each="user in users()">
+  <span>{{user.name}}</span>
+  <span if="user.active" class="badge">Active</span>
+  <span else class="badge muted">Inactive</span>
+  <ul>
+    <li each="role in user.roles">{{role}}</li>
+  </ul>
+</div>
+```
 
 ### Visibility Toggle
 
@@ -313,6 +399,36 @@ Consumer (receives data via template props):
 </wcc-card>
 ```
 
+## Nested Components
+
+Components can use other components in their templates. Import the child `.wcc` file and use its tag in the template:
+
+```html
+<script>
+import { defineComponent, signal } from 'wcc'
+import './wcc-badge.wcc'
+
+export default defineComponent({ tag: 'wcc-profile' })
+
+const count = signal(0)
+
+function increment() {
+  count.set(count() + 1)
+}
+</script>
+
+<template>
+<div class="profile">
+  <wcc-badge :count="count()" @click="increment"></wcc-badge>
+</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
+- **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
+
 ## Lifecycle Hooks
 
 ```js
@@ -332,6 +448,11 @@ onDestroy(() => {
 
 Async callbacks are wrapped in an IIFE — `connectedCallback` itself stays synchronous.
 
+**Details:**
+- Multiple `onMount` / `onDestroy` calls are supported — they all run in declaration order
+- `connectedCallback` is idempotent — re-mounting a component (e.g., moving it in the DOM) re-attaches listeners and effects cleanly
+- All effects and event listeners are automatically cleaned up in `disconnectedCallback` via AbortController
+
 ## CSS Scoping
 
 Styles are automatically scoped to the component using tag-name prefixing:
@@ -391,13 +512,45 @@ defineExpose({ doubled, handleUpdate, watchLog })
 
 `defineExpose()` exposes methods and properties for external access via ref.
 
+```js
+// wcc-timer.wcc — exposes start/stop/elapsed
+const elapsed = signal(0)
+let interval = null
+
+function start() { interval = setInterval(() => elapsed.set(elapsed() + 1), 1000) }
+function stop() { clearInterval(interval) }
+
+defineExpose({ elapsed, start, stop })
+```
+
+```html
+<!-- Parent component accessing exposed API -->
+<script>
+import { defineComponent, templateRef, onMount } from 'wcc'
+import './wcc-timer.wcc'
+
+export default defineComponent({ tag: 'wcc-app' })
+
+const timer = templateRef('timer')
+
+onMount(() => {
+  timer.value.start()       // call exposed method
+  console.log(timer.value.elapsed)  // read exposed signal
+})
+</script>
+
+<template>
+<wcc-timer ref="timer"></wcc-timer>
+</template>
+```
+
 The language server automatically generates a typed interface (PascalCase of the tag name) that can be imported by consumers:
 
 ```ts
 // In the parent component:
-import type { WccTypescript } from './wcc-typescript.wcc'
-const child = templateRef<WccTypescript>('myRef')
-child.value!.handleUpdate() // ✅ typed
+import type { WccTimer } from './wcc-timer.wcc'
+const timer = templateRef<WccTimer>('timer')
+timer.value!.start() // ✅ typed
 ```
 
 ## CLI
@@ -415,14 +568,22 @@ Create `wcc.config.js` in your project root:
 
 ```js
 export default {
-  port: 4100,    // dev server port
-  input: 'src',  // source directory
-  output: 'dist' // output directory
+  port: 4100,       // dev server port (default: 4100)
+  input: 'src',     // source directory (default: 'src')
+  output: 'dist',   // output directory (default: 'dist')
+  standalone: false  // inline runtime per component (default: false)
 }
 ```
 
 All options are optional — defaults shown above.
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | number | `4100` | Dev server port for `wcc dev` |
+| `input` | string | `'src'` | Source directory containing `.wcc` files |
+| `output` | string | `'dist'` | Output directory for compiled `.js` files |
+| `standalone` | boolean | `false` | Inline reactive runtime in each component |
+
 ### Standalone Mode
 
 Controls whether the reactive runtime is inlined in each component or imported from a shared module.
@@ -437,6 +598,23 @@ export default {
 - `standalone: false` (default) — Components import the runtime from a shared `__wcc-signals.js` file. Smaller per-component size when using multiple components.
 - `standalone: true` — Each component includes the full reactive runtime inline. Zero external dependencies per component.
 
+**Output difference:**
+
+```
+Default (false):   component.js → imports __wcc-signals.js
+Standalone (true): component.js → runtime inlined, zero imports
+```
+
+**When to use standalone:**
+- Publishing components as npm packages
+- Embedding widgets in third-party sites
+- CDN distribution (`<script src="component.js">`)
+- Micro-frontends where you don't control the host
+
+**When NOT to use standalone:**
+- Apps with multiple components (runtime would be duplicated in each)
+- Internal projects where you control the build
+
 #### Per-Component Override
 
 Override the global setting for individual components:
@@ -454,6 +632,10 @@ export default defineComponent({
 
 Component-level `standalone` always takes precedence over the global config. This lets you have a project with shared runtime but mark specific components as fully self-contained for distribution.
 
+#### Reactive Scope Isolation
+
+Each standalone component has its own isolated reactive runtime. Signals from component A cannot be observed by effects in component B — they are completely independent. This is by design for distribution scenarios where components must be self-contained. If you need cross-component reactivity (e.g., shared state), use the default shared mode (`standalone: false`).
+
 ## Editor Support
 
 The **wcCompiler (.wcc) Language Support** extension is available on the VS Code Marketplace. It provides syntax highlighting, completions, and diagnostics for `.wcc` files.

package/lib/codegen.js

@@ -904,10 +904,51 @@ export function generateComponent(parseResult, options = {}) {
     lines.push('');
   }
 
-  // Constructor
+  // Constructor — reactive state only (no DOM manipulation per Custom Elements spec)
   lines.push('  constructor() {');
   lines.push('    super();');
 
+  // Prop signal initialization (BEFORE user signals)
+  for (const p of propDefs) {
+    lines.push(`    this._s_${p.name} = __signal(${p.default});`);
+  }
+
+  // Signal initialization
+  for (const s of signals) {
+    lines.push(`    this._${s.name} = __signal(${s.value});`);
+  }
+
+  // Constant initialization
+  for (const c of constantVars) {
+    lines.push(`    this._const_${c.name} = ${c.value};`);
+  }
+
+  // Computed initialization
+  for (const c of computeds) {
+    const body = transformExpr(c.body, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, constantNames, methodNames);
+    lines.push(`    this._c_${c.name} = __computed(() => ${body});`);
+  }
+
+  // Watcher prev-value initialization
+  for (let idx = 0; idx < watchers.length; idx++) {
+    const w = watchers[idx];
+    if (w.kind === 'signal') {
+      lines.push(`    this.__prev_${w.target} = undefined;`);
+    } else {
+      lines.push(`    this.__prev_watch${idx} = undefined;`);
+    }
+  }
+
+  lines.push('  }');
+  lines.push('');
+
+  // connectedCallback (idempotent — safe for re-mount)
+  lines.push('  connectedCallback() {');
+  lines.push('    if (this.__connected) return;');
+  lines.push('    this.__connected = true;');
+
+  // ── DOM SETUP (moved from constructor for Custom Elements spec compliance) ──
+
   // Slot resolution: read childNodes BEFORE clearing innerHTML (when slots are present)
   if (slots.length > 0) {
     lines.push('    const __slotMap = {};');
@@ -973,37 +1014,6 @@ export function generateComponent(parseResult, options = {}) {
     }
   }
 
-  // Prop signal initialization (BEFORE user signals)
-  for (const p of propDefs) {
-    lines.push(`    this._s_${p.name} = __signal(${p.default});`);
-  }
-
-  // Signal initialization
-  for (const s of signals) {
-    lines.push(`    this._${s.name} = __signal(${s.value});`);
-  }
-
-  // Constant initialization
-  for (const c of constantVars) {
-    lines.push(`    this._const_${c.name} = ${c.value};`);
-  }
-
-  // Computed initialization
-  for (const c of computeds) {
-    const body = transformExpr(c.body, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, constantNames, methodNames);
-    lines.push(`    this._c_${c.name} = __computed(() => ${body});`);
-  }
-
-  // Watcher prev-value initialization
-  for (let idx = 0; idx < watchers.length; idx++) {
-    const w = watchers[idx];
-    if (w.kind === 'signal') {
-      lines.push(`    this.__prev_${w.target} = undefined;`);
-    } else {
-      lines.push(`    this.__prev_watch${idx} = undefined;`);
-    }
-  }
-
   // ── if: template creation, anchor reference, state init ──
   for (const ifBlock of ifBlocks) {
     const vn = ifBlock.varName;
@@ -1055,13 +1065,7 @@ export function generateComponent(parseResult, options = {}) {
     }
   }
 
-  lines.push('  }');
-  lines.push('');
-
-  // connectedCallback (idempotent — safe for re-mount)
-  lines.push('  connectedCallback() {');
-  lines.push('    if (this.__connected) return;');
-  lines.push('    this.__connected = true;');
+  // ── EFFECTS AND LISTENERS ──
   lines.push('    this.__ac = new AbortController();');
   lines.push('    this.__disposers = [];');
   lines.push('');

package/package.json

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