@wix/zero-config-implementation 1.65.0 → 1.67.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/react/extractors/index.ts

@@ -31,3 +31,6 @@ export {
   getDefaultDisplayForTag,
 } from './css-properties'
 export type { CssPropertiesData } from './css-properties'
+
+export { inferSupportedNativeStates } from './state-markers'
+export type { SupportedNativeStates } from './state-markers'

package/src/information-extractors/react/extractors/prop-tracker.ts

@@ -20,6 +20,8 @@ export interface PropTrackerData {
   role?: string
   boundProps: string[]
   concatenatedAttrs: Map<string, string> // attrName → propName (for concatenated values)
+  /** on*-handler prop names whose value is a function on this element (e.g. ['onClick', 'onChange']). */
+  eventHandlers: string[]
 }
 
 export interface PropTrackerExtractorState {
@@ -110,10 +112,15 @@ export function createPropTrackerExtractor(): {
 
       const boundProps = new Set<string>()
       const concatenatedAttrs = new Map<string, string>()
+      const eventHandlers: string[] = []
 
       Object.entries(props).forEach(([key, value]) => {
         if (key.startsWith('__') || key === TRACE_ATTR) return
 
+        if (typeof value === 'function' && key.length > 2 && key.startsWith('on') && key[2] === key[2].toUpperCase()) {
+          eventHandlers.push(key)
+        }
+
         const spies = extractSpies(value)
 
         spies.forEach((spy) => {
@@ -141,6 +148,7 @@ export function createPropTrackerExtractor(): {
         role: htmlProps.role,
         boundProps: [...boundProps],
         concatenatedAttrs,
+        eventHandlers,
       }
       store.set(traceId, 'prop-tracker', data)
     },

package/src/information-extractors/react/extractors/state-markers.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest'
+import type { ExtractedElement } from './core/tree-builder'
+import type { PropTrackerData } from './prop-tracker'
+import { inferSupportedNativeStates } from './state-markers'
+
+function makeElement(input: {
+  tag: string
+  attributes?: Record<string, string>
+  role?: string
+  eventHandlers?: string[]
+}): ExtractedElement {
+  const propTrackerData: PropTrackerData = {
+    tag: input.tag,
+    role: input.role,
+    boundProps: [],
+    concatenatedAttrs: new Map(),
+    eventHandlers: input.eventHandlers ?? [],
+  }
+  return {
+    traceId: 'trace-0',
+    name: 'root',
+    tag: input.tag,
+    attributes: input.attributes ?? {},
+    extractorData: new Map([['prop-tracker', propTrackerData]]),
+    children: [],
+  }
+}
+
+describe('inferSupportedNativeStates', () => {
+  describe('hover + focus (interactive)', () => {
+    it('returns true for native form tags', () => {
+      for (const tag of ['button', 'a', 'input', 'select', 'textarea', 'summary']) {
+        const states = inferSupportedNativeStates(makeElement({ tag }))
+        expect(states.hover, `hover for <${tag}>`).toBe(true)
+        expect(states.focus, `focus for <${tag}>`).toBe(true)
+      }
+    })
+
+    it('returns true when role is interactive', () => {
+      const interactiveRoles = ['switch', 'checkbox', 'tab', 'menuitem', 'combobox', 'slider']
+      for (const role of interactiveRoles) {
+        const states = inferSupportedNativeStates(makeElement({ tag: 'div', role }))
+        expect(states.hover, `hover for role=${role}`).toBe(true)
+        expect(states.focus, `focus for role=${role}`).toBe(true)
+      }
+    })
+
+    it('returns true when any pointer/keyboard/form event handler is present', () => {
+      const handlers = ['onClick', 'onPointerDown', 'onFocus', 'onKeyDown', 'onChange']
+      for (const handler of handlers) {
+        const states = inferSupportedNativeStates(makeElement({ tag: 'div', eventHandlers: [handler] }))
+        expect(states.hover, `hover for ${handler}`).toBe(true)
+        expect(states.focus, `focus for ${handler}`).toBe(true)
+      }
+    })
+
+    it('returns false for a plain div with no signals', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'div' }))
+      expect(states.hover).toBe(false)
+      expect(states.focus).toBe(false)
+    })
+
+    it('reads role from the rendered attributes when prop-tracker data is absent', () => {
+      const element: ExtractedElement = {
+        traceId: 'trace-0',
+        name: 'root',
+        tag: 'div',
+        attributes: { role: 'button' },
+        extractorData: new Map(),
+        children: [],
+      }
+      const states = inferSupportedNativeStates(element)
+      expect(states.hover).toBe(true)
+      expect(states.focus).toBe(true)
+    })
+  })
+
+  describe('disabled', () => {
+    it('returns true for form-disableable native tags', () => {
+      for (const tag of ['button', 'input', 'select', 'textarea', 'fieldset']) {
+        const states = inferSupportedNativeStates(makeElement({ tag }))
+        expect(states.disabled, `disabled for <${tag}>`).toBe(true)
+      }
+    })
+
+    it('returns true for form-control roles', () => {
+      for (const role of ['button', 'switch', 'checkbox', 'radio', 'menuitem', 'tab', 'option', 'link']) {
+        const states = inferSupportedNativeStates(makeElement({ tag: 'div', role }))
+        expect(states.disabled, `disabled for role=${role}`).toBe(true)
+      }
+    })
+
+    it('returns false for plain divs and non-form roles', () => {
+      expect(inferSupportedNativeStates(makeElement({ tag: 'div' })).disabled).toBe(false)
+      expect(inferSupportedNativeStates(makeElement({ tag: 'div', role: 'navigation' })).disabled).toBe(false)
+    })
+  })
+
+  describe('invalid', () => {
+    it('returns true for form-validatable native tags', () => {
+      for (const tag of ['input', 'select', 'textarea', 'form']) {
+        const states = inferSupportedNativeStates(makeElement({ tag }))
+        expect(states.invalid, `invalid for <${tag}>`).toBe(true)
+      }
+    })
+
+    it('returns false for a plain button (not form-validatable)', () => {
+      expect(inferSupportedNativeStates(makeElement({ tag: 'button' })).invalid).toBe(false)
+    })
+
+    it('ignores the aria-invalid attribute on non-form tags', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'div', attributes: { 'aria-invalid': 'true' } }))
+      expect(states.invalid).toBe(false)
+    })
+  })
+
+  describe('role="presentation" / "none" opt-out', () => {
+    it('suppresses every native state when role is "presentation"', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'button', role: 'presentation' }))
+      expect(states).toEqual({ hover: false, focus: false, disabled: false, invalid: false })
+    })
+
+    it('suppresses every native state when role is "none"', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'input', role: 'none' }))
+      expect(states).toEqual({ hover: false, focus: false, disabled: false, invalid: false })
+    })
+  })
+
+  describe('tabindex="-1" suppresses focus', () => {
+    it('keeps hover and disabled but suppresses focus on an interactive tag with tabindex="-1"', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'button', attributes: { tabindex: '-1' } }))
+      expect(states.hover).toBe(true)
+      expect(states.focus).toBe(false)
+      expect(states.disabled).toBe(true)
+    })
+
+    it('does not affect non-interactive elements (no focus to suppress)', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'div', attributes: { tabindex: '-1' } }))
+      expect(states.focus).toBe(false)
+      expect(states.hover).toBe(false)
+    })
+  })
+})

package/src/information-extractors/react/extractors/state-markers.ts

@@ -0,0 +1,142 @@
+/**
+ * Design-state inference from React-extractor signals.
+ *
+ * The new design (Notion: "New Design") supports only the four native states
+ * (hover/focus/disabled/invalid) and derives them purely from the React side:
+ * html tag, role attribute, and event handlers. The CSS extractor is not
+ * involved.
+ */
+
+import type { ExtractedElement } from './core/tree-builder'
+import type { PropTrackerData } from './prop-tracker'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SupportedNativeStates {
+  hover: boolean
+  focus: boolean
+  disabled: boolean
+  invalid: boolean
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Signal sets
+// ─────────────────────────────────────────────────────────────────────────────
+
+const INTERACTIVE_TAGS = new Set(['button', 'a', 'input', 'select', 'textarea', 'summary'])
+
+const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'switch',
+  'checkbox',
+  'radio',
+  'tab',
+  'option',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'treeitem',
+  'combobox',
+  'slider',
+  'spinbutton',
+  'searchbox',
+  'textbox',
+  'listbox',
+])
+
+const INTERACTIVE_EVENT_HANDLERS = new Set([
+  'onClick',
+  'onMouseDown',
+  'onMouseUp',
+  'onMouseEnter',
+  'onMouseLeave',
+  'onPointerDown',
+  'onPointerUp',
+  'onFocus',
+  'onBlur',
+  'onKeyDown',
+  'onKeyUp',
+  'onKeyPress',
+  'onChange',
+  'onInput',
+  'onSubmit',
+])
+
+const DISABLEABLE_TAGS = new Set(['button', 'input', 'select', 'textarea', 'fieldset'])
+
+const DISABLEABLE_ROLES = new Set(['button', 'switch', 'checkbox', 'radio', 'menuitem', 'tab', 'option', 'link'])
+
+const VALIDATABLE_TAGS = new Set(['input', 'select', 'textarea', 'form'])
+
+const PRESENTATION_ROLES = new Set(['presentation', 'none'])
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Inference
+// ─────────────────────────────────────────────────────────────────────────────
+
+function getRole(element: ExtractedElement): string | undefined {
+  const propTrackerData = element.extractorData.get('prop-tracker') as PropTrackerData | undefined
+  return propTrackerData?.role ?? element.attributes.role
+}
+
+function getEventHandlers(element: ExtractedElement): string[] {
+  const propTrackerData = element.extractorData.get('prop-tracker') as PropTrackerData | undefined
+  return propTrackerData?.eventHandlers ?? []
+}
+
+/**
+ * `role="presentation"` and `role="none"` strip the element's implicit ARIA
+ * semantics — a `<button role="presentation">` is no longer a button. Treat
+ * either as an explicit opt-out from every native state.
+ */
+function hasPresentationRole(role: string | undefined): boolean {
+  return role !== undefined && PRESENTATION_ROLES.has(role)
+}
+
+function hasInteractiveSignal(tag: string, role: string | undefined, eventHandlers: string[]): boolean {
+  if (INTERACTIVE_TAGS.has(tag)) return true
+  if (role !== undefined && INTERACTIVE_ROLES.has(role)) return true
+  return eventHandlers.some((handler) => INTERACTIVE_EVENT_HANDLERS.has(handler))
+}
+
+function hasDisableableSignal(tag: string, role: string | undefined): boolean {
+  if (DISABLEABLE_TAGS.has(tag)) return true
+  if (role !== undefined && DISABLEABLE_ROLES.has(role)) return true
+  return false
+}
+
+function hasValidatableSignal(tag: string): boolean {
+  return VALIDATABLE_TAGS.has(tag)
+}
+
+/**
+ * Decides which of the four native states the given element supports, based on
+ * its tag, role, and event handlers.
+ *
+ * Two attribute-level overrides apply:
+ *   - `role="presentation"` / `role="none"` opts the element out of every state.
+ *   - `tabindex="-1"` suppresses `focus` only (the element is programmatically
+ *     focusable but not via keyboard tab).
+ */
+export function inferSupportedNativeStates(element: ExtractedElement): SupportedNativeStates {
+  const tag = element.tag.toLowerCase()
+  const role = getRole(element)
+
+  if (hasPresentationRole(role)) {
+    return { hover: false, focus: false, disabled: false, invalid: false }
+  }
+
+  const eventHandlers = getEventHandlers(element)
+  const interactive = hasInteractiveSignal(tag, role, eventHandlers)
+  const isUntabbable = element.attributes.tabindex === '-1'
+
+  return {
+    hover: interactive,
+    focus: interactive && !isUntabbable,
+    disabled: hasDisableableSignal(tag, role),
+    invalid: hasValidatableSignal(tag),
+  }
+}

package/src/information-extractors/react/index.ts

@@ -19,6 +19,7 @@ export {
   enrichGapProperties,
   resolveDisplayValue,
   getDefaultDisplayForTag,
+  inferSupportedNativeStates,
 } from './extractors'
 
 export type {
@@ -34,6 +35,7 @@ export type {
   PropTrackerData,
   PropTrackerExtractorState,
   CssPropertiesData,
+  SupportedNativeStates,
 } from './extractors'
 
 // ─────────────────────────────────────────────────────────────────────────────

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
+}