@wix/zero-config-implementation 1.75.0 → 1.77.0

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

@@ -3,7 +3,14 @@ import { camelCase } from 'case-anything'
 import { generate, lexer, parse, walk } from 'css-tree'
 import type { Atrule, CssNode, Declaration, FunctionNode, Rule, Selector, Value } from 'css-tree'
 import { stateNameFromModifier } from '../../utils/css-class'
-import type { CSSParserAPI, CSSProperty, NativePseudoClass, StateClassRule } from './types'
+import type {
+  CSSParserAPI,
+  CSSProperty,
+  CssDataType,
+  NativePseudoClass,
+  RegisteredCustomProperty,
+  StateClassRule,
+} from './types'
 
 type WalkContext = {
   atrule?: Atrule | null
@@ -22,6 +29,7 @@ export function parseCss(cssString: string): CSSParserAPI {
   const parsedSelectors = new Map<string, Selector>()
   const { propertiesMap: allProperties, varUsagesByProperty } = parseAllProperties(cssString, parsedSelectors)
   const stateClasses = parseStateClasses(cssString)
+  const registeredProperties = parseRegisteredProperties(cssString)
 
   return {
     getStateClasses(): StateClassRule[] {
@@ -77,6 +85,11 @@ export function parseCss(cssString: string): CSSParserAPI {
     },
 
     getVarPropertyType(varName: string, defaultValue: string): string | undefined {
+      // 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
       const uniqueProperties = [...new Set(usages)]
@@ -87,6 +100,10 @@ export function parseCss(cssString: string): CSSParserAPI {
       }
       return inferCssDataType(defaultValue)
     },
+
+    getRegisteredCustomProperties(): Map<string, RegisteredCustomProperty> {
+      return new Map(registeredProperties)
+    },
   }
 }
 
@@ -329,6 +346,150 @@ function extractVarNames(valueNode: CssNode): string[] {
   return varNames
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// @property at-rule parsing (CSS Properties and Values API)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A single `syntax` component (a CSS type reference) → manifest `cssPropertyType`.
+ *
+ * Only types with a matching schema `cssPropertyType` appear here. `<integer>` has no
+ * dedicated schema type, so it maps to `number`. Types with no schema equivalent —
+ * `<image>`, `<url>`, `<resolution>`, `<transform-function>`, `<transform-list>`,
+ * `<custom-ident>` — are deliberately absent; see {@link cssPropertyTypeFromSyntax}.
+ */
+const SYNTAX_TYPE_BY_COMPONENT: Record<string, CssDataType> = {
+  '<color>': CSS_PROPERTIES.CSS_DATA_TYPE.color,
+  '<number>': CSS_PROPERTIES.CSS_DATA_TYPE.number,
+  '<integer>': CSS_PROPERTIES.CSS_DATA_TYPE.number,
+  '<length>': CSS_PROPERTIES.CSS_DATA_TYPE.length,
+  '<percentage>': CSS_PROPERTIES.CSS_DATA_TYPE.percentage,
+  '<length-percentage>': CSS_PROPERTIES.CSS_DATA_TYPE.lengthPercentage,
+  '<angle>': CSS_PROPERTIES.CSS_DATA_TYPE.angle,
+  '<time>': CSS_PROPERTIES.CSS_DATA_TYPE.time,
+}
+
+// A CSS custom-ident: a bare keyword (no `<...>` type reference), e.g. `space-between`.
+const CUSTOM_IDENT_PATTERN = /^-?[A-Za-z_][\w-]*$/
+
+/**
+ * Derives the manifest type from a `@property` `syntax` descriptor, or `undefined`
+ * when the declared type has no matching schema `cssPropertyType` and the registration
+ * should be dropped rather than surfaced.
+ *
+ * Resolution order:
+ *  - a pipe-separated ident list (≥2 bare keywords) → `customEnum` with its options;
+ *  - otherwise the first recognized `<type>` component (list multipliers `+`/`#` stripped);
+ *  - anything else — the universal `*`, a lone keyword, or an unsupported `<type>` such as
+ *    `<image>` / `<url>` / `<resolution>` / `<transform-function>` / `<custom-ident>` —
+ *    has no schema type, so returns `undefined` (dropped).
+ */
+function cssPropertyTypeFromSyntax(
+  rawSyntax: string,
+): { cssPropertyType: CssDataType; enumOptions?: string[] } | undefined {
+  const { CSS_DATA_TYPE } = CSS_PROPERTIES
+  const syntax = rawSyntax
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .trim()
+  if (syntax === '' || syntax === '*') return undefined
+
+  const components = syntax
+    .split('|')
+    .map((component) => component.trim())
+    .filter((component) => component.length > 0)
+
+  const identComponents = components.filter((component) => CUSTOM_IDENT_PATTERN.test(component))
+  if (identComponents.length === components.length && components.length >= 2) {
+    return { cssPropertyType: CSS_DATA_TYPE.customEnum, enumOptions: components }
+  }
+
+  for (const component of components) {
+    const baseType = component.replace(/[+#]$/, '')
+    const mappedType = SYNTAX_TYPE_BY_COMPONENT[baseType]
+    if (mappedType) return { cssPropertyType: mappedType }
+  }
+
+  return undefined
+}
+
+/**
+ * Collects the descriptor declarations (`syntax`, `initial-value`) from a `@property`
+ * block. Re-parses the raw block text when css-tree yields a Raw block, so parsing
+ * doesn't depend on css-tree's at-rule support.
+ */
+function extractAtruleDescriptors(block: CssNode): Map<string, string> {
+  const descriptors = new Map<string, string>()
+  const declarations: Declaration[] = []
+
+  walk(block, {
+    visit: 'Declaration',
+    enter(declaration: Declaration) {
+      declarations.push(declaration)
+    },
+  })
+
+  if (declarations.length === 0) {
+    const innerText = generate(block)
+      .replace(/^\s*\{/, '')
+      .replace(/\}\s*$/, '')
+    try {
+      const parsedBlock = parse(innerText, { context: 'declarationList' })
+      walk(parsedBlock, {
+        visit: 'Declaration',
+        enter(declaration: Declaration) {
+          declarations.push(declaration)
+        },
+      })
+    } catch {
+      // Leave descriptors empty if the raw block can't be re-parsed.
+    }
+  }
+
+  for (const declaration of declarations) {
+    descriptors.set(declaration.property, generate(declaration.value).trim())
+  }
+  return descriptors
+}
+
+/**
+ * Walks the stylesheet for `@property` at-rules and builds a map of registered custom
+ * properties keyed by the `--`-prefixed variable name.
+ */
+function parseRegisteredProperties(cssString: string): Map<string, RegisteredCustomProperty> {
+  const registered = new Map<string, RegisteredCustomProperty>()
+
+  try {
+    const ast = parse(cssString)
+
+    walk(ast, {
+      visit: 'Atrule',
+      enter(atrule: Atrule) {
+        if (atrule.name !== 'property' || !atrule.prelude || !atrule.block) return
+
+        const varName = generate(atrule.prelude).trim()
+        if (!varName.startsWith('--')) return
+
+        const descriptors = extractAtruleDescriptors(atrule.block)
+        const resolved = cssPropertyTypeFromSyntax(descriptors.get('syntax') ?? '*')
+        if (!resolved) return
+        const { cssPropertyType, enumOptions } = resolved
+        const initialValue = descriptors.get('initial-value')
+
+        registered.set(varName, {
+          cssPropertyType,
+          ...(enumOptions && { enumOptions }),
+          ...(initialValue !== undefined && { defaultValue: initialValue }),
+        })
+      },
+    })
+  } catch (error) {
+    console.error('CSS @property parsing error:', error)
+  }
+
+  return registered
+}
+
 // Native pseudo-classes mapped to their design-state key. `:focus-visible` and
 // `:focus-within` both collapse to `focus` (the schema has a single focus state).
 const NATIVE_PSEUDO_BY_NAME: Record<string, NativePseudoClass> = {

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

@@ -1,5 +1,13 @@
+import type { CSS_PROPERTIES } from '@wix/react-component-schema'
 import type { CssNode } from 'css-tree'
 
+/**
+ * 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']`.
+ */
+export type CssDataType = (typeof CSS_PROPERTIES.CSS_DATA_TYPE)[keyof typeof CSS_PROPERTIES.CSS_DATA_TYPE]
+
 export interface CSSProperty {
   name: string
   value: string
@@ -20,6 +28,27 @@ export interface MatchedCssData {
   customProperties: Record<string, string>
 }
 
+/**
+ * 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.
+ */
+export 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[]
+}
+
 export type NativePseudoClass = 'hover' | 'focus' | 'disabled' | 'invalid'
 
 /**
@@ -88,16 +117,25 @@ export 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.