@wix/headless-stores 0.0.29 → 0.0.31

package/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/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/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/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/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;

package/dist/react/Sort.js

@@ -5,6 +5,28 @@ import { SortServiceDefinition, } from "../services/sort-service.js";
  * 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 function Controller({ children }) {
     const sortService = useService(SortServiceDefinition);

package/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/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