@weaverse/next 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { Weaverse } from '@weaverse/react';
+import { WeaverseItemStore, Weaverse, ElementData } from '@weaverse/react';
 export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
 export { InspectorGroup, PageType, SchemaType, createSchema } from '@weaverse/schema';
-import { g as WeaverseNextClientConfig, f as WeaverseNextClient, h as WeaverseNextCommerceContext, w as WeaverseNextRequestContext, s as WeaverseNextLoaderData, x as WeaverseNextRequestInfo, j as WeaverseNextComponentData, H as WeaverseNextThemeSettingsStore, z as WeaverseNextRuntimeInternal, y as WeaverseNextRuntimeConfig } from './seo-B9yNko4W.mjs';
-export { W as WeaverseArticle, a as WeaverseBlog, b as WeaverseCollection, c as WeaverseMetaObject, i as WeaverseNextComponent, k as WeaverseNextComponentLoaderArgs, l as WeaverseNextComponentProps, n as WeaverseNextCustomPageEntry, o as WeaverseNextFetchCustomPagesOptions, q as WeaverseNextI18n, r as WeaverseNextLoadPageInput, t as WeaverseNextPageAssignment, u as WeaverseNextPageData, A as WeaverseNextSeoMetadata, E as WeaverseNextStorefront, I as WeaverseProduct, J as formatWeaverseNextSeoMetadata, K as getWeaverseNextSeoMetadata } from './seo-B9yNko4W.mjs';
+import { h as WeaverseNextClientConfig, g as WeaverseNextClient, i as WeaverseNextCommerceContext, x as WeaverseNextRequestContext, t as WeaverseNextLoaderData, a as TranslationStore, y as WeaverseNextRequestInfo, k as WeaverseNextComponentData, I as WeaverseNextThemeSettingsStore, A as WeaverseNextRuntimeInternal, M as WeaverseNextTranslationMap, v as WeaverseNextPageData, z as WeaverseNextRuntimeConfig, J as WeaverseNextTranslationChanges } from './seo-Dos9t22_.mjs';
+export { T as ThemeTextStore, W as WeaverseArticle, b as WeaverseBlog, c as WeaverseCollection, d as WeaverseMetaObject, j as WeaverseNextComponent, l as WeaverseNextComponentLoaderArgs, m as WeaverseNextComponentProps, o as WeaverseNextCustomPageEntry, p as WeaverseNextFetchCustomPagesOptions, r as WeaverseNextI18n, s as WeaverseNextLoadPageInput, u as WeaverseNextPageAssignment, B as WeaverseNextSeoMetadata, F as WeaverseNextStorefront, K as WeaverseNextTranslationEntry, L as WeaverseNextTranslationItemEntry, N as WeaverseNextTranslationMapEntry, O as WeaverseProduct, P as formatWeaverseNextSeoMetadata, Q as getWeaverseNextSeoMetadata } from './seo-Dos9t22_.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -61,15 +61,157 @@ interface RunComponentLoadersArgs {
  */
 declare function runWeaverseComponentLoaders(args: RunComponentLoadersArgs): Promise<WeaverseNextLoaderData | null>;
 
+/**
+ * Traverse a nested object by dot-path.
+ *
+ * @example
+ * getNestedKey({ cart: { title: 'Cart' } }, 'cart.title') // => 'Cart'
+ * getNestedKey({}, 'cart.title', 'fallback')              // => 'fallback'
+ */
+declare function getNestedKey(obj: Record<string, unknown>, path: string, fallback?: string): string | undefined;
+/**
+ * Replace `{{variable}}` patterns in a string with provided values.
+ *
+ * @example
+ * interpolate('Hello {{name}}!', { name: 'World' }) // => 'Hello World!'
+ * interpolate('-{{percentage}}% Off', { percentage: 15 }) // => '-15% Off'
+ */
+declare function interpolate(template: string, variables?: Record<string, string | number>): string;
+/**
+ * Signature for a translation function.
+ */
+type TranslateFunction = (key: string, variables?: Record<string, string | number>) => string;
+interface TranslationValue {
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
+    /**
+     * Translate a key with optional variable interpolation.
+     *
+     * Priority chain (highest wins):
+     * 1. External `t`        (passed into `WeaverseNextRootProvider` / `TranslationProvider`)
+     * 2. Design overrides   (live Builder edits from `TranslationStore`)
+     * 3. `merchantOverrides` (DB/API overrides for the current locale)
+     * 4. `staticContent`     (theme default JSON)
+     * 5. The key itself      (fallback)
+     *
+     * @example
+     * t('cart.title')                           // => "Cart"
+     * t('badge.sale', { percentage: 15 })       // => "-15% Off"
+     */
+    t: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationValue.translationStore} instead. Kept as a
+     * backward-compatible alias pointing at the same store instance.
+     */
+    themeTextStore: TranslationStore | null;
+    /** Exposed so the runtime/Studio bridge can attach it to `internal`. */
+    translationStore: TranslationStore | null;
+}
+interface TranslationProviderProps {
+    children: ReactNode;
+    merchantOverrides?: Record<string, unknown>;
+    staticContent: Record<string, unknown>;
+    /**
+     * Optional external translation function.
+     * When provided it becomes the **highest-priority** source:
+     * if it returns a non-empty string that differs from the raw key,
+     * that value is used; otherwise the internal resolution chain continues.
+     */
+    t?: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationProviderProps.translationStore} instead.
+     * Still accepted for backward compatibility; ignored when `translationStore`
+     * is also provided.
+     */
+    themeTextStore?: TranslationStore | null;
+    /** Optional store for live design-mode text overrides from the builder. */
+    translationStore?: TranslationStore | null;
+}
+/**
+ * Build the `t()` translation function over a fixed set of sources.
+ *
+ * Resolution order, highest priority first:
+ * 1. `externalT`         – host i18n (e.g. Shopify), unless it echoes the key
+ * 2. `designOverrides`   – live design-mode edits, flat dot-path keys
+ * 3. `merchantOverrides` – locale overrides from the API, nested
+ * 4. `staticContent`     – the theme's default locale JSON
+ * 5. the key itself
+ *
+ * Design overrides are looked up per-key (own properties only) rather than
+ * merged into `merchantOverrides`: a flat key like `cart.title` must override
+ * exactly that leaf without wiping sibling keys (`cart.subtitle`), and a
+ * per-key own-property lookup never builds nested objects from
+ * merchant-controlled keys, so it cannot pollute `Object.prototype`.
+ */
+declare function createTranslate(sources: {
+    staticContent: Record<string, unknown>;
+    merchantOverrides?: Record<string, unknown>;
+    designOverrides?: Record<string, string>;
+    externalT?: TranslateFunction;
+}): TranslateFunction;
+/**
+ * Provider that wraps the app to expose the `t()` function.
+ *
+ * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
+ * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `translationStore`   – optional store for live design-mode text overrides
+ *   (the deprecated `themeTextStore` prop is accepted as a fallback)
+ */
+declare function TranslationProvider({ staticContent, merchantOverrides, t: externalT, translationStore, themeTextStore, children, }: TranslationProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the translation `t()` function.
+ *
+ * Must be used inside a component wrapped by `WeaverseNextRootProvider` or
+ * `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   let { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+declare function useTranslation(): TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProvider} instead.
+ */
+declare const ThemeTextProvider: typeof TranslationProvider;
+/**
+ * @deprecated Use {@link useTranslation} instead.
+ */
+declare const useThemeText: typeof useTranslation;
+/**
+ * @deprecated Use {@link TranslationValue} instead.
+ */
+type ThemeTextValue = TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProviderProps} instead.
+ */
+type ThemeTextProviderProps = TranslationProviderProps;
+
 interface WeaverseNextProviderProps {
     children: ReactNode;
     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>;
 }
@@ -144,13 +286,28 @@ interface RevalidateItemRuntimeLike {
 declare function revalidateWeaverseNextItem(runtime: RevalidateItemRuntimeLike, draftItem: WeaverseNextComponentData, endpoint?: string): Promise<void>;
 
 interface WeaverseNextRootContextValue {
+    /** Active-locale static-text overrides shared with route-level providers. */
+    merchantOverrides?: Record<string, unknown>;
+    /** Theme default locale JSON shared with route-level providers. */
+    staticContent: Record<string, unknown>;
     themeSettingsStore: WeaverseNextThemeSettingsStore;
+    /** Single live design-mode static-text override store for the whole session. */
+    translationStore: TranslationStore;
 }
 interface WeaverseNextRootProviderProps {
     children: ReactNode;
     /** Root-loaded theme settings (published-mode fetch, no design-mode context). */
     initialThemeSettings?: Record<string, unknown>;
+    /** Active-locale static-text overrides from `loadThemeSettings().merchantOverrides`. */
+    merchantOverrides?: Record<string, unknown>;
     publicEnv?: Record<string, string | undefined>;
+    /**
+     * Theme default locale JSON (`loadThemeSettings().staticContent`). Falls back
+     * to `themeSchema.i18n.staticContent` when omitted.
+     */
+    staticContent?: Record<string, unknown>;
+    /** Optional external translation function (host i18n); highest priority in `t()`. */
+    t?: TranslateFunction;
     themeSchema?: unknown;
 }
 /**
@@ -174,6 +331,43 @@ interface WeaverseNextRootProviderProps {
  */
 declare function WeaverseNextRootProvider(props: WeaverseNextRootProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * 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.
+ */
+declare class WeaverseNextItem extends WeaverseItemStore {
+    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;
+    private _snapshotStoreRef;
+    private _snapshotTranslationRef;
+    constructor(initialData: WeaverseNextComponentData, weaverse: Weaverse);
+    /**
+     * 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), and
+     * the inherited shallow merge would leave stale top-level props behind.
+     * Assigning through the inherited `data` setter swaps the `_store` ref,
+     * 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">) => ElementData;
+    /**
+     * 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;
+}
+
 declare global {
     interface Window {
         __weaverse?: WeaverseNextRuntime;
@@ -187,14 +381,76 @@ declare class WeaverseNextRuntime extends Weaverse {
     isPreviewMode: boolean;
     isRevisionPreview: boolean;
     sectionType?: string;
-    translationMap: Record<string, unknown>;
+    /**
+     * Translation map received from Builder in design mode, keyed by item ID.
+     * `WeaverseNextItem.getSnapShot()` overlays these onto the data handed to
+     * components, so translations render without mutating the base `_store`.
+     */
+    translationMap: WeaverseNextTranslationMap;
     translationLocale: string;
     translationLanguageId: string;
+    /**
+     * Fresh page data captured while React was rendering. Runtime reuse happens
+     * inside the renderer's render phase (`useMemo`), where applying it through
+     * `setProjectData()` would emit item updates to `useSyncExternalStore`
+     * subscribers mid-render. The renderer applies it post-commit via
+     * `flushRenderPhaseUpdates()`. Never set on design-mode runtimes — the live
+     * Studio tree owns the page data there.
+     */
+    pendingProjectData?: WeaverseNextPageData & {
+        rootId: string;
+    };
+    /**
+     * Reused item instances whose data was refreshed while this runtime was
+     * constructed during render (core `initProject()` calls `setData()` on
+     * them). Their data is already fresh; only the subscriber notification was
+     * deferred to `flushRenderPhaseUpdates()`.
+     */
+    pendingItemUpdates: WeaverseNextItem[];
     constructor(config: WeaverseNextRuntimeConfig);
-    extractTranslationSidecar: () => undefined;
-    setTranslationSidecar: (map?: Record<string, unknown>, locale?: string, languageId?: string) => void;
-    updateTranslation: () => undefined;
-    getTranslationChanges: () => undefined;
+    /**
+     * Pull `translationMap` / `translationLocale` / `translationLanguageId` off
+     * the current page data (Builder attaches them in design mode). Unlike
+     * Hydrogen, this also clears the sidecar to defaults when the new page data
+     * carries none, so a reused runtime / project-data swap can't leave a stale
+     * map overlaying the fresh tree.
+     */
+    extractTranslationSidecar: () => void;
+    /**
+     * Replace the translation sidecar (Builder pushes this when translation data
+     * arrives or the active language changes) and refresh every item so their
+     * merged snapshots recompute.
+     */
+    setTranslationSidecar: (map?: WeaverseNextTranslationMap, locale?: string, languageId?: string) => void;
+    /**
+     * Update a single translatable field for one item. Assigns a new per-item
+     * entry object so `WeaverseNextItem.getSnapShot()`'s translation-ref cache
+     * invalidates, then triggers only that item's subscribers.
+     */
+    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
+    /**
+     * Collect translation changes for the save flow. Returns `undefined` unless
+     * both the locale and language ID are set and at least one entry exists;
+     * each entry key is namespaced as `data.<field>` to match Builder.
+     */
+    getTranslationChanges: () => WeaverseNextTranslationChanges | undefined;
+    /**
+     * Re-extract the translation sidecar whenever project data is replaced (route
+     * change / non-design reuse), before rebuilding item stores. Takes the
+     * renderable page shape (`rootId` resolved) that `getRenderablePage()` and
+     * the reuse branch pass in.
+     */
+    setProjectData: (data: WeaverseNextPageData & {
+        rootId: string;
+    }) => void;
+    /**
+     * Apply updates deferred off the render phase: swap in any pending page data
+     * captured on runtime reuse, then notify items whose data was refreshed
+     * during construction. The renderer calls this from a layout effect right
+     * after commit, so subscribers re-render before paint (no content flash) and
+     * without React's setState-in-render warning.
+     */
+    flushRenderPhaseUpdates: () => void;
 }
 declare function createWeaverseNextRuntime(config: WeaverseNextRuntimeConfig): WeaverseNextRuntime;
 declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): boolean;
@@ -321,4 +577,4 @@ interface WeaverseNextStudioProps extends CreateWeaverseNextStudioInternalsOptio
  */
 declare function WeaverseNextStudio(props: WeaverseNextStudioProps): react_jsx_runtime.JSX.Element;
 
-export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };
+export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, TranslationProvider, type TranslationProviderProps, TranslationStore, type TranslationValue, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextPageData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, WeaverseNextTranslationChanges, WeaverseNextTranslationMap, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createTranslate, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, getNestedKey, interpolate, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useThemeText, useTranslation, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };