@weaverse/hydrogen 5.17.1 → 5.18.0

package/dist/types/WeaverseHydrogenRoot.d.ts

@@ -0,0 +1,218 @@
+import type { ElementData } from '@weaverse/react';
+import { Weaverse, WeaverseItemStore } from '@weaverse/react';
+import { type ComponentType, type JSX } from 'react';
+import { type TranslateFunction } from './hooks/translation-context';
+import type { HydrogenComponentData, HydrogenElement, HydrogenPageData, HydrogenThemeSettings, TranslationChanges, TranslationMap, WeaverseInternal, WeaverseLoaderRequestInfo } from './index';
+import type { HydrogenComponent, WeaverseHydrogenParams } from './types';
+import { type WeaverseDataValue } from './utils/pick-weaverse-data';
+/** Runtime store for one rendered Hydrogen component instance. */
+export declare class WeaverseHydrogenItem extends WeaverseItemStore {
+    /** Owning Hydrogen runtime instance. */
+    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;
+    /** Creates an item store from serialized component data and its owner. */
+    constructor(initialData: HydrogenComponentData, weaverse: WeaverseHydrogen);
+    /** Registered component definition for this item's type. */
+    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;
+}
+/**
+ * Hydrogen-specific Weaverse runtime that owns page data, component stores,
+ * Studio state, and translation sidecars for one rendered page.
+ */
+export declare class WeaverseHydrogen extends Weaverse {
+    /** Identifier of the rendered page. */
+    pageId: string;
+    /** Runtime services and project metadata exposed to integrations. */
+    internal: Partial<WeaverseInternal>;
+    /** Normalized URL and locale information for the current request. */
+    requestInfo: WeaverseLoaderRequestInfo;
+    /** Identifier of the project supplying the page. */
+    projectId: string;
+    /** Origin used for Studio assets and editor communication. */
+    weaverseHost: string;
+    /** Base URL used for public content API requests. */
+    weaverseApiBase: string;
+    /**
+     * API key read from environment/configuration for storefront requests or
+     * supplied by Studio requests while editing and previewing.
+     */
+    weaverseApiKey: string;
+    /** Studio asset version supplied by the preview request. */
+    weaverseVersion: string;
+    /** Whether the page is running inside the visual editor. */
+    isDesignMode: boolean;
+    /** Whether a single component preview is being rendered. */
+    isPreviewMode: boolean;
+    /** Whether a saved page revision is being previewed. */
+    isRevisionPreview: boolean;
+    /** Component type requested by section preview mode. */
+    sectionType: string;
+    /** Component item store constructor used by the core runtime. */
+    ItemConstructor: typeof WeaverseHydrogenItem;
+    /** Current page content owned by the runtime. */
+    data: HydrogenPageData;
+    /** Component item stores indexed by instance ID. */
+    static itemInstances: Map<string, WeaverseHydrogenItem>;
+    /** Registered component definitions indexed by component type. */
+    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;
+    /** Locale code for the active translation sidecar. */
+    translationLocale: string;
+    /** Builder language identifier for the active translation sidecar. */
+    translationLanguageId: string;
+    /** Creates a page runtime from resolved loader data and request settings. */
+    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.
+ * Must be called before rendering components in WeaverseHydrogenRoot.
+ *
+ * @param element - Component configuration with schema, Component, and optional loader
+ *
+ * @example
+ * ```typescript
+ * import Hero from './sections/Hero'
+ * import { schema } from './sections/Hero'
+ *
+ * registerComponent({
+ *   type: 'hero',
+ *   Component: Hero,
+ *   schema,
+ *   loader: async ({ data, weaverse }) => {
+ *     return { someData: 'value' }
+ *   }
+ * })
+ * ```
+ */
+export declare function registerComponent(element: HydrogenElement): void;
+/** Props passed to a custom Weaverse page error component. */
+export interface WeaverseHydrogenRootErrorProps {
+    /** Error raised while resolving or rendering the Weaverse page. */
+    error: Error | unknown;
+}
+/** Props accepted by {@link WeaverseHydrogenRoot}. */
+export interface WeaverseHydrogenRootProps {
+    /** Theme components available to the page renderer. */
+    components: HydrogenComponent[];
+    /**
+     * Optional explicit `weaverseData` payload. When provided, bypasses the
+     * automatic route-scoped resolution. Accepts a resolved value, a
+     * `Promise` (handled via `<Await>`), or `null` to suppress rendering.
+     *
+     * Recommended for nested layout + child route compositions where two
+     * `<WeaverseHydrogenRoot>` instances need to render different Weaverse
+     * pages on the same URL. See issue #451.
+     */
+    data?: WeaverseDataValue;
+    /** Component rendered when page data cannot be resolved or awaited. */
+    errorComponent?: React.FC<WeaverseHydrogenRootErrorProps>;
+}
+/**
+ * Renders the Weaverse page for the current React Router route.
+ *
+ * Pass `data` to override automatic route-loader resolution. A promise is
+ * handled with React Router's `Await`, while explicit `null` suppresses output.
+ */
+export declare const WeaverseHydrogenRoot: import("react").MemoExoticComponent<({ components, data: dataProp, errorComponent: ErrorComponent, }: WeaverseHydrogenRootProps) => import("react/jsx-runtime").JSX.Element | null>;
+/**
+ * Options for the `withWeaverse` HOC.
+ */
+export type WithWeaverseOptions = {
+    /**
+     * Optional external translation function (e.g. from Shopify i18n).
+     * When provided it becomes the **highest-priority** source
+     * in the `t()` resolution chain exposed by `useTranslation()`.
+     */
+    t?: TranslateFunction;
+};
+/**
+ * Higher-order component that wraps your app with Weaverse theme settings and
+ * translation context, and mounts the Studio connect bridge.
+ *
+ * Export the result as your root route's **`Layout`** (not the default route
+ * `Component`). In React Router the root `Layout` wraps both the matched route
+ * and its `ErrorBoundary`, so the Studio bridge keeps rendering on 404s and
+ * loader/render errors — exactly the pages where Studio must still answer its
+ * handshake instead of reporting a false "Connection lost". A default-component
+ * wrapper (`export default withWeaverse(App)`) is replaced by the error
+ * boundary on those routes and would drop the bridge.
+ *
+ * @param Component - The root layout component to wrap
+ * @param options   - Optional configuration (e.g. an external `t` function)
+ * @returns Wrapped component with theme settings + translation providers
+ *
+ * @example
+ * ```typescript
+ * import { withWeaverse } from '@weaverse/hydrogen'
+ *
+ * // Basic usage — export as the root route Layout
+ * export const Layout = withWeaverse(RootLayout)
+ *
+ * // With an external translation function
+ * export const Layout = withWeaverse(RootLayout, { t: myI18nFunction })
+ * ```
+ */
+export declare function withWeaverse(Component: ComponentType<any>, options?: WithWeaverseOptions): (props: JSX.IntrinsicAttributes) => import("react/jsx-runtime").JSX.Element;
+/**
+ * React hook to access Weaverse theme settings from anywhere in your component tree.
+ * Must be used within a component wrapped by `withWeaverse` or inside `WeaverseHydrogenRoot`.
+ *
+ * @returns Current theme settings object
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const theme = useThemeSettings()
+ *   const primaryColor = theme.colors?.primary
+ *
+ *   return <div style={{ color: primaryColor }}>Styled content</div>
+ * }
+ * ```
+ */
+export declare function useThemeSettings<T = HydrogenThemeSettings>(): T;
+//# sourceMappingURL=WeaverseHydrogenRoot.d.ts.map

package/dist/types/WeaverseHydrogenRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeaverseHydrogenRoot.d.ts","sourceRoot":"","sources":["../../src/WeaverseHydrogenRoot.tsx"],"names":[],"mappings":"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"}

package/dist/types/components/index.d.ts

@@ -0,0 +1,4 @@
+import type { HydrogenComponent } from '../types';
+/** Built-in components required to render the root of every Weaverse page. */
+export declare let defaultComponents: HydrogenComponent[];
+//# sourceMappingURL=index.d.ts.map

package/dist/types/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAGjD,8EAA8E;AAC9E,eAAO,IAAI,iBAAiB,EAAE,iBAAiB,EAK9C,CAAA"}

package/dist/types/components/main.d.ts

@@ -0,0 +1,7 @@
+import { type SchemaType } from '@weaverse/schema';
+import type { HTMLAttributes } from 'react';
+import type { HydrogenComponentProps } from '../types';
+declare function Main(props: HydrogenComponentProps & HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+export default Main;
+export declare let schema: SchemaType;
+//# sourceMappingURL=main.d.ts.map

package/dist/types/components/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/components/main.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAMtD,iBAAS,IAAI,CAAC,KAAK,EAAE,sBAAsB,GAAG,cAAc,CAAC,cAAc,CAAC,2CAY3E;AAED,eAAe,IAAI,CAAA;AAEnB,eAAO,IAAI,MAAM,EAAE,UAGjB,CAAA"}

package/dist/types/hooks/theme-text-context.d.ts

@@ -0,0 +1,2 @@
+export { createTranslate, getNestedKey, interpolate, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, TranslationProvider, type TranslationProviderProps, type TranslationValue, useThemeText, useTranslation, } from './translation-context';
+//# sourceMappingURL=theme-text-context.d.ts.map

package/dist/types/hooks/theme-text-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-text-context.d.ts","sourceRoot":"","sources":["../../../src/hooks/theme-text-context.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,YAAY,EACZ,cAAc,GACf,MAAM,uBAAuB,CAAA"}

package/dist/types/hooks/translation-context.d.ts

@@ -0,0 +1,138 @@
+import { type ReactNode } from 'react';
+import type { TranslationStore } from '../utils/translation-store';
+/**
+ * Traverse a nested object by dot-path.
+ *
+ * @example
+ * getNestedKey({ cart: { title: 'Cart' } }, 'cart.title') // => 'Cart'
+ * getNestedKey({}, 'cart.title', 'fallback')              // => 'fallback'
+ */
+export 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'
+ */
+export declare function interpolate(template: string, variables?: Record<string, string | number>): string;
+/**
+ * Signature for a translation function.
+ */
+export type TranslateFunction = (key: string, variables?: Record<string, string | number>) => string;
+/** Translation function, stores, and locale overrides exposed by the provider. */
+export type TranslationValue = {
+    /**
+     * Translate a key with optional variable interpolation.
+     *
+     * Priority chain (highest wins):
+     * 1. External `t`        (passed into `withWeaverse` / `TranslationProvider`)
+     * 2. `merchantOverrides` (DB overrides for the current locale + design overrides)
+     * 3. `staticContent`     (theme default JSON)
+     * 4. The key itself      (fallback)
+     *
+     * @example
+     * t('cart.title')                           // => "Cart"
+     * t('badge.sale', { percentage: 15 })       // => "-15% Off"
+     */
+    t: TranslateFunction;
+    /** Exposed for useStudio to attach to weaverse.internal. Null in production. */
+    translationStore: TranslationStore | null;
+    /**
+     * @deprecated Use {@link TranslationValue.translationStore} instead. Kept as a
+     * backward-compatible alias pointing at the same store instance.
+     */
+    themeTextStore: TranslationStore | null;
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
+};
+/** Inputs accepted by {@link TranslationProvider}. */
+export type TranslationProviderProps = {
+    /** Theme-provided default-locale translation content. */
+    staticContent: Record<string, unknown>;
+    /** Active-locale translations published by the merchant. */
+    merchantOverrides?: 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;
+    /** Optional store for live design-mode text overrides from the builder. */
+    translationStore?: TranslationStore | null;
+    /**
+     * @deprecated Use {@link TranslationProviderProps.translationStore} instead.
+     * Still accepted for backward compatibility; ignored when `translationStore`
+     * is also provided.
+     */
+    themeTextStore?: TranslationStore | null;
+    /** React content that can consume the translation context. */
+    children: ReactNode;
+};
+/**
+ * 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`.
+ */
+export 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)
+ */
+export declare function TranslationProvider({ staticContent, merchantOverrides, t: externalT, translationStore, themeTextStore, children, }: TranslationProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the translation `t()` function.
+ *
+ * Must be used inside a component wrapped by `withWeaverse` or `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   const { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+export declare function useTranslation(): TranslationValue;
+/**
+ * Legacy name for {@link TranslationProvider}.
+ * @deprecated Use {@link TranslationProvider} instead.
+ */
+export declare const ThemeTextProvider: typeof TranslationProvider;
+/**
+ * Legacy name for {@link useTranslation}.
+ * @deprecated Use {@link useTranslation} instead.
+ */
+export declare const useThemeText: typeof useTranslation;
+/**
+ * Legacy name for {@link TranslationValue}.
+ * @deprecated Use {@link TranslationValue} instead.
+ */
+export type ThemeTextValue = TranslationValue;
+/**
+ * Legacy name for {@link TranslationProviderProps}.
+ * @deprecated Use {@link TranslationProviderProps} instead.
+ */
+export type ThemeTextProviderProps = TranslationProviderProps;
+//# sourceMappingURL=translation-context.d.ts.map

package/dist/types/hooks/translation-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-context.d.ts","sourceRoot":"","sources":["../../../src/hooks/translation-context.tsx"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAElE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAgBpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAC1C,MAAM,CASR;AAMD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KACxC,MAAM,CAAA;AAEX,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;;;;;;;OAYG;IACH,CAAC,EAAE,iBAAiB,CAAA;IACpB,gFAAgF;IAChF,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACzC;;;OAGG;IACH,cAAc,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACvC,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAClD,CAAA;AAKD,sDAAsD;AACtD,MAAM,MAAM,wBAAwB,GAAG;IACrC,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C;;;;;OAKG;IACH,CAAC,CAAC,EAAE,iBAAiB,CAAA;IACrB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC1C;;;;OAIG;IACH,cAAc,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACxC,8DAA8D;IAC9D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B,GAAG,iBAAiB,CA6BpB;AAQD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,aAAa,EACb,iBAAiB,EACjB,CAAC,EAAE,SAAS,EACZ,gBAAgB,EAChB,cAAc,EACd,QAAQ,GACT,EAAE,wBAAwB,2CAgC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CAQjD;AAMD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,4BAAsB,CAAA;AACpD;;;GAGG;AACH,eAAO,MAAM,YAAY,uBAAiB,CAAA;AAC1C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAC7C;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAA"}

package/dist/types/hooks/use-weaverse-data-context.d.ts

@@ -0,0 +1,29 @@
+import { type UIMatch } from 'react-router';
+/** Loader data indexed by React Router's conventional route identifiers. */
+export interface RouteKeyedDataContext {
+    /** Root route loader data, when the root loader returned an object. */
+    root?: Record<string, unknown>;
+    /** Loader data for a non-root route keyed by its route identifier. */
+    [routeKey: `routes/${string}`]: Record<string, unknown>;
+}
+/**
+ * Flat loader-data map keyed by React Router route ID.
+ * Use route IDs such as `root` or `routes/products.$handle` in data bindings.
+ */
+export type WeaverseDataContext = RouteKeyedDataContext & Record<string, unknown>;
+/**
+ * Hook to get flat route-keyed data context from matches
+ * Returns: {root: {...}, "routes/xxx": {...}}
+ * No more useLoaderData dependency - everything comes from matches
+ */
+export declare function useWeaverseDataContext(): WeaverseDataContext;
+/**
+ * Helper function to create flat route-keyed data context from useMatches() result
+ * Returns: {root: {...}, "routes/xxx": {...}}
+ */
+export declare function createWeaverseDataContext(matches: UIMatch<unknown, unknown>[]): WeaverseDataContext;
+/**
+ * Type guard to check if data is WeaverseDataContext (simplified)
+ */
+export declare function isWeaverseDataContext(data: unknown): data is WeaverseDataContext;
+//# sourceMappingURL=use-weaverse-data-context.d.ts.map

package/dist/types/hooks/use-weaverse-data-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-weaverse-data-context.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-weaverse-data-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAc,MAAM,cAAc,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,sEAAsE;IACtE,CAAC,QAAQ,EAAE,UAAU,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACxD;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,GACrD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAuBzB;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,CAK5D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GACnC,mBAAmB,CAGrB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,mBAAmB,CAE7B"}

package/dist/types/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * React and React Router integrations for rendering Weaverse content in
+ * Shopify Hydrogen storefronts.
+ *
+ * @packageDocumentation
+ */
+import type { SelectedOptionInput } from '@shopify/hydrogen/storefront-api-types';
+import { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
+/**
+ * Filter out Weaverse-specific query parameters from product options.
+ * Removes `isDesignMode` and any parameters starting with `weaverse` prefix.
+ *
+ * @param request - The incoming HTTP request
+ * @returns Filtered product options for Shopify Hydrogen
+ *
+ * @example
+ * ```typescript
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const selectedOptions = getSelectedProductOptions(request)
+ *   // Use selectedOptions for product queries without Weaverse params
+ * }
+ * ```
+ */
+export declare function getSelectedProductOptions(request: Request): SelectedOptionInput[];
+/** Placeholder asset URLs for component schema defaults and theme previews. */
+export declare const IMAGES_PLACEHOLDERS: {
+    /** White Weaverse logo placeholder. */
+    logo_white: string;
+    /** Black Weaverse logo placeholder. */
+    logo_black: string;
+    /** Generic square image placeholder. */
+    image: string;
+    /** First landscape banner placeholder. */
+    banner_1: string;
+    /** Second landscape banner placeholder. */
+    banner_2: string;
+    /** Hats collection placeholder. */
+    collection_1: string;
+    /** Shoes collection placeholder. */
+    collection_2: string;
+    /** Glasses collection placeholder. */
+    collection_3: string;
+    /** Lamps collection placeholder. */
+    collection_4: string;
+    /** Bags collection placeholder. */
+    collection_5: string;
+    /** Watches collection placeholder. */
+    collection_6: string;
+    /** Third watch product placeholder. */
+    product_1: string;
+    /** Second bag product placeholder. */
+    product_2: string;
+    /** First shoe product placeholder. */
+    product_3: string;
+    /** Second lamp product placeholder. */
+    product_4: string;
+    /** First glasses product placeholder. */
+    product_5: string;
+    /** First lamp product placeholder. */
+    product_6: string;
+    /** Second glasses product placeholder. */
+    product_7: string;
+    /** Third hat product placeholder. */
+    product_8: string;
+    /** First bag product placeholder. */
+    product_9: string;
+    /** Second shoe product placeholder. */
+    product_10: string;
+    /** Second hat product placeholder. */
+    product_11: string;
+    /** Third glasses product placeholder. */
+    product_12: string;
+    /** Third shoe product placeholder. */
+    product_13: string;
+    /** Third bag product placeholder. */
+    product_14: string;
+    /** First hat product placeholder. */
+    product_15: string;
+    /** Third lamp product placeholder. */
+    product_16: string;
+    /** First watch product placeholder. */
+    product_17: string;
+    /** Second watch product placeholder. */
+    product_18: string;
+};
+export * from '@weaverse/schema';
+export * from './components';
+export { getNestedKey, interpolate, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, TranslationProvider, type TranslationProviderProps, type TranslationValue, useThemeText, useTranslation, } from './hooks/translation-context';
+export { createWeaverseDataContext, type RouteKeyedDataContext, useWeaverseDataContext, type WeaverseDataContext, } from './hooks/use-weaverse-data-context';
+export * from './seo';
+export * from './types';
+export * from './utils';
+export type { WeaverseDataValue } from './utils/pick-weaverse-data';
+export { ThemeTextStore, TranslationStore } from './utils/translation-store';
+export type { ThemeSettingsStore, WeaverseThemeData, } from './utils/use-theme-settings-store';
+export * from './WeaverseHydrogenRoot';
+export * from './weaverse-client';
+export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse, };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAA;AACjF,OAAO,EACL,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GACf,mBAAmB,EAAE,CAKvB;AAED,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB;IAC9B,uCAAuC;;IAGvC,uCAAuC;;IAGvC,wCAAwC;;IAGxC,0CAA0C;;IAG1C,2CAA2C;;IAG3C,mCAAmC;;IAGnC,oCAAoC;;IAGpC,sCAAsC;;IAGtC,oCAAoC;;IAGpC,mCAAmC;;IAGnC,sCAAsC;;IAGtC,uCAAuC;;IAGvC,sCAAsC;;IAGtC,sCAAsC;;IAGtC,uCAAuC;;IAGvC,yCAAyC;;IAGzC,sCAAsC;;IAGtC,0CAA0C;;IAG1C,qCAAqC;;IAGrC,qCAAqC;;IAGrC,uCAAuC;;IAGvC,sCAAsC;;IAGtC,yCAAyC;;IAGzC,sCAAsC;;IAGtC,qCAAqC;;IAGrC,qCAAqC;;IAGrC,sCAAsC;;IAGtC,uCAAuC;;IAGvC,wCAAwC;;CAGzC,CAAA;AAGD,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,OAAO,EACL,YAAY,EACZ,WAAW,EAEX,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EAEtB,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,YAAY,EACZ,cAAc,GACf,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,KAAK,mBAAmB,GACzB,MAAM,mCAAmC,CAAA;AAE1C,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAC5E,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,kCAAkC,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,mBAAmB,CAAA;AAEjC,OAAO,EACL,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,WAAW,GACZ,CAAA"}

package/dist/types/seo.d.ts

@@ -0,0 +1,43 @@
+import type { PageSEOData } from '@weaverse/schema';
+import type { MetaDescriptor } from 'react-router';
+import type { HydrogenPageData, WeaverseLoaderData } from './types';
+/** Object containing an optional Weaverse page for SEO extraction. */
+export interface WeaverseSeoPageContainer {
+    /** Page whose published SEO fields should be formatted. */
+    page?: HydrogenPageData | null;
+}
+/** Input accepted by {@link getWeaverseSeoMeta}. */
+export type WeaverseSeoInput = WeaverseLoaderData | HydrogenPageData | WeaverseSeoPageContainer | null | undefined;
+/**
+ * Convert a Weaverse page-level SEO payload into React Router
+ * `MetaDescriptor[]`. Pure, synchronous, tree-shakeable — does not fetch.
+ *
+ * Behavior:
+ * - `title` → top-level `{ title }` descriptor.
+ * - `description` / `keywords` → `<meta name="...">`.
+ * - `canonicalUrl` → `<link rel="canonical">`.
+ * - `openGraph.*` → `<meta property="og:*">`. `og:type` defaults to
+ *   `'website'` when any other OG field is present.
+ * - `twitter.*` → `<meta name="twitter:*">`. `twitter:card` defaults to
+ *   `'summary'` when any other Twitter field is present.
+ * - `robots` is always emitted (defaults to `'index,follow'`) so themes
+ *   stacking multiple SEO sources have a deterministic last word on
+ *   indexing for Weaverse-managed pages.
+ * - Empty strings / missing fields are filtered before return so empty
+ *   descriptors don't override earlier sources (e.g. Hydrogen
+ *   `getSeoMeta`).
+ */
+export declare function formatMetaDescriptors(seo: PageSEOData | null | undefined): MetaDescriptor[];
+/**
+ * Convenience accessor: pull `page.seo` out of a `WeaverseLoaderData`
+ * (or `HydrogenPageData`) and emit `MetaDescriptor[]`. Null-safe.
+ *
+ * @example
+ * ```ts
+ * export const meta: MetaFunction<typeof loader> = ({ data }) => {
+ *   return getWeaverseSeoMeta(data?.weaverseData)
+ * }
+ * ```
+ */
+export declare function getWeaverseSeoMeta(data: WeaverseSeoInput): MetaDescriptor[];
+//# sourceMappingURL=seo.d.ts.map

package/dist/types/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../../src/seo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEnE,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC/B;AAED,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GACxB,kBAAkB,GAClB,gBAAgB,GAChB,wBAAwB,GACxB,IAAI,GACJ,SAAS,CAAA;AAEb;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAClC,cAAc,EAAE,CA+DlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAS3E"}