@wix/headless-stores 0.0.75 → 0.0.76

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

@@ -641,6 +641,135 @@ export declare const ProductMediaGallery: React.ForwardRefExoticComponent<Produc
  * Alias for ProductMediaGallery to match the documented API
  */
 export { ProductMediaGallery as MediaGallery };
+/**
+ * Props for Product Quantity component
+ */
+export interface ProductQuantityProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        selectedQuantity: number;
+        availableQuantity: number | null;
+        inStock: boolean;
+        isPreOrderEnabled: boolean;
+        setSelectedQuantity: (quantity: number) => void;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for Product Quantity sub-components
+ */
+export interface ProductQuantitySubComponentProps {
+    /** CSS classes to apply to the element */
+    className?: string;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        disabled: boolean;
+    }>;
+    /** Whether the component is disabled */
+    disabled?: boolean;
+}
+/**
+ * Product quantity selector component that integrates with the selected variant.
+ * Provides quantity controls with stock validation and pre-order support.
+ * Uses a compound component pattern with Root, Decrement, Input, Increment, and Raw sub-components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Compound component usage (recommended)
+ * <Product.Quantity.Root className="flex items-center gap-3">
+ *   <div className="flex items-center border border-brand-light rounded-lg">
+ *     <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *     <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ *     <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *   </div>
+ *   <Product.Quantity.Raw asChild>
+ *     {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *       <div>
+ *         {!inStock && isPreOrderEnabled && availableQuantity && (
+ *           <span className="text-content-muted text-sm">
+ *             Max: {availableQuantity} Pre Order
+ *           </span>
+ *         )}
+ *         {inStock && availableQuantity && availableQuantity < 10 && (
+ *           <span className="text-content-muted text-sm">
+ *             Only {availableQuantity} left in stock
+ *           </span>
+ *         )}
+ *       </div>
+ *     )}
+ *   </Product.Quantity.Raw>
+ * </Product.Quantity.Root>
+ *
+ * // Legacy asChild usage (still supported)
+ * <Product.Quantity asChild>
+ *   {({ selectedQuantity, availableQuantity, inStock, setSelectedQuantity }) => (
+ *     <div className="flex items-center gap-3">
+ *       <div className="flex items-center border border-brand-light rounded-lg">
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity - 1)}
+ *           disabled={selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled)}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           -
+ *         </button>
+ *         <span className="px-4 py-2 border-x border-brand-light min-w-[3rem] text-center">
+ *           {selectedQuantity}
+ *         </span>
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity + 1)}
+ *           disabled={availableQuantity && selectedQuantity >= availableQuantity}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           +
+ *         </button>
+ *       </div>
+ *     </div>
+ *   )}
+ * </Product.Quantity>
+ * ```
+ */
+export declare const ProductQuantity: React.ForwardRefExoticComponent<ProductQuantityProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Product Quantity Decrement component.
+ * Automatically handles disabled state based on stock and pre-order settings.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export declare const ProductQuantityDecrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Product Quantity Input component.
+ * Displays the current quantity value. Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ * ```
+ */
+export declare const ProductQuantityInput: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * Product Quantity Increment component.
+ * Automatically handles disabled state based on stock availability.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export declare const ProductQuantityIncrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
 /**
  * Props for Product Action components following the documented API
  */
@@ -660,6 +789,50 @@ export interface ProductActionProps {
     /** Content to display when loading */
     loadingState?: string | React.ReactNode;
 }
+/**
+ * Props for Product Quantity Raw component
+ */
+export interface ProductQuantityRawSubComponentProps {
+    /** CSS classes to apply to the element */
+    className?: string;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        selectedQuantity: number;
+        availableQuantity: number;
+        inStock: boolean;
+        isPreOrderEnabled: boolean;
+        setSelectedQuantity: (quantity: number) => void;
+    }>;
+}
+/**
+ * Product Quantity Raw component.
+ * Provides access to raw quantity data for custom stock messages and advanced use cases.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Raw asChild>
+ *   {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *     <div>
+ *       {!inStock && isPreOrderEnabled && availableQuantity && (
+ *         <span className="text-content-muted text-sm">
+ *           Max: {availableQuantity} Pre Order
+ *         </span>
+ *       )}
+ *       {inStock && availableQuantity && availableQuantity < 10 && (
+ *         <span className="text-content-muted text-sm">
+ *           Only {availableQuantity} left in stock
+ *         </span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Product.Quantity.Raw>
+ * ```
+ */
+export declare const ProductQuantityRaw: React.ForwardRefExoticComponent<ProductQuantityRawSubComponentProps & React.RefAttributes<HTMLElement>>;
 /**
  * Add to cart action button component following the documented API.
  * Automatically integrates with the selected variant and handles loading states.
@@ -687,3 +860,19 @@ export declare const Action: {
     /** Pre-order action button */
     readonly PreOrder: React.ForwardRefExoticComponent<ProductActionProps & React.RefAttributes<HTMLButtonElement>>;
 };
+/**
+ * Quantity namespace containing all product quantity components
+ * following the compound component pattern: Product.Quantity.Root, Product.Quantity.Decrement, etc.
+ */
+export declare const Quantity: {
+    /** Product quantity selector component */
+    readonly Root: React.ForwardRefExoticComponent<ProductQuantityProps & React.RefAttributes<HTMLDivElement>>;
+    /** Product quantity decrement component */
+    readonly Decrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+    /** Product quantity input component */
+    readonly Input: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLInputElement>>;
+    /** Product quantity increment component */
+    readonly Increment: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+    /** Product quantity raw component */
+    readonly Raw: React.ForwardRefExoticComponent<ProductQuantityRawSubComponentProps & React.RefAttributes<HTMLElement>>;
+};

package/cjs/dist/react/Product.js

@@ -4,6 +4,7 @@ import React from 'react';
 import { Commerce } from '@wix/headless-ecom/react';
 import { AsChildSlot } from '@wix/headless-utils/react';
 import { MediaGallery } from '@wix/headless-media/react';
+import { Quantity as QuantityComponent } from '@wix/headless-components/react';
 import * as CoreProduct from './core/Product.js';
 import * as ProductVariantSelector from './core/ProductVariantSelector.js';
 import * as ProductModifiers from './core/ProductModifiers.js';
@@ -54,6 +55,11 @@ var TestIds;
     TestIds["productActionAddToCart"] = "product-action-add-to-cart";
     TestIds["productActionBuyNow"] = "product-action-buy-now";
     TestIds["productActionPreOrder"] = "product-action-pre-order";
+    TestIds["productQuantity"] = "product-quantity";
+    TestIds["productQuantityDecrement"] = "product-quantity-decrement";
+    TestIds["productQuantityInput"] = "product-quantity-input";
+    TestIds["productQuantityIncrement"] = "product-quantity-increment";
+    TestIds["productQuantityRaw"] = "product-quantity-raw";
 })(TestIds || (TestIds = {}));
 /**
  * Root component that provides all necessary service contexts for a complete product experience.
@@ -679,6 +685,177 @@ export const ProductMediaGallery = React.forwardRef((props, ref) => {
  * Alias for ProductMediaGallery to match the documented API
  */
 export { ProductMediaGallery as MediaGallery };
+/**
+ * Product quantity selector component that integrates with the selected variant.
+ * Provides quantity controls with stock validation and pre-order support.
+ * Uses a compound component pattern with Root, Decrement, Input, Increment, and Raw sub-components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Compound component usage (recommended)
+ * <Product.Quantity.Root className="flex items-center gap-3">
+ *   <div className="flex items-center border border-brand-light rounded-lg">
+ *     <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *     <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ *     <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *   </div>
+ *   <Product.Quantity.Raw asChild>
+ *     {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *       <div>
+ *         {!inStock && isPreOrderEnabled && availableQuantity && (
+ *           <span className="text-content-muted text-sm">
+ *             Max: {availableQuantity} Pre Order
+ *           </span>
+ *         )}
+ *         {inStock && availableQuantity && availableQuantity < 10 && (
+ *           <span className="text-content-muted text-sm">
+ *             Only {availableQuantity} left in stock
+ *           </span>
+ *         )}
+ *       </div>
+ *     )}
+ *   </Product.Quantity.Raw>
+ * </Product.Quantity.Root>
+ *
+ * // Legacy asChild usage (still supported)
+ * <Product.Quantity asChild>
+ *   {({ selectedQuantity, availableQuantity, inStock, setSelectedQuantity }) => (
+ *     <div className="flex items-center gap-3">
+ *       <div className="flex items-center border border-brand-light rounded-lg">
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity - 1)}
+ *           disabled={selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled)}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           -
+ *         </button>
+ *         <span className="px-4 py-2 border-x border-brand-light min-w-[3rem] text-center">
+ *           {selectedQuantity}
+ *         </span>
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity + 1)}
+ *           disabled={availableQuantity && selectedQuantity >= availableQuantity}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           +
+ *         </button>
+ *       </div>
+ *     </div>
+ *   )}
+ * </Product.Quantity>
+ * ```
+ */
+export const ProductQuantity = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ inStock, isPreOrderEnabled, availableQuantity, selectedQuantity, setSelectedQuantity, }) => {
+            const renderProps = {
+                selectedQuantity,
+                availableQuantity,
+                inStock,
+                isPreOrderEnabled,
+                setSelectedQuantity,
+            };
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantity, customElement: children, customElementProps: renderProps }));
+            }
+            return (_jsx(QuantityComponent.Root, { initialValue: selectedQuantity, onValueChange: setSelectedQuantity, className: className, ref: ref, "data-testid": TestIds.productQuantity, children: React.isValidElement(children) ? children : null }));
+        } }));
+});
+/**
+ * Product Quantity Decrement component.
+ * Automatically handles disabled state based on stock and pre-order settings.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export const ProductQuantityDecrement = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ selectedQuantity, inStock, isPreOrderEnabled }) => {
+            const disabled = selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled);
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantityDecrement, customElement: children, customElementProps: { disabled } }));
+            }
+            return (_jsx(QuantityComponent.Decrement, { className: className, ref: ref, "data-testid": TestIds.productQuantityDecrement, disabled: disabled }));
+        } }));
+});
+/**
+ * Product Quantity Input component.
+ * Displays the current quantity value. Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ * ```
+ */
+export const ProductQuantityInput = React.forwardRef((props, ref) => {
+    const { asChild, children, className, disabled = true } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: () => {
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, disabled: disabled, "data-testid": TestIds.productQuantityInput, customElement: children, customElementProps: {} }));
+            }
+            return (_jsx(QuantityComponent.Input, { className: className, disabled: disabled, ref: ref, "data-testid": TestIds.productQuantityInput }));
+        } }));
+});
+/**
+ * Product Quantity Increment component.
+ * Automatically handles disabled state based on stock availability.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export const ProductQuantityIncrement = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ selectedQuantity, availableQuantity, inStock, isPreOrderEnabled, }) => {
+            const disabled = (!!availableQuantity && selectedQuantity >= availableQuantity) ||
+                (!inStock && !isPreOrderEnabled);
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantityIncrement, customElement: children, customElementProps: { disabled } }));
+            }
+            return (_jsx(QuantityComponent.Increment, { className: className, ref: ref, "data-testid": TestIds.productQuantityIncrement, disabled: disabled }));
+        } }));
+});
+/**
+ * Product Quantity Raw component.
+ * Provides access to raw quantity data for custom stock messages and advanced use cases.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Raw asChild>
+ *   {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *     <div>
+ *       {!inStock && isPreOrderEnabled && availableQuantity && (
+ *         <span className="text-content-muted text-sm">
+ *           Max: {availableQuantity} Pre Order
+ *         </span>
+ *       )}
+ *       {inStock && availableQuantity && availableQuantity < 10 && (
+ *         <span className="text-content-muted text-sm">
+ *           Only {availableQuantity} left in stock
+ *         </span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Product.Quantity.Raw>
+ * ```
+ */
+export const ProductQuantityRaw = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: (renderProps) => {
+            return (_jsx(AsChildSlot, { ref: ref, customElement: children, asChild: asChild, className: className, "data-testid": TestIds.productQuantityRaw, customElementProps: renderProps }));
+        } }));
+});
 /**
  * Add to cart action button component following the documented API.
  * Automatically integrates with the selected variant and handles loading states.
@@ -758,3 +935,19 @@ export const Action = {
     /** Pre-order action button */
     PreOrder: ProductActionPreOrder,
 };
+/**
+ * Quantity namespace containing all product quantity components
+ * following the compound component pattern: Product.Quantity.Root, Product.Quantity.Decrement, etc.
+ */
+export const Quantity = {
+    /** Product quantity selector component */
+    Root: ProductQuantity,
+    /** Product quantity decrement component */
+    Decrement: ProductQuantityDecrement,
+    /** Product quantity input component */
+    Input: ProductQuantityInput,
+    /** Product quantity increment component */
+    Increment: ProductQuantityIncrement,
+    /** Product quantity raw component */
+    Raw: ProductQuantityRaw,
+};

package/cjs/dist/react/core/ProductVariantSelector.d.ts

@@ -236,6 +236,8 @@ export interface StockRenderProps {
     incrementQuantity: () => void;
     /** Function to decrement quantity */
     decrementQuantity: () => void;
+    /** Function to set selected quantity */
+    setSelectedQuantity: (quantity: number) => void;
 }
 /**
  * Headless component for product stock status

package/cjs/dist/react/core/ProductVariantSelector.js

@@ -238,6 +238,9 @@ export function Stock(props) {
     const decrementQuantity = () => {
         variantService.decrementQuantity();
     };
+    const setSelectedQuantity = (quantity) => {
+        variantService.setSelectedQuantity(quantity);
+    };
     return props.children({
         inStock,
         availableQuantity,
@@ -247,6 +250,7 @@ export function Stock(props) {
         trackInventory,
         selectedQuantity,
         incrementQuantity,
+        setSelectedQuantity,
         decrementQuantity,
     });
 }

package/dist/react/Product.d.ts

@@ -641,6 +641,135 @@ export declare const ProductMediaGallery: React.ForwardRefExoticComponent<Produc
  * Alias for ProductMediaGallery to match the documented API
  */
 export { ProductMediaGallery as MediaGallery };
+/**
+ * Props for Product Quantity component
+ */
+export interface ProductQuantityProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        selectedQuantity: number;
+        availableQuantity: number | null;
+        inStock: boolean;
+        isPreOrderEnabled: boolean;
+        setSelectedQuantity: (quantity: number) => void;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for Product Quantity sub-components
+ */
+export interface ProductQuantitySubComponentProps {
+    /** CSS classes to apply to the element */
+    className?: string;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        disabled: boolean;
+    }>;
+    /** Whether the component is disabled */
+    disabled?: boolean;
+}
+/**
+ * Product quantity selector component that integrates with the selected variant.
+ * Provides quantity controls with stock validation and pre-order support.
+ * Uses a compound component pattern with Root, Decrement, Input, Increment, and Raw sub-components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Compound component usage (recommended)
+ * <Product.Quantity.Root className="flex items-center gap-3">
+ *   <div className="flex items-center border border-brand-light rounded-lg">
+ *     <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *     <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ *     <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *   </div>
+ *   <Product.Quantity.Raw asChild>
+ *     {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *       <div>
+ *         {!inStock && isPreOrderEnabled && availableQuantity && (
+ *           <span className="text-content-muted text-sm">
+ *             Max: {availableQuantity} Pre Order
+ *           </span>
+ *         )}
+ *         {inStock && availableQuantity && availableQuantity < 10 && (
+ *           <span className="text-content-muted text-sm">
+ *             Only {availableQuantity} left in stock
+ *           </span>
+ *         )}
+ *       </div>
+ *     )}
+ *   </Product.Quantity.Raw>
+ * </Product.Quantity.Root>
+ *
+ * // Legacy asChild usage (still supported)
+ * <Product.Quantity asChild>
+ *   {({ selectedQuantity, availableQuantity, inStock, setSelectedQuantity }) => (
+ *     <div className="flex items-center gap-3">
+ *       <div className="flex items-center border border-brand-light rounded-lg">
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity - 1)}
+ *           disabled={selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled)}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           -
+ *         </button>
+ *         <span className="px-4 py-2 border-x border-brand-light min-w-[3rem] text-center">
+ *           {selectedQuantity}
+ *         </span>
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity + 1)}
+ *           disabled={availableQuantity && selectedQuantity >= availableQuantity}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           +
+ *         </button>
+ *       </div>
+ *     </div>
+ *   )}
+ * </Product.Quantity>
+ * ```
+ */
+export declare const ProductQuantity: React.ForwardRefExoticComponent<ProductQuantityProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Product Quantity Decrement component.
+ * Automatically handles disabled state based on stock and pre-order settings.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export declare const ProductQuantityDecrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Product Quantity Input component.
+ * Displays the current quantity value. Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ * ```
+ */
+export declare const ProductQuantityInput: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * Product Quantity Increment component.
+ * Automatically handles disabled state based on stock availability.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export declare const ProductQuantityIncrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
 /**
  * Props for Product Action components following the documented API
  */
@@ -660,6 +789,50 @@ export interface ProductActionProps {
     /** Content to display when loading */
     loadingState?: string | React.ReactNode;
 }
+/**
+ * Props for Product Quantity Raw component
+ */
+export interface ProductQuantityRawSubComponentProps {
+    /** CSS classes to apply to the element */
+    className?: string;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        selectedQuantity: number;
+        availableQuantity: number;
+        inStock: boolean;
+        isPreOrderEnabled: boolean;
+        setSelectedQuantity: (quantity: number) => void;
+    }>;
+}
+/**
+ * Product Quantity Raw component.
+ * Provides access to raw quantity data for custom stock messages and advanced use cases.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Raw asChild>
+ *   {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *     <div>
+ *       {!inStock && isPreOrderEnabled && availableQuantity && (
+ *         <span className="text-content-muted text-sm">
+ *           Max: {availableQuantity} Pre Order
+ *         </span>
+ *       )}
+ *       {inStock && availableQuantity && availableQuantity < 10 && (
+ *         <span className="text-content-muted text-sm">
+ *           Only {availableQuantity} left in stock
+ *         </span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Product.Quantity.Raw>
+ * ```
+ */
+export declare const ProductQuantityRaw: React.ForwardRefExoticComponent<ProductQuantityRawSubComponentProps & React.RefAttributes<HTMLElement>>;
 /**
  * Add to cart action button component following the documented API.
  * Automatically integrates with the selected variant and handles loading states.
@@ -687,3 +860,19 @@ export declare const Action: {
     /** Pre-order action button */
     readonly PreOrder: React.ForwardRefExoticComponent<ProductActionProps & React.RefAttributes<HTMLButtonElement>>;
 };
+/**
+ * Quantity namespace containing all product quantity components
+ * following the compound component pattern: Product.Quantity.Root, Product.Quantity.Decrement, etc.
+ */
+export declare const Quantity: {
+    /** Product quantity selector component */
+    readonly Root: React.ForwardRefExoticComponent<ProductQuantityProps & React.RefAttributes<HTMLDivElement>>;
+    /** Product quantity decrement component */
+    readonly Decrement: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+    /** Product quantity input component */
+    readonly Input: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLInputElement>>;
+    /** Product quantity increment component */
+    readonly Increment: React.ForwardRefExoticComponent<ProductQuantitySubComponentProps & React.RefAttributes<HTMLButtonElement>>;
+    /** Product quantity raw component */
+    readonly Raw: React.ForwardRefExoticComponent<ProductQuantityRawSubComponentProps & React.RefAttributes<HTMLElement>>;
+};

package/dist/react/Product.js

@@ -4,6 +4,7 @@ import React from 'react';
 import { Commerce } from '@wix/headless-ecom/react';
 import { AsChildSlot } from '@wix/headless-utils/react';
 import { MediaGallery } from '@wix/headless-media/react';
+import { Quantity as QuantityComponent } from '@wix/headless-components/react';
 import * as CoreProduct from './core/Product.js';
 import * as ProductVariantSelector from './core/ProductVariantSelector.js';
 import * as ProductModifiers from './core/ProductModifiers.js';
@@ -54,6 +55,11 @@ var TestIds;
     TestIds["productActionAddToCart"] = "product-action-add-to-cart";
     TestIds["productActionBuyNow"] = "product-action-buy-now";
     TestIds["productActionPreOrder"] = "product-action-pre-order";
+    TestIds["productQuantity"] = "product-quantity";
+    TestIds["productQuantityDecrement"] = "product-quantity-decrement";
+    TestIds["productQuantityInput"] = "product-quantity-input";
+    TestIds["productQuantityIncrement"] = "product-quantity-increment";
+    TestIds["productQuantityRaw"] = "product-quantity-raw";
 })(TestIds || (TestIds = {}));
 /**
  * Root component that provides all necessary service contexts for a complete product experience.
@@ -679,6 +685,177 @@ export const ProductMediaGallery = React.forwardRef((props, ref) => {
  * Alias for ProductMediaGallery to match the documented API
  */
 export { ProductMediaGallery as MediaGallery };
+/**
+ * Product quantity selector component that integrates with the selected variant.
+ * Provides quantity controls with stock validation and pre-order support.
+ * Uses a compound component pattern with Root, Decrement, Input, Increment, and Raw sub-components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Compound component usage (recommended)
+ * <Product.Quantity.Root className="flex items-center gap-3">
+ *   <div className="flex items-center border border-brand-light rounded-lg">
+ *     <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *     <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ *     <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ *   </div>
+ *   <Product.Quantity.Raw asChild>
+ *     {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *       <div>
+ *         {!inStock && isPreOrderEnabled && availableQuantity && (
+ *           <span className="text-content-muted text-sm">
+ *             Max: {availableQuantity} Pre Order
+ *           </span>
+ *         )}
+ *         {inStock && availableQuantity && availableQuantity < 10 && (
+ *           <span className="text-content-muted text-sm">
+ *             Only {availableQuantity} left in stock
+ *           </span>
+ *         )}
+ *       </div>
+ *     )}
+ *   </Product.Quantity.Raw>
+ * </Product.Quantity.Root>
+ *
+ * // Legacy asChild usage (still supported)
+ * <Product.Quantity asChild>
+ *   {({ selectedQuantity, availableQuantity, inStock, setSelectedQuantity }) => (
+ *     <div className="flex items-center gap-3">
+ *       <div className="flex items-center border border-brand-light rounded-lg">
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity - 1)}
+ *           disabled={selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled)}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           -
+ *         </button>
+ *         <span className="px-4 py-2 border-x border-brand-light min-w-[3rem] text-center">
+ *           {selectedQuantity}
+ *         </span>
+ *         <button
+ *           onClick={() => setSelectedQuantity(selectedQuantity + 1)}
+ *           disabled={availableQuantity && selectedQuantity >= availableQuantity}
+ *           className="px-3 py-2 hover:bg-surface-primary disabled:opacity-50"
+ *         >
+ *           +
+ *         </button>
+ *       </div>
+ *     </div>
+ *   )}
+ * </Product.Quantity>
+ * ```
+ */
+export const ProductQuantity = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ inStock, isPreOrderEnabled, availableQuantity, selectedQuantity, setSelectedQuantity, }) => {
+            const renderProps = {
+                selectedQuantity,
+                availableQuantity,
+                inStock,
+                isPreOrderEnabled,
+                setSelectedQuantity,
+            };
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantity, customElement: children, customElementProps: renderProps }));
+            }
+            return (_jsx(QuantityComponent.Root, { initialValue: selectedQuantity, onValueChange: setSelectedQuantity, className: className, ref: ref, "data-testid": TestIds.productQuantity, children: React.isValidElement(children) ? children : null }));
+        } }));
+});
+/**
+ * Product Quantity Decrement component.
+ * Automatically handles disabled state based on stock and pre-order settings.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Decrement className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export const ProductQuantityDecrement = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ selectedQuantity, inStock, isPreOrderEnabled }) => {
+            const disabled = selectedQuantity <= 1 || (!inStock && !isPreOrderEnabled);
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantityDecrement, customElement: children, customElementProps: { disabled } }));
+            }
+            return (_jsx(QuantityComponent.Decrement, { className: className, ref: ref, "data-testid": TestIds.productQuantityDecrement, disabled: disabled }));
+        } }));
+});
+/**
+ * Product Quantity Input component.
+ * Displays the current quantity value. Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Input className="w-16 text-center py-1 border-x border-brand-light focus:outline-none focus:ring-2 focus:ring-brand-primary" />
+ * ```
+ */
+export const ProductQuantityInput = React.forwardRef((props, ref) => {
+    const { asChild, children, className, disabled = true } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: () => {
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, disabled: disabled, "data-testid": TestIds.productQuantityInput, customElement: children, customElementProps: {} }));
+            }
+            return (_jsx(QuantityComponent.Input, { className: className, disabled: disabled, ref: ref, "data-testid": TestIds.productQuantityInput }));
+        } }));
+});
+/**
+ * Product Quantity Increment component.
+ * Automatically handles disabled state based on stock availability.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Increment className="px-3 py-1 hover:bg-surface-primary transition-colors" />
+ * ```
+ */
+export const ProductQuantityIncrement = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: ({ selectedQuantity, availableQuantity, inStock, isPreOrderEnabled, }) => {
+            const disabled = (!!availableQuantity && selectedQuantity >= availableQuantity) ||
+                (!inStock && !isPreOrderEnabled);
+            if (asChild && children) {
+                return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.productQuantityIncrement, customElement: children, customElementProps: { disabled } }));
+            }
+            return (_jsx(QuantityComponent.Increment, { className: className, ref: ref, "data-testid": TestIds.productQuantityIncrement, disabled: disabled }));
+        } }));
+});
+/**
+ * Product Quantity Raw component.
+ * Provides access to raw quantity data for custom stock messages and advanced use cases.
+ * Must be used within Product.Quantity.Root.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Product.Quantity.Raw asChild>
+ *   {({ availableQuantity, inStock, isPreOrderEnabled }) => (
+ *     <div>
+ *       {!inStock && isPreOrderEnabled && availableQuantity && (
+ *         <span className="text-content-muted text-sm">
+ *           Max: {availableQuantity} Pre Order
+ *         </span>
+ *       )}
+ *       {inStock && availableQuantity && availableQuantity < 10 && (
+ *         <span className="text-content-muted text-sm">
+ *           Only {availableQuantity} left in stock
+ *         </span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Product.Quantity.Raw>
+ * ```
+ */
+export const ProductQuantityRaw = React.forwardRef((props, ref) => {
+    const { asChild, children, className } = props;
+    return (_jsx(ProductVariantSelector.Stock, { children: (renderProps) => {
+            return (_jsx(AsChildSlot, { ref: ref, customElement: children, asChild: asChild, className: className, "data-testid": TestIds.productQuantityRaw, customElementProps: renderProps }));
+        } }));
+});
 /**
  * Add to cart action button component following the documented API.
  * Automatically integrates with the selected variant and handles loading states.
@@ -758,3 +935,19 @@ export const Action = {
     /** Pre-order action button */
     PreOrder: ProductActionPreOrder,
 };
+/**
+ * Quantity namespace containing all product quantity components
+ * following the compound component pattern: Product.Quantity.Root, Product.Quantity.Decrement, etc.
+ */
+export const Quantity = {
+    /** Product quantity selector component */
+    Root: ProductQuantity,
+    /** Product quantity decrement component */
+    Decrement: ProductQuantityDecrement,
+    /** Product quantity input component */
+    Input: ProductQuantityInput,
+    /** Product quantity increment component */
+    Increment: ProductQuantityIncrement,
+    /** Product quantity raw component */
+    Raw: ProductQuantityRaw,
+};

package/dist/react/core/ProductVariantSelector.d.ts

@@ -236,6 +236,8 @@ export interface StockRenderProps {
     incrementQuantity: () => void;
     /** Function to decrement quantity */
     decrementQuantity: () => void;
+    /** Function to set selected quantity */
+    setSelectedQuantity: (quantity: number) => void;
 }
 /**
  * Headless component for product stock status

package/dist/react/core/ProductVariantSelector.js

@@ -238,6 +238,9 @@ export function Stock(props) {
     const decrementQuantity = () => {
         variantService.decrementQuantity();
     };
+    const setSelectedQuantity = (quantity) => {
+        variantService.setSelectedQuantity(quantity);
+    };
     return props.children({
         inStock,
         availableQuantity,
@@ -247,6 +250,7 @@ export function Stock(props) {
         trackInventory,
         selectedQuantity,
         incrementQuantity,
+        setSelectedQuantity,
         decrementQuantity,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-stores",
-  "version": "0.0.75",
+  "version": "0.0.76",
   "type": "module",
   "scripts": {
     "prebuild": "cd ../media && yarn build && cd ../ecom && yarn build",
@@ -62,7 +62,7 @@
     "@wix/auto_sdk_stores_read-only-variants-v-3": "^1.0.23",
     "@wix/ecom": "^1.0.1278",
     "@wix/essentials": "^0.1.24",
-    "@wix/headless-components": "0.0.11",
+    "@wix/headless-components": "0.0.12",
     "@wix/headless-ecom": "0.0.24",
     "@wix/headless-media": "0.0.11",
     "@wix/headless-utils": "0.0.3",