@weaverse/next 0.1.0-alpha.9 → 1.0.1

package/src/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/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,223 @@
+'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 } from './translate'
+import { 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)
+    }
+  }
+}