@wix/zero-config-implementation 1.89.0 → 1.91.0

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.89.0",
+  "version": "1.91.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -106,5 +106,5 @@
       ]
     }
   },
-  "falconPackageHash": "c9dcb49c34e33e60436cbc45d7c84a7433975392a119386339f5495f"
+  "falconPackageHash": "7232f116f870e20fe94caa49ba503a0a945ec4eed14c9f9b55544590"
 }

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

@@ -225,6 +225,91 @@ describe('toEditorReactComponent — @property design tokens', () => {
     })
   })
 
+  it('carries the --min / --max / --step descriptors of a number @property into number limits', () => {
+    const component = createComponentWithCss(`
+      @property --speed { syntax: "<number>"; inherits: true; initial-value: 4; --min: 1; --max: 10; --step: 0.5; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.speed).toEqual({
+      displayName: 'Speed',
+      defaultValue: '4',
+      cssPropertyType: 'number',
+      number: { min: '1', max: '10', multiplier: '0.5' },
+    })
+  })
+
+  it('emits only the usable half of a partial range and omits the rest', () => {
+    const component = createComponentWithCss(`
+      @property --weight { syntax: "<number>"; inherits: true; initial-value: 2; --min: 0; }
+      @property --tempo { syntax: "<number>"; inherits: true; initial-value: 3; --max: 9; --step: nonsense; }
+      @property --offset { syntax: "<number>"; inherits: true; initial-value: 0; --min: ; --max: 12; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.weight).toEqual({
+      displayName: 'Weight',
+      defaultValue: '2',
+      cssPropertyType: 'number',
+      number: { min: '0' },
+    })
+    expect(customProps?.tempo).toEqual({
+      displayName: 'Tempo',
+      defaultValue: '3',
+      cssPropertyType: 'number',
+      number: { max: '9' },
+    })
+    expect(customProps?.offset).toEqual({
+      displayName: 'Offset',
+      defaultValue: '0',
+      cssPropertyType: 'number',
+      number: { max: '12' },
+    })
+  })
+
+  it('drops an inverted range and a non-positive step, omitting `number` when nothing is usable', () => {
+    const component = createComponentWithCss(`
+      @property --span { syntax: "<number>"; inherits: true; initial-value: 5; --min: 10; --max: 2; --step: 0; }
+      @property --frozen { syntax: "<number>"; inherits: true; initial-value: 5; --min: 5; --max: 5; --step: 1; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.span).toEqual({
+      displayName: 'Span',
+      defaultValue: '5',
+      cssPropertyType: 'number',
+    })
+    expect(customProps?.frozen).toEqual({
+      displayName: 'Frozen',
+      defaultValue: '5',
+      cssPropertyType: 'number',
+      number: { multiplier: '1' },
+    })
+  })
+
+  it('ignores range descriptors on a non-number @property', () => {
+    const component = createComponentWithCss(`
+      @property --sdf-safelight-color { syntax: "<color>"; inherits: true; initial-value: #F02011; --min: 1; --max: 10; }
+      @property --gap { syntax: "<length>"; inherits: true; initial-value: 4px; --min: 1; --max: 10; --step: 1; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.['sdf-safelight-color']).toEqual({
+      displayName: 'Sdf Safelight Color',
+      defaultValue: '#F02011',
+      cssPropertyType: 'color',
+    })
+    expect(customProps?.gap).toEqual({
+      displayName: 'Gap',
+      defaultValue: '4px',
+      cssPropertyType: 'length',
+    })
+  })
+
   it('emits a customEnum dropdown for a pipe-separated ident-list @property', () => {
     const component = createComponentWithCss(`
       @property --sdf-palette { syntax: "warm | cool | neutral"; inherits: false; initial-value: warm; }

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

@@ -1,5 +1,6 @@
 import type {
   CssCustomPropertyItem,
+  CssNumber,
   CssPropertyItem,
   CustomPropertyEnum,
   DataItem,
@@ -324,6 +325,7 @@ function buildNearestCommonAncestorCustomProps(
       ? registration.cssPropertyType
       : getVarPropertyTypeFromCssInfos(varName, defaultValue ?? '', component.css)
     const customEnum = buildCustomEnum(registration)
+    const numberLimits = buildCssNumber(registration, cssPropertyType)
     const cleanVarName = varName.startsWith('--') ? varName.slice(2) : varName
 
     const existingProps = nearestCommonAncestorCustomProps.get(nearestCommonAncestorTraceId) ?? {}
@@ -332,6 +334,7 @@ function buildNearestCommonAncestorCustomProps(
       ...(defaultValue !== undefined && { defaultValue }),
       ...(cssPropertyType !== undefined && { cssPropertyType }),
       ...(customEnum && { customEnum }),
+      ...(numberLimits && { number: numberLimits }),
     }
     nearestCommonAncestorCustomProps.set(nearestCommonAncestorTraceId, existingProps)
   }
@@ -368,6 +371,42 @@ function buildCustomEnum(registration: RegisteredCustomProperty | undefined): Cu
   }
 }
 
+function parseFiniteDescriptor(rawValue: string | undefined): number | undefined {
+  const trimmed = rawValue?.trim()
+  if (!trimmed) return undefined
+  const parsed = Number(trimmed)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/**
+ * Builds the clamp the panel's number control applies, from an @property's range
+ * descriptors. Anything unusable is dropped rather than passed through.
+ */
+function buildCssNumber(
+  registration: RegisteredCustomProperty | undefined,
+  cssPropertyType: CssCustomPropertyItem['cssPropertyType'],
+): CssNumber | undefined {
+  if (!registration?.range || cssPropertyType !== CSS_PROPERTIES.CSS_DATA_TYPE.number) return undefined
+
+  let min = parseFiniteDescriptor(registration.range.min)
+  let max = parseFiniteDescriptor(registration.range.max)
+  if (min !== undefined && max !== undefined && min >= max) {
+    min = undefined
+    max = undefined
+  }
+
+  const step = parseFiniteDescriptor(registration.range.step)
+  const multiplier = step !== undefined && step > 0 ? step : undefined
+
+  if (min === undefined && max === undefined && multiplier === undefined) return undefined
+
+  return {
+    ...(min !== undefined && { min: String(min) }),
+    ...(max !== undefined && { max: String(max) }),
+    ...(multiplier !== undefined && { multiplier: String(multiplier) }),
+  }
+}
+
 /**
  * Queries each CSS parser API for the property type of a variable and returns
  * the first defined result.

package/src/index.ts

@@ -3,7 +3,7 @@ import { Result, ResultAsync } from 'neverthrow'
 import React, { type ComponentType } from 'react'
 
 import { toEditorReactComponent } from './converters'
-import { BaseError, IoError, type NotFoundError, ParseError } from './errors'
+import { BaseError, IoError, type NotFoundError, ParseError, type ValidationError } from './errors'
 import { buildContextProviderModules } from './extensions/context-providers/context'
 import { buildContextAwareWrapper, loadMockProviders } from './extensions/context-providers/mock-provider'
 import { buildRefElementContext } from './extensions/ref-elements/context'
@@ -16,6 +16,7 @@ import type { ComponentInfo } from './information-extractors/ts/types'
 import { processComponent } from './manifest-pipeline'
 import { findComponent, findDefaultComponent, loadModuleForExtraction } from './module-loader'
 import { compileTsFile } from './ts-compiler'
+import { validateEditorElement } from './validators/editor-element-validator'
 
 const defaultWrapper = wrapWithWixServices
 
@@ -52,7 +53,10 @@ export function extractComponentManifestResult(
   options?: ExtractComponentManifestOptions,
 ): ResultAsync<
   ManifestResult,
-  InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError> | InstanceType<typeof IoError>
+  | InstanceType<typeof NotFoundError>
+  | InstanceType<typeof ParseError>
+  | InstanceType<typeof IoError>
+  | InstanceType<typeof ValidationError>
 > {
   // Step 1: Compile TypeScript (fatal)
   return compileTsFile(componentPath)
@@ -206,7 +210,11 @@ async function processComponentWithCleanup(
       throw processResult.error
     }
 
-    return { component: toEditorReactComponent(processResult.component), errors: [] }
+    const editorReactComponent = toEditorReactComponent(processResult.component)
+    if (editorReactComponent.editorElement) {
+      validateEditorElement(editorReactComponent.editorElement, processResult.component.componentName)
+    }
+    return { component: editorReactComponent, errors: [] }
   } finally {
     await cleanup()
   }

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

@@ -9,6 +9,7 @@ import type {
   CssDataType,
   NativePseudoClass,
   RegisteredCustomProperty,
+  RegisteredPropertyRange,
   StateClassRule,
 } from './types'
 
@@ -84,14 +85,14 @@ export function parseCss(cssString: string): CSSParserAPI {
       return getSelectorSpecificity(parsed)
     },
 
-    getVarPropertyType(varName: string, defaultValue: string): string | undefined {
+    getVarPropertyType(varName: string, defaultValue: string): string {
       // A `@property` registration is the declared type and wins over usage inference.
       const normalizedVarName = varName.startsWith('--') ? varName : `--${varName}`
       const registered = registeredProperties.get(normalizedVarName)
       if (registered) return registered.cssPropertyType
 
       const usages = this.getVarUsages(varName)
-      if (usages.length === 0) return undefined
+      if (usages.length === 0) return inferCssDataType(defaultValue)
       const uniqueProperties = [...new Set(usages)]
       if (uniqueProperties.length === 1) {
         const camelCased = camelCase(uniqueProperties[0])
@@ -501,6 +502,19 @@ function extractAtruleDescriptors(block: CssNode): Map<string, string> {
   return descriptors
 }
 
+/** Picks the range descriptors out of the block; css-tree collects them like any other declaration. */
+function extractRangeDescriptors(descriptors: Map<string, string>): RegisteredPropertyRange | undefined {
+  const min = descriptors.get('--min')
+  const max = descriptors.get('--max')
+  const step = descriptors.get('--step')
+  if (min === undefined && max === undefined && step === undefined) return undefined
+  return {
+    ...(min !== undefined && { min }),
+    ...(max !== undefined && { max }),
+    ...(step !== undefined && { step }),
+  }
+}
+
 /**
  * Walks the stylesheet for `@property` at-rules and builds a map of registered custom
  * properties keyed by the `--`-prefixed variable name.
@@ -528,11 +542,13 @@ function parseRegisteredProperties(cssString: string): Map<string, RegisteredCus
       if (!resolved) return
       const { cssPropertyType, enumOptions } = resolved
       const initialValue = descriptors.get('initial-value')
+      const range = extractRangeDescriptors(descriptors)
 
       registered.set(varName, {
         cssPropertyType,
         ...(enumOptions && { enumOptions }),
         ...(initialValue !== undefined && { defaultValue: initialValue }),
+        ...(range && { range }),
       })
     },
   })

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

@@ -47,6 +47,23 @@ export interface RegisteredCustomProperty {
    * (`a | b | c`). Present only when `cssPropertyType` is `customEnum`.
    */
   enumOptions?: string[]
+  /**
+   * The numeric range for the control, as raw descriptor strings. Validated at
+   * conversion time. Meaningful only when `cssPropertyType` is `number`.
+   */
+  range?: RegisteredPropertyRange
+}
+
+/**
+ * `--min` / `--max` / `--step` descriptors an importer may emit inside an `@property`
+ * block. The `--` prefix keeps them in the author namespace: browsers ignore descriptors
+ * they don't know, so the CSS stays valid and CSS can't standardise these names out from
+ * under us.
+ */
+export interface RegisteredPropertyRange {
+  min?: string
+  max?: string
+  step?: string
 }
 
 export type NativePseudoClass = 'hover' | 'focus' | 'disabled' | 'invalid'
@@ -120,13 +137,13 @@ export interface CSSParserAPI {
    * Determines the CSS property type for a custom property.
    * A `@property` registration is the top-priority source (declared type). Otherwise
    * falls back to usage: 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 neither registered nor used via var().
+   * returns that property name; if usages differ, or if the variable is not used via
+   * var() at all, returns the CSS data type inferred from the initial value
+   * ('color', 'length', 'number', or 'string').
    * @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
+  getVarPropertyType: (varName: string, defaultValue: string) => string
 
   /**
    * Returns every custom property registered via a `@property` at-rule, keyed by the

package/src/validators/editor-element-validator.test.ts

@@ -0,0 +1,142 @@
+import type { CssCustomPropertyItem, EditorElement, ElementItem } from '@wix/react-component-schema'
+import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
+import { describe, expect, it } from 'vitest'
+
+import { ValidationError } from '../errors'
+import { validateEditorElement } from './editor-element-validator'
+
+function buildMinimalEditorElement(overrides: Partial<EditorElement> = {}): EditorElement {
+  return {
+    selector: '.root',
+    displayName: 'Test Component',
+    ...overrides,
+  }
+}
+
+function buildInlineElementItem(overrides: Partial<ElementItem> = {}): ElementItem {
+  return {
+    elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
+    inlineElement: {
+      selector: '.child',
+      displayName: 'Child',
+    },
+    ...overrides,
+  }
+}
+
+function buildCssCustomPropertyItem(cssPropertyType: CssCustomPropertyItem['cssPropertyType']): CssCustomPropertyItem {
+  return { cssPropertyType }
+}
+
+describe('validateEditorElement', () => {
+  it('does not throw for a valid minimal editorElement', () => {
+    const editorElement = buildMinimalEditorElement()
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).not.toThrow()
+  })
+
+  it('does not throw when cssCustomProperties have valid property types', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        color: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.color),
+        size: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.length),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).not.toThrow()
+  })
+
+  it('throws ValidationError when a cssCustomProperty has UNKNOWN cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        brokenProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('includes the field path in the error message for UNKNOWN cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        brokenProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      'editorElement.cssCustomProperties.brokenProp',
+    )
+  })
+
+  it('throws ValidationError when a cssCustomProperty is missing cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        missingTypeProp: {} as CssCustomPropertyItem,
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('throws ValidationError when an elements entry has UNKNOWN elementType', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType,
+          inlineElement: { selector: '.child', displayName: 'Child' },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('throws ValidationError when an elements entry is missing elementType', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: buildInlineElementItem({ elementType: undefined }),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('collects all violations and throws once with all of them listed', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        badProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType,
+          inlineElement: { selector: '.child', displayName: 'Child' },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      /editorElement\.cssCustomProperties\.badProp.*\n.*editorElement\.elements\.child/s,
+    )
+  })
+
+  it('validates nested inline element cssCustomProperties recursively', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
+          inlineElement: {
+            selector: '.child',
+            displayName: 'Child',
+            cssCustomProperties: {
+              nestedBad: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+            },
+          },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      'editorElement.elements.child.inlineElement.cssCustomProperties.nestedBad',
+    )
+  })
+
+  it('includes the component name in the error message', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        badProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'MyButton')).toThrow('MyButton')
+  })
+})

package/src/validators/editor-element-validator.ts

@@ -0,0 +1,64 @@
+import type {
+  CssCustomPropertyItem,
+  EditorReactComponent,
+  ElementItem,
+  InlineElement,
+} from '@wix/react-component-schema'
+import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
+
+import { ValidationError } from '../errors'
+
+type RawEditorElement = NonNullable<EditorReactComponent['editorElement']>
+type AnyElement = RawEditorElement | InlineElement
+
+export function validateEditorElement(editorElement: RawEditorElement, componentName: string): void {
+  const violations = collectElementViolations(editorElement, 'editorElement')
+  if (violations.length === 0) return
+
+  const violationList = violations.map((violation) => `  - ${violation}`).join('\n')
+  throw new ValidationError(`Component "${componentName}" produced an invalid editorElement:\n${violationList}`, {
+    props: { phase: 'conversion' },
+  })
+}
+
+function collectElementViolations(element: AnyElement, elementPath: string): string[] {
+  return [
+    ...validateCssCustomProperties(element.cssCustomProperties, elementPath),
+    ...validateElementsMap(element.elements, elementPath),
+  ]
+}
+
+function validateCssCustomProperties(
+  cssCustomProperties: Record<string, CssCustomPropertyItem> | undefined,
+  elementPath: string,
+): string[] {
+  if (!cssCustomProperties) return []
+
+  const violations: string[] = []
+  for (const [propKey, propValue] of Object.entries(cssCustomProperties)) {
+    const unknownType = CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType
+    if (!propValue.cssPropertyType || propValue.cssPropertyType === unknownType) {
+      violations.push(`${elementPath}.cssCustomProperties.${propKey}: cssPropertyType is not set or UNKNOWN`)
+    }
+  }
+  return violations
+}
+
+function validateElementsMap(elements: Record<string, ElementItem> | undefined, elementPath: string): string[] {
+  if (!elements) return []
+
+  const violations: string[] = []
+  for (const [elementKey, elementItem] of Object.entries(elements)) {
+    const itemPath = `${elementPath}.elements.${elementKey}`
+    const unknownType = ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType
+
+    if (!elementItem.elementType || elementItem.elementType === unknownType) {
+      violations.push(`${itemPath}: elementType is not set or UNKNOWN`)
+    }
+
+    if (elementItem.inlineElement) {
+      violations.push(...collectElementViolations(elementItem.inlineElement, `${itemPath}.inlineElement`))
+    }
+  }
+  return violations
+}