@wix/zero-config-implementation 1.66.0 → 1.68.0

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

@@ -2,7 +2,8 @@ import { CSS_PROPERTIES } from '@wix/react-component-schema'
 import { camelCase } from 'case-anything'
 import { generate, lexer, parse, walk } from 'css-tree'
 import type { Atrule, CssNode, Declaration, FunctionNode, Rule, Selector } from 'css-tree'
-import type { CSSParserAPI, CSSProperty } from './types'
+import { stateNameFromModifier } from '../../utils/css-class'
+import type { CSSParserAPI, CSSProperty, NativePseudoClass, StateClassRule } from './types'
 
 type WalkContext = {
   atrule?: Atrule | null
@@ -20,8 +21,13 @@ function isInsideKeyframes(currentContext: WalkContext): boolean {
 export function parseCss(cssString: string): CSSParserAPI {
   const parsedSelectors = new Map<string, Selector>()
   const { propertiesMap: allProperties, varUsagesByProperty } = parseAllProperties(cssString, parsedSelectors)
+  const stateClasses = parseStateClasses(cssString)
 
   return {
+    getStateClasses(): StateClassRule[] {
+      return stateClasses
+    },
+
     getPropertiesForSelector(selector: string): CSSProperty[] {
       return allProperties.get(selector) ?? []
     },
@@ -198,6 +204,176 @@ function extractVarNames(valueNode: CssNode): string[] {
   return varNames
 }
 
+// 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> = {
+  hover: 'hover',
+  focus: 'focus',
+  'focus-visible': 'focus',
+  'focus-within': 'focus',
+  disabled: 'disabled',
+  invalid: 'invalid',
+}
+
+const GLOBAL_MODIFIER_PATTERN = /^:global\(\s*\.([\w-]+)\s*\)$/
+
+interface AnalyzedCompound {
+  /** DOM-matchable base of the compound the modifier/pseudo is attached to, e.g. `.root`. */
+  base: string
+  /** Native pseudo-class on this compound, if any. */
+  pseudoClass?: NativePseudoClass
+  /** Global modifier class names extracted from `:global(.X)` parts on this compound. */
+  modifiers: string[]
+}
+
+type SelectorPart = { kind: 'local'; selector: string } | { kind: 'global'; className: string }
+
+/**
+ * Decides whether a `:global(.X)` class on a selector is a state *modifier* (vs. the
+ * base element it modifies):
+ *   - If the selector has a local (CSS-module) class, that local class is always the
+ *     base, so every global class is a modifier — the current, common form
+ *     (`.root:global(.toggle--hover)`).
+ *   - Otherwise the element itself is authored as a global class, and the base is the
+ *     BEM root: a global class is a modifier only when it `--`-extends another global
+ *     class on the selector (`:global(.card):global(.card--featured)` → base `.card`,
+ *     modifier `card--featured`). A lone `:global(.card):hover` keeps `.card` as base.
+ */
+function isModifierClass(className: string, hasLocalBase: boolean, globalClassNames: string[]): boolean {
+  if (hasLocalBase) return true
+  return globalClassNames.some((other) => other !== className && className.startsWith(`${other}--`))
+}
+
+/**
+ * Analyzes a single compound selector (no combinators) into its DOM-matchable base,
+ * a native pseudo-class (if present), and any `:global(.modifier)` class names. Returns
+ * null for a compound carrying a pseudo-element (unmatchable) or with no base.
+ *
+ * The element a modifier is applied to may itself be authored as a global class, so
+ * the base/modifier split is resolved across all of the compound's classes rather
+ * than assuming the base is local — see `isModifierClass`.
+ */
+function analyzeCompound(componentNodes: CssNode[]): AnalyzedCompound | null {
+  let pseudoClass: NativePseudoClass | undefined
+  const parts: SelectorPart[] = []
+
+  for (const component of componentNodes) {
+    if (component.type === 'PseudoElementSelector') return null
+    if (component.type === 'PseudoClassSelector') {
+      if (component.name === 'global') {
+        const match = generate(component).match(GLOBAL_MODIFIER_PATTERN)
+        if (match) parts.push({ kind: 'global', className: match[1] })
+        continue
+      }
+      pseudoClass ??= NATIVE_PSEUDO_BY_NAME[component.name]
+      continue
+    }
+    parts.push({ kind: 'local', selector: generate(component) })
+  }
+
+  const hasLocalBase = parts.some((part) => part.kind === 'local')
+  const globalClassNames = parts.flatMap((part) => (part.kind === 'global' ? [part.className] : []))
+
+  const baseParts: string[] = []
+  const modifiers: string[] = []
+  for (const part of parts) {
+    if (part.kind === 'local') {
+      baseParts.push(part.selector)
+    } else if (isModifierClass(part.className, hasLocalBase, globalClassNames)) {
+      modifiers.push(part.className)
+    } else {
+      baseParts.push(`.${part.className}`)
+    }
+  }
+
+  const base = baseParts.join('')
+  if (!base) return null
+
+  return { base, pseudoClass, modifiers }
+}
+
+/**
+ * Splits a selector into compound selectors at combinators and analyzes each. A
+ * `:global(.modifier)` (or native pseudo) belongs to the compound it is attached to,
+ * so ancestor/descendant compounds in the same selector are ignored for the base —
+ * e.g. `.header:global(.x--selected) .label` resolves to base `.header`, not
+ * `.header .label`. Returns one entry per compound that carries a modifier or pseudo.
+ */
+function analyzeStateSelector(selector: Selector): AnalyzedCompound[] {
+  const compounds: CssNode[][] = [[]]
+  for (const component of selector.children) {
+    if (component.type === 'Combinator') {
+      compounds.push([])
+    } else {
+      compounds[compounds.length - 1].push(component)
+    }
+  }
+
+  const results: AnalyzedCompound[] = []
+  for (const compoundNodes of compounds) {
+    const analyzed = analyzeCompound(compoundNodes)
+    if (analyzed && (analyzed.modifiers.length > 0 || analyzed.pseudoClass)) {
+      results.push(analyzed)
+    }
+  }
+  return results
+}
+
+/**
+ * Walks every CSS rule and extracts `:global(.modifier)` design-state classes,
+ * pairing each modifier with any native pseudo-class found on the same base within
+ * the same rule. This realizes the contract that a selector matching both a pseudo
+ * and a global modifier marks a native state's editor-trigger class, while a global
+ * modifier with no paired pseudo marks a custom state.
+ */
+function parseStateClasses(cssString: string): StateClassRule[] {
+  const results: StateClassRule[] = []
+
+  try {
+    const ast = parse(cssString)
+
+    walk(ast, {
+      visit: 'Rule',
+      enter(rule: Rule) {
+        if (rule.prelude.type !== 'SelectorList') return
+
+        const pseudoByBase = new Map<string, NativePseudoClass>()
+        const modifiersByBase = new Map<string, Set<string>>()
+
+        for (const selectorNode of rule.prelude.children) {
+          if (selectorNode.type !== 'Selector') continue
+          for (const analyzed of analyzeStateSelector(selectorNode)) {
+            if (analyzed.pseudoClass && !pseudoByBase.has(analyzed.base)) {
+              pseudoByBase.set(analyzed.base, analyzed.pseudoClass)
+            }
+            if (analyzed.modifiers.length > 0) {
+              const modifiers = modifiersByBase.get(analyzed.base) ?? new Set<string>()
+              for (const modifier of analyzed.modifiers) modifiers.add(modifier)
+              modifiersByBase.set(analyzed.base, modifiers)
+            }
+          }
+        }
+
+        for (const [baseSelector, modifiers] of modifiersByBase) {
+          const basePseudo = pseudoByBase.get(baseSelector)
+          for (const modifier of modifiers) {
+            // A modifier is the editor-trigger class for a NATIVE state only when its
+            // own state name matches the base's pseudo (`x--hover` ↔ `:hover`). A custom
+            // modifier sharing a base with a native pseudo (`x--selected` next to `:hover`)
+            // stays custom — it must not inherit the unrelated pseudo.
+            const pseudoClass = basePseudo && stateNameFromModifier(modifier) === basePseudo ? basePseudo : undefined
+            results.push({ baseSelector, modifier, pseudoClass })
+          }
+        }
+      },
+    })
+  } catch (error) {
+    console.error('CSS state-class parsing error:', error)
+  }
+
+  return results
+}
+
 /**
  * Builds a DOM-queryable selector by filtering out pseudo-classes and pseudo-elements.
  * Returns null if the selector contains pseudo-elements (unmatchable against real DOM).

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

@@ -15,6 +15,26 @@ export interface MatchedCssData {
   customProperties: Record<string, string>
 }
 
+export type NativePseudoClass = 'hover' | 'focus' | 'disabled' | 'invalid'
+
+/**
+ * A `:global(.modifier)` design-state class found on a base element selector.
+ * Produced by walking each CSS rule and pairing the global modifier with any
+ * native pseudo-class present on the same base within that rule.
+ */
+export interface StateClassRule {
+  /** DOM-matchable base selector (e.g. `.root`), used to map the modifier to an element. */
+  baseSelector: string
+  /** Global modifier class name from `:global(.X)`, without the leading dot. */
+  modifier: string
+  /**
+   * Native pseudo-class paired with this modifier on the same base within the same
+   * rule. When present, the modifier is the editor-trigger class for a native state;
+   * when absent, the modifier denotes a custom (non-native) design state.
+   */
+  pseudoClass?: NativePseudoClass
+}
+
 /**
  * API returned by parseCss function for querying parsed CSS
  */
@@ -66,4 +86,11 @@ export interface CSSParserAPI {
    * @param defaultValue - The initial value string of the custom property
    */
   getVarPropertyType: (varName: string, defaultValue: string) => string | undefined
+
+  /**
+   * 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.
+   * Modifiers with no paired pseudo are custom (non-native) state triggers.
+   */
+  getStateClasses: () => StateClassRule[]
 }

package/src/information-extractors/ts/components.test.ts

@@ -0,0 +1,29 @@
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { compileTsFile } from '../../ts-compiler'
+import { extractAllComponentInfo } from './components'
+
+const propTriggeredFixture = path.resolve(
+  __dirname,
+  '../../../../example-components/src/components/DesignStates/Custom/PropTriggered/WithMatchingClass/component.tsx',
+)
+
+describe('TS extractor — ElementState<> trigger detection', () => {
+  it('flags an ElementState<>-wrapped prop and unwraps its inner type', async () => {
+    const programResult = await compileTsFile(propTriggeredFixture)
+    expect(programResult.isOk()).toBe(true)
+    const program = programResult._unsafeUnwrap()
+
+    const components = extractAllComponentInfo(program, propTriggeredFixture)
+    const component = components.find((candidate) => candidate.componentName === 'PropStates')
+    expect(component).toBeDefined()
+
+    const isLoading = component!.props.isLoading
+    expect(isLoading.isStateTrigger).toBe(true)
+    // The `ElementState<boolean>` wrapper is unwrapped — the prop behaves as a plain boolean.
+    expect(isLoading.type).toBe('boolean')
+
+    // Plain booleans are never flagged as state triggers.
+    expect(component!.props.showLabel.isStateTrigger).toBeUndefined()
+  })
+})

package/src/information-extractors/ts/components.ts

@@ -208,16 +208,27 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
 
     // Resolve the type deeply
     let declaredTypeInfo: DeclaredTypeInfo | undefined
+    let stateTrigger: StateTriggerInfo | undefined
     if (propSymbol) {
       const decl = propSymbol.getDeclarations()?.[0]
       if (decl) {
-        declaredTypeInfo = getDeclaredTypeInfo(propSymbol, decl.getSourceFile(), checker)
+        const declSourceFile = decl.getSourceFile()
+        declaredTypeInfo = getDeclaredTypeInfo(propSymbol, declSourceFile, checker)
+        stateTrigger = detectStateTrigger(propSymbol, declSourceFile, checker)
       }
     }
 
-    const typeString = declaredTypeInfo?.name ?? propItem.type.name
+    // An `ElementState<Inner>` prop should behave as its inner type everywhere except
+    // for the `isStateTrigger` flag, so unwrap the inner type for `type` and resolution
+    // (and drop the `ElementState` declared symbol so it isn't mistaken for a semantic type).
+    const typeString = stateTrigger?.innerTypeName ?? declaredTypeInfo?.name ?? propItem.type.name
     const resolvedType = propType
-      ? resolveType({ type: propType, checker, typeString, declaredSymbol: declaredTypeInfo?.symbol })
+      ? resolveType({
+          type: propType,
+          checker,
+          typeString,
+          declaredSymbol: stateTrigger ? undefined : declaredTypeInfo?.symbol,
+        })
       : { kind: 'primitive' as const, value: propItem.type.name }
 
     // Convert default value
@@ -239,6 +250,7 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
       resolvedType,
       description: propItem.description || undefined,
       deprecated: tags?.deprecated !== undefined ? true : undefined,
+      isStateTrigger: stateTrigger ? true : undefined,
     }
   }
 
@@ -477,6 +489,63 @@ interface DeclaredTypeInfo {
   symbol?: ts.Symbol
 }
 
+interface StateTriggerInfo {
+  /** Text of the inner type argument, e.g. `'boolean'`. */
+  innerTypeName: string
+}
+
+/**
+ * Detects when a prop is declared with the `ElementState<>` marker type from
+ * `@wix/react-component-utils` (e.g. `isLoading?: ElementState<boolean>`), which opts
+ * the prop in as the trigger for a custom design state. Returns the inner type
+ * argument so callers can treat the prop as its underlying type. Returns
+ * `undefined` for any other declaration.
+ */
+function detectStateTrigger(
+  prop: ts.Symbol,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): StateTriggerInfo | undefined {
+  const declaration = prop.getDeclarations()?.[0]
+  if (!declaration) return undefined
+
+  if (
+    !(ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration) || ts.isParameter(declaration)) ||
+    !declaration.type ||
+    !ts.isTypeReferenceNode(declaration.type) ||
+    !declaration.type.typeArguments ||
+    declaration.type.typeArguments.length !== 1
+  ) {
+    return undefined
+  }
+
+  const typeName = declaration.type.typeName
+  const identifier = ts.isIdentifier(typeName) ? typeName : typeName.right
+  if (identifier.text !== 'ElementState') return undefined
+  if (!isElementStateAliasFromUtils(identifier, checker)) return undefined
+
+  return { innerTypeName: declaration.type.typeArguments[0].getText(sourceFile) }
+}
+
+/**
+ * Confirms an identifier referencing `ElementState` resolves to the marker type
+ * alias exported by `@wix/react-component-utils`, rather than an unrelated local
+ * type that happens to be named `ElementState`.
+ */
+function isElementStateAliasFromUtils(identifier: ts.Identifier, checker: ts.TypeChecker): boolean {
+  let symbol = checker.getSymbolAtLocation(identifier)
+  if (!symbol) return false
+  if ((symbol.getFlags() & ts.SymbolFlags.Alias) !== 0) {
+    symbol = checker.getAliasedSymbol(symbol)
+  }
+
+  const declaration = symbol.getDeclarations()?.[0]
+  if (!declaration || !ts.isTypeAliasDeclaration(declaration)) return false
+  if (declaration.name.text !== 'ElementState') return false
+
+  return declaration.getSourceFile().fileName.includes('react-component-utils')
+}
+
 function getDeclaredTypeInfo(
   prop: ts.Symbol,
   sourceFile: ts.SourceFile,

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

@@ -51,6 +51,11 @@ export interface PropInfo {
   description?: string
   // Whether the prop is marked as deprecated via @deprecated JSDoc tag
   deprecated?: boolean
+  // True when the prop is wrapped in the `ElementState<>` marker type from
+  // @wix/react-component-utils, declaring it as the trigger for a custom design
+  // state. `type` and `resolvedType` reflect the unwrapped inner type, so the prop
+  // still behaves as a normal data prop everywhere else.
+  isStateTrigger?: boolean
 }
 
 export interface ComponentInfo {

package/src/utils/css-class.ts

@@ -46,3 +46,13 @@ export function findPreferredSemanticClass(classNames: string[]): string | undef
   const semanticClasses = classNames.filter(isGlobalSemanticClass)
   return semanticClasses.find((className) => !HAS_BEM_MODIFIER.test(className)) ?? semanticClasses[0]
 }
+
+/**
+ * Derives the state name from a BEM modifier class: the segment after the last `--`
+ * (`custom-states--featured` → `featured`, `card__label--in-progress` → `in-progress`).
+ * Falls back to the whole modifier when no `--` is present.
+ */
+export function stateNameFromModifier(modifier: string): string {
+  const separatorIndex = modifier.lastIndexOf('--')
+  return separatorIndex >= 0 ? modifier.slice(separatorIndex + 2) : modifier
+}