@wix/headless-stores 0.0.30 → 0.0.31

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

@@ -2,6 +2,99 @@ import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import { productsV3 } from "@wix/stores";
 ;
+/**
+ * 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 async function loadProductsListServiceConfig(searchOptions) {
     const result = await productsV3.searchProducts(searchOptions);
     return {

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

@@ -22,4 +22,79 @@ export declare const RelatedProductsService: import("@wix/services-definitions")
     __config: {};
     isServiceDefinition?: boolean;
 } & RelatedProductsServiceAPI, RelatedProductsServiceConfig>;
+/**
+ * Loads related products service configuration for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to create
+ * configuration that tells the RelatedProductsService which product to load related products for.
+ * Unlike other loaders, this creates configuration rather than fetching data during SSR.
+ *
+ * @param productId The ID of the product to find related products for
+ * @param limit Optional number of related products to load (default: 4)
+ * @returns Promise that resolves to RelatedProductsServiceConfig
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * // Create related products config for a specific product
+ * const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *   'product-id-123',
+ *   6
+ * );
+ * ---
+ *
+ * <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *   <RelatedProducts.List>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} related products`}
+ *       </div>
+ *     )}
+ *   </RelatedProducts.List>
+ * </RelatedProducts.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   relatedProductsConfig: Awaited<ReturnType<typeof loadRelatedProductsServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async () => {
+ *   // Create related products config for a specific product
+ *   const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *     'product-id-123',
+ *     6
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       relatedProductsConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ relatedProductsConfig }: ProductPageProps) {
+ *   return (
+ *     <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *       <RelatedProducts.List>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} related products`}
+ *           </div>
+ *         )}
+ *       </RelatedProducts.List>
+ *     </RelatedProducts.Root>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadRelatedProductsServiceConfig(productId: string, limit?: number): Promise<RelatedProductsServiceConfig>;

package/cjs/dist/services/related-products-service.js

@@ -44,6 +44,81 @@ export const RelatedProductsService = implementService.withConfig()(RelatedProdu
         refreshRelatedProducts,
     };
 });
+/**
+ * Loads related products service configuration for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to create
+ * configuration that tells the RelatedProductsService which product to load related products for.
+ * Unlike other loaders, this creates configuration rather than fetching data during SSR.
+ *
+ * @param productId The ID of the product to find related products for
+ * @param limit Optional number of related products to load (default: 4)
+ * @returns Promise that resolves to RelatedProductsServiceConfig
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * // Create related products config for a specific product
+ * const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *   'product-id-123',
+ *   6
+ * );
+ * ---
+ *
+ * <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *   <RelatedProducts.List>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} related products`}
+ *       </div>
+ *     )}
+ *   </RelatedProducts.List>
+ * </RelatedProducts.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   relatedProductsConfig: Awaited<ReturnType<typeof loadRelatedProductsServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async () => {
+ *   // Create related products config for a specific product
+ *   const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *     'product-id-123',
+ *     6
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       relatedProductsConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ relatedProductsConfig }: ProductPageProps) {
+ *   return (
+ *     <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *       <RelatedProducts.List>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} related products`}
+ *           </div>
+ *         )}
+ *       </RelatedProducts.List>
+ *     </RelatedProducts.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadRelatedProductsServiceConfig(productId, limit = 4) {
     return {
         productId,

package/dist/react/Category.d.ts

@@ -11,5 +11,35 @@ export interface CategoryListProps {
  * Headless component for displaying a list of categories
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Category } from '@wix/stores/components';
+ *
+ * function CategoryNavigation() {
+ *   return (
+ *     <Category.List>
+ *       {({ categories, selectedCategory, setSelectedCategory }) => (
+ *         <nav>
+ *           <button
+ *             onClick={() => setSelectedCategory(null)}
+ *             className={selectedCategory === null ? 'active' : ''}
+ *           >
+ *             All Categories
+ *           </button>
+ *           {categories.map(category => (
+ *             <button
+ *               key={category.id}
+ *               onClick={() => setSelectedCategory(category.id)}
+ *               className={selectedCategory === category.id ? 'active' : ''}
+ *             >
+ *               {category.name}
+ *             </button>
+ *           ))}
+ *         </nav>
+ *       )}
+ *     </Category.List>
+ *   );
+ * }
+ * ```
  */
 export declare const List: React.FC<CategoryListProps>;

package/dist/react/Category.js

@@ -5,6 +5,36 @@ import { CategoryServiceDefinition } from "../services/category-service.js";
  * Headless component for displaying a list of categories
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Category } from '@wix/stores/components';
+ *
+ * function CategoryNavigation() {
+ *   return (
+ *     <Category.List>
+ *       {({ categories, selectedCategory, setSelectedCategory }) => (
+ *         <nav>
+ *           <button
+ *             onClick={() => setSelectedCategory(null)}
+ *             className={selectedCategory === null ? 'active' : ''}
+ *           >
+ *             All Categories
+ *           </button>
+ *           {categories.map(category => (
+ *             <button
+ *               key={category.id}
+ *               onClick={() => setSelectedCategory(category.id)}
+ *               className={selectedCategory === category.id ? 'active' : ''}
+ *             >
+ *               {category.name}
+ *             </button>
+ *           ))}
+ *         </nav>
+ *       )}
+ *     </Category.List>
+ *   );
+ * }
+ * ```
  */
 export const List = ({ children }) => {
     const service = useService(CategoryServiceDefinition);

package/dist/react/Collection.d.ts

@@ -27,6 +27,37 @@ export interface GridRenderProps {
  * Headless component for product grid
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function ProductGrid() {
+ *   return (
+ *     <Collection.Grid>
+ *       {({ products, isLoading, error, isEmpty, totalProducts, hasProducts }) => (
+ *         <div>
+ *           {isLoading && <div>Loading products...</div>}
+ *           {error && <div>Error: {error}</div>}
+ *           {isEmpty && <div>No products found</div>}
+ *           {hasProducts && (
+ *             <div>
+ *               <p>Showing {products.length} of {totalProducts} products</p>
+ *               <div className="product-grid">
+ *                 {products.map(product => (
+ *                   <div key={product.id} className="product-card">
+ *                     <h3>{product.name}</h3>
+ *                     <p>{product.price?.price} {product.price?.currency}</p>
+ *                   </div>
+ *                 ))}
+ *               </div>
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.Grid>
+ *   );
+ * }
+ * ```
  */
 export declare const Grid: (props: GridProps) => import("react").ReactNode;
 /**
@@ -63,6 +94,32 @@ export interface ItemRenderProps {
  * Headless component for individual product item
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function ProductCard({ product }) {
+ *   return (
+ *     <Collection.Item product={product}>
+ *       {({ id, title, slug, image, price, compareAtPrice, description, available }) => (
+ *         <div className={`product-card ${!available ? 'unavailable' : ''}`}>
+ *           {image && <img src={image} alt={title} />}
+ *           <h3>{title}</h3>
+ *           <p>{description}</p>
+ *           <div className="pricing">
+ *             <span className="price">{price}</span>
+ *             {compareAtPrice && (
+ *               <span className="compare-price"><s>{compareAtPrice}</s></span>
+ *             )}
+ *           </div>
+ *           {!available && <div className="badge">Out of Stock</div>}
+ *           <a href={`/products/${slug}`}>View Product</a>
+ *         </div>
+ *       )}
+ *     </Collection.Item>
+ *   );
+ * }
+ * ```
  */
 export declare const Item: (props: ItemProps) => import("react").ReactNode;
 /**
@@ -94,6 +151,37 @@ export interface LoadMoreRenderProps {
  * Note: V3 API uses simplified loading without traditional pagination
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function LoadMoreButton() {
+ *   return (
+ *     <Collection.LoadMore>
+ *       {({ loadMore, refresh, isLoading, hasProducts, totalProducts, hasMoreProducts }) => (
+ *         <div className="load-more-section">
+ *           {hasProducts && (
+ *             <div>
+ *               <p>Loaded {totalProducts} products</p>
+ *               <div className="actions">
+ *                 {hasMoreProducts && (
+ *                   <button
+ *                     onClick={loadMore}
+ *                     disabled={isLoading}
+ *                   >
+ *                     {isLoading ? 'Loading...' : 'Load More Products'}
+ *                   </button>
+ *                 )}
+ *                 <button onClick={refresh}>Refresh Collection</button>
+ *               </div>
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.LoadMore>
+ *   );
+ * }
+ * ```
  */
 export declare const LoadMore: (props: LoadMoreProps) => import("react").ReactNode;
 /**
@@ -118,6 +206,28 @@ export interface HeaderRenderProps {
  * Headless component for collection header with product count
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function CollectionHeader() {
+ *   return (
+ *     <Collection.Header>
+ *       {({ totalProducts, isLoading, hasProducts }) => (
+ *         <div className="collection-header">
+ *           {isLoading && <div>Loading collection...</div>}
+ *           {hasProducts && !isLoading && (
+ *             <h2>Products ({totalProducts} items)</h2>
+ *           )}
+ *           {!hasProducts && !isLoading && (
+ *             <h2>No products found</h2>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.Header>
+ *   );
+ * }
+ * ```
  */
 export declare const Header: (props: HeaderProps) => import("react").ReactNode;
 /**
@@ -145,5 +255,40 @@ export interface ActionsRenderProps {
  * Replaces traditional pagination for V3 API
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function CollectionActions() {
+ *   return (
+ *     <Collection.Actions>
+ *       {({ refresh, loadMore, isLoading, error }) => (
+ *         <div className="collection-actions">
+ *           {error && (
+ *             <div className="error">
+ *               Error: {error}
+ *               <button onClick={refresh}>Retry</button>
+ *             </div>
+ *           )}
+ *           <div className="action-buttons">
+ *             <button
+ *               onClick={refresh}
+ *               disabled={isLoading}
+ *             >
+ *               {isLoading ? 'Refreshing...' : 'Refresh'}
+ *             </button>
+ *             <button
+ *               onClick={loadMore}
+ *               disabled={isLoading}
+ *             >
+ *               Load More
+ *             </button>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </Collection.Actions>
+ *   );
+ * }
+ * ```
  */
 export declare const Actions: (props: ActionsProps) => import("react").ReactNode;

package/dist/react/Collection.js

@@ -5,6 +5,37 @@ import { InventoryAvailabilityStatus, } from "@wix/auto_sdk_stores_products-v-3"
  * Headless component for product grid
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function ProductGrid() {
+ *   return (
+ *     <Collection.Grid>
+ *       {({ products, isLoading, error, isEmpty, totalProducts, hasProducts }) => (
+ *         <div>
+ *           {isLoading && <div>Loading products...</div>}
+ *           {error && <div>Error: {error}</div>}
+ *           {isEmpty && <div>No products found</div>}
+ *           {hasProducts && (
+ *             <div>
+ *               <p>Showing {products.length} of {totalProducts} products</p>
+ *               <div className="product-grid">
+ *                 {products.map(product => (
+ *                   <div key={product.id} className="product-card">
+ *                     <h3>{product.name}</h3>
+ *                     <p>{product.price?.price} {product.price?.currency}</p>
+ *                   </div>
+ *                 ))}
+ *               </div>
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.Grid>
+ *   );
+ * }
+ * ```
  */
 export const Grid = (props) => {
     const service = useService(CollectionServiceDefinition);
@@ -52,6 +83,32 @@ export const Grid = (props) => {
  * Headless component for individual product item
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function ProductCard({ product }) {
+ *   return (
+ *     <Collection.Item product={product}>
+ *       {({ id, title, slug, image, price, compareAtPrice, description, available }) => (
+ *         <div className={`product-card ${!available ? 'unavailable' : ''}`}>
+ *           {image && <img src={image} alt={title} />}
+ *           <h3>{title}</h3>
+ *           <p>{description}</p>
+ *           <div className="pricing">
+ *             <span className="price">{price}</span>
+ *             {compareAtPrice && (
+ *               <span className="compare-price"><s>{compareAtPrice}</s></span>
+ *             )}
+ *           </div>
+ *           {!available && <div className="badge">Out of Stock</div>}
+ *           <a href={`/products/${slug}`}>View Product</a>
+ *         </div>
+ *       )}
+ *     </Collection.Item>
+ *   );
+ * }
+ * ```
  */
 export const Item = (props) => {
     const { product } = props;
@@ -84,6 +141,37 @@ export const Item = (props) => {
  * Note: V3 API uses simplified loading without traditional pagination
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function LoadMoreButton() {
+ *   return (
+ *     <Collection.LoadMore>
+ *       {({ loadMore, refresh, isLoading, hasProducts, totalProducts, hasMoreProducts }) => (
+ *         <div className="load-more-section">
+ *           {hasProducts && (
+ *             <div>
+ *               <p>Loaded {totalProducts} products</p>
+ *               <div className="actions">
+ *                 {hasMoreProducts && (
+ *                   <button
+ *                     onClick={loadMore}
+ *                     disabled={isLoading}
+ *                   >
+ *                     {isLoading ? 'Loading...' : 'Load More Products'}
+ *                   </button>
+ *                 )}
+ *                 <button onClick={refresh}>Refresh Collection</button>
+ *               </div>
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.LoadMore>
+ *   );
+ * }
+ * ```
  */
 export const LoadMore = (props) => {
     const service = useService(CollectionServiceDefinition);
@@ -129,6 +217,28 @@ export const LoadMore = (props) => {
  * Headless component for collection header with product count
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function CollectionHeader() {
+ *   return (
+ *     <Collection.Header>
+ *       {({ totalProducts, isLoading, hasProducts }) => (
+ *         <div className="collection-header">
+ *           {isLoading && <div>Loading collection...</div>}
+ *           {hasProducts && !isLoading && (
+ *             <h2>Products ({totalProducts} items)</h2>
+ *           )}
+ *           {!hasProducts && !isLoading && (
+ *             <h2>No products found</h2>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Collection.Header>
+ *   );
+ * }
+ * ```
  */
 export const Header = (props) => {
     const service = useService(CollectionServiceDefinition);
@@ -165,6 +275,41 @@ export const Header = (props) => {
  * Replaces traditional pagination for V3 API
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Collection } from '@wix/stores/components';
+ *
+ * function CollectionActions() {
+ *   return (
+ *     <Collection.Actions>
+ *       {({ refresh, loadMore, isLoading, error }) => (
+ *         <div className="collection-actions">
+ *           {error && (
+ *             <div className="error">
+ *               Error: {error}
+ *               <button onClick={refresh}>Retry</button>
+ *             </div>
+ *           )}
+ *           <div className="action-buttons">
+ *             <button
+ *               onClick={refresh}
+ *               disabled={isLoading}
+ *             >
+ *               {isLoading ? 'Refreshing...' : 'Refresh'}
+ *             </button>
+ *             <button
+ *               onClick={loadMore}
+ *               disabled={isLoading}
+ *             >
+ *               Load More
+ *             </button>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </Collection.Actions>
+ *   );
+ * }
+ * ```
  */
 export const Actions = (props) => {
     const service = useService(CollectionServiceDefinition);