@propeller-commerce/propeller-v2-react-ui 0.16.0 → 0.19.0

package/dist/index.d.ts

@@ -555,7 +555,7 @@ interface AddItemOptions {
     onAddToCart?: (product: Product, clusterId?: number, quantity?: number, childItems?: {
         productId: number;
         quantity: number;
-    }[], notes?: string, price?: number) => Cart;
+    }[], notes?: string, price?: number) => Cart | Promise<Cart>;
     /** Fires after the item is added — receives the updated cart and the matched line item. */
     afterAddToCart?: (cart: Cart, item: CartMainItem | null) => void;
     /** When `true`, rejects the add if `product.inventory.totalQuantity` is below `quantity`. */
@@ -597,6 +597,15 @@ interface UseCartReturn {
         cart: Cart;
         item: CartMainItem | null;
     }, string>>;
+    /**
+     * Adds several products in one call, sequentially, threading the resolved
+     * cart id from each add into the next. Use this instead of looping over
+     * `addItem` yourself. Stops at the first failure and returns that error.
+     */
+    addItems: (items: AddItemOptions[]) => Promise<Result<{
+        cart: Cart;
+        items: (CartMainItem | null)[];
+    }, string>>;
     /** Updates a line item's quantity. */
     updateItemQuantity: (cartItemId: string, quantity: number) => Promise<Cart | undefined>;
     /** Debounced update of a line item's notes (`debounceMs` defaults to 500). */
@@ -894,6 +903,13 @@ interface FavoriteListFormData {
     isDefault: boolean;
 }
 /** Options for {@link useFavorites}. */
+/** What a favorite-list mutation did — see `onListChanged`. */
+interface FavoriteListChange {
+    action: 'created' | 'updated' | 'deleted';
+    listId?: string | number;
+    name?: string;
+    isDefault?: boolean;
+}
 interface UseFavoritesOptions {
     /** GraphQL client the hook derives its Services bundle from. */
     graphqlClient: GraphQLClient;
@@ -908,7 +924,15 @@ interface UseFavoritesOptions {
     /** Override: fires instead of the default `deleteFavoriteList` call. */
     onDelete?: (id: string) => void;
     /** Fires after any list create / update / delete completes. */
-    onListChanged?: () => void;
+    /**
+     * Called after a list mutation succeeds.
+     *
+     * The `change` argument is optional so existing zero-argument callbacks keep
+     * working, but without it a host cannot tell a create from a delete — which
+     * makes the hook useless for analytics, audit trails or optimistic UI that
+     * needs to know WHAT happened rather than merely THAT something did.
+     */
+    onListChanged?: (change?: FavoriteListChange) => void;
 }
 /** State and favorite-list actions returned by {@link useFavorites}. */
 interface UseFavoritesReturn {
@@ -1412,6 +1436,9 @@ interface UseProductSearchOptions {
     /** Portal configuration: base category fallback plus image filters. */
     configuration: {
         baseCategoryId?: number;
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
         imageSearchFiltersGrid?: MediaImageProductSearchInput;
         imageVariantFiltersMedium?: TransformationsInput;
     };
@@ -1547,6 +1574,9 @@ interface UseQuickOrderOptions {
         imageVariantFiltersSmall?: TransformationsInput;
         /** Catalog root. Without it the search returns nothing — see `searchProducts`. */
         baseCategoryId?: number;
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
     };
     /** Fires when `submit` creates a fresh cart — persist the cart id. */
     onCartCreated?: (cart: Cart) => void;
@@ -1659,6 +1689,9 @@ interface UseSparePartsOptions {
     pageSize?: number;
     /** Image filter config, mirroring `useProductSearch`'s `configuration`. */
     configuration?: {
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
         imageSearchFiltersGrid?: unknown;
         imageVariantFiltersMedium?: unknown;
     };
@@ -1773,6 +1806,9 @@ interface UseProductSliderOptions {
     companyId?: number;
     /** Portal configuration: image search/variant filters. */
     configuration?: {
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
         imageSearchFiltersGrid?: MediaImageProductSearchInput;
         imageVariantFiltersMedium?: TransformationsInput;
     };
@@ -2673,7 +2709,7 @@ interface AddToCartProps {
      * Callback to handle adding the product to cart.
      * If not provided the component calls CartService.addItemToCart internally.
      */
-    onAddToCart?: (product: Product, clusterId?: number, quantity?: number, childItems?: CartChildItemInput[], notes?: string, price?: number, showModal?: boolean) => Cart;
+    onAddToCart?: (product: Product, clusterId?: number, quantity?: number, childItems?: CartChildItemInput[], notes?: string, price?: number, showModal?: boolean) => Cart | Promise<Cart>;
     /**
      * Callback triggered after adding the product to cart.
      */
@@ -2698,6 +2734,11 @@ interface AddToCartProps {
     language?: string;
     /** Additional CSS class for the root element */
     className?: string;
+    /**
+     * Labels for the bonus-items block in the success modal.
+     * Keys: `title` ('Bonus items'), `sku` ('SKU').
+     */
+    bonusItemsLabels?: Record<string, string>;
     /** Callback fired when the "Proceed to checkout" modal button is clicked */
     onProceedToCheckout?: () => void;
     /** Callback fired when the "Request a Quote" modal button is clicked */
@@ -2779,6 +2820,13 @@ interface AddToCartEvents {
 declare function AddToCart(rawProps: AddToCartProps): React$1.JSX.Element;
 declare const _default$1: React$1.MemoExoticComponent<typeof AddToCart>;
 
+/** Which way the favorite toggle went — see `onFavoriteChanged`. */
+interface FavoriteChange {
+    action: 'added' | 'removed';
+    listId?: string | number;
+    productId?: number;
+    clusterId?: number;
+}
 interface AddToFavoriteProps {
     /** The initialized GraphQL Client instance. Resolved from PropellerProvider when omitted. */
     graphqlClient?: GraphQLClient;
@@ -2793,7 +2841,15 @@ interface AddToFavoriteProps {
     /** UI string overrides */
     labels?: Record<string, string>;
     /** Called after a favorite list mutation (add/remove) succeeds */
-    onFavoriteChanged?: () => void;
+    /**
+     * Called after the favorite toggle succeeds, with which way it went.
+     *
+     * The argument is optional so existing zero-argument callbacks keep working.
+     * Without it an add and a removal are indistinguishable, so a host cannot
+     * report "added to wishlist" without inventing the direction — and a
+     * wishlist metric that also counts removals is worse than none.
+     */
+    onFavoriteChanged?: (change?: FavoriteChange) => void;
 }
 /**
  * Favorite toggle button for a product or cluster: opens a modal to add the
@@ -3085,6 +3141,12 @@ declare function CartBonusItems(rawProps: CartBonusItemsProps): React$1.JSX.Elem
  */
 
 interface CartCarriersProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading.
+     */
+    language?: string;
     /** Shopping cart object from which the carriers will be displayed */
     cart: Cart;
     /** The CSS class for the carriers container */
@@ -3326,7 +3388,8 @@ interface CartIconAndSidebarProps {
     /**
      * Labels for the component.
      * Available keys: cartIconLabel, totalLabel, itemsLabel, emptyCart,
-     * continueShopping, qty, total, checkoutButton, cartPageButton, closeLabel
+     * continueShopping, qty, total, totalExclVat, checkoutButton, cartPageButton,
+     * closeLabel
      */
     labels?: Record<string, string>;
     /**
@@ -3433,6 +3496,12 @@ declare function CartOverview(props: CartOverviewProps): React$1.JSX.Element;
  */
 
 interface CartPaymethodsProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading. Resolved from `<PropellerProvider>` when omitted.
+     */
+    language?: string;
     /** Shopping cart object from which the payment methods will be displayed */
     cart: Cart;
     /** Authenticated user — used for cart creation / lookup. Resolved from `<PropellerProvider>` when not passed explicitly. */
@@ -3474,10 +3543,18 @@ declare function CartPaymethods(rawProps: CartPaymethodsProps): React$1.JSX.Elem
  */
 
 interface CartSummaryProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading. Resolved from `<PropellerProvider>` when omitted.
+     */
+    language?: string;
     /** The shopping cart used to populate the cart summary data */
     cart: Cart;
     /** Cart summary block title */
     title?: string;
+    /** Extra classes for the panel root, merged over the defaults via tailwind-merge. */
+    className?: string;
     /** Labels for the component */
     labels?: Record<string, string>;
     /** Display the subtotal of the shopping cart. Defaults to `true`. */
@@ -4531,8 +4608,12 @@ interface FavoriteListsProps {
     }) => void;
     /** Action function triggered when deleting a favorite list. If not provided, the default action is executed */
     onDelete?: (favoriteListId: string) => void;
-    /** Called after any list mutation (create, edit, delete) succeeds */
-    onListChanged?: () => void;
+    /**
+     * Called after any list mutation succeeds, with what it did.
+     *
+     * The argument is optional so existing zero-argument callbacks keep working.
+     */
+    onListChanged?: (change?: FavoriteListChange) => void;
 }
 /**
  * Lists the user's favorite lists with inline edit, delete and create-list
@@ -4678,6 +4759,8 @@ interface GridFiltersProps {
     /** Translated labels keyed by the slugs used inside the component (see
      * `getLabel` calls). Missing keys fall back to the English defaults. */
     labels?: Record<string, string>;
+    /** Currency symbol shown in the price-range inputs. Falls back to PropellerInfra.currency, then `'€'`. */
+    currency?: string;
 }
 /**
  * Faceted filter sidebar for a product grid: collapsible attribute checkbox
@@ -5196,9 +5279,22 @@ interface OrderItemCardProps {
      * This component is RSC-safe (no hooks, no context), so the host has to pass
      * it — there is nothing to read it from. Without it a non-default storefront
      * renders default-language names and, worse, default-language slugs in the
-     * links (PWP-940).
+     * links.
      */
     language?: string;
+    /**
+     * URL builders from the host's configuration. Supply them and the item link
+     * is generated the same way every other link on the storefront is — which is
+     * what carries the locale prefix. Without it the component falls back to a
+     * bare `/product/:id/:slug`, and on a prefixed storefront that link drops the
+     * visitor onto the default language.
+     */
+    configuration?: {
+        urls?: {
+            getProductUrl?: (product: Product, language?: string) => string;
+            getClusterUrl?: (cluster: Cluster, language?: string) => string;
+        };
+    };
     /** Should the item title be a link to the PDP */
     titleLinkable?: boolean;
     /** Display a small thumbnail of the order item */
@@ -5273,6 +5369,12 @@ declare function OrderBonusItems(rawProps: OrderBonusItemsProps): React$1.JSX.El
  */
 
 interface OrderListProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading. Resolved from `<PropellerProvider>` when omitted.
+     */
+    language?: string;
     /** The authenticated user (Contact or Customer). Resolved from PropellerProvider when omitted. */
     user?: Contact | Customer | null;
     /** The initialized GraphQL Client instance. Resolved from PropellerProvider when omitted. */
@@ -5418,6 +5520,9 @@ interface QuickOrderProps {
          * has no access to.
          */
         baseCategoryId?: number;
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
     };
     /** Tax zone for price calculation. Defaults to `'NL'`. */
     taxZone?: string;
@@ -5440,6 +5545,12 @@ interface QuickOrderProps {
     parseSpreadsheet?: (file: File) => Promise<QuickOrderUploadLine[]>;
     /** URL to a downloadable XLSX template (shown next to the upload control). */
     templateUrl?: string;
+    /**
+     * Called when the template link is clicked. Navigation is untouched — this is
+     * a notification, not a handler: a buyer fetching the template is a
+     * quick-order intent signal that otherwise leaves no trace at all.
+     */
+    onTemplateDownload?: () => void;
     /** Max upload file size in bytes. Defaults to 2 MB. */
     maxUploadBytes?: number;
     /** Max rows accepted from an upload. Defaults to 500. */
@@ -5509,6 +5620,12 @@ declare function OrderShipments(props: OrderShipmentsProps): React$1.JSX.Element
  */
 
 interface OrderSummaryProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading.
+     */
+    language?: string;
     /** The order object from propeller-sdk-v2 */
     order: any;
     /** The CSS class for the order summary container */
@@ -5572,6 +5689,12 @@ declare function OrderSummary(props: OrderSummaryProps): React$1.JSX.Element;
  */
 
 interface OrderTotalsProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading.
+     */
+    language?: string;
     /** The order/quote used to populate the summary data */
     order: Order;
     /** Order summary block title */
@@ -5654,6 +5777,12 @@ declare function PriceToggle(props: PriceToggleProps): React$1.JSX.Element;
  */
 
 interface ProductBulkPricesProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading.
+     */
+    language?: string;
     /**
      * Bulk price tiers from the product.
      * Obtain from `product.bulkPrices`.
@@ -5940,6 +6069,8 @@ interface ProductCardProps {
      * See `ProductPriceProps.labels` for slugs (inclTax, exclTax, loginToSeePrices). */
     priceLabels?: Record<string, string>;
     /** Replaces the default price block. Receives `PriceComponentProps`. */
+    /** Currency symbol used when formatting the price. Falls back to PropellerInfra.currency, then `'€'`. */
+    currency?: string;
     priceComponent?: React$1.ComponentType<_propeller_commerce_propeller_v2_core_ui.PriceComponentProps>;
     /** Replaces the default stock/availability block. Receives `StockComponentProps`. */
     stockComponent?: React$1.ComponentType<_propeller_commerce_propeller_v2_core_ui.StockComponentProps>;
@@ -6312,6 +6443,9 @@ interface ProductGridProps {
      */
     configuration?: {
         baseCategoryId?: number;
+        /** The channel's anonymous user, seeded by the host. Scopes logged-out
+         *  listings exactly like the SSR seed does. */
+        anonymousUserId?: number;
         imageSearchFiltersGrid?: MediaImageProductSearchInput;
         imageVariantFiltersMedium?: TransformationsInput;
         urls?: {
@@ -6634,6 +6768,12 @@ declare const ProductInfoExport: ProductInfoComponent;
  */
 
 interface ProductPriceProps {
+    /**
+     * Storefront language ('EN', 'NL', …). Decides the number format prices are
+     * rendered in — without it they fall back to Dutch separators regardless of
+     * the language the shopper is reading.
+     */
+    language?: string;
     /**
      * ProductPrice object from the product.
      * Obtain from `product.price`.
@@ -7403,6 +7543,8 @@ interface SearchBarProps {
     priceLabels?: Record<string, string>;
     /** Additional class name for the container */
     containerClassName?: string;
+    /** Extra classes for the search input, merged over the defaults via tailwind-merge. */
+    inputClassName?: string;
     /** Tax zone used for price calculation. Defaults to 'NL'. */
     taxZone?: string;
     /**