@wix/zero-config-implementation 1.77.0 → 1.79.0

package/src/extensions/context-providers/mock-provider.ts

@@ -0,0 +1,210 @@
+import type React from 'react'
+import type { ComponentType, Context } from 'react'
+import { generateMockContextValues } from '../../information-extractors/react/utils/mock-generator'
+import { computeSignedContextProviderUrl, ensureReactRuntimeLoader } from '../../react-runtime-loader'
+import type { RefElementModule } from '../ref-elements/types'
+import type { ContextProviderModule } from './types'
+
+type AnyFunction = (...args: unknown[]) => unknown
+
+interface ReactShim {
+  useContext(context: unknown): unknown
+  [hookName: string]: unknown
+}
+
+type GlobalWithReact = Record<symbol, ReactShim>
+
+// Hooks whose return value is consumed before useContext is reached — returning undefined would crash before the interceptor fires.
+const RETURN_VALUE_HOOK_STUBS: Record<string, AnyFunction> = {
+  useState: (initialState) => [
+    typeof initialState === 'function' ? (initialState as () => unknown)() : initialState,
+    () => {},
+  ],
+  useReducer: (_reducer, initialState, init) => [
+    typeof init === 'function' ? (init as (state: unknown) => unknown)(initialState) : initialState,
+    () => {},
+  ],
+  useRef: (initialValue) => ({ current: initialValue }),
+  useMemo: (factory) => {
+    try {
+      return (factory as () => unknown)()
+    } catch {
+      return undefined
+    }
+  },
+  useCallback: (callbackFn) => callbackFn,
+  useTransition: () => [false, () => {}],
+  useDeferredValue: (value) => value,
+  useSyncExternalStore: (_subscribe, getSnapshot) => (getSnapshot as () => unknown)(),
+}
+
+const genericHookStub: AnyFunction = () => undefined
+
+interface LoadedMockProvider {
+  moduleSpecifier: string
+  contextDependencies: string[]
+  Provider: ComponentType<{ children?: React.ReactNode }>
+}
+
+/**
+ * Builds a synthetic mock Provider for each context provider module, filled with
+ * schema-derived values. Identifies each context by calling the hook and intercepting
+ * `useContext` — intercepting `createContext` would require patching before the module
+ * loads, which fails when the module is already in the ESM cache.
+ *
+ * The loop is intentionally serial — each iteration patches a global and restores it in a
+ * finally block; concurrent iterations would interleave the patches.
+ */
+export async function loadMockProviders(
+  contextProviderModules: ContextProviderModule[],
+  reactInstance: typeof React,
+  refElementModules: RefElementModule[] = [],
+): Promise<LoadedMockProvider[]> {
+  ensureReactRuntimeLoader()
+
+  const loadedProviders: LoadedMockProvider[] = []
+
+  for (const contextProviderModule of contextProviderModules) {
+    const capturedContext = await captureHookContext(contextProviderModule, refElementModules)
+    if (!capturedContext) {
+      console.warn(
+        `Could not capture context for hook "${contextProviderModule.hookName}" from "${contextProviderModule.moduleSpecifier}" — skipping mock provider.`,
+      )
+      continue
+    }
+
+    const mockValues = generateMockContextValues(contextProviderModule.contextSchema)
+    const Provider = buildSyntheticProvider(capturedContext, mockValues, reactInstance)
+    loadedProviders.push({
+      moduleSpecifier: contextProviderModule.moduleSpecifier,
+      contextDependencies: contextProviderModule.contextDependencies,
+      Provider,
+    })
+  }
+
+  return loadedProviders
+}
+
+/** Providers that others depend on are placed outermost (applied last in the chain). */
+export function buildContextAwareWrapper(
+  loadedProviders: LoadedMockProvider[],
+  outerWrapper: (Component: ComponentType<unknown>) => ComponentType<unknown>,
+  reactInstance: typeof React,
+): (Component: ComponentType<unknown>) => ComponentType<unknown> {
+  const sortedProviders = sortProvidersByDependency(loadedProviders)
+
+  return (Component: ComponentType<unknown>): ComponentType<unknown> => {
+    const WrappedWithProviders: ComponentType<unknown> = (props) => {
+      let element = reactInstance.createElement(Component, props as Record<string, unknown>)
+
+      for (const { Provider } of sortedProviders) {
+        element = reactInstance.createElement(Provider, null, element)
+      }
+
+      return element as React.ReactElement
+    }
+    return outerWrapper(WrappedWithProviders)
+  }
+}
+
+async function captureHookContext(
+  contextProviderModule: ContextProviderModule,
+  refElementModules: RefElementModule[],
+): Promise<Context<unknown> | null> {
+  // Must use the same signed URL the statics bundle will use so both paths hit the same ESM cache entry.
+  const signedModuleUrl = computeSignedContextProviderUrl(contextProviderModule.resolvedModuleUrl, refElementModules)
+  const moduleExports = (await import(signedModuleUrl)) as Record<string, unknown>
+  const hookFn = moduleExports[contextProviderModule.hookName]
+  if (typeof hookFn !== 'function') {
+    return null
+  }
+
+  let capturedContext: Context<unknown> | null = null
+
+  const useContextInterceptor = (context: Context<unknown>) => {
+    // First useContext call wins — hooks in this system are expected to read exactly one context.
+    if (!capturedContext) {
+      capturedContext = context
+    }
+    // Return a truthy mock so any "must be used within a Provider" guard doesn't throw
+    return {} as unknown
+  }
+
+  const REACT_KEY = Symbol.for('zero-config:react-originals')
+  const shimReact = (globalThis as unknown as GlobalWithReact)[REACT_KEY]
+
+  if (!shimReact) {
+    throw new Error(
+      `React shim is not registered under Symbol.for('${REACT_KEY.description}') — ensure ensureReactRuntimeLoader() was called before loadMockProviders()`,
+    )
+  }
+
+  const originalUseContext = shimReact.useContext
+  shimReact.useContext = useContextInterceptor
+
+  const originalHooks: Record<string, unknown> = {}
+  for (const hookName of Object.keys(shimReact)) {
+    if (hookName !== 'useContext' && hookName.startsWith('use') && typeof shimReact[hookName] === 'function') {
+      originalHooks[hookName] = shimReact[hookName]
+      shimReact[hookName] = RETURN_VALUE_HOOK_STUBS[hookName] ?? genericHookStub
+    }
+  }
+
+  try {
+    ;(hookFn as () => unknown)()
+  } catch {
+    // Hook may throw after useContext fires (e.g. a "must be used within a Provider" guard) — capturedContext is already set.
+  } finally {
+    shimReact.useContext = originalUseContext
+    for (const [hookName, original] of Object.entries(originalHooks)) {
+      shimReact[hookName] = original
+    }
+  }
+
+  return capturedContext
+}
+
+function buildSyntheticProvider(
+  capturedContext: Context<unknown>,
+  mockValues: Record<string, unknown>,
+  reactInstance: typeof React,
+): ComponentType<{ children?: React.ReactNode }> {
+  return ({ children }: { children?: React.ReactNode }): React.ReactElement => {
+    return reactInstance.createElement(capturedContext.Provider, { value: mockValues }, children)
+  }
+}
+
+// Topological sort: dependency providers come last so they wrap outermost.
+function sortProvidersByDependency(providers: LoadedMockProvider[]): LoadedMockProvider[] {
+  const providerBySpecifier = new Map(providers.map((provider) => [provider.moduleSpecifier, provider]))
+  const visited = new Set<string>()
+  const sorted: LoadedMockProvider[] = []
+
+  function visit(moduleSpecifier: string): void {
+    if (visited.has(moduleSpecifier)) {
+      return
+    }
+    visited.add(moduleSpecifier)
+
+    const provider = providerBySpecifier.get(moduleSpecifier)
+    if (!provider) {
+      return
+    }
+
+    for (const dependency of provider.contextDependencies) {
+      if (providerBySpecifier.has(dependency)) {
+        visit(dependency)
+      }
+    }
+
+    sorted.push(provider)
+  }
+
+  for (const provider of providers) {
+    visit(provider.moduleSpecifier)
+  }
+
+  // Post-order DFS gives [dependency, dependent]. Reverse so dependencies come last
+  // in the loop below — last element applied is outermost in the React tree.
+  return sorted.reverse()
+}

package/src/extensions/context-providers/types.ts

@@ -0,0 +1,22 @@
+export interface ContextProviderModule {
+  hookName: string
+  moduleSpecifier: string
+  resolvedModuleUrl: string
+  contextSchema: ContextSchema
+  contextDependencies: string[]
+}
+
+export interface ContextSchema {
+  items: Record<string, ContextSchemaItem>
+}
+
+export interface ContextSchemaItem {
+  dataType: string
+  displayName?: string
+  data?: ContextSchema
+  arrayItems?: ContextArrayItems
+}
+
+export interface ContextArrayItems {
+  item?: ContextSchemaItem
+}

package/src/{ref-elements → extensions/ref-elements}/context.test.ts

@@ -4,9 +4,9 @@ import path from 'node:path'
 import ts from 'typescript'
 import { afterEach, describe, expect, it } from 'vitest'
 
-import type { ComponentInfo } from '../information-extractors/ts/types'
+import type { ComponentInfo } from '../../information-extractors/ts/types'
+import { resolveModuleUrlFromEntryPath } from '../shared/module-resolution'
 import { buildRefElementContext } from './context'
-import { resolveModuleUrlFromEntryPath } from './module-resolution'
 
 const temporaryDirectoryPaths: string[] = []
 const compiledEntryPath = path.resolve(__dirname, 'context.test.ts')
@@ -97,7 +97,7 @@ describe('buildRefElementContext', () => {
         componentName: 'Component',
         props: {},
       } satisfies ComponentInfo,
-      path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+      path.resolve(__dirname, '../../__fixtures__/esm-ref-element-entry.mjs'),
     )
 
     expect(refElementContext.runtimeModules).toEqual([
@@ -105,7 +105,7 @@ describe('buildRefElementContext', () => {
         exportNames: ['default', 'BareRefButton'],
         moduleSpecifier: '@wix/zero-config-ref-element-fixtures/BareRefButton',
         resolvedModuleUrl: resolveModuleUrlFromEntryPath(
-          path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+          path.resolve(__dirname, '../../__fixtures__/esm-ref-element-entry.mjs'),
           '@wix/zero-config-ref-element-fixtures/BareRefButton',
         ),
         refComponentType: 'wixEditorElements.BareRefButton',

package/src/extensions/ref-elements/context.ts

@@ -0,0 +1,168 @@
+import ts from 'typescript'
+import type { ComponentInfo } from '../../information-extractors/ts/types'
+import { collectAllPackageImportSpecifiers } from '../shared/ast-scanner'
+import { loadNormalizedCatalogEntries } from '../shared/catalog-loader'
+import { resolveModuleUrlFromEntryPath } from '../shared/module-resolution'
+import { extractBasePackageName, extractModuleLeafExportName } from '../shared/package-specifier'
+import { extractEligibleRefElementPaths } from './eligible-paths'
+import type { RefElementContext, RefElementModule } from './types'
+
+interface NormalizedRefElementCatalogEntry {
+  moduleSpecifier: string
+  refComponentType: string
+}
+
+export async function buildRefElementContext(
+  program: ts.Program,
+  sourceFilePath: string,
+  componentInfo: ComponentInfo,
+  compiledEntryPath: string,
+): Promise<RefElementContext> {
+  const importedModuleSpecifiers = collectAllPackageImportSpecifiers(
+    program,
+    sourceFilePath,
+    referencesRefElementModule,
+  )
+
+  return {
+    eligiblePaths: extractEligibleRefElementPaths(componentInfo),
+    runtimeModules: await resolveRuntimeModules(importedModuleSpecifiers, compiledEntryPath),
+  }
+}
+
+async function resolveRuntimeModules(
+  importedModuleSpecifiers: string[],
+  compiledEntryPath: string,
+): Promise<RefElementModule[]> {
+  if (importedModuleSpecifiers.length === 0) {
+    return []
+  }
+
+  const importedModuleSpecifierSet = new Set(importedModuleSpecifiers)
+  const catalogEntries = await loadNormalizedCatalogEntries(
+    importedModuleSpecifiers,
+    compiledEntryPath,
+    normalizeRefElementExtensionEntry,
+  )
+
+  const runtimeModulesBySpecifier = new Map<string, Set<string>>()
+
+  for (const catalogEntry of catalogEntries) {
+    if (!importedModuleSpecifierSet.has(catalogEntry.moduleSpecifier)) {
+      continue
+    }
+
+    const refComponentTypes = runtimeModulesBySpecifier.get(catalogEntry.moduleSpecifier) ?? new Set<string>()
+    refComponentTypes.add(catalogEntry.refComponentType)
+    runtimeModulesBySpecifier.set(catalogEntry.moduleSpecifier, refComponentTypes)
+  }
+
+  const runtimeModules: RefElementModule[] = []
+
+  for (const [moduleSpecifier, refComponentTypes] of runtimeModulesBySpecifier.entries()) {
+    if (refComponentTypes.size !== 1) {
+      continue
+    }
+
+    const refComponentType = [...refComponentTypes][0]
+    if (!refComponentType) {
+      continue
+    }
+
+    const resolvedModuleUrl = resolveModuleUrlFromEntryPath(compiledEntryPath, moduleSpecifier)
+    if (!resolvedModuleUrl) {
+      continue
+    }
+
+    runtimeModules.push({
+      exportNames: buildRefElementExportNames(moduleSpecifier),
+      moduleSpecifier,
+      resolvedModuleUrl,
+      refComponentType,
+    })
+  }
+
+  return runtimeModules
+}
+
+function normalizeRefElementExtensionEntry(rawEntry: unknown): NormalizedRefElementCatalogEntry | undefined {
+  const entry = rawEntry as {
+    options?: { type?: string; resources?: { client?: { moduleSpecifier?: string } } }
+    type?: string
+    resources?: { client?: { moduleSpecifier?: string } }
+  }
+  const normalizedEntry = entry.options ?? entry
+  const moduleSpecifier = normalizedEntry.resources?.client?.moduleSpecifier
+  const refComponentType = normalizedEntry.type
+
+  if (!moduleSpecifier || !refComponentType) {
+    return undefined
+  }
+
+  return {
+    moduleSpecifier,
+    refComponentType,
+  }
+}
+
+function referencesRefElementModule(statement: ts.Statement, moduleSpecifier: string): boolean {
+  const moduleLeafExportName = extractModuleLeafExportName(moduleSpecifier)
+  if (!moduleLeafExportName) {
+    return false
+  }
+
+  if (ts.isImportDeclaration(statement)) {
+    return importsRefElementModule(statement, moduleLeafExportName)
+  }
+
+  if (ts.isExportDeclaration(statement)) {
+    return reExportsRefElementModule(statement, moduleLeafExportName)
+  }
+
+  return false
+}
+
+function importsRefElementModule(importDeclaration: ts.ImportDeclaration, moduleLeafExportName: string): boolean {
+  const importClause = importDeclaration.importClause
+  if (!importClause) {
+    return false
+  }
+
+  if (importClause.name) {
+    return true
+  }
+
+  if (!importClause.namedBindings || !ts.isNamedImports(importClause.namedBindings)) {
+    return false
+  }
+
+  return importClause.namedBindings.elements.some((importSpecifier) => {
+    const importedName = importSpecifier.propertyName?.text ?? importSpecifier.name.text
+    return importedName === moduleLeafExportName
+  })
+}
+
+function reExportsRefElementModule(exportDeclaration: ts.ExportDeclaration, moduleLeafExportName: string): boolean {
+  if (!exportDeclaration.exportClause || !ts.isNamedExports(exportDeclaration.exportClause)) {
+    return false
+  }
+
+  return exportDeclaration.exportClause.elements.some((exportSpecifier) => {
+    const exportedSourceName = exportSpecifier.propertyName?.text ?? exportSpecifier.name.text
+    return exportedSourceName === 'default' || exportedSourceName === moduleLeafExportName
+  })
+}
+
+function buildRefElementExportNames(moduleSpecifier: string): string[] {
+  const exportNames = new Set<string>(['default'])
+  if (extractBasePackageName(moduleSpecifier) === moduleSpecifier) {
+    return [...exportNames]
+  }
+
+  const moduleLeafName = extractModuleLeafExportName(moduleSpecifier)
+  if (moduleLeafName) {
+    exportNames.add(moduleLeafName)
+  }
+
+  return [...exportNames]
+}

package/src/{ref-elements → extensions/ref-elements}/eligible-paths.ts

@@ -1,4 +1,4 @@
-import type { ComponentInfo, ResolvedType } from '../information-extractors/ts/types'
+import type { ComponentInfo, ResolvedType } from '../../information-extractors/ts/types'
 
 export function extractEligibleRefElementPaths(componentInfo: ComponentInfo): string[] {
   const elementPropsInfo = componentInfo.props.elementProps

package/src/extensions/shared/ast-scanner.ts

@@ -0,0 +1,85 @@
+import ts from 'typescript'
+
+export function isPackageModuleSpecifier(moduleSpecifier: string): boolean {
+  return !moduleSpecifier.startsWith('.') && !moduleSpecifier.startsWith('/') && !moduleSpecifier.startsWith('file:')
+}
+
+function findSourceFile(program: ts.Program, sourceFilePath: string): ts.SourceFile | undefined {
+  return (
+    program.getSourceFile(sourceFilePath) ??
+    program.getSourceFiles().find((sourceFile) => sourceFile.fileName === sourceFilePath)
+  )
+}
+
+function resolveImportedSourceFile(
+  program: ts.Program,
+  importingFilePath: string,
+  moduleSpecifier: string,
+): ts.SourceFile | undefined {
+  const resolvedModule = ts.resolveModuleName(moduleSpecifier, importingFilePath, program.getCompilerOptions(), ts.sys)
+  const resolvedFileName = resolvedModule.resolvedModule?.resolvedFileName
+
+  if (!resolvedFileName) {
+    return undefined
+  }
+
+  const resolvedSourceFile = findSourceFile(program, resolvedFileName)
+  if (!resolvedSourceFile || resolvedSourceFile.isDeclarationFile) {
+    return undefined
+  }
+
+  return resolvedSourceFile
+}
+
+function readReferencedModuleSpecifier(statement: ts.Statement): string | undefined {
+  if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+    return statement.moduleSpecifier.text
+  }
+
+  if (ts.isExportDeclaration(statement) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+    return statement.moduleSpecifier.text
+  }
+
+  return undefined
+}
+
+export function collectAllPackageImportSpecifiers(
+  program: ts.Program,
+  sourceFilePath: string,
+  filter?: (statement: ts.Statement, moduleSpecifier: string) => boolean,
+): string[] {
+  const entrySourceFile = findSourceFile(program, sourceFilePath)
+  if (!entrySourceFile) {
+    return []
+  }
+
+  const packageSpecifiers = new Set<string>()
+  const visitedSourceFiles = new Set<string>()
+
+  function visitSourceFile(sourceFile: ts.SourceFile): void {
+    if (visitedSourceFiles.has(sourceFile.fileName)) {
+      return
+    }
+
+    visitedSourceFiles.add(sourceFile.fileName)
+
+    for (const statement of sourceFile.statements) {
+      const moduleSpecifier = readReferencedModuleSpecifier(statement)
+      if (!moduleSpecifier) {
+        continue
+      }
+
+      if (isPackageModuleSpecifier(moduleSpecifier) && (!filter || filter(statement, moduleSpecifier))) {
+        packageSpecifiers.add(moduleSpecifier)
+      }
+
+      const importedSourceFile = resolveImportedSourceFile(program, sourceFile.fileName, moduleSpecifier)
+      if (importedSourceFile) {
+        visitSourceFile(importedSourceFile)
+      }
+    }
+  }
+
+  visitSourceFile(entrySourceFile)
+  return [...packageSpecifiers]
+}

package/src/extensions/shared/catalog-loader.ts

@@ -0,0 +1,64 @@
+import { isPackageModuleSpecifier } from './ast-scanner'
+import { resolveModuleUrlFromEntryPath } from './module-resolution'
+import { extractBasePackageName } from './package-specifier'
+
+interface RawExtensionModule {
+  extensions?: unknown[]
+  default?: unknown
+}
+
+function extractRawExtensionEntries(extensionModule: Record<string, unknown>): unknown[] {
+  const defaultExport = extensionModule.default
+  const extensionEntries = Array.isArray(defaultExport)
+    ? defaultExport
+    : ((defaultExport as { extensions?: unknown[] } | undefined)?.extensions ?? extensionModule.extensions)
+
+  return Array.isArray(extensionEntries) ? extensionEntries : []
+}
+
+async function loadRawExtensionEntries(packageName: string, compiledEntryPath: string): Promise<unknown[]> {
+  const resolvedExtensionsUrl = resolveModuleUrlFromEntryPath(compiledEntryPath, `${packageName}/extensions`)
+  if (!resolvedExtensionsUrl) {
+    return []
+  }
+
+  try {
+    const extensionModule = (await import(resolvedExtensionsUrl)) as RawExtensionModule & Record<string, unknown>
+    return extractRawExtensionEntries(extensionModule)
+  } catch (error) {
+    // The package declared an /extensions export but the file doesn't exist — skip it.
+    if (isModuleNotFoundError(error)) {
+      return []
+    }
+    throw error
+  }
+}
+
+function isModuleNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND')
+  )
+}
+
+/**
+ * For each package name derived from `importedSpecifiers`, loads its `/extensions` catalog and
+ * normalizes every raw entry through `normalizeEntry`. Returns the flat list of non-undefined results.
+ */
+export async function loadNormalizedCatalogEntries<T>(
+  importedSpecifiers: string[],
+  compiledEntryPath: string,
+  normalizeEntry: (rawEntry: unknown) => T | undefined,
+): Promise<T[]> {
+  const packageNames = [...new Set(importedSpecifiers.filter(isPackageModuleSpecifier).map(extractBasePackageName))]
+
+  const entriesPerPackage = await Promise.all(
+    packageNames.map(async (packageName) => {
+      const rawEntries = await loadRawExtensionEntries(packageName, compiledEntryPath)
+      return rawEntries.map(normalizeEntry).filter((entry): entry is T => entry !== undefined)
+    }),
+  )
+
+  return entriesPerPackage.flat()
+}

package/src/{ref-elements → extensions/shared}/module-resolution.test.ts

@@ -19,7 +19,7 @@ describe('resolveModulePathFromEntryPath', () => {
 
     const packageRootPath = path.join(temporaryDirectoryPath, 'consumer-package')
     const nodeModulesPath = path.join(packageRootPath, 'node_modules', '@wix')
-    const fixturePackagePath = path.resolve(__dirname, '../../../ref-element-fixtures')
+    const fixturePackagePath = path.resolve(__dirname, '../../../../ref-element-fixtures')
 
     fs.mkdirSync(nodeModulesPath, { recursive: true })
     fs.symlinkSync(fixturePackagePath, path.join(nodeModulesPath, 'zero-config-ref-element-fixtures'), 'dir')
@@ -40,7 +40,7 @@ describe('resolveModulePathFromEntryPath', () => {
 describe('resolveModuleUrlFromEntryPath', () => {
   it('returns a file url for the resolved module path', () => {
     const resolvedExtensionsUrl = resolveModuleUrlFromEntryPath(
-      path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+      path.resolve(__dirname, '../../__fixtures__/esm-ref-element-entry.mjs'),
       '@wix/zero-config-ref-element-fixtures/extensions',
     )