@sprlab/wccompiler 0.8.0 → 0.8.1

package/adapters/angular.js

@@ -1,9 +1,104 @@
+/**
+ * Angular adapter for WCC defineModel — enables [(propName)] two-way binding.
+ *
+ * Import this ONCE in your Angular app's main.ts:
+ *   import '@sprlab/wccompiler/adapters/angular'
+ *
+ * What it does:
+ * 1. Translates wcc:model events → propNameChange (enables [(prop)] syntax)
+ * 2. Uses queueMicrotask to defer event emission outside Angular's render cycle
+ *    (prevents NG0600: "Writing to signals is not allowed while Angular renders")
+ *
+ * Usage:
+ *   <!-- In Angular template (with CUSTOM_ELEMENTS_SCHEMA) -->
+ *   <wcc-input [(value)]="text"></wcc-input>
+ *   <wcc-counter [(count)]="myCount"></wcc-counter>
+ *
+ * For ngModel support, you need a ControlValueAccessor.
+ * See the exported WccValueAccessor class below.
+ *
+ * @module @sprlab/wccompiler/adapters/angular
+ */
+
+// ── Document-level adapter: wcc:model → propNameChange ──────────────
+// Angular's [(prop)] syntax listens for `propChange` events.
+// Uses queueMicrotask to defer the re-dispatch outside Angular's synchronous
+// render cycle, preventing NG0600 errors when Angular is mid-render.
+
 if (typeof document !== 'undefined') {
   document.addEventListener('wcc:model', (e) => {
     const { prop, value } = e.detail;
-    e.target.dispatchEvent(new CustomEvent(`${prop}Change`, {
-      detail: value,
-      bubbles: true
-    }));
+    const target = e.target;
+
+    // Defer to next microtask to avoid NG0600
+    // (Angular doesn't allow signal writes during render)
+    queueMicrotask(() => {
+      target.dispatchEvent(new CustomEvent(`${prop}Change`, {
+        detail: value,
+        bubbles: true
+      }));
+    });
   });
 }
+
+// ── ControlValueAccessor for ngModel/ReactiveForms ──────────────────
+// Angular's ngModel requires a ControlValueAccessor to bridge form controls.
+// Since this is a JS file (not TypeScript with decorators), we export the
+// implementation as a guide. Users need to create a TypeScript directive.
+//
+// Copy this into your Angular project as a .ts file:
+//
+// ```ts
+// import { Directive, ElementRef, forwardRef, HostListener } from '@angular/core';
+// import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+//
+// @Directive({
+//   selector: '[wccModel]',
+//   providers: [{
+//     provide: NG_VALUE_ACCESSOR,
+//     useExisting: forwardRef(() => WccValueAccessor),
+//     multi: true
+//   }]
+// })
+// export class WccValueAccessor implements ControlValueAccessor {
+//   private onChange: (value: any) => void = () => {};
+//   private onTouched: () => void = () => {};
+//
+//   constructor(private el: ElementRef<HTMLElement>) {}
+//
+//   writeValue(value: any): void {
+//     // Parent → Child: set attribute
+//     if (value != null) {
+//       this.el.nativeElement.setAttribute('value', String(value));
+//     } else {
+//       this.el.nativeElement.removeAttribute('value');
+//     }
+//   }
+//
+//   registerOnChange(fn: (value: any) => void): void {
+//     this.onChange = fn;
+//   }
+//
+//   registerOnTouched(fn: () => void): void {
+//     this.onTouched = fn;
+//   }
+//
+//   @HostListener('wcc:model', ['$event'])
+//   onModelChange(event: CustomEvent): void {
+//     if (event.detail && event.detail.prop === 'value') {
+//       this.onChange(event.detail.value);
+//     }
+//   }
+//
+//   @HostListener('blur')
+//   onBlur(): void {
+//     this.onTouched();
+//   }
+// }
+// ```
+//
+// Usage with ngModel:
+//   <wcc-input wccModel [(ngModel)]="text"></wcc-input>
+//
+// Usage with Reactive Forms:
+//   <wcc-input wccModel [formControl]="myControl"></wcc-input>

package/adapters/vue.js

@@ -1,3 +1,32 @@
+/**
+ * Vue adapter for WCC defineModel — enables v-model and multi-model binding.
+ *
+ * Usage (ONE line in main.js):
+ *   import { createApp } from 'vue'
+ *   import { wccVue } from '@sprlab/wccompiler/adapters/vue'
+ *
+ *   const app = createApp(App)
+ *   app.use(wccVue)  // registers adapter + v-wcc-model directive globally
+ *   app.mount('#app')
+ *
+ * What it does:
+ * 1. Registers document-level wcc:model → update:propName translation (enables v-model)
+ * 2. Registers v-wcc-model directive globally (enables multi-prop two-way binding)
+ *
+ * Template usage:
+ *   <!-- Single model prop (Vue's native v-model) -->
+ *   <!-- Component must declare: defineModel({ name: 'modelValue', default: '' }) -->
+ *   <wcc-input v-model="text"></wcc-input>
+ *
+ *   <!-- Multiple model props (v-wcc-model:propName) -->
+ *   <wcc-form v-model="mainValue" v-wcc-model:count="countRef" v-wcc-model:title="titleRef"></wcc-form>
+ *
+ * @module @sprlab/wccompiler/adapters/vue
+ */
+
+// ── Document-level adapter: wcc:model → update:propName ─────────────
+// This enables Vue's native v-model on WCC custom elements.
+
 if (typeof document !== 'undefined') {
   document.addEventListener('wcc:model', (e) => {
     const { prop, value } = e.detail;
@@ -7,3 +36,97 @@ if (typeof document !== 'undefined') {
     }));
   });
 }
+
+// ── Vue directive: v-wcc-model ──────────────────────────────────────
+
+/**
+ * Vue custom directive for two-way binding with WCC defineModel props.
+ *
+ * Binds a Vue ref to a WCC component's model prop bidirectionally:
+ * - Parent → Child: sets the attribute when the Vue ref changes
+ * - Child → Parent: updates the Vue ref when wcc:model fires for the matching prop
+ *
+ * @example
+ * <wcc-counter v-wcc-model:count="myCount"></wcc-counter>
+ */
+export const vWccModel = {
+  mounted(el, binding) {
+    const propName = binding.arg;
+    if (!propName) {
+      console.warn('[v-wcc-model] Missing argument. Usage: v-wcc-model:propName="ref"');
+      return;
+    }
+
+    // Set initial value (parent → child)
+    if (binding.value != null) {
+      el.setAttribute(propName, String(binding.value));
+    }
+
+    // Listen for child → parent changes via the update:propName event
+    // (which is already dispatched by the document-level adapter above)
+    const handler = (e) => {
+      // Use the update:propName event dispatched by the adapter
+      // Vue will handle the ref update through the directive binding
+    };
+
+    // Listen directly for wcc:model to update the binding
+    const wccHandler = (e) => {
+      if (e.detail && e.detail.prop === propName) {
+        // Trigger Vue reactivity by emitting on the component instance
+        // This works because Vue tracks directive bindings
+        el.dispatchEvent(new CustomEvent(`update:${propName}`, {
+          detail: e.detail.value,
+          bubbles: false
+        }));
+      }
+    };
+
+    el.addEventListener('wcc:model', wccHandler);
+    // Store handler for cleanup
+    el.__wccModelHandlers = el.__wccModelHandlers || {};
+    el.__wccModelHandlers[propName] = wccHandler;
+  },
+
+  updated(el, binding) {
+    const propName = binding.arg;
+    if (!propName) return;
+
+    // Sync parent → child on updates
+    if (binding.value != null) {
+      el.setAttribute(propName, String(binding.value));
+    } else {
+      el.removeAttribute(propName);
+    }
+  },
+
+  beforeUnmount(el, binding) {
+    const propName = binding.arg;
+    if (!propName) return;
+
+    // Cleanup listener
+    const handler = el.__wccModelHandlers?.[propName];
+    if (handler) {
+      el.removeEventListener('wcc:model', handler);
+      delete el.__wccModelHandlers[propName];
+    }
+  }
+};
+
+// ── Vue Plugin: app.use(wccVue) ─────────────────────────────────────
+
+/**
+ * Vue plugin that registers the wcc:model adapter and v-wcc-model directive globally.
+ *
+ * @example
+ * import { createApp } from 'vue'
+ * import { wccVue } from '@sprlab/wccompiler/adapters/vue'
+ *
+ * const app = createApp(App)
+ * app.use(wccVue)
+ * app.mount('#app')
+ */
+export const wccVue = {
+  install(app) {
+    app.directive('wcc-model', vWccModel);
+  }
+};

package/integrations/angular.js

@@ -3,21 +3,34 @@
  *
  * @module @sprlab/wccompiler/integrations/angular
  *
- * 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:
+ * Setup requires two steps:
+ *
+ * 1. Import the adapter in main.ts (enables [(prop)] two-way binding):
+ *    ```ts
+ *    import '@sprlab/wccompiler/adapters/angular'
+ *    ```
+ *
+ * 2. Add CUSTOM_ELEMENTS_SCHEMA to your component/module:
  *
  * @example Standalone component (Angular 17+)
  * ```ts
- * import { Component } from '@angular/core';
- * import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+ * import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
  *
  * @Component({
  *   selector: 'app-root',
  *   schemas: [CUSTOM_ELEMENTS_SCHEMA],
- *   template: `<wcc-counter></wcc-counter>`
+ *   template: `
+ *     <!-- Simple one-way binding -->
+ *     <wcc-counter [count]="myCount"></wcc-counter>
+ *
+ *     <!-- Two-way binding with [(prop)] -->
+ *     <wcc-input [(value)]="text"></wcc-input>
+ *   `
  * })
- * export class AppComponent {}
+ * export class AppComponent {
+ *   text = '';
+ *   myCount = 0;
+ * }
  * ```
  *
  * @example NgModule approach
@@ -30,33 +43,31 @@
  * export class AppModule {}
  * ```
  *
- * @example Two-way binding with defineModel
- * ```ts
- * // The adapter translates wcc:model events to Angular's propNameChange convention.
- * // Import the integration once in your main.ts or app module:
- * import '@sprlab/wccompiler/integrations/angular'
+ * @example Two-way binding with [(prop)]
+ * The adapter translates wcc:model events to Angular's propChange convention.
+ * Angular's banana-in-a-box [(prop)] expands to:
+ *   [prop]="value" (propChange)="value = $event.detail"
  *
- * // Then use Angular's banana-in-a-box syntax:
- * // <wcc-input [(value)]="myValue"></wcc-input>
- * ```
+ * So when the WCC component emits wcc:model with { prop: 'value', value: 'new' },
+ * the adapter re-dispatches as 'valueChange' CustomEvent, which Angular picks up.
+ *
+ * @example ngModel support (requires ControlValueAccessor)
+ * For ngModel/ReactiveForms, see the WccValueAccessor guide in:
+ *   @sprlab/wccompiler/adapters/angular
  *
- * That's it — one line of config. WCC components work as native custom elements
- * in Angular without any additional wrapper or helper.
+ * That file contains a copy-paste TypeScript directive implementation.
  */
 
-// Side-effect: registers document-level wcc:model → propNameChange translation
-// This enables [(propName)] two-way binding on WCC components in Angular templates.
-import '../adapters/angular.js'
-
 /**
  * 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.
  *
- * @type {{ schema: string, standalone: string, ngModule: string }}
+ * @type {{ schema: string, standalone: string, ngModule: string, adapter: string }}
  */
 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] })",
+  adapter: "import '@sprlab/wccompiler/adapters/angular' // in main.ts",
 }

package/integrations/vue.js

@@ -1,17 +1,26 @@
 /**
  * Vue Vite plugin for WCC custom elements.
  * Configures isCustomElement to recognize WCC component tags.
- * Also re-exports the defineModel adapter for v-model support.
  *
  * @module @sprlab/wccompiler/integrations/vue
+ *
+ * IMPORTANT: This file is for vite.config.js (Node.js context).
+ * For browser-side model adapter, import '@sprlab/wccompiler/adapters/vue' in your main.js.
+ *
+ * @example vite.config.js
+ * ```js
+ * import { wccVuePlugin } from '@sprlab/wccompiler/integrations/vue'
+ * export default { plugins: [wccVuePlugin()] }
+ * ```
+ *
+ * @example main.js (browser — enables v-model on WCC components)
+ * ```js
+ * import '@sprlab/wccompiler/adapters/vue'
+ * ```
  */
 
 import vue from '@vitejs/plugin-vue'
 
-// Side-effect: registers document-level wcc:model → update:propName translation
-// This enables v-model:propName on WCC components in Vue templates.
-import '../adapters/vue.js'
-
 /**
  * @typedef {Object} WccVuePluginOptions
  * @property {string} [prefix='wcc-'] - Tag prefix for custom element detection

package/package.json

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