@weaverse/hydrogen 6.1.2 → 6.2.0

package/src/next/client.ts

@@ -0,0 +1,102 @@
+import type { SchemaType } from '@weaverse/schema'
+import { registerWeaverseNextComponents } from './registry'
+import type {
+  WeaverseNextClient,
+  WeaverseNextClientConfig,
+  WeaverseNextCommerceContext,
+  WeaverseNextComponent,
+  WeaverseNextLoaderData,
+  WeaverseNextLoadPageInput,
+  WeaverseNextRequestContext,
+  WeaverseNextStorefront,
+  WeaverseNextThemeSchema,
+} from './types'
+import { generateDataFromSchema } from './utils'
+
+/**
+ * Request-safe Weaverse client for Next.js. Holds the component registry, theme
+ * data, request/commerce context, and the currently loaded page payload.
+ *
+ * Unlike Hydrogen's `WeaverseClient`, it never receives a React Router
+ * `Request`/`LoaderFunctionArgs`. Network I/O is delegated to `fetchPage` /
+ * `fetchThemeSettings` injected through config, keeping v0 testable without
+ * real Weaverse API calls.
+ */
+class NextClient implements WeaverseNextClient {
+  projectId: string
+  components: WeaverseNextComponent[]
+  themeSchema?: SchemaType | WeaverseNextThemeSchema
+  themeSettings: Record<string, unknown>
+  requestContext?: WeaverseNextRequestContext
+  commerce?: WeaverseNextCommerceContext
+  data: WeaverseNextLoaderData | null = null
+  dataContext: Record<string, unknown> = {}
+
+  private readonly _fetchPage?: WeaverseNextClientConfig['fetchPage']
+  private readonly _fetchThemeSettings?: WeaverseNextClientConfig['fetchThemeSettings']
+
+  constructor(config: WeaverseNextClientConfig) {
+    this.projectId = config.projectId
+    this.components = config.components
+    registerWeaverseNextComponents(this.components)
+    this.themeSchema = config.themeSchema
+    // Seed `themeSchema` defaults before merchant-provided overrides, mirroring
+    // Hydrogen's `loadThemeSettings` (schema defaults under remote `theme`).
+    // Without this, `useThemeSettings()` would miss any setting the merchant
+    // never explicitly overrode.
+    this.themeSettings = {
+      ...generateDataFromSchema(config.themeSchema),
+      ...config.themeSettings,
+    }
+    this.requestContext = config.requestContext
+    this.commerce = config.commerce
+    this._fetchPage = config.fetchPage
+    this._fetchThemeSettings = config.fetchThemeSettings
+  }
+
+  /** Compatibility alias so loaders can call `weaverse.storefront.query(...)`. */
+  get storefront(): WeaverseNextStorefront | undefined {
+    return this.commerce?.storefront
+  }
+
+  loadPage = (
+    input: WeaverseNextLoadPageInput = {}
+  ): Promise<WeaverseNextLoaderData | null> => {
+    if (!this._fetchPage) {
+      throw new Error(
+        '[WeaverseNextClient] loadPage requires a `fetchPage` function in client config.'
+      )
+    }
+    return this._fetchPage(input)
+  }
+
+  loadThemeSettings = (
+    context?: WeaverseNextRequestContext
+  ): Promise<unknown> => {
+    if (!this._fetchThemeSettings) {
+      throw new Error(
+        '[WeaverseNextClient] loadThemeSettings requires a `fetchThemeSettings` function in client config.'
+      )
+    }
+    return this._fetchThemeSettings(context ?? this.requestContext)
+  }
+}
+
+/**
+ * Create a {@link WeaverseNextClient} from explicit config.
+ *
+ * @example
+ * ```ts
+ * let client = createWeaverseNextClient({
+ *   projectId: process.env.WEAVERSE_PROJECT_ID!,
+ *   components,
+ *   commerce: { storefront },
+ *   fetchPage: async ({ type, handle }) => fetchWeaversePage({ type, handle }),
+ * })
+ * ```
+ */
+export function createWeaverseNextClient(
+  config: WeaverseNextClientConfig
+): WeaverseNextClient {
+  return new NextClient(config)
+}

package/src/next/hooks.ts

@@ -0,0 +1,52 @@
+'use client'
+
+import { useContext, useSyncExternalStore } from 'react'
+import { WeaverseNextContext } from './provider'
+import type { WeaverseNextCommerceContext } from './types'
+
+const OUTSIDE_PROVIDER_ERROR = 'must be used inside a <WeaverseNextProvider>.'
+
+function useWeaverseNextContext(hookName: string) {
+  let context = useContext(WeaverseNextContext)
+  if (!context) {
+    throw new Error(
+      `[@weaverse/hydrogen/next] ${hookName} ${OUTSIDE_PROVIDER_ERROR}`
+    )
+  }
+  return context
+}
+
+/**
+ * Read explicit root/global data passed to the provider. Next-native
+ * replacement for `useRouteLoaderData('root')`.
+ */
+export function useWeaverseRootData<T = unknown>(): T {
+  return useWeaverseNextContext('useWeaverseRootData').rootData as T
+}
+
+/**
+ * Read explicit page/route commerce data passed to the provider. Next-native
+ * replacement for section-level `useLoaderData()`.
+ */
+export function useWeaversePageData<T = unknown>(): T {
+  return useWeaverseNextContext('useWeaversePageData').pageData as T
+}
+
+/** Read the app-provided commerce context (storefront/cart/customer). */
+export function useWeaverseCommerce<T = WeaverseNextCommerceContext>(): T {
+  return useWeaverseNextContext('useWeaverseCommerce').commerce as T
+}
+
+/**
+ * Read live Weaverse theme settings. The Studio bridge updates the provider's
+ * external store via `updateThemeSettings`, so components re-render during live
+ * design-mode edits.
+ */
+export function useThemeSettings<T = Record<string, unknown>>(): T {
+  let { themeSettingsStore } = useWeaverseNextContext('useThemeSettings')
+  return useSyncExternalStore(
+    themeSettingsStore.subscribe,
+    themeSettingsStore.getSnapshot,
+    themeSettingsStore.getServerSnapshot
+  ) as T
+}

package/src/next/index.ts

@@ -0,0 +1,145 @@
+/**
+ * Next.js App Router rendering, provider, Studio, translation, and schema APIs.
+ *
+ * When migrating from `@weaverse/hydrogen`, replace route-loader context with
+ * {@link WeaverseNextProvider} props and render page data with
+ * {@link WeaverseNextRenderer}. Import server-only fetching and route-handler
+ * helpers from `@weaverse/hydrogen/next/server`.
+ *
+ * @packageDocumentation
+ */
+
+export type { StudioSelection } from '@weaverse/react'
+// Re-export schema authoring for migration ergonomics.
+export * from '@weaverse/schema'
+export {
+  type CreateTranslateSources,
+  createTranslate,
+  getNestedKey,
+  interpolate,
+  type TranslateFunction,
+} from '../utils/translate'
+export { ThemeTextStore, TranslationStore } from '../utils/translation-store'
+// Client code (components, hooks, runtime, and the `@weaverse/react`
+// re-exports) comes by name from `./client-boundary`, which the build emits as
+// its own `'use client'` file. Every other value export below is server-safe,
+// so a Server Component can import this entry.
+export {
+  bindWeaverseNextStudioRuntime,
+  createWeaverseNextClient,
+  createWeaverseNextRuntime,
+  loadWeaverseNextStudioScript,
+  ThemeTextProvider,
+  TranslationProvider,
+  useChildInstances,
+  useItemInstance,
+  useParentInstance,
+  useStudioSelection,
+  useThemeSettings,
+  useThemeText,
+  useTranslation,
+  useWeaverse,
+  useWeaverseCommerce,
+  useWeaverseNextStudioInternals,
+  useWeaversePageData,
+  useWeaverseRootData,
+  WeaverseNextProvider,
+  WeaverseNextRenderer,
+  WeaverseNextRootProvider,
+  WeaverseNextRuntime,
+  WeaverseNextStudio,
+  WeaverseNextStudioBridge,
+  WeaverseNextStudioConnect,
+} from './client-boundary'
+export type { WeaverseNextItem } from './item'
+export {
+  type RunComponentLoadersArgs,
+  runWeaverseComponentLoaders,
+} from './loader'
+export type { WeaverseNextProviderProps } from './provider'
+export type { WeaverseNextRendererProps } from './renderer'
+export { buildWeaverseNextRequestInfo } from './request-info'
+export {
+  buildWeaverseNextRevalidateRouteContext,
+  DEFAULT_REVALIDATE_ENDPOINT,
+  type RevalidateItemRuntimeLike,
+  revalidateWeaverseNextItem,
+  type WeaverseNextRevalidateRouteContext,
+} from './revalidate-item'
+export type {
+  WeaverseNextRootContextValue,
+  WeaverseNextRootProviderProps,
+} from './root-provider'
+export type { WeaverseNextRenderablePage } from './runtime'
+export {
+  formatWeaverseNextSeoMetadata,
+  getWeaverseNextSeoMetadata,
+  type NextOpenGraph,
+  type NextTwitter,
+  type WeaverseNextSeoInput,
+  type WeaverseNextSeoMetadata,
+  type WeaverseNextSeoPageContainer,
+} from './seo'
+export type { WeaverseNextStudioBridgeProps } from './studio-bridge'
+export type {
+  LoadWeaverseNextStudioScriptOptions,
+  WeaverseNextStudioConnectProps,
+} from './studio-connect'
+export {
+  type CreateWeaverseNextStudioInternalsOptions,
+  createWeaverseNextStudioInternals,
+  type WeaverseNextRouterLike,
+  type WeaverseNextStudioInternals,
+} from './studio-router'
+export {
+  type ResolveWeaverseNextStudioScriptSrcOptions,
+  resolveWeaverseNextStudioScriptSrc,
+} from './studio-script-src'
+export {
+  type CreateWeaverseNextThemeSettingsStoreOptions,
+  createWeaverseNextThemeSettingsStore,
+} from './theme-settings-store'
+export type {
+  ThemeTextProviderProps,
+  ThemeTextValue,
+  TranslationProviderProps,
+  TranslationValue,
+} from './translation-context'
+export type {
+  WeaverseArticle,
+  WeaverseBlog,
+  WeaverseCollection,
+  WeaverseMetaObject,
+  WeaverseNextCacheConfig,
+  WeaverseNextClient,
+  WeaverseNextClientConfig,
+  WeaverseNextCommerceContext,
+  WeaverseNextComponent,
+  WeaverseNextComponentData,
+  WeaverseNextComponentLoaderArgs,
+  WeaverseNextComponentProps,
+  WeaverseNextCustomPageEntry,
+  WeaverseNextFetchCustomPagesOptions,
+  WeaverseNextI18n,
+  WeaverseNextLoaderData,
+  WeaverseNextLoadPageInput,
+  WeaverseNextPageAssignment,
+  WeaverseNextPageData,
+  WeaverseNextRequestContext,
+  WeaverseNextRequestInfo,
+  WeaverseNextRuntimeConfig,
+  WeaverseNextRuntimeInternal,
+  WeaverseNextStorefront,
+  WeaverseNextThemeSchema,
+  WeaverseNextThemeSchemaGroup,
+  WeaverseNextThemeSchemaInput,
+  WeaverseNextThemeSettingsStore,
+  WeaverseNextTranslationChanges,
+  WeaverseNextTranslationEntry,
+  WeaverseNextTranslationItemEntry,
+  WeaverseNextTranslationMap,
+  WeaverseNextTranslationMapEntry,
+  WeaverseProduct,
+} from './types'
+export type { WeaverseNextStudioProps } from './use-weaverse-next-studio'
+export { generateDataFromSchema, isBrowser, isIframe } from './utils'

package/src/next/item.ts

@@ -0,0 +1,167 @@
+import type { ElementData } from '@weaverse/react'
+import { Weaverse, WeaverseItemStore } from '@weaverse/react'
+import type { WeaverseNextRuntime } from './runtime'
+import type {
+  WeaverseNextComponentData,
+  WeaverseNextTranslationItemEntry,
+} from './types'
+import { generateDataFromSchema } from './utils'
+
+/**
+ * Spread a serialized item's nested `data` field into top-level props — the
+ * shape the shared `@weaverse/react` renderer expects. Top-level fields win
+ * over nested ones, matching the constructor's original
+ * `Object.assign(store, schemaDefaults, data, rest)` merge order. Flat payloads
+ * with no nested `data` pass through unchanged.
+ */
+function flattenItemData(update: Omit<ElementData, 'id' | 'type'>) {
+  let { data, ...rest } = update
+  if (!(data && typeof data === 'object' && !Array.isArray(data))) {
+    return rest
+  }
+  return { ...data, ...rest }
+}
+
+/**
+ * While set, item `setData()` queues its subscriber notification here instead
+ * of emitting synchronously. `createWeaverseNextRuntime()` runs during React
+ * render (the renderer's `useMemo`), and constructing a runtime makes core's
+ * `initProject()` call `setData()` on reused item instances (locale/client
+ * navigation) — emitting to `useSyncExternalStore` subscribers mid-render
+ * trips React's setState-in-render warning. Data is still applied
+ * synchronously; only the emit is deferred.
+ */
+let deferredItemUpdates: Set<WeaverseNextItem> | null = null
+
+/**
+ * Run `create` with item update emissions deferred, returning its result and
+ * the items whose `setData()` fired meanwhile. The caller is responsible for
+ * calling `triggerUpdate()` on them once React has committed.
+ */
+export function collectDeferredItemUpdates<T>(
+  create: () => T
+): [T, WeaverseNextItem[]] {
+  let previousQueue = deferredItemUpdates
+  let queue = new Set<WeaverseNextItem>()
+  deferredItemUpdates = queue
+  try {
+    return [create(), [...queue]]
+  } finally {
+    deferredItemUpdates = previousQueue
+  }
+}
+
+/**
+ * Item store that flattens the serialized item's nested `data` field onto the
+ * store and seeds schema defaults — same shape Hydrogen produces, so the
+ * shared `@weaverse/react` renderer can spread props at the top level.
+ */
+export class WeaverseNextItem extends WeaverseItemStore {
+  /** Browser runtime that owns this item store. */
+  declare weaverse: WeaverseNextRuntime
+
+  /**
+   * Cached merged snapshot (base `_store` + translations). Reset whenever the
+   * `_store` ref or the item's translation entry ref changes, so
+   * `useSyncExternalStore` sees a stable object between unrelated re-renders.
+   */
+  private _cachedSnapshot: ElementData | null = null
+  private _snapshotStoreRef: ElementData | null = null
+  private _snapshotTranslationRef: WeaverseNextTranslationItemEntry | null =
+    null
+
+  /** Create an item store from serialized component data and its runtime. */
+  constructor(initialData: WeaverseNextComponentData, weaverse: Weaverse) {
+    super(initialData as ElementData, weaverse)
+    let schemaData = generateDataFromSchema(this.Element?.schema)
+    Object.assign(this._store, schemaData, flattenItemData(initialData))
+  }
+
+  /**
+   * Flatten nested `data` on updates exactly like the constructor does. Core's
+   * `initProject()` calls `setData(item)` when a new runtime serves a page
+   * whose item instances already exist (e.g. locale/client navigation).
+   *
+   * A complete serialized item (it carries `id` and `type`; core's
+   * `initProject()` always passes one) replaces the store the way the
+   * constructor builds it: the schema defaults of the item's own `type` — the
+   * Builder can replace a section in place, keeping its id — then the item's
+   * settings. A payload omits a setting — or the whole optional `data` — when
+   * its value equals the schema default, so merging into the previous store
+   * would keep the previous locale's value visible. Partial updates still
+   * merge. Either way the `_store` ref changes, which invalidates the memoized
+   * snapshot below. The subscriber emit is queued instead of fired when a
+   * render-phase deferral is active (see `collectDeferredItemUpdates`).
+   */
+  setData = (update: Omit<ElementData, 'id' | 'type'>) => {
+    if ('id' in update && 'type' in update) {
+      let { data, type } = update as ElementData
+      let schema = this.weaverse.elementRegistry.get(type)?.schema
+      this._store = {
+        ...generateDataFromSchema(schema),
+        ...(data === undefined ? {} : { data }),
+        ...flattenItemData(update),
+      } as ElementData
+    } else {
+      this.data = flattenItemData(update)
+    }
+    if (deferredItemUpdates) {
+      deferredItemUpdates.add(this)
+    } else {
+      this.triggerUpdate()
+    }
+    return this.data
+  }
+
+  /**
+   * Overlay item-level translations onto the base store when the runtime is in
+   * translation mode. Mirrors Hydrogen's `WeaverseHydrogenItem.getSnapShot()`:
+   * memoized by `_store` ref + translation entry ref so the returned object is
+   * referentially stable, and a fast path that returns the base store untouched
+   * when the item has no translations.
+   */
+  getSnapShot = (): ElementData => {
+    let base = this._store
+    let translations = this.weaverse.translationMap[this._id]
+
+    // No translations → return the base store directly (fast path).
+    if (!translations) {
+      return base
+    }
+
+    // Reuse the cached merge while both the store and translation refs hold.
+    if (
+      this._cachedSnapshot &&
+      this._snapshotStoreRef === base &&
+      this._snapshotTranslationRef === translations
+    ) {
+      return this._cachedSnapshot
+    }
+
+    let merged = { ...base }
+    for (let [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
+  }
+}
+
+/**
+ * Register the Next item constructor globally. Idempotent: calling it more than
+ * once is safe. Invoked by the renderer before it builds a Weaverse instance.
+ */
+export function ensureNextItemConstructor() {
+  if (
+    !Weaverse.ItemConstructor ||
+    Weaverse.ItemConstructor === WeaverseItemStore ||
+    Weaverse.ItemConstructor === WeaverseNextItem
+  ) {
+    Weaverse.ItemConstructor = WeaverseNextItem
+  }
+}

package/src/next/loader.ts

@@ -0,0 +1,135 @@
+import type {
+  WeaverseNextClient,
+  WeaverseNextCommerceContext,
+  WeaverseNextComponent,
+  WeaverseNextComponentData,
+  WeaverseNextLoaderData,
+  WeaverseNextRequestContext,
+} from './types'
+import { generateDataFromSchema } from './utils'
+
+/** Inputs for running registered component loaders over a page tree. */
+export interface RunComponentLoadersArgs {
+  /** Weaverse client containing the component registry. */
+  client: WeaverseNextClient
+  /** Request-scoped commerce override; defaults to `client.commerce`. */
+  commerce?: WeaverseNextCommerceContext
+  /** Request-context override; defaults to `client.requestContext`. */
+  context?: WeaverseNextRequestContext
+  /** Page payload to walk; defaults to `client.data`. */
+  data?: WeaverseNextLoaderData | null
+}
+
+function isItemNode(node: unknown): node is WeaverseNextComponentData {
+  return (
+    typeof node === 'object' &&
+    node !== null &&
+    typeof (node as WeaverseNextComponentData).type === 'string'
+  )
+}
+
+function cloneItem(item: WeaverseNextComponentData): WeaverseNextComponentData {
+  return {
+    ...item,
+    children: Array.isArray(item.children)
+      ? item.children.map((child) =>
+          isItemNode(child) ? cloneItem(child) : { ...child }
+        )
+      : item.children,
+  }
+}
+
+/**
+ * Walk a serialized page tree and run each registered component's `loader`,
+ * attaching the result to the item as `loaderData`.
+ *
+ * Loaders receive explicit `commerce.storefront` (and `weaverse.storefront` as
+ * a compatibility alias via the client). Children are walked recursively when
+ * they are inline item objects; flat `items` arrays are covered by the
+ * top-level walk.
+ *
+ * @returns a cloned `data` object with `loaderData` attached to cloned items.
+ */
+export async function runWeaverseComponentLoaders(
+  args: RunComponentLoadersArgs
+): Promise<WeaverseNextLoaderData | null> {
+  let { client, context, commerce } = args
+  let sourceData = args.data ?? client.data
+  if (!sourceData) {
+    return null
+  }
+  if (!sourceData.page.items.length) {
+    return sourceData
+  }
+
+  let data: WeaverseNextLoaderData = {
+    ...sourceData,
+    page: {
+      ...sourceData.page,
+      items: sourceData.page.items.map(cloneItem),
+    },
+  }
+  let items = data.page.items
+
+  let componentMap = new Map<string, WeaverseNextComponent>()
+  for (let component of client.components) {
+    if (component?.schema?.type) {
+      componentMap.set(component.schema.type, component)
+    }
+  }
+
+  let visited = new Set<string>()
+  let resolvedContext = context ?? client.requestContext
+  let resolvedCommerce = commerce ?? client.commerce
+
+  // Per-call `weaverse` alias. When a request-scoped `commerce` is passed, the
+  // `weaverse.storefront` compatibility alias must resolve to *that* storefront,
+  // not the client's construction-time commerce. Pilot-style loaders call
+  // `weaverse.storefront.query(...)`, so a stale alias would query the wrong
+  // (or an undefined) storefront. When no override is given we reuse the client
+  // as-is to preserve its prototype getters.
+  let resolvedWeaverse: WeaverseNextClient =
+    resolvedCommerce === client.commerce
+      ? client
+      : {
+          ...client,
+          commerce: resolvedCommerce,
+          storefront: resolvedCommerce?.storefront,
+        }
+
+  async function walk(nodes: WeaverseNextComponentData[]) {
+    for (let item of nodes) {
+      if (!item || visited.has(item.id)) {
+        continue
+      }
+      visited.add(item.id)
+
+      let component = componentMap.get(item.type)
+      if (component?.loader) {
+        try {
+          item.loaderData = await component.loader({
+            data: { ...generateDataFromSchema(component.schema), ...item.data },
+            weaverse: resolvedWeaverse,
+            context: resolvedContext,
+            commerce: resolvedCommerce,
+          })
+        } catch (error) {
+          console.warn('❌ Item loader run failed.', item.type, item.id, error)
+        }
+      }
+
+      let children = item.children
+      if (Array.isArray(children)) {
+        let inlineChildren = children.filter(
+          isItemNode
+        ) as WeaverseNextComponentData[]
+        if (inlineChildren.length) {
+          await walk(inlineChildren)
+        }
+      }
+    }
+  }
+
+  await walk(items)
+  return data
+}

package/src/next/main.tsx

@@ -0,0 +1,45 @@
+import { createSchema, type SchemaType } from '@weaverse/schema'
+import type { HTMLAttributes, RefObject } from 'react'
+import type { WeaverseNextComponent, WeaverseNextComponentProps } from './types'
+
+/**
+ * Default `main` root component.
+ *
+ * A Weaverse page tree is a flat `items` array with a single root item of type
+ * `main` whose `children` are the page's top-level sections. Hydrogen ships its
+ * own `main`; the Next adapter provides this minimal, framework-neutral
+ * equivalent so consumers don't have to register one just to render a basic
+ * page tree (omitting it would leave child sections unrendered).
+ *
+ * It renders `children` and forwards the Weaverse DOM attributes the shared
+ * renderer injects (`data-wv-id`, `data-wv-type`, `ref`, `className`, ...rest)
+ * onto the root element. `loaderData` is adapter-internal and stripped so it
+ * never lands on the DOM node.
+ */
+function Main(
+  props: WeaverseNextComponentProps & {
+    ref?: RefObject<HTMLDivElement | null>
+  }
+) {
+  let { children, loaderData, ...rest } = props
+  // `rest` carries the Weaverse-injected DOM attributes (data-wv-*, ref,
+  // className). They are all valid div attributes, so the cast is safe.
+  return <div {...(rest as HTMLAttributes<HTMLDivElement>)}>{children}</div>
+}
+Main.displayName = 'main'
+
+/** Schema for the default {@link Main} root component. Type is exactly `main`. */
+export const mainSchema: SchemaType = createSchema({
+  type: 'main',
+  title: 'Main',
+})
+
+/**
+ * Default `main` component module, registered ahead of user components by
+ * {@link registerWeaverseNextComponents}. Kept package-internal — consumers
+ * override it simply by registering their own component with `type: 'main'`.
+ */
+export const defaultMainComponent: WeaverseNextComponent = {
+  default: Main,
+  schema: mainSchema,
+}