@wix/headless-stores 0.0.0

package/dist/react/ProductList.d.ts

@@ -0,0 +1,400 @@
+import type { V3Product } from '@wix/auto_sdk_stores_products-v-3';
+import { Sort as SortPrimitive, GenericListTotalsRenderProps, GenericListLoadMoreRenderProps, ListVariant, GenericListRepeaterRenderProps } from '@wix/headless-components/react';
+import React from 'react';
+import type { ProductsListServiceConfig } from '../services/products-list-service.js';
+import { productsV3 } from '@wix/stores';
+import { AsChildChildren } from '@wix/headless-utils/react';
+/**
+ * Props for the ProductList root component following the documented API
+ */
+export interface ProductListRootProps {
+    children: React.ReactNode;
+    products?: V3Product[];
+    productsListConfig?: ProductsListServiceConfig;
+    className?: string;
+    variant?: ListVariant;
+}
+/**
+ * Root component that provides the ProductList service context for rendering product lists.
+ *
+ * @order 1
+ * @component
+ * @example
+ * ```tsx
+ * import { ProductList } from '@wix/stores/components';
+ *
+ * function ProductListPage({ products }) {
+ *   return (
+ *     <ProductList.Root products={products}>
+ *       <ProductList.Products>
+ *         <ProductList.ProductRepeater>
+ *           <Product.Name />
+ *           <Product.Price />
+ *         </ProductList.ProductRepeater>
+ *       </ProductList.Products>
+ *     </ProductList.Root>
+ *   );
+ * }
+ * ```
+ */
+export declare const Root: React.ForwardRefExoticComponent<ProductListRootProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for ProductList Raw component
+ */
+export interface RawProps {
+    children: ((props: {
+        totalProducts: number;
+        displayedProducts: number;
+        isFiltered: boolean;
+    }) => React.ReactNode) | React.ReactNode;
+}
+/**
+ * Raw component that provides direct access to product list data.
+ * Similar to Product.Raw, this should only be used when you need custom access to list data.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ProductList.Raw>
+ *   {({ totalProducts, displayedProducts, isFiltered }) => (
+ *     <div className="text-content-muted">
+ *       Showing {displayedProducts} of {totalProducts} products
+ *       {isFiltered && <span className="ml-2 text-brand-primary">(Filtered)</span>}
+ *     </div>
+ *   )}
+ * </ProductList.Raw>
+ * ```
+ */
+export declare const Raw: React.ForwardRefExoticComponent<RawProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for ProductList Products component
+ */
+export interface ProductsProps {
+    children: React.ReactNode;
+    emptyState?: React.ReactNode;
+    infiniteScroll?: boolean;
+    pageSize?: number;
+    className?: string;
+}
+/**
+ * Container for the product list with empty state support.
+ * Follows List Container Level pattern.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ProductList.Products emptyState={<div>No products found</div>}>
+ *   <ProductList.ProductRepeater>
+ *     <Product.Name />
+ *     <Product.Price />
+ *   </ProductList.ProductRepeater>
+ * </ProductList.Products>
+ * ```
+ */
+export declare const Products: React.ForwardRefExoticComponent<ProductsProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Render props for ProductRepeater asChild pattern
+ */
+export type ProductRepeaterRenderProps = GenericListRepeaterRenderProps<V3Product>;
+/**
+ * Props for ProductList ProductRepeater component
+ */
+export interface ProductRepeaterProps {
+    children: React.ReactNode | ((props: ProductRepeaterRenderProps, ref: React.Ref<HTMLElement>) => React.ReactNode);
+    /** Whether to render as child component (asChild pattern) */
+    asChild?: boolean;
+}
+/**
+ * Repeater component that renders Product.Root for each product.
+ * Follows Repeater Level pattern and uses GenericList.Repeater for consistency.
+ * Supports asChild pattern for advanced layout components like GalleryWrapper.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Standard usage
+ * <ProductList.ProductRepeater>
+ *   <Product.Name />
+ *   <Product.Price />
+ * </ProductList.ProductRepeater>
+ *
+ * // AsChild usage with GalleryWrapper
+ * <ProductList.ProductRepeater asChild>
+ *   {({ items, variant, itemWrapper }) => (
+ *     <GalleryWrapper
+ *       items={items}
+ *       variant={variant}
+ *       itemRenderer={(item, index) =>
+ *         itemWrapper({ item, index, children: <>
+ *           <Product.Name />
+ *           <Product.Price />
+ *         </> })
+ *       }
+ *     />
+ *   )}
+ * </ProductList.ProductRepeater>
+ * ```
+ */
+export declare const ProductRepeater: React.ForwardRefExoticComponent<ProductRepeaterProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for ProductList LoadMoreTrigger component
+ */
+export interface LoadMoreTriggerProps {
+    /** Custom render function when using asChild */
+    children?: React.ReactNode | React.ForwardRefRenderFunction<HTMLButtonElement, GenericListLoadMoreRenderProps>;
+    /**
+     * Whether to render as a child component.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * The CSS classes to apply to the button.
+     */
+    className?: string;
+    /**
+     * The label to display inside the button.
+     */
+    label?: string;
+    /**
+     * The loading state to display inside the button.
+     */
+    loadingState?: React.ReactNode;
+}
+/**
+ * Displays a button to load more products. Not rendered if infiniteScroll is false or no products are left to load.
+ * Follows the architecture rules - does not support asChild as it's a simple trigger component.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ProductList.LoadMoreTrigger asChild>
+ *   <button>Load More</button>
+ * </ProductList.LoadMoreTrigger>
+ * ```
+ */
+export declare const LoadMoreTrigger: React.ForwardRefExoticComponent<LoadMoreTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Props for ProductList Totals Displayed component
+ */
+export interface TotalsDisplayedProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<GenericListTotalsRenderProps>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Displays the number of products currently displayed.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ProductList.TotalsDisplayed />
+ * // or with asChild
+ * <ProductList.TotalsDisplayed asChild>
+ *   <strong />
+ * </ProductList.TotalsDisplayed>
+ * // or with render function
+ * <ProductList.TotalsDisplayed asChild>
+ *   {({ displayedItems }, ref) => <strong ref={ref}>{displayedItems}</strong>}
+ * </ProductList.TotalsDisplayed>
+ * ```
+ */
+export declare const TotalsDisplayed: React.ForwardRefExoticComponent<TotalsDisplayedProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for the ProductList Sort component
+ */
+export interface SortProps {
+    /**
+     * Render function that provides sort state and controls when using asChild pattern.
+     * Only called when asChild is true and children is provided.
+     *
+     * @param props.currentSort - Current sort configuration from Wix Stores API
+     * @param props.sortOptions - Available sort options with field names, order, and labels
+     * @param props.setSort - Function to update the sort configuration
+     *
+     * @example
+     * ```tsx
+     * <ProductList.Sort asChild>
+     *   {({ currentSort, sortOptions, setSort }) => (
+     *     <CustomSortSelect
+     *       value={currentSort}
+     *       options={sortOptions}
+     *       onChange={setSort}
+     *     />
+     *   )}
+     * </ProductList.Sort>
+     * ```
+     */
+    children?: (props: {
+        currentSort: productsV3.V3ProductSearch['sort'];
+        sortOptions: SortPrimitive.SortOption[];
+        setSort: (sort: productsV3.V3ProductSearch['sort']) => void;
+    }) => React.ReactNode;
+    /**
+     * CSS classes to apply to the sort component.
+     * Only used when asChild is false (default rendering).
+     */
+    className?: string;
+    /**
+     * Render mode for the default sort component.
+     * - 'select': Renders as HTML select dropdown
+     * - 'list': Renders as clickable list of options
+     *
+     * @default 'select'
+     */
+    as?: 'select' | 'list';
+    /**
+     * When true, the component uses the asChild pattern and delegates
+     * rendering to the children render function. When false (default),
+     * renders the built-in Sort.Root component.
+     *
+     * @default false
+     */
+    asChild?: boolean;
+}
+/**
+ * Sort component for product lists that provides sorting functionality.
+ *
+ * This component integrates with the ProductList service to provide predefined sort options
+ * including name (A-Z, Z-A) and price (low to high, high to low). It supports both
+ * controlled rendering via the asChild pattern and default UI rendering.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default select dropdown
+ * <ProductList.Sort />
+ *
+ * // As list of clickable options
+ * <ProductList.Sort as="list" />
+ *
+ * // With custom styling
+ * <ProductList.Sort
+ *   as="select"
+ *   className="custom-sort-select"
+ * />
+ *
+ * // Custom implementation using asChild pattern
+ * <ProductList.Sort asChild>
+ *   {({ currentSort, sortOptions, setSort }) => (
+ *     <div className="custom-sort-container">
+ *       {sortOptions.map((option) => (
+ *         <button
+ *           key={`${option.fieldName}-${option.order}`}
+ *           onClick={() => setSort([{ fieldName: option.fieldName, order: option.order }])}
+ *           className={isCurrentSort(option) ? 'active' : ''}
+ *         >
+ *           {option.label}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   )}
+ * </ProductList.Sort>
+ * ```
+ *
+ * @see {@link ProductListSortPrimitive} for the underlying sort logic
+ * @see {@link SortPrimitive.Root} for the primitive sort component
+ */
+export declare const Sort: React.ForwardRefExoticComponent<SortProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Props for ProductList Filter component
+ */
+export interface FilterProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Child components that will have access to filter functionality */
+    children: React.ReactNode;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+export declare const Filter: {
+    Root: React.ForwardRefExoticComponent<FilterProps & React.RefAttributes<HTMLElement>>;
+};
+/**
+ * Props for ProductList FilterResetTrigger component
+ */
+export interface FilterResetTriggerProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        resetFilters: () => void;
+        isFiltered: boolean;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+    /** Label for the button */
+    label?: string;
+}
+/**
+ * Reset trigger component for clearing all applied filters.
+ * Provides reset functionality and filter state to custom render functions.
+ * Only renders when filters are applied.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage
+ * <ProductList.FilterResetTrigger className="reset-filters-btn" />
+ *
+ * // With custom label
+ * <ProductList.FilterResetTrigger label="Clear Filters" />
+ *
+ * // Custom rendering with forwardRef
+ * <ProductList.FilterResetTrigger asChild>
+ *   {React.forwardRef(({resetFilters, isFiltered, ...props}, ref) => (
+ *     <button
+ *       ref={ref}
+ *       {...props}
+ *       onClick={resetFilters}
+ *       disabled={!isFiltered}
+ *       className="custom-reset-button disabled:opacity-50"
+ *     >
+ *       Reset All Filters
+ *     </button>
+ *   ))}
+ * </ProductList.FilterResetTrigger>
+ * ```
+ */
+export declare const FilterResetTrigger: React.ForwardRefExoticComponent<FilterResetTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Props for ProductList Error component
+ */
+export interface ErrorProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        error: string | null;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Error component that displays product list errors.
+ * Provides error data to custom render functions.
+ * Only renders when there's an error.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage
+ * <ProductList.Error className="error-message" />
+ *
+ * // Custom rendering with forwardRef
+ * <ProductList.Error asChild>
+ *   {React.forwardRef(({error, ...props}, ref) => (
+ *     <div
+ *       ref={ref}
+ *       {...props}
+ *       className="custom-error-container"
+ *     >
+ *       Error: {error}
+ *     </div>
+ *   ))}
+ * </ProductList.Error>
+ * ```
+ */
+export declare const Error: React.ForwardRefExoticComponent<ErrorProps & React.RefAttributes<HTMLElement>>;