@wix/zero-config-implementation 1.105.0 → 1.107.0

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

@@ -1,6 +1,5 @@
 import type {
   CssCustomPropertyItem,
-  CssNumber,
   CssPropertyItem,
   CustomPropertyEnum,
   DataItem,
@@ -17,7 +16,7 @@ import { buildRefElementManifestKey } from '../extensions/ref-elements/path-util
 import type { RefElementMatch } from '../extensions/ref-elements/types'
 import type { ComponentInfoWithCss } from '../index'
 import { cssPropertyTypeFromUsages, inferCssDataType, stripVarFallback } from '../information-extractors/css/parse'
-import type { MatchedCssData, RegisteredCustomProperty } from '../information-extractors/css/types'
+import type { CssSelectorMatch, MatchedCssData, RegisteredCustomProperty } from '../information-extractors/css/types'
 import type {
   CoupledComponentInfo,
   CoupledProp,
@@ -78,15 +77,59 @@ function collectStateClassTriggers(component: ComponentInfoWithCss): StateClassT
 const EXCLUDED_PROPS = new Set(['id', 'className', 'elementProps', 'wix'])
 
 export function toEditorReactComponent(component: ComponentInfoWithCss): EditorReactComponent {
-  const nearestCommonAncestorCustomProps = buildNearestCommonAncestorCustomProps(component)
+  const statesByTraceId = buildStatesByTraceId(component)
+  const nearestCommonAncestorCustomProps = buildNearestCommonAncestorCustomProps(component, statesByTraceId)
   return {
-    editorElement: buildEditorElement(component, nearestCommonAncestorCustomProps),
+    editorElement: buildEditorElement(component, nearestCommonAncestorCustomProps, statesByTraceId),
   }
 }
 
+/** The `states` block of every emitted element, keyed by traceId. */
+type StatesByTraceId = Map<string, States>
+
+/**
+ * Builds every element's `states` block up front, so CSS defaults can be split per state
+ * before the element entries are assembled. 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. Prop triggers (`ElementState<>`) are component-level and
+ * attach to the root only. Ref elements (and their subtrees) emit no states.
+ */
+function buildStatesByTraceId(component: ComponentInfoWithCss): StatesByTraceId {
+  const statesByTraceId: StatesByTraceId = new Map()
+  const rootElement = component.elements[0]
+  if (!rootElement) return statesByTraceId
+
+  const stateClassTriggers = collectStateClassTriggers(component)
+  const rootPropTriggers = Object.values(component.props).filter((prop) => prop.isStateTrigger)
+
+  const visit = (element: ExtractedElement, isRootElement: boolean): void => {
+    if (!isRootElement && element.extractorData.get('ref-element')) return
+    const semanticClass = getSemanticBlockName(element)
+    const states = mergeStates(
+      semanticClass ? buildStatesBlock(element, semanticClass, stateClassTriggers.focus) : undefined,
+      buildCustomStatesBlock({
+        element,
+        propTriggers: isRootElement ? rootPropTriggers : [],
+        classTriggers: stateClassTriggers.custom,
+      }),
+    )
+    if (states) statesByTraceId.set(element.traceId, states)
+    for (const child of element.children) visit(child, false)
+  }
+  visit(rootElement, true)
+
+  return statesByTraceId
+}
+
+function stateNamesOf(statesByTraceId: StatesByTraceId, traceId: string): string[] {
+  return Object.keys(statesByTraceId.get(traceId) ?? {})
+}
+
 function buildEditorElement(
   component: ComponentInfoWithCss,
   nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
+  statesByTraceId: StatesByTraceId,
 ): EditorElement {
   const rootElement = component.elements[0]
   if (!rootElement) {
@@ -98,23 +141,9 @@ function buildEditorElement(
   const childElements = rootElement.children
   const rootCustomProps = nearestCommonAncestorCustomProps.get(rootElement.traceId) ?? {}
 
-  const stateClassTriggers = collectStateClassTriggers(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 rootSemanticClasses = rootSemanticClass ? [rootSemanticClass] : []
-  const rootStates = rootElement
-    ? mergeStates(
-        rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass, stateClassTriggers.focus) : undefined,
-        buildCustomStatesBlock({
-          element: rootElement,
-          propTriggers: Object.values(component.props).filter((prop) => prop.isStateTrigger),
-          classTriggers: stateClassTriggers.custom,
-        }),
-      )
-    : undefined
+  const rootStates = statesByTraceId.get(rootElement.traceId)
 
   const displayGroups = buildActiveItemDisplayGroups(component.props)
   const displayFilters = buildActiveItemIndexDisplayFilters(component.props)
@@ -126,12 +155,12 @@ function buildEditorElement(
     elements: buildElements(
       childElements,
       nearestCommonAncestorCustomProps,
-      stateClassTriggers,
+      statesByTraceId,
       rootSemanticClasses,
       component.innerElementProps,
       component.propUsages,
     ),
-    cssProperties: buildCssProperties(rootElement, true),
+    cssProperties: buildCssProperties(rootElement, true, stateNamesOf(statesByTraceId, rootElement.traceId)),
     cssCustomProperties: rootCustomProps,
     ...(rootStates && { states: rootStates }),
     ...(displayGroups && { displayGroups }),
@@ -202,7 +231,7 @@ function buildData(
 function buildElements(
   elements: ExtractedElement[],
   nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
-  stateClassTriggers: StateClassTriggers,
+  statesByTraceId: StatesByTraceId,
   ancestorSemanticClasses: string[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
@@ -228,15 +257,9 @@ function buildElements(
     const semanticClass = getSemanticBlockName(element)
 
     const data = innerEntry && propUsages ? buildData(innerEntry.props, propUsages) : undefined
-    const cssProps = buildCssProperties(element, false)
+    const cssProps = buildCssProperties(element, false, stateNamesOf(statesByTraceId, element.traceId))
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
-
-    // 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, stateClassTriggers.focus) : undefined,
-      buildCustomStatesBlock({ element, propTriggers: [], classTriggers: stateClassTriggers.custom }),
-    )
+    const states = statesByTraceId.get(element.traceId)
 
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
@@ -257,7 +280,7 @@ function buildElements(
             ? buildElements(
                 element.children,
                 nearestCommonAncestorCustomProps,
-                stateClassTriggers,
+                statesByTraceId,
                 semanticClass ? [...ancestorSemanticClasses, semanticClass] : ancestorSemanticClasses,
                 innerElementProps,
                 propUsages,
@@ -283,8 +306,10 @@ function buildElements(
  */
 function buildNearestCommonAncestorCustomProps(
   component: ComponentInfoWithCss,
+  statesByTraceId: StatesByTraceId,
 ): Map<string, Record<string, CssCustomPropertyItem>> {
   const parentMap = buildParentMap(component.elements)
+  const elementsByTraceId = buildElementsByTraceId(component.elements)
   const rootTraceId = component.elements[0]?.traceId
 
   // Custom properties registered via the standard @property at-rule — the declared
@@ -307,7 +332,13 @@ function buildNearestCommonAncestorCustomProps(
 
   // Emit every declared variable plus every @property registration — a registered var
   // may have no element-level declaration yet still needs a typed control.
-  const varNames = new Set<string>([...allCustomPropertyValues.keys(), ...registeredByVar.keys()])
+  // Variables declared only under a state (`.root:hover { --x: … }`) have no regular default
+  // but still get a control on their declaring element, carrying the state default.
+  const varNames = new Set<string>([
+    ...allCustomPropertyValues.keys(),
+    ...registeredByVar.keys(),
+    ...collectStateDeclaredVarNames(component.elements, statesByTraceId),
+  ])
 
   const nearestCommonAncestorCustomProps = new Map<string, Record<string, CssCustomPropertyItem>>()
 
@@ -320,7 +351,7 @@ function buildNearestCommonAncestorCustomProps(
     const defaultValue = allCustomPropertyValues.get(varName) ?? registration?.defaultValue
 
     // Declaration wins over usage; multiple declaring elements resolve to their NCA.
-    const definingTraceIds = findDefiningElements(component.elements, varName)
+    const definingTraceIds = findDefiningElements(component.elements, varName, statesByTraceId)
 
     let nearestCommonAncestorTraceId: string | undefined
     if (definingTraceIds.size > 0) {
@@ -342,21 +373,28 @@ function buildNearestCommonAncestorCustomProps(
 
     if (!nearestCommonAncestorTraceId) continue
 
-    // A @property registration is the top-priority type source; otherwise infer from usage.
+    const statesDefaultValues = buildCustomPropertyStatesDefaultValues(
+      elementsByTraceId.get(nearestCommonAncestorTraceId),
+      stateNamesOf(statesByTraceId, nearestCommonAncestorTraceId),
+      varName,
+      defaultValue,
+    )
+    // A @property registration is the top-priority type source; otherwise infer from usage,
+    // then from the value — a state value when the variable has no regular declaration.
+    const valueForTypeInference = defaultValue ?? Object.values(statesDefaultValues ?? {})[0] ?? ''
     const cssPropertyType = registration
       ? registration.cssPropertyType
-      : getVarPropertyTypeFromCssInfos(varName, defaultValue ?? '', component.css)
+      : getVarPropertyTypeFromCssInfos(varName, valueForTypeInference, component.css)
     const customEnum = buildCustomEnum(registration)
-    const numberLimits = buildCssNumber(registration, cssPropertyType)
     const cleanVarName = varName.startsWith('--') ? varName.slice(2) : varName
 
     const existingProps = nearestCommonAncestorCustomProps.get(nearestCommonAncestorTraceId) ?? {}
     existingProps[cleanVarName] = {
       displayName: formatDisplayName(cleanVarName),
       ...(defaultValue !== undefined && { defaultValue }),
+      ...(statesDefaultValues && { statesDefaultValues }),
       ...(cssPropertyType !== undefined && { cssPropertyType }),
       ...(customEnum && { customEnum }),
-      ...(numberLimits && { number: numberLimits }),
     }
     nearestCommonAncestorCustomProps.set(nearestCommonAncestorTraceId, existingProps)
   }
@@ -364,6 +402,65 @@ function buildNearestCommonAncestorCustomProps(
   return nearestCommonAncestorCustomProps
 }
 
+/**
+ * Reads the per-state values a variable is declared with on its placement element. Only the
+ * placement element's own state declarations count: a value declared under `:hover` on a
+ * descendant belongs to that descendant's state, not to the ancestor the variable was placed on.
+ * Values equal to the regular default are omitted.
+ */
+function buildCustomPropertyStatesDefaultValues(
+  placementElement: ExtractedElement | undefined,
+  stateNames: string[],
+  varName: string,
+  defaultValue: string | undefined,
+): Record<string, string> | undefined {
+  const matcherData = placementElement?.extractorData.get('css-matcher') as MatchedCssData | undefined
+  const statesDefaultValues: Record<string, string> = {}
+  for (const stateName of stateNames) {
+    const stateValue = matcherData?.stateCustomProperties?.[stateName]?.[varName]
+    if (stateValue !== undefined && stateValue !== defaultValue) statesDefaultValues[stateName] = stateValue
+  }
+  return Object.keys(statesDefaultValues).length > 0 ? statesDefaultValues : undefined
+}
+
+/**
+ * The custom properties an element declares under each state it exposes. Declarations under a
+ * CSS state the element has no `states` entry for are left out — there is nowhere to attach them.
+ */
+function exposedStateCustomProperties(
+  element: ExtractedElement,
+  statesByTraceId: StatesByTraceId,
+): Record<string, string>[] {
+  const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+  return stateNamesOf(statesByTraceId, element.traceId).flatMap((stateName) => {
+    const stateCustomProperties = matcherData?.stateCustomProperties?.[stateName]
+    return stateCustomProperties ? [stateCustomProperties] : []
+  })
+}
+
+/** Collects every variable declared under an exposed state anywhere in the element tree. */
+function collectStateDeclaredVarNames(elements: ExtractedElement[], statesByTraceId: StatesByTraceId): Set<string> {
+  const varNames = new Set<string>()
+  for (const element of elements) {
+    for (const stateCustomProperties of exposedStateCustomProperties(element, statesByTraceId)) {
+      for (const varName of Object.keys(stateCustomProperties)) varNames.add(varName)
+    }
+    for (const varName of collectStateDeclaredVarNames(element.children, statesByTraceId)) varNames.add(varName)
+  }
+  return varNames
+}
+
+function buildElementsByTraceId(elements: ExtractedElement[]): Map<string, ExtractedElement> {
+  const elementsByTraceId = new Map<string, ExtractedElement>()
+  for (const element of elements) {
+    elementsByTraceId.set(element.traceId, element)
+    for (const [traceId, descendant] of buildElementsByTraceId(element.children)) {
+      elementsByTraceId.set(traceId, descendant)
+    }
+  }
+  return elementsByTraceId
+}
+
 /**
  * Merges @property registrations across all of the component's CSS files, keyed by the
  * `--`-prefixed variable name. The first file to register a variable wins.
@@ -393,42 +490,6 @@ function buildCustomEnum(registration: RegisteredCustomProperty | undefined): Cu
   }
 }
 
-function parseFiniteDescriptor(rawValue: string | undefined): number | undefined {
-  const trimmed = rawValue?.trim()
-  if (!trimmed) return undefined
-  const parsed = Number(trimmed)
-  return Number.isFinite(parsed) ? parsed : undefined
-}
-
-/**
- * Builds the clamp the panel's number control applies, from an @property's range
- * descriptors. Anything unusable is dropped rather than passed through.
- */
-function buildCssNumber(
-  registration: RegisteredCustomProperty | undefined,
-  cssPropertyType: CssCustomPropertyItem['cssPropertyType'],
-): CssNumber | undefined {
-  if (!registration?.range || cssPropertyType !== CSS_PROPERTIES.CSS_DATA_TYPE.number) return undefined
-
-  let min = parseFiniteDescriptor(registration.range.min)
-  let max = parseFiniteDescriptor(registration.range.max)
-  if (min !== undefined && max !== undefined && min >= max) {
-    min = undefined
-    max = undefined
-  }
-
-  const step = parseFiniteDescriptor(registration.range.step)
-  const multiplier = step !== undefined && step > 0 ? step : undefined
-
-  if (min === undefined && max === undefined && multiplier === undefined) return undefined
-
-  return {
-    ...(min !== undefined && { min: String(min) }),
-    ...(max !== undefined && { max: String(max) }),
-    ...(multiplier !== undefined && { multiplier: String(multiplier) }),
-  }
-}
-
 function getVarPropertyTypeFromCssInfos(
   varName: string,
   defaultValue: string,
@@ -516,14 +577,24 @@ function findNearestCommonAncestor(traceIds: Set<string>, parentMap: Map<string,
 }
 
 /**
- * Finds every surviving element whose matched CSS declares the given custom property.
+ * Finds every surviving element whose matched CSS declares the given custom property,
+ * in its regular appearance or in any state it exposes.
  */
-function findDefiningElements(elements: ExtractedElement[], varName: string): Set<string> {
+function findDefiningElements(
+  elements: ExtractedElement[],
+  varName: string,
+  statesByTraceId: StatesByTraceId,
+): Set<string> {
   const definingTraceIds = new Set<string>()
   for (const element of elements) {
     const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
-    if (matcherData?.customProperties[varName] !== undefined) definingTraceIds.add(element.traceId)
-    for (const traceId of findDefiningElements(element.children, varName)) definingTraceIds.add(traceId)
+    const declaresInState = exposedStateCustomProperties(element, statesByTraceId).some(
+      (stateCustomProperties) => stateCustomProperties[varName] !== undefined,
+    )
+    if (matcherData?.customProperties[varName] !== undefined || declaresInState) definingTraceIds.add(element.traceId)
+    for (const traceId of findDefiningElements(element.children, varName, statesByTraceId)) {
+      definingTraceIds.add(traceId)
+    }
   }
   return definingTraceIds
 }
@@ -533,22 +604,39 @@ function findDefiningElements(elements: ExtractedElement[], varName: string): Se
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Returns the CSS property values matched for this specific element's selector(s).
- * Reads from css-matcher.matches which is populated by matchCssSelectors.
- * When multiple rules match (e.g. .foo and .foo.dark), later match wins for same property.
+ * The CSS property values (camelCased names) declared by one layer of matches — the regular
+ * matches or one state's matches — split by whether each declaration sits inside an at-rule.
  */
-function getMatchedPropertyValues(element: ExtractedElement): Map<string, string> {
-  const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
-  const matches = matcherData?.matches
-  if (!matches || matches.length === 0) return new Map()
+interface LayerValues {
+  topLevel: Map<string, string>
+  inAtRule: Map<string, string>
+}
 
-  const values = new Map<string, string>()
-  for (const match of matches) {
+/**
+ * Collects one layer's property values. When multiple rules match (e.g. .foo and .foo.dark),
+ * later match wins for same property within each half of the layer.
+ */
+function collectPropertyValues(matches: CssSelectorMatch[] | undefined): LayerValues {
+  const layerValues: LayerValues = { topLevel: new Map(), inAtRule: new Map() }
+  for (const match of matches ?? []) {
     for (const prop of match.properties) {
-      values.set(camelCase(prop.name), prop.value)
+      const targetValues = prop.inAtRule ? layerValues.inAtRule : layerValues.topLevel
+      targetValues.set(camelCase(prop.name), prop.value)
     }
   }
-  return values
+  return layerValues
+}
+
+/**
+ * Resolves a manifest default from one layer, ignoring any `var()` fallback. Top-level
+ * declarations are resolved first, so a conditional at-rule (`@media`) value — even a longhand
+ * under a top-level shorthand — only fills in what the top level leaves undeclared: the
+ * manifest default describes the unconditional appearance.
+ */
+function resolveLayerDefault(propName: string, layerValues: LayerValues): string | undefined {
+  const resolvedValue =
+    resolveLonghand(propName, layerValues.topLevel) ?? resolveLonghand(propName, layerValues.inAtRule)
+  return resolvedValue !== undefined ? stripVarFallback(resolvedValue) : undefined
 }
 
 const { CSS_PROPERTY_TYPE, DISPLAY_VALUE } = CSS_PROPERTIES
@@ -594,6 +682,7 @@ const ROOT_EXCLUDED_CSS_PROPERTIES = new Set<string>([
 function buildCssProperties(
   element: ExtractedElement | undefined,
   isRootElement: boolean,
+  stateNames: string[],
 ): Record<string, CssPropertyItem> {
   const result: Record<string, CssPropertyItem> = {}
 
@@ -602,47 +691,78 @@ function buildCssProperties(
   if (!decidedProperties || decidedProperties.length === 0) {
     return result
   }
-  const cssPropertyValues = element ? getMatchedPropertyValues(element) : new Map<string, string>()
+  const matcherData = element?.extractorData.get('css-matcher') as MatchedCssData | undefined
+  const cssPropertyValues = collectPropertyValues(matcherData?.matches)
+  // Each state layer is resolved on its own — merging it over the regular values would let
+  // a regular longhand (`padding-top`) beat a state shorthand (`padding`).
+  const stateLayers = stateNames.flatMap((stateName) => {
+    const stateMatches = matcherData?.stateMatches?.[stateName]
+    return stateMatches ? [{ stateName, values: collectPropertyValues(stateMatches) }] : []
+  })
   for (const propName of decidedProperties) {
     if (isRootElement && ROOT_EXCLUDED_CSS_PROPERTIES.has(propName)) {
       continue
     }
     if (propName === CSS_PROPERTY_TYPE.display && element) {
       if (!isRootElement) {
-        result[propName] = buildDisplayProperty(element)
+        result[propName] = buildDisplayProperty(element, stateNames)
       }
       continue
     }
-    const resolvedValue = resolveLonghand(propName, cssPropertyValues)
-    const defaultValue = resolvedValue !== undefined ? stripVarFallback(resolvedValue) : undefined
+    const defaultValue = resolveLayerDefault(propName, cssPropertyValues)
+    const statesDefaultValues: Record<string, string> = {}
+    for (const stateLayer of stateLayers) {
+      const stateDefaultValue = resolveLayerDefault(propName, stateLayer.values)
+      if (stateDefaultValue !== undefined && stateDefaultValue !== defaultValue) {
+        statesDefaultValues[stateLayer.stateName] = stateDefaultValue
+      }
+    }
     result[propName] = {
       ...(defaultValue !== undefined && { defaultValue }),
+      ...(Object.keys(statesDefaultValues).length > 0 && { statesDefaultValues }),
     }
   }
 
   return result
 }
 
-function buildDisplayProperty(element: ExtractedElement): CssPropertyItem {
+function buildDisplayProperty(element: ExtractedElement, stateNames: string[]): CssPropertyItem {
   const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
   const resolvedFromCss = matcherData ? resolveDisplayValue(matcherData) : undefined
   const hasExplicitDisplayDeclaration =
     matcherData?.matches.some((match) => match.properties.some((property) => property.name === 'display')) ?? false
 
-  if (hasExplicitDisplayDeclaration && resolvedFromCss === undefined) {
-    return {
-      display: {
-        displayValues: [DISPLAY_VALUE.none],
-      },
-    }
+  // An explicit but unresolvable regular display leaves only `none` as a known option.
+  const isRegularDisplayUnresolved = hasExplicitDisplayDeclaration && resolvedFromCss === undefined
+  const currentEnumValue = isRegularDisplayUnresolved
+    ? undefined
+    : toDisplayEnumValue(resolvedFromCss ?? getDefaultDisplayForTag(element.tag))
+  const displayValues: DisplayEnumValue[] = currentEnumValue
+    ? [DISPLAY_VALUE.none, currentEnumValue]
+    : [DISPLAY_VALUE.none]
+
+  // Each state's effective display becomes its state default, and is offered as an option too.
+  // The state is resolved over the regular matches with its custom properties merged in, so a
+  // state that only changes the variable a regular `display: var(--layout)` reads still counts;
+  // a state's own `display` wins on specificity (and, on a tie, by coming later).
+  const statesDefaultValues: Record<string, DisplayEnumValue> = {}
+  for (const stateName of stateNames) {
+    const stateMatches = matcherData?.stateMatches?.[stateName]
+    const stateCustomProperties = matcherData?.stateCustomProperties?.[stateName]
+    if (!stateMatches && !stateCustomProperties) continue
+    const stateDisplayValue = resolveDisplayValue({
+      matches: [...(matcherData?.matches ?? []), ...(stateMatches ?? [])],
+      customProperties: { ...matcherData?.customProperties, ...stateCustomProperties },
+    })
+    if (stateDisplayValue === undefined) continue
+    const stateEnumValue = toDisplayEnumValue(stateDisplayValue)
+    if (stateEnumValue === currentEnumValue) continue
+    statesDefaultValues[stateName] = stateEnumValue
+    if (!displayValues.includes(stateEnumValue)) displayValues.push(stateEnumValue)
   }
 
-  const currentValue = resolvedFromCss ?? getDefaultDisplayForTag(element.tag)
-  const currentEnumValue = toDisplayEnumValue(currentValue)
-
   return {
-    display: {
-      displayValues: [DISPLAY_VALUE.none, currentEnumValue],
-    },
+    display: { displayValues },
+    ...(Object.keys(statesDefaultValues).length > 0 && { statesDefaultValues }),
   }
 }

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

@@ -121,6 +121,55 @@ describe('parseCss — getStateClasses', () => {
   })
 })
 
+describe('parseCss — getSelectorStateScope', () => {
+  // Selectors are keyed by css-tree's generated form, so look the single rule up by its key.
+  function scopeOf(selector: string) {
+    const api = parseCss(`${selector} { color: red; }`)
+    const [generatedSelector] = api.getAllProperties().keys()
+    return api.getSelectorStateScope(generatedSelector)
+  }
+
+  it.each([
+    ['.root', { kind: 'regular' }],
+    ['.root:hover', { kind: 'state', stateName: 'hover' }],
+    ['.root:global(.button--hover)', { kind: 'state', stateName: 'hover' }],
+    ['.root:global(.button--active)', { kind: 'state', stateName: 'active' }],
+    ['.root:active', { kind: 'state', stateName: 'active' }],
+    ['.root:focus-visible', { kind: 'state', stateName: 'focus' }],
+    ['.root:global(.button--featured)', { kind: 'state', stateName: 'featured' }],
+    ['.root:global(.button--hover):hover', { kind: 'state', stateName: 'hover' }],
+    ['.root:not([dir])', { kind: 'regular' }],
+    ['.root:not(:disabled)', { kind: 'regular' }],
+    ['.root:first-child', { kind: 'regular' }],
+    ['.root:hover .label', { kind: 'unmappedState' }],
+    ['.root:global(.button--active):hover', { kind: 'unmappedState' }],
+    ['.root:hover:focus-visible', { kind: 'unmappedState' }],
+    ['.root:is(:hover, :focus)', { kind: 'unmappedState' }],
+    ['.root:is(:global(.button--selected))', { kind: 'unmappedState' }],
+    ['.root:where(:global(.button--selected))', { kind: 'unmappedState' }],
+  ])('classifies %s', (selector, expectedScope) => {
+    expect(scopeOf(selector)).toEqual(expectedScope)
+  })
+
+  it('treats a global ancestor theme class as regular (no local base to modify)', () => {
+    expect(scopeOf(':global(.dark) .root')).toEqual({ kind: 'regular' })
+  })
+
+  it('classifies each selector of a selector list on its own', () => {
+    const api = parseCss('.root:global(.button--hover), .root:hover, .root { color: red; }')
+    expect(api.getSelectorStateScope('.root:global(.button--hover)')).toEqual({ kind: 'state', stateName: 'hover' })
+    expect(api.getSelectorStateScope('.root:hover')).toEqual({ kind: 'state', stateName: 'hover' })
+    expect(api.getSelectorStateScope('.root')).toEqual({ kind: 'regular' })
+  })
+
+  it('flags declarations inside a conditional at-rule', () => {
+    const api = parseCss('.root { color: red; } @media (min-width: 600px) { .root { background: blue; } }')
+    const properties = api.getPropertiesForSelector('.root')
+    expect(properties.find((property) => property.name === 'color')?.inAtRule).toBeUndefined()
+    expect(properties.find((property) => property.name === 'background')?.inAtRule).toBe(true)
+  })
+})
+
 describe('parseCss — @property registration', () => {
   it('maps each syntax type to its cssPropertyType and reads the initial-value default', () => {
     const registered = parseCss(`