@wix/headless-stores 0.0.30 → 0.0.32

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

@@ -21,6 +21,93 @@ export declare const CategoryService: import("@wix/services-definitions").Servic
     __config: {};
     isServiceDefinition?: boolean;
 } & CategoryServiceAPI, CategoryServiceConfig>;
+/**
+ * Loads categories configuration from the Wix Categories API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * initial categories data that will be passed to the Category.Root component.
+ * Fetches all visible categories and sorts them with "all-products" category first.
+ *
+ * @returns Promise that resolves to an object containing categories array
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/categories.astro
+ * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { Category } from '@wix/stores/components';
+ *
+ * // Load categories data during SSR
+ * const categoryConfig = await loadCategoriesConfig();
+ * ---
+ *
+ * <Category.Root categoryConfig={categoryConfig}>
+ *   <Category.List>
+ *     {({ categories, selectedCategory, setSelectedCategory }) => (
+ *       <nav className="category-nav">
+ *         <h2>Shop by Category</h2>
+ *         {categories.map(category => (
+ *           <button
+ *             key={category.id}
+ *             onClick={() => setSelectedCategory(category.id)}
+ *             className={selectedCategory === category.id ? 'active' : ''}
+ *           >
+ *             {category.name}
+ *           </button>
+ *         ))}
+ *       </nav>
+ *     )}
+ *   </Category.List>
+ * </Category.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/categories.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { Category } from '@wix/stores/components';
+ *
+ * interface CategoryPageProps {
+ *   categoryConfig: Awaited<ReturnType<typeof loadCategoriesConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async () => {
+ *   // Load categories data during SSR
+ *   const categoryConfig = await loadCategoriesConfig();
+ *
+ *   return {
+ *     props: {
+ *       categoryConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function CategoryPage({ categoryConfig }: CategoryPageProps) {
+ *   return (
+ *     <div>
+ *       <h1>Product Categories</h1>
+ *       <Category.Root categoryConfig={categoryConfig}>
+ *         <Category.List>
+ *           {({ categories, selectedCategory, setSelectedCategory }) => (
+ *             <nav className="category-nav">
+ *               {categories.map(category => (
+ *                 <button
+ *                   key={category.id}
+ *                   onClick={() => setSelectedCategory(category.id)}
+ *                   className={`category-btn ${selectedCategory === category.id ? 'active' : ''}`}
+ *                 >
+ *                   {category.name}
+ *                 </button>
+ *               ))}
+ *             </nav>
+ *           )}
+ *         </Category.List>
+ *       </Category.Root>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadCategoriesConfig(): Promise<{
     categories: categories.Category[];
 }>;

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

@@ -38,6 +38,93 @@ export const CategoryService = implementService.withConfig()(CategoryServiceDefi
         loadCategories,
     };
 });
+/**
+ * Loads categories configuration from the Wix Categories API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * initial categories data that will be passed to the Category.Root component.
+ * Fetches all visible categories and sorts them with "all-products" category first.
+ *
+ * @returns Promise that resolves to an object containing categories array
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/categories.astro
+ * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { Category } from '@wix/stores/components';
+ *
+ * // Load categories data during SSR
+ * const categoryConfig = await loadCategoriesConfig();
+ * ---
+ *
+ * <Category.Root categoryConfig={categoryConfig}>
+ *   <Category.List>
+ *     {({ categories, selectedCategory, setSelectedCategory }) => (
+ *       <nav className="category-nav">
+ *         <h2>Shop by Category</h2>
+ *         {categories.map(category => (
+ *           <button
+ *             key={category.id}
+ *             onClick={() => setSelectedCategory(category.id)}
+ *             className={selectedCategory === category.id ? 'active' : ''}
+ *           >
+ *             {category.name}
+ *           </button>
+ *         ))}
+ *       </nav>
+ *     )}
+ *   </Category.List>
+ * </Category.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/categories.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { Category } from '@wix/stores/components';
+ *
+ * interface CategoryPageProps {
+ *   categoryConfig: Awaited<ReturnType<typeof loadCategoriesConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async () => {
+ *   // Load categories data during SSR
+ *   const categoryConfig = await loadCategoriesConfig();
+ *
+ *   return {
+ *     props: {
+ *       categoryConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function CategoryPage({ categoryConfig }: CategoryPageProps) {
+ *   return (
+ *     <div>
+ *       <h1>Product Categories</h1>
+ *       <Category.Root categoryConfig={categoryConfig}>
+ *         <Category.List>
+ *           {({ categories, selectedCategory, setSelectedCategory }) => (
+ *             <nav className="category-nav">
+ *               {categories.map(category => (
+ *                 <button
+ *                   key={category.id}
+ *                   onClick={() => setSelectedCategory(category.id)}
+ *                   className={`category-btn ${selectedCategory === category.id ? 'active' : ''}`}
+ *                 >
+ *                   {category.name}
+ *                 </button>
+ *               ))}
+ *             </nav>
+ *           )}
+ *         </Category.List>
+ *       </Category.Root>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export async function loadCategoriesConfig() {
     try {
         const categoriesResponse = await categories

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

@@ -29,6 +29,95 @@ export declare const CollectionService: import("@wix/services-definitions").Serv
     __config: {};
     isServiceDefinition?: boolean;
 } & CollectionServiceAPI, CollectionServiceConfig>;
+/**
+ * Loads collection service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * initial products data, categories, filters, and sorting that will be used to configure the CollectionService.
+ * Fetches products for a specific category, parses URL parameters for filters and sorting, and returns initial state.
+ *
+ * @param categoryId Optional category ID to filter products by
+ * @param searchParams Optional URLSearchParams for initial filters and sorting
+ * @param preloadedCategories Optional pre-loaded categories to avoid redundant API calls
+ * @returns Promise that resolves to CollectionServiceConfig with initial data
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/products/[categorySlug].astro
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * // Get category from URL params
+ * const { categorySlug } = Astro.params;
+ * const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ * // Load collection data during SSR
+ * const collectionConfig = await loadCollectionServiceConfig(
+ *   categoryId,
+ *   Astro.url.searchParams
+ * );
+ * ---
+ *
+ * <Collection.Root collectionConfig={collectionConfig}>
+ *   <Collection.Grid>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} products`}
+ *       </div>
+ *     )}
+ *   </Collection.Grid>
+ * </Collection.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/products/[categorySlug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * interface ProductsPageProps {
+ *   collectionConfig: Awaited<ReturnType<typeof loadCollectionServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async ({ params, query }) => {
+ *   const categorySlug = params?.categorySlug as string;
+ *   const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ *   // Convert Next.js query to URLSearchParams
+ *   const searchParams = new URLSearchParams();
+ *   Object.entries(query).forEach(([key, value]) => {
+ *     if (typeof value === 'string') searchParams.set(key, value);
+ *   });
+ *
+ *   // Load collection data during SSR
+ *   const collectionConfig = await loadCollectionServiceConfig(
+ *     categoryId,
+ *     searchParams
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       collectionConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductsPage({ collectionConfig }: ProductsPageProps) {
+ *   return (
+ *     <Collection.Root collectionConfig={collectionConfig}>
+ *       <Collection.Grid>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} products`}
+ *           </div>
+ *         )}
+ *       </Collection.Grid>
+ *     </Collection.Root>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadCollectionServiceConfig(categoryId?: string, searchParams?: URLSearchParams, preloadedCategories?: any[]): Promise<CollectionServiceConfig & {
     initialSort?: SortBy;
     initialFilters?: Filter;

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

@@ -432,6 +432,95 @@ function parseOptionFilters(urlParams, optionsMap, filters) {
         }
     });
 }
+/**
+ * Loads collection service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * initial products data, categories, filters, and sorting that will be used to configure the CollectionService.
+ * Fetches products for a specific category, parses URL parameters for filters and sorting, and returns initial state.
+ *
+ * @param categoryId Optional category ID to filter products by
+ * @param searchParams Optional URLSearchParams for initial filters and sorting
+ * @param preloadedCategories Optional pre-loaded categories to avoid redundant API calls
+ * @returns Promise that resolves to CollectionServiceConfig with initial data
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/products/[categorySlug].astro
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * // Get category from URL params
+ * const { categorySlug } = Astro.params;
+ * const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ * // Load collection data during SSR
+ * const collectionConfig = await loadCollectionServiceConfig(
+ *   categoryId,
+ *   Astro.url.searchParams
+ * );
+ * ---
+ *
+ * <Collection.Root collectionConfig={collectionConfig}>
+ *   <Collection.Grid>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} products`}
+ *       </div>
+ *     )}
+ *   </Collection.Grid>
+ * </Collection.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/products/[categorySlug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * interface ProductsPageProps {
+ *   collectionConfig: Awaited<ReturnType<typeof loadCollectionServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async ({ params, query }) => {
+ *   const categorySlug = params?.categorySlug as string;
+ *   const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ *   // Convert Next.js query to URLSearchParams
+ *   const searchParams = new URLSearchParams();
+ *   Object.entries(query).forEach(([key, value]) => {
+ *     if (typeof value === 'string') searchParams.set(key, value);
+ *   });
+ *
+ *   // Load collection data during SSR
+ *   const collectionConfig = await loadCollectionServiceConfig(
+ *     categoryId,
+ *     searchParams
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       collectionConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductsPage({ collectionConfig }: ProductsPageProps) {
+ *   return (
+ *     <Collection.Root collectionConfig={collectionConfig}>
+ *       <Collection.Grid>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} products`}
+ *           </div>
+ *         )}
+ *       </Collection.Grid>
+ *     </Collection.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadCollectionServiceConfig(categoryId, searchParams, preloadedCategories) {
     try {
         // Use pre-loaded categories if provided, otherwise load them

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

@@ -19,10 +19,87 @@ export declare const ProductService: import("@wix/services-definitions").Service
     __config: {};
     isServiceDefinition?: boolean;
 } & ProductServiceAPI, ProductServiceConfig>;
-export type ProductServiceConfigResult = {
+export interface SuccessProductServiceConfigResult {
     type: "success";
     config: ProductServiceConfig;
-} | {
+}
+export interface NotFoundProductServiceConfigResult {
     type: "notFound";
-};
-export declare function loadProductServiceConfig(productSlug: string): Promise<ProductServiceConfigResult>;
+}
+/**
+ * Loads product service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific product by slug that will be used to configure the ProductService.
+ *
+ * @param productSlug The product slug to load
+ * @returns Promise that resolves to ProductServiceConfigResult (success with config or notFound)
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * // Get product slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load product data during SSR
+ * const productResult = await loadProductServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (productResult.type === 'notFound') {
+ *   return Astro.redirect('/404');
+ * }
+ * ---
+ *
+ * <Product.Root productConfig={productResult.config}>
+ *   <Product.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Product.Name>
+ * </Product.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   productConfig: Awaited<ReturnType<typeof loadProductServiceConfig>>['config'];
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load product data during SSR
+ *   const productResult = await loadProductServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (productResult.type === 'notFound') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
+ *
+ *   return {
+ *     props: {
+ *       productConfig: productResult.config,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ productConfig }: ProductPageProps) {
+ *   return (
+ *     <Product.Root productConfig={productConfig}>
+ *       <Product.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Product.Name>
+ *     </Product.Root>
+ *   );
+ * }
+ * ```
+ */
+export declare function loadProductServiceConfig(productSlug: string): Promise<SuccessProductServiceConfigResult | NotFoundProductServiceConfigResult>;

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

@@ -43,6 +43,82 @@ const loadProductBySlug = async (slug) => {
     });
     return productResponse;
 };
+/**
+ * Loads product service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific product by slug that will be used to configure the ProductService.
+ *
+ * @param productSlug The product slug to load
+ * @returns Promise that resolves to ProductServiceConfigResult (success with config or notFound)
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * // Get product slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load product data during SSR
+ * const productResult = await loadProductServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (productResult.type === 'notFound') {
+ *   return Astro.redirect('/404');
+ * }
+ * ---
+ *
+ * <Product.Root productConfig={productResult.config}>
+ *   <Product.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Product.Name>
+ * </Product.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   productConfig: Awaited<ReturnType<typeof loadProductServiceConfig>>['config'];
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load product data during SSR
+ *   const productResult = await loadProductServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (productResult.type === 'notFound') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
+ *
+ *   return {
+ *     props: {
+ *       productConfig: productResult.config,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ productConfig }: ProductPageProps) {
+ *   return (
+ *     <Product.Root productConfig={productConfig}>
+ *       <Product.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Product.Name>
+ *     </Product.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadProductServiceConfig(productSlug) {
     try {
         // Use getProductBySlug directly - single API call with comprehensive fields

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

@@ -6,6 +6,99 @@ export interface ProductsListServiceConfig {
     pagingMetadata: productsV3.CommonCursorPagingMetadata;
     aggregations: productsV3.AggregationData;
 }
+/**
+ * Loads products list service configuration from the Wix Products 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.
+ *
+ * @param searchOptions Search options for filtering and querying products
+ * @returns Promise that resolves to ProductsListServiceConfig with products, metadata, and aggregations
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/search.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');
+ *
+ * // Build search options
+ * const searchOptions = {
+ *   query: { search: searchQuery },
+ *   filter: category ? { categories: [category] } : undefined,
+ *   paging: { limit: 12 }
+ * };
+ *
+ * // Load products during SSR
+ * const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ * ---
+ *
+ * <ProductsList.Root productsListConfig={productsListConfig}>
+ *   <ProductsList.ItemContent>
+ *     {({ product }) => (
+ *       <div class="product-item">
+ *         <h3>{product.name}</h3>
+ *       </div>
+ *     )}
+ *   </ProductsList.ItemContent>
+ * </ProductsList.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/search.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;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<SearchPageProps> = async ({ query }) => {
+ *   const searchQuery = (query.q as string) || '';
+ *   const category = query.category as string;
+ *
+ *   // Build search options
+ *   const searchOptions = {
+ *     query: { search: searchQuery },
+ *     filter: category ? { categories: [category] } : undefined,
+ *     paging: { limit: 12 }
+ *   };
+ *
+ *   // Load products during SSR
+ *   const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ *
+ *   return {
+ *     props: {
+ *       productsListConfig,
+ *       searchQuery,
+ *     },
+ *   };
+ * };
+ *
+ * export default function SearchPage({ productsListConfig, searchQuery }: SearchPageProps) {
+ *   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>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadProductsListServiceConfig(searchOptions: Parameters<typeof productsV3.searchProducts>[0]): Promise<ProductsListServiceConfig>;
 export declare const ProductsListServiceDefinition: string & {
     __api: {