@sprlab/wccompiler 0.10.1 → 0.10.3

package/adapters/react.js

@@ -105,11 +105,33 @@ export function useWccModel(propName, value, setValue, existingRef) {
 }
 
 
+/**
+ * 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`, `onCountChanged` → automatically wired via addEventListener
+ * - 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)
@@ -118,9 +140,9 @@ export function useWccModel(propName, value, setValue, existingRef) {
  * @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' → onCountChanged prop
+ *   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) + `onNameChanged` event
+ *   Each model 'name' creates: `name` prop (sets attribute) + `onNameChange` event
  * @returns {import('react').ForwardRefExoticComponent} A React component
  *
  * @example
@@ -134,8 +156,8 @@ export function useWccModel(propName, value, setValue, existingRef) {
  *   return (
  *     <WccCounter
  *       count={count}
- *       onCountChanged={(e) => setCount(e.detail)}
- *       onChange={(e) => console.log('changed', e.detail)}
+ *       onCountChange={(value) => setCount(value)}
+ *       onChange={(value) => console.log('changed', value)}
  *       label="Clicks"
  *     >
  *       <div slot="footer">Footer content</div>
@@ -147,19 +169,21 @@ export function createWccWrapper(tagName, config = {}) {
   const { events = [], models = [] } = config
 
   // Build a set of event prop names for quick lookup
-  // 'count-changed' → 'onCountChanged'
+  // 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 = 'on' + eventName.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
+    const propName = toReactEventProp(eventName)
     eventPropMap.set(propName, eventName)
   }
 
-  // Model events: 'count' → 'count-changed' → 'onCountChanged'
+  // Model events: 'count' → 'count-changed' → 'onCountChange'
   const modelEventMap = new Map()
   for (const modelName of models) {
     const eventName = `${modelName}-changed`
-    const propName = 'on' + eventName.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
+    const propName = toReactEventProp(eventName)
     eventPropMap.set(propName, eventName)
     modelEventMap.set(modelName, eventName)
   }
@@ -207,7 +231,7 @@ export function createWccWrapper(tagName, config = {}) {
       for (const eventName of allEvents) {
         const listener = (e) => {
           const handler = handlersRef.current[eventName]
-          if (handler) handler(e)
+          if (handler) handler(e instanceof CustomEvent ? e.detail : e)
         }
         el.addEventListener(eventName, listener)
         listeners.push([eventName, listener])
@@ -249,3 +273,88 @@ export function createWccWrapper(tagName, config = {}) {
   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

@@ -745,3 +745,120 @@ export function wccReactPlugin(options = {}) {
     }
   }
 }
+
+
+/**
+ * Vite plugin that generates a virtual module `@wcc/react` (or custom id)
+ * exporting pre-built React wrapper components for all WCC components found
+ * in the project's compiled output directory.
+ *
+ * This enables the ideal import experience:
+ *   import { WccCounter, WccCard } from '@wcc/react'
+ *
+ * The plugin scans the output directory for compiled .js files, reads their
+ * `static __meta` declarations, and generates wrapper code using createWccWrapper.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.moduleId='@wcc/react'] - Virtual module ID for imports
+ * @param {string} [options.componentsDir='./dist'] - Directory containing compiled WCC .js files
+ * @param {string} [options.prefix='wcc-'] - Tag prefix filter
+ * @returns {import('vite').Plugin}
+ *
+ * @example vite.config.js
+ * ```js
+ * import { wccReactPlugin, wccReactComponents } from '@sprlab/wccompiler/integrations/react'
+ * export default {
+ *   plugins: [
+ *     wccReactPlugin(),
+ *     wccReactComponents({ componentsDir: './src/wcc' })
+ *   ]
+ * }
+ * ```
+ *
+ * @example Component.jsx
+ * ```jsx
+ * import { WccCounter, WccCard } from '@wcc/react'
+ *
+ * <WccCounter count={count} onCountChange={setCount} />
+ * <WccCard><div slot="header">Title</div></WccCard>
+ * ```
+ */
+export function wccReactComponents(options = {}) {
+  const {
+    moduleId = '@wcc/react',
+    componentsDir = './dist',
+    prefix = 'wcc-'
+  } = options
+
+  const resolvedId = '\0' + moduleId
+
+  return {
+    name: 'vite-plugin-wcc-react-components',
+    resolveId(id) {
+      if (id === moduleId) return resolvedId
+      return null
+    },
+    async load(id) {
+      if (id !== resolvedId) return null
+
+      // Scan componentsDir for .js files and extract __meta
+      const fs = await import('fs')
+      const path = await import('path')
+
+      const dir = path.default.resolve(componentsDir)
+      if (!fs.default.existsSync(dir)) {
+        this.warn(`[wcc-react-components] Directory not found: ${dir}`)
+        return 'export {}'
+      }
+
+      const files = fs.default.readdirSync(dir).filter(f => f.endsWith('.js'))
+      const components = []
+
+      for (const file of files) {
+        const content = fs.default.readFileSync(path.default.join(dir, file), 'utf-8')
+        const metaMatch = content.match(/static __meta\s*=\s*(\{[^}]+\})/)
+        if (!metaMatch) continue
+
+        try {
+          // Parse the meta object (it's a JS object literal, evaluate safely)
+          const metaStr = metaMatch[1]
+            .replace(/'/g, '"')
+            .replace(/(\w+):/g, '"$1":')
+            .replace(/,\s*}/g, '}')
+            .replace(/,\s*]/g, ']')
+          const meta = JSON.parse(metaStr)
+
+          if (!meta.tag || !meta.tag.startsWith(prefix)) continue
+
+          const pascalName = meta.tag.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
+          components.push({ meta, pascalName, file })
+        } catch (e) {
+          // Skip files with unparseable meta
+        }
+      }
+
+      if (components.length === 0) {
+        return 'export {}'
+      }
+
+      // Generate the virtual module code
+      let code = `import { createWccWrapper } from '@sprlab/wccompiler/adapters/react';\n`
+
+      // Import each component file to ensure registration
+      for (const comp of components) {
+        code += `import '${path.default.resolve(dir, comp.file)}';\n`
+      }
+
+      code += '\n'
+
+      // Generate wrapper exports
+      for (const comp of components) {
+        const eventsArr = JSON.stringify(comp.meta.events || [])
+        const modelsArr = JSON.stringify(comp.meta.models || [])
+        code += `export const ${comp.pascalName} = createWccWrapper('${comp.meta.tag}', { events: ${eventsArr}, models: ${modelsArr} });\n`
+      }
+
+      return code
+    }
+  }
+}

package/lib/codegen.js

@@ -970,6 +970,16 @@ export function generateComponent(parseResult, options = {}) {
     lines.push('');
   }
 
+  // Static __meta — component metadata for framework adapters (React wrappers, Angular events, etc.)
+  {
+    const metaProps = propDefs.map(p => `{ name: '${p.name}', default: ${p.default} }`).join(', ');
+    const metaEvents = emits.map(e => `'${e}'`).join(', ');
+    const metaModels = modelDefs.map(m => `'${m.name}'`).join(', ');
+    const metaSlots = slots.filter(s => s.name).map(s => `'${s.name}'`).join(', ');
+    lines.push(`  static __meta = { tag: '${tagName}', props: [${metaProps}], events: [${metaEvents}], models: [${metaModels}], slots: [${metaSlots}] };`);
+    lines.push('');
+  }
+
   // Constructor — reactive state only (no DOM manipulation per Custom Elements spec)
   lines.push('  constructor() {');
   lines.push('    super();');

package/package.json

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