@sprlab/wccompiler 0.10.5 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprlab/wccompiler",
-  "version": "0.10.5",
+  "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": {