# Cart Page Flow

> How the cart demo page combines cart items, item atoms, coupons, shipping methods, totals, notices, and empty-state rendering.

<!-- Sources: src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Testing/E2E/Woo/WooScenarioProvider.php; src/Patterns/Testing/TestCartDemo/TestCartDemo.php; src/Patterns/Testing/TestCartDemo/TestCartDemo.css; src/Woo/CartViewModel.php; src/Woo/CartItemsDynamicSource.php; src/Woo/CartItemAtomHydrator.php; src/Woo/WooSelectorDynamicSource.php; src/Components/Woo/CartItems/CartItems.php; src/Components/Woo/CartItemQuantity/CartItemQuantity.php; src/Components/Woo/CartItemRemove/CartItemRemove.php; src/Components/Woo/CartTotals/CartTotalsList.php; src/Components/Woo/CouponForm/CouponForm.php; src/Components/Woo/CouponAppliedList/CouponAppliedList.php; src/Components/Woo/CouponRemoveButton/CouponRemoveButton.php; src/Components/Woo/ShippingMethodSelector/ShippingMethodSelector.php; client/src/domains/woo/cart-store.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Cart Page Flow

The cart page flow is built from `TestCartDemo`. It is a two-column cart layout: item rows on the left and coupon, shipping, totals, and checkout action on the right.

## Flow Structure

```text
Cart page
  CartNotices
  CartItems
    CartItemImage
    CartItemTitle
    CartAttributeList
      CartAttributeName
      CartAttributeValue
    CartItemPrice
    CartItemQuantity
    CartItemSubtotal
    CartItemRemove
    Empty slot
  CouponForm
  CouponAppliedList
    CouponRemoveButton
  ShippingMethodSelector
  CartTotalsList
    TotalsSubtotal
    TotalsShipping
    TotalsTax
    TotalsDiscount
    TotalsTotal
```

## CartItems Owns The Repeated Row

`CartItems` renders the current Store API cart items into the default slot. Cart item atom components do not query global cart state by themselves; they read the row context that `CartItems` hydrates.

This is why item atoms should be authored inside the `CartItems` default slot:

| Atom | Row value |
| --- | --- |
| `CartItemImage` | Current item image and alt fallback. |
| `CartItemTitle` | Current item title, optionally with attributes. |
| `CartAttributeList` | Current item variation/attribute list. |
| `CartItemPrice` | Current item unit price text. |
| `CartItemQuantity` | Current item quantity input and update action. |
| `CartItemSubtotal` | Current item subtotal text. |
| `CartItemRemove` | Current item remove action. |

If the cart becomes empty, `CartItems` swaps to the `empty` slot.

## Quantity, Remove, And Totals Refresh

`CartItemQuantity` and `CartItemRemove` both send Store API cart mutation requests through the cart store. After a successful mutation, the normalized cart response updates:

- cart item rows,
- `CartCount`,
- coupon list,
- shipping rates,
- cart total atoms,
- notices.

E2E verifies row count, quantity updates, subtotal text, remove behavior, and final empty-state rendering.

## Coupons

`CouponForm` applies a coupon code. `CouponAppliedList` renders the current applied coupons, and `CouponRemoveButton` belongs inside each coupon row. The cart demo keeps `CartNotices` near the top of the page so coupon errors and success messages share one cart-level live region.

The `cart_coupons` scenario applies `SAVE10`, checks the discount and total values, verifies duplicate coupon errors, removes the coupon, and checks the totals again.

## Shipping And Totals

`ShippingMethodSelector` uses the same UIChoice-backed modes as checkout selectors. The cart demo uses button-radio mode and shows the shipping price next to each rate. The selected Store API shipping rate refreshes total values.

`CartTotalsList` renders authored total rows with total atoms. Each atom reads one normalized total field, so authors can reorder or wrap rows without changing the cart calculation path.

## E2E Coverage

| Scenario | Verified behavior |
| --- | --- |
| `cart_items_dynamic_source` | Dynamic cart item loop values render from seeded cart data. |
| `cart_items_component_preview_contract` | `CartItems` hydrates item atoms and image fallback attributes. |
| `cart_page_update_and_remove` | Quantity updates, remove actions, cart count, and empty state refresh. |
| `cart_totals_and_empty_slot` | Totals and empty slot respond to cart state. |
| `cart_totals_taxed_cart` | Taxed cart totals render expected total fields. |
| `cart_coupons` | Coupon apply/remove updates notices and totals. |
| `shipping_selector` | Shipping method selection changes totals and order summary totals. |