@wix/zero-config-implementation 1.85.0 → 1.87.0

package/src/extensions/wix-services/service-stub.ts

@@ -0,0 +1,126 @@
+import { createServicesManager } from '@wix/services-manager'
+import type { ServicesManager, ServicesRegistrar } from '@wix/services-manager/types'
+
+/** Definitions are plain strings at runtime, so one doubles as both registry key and service id. */
+type ServiceDefinitionLike = { toString(): string }
+
+/** A thenable stub would hang `await`; a stub with `$$typeof` would be read as a React element. */
+const NEVER_STUBBED_PROPERTIES: ReadonlySet<PropertyKey> = new Set([
+  'then',
+  'catch',
+  'finally',
+  '$$typeof',
+  'toJSON',
+  'nodeType',
+])
+
+const HANDLED_SYMBOLS: ReadonlySet<symbol> = new Set([Symbol.toPrimitive, Symbol.toStringTag, Symbol.iterator])
+
+// Shared, so `stub.toString === stub.toString` holds.
+const readAsEmptyString = (): string => ''
+function* iterateAsEmpty(): Generator<never> {}
+
+// Not `Symbol.for`, whose key is global and could collide with another library's.
+const CALL_RESULT_KEY = Symbol('call-result')
+
+/**
+ * Inert but still truthy — a component branching on a stubbed flag takes the truthy path, which
+ * is why stubbed services are reported to the caller.
+ */
+function createServiceStub(servicePath: string): unknown {
+  const childStubs = new Map<PropertyKey, unknown>()
+
+  // Arrow function: callable, and owns no non-configurable props that would make the
+  // `ownKeys`/`getOwnPropertyDescriptor` traps below violate the Proxy invariants.
+  const callableTarget = (): void => {}
+
+  return new Proxy(callableTarget, {
+    get(_target, property) {
+      if (NEVER_STUBBED_PROPERTIES.has(property)) {
+        return undefined
+      }
+      if (property === Symbol.toPrimitive || property === 'valueOf' || property === 'toString') {
+        return readAsEmptyString
+      }
+      if (property === Symbol.toStringTag) {
+        return 'WixServiceStub'
+      }
+      if (property === Symbol.iterator) {
+        return iterateAsEmpty
+      }
+      if (typeof property === 'symbol') {
+        return undefined
+      }
+
+      const existingChildStub = childStubs.get(property)
+      if (existingChildStub !== undefined) {
+        return existingChildStub
+      }
+
+      const childStub = createServiceStub(`${servicePath}.${property}`)
+      childStubs.set(property, childStub)
+      return childStub
+    },
+
+    apply() {
+      const existingCallResult = childStubs.get(CALL_RESULT_KEY)
+      if (existingCallResult !== undefined) {
+        return existingCallResult
+      }
+
+      const callResult = createServiceStub(`${servicePath}()`)
+      childStubs.set(CALL_RESULT_KEY, callResult)
+      return callResult
+    },
+
+    // Mirrors `get`, so `in` never reports a property that reads back as undefined.
+    has: (_target, property) => {
+      if (NEVER_STUBBED_PROPERTIES.has(property)) {
+        return false
+      }
+      return typeof property === 'symbol' ? HANDLED_SYMBOLS.has(property) : true
+    },
+    set: () => true,
+    // No own keys, so spreading terminates instead of recursing forever.
+    ownKeys: () => [],
+    getOwnPropertyDescriptor: () => undefined,
+  })
+}
+
+export interface AutoStubFallbackOptions {
+  /** Invoked once per distinct service id. */
+  onServiceStubbed?: (serviceId: string) => void
+}
+
+/**
+ * `createServicesManager` delegates to its `parentServicesManager` for unbound definitions, so
+ * passing this as the parent turns a "Service X is not provided" throw into an inert stub.
+ */
+export function createAutoStubFallbackManager(options: AutoStubFallbackOptions = {}): ServicesManager {
+  const stubsByServiceId = new Map<string, unknown>()
+
+  const getService = (definition: ServiceDefinitionLike): never => {
+    const serviceId = definition.toString()
+
+    const existingStub = stubsByServiceId.get(serviceId)
+    if (existingStub !== undefined) {
+      return existingStub as never
+    }
+
+    const stub = createServiceStub(serviceId)
+    stubsByServiceId.set(serviceId, stub)
+    options.onServiceStubbed?.(serviceId)
+    return stub as never
+  }
+
+  const fallbackManager: ServicesManager = {
+    getService: getService as ServicesManager['getService'],
+    hasService: () => true,
+    addService: () => {},
+    addServices: () => {},
+    dispose: () => {},
+    extend: (servicesMap: ServicesRegistrar) => createServicesManager(servicesMap, fallbackManager),
+  }
+
+  return fallbackManager
+}

package/src/extensions/wix-services/wrapper.test.ts

@@ -0,0 +1,63 @@
+import { useService } from '@wix/services-manager-react'
+import type { ServiceDefinition } from '@wix/services-manager/types'
+import { TranslationsDefinition } from '@wix/viewer-service-translations/definition'
+import React, { type ComponentType } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import { wrapWithWixServices } from './wrapper'
+
+const UnregisteredDefinition = '@wix/example-unregistered-analytics' as unknown as ServiceDefinition<
+  { trackingId: string },
+  never
+>
+
+function renderThroughWrapper(Component: ComponentType<unknown>): string {
+  return renderToStaticMarkup(React.createElement(wrapWithWixServices(Component), {}))
+}
+
+describe('wrapWithWixServices', () => {
+  it('resolves a registered service to its real implementation, stubbing nothing', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const TranslatingComponent: ComponentType<unknown> = () => {
+      const translations = useService(TranslationsDefinition)
+      return React.createElement('span', null, translations.translate('app')('greeting') ?? 'fallback-text')
+    }
+
+    // The real service echoes the key back; a stub would have produced an empty string.
+    expect(renderThroughWrapper(TranslatingComponent)).toContain('<span>greeting</span>')
+    expect(warn).not.toHaveBeenCalled()
+
+    warn.mockRestore()
+  })
+
+  it('warns per extraction', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const AnalyticsComponent: ComponentType<unknown> = () => {
+      useService(UnregisteredDefinition)
+      return null
+    }
+
+    // A module-level dedupe would leave every component after the first silently degraded.
+    renderThroughWrapper(AnalyticsComponent)
+    renderThroughWrapper(AnalyticsComponent)
+
+    expect(warn).toHaveBeenCalledTimes(2)
+
+    warn.mockRestore()
+  })
+
+  it('renders a component that reads an unregistered service instead of throwing', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const AnalyticsComponent: ComponentType<unknown> = () => {
+      const analytics = useService(UnregisteredDefinition)
+      return React.createElement('div', { 'data-tracking-id': String(analytics.trackingId) }, 'rendered')
+    }
+
+    expect(renderThroughWrapper(AnalyticsComponent)).toContain('<div data-tracking-id="">rendered</div>')
+
+    warn.mockRestore()
+  })
+})

package/src/extensions/wix-services/wrapper.ts

@@ -0,0 +1,204 @@
+import { SeoServiceDefinition } from '@wix/seo-service/definition'
+import { createSeoService } from '@wix/seo-service/implementations'
+import { createServicesManager, createServicesMap } from '@wix/services-manager'
+import { ServicesManagerProvider } from '@wix/services-manager-react'
+import {
+  ProvideComponentServiceDefinition,
+  ProvideComponentServiceFactory,
+} from '@wix/services-manager-react/core-services/provide-component'
+import type { ServiceBinding } from '@wix/services-manager/types'
+import { ConfigurationDefinition } from '@wix/site-service-configuration/definition'
+import { ConfigurationService } from '@wix/site-service-configuration/implementations'
+import { DeviceInfoDefinition } from '@wix/site-service-device-info/definition'
+import { DeviceInfoService } from '@wix/site-service-device-info/implementations'
+import { EditorContextDefinition } from '@wix/site-service-editor-context/definition'
+import { EditorContextService } from '@wix/site-service-editor-context/implementations'
+import { ExperimentsDefinition } from '@wix/site-service-experiments/definition'
+import { ExperimentsService } from '@wix/site-service-experiments/implementations'
+import { LocaleDefinition } from '@wix/site-service-locale/definition'
+import { LocaleService } from '@wix/site-service-locale/implementations'
+import type { IPagesServiceConfig, Page } from '@wix/site-service-pages/definition'
+import { PagesDefinition } from '@wix/site-service-pages/definition'
+import { PagesService } from '@wix/site-service-pages/implementations'
+import { ProvideCssDefinition as SiteProvideCssDefinition } from '@wix/site-service-provide-css/definition'
+import { ProvideCssService as SiteProvideCssService } from '@wix/site-service-provide-css/implementations'
+import { RenderingContextDefinition } from '@wix/site-service-rendering-context/definition'
+import { RenderingContextService } from '@wix/site-service-rendering-context/implementations'
+import { UrlDefinition as SiteUrlDefinition } from '@wix/site-service-url/definition'
+import { UrlService as SiteUrlService } from '@wix/site-service-url/implementations'
+import { AnchorsDefinition } from '@wix/viewer-service-anchors/definition'
+import { AnchorsService } from '@wix/viewer-service-anchors/implementations'
+import { ConsentPolicyDefinition } from '@wix/viewer-service-consent-policy/definition'
+import { ConsentPolicyService } from '@wix/viewer-service-consent-policy/implementations'
+import { EnvironmentDefinition } from '@wix/viewer-service-environment/definition'
+import { EnvironmentService } from '@wix/viewer-service-environment/implementations'
+import { LinkUtilsDefinition } from '@wix/viewer-service-link-utils/definition'
+import { LinkUtilsService } from '@wix/viewer-service-link-utils/implementations'
+import { NamedSignalsDefinition } from '@wix/viewer-service-named-signals/definition'
+import { NamedSignalsService } from '@wix/viewer-service-named-signals/implementations'
+import type { IPagesServiceConfig as IViewerPagesServiceConfig } from '@wix/viewer-service-pages/definition'
+import { PagesDefinition as ViewerPagesDefinition } from '@wix/viewer-service-pages/definition'
+import { PagesService as ViewerPagesService } from '@wix/viewer-service-pages/implementations'
+import { ProvideCssDefinition } from '@wix/viewer-service-provide-css/definition'
+import { ProvideCssService } from '@wix/viewer-service-provide-css/implementations'
+import { RendererConfigurationDefinition } from '@wix/viewer-service-renderer-configuration/definition'
+import { RendererConfigurationService } from '@wix/viewer-service-renderer-configuration/implementations'
+import { SdkStateDefinition } from '@wix/viewer-service-sdk-state/definition'
+import { SdkStateService } from '@wix/viewer-service-sdk-state/implementations'
+import { SiteScrollBlockerDefinition } from '@wix/viewer-service-site-scroll-blocker/definition'
+import { SiteScrollBlockerService } from '@wix/viewer-service-site-scroll-blocker/implementations'
+import type { Topology } from '@wix/viewer-service-topology/definition'
+import { TopologyDefinition } from '@wix/viewer-service-topology/definition'
+import { TopologyService } from '@wix/viewer-service-topology/implementations'
+import { TranslationsDefinition } from '@wix/viewer-service-translations/definition'
+import { TranslationsService } from '@wix/viewer-service-translations/implementations'
+import { UrlDefinition } from '@wix/viewer-service-url/definition'
+import { UrlService } from '@wix/viewer-service-url/implementations'
+import React, { type ComponentType, type ReactNode } from 'react'
+
+import { createAutoStubFallbackManager } from './service-stub'
+
+const PLACEHOLDER_SITE_URL = 'https://wix.com'
+const PLACEHOLDER_EXPERIMENTS = {
+  'specs.thunderbolt.isClassNameToRootEnabled': true,
+}
+const PLACEHOLDER_HOME_PAGE: Page = {
+  id: 'home',
+  title: 'Home',
+  path: '/',
+  popup: false,
+}
+const PLACEHOLDER_CURRENT_PAGE: Page = {
+  id: 'audio',
+  title: 'Audio',
+  path: '/shop/audio',
+  parentPageId: 'shop',
+  popup: false,
+}
+const PLACEHOLDER_PAGES_CONFIG: IPagesServiceConfig = {
+  pages: {
+    home: { title: 'Home', path: '/', popup: false },
+    shop: { title: 'Shop', path: '/shop', parentPageId: 'home', popup: false },
+    audio: { title: 'Audio', path: '/shop/audio', parentPageId: 'shop', popup: false },
+  },
+  mainPage: PLACEHOLDER_HOME_PAGE,
+  currentPage: PLACEHOLDER_CURRENT_PAGE,
+}
+
+/** Derived, so the deprecated pages service and its successor describe the same site. */
+const PLACEHOLDER_VIEWER_PAGES_CONFIG: IViewerPagesServiceConfig = {
+  pages: Object.fromEntries(
+    Object.entries(PLACEHOLDER_PAGES_CONFIG.pages).map(([pageId, { title, path, parentPageId }]) => [
+      pageId,
+      { title, path, parentPageId },
+    ]),
+  ),
+  currentPageId: PLACEHOLDER_PAGES_CONFIG.currentPage.id,
+  mainPageId: PLACEHOLDER_PAGES_CONFIG.mainPage.id,
+}
+
+const PLACEHOLDER_TOPOLOGY: Topology = {
+  mediaRootUrl: 'https://static.wixstatic.com/',
+  staticMediaUrl: 'https://static.wixstatic.com/media',
+  fileRepoUrl: 'https://static.wixstatic.com/ugd',
+  staticHTMLComponentUrl: 'https://static.wixstatic.com/html',
+  scriptsUrl: 'https://static.parastorage.com/',
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: service bindings are heterogeneous by construction
+type AnyServiceBinding = ServiceBinding<any, any>
+
+/** Anything omitted here resolves through {@link createAutoStubFallbackManager} instead. */
+function createServiceBindings(): AnyServiceBinding[] {
+  return [
+    {
+      definition: EnvironmentDefinition,
+      impl: EnvironmentService,
+      config: { experiments: PLACEHOLDER_EXPERIMENTS },
+    },
+    { definition: TranslationsDefinition, impl: TranslationsService, config: { translations: {} } },
+    {
+      definition: UrlDefinition,
+      impl: UrlService,
+      config: { externalBaseUrl: PLACEHOLDER_SITE_URL, requestUrl: PLACEHOLDER_SITE_URL },
+    },
+    { definition: LinkUtilsDefinition, impl: LinkUtilsService, config: {} },
+    { definition: AnchorsDefinition, impl: AnchorsService, config: {} },
+    { definition: SiteScrollBlockerDefinition, impl: SiteScrollBlockerService, config: {} },
+    { definition: ProvideCssDefinition, impl: ProvideCssService, config: {} },
+    { definition: RenderingContextDefinition, impl: RenderingContextService, config: {} },
+    { definition: ExperimentsDefinition, impl: ExperimentsService, config: { experiments: PLACEHOLDER_EXPERIMENTS } },
+    {
+      definition: ConfigurationDefinition,
+      impl: ConfigurationService,
+      config: { qaMode: false, trackClicksAnalytics: false, sandboxInHTMLComp: false },
+    },
+    { definition: SiteProvideCssDefinition, impl: SiteProvideCssService, config: {} },
+    { definition: DeviceInfoDefinition, impl: DeviceInfoService, config: {} },
+    { definition: EditorContextDefinition, impl: EditorContextService, config: { previewMode: false } },
+    {
+      definition: SiteUrlDefinition,
+      impl: SiteUrlService,
+      config: {
+        currentUrl: PLACEHOLDER_SITE_URL,
+        siteUrl: PLACEHOLDER_SITE_URL,
+        pages: [],
+        pageIdToPrefix: {},
+      },
+    },
+    { definition: PagesDefinition, impl: PagesService, config: PLACEHOLDER_PAGES_CONFIG },
+    { definition: ViewerPagesDefinition, impl: ViewerPagesService, config: PLACEHOLDER_VIEWER_PAGES_CONFIG },
+    { definition: LocaleDefinition, impl: LocaleService, config: { language: 'en', direction: 'ltr' } },
+    { definition: TopologyDefinition, impl: TopologyService, config: { topology: PLACEHOLDER_TOPOLOGY } },
+    {
+      definition: RendererConfigurationDefinition,
+      impl: RendererConfigurationService,
+      config: { isHipaaCompliant: false, currency: 'USD' },
+    },
+    { definition: SdkStateDefinition, impl: SdkStateService, config: {} },
+    { definition: NamedSignalsDefinition, impl: NamedSignalsService, config: {} },
+    { definition: ConsentPolicyDefinition, impl: ConsentPolicyService, config: { siteConsentPolicy: undefined } },
+    {
+      definition: SeoServiceDefinition,
+      impl: createSeoService,
+      config: { seoApi: { setVeloSeoTags: async () => {}, resetVeloSeoTags: async () => {} } },
+    },
+    { definition: ProvideComponentServiceDefinition, impl: ProvideComponentServiceFactory, config: {} },
+  ]
+}
+
+/** Dedupes per wrapper instance, so every extraction reports its own stubs. */
+function createStubbedServiceReporter(): (serviceId: string) => void {
+  const reportedServiceIds = new Set<string>()
+
+  return (serviceId) => {
+    if (reportedServiceIds.has(serviceId)) {
+      return
+    }
+    reportedServiceIds.add(serviceId)
+    console.warn(
+      `[zero-config] Service "${serviceId}" is not registered by the extraction wrapper and was replaced with an inert stub. Branches depending on it may be missing from the extracted manifest.`,
+    )
+  }
+}
+
+/** Local replacement for `@wix/builder-services-wrapper`'s `WixServicesWrapper`. */
+export function WixServicesWrapper({ children }: { children?: ReactNode }): React.ReactElement {
+  // Memoized: the manager eagerly constructs every registered service on creation.
+  const servicesManager = React.useMemo(
+    () =>
+      createServicesManager(
+        createServicesMap(createServiceBindings()),
+        createAutoStubFallbackManager({ onServiceStubbed: createStubbedServiceReporter() }),
+      ),
+    [],
+  )
+
+  return React.createElement(ServicesManagerProvider, { servicesManager }, children)
+}
+
+export function wrapWithWixServices(Component: ComponentType<unknown>): ComponentType<unknown> {
+  const WrappedComponent: ComponentType<unknown> = (props) =>
+    React.createElement(WixServicesWrapper, null, React.createElement(Component, props as Record<string, unknown>))
+  return WrappedComponent
+}

package/src/index.ts

@@ -1,4 +1,3 @@
-import { WixServicesWrapper } from '@wix/builder-services-wrapper'
 import type { EditorReactComponent } from '@wix/react-component-schema'
 import { Result, ResultAsync } from 'neverthrow'
 import React, { type ComponentType } from 'react'
@@ -9,6 +8,7 @@ import { buildContextProviderModules } from './extensions/context-providers/cont
 import { buildContextAwareWrapper, loadMockProviders } from './extensions/context-providers/mock-provider'
 import { buildRefElementContext } from './extensions/ref-elements/context'
 import type { RefElementContext } from './extensions/ref-elements/types'
+import { wrapWithWixServices } from './extensions/wix-services/wrapper'
 import type { ExtractionError } from './extraction-types'
 import type { RunExtractorsOptions } from './information-extractors/react'
 import { extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
@@ -17,11 +17,7 @@ import { processComponent } from './manifest-pipeline'
 import { findComponent, findDefaultComponent, loadModuleForExtraction } from './module-loader'
 import { compileTsFile } from './ts-compiler'
 
-const defaultWrapper = (Component: ComponentType<unknown>): ComponentType<unknown> => {
-  const WrappedComponent: ComponentType<unknown> = (props) =>
-    React.createElement(WixServicesWrapper, null, React.createElement(Component, props as Record<string, unknown>))
-  return WrappedComponent
-}
+const defaultWrapper = wrapWithWixServices
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types

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

@@ -18,6 +18,11 @@ const inheritedChildrenFixture = path.resolve(
   '../../../../example-components/src/components/InheritedChildren/component.tsx',
 )
 
+const activeItemIndexFixture = path.resolve(
+  __dirname,
+  '../../../../example-components/src/components/ActiveItemIndex/SimpleTabs/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)
@@ -79,3 +84,35 @@ describe('TS extractor — container children props', () => {
     expect(component!.props.label).toBeDefined()
   })
 })
+
+describe('TS extractor — ActiveItemIndex<> detection', () => {
+  it('flags an ActiveItemIndex<>-wrapped prop with the target array prop name and unwraps to number', async () => {
+    const programResult = await compileTsFile(activeItemIndexFixture)
+    expect(programResult.isOk()).toBe(true)
+    const program = programResult._unsafeUnwrap()
+
+    const components = extractAllComponentInfo(program, activeItemIndexFixture)
+    const component = components.find((candidate) => candidate.componentName === 'SimpleTabs')
+    expect(component).toBeDefined()
+
+    const activeTab = component!.props.activeTab
+    expect(activeTab.activeItemIndexTarget).toBe('tabs')
+    // The `ActiveItemIndex<'tabs'>` wrapper is unwrapped — the prop behaves as a plain number.
+    expect(activeTab.type).toBe('number')
+    // It should not be flagged as a state trigger.
+    expect(activeTab.isStateTrigger).toBeUndefined()
+  })
+
+  it('does not flag a plain number prop as an active item index', async () => {
+    const programResult = await compileTsFile(activeItemIndexFixture)
+    expect(programResult.isOk()).toBe(true)
+    const program = programResult._unsafeUnwrap()
+
+    const components = extractAllComponentInfo(program, activeItemIndexFixture)
+    const component = components.find((candidate) => candidate.componentName === 'SimpleTabs')
+    expect(component).toBeDefined()
+
+    // `tabs` is an array prop, not an active item index.
+    expect(component!.props.tabs.activeItemIndexTarget).toBeUndefined()
+  })
+})

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

@@ -211,25 +211,32 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
     // Resolve the type deeply
     let declaredTypeInfo: DeclaredTypeInfo | undefined
     let stateTrigger: StateTriggerInfo | undefined
+    let activeItemIndex: ActiveItemIndexInfo | undefined
     if (propSymbol) {
       const decl = propSymbol.getDeclarations()?.[0]
       if (decl) {
         const declSourceFile = decl.getSourceFile()
         declaredTypeInfo = getDeclaredTypeInfo(propSymbol, declSourceFile, checker)
         stateTrigger = detectStateTrigger(propSymbol, declSourceFile, checker)
+        activeItemIndex = detectActiveItemIndex(propSymbol, declSourceFile, checker)
       }
     }
 
     // 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
+    // Similarly, `ActiveItemIndex<'arrayPropName'>` unwraps to `number`.
+    const typeString =
+      stateTrigger?.innerTypeName ??
+      (activeItemIndex ? 'number' : undefined) ??
+      declaredTypeInfo?.name ??
+      propItem.type.name
     const resolvedType = propType
       ? resolveType({
           type: propType,
           checker,
           typeString,
-          declaredSymbol: stateTrigger ? undefined : declaredTypeInfo?.symbol,
+          declaredSymbol: stateTrigger || activeItemIndex ? undefined : declaredTypeInfo?.symbol,
         })
       : { kind: 'primitive' as const, value: propItem.type.name }
 
@@ -255,6 +262,7 @@ function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts
       min: parseNumericTag(tags?.min, propName, 'min'),
       max: parseNumericTag(tags?.max, propName, 'max'),
       isStateTrigger: stateTrigger ? true : undefined,
+      activeItemIndexTarget: activeItemIndex?.targetArrayProp,
     }
   }
 
@@ -506,6 +514,11 @@ interface StateTriggerInfo {
   innerTypeName: string
 }
 
+interface ActiveItemIndexInfo {
+  /** The string literal from the type argument, naming the target array prop. */
+  targetArrayProp: string
+}
+
 /**
  * Detects when a prop is declared with the `ElementState<>` marker type from
  * `@wix/react-component-utils` (e.g. `isLoading?: ElementState<boolean>`), which opts
@@ -558,6 +571,65 @@ function isElementStateAliasFromUtils(identifier: ts.Identifier, checker: ts.Typ
   return declaration.getSourceFile().fileName.includes('react-component-utils')
 }
 
+/**
+ * Detects when a prop is declared with the `ActiveItemIndex<>` marker type from
+ * `@wix/react-component-utils` (e.g. `activeTab?: ActiveItemIndex<'tabs'>`), which
+ * links the prop to an array data prop for the `displayGroups.arrayItems` manifest
+ * block. Returns the target array prop name from the string literal type argument.
+ * Returns `undefined` for any other declaration, or when the type argument is missing
+ * or not a string literal.
+ */
+function detectActiveItemIndex(
+  prop: ts.Symbol,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): ActiveItemIndexInfo | 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)
+  ) {
+    return undefined
+  }
+
+  const typeName = declaration.type.typeName
+  const identifier = ts.isIdentifier(typeName) ? typeName : typeName.right
+  if (identifier.text !== 'ActiveItemIndex') return undefined
+  if (!isActiveItemIndexAliasFromUtils(identifier, checker)) return undefined
+
+  // Require an explicit string literal type argument — bare ActiveItemIndex (no arg)
+  // compiles but gives ZeroConfig no array name to link to.
+  const typeArgs = declaration.type.typeArguments
+  if (!typeArgs || typeArgs.length !== 1) return undefined
+
+  const typeArgNode = typeArgs[0]
+  if (!ts.isLiteralTypeNode(typeArgNode) || !ts.isStringLiteral(typeArgNode.literal)) return undefined
+
+  return { targetArrayProp: typeArgNode.literal.text }
+}
+
+/**
+ * Confirms an identifier referencing `ActiveItemIndex` resolves to the marker type
+ * alias exported by `@wix/react-component-utils`, rather than an unrelated local
+ * type that happens to be named `ActiveItemIndex`.
+ */
+function isActiveItemIndexAliasFromUtils(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 !== 'ActiveItemIndex') 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

@@ -59,6 +59,11 @@ export interface PropInfo {
   // state. `type` and `resolvedType` reflect the unwrapped inner type, so the prop
   // still behaves as a normal data prop everywhere else.
   isStateTrigger?: boolean
+  // When the prop is wrapped in `ActiveItemIndex<'arrayPropName'>` from
+  // @wix/react-component-utils, carries the target array prop name. `type` and
+  // `resolvedType` reflect the unwrapped `number` type. Used by the display-groups
+  // builder to auto-generate the `displayGroups.arrayItems` manifest block.
+  activeItemIndexTarget?: string
 }
 
 export interface ComponentInfo {