@wix/headless-stores 0.0.29 → 0.0.31

package/cjs/dist/react/ProductsList.js

@@ -8,10 +8,33 @@ import { ProductService, ProductServiceDefinition, } from "@wix/headless-stores/
  * This component sets up the necessary services for managing products list state.
  *
  * @component
- * @param props - Component props
- * @param props.children - Child components that will have access to the ProductsList service
- * @param props.productsListConfig - Configuration for the ProductsList service
- * @returns JSX element wrapping children with ProductsList service context
+ * @example
+ * ```tsx
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * function ProductsListPage() {
+ *   return (
+ *     <ProductsList.Root
+ *       productsListConfig={{
+ *         collectionId: 'my-collection-id',
+ *         filters: { price: { min: 10, max: 100 } }
+ *       }}
+ *     >
+ *       <ProductsList.Grid>
+ *         {({ products, isLoading, error }) => (
+ *           <div>
+ *             {isLoading && <div>Loading products...</div>}
+ *             {error && <div>Error: {error}</div>}
+ *             {products.map(product => (
+ *               <div key={product.id}>{product.name}</div>
+ *             ))}
+ *           </div>
+ *         )}
+ *       </ProductsList.Grid>
+ *     </ProductsList.Root>
+ *   );
+ * }
+ * ```
  */
 export function Root(props) {
     return (_jsx(WixServices, { servicesMap: createServicesMap().addService(ProductsListServiceDefinition, ProductListService, props.productsListConfig), children: props.children }));
@@ -21,9 +44,24 @@ export function Root(props) {
  * Only displays its children when there are no products, no loading state, and no errors.
  *
  * @component
- * @param props - Component props
- * @param props.children - Content to display when products list is empty (can be a render function or ReactNode)
- * @returns JSX element or null based on products list state
+ * @example
+ * ```tsx
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * function EmptyProductsMessage() {
+ *   return (
+ *     <ProductsList.EmptyState>
+ *       {() => (
+ *         <div className="empty-state">
+ *           <h3>No products found</h3>
+ *           <p>Try adjusting your search or filter criteria</p>
+ *           <button>Clear Filters</button>
+ *         </div>
+ *       )}
+ *     </ProductsList.EmptyState>
+ *   );
+ * }
+ * ```
  */
 export function EmptyState(props) {
     const { isLoading, error, products } = useService(ProductsListServiceDefinition);
@@ -42,9 +80,23 @@ export function EmptyState(props) {
  * Only displays its children when the products list is currently loading.
  *
  * @component
- * @param props - Component props
- * @param props.children - Content to display during loading (can be a render function or ReactNode)
- * @returns JSX element or null based on loading state
+ * @example
+ * ```tsx
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * function ProductsLoading() {
+ *   return (
+ *     <ProductsList.Loading>
+ *       {() => (
+ *         <div className="loading-spinner">
+ *           <div>Loading products...</div>
+ *           <div className="spinner"></div>
+ *         </div>
+ *       )}
+ *     </ProductsList.Loading>
+ *   );
+ * }
+ * ```
  */
 export function Loading(props) {
     const { isLoading } = useService(ProductsListServiceDefinition);
@@ -62,9 +114,26 @@ export function Loading(props) {
  * Only displays its children when an error has occurred.
  *
  * @component
- * @param props - Component props
- * @param props.children - Content to display during error state (can be a render function or ReactNode)
- * @returns JSX element or null based on error state
+ * @example
+ * ```tsx
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * function ProductsError() {
+ *   return (
+ *     <ProductsList.Error>
+ *       {({ error }) => (
+ *         <div className="error-state">
+ *           <h3>Error loading products</h3>
+ *           <p>{error}</p>
+ *           <button onClick={() => window.location.reload()}>
+ *             Try Again
+ *           </button>
+ *         </div>
+ *       )}
+ *     </ProductsList.Error>
+ *   );
+ * }
+ * ```
  */
 export function Error(props) {
     const { error } = useService(ProductsListServiceDefinition);
@@ -82,9 +151,25 @@ export function Error(props) {
  * Only renders when products are successfully loaded (not loading, no error, and has products).
  *
  * @component
- * @param props - Component props
- * @param props.children - Content to display for each product (can be a render function receiving product data or ReactNode)
- * @returns Array of JSX elements for each product or null if no products to display
+ * @example
+ * ```tsx
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * function ProductsGrid() {
+ *   return (
+ *     <ProductsList.ItemContent>
+ *       {({ product }) => (
+ *         <div className="product-card">
+ *           <img src={product.media?.main?.image} alt={product.name} />
+ *           <h3>{product.name}</h3>
+ *           <p>{product.actualPriceRange?.minValue?.formattedAmount}</p>
+ *           <button>View Details</button>
+ *         </div>
+ *       )}
+ *     </ProductsList.ItemContent>
+ *   );
+ * }
+ * ```
  */
 export function ItemContent(props) {
     const { products, isLoading, error } = useService(ProductsListServiceDefinition);

package/cjs/dist/react/RelatedProducts.d.ts

@@ -26,6 +26,35 @@ export interface ListRenderProps {
  * Headless component for displaying related products list
  *
  * @component
+ * @example
+ * ```tsx
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * function RecommendedProducts() {
+ *   return (
+ *     <RelatedProducts.List>
+ *       {({ products, isLoading, error, hasProducts, refresh }) => (
+ *         <div>
+ *           <h3>You might also like</h3>
+ *           {isLoading && <div>Loading related products...</div>}
+ *           {error && <div>Error: {error}</div>}
+ *           {hasProducts && (
+ *             <div className="products-grid">
+ *               {products.map(product => (
+ *                 <div key={product.id}>
+ *                   <h4>{product.name}</h4>
+ *                   <p>{product.price?.price} {product.price?.currency}</p>
+ *                 </div>
+ *               ))}
+ *             </div>
+ *           )}
+ *           <button onClick={refresh}>Refresh Recommendations</button>
+ *         </div>
+ *       )}
+ *     </RelatedProducts.List>
+ *   );
+ * }
+ * ```
  */
 export declare const List: (props: ListProps) => React.ReactNode;
 /**
@@ -58,5 +87,31 @@ export interface ItemRenderProps {
  * Headless component for individual related product item
  *
  * @component
+ * @example
+ * ```tsx
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * function RelatedProductCard({ product }) {
+ *   return (
+ *     <RelatedProducts.Item product={product}>
+ *       {({ title, image, price, available, description, onQuickAdd }) => (
+ *         <div className={`related-product ${!available ? 'unavailable' : ''}`}>
+ *           {image && <img src={image} alt={title} />}
+ *           <h4>{title}</h4>
+ *           {description && <p>{description}</p>}
+ *           <div className="price">{price}</div>
+ *           {!available && <div className="badge">Out of Stock</div>}
+ *           <div className="actions">
+ *             <button onClick={onQuickAdd} disabled={!available}>
+ *               Quick Add
+ *             </button>
+ *             <a href={`/product/${product.slug}`}>View Details</a>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </RelatedProducts.Item>
+ *   );
+ * }
+ * ```
  */
 export declare const Item: (props: ItemProps) => React.ReactNode;

package/cjs/dist/react/RelatedProducts.js

@@ -7,6 +7,35 @@ import { InventoryAvailabilityStatus, } from "@wix/auto_sdk_stores_products-v-3"
  * Headless component for displaying related products list
  *
  * @component
+ * @example
+ * ```tsx
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * function RecommendedProducts() {
+ *   return (
+ *     <RelatedProducts.List>
+ *       {({ products, isLoading, error, hasProducts, refresh }) => (
+ *         <div>
+ *           <h3>You might also like</h3>
+ *           {isLoading && <div>Loading related products...</div>}
+ *           {error && <div>Error: {error}</div>}
+ *           {hasProducts && (
+ *             <div className="products-grid">
+ *               {products.map(product => (
+ *                 <div key={product.id}>
+ *                   <h4>{product.name}</h4>
+ *                   <p>{product.price?.price} {product.price?.currency}</p>
+ *                 </div>
+ *               ))}
+ *             </div>
+ *           )}
+ *           <button onClick={refresh}>Refresh Recommendations</button>
+ *         </div>
+ *       )}
+ *     </RelatedProducts.List>
+ *   );
+ * }
+ * ```
  */
 export const List = (props) => {
     const service = useService(RelatedProductsServiceDefinition);
@@ -44,6 +73,32 @@ export const List = (props) => {
  * Headless component for individual related product item
  *
  * @component
+ * @example
+ * ```tsx
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * function RelatedProductCard({ product }) {
+ *   return (
+ *     <RelatedProducts.Item product={product}>
+ *       {({ title, image, price, available, description, onQuickAdd }) => (
+ *         <div className={`related-product ${!available ? 'unavailable' : ''}`}>
+ *           {image && <img src={image} alt={title} />}
+ *           <h4>{title}</h4>
+ *           {description && <p>{description}</p>}
+ *           <div className="price">{price}</div>
+ *           {!available && <div className="badge">Out of Stock</div>}
+ *           <div className="actions">
+ *             <button onClick={onQuickAdd} disabled={!available}>
+ *               Quick Add
+ *             </button>
+ *             <a href={`/product/${product.slug}`}>View Details</a>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </RelatedProducts.Item>
+ *   );
+ * }
+ * ```
  */
 export const Item = (props) => {
     const { product } = props;

package/cjs/dist/react/SelectedVariant.d.ts

@@ -18,6 +18,23 @@ export interface ProductDetailsRenderProps {
  * Headless component for selected variant details display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function VariantDetails() {
+ *   return (
+ *     <SelectedVariant.Details>
+ *       {({ sku, weight }) => (
+ *         <div>
+ *           {sku && <div>SKU: {sku}</div>}
+ *           {weight && <div>Weight: {weight}</div>}
+ *         </div>
+ *       )}
+ *     </SelectedVariant.Details>
+ *   );
+ * }
+ * ```
  */
 export declare const Details: (props: ProductDetailsProps) => import("react").ReactNode;
 /**
@@ -42,6 +59,28 @@ export interface PriceRenderProps {
  * Headless component for product price display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function ProductPrice() {
+ *   return (
+ *     <SelectedVariant.Price>
+ *       {({ price, compareAtPrice, currency }) => (
+ *         <div className="price-display">
+ *           <span className="current-price">{price}</span>
+ *           {compareAtPrice && (
+ *             <span className="compare-price">
+ *               <s>{compareAtPrice}</s>
+ *             </span>
+ *           )}
+ *           <span className="currency">{currency}</span>
+ *         </div>
+ *       )}
+ *     </SelectedVariant.Price>
+ *   );
+ * }
+ * ```
  */
 export declare const Price: (props: PriceProps) => import("react").ReactNode;
 /**
@@ -62,5 +101,25 @@ export interface SKURenderProps {
  * Headless component for product SKU display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function ProductSKU() {
+ *   return (
+ *     <SelectedVariant.SKU>
+ *       {({ sku }) => (
+ *         <div>
+ *           {sku && (
+ *             <div className="product-sku">
+ *               <strong>SKU:</strong> {sku}
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </SelectedVariant.SKU>
+ *   );
+ * }
+ * ```
  */
 export declare const SKU: (props: SKUProps) => import("react").ReactNode;

package/cjs/dist/react/SelectedVariant.js

@@ -4,6 +4,23 @@ import { SelectedVariantServiceDefinition } from "../services/selected-variant-s
  * Headless component for selected variant details display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function VariantDetails() {
+ *   return (
+ *     <SelectedVariant.Details>
+ *       {({ sku, weight }) => (
+ *         <div>
+ *           {sku && <div>SKU: {sku}</div>}
+ *           {weight && <div>Weight: {weight}</div>}
+ *         </div>
+ *       )}
+ *     </SelectedVariant.Details>
+ *   );
+ * }
+ * ```
  */
 export const Details = (props) => {
     const selectedVariantService = useService(SelectedVariantServiceDefinition);
@@ -19,6 +36,28 @@ export const Details = (props) => {
  * Headless component for product price display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function ProductPrice() {
+ *   return (
+ *     <SelectedVariant.Price>
+ *       {({ price, compareAtPrice, currency }) => (
+ *         <div className="price-display">
+ *           <span className="current-price">{price}</span>
+ *           {compareAtPrice && (
+ *             <span className="compare-price">
+ *               <s>{compareAtPrice}</s>
+ *             </span>
+ *           )}
+ *           <span className="currency">{currency}</span>
+ *         </div>
+ *       )}
+ *     </SelectedVariant.Price>
+ *   );
+ * }
+ * ```
  */
 export const Price = (props) => {
     const variantService = useService(SelectedVariantServiceDefinition);
@@ -35,6 +74,26 @@ export const Price = (props) => {
  * Headless component for product SKU display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SelectedVariant } from '@wix/stores/components';
+ *
+ * function ProductSKU() {
+ *   return (
+ *     <SelectedVariant.SKU>
+ *       {({ sku }) => (
+ *         <div>
+ *           {sku && (
+ *             <div className="product-sku">
+ *               <strong>SKU:</strong> {sku}
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </SelectedVariant.SKU>
+ *   );
+ * }
+ * ```
  */
 export const SKU = (props) => {
     const selectedVariantService = useService(SelectedVariantServiceDefinition);

package/cjs/dist/react/SocialSharing.d.ts

@@ -40,6 +40,43 @@ export interface RootRenderProps {
  * Headless component for social sharing root
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function ShareProduct() {
+ *   const productUrl = 'https://example.com/product/123';
+ *   const productTitle = 'Amazing Product';
+ *
+ *   return (
+ *     <SocialSharing.Root>
+ *       {({ platforms, shareCount, shareFacebook, shareTwitter, copyLink, shareNative }) => (
+ *         <div>
+ *           <p>Share this product ({shareCount} shares)</p>
+ *           <div className="share-buttons">
+ *             <button onClick={() => shareFacebook(productUrl, productTitle)}>
+ *               Share on Facebook
+ *             </button>
+ *             <button onClick={() => shareTwitter(productUrl, `Check out ${productTitle}!`)}>
+ *               Share on Twitter
+ *             </button>
+ *             <button onClick={() => copyLink(productUrl)}>
+ *               Copy Link
+ *             </button>
+ *             <button onClick={() => shareNative({
+ *               title: productTitle,
+ *               text: 'Check this out!',
+ *               url: productUrl
+ *             })}>
+ *               Share
+ *             </button>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </SocialSharing.Root>
+ *   );
+ * }
+ * ```
  */
 export declare const Root: (props: RootProps) => React.ReactNode;
 /**
@@ -66,6 +103,26 @@ export interface PlatformRenderProps {
  * Headless component for individual social platform
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function SocialButton({ platform, onClick }) {
+ *   return (
+ *     <SocialSharing.Platform platform={platform} onClick={onClick}>
+ *       {({ platform, onSelect }) => (
+ *         <button
+ *           onClick={onSelect}
+ *           className={`social-btn social-btn-${platform.name.toLowerCase()}`}
+ *         >
+ *           <span className="icon">{platform.icon}</span>
+ *           Share on {platform.name}
+ *         </button>
+ *       )}
+ *     </SocialSharing.Platform>
+ *   );
+ * }
+ * ```
  */
 export declare const Platform: (props: PlatformProps) => React.ReactNode;
 /**
@@ -108,5 +165,30 @@ export interface PlatformsRenderProps {
  * Headless component for social sharing platforms with logic
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function SocialShareButtons() {
+ *   return (
+ *     <SocialSharing.Platforms
+ *       url="https://example.com/product/123"
+ *       title="Amazing Product"
+ *       description="Check out this amazing product!"
+ *       hashtags={['product', 'amazing']}
+ *     >
+ *       {({ platforms, shareFacebook, shareTwitter, shareLinkedIn, copyLink, shareNative }) => (
+ *         <div className="social-platforms">
+ *           <button onClick={shareFacebook}>Share on Facebook</button>
+ *           <button onClick={shareTwitter}>Share on Twitter</button>
+ *           <button onClick={shareLinkedIn}>Share on LinkedIn</button>
+ *           <button onClick={() => copyLink()}>Copy Link</button>
+ *           <button onClick={() => shareNative()}>Share</button>
+ *         </div>
+ *       )}
+ *     </SocialSharing.Platforms>
+ *   );
+ * }
+ * ```
  */
 export declare const Platforms: (props: PlatformsProps) => React.ReactNode;

package/cjs/dist/react/SocialSharing.js

@@ -6,6 +6,43 @@ import { SignalsServiceDefinition } from "@wix/services-definitions/core-service
  * Headless component for social sharing root
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function ShareProduct() {
+ *   const productUrl = 'https://example.com/product/123';
+ *   const productTitle = 'Amazing Product';
+ *
+ *   return (
+ *     <SocialSharing.Root>
+ *       {({ platforms, shareCount, shareFacebook, shareTwitter, copyLink, shareNative }) => (
+ *         <div>
+ *           <p>Share this product ({shareCount} shares)</p>
+ *           <div className="share-buttons">
+ *             <button onClick={() => shareFacebook(productUrl, productTitle)}>
+ *               Share on Facebook
+ *             </button>
+ *             <button onClick={() => shareTwitter(productUrl, `Check out ${productTitle}!`)}>
+ *               Share on Twitter
+ *             </button>
+ *             <button onClick={() => copyLink(productUrl)}>
+ *               Copy Link
+ *             </button>
+ *             <button onClick={() => shareNative({
+ *               title: productTitle,
+ *               text: 'Check this out!',
+ *               url: productUrl
+ *             })}>
+ *               Share
+ *             </button>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </SocialSharing.Root>
+ *   );
+ * }
+ * ```
  */
 export const Root = (props) => {
     const service = useService(SocialSharingServiceDefinition);
@@ -44,6 +81,26 @@ export const Root = (props) => {
  * Headless component for individual social platform
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function SocialButton({ platform, onClick }) {
+ *   return (
+ *     <SocialSharing.Platform platform={platform} onClick={onClick}>
+ *       {({ platform, onSelect }) => (
+ *         <button
+ *           onClick={onSelect}
+ *           className={`social-btn social-btn-${platform.name.toLowerCase()}`}
+ *         >
+ *           <span className="icon">{platform.icon}</span>
+ *           Share on {platform.name}
+ *         </button>
+ *       )}
+ *     </SocialSharing.Platform>
+ *   );
+ * }
+ * ```
  */
 export const Platform = (props) => {
     const { platform, onClick } = props;
@@ -56,6 +113,31 @@ export const Platform = (props) => {
  * Headless component for social sharing platforms with logic
  *
  * @component
+ * @example
+ * ```tsx
+ * import { SocialSharing } from '@wix/stores/components';
+ *
+ * function SocialShareButtons() {
+ *   return (
+ *     <SocialSharing.Platforms
+ *       url="https://example.com/product/123"
+ *       title="Amazing Product"
+ *       description="Check out this amazing product!"
+ *       hashtags={['product', 'amazing']}
+ *     >
+ *       {({ platforms, shareFacebook, shareTwitter, shareLinkedIn, copyLink, shareNative }) => (
+ *         <div className="social-platforms">
+ *           <button onClick={shareFacebook}>Share on Facebook</button>
+ *           <button onClick={shareTwitter}>Share on Twitter</button>
+ *           <button onClick={shareLinkedIn}>Share on LinkedIn</button>
+ *           <button onClick={() => copyLink()}>Copy Link</button>
+ *           <button onClick={() => shareNative()}>Share</button>
+ *         </div>
+ *       )}
+ *     </SocialSharing.Platforms>
+ *   );
+ * }
+ * ```
  */
 export const Platforms = (props) => {
     const { url, title, description = "", hashtags = [] } = props;

package/cjs/dist/react/Sort.d.ts

@@ -11,5 +11,27 @@ export interface ControllerProps {
  * Headless component for sorting products
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Sort } from '@wix/stores/components';
+ *
+ * function ProductSortDropdown() {
+ *   return (
+ *     <Sort.Controller>
+ *       {({ currentSort, setSortBy }) => (
+ *         <select
+ *           value={currentSort}
+ *           onChange={(e) => setSortBy(e.target.value as Sort.SortBy)}
+ *         >
+ *           <option value="name_asc">Name (A-Z)</option>
+ *           <option value="name_desc">Name (Z-A)</option>
+ *           <option value="price_asc">Price (Low to High)</option>
+ *           <option value="price_desc">Price (High to Low)</option>
+ *         </select>
+ *       )}
+ *     </Sort.Controller>
+ *   );
+ * }
+ * ```
  */
 export declare function Controller({ children }: ControllerProps): import("react/jsx-runtime").JSX.Element;