@wix/zero-config-implementation 1.67.0 → 1.68.0

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

@@ -1,4 +1,4 @@
-import { g as x } from "./index-Ps7eUbv5.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

@@ -2364,6 +2364,7 @@ export declare interface PropInfo {
     resolvedType: ResolvedType;
     description?: string;
     deprecated?: boolean;
+    isStateTrigger?: boolean;
 }
 
 export declare interface PropSpyMeta {

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-Ps7eUbv5.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.67.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": "98b2efba108de51cc5bc3678f7b32253ba1a26e9b875964b6a8e725e"
+  "falconPackageHash": "5848ef0051ff536666dd46c6264f765b40f280afa13b5d120028a1a2"
 }

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

@@ -1,11 +1,16 @@
 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 }
 }
@@ -14,6 +19,7 @@ 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')],
     })
 
@@ -23,6 +29,7 @@ describe('buildCustomStatesBlock', () => {
   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')],
     })
 
@@ -35,6 +42,7 @@ describe('buildCustomStatesBlock', () => {
   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')],
     })
 
@@ -46,6 +54,7 @@ describe('buildCustomStatesBlock', () => {
     // 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)],
     })
 
@@ -55,15 +64,71 @@ describe('buildCustomStatesBlock', () => {
   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 class trigger targets the element', () => {
+  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: [],
     })
 

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

@@ -1,20 +1,25 @@
 /**
  * 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`.
+ * 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.
- *
- * 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 { kebabCase } from 'case-anything'
 import type { StateClassRule } from '../information-extractors/css/types'
-import type { ExtractedElement } from '../information-extractors/react'
+import type { CoupledProp, ExtractedElement } from '../information-extractors/react'
 import { isGlobalSemanticClass, stateNameFromModifier } from '../utils/css-class'
 import { formatDisplayName } from './utils'
 
@@ -23,17 +28,44 @@ 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, classTriggers }: BuildCustomStatesParams): States | undefined {
+export function buildCustomStatesBlock({
+  element,
+  propTriggers,
+  classTriggers,
+}: BuildCustomStatesParams): States | undefined {
   const states: States = {}
 
-  // Custom-class triggers that target this element.
+  // 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
-    const stateName = stateNameFromModifier(rule.modifier)
+    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,
@@ -43,6 +75,16 @@ export function buildCustomStatesBlock({ element, classTriggers }: BuildCustomSt
   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`).

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

@@ -29,7 +29,7 @@ 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
+ * 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 {
@@ -75,7 +75,11 @@ function buildEditorElement(
   const rootStates = rootElement
     ? mergeStates(
         rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass) : undefined,
-        buildCustomStatesBlock({ element: rootElement, classTriggers: customClassTriggers }),
+        buildCustomStatesBlock({
+          element: rootElement,
+          propTriggers: Object.values(component.props).filter((prop) => prop.isStateTrigger),
+          classTriggers: customClassTriggers,
+        }),
       )
     : undefined
 
@@ -147,9 +151,11 @@ function buildElements(
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
     const semanticClass = getSemanticBlockName(element)
+    // 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, classTriggers: customClassTriggers }),
+      buildCustomStatesBlock({ element, propTriggers: [], classTriggers: customClassTriggers }),
     )
 
     result[element.name] = {

package/src/information-extractors/ts/components.test.ts

@@ -0,0 +1,29 @@
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { compileTsFile } from '../../ts-compiler'
+import { extractAllComponentInfo } from './components'
+
+const propTriggeredFixture = path.resolve(
+  __dirname,
+  '../../../../example-components/src/components/DesignStates/Custom/PropTriggered/WithMatchingClass/component.tsx',
+)
+
+describe('TS extractor — ElementState<> trigger detection', () => {
+  it('flags an ElementState<>-wrapped prop and unwraps its inner type', async () => {
+    const programResult = await compileTsFile(propTriggeredFixture)
+    expect(programResult.isOk()).toBe(true)
+    const program = programResult._unsafeUnwrap()
+
+    const components = extractAllComponentInfo(program, propTriggeredFixture)
+    const component = components.find((candidate) => candidate.componentName === 'PropStates')
+    expect(component).toBeDefined()
+
+    const isLoading = component!.props.isLoading
+    expect(isLoading.isStateTrigger).toBe(true)
+    // The `ElementState<boolean>` wrapper is unwrapped — the prop behaves as a plain boolean.
+    expect(isLoading.type).toBe('boolean')
+
+    // Plain booleans are never flagged as state triggers.
+    expect(component!.props.showLabel.isStateTrigger).toBeUndefined()
+  })
+})

package/src/information-extractors/ts/components.ts

@@ -208,16 +208,27 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
 
     // Resolve the type deeply
     let declaredTypeInfo: DeclaredTypeInfo | undefined
+    let stateTrigger: StateTriggerInfo | undefined
     if (propSymbol) {
       const decl = propSymbol.getDeclarations()?.[0]
       if (decl) {
-        declaredTypeInfo = getDeclaredTypeInfo(propSymbol, decl.getSourceFile(), checker)
+        const declSourceFile = decl.getSourceFile()
+        declaredTypeInfo = getDeclaredTypeInfo(propSymbol, declSourceFile, checker)
+        stateTrigger = detectStateTrigger(propSymbol, declSourceFile, checker)
       }
     }
 
-    const typeString = declaredTypeInfo?.name ?? propItem.type.name
+    // An `ElementState<Inner>` prop should behave as its inner type everywhere except
+    // for the `isStateTrigger` flag, so unwrap the inner type for `type` and resolution
+    // (and drop the `ElementState` declared symbol so it isn't mistaken for a semantic type).
+    const typeString = stateTrigger?.innerTypeName ?? declaredTypeInfo?.name ?? propItem.type.name
     const resolvedType = propType
-      ? resolveType({ type: propType, checker, typeString, declaredSymbol: declaredTypeInfo?.symbol })
+      ? resolveType({
+          type: propType,
+          checker,
+          typeString,
+          declaredSymbol: stateTrigger ? undefined : declaredTypeInfo?.symbol,
+        })
       : { kind: 'primitive' as const, value: propItem.type.name }
 
     // Convert default value
@@ -239,6 +250,7 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
       resolvedType,
       description: propItem.description || undefined,
       deprecated: tags?.deprecated !== undefined ? true : undefined,
+      isStateTrigger: stateTrigger ? true : undefined,
     }
   }
 
@@ -477,6 +489,63 @@ interface DeclaredTypeInfo {
   symbol?: ts.Symbol
 }
 
+interface StateTriggerInfo {
+  /** Text of the inner type argument, e.g. `'boolean'`. */
+  innerTypeName: string
+}
+
+/**
+ * Detects when a prop is declared with the `ElementState<>` marker type from
+ * `@wix/react-component-utils` (e.g. `isLoading?: ElementState<boolean>`), which opts
+ * the prop in as the trigger for a custom design state. Returns the inner type
+ * argument so callers can treat the prop as its underlying type. Returns
+ * `undefined` for any other declaration.
+ */
+function detectStateTrigger(
+  prop: ts.Symbol,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): StateTriggerInfo | undefined {
+  const declaration = prop.getDeclarations()?.[0]
+  if (!declaration) return undefined
+
+  if (
+    !(ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration) || ts.isParameter(declaration)) ||
+    !declaration.type ||
+    !ts.isTypeReferenceNode(declaration.type) ||
+    !declaration.type.typeArguments ||
+    declaration.type.typeArguments.length !== 1
+  ) {
+    return undefined
+  }
+
+  const typeName = declaration.type.typeName
+  const identifier = ts.isIdentifier(typeName) ? typeName : typeName.right
+  if (identifier.text !== 'ElementState') return undefined
+  if (!isElementStateAliasFromUtils(identifier, checker)) return undefined
+
+  return { innerTypeName: declaration.type.typeArguments[0].getText(sourceFile) }
+}
+
+/**
+ * Confirms an identifier referencing `ElementState` resolves to the marker type
+ * alias exported by `@wix/react-component-utils`, rather than an unrelated local
+ * type that happens to be named `ElementState`.
+ */
+function isElementStateAliasFromUtils(identifier: ts.Identifier, checker: ts.TypeChecker): boolean {
+  let symbol = checker.getSymbolAtLocation(identifier)
+  if (!symbol) return false
+  if ((symbol.getFlags() & ts.SymbolFlags.Alias) !== 0) {
+    symbol = checker.getAliasedSymbol(symbol)
+  }
+
+  const declaration = symbol.getDeclarations()?.[0]
+  if (!declaration || !ts.isTypeAliasDeclaration(declaration)) return false
+  if (declaration.name.text !== 'ElementState') return false
+
+  return declaration.getSourceFile().fileName.includes('react-component-utils')
+}
+
 function getDeclaredTypeInfo(
   prop: ts.Symbol,
   sourceFile: ts.SourceFile,

package/src/information-extractors/ts/types.ts

@@ -51,6 +51,11 @@ export interface PropInfo {
   description?: string
   // Whether the prop is marked as deprecated via @deprecated JSDoc tag
   deprecated?: boolean
+  // True when the prop is wrapped in the `ElementState<>` marker type from
+  // @wix/react-component-utils, declaring it as the trigger for a custom design
+  // state. `type` and `resolvedType` reflect the unwrapped inner type, so the prop
+  // still behaves as a normal data prop everywhere else.
+  isStateTrigger?: boolean
 }
 
 export interface ComponentInfo {