@wix/headless-stores 0.0.36 → 0.0.38

package/dist/services/products-list-service.js

@@ -1,102 +1,89 @@
 import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
-import { productsV3 } from "@wix/stores";
-;
+import { productsV3, readOnlyVariantsV3 } from "@wix/stores";
 /**
- * Loads products list service configuration from the Wix Products API for SSR initialization.
+ * Loads products list service configuration from the Wix Stores API for SSR initialization.
  * This function is designed to be used during Server-Side Rendering (SSR) to preload
- * products based on search criteria that will be used to configure the ProductsListService.
+ * a list of products based on search criteria.
  *
- * @param searchOptions Search options for filtering and querying products
- * @returns Promise that resolves to ProductsListServiceConfig with products, metadata, and aggregations
+ * @param {Parameters<typeof productsV3.searchProducts>[0]} searchOptions - The search options for querying products
+ * @returns {Promise<ProductsListServiceConfig>} Promise that resolves to the products list configuration
  *
  * @example
  * ```astro
  * ---
- * // Astro page example - pages/search.astro
+ * // Astro page example - pages/products.astro
  * import { loadProductsListServiceConfig } from '@wix/stores/services';
- * import { ProductsList } from '@wix/stores/components';
- *
- * // Get search query from URL params
- * const searchQuery = Astro.url.searchParams.get('q') || '';
- * const category = Astro.url.searchParams.get('category');
+ * import { ProductList } from '@wix/stores/components';
  *
- * // Build search options
+ * // Define search options
  * const searchOptions = {
- *   query: { search: searchQuery },
- *   filter: category ? { categories: [category] } : undefined,
- *   paging: { limit: 12 }
+ *   cursorPaging: { limit: 12 },
+ *   filter: {},
+ *   sort: [{ fieldName: 'name', order: 'ASC' }]
  * };
  *
- * // Load products during SSR
- * const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ * // Load products data during SSR
+ * const productsConfig = await loadProductsListServiceConfig(searchOptions);
  * ---
  *
- * <ProductsList.Root productsListConfig={productsListConfig}>
- *   <ProductsList.ItemContent>
+ * <ProductList.Root productsConfig={productsConfig}>
+ *   <ProductList.ItemContent>
  *     {({ product }) => (
- *       <div class="product-item">
+ *       <div>
  *         <h3>{product.name}</h3>
+ *         <p>{product.description}</p>
  *       </div>
  *     )}
- *   </ProductsList.ItemContent>
- * </ProductsList.Root>
+ *   </ProductList.ItemContent>
+ * </ProductList.Root>
  * ```
  *
  * @example
  * ```tsx
- * // Next.js page example - pages/search.tsx
+ * // Next.js page example - pages/products.tsx
  * import { GetServerSideProps } from 'next';
  * import { loadProductsListServiceConfig } from '@wix/stores/services';
  * import { ProductsList } from '@wix/stores/components';
  *
- * interface SearchPageProps {
- *   productsListConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
- *   searchQuery: string;
+ * interface ProductsPageProps {
+ *   productsConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
  * }
  *
- * export const getServerSideProps: GetServerSideProps<SearchPageProps> = async ({ query }) => {
- *   const searchQuery = (query.q as string) || '';
- *   const category = query.category as string;
- *
- *   // Build search options
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async () => {
  *   const searchOptions = {
- *     query: { search: searchQuery },
- *     filter: category ? { categories: [category] } : undefined,
- *     paging: { limit: 12 }
+ *     cursorPaging: { limit: 12 },
+ *     filter: {},
+ *     sort: [{ fieldName: 'name', order: 'ASC' }]
  *   };
  *
- *   // Load products during SSR
- *   const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ *   const productsConfig = await loadProductsListServiceConfig(searchOptions);
  *
  *   return {
  *     props: {
- *       productsListConfig,
- *       searchQuery,
+ *       productsConfig,
  *     },
  *   };
  * };
  *
- * export default function SearchPage({ productsListConfig, searchQuery }: SearchPageProps) {
+ * export default function ProductsPage({ productsConfig }: ProductsPageProps) {
  *   return (
- *     <div>
- *       <h1>Search Results for "{searchQuery}"</h1>
- *       <ProductsList.Root productsListConfig={productsListConfig}>
- *         <ProductsList.ItemContent>
- *           {({ product }) => (
- *             <div className="product-item">
- *               <h3>{product.name}</h3>
- *             </div>
- *           )}
- *         </ProductsList.ItemContent>
- *       </ProductsList.Root>
- *     </div>
+ *     <ProductList.Root productsConfig={productsConfig}>
+ *       <ProductList.ItemContent>
+ *         {({ product }) => (
+ *           <div>
+ *             <h3>{product.name}</h3>
+ *             <p>{product.description}</p>
+ *           </div>
+ *         )}
+ *       </ProductList.ItemContent>
+ *     </ProductList.Root>
  *   );
  * }
  * ```
  */
 export async function loadProductsListServiceConfig(searchOptions) {
-    const result = await productsV3.searchProducts(searchOptions);
+    const result = await fetchProducts(searchOptions);
     return {
         products: result.products ?? [],
         searchOptions,
@@ -104,7 +91,151 @@ export async function loadProductsListServiceConfig(searchOptions) {
         aggregations: result.aggregationData,
     };
 }
+/**
+ * Fetches products and their missing variants in one optimized request.
+ * This function wraps the standard searchProducts call and automatically
+ * fetches missing variant data for all products that need it.
+ *
+ * @param searchOptions - The search options for querying products
+ * @returns Promise that resolves to the search result with complete variant data
+ */
+const fetchProducts = async (searchOptions) => {
+    const result = await productsV3.searchProducts(searchOptions);
+    // Fetch missing variants for all products in one batch request
+    if (result.products) {
+        result.products = await fetchMissingVariants(result.products);
+    }
+    return result;
+};
+/**
+ * Fetches missing variants for all products in one batch request.
+ * This function identifies products that need variant data and fetches
+ * all variants efficiently using the readOnlyVariantsV3 API.
+ *
+ * @param products - Array of products that may need variant data
+ * @returns Promise that resolves to products with complete variant information
+ */
+const fetchMissingVariants = async (products) => {
+    // Find products that need variants (both single and multi-variant products)
+    const productsNeedingVariants = products.filter((product) => !product.variantsInfo?.variants &&
+        product.variantSummary?.variantCount &&
+        product.variantSummary.variantCount > 0);
+    if (productsNeedingVariants.length === 0) {
+        return products;
+    }
+    try {
+        const productIds = productsNeedingVariants
+            .map((p) => p._id)
+            .filter(Boolean);
+        if (productIds.length === 0) {
+            return products;
+        }
+        const items = [];
+        const res = await readOnlyVariantsV3
+            .queryVariants({})
+            .in("productData.productId", productIds)
+            .limit(100)
+            .find();
+        items.push(...res.items);
+        let nextRes = res;
+        while (nextRes.hasNext()) {
+            nextRes = await nextRes.next();
+            items.push(...nextRes.items);
+        }
+        const variantsByProductId = new Map();
+        items.forEach((item) => {
+            const productId = item.productData?.productId;
+            if (productId) {
+                if (!variantsByProductId.has(productId)) {
+                    variantsByProductId.set(productId, []);
+                }
+                variantsByProductId.get(productId).push({
+                    ...item,
+                    choices: item.optionChoices,
+                });
+            }
+        });
+        // Update products with their variants
+        return products.map((product) => {
+            const variants = variantsByProductId.get(product._id || "");
+            if (variants && variants.length > 0) {
+                return {
+                    ...product,
+                    variantsInfo: {
+                        ...product.variantsInfo,
+                        variants,
+                    },
+                };
+            }
+            return product;
+        });
+    }
+    catch (error) {
+        console.error("Failed to fetch missing variants:", error);
+        return products;
+    }
+};
+/**
+ * Service definition for the Products List service.
+ * This defines the reactive API contract for managing a list of products with search, pagination, and filtering capabilities.
+ *
+ * @constant
+ */
 export const ProductsListServiceDefinition = defineService("products-list");
+/**
+ * Implementation of the Products List service that manages reactive products data.
+ * This service provides signals for products data, search options, pagination, aggregations,
+ * loading state, and error handling. It automatically re-fetches products when search options change.
+ *
+ * @example
+ * ```tsx
+ * import { ProductListService, ProductsListServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function ProductsComponent({ productsConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListServiceDefinition, ProductListService.withConfig(productsConfig)]
+ *     ])}>
+ *       <ProductsDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function ProductsDisplay() {
+ *   const productsService = useService(ProductsListServiceDefinition);
+ *   const products = productsService.products.get();
+ *   const isLoading = productsService.isLoading.get();
+ *   const error = productsService.error.get();
+ *
+ *   // Update search options to filter by category
+ *   const filterByCategory = (categoryId: string) => {
+ *     const currentOptions = productsService.searchOptions.get();
+ *     productsService.setSearchOptions({
+ *       ...currentOptions,
+ *       filter: {
+ *         ...currentOptions.filter,
+ *         categoryIds: [categoryId]
+ *       }
+ *     });
+ *   };
+ *
+ *   if (isLoading) return <div>Loading products...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {products.map(product => (
+ *         <div key={product._id}>
+ *           <h3>{product.name}</h3>
+ *           <p>{product.description}</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const ProductListService = implementService.withConfig()(ProductsListServiceDefinition, ({ getService, config }) => {
     let firstRun = true;
     const signalsService = getService(SignalsServiceDefinition);
@@ -132,7 +263,7 @@ export const ProductListService = implementService.withConfig()(ProductsListServ
                         },
                     }
                     : searchOptions;
-                const result = await productsV3.searchProducts(affectiveSearchOptions);
+                const result = await fetchProducts(affectiveSearchOptions);
                 productsSignal.set(result.products ?? []);
                 pagingMetadataSignal.set(result.pagingMetadata);
             }

package/dist/services/products-list-sort-service.d.ts

@@ -0,0 +1,117 @@
+import type { Signal } from "@wix/services-definitions/core-services/signals";
+/**
+ * Service definition for the Products List Sort service.
+ * This defines the reactive API contract for managing product list sorting options.
+ *
+ * @constant
+ */
+export declare const ProductsListSortServiceDefinition: string & {
+    __api: {
+        /** Reactive signal containing the currently selected sort option */
+        selectedSortOption: Signal<string>;
+        /** Function to update the selected sort option */
+        setSelectedSortOption: (sort: string) => void;
+        /** Array of available sort types */
+        sortOptions: SortType[];
+    };
+    __config: {};
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the currently selected sort option */
+    selectedSortOption: Signal<string>;
+    /** Function to update the selected sort option */
+    setSelectedSortOption: (sort: string) => void;
+    /** Array of available sort types */
+    sortOptions: SortType[];
+};
+/**
+ * Configuration interface for the Products List Sort service.
+ * Currently empty as this service doesn't require initial configuration.
+ *
+ * @interface ProductsListSortServiceConfig
+ */
+export type ProductsListSortServiceConfig = {};
+/**
+ * Enumeration of available product sort types.
+ * These values correspond to how products can be sorted in the product list.
+ *
+ * @enum {string}
+ */
+export declare enum SortType {
+    /** Sort by newest products first */
+    NEWEST = "newest",
+    /** Sort by product name in ascending order (A-Z) */
+    NAME_ASC = "name_asc",
+    /** Sort by product name in descending order (Z-A) */
+    NAME_DESC = "name_desc",
+    /** Sort by price in ascending order (lowest first) */
+    PRICE_ASC = "price_asc",
+    /** Sort by price in descending order (highest first) */
+    PRICE_DESC = "price_desc",
+    /** Sort by recommended products (algorithm-based) */
+    RECOMMENDED = "recommended"
+}
+/**
+ * Implementation of the Products List Sort service that manages reactive sorting state.
+ * This service provides signals for the current sort option and automatically updates
+ * the products list search options when the sort selection changes.
+ *
+ * @example
+ * ```tsx
+ * import { ProductsListSortService, ProductsListSortServiceDefinition, SortType } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function SortComponent() {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListSortServiceDefinition, ProductsListSortService.withConfig({})]
+ *     ])}>
+ *       <SortSelector />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function SortSelector() {
+ *   const sortService = useService(ProductsListSortServiceDefinition);
+ *   const selectedSort = sortService.selectedSortOption.get();
+ *   const sortOptions = sortService.sortOptions;
+ *
+ *   return (
+ *     <select
+ *       value={selectedSort}
+ *       onChange={(e) => sortService.setSelectedSortOption(e.target.value)}
+ *     >
+ *       {sortOptions.map(option => (
+ *         <option key={option} value={option}>
+ *           {option === SortType.NAME_ASC ? 'Name A-Z' :
+ *            option === SortType.NAME_DESC ? 'Name Z-A' :
+ *            option === SortType.PRICE_ASC ? 'Price Low to High' :
+ *            option === SortType.PRICE_DESC ? 'Price High to Low' :
+ *            option === SortType.NEWEST ? 'Newest First' :
+ *            'Recommended'}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export declare const ProductsListSortService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: {
+        /** Reactive signal containing the currently selected sort option */
+        selectedSortOption: Signal<string>;
+        /** Function to update the selected sort option */
+        setSelectedSortOption: (sort: string) => void;
+        /** Array of available sort types */
+        sortOptions: SortType[];
+    };
+    __config: {};
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the currently selected sort option */
+    selectedSortOption: Signal<string>;
+    /** Function to update the selected sort option */
+    setSelectedSortOption: (sort: string) => void;
+    /** Array of available sort types */
+    sortOptions: SortType[];
+}, ProductsListSortServiceConfig>;

package/dist/services/products-list-sort-service.js

@@ -0,0 +1,144 @@
+import { defineService, implementService } from "@wix/services-definitions";
+import { SignalsServiceDefinition } from "@wix/services-definitions/core-services/signals";
+import { ProductsListServiceDefinition } from "./products-list-service.js";
+import { productsV3 } from "@wix/stores";
+/**
+ * Service definition for the Products List Sort service.
+ * This defines the reactive API contract for managing product list sorting options.
+ *
+ * @constant
+ */
+export const ProductsListSortServiceDefinition = defineService("products-list-sort");
+/**
+ * Enumeration of available product sort types.
+ * These values correspond to how products can be sorted in the product list.
+ *
+ * @enum {string}
+ */
+export var SortType;
+(function (SortType) {
+    /** Sort by newest products first */
+    SortType["NEWEST"] = "newest";
+    /** Sort by product name in ascending order (A-Z) */
+    SortType["NAME_ASC"] = "name_asc";
+    /** Sort by product name in descending order (Z-A) */
+    SortType["NAME_DESC"] = "name_desc";
+    /** Sort by price in ascending order (lowest first) */
+    SortType["PRICE_ASC"] = "price_asc";
+    /** Sort by price in descending order (highest first) */
+    SortType["PRICE_DESC"] = "price_desc";
+    /** Sort by recommended products (algorithm-based) */
+    SortType["RECOMMENDED"] = "recommended";
+})(SortType || (SortType = {}));
+/**
+ * Implementation of the Products List Sort service that manages reactive sorting state.
+ * This service provides signals for the current sort option and automatically updates
+ * the products list search options when the sort selection changes.
+ *
+ * @example
+ * ```tsx
+ * import { ProductsListSortService, ProductsListSortServiceDefinition, SortType } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function SortComponent() {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListSortServiceDefinition, ProductsListSortService.withConfig({})]
+ *     ])}>
+ *       <SortSelector />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function SortSelector() {
+ *   const sortService = useService(ProductsListSortServiceDefinition);
+ *   const selectedSort = sortService.selectedSortOption.get();
+ *   const sortOptions = sortService.sortOptions;
+ *
+ *   return (
+ *     <select
+ *       value={selectedSort}
+ *       onChange={(e) => sortService.setSelectedSortOption(e.target.value)}
+ *     >
+ *       {sortOptions.map(option => (
+ *         <option key={option} value={option}>
+ *           {option === SortType.NAME_ASC ? 'Name A-Z' :
+ *            option === SortType.NAME_DESC ? 'Name Z-A' :
+ *            option === SortType.PRICE_ASC ? 'Price Low to High' :
+ *            option === SortType.PRICE_DESC ? 'Price High to Low' :
+ *            option === SortType.NEWEST ? 'Newest First' :
+ *            'Recommended'}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export const ProductsListSortService = implementService.withConfig()(ProductsListSortServiceDefinition, ({ getService }) => {
+    let firstRun = true;
+    const signalsService = getService(SignalsServiceDefinition);
+    const productsListService = getService(ProductsListServiceDefinition);
+    const selectedSortOptionSignal = signalsService.signal("name");
+    if (typeof window !== "undefined") {
+        signalsService.effect(() => {
+            const sort = selectedSortOptionSignal.get();
+            if (firstRun) {
+                firstRun = false;
+                return;
+            }
+            const newSearchOptions = {
+                ...productsListService.searchOptions.peek(),
+            };
+            if (!newSearchOptions.sort) {
+                newSearchOptions.sort = [];
+            }
+            else {
+                // Copy existing filter to avoid mutation
+                newSearchOptions.sort = [...newSearchOptions.sort];
+            }
+            switch (sort) {
+                case SortType.NAME_ASC:
+                    newSearchOptions.sort = [
+                        { fieldName: "name", order: productsV3.SortDirection.ASC },
+                    ];
+                    break;
+                case SortType.NAME_DESC:
+                    newSearchOptions.sort = [
+                        { fieldName: "name", order: productsV3.SortDirection.DESC },
+                    ];
+                    break;
+                case SortType.PRICE_ASC:
+                    newSearchOptions.sort = [
+                        {
+                            fieldName: "actualPriceRange.minValue.amount",
+                            order: productsV3.SortDirection.ASC,
+                        },
+                    ];
+                    break;
+                case SortType.PRICE_DESC:
+                    newSearchOptions.sort = [
+                        {
+                            fieldName: "actualPriceRange.minValue.amount",
+                            order: productsV3.SortDirection.DESC,
+                        },
+                    ];
+                    break;
+                case SortType.RECOMMENDED:
+                    newSearchOptions.sort = [
+                        {
+                            fieldName: "name",
+                            order: productsV3.SortDirection.DESC,
+                        },
+                    ];
+                    break;
+            }
+            productsListService.setSearchOptions(newSearchOptions);
+        });
+    }
+    return {
+        selectedSortOption: selectedSortOptionSignal,
+        sortOptions: Object.values(SortType),
+        setSelectedSortOption: (sort) => selectedSortOptionSignal.set(sort),
+    };
+});

package/dist/utils/url-params.d.ts

@@ -1,5 +1,73 @@
+/**
+ * Utility class for managing URL parameters in web applications.
+ * Provides methods to parse, update, and retrieve URL search parameters with support for multiple values.
+ *
+ * @class URLParamsUtils
+ */
 export declare class URLParamsUtils {
+    /**
+     * Parses URLSearchParams into a more convenient format that supports multiple values for the same key.
+     * Converts multiple parameters with the same key into an array.
+     *
+     * @static
+     * @param {URLSearchParams} searchParams - The URLSearchParams object to parse
+     * @returns {Record<string, string | string[]>} Object with parameter names as keys and values as strings or arrays
+     *
+     * @example
+     * ```typescript
+     * // URL: ?color=red&color=blue&size=large
+     * const params = new URLSearchParams('color=red&color=blue&size=large');
+     * const parsed = URLParamsUtils.parseSearchParams(params);
+     * // Result: { color: ['red', 'blue'], size: 'large' }
+     * ```
+     */
     static parseSearchParams(searchParams: URLSearchParams): Record<string, string | string[]>;
+    /**
+     * Updates the current page URL with new parameters without causing a page reload.
+     * Supports multiple values for the same parameter key.
+     *
+     * @static
+     * @param {Record<string, string | string[]>} params - Object with parameter names and values to set
+     *
+     * @example
+     * ```typescript
+     * // Update URL with single and multiple values
+     * URLParamsUtils.updateURL({
+     *   category: 'electronics',
+     *   color: ['red', 'blue'],
+     *   price: '100'
+     * });
+     * // URL becomes: ?category=electronics&color=red&color=blue&price=100
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clear all parameters by passing empty object
+     * URLParamsUtils.updateURL({});
+     * // URL becomes: current-path (no query string)
+     * ```
+     */
     static updateURL(params: Record<string, string | string[]>): void;
+    /**
+     * Gets the current URL parameters parsed into a convenient format.
+     * Returns an empty object when running in server-side environment.
+     *
+     * @static
+     * @returns {Record<string, string | string[]>} Object with current URL parameters
+     *
+     * @example
+     * ```typescript
+     * // Current URL: ?category=electronics&color=red&color=blue
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: { category: 'electronics', color: ['red', 'blue'] }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Server-side usage
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: {} (empty object)
+     * ```
+     */
     static getURLParams(): Record<string, string | string[]>;
 }