@wix/zero-config-implementation 1.71.0 → 1.72.0

package/dist/index.d.ts

@@ -302,7 +302,10 @@ export declare interface CoupledComponentInfo {
     componentName: string;
     props: Record<string, CoupledProp>;
     elements: ExtractedElement[];
-    innerElementProps?: Map<string, Record<string, CoupledProp>>;
+    innerElementProps?: Map<string, {
+        elementPropsPath: string;
+        props: Record<string, CoupledProp>;
+    }>;
     propUsages: TrackingStores['propUsages'];
 }
 
@@ -318,13 +321,12 @@ export declare interface CoupledProp extends PropInfo {
  */
 export declare function createCssPropertiesExtractor(): ReactExtractor;
 
-/**
- * Event emitted for each DOM element created during render.
- */
 export declare interface CreateElementEvent {
-    tag: string;
+    type: unknown;
+    isDomElement: boolean;
+    tag?: string;
     props: Record<string, unknown>;
-    traceId: string;
+    traceId?: string;
     children: unknown[];
     store: ExtractorStore;
 }
@@ -337,13 +339,18 @@ export declare interface CreateElementListener {
  * Creates a prop tracker extractor that:
  * 1. Generates spy-instrumented mock props during beforeRender
  * 2. Detects spy markers in element props during onCreateElement
- * 3. propUsages tracking data to the store namespaced by 'prop-tracker'
+ * 3. Tracks runtime refElement markers from composite components to rendered DOM
+ * 4. Writes prop usage data to the store namespaced by 'prop-tracker'
  */
-export declare function createPropTrackerExtractor(): {
+export declare function createPropTrackerExtractor(options?: CreatePropTrackerExtractorOptions): {
     extractor: ReactExtractor;
     state: PropTrackerExtractorState;
 };
 
+declare interface CreatePropTrackerExtractorOptions {
+    eligiblePaths?: string[];
+}
+
 /**
  * `ErrorClass.subclass()`
  *

package/dist/index.js

@@ -1,4 +1,4 @@
-import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-C4cP1dwy.js";
+import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-CdHu4-o-.js";
 import "react";
 export {
   t as BaseError,

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.71.0",
+  "version": "1.72.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,8 @@
   },
   "dependencies": {
     "@wix/builder-services-wrapper": "^1.42.0",
-    "@wix/react-component-schema": "1.7.0"
+    "@wix/react-component-schema": "1.7.0",
+    "import-meta-resolve": "^4.2.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.2.0",
@@ -81,5 +82,5 @@
       ]
     }
   },
-  "falconPackageHash": "d6c8e03493b96fe9947b6b075e997e8ba6e5fea0f79a417f6e26c201"
+  "falconPackageHash": "2d1621ee1db1cc5a90b528fc0d45129b0534a3ba693b766403f23b2f"
 }

package/src/__fixtures__/cjs-ref-element-entry.cjs

@@ -0,0 +1 @@
+module.exports = require('./cjs-ref-element-target.cjs')

package/src/__fixtures__/cjs-ref-element-lazy-entry.cjs

@@ -0,0 +1,3 @@
+exports.loadTargetModule = function loadTargetModule() {
+  return require('./cjs-ref-element-target.cjs')
+}

package/src/__fixtures__/cjs-ref-element-order-entry.cjs

@@ -0,0 +1,8 @@
+globalThis.__zeroConfigRefElementEvaluationOrder = ['entry']
+
+const target = require('./cjs-ref-element-order-target.cjs')
+
+module.exports = {
+  evaluationOrder: globalThis.__zeroConfigRefElementEvaluationOrder,
+  target,
+}

package/src/__fixtures__/cjs-ref-element-order-target.cjs

@@ -0,0 +1,7 @@
+globalThis.__zeroConfigRefElementEvaluationOrder.push('target')
+
+function FixtureRefElementOrderTarget() {
+  return null
+}
+
+module.exports = FixtureRefElementOrderTarget

package/src/__fixtures__/cjs-ref-element-target.cjs

@@ -0,0 +1,5 @@
+function FixtureRefElementTarget() {
+  return null
+}
+
+module.exports = FixtureRefElementTarget

package/src/__fixtures__/esm-ref-element-entry.mjs

@@ -0,0 +1,3 @@
+import RefElementTarget from '@wix/zero-config-ref-element-fixtures/BareRefButton'
+
+export default RefElementTarget

package/src/component-renderer.ts

@@ -10,7 +10,7 @@
  * Four complementary layers ensure interception regardless of how JSX is compiled
  * AND regardless of how many React module instances are loaded in the process:
  *
- * 1. **Node.js ESM loader hook** — registered by `registerJsxLoaderHook()` in
+ * 1. **Node.js ESM loader hook** — registered by `ensureReactRuntimeLoader()` in
  *    `module-loader.ts` before any user bundle is imported. Redirects
  *    `react/jsx-runtime` and `react/jsx-dev-runtime` bare-specifier imports to
  *    an in-memory `data:` URL interceptor that reads mutable state from
@@ -75,7 +75,7 @@ import {
   getOriginals,
   setCreateElementInterceptor,
   setJsxInterceptors,
-} from './jsx-runtime-interceptor'
+} from './react-runtime-interceptor'
 
 export const TRACE_ATTR = 'data-trace-id'
 
@@ -104,18 +104,17 @@ function createInterceptor(
   store: ExtractorStore,
 ): ElementCreator {
   return (type, elementProps, ...rest) => {
-    if (!isDOMTag(type)) {
-      return original(type, elementProps, ...rest)
-    }
-
     const props = (elementProps ?? {}) as Record<string, unknown>
-    const traceId = getNextId()
+    const isDomElement = isDOMTag(type)
+    const traceId = isDomElement ? getNextId() : undefined
 
     // Children location differs: createElement uses rest params, jsx/jsxs uses props.children
     const children = rest.length > 0 ? rest : props.children ? [props.children] : []
 
     const event: CreateElementEvent = {
-      tag: type,
+      type,
+      isDomElement,
+      tag: isDomElement ? type : undefined,
       props: { ...props, children },
       traceId,
       children: children as unknown[],
@@ -124,6 +123,10 @@ function createInterceptor(
 
     listeners.forEach((listener) => listener.onCreateElement(event))
 
+    if (!isDomElement || !traceId) {
+      return original(type, elementProps, ...rest)
+    }
+
     const stampedProps = { ...props, [TRACE_ATTR]: traceId }
     return original(type, stampedProps, ...rest)
   }
@@ -248,7 +251,7 @@ export function renderWithExtractors(
   try {
     // @ts-expect-error Monkey-patch createElement for default-import callers
     React.createElement = interceptedCreateElement
-    // The data: URL react shim (registered by registerJsxLoaderHook) reads this state on every
+    // The data: URL react shim (registered by ensureReactRuntimeLoader) reads this state on every
     // createElement call, covering Rspack/webpack bundles that use `import * as React from 'react'`.
     setCreateElementInterceptor(interceptedCreateElement)
     // Use the interceptor API for jsx-runtime (includes jsxDEV for dev mode)

package/src/converters/to-editor-component.ts

@@ -20,7 +20,9 @@ import type {
   TrackingStores,
 } from '../information-extractors/react'
 import { getDefaultDisplayForTag, resolveDisplayValue } from '../information-extractors/react'
-import { findPreferredSemanticClass } from '../utils/css-class'
+import { buildRefElementManifestKey } from '../ref-elements/path-utils'
+import type { RefElementMatch } from '../ref-elements/types'
+import { findPreferredSemanticClass, normalizeClassNames } from '../utils/css-class'
 import { resolveLonghand } from './css-longhand-resolver'
 import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
 import { buildDataItem } from './data-item-builder'
@@ -102,12 +104,12 @@ function buildEditorElement(
 
 function getSemanticBlockName(element: ExtractedElement | undefined): string | undefined {
   if (!element?.attributes.class) return undefined
-  return findPreferredSemanticClass(element.attributes.class.split(' '))
+  return findPreferredSemanticClass(normalizeClassNames(element.attributes.class))
 }
 
 function buildSelector(rootElement?: ExtractedElement): string {
   if (rootElement?.attributes.class) {
-    const semanticClass = findPreferredSemanticClass(rootElement.attributes.class.split(' '))
+    const semanticClass = findPreferredSemanticClass(normalizeClassNames(rootElement.attributes.class))
     if (semanticClass) return `.${semanticClass}`
   }
   return rootElement?.tag ?? ''
@@ -141,16 +143,31 @@ function buildElements(
   customClassTriggers: CustomClassTrigger[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
+  parentElementPropsPath?: string,
 ): Record<string, ElementItem> {
   const result: Record<string, ElementItem> = {}
 
   for (const element of elements) {
-    const elementData = innerElementProps?.get(element.traceId)
-    const data = elementData && propUsages ? buildData(elementData, propUsages) : undefined
+    const innerEntry = innerElementProps?.get(element.traceId)
+    const refElementMatch = element.extractorData.get('ref-element') as RefElementMatch | undefined
+
+    if (refElementMatch) {
+      result[buildRefElementManifestKey(refElementMatch.elementPropsPath, parentElementPropsPath)] = {
+        elementType: ELEMENTS.ELEMENT_TYPE.refElement,
+        refElement: {
+          selector: refElementMatch.selector,
+          type: refElementMatch.refComponentType,
+        },
+      }
+      continue
+    }
+
+    const semanticClass = getSemanticBlockName(element)
+
+    const data = innerEntry && propUsages ? buildData(innerEntry.props, propUsages) : undefined
     const cssProps = buildCssProperties(element)
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
-    const semanticClass = getSemanticBlockName(element)
     // Inner-element custom states come from custom-class triggers only; prop
     // triggers (`ElementState<>`) are component-level and attach to the root.
     const states = mergeStates(
@@ -180,6 +197,7 @@ function buildElements(
                 customClassTriggers,
                 innerElementProps,
                 propUsages,
+                innerEntry?.elementPropsPath ?? parentElementPropsPath,
               )
             : undefined,
       },

package/src/index.ts

@@ -1,16 +1,19 @@
 import { WixServicesWrapper } from '@wix/builder-services-wrapper'
 import type { EditorReactComponent } from '@wix/react-component-schema'
-import { Result, type ResultAsync, errAsync, okAsync } from 'neverthrow'
+import { Result, ResultAsync, errAsync, okAsync } from 'neverthrow'
 import React, { type ComponentType } from 'react'
 
 import { toEditorReactComponent } from './converters'
-import { IoError, type NotFoundError, ParseError } from './errors'
+import { BaseError, IoError, type NotFoundError, ParseError } from './errors'
 import type { ExtractionError } from './extraction-types'
 import type { RunExtractorsOptions } from './information-extractors/react'
 import { extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
+import type { ComponentInfo } from './information-extractors/ts/types'
 import { processComponent } from './manifest-pipeline'
-import { findComponent, findDefaultComponent, loadModule } from './module-loader'
+import { findComponent, findDefaultComponent, loadModuleForExtraction } from './module-loader'
 import type { LoadModuleFailure } from './module-loader'
+import { buildRefElementContext } from './ref-elements/context'
+import type { RefElementContext } from './ref-elements/types'
 import { compileTsFile } from './ts-compiler'
 
 const defaultWrapper = (Component: ComponentType<unknown>): ComponentType<unknown> => {
@@ -65,7 +68,6 @@ export function extractComponentManifestResult(
     ...options,
     wrapper: options?.wrapper ?? defaultWrapper,
   }
-
   // Step 1: Compile TypeScript (fatal)
   return compileTsFile(componentPath)
     .andThen((program) => {
@@ -89,66 +91,131 @@ export function extractComponentManifestResult(
     .andThen(({ program, componentInfo }) => {
       const { componentName } = componentInfo
 
-      // Step 3: Load the compiled package module (non-fatal) — done after TS extraction
-      // so componentName is known when reporting failures
-      return loadModule(compiledEntryPath)
-        .map((moduleExports) => ({
-          loadComponent: (name: string) => findComponent(moduleExports, name) ?? findDefaultComponent(moduleExports),
-          failure: null as LoadModuleFailure | null,
-        }))
-        .orElse((failure) => okAsync({ loadComponent: () => null as ComponentType<unknown> | null, failure }))
-        .andThen(({ loadComponent, failure }) => {
-          if (failure) {
-            if (failure.esmError) {
+      return ResultAsync.fromPromise(
+        buildRefElementContext(program, componentPath, componentInfo, compiledEntryPath),
+        (thrown) =>
+          new ParseError(
+            `Failed to build the ref-element context for "${componentPath}": ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+            { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'extract' } },
+          ),
+      ).andThen((refElementContext) =>
+        // Step 3: Load the compiled package module (non-fatal) — done after TS extraction
+        // so componentName is known when reporting failures
+        loadModuleForExtraction(compiledEntryPath, refElementContext.runtimeModules)
+          .map(({ cleanup, moduleExports }) => ({
+            loadComponent: (name: string) => findComponent(moduleExports, name) ?? findDefaultComponent(moduleExports),
+            failure: null as LoadModuleFailure | null,
+            cleanup,
+          }))
+          .orElse((failure) =>
+            okAsync({
+              loadComponent: () => null as ComponentType<unknown> | null,
+              cleanup: async () => {},
+              failure,
+            }),
+          )
+          .andThen(({ cleanup, failure, loadComponent }) => {
+            if (failure) {
+              if (failure.esmError) {
+                report({
+                  componentName,
+                  phase: 'loader',
+                  error: new IoError('ESM import failed', { cause: failure.esmError, props: { phase: 'loader' } }),
+                })
+              }
               report({
                 componentName,
                 phase: 'loader',
-                error: new IoError('ESM import failed', { cause: failure.esmError, props: { phase: 'loader' } }),
+                error: new IoError('CJS require failed', { cause: failure.cjsError, props: { phase: 'loader' } }),
               })
             }
-            report({
-              componentName,
-              phase: 'loader',
-              error: new IoError('CJS require failed', { cause: failure.cjsError, props: { phase: 'loader' } }),
-            })
-          }
 
-          // Step 4: Extract CSS imports (non-fatal)
-          let cssImportPaths: string[] = []
-          const cssResult = Result.fromThrowable(extractCssImports, (thrown) => thrown)(program)
-          if (cssResult.isOk()) {
-            cssImportPaths = cssResult.value
-          } else {
-            const thrown = cssResult.error
-            report({
-              componentName,
-              phase: 'css',
-              error: new ParseError(
-                `Failed to extract CSS imports: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
-                { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'css' } },
-              ),
-            })
-          }
+            // Step 4: Extract CSS imports (non-fatal)
+            let cssImportPaths: string[] = []
+            const cssResult = Result.fromThrowable(extractCssImports, (thrown) => thrown)(program)
+            if (cssResult.isOk()) {
+              cssImportPaths = cssResult.value
+            } else {
+              const thrown = cssResult.error
+              report({
+                componentName,
+                phase: 'css',
+                error: new ParseError(
+                  `Failed to extract CSS imports: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+                  { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'css' } },
+                ),
+              })
+            }
 
-          // Step 5: Process the default-exported component (non-fatal unless render fails after load)
-          const processResult = processComponent(
-            componentInfo,
-            loadComponent,
-            cssImportPaths,
-            !!failure,
-            report,
-            optionsWithDefaults,
-            compiledEntryPath,
-          )
-          if (!processResult.ok) {
-            return errAsync(processResult.error)
-          }
-          const component = toEditorReactComponent(processResult.component)
-          return okAsync({ component, errors })
-        })
+            // Step 5: Process the default-exported component (non-fatal unless render fails after load)
+            return ResultAsync.fromPromise(
+              processComponentWithCleanup(
+                componentInfo,
+                loadComponent,
+                cssImportPaths,
+                !!failure,
+                report,
+                optionsWithDefaults,
+                compiledEntryPath,
+                refElementContext,
+                cleanup,
+                errors,
+              ),
+              normalizeComponentExtractionCleanupFailure,
+            )
+          }),
+      )
     })
 }
 
+function normalizeComponentExtractionCleanupFailure(thrown: unknown): InstanceType<typeof BaseError> {
+  const normalizedError = BaseError.normalize(thrown)
+  if (normalizedError instanceof BaseError) {
+    return normalizedError
+  }
+
+  return new IoError('Unexpected failure during component extraction cleanup', {
+    cause: normalizedError,
+    props: { phase: 'loader' },
+  })
+}
+
+async function processComponentWithCleanup(
+  componentInfo: ComponentInfo,
+  loadComponent: (name: string) => ComponentType<unknown> | null,
+  cssImportPaths: string[],
+  didModuleLoadFail: boolean,
+  report: (error: ExtractionError) => void,
+  options: ExtractComponentManifestOptions,
+  compiledEntryPath: string,
+  refElementContext: RefElementContext,
+  cleanup: () => Promise<void>,
+  errors: ExtractionError[],
+): Promise<ManifestResult> {
+  try {
+    const processResult = processComponent(
+      componentInfo,
+      loadComponent,
+      cssImportPaths,
+      didModuleLoadFail,
+      report,
+      options,
+      compiledEntryPath,
+      refElementContext.eligiblePaths,
+    )
+    if (!processResult.ok) {
+      throw processResult.error
+    }
+
+    return {
+      component: toEditorReactComponent(processResult.component),
+      errors,
+    }
+  } finally {
+    await cleanup()
+  }
+}
+
 export async function extractComponentManifest(
   componentPath: string,
   compiledEntryPath: string,

package/src/information-extractors/react/extractors/core/tree-builder.ts

@@ -8,7 +8,7 @@
 import { camelCase } from 'case-anything'
 import { type DefaultTreeAdapterMap, parseFragment } from 'parse5'
 import { TRACE_ATTR } from '../../../../component-renderer'
-import { findPreferredSemanticClass } from '../../../../utils/css-class'
+import { findPreferredSemanticClass, normalizeClassNames } from '../../../../utils/css-class'
 import { PRESETS_WRAPPER_CLASS_NAME } from '../../utils/mock-generator'
 import type { CssPropertiesData } from '../css-properties'
 import { addTextProperties } from '../css-properties'
@@ -174,7 +174,7 @@ function getElementNamePart(element: Element, getElementById: (id: string) => El
 
   const classAttr = getAttribute(element, 'class')
   if (classAttr) {
-    const semanticClass = findPreferredSemanticClass(classAttr.split(' '))
+    const semanticClass = findPreferredSemanticClass(normalizeClassNames(classAttr))
     if (semanticClass) elementName = semanticClass
   }
 
@@ -197,7 +197,7 @@ function getElementNamePart(element: Element, getElementById: (id: string) => El
 function hasClassNameCriteria(element: Element, extractorData: Map<string, unknown>): boolean {
   const classAttr = getAttribute(element, 'class')
   if (classAttr) {
-    const semanticClass = findPreferredSemanticClass(classAttr.split(' '))
+    const semanticClass = findPreferredSemanticClass(normalizeClassNames(classAttr))
     if (semanticClass) return true
   }
 

package/src/information-extractors/react/extractors/core/types.ts

@@ -17,13 +17,12 @@ export interface RenderContext {
   store: ExtractorStore
 }
 
-/**
- * Event emitted for each DOM element created during render.
- */
 export interface CreateElementEvent {
-  tag: string
+  type: unknown
+  isDomElement: boolean
+  tag?: string
   props: Record<string, unknown>
-  traceId: string
+  traceId?: string
   children: unknown[]
   store: ExtractorStore
 }

package/src/information-extractors/react/extractors/css-properties.ts

@@ -329,6 +329,8 @@ export function createCssPropertiesExtractor(): ReactExtractor {
     name: 'css-properties',
 
     onCreateElement(event: CreateElementEvent): void {
+      if (!event.isDomElement || !event.tag || !event.traceId) return
+
       const { tag, props, traceId, store } = event
       const role = props.role as string | undefined