@sprlab/wccompiler 0.9.1 → 0.9.3

package/adapters/angular.js

@@ -1,5 +1,73 @@
 /**
- * Angular adapter for WCC defineModel (OPTIONAL).
+ * Angular adapter for WCC (defineModel + Scoped Slots).
+ *
+ * This module provides Angular integration for WCC components:
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * SCOPED SLOTS (Native Angular Syntax)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * For native Angular scoped slot support, use the TypeScript directives:
+ *
+ *   import { WccSlotsDirective, WccSlotDef } from '@sprlab/wccompiler/adapters/angular';
+ *
+ * Setup:
+ *   @Component({
+ *     imports: [WccSlotsDirective, WccSlotDef],
+ *     schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ *     template: `...`
+ *   })
+ *
+ * The directives auto-activate on custom elements (tags with hyphen).
+ * No [wccSlots] attribute is needed on the host element.
+ *
+ * Slot declaration uses ng-template[slot] syntax:
+ *
+ *   <!-- Named slot (static content, no let-*) -->
+ *   <wcc-card>
+ *     <ng-template slot="header"><strong>My Header</strong></ng-template>
+ *   </wcc-card>
+ *
+ *   <!-- Scoped slot (reactive data via let-*) -->
+ *   <wcc-card>
+ *     <ng-template slot="stats" let-likes>{{ likes }} likes</ng-template>
+ *   </wcc-card>
+ *
+ *   <!-- Multiple props in scoped slot -->
+ *   <wcc-card>
+ *     <ng-template slot="details" let-data let-likes="likes" let-total="total">
+ *       {{ likes }}/{{ total }}
+ *     </ng-template>
+ *   </wcc-card>
+ *
+ * How it works:
+ *   - WccSlotDef captures the TemplateRef and slot name from the 'slot' attribute
+ *   - WccSlotsDirective classifies slots as named or scoped using __scopedSlots
+ *   - Named slots render immediately into <div slot="name" style="display:contents">
+ *   - Scoped slots register a renderer via element.registerSlotRenderer()
+ *   - When slot props change, the renderer updates the Angular EmbeddedView
+ *   - Compatible with OnPush change detection strategy
+ *
+ * The directive source is in adapters/angular.ts (TypeScript with Angular decorators).
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * BACKWARD COMPATIBILITY: slot-template-* (Token Replacement)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * The legacy slot-template-* attribute approach continues to work without
+ * importing the directives:
+ *
+ *   <wcc-list>
+ *     <div slot-template-item="<li>{%item%}</li>"></div>
+ *   </wcc-list>
+ *
+ * When WccSlotsDirective IS imported, ng-template[slot] takes priority over
+ * slot-template-* for the same slot name. Slots not covered by ng-template
+ * continue using the token replacement path.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * defineModel (Two-Way Binding)
+ * ═══════════════════════════════════════════════════════════════════════════════
  *
  * The WCC component already emits `propNameChange` directly from _modelSet,
  * so Angular's [(prop)] banana-box syntax works WITHOUT this adapter.
@@ -9,7 +77,7 @@
  * 2. The ControlValueAccessor guide for ngModel support
  *
  * Setup (Angular):
- *   // No adapter import needed! Just use CUSTOM_ELEMENTS_SCHEMA:
+ *   // No adapter import needed for [(prop)]! Just use CUSTOM_ELEMENTS_SCHEMA:
  *   import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
  *   @Component({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
  *

package/adapters/angular.ts

@@ -0,0 +1,310 @@
+/**
+ * Angular adapter for WCC Scoped Slots.
+ *
+ * Exports:
+ *   - WccSlotDef: Auxiliary directive for ng-template[slot]
+ *   - WccSlotsDirective: Main directive that auto-activates on custom elements
+ *   - SlotContext: Interface for template context typing
+ *
+ * Usage:
+ *   import { WccSlotsDirective, WccSlotDef } from '@sprlab/wccompiler/adapters/angular';
+ *
+ *   @Component({
+ *     imports: [WccSlotsDirective, WccSlotDef],
+ *     schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ *     template: `
+ *       <wcc-card>
+ *         <ng-template slot="header"><strong>Header</strong></ng-template>
+ *         <ng-template slot="stats" let-likes>{{ likes }} likes</ng-template>
+ *       </wcc-card>
+ *     `
+ *   })
+ *
+ * @module @sprlab/wccompiler/adapters/angular
+ */
+
+import {
+  Directive,
+  TemplateRef,
+  ElementRef,
+  ViewContainerRef,
+  ChangeDetectorRef,
+  ContentChildren,
+  QueryList,
+  EmbeddedViewRef,
+  AfterContentInit,
+  OnDestroy,
+  inject,
+  Attribute,
+} from '@angular/core';
+
+// ─── Interfaces ─────────────────────────────────────────────────────────────
+
+/** Context object passed to createEmbeddedView for scoped slots */
+export interface SlotContext {
+  $implicit: any;
+  [key: string]: any;
+}
+
+type SlotType = 'named' | 'scoped';
+
+interface SlotState {
+  type: SlotType;
+  slotDef: WccSlotDef;
+  viewRef: EmbeddedViewRef<SlotContext> | null;
+  cleanup: (() => void) | null;
+  wrapperEl: HTMLElement | null;
+  context: SlotContext | null;
+}
+
+// ─── WccSlotDef — Auxiliary Directive ───────────────────────────────────────
+
+/**
+ * Auxiliary directive that marks an ng-template as slot content.
+ * Captures the TemplateRef and the slot name from the HTML 'slot' attribute.
+ *
+ * Usage:
+ *   <ng-template slot="header">...</ng-template>
+ *   <ng-template slot="stats" let-likes>{{likes}}</ng-template>
+ */
+@Directive({
+  selector: 'ng-template[slot]',
+  standalone: true,
+})
+export class WccSlotDef {
+  public readonly templateRef = inject<TemplateRef<any>>(TemplateRef);
+  public readonly slotName: string;
+
+  constructor(@Attribute('slot') name: string | null) {
+    this.slotName = name || '';
+  }
+}
+
+// ─── WccSlotsDirective — Main Directive ─────────────────────────────────────
+
+/**
+ * Exclusion selector: lists all standard HTML elements.
+ * Custom elements (which MUST contain a hyphen) are not excluded.
+ */
+const STANDARD_ELEMENTS = 'div,span,p,a,button,input,form,section,article,header,footer,nav,main,ul,ol,li,table,tr,td,th,thead,tbody,tfoot,img,h1,h2,h3,h4,h5,h6,label,select,textarea,option,fieldset,legend,details,summary,dialog,slot,template,canvas,video,audio,source,iframe,pre,code,blockquote,hr,br,strong,em,small,sub,sup,mark,del,ins,figure,figcaption,picture,svg,math,body,html,head,script,style,link,meta,title,base,col,colgroup,caption,abbr,address,area,aside,b,bdi,bdo,cite,data,dd,dfn,dl,dt,i,kbd,map,meter,noscript,output,progress,q,rp,rt,ruby,s,samp,time,u,var,wbr';
+
+/** Build the exclusion selector string */
+const EXCLUSION_SELECTOR = STANDARD_ELEMENTS.split(',').map(t => `:not(${t})`).join('');
+
+/**
+ * Main directive that auto-activates on custom elements (tags with hyphen).
+ * Classifies ng-template[slot] children as named or scoped slots and manages
+ * their lifecycle.
+ */
+@Directive({
+  selector: EXCLUSION_SELECTOR,
+  standalone: true,
+})
+export class WccSlotsDirective implements AfterContentInit, OnDestroy {
+  @ContentChildren(WccSlotDef) slotDefs!: QueryList<WccSlotDef>;
+
+  private el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private vcr = inject(ViewContainerRef);
+  private cdr = inject(ChangeDetectorRef);
+
+  private slots = new Map<string, SlotState>();
+  private eventCleanups: (() => void)[] = [];
+  private destroyed = false;
+
+  ngAfterContentInit(): void {
+    // Runtime guard: only proceed for custom elements (tag name contains hyphen)
+    if (!this.el.nativeElement.tagName.toLowerCase().includes('-')) return;
+
+    this.classifyAndInitSlots();
+  }
+
+  ngOnDestroy(): void {
+    this.destroyed = true;
+    this.cleanup();
+  }
+
+  // ─── Classification ─────────────────────────────────────────────────────
+
+  /** Classifies slots using __scopedSlots from the host element and initializes them */
+  private classifyAndInitSlots(): void {
+    const element = this.el.nativeElement as any;
+    const scopedNames: string[] = element.__scopedSlots || [];
+
+    for (const slotDef of this.slotDefs) {
+      // Ignore templates with empty slot name
+      if (!slotDef.slotName) continue;
+
+      if (scopedNames.includes(slotDef.slotName)) {
+        this.initScopedSlot(slotDef);
+      } else {
+        this.initNamedSlot(slotDef);
+      }
+    }
+  }
+
+  // ─── Named Slot ─────────────────────────────────────────────────────────
+
+  /** Named Slot: immediate static rendering */
+  private initNamedSlot(slotDef: WccSlotDef): void {
+    const hostEl = this.el.nativeElement;
+    const wrapper = document.createElement('div');
+    wrapper.setAttribute('slot', slotDef.slotName);
+    wrapper.style.display = 'contents';
+
+    const viewRef = this.vcr.createEmbeddedView(slotDef.templateRef);
+    for (const node of viewRef.rootNodes) {
+      wrapper.appendChild(node);
+    }
+    hostEl.appendChild(wrapper);
+
+    this.slots.set(slotDef.slotName, {
+      type: 'named',
+      slotDef,
+      viewRef,
+      cleanup: null,
+      wrapperEl: wrapper,
+      context: null,
+    });
+  }
+
+  // ─── Scoped Slot ────────────────────────────────────────────────────────
+
+  /** Scoped Slot: async registration + reactive rendering */
+  private async initScopedSlot(slotDef: WccSlotDef): Promise<void> {
+    const hostEl = this.el.nativeElement;
+    const tagName = hostEl.tagName.toLowerCase();
+
+    // Wait for the custom element to be defined
+    await customElements.whenDefined(tagName);
+    if (this.destroyed) return;
+
+    const state: SlotState = {
+      type: 'scoped',
+      slotDef,
+      viewRef: null,
+      cleanup: null,
+      wrapperEl: null,
+      context: null,
+    };
+    this.slots.set(slotDef.slotName, state);
+
+    // Register renderer
+    const element = hostEl as any;
+    if (typeof element.registerSlotRenderer === 'function') {
+      state.cleanup = element.registerSlotRenderer(
+        slotDef.slotName,
+        (props: Record<string, any>) => this.renderSlot(slotDef.slotName, props)
+      );
+    } else {
+      // Fallback: listen for wcc:slot-update event
+      const handler = (e: CustomEvent) => {
+        if (e.detail?.slot === slotDef.slotName) {
+          this.renderSlot(slotDef.slotName, e.detail.props);
+        }
+      };
+      hostEl.addEventListener('wcc:slot-update', handler as EventListener);
+      this.eventCleanups.push(() =>
+        hostEl.removeEventListener('wcc:slot-update', handler as EventListener)
+      );
+    }
+  }
+
+  // ─── Context Construction ───────────────────────────────────────────────
+
+  /**
+   * Builds the Angular context for createEmbeddedView.
+   *
+   * Rules:
+   * - 0 props: $implicit = undefined
+   * - 1 prop: $implicit = that single value, plus the named prop key
+   * - N props (N > 1): $implicit = full props object, plus all named props
+   */
+  buildContext(props: Record<string, any>): SlotContext {
+    const keys = Object.keys(props);
+    if (keys.length === 0) {
+      return { $implicit: undefined };
+    }
+    if (keys.length === 1) {
+      return { $implicit: props[keys[0]], ...props };
+    }
+    return { $implicit: props, ...props };
+  }
+
+  // ─── Render Slot ────────────────────────────────────────────────────────
+
+  /** Creates or updates the EmbeddedView of a scoped slot */
+  private renderSlot(slotName: string, props: Record<string, any> | null): void {
+    const state = this.slots.get(slotName);
+    if (!state || this.destroyed) return;
+
+    // Props null/undefined: clear the view
+    if (props == null) {
+      if (state.viewRef) {
+        state.viewRef.destroy();
+        state.viewRef = null;
+      }
+      return;
+    }
+
+    const context = this.buildContext(props);
+    state.context = context;
+
+    if (state.viewRef) {
+      // Update existing context
+      Object.assign(state.viewRef.context, context);
+      state.viewRef.markForCheck();
+    } else {
+      // Create new view
+      state.viewRef = this.vcr.createEmbeddedView(state.slotDef.templateRef, context);
+      this.insertView(slotName, state);
+    }
+
+    this.cdr.markForCheck();
+  }
+
+  // ─── DOM Insertion ──────────────────────────────────────────────────────
+
+  /** Inserts view root nodes into the custom element's DOM via a wrapper div */
+  private insertView(slotName: string, state: SlotState): void {
+    if (!state.viewRef) return;
+    const hostEl = this.el.nativeElement;
+
+    if (!state.wrapperEl) {
+      state.wrapperEl = document.createElement('div');
+      state.wrapperEl.setAttribute('slot', slotName);
+      state.wrapperEl.style.display = 'contents';
+      hostEl.appendChild(state.wrapperEl);
+    }
+
+    // Clear previous wrapper content and append new nodes
+    state.wrapperEl.innerHTML = '';
+    for (const node of state.viewRef.rootNodes) {
+      state.wrapperEl.appendChild(node);
+    }
+  }
+
+  // ─── Cleanup ────────────────────────────────────────────────────────────
+
+  /** Full cleanup on destroy */
+  private cleanup(): void {
+    // Destroy views, invoke cleanup functions, remove wrappers
+    for (const [, state] of this.slots) {
+      if (state.viewRef) {
+        state.viewRef.destroy();
+      }
+      if (state.cleanup) {
+        state.cleanup();
+      }
+      if (state.wrapperEl && state.wrapperEl.parentNode) {
+        state.wrapperEl.parentNode.removeChild(state.wrapperEl);
+      }
+    }
+    this.slots.clear();
+
+    // Remove event listeners
+    for (const fn of this.eventCleanups) {
+      fn();
+    }
+    this.eventCleanups = [];
+  }
+}

package/integrations/react.js

@@ -21,6 +21,11 @@
  */
 
 import { useRef, useEffect, useCallback } from 'react'
+import { parse } from '@babel/parser'
+import _traverse from '@babel/traverse'
+import _generate from '@babel/generator'
+const traverse = _traverse.default || _traverse
+const generate = _generate.default || _generate
 
 /**
  * Hook that attaches a CustomEvent listener to a DOM element via ref.
@@ -114,3 +119,725 @@ export function useWccModel(propName, value, setValue, existingRef) {
 
   return elementRef
 }
+
+
+/**
+ * JSX attribute name to HTML attribute name mapping.
+ * React uses camelCase for some attributes that HTML uses lowercase.
+ * @type {Record<string, string>}
+ */
+const JSX_TO_HTML_ATTRS = {
+  className: 'class',
+  htmlFor: 'for',
+  tabIndex: 'tabindex',
+  readOnly: 'readonly',
+  maxLength: 'maxlength',
+  autoFocus: 'autofocus',
+  autoComplete: 'autocomplete'
+}
+
+/**
+ * HTML void elements that should not have a closing tag.
+ * @type {Set<string>}
+ */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+])
+
+/**
+ * Serializes a Babel JSX AST node into an HTML string.
+ *
+ * Converts JSX attribute names to HTML equivalents, handles void elements,
+ * recursively serializes nested elements, and replaces parameter references
+ * with {%paramName%} tokens for scoped slot templates.
+ *
+ * @param {object} node - A Babel AST node (JSXElement, JSXFragment, JSXText, JSXExpressionContainer, etc.)
+ * @param {string[]} [paramNames] - Parameter names to replace with {%param%} tokens (for scoped slots)
+ * @param {Array<string>} [warnings] - Array to collect warning messages about unsupported expressions
+ * @returns {string} The serialized HTML string
+ */
+export function serializeJsxToHtml(node, paramNames, warnings) {
+  if (!node) return ''
+
+  switch (node.type) {
+    case 'JSXElement':
+      return serializeJsxElement(node, paramNames, warnings)
+
+    case 'JSXFragment':
+      return serializeJsxChildren(node.children, paramNames, warnings)
+
+    case 'JSXText':
+      return serializeJsxText(node)
+
+    case 'JSXExpressionContainer':
+      return serializeJsxExpression(node.expression, paramNames, warnings)
+
+    case 'StringLiteral':
+      return node.value
+
+    default:
+      return ''
+  }
+}
+
+/**
+ * Serializes a JSXElement node to HTML.
+ * @param {object} node - JSXElement Babel AST node
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string}
+ */
+function serializeJsxElement(node, paramNames, warnings) {
+  const opening = node.openingElement
+  const tagName = getJsxElementName(opening.name)
+  const attrs = serializeAttributes(opening.attributes, paramNames, warnings)
+  const isVoid = VOID_ELEMENTS.has(tagName)
+
+  if (isVoid) {
+    return `<${tagName}${attrs}>`
+  }
+
+  const children = serializeJsxChildren(node.children, paramNames, warnings)
+  return `<${tagName}${attrs}>${children}</${tagName}>`
+}
+
+/**
+ * Gets the tag name string from a JSX element name node.
+ * @param {object} nameNode - JSXIdentifier or JSXMemberExpression
+ * @returns {string}
+ */
+function getJsxElementName(nameNode) {
+  if (nameNode.type === 'JSXIdentifier') {
+    return nameNode.name
+  }
+  if (nameNode.type === 'JSXMemberExpression') {
+    return `${getJsxElementName(nameNode.object)}.${nameNode.property.name}`
+  }
+  if (nameNode.type === 'JSXNamespacedName') {
+    return `${nameNode.namespace.name}:${nameNode.name.name}`
+  }
+  return ''
+}
+
+/**
+ * Serializes JSX attributes to an HTML attribute string.
+ * @param {Array<object>} attributes - Array of JSXAttribute or JSXSpreadAttribute nodes
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string} Attribute string with leading space, or empty string
+ */
+function serializeAttributes(attributes, paramNames, warnings) {
+  if (!attributes || attributes.length === 0) return ''
+
+  const parts = []
+  for (const attr of attributes) {
+    if (attr.type === 'JSXSpreadAttribute') {
+      // Spread attributes can't be statically serialized
+      if (warnings) {
+        warnings.push(`Spread attribute cannot be statically serialized`)
+      }
+      continue
+    }
+
+    if (attr.type === 'JSXAttribute') {
+      const rawName = attr.name.type === 'JSXNamespacedName'
+        ? `${attr.name.namespace.name}:${attr.name.name.name}`
+        : attr.name.name
+      const htmlName = JSX_TO_HTML_ATTRS[rawName] || rawName
+
+      if (attr.value === null || attr.value === undefined) {
+        // Boolean attribute (e.g., `disabled`)
+        parts.push(htmlName)
+      } else if (attr.value.type === 'StringLiteral') {
+        parts.push(`${htmlName}="${attr.value.value}"`)
+      } else if (attr.value.type === 'JSXExpressionContainer') {
+        const exprValue = serializeAttributeExpression(attr.value.expression, paramNames, warnings)
+        if (exprValue !== null) {
+          parts.push(`${htmlName}="${exprValue}"`)
+        }
+      }
+    }
+  }
+
+  return parts.length > 0 ? ' ' + parts.join(' ') : ''
+}
+
+/**
+ * Serializes an expression used as an attribute value.
+ * @param {object} expression - Babel AST expression node
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string|null} The serialized value, or null if it can't be serialized
+ */
+function serializeAttributeExpression(expression, paramNames, warnings) {
+  if (!expression) return null
+
+  if (expression.type === 'StringLiteral') {
+    return expression.value
+  }
+
+  if (expression.type === 'NumericLiteral') {
+    return String(expression.value)
+  }
+
+  if (expression.type === 'BooleanLiteral') {
+    return String(expression.value)
+  }
+
+  if (expression.type === 'Identifier') {
+    if (paramNames && paramNames.includes(expression.name)) {
+      return `{%${expression.name}%}`
+    }
+    // Dynamic expression that can't be statically serialized
+    if (warnings) {
+      warnings.push(`Dynamic expression "{${expression.name}}" cannot be statically serialized`)
+    }
+    return null
+  }
+
+  if (expression.type === 'TemplateLiteral') {
+    return serializeTemplateLiteral(expression, paramNames, warnings)
+  }
+
+  // Other expressions can't be statically serialized
+  if (warnings) {
+    warnings.push(`Expression of type "${expression.type}" cannot be statically serialized`)
+  }
+  return null
+}
+
+/**
+ * Serializes a template literal expression.
+ * @param {object} node - TemplateLiteral AST node
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string|null}
+ */
+function serializeTemplateLiteral(node, paramNames, warnings) {
+  let result = ''
+  for (let i = 0; i < node.quasis.length; i++) {
+    result += node.quasis[i].value.raw
+    if (i < node.expressions.length) {
+      const expr = node.expressions[i]
+      if (expr.type === 'Identifier' && paramNames && paramNames.includes(expr.name)) {
+        result += `{%${expr.name}%}`
+      } else if (expr.type === 'StringLiteral') {
+        result += expr.value
+      } else if (expr.type === 'NumericLiteral') {
+        result += String(expr.value)
+      } else {
+        if (warnings) {
+          warnings.push(`Dynamic expression in template literal cannot be statically serialized`)
+        }
+        return null
+      }
+    }
+  }
+  return result
+}
+
+/**
+ * Serializes an array of JSX children nodes.
+ * @param {Array<object>} children
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string}
+ */
+function serializeJsxChildren(children, paramNames, warnings) {
+  if (!children || children.length === 0) return ''
+  return children.map(child => serializeJsxToHtml(child, paramNames, warnings)).join('')
+}
+
+/**
+ * Serializes a JSXText node, handling whitespace similar to how React does.
+ * - Whitespace-only text nodes (just newlines/spaces between elements) → empty
+ * - Newlines with surrounding whitespace are collapsed to a single space
+ * - Inline spaces are preserved (they are significant content)
+ * @param {object} node - JSXText AST node
+ * @returns {string}
+ */
+function serializeJsxText(node) {
+  const text = node.value
+  // If the text is only whitespace (newlines, spaces, tabs), return empty
+  if (/^\s+$/.test(text)) return ''
+  // Collapse newlines and their surrounding whitespace to a single space
+  let result = text.replace(/[ \t]*\n[ \t]*/g, '\n')
+  // Split by newlines to handle multi-line text
+  const lines = result.split('\n')
+  // Trim empty leading/trailing lines but preserve inline content
+  let start = 0
+  while (start < lines.length && lines[start].trim() === '') start++
+  let end = lines.length - 1
+  while (end >= start && lines[end].trim() === '') end--
+  if (start > end) return ''
+  // Join remaining lines with a space (newlines become spaces in JSX)
+  return lines.slice(start, end + 1).map((line, i) => {
+    if (i === 0 && start > 0) return line.trimStart()
+    if (i === end - start && end < lines.length - 1) return line.trimEnd()
+    return line
+  }).join(' ')
+}
+
+/**
+ * Serializes a JSX expression container's expression.
+ * @param {object} expression - The expression inside {  }
+ * @param {string[]} [paramNames]
+ * @param {Array<string>} [warnings]
+ * @returns {string}
+ */
+function serializeJsxExpression(expression, paramNames, warnings) {
+  if (!expression) return ''
+
+  // JSXEmptyExpression (e.g., {/* comment */})
+  if (expression.type === 'JSXEmptyExpression') return ''
+
+  // Identifier — check if it's a param reference
+  if (expression.type === 'Identifier') {
+    if (paramNames && paramNames.includes(expression.name)) {
+      return `{%${expression.name}%}`
+    }
+    // Dynamic expression
+    if (warnings) {
+      warnings.push(`Dynamic expression "{${expression.name}}" cannot be statically serialized`)
+    }
+    return ''
+  }
+
+  // String literal — inline the value
+  if (expression.type === 'StringLiteral') {
+    return expression.value
+  }
+
+  // Numeric literal — inline the value
+  if (expression.type === 'NumericLiteral') {
+    return String(expression.value)
+  }
+
+  // Template literal
+  if (expression.type === 'TemplateLiteral') {
+    const result = serializeTemplateLiteral(expression, paramNames, warnings)
+    return result !== null ? result : ''
+  }
+
+  // Other expressions can't be statically serialized
+  if (warnings) {
+    warnings.push(`Expression of type "${expression.type}" cannot be statically serialized`)
+  }
+  return ''
+}
+
+
+/**
+ * Reserved prop names that should always pass through without slot transformation.
+ * @type {Set<string>}
+ */
+const RESERVED_PROPS = new Set([
+  'children', 'key', 'ref', 'className', 'id', 'style', 'slot', 'is', 'dangerouslySetInnerHTML'
+])
+
+/**
+ * Classifies a prop on a custom element to determine how it should be handled.
+ *
+ * Classification rules are applied in priority order:
+ * 1. Reserved props → passthrough
+ * 2. Event handlers (on + uppercase) → passthrough
+ * 3. data-/aria- prefixed props → passthrough
+ * 4. Props in user's exclude list → passthrough
+ * 5. Render props (render + uppercase + ArrowFunctionExpression) → renderProp
+ * 6. Non-JSX/non-string values → passthrough
+ * 7. Named slot prop (respecting slotProps option) → slot
+ *
+ * @param {string} propName - The prop name
+ * @param {object} propValue - The Babel AST node for the prop value
+ * @param {object} options - Plugin options
+ * @param {string[]} [options.exclude] - Prop names to never treat as slots
+ * @param {string[]} [options.slotProps] - Explicit list of prop names to treat as named slots
+ * @returns {{ type: 'slot', name: string, value: object } | { type: 'renderProp', slotName: string, params: string[], body: object } | { type: 'passthrough' }}
+ */
+export function classifyProp(propName, propValue, options = {}) {
+  const { exclude = [], slotProps } = options
+
+  // Rule 1: Reserved props always pass through
+  if (RESERVED_PROPS.has(propName)) {
+    return { type: 'passthrough' }
+  }
+
+  // Rule 2: Event handlers (on + uppercase letter) always pass through
+  if (propName.length > 2 && propName[0] === 'o' && propName[1] === 'n' && propName[2] >= 'A' && propName[2] <= 'Z') {
+    return { type: 'passthrough' }
+  }
+
+  // Rule 3: data- and aria- prefixed props always pass through
+  if (propName.startsWith('data-') || propName.startsWith('aria-')) {
+    return { type: 'passthrough' }
+  }
+
+  // Rule 4: Props in the user's exclude list always pass through
+  if (exclude.includes(propName)) {
+    return { type: 'passthrough' }
+  }
+
+  // Rule 5: Render props (render + uppercase AND ArrowFunctionExpression value)
+  if (/^render[A-Z]/.test(propName) && propValue && propValue.type === 'ArrowFunctionExpression') {
+    const slotName = propName.slice(6)
+    const derivedSlotName = slotName[0].toLowerCase() + slotName.slice(1)
+    const params = (propValue.params || []).map(p => p.name || (p.type === 'Identifier' ? p.name : ''))
+    return {
+      type: 'renderProp',
+      slotName: derivedSlotName,
+      params,
+      body: propValue.body
+    }
+  }
+
+  // Rule 6: Non-JSX/non-string values always pass through
+  // We need to check the actual value type. In JSX, prop values come wrapped in
+  // JSXExpressionContainer. The propValue here is the raw value node.
+  if (propValue) {
+    const valueType = propValue.type
+    // String literals are slot-eligible
+    if (valueType === 'StringLiteral') {
+      // Fall through to Rule 7
+    }
+    // JSX expressions are slot-eligible
+    else if (valueType === 'JSXElement' || valueType === 'JSXFragment') {
+      // Fall through to Rule 7
+    }
+    // Everything else (NumericLiteral, BooleanLiteral, Identifier, ArrayExpression,
+    // ObjectExpression, CallExpression, etc.) passes through
+    else {
+      return { type: 'passthrough' }
+    }
+  } else {
+    // No value (boolean shorthand like `disabled`) passes through
+    return { type: 'passthrough' }
+  }
+
+  // Rule 7: Named slot prop (respecting slotProps option if set)
+  if (slotProps) {
+    // When slotProps is set, only props in that list become slots
+    if (slotProps.includes(propName)) {
+      return { type: 'slot', name: propName, value: propValue }
+    }
+    // Not in the explicit list → passthrough
+    return { type: 'passthrough' }
+  }
+
+  // Default heuristic: any remaining prop with JSX or string value is a slot
+  return { type: 'slot', name: propName, value: propValue }
+}
+
+
+/**
+ * Derives a slot name from a render prop name by stripping the `render` prefix
+ * and lowercasing the first character of the remaining name.
+ *
+ * @param {string} renderPropName - The render prop name (e.g., 'renderStats', 'renderItemRow')
+ * @returns {string} The derived slot name (e.g., 'stats', 'itemRow')
+ *
+ * @example
+ * deriveSlotName('renderStats')   // → 'stats'
+ * deriveSlotName('renderItemRow') // → 'itemRow'
+ */
+export function deriveSlotName(renderPropName) {
+  const withoutPrefix = renderPropName.slice(6) // strip "render"
+  return withoutPrefix[0].toLowerCase() + withoutPrefix.slice(1)
+}
+
+
+/**
+ * Creates a Babel AST JSXElement node representing `<div slot="name">content</div>`.
+ * Used for named slot props whose value is a JSX expression.
+ *
+ * @param {string} slotName - The slot name to use in the `slot` attribute
+ * @param {object} content - A Babel JSX AST node (JSXElement, JSXFragment, etc.) to wrap as children
+ * @returns {object} A Babel JSXElement AST node
+ */
+export function generateNamedSlotElement(slotName, content) {
+  const slotAttr = {
+    type: 'JSXAttribute',
+    name: { type: 'JSXIdentifier', name: 'slot' },
+    value: { type: 'StringLiteral', value: slotName }
+  }
+
+  const openingElement = {
+    type: 'JSXOpeningElement',
+    name: { type: 'JSXIdentifier', name: 'div' },
+    attributes: [slotAttr],
+    selfClosing: false
+  }
+
+  const closingElement = {
+    type: 'JSXClosingElement',
+    name: { type: 'JSXIdentifier', name: 'div' }
+  }
+
+  // Wrap content in a JSXExpressionContainer if it's not already a JSX child type
+  let children
+  if (content.type === 'JSXElement' || content.type === 'JSXFragment' || content.type === 'JSXText' || content.type === 'JSXExpressionContainer') {
+    children = [content]
+  } else {
+    children = [{ type: 'JSXExpressionContainer', expression: content }]
+  }
+
+  return {
+    type: 'JSXElement',
+    openingElement,
+    closingElement,
+    children
+  }
+}
+
+
+/**
+ * Creates a Babel AST JSXElement node representing `<span slot="name">text</span>`.
+ * Used for named slot props whose value is a string literal.
+ *
+ * @param {string} slotName - The slot name to use in the `slot` attribute
+ * @param {string} text - The string text content
+ * @returns {object} A Babel JSXElement AST node
+ */
+export function generateStringSlotElement(slotName, text) {
+  const slotAttr = {
+    type: 'JSXAttribute',
+    name: { type: 'JSXIdentifier', name: 'slot' },
+    value: { type: 'StringLiteral', value: slotName }
+  }
+
+  const openingElement = {
+    type: 'JSXOpeningElement',
+    name: { type: 'JSXIdentifier', name: 'span' },
+    attributes: [slotAttr],
+    selfClosing: false
+  }
+
+  const closingElement = {
+    type: 'JSXClosingElement',
+    name: { type: 'JSXIdentifier', name: 'span' }
+  }
+
+  return {
+    type: 'JSXElement',
+    openingElement,
+    closingElement,
+    children: [{ type: 'JSXText', value: text }]
+  }
+}
+
+
+/**
+ * Creates a Babel AST JSXElement node representing:
+ * `<div slot="name" slot-props="param1,param2" dangerouslySetInnerHTML={{__html: `...`}}></div>`
+ *
+ * Used for render prop (scoped slot) transformation. The body JSX is serialized to an HTML
+ * template string with {%param%} tokens using `serializeJsxToHtml`.
+ *
+ * @param {string} slotName - The derived slot name
+ * @param {string[]} params - The arrow function parameter names
+ * @param {object} body - The Babel JSX AST node for the arrow function body
+ * @returns {object} A Babel JSXElement AST node
+ */
+export function generateScopedSlotElement(slotName, params, body) {
+  // Serialize the body to an HTML template string with {%param%} tokens
+  const htmlTemplate = serializeJsxToHtml(body, params)
+
+  // slot="name" attribute
+  const slotAttr = {
+    type: 'JSXAttribute',
+    name: { type: 'JSXIdentifier', name: 'slot' },
+    value: { type: 'StringLiteral', value: slotName }
+  }
+
+  // slot-props="param1,param2" attribute
+  const slotPropsAttr = {
+    type: 'JSXAttribute',
+    name: { type: 'JSXIdentifier', name: 'slot-props' },
+    value: { type: 'StringLiteral', value: params.join(',') }
+  }
+
+  // dangerouslySetInnerHTML={{__html: `...`}} attribute
+  const dangerouslyAttr = {
+    type: 'JSXAttribute',
+    name: { type: 'JSXIdentifier', name: 'dangerouslySetInnerHTML' },
+    value: {
+      type: 'JSXExpressionContainer',
+      expression: {
+        type: 'ObjectExpression',
+        properties: [{
+          type: 'ObjectProperty',
+          key: { type: 'Identifier', name: '__html' },
+          value: { type: 'TemplateLiteral', quasis: [{ type: 'TemplateElement', value: { raw: htmlTemplate, cooked: htmlTemplate } }], expressions: [] },
+          computed: false,
+          shorthand: false
+        }]
+      }
+    }
+  }
+
+  const openingElement = {
+    type: 'JSXOpeningElement',
+    name: { type: 'JSXIdentifier', name: 'div' },
+    attributes: [slotAttr, slotPropsAttr, dangerouslyAttr],
+    selfClosing: false
+  }
+
+  const closingElement = {
+    type: 'JSXClosingElement',
+    name: { type: 'JSXIdentifier', name: 'div' }
+  }
+
+  return {
+    type: 'JSXElement',
+    openingElement,
+    closingElement,
+    children: []
+  }
+}
+
+
+/**
+ * Vite plugin that transforms idiomatic React JSX slot patterns into
+ * WCC-compatible slot markup at build time.
+ *
+ * Runs with `enforce: 'pre'` so it processes JSX before @vitejs/plugin-react.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.prefix] - Tag prefix filter (e.g., 'wcc-'). If set, only elements starting with this prefix are processed.
+ * @param {string[]} [options.exclude] - Prop names to never treat as slots.
+ * @param {string[]} [options.slotProps] - Explicit list of prop names to treat as named slots (overrides default heuristic).
+ * @returns {import('vite').Plugin}
+ */
+export function wccReactPlugin(options = {}) {
+  const { prefix, exclude = [], slotProps } = options
+
+  return {
+    name: 'vite-plugin-wcc-react-slots',
+    enforce: 'pre',
+    transform(code, id) {
+      // Only process .jsx and .tsx files
+      if (!/\.[jt]sx$/.test(id)) {
+        return null
+      }
+
+      let ast
+      try {
+        ast = parse(code, {
+          sourceType: 'module',
+          plugins: ['jsx', 'typescript']
+        })
+      } catch (e) {
+        this.warn(`[wcc-react] ${id} — failed to parse: ${e.message}`)
+        return null
+      }
+
+      let transformed = false
+      const pluginCtx = this
+
+      traverse(ast, {
+        JSXElement(path) {
+          const openingElement = path.node.openingElement
+          const nameNode = openingElement.name
+
+          // Only process elements with hyphenated tag names (custom elements)
+          if (nameNode.type !== 'JSXIdentifier') return
+          const tagName = nameNode.name
+          if (!tagName.includes('-')) return
+
+          // Apply prefix filtering if set
+          if (prefix && !tagName.startsWith(prefix)) return
+
+          const slotChildren = []
+          const remainingAttributes = []
+
+          for (const attr of openingElement.attributes) {
+            // Skip spread attributes — leave them unchanged
+            if (attr.type !== 'JSXAttribute') {
+              remainingAttributes.push(attr)
+              continue
+            }
+
+            const propName = attr.name.type === 'JSXNamespacedName'
+              ? `${attr.name.namespace.name}:${attr.name.name.name}`
+              : attr.name.name
+
+            // Get the prop value — unwrap JSXExpressionContainer
+            let propValue = attr.value
+            if (propValue && propValue.type === 'JSXExpressionContainer') {
+              propValue = propValue.expression
+            }
+
+            // Task 7.2: Warn on invalid render prop values (non-arrow-function)
+            if (/^render[A-Z]/.test(propName) && propValue && propValue.type !== 'ArrowFunctionExpression' && propValue.type !== 'StringLiteral') {
+              pluginCtx.warn(`[wcc-react] ${id} — ${propName}: expected ArrowFunctionExpression, got ${propValue.type}`)
+              remainingAttributes.push(attr)
+              continue
+            }
+
+            const classification = classifyProp(propName, propValue, { exclude, slotProps })
+
+            if (classification.type === 'slot') {
+              // Task 7.4: Warn on dynamic expressions in named slot props — leave prop unchanged
+              if (classification.value.type === 'JSXElement' || classification.value.type === 'JSXFragment') {
+                const slotWarnings = []
+                serializeJsxToHtml(classification.value, [], slotWarnings)
+                if (slotWarnings.length > 0) {
+                  pluginCtx.warn(`[wcc-react] ${id} — ${propName}: ${slotWarnings[0]}`)
+                  remainingAttributes.push(attr)
+                  continue
+                }
+              }
+              // Generate slot child element
+              if (classification.value.type === 'StringLiteral') {
+                slotChildren.push(generateStringSlotElement(classification.name, classification.value.value))
+              } else {
+                slotChildren.push(generateNamedSlotElement(classification.name, classification.value))
+              }
+              transformed = true
+            } else if (classification.type === 'renderProp') {
+              // Task 7.3: Warn on unsupported expressions in render prop bodies — leave prop unchanged
+              const renderWarnings = []
+              serializeJsxToHtml(classification.body, classification.params, renderWarnings)
+              if (renderWarnings.length > 0) {
+                pluginCtx.warn(`[wcc-react] ${id} — ${propName}: ${renderWarnings[0]}`)
+                remainingAttributes.push(attr)
+                continue
+              }
+              // Generate scoped slot element
+              slotChildren.push(generateScopedSlotElement(
+                classification.slotName,
+                classification.params,
+                classification.body
+              ))
+              transformed = true
+            } else {
+              // passthrough — keep the attribute
+              remainingAttributes.push(attr)
+            }
+          }
+
+          if (slotChildren.length > 0) {
+            // Remove transformed slot props from the element's attributes
+            openingElement.attributes = remainingAttributes
+
+            // If element was self-closing, convert to open/close pair
+            if (openingElement.selfClosing) {
+              openingElement.selfClosing = false
+              path.node.closingElement = { type: 'JSXClosingElement', name: { ...nameNode } }
+            }
+
+            // Append generated slot elements after existing children
+            path.node.children = [...path.node.children, ...slotChildren]
+          }
+        }
+      })
+
+      if (!transformed) {
+        return null
+      }
+
+      const result = generate(ast, { sourceMaps: true, sourceFileName: id }, code)
+      return { code: result.code, map: result.map }
+    }
+  }
+}

package/lib/codegen.js

@@ -962,10 +962,24 @@ export function generateComponent(parseResult, options = {}) {
     lines.push('');
   }
 
+  // Static __scopedSlots array (lists slot names with reactive props)
+  const scopedSlotNames = slots.filter(s => s.name && s.slotProps.length > 0).map(s => s.name);
+  if (scopedSlotNames.length > 0) {
+    const scopedArr = scopedSlotNames.map(n => `'${n}'`).join(', ');
+    lines.push(`  static __scopedSlots = [${scopedArr}];`);
+    lines.push('');
+  }
+
   // Constructor — reactive state only (no DOM manipulation per Custom Elements spec)
   lines.push('  constructor() {');
   lines.push('    super();');
 
+  // Scoped slot storage initialization
+  if (scopedSlotNames.length > 0) {
+    lines.push('    this.__slotRenderers = {};');
+    lines.push('    this.__slotProps = {};');
+  }
+
   // Prop signal initialization (BEFORE user signals)
   for (const p of propDefs) {
     lines.push(`    this._s_${p.name} = __signal(${p.default});`);
@@ -1277,11 +1291,20 @@ export function generateComponent(parseResult, options = {}) {
       lines.push(`    if (this.__slotTpl_${s.name}) {`);
       lines.push('      __effect(() => {');
       lines.push(`        const __props = { ${propsObj} };`);
-      lines.push(`        let __html = this.__slotTpl_${s.name};`);
-      lines.push("        for (const [k, v] of Object.entries(__props)) {");
-      lines.push(`          __html = __html.replace(new RegExp('(?:\\\\{\\\\{|\\\\{%)\\\\s*' + k + '(\\\\(\\\\))?\\\\s*(?:\\\\}\\\\}|%\\\\})', 'g'), v ?? '');`);
+      // Task 3.1: Store current props in __slotProps
+      lines.push(`        this.__slotProps['${s.name}'] = __props;`);
+      // Task 3.2: Emit wcc:slot-update event
+      lines.push(`        this.dispatchEvent(new CustomEvent('wcc:slot-update', { detail: { slot: '${s.name}', props: __props }, bubbles: false }));`);
+      // Task 3.3: Check for registered renderer, skip token replacement if present
+      lines.push(`        if (this.__slotRenderers && this.__slotRenderers['${s.name}']) {`);
+      lines.push(`          this.__slotRenderers['${s.name}'](__props);`);
+      lines.push('        } else {');
+      lines.push(`          let __html = this.__slotTpl_${s.name};`);
+      lines.push("          for (const [k, v] of Object.entries(__props)) {");
+      lines.push(`            __html = __html.replace(new RegExp('(?:\\\\{\\\\{|\\\\{%)\\\\s*' + k + '(\\\\(\\\\))?\\\\s*(?:\\\\}\\\\}|%\\\\})', 'g'), v ?? '');`);
+      lines.push('          }');
+      lines.push(`          this.${s.varName}.innerHTML = __html;`);
       lines.push('        }');
-      lines.push(`        this.${s.varName}.innerHTML = __html;`);
       lines.push('      });');
       lines.push('    }');
     }
@@ -1769,6 +1792,25 @@ export function generateComponent(parseResult, options = {}) {
     lines.push('');
   }
 
+  // __scopedSlots instance getter and registerSlotRenderer (if scoped slots exist)
+  if (scopedSlotNames.length > 0) {
+    lines.push('  get __scopedSlots() { return this.constructor.__scopedSlots || []; }');
+    lines.push('');
+    lines.push('  registerSlotRenderer(slotName, callback) {');
+    lines.push('    if (!this.__slotRenderers) this.__slotRenderers = {};');
+    lines.push('    this.__slotRenderers[slotName] = callback;');
+    lines.push('    if (this.__slotProps && this.__slotProps[slotName]) {');
+    lines.push('      callback(this.__slotProps[slotName]);');
+    lines.push('    }');
+    lines.push('    return () => {');
+    lines.push('      if (this.__slotRenderers) {');
+    lines.push('        delete this.__slotRenderers[slotName];');
+    lines.push('      }');
+    lines.push('    };');
+    lines.push('  }');
+    lines.push('');
+  }
+
   // User methods (prefixed with _)
   for (const m of methods) {
     const body = transformMethodBody(m.body, signalNames, computedNames, propsObjectName, propNames, emitsObjectName, refVarNames, constantNames, modelVarMap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprlab/wccompiler",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Zero-runtime compiler that transforms .wcc single-file components into native web components with signals-based reactivity",
   "type": "module",
   "exports": {
@@ -41,20 +41,32 @@
     "access": "public"
   },
   "dependencies": {
+    "@babel/generator": "^7.27.0",
+    "@babel/parser": "^7.27.0",
+    "@babel/traverse": "^7.27.0",
+    "@babel/types": "^7.27.0",
     "esbuild": "^0.27.0",
     "linkedom": "^0.18.12"
   },
   "peerDependencies": {
+    "@angular/core": ">=14.0.0",
     "@vitejs/plugin-vue": ">=4.0.0",
-    "vue": ">=3.0.0",
     "react": ">=18.0.0",
-    "@angular/core": ">=14.0.0"
+    "vue": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "@vitejs/plugin-vue": { "optional": true },
-    "vue": { "optional": true },
-    "react": { "optional": true },
-    "@angular/core": { "optional": true }
+    "@angular/core": {
+      "optional": true
+    },
+    "@vitejs/plugin-vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "fast-check": "^4.1.1",