@weaverse/hydrogen 5.8.6 → 5.8.8

package/dist/index.d.mts

@@ -57,6 +57,27 @@ declare class WeaverseHydrogen extends Weaverse {
     static elementRegistry: Map<string, HydrogenElement>;
     constructor(params: WeaverseHydrogenParams);
 }
+/**
+ * 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' }
+ *   }
+ * })
+ * ```
+ */
 declare function registerComponent(element: HydrogenElement): void;
 declare const WeaverseHydrogenRoot: React$1.MemoExoticComponent<({ components, errorComponent: ErrorComponent, }: {
     components: HydrogenComponent[];
@@ -64,7 +85,41 @@ declare const WeaverseHydrogenRoot: React$1.MemoExoticComponent<({ components, e
         error: Error | unknown;
     }>;
 }) => react_jsx_runtime.JSX.Element>;
+/**
+ * Higher-order component that wraps your app with Weaverse theme settings context.
+ * Provides theme settings to all child components via React context.
+ *
+ * @param Component - The root component to wrap
+ * @returns Wrapped component with theme settings provider
+ *
+ * @example
+ * ```typescript
+ * import { withWeaverse } from '@weaverse/hydrogen'
+ *
+ * function App() {
+ *   return <div>My App</div>
+ * }
+ *
+ * export default withWeaverse(App)
+ * ```
+ */
 declare function withWeaverse(Component: ComponentType<any>): (props: JSX.IntrinsicAttributes) => 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>
+ * }
+ * ```
+ */
 declare function useThemeSettings<T = HydrogenThemeSettings>(): T;
 
 declare class WeaverseClient {
@@ -169,11 +224,76 @@ declare class WeaverseClient {
      */
     private readonly directFetch;
     private getApiUrl;
+    /**
+     * Fetch data with caching support for both design mode and production.
+     * Uses direct fetch in design mode, Hydrogen's withCache in production.
+     * Automatically includes projectId in cache key for multi-project isolation.
+     *
+     * @param url - The URL to fetch from
+     * @param options - Fetch options including optional cache strategy
+     * @returns Promise resolving to the fetched data
+     *
+     * @example
+     * ```typescript
+     * const data = await weaverse.fetchWithCache<MyData>(
+     *   'https://api.example.com/data',
+     *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
+     * )
+     * ```
+     */
     fetchWithCache: <T = unknown>(url: string, options?: RequestInit & {
         strategy?: CachingStrategy;
     }) => Promise<T>;
+    /**
+     * Load theme settings from Weaverse API with fallback to schema defaults.
+     * Merges remote settings with local theme schema and handles design mode serialization.
+     *
+     * @param strategy - Optional cache strategy override
+     * @returns Promise resolving to theme settings response
+     *
+     * @example
+     * ```typescript
+     * const settings = await weaverse.loadThemeSettings()
+     * const primaryColor = settings.theme.colors?.primary
+     * ```
+     */
     loadThemeSettings: (strategy?: CachingStrategy) => Promise<ThemeSettingsResponse>;
+    /**
+     * Generate fallback page with default structure when page data is unavailable.
+     * Used internally when API returns no page or when page needs default content.
+     *
+     * @param message - Custom message to display in the fallback page
+     * @returns HydrogenPageData with single main component containing the message
+     */
     generateFallbackPage: (message: string) => HydrogenPageData;
+    /**
+     * Load page data from Weaverse API with optional route-level project override.
+     * Fetches page content, executes component loaders, and handles empty items fallback.
+     *
+     * @param params - Optional page loading parameters
+     * @param params.type - Page type (HOME, PAGE, PRODUCT, COLLECTION, etc.)
+     * @param params.handle - Page handle for dynamic routes
+     * @param params.locale - Locale override
+     * @param params.projectId - Route-level project ID override (for multi-project)
+     * @param params.strategy - Custom cache strategy override
+     * @returns Promise resolving to page data or null on error
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const data = await weaverse.loadPage()
+     *
+     * // With page type
+     * const data = await weaverse.loadPage({ type: 'HOME' })
+     *
+     * // Route-level project override
+     * const data = await weaverse.loadPage({
+     *   type: 'PAGE',
+     *   handle: 'about',
+     *   projectId: 'campaign-project-123'
+     * })
+     * ```
+     */
     loadPage: (params?: LoadPageParams) => Promise<WeaverseLoaderData | null>;
     execComponentLoader: (item: HydrogenComponentData) => Promise<HydrogenComponentData>;
 }
@@ -756,6 +876,21 @@ declare function getWeaverseConfigs(request: Request, env: HydrogenEnv): Weavers
 declare function generateDataFromSchema(schema: HydrogenComponentSchema | HydrogenThemeSchema): Record<string, any>;
 declare function getPreviewData(type: string, components: HydrogenComponent[], weaverseHost: string): WeaverseLoaderData;
 
+/**
+ * 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
+ * }
+ * ```
+ */
 declare function getSelectedProductOptions(request: Request): SelectedOptionInput[];
 declare const IMAGES_PLACEHOLDERS: {
     logo_white: string;

package/dist/index.d.ts

@@ -57,6 +57,27 @@ declare class WeaverseHydrogen extends Weaverse {
     static elementRegistry: Map<string, HydrogenElement>;
     constructor(params: WeaverseHydrogenParams);
 }
+/**
+ * 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' }
+ *   }
+ * })
+ * ```
+ */
 declare function registerComponent(element: HydrogenElement): void;
 declare const WeaverseHydrogenRoot: React$1.MemoExoticComponent<({ components, errorComponent: ErrorComponent, }: {
     components: HydrogenComponent[];
@@ -64,7 +85,41 @@ declare const WeaverseHydrogenRoot: React$1.MemoExoticComponent<({ components, e
         error: Error | unknown;
     }>;
 }) => react_jsx_runtime.JSX.Element>;
+/**
+ * Higher-order component that wraps your app with Weaverse theme settings context.
+ * Provides theme settings to all child components via React context.
+ *
+ * @param Component - The root component to wrap
+ * @returns Wrapped component with theme settings provider
+ *
+ * @example
+ * ```typescript
+ * import { withWeaverse } from '@weaverse/hydrogen'
+ *
+ * function App() {
+ *   return <div>My App</div>
+ * }
+ *
+ * export default withWeaverse(App)
+ * ```
+ */
 declare function withWeaverse(Component: ComponentType<any>): (props: JSX.IntrinsicAttributes) => 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>
+ * }
+ * ```
+ */
 declare function useThemeSettings<T = HydrogenThemeSettings>(): T;
 
 declare class WeaverseClient {
@@ -169,11 +224,76 @@ declare class WeaverseClient {
      */
     private readonly directFetch;
     private getApiUrl;
+    /**
+     * Fetch data with caching support for both design mode and production.
+     * Uses direct fetch in design mode, Hydrogen's withCache in production.
+     * Automatically includes projectId in cache key for multi-project isolation.
+     *
+     * @param url - The URL to fetch from
+     * @param options - Fetch options including optional cache strategy
+     * @returns Promise resolving to the fetched data
+     *
+     * @example
+     * ```typescript
+     * const data = await weaverse.fetchWithCache<MyData>(
+     *   'https://api.example.com/data',
+     *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
+     * )
+     * ```
+     */
     fetchWithCache: <T = unknown>(url: string, options?: RequestInit & {
         strategy?: CachingStrategy;
     }) => Promise<T>;
+    /**
+     * Load theme settings from Weaverse API with fallback to schema defaults.
+     * Merges remote settings with local theme schema and handles design mode serialization.
+     *
+     * @param strategy - Optional cache strategy override
+     * @returns Promise resolving to theme settings response
+     *
+     * @example
+     * ```typescript
+     * const settings = await weaverse.loadThemeSettings()
+     * const primaryColor = settings.theme.colors?.primary
+     * ```
+     */
     loadThemeSettings: (strategy?: CachingStrategy) => Promise<ThemeSettingsResponse>;
+    /**
+     * Generate fallback page with default structure when page data is unavailable.
+     * Used internally when API returns no page or when page needs default content.
+     *
+     * @param message - Custom message to display in the fallback page
+     * @returns HydrogenPageData with single main component containing the message
+     */
     generateFallbackPage: (message: string) => HydrogenPageData;
+    /**
+     * Load page data from Weaverse API with optional route-level project override.
+     * Fetches page content, executes component loaders, and handles empty items fallback.
+     *
+     * @param params - Optional page loading parameters
+     * @param params.type - Page type (HOME, PAGE, PRODUCT, COLLECTION, etc.)
+     * @param params.handle - Page handle for dynamic routes
+     * @param params.locale - Locale override
+     * @param params.projectId - Route-level project ID override (for multi-project)
+     * @param params.strategy - Custom cache strategy override
+     * @returns Promise resolving to page data or null on error
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const data = await weaverse.loadPage()
+     *
+     * // With page type
+     * const data = await weaverse.loadPage({ type: 'HOME' })
+     *
+     * // Route-level project override
+     * const data = await weaverse.loadPage({
+     *   type: 'PAGE',
+     *   handle: 'about',
+     *   projectId: 'campaign-project-123'
+     * })
+     * ```
+     */
     loadPage: (params?: LoadPageParams) => Promise<WeaverseLoaderData | null>;
     execComponentLoader: (item: HydrogenComponentData) => Promise<HydrogenComponentData>;
 }
@@ -756,6 +876,21 @@ declare function getWeaverseConfigs(request: Request, env: HydrogenEnv): Weavers
 declare function generateDataFromSchema(schema: HydrogenComponentSchema | HydrogenThemeSchema): Record<string, any>;
 declare function getPreviewData(type: string, components: HydrogenComponent[], weaverseHost: string): WeaverseLoaderData;
 
+/**
+ * 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
+ * }
+ * ```
+ */
 declare function getSelectedProductOptions(request: Request): SelectedOptionInput[];
 declare const IMAGES_PLACEHOLDERS: {
     logo_white: string;

package/dist/index.js

@@ -914,6 +914,23 @@ var WeaverseClient = class {
     }
     return `${weaverseHost}/api/public/${endpoint}`;
   }
+  /**
+   * Fetch data with caching support for both design mode and production.
+   * Uses direct fetch in design mode, Hydrogen's withCache in production.
+   * Automatically includes projectId in cache key for multi-project isolation.
+   *
+   * @param url - The URL to fetch from
+   * @param options - Fetch options including optional cache strategy
+   * @returns Promise resolving to the fetched data
+   *
+   * @example
+   * ```typescript
+   * const data = await weaverse.fetchWithCache<MyData>(
+   *   'https://api.example.com/data',
+   *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
+   * )
+   * ```
+   */
   fetchWithCache = async (url, options = {}) => {
     const strategy = options.strategy || hydrogen.CacheCustom(DEFAULT_CACHE_STRATEGY);
     const cacheKey = [
@@ -938,6 +955,19 @@ var WeaverseClient = class {
     }
     return result.data;
   };
+  /**
+   * Load theme settings from Weaverse API with fallback to schema defaults.
+   * Merges remote settings with local theme schema and handles design mode serialization.
+   *
+   * @param strategy - Optional cache strategy override
+   * @returns Promise resolving to theme settings response
+   *
+   * @example
+   * ```typescript
+   * const settings = await weaverse.loadThemeSettings()
+   * const primaryColor = settings.theme.colors?.primary
+   * ```
+   */
   loadThemeSettings = async (strategy) => {
     const defaultThemeSettings = generateDataFromSchema(this.themeSchema);
     try {
@@ -1013,6 +1043,13 @@ var WeaverseClient = class {
       };
     }
   };
+  /**
+   * Generate fallback page with default structure when page data is unavailable.
+   * Used internally when API returns no page or when page needs default content.
+   *
+   * @param message - Custom message to display in the fallback page
+   * @returns HydrogenPageData with single main component containing the message
+   */
   generateFallbackPage = (message) => {
     const rootId = crypto.randomUUID();
     return {
@@ -1028,6 +1065,34 @@ var WeaverseClient = class {
       ]
     };
   };
+  /**
+   * Load page data from Weaverse API with optional route-level project override.
+   * Fetches page content, executes component loaders, and handles empty items fallback.
+   *
+   * @param params - Optional page loading parameters
+   * @param params.type - Page type (HOME, PAGE, PRODUCT, COLLECTION, etc.)
+   * @param params.handle - Page handle for dynamic routes
+   * @param params.locale - Locale override
+   * @param params.projectId - Route-level project ID override (for multi-project)
+   * @param params.strategy - Custom cache strategy override
+   * @returns Promise resolving to page data or null on error
+   *
+   * @example
+   * ```typescript
+   * // Basic usage
+   * const data = await weaverse.loadPage()
+   *
+   * // With page type
+   * const data = await weaverse.loadPage({ type: 'HOME' })
+   *
+   * // Route-level project override
+   * const data = await weaverse.loadPage({
+   *   type: 'PAGE',
+   *   handle: 'about',
+   *   projectId: 'campaign-project-123'
+   * })
+   * ```
+   */
   loadPage = async (params = {}) => {
     try {
       const { request, storefront, basePageRequestBody, basePageConfigs } = this;
@@ -1112,6 +1177,13 @@ var WeaverseClient = class {
       if (!page) {
         page = this.generateFallbackPage("Please add new section to start.");
       }
+      if (page?.items?.length === 0) {
+        page.items.push({
+          type: "main",
+          id: page.rootId || crypto.randomUUID(),
+          data: {}
+        });
+      }
       if (page?.items) {
         const items = page.items;
         page.items = await Promise.all(items.map(this.execComponentLoader));