@wix/headless-stores 0.0.29 → 0.0.31

package/cjs/dist/react/FilteredCollection.js

@@ -7,6 +7,26 @@ import { InventoryAvailabilityStatus, } from "@wix/auto_sdk_stores_products-v-3"
  * Headless component for displaying a loading state for filters
  *
  * @component
+ * @example
+ * ```tsx
+ * import { FilteredCollection } from '@wix/stores/components';
+ *
+ * function FiltersLoadingIndicator() {
+ *   return (
+ *     <FilteredCollection.FiltersLoading>
+ *       {({ isFullyLoaded }) => (
+ *         <div>
+ *           {!isFullyLoaded && (
+ *             <div className="loading-pulse">
+ *               Loading filters...
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </FilteredCollection.FiltersLoading>
+ *   );
+ * }
+ * ```
  */
 export const FiltersLoading = ({ children }) => {
     const filter = useService(FilterServiceDefinition);
@@ -17,6 +37,35 @@ export const FiltersLoading = ({ children }) => {
  * Headless component for displaying a grid of filtered products
  *
  * @component
+ * @example
+ * ```tsx
+ * import { FilteredCollection } from '@wix/stores/components';
+ *
+ * function FilteredProductsGrid() {
+ *   return (
+ *     <FilteredCollection.Grid>
+ *       {({ products, isLoading, error, isEmpty, totalProducts, hasMoreProducts }) => (
+ *         <div>
+ *           {isLoading && <div>Loading filtered products...</div>}
+ *           {error && <div>Error: {error}</div>}
+ *           {isEmpty && <div>No products match your filters</div>}
+ *           {products.length > 0 && (
+ *             <div>
+ *               <p>Showing {products.length} of {totalProducts} products</p>
+ *               <div className="filtered-grid">
+ *                 {products.map(product => (
+ *                   <div key={product.id}>{product.name}</div>
+ *                 ))}
+ *               </div>
+ *               {hasMoreProducts && <button>Load More</button>}
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </FilteredCollection.Grid>
+ *   );
+ * }
+ * ```
  */
 export const Grid = ({ children }) => {
     const collection = useService(CollectionServiceDefinition);
@@ -39,6 +88,30 @@ export const Grid = ({ children }) => {
  * Headless component for displaying a filtered product item
  *
  * @component
+ * @example
+ * ```tsx
+ * import { FilteredCollection } from '@wix/stores/components';
+ *
+ * function FilteredProductItem({ product }) {
+ *   return (
+ *     <FilteredCollection.Item product={product}>
+ *       {({ title, image, price, compareAtPrice, available, slug, description }) => (
+ *         <div className={`product-item ${!available ? 'unavailable' : ''}`}>
+ *           {image && <img src={image} alt={title} />}
+ *           <h3>{title}</h3>
+ *           {description && <p>{description}</p>}
+ *           <div className="price">
+ *             <span className="current">{price}</span>
+ *             {compareAtPrice && <span className="compare"><s>{compareAtPrice}</s></span>}
+ *           </div>
+ *           {!available && <div className="out-of-stock">Out of Stock</div>}
+ *           <a href={`/product/${slug}`}>View Details</a>
+ *         </div>
+ *       )}
+ *     </FilteredCollection.Item>
+ *   );
+ * }
+ * ```
  */
 export const Item = ({ product, children }) => {
     // Safe conversion of product data with type safety guards
@@ -77,6 +150,35 @@ export const Item = ({ product, children }) => {
  * Headless component for load more filtered products functionality
  *
  * @component
+ * @example
+ * ```tsx
+ * import { FilteredCollection } from '@wix/stores/components';
+ *
+ * function LoadMoreProducts() {
+ *   return (
+ *     <FilteredCollection.LoadMore>
+ *       {({ loadMore, refresh, isLoading, hasProducts, totalProducts, hasMoreProducts }) => (
+ *         <div>
+ *           {hasProducts && (
+ *             <div>
+ *               <p>Showing products ({totalProducts} total)</p>
+ *               {hasMoreProducts && (
+ *                 <button
+ *                   onClick={loadMore}
+ *                   disabled={isLoading}
+ *                 >
+ *                   {isLoading ? 'Loading...' : 'Load More'}
+ *                 </button>
+ *               )}
+ *               <button onClick={refresh}>Refresh</button>
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </FilteredCollection.LoadMore>
+ *   );
+ * }
+ * ```
  */
 export const LoadMore = ({ children }) => {
     const collection = useService(CollectionServiceDefinition);
@@ -99,6 +201,38 @@ export const LoadMore = ({ children }) => {
  * Headless component for product filters with available options
  *
  * @component
+ * @example
+ * ```tsx
+ * import { FilteredCollection } from '@wix/stores/components';
+ *
+ * function ProductFilters() {
+ *   return (
+ *     <FilteredCollection.Filters>
+ *       {({ applyFilters, clearFilters, currentFilters, availableOptions, isFiltered }) => (
+ *         <div className="filters">
+ *           <h3>Filters</h3>
+ *           <div className="price-filter">
+ *             <label>Price Range</label>
+ *             <input
+ *               type="range"
+ *               min={availableOptions.priceRange.min}
+ *               max={availableOptions.priceRange.max}
+ *               value={currentFilters.priceRange.min}
+ *               onChange={(e) => applyFilters({
+ *                 ...currentFilters,
+ *                 priceRange: { ...currentFilters.priceRange, min: Number(e.target.value) }
+ *               })}
+ *             />
+ *           </div>
+ *           {isFiltered && (
+ *             <button onClick={clearFilters}>Clear All Filters</button>
+ *           )}
+ *         </div>
+ *       )}
+ *     </FilteredCollection.Filters>
+ *   );
+ * }
+ * ```
  */
 export const Filters = ({ children }) => {
     const collection = useService(CollectionServiceDefinition);

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

@@ -17,6 +17,20 @@ export interface ProductNameRenderProps {
  * Headless component for product name display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Product } from '@wix/stores/components';
+ *
+ * function ProductHeader() {
+ *   return (
+ *     <Product.Name>
+ *       {({ name }) => (
+ *         <h1>{name}</h1>
+ *       )}
+ *     </Product.Name>
+ *   );
+ * }
+ * ```
  */
 export declare const Name: (props: ProductNameProps) => import("react").ReactNode;
 /**
@@ -45,22 +59,33 @@ export interface ProductDescriptionRenderProps {
     plainDescription: NonNullable<V3Product["plainDescription"]>;
 }
 /**
-* Headless component for product description display
-*
-* @example
-* <Product.Description>
-*   {({ plainDescription }) => (
-*     <>
-*       {plainDescription && (
-*         <p
-*           dangerouslySetInnerHTML={{
-*             __html: plainDescription,
-*           }}
-*         />
-*       )}
-*     </>
-*   )}
-* </Product.Description>
-* @component
-*/
+ * Headless component for product description display
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Product } from '@wix/stores/components';
+ *
+ * function ProductDescription() {
+ *   return (
+ *     <Product.Description>
+ *       {({ plainDescription, description }) => (
+ *         <div>
+ *           {plainDescription && (
+ *             <div
+ *               dangerouslySetInnerHTML={{
+ *                 __html: plainDescription,
+ *               }}
+ *             />
+ *           )}
+ *           {description && (
+ *             <div>Rich content description available</div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Product.Description>
+ *   );
+ * }
+ * ```
+ */
 export declare const Description: (props: ProductDescriptionProps) => import("react").ReactNode;

package/cjs/dist/react/Product.js

@@ -4,6 +4,20 @@ import { ProductServiceDefinition } from "../services/product-service.js";
  * Headless component for product name display
  *
  * @component
+ * @example
+ * ```tsx
+ * import { Product } from '@wix/stores/components';
+ *
+ * function ProductHeader() {
+ *   return (
+ *     <Product.Name>
+ *       {({ name }) => (
+ *         <h1>{name}</h1>
+ *       )}
+ *     </Product.Name>
+ *   );
+ * }
+ * ```
  */
 export const Name = (props) => {
     const service = useService(ProductServiceDefinition);
@@ -14,24 +28,35 @@ export const Name = (props) => {
     });
 };
 /**
-* Headless component for product description display
-*
-* @example
-* <Product.Description>
-*   {({ plainDescription }) => (
-*     <>
-*       {plainDescription && (
-*         <p
-*           dangerouslySetInnerHTML={{
-*             __html: plainDescription,
-*           }}
-*         />
-*       )}
-*     </>
-*   )}
-* </Product.Description>
-* @component
-*/
+ * Headless component for product description display
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Product } from '@wix/stores/components';
+ *
+ * function ProductDescription() {
+ *   return (
+ *     <Product.Description>
+ *       {({ plainDescription, description }) => (
+ *         <div>
+ *           {plainDescription && (
+ *             <div
+ *               dangerouslySetInnerHTML={{
+ *                 __html: plainDescription,
+ *               }}
+ *             />
+ *           )}
+ *           {description && (
+ *             <div>Rich content description available</div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </Product.Description>
+ *   );
+ * }
+ * ```
+ */
 export const Description = (props) => {
     const service = useService(ProductServiceDefinition);
     const product = service.product.get();

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

@@ -36,5 +36,35 @@ export interface ActionsRenderProps {
  * Headless component for product actions (add to cart, buy now)
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductActions } from '@wix/stores/components';
+ *
+ * function AddToCartButton() {
+ *   return (
+ *     <ProductActions.Actions quantity={1}>
+ *       {({ onAddToCart, onBuyNow, canAddToCart, isLoading, price, inStock, error }) => (
+ *         <div>
+ *           <div>Price: {price}</div>
+ *           {error && <div className="error">{error}</div>}
+ *           {!inStock && <div>Out of stock</div>}
+ *           <button
+ *             onClick={onAddToCart}
+ *             disabled={!canAddToCart || isLoading}
+ *           >
+ *             {isLoading ? 'Adding...' : 'Add to Cart'}
+ *           </button>
+ *           <button
+ *             onClick={onBuyNow}
+ *             disabled={!canAddToCart || isLoading}
+ *           >
+ *             Buy Now
+ *           </button>
+ *         </div>
+ *       )}
+ *     </ProductActions.Actions>
+ *   );
+ * }
+ * ```
  */
 export declare const Actions: (props: ActionsProps) => import("react").ReactNode;

package/cjs/dist/react/ProductActions.js

@@ -6,6 +6,36 @@ import { CurrentCartServiceDefinition } from "@wix/headless-ecom/services";
  * Headless component for product actions (add to cart, buy now)
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductActions } from '@wix/stores/components';
+ *
+ * function AddToCartButton() {
+ *   return (
+ *     <ProductActions.Actions quantity={1}>
+ *       {({ onAddToCart, onBuyNow, canAddToCart, isLoading, price, inStock, error }) => (
+ *         <div>
+ *           <div>Price: {price}</div>
+ *           {error && <div className="error">{error}</div>}
+ *           {!inStock && <div>Out of stock</div>}
+ *           <button
+ *             onClick={onAddToCart}
+ *             disabled={!canAddToCart || isLoading}
+ *           >
+ *             {isLoading ? 'Adding...' : 'Add to Cart'}
+ *           </button>
+ *           <button
+ *             onClick={onBuyNow}
+ *             disabled={!canAddToCart || isLoading}
+ *           >
+ *             Buy Now
+ *           </button>
+ *         </div>
+ *       )}
+ *     </ProductActions.Actions>
+ *   );
+ * }
+ * ```
  */
 export const Actions = (props) => {
     const variantService = useService(SelectedVariantServiceDefinition);

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

@@ -23,6 +23,46 @@ export interface ModifiersRenderProps {
  * Headless component for all product modifiers
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductModifiers } from '@wix/stores/components';
+ *
+ * function ModifiersSelector() {
+ *   return (
+ *     <ProductModifiers.Modifiers>
+ *       {({ modifiers, hasModifiers, selectedModifiers, areAllRequiredModifiersFilled }) => (
+ *         <div>
+ *           {hasModifiers && (
+ *             <div>
+ *               <h3>Customize your product</h3>
+ *               {modifiers.map(modifier => (
+ *                 <div key={modifier.id}>
+ *                   <label>{modifier.name}</label>
+ *                   {modifier.required && <span>*</span>}
+ *                   {modifier.choices?.map(choice => (
+ *                     <label key={choice.id}>
+ *                       <input
+ *                         type={modifier.multiple ? 'checkbox' : 'radio'}
+ *                         name={modifier.id}
+ *                         value={choice.id}
+ *                         checked={selectedModifiers[modifier.id] === choice.id}
+ *                       />
+ *                       {choice.description} (+{choice.priceChange?.price})
+ *                     </label>
+ *                   ))}
+ *                 </div>
+ *               ))}
+ *               {!areAllRequiredModifiersFilled && (
+ *                 <div className="warning">Please fill all required options</div>
+ *               )}
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </ProductModifiers.Modifiers>
+ *   );
+ * }
+ * ```
  */
 export declare const Modifiers: (props: ModifiersProps) => import("react").ReactNode;
 /**
@@ -61,6 +101,47 @@ export interface ModifierRenderProps {
  * Headless component for a specific product modifier
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductModifiers } from '@wix/stores/components';
+ *
+ * function ModifierField({ modifier }) {
+ *   return (
+ *     <ProductModifiers.Modifier modifier={modifier}>
+ *       {({ name, mandatory, hasChoices, choices, selectedValue, isFreeText, placeholder, maxChars }) => (
+ *         <div className="modifier-field">
+ *           <label>
+ *             {name} {mandatory && <span className="required">*</span>}
+ *           </label>
+ *           {hasChoices && (
+ *             <div className="choices">
+ *               {choices.map(choice => (
+ *                 <label key={choice.id}>
+ *                   <input
+ *                     type="radio"
+ *                     name={name}
+ *                     value={choice.name}
+ *                     checked={selectedValue?.choiceValue === choice.name}
+ *                   />
+ *                   {choice.description} (+{choice.priceChange?.price || '0'})
+ *                 </label>
+ *               ))}
+ *             </div>
+ *           )}
+ *           {isFreeText && (
+ *             <input
+ *               type="text"
+ *               placeholder={placeholder}
+ *               maxLength={maxChars}
+ *               value={selectedValue?.freeTextValue || ''}
+ *             />
+ *           )}
+ *         </div>
+ *       )}
+ *     </ProductModifiers.Modifier>
+ *   );
+ * }
+ * ```
  */
 export declare const Modifier: (props: ModifierProps) => import("react").ReactNode;
 /**
@@ -97,6 +178,31 @@ export interface ChoiceRenderProps {
  * Headless component for individual modifier choice selection
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductModifiers } from '@wix/stores/components';
+ *
+ * function ModifierChoiceButton({ modifier, choice }) {
+ *   return (
+ *     <ProductModifiers.Choice modifier={modifier} choice={choice}>
+ *       {({ value, description, isSelected, onSelect, colorCode }) => (
+ *         <button
+ *           onClick={onSelect}
+ *           className={`choice-button ${isSelected ? 'selected' : ''}`}
+ *           style={colorCode ? { backgroundColor: colorCode } : {}}
+ *         >
+ *           {colorCode ? (
+ *             <div className="color-swatch" title={value} />
+ *           ) : (
+ *             <span>{value}</span>
+ *           )}
+ *           {description && <span className="description">{description}</span>}
+ *         </button>
+ *       )}
+ *     </ProductModifiers.Choice>
+ *   );
+ * }
+ * ```
  */
 export declare const Choice: (props: ChoiceProps) => import("react").ReactNode;
 /**
@@ -133,6 +239,36 @@ export interface FreeTextRenderProps {
  * Headless component for free text modifier input
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductModifiers } from '@wix/stores/components';
+ *
+ * function FreeTextModifier({ modifier }) {
+ *   return (
+ *     <ProductModifiers.FreeText modifier={modifier}>
+ *       {({ value, onChange, mandatory, maxChars, placeholder, charCount, isOverLimit, modifierName }) => (
+ *         <div className="free-text-modifier">
+ *           <label>
+ *             {modifierName} {mandatory && <span className="required">*</span>}
+ *           </label>
+ *           <textarea
+ *             value={value}
+ *             onChange={(e) => onChange(e.target.value)}
+ *             placeholder={placeholder}
+ *             maxLength={maxChars}
+ *             className={isOverLimit ? 'over-limit' : ''}
+ *           />
+ *           {maxChars && (
+ *             <div className={`char-count ${isOverLimit ? 'over-limit' : ''}`}>
+ *               {charCount}/{maxChars}
+ *             </div>
+ *           )}
+ *         </div>
+ *       )}
+ *     </ProductModifiers.FreeText>
+ *   );
+ * }
+ * ```
  */
 export declare const FreeText: (props: FreeTextProps) => import("react").ReactNode;
 /**
@@ -162,5 +298,41 @@ export interface ToggleFreeTextRenderProps {
  * Used for optional free text modifiers where a checkbox shows/hides the input
  *
  * @component
+ * @example
+ * ```tsx
+ * import { ProductModifiers } from '@wix/stores/components';
+ *
+ * function ToggleFreeTextModifier({ modifier }) {
+ *   return (
+ *     <ProductModifiers.ToggleFreeText modifier={modifier}>
+ *       {({ isTextInputShown, onToggle, mandatory, modifierName }) => (
+ *         <div className="toggle-free-text">
+ *           {!mandatory && (
+ *             <label>
+ *               <input
+ *                 type="checkbox"
+ *                 checked={isTextInputShown}
+ *                 onChange={onToggle}
+ *               />
+ *               Add {modifierName}
+ *             </label>
+ *           )}
+ *           {isTextInputShown && (
+ *             <ProductModifiers.FreeText modifier={modifier}>
+ *               {(props) => (
+ *                 <textarea
+ *                   value={props.value}
+ *                   onChange={(e) => props.onChange(e.target.value)}
+ *                   placeholder={props.placeholder}
+ *                 />
+ *               )}
+ *             </ProductModifiers.FreeText>
+ *           )}
+ *         </div>
+ *       )}
+ *     </ProductModifiers.ToggleFreeText>
+ *   );
+ * }
+ * ```
  */
 export declare const ToggleFreeText: (props: ToggleFreeTextProps) => import("react").ReactNode;