@weaverse/hydrogen 6.1.3 → 6.2.0

package/src/next/provider.tsx

@@ -0,0 +1,241 @@
+'use client'
+
+import {
+  StudioSelectionStore,
+  StudioSelectionStoreContext,
+} from '@weaverse/react'
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import type { TranslateFunction } from '../utils/translate'
+import { TranslationStore } from '../utils/translation-store'
+import { WeaverseNextRootContext } from './root-provider'
+import { createWeaverseNextThemeSettingsStore } from './theme-settings-store'
+import { TranslationProvider } from './translation-context'
+import type {
+  WeaverseNextClient,
+  WeaverseNextCommerceContext,
+  WeaverseNextThemeSettingsStore,
+} from './types'
+
+const EMPTY_THEME_SETTINGS: Record<string, unknown> = {}
+const EMPTY_STATIC_CONTENT: Record<string, unknown> = {}
+
+/** Read `themeSchema.i18n.staticContent` for the fallback (no-root) provider. */
+export function getSchemaStaticContent(
+  schema: unknown
+): Record<string, unknown> {
+  let i18n = (schema as { i18n?: { staticContent?: Record<string, unknown> } })
+    ?.i18n
+  return i18n?.staticContent ?? EMPTY_STATIC_CONTENT
+}
+
+/**
+ * Value carried by {@link WeaverseNextContext}. Holds the explicit data
+ * boundaries that replace React Router's `useLoaderData` /
+ * `useRouteLoaderData` inside sections.
+ */
+export interface WeaverseNextContextValue {
+  /** Client used by the renderer and component-loader compatibility hooks. */
+  client?: WeaverseNextClient
+  /** App-provided commerce context for rendered components. */
+  commerce?: WeaverseNextCommerceContext
+  /** Active-locale static-text overrides, threaded into the runtime. */
+  merchantOverrides?: Record<string, unknown>
+  /** Page-scoped data exposed to rendered components. */
+  pageData?: unknown
+  /** Root-scoped data exposed to rendered components. */
+  rootData?: unknown
+  /** Studio selection store read by `useStudioSelection`, threaded into the runtime. */
+  studioSelectionStore: StudioSelectionStore
+  /** Current merged theme-setting values. */
+  themeSettings: Record<string, unknown>
+  /** External store that publishes live theme-setting updates. */
+  themeSettingsStore: WeaverseNextThemeSettingsStore
+  /** Live design-mode static-text override store, threaded into the runtime. */
+  translationStore: TranslationStore
+}
+
+/**
+ * Null sentinel default lets hooks detect usage outside the provider and throw
+ * a clear error instead of silently returning empty data.
+ */
+export const WeaverseNextContext =
+  createContext<WeaverseNextContextValue | null>(null)
+
+/** Explicit page, commerce, theme, and translation data for Next components. */
+export interface WeaverseNextProviderProps {
+  /** React subtree that consumes the Weaverse Next contexts. */
+  children: ReactNode
+  /** Client used by the renderer and component-loader compatibility hooks. */
+  client?: WeaverseNextClient
+  /** App-provided commerce context (storefront/cart/customer). */
+  commerce?: WeaverseNextCommerceContext
+  /**
+   * Active-locale static-text overrides (nested, from `loadThemeSettings()`).
+   * Adopts the root provider's `merchantOverrides` when omitted.
+   */
+  merchantOverrides?: Record<string, unknown>
+  /** Explicit page/route commerce data (replaces section-level `useLoaderData`). */
+  pageData?: unknown
+  /** Explicit root/global data (replaces `useRouteLoaderData('root')`). */
+  rootData?: unknown
+  /**
+   * Theme default locale JSON (`loadThemeSettings().staticContent`). Adopts the
+   * root provider's `staticContent` when omitted, then falls back to
+   * `client.themeSchema.i18n.staticContent`.
+   */
+  staticContent?: Record<string, unknown>
+  /** Optional external translation function (host i18n); highest priority in `t()`. */
+  t?: TranslateFunction
+  /** Theme settings override; falls back to `client.themeSettings`. */
+  themeSettings?: Record<string, unknown>
+}
+
+/**
+ * Client boundary that supplies explicit root/page/commerce data to Weaverse
+ * sections. Next-native replacement for `withWeaverse` + route loader data —
+ * no React Router route matches are emulated.
+ *
+ * In App Router, create/pass `client` only from a client component wrapper. A
+ * `WeaverseNextClient` contains functions and component references, so it is
+ * not serializable across a Server Component → Client Component boundary.
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ *
+ * <WeaverseNextProvider client={client} rootData={rootData} pageData={pageData} commerce={commerce}>
+ *   <WeaverseNextRenderer />
+ * </WeaverseNextProvider>
+ * ```
+ */
+export function WeaverseNextProvider(props: WeaverseNextProviderProps) {
+  let { children, client, rootData, pageData, commerce, themeSettings } = props
+  let rootContext = useContext(WeaverseNextRootContext)
+
+  let themeSettingsValue =
+    themeSettings ?? client?.themeSettings ?? EMPTY_THEME_SETTINGS
+
+  // Fallback translation store when no `WeaverseNextRootProvider` is mounted.
+  // Otherwise the ambient root store is adopted, so exactly one live static-text
+  // store backs Builder's `updateStaticText()` RPC per page load — mirroring the
+  // theme-settings store adoption below. `useRef`, not `useMemo`: React may
+  // evict memoized values, but this store must survive every re-render so
+  // design-mode overrides already applied by Builder are never dropped.
+  let ownTranslationStoreRef = useRef<TranslationStore | null>(null)
+  if (!(rootContext || ownTranslationStoreRef.current)) {
+    ownTranslationStoreRef.current = new TranslationStore()
+  }
+  let translationStore =
+    rootContext?.translationStore ??
+    (ownTranslationStoreRef.current as TranslationStore)
+
+  // Same adoption rule as the translation store: one selection store per page
+  // load, so the Studio bridge and root-level UI observe the same instance.
+  // The route's own store is only used when no root provider is mounted.
+  let [ownSelectionStore] = useState(() => new StudioSelectionStore())
+  let studioSelectionStore =
+    rootContext?.studioSelectionStore ?? ownSelectionStore
+
+  // Static content / merchant overrides feeding `useTranslation()`. Precedence:
+  // explicit prop → ambient root value → (static content only) schema default.
+  let staticContent =
+    props.staticContent ??
+    rootContext?.staticContent ??
+    getSchemaStaticContent(client?.themeSchema)
+  let merchantOverrides =
+    props.merchantOverrides ?? rootContext?.merchantOverrides
+
+  // Fallback store for apps that don't mount `WeaverseNextRootProvider`. Not
+  // created at all when a root store is present, so exactly one
+  // `WeaverseNextThemeSettingsStore` exists per page load either way.
+  let ownThemeSettingsStore = useMemo(() => {
+    if (rootContext) {
+      return null
+    }
+    return createWeaverseNextThemeSettingsStore({
+      schema: client?.themeSchema,
+      settings: themeSettingsValue,
+    })
+  }, [rootContext, client?.themeSchema, themeSettingsValue])
+
+  let themeSettingsStore =
+    rootContext?.themeSettingsStore ??
+    (ownThemeSettingsStore as WeaverseNextThemeSettingsStore)
+
+  // When adopting the root store, route-supplied theme data augments it in
+  // place (merge), never replaces it — Studio and root `Header`/`Footer` must
+  // keep observing the same instance. Guarded so a stable `themeSettingsValue`
+  // across re-renders doesn't re-merge/re-notify every render.
+  //
+  // This runs in an effect, not render: mutating a store shared outside this
+  // component's subtree is a side effect, and render functions must stay
+  // pure under concurrent React (retried/discarded renders, StrictMode
+  // double-invocation). The root's initial theme is authoritative for SSR;
+  // a route's `themeSettings`/`client.themeSettings` override applies after
+  // client mount instead of racing a render-phase store mutation. Apps that
+  // don't mount `WeaverseNextRootProvider` are unaffected — `themeSettings`
+  // still renders synchronously on SSR via `ownThemeSettingsStore` below.
+  let mergedIntoRootRef = useRef<Record<string, unknown> | undefined>(undefined)
+  useEffect(() => {
+    if (
+      rootContext &&
+      themeSettingsValue !== EMPTY_THEME_SETTINGS &&
+      mergedIntoRootRef.current !== themeSettingsValue
+    ) {
+      rootContext.themeSettingsStore.updateThemeSettings(themeSettingsValue)
+      mergedIntoRootRef.current = themeSettingsValue
+    }
+  }, [rootContext, themeSettingsValue])
+
+  // Do not depend on `themeSettingsValue` here. In fallback mode it is already
+  // represented by a new `themeSettingsStore`; in root-adoption mode the
+  // post-mount merge effect notifies `useThemeSettings()` subscribers. Including
+  // it would recreate this context with a stale root snapshot before the effect
+  // fires, causing an avoidable extra render.
+  let value = useMemo<WeaverseNextContextValue>(
+    () => ({
+      client,
+      rootData,
+      pageData,
+      commerce: commerce ?? client?.commerce,
+      merchantOverrides,
+      themeSettings: themeSettingsStore.getSnapshot(),
+      themeSettingsStore,
+      studioSelectionStore,
+      translationStore,
+    }),
+    [
+      client,
+      rootData,
+      pageData,
+      commerce,
+      merchantOverrides,
+      themeSettingsStore,
+      studioSelectionStore,
+      translationStore,
+    ]
+  )
+
+  return (
+    <WeaverseNextContext.Provider value={value}>
+      <StudioSelectionStoreContext.Provider value={studioSelectionStore}>
+        <TranslationProvider
+          merchantOverrides={merchantOverrides}
+          staticContent={staticContent}
+          t={props.t}
+          translationStore={translationStore}
+        >
+          {children}
+        </TranslationProvider>
+      </StudioSelectionStoreContext.Provider>
+    </WeaverseNextContext.Provider>
+  )
+}

package/src/next/registry.ts

@@ -0,0 +1,63 @@
+import { Weaverse } from '@weaverse/react'
+import { ensureNextItemConstructor } from './item'
+import { defaultMainComponent } from './main'
+import type { WeaverseNextComponent } from './types'
+
+const MAIN_TYPE = 'main'
+
+/**
+ * Component types already pushed into the element registry. Registration is
+ * idempotent by `schema.type`, so callers may pass fresh arrays per request
+ * without causing repeated global registry writes.
+ */
+const registeredComponentTypes = new Set<string>()
+
+/**
+ * Register Next adapter components with the shared Weaverse element registry.
+ *
+ * This mutates global Weaverse runtime state, so callers should run it while
+ * creating their app/client wiring, not from a React render body.
+ *
+ * A default `main` root component is always registered first so consumers don't
+ * have to register one for basic page-tree rendering. If the consumer registers
+ * their own `main`, that one is preferred: we only prepend the default when the
+ * provided components don't already include a `main`, so a user-provided `main`
+ * never collides with (or is shadowed by) the default.
+ */
+export function registerWeaverseNextComponents(
+  components: WeaverseNextComponent[]
+) {
+  ensureNextItemConstructor()
+
+  let hasUserMain = components.some(
+    (component) => component.schema?.type === MAIN_TYPE
+  )
+  let effectiveComponents = hasUserMain
+    ? components
+    : [defaultMainComponent, ...components]
+
+  for (let component of effectiveComponents) {
+    let type = component.schema.type
+    let element = {
+      type,
+      Component: component.default,
+      schema: component.schema,
+      loader: component.loader,
+    }
+
+    if (type === MAIN_TYPE && hasUserMain) {
+      // `main` is the only built-in default. If a consumer registers their own
+      // root component after the default was already installed by another
+      // client/test/request, prefer the consumer version by replacing the global
+      // registry entry explicitly.
+      Weaverse.elementRegistry.set(type, element)
+      registeredComponentTypes.add(type)
+      continue
+    }
+
+    if (type && !registeredComponentTypes.has(type)) {
+      Weaverse.registerElement(element)
+      registeredComponentTypes.add(type)
+    }
+  }
+}

package/src/next/renderer.tsx

@@ -0,0 +1,102 @@
+'use client'
+
+import { WeaverseRoot } from '@weaverse/react'
+import { memo, useContext, useEffect, useLayoutEffect, useMemo } from 'react'
+import type { JSX } from 'react/jsx-runtime'
+import { WeaverseNextContext } from './provider'
+import { createWeaverseNextRuntime } from './runtime'
+import type {
+  WeaverseNextClient,
+  WeaverseNextLoaderData,
+  WeaverseNextPageData,
+} from './types'
+import { WeaverseNextStudio } from './use-weaverse-next-studio'
+
+const EMPTY_DATA_CONTEXT: Record<string, unknown> = {}
+const useIsomorphicLayoutEffect =
+  typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+function getRenderablePage(
+  data: WeaverseNextLoaderData | null | undefined
+): (WeaverseNextPageData & { rootId: string }) | null {
+  let page = data?.page
+  if (!page) {
+    return null
+  }
+  let rootId =
+    page.rootId ??
+    page.items.find((item) => item.type === 'main')?.id ??
+    page.items[0]?.id ??
+    page.id
+  return { ...page, rootId }
+}
+
+/** Page payload, client, and connector data accepted by the Next renderer. */
+export interface WeaverseNextRendererProps {
+  /** Client to render from. Defaults to the provider's client. */
+  client?: WeaverseNextClient
+  /** Page payload to render. Defaults to `client.data`. */
+  data?: WeaverseNextLoaderData | null
+  /** Data-connector context for `{{...}}` template replacement. */
+  dataContext?: Record<string, unknown>
+}
+
+/**
+ * Render a serialized Weaverse page tree through `@weaverse/react` primitives.
+ *
+ * Reads the client/page data supplied by {@link WeaverseNextProvider} when no
+ * props are passed, or accepts an explicit `client` + `data` for standalone use. Builds a
+ * framework-neutral `Weaverse` core instance (no React Router hooks) and hands
+ * it to the shared `WeaverseRoot`.
+ */
+export const WeaverseNextRenderer = memo(function WeaverseNextRendererComponent(
+  props: WeaverseNextRendererProps
+): JSX.Element | null {
+  let context = useContext(WeaverseNextContext)
+  let client = props.client ?? context?.client
+  let data = props.data ?? client?.data ?? null
+  let dataContext =
+    props.dataContext ?? client?.dataContext ?? EMPTY_DATA_CONTEXT
+
+  let page = useMemo(() => getRenderablePage(data), [data])
+
+  let weaverse = useMemo(() => {
+    if (!page) {
+      return null
+    }
+
+    return createWeaverseNextRuntime({
+      client,
+      data: { ...(data as WeaverseNextLoaderData), page },
+      dataContext,
+      merchantOverrides: context?.merchantOverrides,
+      themeSettingsStore: context?.themeSettingsStore,
+      studioSelectionStore: context?.studioSelectionStore,
+      translationStore: context?.translationStore,
+    })
+  }, [
+    client,
+    page,
+    data,
+    dataContext,
+    context?.merchantOverrides,
+    context?.themeSettingsStore,
+    context?.studioSelectionStore,
+    context?.translationStore,
+  ])
+
+  useIsomorphicLayoutEffect(() => {
+    weaverse?.flushRenderPhaseUpdates()
+  }, [weaverse])
+
+  if (!weaverse) {
+    return null
+  }
+
+  return (
+    <>
+      <WeaverseRoot context={weaverse} />
+      <WeaverseNextStudio runtime={weaverse} />
+    </>
+  )
+})

package/src/next/request-info.ts

@@ -0,0 +1,124 @@
+import type {
+  WeaverseNextRequestContext,
+  WeaverseNextRequestInfo,
+} from './types'
+
+function toUrl(value: string | URL): URL {
+  return typeof value === 'string' ? new URL(value, 'http://localhost') : value
+}
+
+function getSearchParamsFromContext(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams)
+  }
+
+  if (context?.url) {
+    let url = toUrl(context.url)
+    return new URLSearchParams(url.searchParams)
+  }
+
+  return new URLSearchParams()
+}
+
+/**
+ * Put the request's market prefix (`i18n.pathPrefix`, e.g. `/de-de`) on a
+ * pathname that does not carry it yet.
+ *
+ * A Next app builds its request context from the route path, and with
+ * locale-segmented routes that path is usually unprefixed. Studio's address
+ * bar follows `requestInfo.pathname`, so without the prefix it snaps back to
+ * the default market after every navigation. A path that already carries the
+ * prefix, and the default market's empty prefix, pass through unchanged.
+ */
+export function withPathPrefix(
+  pathname: string,
+  i18n?: WeaverseNextRequestContext['i18n']
+): string {
+  let raw = typeof i18n?.pathPrefix === 'string' ? i18n.pathPrefix : ''
+  // Split rather than regex-trim: `pathPrefix` is caller input, and an anchored
+  // `/\/+$/` backtracks polynomially on long runs of slashes.
+  let segments = raw.split('/').filter(Boolean)
+  let prefix = segments.length > 0 ? `/${segments.join('/')}` : ''
+  if (
+    prefix === '' ||
+    pathname === prefix ||
+    pathname.startsWith(`${prefix}/`)
+  ) {
+    return pathname
+  }
+  return pathname === '/' ? prefix : `${prefix}${pathname}`
+}
+
+function getPathnameFromContext(context?: WeaverseNextRequestContext): string {
+  if (context?.pathname) {
+    return withPathPrefix(context.pathname, context.i18n)
+  }
+
+  if (context?.url) {
+    let url = toUrl(context.url)
+    return withPathPrefix(url.pathname || '/', context.i18n)
+  }
+
+  return '/'
+}
+
+function coerceQueryValue(value: string): string | boolean {
+  if (value === 'true') {
+    return true
+  }
+  if (value === 'false') {
+    return false
+  }
+  return value
+}
+
+function toQueryRecord(
+  searchParams: URLSearchParams
+): Record<string, string | boolean> {
+  let queries: Record<string, string | boolean> = {}
+  for (let [key, value] of searchParams.entries()) {
+    queries[key] = coerceQueryValue(value)
+  }
+  return queries
+}
+
+const TRANSIENT_STUDIO_PARAMS = new Set([
+  'weaverseDraftItem',
+  // Legacy name from the original design-mode draft-item spike. Keep it out of
+  // runtime requestInfo too, in case an older Builder bundle is in front of a
+  // newer Next storefront.
+  '__weaverseDraftItem',
+])
+
+function getRequestInfoSearchParams(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  let searchParams = new URLSearchParams(getSearchParamsFromContext(context))
+  for (let key of TRANSIENT_STUDIO_PARAMS) {
+    searchParams.delete(key)
+  }
+  return searchParams
+}
+
+/**
+ * Build the Hydrogen-like request info shape consumed by the Studio bridge.
+ * Duplicate query keys keep the last value, matching `URLSearchParams` iteration
+ * assignment and Hydrogen's practical query-object behavior.
+ */
+export function buildWeaverseNextRequestInfo(
+  context?: WeaverseNextRequestContext
+): WeaverseNextRequestInfo {
+  let searchParams = getRequestInfoSearchParams(context)
+  let search = searchParams.toString()
+
+  return {
+    pathname: getPathnameFromContext(context),
+    search: search ? `?${search}` : '',
+    queries: toQueryRecord(searchParams),
+    ...(context?.i18n ? { i18n: context.i18n } : {}),
+    ...(context?.pageType ? { pageType: context.pageType } : {}),
+    ...(context?.handle ? { handle: context.handle } : {}),
+  }
+}