From f1cf48e9012ba285b4d99e0418a200bcd824fb06 Mon Sep 17 00:00:00 2001 From: chutingy Date: Fri, 15 May 2026 15:04:35 -0500 Subject: [PATCH 1/4] add docs --- .../cart/containers/cart-summary-list.mdx | 24 +++++ .../dropins/cart/containers/mini-cart.mdx | 3 + src/content/docs/dropins/cart/slots.mdx | 90 ++++++++++++++++++- 3 files changed, 115 insertions(+), 2 deletions(-) diff --git a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx index 4a29b06fc..8ea7014e5 100644 --- a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx +++ b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx @@ -51,6 +51,7 @@ The `CartSummaryList` container provides the following configuration options: | `dropdownOptions` | `string[]` | No | An array of items to display in a dropdown menu. | | `undo` | `boolean` | No | Enables the undo banner to restore recently removed items to the cart. | | `includeOutOfStockItems` | `boolean` | No | Display out-of-stock and insufficient-quantity items in the main cart item list alongside in-stock items. Default: `false`. | +| `confirmBeforeDelete` | `boolean` | No | When `true`, reducing an item's quantity to 0 or clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. Confirming triggers the delete; cancelling restores the original quantity. Defaults to `false`. | @@ -70,6 +71,7 @@ The `CartSummaryList` container supports the following slots: * CartSummaryFooter * CartItem * UndoBanner +* ConfirmDeleteBanner * ItemTitle * ItemPrice * ItemQuantity @@ -77,6 +79,27 @@ The `CartSummaryList` container supports the following slots: * ItemSku * ItemRemoveAction +## QuantityIncrementer + +`CartSummaryList` uses `QuantityIncrementer` as its built-in quantity stepper. It wraps the SDK `Incrementer` component and adds an empty-input error state: when a shopper clears the quantity field to blank, the `+` and `−` buttons are disabled and an error style is applied so no cart update is sent until a valid number is entered. + +The component is also available as a named export for use in custom `ItemQuantity` slots: + +```js +import { QuantityIncrementer } from '@dropins/storefront-cart/components/QuantityIncrementer.js'; +``` + + + +| Prop | Type | Required | Description | +|------|------|----------|-------------| +| `item` | `CartModel['items'][0]` | Yes | The cart item whose `quantity` seeds the stepper. | +| `disabled` | `boolean` | Yes | Disables the entire stepper (passed through to `Incrementer`). | +| `ariaLabel` | `string` | Yes | Accessible label for the stepper input. | +| `onValue` | `(value: number) => void` | Yes | Called with the new quantity after the user commits a valid value. | + + + ## Example configuration The following example demonstrates how to render the `CartSummaryList` container with the `routeProduct` and `routeEmptyCartCTA` callbacks: @@ -86,6 +109,7 @@ provider.render(CartSummaryList, { enableRemoveItem: true, enableUpdateItemQuantity: true, showDiscount: true, + // confirmBeforeDelete: true, // accordion: true, // includeOutOfStockItems: true, // showMaxItems: false, diff --git a/src/content/docs/dropins/cart/containers/mini-cart.mdx b/src/content/docs/dropins/cart/containers/mini-cart.mdx index 32b96338e..047a5a619 100644 --- a/src/content/docs/dropins/cart/containers/mini-cart.mdx +++ b/src/content/docs/dropins/cart/containers/mini-cart.mdx @@ -40,6 +40,7 @@ The `MiniCart` container provides the following configuration options: | `enableQuantityUpdate` | `boolean` | No | Flag to enable updating item quantities in the mini cart. When set to true, users can adjust product quantities directly in the mini cart interface. | | `hideHeading` | `boolean` | No | Flag to hide the heading in the mini cart. When set to true, the mini cart header will not be displayed. | | `undo` | `boolean` | No | Enables the undo banner to restore recently removed items to the cart. | +| `confirmBeforeDelete` | `boolean` | No | When `true`, clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. Forwarded to the internal `CartSummaryList`. Defaults to `false`. | @@ -61,6 +62,7 @@ The `MiniCart` container supports the following slots: * CartSummaryFooter * CartItem * UndoBanner +* ConfirmDeleteBanner * ItemTitle * ItemPrice * ItemQuantity @@ -85,5 +87,6 @@ provider.render(MiniCart, { // enableItemRemoval: true, // enableQuantityUpdate: true, // hideHeading: true, + // confirmBeforeDelete: true, })($miniCart); ``` \ No newline at end of file diff --git a/src/content/docs/dropins/cart/slots.mdx b/src/content/docs/dropins/cart/slots.mdx index 63b07dc16..9b03343a6 100644 --- a/src/content/docs/dropins/cart/slots.mdx +++ b/src/content/docs/dropins/cart/slots.mdx @@ -27,10 +27,10 @@ Do not use context methods inside other context methods (for example, `appendChi | Container | Slots | |-----------|-------| | [`CartSummaryGrid`](#cartsummarygrid-slots) | `Thumbnail` | -| [`CartSummaryList`](#cartsummarylist-slots) | `Heading`, `EmptyCart`, `Footer`, `RowTotalFooter`, `Thumbnail`, `ProductAttributes`, `CartSummaryFooter`, `CartItem`, `UndoBanner`, `ItemTitle`, `ItemPrice`, `ItemQuantity`, `ItemTotal`, `ItemSku`, `ItemRemoveAction` | +| [`CartSummaryList`](#cartsummarylist-slots) | `Heading`, `EmptyCart`, `Footer`, `RowTotalFooter`, `Thumbnail`, `ProductAttributes`, `CartSummaryFooter`, `CartItem`, `UndoBanner`, `ConfirmDeleteBanner`, `ItemTitle`, `ItemPrice`, `ItemQuantity`, `ItemTotal`, `ItemSku`, `ItemRemoveAction` | | [`CartSummaryTable`](#cartsummarytable-slots) | `Item`, `Price`, `Quantity`, `Subtotal`, `Thumbnail`, `ProductTitle`, `Sku`, `Configurations`, `ItemAlert`, `ItemWarning`, `Actions`, `UndoBanner`, `EmptyCart` | | [`GiftOptions`](#giftoptions-slots) | `SwatchImage` | -| [`MiniCart`](#minicart-slots) | `ProductList`, `ProductListFooter`, `PreCheckoutSection`, `Thumbnail`, `Heading`, `EmptyCart`, `Footer`, `RowTotalFooter`, `ProductAttributes`, `CartSummaryFooter`, `CartItem`, `UndoBanner`, `ItemTitle`, `ItemPrice`, `ItemQuantity`, `ItemTotal`, `ItemSku`, `ItemRemoveAction` | +| [`MiniCart`](#minicart-slots) | `ProductList`, `ProductListFooter`, `PreCheckoutSection`, `Thumbnail`, `Heading`, `EmptyCart`, `Footer`, `RowTotalFooter`, `ProductAttributes`, `CartSummaryFooter`, `CartItem`, `UndoBanner`, `ConfirmDeleteBanner`, `ItemTitle`, `ItemPrice`, `ItemQuantity`, `ItemTotal`, `ItemSku`, `ItemRemoveAction` | | [`OrderSummary`](#ordersummary-slots) | `EstimateShipping`, `Coupons`, `GiftCards` | @@ -98,6 +98,11 @@ interface CartSummaryListProps { onUndo: () => void; onDismiss: () => void; }>; + ConfirmDeleteBanner?: SlotProps<{ + item: CartModel['items'][number]; + onConfirm: () => void; + onCancel: () => void; + }>; ItemTitle?: SlotProps<{ item: CartModel['items'][number] }>; ItemPrice?: SlotProps<{ item: CartModel['items'][number] }>; ItemQuantity?: SlotProps<{ @@ -337,6 +342,44 @@ await provider.render(CartSummaryList, { })(block); ``` +### ConfirmDeleteBanner slot + +The `ConfirmDeleteBanner` slot lets you replace the default confirmation banner that appears when `confirmBeforeDelete={true}` and a shopper reduces an item's quantity to 0 or clicks the remove button. Use it to customize the banner's appearance, message text, and action buttons. + +#### Context + +The slot receives the following context: + +| Property | Type | Description | +|----------|------|-------------| +| `item` | `CartModel['items'][number]` | The cart item pending deletion. | +| `onConfirm` | `() => void` | Call to confirm deletion and trigger the remove API. | +| `onCancel` | `() => void` | Call to dismiss the banner and restore the item row with its original quantity. | + +#### Example + +```js +import { render as provider } from '@dropins/storefront-cart/render.js'; +import { CartSummaryList } from '@dropins/storefront-cart/containers/CartSummaryList.js'; + +await provider.render(CartSummaryList, { + confirmBeforeDelete: true, + slots: { + ConfirmDeleteBanner: (ctx) => { + const banner = document.createElement('div'); + banner.innerHTML = ` +

Remove "${ctx.item.name}" from your cart?

+ + + `; + banner.querySelector('#confirm').addEventListener('click', ctx.onConfirm); + banner.querySelector('#cancel').addEventListener('click', ctx.onCancel); + ctx.appendChild(banner); + } + } +})(block); +``` + ### ItemTitle slot The `ItemTitle` slot allows you to customize the item title section of the `CartSummaryList` container. @@ -536,6 +579,11 @@ interface MiniCartProps { onUndo: () => void; onDismiss: () => void; }>; + ConfirmDeleteBanner?: SlotProps<{ + item: CartModel['items'][number]; + onConfirm: () => void; + onCancel: () => void; + }>; ItemTitle?: SlotProps<{ item: CartModel['items'][number] }>; ItemPrice?: SlotProps<{ item: CartModel['items'][number] }>; ItemQuantity?: SlotProps<{ @@ -820,6 +868,44 @@ await provider.render(MiniCart, { })(block); ``` +### ConfirmDeleteBanner slot + +The `ConfirmDeleteBanner` slot lets you replace the default confirmation banner that appears when `confirmBeforeDelete={true}` and a shopper clicks the remove button. Use it to customize the banner's appearance, message text, and action buttons. + +#### Context + +The slot receives the following context: + +| Property | Type | Description | +|----------|------|-------------| +| `item` | `CartModel['items'][number]` | The cart item pending deletion. | +| `onConfirm` | `() => void` | Call to confirm deletion and trigger the remove API. | +| `onCancel` | `() => void` | Call to dismiss the banner and restore the item row with its original quantity. | + +#### Example + +```js +import { render as provider } from '@dropins/storefront-cart/render.js'; +import { MiniCart } from '@dropins/storefront-cart/containers/MiniCart.js'; + +await provider.render(MiniCart, { + confirmBeforeDelete: true, + slots: { + ConfirmDeleteBanner: (ctx) => { + const banner = document.createElement('div'); + banner.innerHTML = ` +

Remove "${ctx.item.name}" from your cart?

+ + + `; + banner.querySelector('#confirm').addEventListener('click', ctx.onConfirm); + banner.querySelector('#cancel').addEventListener('click', ctx.onCancel); + ctx.appendChild(banner); + } + } +})(block); +``` + ### ItemTitle slot The `ItemTitle` slot allows you to customize the item title section of the `MiniCart` container. From b3ce7730bb92763bfd15b4be9e800c500f41360a Mon Sep 17 00:00:00 2001 From: "Carlos A. Cabrera" Date: Mon, 18 May 2026 16:18:28 -0500 Subject: [PATCH 2/4] refine confirmation banner descriptions in CartSummaryList and MiniCart documentation --- .../cart/containers/cart-summary-list.mdx | 69 +------------------ .../dropins/cart/containers/mini-cart.mdx | 2 +- 2 files changed, 2 insertions(+), 69 deletions(-) diff --git a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx index 8ea7014e5..724b6013c 100644 --- a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx +++ b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx @@ -51,7 +51,7 @@ The `CartSummaryList` container provides the following configuration options: | `dropdownOptions` | `string[]` | No | An array of items to display in a dropdown menu. | | `undo` | `boolean` | No | Enables the undo banner to restore recently removed items to the cart. | | `includeOutOfStockItems` | `boolean` | No | Display out-of-stock and insufficient-quantity items in the main cart item list alongside in-stock items. Default: `false`. | -| `confirmBeforeDelete` | `boolean` | No | When `true`, reducing an item's quantity to 0 or clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. Confirming triggers the delete; cancelling restores the original quantity. Defaults to `false`. | +| `confirmBeforeDelete` | `boolean` | No | Enables the confirmation banner when an item is removed from the cart. When set to true, clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. | @@ -79,70 +79,3 @@ The `CartSummaryList` container supports the following slots: * ItemSku * ItemRemoveAction -## QuantityIncrementer - -`CartSummaryList` uses `QuantityIncrementer` as its built-in quantity stepper. It wraps the SDK `Incrementer` component and adds an empty-input error state: when a shopper clears the quantity field to blank, the `+` and `−` buttons are disabled and an error style is applied so no cart update is sent until a valid number is entered. - -The component is also available as a named export for use in custom `ItemQuantity` slots: - -```js -import { QuantityIncrementer } from '@dropins/storefront-cart/components/QuantityIncrementer.js'; -``` - - - -| Prop | Type | Required | Description | -|------|------|----------|-------------| -| `item` | `CartModel['items'][0]` | Yes | The cart item whose `quantity` seeds the stepper. | -| `disabled` | `boolean` | Yes | Disables the entire stepper (passed through to `Incrementer`). | -| `ariaLabel` | `string` | Yes | Accessible label for the stepper input. | -| `onValue` | `(value: number) => void` | Yes | Called with the new quantity after the user commits a valid value. | - - - -## Example configuration - -The following example demonstrates how to render the `CartSummaryList` container with the `routeProduct` and `routeEmptyCartCTA` callbacks: - -```js -provider.render(CartSummaryList, { - enableRemoveItem: true, - enableUpdateItemQuantity: true, - showDiscount: true, - // confirmBeforeDelete: true, - // accordion: true, - // includeOutOfStockItems: true, - // showMaxItems: false, - // maxItems: 6, - // routeCart: () => '#cart', - // showSavings: true, - // quantityType: 'dropdown', - // dropdownOptions: [ - // { value: '1', text: '1' }, - // { value: '2', text: '2' }, - // { value: '3', text: '3' }, - // ], - routeProduct: (item) => { - return `${item.url.categories.join('/')}/${item.url.urlKey}`; - }, - routeEmptyCartCTA: () => '#empty-cart', - slots: { - Footer: (ctx) => { - // Runs on mount - const wrapper = document.createElement('div'); - ctx.appendChild(wrapper); - - // Append Product Promotions on every update - ctx.onChange((next) => { - wrapper.innerHTML = ''; - - next.item?.discount?.label?.forEach((label) => { - const discount = document.createElement('div'); - discount.style.color = '#3d3d3d'; - discount.innerText = label; - wrapper.appendChild(discount); - }); - }); - }, - }, -})($cartSummaryList); diff --git a/src/content/docs/dropins/cart/containers/mini-cart.mdx b/src/content/docs/dropins/cart/containers/mini-cart.mdx index 047a5a619..bb289465c 100644 --- a/src/content/docs/dropins/cart/containers/mini-cart.mdx +++ b/src/content/docs/dropins/cart/containers/mini-cart.mdx @@ -40,7 +40,7 @@ The `MiniCart` container provides the following configuration options: | `enableQuantityUpdate` | `boolean` | No | Flag to enable updating item quantities in the mini cart. When set to true, users can adjust product quantities directly in the mini cart interface. | | `hideHeading` | `boolean` | No | Flag to hide the heading in the mini cart. When set to true, the mini cart header will not be displayed. | | `undo` | `boolean` | No | Enables the undo banner to restore recently removed items to the cart. | -| `confirmBeforeDelete` | `boolean` | No | When `true`, clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. Forwarded to the internal `CartSummaryList`. Defaults to `false`. | +| `confirmBeforeDelete` | `boolean` | No | Enables the confirmation banner when an item is removed from the cart. When set to true, clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. | From 638d960400886dcb02eb13e9917180ccae460e39 Mon Sep 17 00:00:00 2001 From: "Carlos A. Cabrera" Date: Mon, 18 May 2026 16:19:44 -0500 Subject: [PATCH 3/4] Add example configuration for CartSummaryList container in documentation --- .../cart/containers/cart-summary-list.mdx | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx index 724b6013c..de10ae5df 100644 --- a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx +++ b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx @@ -79,3 +79,49 @@ The `CartSummaryList` container supports the following slots: * ItemSku * ItemRemoveAction +## Example configuration + +The following example demonstrates how to render the `CartSummaryList` container with the `routeProduct` and `routeEmptyCartCTA` callbacks: + +```js +provider.render(CartSummaryList, { + enableRemoveItem: true, + enableUpdateItemQuantity: true, + showDiscount: true, + // confirmBeforeDelete: true, + // accordion: true, + // includeOutOfStockItems: true, + // showMaxItems: false, + // maxItems: 6, + // routeCart: () => '#cart', + // showSavings: true, + // quantityType: 'dropdown', + // dropdownOptions: [ + // { value: '1', text: '1' }, + // { value: '2', text: '2' }, + // { value: '3', text: '3' }, + // ], + routeProduct: (item) => { + return `${item.url.categories.join('/')}/${item.url.urlKey}`; + }, + routeEmptyCartCTA: () => '#empty-cart', + slots: { + Footer: (ctx) => { + // Runs on mount + const wrapper = document.createElement('div'); + ctx.appendChild(wrapper); + + // Append Product Promotions on every update + ctx.onChange((next) => { + wrapper.innerHTML = ''; + + next.item?.discount?.label?.forEach((label) => { + const discount = document.createElement('div'); + discount.style.color = '#3d3d3d'; + discount.innerText = label; + wrapper.appendChild(discount); + }); + }); + }, + }, +})($cartSummaryList); From 8a72e31da4f4528c97821d16eff5d0a5020dfef6 Mon Sep 17 00:00:00 2001 From: "Carlos A. Cabrera" Date: Thu, 21 May 2026 10:36:34 -0500 Subject: [PATCH 4/4] Update CartSummaryList documentation to clarify enableUpdateItemQuantity option, including details on removeOnZero behavior. --- src/content/docs/dropins/cart/containers/cart-summary-list.mdx | 2 +- src/content/docs/dropins/cart/containers/mini-cart.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx index de10ae5df..f415a69b0 100644 --- a/src/content/docs/dropins/cart/containers/cart-summary-list.mdx +++ b/src/content/docs/dropins/cart/containers/cart-summary-list.mdx @@ -39,7 +39,7 @@ The `CartSummaryList` container provides the following configuration options: | `slots` | `function` | No | Allows passing a container or custom component. | | `attributesToHide` | `string[]` | No | Attributes to hide. | | `enableRemoveItem` | `boolean` | No | Enable remove item. | -| `enableUpdateItemQuantity` | `boolean` | No | Enable update item quantity. | +| `enableUpdateItemQuantity` | `boolean \| { removeOnZero?: boolean }` | No | Enables the quantity stepper. Pass `{ removeOnZero: true }` to also remove the item when the quantity reaches `0`; defaults to `false`. | | `onItemsErrorsChange` | `function` | No | Callback function that changes the items errors. | | `accordion` | `boolean` | No | Toggle accordion view. | | `variant` | `primary \| secondary` | No | Cart variant. | diff --git a/src/content/docs/dropins/cart/containers/mini-cart.mdx b/src/content/docs/dropins/cart/containers/mini-cart.mdx index bb289465c..148022a59 100644 --- a/src/content/docs/dropins/cart/containers/mini-cart.mdx +++ b/src/content/docs/dropins/cart/containers/mini-cart.mdx @@ -37,7 +37,7 @@ The `MiniCart` container provides the following configuration options: | `showDiscount` | `boolean` | No | Flag to show discounts in the mini cart. | | `showSavings` | `boolean` | No | Flag to show savings in the mini cart. | | `enableItemRemoval` | `boolean` | Yes | Flag to enable removing items from the mini cart. When set to true, users can remove products from the cart directly in the mini cart interface. | -| `enableQuantityUpdate` | `boolean` | No | Flag to enable updating item quantities in the mini cart. When set to true, users can adjust product quantities directly in the mini cart interface. | +| `enableQuantityUpdate` | `boolean \| { removeOnZero?: boolean }` | No | Enables quantity updates in the mini cart. Pass `{ removeOnZero: true }` to also remove the item when the quantity reaches `0`; defaults to `false`. | | `hideHeading` | `boolean` | No | Flag to hide the heading in the mini cart. When set to true, the mini cart header will not be displayed. | | `undo` | `boolean` | No | Enables the undo banner to restore recently removed items to the cart. | | `confirmBeforeDelete` | `boolean` | No | Enables the confirmation banner when an item is removed from the cart. When set to true, clicking the remove button shows an inline confirmation banner instead of immediately deleting the item. |