@wix/zero-config-implementation 1.65.0 → 1.67.0

package/dist/index.d.ts

@@ -422,6 +422,12 @@ export declare 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[];
 }
 
 export declare interface CssPropertiesData {
@@ -1577,6 +1583,8 @@ PropsTwo extends ErrorProps,
 declare type MethodOptions<PluginArg extends Plugin> =
 ExternalPluginOptions<PluginArg>
 
+declare type NativePseudoClass = 'hover' | 'focus' | 'disabled' | 'invalid';
+
 /**
  * Normalize each error in the `errors` option to `Error` instances
  */
@@ -2369,6 +2377,8 @@ export declare interface PropTrackerData {
     role?: string;
     boundProps: string[];
     concatenatedAttrs: Map<string, string>;
+    /** on*-handler prop names whose value is a function on this element (e.g. ['onClick', 'onChange']). */
+    eventHandlers: string[];
 }
 
 export declare interface PropTrackerExtractorState {
@@ -2642,6 +2652,24 @@ CauseArg extends Cause,
 > = MainInstanceOptions<AggregateErrorsArg, CauseArg> &
 PluginsOptions<PluginsArg, ChildProps>
 
+/**
+ * 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.
+ */
+declare 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;
+}
+
 /**
  * Unbound static method of a plugin
  */

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-BLr9vmnH.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-Ps7eUbv5.js";
 import "react";
 export {
   t as BaseError,

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.65.0",
+  "version": "1.67.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -81,5 +81,5 @@
       ]
     }
   },
-  "falconPackageHash": "978c6e182cced111caaef8f5bc88bdaadfdd813f14c0f9280352d625"
+  "falconPackageHash": "98b2efba108de51cc5bc3678f7b32253ba1a26e9b875964b6a8e725e"
 }

package/src/converters/custom-states-builder.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest'
+import type { ExtractedElement } from '../information-extractors/react'
+import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
+
+function elementWithClass(classAttribute: string): ExtractedElement {
+  return { attributes: { class: classAttribute } } as unknown as ExtractedElement
+}
+
+function classTrigger(baseSelector: string, modifier: string, isCssModule = false): CustomClassTrigger {
+  return { baseSelector, modifier, isCssModule }
+}
+
+describe('buildCustomStatesBlock', () => {
+  it('emits a custom-class state with className only (no props, no pseudoClass)', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('custom-states'),
+      classTriggers: [classTrigger('.custom-states', 'custom-states--featured')],
+    })
+
+    expect(states).toEqual({ featured: { displayName: 'Featured', className: 'custom-states--featured' } })
+  })
+
+  it('derives a multi-word state name from the modifier and capital-cases the displayName', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('widget'),
+      classTriggers: [classTrigger('.widget', 'widget--in-progress')],
+    })
+
+    expect(states?.['in-progress']).toEqual({
+      displayName: 'In Progress',
+      className: 'widget--in-progress',
+    })
+  })
+
+  it('does not apply a block-base class trigger to a BEM child element (plain CSS, exact match)', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('custom-states__label'),
+      classTriggers: [classTrigger('.custom-states', 'custom-states--featured')],
+    })
+
+    expect(states).toBeUndefined()
+  })
+
+  it('matches a base class rendered as a double-underscore CSS-module hash (`root__HASH`)', () => {
+    // Vite emits `[name]__[hash]` for `styles.root`; the hash carries uppercase, so it is the
+    // base element — not a BEM child. (Regression: this used to be dropped as a child.)
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('root__IWjkn wixui-test-comp-card test-comp-card'),
+      classTriggers: [classTrigger('.root', 'test-comp-card--featured', true)],
+    })
+
+    expect(states).toEqual({ featured: { displayName: 'Featured', className: 'test-comp-card--featured' } })
+  })
+
+  it('still excludes a genuine BEM child (`root__label`) from a block-base trigger in a module', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('root__label'),
+      classTriggers: [classTrigger('.root', 'test-comp-card--featured', true)],
+    })
+
+    expect(states).toBeUndefined()
+  })
+
+  it('returns undefined when no class trigger targets the element', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('custom-states'),
+      classTriggers: [],
+    })
+
+    expect(states).toBeUndefined()
+  })
+})

package/src/converters/custom-states-builder.ts

@@ -0,0 +1,75 @@
+/**
+ * Builds the custom (non-native) `states` entries for an element.
+ *
+ * The custom-class trigger feeds this: a `:global(.modifier)` class on the element
+ * with no paired native pseudo (CSS extractor `getStateClasses`). It emits the
+ * modifier as the state's editor-trigger `className`.
+ *
+ * Native states are built separately and take precedence on any key collision.
+ *
+ * Note: the prop trigger (`State<>` markers → `props` overrides) is intentionally
+ * not handled here yet — it is deferred to a follow-up PR, gated on the upstream
+ * marker-type agreement.
+ */
+
+import type { States } from '@wix/react-component-schema'
+import type { StateClassRule } from '../information-extractors/css/types'
+import type { ExtractedElement } from '../information-extractors/react'
+import { isGlobalSemanticClass, stateNameFromModifier } from '../utils/css-class'
+import { formatDisplayName } from './utils'
+
+/** A custom-class trigger tagged with whether its source file is a CSS module. */
+export type CustomClassTrigger = StateClassRule & { isCssModule: boolean }
+
+interface BuildCustomStatesParams {
+  element: ExtractedElement
+  /** Custom-class triggers (modifiers with no paired native pseudo) across all CSS files. */
+  classTriggers: CustomClassTrigger[]
+}
+
+export function buildCustomStatesBlock({ element, classTriggers }: BuildCustomStatesParams): States | undefined {
+  const states: States = {}
+
+  // Custom-class triggers that target this element.
+  for (const rule of classTriggers) {
+    if (!elementMatchesBase(element, rule.baseSelector, rule.isCssModule)) continue
+    const stateName = stateNameFromModifier(rule.modifier)
+    states[stateName] = {
+      displayName: formatDisplayName(stateName),
+      className: rule.modifier,
+    }
+  }
+
+  return Object.keys(states).length > 0 ? states : undefined
+}
+
+/**
+ * Checks whether an element's rendered class list matches a simple single-class
+ * base selector (e.g. `.root`, `.custom-states`).
+ *
+ * Exact class match always counts. For CSS-module files the Vite hash patterns also
+ * count: `localName_HASH`, `_localName_HASH`, and the double-underscore `localName__HASH`
+ * form. The catch is that `localName__HASH` is syntactically identical to a BEM child
+ * class (`localName__child`) — which denotes a *different* element and must NOT match the
+ * block's base selector. We disambiguate by shape: a real BEM child is an all-lowercase
+ * semantic name (`isGlobalSemanticClass`), whereas a module hash carries uppercase / other
+ * non-kebab characters. So only genuine BEM children are excluded; hashed base classes match.
+ */
+function elementMatchesBase(element: ExtractedElement, baseSelector: string, isCssModule: boolean): boolean {
+  const match = baseSelector.match(/^\.([\w-]+)$/)
+  if (!match) return false
+
+  const localName = match[1]
+  const classList = element.attributes.class?.split(/\s+/).filter(Boolean) ?? []
+  return classList.some((className) => {
+    if (className === localName) return true
+    if (!isCssModule) return false
+    // Genuine BEM child (`localName__<lowercase-element>`) → a different element, exclude it.
+    // A double-underscore module hash (`localName__<hash>`) is NOT semantic, so it falls through.
+    const isBemChild =
+      (className.startsWith(`${localName}__`) || className.startsWith(`_${localName}__`)) &&
+      isGlobalSemanticClass(className.replace(/^_/, ''))
+    if (isBemChild) return false
+    return className.startsWith(`${localName}_`) || className.startsWith(`_${localName}_`)
+  })
+}

package/src/converters/states-builder.ts

@@ -0,0 +1,58 @@
+/**
+ * Builds the `states` block for the root EditorElement and inline elements.
+ *
+ * Native states only (hover/focus/disabled/invalid). Signals come from the
+ * React extractor (tag, role, event handlers). The CSS extractor is not
+ * consulted.
+ *
+ * className follows BEM by appending `--<state>` to the element's own
+ * semantic class. Component authors are expected to write inner elements
+ * with full BEM class names (e.g. `toggle__label`), so the resulting state
+ * className is `<semanticClass>--<state>`:
+ *   - root  `toggle`         → `toggle--hover`
+ *   - inner `toggle__label`  → `toggle__label--hover`
+ *
+ * `props` is never emitted on native-state entries — that field is reserved
+ * for functional (non-native) states.
+ */
+
+import type { States } from '@wix/react-component-schema'
+import { NATIVE_STATE_TYPE } from '@wix/react-component-schema'
+import {
+  type ExtractedElement,
+  type SupportedNativeStates,
+  inferSupportedNativeStates,
+} from '../information-extractors/react'
+
+const STATE_DISPLAY_NAMES = {
+  hover: 'Hover',
+  focus: 'Focus',
+  disabled: 'Disabled',
+  invalid: 'Invalid',
+} as const
+
+type NativeStateName = keyof SupportedNativeStates
+
+const PSEUDO_CLASS_BY_STATE: Record<NativeStateName, NATIVE_STATE_TYPE> = {
+  hover: NATIVE_STATE_TYPE.hover,
+  focus: NATIVE_STATE_TYPE.focus,
+  disabled: NATIVE_STATE_TYPE.disabled,
+  invalid: NATIVE_STATE_TYPE.invalid,
+}
+
+export function buildStatesBlock(element: ExtractedElement, semanticClass: string): States | undefined {
+  const supported = inferSupportedNativeStates(element)
+  const states: States = {}
+
+  for (const stateName of Object.keys(supported) as NativeStateName[]) {
+    if (!supported[stateName]) continue
+
+    states[stateName] = {
+      displayName: STATE_DISPLAY_NAMES[stateName],
+      className: `${semanticClass}--${stateName}`,
+      pseudoClass: PSEUDO_CLASS_BY_STATE[stateName],
+    }
+  }
+
+  return Object.keys(states).length > 0 ? states : undefined
+}

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

@@ -6,6 +6,7 @@ import type {
   EditorElement,
   EditorReactComponent,
   ElementItem,
+  States,
 } from '@wix/react-component-schema'
 import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
 import { camelCase } from 'case-anything'
@@ -21,9 +22,32 @@ import type {
 import { getDefaultDisplayForTag, resolveDisplayValue } from '../information-extractors/react'
 import { findPreferredSemanticClass } from '../utils/css-class'
 import { resolveLonghand } from './css-longhand-resolver'
+import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
 import { buildDataItem } from './data-item-builder'
+import { buildStatesBlock } from './states-builder'
 import { formatDisplayName } from './utils'
 
+/**
+ * Merges native and custom state blocks. Native states take precedence on any
+ * key collision (e.g. an author wrapping `isDisabled` in `State<>` does not
+ * shadow the inferred native `disabled` state).
+ */
+function mergeStates(native: States | undefined, custom: States | undefined): States | undefined {
+  if (!native && !custom) return undefined
+  const merged: States = { ...custom, ...native }
+  return Object.keys(merged).length > 0 ? merged : undefined
+}
+
+/** Collects custom-class state triggers (modifiers with no paired native pseudo) across all CSS files. */
+function collectCustomClassTriggers(component: ComponentInfoWithCss): CustomClassTrigger[] {
+  return component.css.flatMap((cssInfo) =>
+    cssInfo.api
+      .getStateClasses()
+      .filter((rule) => rule.pseudoClass === undefined)
+      .map((rule) => ({ ...rule, isCssModule: cssInfo.isCssModule })),
+  )
+}
+
 // Props to exclude from data items (same as in element-data.ts)
 const EXCLUDED_PROPS = new Set(['id', 'className', 'elementProps', 'wix'])
 
@@ -42,6 +66,19 @@ function buildEditorElement(
   const childElements = rootElement?.children ?? []
   const rootCustomProps = rootElement ? (nearestCommonAncestorCustomProps.get(rootElement.traceId) ?? {}) : {}
 
+  const customClassTriggers = collectCustomClassTriggers(component)
+
+  // Native states need a semantic block name to synthesize `<block>--<state>`; custom
+  // class triggers don't (they carry the className verbatim and match the element
+  // directly), so they're built even when the element resolves no semantic class.
+  const rootSemanticClass = getSemanticBlockName(rootElement)
+  const rootStates = rootElement
+    ? mergeStates(
+        rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass) : undefined,
+        buildCustomStatesBlock({ element: rootElement, classTriggers: customClassTriggers }),
+      )
+    : undefined
+
   return {
     selector: buildSelector(rootElement),
     displayName: formatDisplayName(component.componentName),
@@ -49,14 +86,21 @@ function buildEditorElement(
     elements: buildElements(
       childElements,
       nearestCommonAncestorCustomProps,
+      customClassTriggers,
       component.innerElementProps,
       component.propUsages,
     ),
     cssProperties: buildCssProperties(rootElement),
     cssCustomProperties: rootCustomProps,
+    ...(rootStates && { states: rootStates }),
   }
 }
 
+function getSemanticBlockName(element: ExtractedElement | undefined): string | undefined {
+  if (!element?.attributes.class) return undefined
+  return findPreferredSemanticClass(element.attributes.class.split(' '))
+}
+
 function buildSelector(rootElement?: ExtractedElement): string {
   if (rootElement?.attributes.class) {
     const semanticClass = findPreferredSemanticClass(rootElement.attributes.class.split(' '))
@@ -90,6 +134,7 @@ function buildData(
 function buildElements(
   elements: ExtractedElement[],
   nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
+  customClassTriggers: CustomClassTrigger[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
 ): Record<string, ElementItem> {
@@ -101,6 +146,12 @@ function buildElements(
     const cssProps = buildCssProperties(element)
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
+    const semanticClass = getSemanticBlockName(element)
+    const states = mergeStates(
+      semanticClass ? buildStatesBlock(element, semanticClass) : undefined,
+      buildCustomStatesBlock({ element, classTriggers: customClassTriggers }),
+    )
+
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
       inlineElement: {
@@ -113,10 +164,17 @@ function buildElements(
         ...(Object.keys(cssProps).length > 0 && { cssProperties: cssProps }),
         // CSS custom properties placed on the Nearest Common Ancestor of all elements that use each variable
         ...(Object.keys(cssCustomProps).length > 0 && { cssCustomProperties: cssCustomProps }),
+        ...(states && { states }),
         // Recursively build nested elements
         elements:
           element.children.length > 0
-            ? buildElements(element.children, nearestCommonAncestorCustomProps, innerElementProps, propUsages)
+            ? buildElements(
+                element.children,
+                nearestCommonAncestorCustomProps,
+                customClassTriggers,
+                innerElementProps,
+                propUsages,
+              )
             : undefined,
       },
     }

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

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import { parseCss } from './parse'
+
+describe('parseCss — getStateClasses', () => {
+  it('extracts a custom-class modifier with no paired pseudo', () => {
+    const stateClasses = parseCss(`
+      .root:global(.custom-states--featured) {
+        border: 2px solid orange;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([
+      { baseSelector: '.root', modifier: 'custom-states--featured', pseudoClass: undefined },
+    ])
+  })
+
+  it('pairs a global modifier with a native pseudo on the same base in the same rule', () => {
+    const stateClasses = parseCss(`
+      .root:global(.toggle--hover),
+      .root:hover {
+        filter: brightness(1.05);
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([{ baseSelector: '.root', modifier: 'toggle--hover', pseudoClass: 'hover' }])
+  })
+
+  it('maps :focus-visible and :focus-within to the focus state', () => {
+    const stateClasses = parseCss(`
+      .root:global(.toggle--focus),
+      .root:focus-within {
+        outline: 2px solid;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([{ baseSelector: '.root', modifier: 'toggle--focus', pseudoClass: 'focus' }])
+  })
+
+  it('keeps modifiers on distinct base elements separate', () => {
+    const stateClasses = parseCss(`
+      .root:global(.card--featured) { color: red; }
+      .label:global(.card__label--featured) { font-weight: 700; }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([
+      { baseSelector: '.root', modifier: 'card--featured', pseudoClass: undefined },
+      { baseSelector: '.label', modifier: 'card__label--featured', pseudoClass: undefined },
+    ])
+  })
+
+  it('treats a global base class with a global modifier as base + modifier (BEM extension)', () => {
+    const stateClasses = parseCss(`
+      :global(.card):global(.card--featured) {
+        border: 2px solid orange;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([{ baseSelector: '.card', modifier: 'card--featured', pseudoClass: undefined }])
+  })
+
+  it('resolves a global base for an inner BEM element (`__`) carrying a modifier', () => {
+    const stateClasses = parseCss(`
+      :global(.card__label):global(.card__label--highlight) {
+        font-weight: 700;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([
+      { baseSelector: '.card__label', modifier: 'card__label--highlight', pseudoClass: undefined },
+    ])
+  })
+
+  it('pairs a native pseudo with a modifier when the base element is global', () => {
+    const stateClasses = parseCss(`
+      :global(.card):global(.card--hover),
+      :global(.card):hover {
+        filter: brightness(1.05);
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([{ baseSelector: '.card', modifier: 'card--hover', pseudoClass: 'hover' }])
+  })
+
+  it('anchors a modifier to the compound it sits on, ignoring a descendant combinator', () => {
+    // SCSS `.header { &:global(.card__title--selected) { .label { … } } }` compiles to a
+    // descendant selector; the modifier belongs to `.header`, not `.header .label`.
+    const stateClasses = parseCss(`
+      .header:global(.card__title--selected) .label {
+        text-decoration: underline;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([
+      { baseSelector: '.header', modifier: 'card__title--selected', pseudoClass: undefined },
+    ])
+  })
+
+  it('pairs only the same-named modifier with a pseudo when a base carries both native and custom modifiers', () => {
+    // One rule, descendant-anchored: `--hover` pairs with `:hover`; `--selected` stays custom.
+    const stateClasses = parseCss(`
+      .header:hover .label,
+      .header:global(.card__title--hover) .label,
+      .header:global(.card__title--selected) .label {
+        text-decoration: underline;
+      }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([
+      { baseSelector: '.header', modifier: 'card__title--hover', pseudoClass: 'hover' },
+      { baseSelector: '.header', modifier: 'card__title--selected', pseudoClass: undefined },
+    ])
+  })
+
+  it('ignores rules with no global modifier', () => {
+    const stateClasses = parseCss(`
+      .root:hover { cursor: pointer; }
+      .root { color: black; }
+    `).getStateClasses()
+
+    expect(stateClasses).toEqual([])
+  })
+})