@sprlab/wccompiler 0.7.3 → 0.8.1

package/adapters/angular.js

@@ -0,0 +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;
+    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

@@ -0,0 +1,132 @@
+/**
+ * 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;
+    e.target.dispatchEvent(new CustomEvent(`update:${prop}`, {
+      detail: value,
+      bubbles: true
+    }));
+  });
+}
+
+// ── 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,8 +43,19 @@
  * 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.
+ * @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"
+ *
+ * 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 file contains a copy-paste TypeScript directive implementation.
  */
 
 /**
@@ -39,10 +63,11 @@
  * 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/react.js

@@ -13,9 +13,14 @@
  *   // Form 2: Let the hook create the ref
  *   const ref = useWccEvent('change', (e) => console.log(e.detail))
  *   <wcc-counter ref={ref}></wcc-counter>
+ *
+ *   // Form 3: Two-way binding with defineModel
+ *   const [value, setValue] = useState('')
+ *   const ref = useWccModel('value', value, setValue)
+ *   <wcc-input ref={ref}></wcc-input>
  */
 
-import { useRef, useEffect } from 'react'
+import { useRef, useEffect, useCallback } from 'react'
 
 /**
  * Hook that attaches a CustomEvent listener to a DOM element via ref.
@@ -50,3 +55,62 @@ export function useWccEvent(refOrEventName, eventNameOrHandler, handler) {
   // Only return ref if we created it (Form 2)
   if (!isRefForm) return elementRef
 }
+
+
+/**
+ * Hook for two-way binding with WCC defineModel props.
+ *
+ * Listens for `wcc:model` events on the element and calls the setter
+ * when the matching prop changes internally. Also syncs the React state
+ * to the element's attribute when the value changes externally.
+ *
+ * @param {string} propName - The model prop name (e.g., 'value', 'count')
+ * @param {*} value - Current React state value
+ * @param {(newValue: *) => void} setValue - React state setter
+ * @param {import('react').RefObject<HTMLElement>} [existingRef] - Optional existing ref
+ * @returns {import('react').RefObject<HTMLElement>} Ref to attach to the WCC element
+ *
+ * @example
+ * ```jsx
+ * function App() {
+ *   const [text, setText] = useState('')
+ *   const inputRef = useWccModel('value', text, setText)
+ *   return <wcc-input ref={inputRef}></wcc-input>
+ * }
+ * ```
+ */
+export function useWccModel(propName, value, setValue, existingRef) {
+  const internalRef = useRef(null)
+  const elementRef = existingRef || internalRef
+
+  const setValueRef = useRef(setValue)
+  setValueRef.current = setValue
+
+  // Listen for wcc:model events from the component (child → parent)
+  useEffect(() => {
+    const el = elementRef.current
+    if (!el) return
+
+    const listener = (e) => {
+      if (e.detail && e.detail.prop === propName) {
+        setValueRef.current(e.detail.value)
+      }
+    }
+
+    el.addEventListener('wcc:model', listener)
+    return () => el.removeEventListener('wcc:model', listener)
+  }, [propName])
+
+  // Sync React state to the element's attribute (parent → child)
+  useEffect(() => {
+    const el = elementRef.current
+    if (!el) return
+    if (value != null) {
+      el.setAttribute(propName, String(value))
+    } else {
+      el.removeAttribute(propName)
+    }
+  }, [propName, value])
+
+  return elementRef
+}

package/integrations/vue.js

@@ -3,6 +3,20 @@
  * Configures isCustomElement to recognize WCC component tags.
  *
  * @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'