@wix/zero-config-implementation 1.19.0 → 1.21.0

package/dist/information-extractors/css/selector-matcher.d.ts

@@ -1,3 +1,6 @@
 import { ExtractedCssInfo } from '../../index';
 import { ExtractedElement } from '../react/extractors/core/tree-builder';
-export declare function matchCssSelectors(html: string, elements: ExtractedElement[], cssInfos: ExtractedCssInfo[]): ExtractedElement[];
+export declare function matchCssSelectors(html: string, elements: ExtractedElement[], cssInfos: ExtractedCssInfo[]): {
+    elements: ExtractedElement[];
+    varUsedByTraceId: Map<string, Set<string>>;
+};

package/dist/information-extractors/css/types.d.ts

@@ -46,4 +46,14 @@ export interface CSSParserAPI {
      * @returns DOM-matchable selector string or null
      */
     getDomSelector: (selector: string) => string | null;
+    /**
+     * Determines the CSS property type for a custom property based on how it is used.
+     * If all usages of varName are within the same CSS property, returns that property name.
+     * If usages differ, returns the CSS data type inferred from the initial value
+     * ('color', 'length', 'number', or 'string').
+     * Returns undefined if the variable is never used via var().
+     * @param varName - The CSS variable name (with or without --)
+     * @param defaultValue - The initial value string of the custom property
+     */
+    getVarPropertyType: (varName: string, defaultValue: string) => string | undefined;
 }

package/dist/manifest-pipeline.d.ts

@@ -17,6 +17,7 @@ export interface ExtractedCssInfo {
 }
 export interface ComponentInfoWithCss extends CoupledComponentInfo {
     css: ExtractedCssInfo[];
+    varUsedByTraceId: Map<string, Set<string>>;
 }
 /** The result of processing a single component through the manifest pipeline. */
 export interface ProcessComponentResult {

package/dist/wix-type-to-data-type.d.ts

@@ -0,0 +1,6 @@
+import { DATA } from '@wix/zero-config-schema';
+/**
+ * Maps @wix/public-schemas type names (PascalCase) to their DATA_TYPE keys.
+ * Derived from the exports of @wix/public-schemas.
+ */
+export declare const WIX_TYPE_TO_DATA_TYPE: Record<string, keyof typeof DATA.DATA_TYPE>;

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -38,6 +38,7 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
+    "@wix/zero-config-schema": "1.0.0",
     "lightningcss": "^1.31.1"
   },
   "devDependencies": {
@@ -75,5 +76,5 @@
       ]
     }
   },
-  "falconPackageHash": "c023fc2f7c36ad9d9d7f5d3e24b22d292e138350cb6a48ae6964e8a0"
+  "falconPackageHash": "3957b9b1458a26239d8d8e3088fe1996b439e4c7aa91e8add92e1305"
 }

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

@@ -12,16 +12,17 @@
  * resolved type metadata is inconsistent (kind === 'array' but no elementType).
  */
 
+import type { DataItem } from '@wix/zero-config-schema'
+import { DATA, MEDIA } from '@wix/zero-config-schema'
 import type { Result } from 'neverthrow'
 import { err, ok } from 'neverthrow'
 import { ParseError } from '../errors'
 import type { DOMBinding, TrackingStores } from '../information-extractors/react'
 import type { PropInfo, ResolvedType } from '../information-extractors/ts/types'
-import type { DataItem } from '../schema'
-import { DATA, MEDIA } from '../schema'
+import { WIX_TYPE_TO_DATA_TYPE } from '../wix-type-to-data-type'
 import { formatDisplayName } from './utils'
 
-const { DATA_TYPE, WIX_TYPE_TO_DATA_TYPE } = DATA
+const { DATA_TYPE } = DATA
 
 type ParseErrorInstance = InstanceType<typeof ParseError>
 
@@ -376,7 +377,7 @@ function handleSemanticType(dataItem: DataItem, resolvedType: ResolvedType): voi
   dataItem.text = {}
 }
 
-const EVENT_HANDLER_ATTR_TO_DATA_TYPE: Record<string, string> = {
+const EVENT_HANDLER_ATTR_TO_DATA_TYPE: Record<string, (typeof DATA_TYPE)[keyof typeof DATA_TYPE]> = {
   onclick: DATA_TYPE.onClick,
   onchange: DATA_TYPE.onChange,
   onkeypress: DATA_TYPE.onKeyPress,

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

@@ -1,3 +1,12 @@
+import type {
+  CssCustomPropertyItem,
+  CssPropertyItem,
+  DataItem,
+  EditorElement,
+  EditorReactComponent,
+  ElementItem,
+} from '@wix/zero-config-schema'
+import { ELEMENTS } from '@wix/zero-config-schema'
 import type { ComponentInfoWithCss } from '../index'
 import type { MatchedCssData } from '../information-extractors/css/types'
 import type {
@@ -7,15 +16,6 @@ import type {
   ExtractedElement,
   TrackingStores,
 } from '../information-extractors/react'
-import type {
-  CssCustomPropertyItem,
-  CssPropertyItem,
-  DataItem,
-  EditorElement,
-  EditorReactComponent,
-  ElementItem,
-} from '../schema'
-import { ELEMENTS } from '../schema'
 import { findPreferredSemanticClass } from '../utils/css-class'
 import { buildDataItem } from './data-item-builder'
 import { formatDisplayName } from './utils'
@@ -24,22 +24,32 @@ import { formatDisplayName } from './utils'
 const EXCLUDED_PROPS = new Set(['id', 'className', 'elementProps', 'wix'])
 
 export function toEditorReactComponent(component: ComponentInfoWithCss): EditorReactComponent {
+  const nearestCommonAncestorCustomProps = buildNearestCommonAncestorCustomProps(component)
   return {
-    editorElement: buildEditorElement(component),
+    editorElement: buildEditorElement(component, nearestCommonAncestorCustomProps),
   }
 }
 
-function buildEditorElement(component: ComponentInfoWithCss): EditorElement {
+function buildEditorElement(
+  component: ComponentInfoWithCss,
+  nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
+): EditorElement {
   const rootElement = component.elements[0]
   const childElements = rootElement?.children ?? []
+  const rootCustomProps = rootElement ? (nearestCommonAncestorCustomProps.get(rootElement.traceId) ?? {}) : {}
 
   return {
     selector: buildSelector(rootElement),
     displayName: formatDisplayName(component.componentName),
     data: buildData(component.props, component.propUsages),
-    elements: buildElements(childElements, component.innerElementProps, component.propUsages),
+    elements: buildElements(
+      childElements,
+      nearestCommonAncestorCustomProps,
+      component.innerElementProps,
+      component.propUsages,
+    ),
     cssProperties: buildCssProperties(rootElement),
-    cssCustomProperties: buildCssCustomPropertiesForElement(rootElement),
+    cssCustomProperties: rootCustomProps,
   }
 }
 
@@ -75,6 +85,7 @@ function buildData(
 
 function buildElements(
   elements: ExtractedElement[],
+  nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
 ): Record<string, ElementItem> {
@@ -84,7 +95,7 @@ function buildElements(
     const elementData = innerElementProps?.get(element.traceId)
     const data = elementData && propUsages ? buildData(elementData, propUsages) : undefined
     const cssProps = buildCssProperties(element)
-    const cssCustomProps = buildCssCustomPropertiesForElement(element)
+    const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
@@ -95,11 +106,13 @@ function buildElements(
         ...(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
+        // CSS custom properties placed on the Nearest Common Ancestor of all elements that use each variable
         ...(Object.keys(cssCustomProps).length > 0 && { cssCustomProperties: cssCustomProps }),
         // Recursively build nested elements
         elements:
-          element.children.length > 0 ? buildElements(element.children, innerElementProps, propUsages) : undefined,
+          element.children.length > 0
+            ? buildElements(element.children, nearestCommonAncestorCustomProps, innerElementProps, propUsages)
+            : undefined,
       },
     }
   }
@@ -107,6 +120,174 @@ function buildElements(
   return result
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Custom Properties — Nearest Common Ancestor computation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Pre-computes a map of traceId → custom property items to assign to each element.
+ * Each custom property is placed on the nearest common ancestor (Nearest Common Ancestor) of all elements
+ * that use it via var(). Falls back to the element that defines it if unused.
+ */
+function buildNearestCommonAncestorCustomProps(
+  component: ComponentInfoWithCss,
+): Map<string, Record<string, CssCustomPropertyItem>> {
+  const parentMap = buildParentMap(component.elements)
+
+  // Collect default values from matched elements only — this excludes values from theme/modifier
+  // selectors that were not applied during mock rendering (e.g. .component.dark when variant='light').
+  const allCustomPropertyValues = collectMatchedCustomPropertyValues(component.elements)
+
+  // Fall back to the raw CSS scan for any vars not captured by element matching
+  // (e.g. vars defined in a selector that matched no element in the rendered output).
+  for (const cssInfo of component.css) {
+    for (const [varName, defaultValue] of cssInfo.customProperties) {
+      if (!allCustomPropertyValues.has(varName)) {
+        allCustomPropertyValues.set(varName, defaultValue)
+      }
+    }
+  }
+
+  const nearestCommonAncestorCustomProps = new Map<string, Record<string, CssCustomPropertyItem>>()
+
+  for (const [varName, defaultValue] of allCustomPropertyValues) {
+    if (varName === '--display') continue
+
+    const usedByTraceIds = component.varUsedByTraceId.get(varName) ?? new Set<string>()
+
+    let nearestCommonAncestorTraceId: string | undefined
+    if (usedByTraceIds.size > 0) {
+      nearestCommonAncestorTraceId = findNearestCommonAncestor(usedByTraceIds, parentMap)
+    } else {
+      // Fallback: place on the element whose CSS selector defines the variable
+      nearestCommonAncestorTraceId = findDefiningElement(component.elements, varName)
+    }
+
+    if (!nearestCommonAncestorTraceId) continue
+
+    const cssPropertyType = getVarPropertyTypeFromCssInfos(varName, defaultValue, component.css)
+    const cleanVarName = varName.startsWith('--') ? varName.slice(2) : varName
+
+    const existingProps = nearestCommonAncestorCustomProps.get(nearestCommonAncestorTraceId) ?? {}
+    existingProps[cleanVarName] = {
+      defaultValue,
+      ...(cssPropertyType !== undefined && { cssPropertyType }),
+    }
+    nearestCommonAncestorCustomProps.set(nearestCommonAncestorTraceId, existingProps)
+  }
+
+  return nearestCommonAncestorCustomProps
+}
+
+/**
+ * Queries each CSS parser API for the property type of a variable and returns
+ * the first defined result.
+ */
+function getVarPropertyTypeFromCssInfos(
+  varName: string,
+  defaultValue: string,
+  cssInfos: ComponentInfoWithCss['css'],
+): CssCustomPropertyItem['cssPropertyType'] {
+  for (const cssInfo of cssInfos) {
+    const propertyType = cssInfo.api.getVarPropertyType(varName, defaultValue)
+    if (propertyType !== undefined) return propertyType as CssCustomPropertyItem['cssPropertyType']
+  }
+  return undefined
+}
+
+/**
+ * Walks the element tree and collects custom property default values from the CSS selector
+ * matches recorded on each element. Only values from selectors that matched during mock rendering
+ * are included, so theme/modifier variant values (e.g. .component.dark) are excluded when the
+ * corresponding class was not present on the rendered element.
+ */
+function collectMatchedCustomPropertyValues(elements: ExtractedElement[]): Map<string, string> {
+  const values = new Map<string, string>()
+  for (const element of elements) {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    if (matcherData) {
+      for (const [varName, varValue] of Object.entries(matcherData.customProperties)) {
+        if (!values.has(varName)) values.set(varName, varValue)
+      }
+    }
+    for (const [varName, varValue] of collectMatchedCustomPropertyValues(element.children)) {
+      if (!values.has(varName)) values.set(varName, varValue)
+    }
+  }
+  return values
+}
+
+/**
+ * Builds a map of traceId → parent traceId by recursively walking the element tree.
+ */
+function buildParentMap(elements: ExtractedElement[], parentTraceId?: string): Map<string, string> {
+  const parentMap = new Map<string, string>()
+  for (const element of elements) {
+    if (parentTraceId !== undefined) {
+      parentMap.set(element.traceId, parentTraceId)
+    }
+    for (const [childTraceId, childParentTraceId] of buildParentMap(element.children, element.traceId)) {
+      parentMap.set(childTraceId, childParentTraceId)
+    }
+  }
+  return parentMap
+}
+
+/**
+ * Returns the path from the root element down to the given traceId (inclusive).
+ */
+function pathFromRoot(traceId: string, parentMap: Map<string, string>): string[] {
+  const path = [traceId]
+  let currentTraceId = traceId
+  while (parentMap.has(currentTraceId)) {
+    currentTraceId = parentMap.get(currentTraceId) as string
+    path.unshift(currentTraceId)
+  }
+  return path
+}
+
+/**
+ * Finds the nearest common ancestor traceId for a set of element traceIds.
+ * If a single traceId is given, returns it directly.
+ */
+function findNearestCommonAncestor(traceIds: Set<string>, parentMap: Map<string, string>): string {
+  const traceIdList = [...traceIds]
+  if (traceIdList.length === 1) return traceIdList[0]
+
+  const paths = traceIdList.map((traceId) => pathFromRoot(traceId, parentMap))
+  const shortestPathLength = Math.min(...paths.map((path) => path.length))
+
+  let nearestCommonAncestorTraceId = paths[0][0]
+  for (let depth = 0; depth < shortestPathLength; depth++) {
+    const candidateTraceId = paths[0][depth]
+    if (paths.every((path) => path[depth] === candidateTraceId)) {
+      nearestCommonAncestorTraceId = candidateTraceId
+    } else {
+      break
+    }
+  }
+
+  return nearestCommonAncestorTraceId
+}
+
+/**
+ * Finds the traceId of the first element in the tree whose matched CSS rules
+ * define the given custom property (fallback when var() usage is not tracked).
+ */
+function findDefiningElement(elements: ExtractedElement[], varName: string): string | undefined {
+  for (const element of elements) {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    if (matcherData?.customProperties[varName] !== undefined) return element.traceId
+    const childResult = findDefiningElement(element.children, varName)
+    if (childResult !== undefined) return childResult
+  }
+  return undefined
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Properties helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
  * Returns the CSS property values matched for this specific element's selector(s).
  * Reads from css-matcher.matches which is populated by matchCssSelectors.
@@ -146,30 +327,3 @@ function buildCssProperties(element: ExtractedElement | undefined): Record<strin
 
   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/index.ts

@@ -1,6 +1,6 @@
+import type { EditorReactComponent } from '@wix/zero-config-schema'
 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'
@@ -23,7 +23,7 @@ export type {
   ProcessComponentResult,
 } from './manifest-pipeline'
 
-export type { EditorReactComponent } from './schema'
+export type { EditorReactComponent } from '@wix/zero-config-schema'
 
 // Converter
 import { toEditorReactComponent } from './converters'