@wix/headless-stores 0.0.35 → 0.0.37

package/cjs/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/cjs/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/cjs/dist/services/selected-variant-service.js

@@ -9,7 +9,6 @@ export const SelectedVariantService = implementService.withConfig()(SelectedVari
     const signalsService = getService(SignalsServiceDefinition);
     const cartService = getService(CurrentCartServiceDefinition);
     const productService = getService(ProductServiceDefinition);
-    // const mediaService = getService(MediaGalleryServiceDefinition);
     const selectedChoices = signalsService.signal({});
     const preOrderMessage = signalsService.signal(null);
     const initialProduct = productService.product.get();

package/cjs/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/cjs/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/dist/react/Category.d.ts

@@ -1,45 +1,97 @@
-import { type Category } from "@wix/auto_sdk_categories_categories";
-import React, { type ReactNode } from "react";
-export interface CategoryListProps {
-    children: (data: {
-        categories: Category[];
-        selectedCategory: string | null;
-        setSelectedCategory: (categoryId: string | null) => void;
-    }) => ReactNode;
+import type { PropsWithChildren, ReactNode } from "react";
+import { type CategoryServiceConfig } from "../services/category-service.js";
+/**
+ * Root component that provides the Category service context to its children.
+ * This component sets up the necessary services for managing category state.
+ *
+ * @order 1
+ * @component
+ * @example
+ * ```tsx
+ * import { Category } from '@wix/stores/components';
+ *
+ * function CategoryPage() {
+ *   return (
+ *     <Category.Root categoryServiceConfig={{ category: myCategory }}>
+ *       <Category.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Category.Name>
+ *       <Category.Slug>
+ *         {({ slug }) => <p>Slug: {slug}</p>}
+ *       </Category.Slug>
+ *     </Category.Root>
+ *   );
+ * }
+ * ```
+ */
+export declare function Root(props: PropsWithChildren<{
+    categoryServiceConfig: CategoryServiceConfig;
+}>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for Name headless component
+ */
+export interface NameProps {
+    /** Content to display (can be a render function receiving name data or ReactNode) */
+    children: ((props: NameRenderProps) => ReactNode) | ReactNode;
+}
+/**
+ * Render props for Name component
+ */
+export interface NameRenderProps {
+    /** Category name */
+    name: string;
+}
+/**
+ * Headless component for category name display
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Category } from '@wix/stores/components';
+ *
+ * function CategoryHeader() {
+ *   return (
+ *     <Category.Name>
+ *       {({ name }) => (
+ *         <h1 className="category-title">{name}</h1>
+ *       )}
+ *     </Category.Name>
+ *   );
+ * }
+ * ```
+ */
+export declare function Name(props: NameProps): ReactNode;
+/**
+ * Props for Slug headless component
+ */
+export interface SlugProps {
+    /** Content to display (can be a render function receiving slug data or ReactNode) */
+    children: ((props: SlugRenderProps) => ReactNode) | ReactNode;
+}
+/**
+ * Render props for Slug component
+ */
+export interface SlugRenderProps {
+    /** Category slug */
+    slug: string;
 }
 /**
- * Headless component for displaying a list of categories
+ * Headless component for category slug display
  *
  * @component
  * @example
  * ```tsx
  * import { Category } from '@wix/stores/components';
  *
- * function CategoryNavigation() {
+ * function CategoryInfo() {
  *   return (
- *     <Category.List>
- *       {({ categories, selectedCategory, setSelectedCategory }) => (
- *         <nav>
- *           <button
- *             onClick={() => setSelectedCategory(null)}
- *             className={selectedCategory === null ? 'active' : ''}
- *           >
- *             All Categories
- *           </button>
- *           {categories.map(category => (
- *             <button
- *               key={category.id}
- *               onClick={() => setSelectedCategory(category.id)}
- *               className={selectedCategory === category.id ? 'active' : ''}
- *             >
- *               {category.name}
- *             </button>
- *           ))}
- *         </nav>
+ *     <Category.Slug>
+ *       {({ slug }) => (
+ *         <p className="category-slug">Category slug: {slug}</p>
  *       )}
- *     </Category.List>
+ *     </Category.Slug>
  *   );
  * }
  * ```
  */
-export declare const List: React.FC<CategoryListProps>;
+export declare function Slug(props: SlugProps): ReactNode;