@wix/headless-stores 0.0.36 → 0.0.38

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

@@ -0,0 +1,179 @@
+import { defineService } from "@wix/services-definitions";
+import { implementService } from "@wix/services-definitions";
+import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
+import { ProductsListServiceDefinition } from "./products-list-service.js";
+/**
+ * Service definition for the Products List Pagination service.
+ * This defines the reactive API contract for managing product list pagination state and navigation.
+ *
+ * @constant
+ */
+export const ProductsListPaginationServiceDefinition = defineService("products-list-pagination");
+/**
+ * Implementation of the Products List Pagination service that manages reactive pagination state.
+ * This service provides signals for pagination state and automatically updates the products list
+ * search options when pagination settings change. It supports both cursor-based pagination
+ * and load-more functionality.
+ *
+ * @example
+ * ```tsx
+ * import { ProductsListPaginationService, ProductsListPaginationServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function PaginationComponent() {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListPaginationServiceDefinition, ProductsListPaginationService.withConfig({})]
+ *     ])}>
+ *       <PaginationControls />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function PaginationControls() {
+ *   const paginationService = useService(ProductsListPaginationServiceDefinition);
+ *   const currentLimit = paginationService.currentLimit.get();
+ *   const hasNextPage = paginationService.hasNextPage.get();
+ *   const hasPrevPage = paginationService.hasPrevPage.get();
+ *
+ *   return (
+ *     <div>
+ *       <div>
+ *         Items per page:
+ *         <select
+ *           value={currentLimit}
+ *           onChange={(e) => paginationService.setLimit(parseInt(e.target.value))}
+ *         >
+ *           <option value={12}>12</option>
+ *           <option value={24}>24</option>
+ *           <option value={48}>48</option>
+ *         </select>
+ *       </div>
+ *
+ *       <div>
+ *         <button
+ *           onClick={() => paginationService.goToFirstPage()}
+ *           disabled={!hasPrevPage}
+ *         >
+ *           First
+ *         </button>
+ *         <button
+ *           onClick={() => paginationService.prevPage()}
+ *           disabled={!hasPrevPage}
+ *         >
+ *           Previous
+ *         </button>
+ *         <button
+ *           onClick={() => paginationService.nextPage()}
+ *           disabled={!hasNextPage}
+ *         >
+ *           Next
+ *         </button>
+ *       </div>
+ *
+ *       <button onClick={() => paginationService.loadMore(12)}>
+ *         Load More
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const ProductsListPaginationService = implementService.withConfig()(ProductsListPaginationServiceDefinition, ({ getService }) => {
+    let firstRun = true;
+    const signalsService = getService(SignalsServiceDefinition);
+    const productsListService = getService(ProductsListServiceDefinition);
+    const currentLimitSignal = signalsService.signal(getCurrentLimit(productsListService.searchOptions.get()));
+    const currentCursorSignal = signalsService.signal(getCurrentCursor(productsListService.searchOptions.get()));
+    // Computed signals derived from paging metadata
+    const hasNextPageSignal = signalsService.computed(() => {
+        const pagingMetadata = productsListService.pagingMetadata.get();
+        return pagingMetadata?.hasNext || false;
+    });
+    const hasPrevPageSignal = signalsService.computed(() => {
+        const pagingMetadata = productsListService.pagingMetadata.get();
+        return typeof pagingMetadata.cursors?.prev !== "undefined";
+    });
+    if (typeof window !== "undefined") {
+        // Watch for changes in pagination settings and update search options
+        signalsService.effect(() => {
+            // CRITICAL: Read the signals FIRST to establish dependencies, even on first run
+            const limit = currentLimitSignal.get();
+            const cursor = currentCursorSignal.get();
+            if (firstRun) {
+                firstRun = false;
+                return;
+            }
+            // Build new search options with updated pagination
+            const newSearchOptions = {
+                ...productsListService.searchOptions.peek(),
+            };
+            // Update cursor paging
+            if (limit > 0) {
+                newSearchOptions.cursorPaging = {
+                    limit,
+                    ...(cursor && { cursor }),
+                };
+            }
+            else {
+                delete newSearchOptions.cursorPaging;
+            }
+            // Use callback to update search options
+            productsListService.setSearchOptions(newSearchOptions);
+        });
+    }
+    return {
+        currentLimit: currentLimitSignal,
+        currentCursor: currentCursorSignal,
+        hasNextPage: hasNextPageSignal,
+        hasPrevPage: hasPrevPageSignal,
+        setLimit: (limit) => {
+            currentLimitSignal.set(limit);
+            // Reset pagination when changing page size
+            currentCursorSignal.set(null);
+        },
+        loadMore: (count) => {
+            const limit = currentLimitSignal.get();
+            currentLimitSignal.set(limit + count);
+        },
+        nextPage: () => {
+            const pagingMetadata = productsListService.pagingMetadata.get();
+            const nextCursor = pagingMetadata?.cursors?.next;
+            if (nextCursor) {
+                currentCursorSignal.set(nextCursor);
+            }
+        },
+        prevPage: () => {
+            const pagingMetadata = productsListService.pagingMetadata.get();
+            const previousCursor = pagingMetadata?.cursors?.prev;
+            if (previousCursor) {
+                currentCursorSignal.set(previousCursor);
+            }
+        },
+        goToFirstPage: () => {
+            currentCursorSignal.set(null);
+        },
+    };
+});
+/**
+ * Helper function to extract the current limit from search options.
+ * Returns the pagination limit or a default value of 100 if not specified.
+ *
+ * @private
+ * @param {Parameters<typeof productsV3.searchProducts>[0]} searchOptions - The search options object
+ * @returns {number} The current limit value
+ */
+function getCurrentLimit(searchOptions) {
+    return searchOptions.cursorPaging?.limit || 100;
+}
+/**
+ * Helper function to extract the current cursor from search options.
+ * Returns the cursor string or null if not specified.
+ *
+ * @private
+ * @param {Parameters<typeof productsV3.searchProducts>[0]} searchOptions - The search options object
+ * @returns {string | null} The current cursor value or null
+ */
+function getCurrentCursor(searchOptions) {
+    return searchOptions.cursorPaging?.cursor || null;
+}

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

@@ -1,144 +1,230 @@
 import { type Signal } from "@wix/services-definitions/core-services/signals";
 import { productsV3 } from "@wix/stores";
-export interface ProductsListServiceConfig {
+/**
+ * Configuration interface for the Products List service.
+ * Contains the initial products data, search options, and metadata.
+ *
+ * @interface ProductsListServiceConfig
+ */
+export type ProductsListServiceConfig = {
+    /** Array of product objects to initialize the service with */
     products: productsV3.V3Product[];
+    /** Search options used to fetch the products */
     searchOptions: Parameters<typeof productsV3.searchProducts>[0];
+    /** Pagination metadata from the search response */
     pagingMetadata: productsV3.CommonCursorPagingMetadata;
+    /** Aggregation data containing filters, facets, and counts */
     aggregations: productsV3.AggregationData;
-}
+};
 /**
- * Loads products list service configuration from the Wix Products API for SSR initialization.
+ * 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
- * products based on search criteria that will be used to configure the ProductsListService.
+ * a list of products based on search criteria.
  *
- * @param searchOptions Search options for filtering and querying products
- * @returns Promise that resolves to ProductsListServiceConfig with products, metadata, and aggregations
+ * @param {Parameters<typeof productsV3.searchProducts>[0]} searchOptions - The search options for querying products
+ * @returns {Promise<ProductsListServiceConfig>} Promise that resolves to the products list configuration
  *
  * @example
  * ```astro
  * ---
- * // Astro page example - pages/search.astro
+ * // Astro page example - pages/products.astro
  * import { loadProductsListServiceConfig } from '@wix/stores/services';
- * import { ProductsList } from '@wix/stores/components';
- *
- * // Get search query from URL params
- * const searchQuery = Astro.url.searchParams.get('q') || '';
- * const category = Astro.url.searchParams.get('category');
+ * import { ProductList } from '@wix/stores/components';
  *
- * // Build search options
+ * // Define search options
  * const searchOptions = {
- *   query: { search: searchQuery },
- *   filter: category ? { categories: [category] } : undefined,
- *   paging: { limit: 12 }
+ *   cursorPaging: { limit: 12 },
+ *   filter: {},
+ *   sort: [{ fieldName: 'name', order: 'ASC' }]
  * };
  *
- * // Load products during SSR
- * const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ * // Load products data during SSR
+ * const productsConfig = await loadProductsListServiceConfig(searchOptions);
  * ---
  *
- * <ProductsList.Root productsListConfig={productsListConfig}>
- *   <ProductsList.ItemContent>
+ * <ProductList.Root productsConfig={productsConfig}>
+ *   <ProductList.ItemContent>
  *     {({ product }) => (
- *       <div class="product-item">
+ *       <div>
  *         <h3>{product.name}</h3>
+ *         <p>{product.description}</p>
  *       </div>
  *     )}
- *   </ProductsList.ItemContent>
- * </ProductsList.Root>
+ *   </ProductList.ItemContent>
+ * </ProductList.Root>
  * ```
  *
  * @example
  * ```tsx
- * // Next.js page example - pages/search.tsx
+ * // Next.js page example - pages/products.tsx
  * import { GetServerSideProps } from 'next';
  * import { loadProductsListServiceConfig } from '@wix/stores/services';
  * import { ProductsList } from '@wix/stores/components';
  *
- * interface SearchPageProps {
- *   productsListConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
- *   searchQuery: string;
+ * interface ProductsPageProps {
+ *   productsConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
  * }
  *
- * export const getServerSideProps: GetServerSideProps<SearchPageProps> = async ({ query }) => {
- *   const searchQuery = (query.q as string) || '';
- *   const category = query.category as string;
- *
- *   // Build search options
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async () => {
  *   const searchOptions = {
- *     query: { search: searchQuery },
- *     filter: category ? { categories: [category] } : undefined,
- *     paging: { limit: 12 }
+ *     cursorPaging: { limit: 12 },
+ *     filter: {},
+ *     sort: [{ fieldName: 'name', order: 'ASC' }]
  *   };
  *
- *   // Load products during SSR
- *   const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ *   const productsConfig = await loadProductsListServiceConfig(searchOptions);
  *
  *   return {
  *     props: {
- *       productsListConfig,
- *       searchQuery,
+ *       productsConfig,
  *     },
  *   };
  * };
  *
- * export default function SearchPage({ productsListConfig, searchQuery }: SearchPageProps) {
+ * export default function ProductsPage({ productsConfig }: ProductsPageProps) {
  *   return (
- *     <div>
- *       <h1>Search Results for "{searchQuery}"</h1>
- *       <ProductsList.Root productsListConfig={productsListConfig}>
- *         <ProductsList.ItemContent>
- *           {({ product }) => (
- *             <div className="product-item">
- *               <h3>{product.name}</h3>
- *             </div>
- *           )}
- *         </ProductsList.ItemContent>
- *       </ProductsList.Root>
- *     </div>
+ *     <ProductList.Root productsConfig={productsConfig}>
+ *       <ProductList.ItemContent>
+ *         {({ product }) => (
+ *           <div>
+ *             <h3>{product.name}</h3>
+ *             <p>{product.description}</p>
+ *           </div>
+ *         )}
+ *       </ProductList.ItemContent>
+ *     </ProductList.Root>
  *   );
  * }
  * ```
  */
 export declare function loadProductsListServiceConfig(searchOptions: Parameters<typeof productsV3.searchProducts>[0]): Promise<ProductsListServiceConfig>;
+/**
+ * Service definition for the Products List service.
+ * This defines the reactive API contract for managing a list of products with search, pagination, and filtering capabilities.
+ *
+ * @constant
+ */
 export declare const ProductsListServiceDefinition: string & {
     __api: {
+        /** Reactive signal containing the list of products */
         products: Signal<productsV3.V3Product[]>;
+        /** Reactive signal containing aggregation data for filters and facets */
         aggregations: Signal<productsV3.AggregationData>;
+        /** Reactive signal containing pagination metadata */
         pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+        /** Reactive signal containing current search options */
         searchOptions: Signal<Parameters<typeof productsV3.searchProducts>[0]>;
+        /** Reactive signal indicating if products are currently being loaded */
         isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         error: Signal<string | null>;
+        /** Function to update search options and trigger a new search */
         setSearchOptions: (searchOptions: Parameters<typeof productsV3.searchProducts>[0]) => void;
     };
     __config: ProductsListServiceConfig;
     isServiceDefinition?: boolean;
 } & {
+    /** Reactive signal containing the list of products */
     products: Signal<productsV3.V3Product[]>;
+    /** Reactive signal containing aggregation data for filters and facets */
     aggregations: Signal<productsV3.AggregationData>;
+    /** Reactive signal containing pagination metadata */
     pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+    /** Reactive signal containing current search options */
     searchOptions: Signal<Parameters<typeof productsV3.searchProducts>[0]>;
+    /** Reactive signal indicating if products are currently being loaded */
     isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     error: Signal<string | null>;
+    /** Function to update search options and trigger a new search */
     setSearchOptions: (searchOptions: Parameters<typeof productsV3.searchProducts>[0]) => void;
 };
+/**
+ * Implementation of the Products List service that manages reactive products data.
+ * This service provides signals for products data, search options, pagination, aggregations,
+ * loading state, and error handling. It automatically re-fetches products when search options change.
+ *
+ * @example
+ * ```tsx
+ * import { ProductListService, ProductsListServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function ProductsComponent({ productsConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListServiceDefinition, ProductListService.withConfig(productsConfig)]
+ *     ])}>
+ *       <ProductsDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function ProductsDisplay() {
+ *   const productsService = useService(ProductsListServiceDefinition);
+ *   const products = productsService.products.get();
+ *   const isLoading = productsService.isLoading.get();
+ *   const error = productsService.error.get();
+ *
+ *   // Update search options to filter by category
+ *   const filterByCategory = (categoryId: string) => {
+ *     const currentOptions = productsService.searchOptions.get();
+ *     productsService.setSearchOptions({
+ *       ...currentOptions,
+ *       filter: {
+ *         ...currentOptions.filter,
+ *         categoryIds: [categoryId]
+ *       }
+ *     });
+ *   };
+ *
+ *   if (isLoading) return <div>Loading products...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {products.map(product => (
+ *         <div key={product._id}>
+ *           <h3>{product.name}</h3>
+ *           <p>{product.description}</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare const ProductListService: import("@wix/services-definitions").ServiceFactory<string & {
     __api: {
+        /** Reactive signal containing the list of products */
         products: Signal<productsV3.V3Product[]>;
+        /** Reactive signal containing aggregation data for filters and facets */
         aggregations: Signal<productsV3.AggregationData>;
+        /** Reactive signal containing pagination metadata */
         pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+        /** Reactive signal containing current search options */
         searchOptions: Signal<Parameters<typeof productsV3.searchProducts>[0]>;
+        /** Reactive signal indicating if products are currently being loaded */
         isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         error: Signal<string | null>;
+        /** Function to update search options and trigger a new search */
         setSearchOptions: (searchOptions: Parameters<typeof productsV3.searchProducts>[0]) => void;
     };
     __config: ProductsListServiceConfig;
     isServiceDefinition?: boolean;
 } & {
+    /** Reactive signal containing the list of products */
     products: Signal<productsV3.V3Product[]>;
+    /** Reactive signal containing aggregation data for filters and facets */
     aggregations: Signal<productsV3.AggregationData>;
+    /** Reactive signal containing pagination metadata */
     pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+    /** Reactive signal containing current search options */
     searchOptions: Signal<Parameters<typeof productsV3.searchProducts>[0]>;
+    /** Reactive signal indicating if products are currently being loaded */
     isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     error: Signal<string | null>;
+    /** Function to update search options and trigger a new search */
     setSearchOptions: (searchOptions: Parameters<typeof productsV3.searchProducts>[0]) => void;
 }, ProductsListServiceConfig>;