@weaverse/next 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/types/studio-router.d.ts

@@ -0,0 +1,50 @@
+import type { WeaverseNextRuntimeInternal } from './types';
+/**
+ * Minimal structural shape of the Next App Router returned by `useRouter()`
+ * (`next/navigation`) that the Studio bridge needs. Declared locally — rather
+ * than importing `AppRouterInstance` from `next` — so the adapter stays a pure
+ * function that unit tests can drive with a plain mock and never pulls
+ * `next/navigation` into the test graph.
+ */
+export interface WeaverseNextRouterLike {
+    /** Add a route to browser history. */
+    push: (href: string, options?: {
+        /** Whether to scroll to the top after navigation. */
+        scroll?: boolean;
+    }) => void;
+    /** Refresh the current App Router route and server data. */
+    refresh: () => void;
+    /** Replace the current browser-history entry. */
+    replace: (href: string, options?: {
+        /** Whether to scroll to the top after navigation. */
+        scroll?: boolean;
+    }) => void;
+}
+/** Resolved Studio navigation/revalidation callbacks for a Next runtime. */
+export interface WeaverseNextStudioInternals {
+    /** Navigate Studio's preview with React Router-compatible options. */
+    navigate: NonNullable<WeaverseNextRuntimeInternal['navigate']>;
+    /** Refresh the current App Router route. */
+    revalidate: NonNullable<WeaverseNextRuntimeInternal['revalidate']>;
+}
+/** Controls how Studio navigation maps to the Next App Router. */
+export interface CreateWeaverseNextStudioInternalsOptions {
+    /** Use `router.replace` instead of `router.push` for navigation. */
+    replace?: boolean;
+}
+/**
+ * Build Studio `navigate` / `revalidate` callbacks from a Next App Router.
+ *
+ * Maps Hydrogen's React Router semantics onto Next App Router:
+ * - `navigate(to, { preventScrollReset })` → `router.push(to, { scroll })`,
+ *   where `scroll` is the inverse of `preventScrollReset`. Studio passes
+ *   `preventScrollReset` for in-place edits so the preview viewport is kept,
+ *   matching React Router's `navigate({ preventScrollReset })`.
+ * - `revalidate()` → `router.refresh()`, the App Router's loader-backed refresh
+ *   and the closest equivalent to React Router's `useRevalidator`.
+ *
+ * Pure (no React, no `next/navigation`) so it is unit-testable with a mock
+ * router; the {@link WeaverseNextRouterLike} contract is the only coupling.
+ */
+export declare function createWeaverseNextStudioInternals(router: WeaverseNextRouterLike, options?: CreateWeaverseNextStudioInternalsOptions): WeaverseNextStudioInternals;
+//# sourceMappingURL=studio-router.d.ts.map

package/dist/types/studio-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-router.d.ts","sourceRoot":"","sources":["../../src/studio-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,sCAAsC;IACtC,IAAI,EAAE,CACJ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,qDAAqD;QACrD,MAAM,CAAC,EAAE,OAAO,CAAA;KACjB,KACE,IAAI,CAAA;IACT,4DAA4D;IAC5D,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,iDAAiD;IACjD,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,qDAAqD;QACrD,MAAM,CAAC,EAAE,OAAO,CAAA;KACjB,KACE,IAAI,CAAA;CACV;AAED,4EAA4E;AAC5E,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,EAAE,WAAW,CAAC,2BAA2B,CAAC,UAAU,CAAC,CAAC,CAAA;IAC9D,4CAA4C;IAC5C,UAAU,EAAE,WAAW,CAAC,2BAA2B,CAAC,YAAY,CAAC,CAAC,CAAA;CACnE;AAED,kEAAkE;AAClE,MAAM,WAAW,wCAAwC;IACvD,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,wCAA6C,GACrD,2BAA2B,CAc7B"}

package/dist/types/studio-script-src.d.ts

@@ -0,0 +1,12 @@
+import type { WeaverseNextRequestContext } from './types';
+/** Trust context used when resolving a Studio bridge script URL. */
+export interface ResolveWeaverseNextStudioScriptSrcOptions {
+    /** Storefront hostname; required to permit loopback Studio origins. */
+    storefrontHostname?: string;
+}
+/**
+ * Resolve the Studio script URL from request/search context. `@weaverse/next`
+ * uses the dedicated Next bridge path served by Builder.
+ */
+export declare function resolveWeaverseNextStudioScriptSrc(context?: WeaverseNextRequestContext, options?: ResolveWeaverseNextStudioScriptSrcOptions): string | null;
+//# sourceMappingURL=studio-script-src.d.ts.map

package/dist/types/studio-script-src.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-script-src.d.ts","sourceRoot":"","sources":["../../src/studio-script-src.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AAmFzD,oEAAoE;AACpE,MAAM,WAAW,yCAAyC;IACxD,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,CAAC,EAAE,0BAA0B,EACpC,OAAO,GAAE,yCAA8C,GACtD,MAAM,GAAG,IAAI,CA+Bf"}

package/dist/types/theme-settings-store.d.ts

@@ -0,0 +1,17 @@
+import type { WeaverseNextThemeSchema, WeaverseNextThemeSettingsStore } from './types';
+/** Initial values for a root-scoped theme-settings store. */
+export interface CreateWeaverseNextThemeSettingsStoreOptions {
+    /** Public environment values exposed alongside the store. */
+    publicEnv?: Record<string, string | undefined>;
+    /** Theme schema associated with the settings. */
+    schema?: WeaverseNextThemeSchema;
+    /** Initial setting values. */
+    settings?: Record<string, unknown>;
+}
+/**
+ * Small external store shape compatible with the Studio bridge and React's
+ * `useSyncExternalStore` contract. The bridge calls `updateThemeSettings` during
+ * live theme edits, so keep that method name stable.
+ */
+export declare function createWeaverseNextThemeSettingsStore(options?: CreateWeaverseNextThemeSettingsStoreOptions): WeaverseNextThemeSettingsStore;
+//# sourceMappingURL=theme-settings-store.d.ts.map

package/dist/types/theme-settings-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-settings-store.d.ts","sourceRoot":"","sources":["../../src/theme-settings-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,SAAS,CAAA;AAEhB,6DAA6D;AAC7D,MAAM,WAAW,2CAA2C;IAC1D,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC9C,iDAAiD;IACjD,MAAM,CAAC,EAAE,uBAAuB,CAAA;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,GAAE,2CAAgD,GACxD,8BAA8B,CAuBhC"}

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

@@ -0,0 +1,156 @@
+import { type ReactNode } from 'react';
+import type { TranslationStore } from './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 and live override stores exposed by `useTranslation`. */
+export 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;
+    /**
+     * Legacy name for the live design-mode translation store.
+     *
+     * @deprecated Migrate to {@link TranslationValue.translationStore}. This
+     * alias points at the same store instance.
+     */
+    themeTextStore: TranslationStore | null;
+    /** Exposed so the runtime/Studio bridge can attach it to `internal`. */
+    translationStore: TranslationStore | null;
+}
+/** Sources and content rendered by {@link TranslationProvider}. */
+export interface TranslationProviderProps {
+    /** React subtree that can call `useTranslation`. */
+    children: ReactNode;
+    /** Active-locale static-text overrides loaded from Weaverse. */
+    merchantOverrides?: Record<string, unknown>;
+    /** Default-locale static content from the theme schema. */
+    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;
+    /**
+     * Legacy prop name for the live translation store.
+     *
+     * @deprecated Migrate to {@link TranslationProviderProps.translationStore}.
+     * 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;
+}
+/** Translation sources accepted by {@link createTranslate}. */
+export interface CreateTranslateSources {
+    /** Unsaved live overrides received from Builder design mode. */
+    designOverrides?: Record<string, string>;
+    /** Host application's highest-priority translation function. */
+    externalT?: TranslateFunction;
+    /** Active-locale static-text overrides loaded from Weaverse. */
+    merchantOverrides?: Record<string, unknown>;
+    /** Default-locale static content from the theme schema. */
+    staticContent: Record<string, unknown>;
+}
+/**
+ * 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: CreateTranslateSources): 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 `WeaverseNextRootProvider` or
+ * `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   let { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+export declare function useTranslation(): TranslationValue;
+/**
+ * Legacy name for {@link TranslationProvider}.
+ *
+ * @deprecated Replace `ThemeTextProvider` with {@link TranslationProvider};
+ * the props and runtime behavior are unchanged.
+ */
+export declare const ThemeTextProvider: typeof TranslationProvider;
+/**
+ * Legacy name for {@link useTranslation}.
+ *
+ * @deprecated Replace `useThemeText` with {@link useTranslation}; the return
+ * value is unchanged.
+ */
+export declare const useThemeText: typeof useTranslation;
+/**
+ * Legacy name for {@link TranslationValue}.
+ *
+ * @deprecated Import {@link TranslationValue} instead.
+ */
+export type ThemeTextValue = TranslationValue;
+/**
+ * Legacy name for {@link TranslationProviderProps}.
+ *
+ * @deprecated Import {@link TranslationProviderProps} instead.
+ */
+export type ThemeTextProviderProps = TranslationProviderProps;
+//# sourceMappingURL=translation-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"translation-context.d.ts","sourceRoot":"","sources":["../../src/translation-context.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;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,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACjD;;;;;;;;;;;;;OAaG;IACH,CAAC,EAAE,iBAAiB,CAAA;IACpB;;;;;OAKG;IACH,cAAc,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACvC,wEAAwE;IACxE,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC1C;AAKD,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,QAAQ,EAAE,SAAS,CAAA;IACnB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC;;;;;OAKG;IACH,CAAC,CAAC,EAAE,iBAAiB,CAAA;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACxC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC3C;AAED,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,gEAAgE;IAChE,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,iBAAiB,CA4BnB;AAUD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,aAAa,EACb,iBAAiB,EACjB,CAAC,EAAE,SAAS,EACZ,gBAAgB,EAChB,cAAc,EACd,QAAQ,GACT,EAAE,wBAAwB,2CAgC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CAQjD;AAMD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,4BAAsB,CAAA;AACpD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,uBAAiB,CAAA;AAC1C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAC7C;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAA"}

package/dist/types/translation-store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal mutable store for design-mode static text overrides.
+ *
+ * `useSyncExternalStore`-compatible. Passed into {@link TranslationProvider}
+ * (from `./translation-context`) which subscribes internally and layers
+ * overrides on top of `merchantOverrides`/`staticContent`. The Studio bridge
+ * calls `updateOverrides()` via `runtime.internal.translationStore` (also
+ * exposed as the deprecated `runtime.internal.themeTextStore` alias) so live
+ * static-text edits reach the runtime — identical surface to Hydrogen's store,
+ * so Builder's existing static-text RPC works with `@weaverse/next` unchanged.
+ *
+ * Shape: flat `Record<string, string>` — dot-notation keys map to values
+ * (e.g. "cart.title" → "Shopping Cart").
+ */
+export declare class TranslationStore {
+    /** Current flat translation overrides keyed by dot path. */
+    overrides: Record<string, string>;
+    private readonly listeners;
+    /** Replace every override and notify subscribers. */
+    setOverrides: (overrides: Record<string, string>) => void;
+    /** Merge changed overrides into the current values and notify subscribers. */
+    updateOverrides: (newOverrides: Record<string, string>) => void;
+    /** Return the current client-side override snapshot. */
+    getSnapshot: () => Record<string, string>;
+    /** Return the override snapshot used during server rendering. */
+    getServerSnapshot: () => Record<string, string>;
+    /** Subscribe to override changes and return an unsubscribe function. */
+    subscribe: (callback: () => void) => () => void;
+    private readonly emit;
+}
+/**
+ * Legacy constructor name for {@link TranslationStore}.
+ *
+ * @deprecated Replace `ThemeTextStore` with {@link TranslationStore}; the
+ * store contract and runtime behavior are unchanged.
+ */
+export declare const ThemeTextStore: typeof TranslationStore;
+/**
+ * Legacy type name for {@link TranslationStore}.
+ *
+ * @deprecated Import {@link TranslationStore} instead.
+ */
+export type ThemeTextStore = TranslationStore;
+//# sourceMappingURL=translation-store.d.ts.map

package/dist/types/translation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-store.d.ts","sourceRoot":"","sources":["../../src/translation-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAC3B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAK;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD,qDAAqD;IACrD,YAAY,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAGhD;IAED,8EAA8E;IAC9E,eAAe,GAAI,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAGtD;IAED,wDAAwD;IACxD,WAAW,+BAAuB;IAElC,iEAAiE;IACjE,iBAAiB,+BAAuB;IAExC,wEAAwE;IACxE,SAAS,GAAI,UAAU,MAAM,IAAI,gBAKhC;IAED,OAAO,CAAC,QAAQ,CAAC,IAAI,CAQpB;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,yBAAmB,CAAA;AAC9C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAA"}