@wix/headless-stores 0.0.36 → 0.0.37

package/cjs/dist/services/product-service.d.ts

@@ -1,29 +1,100 @@
 import { type Signal } from "@wix/services-definitions/core-services/signals";
 import * as productsV3 from "@wix/auto_sdk_stores_products-v-3";
+/**
+ * API interface for the Product service, providing reactive product data management.
+ * This service handles loading and managing a single product's data, loading state, and errors.
+ *
+ * @interface ProductServiceAPI
+ */
 export interface ProductServiceAPI {
+    /** Reactive signal containing the current product data */
     product: Signal<productsV3.V3Product>;
+    /** Reactive signal indicating if a product is currently being loaded */
     isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     error: Signal<string | null>;
+    /** Function to load a product by its slug */
     loadProduct: (slug: string) => Promise<void>;
 }
+/**
+ * Service definition for the Product service.
+ * This defines the contract that the ProductService must implement.
+ *
+ * @constant
+ */
 export declare const ProductServiceDefinition: string & {
     __api: ProductServiceAPI;
     __config: {};
     isServiceDefinition?: boolean;
 } & ProductServiceAPI;
+/**
+ * Configuration interface required to initialize the ProductService.
+ * Contains the initial product data that will be loaded into the service.
+ *
+ * @interface ProductServiceConfig
+ */
 export interface ProductServiceConfig {
+    /** The initial product data to configure the service with */
     product: productsV3.V3Product;
 }
+/**
+ * Implementation of the Product service that manages reactive product data.
+ * This service provides signals for product data, loading state, and error handling,
+ * along with methods to dynamically load products.
+ *
+ * @example
+ * ```tsx
+ * import { ProductService, ProductServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function ProductComponent({ productConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductServiceDefinition, ProductService.withConfig(productConfig)]
+ *     ])}>
+ *       <ProductDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function ProductDisplay() {
+ *   const productService = useService(ProductServiceDefinition);
+ *   const product = productService.product.get();
+ *   const isLoading = productService.isLoading.get();
+ *   const error = productService.error.get();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return <h1>{product.name}</h1>;
+ * }
+ * ```
+ */
 export declare const ProductService: import("@wix/services-definitions").ServiceFactory<string & {
     __api: ProductServiceAPI;
     __config: {};
     isServiceDefinition?: boolean;
 } & ProductServiceAPI, ProductServiceConfig>;
+/**
+ * Success result interface for product service configuration loading.
+ * Returned when a product is successfully found and loaded.
+ *
+ * @interface SuccessProductServiceConfigResult
+ */
 export interface SuccessProductServiceConfigResult {
+    /** Type "success" means that the product was found and the config is valid */
     type: "success";
+    /** The product config containing the loaded product data */
     config: ProductServiceConfig;
 }
+/**
+ * Not found result interface for product service configuration loading.
+ * Returned when a product with the given slug cannot be found.
+ *
+ * @interface NotFoundProductServiceConfigResult
+ */
 export interface NotFoundProductServiceConfigResult {
+    /** Type "notFound" means that the product was not found */
     type: "notFound";
 }
 /**

package/cjs/dist/services/product-service.js

@@ -1,7 +1,46 @@
 import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import * as productsV3 from "@wix/auto_sdk_stores_products-v-3";
+/**
+ * Service definition for the Product service.
+ * This defines the contract that the ProductService must implement.
+ *
+ * @constant
+ */
 export const ProductServiceDefinition = defineService("product");
+/**
+ * Implementation of the Product service that manages reactive product data.
+ * This service provides signals for product data, loading state, and error handling,
+ * along with methods to dynamically load products.
+ *
+ * @example
+ * ```tsx
+ * import { ProductService, ProductServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function ProductComponent({ productConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductServiceDefinition, ProductService.withConfig(productConfig)]
+ *     ])}>
+ *       <ProductDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function ProductDisplay() {
+ *   const productService = useService(ProductServiceDefinition);
+ *   const product = productService.product.get();
+ *   const isLoading = productService.isLoading.get();
+ *   const error = productService.error.get();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return <h1>{product.name}</h1>;
+ * }
+ * ```
+ */
 export const ProductService = implementService.withConfig()(ProductServiceDefinition, ({ getService, config }) => {
     const signalsService = getService(SignalsServiceDefinition);
     const product = signalsService.signal(config.product);
@@ -26,6 +65,14 @@ export const ProductService = implementService.withConfig()(ProductServiceDefini
         loadProduct,
     };
 });
+/**
+ * Internal helper function to load a product by its slug from the Wix Products API.
+ * Fetches comprehensive product data including description, categories, media, etc.
+ *
+ * @private
+ * @param {string} slug - The product slug to load
+ * @returns {Promise} Product response from the API
+ */
 const loadProductBySlug = async (slug) => {
     const productResponse = await productsV3.getProductBySlug(slug, {
         fields: [

package/cjs/dist/services/products-list-filters-service.d.ts

@@ -0,0 +1,292 @@
+import { type Signal } from "@wix/services-definitions/core-services/signals";
+import { customizationsV3 } from "@wix/stores";
+/**
+ * Interface representing a product option (like Size, Color, etc.).
+ * Contains the option metadata and available choices.
+ *
+ * @interface ProductOption
+ */
+export interface ProductOption {
+    /** Unique identifier for the product option */
+    id: string;
+    /** Display name of the option (e.g., "Size", "Color") */
+    name: string;
+    /** Array of available choices for this option */
+    choices: ProductChoice[];
+    /** Optional render type for UI display purposes */
+    optionRenderType?: string;
+}
+/**
+ * Interface representing a choice within a product option.
+ * For example, "Red" would be a choice within a "Color" option.
+ *
+ * @interface ProductChoice
+ */
+export interface ProductChoice {
+    /** Unique identifier for the choice */
+    id: string;
+    /** Display name of the choice (e.g., "Red", "Large") */
+    name: string;
+    /** Optional color code for color-based choices */
+    colorCode?: string;
+}
+/**
+ * Enumeration of inventory status types available for filtering.
+ * Maps to the Wix Stores API inventory availability statuses.
+ *
+ * @enum {string}
+ */
+export declare enum InventoryStatusType {
+    /** Product is in stock and available for purchase */
+    IN_STOCK = "IN_STOCK",
+    /** Product is out of stock */
+    OUT_OF_STOCK = "OUT_OF_STOCK",
+    /** Product is partially out of stock (some variants available) */
+    PARTIALLY_OUT_OF_STOCK = "PARTIALLY_OUT_OF_STOCK"
+}
+/**
+ * Configuration interface for the Products List Filters service.
+ * Contains customizations data used to build filter options.
+ *
+ * @interface ProductsListFiltersServiceConfig
+ */
+export type ProductsListFiltersServiceConfig = {
+    /** Array of product customizations for building filter options */
+    customizations: customizationsV3.Customization[];
+};
+/**
+ * Loads products list filters service configuration from the Wix Stores API for SSR initialization.
+ * This function fetches customization data that will be used to build product filter options.
+ *
+ * @returns {Promise<ProductsListFiltersServiceConfig>} Promise that resolves to the filters configuration
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/products.astro
+ * import { loadProductsListFiltersServiceConfig } from '@wix/stores/services';
+ * import { ProductsListFilters } from '@wix/stores/components';
+ *
+ * // Load filters configuration during SSR
+ * const filtersConfig = await loadProductsListFiltersServiceConfig();
+ * ---
+ *
+ * <ProductsListFilters.Root filtersConfig={filtersConfig}>
+ *   <ProductsListFilters.MinPrice>
+ *     {({ minPrice, setMinPrice }) => (
+ *       <input
+ *         type="number"
+ *         value={minPrice}
+ *         onChange={(e) => setMinPrice(parseFloat(e.target.value))}
+ *         placeholder="Min Price"
+ *       />
+ *     )}
+ *   </ProductsListFilters.MinPrice>
+ * </ProductsListFilters.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductsListFiltersServiceConfig } from '@wix/stores/services';
+ *
+ * export const getServerSideProps: GetServerSideProps = async () => {
+ *   const filtersConfig = await loadProductsListFiltersServiceConfig();
+ *
+ *   return {
+ *     props: {
+ *       filtersConfig,
+ *     },
+ *   };
+ * };
+ * ```
+ */
+export declare function loadProductsListFiltersServiceConfig(): Promise<ProductsListFiltersServiceConfig>;
+/**
+ * Service definition for the Products List Filters service.
+ * This defines the reactive API contract for managing product list filtering capabilities
+ * including price, inventory status, and product option filters.
+ *
+ * @constant
+ */
+export declare const ProductsListFiltersServiceDefinition: string & {
+    __api: {
+        /** Reactive signal containing the minimum price filter value */
+        minPrice: Signal<number>;
+        /** Reactive signal containing the maximum price filter value */
+        maxPrice: Signal<number>;
+        /** Reactive signal containing available inventory status options */
+        availableInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing selected inventory status filters */
+        selectedInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing available product options for filtering */
+        availableProductOptions: Signal<ProductOption[]>;
+        /** Reactive signal containing selected product option filters */
+        selectedProductOptions: Signal<Record<string, string[]>>;
+        /** Function to set the minimum price filter */
+        setMinPrice: (minPrice: number) => void;
+        /** Function to set the maximum price filter */
+        setMaxPrice: (maxPrice: number) => void;
+        /** Function to toggle an inventory status filter */
+        toggleInventoryStatus: (status: InventoryStatusType) => void;
+        /** Function to toggle a product option choice filter */
+        toggleProductOption: (optionId: string, choiceId: string) => void;
+        /** Reactive signal indicating if any filters are currently applied */
+        isFiltered: Signal<boolean>;
+        /** Function to reset all filters to their default state */
+        reset: () => void;
+    };
+    __config: {};
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the minimum price filter value */
+    minPrice: Signal<number>;
+    /** Reactive signal containing the maximum price filter value */
+    maxPrice: Signal<number>;
+    /** Reactive signal containing available inventory status options */
+    availableInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing selected inventory status filters */
+    selectedInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing available product options for filtering */
+    availableProductOptions: Signal<ProductOption[]>;
+    /** Reactive signal containing selected product option filters */
+    selectedProductOptions: Signal<Record<string, string[]>>;
+    /** Function to set the minimum price filter */
+    setMinPrice: (minPrice: number) => void;
+    /** Function to set the maximum price filter */
+    setMaxPrice: (maxPrice: number) => void;
+    /** Function to toggle an inventory status filter */
+    toggleInventoryStatus: (status: InventoryStatusType) => void;
+    /** Function to toggle a product option choice filter */
+    toggleProductOption: (optionId: string, choiceId: string) => void;
+    /** Reactive signal indicating if any filters are currently applied */
+    isFiltered: Signal<boolean>;
+    /** Function to reset all filters to their default state */
+    reset: () => void;
+};
+/**
+ * Implementation of the Products List Filters service that manages reactive filtering state.
+ * This service provides signals for all filter types (price, inventory, product options) and
+ * automatically updates the products list search options when filters change.
+ *
+ * @example
+ * ```tsx
+ * import { ProductsListFiltersService, ProductsListFiltersServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function FiltersComponent({ filtersConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListFiltersServiceDefinition, ProductsListFiltersService.withConfig(filtersConfig)]
+ *     ])}>
+ *       <FilterControls />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function FilterControls() {
+ *   const filtersService = useService(ProductsListFiltersServiceDefinition);
+ *   const minPrice = filtersService.minPrice.get();
+ *   const maxPrice = filtersService.maxPrice.get();
+ *   const selectedInventoryStatuses = filtersService.selectedInventoryStatuses.get();
+ *   const availableProductOptions = filtersService.availableProductOptions.get();
+ *   const isFiltered = filtersService.isFiltered.get();
+ *
+ *   return (
+ *     <div>
+ *       <div>
+ *         <input
+ *           type="number"
+ *           value={minPrice}
+ *           onChange={(e) => filtersService.setMinPrice(parseFloat(e.target.value))}
+ *           placeholder="Min Price"
+ *         />
+ *         <input
+ *           type="number"
+ *           value={maxPrice}
+ *           onChange={(e) => filtersService.setMaxPrice(parseFloat(e.target.value))}
+ *           placeholder="Max Price"
+ *         />
+ *       </div>
+ *
+ *       {availableProductOptions.map(option => (
+ *         <div key={option.id}>
+ *           <h4>{option.name}</h4>
+ *           {option.choices.map(choice => (
+ *             <label key={choice.id}>
+ *               <input
+ *                 type="checkbox"
+ *                 onChange={() => filtersService.toggleProductOption(option.id, choice.id)}
+ *               />
+ *               {choice.name}
+ *             </label>
+ *           ))}
+ *         </div>
+ *       ))}
+ *
+ *       {isFiltered && (
+ *         <button onClick={() => filtersService.reset()}>
+ *           Clear All Filters
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const ProductsListFiltersService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: {
+        /** Reactive signal containing the minimum price filter value */
+        minPrice: Signal<number>;
+        /** Reactive signal containing the maximum price filter value */
+        maxPrice: Signal<number>;
+        /** Reactive signal containing available inventory status options */
+        availableInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing selected inventory status filters */
+        selectedInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing available product options for filtering */
+        availableProductOptions: Signal<ProductOption[]>;
+        /** Reactive signal containing selected product option filters */
+        selectedProductOptions: Signal<Record<string, string[]>>;
+        /** Function to set the minimum price filter */
+        setMinPrice: (minPrice: number) => void;
+        /** Function to set the maximum price filter */
+        setMaxPrice: (maxPrice: number) => void;
+        /** Function to toggle an inventory status filter */
+        toggleInventoryStatus: (status: InventoryStatusType) => void;
+        /** Function to toggle a product option choice filter */
+        toggleProductOption: (optionId: string, choiceId: string) => void;
+        /** Reactive signal indicating if any filters are currently applied */
+        isFiltered: Signal<boolean>;
+        /** Function to reset all filters to their default state */
+        reset: () => void;
+    };
+    __config: {};
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the minimum price filter value */
+    minPrice: Signal<number>;
+    /** Reactive signal containing the maximum price filter value */
+    maxPrice: Signal<number>;
+    /** Reactive signal containing available inventory status options */
+    availableInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing selected inventory status filters */
+    selectedInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing available product options for filtering */
+    availableProductOptions: Signal<ProductOption[]>;
+    /** Reactive signal containing selected product option filters */
+    selectedProductOptions: Signal<Record<string, string[]>>;
+    /** Function to set the minimum price filter */
+    setMinPrice: (minPrice: number) => void;
+    /** Function to set the maximum price filter */
+    setMaxPrice: (maxPrice: number) => void;
+    /** Function to toggle an inventory status filter */
+    toggleInventoryStatus: (status: InventoryStatusType) => void;
+    /** Function to toggle a product option choice filter */
+    toggleProductOption: (optionId: string, choiceId: string) => void;
+    /** Reactive signal indicating if any filters are currently applied */
+    isFiltered: Signal<boolean>;
+    /** Function to reset all filters to their default state */
+    reset: () => void;
+}, ProductsListFiltersServiceConfig>;