@wix/zero-config-implementation 1.5.0

package/src/converters/data-item-builder.ts

@@ -0,0 +1,354 @@
+/**
+ * Data Item Builder
+ *
+ * Converts PropInfo (TypeScript prop types) to DataItem (Wix Editor schema).
+ * Handles all TypeScript type kinds: primitives, arrays, objects, unions, functions, etc.
+ *
+ * Unknown or unrecognized types silently fall back to `DATA_TYPE.text` — this is
+ * intentional because new type kinds are expected as the TypeScript type system
+ * evolves, and a text fallback is always a safe default.
+ *
+ * The only real error is an invariant violation in `handleArrayType` when the
+ * resolved type metadata is inconsistent (kind === 'array' but no elementType).
+ */
+
+import { camelCase } from 'case-anything'
+import type { Result } from 'neverthrow'
+import { err, ok } from 'neverthrow'
+import { ParseError } from '../errors'
+import type { PropInfo, ResolvedType } from '../information-extractors/ts/types'
+import type { DataItem } from '../schema'
+import { DATA, MEDIA } from '../schema'
+import { formatDisplayName } from './utils'
+
+const { DATA_TYPE } = DATA
+
+type ParseErrorInstance = InstanceType<typeof ParseError>
+
+/**
+ * Converts a single PropInfo to a DataItem for the Wix Editor component schema.
+ *
+ * @param propInfo - The resolved TypeScript prop information to convert.
+ * @param defaultValue - Optional default value for the data item.
+ * @returns `Ok<DataItem>` on success, `Err<ParseError>` if an invariant is violated
+ *          (e.g. an array type missing its element type).
+ */
+export function buildDataItem(propInfo: PropInfo, defaultValue?: unknown): Result<DataItem, ParseErrorInstance> {
+  const dataItem: DataItem = {
+    displayName: formatDisplayName(propInfo.name),
+  }
+
+  if (defaultValue !== undefined) {
+    dataItem.defaultValue = defaultValue
+  }
+
+  const result = applyResolvedTypeToDataItem(dataItem, propInfo.resolvedType, propInfo)
+  if (result.isErr()) {
+    return err(result.error)
+  }
+
+  return ok(dataItem)
+}
+
+/**
+ * Maps resolved TypeScript type to DataItem configuration by dispatching
+ * to the appropriate handler based on `resolvedType.kind`.
+ *
+ * Unknown type kinds silently fall back to `DATA_TYPE.text`.
+ */
+function applyResolvedTypeToDataItem(
+  dataItem: DataItem,
+  resolvedType: ResolvedType,
+  propInfo: PropInfo,
+): Result<void, ParseErrorInstance> {
+  switch (resolvedType.kind) {
+    case 'primitive':
+      handlePrimitiveType(dataItem, resolvedType, propInfo)
+      return ok(undefined)
+
+    case 'literal':
+      handleLiteralType(dataItem)
+      return ok(undefined)
+
+    case 'enum':
+      handleEnumType(dataItem)
+      return ok(undefined)
+
+    case 'array':
+      return handleArrayType(dataItem, resolvedType)
+
+    case 'object':
+      return handleObjectType(dataItem, resolvedType)
+
+    case 'union':
+      return handleUnionType(dataItem, resolvedType, propInfo)
+
+    case 'function':
+      handleFunctionType(dataItem, propInfo)
+      return ok(undefined)
+
+    case 'semantic':
+      handleSemanticType(dataItem, resolvedType)
+      return ok(undefined)
+
+    default:
+      // Unknown type kind — silently fall back to text
+      dataItem.dataType = DATA_TYPE.text
+      dataItem.text = {}
+      return ok(undefined)
+  }
+}
+
+/**
+ * Handles primitive types (string, number, boolean).
+ * Unrecognized primitives silently fall back to text.
+ */
+function handlePrimitiveType(dataItem: DataItem, resolvedType: ResolvedType, propInfo: PropInfo): void {
+  const typeValue = (resolvedType.value as string | undefined)?.toLowerCase() || propInfo.type.toLowerCase()
+
+  if (typeValue.includes('string')) {
+    dataItem.dataType = DATA_TYPE.text
+    dataItem.text = {}
+  } else if (typeValue.includes('number')) {
+    dataItem.dataType = DATA_TYPE.number
+    dataItem.number = {}
+  } else if (typeValue.includes('boolean')) {
+    dataItem.dataType = DATA_TYPE.booleanValue
+  } else {
+    // Unknown primitive — silently fall back to text
+    dataItem.dataType = DATA_TYPE.text
+    dataItem.text = {}
+  }
+}
+
+/**
+ * Handles literal types (e.g., "red" | "blue").
+ */
+function handleLiteralType(dataItem: DataItem): void {
+  dataItem.dataType = DATA_TYPE.text
+  dataItem.text = {}
+}
+
+/**
+ * Handles enum types.
+ */
+function handleEnumType(dataItem: DataItem): void {
+  dataItem.dataType = DATA_TYPE.textEnum
+  dataItem.textEnum = {
+    options: [],
+  }
+}
+
+/**
+ * Handles array types. Fails with a `ParseError` if the resolved type
+ * has kind 'array' but is missing its `elementType` (invariant violation).
+ */
+function handleArrayType(dataItem: DataItem, resolvedType: ResolvedType): Result<void, ParseErrorInstance> {
+  if (resolvedType.kind !== 'array' || resolvedType.elementType === undefined) {
+    return err(
+      new ParseError('Invalid array type: resolved type has kind "array" but is missing elementType', {
+        props: { phase: 'conversion', isDefect: true },
+      }),
+    )
+  }
+
+  dataItem.dataType = DATA_TYPE.arrayItems
+  const elementDataItem: DataItem = {}
+  const result = applyResolvedTypeToDataItem(elementDataItem, resolvedType.elementType, {
+    name: 'element',
+    required: false,
+    type: resolvedType.elementType.kind,
+    resolvedType: resolvedType.elementType,
+  } satisfies PropInfo)
+
+  if (result.isErr()) {
+    return result
+  }
+
+  dataItem.arrayItems = {
+    dataItem: elementDataItem,
+  }
+
+  return ok(undefined)
+}
+
+/**
+ * Handles object types with nested properties.
+ * Recursively calls `buildDataItem` for each property.
+ */
+function handleObjectType(dataItem: DataItem, resolvedType: ResolvedType): Result<void, ParseErrorInstance> {
+  dataItem.dataType = DATA_TYPE.data
+
+  if (resolvedType.properties) {
+    const nestedItems: Record<string, DataItem> = {}
+
+    for (const [propName, propInfo] of Object.entries(resolvedType.properties)) {
+      const result = buildDataItem(propInfo, undefined)
+      if (result.isErr()) {
+        return err(result.error)
+      }
+      nestedItems[propName] = result.value
+    }
+
+    dataItem.data = {
+      items: nestedItems,
+    }
+  } else {
+    dataItem.data = {
+      items: {},
+    }
+  }
+
+  return ok(undefined)
+}
+
+/**
+ * Handles union types by detecting special patterns (boolean literals,
+ * string literal enums) or falling back to the first valid member type.
+ */
+function handleUnionType(
+  dataItem: DataItem,
+  resolvedType: ResolvedType,
+  propInfo: PropInfo,
+): Result<void, ParseErrorInstance> {
+  if (!resolvedType.types || resolvedType.types.length === 0) {
+    dataItem.dataType = DATA_TYPE.text
+    dataItem.text = {}
+    return ok(undefined)
+  }
+
+  // Filter out undefined and null types
+  const validTypes = resolvedType.types.filter((t) => t.value !== 'undefined' && t.value !== 'null')
+
+  if (validTypes.length === 0) {
+    dataItem.dataType = DATA_TYPE.text
+    dataItem.text = {}
+    return ok(undefined)
+  }
+
+  // Check if it's a boolean type (union of true | false literals)
+  const isBooleanLiteralUnion =
+    validTypes.length <= 2 && validTypes.every((t) => t.kind === 'literal' && (t.value === true || t.value === false))
+  if (isBooleanLiteralUnion) {
+    dataItem.dataType = DATA_TYPE.booleanValue
+    return ok(undefined)
+  }
+
+  // Check if it's a union of string literals (enum-like)
+  const allStringLiterals = validTypes.every((t) => t.kind === 'literal' && typeof t.value === 'string')
+  if (allStringLiterals) {
+    dataItem.dataType = DATA_TYPE.textEnum
+    dataItem.textEnum = {
+      options: validTypes
+        .map((t) => ({
+          value: String(t.value || ''),
+          displayName: formatDisplayName(String(t.value || '')),
+        }))
+        .filter((opt) => opt.value),
+    }
+    return ok(undefined)
+  }
+
+  // For other unions, use the first valid type
+  const firstValidType = validTypes[0]
+  if (firstValidType) {
+    return applyResolvedTypeToDataItem(dataItem, firstValidType, propInfo)
+  }
+
+  dataItem.dataType = DATA_TYPE.text
+  dataItem.text = {}
+  return ok(undefined)
+}
+
+/**
+ * Handles semantic types from React and @wix/public-schemas packages.
+ * Unknown semantic sources or types silently fall back to text.
+ */
+function handleSemanticType(dataItem: DataItem, resolvedType: ResolvedType): void {
+  const semanticValue = resolvedType.value as string
+  const source = resolvedType.source
+
+  // React types - handle containers
+  if (source === '@types/react' || source === 'react') {
+    if (semanticValue === 'ReactNode' || semanticValue === 'ReactElement') {
+      dataItem.dataType = DATA_TYPE.container
+    } else {
+      dataItem.dataType = DATA_TYPE.text
+      dataItem.text = {}
+    }
+    return
+  }
+
+  // Wix public-schemas (Builder) types - map directly to DATA_TYPE via camelCase conversion
+  if (source === '@wix/public-schemas') {
+    const dataTypeKey = camelCase(semanticValue) as keyof typeof DATA_TYPE
+    if (dataTypeKey in DATA_TYPE) {
+      dataItem.dataType = DATA_TYPE[dataTypeKey]
+      applyDataToBuilderType(dataItem, dataTypeKey)
+    } else {
+      // Unknown Wix semantic type — silently fall back to text
+      dataItem.dataType = DATA_TYPE.text
+      dataItem.text = {}
+    }
+    return
+  }
+
+  // Unknown source — silently fall back to text
+  dataItem.dataType = DATA_TYPE.text
+  dataItem.text = {}
+}
+
+/**
+ * Handles function types — maps to event handlers.
+ */
+function handleFunctionType(dataItem: DataItem, propInfo: PropInfo): void {
+  const propName = propInfo.name.toLowerCase()
+
+  if (propName === 'onclick') {
+    dataItem.dataType = DATA_TYPE.onClick
+  } else if (propName === 'onchange') {
+    dataItem.dataType = DATA_TYPE.onChange
+  } else if (propName === 'onkeypress') {
+    dataItem.dataType = DATA_TYPE.onKeyPress
+  } else if (propName === 'onkeyup') {
+    dataItem.dataType = DATA_TYPE.onKeyUp
+  } else if (propName === 'onsubmit') {
+    dataItem.dataType = DATA_TYPE.onSubmit
+  } else {
+    dataItem.dataType = DATA_TYPE.function
+    dataItem.function = {}
+  }
+}
+
+/**
+ * Applies special data to builder types if required (e.g., link types, image category).
+ */
+function applyDataToBuilderType(dataItem: DataItem, builderType: keyof typeof DATA_TYPE): void {
+  switch (builderType) {
+    case 'link':
+      dataItem.dataType = DATA_TYPE.link
+      dataItem.link = {
+        linkTypes: [
+          DATA.LINK_TYPE.externalLink,
+          DATA.LINK_TYPE.anchorLink,
+          DATA.LINK_TYPE.emailLink,
+          DATA.LINK_TYPE.phoneLink,
+          DATA.LINK_TYPE.dynamicPageLink,
+          DATA.LINK_TYPE.pageLink,
+          DATA.LINK_TYPE.whatsAppLink,
+          DATA.LINK_TYPE.documentLink,
+          DATA.LINK_TYPE.popupLink,
+          DATA.LINK_TYPE.addressLink,
+          DATA.LINK_TYPE.edgeAnchorLinks,
+          DATA.LINK_TYPE.loginToWixLink,
+        ],
+      }
+      break
+    case 'image':
+      dataItem.dataType = DATA_TYPE.image
+      dataItem.image = {
+        category: MEDIA.IMAGE_CATEGORY.IMAGE,
+      }
+      break
+  }
+}

package/src/converters/index.ts

@@ -0,0 +1 @@
+export { toEditorReactComponent } from './to-editor-component'

package/src/converters/to-editor-component.ts

@@ -0,0 +1,167 @@
+import type { ComponentInfoWithCss } from '../index'
+import type { MatchedCssData } from '../information-extractors/css/types'
+import type {
+  CoupledComponentInfo,
+  CoupledProp,
+  CssPropertiesData,
+  ExtractedElement,
+} from '../information-extractors/react'
+import type {
+  CssCustomPropertyItem,
+  CssPropertyItem,
+  DataItem,
+  EditorElement,
+  EditorReactComponent,
+  ElementItem,
+} from '../schema'
+import { ELEMENTS } from '../schema'
+import { buildDataItem } from './data-item-builder'
+import { formatDisplayName } from './utils'
+
+// Props to exclude from data items (same as in element-data.ts)
+const EXCLUDED_PROPS = new Set(['id', 'className', 'elementProps', 'wix'])
+
+export function toEditorReactComponent(component: ComponentInfoWithCss): EditorReactComponent {
+  return {
+    editorElement: buildEditorElement(component),
+  }
+}
+
+function buildEditorElement(component: ComponentInfoWithCss): EditorElement {
+  const rootElement = component.elements[0]
+  const childElements = rootElement?.children ?? []
+
+  return {
+    selector: buildSelector(rootElement),
+    displayName: formatDisplayName(component.componentName),
+    data: buildData(component.props),
+    elements: buildElements(childElements, component.innerElementProps),
+    cssProperties: buildCssProperties(rootElement),
+    cssCustomProperties: buildCssCustomPropertiesForElement(rootElement),
+  }
+}
+
+function buildSelector(rootElement?: ExtractedElement): string {
+  if (rootElement?.attributes.class) {
+    return `.${rootElement.attributes.class.split(' ')[0]}`
+  }
+  return rootElement?.tag ?? ''
+}
+
+function buildData(props: Record<string, CoupledProp>): Record<string, DataItem> {
+  const data: Record<string, DataItem> = {}
+
+  for (const [name, prop] of Object.entries(props)) {
+    // Skip excluded props and literals
+    if (EXCLUDED_PROPS.has(name) || prop.resolvedType.kind === 'literal') continue
+
+    // Extract default value for buildDataItem
+    const defaultValue = prop.defaultValue?.kind !== 'unresolved' ? prop.defaultValue?.value : undefined
+
+    const result = buildDataItem(prop, defaultValue)
+    if (result.isOk()) {
+      data[name] = result.value
+    }
+  }
+
+  return data
+}
+
+function buildElements(
+  elements: ExtractedElement[],
+  innerElementProps?: CoupledComponentInfo['innerElementProps'],
+): Record<string, ElementItem> {
+  const result: Record<string, ElementItem> = {}
+
+  for (const el of elements) {
+    const elementData = innerElementProps?.get(el.traceId)
+    const data = elementData ? buildData(elementData) : undefined
+    const cssProps = buildCssProperties(el)
+    const cssCustomProps = buildCssCustomPropertiesForElement(el)
+
+    result[el.name] = {
+      elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
+      inlineElement: {
+        selector: buildSelector(el),
+        displayName: formatDisplayName(el.name),
+        // Add data from inner element props if available
+        ...(data && Object.keys(data).length > 0 && { data }),
+        // CSS properties from heuristic + matched CSS files
+        ...(Object.keys(cssProps).length > 0 && { cssProperties: cssProps }),
+        // CSS custom properties from matched rules for this element
+        ...(Object.keys(cssCustomProps).length > 0 && { cssCustomProperties: cssCustomProps }),
+        // Recursively build nested elements
+        elements: el.children.length > 0 ? buildElements(el.children, innerElementProps) : undefined,
+      },
+    }
+  }
+
+  return result
+}
+
+/**
+ * Returns the CSS property values matched for this specific element's selector(s).
+ * Reads from css-matcher.matches which is populated by matchCssSelectors.
+ * When multiple rules match (e.g. .foo and .foo.dark), later match wins for same property.
+ */
+function getMatchedPropertyValues(element: ExtractedElement): Map<string, string> {
+  const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+  const matches = matcherData?.matches
+  if (!matches || matches.length === 0) return new Map()
+
+  const values = new Map<string, string>()
+  for (const match of matches) {
+    for (const prop of match.properties) {
+      values.set(prop.name, prop.value)
+    }
+  }
+  return values
+}
+
+function buildCssProperties(element: ExtractedElement | undefined): Record<string, CssPropertyItem> {
+  const result: Record<string, CssPropertyItem> = {}
+
+  // Get the CSS properties decided by the heuristic
+  const cssData = element?.extractorData.get('css-properties') as CssPropertiesData | undefined
+  const decidedProperties = cssData?.relevant
+  if (!decidedProperties || decidedProperties.length === 0) {
+    return result
+  }
+  const cssPropertyValues = element ? getMatchedPropertyValues(element) : new Map<string, string>()
+  for (const propName of decidedProperties) {
+    const defaultValue = cssPropertyValues.get(propName)
+    result[propName] = {
+      // Only include defaultValue if found in CSS files
+      ...(defaultValue !== undefined && { defaultValue }),
+    }
+  }
+
+  return result
+}
+
+/**
+ * Build cssCustomProperties for a single element from this element's matched rules only.
+ * Only includes --vars that were declared in a rule that matched this element's selector(s).
+ */
+function buildCssCustomPropertiesForElement(
+  element: ExtractedElement | undefined,
+): Record<string, CssCustomPropertyItem> {
+  const matcherData = element?.extractorData.get('css-matcher') as MatchedCssData | undefined
+  const customProperties = matcherData?.customProperties
+  if (!customProperties || Object.keys(customProperties).length === 0) {
+    return {}
+  }
+
+  const result: Record<string, CssCustomPropertyItem> = {}
+  for (const [name, value] of Object.entries(customProperties)) {
+    // Skip --display (handled in regular properties)
+    if (name === '--display') continue
+
+    // Strip the -- prefix from the name
+    const cleanName = name.startsWith('--') ? name.slice(2) : name
+    result[cleanName] = {
+      defaultValue: value,
+    }
+  }
+  return result
+}

package/src/converters/utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility functions for the converter module
+ */
+
+import { capitalCase } from 'case-anything'
+
+/**
+ * Formats any string format to Title Case display name
+ * Handles: kebab-case, camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE, and mixed formats
+ *
+ * Examples:
+ *   "input-field-weight" -> "Input Field Weight"
+ *   "camelCaseExample" -> "Camel Case Example"
+ *   "PascalCaseExample" -> "Pascal Case Example"
+ *   "snake_case_example" -> "Snake Case Example"
+ *   "SCREAMING_SNAKE_CASE" -> "Screaming Snake Case"
+ *   "mixed-format_example" -> "Mixed Format Example"
+ */
+export function formatDisplayName(input: string): string {
+  return capitalCase(input, { keepSpecialCharacters: false })
+}

package/src/errors.ts

@@ -0,0 +1,103 @@
+/**
+ * Error class hierarchy using modern-errors and modern-errors-cli.
+ *
+ * Classes are organized by **failure type** (what went wrong), not by pipeline
+ * phase (where it happened). Phase is an orthogonal runtime property composed
+ * onto any error instance via `mapErr` or instance `props`.
+ */
+
+import ModernError from 'modern-errors'
+import modernErrorsCli from 'modern-errors-cli'
+
+// ---------------------------------------------------------------------------
+// Base Error
+// ---------------------------------------------------------------------------
+
+/**
+ * Root error class for the entire project. All domain errors extend this.
+ *
+ * Plugins attached here cascade to every subclass automatically.
+ * The `phase` prop defaults to `"unknown"` and is overridden at the call
+ * site or via `mapErr` as the error propagates through pipeline stages.
+ */
+export const BaseError = ModernError.subclass('BaseError', {
+  plugins: [modernErrorsCli],
+  props: {
+    /** Pipeline stage where the error originated (composed at runtime). */
+    phase: 'unknown' as string,
+    /** True if this error represents a violated invariant, not a user error. */
+    isDefect: false,
+    /** Process exit code used by BaseError.exit(). */
+    exitCode: 1,
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Domain Subclasses — organized by failure type
+// ---------------------------------------------------------------------------
+
+/** A required resource (file, module, component) could not be found. */
+export const NotFoundError = BaseError.subclass('NotFoundError')
+
+/** Data could not be parsed or decoded (JSON, source code, config, CSS). */
+export const ParseError = BaseError.subclass('ParseError')
+
+/** Input or data does not satisfy validation rules. */
+export const ValidationError = BaseError.subclass('ValidationError')
+
+/** File system or network I/O failed (permissions, disk full, timeout). */
+export const IoError = BaseError.subclass('IoError')
+
+// ---------------------------------------------------------------------------
+// Defect Error
+// ---------------------------------------------------------------------------
+
+/**
+ * Represents an unexpected internal failure — a violated invariant or
+ * impossible state that should never occur during normal operation.
+ *
+ * Exit code 70 (EX_SOFTWARE) signals an internal software error.
+ */
+export const DefectError = BaseError.subclass('DefectError', {
+  props: {
+    phase: 'internal',
+    isDefect: true,
+    exitCode: 70,
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Defect Boundary
+// ---------------------------------------------------------------------------
+
+const REPO_ISSUES_URL = 'https://github.com/wix-private/ZeroConfig/issues'
+
+/**
+ * Wrap an async entry point with a defect boundary.
+ *
+ * If the wrapped function throws an exception (i.e. a defect that was not
+ * captured as a Result), it is caught, wrapped in a DefectError, and printed
+ * via BaseError.exit().
+ *
+ * @param fn - The entry point function to wrap
+ * @throws {DefectError} If an unexpected exception occurs during execution
+ */
+export async function withDefectBoundary(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn()
+  } catch (thrown) {
+    const normalized = BaseError.normalize(thrown)
+
+    if (normalized instanceof BaseError) {
+      BaseError.exit(normalized)
+      return
+    }
+
+    const defect = new DefectError(
+      `[DEFECT] An unexpected internal error occurred — please report at ${REPO_ISSUES_URL}`,
+      { cause: normalized },
+    )
+
+    BaseError.exit(defect)
+  }
+}