@wix/zero-config-implementation 1.5.0

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

@@ -0,0 +1,214 @@
+/**
+ * CSS Properties Extractor
+ *
+ * Determines which CSS properties are relevant to each element
+ * based on its tag, role, and whether it has text content.
+ */
+
+import type { CreateElementEvent, ReactExtractor } from './core/types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CssPropertiesData {
+  relevant: string[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Element Categories
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Layout Containers - structural boxes focused on spacing and positioning
+ */
+const LAYOUT_CONTAINER_TAGS = new Set(['div', 'section', 'article', 'header', 'footer', 'main', 'nav', 'aside'])
+
+/**
+ * Text & Typography - elements where readability and hierarchy are primary
+ */
+const TEXT_TAGS = new Set([
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'span',
+  'li',
+  'a',
+  'label',
+  'strong',
+  'em',
+  'b',
+  'i',
+])
+
+/**
+ * Media & Visuals - elements requiring aspect ratio control (excluding svg)
+ */
+const MEDIA_TAGS = new Set(['img', 'video', 'canvas', 'picture'])
+
+/**
+ * Form Inputs & Interactive Elements - require state-based styling
+ */
+const INTERACTIVE_TAGS = new Set(['button', 'input', 'textarea', 'select'])
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Property Sets (using logical properties)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * CSS properties for Layout Containers and Interactive Elements
+ */
+const CONTAINER_CSS_PROPERTIES = [
+  'background',
+  'border-block-start',
+  'border-block-end',
+  'border-inline-start',
+  'border-inline-end',
+  'padding-block-start',
+  'padding-block-end',
+  'padding-inline-start',
+  'padding-inline-end',
+  'border-start-start-radius',
+  'border-start-end-radius',
+  'border-end-start-radius',
+  'border-end-end-radius',
+  'box-shadow',
+]
+
+/**
+ * CSS properties for Text elements and leaf elements with textContent
+ */
+const TEXT_CSS_PROPERTIES = ['font', 'line-height', 'letter-spacing', 'text-decoration']
+
+/**
+ * CSS properties for Media elements (excluding svg)
+ */
+const MEDIA_CSS_PROPERTIES = [
+  'border-block-start',
+  'border-block-end',
+  'border-inline-start',
+  'border-inline-end',
+  'border-start-start-radius',
+  'border-start-end-radius',
+  'border-end-start-radius',
+  'border-end-end-radius',
+  'box-shadow',
+]
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Category Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+type ElementCategory = 'layout' | 'text' | 'media' | 'interactive' | 'unknown'
+
+/**
+ * Determines the category of an element based on its tag and role
+ */
+function getElementCategory(tag: string, role?: string): ElementCategory {
+  const normalizedTag = tag.toLowerCase()
+
+  // Check role-based overrides first
+  if (role) {
+    const normalizedRole = role.toLowerCase()
+    if (normalizedRole === 'button' || normalizedRole === 'textbox') {
+      return 'interactive'
+    }
+    if (normalizedRole === 'heading' || normalizedRole === 'paragraph') {
+      return 'text'
+    }
+    if (normalizedRole === 'img' || normalizedRole === 'figure') {
+      return 'media'
+    }
+  }
+
+  // Check tag-based categories
+  if (INTERACTIVE_TAGS.has(normalizedTag)) {
+    return 'interactive'
+  }
+  if (TEXT_TAGS.has(normalizedTag)) {
+    return 'text'
+  }
+  if (MEDIA_TAGS.has(normalizedTag)) {
+    return 'media'
+  }
+  if (LAYOUT_CONTAINER_TAGS.has(normalizedTag)) {
+    return 'layout'
+  }
+
+  return 'unknown'
+}
+
+/**
+ * Gets CSS properties relevant to an element based on tag and role.
+ * Note: hasTextContent determination is deferred to tree building since
+ * we can't know during createElement if a child will have text content.
+ */
+export function getCssPropertiesForTag(tag: string, role?: string): string[] {
+  const category = getElementCategory(tag, role)
+  const properties: string[] = []
+
+  switch (category) {
+    case 'layout':
+    case 'interactive':
+      properties.push(...CONTAINER_CSS_PROPERTIES)
+      break
+
+    case 'text':
+      properties.push(...TEXT_CSS_PROPERTIES)
+      break
+
+    case 'media':
+      properties.push(...MEDIA_CSS_PROPERTIES)
+      break
+
+    case 'unknown':
+      // For unknown elements, default to container properties
+      // (can be refined during tree building based on children)
+      properties.push(...CONTAINER_CSS_PROPERTIES)
+      break
+  }
+
+  return properties
+}
+
+/**
+ * Adds text CSS properties to an existing property list without duplicates.
+ * Called during tree building when we know an element has text content.
+ */
+export function addTextProperties(existing: string[]): string[] {
+  const result = [...existing]
+  for (const prop of TEXT_CSS_PROPERTIES) {
+    if (!result.includes(prop)) {
+      result.push(prop)
+    }
+  }
+  return result
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a CSS properties extractor that determines relevant CSS properties
+ * for each element based on its tag and role.
+ */
+export function createCssPropertiesExtractor(): ReactExtractor {
+  return {
+    name: 'css-properties',
+
+    onCreateElement(event: CreateElementEvent): void {
+      const { tag, props, traceId, store } = event
+      const role = props.role as string | undefined
+
+      const relevant = getCssPropertiesForTag(tag, role)
+      const data: CssPropertiesData = { relevant }
+
+      store.set(traceId, 'css-properties', data)
+    },
+  }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * React Extractors
+ *
+ * Core infrastructure and pluggable extractors for the React information extraction system.
+ */
+
+// Core infrastructure
+export {
+  ExtractorStore,
+  runExtractors,
+  buildElementTree,
+} from './core'
+export type {
+  ExtractionResult,
+  ExtractedElement,
+  ReactExtractor,
+  RenderContext,
+  CreateElementEvent,
+  RenderCompleteEvent,
+} from './core'
+
+// Extractors
+export { createPropTrackerExtractor } from './prop-tracker'
+export type { PropTrackerData, PropTrackerExtractorState } from './prop-tracker'
+
+export { createCssPropertiesExtractor } from './css-properties'
+export type { CssPropertiesData } from './css-properties'

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

@@ -0,0 +1,132 @@
+/**
+ * PropTracker Extractor
+ *
+ * Tracks how props flow into DOM elements during render.
+ * Detects spy markers in element attributes and records prop→DOM bindings.
+ */
+
+import type { HTMLAttributes } from 'react'
+import { TRACE_ATTR } from '../../../component-renderer'
+import type { PropSpyMeta, TrackingStores } from '../types'
+import { type PropSpyContext, createPropSpyContext } from '../utils/prop-spy'
+import type { CreateElementEvent, ReactExtractor, RenderContext } from './core/types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SPY_REGEX = /__spy_\d+__/g
+
+export type GetSpyMetadataFn = (id: string) => PropSpyMeta | null
+
+export interface PropTrackerData {
+  tag: string
+  role?: string
+  boundProps: string[]
+  concatenatedAttrs: Map<string, string> // attrName → propName (for concatenated values)
+}
+
+export interface PropTrackerExtractorState {
+  stores: TrackingStores
+  spyContext: PropSpyContext
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a prop tracker extractor that:
+ * 1. Wraps props with spy proxies during beforeRender
+ * 2. Detects spy markers in element props during onCreateElement
+ * 3. Writes tracking data to the store namespaced by 'prop-tracker'
+ */
+export function createPropTrackerExtractor(): {
+  extractor: ReactExtractor
+  state: PropTrackerExtractorState
+} {
+  const spyContext = createPropSpyContext()
+  const stores: TrackingStores = {
+    reads: new Map(),
+    writes: new Map(),
+  }
+
+  const extractSpies = (value: unknown, seen = new WeakSet<object>()): { propName: string; path: string }[] => {
+    if (typeof value === 'string') {
+      return (value.match(SPY_REGEX) ?? [])
+        .map((id) => {
+          const meta = spyContext.getSpyMetadataByUniqueId(id)
+          return meta ? { propName: meta.propName, path: meta.path } : null
+        })
+        .filter(Boolean) as { propName: string; path: string }[]
+    }
+    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 []
+  }
+
+  const extractor: ReactExtractor = {
+    name: 'prop-tracker',
+
+    onBeforeRender(context: RenderContext): void {
+      // Wrap props with spy proxies to track access
+      context.props = spyContext.createAuditedProps(context.props, stores, () => context.componentInfo.componentName)
+    },
+
+    onCreateElement(event: CreateElementEvent): void {
+      const { tag, props, traceId, store } = event
+      const htmlProps = props as HTMLAttributes<unknown>
+
+      const boundProps = new Set<string>()
+      const concatenatedAttrs = new Map<string, string>()
+
+      Object.entries(props).forEach(([key, value]) => {
+        if (key.startsWith('__') || key === TRACE_ATTR) return
+
+        const spies = extractSpies(value)
+
+        spies.forEach((spy) => {
+          boundProps.add(spy.propName)
+          const path = spy.path
+          const entry = stores.writes.get(path) ?? { elements: new Map(), attributes: new Map() }
+
+          if (!stores.writes.has(path)) {
+            stores.writes.set(path, entry)
+          }
+
+          entry.elements.set(traceId, { tag, elementId: traceId })
+          entry.attributes.set(`${traceId}:${key}`, { attr: key, concatenated: spies.length > 1 })
+
+          // Track concatenated attributes
+          if (spies.length > 1) {
+            concatenatedAttrs.set(key, spy.propName)
+          }
+        })
+      })
+
+      // Write to store
+      const data: PropTrackerData = {
+        tag,
+        role: htmlProps.role,
+        boundProps: [...boundProps],
+        concatenatedAttrs,
+      }
+      store.set(traceId, 'prop-tracker', data)
+    },
+  }
+
+  return {
+    extractor,
+    state: { stores, spyContext },
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * React Information Extraction
+ *
+ * API: runExtractors() with pluggable extractors
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core API - Re-export from extractors module
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  // Core
+  ExtractorStore,
+  runExtractors,
+  buildElementTree,
+  // Extractors
+  createPropTrackerExtractor,
+  createCssPropertiesExtractor,
+} from './extractors'
+
+export type {
+  // Core types
+  ExtractionResult,
+  ExtractedElement,
+  ReactExtractor,
+  RenderContext,
+  CreateElementEvent,
+  RenderCompleteEvent,
+  // Extractor types
+  PropTrackerData,
+  PropTrackerExtractorState,
+  CssPropertiesData,
+} from './extractors'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type {
+  CoupledComponentInfo,
+  CoupledProp,
+  TrackingStores,
+  DOMBinding,
+  PropReadInfo,
+  PropWriteInfo,
+  PropSpyMeta,
+} from './types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type { PropSpyContext } from './utils/prop-spy'

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

@@ -0,0 +1,70 @@
+/**
+ * Types for React Information Extraction
+ */
+
+import type { PropInfo } from '../ts/types'
+import type { ExtractedElement } from './extractors/core/tree-builder'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Prop Spy (for tracking prop access)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const PROP_SPY_SYMBOL = Symbol.for('__prop_spy__')
+
+export interface PropSpyMeta {
+  path: string
+  propName: string
+  uniqueId: string
+  originalValue: unknown
+}
+
+export interface PropSpy<T = unknown> {
+  [PROP_SPY_SYMBOL]: true
+  __meta: PropSpyMeta
+  valueOf: () => T
+  toString: () => string
+  toJSON: () => T
+  [Symbol.toPrimitive]?: (hint: string) => T | string | number
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tracking Stores
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PropReadInfo {
+  components: Set<string>
+  value: unknown
+}
+
+export interface PropWriteInfo {
+  elements: Map<string, { tag: string; elementId: string }>
+  attributes: Map<string, { attr: string; concatenated: boolean }>
+}
+
+export interface TrackingStores {
+  reads: Map<string, PropReadInfo>
+  writes: Map<string, PropWriteInfo>
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DOMBinding {
+  element: string
+  attribute: string
+  concatenated: boolean
+  elementId: string
+}
+
+export interface CoupledProp extends PropInfo {
+  bindings: DOMBinding[]
+  logicOnly: boolean
+}
+
+export interface CoupledComponentInfo {
+  componentName: string
+  props: Record<string, CoupledProp>
+  elements: ExtractedElement[]
+  innerElementProps?: Map<string, Record<string, CoupledProp>>
+}