@weaverse/hydrogen 5.11.1 → 5.12.1

package/dist/index.d.mts

@@ -12,6 +12,27 @@ import { ReactNode, ComponentType, JSX, ForwardRefExoticComponent } from 'react'
 import { NavigateFunction, UIMatch } from 'react-router';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * Minimal mutable store for design-mode static text overrides.
+ *
+ * useSyncExternalStore-compatible. Passed into ThemeTextProvider which
+ * subscribes internally and merges overrides into merchantOverrides.
+ * The studio bridge calls updateOverrides() via weaverse.internal.themeTextStore.
+ *
+ * Shape: flat Record<string, string> — dot-notation keys map to values
+ * (e.g. "cart.title" → "Shopping Cart").
+ */
+declare class ThemeTextStore {
+    overrides: Record<string, string>;
+    private listeners;
+    setOverrides: (overrides: Record<string, string>) => void;
+    updateOverrides: (newOverrides: Record<string, string>) => void;
+    getSnapshot: () => Record<string, string>;
+    getServerSnapshot: () => Record<string, string>;
+    subscribe: (callback: () => void) => () => void;
+    private emit;
+}
+
 type WeaverseThemeData = {
     theme: HydrogenThemeSettings;
     schema?: HydrogenThemeSchema;
@@ -59,7 +80,7 @@ type ThemeTextValue = {
      *
      * Priority chain (highest wins):
      * 1. External `t`        (passed into `withWeaverse` / `ThemeTextProvider`)
-     * 2. `merchantOverrides` (DB overrides for the current locale)
+     * 2. `merchantOverrides` (DB overrides for the current locale + design overrides)
      * 3. `staticContent`     (theme default JSON)
      * 4. The key itself      (fallback)
      *
@@ -68,6 +89,10 @@ type ThemeTextValue = {
      * t('badge.sale', { percentage: 15 })       // => "-15% Off"
      */
     t: TranslateFunction;
+    /** Exposed for useStudio to attach to weaverse.internal. Null in production. */
+    themeTextStore: ThemeTextStore | null;
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
 };
 type ThemeTextProviderProps = {
     staticContent: Record<string, unknown>;
@@ -79,6 +104,8 @@ type ThemeTextProviderProps = {
      * that value is used; otherwise the internal resolution chain continues.
      */
     t?: TranslateFunction;
+    /** Optional store for live design-mode text overrides from the builder. */
+    themeTextStore?: ThemeTextStore | null;
     children: ReactNode;
 };
 /**
@@ -86,8 +113,9 @@ type ThemeTextProviderProps = {
  *
  * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
  * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `themeTextStore`     – optional store for live design-mode text overrides
  */
-declare function ThemeTextProvider({ staticContent, merchantOverrides, t: externalT, children, }: ThemeTextProviderProps): react_jsx_runtime.JSX.Element;
+declare function ThemeTextProvider({ staticContent, merchantOverrides, t: externalT, themeTextStore, children, }: ThemeTextProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the theme text `t()` function.
  *
@@ -105,8 +133,22 @@ declare function useThemeText(): ThemeTextValue;
 
 declare class WeaverseHydrogenItem extends WeaverseItemStore {
     weaverse: WeaverseHydrogen;
+    /**
+     * Cached merged snapshot (base + translations).
+     * Reset to `null` whenever `_store` or the item's translation entry changes.
+     */
+    private _cachedSnapshot;
+    private _snapshotStoreRef;
+    private _snapshotTranslationRef;
     constructor(initialData: HydrogenComponentData, weaverse: WeaverseHydrogen);
     get Element(): HydrogenElement;
+    /**
+     * Override getSnapShot to merge translation data when in translation mode.
+     * Memoizes the result: returns the same object reference as long as
+     * both `_store` and the translation entry haven't changed.
+     * This is critical for `useSyncExternalStore` stability.
+     */
+    getSnapShot: () => ElementData;
 }
 declare class WeaverseHydrogen extends Weaverse {
     pageId: string;
@@ -125,7 +167,42 @@ declare class WeaverseHydrogen extends Weaverse {
     data: HydrogenPageData;
     static itemInstances: Map<string, WeaverseHydrogenItem>;
     static elementRegistry: Map<string, HydrogenElement>;
+    /**
+     * Translation map received from the builder in design mode.
+     * Keyed by item ID, each entry maps field names to translated values.
+     * `WeaverseHydrogenItem.getSnapShot()` merges these into the data
+     * returned to components, so translations render without monkey-patching.
+     */
+    translationMap: TranslationMap;
+    translationLocale: string;
+    translationLanguageId: string;
     constructor(params: WeaverseHydrogenParams);
+    /**
+     * Extract translation sidecar data from `this.data` (the page data).
+     * The builder attaches `translationMap`, `translationLocale`, and
+     * `translationLanguageId` to the page data in design mode.
+     */
+    extractTranslationSidecar: () => void;
+    /**
+     * Set the translation sidecar data.
+     * Called by the studio bridge when translation data arrives or changes.
+     * Triggers a re-render of all items so translated snapshots are recalculated.
+     */
+    setTranslationSidecar: (translationMap: TranslationMap, locale: string, languageId: string) => void;
+    /**
+     * Update a single translation entry for a specific item field.
+     * Used by the studio bridge when the user edits a translatable field.
+     */
+    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
+    /**
+     * Collect all translation changes across all weaverse instances.
+     * Used by the save flow to persist translation edits.
+     */
+    getTranslationChanges: () => TranslationChanges | undefined;
+    /**
+     * Override setProjectData to re-extract translation sidecar from new page data.
+     */
+    setProjectData: (data: HydrogenPageData) => void;
 }
 /**
  * Register a Weaverse component with the global element registry.
@@ -440,6 +517,8 @@ type WeaverseInternal = {
     navigate: NavigateFunction;
     revalidate: () => void;
     themeSettingsStore: ThemeSettingsStore;
+    themeTextStore?: ThemeTextStore | null;
+    merchantOverrides?: Record<string, unknown> | null;
 };
 /**
  * Optimized: Use direct type alias to maintain consistency
@@ -531,9 +610,6 @@ type WeaverseI18n = I18nBase & {
     [key: string]: any;
 };
 type HydrogenThemeSchema = {
-    betaFlags?: {
-        contentManager?: boolean;
-    };
     info: {
         name: string;
         version: string;
@@ -550,6 +626,8 @@ type HydrogenThemeSchema = {
         defaultLocale: WeaverseI18n;
         shopLocales: WeaverseI18n[];
         staticContent?: Record<string, unknown>;
+        /** Enable the translation UI in the builder. */
+        translation?: boolean;
     };
 };
 type FetchProjectRequestBody = {
@@ -918,6 +996,35 @@ type LoadPageParams = {
      */
     projectId?: string;
 };
+/** A single translated field for one item */
+interface TranslationMapEntry {
+    originalValue: string;
+    translatedValue: string;
+}
+/** Per-item translation fields, keyed by field name */
+type TranslationItemEntry = {
+    [key: string]: TranslationMapEntry;
+};
+/**
+ * Translation map sent from the builder alongside page data in design mode.
+ * Keyed by item ID, each value maps field names to translation entries.
+ */
+type TranslationMap = {
+    [itemId: string]: TranslationItemEntry;
+};
+/** A single translation entry for save payloads */
+interface TranslationEntry {
+    deleted?: boolean;
+    itemId: string;
+    key: string;
+    originalValue: string;
+    translatedValue: string;
+}
+/** Result of collecting translation changes for the save flow */
+type TranslationChanges = {
+    languageId: string;
+    entries: TranslationEntry[];
+};
 
 declare let defaultComponents: HydrogenComponent[];
 
@@ -1020,4 +1127,4 @@ declare const IMAGES_PLACEHOLDERS: {
     product_18: string;
 };
 
-export { type CacheResponseValidator, type ComponentDataValue, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, type WithWeaverseOptions, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getNestedKey, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, hasWeaverseStudio, interpolate, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useThemeText, useWeaverseDataContext, withWeaverse };
+export { type CacheResponseValidator, type ComponentDataValue, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, ThemeTextProvider, type ThemeTextProviderProps, ThemeTextStore, type ThemeTextValue, type TranslateFunction, type TranslationChanges, type TranslationEntry, type TranslationItemEntry, type TranslationMap, type TranslationMapEntry, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, type WithWeaverseOptions, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getNestedKey, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, hasWeaverseStudio, interpolate, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useThemeText, useWeaverseDataContext, withWeaverse };

package/dist/index.d.ts

@@ -12,6 +12,27 @@ import { ReactNode, ComponentType, JSX, ForwardRefExoticComponent } from 'react'
 import { NavigateFunction, UIMatch } from 'react-router';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * Minimal mutable store for design-mode static text overrides.
+ *
+ * useSyncExternalStore-compatible. Passed into ThemeTextProvider which
+ * subscribes internally and merges overrides into merchantOverrides.
+ * The studio bridge calls updateOverrides() via weaverse.internal.themeTextStore.
+ *
+ * Shape: flat Record<string, string> — dot-notation keys map to values
+ * (e.g. "cart.title" → "Shopping Cart").
+ */
+declare class ThemeTextStore {
+    overrides: Record<string, string>;
+    private listeners;
+    setOverrides: (overrides: Record<string, string>) => void;
+    updateOverrides: (newOverrides: Record<string, string>) => void;
+    getSnapshot: () => Record<string, string>;
+    getServerSnapshot: () => Record<string, string>;
+    subscribe: (callback: () => void) => () => void;
+    private emit;
+}
+
 type WeaverseThemeData = {
     theme: HydrogenThemeSettings;
     schema?: HydrogenThemeSchema;
@@ -59,7 +80,7 @@ type ThemeTextValue = {
      *
      * Priority chain (highest wins):
      * 1. External `t`        (passed into `withWeaverse` / `ThemeTextProvider`)
-     * 2. `merchantOverrides` (DB overrides for the current locale)
+     * 2. `merchantOverrides` (DB overrides for the current locale + design overrides)
      * 3. `staticContent`     (theme default JSON)
      * 4. The key itself      (fallback)
      *
@@ -68,6 +89,10 @@ type ThemeTextValue = {
      * t('badge.sale', { percentage: 15 })       // => "-15% Off"
      */
     t: TranslateFunction;
+    /** Exposed for useStudio to attach to weaverse.internal. Null in production. */
+    themeTextStore: ThemeTextStore | null;
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
 };
 type ThemeTextProviderProps = {
     staticContent: Record<string, unknown>;
@@ -79,6 +104,8 @@ type ThemeTextProviderProps = {
      * that value is used; otherwise the internal resolution chain continues.
      */
     t?: TranslateFunction;
+    /** Optional store for live design-mode text overrides from the builder. */
+    themeTextStore?: ThemeTextStore | null;
     children: ReactNode;
 };
 /**
@@ -86,8 +113,9 @@ type ThemeTextProviderProps = {
  *
  * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
  * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `themeTextStore`     – optional store for live design-mode text overrides
  */
-declare function ThemeTextProvider({ staticContent, merchantOverrides, t: externalT, children, }: ThemeTextProviderProps): react_jsx_runtime.JSX.Element;
+declare function ThemeTextProvider({ staticContent, merchantOverrides, t: externalT, themeTextStore, children, }: ThemeTextProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the theme text `t()` function.
  *
@@ -105,8 +133,22 @@ declare function useThemeText(): ThemeTextValue;
 
 declare class WeaverseHydrogenItem extends WeaverseItemStore {
     weaverse: WeaverseHydrogen;
+    /**
+     * Cached merged snapshot (base + translations).
+     * Reset to `null` whenever `_store` or the item's translation entry changes.
+     */
+    private _cachedSnapshot;
+    private _snapshotStoreRef;
+    private _snapshotTranslationRef;
     constructor(initialData: HydrogenComponentData, weaverse: WeaverseHydrogen);
     get Element(): HydrogenElement;
+    /**
+     * Override getSnapShot to merge translation data when in translation mode.
+     * Memoizes the result: returns the same object reference as long as
+     * both `_store` and the translation entry haven't changed.
+     * This is critical for `useSyncExternalStore` stability.
+     */
+    getSnapShot: () => ElementData;
 }
 declare class WeaverseHydrogen extends Weaverse {
     pageId: string;
@@ -125,7 +167,42 @@ declare class WeaverseHydrogen extends Weaverse {
     data: HydrogenPageData;
     static itemInstances: Map<string, WeaverseHydrogenItem>;
     static elementRegistry: Map<string, HydrogenElement>;
+    /**
+     * Translation map received from the builder in design mode.
+     * Keyed by item ID, each entry maps field names to translated values.
+     * `WeaverseHydrogenItem.getSnapShot()` merges these into the data
+     * returned to components, so translations render without monkey-patching.
+     */
+    translationMap: TranslationMap;
+    translationLocale: string;
+    translationLanguageId: string;
     constructor(params: WeaverseHydrogenParams);
+    /**
+     * Extract translation sidecar data from `this.data` (the page data).
+     * The builder attaches `translationMap`, `translationLocale`, and
+     * `translationLanguageId` to the page data in design mode.
+     */
+    extractTranslationSidecar: () => void;
+    /**
+     * Set the translation sidecar data.
+     * Called by the studio bridge when translation data arrives or changes.
+     * Triggers a re-render of all items so translated snapshots are recalculated.
+     */
+    setTranslationSidecar: (translationMap: TranslationMap, locale: string, languageId: string) => void;
+    /**
+     * Update a single translation entry for a specific item field.
+     * Used by the studio bridge when the user edits a translatable field.
+     */
+    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
+    /**
+     * Collect all translation changes across all weaverse instances.
+     * Used by the save flow to persist translation edits.
+     */
+    getTranslationChanges: () => TranslationChanges | undefined;
+    /**
+     * Override setProjectData to re-extract translation sidecar from new page data.
+     */
+    setProjectData: (data: HydrogenPageData) => void;
 }
 /**
  * Register a Weaverse component with the global element registry.
@@ -440,6 +517,8 @@ type WeaverseInternal = {
     navigate: NavigateFunction;
     revalidate: () => void;
     themeSettingsStore: ThemeSettingsStore;
+    themeTextStore?: ThemeTextStore | null;
+    merchantOverrides?: Record<string, unknown> | null;
 };
 /**
  * Optimized: Use direct type alias to maintain consistency
@@ -531,9 +610,6 @@ type WeaverseI18n = I18nBase & {
     [key: string]: any;
 };
 type HydrogenThemeSchema = {
-    betaFlags?: {
-        contentManager?: boolean;
-    };
     info: {
         name: string;
         version: string;
@@ -550,6 +626,8 @@ type HydrogenThemeSchema = {
         defaultLocale: WeaverseI18n;
         shopLocales: WeaverseI18n[];
         staticContent?: Record<string, unknown>;
+        /** Enable the translation UI in the builder. */
+        translation?: boolean;
     };
 };
 type FetchProjectRequestBody = {
@@ -918,6 +996,35 @@ type LoadPageParams = {
      */
     projectId?: string;
 };
+/** A single translated field for one item */
+interface TranslationMapEntry {
+    originalValue: string;
+    translatedValue: string;
+}
+/** Per-item translation fields, keyed by field name */
+type TranslationItemEntry = {
+    [key: string]: TranslationMapEntry;
+};
+/**
+ * Translation map sent from the builder alongside page data in design mode.
+ * Keyed by item ID, each value maps field names to translation entries.
+ */
+type TranslationMap = {
+    [itemId: string]: TranslationItemEntry;
+};
+/** A single translation entry for save payloads */
+interface TranslationEntry {
+    deleted?: boolean;
+    itemId: string;
+    key: string;
+    originalValue: string;
+    translatedValue: string;
+}
+/** Result of collecting translation changes for the save flow */
+type TranslationChanges = {
+    languageId: string;
+    entries: TranslationEntry[];
+};
 
 declare let defaultComponents: HydrogenComponent[];
 
@@ -1020,4 +1127,4 @@ declare const IMAGES_PLACEHOLDERS: {
     product_18: string;
 };
 
-export { type CacheResponseValidator, type ComponentDataValue, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, type WithWeaverseOptions, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getNestedKey, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, hasWeaverseStudio, interpolate, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useThemeText, useWeaverseDataContext, withWeaverse };
+export { type CacheResponseValidator, type ComponentDataValue, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, ThemeTextProvider, type ThemeTextProviderProps, ThemeTextStore, type ThemeTextValue, type TranslateFunction, type TranslationChanges, type TranslationEntry, type TranslationItemEntry, type TranslationMap, type TranslationMapEntry, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, type WithWeaverseOptions, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getNestedKey, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, hasWeaverseStudio, interpolate, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useThemeText, useWeaverseDataContext, withWeaverse };