@wix/zero-config-implementation 1.71.0 → 1.72.0

package/src/information-extractors/react/extractors/prop-tracker.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from 'vitest'
+import { createRefElementMarker } from '../../../ref-elements/path-utils'
+import type { RefElementMatch } from '../../../ref-elements/types'
+import { ExtractorStore } from './core/store'
+import { createPropTrackerExtractor } from './prop-tracker'
+
+function markRefElementComponent(runtimeComponent: (...args: unknown[]) => unknown, refComponentType: string): void {
+  Object.defineProperty(
+    runtimeComponent as unknown as Record<PropertyKey, unknown>,
+    Symbol.for('zero-config:ref-element-component-type'),
+    {
+      value: refComponentType,
+    },
+  )
+}
+
+describe('createPropTrackerExtractor', () => {
+  it('associates a ref-capable composite component with the rendered DOM trace id', () => {
+    const store = new ExtractorStore()
+    const runtimeRefComponent = function LocalButton(): null {
+      return null
+    }
+    markRefElementComponent(runtimeRefComponent, 'myPkg.LocalButton')
+    const { extractor } = createPropTrackerExtractor({
+      eligiblePaths: ['actionButton'],
+    })
+    const taggedProps = { id: createRefElementMarker('actionButton') }
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: taggedProps,
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-1',
+      props: {
+        ...taggedProps,
+        className: 'action-button action-button--accent',
+      },
+      children: [],
+      store,
+    })
+
+    expect(store.get<RefElementMatch>('trace-1', 'ref-element')).toEqual({
+      elementPropsPath: 'actionButton',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.action-button',
+    })
+  })
+
+  it('uses the marker from the final id value that reaches the rendered element', () => {
+    const store = new ExtractorStore()
+    const runtimeRefComponent = function LocalButton(): null {
+      return null
+    }
+    markRefElementComponent(runtimeRefComponent, 'myPkg.LocalButton')
+    const { extractor } = createPropTrackerExtractor({
+      eligiblePaths: ['primaryAction', 'secondaryAction'],
+    })
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: { id: createRefElementMarker('secondaryAction') },
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-2',
+      props: {
+        id: createRefElementMarker('secondaryAction'),
+        className: 'action-button',
+      },
+      children: [],
+      store,
+    })
+
+    expect(store.get<RefElementMatch>('trace-2', 'ref-element')).toEqual({
+      elementPropsPath: 'secondaryAction',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.action-button',
+    })
+  })
+
+  it('waits for the first semantic DOM target before consuming a pending ref element', () => {
+    const store = new ExtractorStore()
+    const runtimeRefComponent = function LocalButton(): null {
+      return null
+    }
+    markRefElementComponent(runtimeRefComponent, 'myPkg.LocalButton')
+    const { extractor } = createPropTrackerExtractor({
+      eligiblePaths: ['actionButton'],
+    })
+    const taggedProps = { id: createRefElementMarker('actionButton') }
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: taggedProps,
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'div',
+      isDomElement: true,
+      tag: 'div',
+      traceId: 'trace-wrapper',
+      props: {
+        ...taggedProps,
+        className: '_hashWrapper_123abc',
+      },
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-button',
+      props: {
+        ...taggedProps,
+        className: 'action-button',
+      },
+      children: [],
+      store,
+    })
+
+    expect(store.get<RefElementMatch>('trace-wrapper', 'ref-element')).toBeUndefined()
+    expect(store.get<RefElementMatch>('trace-button', 'ref-element')).toEqual({
+      elementPropsPath: 'actionButton',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.action-button',
+    })
+  })
+
+  it('tracks repeated instances of the same ref-element marker in render order', () => {
+    const store = new ExtractorStore()
+    const runtimeRefComponent = function LocalButton(): null {
+      return null
+    }
+    markRefElementComponent(runtimeRefComponent, 'myPkg.LocalButton')
+    const { extractor } = createPropTrackerExtractor({
+      eligiblePaths: ['actionButton'],
+    })
+    const taggedProps = { id: createRefElementMarker('actionButton') }
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: taggedProps,
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: taggedProps,
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-first',
+      props: {
+        ...taggedProps,
+        className: 'action-button',
+      },
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-second',
+      props: {
+        ...taggedProps,
+        className: 'action-button action-button--secondary',
+      },
+      children: [],
+      store,
+    })
+
+    expect(store.get<RefElementMatch>('trace-first', 'ref-element')).toEqual({
+      elementPropsPath: 'actionButton',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.action-button',
+    })
+    expect(store.get<RefElementMatch>('trace-second', 'ref-element')).toEqual({
+      elementPropsPath: 'actionButton',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.action-button',
+    })
+  })
+
+  it('preserves nested elementProps paths in ref-element runtime metadata', () => {
+    const store = new ExtractorStore()
+    const runtimeRefComponent = function LocalButton(): null {
+      return null
+    }
+    markRefElementComponent(runtimeRefComponent, 'myPkg.LocalButton')
+    const { extractor } = createPropTrackerExtractor({
+      eligiblePaths: ['card.elementProps.cta'],
+    })
+    const taggedProps = { id: createRefElementMarker('card.elementProps.cta') }
+
+    extractor.onCreateElement?.({
+      type: runtimeRefComponent,
+      isDomElement: false,
+      props: taggedProps,
+      children: [],
+      store,
+    })
+
+    extractor.onCreateElement?.({
+      type: 'button',
+      isDomElement: true,
+      tag: 'button',
+      traceId: 'trace-nested',
+      props: {
+        ...taggedProps,
+        className: 'card-cta',
+      },
+      children: [],
+      store,
+    })
+
+    expect(store.get<RefElementMatch>('trace-nested', 'ref-element')).toEqual({
+      elementPropsPath: 'card.elementProps.cta',
+      refComponentType: 'myPkg.LocalButton',
+      selector: '.card-cta',
+    })
+  })
+})

package/src/information-extractors/react/extractors/prop-tracker.ts

@@ -7,6 +7,10 @@
 
 import type { HTMLAttributes } from 'react'
 import { TRACE_ATTR } from '../../../component-renderer'
+import { readRefElementComponentType } from '../../../ref-elements/component-tag'
+import { parseRefElementMarker } from '../../../ref-elements/path-utils'
+import type { RefElementMatch } from '../../../ref-elements/types'
+import { findPreferredSemanticClass, normalizeClassNames } from '../../../utils/css-class'
 import type { PropSpyMeta, TrackingStores } from '../types'
 import { type PropSpyRegistrar, generateMockProps, resetMockCounter } from '../utils/mock-generator'
 import type { CreateElementEvent, ReactExtractor, RenderContext } from './core/types'
@@ -28,6 +32,15 @@ export interface PropTrackerExtractorState {
   stores: TrackingStores
 }
 
+interface CreatePropTrackerExtractorOptions {
+  eligiblePaths?: string[]
+}
+
+interface PendingRefElement {
+  elementPropsPath: string
+  refComponentType: string
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory
 // ─────────────────────────────────────────────────────────────────────────────
@@ -36,9 +49,10 @@ export interface PropTrackerExtractorState {
  * 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 function createPropTrackerExtractor(): {
+export function createPropTrackerExtractor(options?: CreatePropTrackerExtractorOptions): {
   extractor: ReactExtractor
   state: PropTrackerExtractorState
 } {
@@ -48,6 +62,8 @@ export function createPropTrackerExtractor(): {
   const stores: TrackingStores = {
     propUsages: new Map(),
   }
+  const eligiblePaths = new Set(options?.eligiblePaths ?? [])
+  const pendingRefElementsByPath = new Map<string, PendingRefElement[]>()
 
   const registrar: PropSpyRegistrar = {
     registerString(path, propName, value) {
@@ -84,16 +100,14 @@ export function createPropTrackerExtractor(): {
       return meta ? [{ propName: meta.propName, path: meta.path, embedded: false }] : []
     }
     if (value && typeof value === 'object') {
-      // Prevent infinite recursion from circular references
       if (seen.has(value as object)) {
         return []
       }
       seen.add(value as object)
-      // Skip React elements (have $$typeof symbol) - they have circular refs
       if ('$$typeof' in value) {
         return []
       }
-      return Object.values(value).flatMap((v) => extractSpies(v, seen))
+      return Object.values(value).flatMap((nestedValue) => extractSpies(nestedValue, seen))
     }
     return []
   }
@@ -103,10 +117,19 @@ export function createPropTrackerExtractor(): {
 
     onBeforeRender(context: RenderContext): void {
       resetMockCounter()
-      context.props = generateMockProps(context.componentInfo, registrar)
+      context.props = generateMockProps(context.componentInfo, registrar, {
+        eligibleRefElementPaths: eligiblePaths,
+      })
     },
 
     onCreateElement(event: CreateElementEvent): void {
+      if (!event.isDomElement) {
+        queuePendingRefElement(event.props.id, readRefElementComponentType(event.type))
+        return
+      }
+
+      if (!event.tag || !event.traceId) return
+
       const { tag, props, traceId, store } = event
       const htmlProps = props as HTMLAttributes<unknown>
 
@@ -132,25 +155,24 @@ export function createPropTrackerExtractor(): {
           const entry = stores.propUsages.get(path)!
 
           entry.elements.set(traceId, { tag, elementId: traceId })
-          const isConcat = spies.length > 1 || spy.embedded
-          entry.attributes.set(`${traceId}:${key}`, { attr: key, concatenated: isConcat })
+          const isConcatenatedAttribute = spies.length > 1 || spy.embedded
+          entry.attributes.set(`${traceId}:${key}`, { attr: key, concatenated: isConcatenatedAttribute })
 
-          // Track concatenated attributes
-          if (isConcat) {
+          if (isConcatenatedAttribute) {
             concatenatedAttrs.set(key, spy.propName)
           }
         })
       })
 
-      // Write to store
-      const data: PropTrackerData = {
+      store.set(traceId, 'prop-tracker', {
         tag,
         role: htmlProps.role,
         boundProps: [...boundProps],
         concatenatedAttrs,
         eventHandlers,
-      }
-      store.set(traceId, 'prop-tracker', data)
+      } satisfies PropTrackerData)
+
+      attachMatchedRefElement(traceId, props, store)
     },
   }
 
@@ -158,4 +180,46 @@ export function createPropTrackerExtractor(): {
     extractor,
     state: { stores },
   }
+
+  function queuePendingRefElement(idValue: unknown, refComponentType: string | undefined): void {
+    const elementPropsPath = parseRefElementMarker(idValue)
+    if (!elementPropsPath || !refComponentType) return
+    if (eligiblePaths.size > 0 && !eligiblePaths.has(elementPropsPath)) return
+
+    const pendingRefElements = pendingRefElementsByPath.get(elementPropsPath) ?? []
+    pendingRefElements.push({ elementPropsPath, refComponentType })
+    pendingRefElementsByPath.set(elementPropsPath, pendingRefElements)
+  }
+
+  function attachMatchedRefElement(
+    traceId: string,
+    props: Record<string, unknown>,
+    store: CreateElementEvent['store'],
+  ): void {
+    const elementPropsPath = parseRefElementMarker(props.id)
+    if (!elementPropsPath) return
+
+    const selector = getRefElementSelector(props.className)
+    if (!selector) return
+
+    const pendingRefElements = pendingRefElementsByPath.get(elementPropsPath)
+    const pendingRefElement = pendingRefElements?.shift()
+    if (!pendingRefElement) return
+    if (pendingRefElements?.length === 0) {
+      pendingRefElementsByPath.delete(elementPropsPath)
+    }
+
+    const refElementMatch: RefElementMatch = {
+      elementPropsPath: pendingRefElement.elementPropsPath,
+      refComponentType: pendingRefElement.refComponentType,
+      selector,
+    }
+
+    store.set(traceId, 'ref-element', refElementMatch)
+  }
+}
+
+function getRefElementSelector(classNameValue: unknown): string | undefined {
+  const semanticClassName = findPreferredSemanticClass(normalizeClassNames(classNameValue))
+  return semanticClassName ? `.${semanticClassName}` : undefined
 }

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

@@ -49,6 +49,6 @@ export 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']
 }

package/src/information-extractors/react/utils/mock-generator.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest'
+import { createRefElementMarker, parseRefElementMarker } from '../../../ref-elements/path-utils'
+import type { ComponentInfo } from '../../ts/types'
+import { generateMockProps, resetMockCounter } from './mock-generator'
+
+describe('generateMockProps', () => {
+  it('injects a dedicated ref-element id marker into each eligible elementProps branch', () => {
+    resetMockCounter()
+
+    const componentInfo: ComponentInfo = {
+      componentName: 'TestComponent',
+      props: {
+        elementProps: {
+          name: 'elementProps',
+          type: 'ElementProps',
+          required: true,
+          resolvedType: {
+            kind: 'object',
+            properties: {
+              actionButton: {
+                name: 'actionButton',
+                type: '{ className?: string; label?: string }',
+                required: true,
+                resolvedType: {
+                  kind: 'object',
+                  properties: {
+                    className: {
+                      name: 'className',
+                      type: 'string',
+                      required: false,
+                      resolvedType: { kind: 'primitive', value: 'string' },
+                    },
+                    label: {
+                      name: 'label',
+                      type: 'string',
+                      required: false,
+                      resolvedType: { kind: 'primitive', value: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+
+    const mockProps = generateMockProps(componentInfo, undefined, {
+      eligibleRefElementPaths: new Set(['actionButton']),
+    })
+    expect(mockProps).toMatchObject({
+      elementProps: {
+        actionButton: {
+          id: createRefElementMarker('actionButton'),
+        },
+      },
+    })
+
+    const actionButtonProps = (mockProps.elementProps as Record<string, unknown>).actionButton as Record<
+      string,
+      unknown
+    >
+    expect(parseRefElementMarker(actionButtonProps.id)).toBe('actionButton')
+  })
+
+  it('injects nested ref-element markers using the full elementProps path', () => {
+    resetMockCounter()
+
+    const componentInfo: ComponentInfo = {
+      componentName: 'NestedTestComponent',
+      props: {
+        elementProps: {
+          name: 'elementProps',
+          type: 'ElementProps',
+          required: true,
+          resolvedType: {
+            kind: 'object',
+            properties: {
+              card: {
+                name: 'card',
+                type: '{ elementProps: { cta: { className?: string } } }',
+                required: true,
+                resolvedType: {
+                  kind: 'object',
+                  properties: {
+                    elementProps: {
+                      name: 'elementProps',
+                      type: '{ cta: { className?: string } }',
+                      required: true,
+                      resolvedType: {
+                        kind: 'object',
+                        properties: {
+                          cta: {
+                            name: 'cta',
+                            type: '{ className?: string }',
+                            required: true,
+                            resolvedType: {
+                              kind: 'object',
+                              properties: {
+                                className: {
+                                  name: 'className',
+                                  type: 'string',
+                                  required: false,
+                                  resolvedType: { kind: 'primitive', value: 'string' },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+
+    const mockProps = generateMockProps(componentInfo, undefined, {
+      eligibleRefElementPaths: new Set(['card.elementProps.cta']),
+    })
+
+    const cardProps = (mockProps.elementProps as Record<string, unknown>).card as Record<string, unknown>
+    const nestedElementProps = cardProps.elementProps as Record<string, unknown>
+    const ctaProps = nestedElementProps.cta as Record<string, unknown>
+
+    expect(parseRefElementMarker(ctaProps.id)).toBe('card.elementProps.cta')
+  })
+})