@wix/headless-stores 0.0.58 → 0.0.60

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

@@ -1,7 +1,19 @@
 import { type Signal, type ReadOnlySignal } from '@wix/services-definitions/core-services/signals';
 import { customizationsV3, productsV3 } from '@wix/stores';
-import { InventoryStatusType } from './products-list-search-service.js';
+import { type Category } from './category-service.js';
 export declare const DEFAULT_QUERY_LIMIT = 100;
+import { SortType } from './../enums/sort-enums.js';
+export { SortType } from './../enums/sort-enums.js';
+/**
+ * Enumeration of inventory status types available for filtering.
+ * Re-exports the Wix inventory availability status enum values.
+ */
+export declare const InventoryStatusType: typeof productsV3.InventoryAvailabilityStatus;
+/**
+ * Type for inventory status values.
+ * Re-exports the Wix inventory availability status enum type.
+ */
+export type InventoryStatusType = productsV3.InventoryAvailabilityStatus;
 /**
  * Interface representing a product option (like Size, Color, etc.).
  */
@@ -362,3 +374,55 @@ export declare const ProductListService: import("@wix/services-definitions").Ser
     /** Reactive signal indicating if there are more products to load */
     hasMoreProducts: ReadOnlySignal<boolean>;
 }, ProductsListServiceConfig>;
+/**
+ * Initial search state that can be loaded from URL parameters.
+ */
+export type InitialSearchState = {
+    sort?: SortType;
+    limit?: number;
+    cursor?: string | null;
+    priceRange?: {
+        min?: number;
+        max?: number;
+    };
+    inventoryStatuses?: InventoryStatusType[];
+    productOptions?: Record<string, string[]>;
+    category?: Category;
+    visible?: boolean;
+    productType?: string;
+};
+/**
+ * Parse URL and build complete search options with all filters, sort, and pagination.
+ * This function extracts search parameters, filters, sorting, and pagination from a URL
+ * and converts them into the format expected by the Wix Stores API.
+ *
+ * @param {string} url - The URL to parse search parameters from
+ * @param {Category[]} categoriesList - List of available categories for category slug resolution
+ * @param {productsV3.V3ProductSearch} [defaultSearchOptions] - Default search options to merge with parsed URL parameters
+ * @returns {Promise<{searchOptions: productsV3.V3ProductSearch, initialSearchState: InitialSearchState}>}
+ *   Object containing both API-ready search options and UI-ready initial state
+ *
+ * @example
+ * ```tsx
+ * // Parse URL with filters, sort, and pagination
+ * const categories = await loadCategoriesListServiceConfig();
+ * const { searchOptions, initialSearchState } = await parseUrlToSearchOptions(
+ *   'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50',
+ *   categories.categories
+ * );
+ *
+ * // Use searchOptions for API calls
+ * const products = await productsV3.searchProducts(searchOptions);
+ *
+ * // Use initialSearchState for UI initialization
+ * const filterState = initialSearchState.productOptions; // { colorId: ['red-id', 'blue-id'] }
+ * ```
+ */
+export declare function parseUrlToSearchOptions(url: string, categoriesList: Category[], customizations: customizationsV3.Customization[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{
+    searchOptions: productsV3.V3ProductSearch;
+    initialSearchState: InitialSearchState;
+}>;
+/**
+ * Convert URL sort format to SortType enum
+ */
+export declare function convertUrlSortToSortType(urlSort: string): SortType | null;

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

@@ -2,8 +2,14 @@ import { defineService, implementService } from '@wix/services-definitions';
 import { SignalsServiceDefinition, } from '@wix/services-definitions/core-services/signals';
 import { customizationsV3, productsV3, readOnlyVariantsV3 } from '@wix/stores';
 import { loadCategoriesListServiceConfig } from './categories-list-service.js';
-import { InventoryStatusType, parseUrlToSearchOptions, } from './products-list-search-service.js';
 export const DEFAULT_QUERY_LIMIT = 100;
+import { SortType } from './../enums/sort-enums.js';
+export { SortType } from './../enums/sort-enums.js';
+/**
+ * Enumeration of inventory status types available for filtering.
+ * Re-exports the Wix inventory availability status enum values.
+ */
+export const InventoryStatusType = productsV3.InventoryAvailabilityStatus;
 /**
  * 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
@@ -471,3 +477,409 @@ function getAvailableProductOptions(aggregationData = [], customizations = []) {
         .filter((option) => option.choices.length > 0);
     return options;
 }
+/**
+ * Parse URL and build complete search options with all filters, sort, and pagination.
+ * This function extracts search parameters, filters, sorting, and pagination from a URL
+ * and converts them into the format expected by the Wix Stores API.
+ *
+ * @param {string} url - The URL to parse search parameters from
+ * @param {Category[]} categoriesList - List of available categories for category slug resolution
+ * @param {productsV3.V3ProductSearch} [defaultSearchOptions] - Default search options to merge with parsed URL parameters
+ * @returns {Promise<{searchOptions: productsV3.V3ProductSearch, initialSearchState: InitialSearchState}>}
+ *   Object containing both API-ready search options and UI-ready initial state
+ *
+ * @example
+ * ```tsx
+ * // Parse URL with filters, sort, and pagination
+ * const categories = await loadCategoriesListServiceConfig();
+ * const { searchOptions, initialSearchState } = await parseUrlToSearchOptions(
+ *   'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50',
+ *   categories.categories
+ * );
+ *
+ * // Use searchOptions for API calls
+ * const products = await productsV3.searchProducts(searchOptions);
+ *
+ * // Use initialSearchState for UI initialization
+ * const filterState = initialSearchState.productOptions; // { colorId: ['red-id', 'blue-id'] }
+ * ```
+ */
+export async function parseUrlToSearchOptions(url, categoriesList, customizations, defaultSearchOptions) {
+    const urlObj = new URL(url);
+    const searchParams = urlObj.searchParams;
+    // Build search options
+    const searchOptions = {
+        cursorPaging: {
+            limit: DEFAULT_QUERY_LIMIT,
+        },
+        ...defaultSearchOptions,
+    };
+    // Initialize search state for service
+    const initialSearchState = {};
+    // Extract category slug from URL path
+    // The category slug is always the last segment of the path
+    const pathSegments = urlObj.pathname.split('/').filter(Boolean);
+    let category = undefined;
+    if (pathSegments.length > 0) {
+        const lastSegment = pathSegments[pathSegments.length - 1];
+        // Check if the last segment matches any category in the categories list
+        category = categoriesList.find((cat) => cat.slug === lastSegment);
+        if (category) {
+            initialSearchState.category = category;
+        }
+    }
+    // Handle text search (q parameter)
+    const query = searchParams.get('q');
+    if (query) {
+        searchOptions.search = {
+            expression: query,
+        };
+    }
+    // Handle sorting
+    const sort = searchParams.get('sort');
+    if (sort) {
+        const sortType = convertUrlSortToSortType(sort);
+        if (sortType) {
+            initialSearchState.sort = sortType;
+            // Apply sort to search options
+            switch (sortType) {
+                case SortType.NAME_ASC:
+                    searchOptions.sort = [
+                        { fieldName: 'name', order: productsV3.SortDirection.ASC },
+                    ];
+                    break;
+                case SortType.NAME_DESC:
+                    searchOptions.sort = [
+                        { fieldName: 'name', order: productsV3.SortDirection.DESC },
+                    ];
+                    break;
+                case SortType.PRICE_ASC:
+                    searchOptions.sort = [
+                        {
+                            fieldName: 'actualPriceRange.minValue.amount',
+                            order: productsV3.SortDirection.ASC,
+                        },
+                    ];
+                    break;
+                case SortType.PRICE_DESC:
+                    searchOptions.sort = [
+                        {
+                            fieldName: 'actualPriceRange.minValue.amount',
+                            order: productsV3.SortDirection.DESC,
+                        },
+                    ];
+                    break;
+                case SortType.RECOMMENDED:
+                    searchOptions.sort = [
+                        {
+                            fieldName: 'name',
+                            order: productsV3.SortDirection.DESC,
+                        },
+                    ];
+                    break;
+            }
+        }
+    }
+    // Handle pagination
+    const limit = searchParams.get('limit');
+    const cursor = searchParams.get('cursor');
+    if (limit || cursor) {
+        searchOptions.cursorPaging = {};
+        if (limit) {
+            const limitNum = parseInt(limit, 10);
+            if (!isNaN(limitNum) && limitNum > 0) {
+                searchOptions.cursorPaging.limit = limitNum;
+                initialSearchState.limit = limitNum;
+            }
+        }
+        if (cursor) {
+            searchOptions.cursorPaging.cursor = cursor;
+            initialSearchState.cursor = cursor;
+        }
+    }
+    // Handle filtering for search options
+    const filter = {};
+    const visible = searchParams.get('visible');
+    if (visible !== null) {
+        filter['visible'] = visible === 'true';
+        initialSearchState.visible = visible === 'true';
+    }
+    const productType = searchParams.get('productType');
+    if (productType) {
+        filter['productType'] = productType;
+        initialSearchState.productType = productType;
+    }
+    // Add category filter if found
+    if (category) {
+        filter['allCategoriesInfo.categories'] = {
+            $matchItems: [{ _id: { $in: [category._id] } }],
+        };
+    }
+    // Price range filtering
+    const minPrice = searchParams.get('minPrice');
+    const maxPrice = searchParams.get('maxPrice');
+    if (minPrice || maxPrice) {
+        initialSearchState.priceRange = {};
+        if (minPrice) {
+            const minPriceNum = parseFloat(minPrice);
+            if (!isNaN(minPriceNum)) {
+                filter['actualPriceRange.minValue.amount'] = { $gte: minPriceNum };
+                initialSearchState.priceRange.min = minPriceNum;
+            }
+        }
+        if (maxPrice) {
+            const maxPriceNum = parseFloat(maxPrice);
+            if (!isNaN(maxPriceNum)) {
+                filter['actualPriceRange.maxValue.amount'] = { $lte: maxPriceNum };
+                initialSearchState.priceRange.max = maxPriceNum;
+            }
+        }
+    }
+    const inventoryStatus = searchParams.get('inventoryStatus');
+    if (inventoryStatus) {
+        filter['inventory.availabilityStatus'] = {
+            $in: inventoryStatus.split(','),
+        };
+    }
+    // Parse product options from URL parameters
+    const reservedParams = [
+        'minPrice',
+        'maxPrice',
+        'inventory_status',
+        'inventoryStatus',
+        'visible',
+        'productType',
+        'q',
+        'limit',
+        'cursor',
+        'sort',
+    ];
+    const productOptionsById = {};
+    for (const [optionName, optionValues] of searchParams.entries()) {
+        if (reservedParams.includes(optionName))
+            continue;
+        // Find the option by name in customizations
+        const option = customizations.find((c) => c.name === optionName &&
+            c.customizationType ===
+                customizationsV3.CustomizationType.PRODUCT_OPTION);
+        if (option && option._id) {
+            const choiceValues = optionValues.split(',').filter(Boolean);
+            const choiceIds = [];
+            // Convert choice names to IDs
+            for (const choiceName of choiceValues) {
+                const choice = option.choicesSettings?.choices?.find((c) => c.name === choiceName);
+                if (choice && choice._id) {
+                    choiceIds.push(choice._id);
+                }
+            }
+            if (choiceIds.length > 0) {
+                productOptionsById[option._id] = choiceIds;
+            }
+        }
+    }
+    if (Object.keys(productOptionsById).length > 0) {
+        initialSearchState.productOptions = productOptionsById;
+        // Add product option filter to search options
+        filter[`options.choicesSettings.choices.choiceId`] = {
+            $hasSome: Object.values(productOptionsById).flat(),
+        };
+    }
+    // Add filter to search options if any filters were set
+    if (Object.keys(filter).length > 0) {
+        searchOptions.filter = filter;
+    }
+    // Add aggregations for getting filter options
+    searchOptions.aggregations = [
+        {
+            name: 'minPrice',
+            fieldPath: 'actualPriceRange.minValue.amount',
+            type: 'SCALAR',
+            scalar: { type: 'MIN' },
+        },
+        {
+            name: 'maxPrice',
+            fieldPath: 'actualPriceRange.maxValue.amount',
+            type: 'SCALAR',
+            scalar: { type: 'MAX' },
+        },
+        {
+            name: 'optionNames',
+            fieldPath: 'options.name',
+            type: productsV3.SortType.VALUE,
+            value: {
+                limit: 20,
+                sortType: productsV3.SortType.VALUE,
+                sortDirection: productsV3.SortDirection.ASC,
+            },
+        },
+        {
+            name: 'choiceNames',
+            fieldPath: 'options.choicesSettings.choices.name',
+            type: productsV3.SortType.VALUE,
+            value: {
+                limit: 50,
+                sortType: productsV3.SortType.VALUE,
+                sortDirection: productsV3.SortDirection.ASC,
+            },
+        },
+        {
+            name: 'inventoryStatus',
+            fieldPath: 'inventory.availabilityStatus',
+            type: productsV3.SortType.VALUE,
+            value: {
+                limit: 10,
+                sortType: productsV3.SortType.VALUE,
+                sortDirection: productsV3.SortDirection.ASC,
+            },
+        },
+    ];
+    return { searchOptions, initialSearchState };
+}
+/**
+ * Convert SortType enum to URL format
+ */
+function convertSortTypeToUrl(sortType) {
+    switch (sortType) {
+        case SortType.NAME_ASC:
+            return 'name';
+        case SortType.NAME_DESC:
+            return 'name:desc';
+        case SortType.PRICE_ASC:
+            return 'price';
+        case SortType.PRICE_DESC:
+            return 'price:desc';
+        case SortType.NEWEST:
+            return 'newest';
+        case SortType.RECOMMENDED:
+            return 'recommended';
+        default:
+            return 'name';
+    }
+}
+/**
+ * Convert URL sort format to SortType enum
+ */
+export function convertUrlSortToSortType(urlSort) {
+    const sortParts = urlSort.split(':');
+    const field = sortParts[0]?.toLowerCase();
+    const order = sortParts[1]?.toLowerCase() === 'desc' ? 'desc' : 'asc';
+    switch (field) {
+        case 'name':
+            return order === 'desc' ? SortType.NAME_DESC : SortType.NAME_ASC;
+        case 'price':
+            return order === 'desc' ? SortType.PRICE_DESC : SortType.PRICE_ASC;
+        case 'newest':
+        case 'created':
+            return SortType.NEWEST;
+        case 'recommended':
+            return SortType.RECOMMENDED;
+        default:
+            return null;
+    }
+}
+/**
+ * Update URL with current search state (sort, filters, pagination)
+ */
+//@ts-expect-error
+function updateUrlWithSearchState(searchState) {
+    if (typeof window === 'undefined')
+        return;
+    const { sort, filters, customizations, catalogBounds, categorySlug } = searchState;
+    // Convert filter IDs back to human-readable names for URL
+    const humanReadableOptions = {};
+    for (const [optionId, choiceIds] of Object.entries(filters?.productOptions ?? {})) {
+        const option = customizations.find((c) => c._id === optionId);
+        if (option && option.name) {
+            const choiceNames = [];
+            for (const choiceId of choiceIds) {
+                const choice = option.choicesSettings?.choices?.find((c) => c._id === choiceId);
+                if (choice && choice.name) {
+                    choiceNames.push(choice.name);
+                }
+            }
+            if (choiceNames.length > 0) {
+                humanReadableOptions[option.name] = choiceNames;
+            }
+        }
+    }
+    // Start with current URL parameters to preserve non-search parameters
+    const params = new URLSearchParams(window.location.search);
+    // Define search-related parameters that we manage
+    const searchParams = [
+        'sort',
+        'limit',
+        'cursor',
+        'minPrice',
+        'maxPrice',
+        'inventoryStatus',
+        'visible',
+        'productType',
+        // Product option names will be dynamically added below
+        // Note: category is NOT included here as it's handled in the URL path
+    ];
+    // Remove existing search parameters first
+    searchParams.forEach((param) => params.delete(param));
+    // Remove existing product option parameters (they have dynamic names)
+    for (const customization of customizations) {
+        if (customization.customizationType ===
+            customizationsV3.CustomizationType.PRODUCT_OPTION &&
+            customization.name) {
+            params.delete(customization.name);
+        }
+    }
+    // Add sort parameter (only if not default)
+    const urlSort = convertSortTypeToUrl(sort);
+    if (sort !== SortType.NAME_ASC) {
+        params.set('sort', urlSort);
+    }
+    // Add price range parameters only if they differ from catalog bounds
+    if (filters.priceRange?.min &&
+        filters.priceRange.min > catalogBounds.minPrice) {
+        params.set('minPrice', filters.priceRange.min.toString());
+    }
+    if (filters.priceRange?.max &&
+        filters.priceRange.max < catalogBounds.maxPrice) {
+        params.set('maxPrice', filters.priceRange.max.toString());
+    }
+    // Add inventory status parameters
+    if (filters.inventoryStatuses && filters.inventoryStatuses.length > 0) {
+        params.set('inventoryStatus', filters.inventoryStatuses.join(','));
+    }
+    // Add visibility filter (only if explicitly false, since true is default)
+    if (filters.visible === false) {
+        params.set('visible', 'false');
+    }
+    // Add product type filter
+    if (filters.productType) {
+        params.set('productType', filters.productType);
+    }
+    // Add product options as individual parameters (Color=Red,Blue&Size=Large)
+    for (const [optionName, values] of Object.entries(humanReadableOptions)) {
+        if (values.length > 0) {
+            params.set(optionName, values.join(','));
+        }
+    }
+    // Handle URL path construction with category
+    let baseUrl = window.location.pathname;
+    // If categorySlug is provided, replace the last path segment (which represents the category)
+    if (categorySlug) {
+        const pathSegments = baseUrl.split('/').filter(Boolean);
+        if (pathSegments.length > 0) {
+            // Replace the last segment with the new category slug
+            pathSegments[pathSegments.length - 1] = categorySlug;
+            baseUrl = '/' + pathSegments.join('/');
+        }
+        else {
+            // If no segments, just use the category slug
+            baseUrl = `/${categorySlug}`;
+        }
+    }
+    // Build the new URL
+    const newUrl = params.toString()
+        ? `${baseUrl}?${params.toString()}`
+        : baseUrl;
+    // Only update if URL actually changed
+    if (newUrl !== window.location.pathname + window.location.search) {
+        window.history.pushState(null, '', newUrl);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-stores",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "type": "module",
   "scripts": {
     "prebuild": "cd ../media && yarn build && cd ../ecom && yarn build",
@@ -62,9 +62,10 @@
     "@wix/auto_sdk_stores_read-only-variants-v-3": "^1.0.23",
     "@wix/ecom": "^1.0.1278",
     "@wix/essentials": "^0.1.24",
+    "@wix/headless-components": "0.0.2",
     "@wix/headless-ecom": "0.0.17",
     "@wix/headless-media": "^0.0.11",
-    "@wix/headless-utils": "^0.0.1",
+    "@wix/headless-utils": "^0.0.2",
     "@wix/redirects": "^1.0.83",
     "@wix/services-definitions": "^0.1.4",
     "@wix/services-manager-react": "^0.1.26"