@sprlab/wccompiler 0.7.1 → 0.7.3

package/README.md

@@ -656,12 +656,21 @@ export default defineConfig({
 
 ### React
 
-React 19+ supports custom elements natively. For React 18, use the event hook:
+React 19+ supports custom elements natively. For React 18, use the event hook to bridge CustomEvents:
 
 ```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>
+}
+
+// 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>
 }
@@ -669,19 +678,23 @@ function App() {
 
 ### Angular
 
+Add `CUSTOM_ELEMENTS_SCHEMA` to your component or module — this is Angular's built-in way to allow custom elements:
+
 ```ts
-import { WCC_SCHEMAS } from '@sprlab/wccompiler/integrations/angular'
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
 
 // Standalone component (Angular 17+)
 @Component({
-  schemas: WCC_SCHEMAS,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
   template: `<wcc-counter></wcc-counter>`
 })
+export class AppComponent {}
 
 // Or NgModule approach
 @NgModule({
-  schemas: WCC_SCHEMAS,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+export class AppModule {}
 ```
 
 ### Vanilla

package/integrations/angular.js

@@ -1,31 +1,48 @@
 /**
- * Angular schema helper for WCC custom elements.
- * Provides CUSTOM_ELEMENTS_SCHEMA configuration for Angular modules/components.
+ * Angular integration guide for WCC custom elements.
  *
  * @module @sprlab/wccompiler/integrations/angular
- */
-
-import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
-
-/**
- * Schema array for Angular components/modules that use WCC custom elements.
- * Use in @Component({ schemas: WCC_SCHEMAS }) or @NgModule({ schemas: WCC_SCHEMAS })
  *
- * @type {Array<import('@angular/core').SchemaMetadata>}
+ * Angular's AOT compiler requires schemas to be statically analyzable,
+ * so we cannot provide a re-exported schema constant that works at compile time.
+ * Instead, use Angular's built-in CUSTOM_ELEMENTS_SCHEMA directly:
+ *
+ * @example Standalone component (Angular 17+)
+ * ```ts
+ * import { Component } from '@angular/core';
+ * import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+ *
+ * @Component({
+ *   selector: 'app-root',
+ *   schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ *   template: `<wcc-counter></wcc-counter>`
+ * })
+ * export class AppComponent {}
+ * ```
+ *
+ * @example NgModule approach
+ * ```ts
+ * import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+ *
+ * @NgModule({
+ *   schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * That's it — one line of config. WCC components work as native custom elements
+ * in Angular without any additional wrapper or helper.
  */
-export const WCC_SCHEMAS = [CUSTOM_ELEMENTS_SCHEMA]
 
 /**
- * NgModule-compatible class that declares CUSTOM_ELEMENTS_SCHEMA.
- * Import this in your NgModule's imports array.
- *
- * Usage:
- * @NgModule({ imports: [WccModule] })
- * export class AppModule {}
+ * Configuration instructions for Angular projects using WCC components.
+ * This is a documentation-only export — Angular's AOT compiler requires
+ * CUSTOM_ELEMENTS_SCHEMA to be imported directly from @angular/core.
  *
- * Note: For standalone components (Angular 17+), use WCC_SCHEMAS directly:
- * @Component({ schemas: WCC_SCHEMAS })
+ * @type {{ schema: string, standalone: string, ngModule: string }}
  */
-export class WccModule {
-  static schemas = WCC_SCHEMAS
+export const WCC_ANGULAR_CONFIG = {
+  schema: "import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'",
+  standalone: "@Component({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })",
+  ngModule: "@NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })",
 }

package/integrations/react.js

@@ -3,6 +3,16 @@
  * Bridges CustomEvent to React's ref-based event system.
  *
  * @module @sprlab/wccompiler/integrations/react
+ *
+ * Usage:
+ *   // Form 1: Pass an existing ref
+ *   const ref = useRef(null)
+ *   useWccEvent(ref, 'change', (e) => console.log(e.detail))
+ *   <wcc-counter ref={ref}></wcc-counter>
+ *
+ *   // Form 2: Let the hook create the ref
+ *   const ref = useWccEvent('change', (e) => console.log(e.detail))
+ *   <wcc-counter ref={ref}></wcc-counter>
  */
 
 import { useRef, useEffect } from 'react'
@@ -10,22 +20,33 @@ import { useRef, useEffect } from 'react'
 /**
  * Hook that attaches a CustomEvent listener to a DOM element via ref.
  *
- * @param {string} eventName - The event name to listen for
- * @param {(event: CustomEvent) => void} handler - Event handler callback
- * @returns {import('react').RefObject<HTMLElement>}
+ * Supports two calling conventions:
+ * - useWccEvent(ref, eventName, handler) — uses an existing ref
+ * - useWccEvent(eventName, handler) — creates and returns a new ref
+ *
+ * @param {import('react').RefObject<HTMLElement> | string} refOrEventName
+ * @param {string | ((event: CustomEvent) => void)} eventNameOrHandler
+ * @param {((event: CustomEvent) => void)} [handler]
+ * @returns {import('react').RefObject<HTMLElement> | void}
  */
-export function useWccEvent(eventName, handler) {
-  const ref = useRef(null)
-  const handlerRef = useRef(handler)
-  handlerRef.current = handler
+export function useWccEvent(refOrEventName, eventNameOrHandler, handler) {
+  // Detect calling convention
+  const isRefForm = typeof refOrEventName !== 'string'
+  const elementRef = isRefForm ? refOrEventName : useRef(null)
+  const eventName = isRefForm ? eventNameOrHandler : refOrEventName
+  const callback = isRefForm ? handler : eventNameOrHandler
+
+  const handlerRef = useRef(callback)
+  handlerRef.current = callback
 
   useEffect(() => {
-    const el = ref.current
+    const el = elementRef.current
     if (!el) return
     const listener = (e) => handlerRef.current(e)
     el.addEventListener(eventName, listener)
     return () => el.removeEventListener(eventName, listener)
   }, [eventName])
 
-  return ref
+  // Only return ref if we created it (Form 2)
+  if (!isRefForm) return elementRef
 }

package/lib/codegen.js

@@ -1186,7 +1186,9 @@ export function generateComponent(parseResult, options = {}) {
       lines.push('    this.__disposers.push(__effect(() => {');
       lines.push(`      const ${w.newParam} = ${watchRef};`);
       lines.push(`      if (this.__prev_${w.target} !== undefined && this.__prev_${w.target} !== ${w.newParam}) {`);
-      lines.push(`        const ${w.oldParam} = this.__prev_${w.target};`);
+      if (w.oldParam) {
+        lines.push(`        const ${w.oldParam} = this.__prev_${w.target};`);
+      }
       lines.push('        __untrack(() => {');
       const bodyLines = body.split('\n');
       for (const line of bodyLines) {
@@ -1203,7 +1205,9 @@ export function generateComponent(parseResult, options = {}) {
       lines.push('    this.__disposers.push(__effect(() => {');
       lines.push(`      const ${w.newParam} = ${getterExpr};`);
       lines.push(`      if (this.${prevName} !== undefined && this.${prevName} !== ${w.newParam}) {`);
-      lines.push(`        const ${w.oldParam} = this.${prevName};`);
+      if (w.oldParam) {
+        lines.push(`        const ${w.oldParam} = this.${prevName};`);
+      }
       lines.push('        __untrack(() => {');
       const bodyLines2 = body.split('\n');
       for (const line of bodyLines2) {

package/lib/parser-extractors.js

@@ -782,10 +782,10 @@ export function extractWatchers(source) {
   while (i < lines.length) {
     const line = lines[i];
 
-    // Form 2 — Getter function: watch(() => expr, (newVal, oldVal) => {
-    const mGetter = line.match(/\bwatch\s*\(\s*\(\)\s*=>\s*(.+?)\s*,\s*\((\w+)\s*,\s*(\w+)\)\s*=>\s*\{/);
-    // Form 1 — Signal direct: watch(identifier, (newVal, oldVal) => {
-    const mSignal = !mGetter ? line.match(/\bwatch\s*\(\s*(\w+)\s*,\s*\((\w+)\s*,\s*(\w+)\)\s*=>\s*\{/) : null;
+    // Form 2 — Getter function: watch(() => expr, (newVal, oldVal) => {  OR  watch(() => expr, (newVal) => {
+    const mGetter = line.match(/\bwatch\s*\(\s*\(\)\s*=>\s*(.+?)\s*,\s*\((\w+)(?:\s*,\s*(\w+))?\)\s*=>\s*\{/);
+    // Form 1 — Signal direct: watch(identifier, (newVal, oldVal) => {  OR  watch(identifier, (newVal) => {
+    const mSignal = !mGetter ? line.match(/\bwatch\s*\(\s*(\w+)\s*,\s*\((\w+)(?:\s*,\s*(\w+))?\)\s*=>\s*\{/) : null;
 
     const m = mGetter || mSignal;
 

package/package.json

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