@wix/headless-stores 0.0.36 → 0.0.37

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[]>;
 }

package/dist/utils/url-params.js

@@ -1,4 +1,26 @@
+/**
+ * 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 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) {
         const params = {};
         // Parse all parameters
@@ -18,15 +40,40 @@ export class URLParamsUtils {
         }
         return params;
     }
+    /**
+     * 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) {
-        if (typeof window === 'undefined')
+        if (typeof window === "undefined")
             return;
         const url = new URL(window.location.href);
         const urlParams = new URLSearchParams();
         // Add all parameters
         Object.entries(params).forEach(([key, value]) => {
             if (Array.isArray(value)) {
-                value.forEach(v => urlParams.append(key, v));
+                value.forEach((v) => urlParams.append(key, v));
             }
             else if (value) {
                 urlParams.set(key, value);
@@ -36,10 +83,31 @@ export class URLParamsUtils {
         const newURL = urlParams.toString()
             ? `${url.pathname}?${urlParams.toString()}`
             : url.pathname;
-        window.history.replaceState({}, '', newURL);
+        window.history.replaceState({}, "", newURL);
     }
+    /**
+     * 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() {
-        if (typeof window === 'undefined')
+        if (typeof window === "undefined")
             return {};
         return this.parseSearchParams(new URLSearchParams(window.location.search));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-stores",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "type": "module",
   "scripts": {
     "prebuild": "cd ../media && yarn build && cd ../ecom && yarn build",
@@ -58,8 +58,8 @@
     "@wix/auto_sdk_stores_read-only-variants-v-3": "^1.0.23",
     "@wix/ecom": "^1.0.1238",
     "@wix/essentials": "^0.1.24",
-    "@wix/headless-ecom": "^0.0.8",
-    "@wix/headless-media": "^0.0.5",
+    "@wix/headless-ecom": "^0.0.10",
+    "@wix/headless-media": "^0.0.7",
     "@wix/redirects": "^1.0.83",
     "@wix/services-definitions": "^0.1.4",
     "@wix/services-manager-react": "^0.1.26"