@wix/zero-config-implementation 1.70.0 → 1.72.0

package/src/ref-elements/path-utils.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { buildRefElementManifestKey } from './path-utils'
+
+describe('buildRefElementManifestKey', () => {
+  it('falls back to the leaf key when the ref-element path matches the inherited parent path exactly', () => {
+    expect(buildRefElementManifestKey('cta', 'cta')).toBe('cta')
+    expect(buildRefElementManifestKey('card.elementProps.cta', 'card.elementProps.cta')).toBe('cta')
+  })
+
+  it('keeps nested relative paths when the ref-element path extends the parent path', () => {
+    expect(buildRefElementManifestKey('card.elementProps.cta', 'card')).toBe('cta')
+    expect(buildRefElementManifestKey('card.elementProps.primaryAction', 'card')).toBe('primaryAction')
+  })
+})

package/src/ref-elements/path-utils.ts

@@ -0,0 +1,55 @@
+import { camelCase } from 'case-anything'
+
+const REF_ELEMENT_MARKER_PREFIX = 'mock_ref_element__'
+const REF_ELEMENT_MARKER_PATTERN = /^mock_ref_element__([A-Za-z0-9\-_.!~*'()%]+)$/
+const ELEMENT_PROPS_ROOT_PATH_PREFIX = 'props.elementProps.'
+
+export function createRefElementMarker(elementPropsPath: string): string {
+  return `${REF_ELEMENT_MARKER_PREFIX}${encodeURIComponent(elementPropsPath)}`
+}
+
+export function parseRefElementMarker(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+
+  const trimmedValue = value.trim()
+  const markerMatch = REF_ELEMENT_MARKER_PATTERN.exec(trimmedValue)
+  if (!markerMatch?.[1]) return undefined
+
+  return decodeURIComponent(markerMatch[1])
+}
+
+export function extractElementPropsPathFromPropPath(propPath: string): string | undefined {
+  if (!propPath.startsWith(ELEMENT_PROPS_ROOT_PATH_PREFIX)) {
+    return undefined
+  }
+
+  return propPath.slice(ELEMENT_PROPS_ROOT_PATH_PREFIX.length)
+}
+
+export function extractParentElementPropsPath(relativeElementPropsPropPath: string): string | undefined {
+  const lastDotIndex = relativeElementPropsPropPath.lastIndexOf('.')
+  if (lastDotIndex === -1) return undefined
+
+  return relativeElementPropsPropPath.slice(0, lastDotIndex)
+}
+
+export function splitElementPropsPathSegments(elementPropsPath: string): string[] {
+  return elementPropsPath.split('.').filter((segment) => segment !== 'elementProps')
+}
+
+export function buildRefElementManifestKey(elementPropsPath: string, parentElementPropsPath?: string): string {
+  const elementPropsSegments = splitElementPropsPathSegments(elementPropsPath)
+  const parentSegments = parentElementPropsPath ? splitElementPropsPathSegments(parentElementPropsPath) : []
+  const sharesParentPath = parentSegments.every((segment, index) => elementPropsSegments[index] === segment)
+  const relativeSegments =
+    sharesParentPath && parentSegments.length > 0
+      ? elementPropsSegments.slice(parentSegments.length)
+      : elementPropsSegments
+  const manifestKeySegments = relativeSegments.length > 0 ? relativeSegments : elementPropsSegments.slice(-1)
+
+  if (manifestKeySegments.length <= 1) {
+    return manifestKeySegments[0] ?? ''
+  }
+
+  return camelCase(manifestKeySegments.join(' '))
+}

package/src/ref-elements/types.ts

@@ -0,0 +1,17 @@
+export interface RefElementModule {
+  exportNames: string[]
+  moduleSpecifier: string
+  resolvedModuleUrl: string
+  refComponentType: string
+}
+
+export interface RefElementContext {
+  eligiblePaths: string[]
+  runtimeModules: RefElementModule[]
+}
+
+export interface RefElementMatch {
+  elementPropsPath: string
+  refComponentType: string
+  selector: string
+}

package/src/utils/css-class.ts

@@ -35,6 +35,21 @@ export function isGlobalSemanticClass(className: string): boolean {
   return SEMANTIC_CLASS_PATTERN.test(className)
 }
 
+export function normalizeClassNames(classNameValue: unknown): string[] {
+  if (typeof classNameValue === 'string') {
+    return classNameValue
+      .split(/\s+/)
+      .map((className) => className.trim())
+      .filter(Boolean)
+  }
+
+  if (Array.isArray(classNameValue)) {
+    return classNameValue.flatMap((value) => normalizeClassNames(value))
+  }
+
+  return []
+}
+
 /**
  * Picks the best semantic class from a list of class names.
  * Prefers a class without a BEM modifier (e.g. `card__header`) over one with

package/src/jsx-runtime-interceptor.ts

@@ -1,245 +0,0 @@
-/**
- * JSX Interception
- *
- * Provides mutable interception of React's jsx-runtime functions and registers
- * the Node.js ESM loader hook that redirects `react/jsx-runtime` and
- * `react/jsx-dev-runtime` imports to an in-memory data: URL interceptor.
- *
- * Mutable state lives on `globalThis` via `Symbol.for()` so that the bundled
- * copy of this module and the data: URL interceptor module share the same state.
- */
-
-import { createRequire, register } from 'node:module'
-
-// Use require() to load the real React modules, bypassing Vite alias / ESM loader hook
-const require = createRequire(import.meta.url)
-const originalRuntime = require('react/jsx-runtime') as typeof import('react/jsx-runtime')
-const originalDevRuntime = require('react/jsx-dev-runtime') as typeof import('react/jsx-dev-runtime')
-
-// Type for jsxDEV function
-type JsxDevFn = typeof originalDevRuntime.jsxDEV
-
-// biome-ignore lint/suspicious/noExplicitAny: broad function type matching React.createElement's signature
-type CreateElementFn = (...args: any[]) => unknown
-
-// Captured at module-init time for getOriginalCreateElement(); also reused in
-// registerJsxLoaderHook() to stash the full exports for the react data: URL shim.
-const cjsReact = require('react') as { createElement: CreateElementFn }
-const originalCreateElement: CreateElementFn = cjsReact.createElement
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Shared state via globalThis
-//
-// The bundled copy (inside index.js) and the data: URL interceptor module share
-// mutable state via globalThis. Symbol.for() guarantees a process-wide key.
-// ─────────────────────────────────────────────────────────────────────────────
-
-const STATE_KEY = Symbol.for('zero-config:jsx-interceptor')
-
-interface JsxInterceptorState {
-  currentJsx: typeof originalRuntime.jsx
-  currentJsxs: typeof originalRuntime.jsxs
-  currentJsxDEV: JsxDevFn
-  isInsideOriginal: boolean
-  /** Interceptor for React.createElement set during render; null when not intercepting. */
-  currentCreateElement: CreateElementFn | null
-}
-
-function getState(): JsxInterceptorState {
-  const g = globalThis as unknown as Record<symbol, JsxInterceptorState | undefined>
-  if (!g[STATE_KEY]) {
-    g[STATE_KEY] = {
-      currentJsx: originalRuntime.jsx,
-      currentJsxs: originalRuntime.jsxs,
-      currentJsxDEV: originalDevRuntime.jsxDEV,
-      isInsideOriginal: false,
-      currentCreateElement: null,
-    }
-  }
-  return g[STATE_KEY]!
-}
-
-/**
- * Sets custom jsx/jsxs/jsxDEV implementations for interception.
- * Call with no arguments to restore originals.
- */
-export function setJsxInterceptors(
-  jsx?: typeof originalRuntime.jsx,
-  jsxs?: typeof originalRuntime.jsxs,
-  jsxDEV?: JsxDevFn,
-): void {
-  const state = getState()
-  state.currentJsx = jsx ?? originalRuntime.jsx
-  state.currentJsxs = jsxs ?? originalRuntime.jsxs
-  state.currentJsxDEV = jsxDEV ?? originalDevRuntime.jsxDEV
-}
-
-/**
- * Gets the original jsx/jsxs/jsxDEV functions.
- */
-export function getOriginals() {
-  return {
-    jsx: originalRuntime.jsx,
-    jsxs: originalRuntime.jsxs,
-    jsxDEV: originalDevRuntime.jsxDEV,
-  }
-}
-
-/**
- * Sets (or clears) the React.createElement interceptor used by the wrapper
- * installed on the CJS react module by registerJsxLoaderHook.
- *
- * This handles ESM namespace imports (`import * as React from 'react'`) which
- * snapshot the createElement reference at module-load time. Those snapshots
- * point to the wrapper, which reads from this state on every call.
- *
- * Pass null to restore pass-through behaviour (wrapper delegates to original).
- */
-export function setCreateElementInterceptor(fn: CreateElementFn | null): void {
-  getState().currentCreateElement = fn
-}
-
-/**
- * Returns the pre-wrapper React.createElement captured at module-init time.
- */
-export function getOriginalCreateElement(): CreateElementFn {
-  return originalCreateElement
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Hook Registration
-// ─────────────────────────────────────────────────────────────────────────────
-
-const LOADER_REGISTERED_KEY = Symbol.for('zero-config:jsx-loader-registered')
-const ORIGINALS_KEY = Symbol.for('zero-config:jsx-originals')
-
-interface JsxOriginals {
-  Fragment: typeof originalRuntime.Fragment
-  jsx: typeof originalRuntime.jsx
-  jsxs: typeof originalRuntime.jsxs
-  jsxDEV: JsxDevFn
-}
-
-const REACT_ORIGINALS_KEY = Symbol.for('zero-config:react-originals')
-
-/**
- * Registers a Node.js ESM loader hook that redirects `react/jsx-runtime`,
- * `react/jsx-dev-runtime`, and `react` imports to in-memory `data:` URL
- * interceptors — no separate files required, safe for bundled consumers.
- *
- * Intercepting `react` itself is necessary for bundled components (e.g. from
- * @wix/site-ui) that use `import * as React from 'react'` (Rspack/webpack style)
- * and call `React.createElement` through the namespace object. Node.js snapshots
- * named CJS exports into the namespace at first-load time; since Vitest loads
- * react before our module runs, the snapshot always contains the unwrapped
- * original. The loader hook fires for NEWLY-loaded modules (i.e., the user bundle
- * and its dependencies), redirecting `react` to a data: shim that wraps
- * `createElement` with our state-based interceptor while delegating everything
- * else to the real react instance.
- *
- * Must be called before any dynamic `import()` of user components.
- * Safe to call multiple times; subsequent calls are no-ops.
- */
-export function registerJsxLoaderHook(): void {
-  const globalRecord = globalThis as unknown as Record<symbol, unknown>
-  if (globalRecord[LOADER_REGISTERED_KEY]) return
-  globalRecord[LOADER_REGISTERED_KEY] = true
-
-  const cjsRequire = createRequire(import.meta.url)
-  const realRuntime = cjsRequire('react/jsx-runtime') as typeof originalRuntime
-  const realDevRuntime = cjsRequire('react/jsx-dev-runtime') as typeof originalDevRuntime
-
-  // Stash jsx-runtime originals so the data: interceptor module can read them
-  // without needing createRequire (data: modules have no filesystem context)
-  globalRecord[ORIGINALS_KEY] = {
-    Fragment: realRuntime.Fragment,
-    jsx: realRuntime.jsx,
-    jsxs: realRuntime.jsxs,
-    jsxDEV: realDevRuntime.jsxDEV,
-  } satisfies JsxOriginals
-
-  // Stash the full react module so the react data: shim can re-export everything
-  const cjsReactExports = cjsRequire('react') as Record<string, unknown>
-  globalRecord[REACT_ORIGINALS_KEY] = cjsReactExports
-
-  // Generate named re-export lines for every enumerable property of react.
-  // `createElement` gets a state-aware wrapper; everything else is a direct
-  // delegation to the real react so hooks and other internals work correctly.
-  const reactExportLines = Object.keys(cjsReactExports)
-    .map((key) => {
-      if (key === 'createElement') {
-        return `export function createElement() {
-  var state = globalThis[STATE_KEY];
-  if (state && state.currentCreateElement) return state.currentCreateElement.apply(null, arguments);
-  return r.createElement.apply(null, arguments);
-}`
-      }
-      return `export var ${key} = r.${key};`
-    })
-    .join('\n')
-
-  const reactShimSource = `
-var REACT_KEY = Symbol.for('zero-config:react-originals');
-var STATE_KEY = Symbol.for('zero-config:jsx-interceptor');
-var r = globalThis[REACT_KEY];
-export default r;
-${reactExportLines}
-`
-
-  const reactShimUrl = `data:text/javascript,${encodeURIComponent(reactShimSource)}`
-
-  const interceptorSource = `
-const ORIGINALS_KEY = Symbol.for('zero-config:jsx-originals');
-const STATE_KEY = Symbol.for('zero-config:jsx-interceptor');
-const originals = globalThis[ORIGINALS_KEY];
-function getState() {
-  if (!globalThis[STATE_KEY]) {
-    globalThis[STATE_KEY] = {
-      currentJsx: originals.jsx, currentJsxs: originals.jsxs,
-      currentJsxDEV: originals.jsxDEV, isInsideOriginal: false,
-    };
-  }
-  return globalThis[STATE_KEY];
-}
-export const Fragment = originals.Fragment;
-export function jsx(type, props, key) {
-  const state = getState();
-  if (state.isInsideOriginal) return originals.jsx(type, props, key);
-  state.isInsideOriginal = true;
-  try { return state.currentJsx(type, props, key); }
-  finally { state.isInsideOriginal = false; }
-}
-export function jsxs(type, props, key) {
-  const state = getState();
-  if (state.isInsideOriginal) return originals.jsxs(type, props, key);
-  state.isInsideOriginal = true;
-  try { return state.currentJsxs(type, props, key); }
-  finally { state.isInsideOriginal = false; }
-}
-export function jsxDEV(type, props, key, isStaticChildren, source, self) {
-  const state = getState();
-  if (state.isInsideOriginal) return originals.jsxDEV(type, props, key, isStaticChildren, source, self);
-  state.isInsideOriginal = true;
-  try { return state.currentJsxDEV(type, props, key, isStaticChildren, source, self); }
-  finally { state.isInsideOriginal = false; }
-}
-`
-
-  const interceptorDataUrl = `data:text/javascript,${encodeURIComponent(interceptorSource)}`
-
-  const loaderSource = `
-const INTERCEPTOR_URL = ${JSON.stringify(interceptorDataUrl)};
-const REACT_SHIM_URL = ${JSON.stringify(reactShimUrl)};
-export async function resolve(specifier, context, nextResolve) {
-  if (specifier === 'react/jsx-runtime' || specifier === 'react/jsx-dev-runtime') {
-    return { shortCircuit: true, url: INTERCEPTOR_URL };
-  }
-  if (specifier === 'react') {
-    return { shortCircuit: true, url: REACT_SHIM_URL };
-  }
-  return nextResolve(specifier, context);
-}
-`
-
-  register(`data:text/javascript,${encodeURIComponent(loaderSource)}`)
-}