@wix/zero-config-implementation 1.76.0 → 1.77.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ComponentType } from 'react';
+import { CSS_PROPERTIES } from '@wix/react-component-schema';
 import { CssNode } from 'css-tree';
 import { default as default_2 } from 'typescript';
 import { EditorReactComponent } from '@wix/react-component-schema';
@@ -384,6 +385,13 @@ MergeErrorProps<ErrorPropsArg, ChildProps>,
 ChildCustomClass
 >
 
+/**
+ * The subset of manifest `cssPropertyType` values a `@property` `syntax` can resolve to —
+ * the schema's CSS data types (`color`, `number`, `length`, …, `customEnum`). Derived from
+ * the schema so it stays in sync with `CssCustomPropertyItem['cssPropertyType']`.
+ */
+declare type CssDataType = (typeof CSS_PROPERTIES.CSS_DATA_TYPE)[keyof typeof CSS_PROPERTIES.CSS_DATA_TYPE];
+
 /**
  * API returned by parseCss function for querying parsed CSS
  */
@@ -426,15 +434,23 @@ export declare interface CSSParserAPI {
      */
     getSelectorSpecificity: (selector: string) => [number, number, number] | 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().
+     * 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().
      * @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;
+    /**
+     * Returns every custom property registered via a `@property` at-rule, keyed by the
+     * variable name including its leading `--`. Each entry carries the type derived from
+     * `syntax`, the default from `initial-value`, and (for a pipe-separated ident list)
+     * the enum options.
+     */
+    getRegisteredCustomProperties: () => Map<string, RegisteredCustomProperty>;
     /**
      * Returns every `:global(.modifier)` design-state class found in the CSS, paired
      * with any native pseudo-class on the same base element within the same rule.
@@ -2423,6 +2439,27 @@ export declare interface ReactExtractor {
     onRenderComplete?(event: RenderCompleteEvent): void;
 }
 
+/**
+ * A CSS custom property registered via the standard `@property` at-rule.
+ * The `syntax` descriptor gives the type (and, for a pipe-separated ident list, a
+ * finite set of options); the `initial-value` descriptor gives the default. Unlike
+ * usage-inferred types, this is a declared source of truth and takes precedence.
+ */
+declare interface RegisteredCustomProperty {
+    /**
+     * The manifest `cssPropertyType` derived from the `@property` `syntax` descriptor
+     * (e.g. `color`, `number`, `length`, or `customEnum` for a pipe-separated ident list).
+     */
+    cssPropertyType: CssDataType;
+    /** The default value from the `@property` `initial-value` descriptor, if declared. */
+    defaultValue?: string;
+    /**
+     * The custom-ident options when `syntax` is a pipe-separated ident list
+     * (`a | b | c`). Present only when `cssPropertyType` is `customEnum`.
+     */
+    enumOptions?: string[];
+}
+
 /**
  * Event emitted after render completes.
  */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-CukAHhd0.js";
+import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-DRWoSsTZ.js";
 import "react";
 export {
   t as BaseError,

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.76.0",
+  "version": "1.77.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -82,5 +82,5 @@
       ]
     }
   },
-  "falconPackageHash": "961c9ff14e1a1aaf443e4e28497e18b4774e7858411e613df8e151d3"
+  "falconPackageHash": "29046e5eac674ef42dc21f8449f7f0b5c99691e835215a1133464500"
 }

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

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
 import { parseCss } from '../information-extractors/css/parse'
 import type { MatchedCssData } from '../information-extractors/css/types'
 import type { ExtractedElement } from '../information-extractors/react'
-import type { ComponentInfoWithCss } from '../manifest-pipeline'
+import type { ComponentInfoWithCss, ExtractedCssInfo } from '../manifest-pipeline'
 import { toEditorReactComponent } from './to-editor-component'
 
 function matcherDataFromCss(declarations: string): MatchedCssData {
@@ -86,3 +86,156 @@ describe('toEditorReactComponent display conversion', () => {
     })
   })
 })
+
+function cssInfoFromStylesheet(cssString: string): ExtractedCssInfo {
+  const api = parseCss(cssString)
+  const properties = new Map<string, string>()
+  const customProperties = new Map<string, string>()
+
+  for (const [, selectorProperties] of api.getAllProperties()) {
+    for (const property of selectorProperties) {
+      if (property.name.startsWith('--')) {
+        customProperties.set(property.name, property.value)
+      } else {
+        properties.set(property.name, property.value)
+      }
+    }
+  }
+
+  return { filePath: 'property-tokens.css', api, properties, customProperties, isCssModule: false }
+}
+
+function createComponentWithCss(cssString: string): ComponentInfoWithCss {
+  const rootElement: ExtractedElement = {
+    traceId: 'trace-root',
+    name: 'root',
+    tag: 'div',
+    attributes: {},
+    extractorData: new Map<string, unknown>(),
+    children: [],
+  }
+
+  return {
+    componentName: 'PropertyTokens',
+    props: {},
+    elements: [rootElement],
+    propUsages: new Map(),
+    css: [cssInfoFromStylesheet(cssString)],
+    varUsedByTraceId: new Map(),
+  }
+}
+
+describe('toEditorReactComponent — @property design tokens', () => {
+  it('emits typed cssCustomProperties from @property, defaulting from initial-value with no element declaration', () => {
+    const component = createComponentWithCss(`
+      @property --sdf-safelight-color { syntax: "<color>"; inherits: true; initial-value: #F02011; }
+      @property --sdf-contrast { syntax: "<number>"; inherits: true; initial-value: 1.5; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.['sdf-safelight-color']).toEqual({
+      displayName: 'Sdf Safelight Color',
+      defaultValue: '#F02011',
+      cssPropertyType: 'color',
+    })
+    expect(customProps?.['sdf-contrast']).toEqual({
+      displayName: 'Sdf Contrast',
+      defaultValue: '1.5',
+      cssPropertyType: 'number',
+    })
+  })
+
+  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; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.['sdf-palette']).toEqual({
+      displayName: 'Sdf Palette',
+      defaultValue: 'warm',
+      cssPropertyType: 'customEnum',
+      customEnum: {
+        cssPropertyType: 'string',
+        options: [
+          { value: 'warm', displayName: 'Warm' },
+          { value: 'cool', displayName: 'Cool' },
+          { value: 'neutral', displayName: 'Neutral' },
+        ],
+      },
+    })
+  })
+
+  it('drops a @property whose type has no matching schema cssPropertyType', () => {
+    const component = createComponentWithCss(`
+      @property --sdf-hero-image { syntax: "<image>"; inherits: false; }
+      @property --sdf-safelight-color { syntax: "<color>"; inherits: true; initial-value: #F02011; }
+    `)
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    expect(customProps?.['sdf-hero-image']).toBeUndefined()
+    expect(customProps?.['sdf-safelight-color']).toBeDefined()
+  })
+
+  it('emits @property-typed and usage-inferred custom properties side by side', () => {
+    const matcherData: MatchedCssData = {
+      matches: [{ selector: '.root', properties: [], specificity: [0, 1, 0] }],
+      customProperties: { '--spacing': '8px' },
+    }
+    const rootElement: ExtractedElement = {
+      traceId: 'trace-root',
+      name: 'root',
+      tag: 'div',
+      attributes: {},
+      extractorData: new Map<string, unknown>([['css-matcher', matcherData]]),
+      children: [],
+    }
+    const component: ComponentInfoWithCss = {
+      componentName: 'MixedTokens',
+      props: {},
+      elements: [rootElement],
+      propUsages: new Map(),
+      css: [
+        cssInfoFromStylesheet(`
+          @property --brand-color { syntax: "<color>"; inherits: false; initial-value: #123456; }
+          .root { --spacing: 8px; padding: var(--spacing); color: var(--brand-color); }
+        `),
+      ],
+      varUsedByTraceId: new Map([
+        ['--brand-color', new Set(['trace-root'])],
+        ['--spacing', new Set(['trace-root'])],
+      ]),
+    }
+
+    const customProps = toEditorReactComponent(component).editorElement?.cssCustomProperties
+
+    // --brand-color is typed from its @property declaration; --spacing keeps the existing
+    // usage-inference behavior (single usage in `padding` → the `padding` property type).
+    expect(customProps?.['brand-color']).toEqual({
+      displayName: 'Brand Color',
+      defaultValue: '#123456',
+      cssPropertyType: 'color',
+    })
+    expect(customProps?.spacing).toEqual({
+      displayName: 'Spacing',
+      defaultValue: '8px',
+      cssPropertyType: 'padding',
+    })
+  })
+
+  it('does not leak a registered @property variable into cssProperties', () => {
+    const component = createComponentWithCss(`
+      @property --sdf-safelight-color { syntax: "<color>"; inherits: true; initial-value: #F02011; }
+      .root { --sdf-safelight-color: #F02011; }
+    `)
+
+    const editorElement = toEditorReactComponent(component).editorElement
+
+    expect(editorElement?.cssCustomProperties?.['sdf-safelight-color']).toBeDefined()
+    expect(editorElement?.cssProperties?.['sdf-safelight-color']).toBeUndefined()
+    expect(editorElement?.cssProperties?.['--sdf-safelight-color']).toBeUndefined()
+  })
+})

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

@@ -1,6 +1,7 @@
 import type {
   CssCustomPropertyItem,
   CssPropertyItem,
+  CustomPropertyEnum,
   DataItem,
   Display,
   EditorElement,
@@ -11,7 +12,7 @@ import type {
 import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
 import { camelCase } from 'case-anything'
 import type { ComponentInfoWithCss } from '../index'
-import type { MatchedCssData } from '../information-extractors/css/types'
+import type { MatchedCssData, RegisteredCustomProperty } from '../information-extractors/css/types'
 import type {
   CoupledComponentInfo,
   CoupledProp,
@@ -220,6 +221,11 @@ function buildNearestCommonAncestorCustomProps(
   component: ComponentInfoWithCss,
 ): Map<string, Record<string, CssCustomPropertyItem>> {
   const parentMap = buildParentMap(component.elements)
+  const rootTraceId = component.elements[0]?.traceId
+
+  // Custom properties registered via the standard @property at-rule — the declared
+  // source of each variable's type, default, and (for ident lists) enum options.
+  const registeredByVar = collectRegisteredCustomProperties(component)
 
   // 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').
@@ -235,31 +241,47 @@ function buildNearestCommonAncestorCustomProps(
     }
   }
 
+  // Emit every declared variable plus every @property registration — a registered var
+  // may have no element-level declaration yet still needs a typed control.
+  const varNames = new Set<string>([...allCustomPropertyValues.keys(), ...registeredByVar.keys()])
+
   const nearestCommonAncestorCustomProps = new Map<string, Record<string, CssCustomPropertyItem>>()
 
-  for (const [varName, defaultValue] of allCustomPropertyValues) {
+  for (const varName of varNames) {
     if (varName === '--display') continue
 
+    const registration = registeredByVar.get(varName)
+    // Prefer a concrete declared value; fall back to the @property initial-value so a
+    // component doesn't need an element-level `--x: ...` declaration.
+    const defaultValue = allCustomPropertyValues.get(varName) ?? registration?.defaultValue
+
     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)
+      // Fallback: the element whose CSS selector defines the variable; failing that, a
+      // registered @property with no var() usage anchors on the component root.
+      nearestCommonAncestorTraceId =
+        findDefiningElement(component.elements, varName) ?? (registration ? rootTraceId : undefined)
     }
 
     if (!nearestCommonAncestorTraceId) continue
 
-    const cssPropertyType = getVarPropertyTypeFromCssInfos(varName, defaultValue, component.css)
+    // A @property registration is the top-priority type source; otherwise infer from usage.
+    const cssPropertyType = registration
+      ? registration.cssPropertyType
+      : getVarPropertyTypeFromCssInfos(varName, defaultValue ?? '', component.css)
+    const customEnum = buildCustomEnum(registration)
     const cleanVarName = varName.startsWith('--') ? varName.slice(2) : varName
 
     const existingProps = nearestCommonAncestorCustomProps.get(nearestCommonAncestorTraceId) ?? {}
     existingProps[cleanVarName] = {
       displayName: formatDisplayName(cleanVarName),
-      defaultValue,
+      ...(defaultValue !== undefined && { defaultValue }),
       ...(cssPropertyType !== undefined && { cssPropertyType }),
+      ...(customEnum && { customEnum }),
     }
     nearestCommonAncestorCustomProps.set(nearestCommonAncestorTraceId, existingProps)
   }
@@ -267,6 +289,35 @@ function buildNearestCommonAncestorCustomProps(
   return nearestCommonAncestorCustomProps
 }
 
+/**
+ * Merges @property registrations across all of the component's CSS files, keyed by the
+ * `--`-prefixed variable name. The first file to register a variable wins.
+ */
+function collectRegisteredCustomProperties(component: ComponentInfoWithCss): Map<string, RegisteredCustomProperty> {
+  const merged = new Map<string, RegisteredCustomProperty>()
+  for (const cssInfo of component.css) {
+    for (const [varName, registration] of cssInfo.api.getRegisteredCustomProperties()) {
+      if (!merged.has(varName)) merged.set(varName, registration)
+    }
+  }
+  return merged
+}
+
+/**
+ * Builds a `customEnum` (a named-option dropdown) from an @property whose `syntax` is a
+ * pipe-separated ident list. Option labels are humanized from the idents.
+ */
+function buildCustomEnum(registration: RegisteredCustomProperty | undefined): CustomPropertyEnum | undefined {
+  if (!registration?.enumOptions || registration.enumOptions.length === 0) return undefined
+  return {
+    cssPropertyType: CSS_PROPERTIES.CSS_DATA_TYPE.string,
+    options: registration.enumOptions.map((value) => ({
+      value,
+      displayName: formatDisplayName(value),
+    })),
+  }
+}
+
 /**
  * Queries each CSS parser API for the property type of a variable and returns
  * the first defined result.

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

@@ -121,6 +121,105 @@ describe('parseCss — getStateClasses', () => {
   })
 })
 
+describe('parseCss — @property registration', () => {
+  it('maps each syntax type to its cssPropertyType and reads the initial-value default', () => {
+    const registered = parseCss(`
+      @property --sdf-safelight-color { syntax: "<color>"; inherits: true; initial-value: #F02011; }
+      @property --sdf-contrast { syntax: "<number>"; inherits: true; initial-value: 1.5; }
+      @property --sdf-radius { syntax: "<length>"; inherits: false; initial-value: 8px; }
+      @property --sdf-scale { syntax: "<percentage>"; inherits: false; initial-value: 50%; }
+      @property --sdf-tilt { syntax: "<angle>"; inherits: false; initial-value: 90deg; }
+      @property --sdf-delay { syntax: "<time>"; inherits: false; initial-value: 200ms; }
+      @property --sdf-inset { syntax: "<length-percentage>"; inherits: false; initial-value: 10px; }
+    `).getRegisteredCustomProperties()
+
+    expect(registered.get('--sdf-safelight-color')).toEqual({ cssPropertyType: 'color', defaultValue: '#F02011' })
+    expect(registered.get('--sdf-contrast')).toEqual({ cssPropertyType: 'number', defaultValue: '1.5' })
+    expect(registered.get('--sdf-radius')).toEqual({ cssPropertyType: 'length', defaultValue: '8px' })
+    expect(registered.get('--sdf-scale')).toEqual({ cssPropertyType: 'percentage', defaultValue: '50%' })
+    expect(registered.get('--sdf-tilt')).toEqual({ cssPropertyType: 'angle', defaultValue: '90deg' })
+    expect(registered.get('--sdf-delay')).toEqual({ cssPropertyType: 'time', defaultValue: '200ms' })
+    expect(registered.get('--sdf-inset')).toEqual({ cssPropertyType: 'lengthPercentage', defaultValue: '10px' })
+  })
+
+  it('maps <integer> to number (there is no dedicated integer control)', () => {
+    const registered = parseCss(`
+      @property --sdf-steps { syntax: "<integer>"; inherits: false; initial-value: 3; }
+    `).getRegisteredCustomProperties()
+
+    expect(registered.get('--sdf-steps')).toEqual({ cssPropertyType: 'number', defaultValue: '3' })
+  })
+
+  it('drops @property registrations whose syntax has no matching schema cssPropertyType', () => {
+    // No matching schema cssPropertyType → dropped, not emitted with a fallback type.
+    const registered = parseCss(`
+      @property --sdf-universal   { syntax: "*"; inherits: false; initial-value: anything; }
+      @property --sdf-image       { syntax: "<image>"; inherits: false; }
+      @property --sdf-url         { syntax: "<url>"; inherits: false; }
+      @property --sdf-resolution  { syntax: "<resolution>"; inherits: false; initial-value: 96dpi; }
+      @property --sdf-transform   { syntax: "<transform-function>"; inherits: false; }
+      @property --sdf-ident       { syntax: "<custom-ident>"; inherits: false; initial-value: foo; }
+      @property --sdf-lone-keyword { syntax: "auto"; inherits: false; initial-value: auto; }
+    `).getRegisteredCustomProperties()
+
+    for (const droppedVarName of [
+      '--sdf-universal',
+      '--sdf-image',
+      '--sdf-url',
+      '--sdf-resolution',
+      '--sdf-transform',
+      '--sdf-ident',
+      '--sdf-lone-keyword',
+    ]) {
+      expect(registered.has(droppedVarName)).toBe(false)
+    }
+    expect(registered.size).toBe(0)
+  })
+
+  it('picks the first recognized <type> from a mixed type/keyword list', () => {
+    const registered = parseCss(`
+      @property --sdf-size { syntax: "<length> | auto"; inherits: false; initial-value: auto; }
+      @property --sdf-scale { syntax: "small | medium | <length>"; inherits: false; initial-value: medium; }
+    `).getRegisteredCustomProperties()
+
+    expect(registered.get('--sdf-size')).toEqual({ cssPropertyType: 'length', defaultValue: 'auto' })
+    expect(registered.get('--sdf-scale')).toEqual({ cssPropertyType: 'length', defaultValue: 'medium' })
+  })
+
+  it('turns a pipe-separated ident list into a customEnum with its option idents', () => {
+    const registered = parseCss(`
+      @property --sdf-palette { syntax: "warm | cool | neutral"; inherits: false; initial-value: warm; }
+    `).getRegisteredCustomProperties()
+
+    expect(registered.get('--sdf-palette')).toEqual({
+      cssPropertyType: 'customEnum',
+      enumOptions: ['warm', 'cool', 'neutral'],
+      defaultValue: 'warm',
+    })
+  })
+
+  it('strips list multipliers when resolving a type component', () => {
+    const registered = parseCss(`
+      @property --sdf-shadows { syntax: "<length>+"; inherits: false; initial-value: 0px; }
+      @property --sdf-stops { syntax: "<color>#"; inherits: false; initial-value: red; }
+    `).getRegisteredCustomProperties()
+
+    expect(registered.get('--sdf-shadows')).toEqual({ cssPropertyType: 'length', defaultValue: '0px' })
+    expect(registered.get('--sdf-stops')).toEqual({ cssPropertyType: 'color', defaultValue: 'red' })
+  })
+
+  it('lets a @property registration override the usage-inferred type', () => {
+    const api = parseCss(`
+      @property --sdf-intensity { syntax: "<number>"; inherits: false; initial-value: 1; }
+      .root { --sdf-intensity: 1; background-color: var(--sdf-intensity); }
+    `)
+
+    // Used only in background-color, which would otherwise infer 'backgroundColor';
+    // the @property declaration wins.
+    expect(api.getVarPropertyType('--sdf-intensity', '1')).toBe('number')
+  })
+})
+
 describe('resolveCssPropertyValue', () => {
   it('uses the fallback when a referenced custom property is missing from the property-level map', () => {
     const [displayProperty] = parseCss(`