@wix/zero-config-implementation 1.5.0

package/src/manifest-pipeline.ts

@@ -0,0 +1,362 @@
+import fs from 'node:fs'
+
+import type { ComponentInfo } from './information-extractors/ts'
+import type { PropInfo } from './information-extractors/ts/types'
+
+import {
+  type ExtractedElement,
+  type PropTrackerData,
+  createCssPropertiesExtractor,
+  createPropTrackerExtractor,
+  runExtractors,
+} from './information-extractors/react'
+import type { CoupledComponentInfo, CoupledProp, DOMBinding, TrackingStores } from './information-extractors/react'
+
+import { matchCssSelectors, parseCss } from './information-extractors/css'
+import type { CSSParserAPI } from './information-extractors/css'
+
+import type { ComponentType } from 'react'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A non-fatal issue encountered during component processing. */
+export interface ExtractionWarning {
+  componentName: string
+  phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion'
+  error: string
+}
+
+export interface ExtractedCssInfo {
+  filePath: string
+  api: CSSParserAPI
+  properties: Map<string, string>
+  customProperties: Map<string, string>
+}
+
+export interface ComponentInfoWithCss extends CoupledComponentInfo {
+  css: ExtractedCssInfo[]
+}
+
+/** The result of processing a single component through the manifest pipeline. */
+export interface ProcessComponentResult {
+  component: ComponentInfoWithCss
+  warnings: ExtractionWarning[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Component Processing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Processes a single component through the full manifest pipeline:
+ * loading, rendering with prop tracking, CSS extraction, and selector matching.
+ *
+ * Returns the enriched component info alongside any non-fatal warnings
+ * encountered during processing. Always returns a component, falling back
+ * to minimal info (without DOM coupling) when rendering fails.
+ */
+export function processComponent(
+  componentInfo: ComponentInfo,
+  loadComponent: (componentName: string) => ComponentType<unknown> | null,
+  cssImportPaths: string[],
+  loaderHasError?: boolean,
+): ProcessComponentResult {
+  const warnings: ExtractionWarning[] = []
+
+  // Load the actual component
+  let Component: ComponentType<unknown> | null = null
+  try {
+    Component = loadComponent(componentInfo.componentName)
+    if (!Component && !loaderHasError) {
+      warnings.push({
+        componentName: componentInfo.componentName,
+        phase: 'loader',
+        error: `Component "${componentInfo.componentName}" not found in package exports`,
+      })
+    }
+  } catch (error) {
+    if (!loaderHasError) {
+      warnings.push({
+        componentName: componentInfo.componentName,
+        phase: 'loader',
+        error: `Failed to load "${componentInfo.componentName}": ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+
+  let coupledInfo: CoupledComponentInfo | null = null
+  let enhancedInfo: CoupledComponentInfo
+  let html: string | undefined
+  let extractedElements: ExtractedElement[] = []
+
+  // Render component with mock props and track prop flow (can fail)
+  if (Component) {
+    try {
+      const { extractor: propTracker, state } = createPropTrackerExtractor()
+      const cssExtractor = createCssPropertiesExtractor()
+
+      const result = runExtractors(componentInfo, Component, [propTracker, cssExtractor])
+      html = result.html
+      extractedElements = result.elements
+
+      const { props: coupledProps, innerElementProps } = buildCoupledProps(componentInfo, state.stores)
+      coupledInfo = {
+        componentName: componentInfo.componentName,
+        props: coupledProps,
+        elements: convertElements(extractedElements),
+        innerElementProps: innerElementProps.size > 0 ? innerElementProps : undefined,
+      }
+    } catch (error) {
+      warnings.push({
+        componentName: componentInfo.componentName,
+        phase: 'render',
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  // If rendering succeeded, use the coupled info directly
+  // (CSS properties are now embedded via css-properties-extractor)
+  if (coupledInfo) {
+    enhancedInfo = coupledInfo
+  } else {
+    // Fallback: create minimal info without DOM coupling
+    enhancedInfo = {
+      componentName: componentInfo.componentName,
+      props: Object.fromEntries(
+        Object.entries(componentInfo.props).map(([name, info]) => [name, { ...info, bindings: [], logicOnly: false }]),
+      ),
+      elements: [],
+    }
+  }
+
+  // Read and parse CSS imports
+  const { cssInfos: css, warnings: cssWarnings } = extractCssInfo(cssImportPaths, componentInfo.componentName)
+  warnings.push(...cssWarnings)
+
+  // Match CSS selectors to elements
+  if (html && extractedElements.length > 0 && css.length > 0) {
+    try {
+      const enrichedElements = matchCssSelectors(html, extractedElements, css)
+      enhancedInfo = {
+        ...enhancedInfo,
+        elements: convertElements(enrichedElements),
+      }
+    } catch (error) {
+      warnings.push({
+        componentName: componentInfo.componentName,
+        phase: 'css',
+        error: `CSS selector matching failed: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+
+  return {
+    component: {
+      ...enhancedInfo,
+      css,
+    },
+    warnings,
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Prop Coupling Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildCoupledProps(
+  componentInfo: ComponentInfo,
+  stores: TrackingStores,
+): { props: Record<string, CoupledProp>; innerElementProps: Map<string, Record<string, CoupledProp>> } {
+  const result: Record<string, CoupledProp> = {}
+
+  for (const [name, info] of Object.entries(componentInfo.props)) {
+    const path = `props.${name}`
+    const wasRead = stores.reads.has(path)
+    const writeInfo = stores.writes.get(path)
+
+    result[name] = {
+      ...info,
+      logicOnly: wasRead && !writeInfo,
+      bindings: writeInfo ? extractBindings(writeInfo) : [],
+    }
+  }
+
+  const innerElementProps = processElementPropsWrites(componentInfo, stores)
+
+  return { props: result, innerElementProps }
+}
+
+const ELEMENT_PROPS_PREFIX = 'props.elementProps.'
+
+/**
+ * Processes stores.writes entries with paths starting with "props.elementProps."
+ * to extract inner element prop bindings grouped by elementId (traceId).
+ */
+function processElementPropsWrites(
+  componentInfo: ComponentInfo,
+  stores: TrackingStores,
+): Map<string, Record<string, CoupledProp>> {
+  const result = new Map<string, Record<string, CoupledProp>>()
+
+  const elementPropsInfo = componentInfo.props.elementProps
+  if (!elementPropsInfo) return result
+
+  for (const [path, writeInfo] of stores.writes) {
+    if (!path.startsWith(ELEMENT_PROPS_PREFIX)) continue
+
+    // Resolve the PropInfo for this leaf prop by walking the type tree
+    const relativePath = path.slice(ELEMENT_PROPS_PREFIX.length) // e.g. "navbar.items"
+    const propInfo = resolveInnerPropInfo(elementPropsInfo, relativePath)
+    if (!propInfo) continue
+
+    const bindings = extractBindings(writeInfo)
+
+    // Group by elementId from the bindings
+    for (const binding of bindings) {
+      const { elementId } = binding
+      let propsForElement = result.get(elementId)
+      if (!propsForElement) {
+        propsForElement = {}
+        result.set(elementId, propsForElement)
+      }
+
+      const leafName = propInfo.name
+      if (!propsForElement[leafName]) {
+        propsForElement[leafName] = {
+          ...propInfo,
+          logicOnly: false,
+          bindings: [],
+        }
+      }
+      propsForElement[leafName].bindings.push(binding)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Walks the elementProps resolved type tree by path segments to find the leaf PropInfo.
+ * e.g., path "navbar.items" -> walk elementProps type -> navbar property -> items property
+ * Handles recursive nesting: "hamburgerMenu.elementProps.hamburgerCloseButton.label"
+ */
+function resolveInnerPropInfo(elementPropsPropInfo: PropInfo, relativePath: string): PropInfo | null {
+  const segments = relativePath.split('.')
+  let currentType = elementPropsPropInfo.resolvedType
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    if (!currentType.properties) return null
+
+    const propInfo = currentType.properties[segment]
+    if (!propInfo) return null
+
+    // If this is the last segment, return the PropInfo
+    if (i === segments.length - 1) {
+      return propInfo
+    }
+
+    // Otherwise, descend into this property's resolved type
+    currentType = propInfo.resolvedType
+  }
+
+  return null
+}
+
+function extractBindings(writeInfo: TrackingStores['writes'] extends Map<string, infer V> ? V : never): DOMBinding[] {
+  const bindings: DOMBinding[] = []
+
+  for (const [key, attrInfo] of writeInfo.attributes) {
+    const elementId = key.split(':')[0]
+    const elementInfo = writeInfo.elements.get(elementId)
+    if (elementInfo) {
+      bindings.push({
+        element: elementInfo.tag,
+        attribute: attrInfo.attr,
+        concatenated: attrInfo.concatenated,
+        elementId: elementInfo.elementId,
+      })
+    }
+  }
+
+  return bindings
+}
+
+function convertElements(elements: ExtractedElement[]): CoupledComponentInfo['elements'] {
+  return elements.map((el) => {
+    // Get prop-tracker data for boundProps
+    const propTrackerData = el.extractorData.get('prop-tracker') as PropTrackerData | undefined
+
+    return {
+      traceId: el.traceId,
+      name: el.name,
+      tag: el.tag,
+      attributes: el.attributes,
+      extractorData: el.extractorData,
+      children: convertElements(el.children),
+      // Legacy fields
+      boundProps: propTrackerData?.boundProps ?? [],
+      role: propTrackerData?.role,
+      hasTextContent: el.hasTextContent,
+    }
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Reads and parses CSS files, extracting standard and custom properties.
+ * Returns the parsed CSS info alongside any warnings from files that failed to parse.
+ */
+function extractCssInfo(
+  cssImportPaths: string[],
+  componentName: string,
+): { cssInfos: ExtractedCssInfo[]; warnings: ExtractionWarning[] } {
+  const cssInfos: ExtractedCssInfo[] = []
+  const warnings: ExtractionWarning[] = []
+
+  for (const cssPath of cssImportPaths) {
+    try {
+      // Read CSS file
+      const cssContent = fs.readFileSync(cssPath, 'utf-8')
+
+      // Parse CSS
+      const api = parseCss(cssContent)
+      const allProps = api.getAllProperties()
+
+      // Extract regular properties and custom properties (CSS variables)
+      const properties = new Map<string, string>()
+      const customProperties = new Map<string, string>()
+
+      for (const [, props] of allProps) {
+        for (const prop of props) {
+          if (prop.name.startsWith('--')) {
+            customProperties.set(prop.name, prop.value)
+          } else {
+            properties.set(prop.name, prop.value)
+          }
+        }
+      }
+
+      cssInfos.push({
+        filePath: cssPath,
+        api,
+        properties,
+        customProperties,
+      })
+    } catch (error) {
+      warnings.push({
+        componentName,
+        phase: 'css',
+        error: `Failed to parse ${cssPath}: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+
+  return { cssInfos, warnings }
+}

package/src/schema.ts

@@ -0,0 +1,174 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// Extracted verbatim from @wix/component-protocol (chunk-U3HQJA7D.js).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DATA_TYPE = {
+  UNKNOWN_DataType: 'UNKNOWN_DataType',
+  text: 'text',
+  textEnum: 'textEnum',
+  number: 'number',
+  booleanValue: 'booleanValue',
+  a11y: 'a11y',
+  link: 'link',
+  image: 'image',
+  video: 'video',
+  vectorArt: 'vectorArt',
+  audio: 'audio',
+  schema: 'schema',
+  localDate: 'localDate',
+  localTime: 'localTime',
+  localDateTime: 'localDateTime',
+  webUrl: 'webUrl',
+  email: 'email',
+  phone: 'phone',
+  hostname: 'hostname',
+  regex: 'regex',
+  guid: 'guid',
+  richText: 'richText',
+  container: 'container',
+  arrayItems: 'arrayItems',
+  direction: 'direction',
+  menuItems: 'menuItems',
+  data: 'data',
+  function: 'function',
+  onClick: 'onClick',
+  onChange: 'onChange',
+  onKeyPress: 'onKeyPress',
+  onKeyUp: 'onKeyUp',
+  onSubmit: 'onSubmit',
+} as const
+
+const A11Y_ATTRIBUTES = {
+  Unknown_AriaAttributes: 'Unknown_AriaAttributes',
+  tabIndex: 'tabIndex',
+  ariaLevel: 'ariaLevel',
+  ariaExpanded: 'ariaExpanded',
+  ariaDisabled: 'ariaDisabled',
+  ariaAtomic: 'ariaAtomic',
+  ariaHidden: 'ariaHidden',
+  ariaBusy: 'ariaBusy',
+  multiline: 'multiline',
+  ariaAutocomplete: 'ariaAutocomplete',
+  ariaPressed: 'ariaPressed',
+  ariaHaspopup: 'ariaHaspopup',
+  ariaRelevant: 'ariaRelevant',
+  role: 'role',
+  ariaLive: 'ariaLive',
+  ariaCurrent: 'ariaCurrent',
+  ariaLabel: 'ariaLabel',
+  ariaRoledescription: 'ariaRoledescription',
+  ariaDescribedby: 'ariaDescribedby',
+  ariaLabelledby: 'ariaLabelledby',
+  ariaErrormessage: 'ariaErrormessage',
+  ariaOwns: 'ariaOwns',
+  ariaControls: 'ariaControls',
+  tag: 'tag',
+  ariaMultiline: 'ariaMultiline',
+  ariaInvalid: 'ariaInvalid',
+} as const
+
+const LINK_TYPE = {
+  UNKNOWN_LinkType: 'UNKNOWN_LinkType',
+  externalLink: 'externalLink',
+  anchorLink: 'anchorLink',
+  emailLink: 'emailLink',
+  phoneLink: 'phoneLink',
+  dynamicPageLink: 'dynamicPageLink',
+  pageLink: 'pageLink',
+  whatsAppLink: 'whatsAppLink',
+  documentLink: 'documentLink',
+  popupLink: 'popupLink',
+  addressLink: 'addressLink',
+  edgeAnchorLinks: 'edgeAnchorLinks',
+  loginToWixLink: 'loginToWixLink',
+} as const
+
+const IMAGE_CATEGORY = {
+  UNKNOWN_CategoryName: 'UNKNOWN_CategoryName',
+  IMAGE: 'IMAGE',
+  IMAGE_BACKGROUND: 'IMAGE_BACKGROUND',
+} as const
+
+const VIDEO_CATEGORY = {
+  UNKNOWN_VideoCategoryTypes: 'UNKNOWN_VideoCategoryTypes',
+  VIDEO: 'VIDEO',
+  VIDEO_TRANSPARENT: 'VIDEO_TRANSPARENT',
+  VIDEO_OPAQUE: 'VIDEO_OPAQUE',
+} as const
+
+const VECTOR_ART_CATEGORY = {
+  UNKNOWN_VectorArtCategoryTypes: 'UNKNOWN_VectorArtCategoryTypes',
+  SHAPE_ALL: 'SHAPE_ALL',
+  SHAPE_BASIC: 'SHAPE_BASIC',
+  SHAPE_ART: 'SHAPE_ART',
+  ICON_SOCIAL: 'ICON_SOCIAL',
+  SHAPE_DIVIDERS: 'SHAPE_DIVIDERS',
+  SHAPE_LOCATION: 'SHAPE_LOCATION',
+  SHAPE_DOCUMENTS: 'SHAPE_DOCUMENTS',
+  SHAPE_SOCIAL: 'SHAPE_SOCIAL',
+  SHAPE_ARROWS: 'SHAPE_ARROWS',
+} as const
+
+const ELEMENT_TYPE = {
+  UNKNOWN_ElementType: 'UNKNOWN_ElementType',
+  inlineElement: 'inlineElement',
+  refElement: 'refElement',
+} as const
+
+export const DATA = { DATA_TYPE, A11Y_ATTRIBUTES, LINK_TYPE }
+export const MEDIA = { VIDEO_CATEGORY, VECTOR_ART_CATEGORY, IMAGE_CATEGORY }
+export const ELEMENTS = { ELEMENT_TYPE }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// Minimal stubs matching only the properties accessed in this codebase.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DataItem {
+  displayName?: string
+  defaultValue?: unknown
+  dataType?: string
+  text?: Record<string, unknown>
+  number?: Record<string, unknown>
+  booleanValue?: unknown
+  textEnum?: { options: Array<{ value: string; displayName?: string }> }
+  arrayItems?: { dataItem?: DataItem }
+  data?: { items?: Record<string, DataItem> }
+  function?: Record<string, unknown>
+  link?: { linkTypes?: string[] }
+  image?: { category?: string }
+}
+
+export interface CssPropertyItem {
+  defaultValue?: string
+}
+
+export interface CssCustomPropertyItem {
+  defaultValue?: string
+}
+
+export interface EditorElement {
+  selector?: string
+  displayName?: string
+  data?: Record<string, DataItem>
+  elements?: Record<string, ElementItem>
+  cssProperties?: Record<string, CssPropertyItem>
+  cssCustomProperties?: Record<string, CssCustomPropertyItem>
+}
+
+export interface ElementItem {
+  elementType?: string
+  inlineElement?: {
+    selector?: string
+    displayName?: string
+    data?: Record<string, DataItem>
+    cssProperties?: Record<string, CssPropertyItem>
+    cssCustomProperties?: Record<string, CssCustomPropertyItem>
+    elements?: Record<string, ElementItem>
+  }
+}
+
+export interface EditorReactComponent {
+  editorElement?: EditorElement
+}

package/src/ts-compiler.ts

@@ -0,0 +1,41 @@
+import * as fs from 'node:fs'
+import path from 'node:path'
+import { ResultAsync, errAsync } from 'neverthrow'
+import { parseNative } from 'tsconfck'
+import ts from 'typescript'
+import { NotFoundError, ParseError } from './errors'
+
+/**
+ * Compile a TypeScript file into a ts.Program.
+ *
+ * @param filePath - Path to the TypeScript source file
+ * @returns The compiled TypeScript program on success
+ * @errors
+ * - {@link NotFoundError} — Source file does not exist (phase: `compile`)
+ * - {@link ParseError} — TypeScript config could not be parsed (phase: `compile`)
+ */
+export function compileTsFile(
+  filePath: string,
+): ResultAsync<ts.Program, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError>> {
+  const resolvedPath = path.resolve(filePath)
+
+  if (!fs.existsSync(resolvedPath)) {
+    return errAsync(new NotFoundError(`File not found: ${resolvedPath}`, { props: { phase: 'compile' } }))
+  }
+
+  return ResultAsync.fromPromise(
+    parseNative(resolvedPath),
+    (error) =>
+      new ParseError(`Failed to parse TypeScript config for ${resolvedPath}`, {
+        cause: error as Error,
+        props: { phase: 'compile' },
+      }),
+  ).map(({ tsconfig, tsconfigFile }) => {
+    // Parse the JSON config through TypeScript's API to handle inheritance,
+    // convert string values (like "ES2020") to enum values, and process extends
+    const configDir = path.dirname(tsconfigFile)
+    const parsedConfig = ts.parseJsonConfigFileContent(tsconfig, ts.sys, configDir)
+
+    return ts.createProgram([filePath], parsedConfig.options)
+  })
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/typedoc.json

@@ -0,0 +1,18 @@
+{
+    "entryPoints": [
+        "./src"
+    ],
+    "entryPointStrategy": "expand",
+    "out": "docs-audit",
+    "plugin": [
+        "typedoc-plugin-markdown"
+    ],
+    "readme": "none",
+    "githubPages": false,
+    "disableSources": true,
+    "cleanOutputDir": true,
+    "excludePrivate": false,
+    "excludeProtected": false,
+    "excludeInternal": false,
+    "excludeExternals": false
+}

package/vite.config.ts

@@ -0,0 +1,45 @@
+import { builtinModules } from 'node:module'
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: ['src/**/*.ts'],
+      exclude: ['**/*.test.ts'],
+    }),
+  ],
+  build: {
+    lib: {
+      entry: {
+        index: resolve(__dirname, 'src/index.ts'),
+        'jsx-runtime-interceptor': resolve(__dirname, 'src/jsx-runtime-interceptor.ts'),
+        'jsx-runtime-loader': resolve(__dirname, 'src/jsx-runtime-loader.ts'),
+      },
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: (id) => {
+        // Externalize Node.js built-ins (both node: prefixed and bare), typescript (peer dep), and lightningcss (native bindings)
+        if (id.startsWith('node:') || builtinModules.includes(id) || ['typescript', 'lightningcss'].includes(id)) {
+          return true
+        }
+        return false
+      },
+    },
+    outDir: 'dist',
+  },
+  resolve: {
+    // Ensure Node.js-specific export conditions are used when bundling for Node
+    conditions: ['node', 'import', 'module', 'default'],
+    alias: {
+      // Alias jsx-runtime to our interceptable version for tests
+      'react/jsx-runtime': resolve(__dirname, 'src/jsx-runtime-interceptor.ts'),
+      'react/jsx-dev-runtime': resolve(__dirname, 'src/jsx-runtime-interceptor.ts'),
+    },
+  },
+  test: {
+    globals: true,
+  },
+})