@sprlab/wccompiler 0.10.6 → 0.10.8

package/adapters/react.js

@@ -4,25 +4,24 @@
  *
  * @module @sprlab/wccompiler/adapters/react
  *
- * IMPORTANT: Import hooks from THIS file (not from integrations/react).
- * The integrations/react file is for vite.config.js only (contains Babel).
+ * NOTE: These hooks are optional utilities for React 18 or edge cases.
+ * With React 19 + wccReactPlugin, WCC components work natively:
  *
- * Usage:
- *   import { useWccEvent, useWccModel, createWccWrapper } from '@sprlab/wccompiler/adapters/react'
+ *   <WccCounter count={state} oncountchanged={(e) => setState(e.detail)} />
+ *   <WccCard>
+ *     <WccCard.Header><strong>Title</strong></WccCard.Header>
+ *   </WccCard>
  *
- *   // Option A: Low-level hooks (full control)
- *   const ref = useWccEvent('change', (e) => console.log(e.detail))
- *   <wcc-counter ref={ref}></wcc-counter>
+ * The plugin handles PascalCase → kebab-case, compound components, and
+ * scoped slots at build time. No runtime wrappers needed.
  *
- *   // Option B: Wrapper components (idiomatic React DX)
- *   const WccCounter = createWccWrapper('wcc-counter', {
- *     events: ['change'],
- *     models: ['count']
- *   })
- *   <WccCounter onChange={handler} count={count} onCountChanged={setCount} />
+ * These hooks are for cases where you need manual event bridging
+ * (e.g., React 18, non-Vite builds, or dynamic event names):
+ *
+ *   import { useWccEvent, useWccModel } from '@sprlab/wccompiler/adapters/react'
  */
 
-import React, { useRef, useEffect } from 'react'
+import { useRef, useEffect } from 'react'
 
 /**
  * Hook that attaches a CustomEvent listener to a DOM element via ref.
@@ -35,6 +34,16 @@ import React, { useRef, useEffect } from 'react'
  * @param {string | ((event: CustomEvent) => void)} eventNameOrHandler
  * @param {((event: CustomEvent) => void)} [handler]
  * @returns {import('react').RefObject<HTMLElement> | void}
+ *
+ * @example
+ * // Form 1: Let the hook create the ref
+ * const ref = useWccEvent('count-changed', (e) => setCount(e.detail))
+ * <wcc-counter ref={ref}></wcc-counter>
+ *
+ * // Form 2: Pass an existing ref
+ * const myRef = useRef(null)
+ * useWccEvent(myRef, 'count-changed', (e) => setCount(e.detail))
+ * <wcc-counter ref={myRef}></wcc-counter>
  */
 export function useWccEvent(refOrEventName, eventNameOrHandler, handler) {
   const isRefForm = typeof refOrEventName !== 'string'
@@ -103,286 +112,3 @@ export function useWccModel(propName, value, setValue, existingRef) {
 
   return elementRef
 }
-
-
-/**
- * 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`, `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)
- * - Ref forwarding: supports React refs via forwardRef
- *
- * @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' → onCountChange prop (React convention)
- * @param {string[]} [config.models] - Model prop names for two-way binding
- *   Each model 'name' creates: `name` prop (sets attribute) + `onNameChange` event
- * @param {string[]} [config.slots] - Named slot names for compound sub-components
- *   Each slot 'name' creates a `.Name` sub-component that renders `<div slot="name">`
- * @returns {import('react').ForwardRefExoticComponent} A React component with compound sub-components
- *
- * @example
- * const WccCounter = createWccWrapper('wcc-counter', {
- *   events: ['change'],
- *   models: ['count'],
- *   slots: ['header', 'footer']
- * })
- *
- * function App() {
- *   const [count, setCount] = useState(0)
- *   return (
- *     <WccCounter
- *       count={count}
- *       onCountChange={(value) => setCount(value)}
- *       onChange={(value) => console.log('changed', value)}
- *       label="Clicks"
- *     >
- *       <WccCounter.Header><strong>Title</strong></WccCounter.Header>
- *       <p>Body content</p>
- *       <WccCounter.Footer>Footer text</WccCounter.Footer>
- *     </WccCounter>
- *   )
- * }
- */
-export function createWccWrapper(tagName, config = {}) {
-  const { events = [], models = [], slots = [] } = config
-
-  // Build a set of event prop names for quick lookup
-  // 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 = toReactEventProp(eventName)
-    eventPropMap.set(propName, eventName)
-  }
-
-  // Model events: 'count' → 'count-changed' → 'onCountChange'
-  const modelEventMap = new Map()
-  for (const modelName of models) {
-    const eventName = `${modelName}-changed`
-    const propName = toReactEventProp(eventName)
-    eventPropMap.set(propName, eventName)
-    modelEventMap.set(modelName, eventName)
-  }
-
-  // Reserved prop names that should not be passed as attributes
-  const SKIP_PROPS = new Set(['children', 'key', 'ref', 'style', 'className', 'dangerouslySetInnerHTML'])
-
-  const WccWrapper = React.forwardRef(function WccWrapper(props, externalRef) {
-    const internalRef = useRef(null)
-    const ref = externalRef || internalRef
-
-    // Store event handlers in a ref to avoid re-subscribing on every render
-    const handlersRef = useRef({})
-
-    // Collect event handlers and regular props
-    const regularProps = {}
-    const eventHandlers = {}
-
-    for (const [key, value] of Object.entries(props)) {
-      if (SKIP_PROPS.has(key)) continue
-
-      if (eventPropMap.has(key)) {
-        eventHandlers[eventPropMap.get(key)] = value
-      } else if (key.startsWith('on') && key.length > 2 && key[2] >= 'A' && key[2] <= 'Z') {
-        // Generic React event handler pattern: onClick, onFocus, etc.
-        // Convert onSomething → 'something' (lowercase first char)
-        const nativeEvent = key[2].toLowerCase() + key.slice(3)
-        eventHandlers[nativeEvent] = value
-      } else {
-        regularProps[key] = value
-      }
-    }
-
-    // Update handlers ref
-    handlersRef.current = eventHandlers
-
-    // Subscribe to custom events
-    useEffect(() => {
-      const el = typeof ref === 'function' ? null : ref?.current
-      if (!el) return
-
-      const listeners = []
-      const allEvents = new Set([...eventPropMap.values(), ...Object.keys(eventHandlers)])
-
-      for (const eventName of allEvents) {
-        const listener = (e) => {
-          const handler = handlersRef.current[eventName]
-          if (handler) handler(e instanceof CustomEvent ? e.detail : e)
-        }
-        el.addEventListener(eventName, listener)
-        listeners.push([eventName, listener])
-      }
-
-      return () => {
-        for (const [name, listener] of listeners) {
-          el.removeEventListener(name, listener)
-        }
-      }
-    }, []) // eslint-disable-line react-hooks/exhaustive-deps
-
-    // Sync regular props as attributes
-    useEffect(() => {
-      const el = typeof ref === 'function' ? null : ref?.current
-      if (!el) return
-
-      for (const [key, value] of Object.entries(regularProps)) {
-        if (value == null || value === false) {
-          el.removeAttribute(key)
-        } else if (value === true) {
-          el.setAttribute(key, '')
-        } else {
-          el.setAttribute(key, String(value))
-        }
-      }
-    })
-
-    // Build the element props for React's createElement
-    const elementProps = { ref }
-    if (props.style) elementProps.style = props.style
-    if (props.className) elementProps.className = props.className
-
-    return React.createElement(tagName, elementProps, props.children)
-  })
-
-  WccWrapper.displayName = tagName.split('-').map(s => s[0].toUpperCase() + s.slice(1)).join('')
-
-  // Compound components: generate .SlotName sub-components for each named slot
-  // This enables the pattern: <WccLayout.Header>content</WccLayout.Header>
-  // which renders as: <div slot="header">content</div>
-  for (const slotName of slots) {
-    if (!slotName) continue // skip default slot
-    const pascalSlot = slotName[0].toUpperCase() + slotName.slice(1)
-    const SlotComponent = function WccSlot({ children, ...rest }) {
-      const slotProps = { slot: slotName, style: { display: 'contents' } }
-      // Pass through any extra props as attributes on the wrapper div
-      for (const [key, value] of Object.entries(rest)) {
-        slotProps[key] = value
-      }
-      return React.createElement('div', slotProps, children)
-    }
-    SlotComponent.displayName = `${WccWrapper.displayName}.${pascalSlot}`
-    WccWrapper[pascalSlot] = SlotComponent
-  }
-
-  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 || [],
-    slots: meta.slots || [],
-  })
-}
-
-/**
- * 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} onCountChange={setCount} />
- * <WccCard>
- *   <WccCard.Header><strong>Title</strong></WccCard.Header>
- *   <p>Body</p>
- *   <WccCard.Footer>Footer</WccCard.Footer>
- * </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

@@ -643,9 +643,102 @@ export function wccReactPlugin(options = {}) {
           const openingElement = path.node.openingElement
           const nameNode = openingElement.name
 
+          // ── Compound component transform ──
+          // <WccCard.Header>children</WccCard.Header> → <div slot="header" style={{display:'contents'}}>children</div>
+          // <WccCard.Stats>{(likes) => <span>{likes}</span>}</WccCard.Stats> → scoped slot div
+          if (nameNode.type === 'JSXMemberExpression') {
+            const objectName = nameNode.object?.name // e.g., 'WccCard'
+            const propName = nameNode.property?.name // e.g., 'Header'
+            if (!objectName || !propName) return
+
+            // Convert PascalCase object to kebab-case and check if it's a custom element
+            const kebab = objectName.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')
+            if (!kebab.includes('-')) return
+            if (prefix && !kebab.startsWith(prefix)) return
+
+            // Derive slot name: Header → header, FooterNav → footerNav (lcfirst)
+            const slotName = propName[0].toLowerCase() + propName.slice(1)
+
+            // Check if children is a function (scoped slot / render prop pattern)
+            const children = path.node.children
+            const isScopedSlot = children.length === 1
+              && children[0].type === 'JSXExpressionContainer'
+              && children[0].expression.type === 'ArrowFunctionExpression'
+
+            if (isScopedSlot) {
+              // Scoped slot: <WccCard.Stats>{(likes) => <span>{likes}</span>}</WccCard.Stats>
+              const arrowFn = children[0].expression
+              const params = (arrowFn.params || []).map(p => p.name || '')
+              const body = arrowFn.body
+
+              // Warn on unsupported expressions
+              const renderWarnings = []
+              serializeJsxToHtml(body, params, renderWarnings)
+              if (renderWarnings.length > 0) {
+                pluginCtx.warn(`[wcc-react] ${id} — ${objectName}.${propName}: ${renderWarnings[0]}`)
+                return
+              }
+
+              // Replace with scoped slot element
+              const scopedEl = generateScopedSlotElement(slotName, params, body)
+              path.replaceWith(scopedEl)
+              transformed = true
+            } else {
+              // Named slot: <WccCard.Header><strong>Title</strong></WccCard.Header>
+              // → <div slot="header" style={{display:'contents'}}>children</div>
+              const slotAttr = {
+                type: 'JSXAttribute',
+                name: { type: 'JSXIdentifier', name: 'slot' },
+                value: { type: 'StringLiteral', value: slotName }
+              }
+              const styleAttr = {
+                type: 'JSXAttribute',
+                name: { type: 'JSXIdentifier', name: 'style' },
+                value: {
+                  type: 'JSXExpressionContainer',
+                  expression: {
+                    type: 'ObjectExpression',
+                    properties: [{
+                      type: 'ObjectProperty',
+                      key: { type: 'Identifier', name: 'display' },
+                      value: { type: 'StringLiteral', value: 'contents' },
+                      computed: false,
+                      shorthand: false
+                    }]
+                  }
+                }
+              }
+
+              openingElement.name = { type: 'JSXIdentifier', name: 'div' }
+              openingElement.attributes = [...openingElement.attributes, slotAttr, styleAttr]
+              if (path.node.closingElement) {
+                path.node.closingElement.name = { type: 'JSXIdentifier', name: 'div' }
+              }
+              transformed = true
+            }
+            return
+          }
+
+          // ── PascalCase custom element transform ──
+          // <WccCard> → <wcc-card> (only if it maps to a hyphenated tag)
+          if (nameNode.type === 'JSXIdentifier' && /^[A-Z]/.test(nameNode.name)) {
+            const kebab = nameNode.name.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')
+            if (!kebab.includes('-')) return
+            if (prefix && !kebab.startsWith(prefix)) return
+
+            // Rewrite tag name to kebab-case
+            openingElement.name = { type: 'JSXIdentifier', name: kebab }
+            if (path.node.closingElement) {
+              path.node.closingElement.name = { type: 'JSXIdentifier', name: kebab }
+            }
+            transformed = true
+            // Fall through to process props on this element
+          }
+
           // Only process elements with hyphenated tag names (custom elements)
-          if (nameNode.type !== 'JSXIdentifier') return
-          const tagName = nameNode.name
+          const currentName = openingElement.name
+          if (currentName.type !== 'JSXIdentifier') return
+          const tagName = currentName.name
           if (!tagName.includes('-')) return
 
           // Apply prefix filtering if set
@@ -748,15 +841,15 @@ 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.
+ * Vite plugin that generates a virtual module with component stubs for
+ * PascalCase imports. These stubs satisfy the linter/IDE (component is "defined")
+ * and the wccReactPlugin transforms them to native custom elements at build time.
  *
- * This enables the ideal import experience:
+ * This enables the standard React import pattern:
  *   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.
+ * The stubs are zero-runtime — they're just tag name strings with slot name
+ * properties. The wccReactPlugin handles the actual JSX transformation.
  *
  * @param {Object} [options]
  * @param {string} [options.moduleId='@wcc/react'] - Virtual module ID for imports
@@ -769,18 +862,25 @@ export function wccReactPlugin(options = {}) {
  * import { wccReactPlugin, wccReactComponents } from '@sprlab/wccompiler/integrations/react'
  * export default {
  *   plugins: [
+ *     wccReactComponents({ componentsDir: './src/wcc' }),
  *     wccReactPlugin(),
- *     wccReactComponents({ componentsDir: './src/wcc' })
+ *     react()
  *   ]
  * }
  * ```
  *
  * @example Component.jsx
  * ```jsx
- * import { WccCounter, WccCard } from '@wcc/react'
+ * import { WccCard, WccList } from '@wcc/react'
  *
- * <WccCounter count={count} onCountChange={setCount} />
- * <WccCard><div slot="header">Title</div></WccCard>
+ * <WccCard>
+ *   <WccCard.Header><strong>Title</strong></WccCard.Header>
+ *   <p>Body</p>
+ * </WccCard>
+ *
+ * <WccList>
+ *   <WccList.Item>{(item) => <li>{item}</li>}</WccList.Item>
+ * </WccList>
  * ```
  */
 export function wccReactComponents(options = {}) {
@@ -820,7 +920,6 @@ export function wccReactComponents(options = {}) {
         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":')
@@ -841,21 +940,28 @@ export function wccReactComponents(options = {}) {
         return 'export {}'
       }
 
-      // Generate the virtual module code
-      let code = `import { createWccWrapper } from '@sprlab/wccompiler/adapters/react';\n`
+      // Generate lightweight stubs (zero runtime)
+      // The wccReactPlugin transforms these at build time
+      let code = '// Auto-generated WCC component stubs (transformed by wccReactPlugin at build time)\n'
 
-      // Import each component file to ensure registration
+      // Import each component file to ensure custom element registration
       for (const comp of components) {
         code += `import '${path.default.resolve(dir, comp.file)}';\n`
       }
 
       code += '\n'
 
-      // Generate wrapper exports
+      // Generate stub exports with compound slot properties
+      // Use Object.assign to create an object that holds the tag name and slot sub-properties
       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`
+        const slots = comp.meta.slots || []
+        code += `export const ${comp.pascalName} = Object.assign(() => '${comp.meta.tag}', { __tag: '${comp.meta.tag}'`
+        for (const slot of slots) {
+          if (!slot) continue
+          const pascalSlot = slot[0].toUpperCase() + slot.slice(1)
+          code += `, ${pascalSlot}: '${slot}'`
+        }
+        code += ` });\n`
       }
 
       return code

package/package.json

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