@weaverse/hydrogen 5.17.1 → 5.18.0

package/src/WeaverseHydrogenRoot.tsx

@@ -0,0 +1,649 @@
+import type { ElementData } from '@weaverse/react'
+import {
+  isBrowser,
+  useSafeExternalStore,
+  Weaverse,
+  WeaverseItemStore,
+  WeaverseRoot,
+} from '@weaverse/react'
+import {
+  type ComponentType,
+  type JSX,
+  memo,
+  Suspense,
+  useMemo,
+  useRef,
+} from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+import {
+  Await,
+  useLoaderData,
+  useMatches,
+  useRouteLoaderData,
+} from 'react-router'
+import { defaultComponents } from './components'
+import {
+  type TranslateFunction,
+  TranslationProvider,
+} from './hooks/translation-context'
+import { createWeaverseDataContext } from './hooks/use-weaverse-data-context'
+import type {
+  HydrogenComponentData,
+  HydrogenElement,
+  HydrogenPageData,
+  HydrogenThemeSettings,
+  TranslationChanges,
+  TranslationEntry,
+  TranslationItemEntry,
+  TranslationMap,
+  WeaverseInternal,
+  WeaverseLoaderRequestInfo,
+} from './index'
+import type {
+  HydrogenComponent,
+  WeaverseHydrogenParams,
+  WeaverseLoaderData,
+} from './types'
+import { hasWeaverseStudio } from './types'
+import { generateDataFromSchema } from './utils'
+import {
+  pickWeaverseData,
+  type WeaverseDataValue,
+} from './utils/pick-weaverse-data'
+import { normalizeRequestInfo } from './utils/studio-request-info'
+import { syncReusedInstance } from './utils/sync-reused-instance'
+import { TranslationStore } from './utils/translation-store'
+import { useStudio, useStudioConnect } from './utils/use-studio'
+import {
+  ThemeSettingsStoreContext,
+  useCreateThemeSettingsStore,
+  useThemeSettingsStore,
+} from './utils/use-theme-settings-store'
+
+/*
+=== IMPORTANT DESIGN PRINCIPLE ===
+CONSTRUCTOR TIMING AND DEFERRED PROCESSING
+
+When working with React component systems and registries:
+- Keep constructors SIMPLE - don't do heavy work in them
+- Defer processing until RENDER TIME, not initialization
+- Avoid registry lookups during object construction (components may not be registered yet)
+- Simple code is more reliable than complex upfront optimization
+- Respect the initialization sequence: registration → instance creation → rendering
+
+History: Attempting to do schema processing in the constructor (commit 495e1220) broke
+the pilot template because it tried to access the component registry before components were registered.
+The fix was to defer that work until the component is actually rendered.
+====================================
+*/
+
+/** Runtime store for one rendered Hydrogen component instance. */
+export class WeaverseHydrogenItem extends WeaverseItemStore {
+  /** Owning Hydrogen runtime instance. */
+  declare weaverse: WeaverseHydrogen
+
+  /**
+   * Cached merged snapshot (base + translations).
+   * Reset to `null` whenever `_store` or the item's translation entry changes.
+   */
+  private _cachedSnapshot: ElementData | null = null
+  private _snapshotStoreRef: ElementData | null = null
+  private _snapshotTranslationRef: TranslationItemEntry | null = null
+
+  /** Creates an item store from serialized component data and its owner. */
+  constructor(initialData: HydrogenComponentData, weaverse: WeaverseHydrogen) {
+    super(initialData, weaverse)
+    const { data, ...rest } = initialData
+    if (!this.Element?.schema) {
+      console.error('Element is missing schema or not found!')
+      return
+    }
+    const schemaData = generateDataFromSchema(this.Element.schema)
+    Object.assign(this._store, schemaData, data, rest)
+  }
+
+  /** Registered component definition for this item's type. */
+  get Element(): HydrogenElement {
+    return super.Element
+  }
+
+  /**
+   * Override getSnapShot to merge translation data when in translation mode.
+   * Memoizes the result: returns the same object reference as long as
+   * both `_store` and the translation entry haven't changed.
+   * This is critical for `useSyncExternalStore` stability.
+   */
+  getSnapShot = (): ElementData => {
+    const base = this._store
+    const translations = this.weaverse.translationMap?.[this._id]
+
+    // No translations → return base directly (fast path)
+    if (!translations) {
+      return base
+    }
+
+    // Check if cache is still valid (same _store ref + same translation entry ref)
+    if (
+      this._cachedSnapshot &&
+      this._snapshotStoreRef === base &&
+      this._snapshotTranslationRef === translations
+    ) {
+      return this._cachedSnapshot
+    }
+
+    // Build merged snapshot
+    const merged = { ...base }
+    for (const [key, entry] of Object.entries(translations)) {
+      if (entry.translatedValue !== undefined) {
+        merged[key] = entry.translatedValue
+      }
+    }
+
+    this._cachedSnapshot = merged
+    this._snapshotStoreRef = base
+    this._snapshotTranslationRef = translations
+    return merged
+  }
+}
+
+Weaverse.ItemConstructor = WeaverseHydrogenItem
+
+/**
+ * Hydrogen-specific Weaverse runtime that owns page data, component stores,
+ * Studio state, and translation sidecars for one rendered page.
+ */
+export class WeaverseHydrogen extends Weaverse {
+  /** Identifier of the rendered page. */
+  pageId: string
+  /** Runtime services and project metadata exposed to integrations. */
+  internal: Partial<WeaverseInternal>
+  /** Normalized URL and locale information for the current request. */
+  requestInfo: WeaverseLoaderRequestInfo
+  /** Identifier of the project supplying the page. */
+  projectId: string
+  /** Origin used for Studio assets and editor communication. */
+  weaverseHost: string
+  /** Base URL used for public content API requests. */
+  weaverseApiBase: string
+  /**
+   * API key read from environment/configuration for storefront requests or
+   * supplied by Studio requests while editing and previewing.
+   */
+  weaverseApiKey: string
+  /** Studio asset version supplied by the preview request. */
+  weaverseVersion: string
+  /** Whether the page is running inside the visual editor. */
+  isDesignMode: boolean
+  /** Whether a single component preview is being rendered. */
+  isPreviewMode: boolean
+  /** Whether a saved page revision is being previewed. */
+  isRevisionPreview: boolean
+  /** Component type requested by section preview mode. */
+  sectionType: string
+  /** Component item store constructor used by the core runtime. */
+  declare ItemConstructor: typeof WeaverseHydrogenItem
+  /** Current page content owned by the runtime. */
+  declare data: HydrogenPageData
+  /** Component item stores indexed by instance ID. */
+  declare static itemInstances: Map<string, WeaverseHydrogenItem>
+  /** Registered component definitions indexed by component type. */
+  declare static elementRegistry: Map<string, HydrogenElement>
+
+  // ─── Translation sidecar (design mode only) ────────────────────────
+  /**
+   * Translation map received from the builder in design mode.
+   * Keyed by item ID, each entry maps field names to translated values.
+   * `WeaverseHydrogenItem.getSnapShot()` merges these into the data
+   * returned to components, so translations render without monkey-patching.
+   */
+  translationMap: TranslationMap = {}
+  /** Locale code for the active translation sidecar. */
+  translationLocale = ''
+  /** Builder language identifier for the active translation sidecar. */
+  translationLanguageId = ''
+
+  /** Creates a page runtime from resolved loader data and request settings. */
+  constructor(params: WeaverseHydrogenParams) {
+    const { internal, pageId, requestInfo, ...coreParams } = params
+    super({ ...coreParams })
+    this.internal = internal
+    this.pageId = pageId
+    this.requestInfo = requestInfo
+    // Assign configuration properties
+    this.projectId = params.projectId
+    this.weaverseHost = params.weaverseHost
+    this.weaverseApiBase = params.weaverseApiBase
+    this.weaverseApiKey = params.weaverseApiKey
+    this.weaverseVersion = params.weaverseVersion || ''
+    this.isDesignMode = params.isDesignMode ?? false
+    this.isPreviewMode = params.isPreviewMode ?? false
+    this.isRevisionPreview = params.isRevisionPreview ?? false
+    this.sectionType = params.sectionType || ''
+
+    // Extract translation sidecar from page data if present (design mode)
+    this.extractTranslationSidecar()
+  }
+
+  /**
+   * Extract translation sidecar data from `this.data` (the page data).
+   * The builder attaches `translationMap`, `translationLocale`, and
+   * `translationLanguageId` to the page data in design mode.
+   */
+  extractTranslationSidecar = () => {
+    const pageData = this.data as Record<string, any>
+    if (pageData?.translationMap) {
+      this.translationMap = pageData.translationMap
+      this.translationLocale = pageData.translationLocale || ''
+      this.translationLanguageId = pageData.translationLanguageId || ''
+    }
+  }
+
+  /**
+   * Set the translation sidecar data.
+   * Called by the studio bridge when translation data arrives or changes.
+   * Triggers a re-render of all items so translated snapshots are recalculated.
+   */
+  setTranslationSidecar = (
+    translationMap: TranslationMap,
+    locale: string,
+    languageId: string
+  ) => {
+    this.translationMap = translationMap
+    this.translationLocale = locale
+    this.translationLanguageId = languageId
+    // Invalidate all item snapshot caches and trigger re-render
+    this.refreshAllItems()
+  }
+
+  /**
+   * Update a single translation entry for a specific item field.
+   * Used by the studio bridge when the user edits a translatable field.
+   */
+  updateTranslation = (
+    itemId: string,
+    key: string,
+    originalValue: string,
+    translatedValue: string
+  ) => {
+    if (!this.translationMap[itemId]) {
+      this.translationMap[itemId] = {}
+    }
+    // Create a new entry reference so getSnapShot detects the change
+    this.translationMap[itemId] = {
+      ...this.translationMap[itemId],
+      [key]: { originalValue, translatedValue },
+    }
+    // Trigger re-render for this specific item
+    const instance = this.itemInstances.get(itemId)
+    if (instance) {
+      instance.triggerUpdate()
+    }
+  }
+
+  /**
+   * Collect all translation changes across all weaverse instances.
+   * Used by the save flow to persist translation edits.
+   */
+  getTranslationChanges = (): TranslationChanges | undefined => {
+    const entries: TranslationEntry[] = []
+    const languageId = this.translationLanguageId
+    if (!(this.translationLocale && languageId)) {
+      return
+    }
+
+    for (const [itemId, fields] of Object.entries(this.translationMap)) {
+      for (const [key, entry] of Object.entries(fields)) {
+        entries.push({
+          itemId,
+          key: `data.${key}`,
+          originalValue: entry.originalValue,
+          translatedValue: entry.translatedValue,
+        })
+      }
+    }
+
+    if (entries.length === 0) {
+      return
+    }
+    return { languageId, entries }
+  }
+
+  /**
+   * Override setProjectData to re-extract translation sidecar from new page data.
+   */
+  setProjectData = (data: HydrogenPageData) => {
+    this.data = data
+    this.extractTranslationSidecar()
+    this.initProject()
+  }
+}
+
+function createWeaverseInstance(
+  params: WeaverseHydrogenParams
+): WeaverseHydrogen {
+  const normalizedParams = normalizeRequestInfo(params)
+  if (isBrowser) {
+    window.__weaverses = window.__weaverses || {}
+    const existing = window.__weaverses[normalizedParams.pageId]
+    // Reuse the instance only while the browser stays on the same URL —
+    // navigation to a different pathname/search builds a fresh instance.
+    const isReused =
+      existing?.requestInfo?.pathname ===
+        normalizedParams.requestInfo.pathname &&
+      existing?.requestInfo?.search === normalizedParams.requestInfo.search
+    const weaverse = isReused
+      ? existing
+      : new WeaverseHydrogen(normalizedParams)
+    window.__weaverses[normalizedParams.pageId] = weaverse
+    if (weaverse.isDesignMode) {
+      weaverse.requestInfo = normalizedParams.requestInfo
+      if (hasWeaverseStudio(window)) {
+        window.weaverseStudio.refreshStudio(normalizedParams)
+      }
+    } else if (isReused) {
+      // Same-URL revalidation in live/preview mode: the reused instance
+      // must adopt the fresh loader payload (see syncReusedInstance).
+      syncReusedInstance(weaverse, normalizedParams)
+    }
+    return weaverse
+  }
+  return new WeaverseHydrogen(normalizedParams)
+}
+
+const StudioBridge = memo(({ context }: { context: WeaverseHydrogen }) => {
+  useStudio(context)
+  return null
+})
+
+const StudioConnect = memo(() => {
+  useStudioConnect()
+  return null
+})
+
+/**
+ * Component lists already pushed into the element registry. Registration is
+ * idempotent (the registry checks `has(type)`), but walking the full list
+ * allocates and loops on every render — theme component arrays are
+ * module-level constants, so register each list identity once.
+ */
+const registeredComponentLists = new WeakSet<HydrogenComponent[]>()
+
+function RenderRoot(props: {
+  data: WeaverseLoaderData
+  components: HydrogenComponent[]
+  dataContext?: Record<string, any>
+}) {
+  const { data, components, dataContext } = props
+  if (!registeredComponentLists.has(components)) {
+    for (const comp of [...components, ...defaultComponents]) {
+      if (comp?.schema?.type) {
+        registerComponent({
+          type: comp.schema.type,
+          Component: comp.default,
+          schema: comp.schema,
+          loader: comp.loader,
+        })
+      }
+    }
+    registeredComponentLists.add(components)
+  }
+  const { page, configs, project, pageAssignment } = data || {}
+
+  // Keep original page data - processing will happen at component level in renderer
+
+  const weaverse = createWeaverseInstance({
+    ...configs,
+    dataContext,
+    data: page,
+    pageId: page?.id,
+    internal: { project, pageAssignment },
+  })
+  return (
+    <>
+      <WeaverseRoot context={weaverse} />
+      <StudioBridge context={weaverse} />
+    </>
+  )
+}
+
+/**
+ * Register a Weaverse component with the global element registry.
+ * Must be called before rendering components in WeaverseHydrogenRoot.
+ *
+ * @param element - Component configuration with schema, Component, and optional loader
+ *
+ * @example
+ * ```typescript
+ * import Hero from './sections/Hero'
+ * import { schema } from './sections/Hero'
+ *
+ * registerComponent({
+ *   type: 'hero',
+ *   Component: Hero,
+ *   schema,
+ *   loader: async ({ data, weaverse }) => {
+ *     return { someData: 'value' }
+ *   }
+ * })
+ * ```
+ */
+export function registerComponent(element: HydrogenElement) {
+  WeaverseHydrogen.registerElement(element)
+}
+
+/** Props passed to a custom Weaverse page error component. */
+export interface WeaverseHydrogenRootErrorProps {
+  /** Error raised while resolving or rendering the Weaverse page. */
+  error: Error | unknown
+}
+
+/** Props accepted by {@link WeaverseHydrogenRoot}. */
+export interface WeaverseHydrogenRootProps {
+  /** Theme components available to the page renderer. */
+  components: HydrogenComponent[]
+  /**
+   * Optional explicit `weaverseData` payload. When provided, bypasses the
+   * automatic route-scoped resolution. Accepts a resolved value, a
+   * `Promise` (handled via `<Await>`), or `null` to suppress rendering.
+   *
+   * Recommended for nested layout + child route compositions where two
+   * `<WeaverseHydrogenRoot>` instances need to render different Weaverse
+   * pages on the same URL. See issue #451.
+   */
+  data?: WeaverseDataValue
+  /** Component rendered when page data cannot be resolved or awaited. */
+  errorComponent?: React.FC<WeaverseHydrogenRootErrorProps>
+}
+
+/**
+ * Renders the Weaverse page for the current React Router route.
+ *
+ * Pass `data` to override automatic route-loader resolution. A promise is
+ * handled with React Router's `Await`, while explicit `null` suppresses output.
+ */
+export const WeaverseHydrogenRoot = memo(
+  ({
+    components,
+    data: dataProp,
+    errorComponent: ErrorComponent = ({ error }) => (
+      <div>
+        {error instanceof Error
+          ? error.message
+          : 'An unexpected error occurred'}
+      </div>
+    ),
+  }: WeaverseHydrogenRootProps) => {
+    const matches = useMatches()
+
+    // Flat route-keyed data context for data-connector template resolution
+    // (e.g. {{root.layout.shop.name}}). Legitimately needs all matches;
+    // memoized so same-matches re-renders don't allocate a fresh context.
+    const enhancedDataContext = useMemo(
+      () => createWeaverseDataContext(matches),
+      [matches]
+    )
+
+    // Route-scoped weaverseData lookup. `useLoaderData()` returns the
+    // closest route's loader data, which is what makes nested layout +
+    // child routes work — each <WeaverseHydrogenRoot> instance resolves
+    // to its own route's weaverseData. See pickWeaverseData() for the
+    // three-tier fallback policy.
+    const ownLoaderData = useLoaderData() as unknown
+    const weaverseData = useMemo(
+      () => pickWeaverseData(dataProp, ownLoaderData, matches),
+      [dataProp, ownLoaderData, matches]
+    )
+
+    // Explicit `data={null}` is the documented signal for "suppress rendering"
+    // (e.g. a route conditionally disables Weaverse without unmounting the
+    // component). This is distinct from auto-resolution returning `null`,
+    // which means "data was expected but not found" — the error path below.
+    if (dataProp === null) {
+      return null
+    }
+
+    if (weaverseData) {
+      if (weaverseData instanceof Promise) {
+        return (
+          <ErrorBoundary fallbackRender={ErrorComponent as any}>
+            <Suspense>
+              <Await resolve={weaverseData}>
+                {(resolvedData) => (
+                  <RenderRoot
+                    components={components}
+                    data={resolvedData}
+                    dataContext={enhancedDataContext}
+                  />
+                )}
+              </Await>
+            </Suspense>
+          </ErrorBoundary>
+        )
+      }
+      return (
+        <RenderRoot
+          components={components}
+          data={weaverseData}
+          dataContext={enhancedDataContext}
+        />
+      )
+    }
+    return (
+      <ErrorComponent
+        error={{ message: 'No Weaverse data found in route matches!' }}
+      />
+    )
+  }
+)
+
+/**
+ * Options for the `withWeaverse` HOC.
+ */
+export type WithWeaverseOptions = {
+  /**
+   * Optional external translation function (e.g. from Shopify i18n).
+   * When provided it becomes the **highest-priority** source
+   * in the `t()` resolution chain exposed by `useTranslation()`.
+   */
+  t?: TranslateFunction
+}
+
+/**
+ * Higher-order component that wraps your app with Weaverse theme settings and
+ * translation context, and mounts the Studio connect bridge.
+ *
+ * Export the result as your root route's **`Layout`** (not the default route
+ * `Component`). In React Router the root `Layout` wraps both the matched route
+ * and its `ErrorBoundary`, so the Studio bridge keeps rendering on 404s and
+ * loader/render errors — exactly the pages where Studio must still answer its
+ * handshake instead of reporting a false "Connection lost". A default-component
+ * wrapper (`export default withWeaverse(App)`) is replaced by the error
+ * boundary on those routes and would drop the bridge.
+ *
+ * @param Component - The root layout component to wrap
+ * @param options   - Optional configuration (e.g. an external `t` function)
+ * @returns Wrapped component with theme settings + translation providers
+ *
+ * @example
+ * ```typescript
+ * import { withWeaverse } from '@weaverse/hydrogen'
+ *
+ * // Basic usage — export as the root route Layout
+ * export const Layout = withWeaverse(RootLayout)
+ *
+ * // With an external translation function
+ * export const Layout = withWeaverse(RootLayout, { t: myI18nFunction })
+ * ```
+ */
+export function withWeaverse(
+  Component: ComponentType<any>,
+  options?: WithWeaverseOptions
+) {
+  return (props: JSX.IntrinsicAttributes) => {
+    const themeSettingsStore = useCreateThemeSettingsStore()
+    const translationData = useTranslationData()
+    const translationStoreRef = useRef<TranslationStore | null>(null)
+    if (!translationStoreRef.current) {
+      translationStoreRef.current = new TranslationStore()
+    }
+    return (
+      <ThemeSettingsStoreContext.Provider value={themeSettingsStore}>
+        <TranslationProvider
+          merchantOverrides={translationData.merchantOverrides}
+          staticContent={translationData.staticContent}
+          t={options?.t}
+          translationStore={translationStoreRef.current}
+        >
+          <StudioConnect />
+          <Component {...props} />
+        </TranslationProvider>
+      </ThemeSettingsStoreContext.Provider>
+    )
+  }
+}
+
+/**
+ * Internal hook to read staticContent and merchantOverrides from root loader data.
+ * Similar pattern to useThemeSettingsStore – reads from the 'root' route loader.
+ */
+function useTranslationData(): {
+  staticContent: Record<string, unknown>
+  merchantOverrides?: Record<string, unknown>
+} {
+  const data = useRouteLoaderData('root') as {
+    weaverseTheme?: {
+      staticContent?: Record<string, unknown>
+      merchantOverrides?: Record<string, unknown>
+    }
+  }
+  return {
+    staticContent: data?.weaverseTheme?.staticContent ?? {},
+    merchantOverrides: data?.weaverseTheme?.merchantOverrides,
+  }
+}
+
+/**
+ * React hook to access Weaverse theme settings from anywhere in your component tree.
+ * Must be used within a component wrapped by `withWeaverse` or inside `WeaverseHydrogenRoot`.
+ *
+ * @returns Current theme settings object
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const theme = useThemeSettings()
+ *   const primaryColor = theme.colors?.primary
+ *
+ *   return <div style={{ color: primaryColor }}>Styled content</div>
+ * }
+ * ```
+ */
+export function useThemeSettings<T = HydrogenThemeSettings>() {
+  const themeSettingsStore = useThemeSettingsStore()
+  const settings = useSafeExternalStore(
+    themeSettingsStore.subscribe,
+    themeSettingsStore.getSnapshot,
+    themeSettingsStore.getServerSnapshot
+  )
+  return settings as T
+}

package/src/components/index.ts

@@ -0,0 +1,10 @@
+import type { HydrogenComponent } from '../types'
+import MainComponent, { schema as mainSchema } from './main'
+
+/** Built-in components required to render the root of every Weaverse page. */
+export let defaultComponents: HydrogenComponent[] = [
+  {
+    default: MainComponent,
+    schema: mainSchema,
+  },
+]

package/src/components/main.tsx

@@ -0,0 +1,28 @@
+import { createSchema, type SchemaType } from '@weaverse/schema'
+import type { HTMLAttributes } from 'react'
+import type { HydrogenComponentProps } from '../types'
+
+/*
+  Main is the default Weaverse component that is used to render the main content.
+  This component wraps all the sections/components inside a Weaverse page.
+*/
+function Main(props: HydrogenComponentProps & HTMLAttributes<HTMLDivElement>) {
+  let { children, dangerouslySetInnerHTML, ...rest } = props
+
+  return (
+    <div
+      {...rest}
+      // biome-ignore lint/correctness/noChildrenProp: <explanation>
+      children={children}
+      // biome-ignore lint/security/noDangerouslySetInnerHtmlWithChildren: <explanation>
+      dangerouslySetInnerHTML={children ? undefined : dangerouslySetInnerHTML}
+    />
+  )
+}
+
+export default Main
+
+export let schema: SchemaType = createSchema({
+  type: 'main',
+  title: 'Main',
+})

package/src/hooks/theme-text-context.tsx

@@ -0,0 +1,14 @@
+export {
+  createTranslate,
+  getNestedKey,
+  interpolate,
+  ThemeTextProvider,
+  type ThemeTextProviderProps,
+  type ThemeTextValue,
+  type TranslateFunction,
+  TranslationProvider,
+  type TranslationProviderProps,
+  type TranslationValue,
+  useThemeText,
+  useTranslation,
+} from './translation-context'