@weaverse/next 0.1.0-alpha.12 → 0.1.0-alpha.14

package/src/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/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,
+}

package/src/provider.tsx

@@ -0,0 +1,225 @@
+'use client'
+
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react'
+import { WeaverseNextRootContext } from './root-provider'
+import { createWeaverseNextThemeSettingsStore } from './theme-settings-store'
+import {
+  type TranslateFunction,
+  TranslationProvider,
+} from './translation-context'
+import { TranslationStore } from './translation-store'
+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
+  /** 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)
+
+  // 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,
+      translationStore,
+    }),
+    [
+      client,
+      rootData,
+      pageData,
+      commerce,
+      merchantOverrides,
+      themeSettingsStore,
+      translationStore,
+    ]
+  )
+
+  return (
+    <WeaverseNextContext.Provider value={value}>
+      <TranslationProvider
+        merchantOverrides={merchantOverrides}
+        staticContent={staticContent}
+        t={props.t}
+        translationStore={translationStore}
+      >
+        {children}
+      </TranslationProvider>
+    </WeaverseNextContext.Provider>
+  )
+}

package/src/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/renderer.tsx

@@ -0,0 +1,99 @@
+'use client'
+
+import { WeaverseRoot } from '@weaverse/react'
+import { memo, useContext, useEffect, useLayoutEffect, useMemo } from 'react'
+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
+) {
+  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,
+      translationStore: context?.translationStore,
+    })
+  }, [
+    client,
+    page,
+    data,
+    dataContext,
+    context?.merchantOverrides,
+    context?.themeSettingsStore,
+    context?.translationStore,
+  ])
+
+  useIsomorphicLayoutEffect(() => {
+    weaverse?.flushRenderPhaseUpdates()
+  }, [weaverse])
+
+  if (!weaverse) {
+    return null
+  }
+
+  return (
+    <>
+      <WeaverseRoot context={weaverse} />
+      <WeaverseNextStudio runtime={weaverse} />
+    </>
+  )
+})

package/src/request-info.ts

@@ -0,0 +1,95 @@
+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()
+}
+
+function getPathnameFromContext(context?: WeaverseNextRequestContext): string {
+  if (context?.pathname) {
+    return context.pathname
+  }
+
+  if (context?.url) {
+    let url = toUrl(context.url)
+    return url.pathname || '/'
+  }
+
+  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 } : {}),
+  }
+}