@wix/zero-config-implementation 1.5.0

package/src/index.ts

@@ -0,0 +1,223 @@
+import { Result, ResultAsync } from 'neverthrow'
+import type { ComponentType } from 'react'
+import type { EditorReactComponent } from './schema'
+
+import { extractAllComponentInfo, extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
+import type { ComponentInfo } from './information-extractors/ts'
+// TypeScript extraction
+import { compileTsFile } from './ts-compiler'
+
+// Error classes
+import { type NotFoundError, ParseError } from './errors'
+
+// Component loader helpers
+import { findComponent, loadModule } from './component-loader'
+
+// Pipeline orchestration
+import { processComponent } from './manifest-pipeline'
+export type {
+  ComponentInfoWithCss,
+  ExtractedCssInfo,
+  ExtractionWarning,
+  ProcessComponentResult,
+} from './manifest-pipeline'
+
+// Converter
+import { toEditorReactComponent } from './converters'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ManifestResult {
+  component: EditorReactComponent
+  errors: ExtractionError[]
+}
+
+export interface ExtractionError {
+  componentName: string
+  phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion'
+  error: string
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract component manifest from a TypeScript source file.
+ *
+ * @param componentPath - Path to the TypeScript source file
+ * @param compiledEntryPath - Path to the built JS entry file of the component's package (e.g. dist/index.js)
+ * @returns The manifest result containing components and non-fatal warnings
+ * @errors
+ * - {@link NotFoundError} — Source file does not exist (phase: `compile`)
+ * - {@link ParseError} — TypeScript config or component types could not be parsed (phase: `compile` | `extract`)
+ */
+export function extractComponentManifest(
+  componentPath: string,
+  compiledEntryPath: string,
+): ResultAsync<ManifestResult, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError>> {
+  // Step 1: Load the compiled package module (non-fatal)
+  return loadModule(compiledEntryPath)
+    .map((moduleExports) => ({ moduleExports, loaderError: null as string | null }))
+    .orElse((err) =>
+      ResultAsync.fromSafePromise(
+        Promise.resolve({ moduleExports: null as Record<string, unknown> | null, loaderError: err.message }),
+      ),
+    )
+    .andThen(({ moduleExports, loaderError }) => {
+      const loadComponent: (componentName: string) => ComponentType<unknown> | null = moduleExports
+        ? (name) => findComponent(moduleExports, name)
+        : () => null
+
+      // Step 2: Compile TypeScript (fatal)
+      return compileTsFile(componentPath)
+        .andThen((program) => {
+          // Step 3: Extract default-exported component types (fatal)
+          const safeExtract = Result.fromThrowable(
+            (prog: typeof program) => {
+              const componentInfo = extractDefaultComponentInfo(prog, componentPath)
+              if (!componentInfo) {
+                throw new Error(`No default export found in "${componentPath}"`)
+              }
+              return componentInfo
+            },
+            (thrown) =>
+              new ParseError(
+                `Failed to extract component types from "${componentPath}": ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+                {
+                  cause: thrown as Error,
+                  props: { phase: 'extract' },
+                },
+              ),
+          )
+          const componentInfoResult = safeExtract(program)
+
+          return componentInfoResult.map((componentInfo) => ({ program, componentInfo }))
+        })
+        .map(({ program, componentInfo }) => {
+          const errors: ExtractionError[] = []
+
+          // Surface loader error as a non-fatal error
+          if (loaderError) {
+            errors.push({
+              componentName: compiledEntryPath,
+              phase: 'loader',
+              error: loaderError,
+            })
+          }
+
+          // Step 4: Extract CSS imports (non-fatal)
+          let cssImportPaths: string[] = []
+          const safeCssImports = Result.fromThrowable(extractCssImports, (thrown) => thrown)
+          const cssResult = safeCssImports(program)
+          if (cssResult.isOk()) {
+            cssImportPaths = cssResult.value
+          } else {
+            const thrown = cssResult.error
+            errors.push({
+              componentName: componentPath,
+              phase: 'css',
+              error: `Failed to extract CSS imports: ${thrown instanceof Error ? (thrown as Error).message : String(thrown)}`,
+            })
+          }
+
+          // Step 5: Process the default-exported component (non-fatal)
+          const processResult = processComponent(componentInfo, loadComponent, cssImportPaths, !!loaderError)
+          errors.push(...processResult.warnings)
+          const component = toEditorReactComponent(processResult.component)
+
+          return { component, errors }
+        })
+    })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API Exports
+//
+// The API is organized into three tiers:
+//
+//   Tier 1 — High-Level API
+//     One-call manifest extraction. Pass a file path, get back a manifest.
+//     Start here if you want the default pipeline with no customization.
+//
+//   Tier 2 — Pipeline Building Blocks
+//     Individual steps of the extraction pipeline. Use these to compose a
+//     custom pipeline, swap out extractors, or process intermediate results.
+//
+//   Tier 3 — Low-Level Renderer
+//     Direct React.createElement interception. Use this only if you need
+//     full control over the rendering and listener lifecycle.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── Tier 1: High-Level API ──────────────────────────────────────────────────
+// extractComponentManifest() is exported above as a named function declaration.
+
+// ── Tier 2: Pipeline Building Blocks ────────────────────────────────────────
+
+/** TypeScript compilation & static analysis */
+export { compileTsFile } from './ts-compiler'
+export { extractAllComponentInfo, extractDefaultComponentInfo } from './information-extractors/ts/components'
+export { extractCssImports } from './information-extractors/ts/css-imports'
+export type {
+  ComponentInfo,
+  PropInfo,
+  ResolvedType,
+  ResolvedKind,
+  DefaultValue,
+} from './information-extractors/ts/types'
+
+/** React render-time extraction */
+export {
+  runExtractors,
+  ExtractorStore,
+  buildElementTree,
+  createPropTrackerExtractor,
+  createCssPropertiesExtractor,
+} from './information-extractors/react'
+export type {
+  ExtractionResult,
+  ReactExtractor,
+  RenderContext,
+  CreateElementEvent,
+  RenderCompleteEvent,
+  ExtractedElement,
+  PropTrackerData,
+  PropTrackerExtractorState,
+  CssPropertiesData,
+  PropSpyContext,
+} from './information-extractors/react'
+export type {
+  CoupledComponentInfo,
+  CoupledProp,
+  DOMBinding,
+  TrackingStores,
+  PropReadInfo,
+  PropWriteInfo,
+  PropSpyMeta,
+} from './information-extractors/react'
+
+/** CSS parsing & selector matching */
+export { parseCss } from './information-extractors/css'
+export type { CSSParserAPI } from './information-extractors/css'
+
+/** Error classes */
+export {
+  BaseError,
+  NotFoundError,
+  ParseError,
+  ValidationError,
+  IoError,
+  DefectError,
+  withDefectBoundary,
+} from './errors'
+
+/** Component loader */
+export { createComponentLoader } from './component-loader'
+
+// ── Tier 3: Low-Level Renderer ──────────────────────────────────────────────
+
+export { renderWithExtractors } from './component-renderer'
+export type { CreateElementListener } from './component-renderer'

package/src/information-extractors/css/README.md

@@ -0,0 +1,3 @@
+# CSS Parser
+
+An abstraction over a CSS file that exposes a closed API for accessing css properties in a structured way.

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

@@ -0,0 +1,3 @@
+export { parseCss } from './parse'
+export { matchCssSelectors } from './selector-matcher'
+export type { CSSParserAPI } from './types'

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

@@ -0,0 +1,450 @@
+import { transform } from 'lightningcss'
+import type { CSSParserAPI, CSSProperty } from './types'
+// Store parsed selectors for later DOM selector computation
+const parsedSelectors = new Map<string, unknown[]>()
+
+/**
+ * Factory function that parses CSS and returns an API to query the parsed result
+ * @param cssString - The CSS file content as a string
+ * @returns API object with methods to query the parsed CSS
+ */
+export function parseCss(cssString: string): CSSParserAPI {
+  // Clear previous selectors for this parse
+  parsedSelectors.clear()
+
+  // Parse all properties eagerly at initialization using lightningcss
+  const allProperties = parseAllProperties(cssString)
+
+  return {
+    getPropertiesForSelector(selector: string): CSSProperty[] {
+      return allProperties.get(selector) ?? []
+    },
+
+    getAllProperties(): Map<string, CSSProperty[]> {
+      return allProperties
+    },
+
+    getVarUsages(varName: string): string[] {
+      // Normalize variable name to include --
+      const normalizedVarName = varName.startsWith('--') ? varName : `--${varName}`
+
+      const propertyNames = new Set<string>()
+
+      // Search through all properties for var() usage
+      for (const properties of allProperties.values()) {
+        for (const property of properties) {
+          // Check if the value contains var(--varName)
+          const varPattern = new RegExp(`var\\(\\s*${escapeRegex(normalizedVarName)}\\s*[,)]`, 'i')
+
+          if (varPattern.test(property.value)) {
+            // Ignore shorthand properties (values with multiple space-separated values)
+            if (!isShorthandValue(property.value)) {
+              propertyNames.add(property.name)
+            }
+          }
+        }
+      }
+
+      return Array.from(propertyNames)
+    },
+
+    getUniqueProperties(selectors: string[]): Map<string, string> {
+      const mergedProperties = new Map<string, string>()
+
+      for (const selector of selectors) {
+        const properties = this.getPropertiesForSelector(selector)
+
+        // Within a selector, last value wins (CSS behavior)
+        const selectorProperties = new Map<string, string>()
+        for (const prop of properties) {
+          selectorProperties.set(prop.name, prop.value)
+        }
+
+        // Merge into final map - first selector wins
+        for (const [name, value] of selectorProperties) {
+          if (!mergedProperties.has(name)) {
+            mergedProperties.set(name, value)
+          }
+        }
+      }
+
+      return mergedProperties
+    },
+
+    getDomSelector(selector: string): string | null {
+      const parsed = parsedSelectors.get(selector)
+      if (!parsed) return null
+      return buildDomSelector(parsed)
+    },
+  }
+}
+
+/**
+ * Parses all selectors and their properties from the CSS using lightningcss
+ * Supports @media rules, @keyframes, and nested selectors
+ * @param cssString - CSS string to parse
+ * @returns Map from selector to its CSS properties
+ */
+function parseAllProperties(cssString: string): Map<string, CSSProperty[]> {
+  const propertiesMap = new Map<string, CSSProperty[]>()
+
+  try {
+    // Use lightningcss transform with visitor to collect properties
+    // Note: We don't return the rule from visitors - just collect data
+    transform({
+      filename: 'input.css',
+      code: Buffer.from(cssString),
+      minify: false,
+      visitor: {
+        Rule: {
+          style(rule) {
+            try {
+              // Extract selector string from the rule
+              const selectors = rule.value.selectors
+              if (!selectors?.length) return undefined
+
+              // Convert selector AST to string representation and store parsed selectors
+              const selectorStrings = selectors.map((sel: unknown[]) => {
+                const str = selectorToString(sel)
+                parsedSelectors.set(str, sel)
+                return str
+              })
+
+              // Extract properties from declarations
+              const properties: CSSProperty[] = []
+              for (const decl of rule.value.declarations?.declarations ?? []) {
+                const extracted = extractPropertyNameAndValue(decl)
+                if (extracted) {
+                  properties.push(extracted)
+                }
+              }
+
+              // Store properties for each selector
+              if (properties.length > 0) {
+                for (const selector of selectorStrings) {
+                  const existing = propertiesMap.get(selector) ?? []
+                  propertiesMap.set(selector, [...existing, ...properties])
+                }
+              }
+            } catch {
+              // Skip rules that can't be processed
+            }
+
+            return undefined
+          },
+
+          keyframes(rule) {
+            try {
+              // Extract @keyframes name and its keyframe selectors
+              const keyframeName = rule.value.name.type === 'ident' ? rule.value.name.value : rule.value.name.value
+
+              for (const keyframe of rule.value.keyframes) {
+                // Each keyframe has selectors like 'from', 'to', '50%'
+                const keyframeSelectors = keyframe.selectors.map((s) => {
+                  if (typeof s === 'string') return s
+                  if ('percentage' in s) return `${s.percentage}%`
+                  return String(s)
+                })
+
+                const properties: CSSProperty[] = []
+                for (const decl of keyframe.declarations?.declarations ?? []) {
+                  const extracted = extractPropertyNameAndValue(decl)
+                  if (extracted) {
+                    properties.push(extracted)
+                  }
+                }
+
+                if (properties.length > 0) {
+                  for (const selector of keyframeSelectors) {
+                    const fullSelector = `@keyframes ${keyframeName} ${selector}`
+                    const existing = propertiesMap.get(fullSelector) ?? []
+                    propertiesMap.set(fullSelector, [...existing, ...properties])
+                  }
+                }
+              }
+            } catch {
+              // Skip keyframes that can't be processed
+            }
+
+            return undefined
+          },
+        },
+      },
+    })
+  } catch (error) {
+    // If parsing fails, return empty map
+    console.error('CSS parsing error:', error)
+  }
+
+  return propertiesMap
+}
+
+/**
+ * Converts a single selector component to a string
+ */
+function selectorComponentToString(component: unknown): string {
+  if (!component || typeof component !== 'object') return ''
+  const comp = component as Record<string, unknown>
+
+  try {
+    if (comp.type === 'class') {
+      return `.${comp.name}`
+    }
+    if (comp.type === 'id') {
+      return `#${comp.name}`
+    }
+    if (comp.type === 'type') {
+      return comp.name as string
+    }
+    if (comp.type === 'universal') {
+      return '*'
+    }
+    if (comp.type === 'attribute') {
+      const attr = comp as { name: string; operation?: { operator: string; value: string } }
+      if (attr.operation) {
+        return `[${attr.name}${attr.operation.operator}"${attr.operation.value}"]`
+      }
+      return `[${attr.name}]`
+    }
+    if (comp.type === 'pseudo-class') {
+      const pseudo = comp as { kind: string; name?: string }
+      return `:${pseudo.kind === 'custom' ? pseudo.name : pseudo.kind}`
+    }
+    if (comp.type === 'pseudo-element') {
+      const pseudo = comp as { kind: string; name?: string }
+      return `::${pseudo.kind === 'custom' ? pseudo.name : pseudo.kind}`
+    }
+    if (comp.type === 'combinator') {
+      const combinator = comp.value as string
+      if (combinator === 'descendant') return ' '
+      if (combinator === 'child') return ' > '
+      if (combinator === 'next-sibling') return ' + '
+      if (combinator === 'later-sibling') return ' ~ '
+    }
+  } catch {
+    // Skip components that can't be processed
+  }
+
+  return ''
+}
+
+/**
+ * Converts a selector AST node to a string
+ */
+function selectorToString(selector: unknown[]): string {
+  return selector.map(selectorComponentToString).join('')
+}
+
+/**
+ * Builds a DOM-queryable selector by filtering out pseudo-classes and pseudo-elements.
+ * Returns null if the selector contains pseudo-elements (unmatchable against real DOM).
+ */
+function buildDomSelector(selector: unknown[]): string | null {
+  const parts: string[] = []
+
+  for (const component of selector) {
+    if (!component || typeof component !== 'object') continue
+    const comp = component as Record<string, unknown>
+
+    // Pseudo-elements cannot be matched against real DOM
+    if (comp.type === 'pseudo-element') {
+      return null
+    }
+
+    // Skip pseudo-classes (they apply to states, not static DOM)
+    if (comp.type === 'pseudo-class') {
+      continue
+    }
+
+    parts.push(selectorComponentToString(component))
+  }
+
+  const result = parts.join('')
+  return result || null
+}
+
+// Type for lightningcss declaration with custom property support
+interface LightningDecl {
+  property: string
+  value: unknown
+}
+
+interface CustomPropertyValue {
+  name: string
+  value: unknown[]
+}
+
+/**
+ * Extracts the property name and value from a lightningcss declaration.
+ * Handles special cases like custom properties (CSS variables) and unparsed values.
+ */
+function extractPropertyNameAndValue(decl: LightningDecl): CSSProperty | null {
+  try {
+    // Handle CSS custom properties (variables)
+    if (decl.property === 'custom') {
+      const customValue = decl.value as CustomPropertyValue
+      const name = customValue.name // e.g., "--primary-color"
+      const value = serializeCustomPropertyValue(customValue.value)
+      if (name && value) {
+        return { name, value }
+      }
+      return null
+    }
+
+    // Handle unparsed properties (e.g., properties using var())
+    if (decl.property === 'unparsed') {
+      const unparsedValue = decl.value as { propertyId: { property: string }; value: unknown[] }
+      const name = unparsedValue.propertyId?.property
+      if (name) {
+        const value = propertyValueToString(decl)
+        if (value) {
+          return { name, value }
+        }
+      }
+      return null
+    }
+
+    // Standard property
+    const name = propertyNameToString(decl.property)
+    const value = propertyValueToString(decl)
+    if (name && value) {
+      return { name, value }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Serializes a custom property value array to a CSS string
+ */
+function serializeCustomPropertyValue(valueArray: unknown[]): string {
+  const parts: string[] = []
+
+  for (const token of valueArray) {
+    if (!token || typeof token !== 'object') continue
+    const t = token as Record<string, unknown>
+
+    if (t.type === 'color') {
+      const color = t.value as Record<string, unknown>
+      if (color.type === 'rgb') {
+        const r = color.r as number
+        const g = color.g as number
+        const b = color.b as number
+        const a = color.alpha as number
+        if (a === 1) {
+          parts.push(`#${toHex(r)}${toHex(g)}${toHex(b)}`)
+        } else {
+          parts.push(`rgba(${r}, ${g}, ${b}, ${a})`)
+        }
+      }
+    } else if (t.type === 'length' || t.type === 'dimension') {
+      const dim = (t.value as Record<string, unknown>) ?? t
+      const unit = dim.unit as string
+      const val = dim.value as number
+      parts.push(`${val}${unit}`)
+    } else if (t.type === 'number') {
+      parts.push(String(t.value))
+    } else if (t.type === 'token') {
+      const tokenValue = t.value as Record<string, unknown>
+      if (tokenValue.type === 'ident') {
+        parts.push(tokenValue.value as string)
+      } else if (tokenValue.type === 'string') {
+        parts.push(`"${tokenValue.value}"`)
+      }
+    }
+  }
+
+  return parts.join(' ')
+}
+
+function toHex(n: number): string {
+  return Math.round(n).toString(16).padStart(2, '0')
+}
+
+/**
+ * Converts a property name enum to a CSS property string
+ */
+function propertyNameToString(property: string): string {
+  // lightningcss provides property names in kebab-case format
+  // Handle both string names and enum values
+  if (typeof property === 'string') {
+    // Convert camelCase to kebab-case if needed
+    return property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+  }
+  return String(property)
+}
+
+/**
+ * Converts a declaration AST back to a CSS string using lightningcss's own serializer.
+ * This approach uses lightningcss transform with a visitor to inject the AST node
+ * into a dummy rule, then extracts the serialized value from the output.
+ */
+function propertyValueToString(decl: { value: unknown; property: string }): string {
+  try {
+    // Create a dummy CSS rule with a placeholder value
+    const dummyCss = `.x { ${decl.property}: 0; }`
+
+    const result = transform({
+      filename: 'input.css',
+      code: Buffer.from(dummyCss),
+      minify: false,
+      visitor: {
+        // Use property-specific visitor by creating an object with the property name as key
+        Declaration: {
+          [decl.property]: () => decl,
+        } as Record<string, () => typeof decl>,
+      },
+    })
+
+    // Extract just the property value from the output
+    const output = result.code.toString()
+    const match = output.match(/\.x\s*\{\s*([^}]+)\s*\}/)
+
+    if (match) {
+      // Parse the property: value pair and extract just the value
+      const declaration = match[1].trim()
+      const colonIndex = declaration.indexOf(':')
+      if (colonIndex !== -1) {
+        return declaration
+          .slice(colonIndex + 1)
+          .trim()
+          .replace(/;$/, '')
+      }
+    }
+
+    return ''
+  } catch {
+    // Fallback for any errors
+    return ''
+  }
+}
+
+/**
+ * Checks if a CSS property value is a shorthand (has multiple space-separated values)
+ * Ignores spaces inside parentheses (like in var() or calc())
+ */
+function isShorthandValue(value: string): boolean {
+  let depth = 0
+  let result = ''
+
+  for (const char of value) {
+    if (char === '(') {
+      depth++
+    } else if (char === ')') {
+      depth--
+    } else if (depth === 0) {
+      result += char
+    }
+  }
+
+  return result.trim().includes(' ')
+}
+
+/**
+ * Escapes special regex characters in a string to use it as a literal pattern
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}