@wix/zero-config-implementation 1.66.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
  */
@@ -2644,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-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-Ps7eUbv5.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.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": "2a3fd8ab08ce40ac87e3bf2f07ad6928e67ddb1262856b12f593624b"
+  "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/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 `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'])
 
@@ -43,8 +66,18 @@ 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, classTriggers: customClassTriggers }),
+      )
+    : undefined
 
   return {
     selector: buildSelector(rootElement),
@@ -53,6 +86,7 @@ function buildEditorElement(
     elements: buildElements(
       childElements,
       nearestCommonAncestorCustomProps,
+      customClassTriggers,
       component.innerElementProps,
       component.propUsages,
     ),
@@ -100,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> {
@@ -112,7 +147,10 @@ function buildElements(
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
     const semanticClass = getSemanticBlockName(element)
-    const states = semanticClass ? buildStatesBlock(element, semanticClass) : undefined
+    const states = mergeStates(
+      semanticClass ? buildStatesBlock(element, semanticClass) : undefined,
+      buildCustomStatesBlock({ element, classTriggers: customClassTriggers }),
+    )
 
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
@@ -130,7 +168,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([])
+  })
+})

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[]
 }