@wix/zero-config-implementation 1.71.0 → 1.72.0

package/src/ref-elements/component-tag.ts

@@ -0,0 +1,105 @@
+import type { ComponentType } from 'react'
+
+export const REF_ELEMENT_COMPONENT_TYPE_SYMBOL_KEY = 'zero-config:ref-element-component-type'
+export const refElementComponentTypeSymbol = Symbol.for(REF_ELEMENT_COMPONENT_TYPE_SYMBOL_KEY)
+
+export function readRefElementComponentType(componentType: unknown): string | undefined {
+  if (!componentType || (typeof componentType !== 'function' && typeof componentType !== 'object')) {
+    return undefined
+  }
+
+  const refComponentType = (componentType as Record<PropertyKey, unknown>)[refElementComponentTypeSymbol]
+  return typeof refComponentType === 'string' ? refComponentType : undefined
+}
+
+export function safelyTagRefElementComponent(componentValue: unknown, refComponentType: string): unknown {
+  if (!isComponentLike(componentValue)) {
+    return componentValue
+  }
+
+  try {
+    if (readRefElementComponentType(componentValue) === refComponentType) {
+      return componentValue
+    }
+
+    Object.defineProperty(componentValue, refElementComponentTypeSymbol, {
+      value: refComponentType,
+      configurable: true,
+    })
+  } catch {
+    return componentValue
+  }
+
+  return componentValue
+}
+
+export function tagRefElementComponentForCleanup(
+  componentValue: unknown,
+  refComponentType: string,
+): (() => void) | undefined {
+  if (!isComponentLike(componentValue)) {
+    return undefined
+  }
+
+  const existingRefComponentType = readRefElementComponentType(componentValue)
+  if (existingRefComponentType !== undefined) {
+    return undefined
+  }
+
+  safelyTagRefElementComponent(componentValue, refComponentType)
+  if (readRefElementComponentType(componentValue) !== refComponentType) {
+    return undefined
+  }
+
+  return () => {
+    try {
+      if (readRefElementComponentType(componentValue) === refComponentType) {
+        delete (componentValue as unknown as Record<PropertyKey, unknown>)[refElementComponentTypeSymbol]
+      }
+    } catch {
+      return
+    }
+  }
+}
+
+export function buildRefElementTaggerSource(): string {
+  return `
+const REF_ELEMENT_COMPONENT_TYPE_SYMBOL_KEY = ${JSON.stringify(REF_ELEMENT_COMPONENT_TYPE_SYMBOL_KEY)};
+const refElementComponentTypeSymbol = Symbol.for(REF_ELEMENT_COMPONENT_TYPE_SYMBOL_KEY);
+function isComponentLike(value) {
+  return typeof value === 'function' || (typeof value === 'object' && value !== null && '$$typeof' in value);
+}
+function readRefElementComponentType(componentType) {
+  if (!componentType || (typeof componentType !== 'function' && typeof componentType !== 'object')) {
+    return undefined;
+  }
+
+  const refComponentType = componentType[refElementComponentTypeSymbol];
+  return typeof refComponentType === 'string' ? refComponentType : undefined;
+}
+function safelyTagRefElementComponent(componentValue, refComponentType) {
+  if (!isComponentLike(componentValue)) {
+    return componentValue;
+  }
+
+  try {
+    if (readRefElementComponentType(componentValue) === refComponentType) {
+      return componentValue;
+    }
+
+    Object.defineProperty(componentValue, refElementComponentTypeSymbol, {
+      value: refComponentType,
+      configurable: true,
+    });
+  } catch {
+    return componentValue;
+  }
+
+  return componentValue;
+}
+`
+}
+
+function isComponentLike(value: unknown): value is ComponentType<unknown> {
+  return typeof value === 'function' || (typeof value === 'object' && value !== null && '$$typeof' in value)
+}

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

@@ -0,0 +1,179 @@
+import fs from 'node:fs'
+import os from 'node:os'
+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 { buildRefElementContext } from './context'
+import { resolveModuleUrlFromEntryPath } from './module-resolution'
+
+const temporaryDirectoryPaths: string[] = []
+const compiledEntryPath = path.resolve(__dirname, 'context.test.ts')
+
+afterEach(() => {
+  for (const temporaryDirectoryPath of temporaryDirectoryPaths.splice(0)) {
+    fs.rmSync(temporaryDirectoryPath, { force: true, recursive: true })
+  }
+})
+
+describe('buildRefElementContext', () => {
+  it('does not tag bare package imports because runtime modules are keyed by the exact externalized moduleSpecifier', async () => {
+    const sourceFilePath = createModuleImportFixture('@wix/editor-react-components')
+    const program = createProgram(sourceFilePath)
+
+    const refElementContext = await buildRefElementContext(
+      program,
+      sourceFilePath,
+      { componentName: 'Component', props: {} },
+      compiledEntryPath,
+    )
+
+    expect(refElementContext.runtimeModules).toEqual([])
+  })
+
+  it('tags the exact catalog moduleSpecifier for the same package', async () => {
+    const sourceFilePath = createModuleImportFixture('@wix/editor-react-components/Button')
+    const program = createProgram(sourceFilePath)
+
+    const refElementContext = await buildRefElementContext(
+      program,
+      sourceFilePath,
+      { componentName: 'Component', props: {} },
+      compiledEntryPath,
+    )
+
+    expect(refElementContext.runtimeModules).toEqual([
+      {
+        exportNames: ['default', 'Button'],
+        moduleSpecifier: '@wix/editor-react-components/Button',
+        resolvedModuleUrl: resolveModuleUrlFromEntryPath(compiledEntryPath, '@wix/editor-react-components/Button'),
+        refComponentType: 'wixEditorElements.Button',
+      },
+    ])
+  })
+
+  it('follows aliased local wrappers before classifying imports as external ref-elements', async () => {
+    const temporaryDirectoryPath = fs.mkdtempSync(path.join(os.tmpdir(), 'zero-config-ref-element-context-'))
+    temporaryDirectoryPaths.push(temporaryDirectoryPath)
+
+    const componentPath = path.join(temporaryDirectoryPath, 'Component.tsx')
+    const aliasedWrapperPath = path.join(temporaryDirectoryPath, 'ButtonWrapper.tsx')
+    const internalWrapperPath = path.join(temporaryDirectoryPath, 'InternalButton.tsx')
+
+    fs.writeFileSync(
+      componentPath,
+      "import ButtonWrapper from '@/ButtonWrapper'\nexport default function Component() { return <ButtonWrapper /> }\n",
+    )
+    fs.writeFileSync(
+      aliasedWrapperPath,
+      "import InternalButton from '@/InternalButton'\nexport default InternalButton\n",
+    )
+    fs.writeFileSync(
+      internalWrapperPath,
+      "export { default } from '@wix/zero-config-ref-element-fixtures/BareRefButton'\n",
+    )
+
+    const program = ts.createProgram({
+      rootNames: [componentPath, aliasedWrapperPath, internalWrapperPath],
+      options: {
+        allowSyntheticDefaultImports: true,
+        baseUrl: temporaryDirectoryPath,
+        jsx: ts.JsxEmit.ReactJSX,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        paths: {
+          '@/*': ['./*'],
+        },
+        skipLibCheck: true,
+        target: ts.ScriptTarget.ES2020,
+      },
+    })
+
+    const refElementContext = await buildRefElementContext(
+      program,
+      componentPath,
+      {
+        componentName: 'Component',
+        props: {},
+      } satisfies ComponentInfo,
+      path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+    )
+
+    expect(refElementContext.runtimeModules).toEqual([
+      {
+        exportNames: ['default', 'BareRefButton'],
+        moduleSpecifier: '@wix/zero-config-ref-element-fixtures/BareRefButton',
+        resolvedModuleUrl: resolveModuleUrlFromEntryPath(
+          path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+          '@wix/zero-config-ref-element-fixtures/BareRefButton',
+        ),
+        refComponentType: 'wixEditorElements.BareRefButton',
+      },
+    ])
+  })
+
+  it('fails when a resolved extensions module throws during catalog loading', async () => {
+    const temporaryDirectoryPath = fs.mkdtempSync(path.join(os.tmpdir(), 'zero-config-ref-element-context-'))
+    temporaryDirectoryPaths.push(temporaryDirectoryPath)
+
+    const componentPath = path.join(temporaryDirectoryPath, 'Component.tsx')
+    const compiledEntryPath = path.join(temporaryDirectoryPath, 'dist', 'index.js')
+    const packageDirectoryPath = path.join(temporaryDirectoryPath, 'node_modules', 'broken-ref-elements')
+
+    fs.mkdirSync(path.dirname(compiledEntryPath), { recursive: true })
+    fs.mkdirSync(packageDirectoryPath, { recursive: true })
+
+    fs.writeFileSync(
+      componentPath,
+      "import Button from 'broken-ref-elements/Button'\nexport default function Component() { return <Button /> }\n",
+    )
+    fs.writeFileSync(compiledEntryPath, 'export {}\n')
+    fs.writeFileSync(
+      path.join(packageDirectoryPath, 'package.json'),
+      JSON.stringify(
+        {
+          exports: {
+            './Button': './Button.js',
+            './extensions': './extensions.js',
+          },
+          name: 'broken-ref-elements',
+          type: 'module',
+        },
+        null,
+        2,
+      ),
+    )
+    fs.writeFileSync(path.join(packageDirectoryPath, 'Button.js'), 'export default function Button() {}\n')
+    fs.writeFileSync(path.join(packageDirectoryPath, 'extensions.js'), "throw new Error('broken catalog')\n")
+
+    const program = createProgram(componentPath)
+
+    await expect(
+      buildRefElementContext(program, componentPath, { componentName: 'Component', props: {} }, compiledEntryPath),
+    ).rejects.toThrow('broken catalog')
+  })
+})
+
+function createProgram(sourceFilePath: string): ts.Program {
+  return ts.createProgram({
+    rootNames: [sourceFilePath],
+    options: {
+      allowJs: true,
+      jsx: ts.JsxEmit.ReactJSX,
+    },
+  })
+}
+
+function createModuleImportFixture(moduleSpecifier: string): string {
+  const temporaryDirectoryPath = fs.mkdtempSync(path.join(os.tmpdir(), 'zero-config-ref-element-context-'))
+  temporaryDirectoryPaths.push(temporaryDirectoryPath)
+
+  const sourceFilePath = path.join(temporaryDirectoryPath, 'Component.tsx')
+  fs.writeFileSync(
+    sourceFilePath,
+    `import Button from '${moduleSpecifier}'\nexport default function Component() { return <Button /> }\n`,
+  )
+
+  return sourceFilePath
+}

package/src/ref-elements/context.ts

@@ -0,0 +1,280 @@
+import ts from 'typescript'
+import type { ComponentInfo } from '../information-extractors/ts/types'
+import { extractEligibleRefElementPaths } from './eligible-paths'
+import { resolveModuleUrlFromEntryPath } from './module-resolution'
+import { extractBasePackageName, extractModuleLeafExportName } from './module-specifier'
+import type { RefElementContext, RefElementModule } from './types'
+
+interface RawRefElementExtensionEntry {
+  options?: {
+    type?: string
+    resources?: {
+      client?: {
+        moduleSpecifier?: string
+      }
+    }
+  }
+  type?: string
+  resources?: {
+    client?: {
+      moduleSpecifier?: string
+    }
+  }
+}
+
+interface NormalizedRefElementCatalogEntry {
+  moduleSpecifier: string
+  refComponentType: string
+}
+
+export async function buildRefElementContext(
+  program: ts.Program,
+  sourceFilePath: string,
+  componentInfo: ComponentInfo,
+  compiledEntryPath: string,
+): Promise<RefElementContext> {
+  const importedModuleSpecifiers = collectImportedRefElementModuleSpecifiers(program, sourceFilePath)
+
+  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 importedPackageNames = [
+    ...new Set(importedModuleSpecifiers.filter(isPackageModuleSpecifier).map(extractBasePackageName)),
+  ]
+  const catalogEntries = (
+    await Promise.all(importedPackageNames.map((packageName) => loadCatalogEntries(packageName, compiledEntryPath)))
+  ).flat()
+
+  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 isPackageModuleSpecifier(moduleSpecifier: string): boolean {
+  return !moduleSpecifier.startsWith('.') && !moduleSpecifier.startsWith('/') && !moduleSpecifier.startsWith('file:')
+}
+
+function collectImportedRefElementModuleSpecifiers(program: ts.Program, sourceFilePath: string): string[] {
+  const entrySourceFile = findSourceFile(program, sourceFilePath)
+  if (!entrySourceFile) {
+    return []
+  }
+
+  const importedModuleSpecifiers = 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 (referencesRefElementModule(statement, moduleSpecifier)) {
+        importedModuleSpecifiers.add(moduleSpecifier)
+      }
+
+      const importedSourceFile = resolveImportedSourceFile(program, sourceFile.fileName, moduleSpecifier)
+      if (importedSourceFile) {
+        visitSourceFile(importedSourceFile)
+      }
+    }
+  }
+
+  visitSourceFile(entrySourceFile)
+  return [...importedModuleSpecifiers]
+}
+
+async function loadCatalogEntries(
+  packageName: string,
+  compiledEntryPath: string,
+): Promise<NormalizedRefElementCatalogEntry[]> {
+  const resolvedExtensionsUrl = resolveModuleUrlFromEntryPath(compiledEntryPath, `${packageName}/extensions`)
+  if (!resolvedExtensionsUrl) {
+    return []
+  }
+
+  const extensionModule = (await import(resolvedExtensionsUrl)) as Record<string, unknown>
+
+  return extractRawExtensionEntries(extensionModule)
+    .map(normalizeExtensionEntry)
+    .flatMap((catalogEntry) => (catalogEntry ? [catalogEntry] : []))
+}
+
+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 extractRawExtensionEntries(extensionModule: Record<string, unknown>): RawRefElementExtensionEntry[] {
+  const defaultExport = extensionModule.default
+  const extensionEntries = Array.isArray(defaultExport)
+    ? defaultExport
+    : ((defaultExport as { extensions?: unknown[] } | undefined)?.extensions ?? extensionModule.extensions)
+
+  return Array.isArray(extensionEntries) ? (extensionEntries as RawRefElementExtensionEntry[]) : []
+}
+
+function normalizeExtensionEntry(rawEntry: RawRefElementExtensionEntry): NormalizedRefElementCatalogEntry | undefined {
+  const normalizedEntry = rawEntry.options ?? rawEntry
+  const moduleSpecifier = normalizedEntry.resources?.client?.moduleSpecifier
+  const refComponentType = normalizedEntry.type
+
+  if (!moduleSpecifier || !refComponentType) {
+    return undefined
+  }
+
+  return {
+    moduleSpecifier,
+    refComponentType,
+  }
+}
+
+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]
+}
+
+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
+}

package/src/ref-elements/eligible-paths.ts

@@ -0,0 +1,45 @@
+import type { ComponentInfo, ResolvedType } from '../information-extractors/ts/types'
+
+export function extractEligibleRefElementPaths(componentInfo: ComponentInfo): string[] {
+  const elementPropsInfo = componentInfo.props.elementProps
+  if (!elementPropsInfo) {
+    return []
+  }
+
+  const eligibleRefElementPaths = new Set<string>()
+  collectEligibleRefElementPaths(elementPropsInfo.resolvedType, undefined, true, eligibleRefElementPaths)
+  return [...eligibleRefElementPaths]
+}
+
+function collectEligibleRefElementPaths(
+  resolvedType: ResolvedType,
+  parentPath: string | undefined,
+  collectBranchPaths: boolean,
+  eligibleRefElementPaths: Set<string>,
+): void {
+  if (resolvedType.kind === 'union' || resolvedType.kind === 'intersection') {
+    for (const nestedType of resolvedType.types ?? []) {
+      collectEligibleRefElementPaths(nestedType, parentPath, collectBranchPaths, eligibleRefElementPaths)
+    }
+    return
+  }
+
+  if (resolvedType.kind !== 'object') {
+    return
+  }
+
+  for (const [propertyName, propInfo] of Object.entries(resolvedType.properties ?? {})) {
+    if (propertyName === 'elementProps') {
+      const nestedParentPath = parentPath ? `${parentPath}.elementProps` : undefined
+      collectEligibleRefElementPaths(propInfo.resolvedType, nestedParentPath, true, eligibleRefElementPaths)
+      continue
+    }
+
+    const propertyPath = parentPath ? `${parentPath}.${propertyName}` : propertyName
+    if (collectBranchPaths) {
+      eligibleRefElementPaths.add(propertyPath)
+    }
+
+    collectEligibleRefElementPaths(propInfo.resolvedType, propertyPath, false, eligibleRefElementPaths)
+  }
+}

package/src/ref-elements/module-resolution.test.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { resolveModulePathFromEntryPath, resolveModuleUrlFromEntryPath } from './module-resolution'
+
+const temporaryDirectoryPaths: string[] = []
+
+afterEach(() => {
+  for (const temporaryDirectoryPath of temporaryDirectoryPaths.splice(0)) {
+    fs.rmSync(temporaryDirectoryPath, { force: true, recursive: true })
+  }
+})
+
+describe('resolveModulePathFromEntryPath', () => {
+  it('resolves packages from the compiled entry package, not from zero-config-implementation', () => {
+    const temporaryDirectoryPath = fs.mkdtempSync(path.join(os.tmpdir(), 'zero-config-module-resolution-'))
+    temporaryDirectoryPaths.push(temporaryDirectoryPath)
+
+    const packageRootPath = path.join(temporaryDirectoryPath, 'consumer-package')
+    const nodeModulesPath = path.join(packageRootPath, 'node_modules', '@wix')
+    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')
+
+    const compiledEntryPath = path.join(packageRootPath, 'dist', 'Component.mjs')
+    fs.mkdirSync(path.dirname(compiledEntryPath), { recursive: true })
+    fs.writeFileSync(compiledEntryPath, 'export default null\n')
+
+    const resolvedExtensionsPath = resolveModulePathFromEntryPath(
+      compiledEntryPath,
+      '@wix/zero-config-ref-element-fixtures/extensions',
+    )
+
+    expect(resolvedExtensionsPath).toBe(path.join(fixturePackagePath, 'dist', 'extensions.js'))
+  })
+})
+
+describe('resolveModuleUrlFromEntryPath', () => {
+  it('returns a file url for the resolved module path', () => {
+    const resolvedExtensionsUrl = resolveModuleUrlFromEntryPath(
+      path.resolve(__dirname, '../__fixtures__/esm-ref-element-entry.mjs'),
+      '@wix/zero-config-ref-element-fixtures/extensions',
+    )
+
+    expect(resolvedExtensionsUrl).toMatch(/^file:/)
+    expect(resolvedExtensionsUrl).toContain('/packages/ref-element-fixtures/dist/extensions.js')
+  })
+})

package/src/ref-elements/module-resolution.ts

@@ -0,0 +1,21 @@
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { resolve as resolveImportSpecifier } from 'import-meta-resolve'
+
+export function resolveModulePathFromEntryPath(entryPath: string, moduleSpecifier: string): string | undefined {
+  const entryUrl = pathToFileURL(entryPath).href
+
+  try {
+    return fileURLToPath(resolveImportSpecifier(moduleSpecifier, entryUrl))
+  } catch {
+    return undefined
+  }
+}
+
+export function resolveModuleUrlFromEntryPath(entryPath: string, moduleSpecifier: string): string | undefined {
+  const resolvedModulePath = resolveModulePathFromEntryPath(entryPath, moduleSpecifier)
+  if (!resolvedModulePath) {
+    return undefined
+  }
+
+  return pathToFileURL(resolvedModulePath).href
+}

package/src/ref-elements/module-specifier.ts

@@ -0,0 +1,17 @@
+export function extractBasePackageName(moduleSpecifier: string): string {
+  if (moduleSpecifier.startsWith('@')) {
+    const [scopeName = '', packageName = ''] = moduleSpecifier.split('/')
+    return `${scopeName}/${packageName}`
+  }
+
+  return moduleSpecifier.split('/')[0] ?? moduleSpecifier
+}
+
+export function extractModuleLeafExportName(moduleSpecifier: string): string | undefined {
+  const moduleLeafName = moduleSpecifier.split('/').pop()
+  if (!moduleLeafName) {
+    return undefined
+  }
+
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(moduleLeafName) ? moduleLeafName : undefined
+}