@wix/headless-restaurants-olo 0.0.31 → 0.0.32

package/dist/react/ItemDetails.d.ts

@@ -5,39 +5,40 @@ import { ItemServiceConfig } from '../services/item-details-service.js';
 import { EnhancedVariant } from '@wix/headless-restaurants-menus/services';
 import { AvailabilityStatus, AvailabilityStatusMap, AddToCartButtonState } from '../services/common-types.js';
 /**
- * Root component for menu item display and interaction.
- * Provides context for all menu item-related components like name, price, description, image, etc.
- *
- * @component
- * @example
- * ```tsx
- * <ItemDetails>
- *   <ItemDetailsImage src="wix:image://v1/abc123.jpg" alt="Menu item" />
- *   <ItemDetailsName />
- *   <ItemDetailsPrice />
- *   <ItemDetailsDescription />
- * </ItemDetails>
- * ```
+ * Props for the ItemDetails Root component
  */
 export interface RootProps {
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** Child components that will have access to the item context */
     children: React.ReactNode;
+    /** Optional pre-loaded item details service configuration */
     itemDetailsServiceConfig?: ItemServiceConfig;
 }
-export declare const Root: ({ children, itemDetailsServiceConfig }: RootProps) => import("react/jsx-runtime").JSX.Element;
 /**
- * Wrapper component for CoreItemDetails.VariantsComponent.
- * Renders the variants for the item using Radix UI RadioGroup.
+ * Root headless component for menu item details
+ * Provides service context and item data for all child components
  *
- * @component
  * @example
  * ```tsx
- * <ItemDetails.Variants>
- *   {(variant) => <span>{variant.name}</span>}
- * </ItemDetails.Variants>
+ * <ItemDetails.Root itemDetailsServiceConfig={config}>
+ *   <ItemDetails.Name />
+ *   <ItemDetails.Price />
+ *   <ItemDetails.Description />
+ *   <ItemDetails.Variants />
+ *   <ItemDetails.AddToCartButton />
+ * </ItemDetails.Root>
  * ```
  */
+export declare const Root: {
+    ({ children, itemDetailsServiceConfig }: RootProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * Props for the ItemDetails Variants component
+ */
 export interface ItemDetailsVariantsProps {
+    /** Children render prop that receives variant data */
     children?: AsChildChildren<{
         variant: EnhancedVariant;
         variants: EnhancedVariant[];
@@ -45,31 +46,60 @@ export interface ItemDetailsVariantsProps {
         selectedVariantId?: string;
         onVariantChange?: (variantId: string) => void;
     }>;
+    /** CSS classes to apply to the default container */
     className?: string;
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** CSS classes to apply to variant names */
     variantNameClassName?: string;
+    /** CSS classes to apply to variant prices */
     variantPriceClassName?: string;
+    /** Optional content to display when no variants are available */
     emptyState?: React.ReactNode;
 }
-export declare const Variants: React.ForwardRefExoticComponent<ItemDetailsVariantsProps & React.RefAttributes<HTMLElement>>;
 /**
- * Multi-line text input component for special requests or instructions.
- * Provides a textarea for customers to add custom notes or modifications.
+ * Headless component for item variants selection
+ * Renders variants using Radix UI RadioGroup for single selection
+ * Supports custom rendering via asChild or children render prop
  *
- * @component
  * @example
  * ```tsx
- * <ItemDetails>
- *   <SpecialRequest
- *     placeholder="Any special requests or dietary restrictions?"
- *     maxLength={200}
- *     className="mt-4"
- *   />
- * </ItemDetails>
+ * <ItemDetails.Variants
+ *   variantNameClassName="font-paragraph text-foreground"
+ *   variantPriceClassName="font-paragraph text-secondary-foreground"
+ *   emptyState={<div>No variants available</div>}
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.Variants asChild>
+ *   {({ variants, selectedVariantId, onVariantChange }) => (
+ *     <div className="variant-grid">
+ *       {variants.map((variant) => (
+ *         <button
+ *           key={variant._id}
+ *           onClick={() => onVariantChange?.(variant._id ?? '')}
+ *           data-selected={selectedVariantId === variant._id}
+ *         >
+ *           <span>{variant.name}</span>
+ *           <span>{variant.priceInfo?.formattedPrice}</span>
+ *         </button>
+ *       ))}
+ *     </div>
+ *   )}
+ * </ItemDetails.Variants>
  * ```
  */
+export declare const Variants: React.ForwardRefExoticComponent<ItemDetailsVariantsProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for the ItemDetails SpecialRequest component
+ */
 export interface SpecialRequestProps {
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** Children render prop that receives value and onChange handler */
     children?: AsChildChildren<{
         value: string;
         onChange: (value: string) => void;
@@ -82,6 +112,7 @@ export interface SpecialRequestProps {
     rows?: number;
     /** CSS classes to apply to the textarea */
     className?: string;
+    /** CSS classes to apply to the label */
     labelClassName?: string;
     /** Label text for the input */
     label?: string;
@@ -89,16 +120,16 @@ export interface SpecialRequestProps {
     showCharCount?: boolean;
 }
 /**
- * AddToCartButton component that uses Commerce.Actions.AddToCart with AsChildSlot,
- * and gets the lineItem from CoreItemDetails.LineItemComponent.
- *
- * Usage:
- * <ItemDetails.AddToCartButton>Add to cart</ItemDetails.AddToCartButton>
+ * Props for the ItemDetails AddToCartButton component
  */
 export interface AddToCartButtonProps {
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** CSS classes to apply to the button */
     className?: string;
+    /** Map of button states to display text */
     addToCartLabelMap: Record<AddToCartButtonState, string>;
+    /** Children render prop that receives button state and line item data */
     children?: AsChildChildren<{
         lineItem: LineItem;
         buttonState: AddToCartButtonState;
@@ -111,10 +142,52 @@ export interface AddToCartButtonProps {
         modifierGroupHasError: boolean;
     }>;
 }
+/**
+ * Headless component for adding item to cart
+ * Wraps Commerce.Actions.AddToCart and provides item-specific state
+ * Displays button state, price, and handles disabled states
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.AddToCartButton
+ *   className="bg-primary text-primary-foreground"
+ *   addToCartLabelMap={{
+ *     [AddToCartButtonState.ADD_TO_CART]: 'Add to Cart',
+ *     [AddToCartButtonState.LOADING]: 'Adding...',
+ *     [AddToCartButtonState.UPDATE_CART]: 'Update Cart',
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.AddToCartButton
+ *   addToCartLabelMap={labelMap}
+ *   asChild
+ * >
+ *   {({ buttonState, formattedPrice, modifierGroupHasError, addToCartButtonDisabled }) => (
+ *     <button
+ *       disabled={addToCartButtonDisabled || modifierGroupHasError}
+ *       className="bg-primary text-primary-foreground"
+ *     >
+ *       <span>{labelMap[buttonState]}</span>
+ *       <span>{formattedPrice}</span>
+ *     </button>
+ *   )}
+ * </ItemDetails.AddToCartButton>
+ * ```
+ */
 export declare const AddToCartButton: React.ForwardRefExoticComponent<AddToCartButtonProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for the ItemDetails Quantity component
+ */
 export interface ItemDetailsQuantityProps {
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** CSS classes to apply to the container */
     className?: string;
+    /** Children render prop that receives quantity state and handlers */
     children: (props: {
         quantity: number;
         increment: () => void;
@@ -125,13 +198,87 @@ export interface ItemDetailsQuantityProps {
         onValueChange: (value: number) => void;
     }) => React.ReactNode;
 }
+/**
+ * Headless component for item quantity selection
+ * Provides increment/decrement controls with validation
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.Quantity>
+ *   {({ quantity, increment, decrement, canIncrement, canDecrement }) => (
+ *     <div className="flex items-center gap-2">
+ *       <button
+ *         onClick={decrement}
+ *         disabled={!canDecrement}
+ *         className="bg-secondary text-secondary-foreground"
+ *       >
+ *         -
+ *       </button>
+ *       <span className="font-paragraph text-foreground">{quantity}</span>
+ *       <button
+ *         onClick={increment}
+ *         disabled={!canIncrement}
+ *         className="bg-secondary text-secondary-foreground"
+ *       >
+ *         +
+ *       </button>
+ *     </div>
+ *   )}
+ * </ItemDetails.Quantity>
+ * ```
+ */
 export declare const Quantity: React.FC<ItemDetailsQuantityProps>;
+/**
+ * Headless component for special requests or custom instructions
+ * Provides a textarea for customers to add notes or modifications
+ * Supports character count and validation
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.SpecialRequest
+ *   placeholder="Any special requests?"
+ *   maxLength={200}
+ *   rows={3}
+ *   label="Special Requests"
+ *   className="border-foreground text-foreground"
+ *   labelClassName="font-paragraph text-foreground"
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.SpecialRequest asChild>
+ *   {({ value, onChange }) => (
+ *     <div>
+ *       <label>Custom Instructions</label>
+ *       <textarea
+ *         value={value}
+ *         onChange={(e) => onChange(e.target.value)}
+ *         className="border-foreground text-foreground"
+ *       />
+ *       <span className="text-secondary-foreground">
+ *         {value.length}/200
+ *       </span>
+ *     </div>
+ *   )}
+ * </ItemDetails.SpecialRequest>
+ * ```
+ */
 export declare const SpecialRequest: React.ForwardRefExoticComponent<SpecialRequestProps & React.RefAttributes<never>>;
+/**
+ * Props for the ItemDetails Availability component
+ */
 export interface ItemDetailsAvailabilityProps {
+    /** Whether to render as a child component */
     asChild?: boolean;
+    /** CSS classes to apply to the availability text */
     textClassName?: string;
+    /** CSS classes to apply to the action button */
     buttonClassName?: string;
+    /** Map of availability statuses to display text and actions */
     availabilityStatusMap: AvailabilityStatusMap;
+    /** Children render prop that receives availability state and handlers */
     children: (props: {
         availabilityStatus: AvailabilityStatus;
         availabilityStatusText?: string;
@@ -139,4 +286,54 @@ export interface ItemDetailsAvailabilityProps {
         availabilityAction?: () => void;
     }) => React.ReactNode;
 }
+/**
+ * Headless component for item availability status display
+ * Shows availability messages and optional action buttons
+ * Does not render when item is available
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.AvailabilityComponent
+ *   availabilityStatusMap={{
+ *     [AvailabilityStatus.OUT_OF_STOCK]: {
+ *       text: 'Currently unavailable',
+ *       buttonText: 'Notify me',
+ *       action: () => handleNotify(),
+ *     },
+ *     [AvailabilityStatus.LIMITED_STOCK]: {
+ *       text: 'Limited availability',
+ *     },
+ *   }}
+ *   textClassName="text-destructive"
+ *   buttonClassName="bg-primary text-primary-foreground"
+ * >
+ *   {({ availabilityStatus, availabilityStatusText }) => (
+ *     <div>{availabilityStatusText}</div>
+ *   )}
+ * </ItemDetails.AvailabilityComponent>
+ * ```
+ *
+ * @example
+ * Custom rendering with action button:
+ * ```tsx
+ * <ItemDetails.AvailabilityComponent
+ *   availabilityStatusMap={statusMap}
+ *   asChild
+ * >
+ *   {({ availabilityStatus, availabilityStatusText, availabilityStatusButtonText, availabilityAction }) => (
+ *     <div className="bg-destructive/10 p-4">
+ *       <p className="text-destructive">{availabilityStatusText}</p>
+ *       {availabilityStatusButtonText && availabilityAction && (
+ *         <button
+ *           onClick={availabilityAction}
+ *           className="bg-primary text-primary-foreground"
+ *         >
+ *           {availabilityStatusButtonText}
+ *         </button>
+ *       )}
+ *     </div>
+ *   )}
+ * </ItemDetails.AvailabilityComponent>
+ * ```
+ */
 export declare const AvailabilityComponent: React.ForwardRefExoticComponent<ItemDetailsAvailabilityProps & React.RefAttributes<HTMLElement>>;

package/dist/react/ItemDetails.js

@@ -7,6 +7,11 @@ import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import { Item } from '@wix/headless-restaurants-menus/react';
 import * as CoreItemDetails from './core/ItemDetails.js';
 import { AvailabilityStatus, } from '../services/common-types.js';
+// ========================================
+// ITEM DETAILS HEADLESS COMPONENTS
+// ========================================
+// Headless components for menu item details display and interaction
+// These components provide access to item data, variants, modifiers, and cart actions
 var TestIds;
 (function (TestIds) {
     TestIds["itemName"] = "item-name";
@@ -19,9 +24,60 @@ var TestIds;
     TestIds["itemVariants"] = "item-variants";
     TestIds["itemAvailability"] = "item-availability";
 })(TestIds || (TestIds = {}));
+/**
+ * Root headless component for menu item details
+ * Provides service context and item data for all child components
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.Root itemDetailsServiceConfig={config}>
+ *   <ItemDetails.Name />
+ *   <ItemDetails.Price />
+ *   <ItemDetails.Description />
+ *   <ItemDetails.Variants />
+ *   <ItemDetails.AddToCartButton />
+ * </ItemDetails.Root>
+ * ```
+ */
 export const Root = ({ children, itemDetailsServiceConfig }) => {
     return (_jsx(CoreItemDetails.Root, { itemDetailsServiceConfig: itemDetailsServiceConfig, children: ({ item }) => _jsx(Item.Root, { item: item, children: children }) }));
 };
+Root.displayName = 'ItemDetails.Root';
+/**
+ * Headless component for item variants selection
+ * Renders variants using Radix UI RadioGroup for single selection
+ * Supports custom rendering via asChild or children render prop
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.Variants
+ *   variantNameClassName="font-paragraph text-foreground"
+ *   variantPriceClassName="font-paragraph text-secondary-foreground"
+ *   emptyState={<div>No variants available</div>}
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.Variants asChild>
+ *   {({ variants, selectedVariantId, onVariantChange }) => (
+ *     <div className="variant-grid">
+ *       {variants.map((variant) => (
+ *         <button
+ *           key={variant._id}
+ *           onClick={() => onVariantChange?.(variant._id ?? '')}
+ *           data-selected={selectedVariantId === variant._id}
+ *         >
+ *           <span>{variant.name}</span>
+ *           <span>{variant.priceInfo?.formattedPrice}</span>
+ *         </button>
+ *       ))}
+ *     </div>
+ *   )}
+ * </ItemDetails.Variants>
+ * ```
+ */
 export const Variants = React.forwardRef(({ children, className, asChild, variantNameClassName, variantPriceClassName, emptyState, }, ref) => {
     return (_jsx(CoreItemDetails.VariantsComponent, { children: ({ variants, hasVariants, selectedVariantId, onVariantChange }) => {
             if (!hasVariants) {
@@ -38,6 +94,42 @@ export const Variants = React.forwardRef(({ children, className, asChild, varian
         } }));
 });
 Variants.displayName = 'ItemDetails.Variants';
+/**
+ * Headless component for adding item to cart
+ * Wraps Commerce.Actions.AddToCart and provides item-specific state
+ * Displays button state, price, and handles disabled states
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.AddToCartButton
+ *   className="bg-primary text-primary-foreground"
+ *   addToCartLabelMap={{
+ *     [AddToCartButtonState.ADD_TO_CART]: 'Add to Cart',
+ *     [AddToCartButtonState.LOADING]: 'Adding...',
+ *     [AddToCartButtonState.UPDATE_CART]: 'Update Cart',
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.AddToCartButton
+ *   addToCartLabelMap={labelMap}
+ *   asChild
+ * >
+ *   {({ buttonState, formattedPrice, modifierGroupHasError, addToCartButtonDisabled }) => (
+ *     <button
+ *       disabled={addToCartButtonDisabled || modifierGroupHasError}
+ *       className="bg-primary text-primary-foreground"
+ *     >
+ *       <span>{labelMap[buttonState]}</span>
+ *       <span>{formattedPrice}</span>
+ *     </button>
+ *   )}
+ * </ItemDetails.AddToCartButton>
+ * ```
+ */
 export const AddToCartButton = React.forwardRef(({ asChild, children, className, addToCartLabelMap, ...props }, ref) => {
     return (_jsx(CoreItemDetails.LineItemComponent, { addToCartLabelMap: addToCartLabelMap, children: ({ lineItem, buttonState, addToCartButtonDisabled, loadingState, labelText, formattedPrice, modifierGroupHasError, }) => {
             const label = (_jsxs(_Fragment, { children: [_jsx("span", { children: labelText }), " ", _jsx("span", { children: " | " }), _jsx("span", { children: formattedPrice })] }));
@@ -54,6 +146,35 @@ export const AddToCartButton = React.forwardRef(({ asChild, children, className,
         } }));
 });
 AddToCartButton.displayName = 'AddToCartButton';
+/**
+ * Headless component for item quantity selection
+ * Provides increment/decrement controls with validation
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.Quantity>
+ *   {({ quantity, increment, decrement, canIncrement, canDecrement }) => (
+ *     <div className="flex items-center gap-2">
+ *       <button
+ *         onClick={decrement}
+ *         disabled={!canDecrement}
+ *         className="bg-secondary text-secondary-foreground"
+ *       >
+ *         -
+ *       </button>
+ *       <span className="font-paragraph text-foreground">{quantity}</span>
+ *       <button
+ *         onClick={increment}
+ *         disabled={!canIncrement}
+ *         className="bg-secondary text-secondary-foreground"
+ *       >
+ *         +
+ *       </button>
+ *     </div>
+ *   )}
+ * </ItemDetails.Quantity>
+ * ```
+ */
 export const Quantity = ({ children }) => {
     return (_jsx(CoreItemDetails.QuantityComponent, { children: ({ quantity, onValueChange, increment, decrement, setQuantity, canIncrement, canDecrement, }) => (_jsx(QuantityComponent.Root, { onValueChange: onValueChange, initialValue: quantity, children: children({
                 quantity,
@@ -66,10 +187,97 @@ export const Quantity = ({ children }) => {
             }) })) }));
 };
 Quantity.displayName = 'Quantity';
+/**
+ * Headless component for special requests or custom instructions
+ * Provides a textarea for customers to add notes or modifications
+ * Supports character count and validation
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.SpecialRequest
+ *   placeholder="Any special requests?"
+ *   maxLength={200}
+ *   rows={3}
+ *   label="Special Requests"
+ *   className="border-foreground text-foreground"
+ *   labelClassName="font-paragraph text-foreground"
+ * />
+ * ```
+ *
+ * @example
+ * Custom rendering with children prop:
+ * ```tsx
+ * <ItemDetails.SpecialRequest asChild>
+ *   {({ value, onChange }) => (
+ *     <div>
+ *       <label>Custom Instructions</label>
+ *       <textarea
+ *         value={value}
+ *         onChange={(e) => onChange(e.target.value)}
+ *         className="border-foreground text-foreground"
+ *       />
+ *       <span className="text-secondary-foreground">
+ *         {value.length}/200
+ *       </span>
+ *     </div>
+ *   )}
+ * </ItemDetails.SpecialRequest>
+ * ```
+ */
 export const SpecialRequest = React.forwardRef(({ className, labelClassName, placeholder = 'Any special requests or dietary restrictions?', maxLength = 200, rows = 3, label = 'Special Requests', asChild, children, ...props }, ref) => {
     return (_jsx(CoreItemDetails.SpecialRequest, { children: ({ value, onChange, }) => (_jsxs(AsChildSlot, { ref: ref, asChild: asChild, className: className, onChange: onChange, "data-testid": TestIds.itemSpecialRequest, customElement: children, customElementProps: { label, value, onChange }, content: value, ...props, children: [label && _jsx("label", { className: labelClassName, children: label }), _jsx("textarea", { value: value, onChange: (e) => onChange(e.target.value), placeholder: placeholder, maxLength: maxLength, rows: rows, className: className, children: value })] })) }));
 });
 SpecialRequest.displayName = 'SpecialRequest';
+/**
+ * Headless component for item availability status display
+ * Shows availability messages and optional action buttons
+ * Does not render when item is available
+ *
+ * @example
+ * ```tsx
+ * <ItemDetails.AvailabilityComponent
+ *   availabilityStatusMap={{
+ *     [AvailabilityStatus.OUT_OF_STOCK]: {
+ *       text: 'Currently unavailable',
+ *       buttonText: 'Notify me',
+ *       action: () => handleNotify(),
+ *     },
+ *     [AvailabilityStatus.LIMITED_STOCK]: {
+ *       text: 'Limited availability',
+ *     },
+ *   }}
+ *   textClassName="text-destructive"
+ *   buttonClassName="bg-primary text-primary-foreground"
+ * >
+ *   {({ availabilityStatus, availabilityStatusText }) => (
+ *     <div>{availabilityStatusText}</div>
+ *   )}
+ * </ItemDetails.AvailabilityComponent>
+ * ```
+ *
+ * @example
+ * Custom rendering with action button:
+ * ```tsx
+ * <ItemDetails.AvailabilityComponent
+ *   availabilityStatusMap={statusMap}
+ *   asChild
+ * >
+ *   {({ availabilityStatus, availabilityStatusText, availabilityStatusButtonText, availabilityAction }) => (
+ *     <div className="bg-destructive/10 p-4">
+ *       <p className="text-destructive">{availabilityStatusText}</p>
+ *       {availabilityStatusButtonText && availabilityAction && (
+ *         <button
+ *           onClick={availabilityAction}
+ *           className="bg-primary text-primary-foreground"
+ *         >
+ *           {availabilityStatusButtonText}
+ *         </button>
+ *       )}
+ *     </div>
+ *   )}
+ * </ItemDetails.AvailabilityComponent>
+ * ```
+ */
 export const AvailabilityComponent = React.forwardRef(({ asChild, children, textClassName, buttonClassName, availabilityStatusMap, ...rest }, ref) => {
     return (_jsx(CoreItemDetails.AvailabilityComponent, { availabilityStatusMap: availabilityStatusMap, children: ({ availabilityStatus, availabilityAction, availabilityStatusText, availabilityStatusButtonText, }) => {
             if (availabilityStatus === AvailabilityStatus.AVAILABLE) {