@sprlab/wccompiler 0.10.4 → 0.10.6

package/README.md

@@ -192,6 +192,11 @@ watch(count, (newVal, oldVal) => {
 watch(() => props.count, (newVal, oldVal) => {
   console.log(`Prop changed: ${oldVal} → ${newVal}`)
 })
+
+// Watch a derived expression
+watch(() => count() * 2, (newVal, oldVal) => {
+  console.log(`Doubled changed: ${oldVal} → ${newVal}`)
+})
 ```
 
 `watch` observes a specific signal or getter and provides both old and new values. The callback does not run on initial mount — only on subsequent changes.
@@ -248,6 +253,58 @@ const emit = defineEmits<{ (e: 'change', value: number): void }>()
 
 The compiler validates emit calls against declared events at compile time.
 
+## defineModel (Two-Way Binding)
+
+`defineModel` declares a prop that supports two-way binding across frameworks:
+
+```js
+import { defineModel } from 'wcc'
+
+const count = defineModel({ name: 'count', default: 0 })
+const title = defineModel({ name: 'title', default: 'untitled' })
+```
+
+Read and write like a signal:
+```js
+count()          // read current value
+count.set(5)     // write — updates internal state + emits events
+```
+
+**Events emitted on write:**
+
+| Event | Purpose |
+|-------|---------|
+| `count-changed` | Kebab-case — for Vue plugin, addEventListener |
+| `countChanged` | camelCase — for Angular, direct binding |
+| `countChange` | Angular `[(count)]` banana-box syntax |
+| `wcc:model` | Generic — for vanilla JS and WCC-to-WCC |
+
+**Usage per framework:**
+
+```vue
+<!-- Vue (with plugin) -->
+<wcc-counter v-model:count="ref"></wcc-counter>
+
+<!-- Vue (without plugin) -->
+<wcc-counter :count="ref" @count-changed="ref = $event.detail"></wcc-counter>
+```
+
+```jsx
+// React (with wrapper)
+<WccCounter count={count} onCountChange={(value) => setCount(value)} />
+
+// React (native CE)
+<wcc-counter count={count} oncountchanged={(e) => setCount(e.detail)} />
+```
+
+```html
+<!-- Angular (zero-config two-way) -->
+<wcc-counter [(count)]="signal"></wcc-counter>
+
+<!-- Angular (manual) -->
+<wcc-counter [count]="signal()" (countChange)="signal.set($event.detail)"></wcc-counter>
+```
+
 ## Template Directives
 
 ### Text Interpolation
@@ -638,63 +695,96 @@ Each standalone component has its own isolated reactive runtime. Signals from co
 
 ## Framework Integrations
 
-WCC components are native custom elements — they work in any framework. Optional integration helpers reduce configuration friction:
+WCC components are native custom elements — they work in any framework. Props, events, and named slots work natively with zero WCC-specific config. Two-way binding is zero-config in Angular; Vue and React require a lightweight plugin. Scoped slots require a framework plugin for idiomatic syntax.
 
-### Vue 3 (Vite)
+### Zero-Config (works immediately)
+
+Just import the compiled component and use it:
+
+```html
+<script type="module" src="dist/wcc-counter.js"></script>
+```
+
+**Vue:**
+```vue
+<wcc-counter :count="ref" @count-changed="handler($event.detail)">
+  <div slot="footer">Footer content</div>
+</wcc-counter>
+```
+
+**React 19:**
+```jsx
+<wcc-counter count={state} onCountchanged={(e) => handler(e.detail)}>
+  <div slot="footer">Footer content</div>
+</wcc-counter>
+```
+
+**Angular:**
+```html
+<wcc-counter [count]="signal()" (count-changed)="handler($event.detail)" [(count)]="signal">
+  <div slot="footer">Footer content</div>
+</wcc-counter>
+```
+
+### Vue Plugin (v-model, modifiers, scoped slots)
 
 ```js
 // vite.config.js
 import { wccVuePlugin } from '@sprlab/wccompiler/integrations/vue'
+export default defineConfig({ plugins: [wccVuePlugin()] })
+```
 
-export default defineConfig({
-  plugins: [wccVuePlugin()]
-})
-
-// Custom prefix:
-// plugins: [wccVuePlugin({ prefix: 'my-' })]
+```vue
+<wcc-input v-model="text" v-model:count.number="count"></wcc-input>
+<wcc-card>
+  <template #header><strong>Title</strong></template>
+  <template #stats="{ likes }">{{ likes }} likes</template>
+</wcc-card>
 ```
 
-### React
+The plugin is needed for: v-model:prop (Vue assigns raw Event, not detail), v-model modifiers (.trim, .number), and scoped slot syntax (`{{prop}}` → `{%prop%}` escape).
+
+Without the plugin, use `:prop` + `@prop-changed` for two-way binding manually.
+
+### React Plugin + Wrappers (scoped slots, typed events, two-way)
 
-React 19+ supports custom elements natively. For React 18, use the event hook to bridge CustomEvents:
+```js
+// vite.config.js
+import { wccReactPlugin } from '@sprlab/wccompiler/integrations/react'
+import react from '@vitejs/plugin-react'
+export default defineConfig({ plugins: [wccReactPlugin(), react()] })
+```
 
 ```jsx
-import { useRef } from 'react'
-import { useWccEvent } from '@sprlab/wccompiler/integrations/react'
-
-function App() {
-  // Form 1: Pass an existing ref
-  const counterRef = useRef(null)
-  useWccEvent(counterRef, 'change', (e) => console.log(e.detail))
-  return <wcc-counter ref={counterRef}></wcc-counter>
-}
+// Auto-generated wrappers — events unwrapped, React-idiomatic naming
+import { createWccWrappers } from '@sprlab/wccompiler/adapters/react'
+const { WccCounter, WccCard } = createWccWrappers()
 
-// Form 2: Let the hook create the ref
-function App2() {
-  const ref = useWccEvent('change', (e) => console.log(e.detail))
-  return <wcc-counter ref={ref}></wcc-counter>
-}
+<WccCounter count={count} onCountChange={(value) => setCount(value)} />
+<WccCard renderStats={(likes) => <span>{likes} likes</span>}>
+  <p>Body</p>
+</WccCard>
 ```
 
-### Angular
+Wrappers read component metadata (`static __meta`) automatically — no manual event/model config needed.
+
+### Angular Directive (scoped slots only)
 
-Add `CUSTOM_ELEMENTS_SCHEMA` to your component or module — this is Angular's built-in way to allow custom elements:
+Angular needs no plugin for props, events, or two-way binding. The directive is only needed for scoped slots:
 
 ```ts
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
+import { WccSlotsDirective, WccSlotDef } from '@sprlab/wccompiler/adapters/angular'
 
-// Standalone component (Angular 17+)
 @Component({
+  imports: [WccSlotsDirective, WccSlotDef],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: `<wcc-counter></wcc-counter>`
-})
-export class AppComponent {}
-
-// Or NgModule approach
-@NgModule({
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <wcc-card wccSlots>
+      <ng-template slot="header"><strong>Title</strong></ng-template>
+      <ng-template slot="stats" let-likes>{{ likes }} likes</ng-template>
+    </wcc-card>
+  `
 })
-export class AppModule {}
 ```
 
 ### Vanilla

package/adapters/react.js

@@ -143,12 +143,15 @@ function toReactEventProp(eventName) {
  *   Event names are converted: 'count-changed' → onCountChange prop (React convention)
  * @param {string[]} [config.models] - Model prop names for two-way binding
  *   Each model 'name' creates: `name` prop (sets attribute) + `onNameChange` event
- * @returns {import('react').ForwardRefExoticComponent} A React component
+ * @param {string[]} [config.slots] - Named slot names for compound sub-components
+ *   Each slot 'name' creates a `.Name` sub-component that renders `<div slot="name">`
+ * @returns {import('react').ForwardRefExoticComponent} A React component with compound sub-components
  *
  * @example
  * const WccCounter = createWccWrapper('wcc-counter', {
  *   events: ['change'],
- *   models: ['count']
+ *   models: ['count'],
+ *   slots: ['header', 'footer']
  * })
  *
  * function App() {
@@ -160,13 +163,15 @@ function toReactEventProp(eventName) {
  *       onChange={(value) => console.log('changed', value)}
  *       label="Clicks"
  *     >
- *       <div slot="footer">Footer content</div>
+ *       <WccCounter.Header><strong>Title</strong></WccCounter.Header>
+ *       <p>Body content</p>
+ *       <WccCounter.Footer>Footer text</WccCounter.Footer>
  *     </WccCounter>
  *   )
  * }
  */
 export function createWccWrapper(tagName, config = {}) {
-  const { events = [], models = [] } = config
+  const { events = [], models = [], slots = [] } = config
 
   // Build a set of event prop names for quick lookup
   // Convention: kebab-case event → React onCamelCase (without trailing 'd' from 'changed')
@@ -270,6 +275,24 @@ export function createWccWrapper(tagName, config = {}) {
 
   WccWrapper.displayName = tagName.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
 
+  // Compound components: generate .SlotName sub-components for each named slot
+  // This enables the pattern: <WccLayout.Header>content</WccLayout.Header>
+  // which renders as: <div slot="header">content</div>
+  for (const slotName of slots) {
+    if (!slotName) continue // skip default slot
+    const pascalSlot = slotName[0].toUpperCase() + slotName.slice(1)
+    const SlotComponent = function WccSlot({ children, ...rest }) {
+      const slotProps = { slot: slotName, style: { display: 'contents' } }
+      // Pass through any extra props as attributes on the wrapper div
+      for (const [key, value] of Object.entries(rest)) {
+        slotProps[key] = value
+      }
+      return React.createElement('div', slotProps, children)
+    }
+    SlotComponent.displayName = `${WccWrapper.displayName}.${pascalSlot}`
+    WccWrapper[pascalSlot] = SlotComponent
+  }
+
   return WccWrapper
 }
 
@@ -304,6 +327,7 @@ export function wrapWccComponent(WccClass) {
   return createWccWrapper(meta.tag, {
     events: meta.events || [],
     models: meta.models || [],
+    slots: meta.slots || [],
   })
 }
 
@@ -326,8 +350,12 @@ export function wrapWccComponent(WccClass) {
  * export const { WccCounter, WccCard } = createWccWrappers()
  *
  * // Then use anywhere:
- * <WccCounter count={count} onCountChanged={setCount} />
- * <WccCard><div slot="header">Title</div></WccCard>
+ * <WccCounter count={count} onCountChange={setCount} />
+ * <WccCard>
+ *   <WccCard.Header><strong>Title</strong></WccCard.Header>
+ *   <p>Body</p>
+ *   <WccCard.Footer>Footer</WccCard.Footer>
+ * </WccCard>
  */
 export function createWccWrappers(options = {}) {
   const { prefix = 'wcc-' } = options

package/integrations/vue.js

@@ -65,11 +65,15 @@ export function wccVuePlugin(options = {}) {
 
       let result = code
 
-      // NOTE: As of WCC 0.10.3+, v-model:propName works WITHOUT this plugin
-      // because the compiled component emits 'update:propName' natively (Vue 3.4+ CE support).
-      // This transform is still useful for:
-      //   1. v-model modifiers (.trim, .number) — Vue doesn't apply modifiers to CE v-model natively
-      //   2. Older Vue versions (< 3.4) that don't support v-model on CE via update:propName
+      // NOTE: As of WCC 0.10.3+, basic events work WITHOUT this plugin because
+      // the compiled component emits events in multiple formats (kebab, camelCase, lowercase).
+      // However, v-model:propName STILL REQUIRES this plugin because Vue assigns the raw
+      // Event object to the ref — it doesn't extract .detail automatically.
+      // This transform rewrites v-model:prop to @prop-changed="ref = $event.detail".
+      //
+      // This plugin is needed for:
+      //   1. v-model:propName (Vue can't unwrap CustomEvent.detail natively)
+      //   2. v-model modifiers (.trim, .number)
       //   3. Scoped slot syntax transformation ({{prop}} → {%prop%})
 
       // Transform v-model:propName="expr" on custom elements (tags with hyphens)

package/lib/codegen.js

@@ -1799,11 +1799,14 @@ export function generateComponent(parseResult, options = {}) {
   // _modelSet methods (one per defineModel prop — emits events on internal write)
   // Emits:
   //   1. wcc:model — generic event for vanilla JS and WCC-to-WCC binding
-  //   2. propName-changed — kebab-case for direct addEventListener
+  //   2. propName-changed — kebab-case for direct addEventListener and Vue plugin
   //   3. propNameChanged — camelCase for Angular WccEvents / direct binding
   //   4. propnamechanged — lowercase for React 19 (onPropnameChanged → 'propnamechanged')
   //   5. propNameChange — for Angular [(prop)] banana-box syntax
-  //   6. update:propName — for Vue v-model:propName on custom elements (Vue 3.4+)
+  //
+  // NOTE: Vue v-model:prop requires the wccVuePlugin because Vue assigns the raw
+  // Event object to the ref (not event.detail). The plugin transforms v-model:prop
+  // to @prop-changed="ref = $event.detail" which correctly extracts the value.
   for (const md of modelDefs) {
     const kebabName = camelToKebab(md.name);
     const camelChanged = `${md.name}Changed`;
@@ -1815,16 +1818,14 @@ export function generateComponent(parseResult, options = {}) {
     lines.push(`      bubbles: true,`);
     lines.push(`      composed: true`);
     lines.push(`    }));`);
-    // Kebab-case: prop-name-changed
+    // Kebab-case: prop-name-changed (Vue plugin, addEventListener)
     lines.push(`    this.dispatchEvent(new CustomEvent('${kebabName}-changed', { detail: newVal, bubbles: true }));`);
-    // camelCase: propNameChanged
+    // camelCase: propNameChanged (Angular, addEventListener)
     lines.push(`    this.dispatchEvent(new CustomEvent('${camelChanged}', { detail: newVal, bubbles: true }));`);
     // lowercase: propnamechanged (React 19)
     lines.push(`    this.dispatchEvent(new CustomEvent('${camelChanged.toLowerCase()}', { detail: newVal, bubbles: true }));`);
     // Angular banana-box: propNameChange
     lines.push(`    this.dispatchEvent(new CustomEvent('${md.name}Change', { detail: newVal, bubbles: true }));`);
-    // Vue v-model: update:propName
-    lines.push(`    this.dispatchEvent(new CustomEvent('update:${md.name}', { detail: newVal, bubbles: true }));`);
     lines.push('  }');
     lines.push('');
   }

package/package.json

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