@wix/zero-config-implementation 1.5.0

package/src/information-extractors/css/selector-matcher.ts

@@ -0,0 +1,88 @@
+import * as cheerio from 'cheerio'
+import { TRACE_ATTR } from '../../component-renderer'
+import type { ExtractedCssInfo } from '../../index'
+import type { ExtractedElement } from '../react/extractors/core/tree-builder'
+import type { CSSProperty, CssSelectorMatch, MatchedCssData } from './types'
+
+export function matchCssSelectors(
+  html: string,
+  elements: ExtractedElement[],
+  cssInfos: ExtractedCssInfo[],
+): ExtractedElement[] {
+  const $ = cheerio.load(html)
+
+  // Build traceId -> matches map
+  const matchesByTraceId = new Map<string, CssSelectorMatch[]>()
+  const customPropsByTraceId = new Map<string, Record<string, string>>()
+
+  for (const cssInfo of cssInfos) {
+    const allProps = cssInfo.api.getAllProperties()
+
+    for (const [selector, properties] of allProps) {
+      // Skip @keyframes - not element selectors
+      if (selector.startsWith('@')) continue
+
+      // Get DOM-matchable selector from the API
+      const domSelector = cssInfo.api.getDomSelector(selector)
+      if (!domSelector) continue
+
+      try {
+        $(domSelector).each((_, elem) => {
+          const traceId = $(elem).attr(TRACE_ATTR)
+          if (!traceId) return
+
+          // Use reduce to separate regular and custom properties in one pass
+          const { regular, custom } = properties.reduce<{
+            regular: CSSProperty[]
+            custom: Record<string, string>
+          }>(
+            (acc, prop) => {
+              if (prop.name.startsWith('--')) {
+                acc.custom[prop.name] = prop.value
+              } else {
+                acc.regular.push(prop)
+              }
+              return acc
+            },
+            { regular: [], custom: {} },
+          )
+
+          if (regular.length > 0) {
+            const existing = matchesByTraceId.get(traceId) ?? []
+            existing.push({ selector, properties: regular })
+            matchesByTraceId.set(traceId, existing)
+          }
+
+          if (Object.keys(custom).length > 0) {
+            const existing = customPropsByTraceId.get(traceId) ?? {}
+            Object.assign(existing, custom)
+            customPropsByTraceId.set(traceId, existing)
+          }
+        })
+      } catch {
+        // Invalid selector for Cheerio, skip
+      }
+    }
+  }
+
+  return enrichElements(elements, matchesByTraceId, customPropsByTraceId)
+}
+
+function enrichElements(
+  elements: ExtractedElement[],
+  matchesByTraceId: Map<string, CssSelectorMatch[]>,
+  customPropsByTraceId: Map<string, Record<string, string>>,
+): ExtractedElement[] {
+  return elements.map((el) => {
+    const data: MatchedCssData = {
+      matches: matchesByTraceId.get(el.traceId) ?? [],
+      customProperties: customPropsByTraceId.get(el.traceId) ?? {},
+    }
+    el.extractorData.set('css-matcher', data)
+
+    return {
+      ...el,
+      children: enrichElements(el.children, matchesByTraceId, customPropsByTraceId),
+    }
+  })
+}

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

@@ -0,0 +1,56 @@
+export interface CSSProperty {
+  name: string
+  value: string
+}
+
+export interface CssSelectorMatch {
+  selector: string
+  properties: CSSProperty[]
+}
+
+export interface MatchedCssData {
+  matches: CssSelectorMatch[]
+  customProperties: Record<string, string>
+}
+
+/**
+ * API returned by parseCss function for querying parsed CSS
+ */
+export interface CSSParserAPI {
+  /**
+   * Gets CSS properties for a specific selector
+   * @param selector - The selector to extract properties for
+   * @returns Array of CSS properties for the specified selector
+   */
+  getPropertiesForSelector: (selector: string) => CSSProperty[]
+
+  /**
+   * Gets all selectors and their properties from the CSS
+   * @returns Map from selector to its CSS properties
+   */
+  getAllProperties: () => Map<string, CSSProperty[]>
+
+  /**
+   * Gets all CSS property names that use a specific CSS variable
+   * @param varName - The CSS variable name (with or without --)
+   * @returns Array of CSS property names that use this variable
+   */
+  getVarUsages: (varName: string) => string[]
+
+  /**
+   * Gets unique properties from multiple selectors with CSS cascade rules:
+   * - First selector wins (properties from earlier selectors take precedence)
+   * - Within a selector, last value wins (if property appears multiple times)
+   * @param selectors - Array of selectors to extract properties from
+   * @returns Map of property names to their values
+   */
+  getUniqueProperties: (selectors: string[]) => Map<string, string>
+
+  /**
+   * Gets a DOM-matchable selector by stripping pseudo-classes.
+   * Returns null if the selector contains pseudo-elements (unmatchable against real DOM).
+   * @param selector - The original CSS selector string
+   * @returns DOM-matchable selector string or null
+   */
+  getDomSelector: (selector: string) => string | null
+}

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

@@ -0,0 +1,6 @@
+export { ExtractorStore } from './store'
+export { runExtractors } from './runner'
+export type { ExtractionResult } from './runner'
+export { buildElementTree } from './tree-builder'
+export type { ExtractedElement } from './tree-builder'
+export type { ReactExtractor, RenderContext, CreateElementEvent, RenderCompleteEvent } from './types'

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

@@ -0,0 +1,89 @@
+/**
+ * Generic Extractor Runner
+ *
+ * Orchestrates the extractor lifecycle:
+ * 1. Create shared ExtractorStore
+ * 2. Run beforeRender phase (extractors can modify props)
+ * 3. Render with onCreateElement hooks
+ * 4. Run renderComplete phase
+ * 5. Parse HTML and merge with store data
+ */
+
+import type { ComponentType } from 'react'
+import { type CreateElementListener, renderWithExtractors } from '../../../../component-renderer'
+import type { ComponentInfo } from '../../../ts/types'
+import { generateMockProps, resetMockCounter } from '../../utils/mock-generator'
+import { ExtractorStore } from './store'
+import { type ExtractedElement, buildElementTree } from './tree-builder'
+import type { CreateElementEvent, ReactExtractor, RenderContext } from './types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ExtractionResult {
+  html: string
+  store: ExtractorStore
+  elements: ExtractedElement[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runner
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Runs extractors through the full lifecycle and returns extraction results.
+ *
+ * @param componentInfo - TypeScript-extracted component information
+ * @param component - The React component to render
+ * @param extractors - Array of extractors to run
+ * @returns Extraction results including HTML, store, and element tree
+ */
+export function runExtractors(
+  componentInfo: ComponentInfo,
+  component: ComponentType<unknown>,
+  extractors: ReactExtractor[],
+): ExtractionResult {
+  // Reset mock counter for reproducible results
+  resetMockCounter()
+
+  // Create shared store
+  const store = new ExtractorStore()
+
+  // Create render context with mutable props
+  const context: RenderContext = {
+    componentInfo,
+    component,
+    props: generateMockProps(componentInfo),
+    store,
+  }
+
+  // Phase 1: beforeRender - extractors can modify props
+  for (const ext of extractors) {
+    ext.onBeforeRender?.(context)
+  }
+
+  // Create listeners that call onCreateElement for each extractor
+  const listeners: CreateElementListener[] = [
+    {
+      onCreateElement(event: CreateElementEvent): void {
+        for (const ext of extractors) {
+          ext.onCreateElement?.(event)
+        }
+      },
+    },
+  ]
+
+  // Phase 2: Render with element creation interception
+  const html = renderWithExtractors(context.component, context.props, listeners, store)
+
+  // Phase 3: renderComplete - extractors can post-process
+  for (const ext of extractors) {
+    ext.onRenderComplete?.({ html, context })
+  }
+
+  // Phase 4: Parse HTML and merge with store data
+  const elements = buildElementTree(html, store)
+
+  return { html, store, elements }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * ExtractorStore - Shared store for extractors with namespace support
+ *
+ * Extractors write to this store during render, namespaced by their name:
+ *   store.set(traceId, 'prop-tracker', { boundProps: ['label', 'onClick'] })
+ *   store.set(traceId, 'css-properties', { relevant: ['color', 'background'] })
+ *
+ * Store structure: Map<traceId, Map<extractorName, data>>
+ */
+
+export class ExtractorStore {
+  private data = new Map<string, Map<string, unknown>>()
+
+  set<T>(traceId: string, extractorName: string, value: T): void {
+    if (!this.data.has(traceId)) {
+      this.data.set(traceId, new Map())
+    }
+    this.data.get(traceId)!.set(extractorName, value)
+  }
+
+  get<T>(traceId: string, extractorName: string): T | undefined {
+    return this.data.get(traceId)?.get(extractorName) as T | undefined
+  }
+
+  getAll(traceId: string): Map<string, unknown> | undefined {
+    return this.data.get(traceId)
+  }
+
+  entries(): IterableIterator<[string, Map<string, unknown>]> {
+    return this.data.entries()
+  }
+
+  clear(): void {
+    this.data.clear()
+  }
+}

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

@@ -0,0 +1,273 @@
+/**
+ * Build Element Tree
+ *
+ * Parses HTML to get hierarchy and merges with ExtractorStore data.
+ * Each element gets a semantic name computed by concatenating ancestor names.
+ */
+
+import { pascalCase } from 'case-anything'
+import { type DefaultTreeAdapterMap, parseFragment } from 'parse5'
+import { TRACE_ATTR } from '../../../../component-renderer'
+import type { CssPropertiesData } from '../css-properties'
+import { addTextProperties } from '../css-properties'
+import type { ExtractorStore } from './store'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ExtractedElement {
+  traceId: string
+  name: string // Semantic name for the element (see naming rules)
+  tag: string
+  attributes: Record<string, string>
+  extractorData: Map<string, unknown> // extractorName → data
+  children: ExtractedElement[]
+  hasTextContent?: boolean
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tag Normalization Map
+// ─────────────────────────────────────────────────────────────────────────────
+
+const TAG_NAMES: Record<string, string> = {
+  a: 'Anchor',
+  abbr: 'Abbreviation',
+  article: 'Article',
+  aside: 'Aside',
+  button: 'Button',
+  caption: 'Caption',
+  col: 'TableColumn',
+  colgroup: 'TableColumnGroup',
+  dd: 'DescriptionDetails',
+  details: 'Details',
+  div: 'Div',
+  dl: 'DescriptionList',
+  dt: 'DescriptionTerm',
+  fieldset: 'Fieldset',
+  figcaption: 'FigureCaption',
+  figure: 'Figure',
+  footer: 'Footer',
+  form: 'Form',
+  h1: 'Heading1',
+  h2: 'Heading2',
+  h3: 'Heading3',
+  h4: 'Heading4',
+  h5: 'Heading5',
+  h6: 'Heading6',
+  header: 'Header',
+  hr: 'HorizontalRule',
+  img: 'Image',
+  input: 'Input',
+  label: 'Label',
+  legend: 'Legend',
+  li: 'ListItem',
+  main: 'Main',
+  nav: 'Navigation',
+  ol: 'OrderedList',
+  optgroup: 'OptionGroup',
+  option: 'Option',
+  p: 'Paragraph',
+  pre: 'Preformatted',
+  progress: 'Progress',
+  section: 'Section',
+  select: 'Select',
+  span: 'Span',
+  strong: 'Strong',
+  summary: 'Summary',
+  table: 'Table',
+  tbody: 'TableBody',
+  td: 'TableCell',
+  textarea: 'TextArea',
+  tfoot: 'TableFooter',
+  th: 'TableHeader',
+  thead: 'TableHead',
+  tr: 'TableRow',
+  ul: 'UnorderedList',
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Element = DefaultTreeAdapterMap['element']
+type TextNode = DefaultTreeAdapterMap['textNode']
+type Node = DefaultTreeAdapterMap['node']
+
+const isElement = (node: Node): node is Element => 'tagName' in node
+const isTextNode = (node: Node): node is TextNode => 'nodeName' in node && node.nodeName === '#text'
+
+const getAttribute = (element: Element, name: string): string | undefined =>
+  element.attrs.find((attr) => attr.name === name)?.value
+
+const getAttributes = (element: Element): Record<string, string> => {
+  const attrs: Record<string, string> = {}
+  for (const attr of element.attrs) {
+    attrs[attr.name] = attr.value
+  }
+  return attrs
+}
+
+/**
+ * Checks if an element has direct text content (non-whitespace text nodes as children)
+ */
+const hasDirectTextContent = (element: Element): boolean =>
+  element.childNodes.some((child) => isTextNode(child) && child.value.trim().length > 0)
+
+/**
+ * Normalizes a tag name to its semantic PascalCase form
+ */
+function normalizeTagName(tag: string): string {
+  return TAG_NAMES[tag.toLowerCase()] ?? pascalCase(tag)
+}
+
+/**
+ * Gets the text content of an element (for aria-labelledby resolution)
+ */
+function getTextContent(element: Element): string {
+  let text = ''
+  for (const child of element.childNodes) {
+    if (isTextNode(child)) {
+      text += child.value
+    } else if (isElement(child)) {
+      text += getTextContent(child)
+    }
+  }
+  return text.trim()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Element Naming
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Computes the name contribution for a single element.
+ * Priority: id > aria-label > aria-labelledby > normalized tag name
+ */
+function getElementNamePart(element: Element, getElementById: (id: string) => Element | undefined): string {
+  const id = getAttribute(element, 'id')
+  if (id) {
+    return pascalCase(id)
+  }
+
+  const ariaLabel = getAttribute(element, 'aria-label')
+  if (ariaLabel) {
+    return pascalCase(ariaLabel)
+  }
+
+  const ariaLabelledBy = getAttribute(element, 'aria-labelledby')
+  if (ariaLabelledBy) {
+    const labelElement = getElementById(ariaLabelledBy)
+    if (labelElement) {
+      const labelText = getTextContent(labelElement)
+      if (labelText) {
+        return pascalCase(labelText)
+      }
+    }
+  }
+
+  return normalizeTagName(element.tagName)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tree Building
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Builds an element tree from HTML, merging with store data.
+ * Each element gets a semantic name from concatenated ancestor names.
+ */
+export function buildElementTree(html: string, store: ExtractorStore): ExtractedElement[] {
+  const fragment = parseFragment(html)
+
+  // Build ID lookup for aria-labelledby resolution
+  const elementsById = new Map<string, Element>()
+  const collectIds = (node: Node): void => {
+    if (isElement(node)) {
+      const id = getAttribute(node, 'id')
+      if (id) {
+        elementsById.set(id, node)
+      }
+      node.childNodes.forEach(collectIds)
+    }
+  }
+  fragment.childNodes.forEach(collectIds)
+
+  const getElementById = (id: string): Element | undefined => elementsById.get(id)
+
+  /**
+   * Recursively walks the tree, building ExtractedElements.
+   * @param node - The current parse5 node
+   * @param ancestorPath - The concatenated name path from ancestors (empty for root's children)
+   * @param isRoot - Whether this is the root element (first traced element)
+   */
+  const walkTree = (node: Node, ancestorPath: string, isRoot: boolean): ExtractedElement[] => {
+    if (!isElement(node)) return []
+
+    const traceId = getAttribute(node, TRACE_ATTR)
+
+    // If this element has a traceId, it's a traced element
+    if (traceId) {
+      // Compute this element's name part
+      const namePart = isRoot ? 'root' : getElementNamePart(node, getElementById)
+
+      // Full name is ancestor path + this element's name (no separator)
+      const name = isRoot ? 'root' : ancestorPath + namePart
+
+      // Get extractor data from store
+      const extractorData = store.getAll(traceId) ?? new Map()
+
+      // Check for text content
+      const hasText = hasDirectTextContent(node)
+
+      // If element has text content and has css-properties data, add text properties
+      if (hasText) {
+        const cssData = extractorData.get('css-properties') as CssPropertiesData | undefined
+        if (cssData) {
+          const enhanced: CssPropertiesData = {
+            relevant: addTextProperties(cssData.relevant),
+          }
+          extractorData.set('css-properties', enhanced)
+        }
+      }
+
+      // Recursively process children
+      // Children use this element's full name as their ancestor path
+      const childPath = isRoot ? '' : name
+      const children = node.childNodes.flatMap((child) => walkTree(child, childPath, false))
+
+      // Build attributes (excluding trace-id)
+      const attributes = getAttributes(node)
+      delete attributes[TRACE_ATTR]
+
+      return [
+        {
+          traceId,
+          name,
+          tag: node.tagName,
+          attributes,
+          extractorData,
+          children,
+          ...(hasText && { hasTextContent: true }),
+        },
+      ]
+    }
+
+    // No traceId - just pass through to children with same ancestor path
+    return node.childNodes.flatMap((child) => walkTree(child, ancestorPath, false))
+  }
+
+  // Start with empty ancestor path, first traced element is root
+  let isFirst = true
+  const result: ExtractedElement[] = []
+
+  for (const node of fragment.childNodes) {
+    const elements = walkTree(node, '', isFirst)
+    if (elements.length > 0) {
+      result.push(...elements)
+      isFirst = false // Only the first traced element is root
+    }
+  }
+
+  return result
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Core interfaces for the pluggable extractor system
+ */
+
+import type { ComponentType } from 'react'
+import type { ComponentInfo } from '../../../ts/types'
+import type { ExtractorStore } from './store'
+
+/**
+ * Context available to extractors during the beforeRender phase.
+ * Props are mutable - extractors can modify them before render.
+ */
+export interface RenderContext {
+  componentInfo: ComponentInfo
+  component: ComponentType<unknown>
+  props: Record<string, unknown> // Mutable - extractors can modify
+  store: ExtractorStore
+}
+
+/**
+ * Event emitted for each DOM element created during render.
+ */
+export interface CreateElementEvent {
+  tag: string
+  props: Record<string, unknown>
+  traceId: string
+  children: unknown[]
+  store: ExtractorStore
+}
+
+/**
+ * Event emitted after render completes.
+ */
+export interface RenderCompleteEvent {
+  html: string
+  context: RenderContext
+}
+
+/**
+ * Interface for pluggable extractors.
+ * Extractors can hook into any combination of lifecycle events.
+ */
+export interface ReactExtractor {
+  name: string
+  onBeforeRender?(context: RenderContext): void
+  onCreateElement?(event: CreateElementEvent): void
+  onRenderComplete?(event: RenderCompleteEvent): void
+}