@sprlab/wccompiler 0.10.5 → 0.10.7

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

@@ -4,25 +4,24 @@
  *
  * @module @sprlab/wccompiler/adapters/react
  *
- * IMPORTANT: Import hooks from THIS file (not from integrations/react).
- * The integrations/react file is for vite.config.js only (contains Babel).
+ * NOTE: These hooks are optional utilities for React 18 or edge cases.
+ * With React 19 + wccReactPlugin, WCC components work natively:
  *
- * Usage:
- *   import { useWccEvent, useWccModel, createWccWrapper } from '@sprlab/wccompiler/adapters/react'
+ *   <WccCounter count={state} oncountchanged={(e) => setState(e.detail)} />
+ *   <WccCard>
+ *     <WccCard.Header><strong>Title</strong></WccCard.Header>
+ *   </WccCard>
  *
- *   // Option A: Low-level hooks (full control)
- *   const ref = useWccEvent('change', (e) => console.log(e.detail))
- *   <wcc-counter ref={ref}></wcc-counter>
+ * The plugin handles PascalCase → kebab-case, compound components, and
+ * scoped slots at build time. No runtime wrappers needed.
  *
- *   // Option B: Wrapper components (idiomatic React DX)
- *   const WccCounter = createWccWrapper('wcc-counter', {
- *     events: ['change'],
- *     models: ['count']
- *   })
- *   <WccCounter onChange={handler} count={count} onCountChanged={setCount} />
+ * These hooks are for cases where you need manual event bridging
+ * (e.g., React 18, non-Vite builds, or dynamic event names):
+ *
+ *   import { useWccEvent, useWccModel } from '@sprlab/wccompiler/adapters/react'
  */
 
-import React, { useRef, useEffect } from 'react'
+import { useRef, useEffect } from 'react'
 
 /**
  * Hook that attaches a CustomEvent listener to a DOM element via ref.
@@ -35,6 +34,16 @@ import React, { useRef, useEffect } from 'react'
  * @param {string | ((event: CustomEvent) => void)} eventNameOrHandler
  * @param {((event: CustomEvent) => void)} [handler]
  * @returns {import('react').RefObject<HTMLElement> | void}
+ *
+ * @example
+ * // Form 1: Let the hook create the ref
+ * const ref = useWccEvent('count-changed', (e) => setCount(e.detail))
+ * <wcc-counter ref={ref}></wcc-counter>
+ *
+ * // Form 2: Pass an existing ref
+ * const myRef = useRef(null)
+ * useWccEvent(myRef, 'count-changed', (e) => setCount(e.detail))
+ * <wcc-counter ref={myRef}></wcc-counter>
  */
 export function useWccEvent(refOrEventName, eventNameOrHandler, handler) {
   const isRefForm = typeof refOrEventName !== 'string'
@@ -103,258 +112,3 @@ export function useWccModel(propName, value, setValue, existingRef) {
 
   return elementRef
 }
-
-
-/**
- * Converts a kebab-case event name to a React-idiomatic prop name.
- *
- * Rules:
- * - 'change' → 'onChange'
- * - 'count-changed' → 'onCountChange' (strips trailing 'd' from past tense)
- * - 'value-updated' → 'onValueUpdate' (strips trailing 'd')
- * - 'reset' → 'onReset'
- * - 'item-click' → 'onItemClick'
- *
- * @param {string} eventName - kebab-case event name
- * @returns {string} React prop name (onCamelCase)
- */
-function toReactEventProp(eventName) {
-  const parts = eventName.split('-')
-  const camel = parts.map(s => s[0].toUpperCase() + s.slice(1)).join('')
-  // Strip trailing 'd' from past tense verbs (changed→Change, updated→Update)
-  const normalized = camel.replace(/(Changed|Updated|Removed|Added|Closed|Opened|Submitted|Cancelled)$/, (m) => m.slice(0, -1))
-  return 'on' + normalized
-}
-
-/**
- * Creates a React wrapper component for a WCC custom element.
- *
- * The wrapper provides idiomatic React DX:
- * - Event props: `onChange`, `onCountChange` → automatically wired via addEventListener
- *   Handlers receive the unwrapped value (event.detail), not the raw CustomEvent.
- * - Model props: two-way binding via attribute + event listener
- * - Regular props: passed as attributes on the custom element
- * - Children: passed through as-is (use `<div slot="name">` for named slots)
- * - Ref forwarding: supports React refs via forwardRef
- *
- * @param {string} tagName - The custom element tag name (e.g., 'wcc-card')
- * @param {Object} [config] - Configuration for the wrapper
- * @param {string[]} [config.events] - Custom event names to expose as onEventName props
- *   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
- *
- * @example
- * const WccCounter = createWccWrapper('wcc-counter', {
- *   events: ['change'],
- *   models: ['count']
- * })
- *
- * function App() {
- *   const [count, setCount] = useState(0)
- *   return (
- *     <WccCounter
- *       count={count}
- *       onCountChange={(value) => setCount(value)}
- *       onChange={(value) => console.log('changed', value)}
- *       label="Clicks"
- *     >
- *       <div slot="footer">Footer content</div>
- *     </WccCounter>
- *   )
- * }
- */
-export function createWccWrapper(tagName, config = {}) {
-  const { events = [], models = [] } = config
-
-  // Build a set of event prop names for quick lookup
-  // Convention: kebab-case event → React onCamelCase (without trailing 'd' from 'changed')
-  // 'count-changed' → 'onCountChange' (not 'onCountChanged')
-  // 'change' → 'onChange'
-  // 'value-updated' → 'onValueUpdate' (strips trailing 'd' from past tense)
-  const eventPropMap = new Map()
-  for (const eventName of events) {
-    const propName = toReactEventProp(eventName)
-    eventPropMap.set(propName, eventName)
-  }
-
-  // Model events: 'count' → 'count-changed' → 'onCountChange'
-  const modelEventMap = new Map()
-  for (const modelName of models) {
-    const eventName = `${modelName}-changed`
-    const propName = toReactEventProp(eventName)
-    eventPropMap.set(propName, eventName)
-    modelEventMap.set(modelName, eventName)
-  }
-
-  // Reserved prop names that should not be passed as attributes
-  const SKIP_PROPS = new Set(['children', 'key', 'ref', 'style', 'className', 'dangerouslySetInnerHTML'])
-
-  const WccWrapper = React.forwardRef(function WccWrapper(props, externalRef) {
-    const internalRef = useRef(null)
-    const ref = externalRef || internalRef
-
-    // Store event handlers in a ref to avoid re-subscribing on every render
-    const handlersRef = useRef({})
-
-    // Collect event handlers and regular props
-    const regularProps = {}
-    const eventHandlers = {}
-
-    for (const [key, value] of Object.entries(props)) {
-      if (SKIP_PROPS.has(key)) continue
-
-      if (eventPropMap.has(key)) {
-        eventHandlers[eventPropMap.get(key)] = value
-      } else if (key.startsWith('on') && key.length > 2 && key[2] >= 'A' && key[2] <= 'Z') {
-        // Generic React event handler pattern: onClick, onFocus, etc.
-        // Convert onSomething → 'something' (lowercase first char)
-        const nativeEvent = key[2].toLowerCase() + key.slice(3)
-        eventHandlers[nativeEvent] = value
-      } else {
-        regularProps[key] = value
-      }
-    }
-
-    // Update handlers ref
-    handlersRef.current = eventHandlers
-
-    // Subscribe to custom events
-    useEffect(() => {
-      const el = typeof ref === 'function' ? null : ref?.current
-      if (!el) return
-
-      const listeners = []
-      const allEvents = new Set([...eventPropMap.values(), ...Object.keys(eventHandlers)])
-
-      for (const eventName of allEvents) {
-        const listener = (e) => {
-          const handler = handlersRef.current[eventName]
-          if (handler) handler(e instanceof CustomEvent ? e.detail : e)
-        }
-        el.addEventListener(eventName, listener)
-        listeners.push([eventName, listener])
-      }
-
-      return () => {
-        for (const [name, listener] of listeners) {
-          el.removeEventListener(name, listener)
-        }
-      }
-    }, []) // eslint-disable-line react-hooks/exhaustive-deps
-
-    // Sync regular props as attributes
-    useEffect(() => {
-      const el = typeof ref === 'function' ? null : ref?.current
-      if (!el) return
-
-      for (const [key, value] of Object.entries(regularProps)) {
-        if (value == null || value === false) {
-          el.removeAttribute(key)
-        } else if (value === true) {
-          el.setAttribute(key, '')
-        } else {
-          el.setAttribute(key, String(value))
-        }
-      }
-    })
-
-    // Build the element props for React's createElement
-    const elementProps = { ref }
-    if (props.style) elementProps.style = props.style
-    if (props.className) elementProps.className = props.className
-
-    return React.createElement(tagName, elementProps, props.children)
-  })
-
-  WccWrapper.displayName = tagName.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
-
-  return WccWrapper
-}
-
-
-
-/**
- * Creates a React wrapper from a WCC component class that has `static __meta`.
- *
- * Unlike `createWccWrapper` which requires manual event/model configuration,
- * this function reads the metadata directly from the compiled component class.
- *
- * @param {Function} WccClass - The WCC custom element class (must have static __meta)
- * @returns {import('react').ForwardRefExoticComponent} A React component
- *
- * @example
- * import { wrapWccComponent } from '@sprlab/wccompiler/adapters/react'
- * import '../wcc-components/wcc-counter.js'  // registers the custom element
- *
- * // Read metadata directly from the registered class
- * const WccCounter = wrapWccComponent(customElements.get('wcc-counter'))
- *
- * // Use idiomatically — no manual config needed
- * // Handlers receive the value directly (not the event)
- * <WccCounter count={count} onCountChange={setCount} onChange={(val) => console.log(val)} />
- */
-export function wrapWccComponent(WccClass) {
-  const meta = WccClass?.__meta
-  if (!meta) {
-    throw new Error(`wrapWccComponent: class does not have static __meta. Is it a compiled WCC component?`)
-  }
-
-  return createWccWrapper(meta.tag, {
-    events: meta.events || [],
-    models: meta.models || [],
-  })
-}
-
-/**
- * Creates React wrappers for all registered WCC custom elements matching a prefix.
- *
- * Scans the custom elements registry for components with `static __meta` and
- * generates typed wrapper components for each one.
- *
- * @param {Object} [options]
- * @param {string} [options.prefix='wcc-'] - Tag prefix to filter components
- * @returns {Record<string, import('react').ForwardRefExoticComponent>} Map of PascalCase name → React component
- *
- * @example
- * // In your app entry point, after importing all WCC components:
- * import '../wcc-components/wcc-counter.js'
- * import '../wcc-components/wcc-card.js'
- * import { createWccWrappers } from '@sprlab/wccompiler/adapters/react'
- *
- * export const { WccCounter, WccCard } = createWccWrappers()
- *
- * // Then use anywhere:
- * <WccCounter count={count} onCountChanged={setCount} />
- * <WccCard><div slot="header">Title</div></WccCard>
- */
-export function createWccWrappers(options = {}) {
-  const { prefix = 'wcc-' } = options
-  const wrappers = {}
-
-  // Note: customElements registry doesn't have a list API,
-  // so we need the component files to be imported first (which registers them).
-  // This function is meant to be called after all component imports.
-
-  // We'll use a Proxy that lazily creates wrappers on first access
-  return new Proxy(wrappers, {
-    get(target, prop) {
-      if (typeof prop !== 'string') return undefined
-      if (prop in target) return target[prop]
-
-      // Convert PascalCase to kebab-case: WccCounter → wcc-counter
-      const kebab = prop.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')
-
-      // Check if it starts with the prefix
-      if (!kebab.startsWith(prefix)) return undefined
-
-      const ctor = customElements.get(kebab)
-      if (!ctor || !(ctor).__meta) return undefined
-
-      const wrapper = wrapWccComponent(ctor)
-      target[prop] = wrapper
-      return wrapper
-    }
-  })
-}

package/integrations/react.js

@@ -643,9 +643,102 @@ export function wccReactPlugin(options = {}) {
           const openingElement = path.node.openingElement
           const nameNode = openingElement.name
 
+          // ── Compound component transform ──
+          // <WccCard.Header>children</WccCard.Header> → <div slot="header" style={{display:'contents'}}>children</div>
+          // <WccCard.Stats>{(likes) => <span>{likes}</span>}</WccCard.Stats> → scoped slot div
+          if (nameNode.type === 'JSXMemberExpression') {
+            const objectName = nameNode.object?.name // e.g., 'WccCard'
+            const propName = nameNode.property?.name // e.g., 'Header'
+            if (!objectName || !propName) return
+
+            // Convert PascalCase object to kebab-case and check if it's a custom element
+            const kebab = objectName.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')
+            if (!kebab.includes('-')) return
+            if (prefix && !kebab.startsWith(prefix)) return
+
+            // Derive slot name: Header → header, FooterNav → footerNav (lcfirst)
+            const slotName = propName[0].toLowerCase() + propName.slice(1)
+
+            // Check if children is a function (scoped slot / render prop pattern)
+            const children = path.node.children
+            const isScopedSlot = children.length === 1
+              && children[0].type === 'JSXExpressionContainer'
+              && children[0].expression.type === 'ArrowFunctionExpression'
+
+            if (isScopedSlot) {
+              // Scoped slot: <WccCard.Stats>{(likes) => <span>{likes}</span>}</WccCard.Stats>
+              const arrowFn = children[0].expression
+              const params = (arrowFn.params || []).map(p => p.name || '')
+              const body = arrowFn.body
+
+              // Warn on unsupported expressions
+              const renderWarnings = []
+              serializeJsxToHtml(body, params, renderWarnings)
+              if (renderWarnings.length > 0) {
+                pluginCtx.warn(`[wcc-react] ${id} — ${objectName}.${propName}: ${renderWarnings[0]}`)
+                return
+              }
+
+              // Replace with scoped slot element
+              const scopedEl = generateScopedSlotElement(slotName, params, body)
+              path.replaceWith(scopedEl)
+              transformed = true
+            } else {
+              // Named slot: <WccCard.Header><strong>Title</strong></WccCard.Header>
+              // → <div slot="header" style={{display:'contents'}}>children</div>
+              const slotAttr = {
+                type: 'JSXAttribute',
+                name: { type: 'JSXIdentifier', name: 'slot' },
+                value: { type: 'StringLiteral', value: slotName }
+              }
+              const styleAttr = {
+                type: 'JSXAttribute',
+                name: { type: 'JSXIdentifier', name: 'style' },
+                value: {
+                  type: 'JSXExpressionContainer',
+                  expression: {
+                    type: 'ObjectExpression',
+                    properties: [{
+                      type: 'ObjectProperty',
+                      key: { type: 'Identifier', name: 'display' },
+                      value: { type: 'StringLiteral', value: 'contents' },
+                      computed: false,
+                      shorthand: false
+                    }]
+                  }
+                }
+              }
+
+              openingElement.name = { type: 'JSXIdentifier', name: 'div' }
+              openingElement.attributes = [...openingElement.attributes, slotAttr, styleAttr]
+              if (path.node.closingElement) {
+                path.node.closingElement.name = { type: 'JSXIdentifier', name: 'div' }
+              }
+              transformed = true
+            }
+            return
+          }
+
+          // ── PascalCase custom element transform ──
+          // <WccCard> → <wcc-card> (only if it maps to a hyphenated tag)
+          if (nameNode.type === 'JSXIdentifier' && /^[A-Z]/.test(nameNode.name)) {
+            const kebab = nameNode.name.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')
+            if (!kebab.includes('-')) return
+            if (prefix && !kebab.startsWith(prefix)) return
+
+            // Rewrite tag name to kebab-case
+            openingElement.name = { type: 'JSXIdentifier', name: kebab }
+            if (path.node.closingElement) {
+              path.node.closingElement.name = { type: 'JSXIdentifier', name: kebab }
+            }
+            transformed = true
+            // Fall through to process props on this element
+          }
+
           // Only process elements with hyphenated tag names (custom elements)
-          if (nameNode.type !== 'JSXIdentifier') return
-          const tagName = nameNode.name
+          const currentName = openingElement.name
+          if (currentName.type !== 'JSXIdentifier') return
+          const tagName = currentName.name
           if (!tagName.includes('-')) return
 
           // Apply prefix filtering if set

package/package.json

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