@weaverse/hydrogen 5.11.0 → 5.12.0

package/dist/index.d.mts

@@ -105,8 +105,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 +139,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.
@@ -531,9 +580,6 @@ type WeaverseI18n = I18nBase & {
     [key: string]: any;
 };
 type HydrogenThemeSchema = {
-    betaFlags?: {
-        contentManager?: boolean;
-    };
     info: {
         name: string;
         version: string;
@@ -550,6 +596,8 @@ type HydrogenThemeSchema = {
         defaultLocale: WeaverseI18n;
         shopLocales: WeaverseI18n[];
         staticContent?: Record<string, unknown>;
+        /** Enable the translation UI in the builder. */
+        translation?: boolean;
     };
 };
 type FetchProjectRequestBody = {
@@ -918,6 +966,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 +1097,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, 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

@@ -105,8 +105,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 +139,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.
@@ -531,9 +580,6 @@ type WeaverseI18n = I18nBase & {
     [key: string]: any;
 };
 type HydrogenThemeSchema = {
-    betaFlags?: {
-        contentManager?: boolean;
-    };
     info: {
         name: string;
         version: string;
@@ -550,6 +596,8 @@ type HydrogenThemeSchema = {
         defaultLocale: WeaverseI18n;
         shopLocales: WeaverseI18n[];
         staticContent?: Record<string, unknown>;
+        /** Enable the translation UI in the builder. */
+        translation?: boolean;
     };
 };
 type FetchProjectRequestBody = {
@@ -918,6 +966,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 +1097,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, 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.js

@@ -48,12 +48,12 @@ function getNestedKey(obj, path, fallback) {
   return fallback;
 }
 function interpolate(template, variables) {
-  if (!variables || Object.keys(variables).length === 0) {
+  if (!variables) {
     return template;
   }
   return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
     const value = variables[key];
-    return value !== void 0 ? String(value) : match;
+    return value === void 0 ? match : String(value);
   });
 }
 var ThemeTextContext = react$1.createContext(null);
@@ -501,6 +501,13 @@ function usePixel(context) {
   }, []);
 }
 var WeaverseHydrogenItem = class extends react.WeaverseItemStore {
+  /**
+   * Cached merged snapshot (base + translations).
+   * Reset to `null` whenever `_store` or the item's translation entry changes.
+   */
+  _cachedSnapshot = null;
+  _snapshotStoreRef = null;
+  _snapshotTranslationRef = null;
   constructor(initialData, weaverse) {
     super(initialData, weaverse);
     const { data, ...rest } = initialData;
@@ -514,6 +521,32 @@ var WeaverseHydrogenItem = class extends react.WeaverseItemStore {
   get Element() {
     return super.Element;
   }
+  /**
+   * 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 = () => {
+    const base = this._store;
+    const translations = this.weaverse.translationMap?.[this._id];
+    if (!translations) {
+      return base;
+    }
+    if (this._cachedSnapshot && this._snapshotStoreRef === base && this._snapshotTranslationRef === translations) {
+      return this._cachedSnapshot;
+    }
+    const merged = { ...base };
+    for (const [key, entry] of Object.entries(translations)) {
+      if (entry.translatedValue !== void 0) {
+        merged[key] = entry.translatedValue;
+      }
+    }
+    this._cachedSnapshot = merged;
+    this._snapshotStoreRef = base;
+    this._snapshotTranslationRef = translations;
+    return merged;
+  };
 };
 react.Weaverse.ItemConstructor = WeaverseHydrogenItem;
 var WeaverseHydrogen = class extends react.Weaverse {
@@ -529,8 +562,16 @@ var WeaverseHydrogen = class extends react.Weaverse {
   isPreviewMode;
   isRevisionPreview;
   sectionType;
-  static itemInstances;
-  static elementRegistry;
+  // ─── Translation sidecar (design mode only) ────────────────────────
+  /**
+   * 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 = {};
+  translationLocale = "";
+  translationLanguageId = "";
   constructor(params) {
     const { internal, pageId, requestInfo, ...coreParams } = params;
     super({ ...coreParams });
@@ -546,7 +587,82 @@ var WeaverseHydrogen = class extends react.Weaverse {
     this.isPreviewMode = params.isPreviewMode ?? false;
     this.isRevisionPreview = params.isRevisionPreview ?? false;
     this.sectionType = params.sectionType || "";
+    this.extractTranslationSidecar();
   }
+  /**
+   * 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 = () => {
+    const pageData = this.data;
+    if (pageData?.translationMap) {
+      this.translationMap = pageData.translationMap;
+      this.translationLocale = pageData.translationLocale || "";
+      this.translationLanguageId = pageData.translationLanguageId || "";
+    }
+  };
+  /**
+   * 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, locale, languageId) => {
+    this.translationMap = translationMap;
+    this.translationLocale = locale;
+    this.translationLanguageId = languageId;
+    this.refreshAllItems();
+  };
+  /**
+   * Update a single translation entry for a specific item field.
+   * Used by the studio bridge when the user edits a translatable field.
+   */
+  updateTranslation = (itemId, key, originalValue, translatedValue) => {
+    if (!this.translationMap[itemId]) {
+      this.translationMap[itemId] = {};
+    }
+    this.translationMap[itemId] = {
+      ...this.translationMap[itemId],
+      [key]: { originalValue, translatedValue }
+    };
+    const instance = this.itemInstances.get(itemId);
+    if (instance) {
+      instance.triggerUpdate();
+    }
+  };
+  /**
+   * Collect all translation changes across all weaverse instances.
+   * Used by the save flow to persist translation edits.
+   */
+  getTranslationChanges = () => {
+    const entries = [];
+    const languageId = this.translationLanguageId;
+    if (!(this.translationLocale && languageId)) {
+      return void 0;
+    }
+    for (const [itemId, fields] of Object.entries(this.translationMap)) {
+      for (const [key, entry] of Object.entries(fields)) {
+        entries.push({
+          itemId,
+          key: `data.${key}`,
+          originalValue: entry.originalValue,
+          translatedValue: entry.translatedValue
+        });
+      }
+    }
+    if (entries.length === 0) {
+      return void 0;
+    }
+    return { languageId, entries };
+  };
+  /**
+   * Override setProjectData to re-extract translation sidecar from new page data.
+   */
+  setProjectData = (data) => {
+    this.data = data;
+    this.extractTranslationSidecar();
+    this.initProject();
+  };
 };
 function createWeaverseInstance(params) {
   if (react.isBrowser) {
@@ -1097,7 +1213,7 @@ var WeaverseClient = class {
             type: typeof result,
             isString: typeof result === "string",
             length: typeof result === "string" ? result.length : "N/A",
-            preview: typeof result === "string" ? `${result.substring(0, 50)}...` : String(result)
+            preview: typeof result === "string" ? `${result.slice(0, 50)}...` : String(result)
           }
         );
         result = { theme: defaultThemeSettings };