@wix/headless-stores 0.0.35 → 0.0.37

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>;