@wix/zero-config-implementation 1.66.0 → 1.68.0

package/dist/{index-CtX9f415.js → index-DTB9iwv9.js}

@@ -1,4 +1,4 @@
-import { g as x } from "./index-BEdi2EUy.js";
+import { g as x } from "./index-BewAGOQY.js";
 function h(r, a) {
   for (var i = 0; i < a.length; i++) {
     const o = a[i];

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
  */
@@ -2356,6 +2364,7 @@ export declare interface PropInfo {
     resolvedType: ResolvedType;
     description?: string;
     deprecated?: boolean;
+    isStateTrigger?: boolean;
 }
 
 export declare interface PropSpyMeta {
@@ -2644,6 +2653,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-BEdi2EUy.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-BewAGOQY.js";
 import "react";
 export {
   t as BaseError,

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.66.0",
+  "version": "1.68.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -81,5 +81,5 @@
       ]
     }
   },
-  "falconPackageHash": "2a3fd8ab08ce40ac87e3bf2f07ad6928e67ddb1262856b12f593624b"
+  "falconPackageHash": "5848ef0051ff536666dd46c6264f765b40f280afa13b5d120028a1a2"
 }

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

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest'
+import type { ExtractedElement } from '../information-extractors/react'
+import type { CoupledProp } from '../information-extractors/react/types'
+import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
+
+function elementWithClass(classAttribute: string): ExtractedElement {
+  return { attributes: { class: classAttribute } } as unknown as ExtractedElement
+}
+
+function booleanStateProp(name: string): CoupledProp {
+  return { name, type: 'boolean', isStateTrigger: true } as unknown as CoupledProp
+}
+
+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'),
+      propTriggers: [],
+      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'),
+      propTriggers: [],
+      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'),
+      propTriggers: [],
+      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'),
+      propTriggers: [],
+      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'),
+      propTriggers: [],
+      classTriggers: [classTrigger('.root', 'test-comp-card--featured', true)],
+    })
+
+    expect(states).toBeUndefined()
+  })
+
+  it('returns undefined when no trigger targets the element', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('custom-states'),
+      propTriggers: [],
+      classTriggers: [],
+    })
+
+    expect(states).toBeUndefined()
+  })
+
+  it('emits a props-only state for a prop trigger with no matching class (no className synthesized)', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('panel'),
+      propTriggers: [booleanStateProp('isExpanded')],
+      classTriggers: [],
+    })
+
+    expect(states).toEqual({
+      'is-expanded': { displayName: 'Is Expanded', props: { isExpanded: true } },
+    })
+  })
+
+  it('keeps the full prop name in the state key and displayName (no is/has stripping)', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('widget'),
+      propTriggers: [booleanStateProp('isLoading')],
+      classTriggers: [],
+    })
+
+    expect(states?.['is-loading']).toEqual({
+      displayName: 'Is Loading',
+      props: { isLoading: true },
+    })
+  })
+
+  it('merges a prop trigger with a class trigger that resolves to the same state name', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('prop-states'),
+      propTriggers: [booleanStateProp('isLoading')],
+      classTriggers: [classTrigger('.prop-states', 'prop-states--is-loading')],
+    })
+
+    expect(states).toEqual({
+      'is-loading': {
+        displayName: 'Is Loading',
+        className: 'prop-states--is-loading',
+        props: { isLoading: true },
+      },
+    })
+  })
+
+  it('ignores plain (non-ElementState) props and non-boolean state triggers', () => {
+    const states = buildCustomStatesBlock({
+      element: elementWithClass('custom-states'),
+      propTriggers: [
+        { name: 'showLabel', type: 'boolean' } as unknown as CoupledProp,
+        { name: 'variant', type: "'a' | 'b'", isStateTrigger: true } as unknown as CoupledProp,
+      ],
+      classTriggers: [],
+    })
+
+    expect(states).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,117 @@
+/**
+ * Builds the custom (non-native) `states` entries for an element.
+ *
+ * Two triggers feed this, per the agreed design — props are looked at first:
+ *   - Prop        — a boolean prop wrapped in `ElementState<>` (TS extractor sets
+ *                    `isStateTrigger`) IS a custom state, emitting
+ *                    `props: { <prop>: true }`. The CSS is then searched for a
+ *                    class trigger matching that state's name — when found it
+ *                    supplies the editor-trigger `className`; otherwise the entry
+ *                    is props-only (`className` is never synthesized).
+ *   - Custom class — a `:global(.modifier)` class on the element with no paired
+ *                    native pseudo (CSS extractor `getStateClasses`) and not
+ *                    claimed by a prop trigger. Emits the modifier as a
+ *                    className-only state.
+ *
+ * Native states are built separately and take precedence on any key collision.
+ */
+
+import type { States } from '@wix/react-component-schema'
+import { kebabCase } from 'case-anything'
+import type { StateClassRule } from '../information-extractors/css/types'
+import type { CoupledProp, 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
+  /** Prop triggers in scope for this element (root-level `ElementState<>` props; `[]` for inner elements). */
+  propTriggers: CoupledProp[]
+  /** Custom-class triggers (modifiers with no paired native pseudo) across all CSS files. */
+  classTriggers: CustomClassTrigger[]
+}
+
+export function buildCustomStatesBlock({
+  element,
+  propTriggers,
+  classTriggers,
+}: BuildCustomStatesParams): States | undefined {
+  const states: States = {}
+
+  // Class triggers that target this element, keyed by their derived state name,
+  // so prop triggers can look up their matching class.
+  const elementClassTriggers = new Map<string, CustomClassTrigger>()
+  for (const rule of classTriggers) {
+    if (!elementMatchesBase(element, rule.baseSelector, rule.isCssModule)) continue
+    elementClassTriggers.set(stateNameFromModifier(rule.modifier), rule)
+  }
+
+  // Prop triggers first: each boolean `ElementState<>` prop is a custom state.
+  // Then search the CSS for the class trigger matching that state's name — when
+  // found it supplies the editor-trigger className; otherwise props-only.
+  for (const prop of propTriggers) {
+    if (!prop.isStateTrigger || prop.type !== 'boolean') continue
+    const stateName = stateNameFromProp(prop.name)
+    const matchingClassTrigger = elementClassTriggers.get(stateName)
+    states[stateName] = {
+      displayName: formatDisplayName(stateName),
+      ...(matchingClassTrigger && { className: matchingClassTrigger.modifier }),
+      props: { [prop.name]: true },
+    }
+  }
+
+  // Remaining class triggers — those not claimed by a prop — are className-only states.
+  for (const [stateName, rule] of elementClassTriggers) {
+    if (states[stateName] !== undefined) continue
+    states[stateName] = {
+      displayName: formatDisplayName(stateName),
+      className: rule.modifier,
+    }
+  }
+
+  return Object.keys(states).length > 0 ? states : undefined
+}
+
+/**
+ * Derives the state name from a boolean prop by kebab-casing the full prop name
+ * (`isLoading` → `is-loading`, so the displayName reads "Is Loading"). The prop
+ * name is kept whole — no `is`/`has` prefix stripping — so the state key mirrors
+ * the prop that triggers it.
+ */
+function stateNameFromProp(propName: string): string {
+  return kebabCase(propName)
+}
+
+/**
+ * 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/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,10 +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 `ElementState<>` 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'])
 
@@ -43,8 +66,22 @@ 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 && rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass) : undefined
+  const rootStates = rootElement
+    ? mergeStates(
+        rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass) : undefined,
+        buildCustomStatesBlock({
+          element: rootElement,
+          propTriggers: Object.values(component.props).filter((prop) => prop.isStateTrigger),
+          classTriggers: customClassTriggers,
+        }),
+      )
+    : undefined
 
   return {
     selector: buildSelector(rootElement),
@@ -53,6 +90,7 @@ function buildEditorElement(
     elements: buildElements(
       childElements,
       nearestCommonAncestorCustomProps,
+      customClassTriggers,
       component.innerElementProps,
       component.propUsages,
     ),
@@ -100,6 +138,7 @@ function buildData(
 function buildElements(
   elements: ExtractedElement[],
   nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
+  customClassTriggers: CustomClassTrigger[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
 ): Record<string, ElementItem> {
@@ -112,7 +151,12 @@ function buildElements(
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
     const semanticClass = getSemanticBlockName(element)
-    const states = semanticClass ? buildStatesBlock(element, semanticClass) : undefined
+    // Inner-element custom states come from custom-class triggers only; prop
+    // triggers (`ElementState<>`) are component-level and attach to the root.
+    const states = mergeStates(
+      semanticClass ? buildStatesBlock(element, semanticClass) : undefined,
+      buildCustomStatesBlock({ element, propTriggers: [], classTriggers: customClassTriggers }),
+    )
 
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
@@ -130,7 +174,13 @@ function buildElements(
         // 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([])
+  })
+})