# OhMyEtch Woo Components

> Complete reference for WooCommerce components.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Checkout Fields and Validation

<!-- Sources: src/Woo/CheckoutFieldSchema.php; src/Components/Woo/Shared/AddressFormProperties.php; src/Components/Woo/Shared/AddressFormMarkup.php; src/Components/Woo/BillingAddressForm/BillingAddressForm.php; src/Components/Woo/ShippingAddressForm/ShippingAddressForm.php; client/src/domains/woo/checkout-field-schema.ts; client/src/domains/woo/checkout-validation.ts; client/src/domains/woo/components/address-fields.ts; client/src/domains/woo/components/checkout-form.ts; client/src/domains/woo/store-api-client.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Checkout Fields and Validation

Billing and shipping address forms are authored components, but their field rules come from WooCommerce.

## Field Schema

`CheckoutFieldSchema::build()` produces:

| Schema key | Meaning |
| --- | --- |
| `billing.countries` | Allowed billing countries. |
| `shipping.countries` | Allowed shipping countries. |
| `billing.fields` | Woo billing field rules normalized without the `billing_` prefix. |
| `shipping.fields` | Woo shipping field rules normalized without the `shipping_` prefix. |
| `locales` | Country-specific label, required, hidden, type, validation, priority, and autocomplete overrides. |
| `states` | State/province options by country. |
| `defaults` | Base billing country/state and shipping defaults. |

The runtime normalizes this schema before applying it, so missing or malformed schema data becomes empty field lists rather than runtime crashes.

## Address Form Props

Both address forms use the shared address property builder.

| Prop group | Meaning |
| --- | --- |
| `content.legend` and `content.show_legend` | Fieldset legend text and visibility. |
| Per-field `use_woo_defaults` | When true, Woo field copy and validation copy win. |
| Per-field custom copy | Label, field hint text, and local validation message used only when Woo defaults are disabled. |
| `accessibility.aria_label` | Accessible name for the fieldset. |
| `preview.state` | Builder preview state for fields. |

Billing fields include first name, last name, company, address lines, city, state, postcode, country, email, and phone. Shipping fields include the same address fields except email and phone.

## Country and State Controls

Country and state are UIChoice-backed controls with hidden transport inputs. Runtime behavior:

1. Render country options from the schema.
2. Select a default from the current value or Woo defaults.
3. Render state as a select when the selected country has predefined states.
4. Render state as a text input when the country requires free text.
5. Hide state when Woo marks it hidden.
6. Re-apply field labels, priorities, hidden flags, required flags, input types, and autocomplete tokens after country changes.

E2E covers changing billing country from `US` to `PL` and verifies that state switches from ready to hidden with an empty value.

## Different Shipping Address

`ShippingAddressForm` includes a different-shipping toggle. Runtime hides or shows the shipping fields based on that checkbox.

Checkout serialization follows the toggle:

| Toggle state | Payload behavior |
| --- | --- |
| Unchecked | Billing address is copied to shipping. |
| Checked | Rendered shipping fields are serialized separately. |

## Local Validation

`CheckoutForm` validates rendered fields before sending Store API requests.

| Validation | Behavior |
| --- | --- |
| Required fields | Checked on submit; required checks can be overridden by rendered `data-ome-required`. |
| Email | Billing email must match the local email pattern. |
| Country | Country value must exist in schema options. |
| State | State value must exist when the selected country has predefined states. |
| Hidden fields | Hidden Woo fields are not validated. |
| Rendered field scope | Only fields present in the authored checkout scope are validated. |

On local validation failure, no Store API checkout request is sent. E2E verifies invalid email blocks before `/wc/store/v1/checkout`.

## Store API Field Errors

If Woo returns checkout errors, the runtime maps them to fields when possible:

- It reads `data.params` field keys from Store API errors.
- It falls back to known Woo error codes such as missing email, first name, last name, address, country, postcode, phone, city, and state.
- It marks matching inputs with `aria-invalid`, updates field error text, and links fields to error messages with `aria-describedby`.

## Terms and Notices

`TermsCheckbox` tells the checkout store whether terms are required and accepted. If required terms are unchecked, the checkout store emits a local `terms_required` error and `CheckoutNotices` renders the message.

`CheckoutNotices` renders text-only checkout notices from local validation and Store API errors. E2E verifies the terms-blocked flow and that notice contents are safe text.

---

## Cart Items

<!-- Sources: src/Components/Woo/CartItems/CartItems.php; src/Components/Woo/CartItemImage/CartItemImage.php; src/Components/Woo/CartItemTitle/CartItemTitle.php; src/Components/Woo/CartItemPrice/CartItemPrice.php; src/Components/Woo/CartItemSubtotal/CartItemSubtotal.php; src/Components/Woo/CartItemQuantity/CartItemQuantity.php; src/Components/Woo/CartItemRemove/CartItemRemove.php; src/Components/Woo/CartAttributeList/CartAttributeList.php; src/Components/Woo/CartAttributeName/CartAttributeName.php; src/Components/Woo/CartAttributeValue/CartAttributeValue.php; src/Woo/CartItemsDynamicSource.php; src/Woo/CartItemAtomHydrator.php; client/src/domains/woo/components/cart-items.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts -->

# Cart Items

This family renders the editable cart line-item list. `CartItems` owns the row loop. The atoms inside the default slot read the current row.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooCartItems` | Renders cart rows and an authored empty slot. |
| `OmeWooCartItemImage` | Displays line product image. |
| `OmeWooCartItemTitle` | Displays product title or composed variant title. |
| `OmeWooCartItemPrice` | Displays unit price. |
| `OmeWooCartItemSubtotal` | Displays line subtotal. |
| `OmeWooCartItemQuantity` | Interactive quantity input or display quantity. |
| `OmeWooCartItemRemove` | Removes the current cart item. |
| `OmeWooCartAttributeList` | Loops the selected variation attributes for the current line. |
| `OmeWooCartAttributeName` | Displays attribute name inside `CartAttributeList`. |
| `OmeWooCartAttributeValue` | Displays attribute value inside `CartAttributeList`. |

## Authoring Structure

```text
CartItems
  default slot
    CartItemImage
    CartItemTitle
    CartAttributeList
      CartAttributeName
      CartAttributeValue
    CartItemPrice
    CartItemQuantity
    CartItemSubtotal
    CartItemRemove
  empty slot
    authored empty-cart content
```

## CartItems Props

| Prop | Meaning |
| --- | --- |
| `structure.root_tag` | Root wrapper tag. |
| `structure.item_tag` | Row tag. |
| `structure.empty_tag` | Empty state wrapper tag. |
| `preview.rows` | Number of builder preview rows. |
| `preview.empty_state` | Shows the empty slot in builder preview. |

The runtime sets `data-ome-state` to `has-items` or `empty`.

## Cart Item Atom Props

| Component | Important props |
| --- | --- |
| `CartItemImage` | `content.alt_fallback` is used when Woo image alt text is empty. |
| `CartItemTitle` | `content.include_attributes` and `content.variant_separator` control composed variant title text. |
| `CartItemQuantity` | `configuration.mode` is `interactive` or `preview`; content and accessibility props control label text. |
| `CartItemRemove` | `content.label` and `accessibility.aria_label` control button text and accessible name. |

`CartItemPrice` and `CartItemSubtotal` display Store API formatted price text from the current row.

## Attribute Props

`CartAttributeList` exposes:

| Prop | Meaning |
| --- | --- |
| `structure.root_tag` | Attribute list wrapper tag. |
| `structure.item_tag` | Attribute row tag. |
| `preview.rows` | Number of builder preview attributes. |

`CartAttributeName` and `CartAttributeValue` are row atoms; they need the current attribute row from `CartAttributeList`.

## Hydration Rules

Server render uses `CartItemAtomHydrator` when current cart data exists. Runtime uses `cart-items.ts` after Store API responses. Both update:

- Row keys and indexes.
- Text fields.
- Image attributes.
- Quantity input values and cart item keys.
- Remove button cart item keys.
- Attribute rows cloned from the attribute row template.

Rows inside `<template>` elements are ignored until cloned.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `cart_items_dynamic_source` | Etch loop can render `cartItems` source directly. |
| `cart_items_component_preview_contract` | `CartItems` renders seeded cart rows through cart item atoms. |
| `cart_totals_taxed_cart` | Quantity updates and item removal refresh rows and totals. |
| `cart_page_update_and_remove` | Cart page row actions update state and empty slot. |

---

## Cart State and Notices

<!-- Sources: src/Components/Woo/CartCount/CartCount.php; src/Components/Woo/CartNotices/CartNotices.php; client/src/domains/woo/components/cart-count.ts; client/src/domains/woo/components/cart-notices.ts; client/src/domains/woo/cart-store.ts; client/src/domains/woo/helpers/normalize-woo-notice-message.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Cart State and Notices

This family renders global cart feedback: item count and cart notices. Both can be used outside a cart page.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooCartCount` | Displays the current cart item quantity and state. |
| `OmeWooCartNotices` | Renders Store API and Woo cart notices as safe text. |

## CartCount

`CartCount` subscribes to `WooCartStore` and displays `cartSummary.item_count`. It sets:

| State | Meaning |
| --- | --- |
| `empty` | Cart has no lines. |
| `has-items` | Cart has one or more lines. |

It is useful in product archive headers, single product templates, mini-cart indicators, and cart pages.

## CartNotices

`CartNotices` is a runtime notice region. It renders notices from cart actions:

| Source | Typical action |
| --- | --- |
| `add-to-cart` | Product add failed. |
| `quantity` | Quantity update failed. |
| `remove` | Remove item failed. |
| `coupon` | Apply or remove coupon failed. |
| `shipping` | Shipping rate selection failed. |
| `stock` or `variation` | Woo Store API product constraints. |

Messages are normalized and rendered as text, so Woo error content is not injected as HTML.

## Props

| Component | Prop | Meaning |
| --- | --- | --- |
| Cart notices | `preview.show_in_builder` | Shows a sample notice in Etch builder preview. |
| Cart notices | `preview.notice_type` | Preview notice type: `error`, `success`, `info`, or `warning`. |
| Cart notices | `accessibility.aria_label` | Accessible label for the notice region. |
| Cart notices | `accessibility.live_region` | Live region politeness, defaulting to `polite`. |

`CartCount` is mostly display and styling; its runtime content comes from the cart store.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `cart_count_add_to_cart` | Count changes from `0` to `1` after add. |
| `out_of_stock_cart_notice` | Out-of-stock add renders cart notice as text with error type and code. |
| `lifecycle_add_to_cart` | Native add-to-cart validation can block mutation and render a Woo notice. |
| `cart_coupons` | Invalid coupon renders cart notice without encoded text leaking into display. |

---

## Cart Totals

<!-- Sources: src/Components/Woo/CartTotals/CartTotalsList.php; src/Components/Woo/CartTotals/TotalsSubtotal.php; src/Components/Woo/CartTotals/TotalsDiscount.php; src/Components/Woo/CartTotals/TotalsShipping.php; src/Components/Woo/CartTotals/TotalsTax.php; src/Components/Woo/CartTotals/TotalsTotal.php; src/Components/Woo/Shared/CartTotalProperties.php; src/Components/Woo/Shared/TotalsListProperties.php; client/src/domains/woo/components/cart-totals.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Cart Totals

This family renders cart total fields from `cartTotals` and live Store API cart totals.

## Components

| Component key | Field |
| --- | --- |
| `OmeWooCartTotalsList` | Container for total atoms on cart pages. |
| `OmeWooTotalsSubtotal` | `total_items` |
| `OmeWooTotalsDiscount` | `total_discount` |
| `OmeWooTotalsShipping` | `total_shipping` |
| `OmeWooTotalsTax` | `total_tax` |
| `OmeWooTotalsTotal` | `total_price` |

The same total atoms are also used in `OrderSummaryTotalsList` on checkout pages.

## Authoring Structure

```text
CartTotalsList
  TotalsSubtotal
  TotalsDiscount
  TotalsShipping
  TotalsTax
  TotalsTotal
```

## List Props

| Prop | Meaning |
| --- | --- |
| `structure.root_tag` | Wrapper element for the list. |
| `styling.list_class` | Class prop for the list wrapper. |

## Atom Props

All total atoms share props from `CartTotalProperties`.

| Prop | Meaning |
| --- | --- |
| `content.show_label` | Renders label and value in a wrapper when true. |
| `content.label` | Label text when labels are enabled. |
| `content.label_position` | `prefix` or `suffix`. |
| `structure.html_tag` | Wrapper tag when label is enabled. |
| `styling.value_class` | Class prop for the value span. |
| `styling.class` | Wrapper class when label is enabled. |
| `styling.label_class` | Label class when label is enabled. |

## Runtime Behavior

`cart-totals.ts` formats minor-unit Store API totals using currency metadata from the response. It updates every matching `data-ome-woo-cart-total-field`, except fields inside an order summary when the cart page binding is running. `OrderSummary` owns its own summary total rendering.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `cart_totals_taxed_cart` | Tax, subtotal, and final total render for a seeded taxable cart. |
| `cart_totals_and_empty_slot` | Empty cart keeps totals at zero. |
| `cart_page_update_and_remove` | Quantity and removal refresh totals. |
| `shipping_selector` | Shipping rate selection updates shipping and total. |
| `lifecycle pricing` | Native Woo pricing hooks change rendered totals. |

---

## Checkout Address Forms

<!-- Sources: src/Components/Woo/BillingAddressForm/BillingAddressForm.php; src/Components/Woo/ShippingAddressForm/ShippingAddressForm.php; src/Components/Woo/Shared/AddressFormProperties.php; src/Components/Woo/Shared/AddressFormMarkup.php; src/Woo/CheckoutFieldSchema.php; client/src/domains/woo/components/address-fields.ts; client/src/domains/woo/components/shipping-address-form.ts; client/src/domains/woo/checkout-field-schema.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Checkout Address Forms

This family renders Woo billing and shipping fields. Field definitions are authored in components, but runtime field rules come from Woo's checkout schema.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooBillingAddressForm` | Renders billing address fields. |
| `OmeWooShippingAddressForm` | Renders shipping address fields plus the different-shipping toggle. |

## Shared Field Props

Both address forms expose the same field-copy pattern:

| Prop | Meaning |
| --- | --- |
| `content.legend` | Fieldset legend text. |
| `content.show_legend` | Renders or hides the legend. |
| `{field}.use_woo_defaults` | Uses Woo label, hint text, and validation copy. |
| `{field}.label` | Custom label when Woo defaults are disabled. |
| Field hint copy | Custom input hint copy when Woo defaults are disabled. |
| `{field}.error_message` | Custom local validation copy when Woo defaults are disabled. |
| `accessibility.aria_label` | Fieldset accessible label. |
| `preview.state` | Builder preview state. |

Billing includes email and phone. Shipping does not.

## Shipping Toggle Props

`ShippingAddressForm` adds:

| Prop | Meaning |
| --- | --- |
| `shipping_toggle.label` | Visible toggle label. |
| `shipping_toggle.use_aria_label` | Uses a separate ARIA label when true. |
| `shipping_toggle.aria_label` | Accessible toggle label when enabled. |
| `shipping_toggle.preview_checked` | Builder preview checked state. |

Runtime hides shipping fields until the toggle is checked.

## Runtime Field Rules

Runtime applies the Woo schema:

| Rule | Runtime result |
| --- | --- |
| `hidden` | Field root becomes hidden and controls are disabled. |
| `required` | Field gets `data-ome-required`, and checkout validation uses it. |
| `label` | Label text is updated unless custom copy is enabled. |
| Field hint copy | Input hint copy is updated unless custom copy is enabled. |
| `type` | Native input type is updated. |
| `priority` | Field roots are sorted by Woo priority. |
| `autocomplete` | Autocomplete token is applied. |

Country and state controls are UIChoice-backed. State can become select, text, or hidden depending on the selected country.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `checkout_success` | Billing fields, country/state choices, and payment data produce a real order. |
| `checkout_validation_error` | Required and invalid billing fields are marked locally. |
| `checkout_terms_blocked` | Checkout notices mark error state without unsafe HTML. |
| `checkout country changes refresh state control` | State changes from ready to hidden after country change. |
| `checkout shipping address fields follow toggle` | Shipping fields show and hide with the embedded toggle. |

---

## Checkout Shell

<!-- Sources: src/Components/Woo/CheckoutProvider/CheckoutProvider.php; src/Components/Woo/CheckoutForm/CheckoutForm.php; src/Components/Woo/CheckoutNotices/CheckoutNotices.php; src/Components/Woo/PlaceOrderButton/PlaceOrderButton.php; client/src/domains/woo/components/checkout-form.ts; client/src/domains/woo/components/checkout-notices.ts; client/src/domains/woo/components/place-order-button.ts; client/src/domains/woo/checkout-store.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Checkout Shell

The checkout shell owns checkout scope, form serialization, notices, and order submission.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooCheckoutProvider` | Layout and state scope for checkout components. It does not submit data. |
| `OmeWooCheckoutForm` | Real checkout form shell. Serializes authored checkout fields and submits Store API checkout. |
| `OmeWooCheckoutNotices` | Checkout notice region. |
| `OmeWooPlaceOrderButton` | Submit button for the checkout form. |

## Authoring Structure

```text
CheckoutProvider
  CheckoutForm
    BillingAddressForm
    ShippingAddressForm
    ShippingMethodSelector
    PaymentMethodSelector
    TermsCheckbox
    CheckoutNotices
    PlaceOrderButton
  OrderSummary
```

`OrderSummary` can sit inside the provider but does not have to be inside the `<form>`.

## CheckoutProvider

`CheckoutProvider` provides a stable checkout root and state scope. It is the preferred wrapper for full checkout layouts because `CheckoutForm` uses the closest provider as its serialization scope.

## CheckoutForm

`CheckoutForm`:

- Serializes all `[data-ome-woo-checkout-field]` controls inside the provider or form scope.
- Copies billing to shipping when the different-shipping toggle is unchecked.
- Runs local validation before submit.
- Persists field changes with Store API update requests.
- Submits checkout through Store API.
- Dispatches checkout lifecycle events.
- Redirects when the Store API payment result returns a redirect URL.

Form state is mirrored as `data-ome-state`: `idle`, `loading`, `updating`, `processing`, `success`, or `error`.

## CheckoutNotices Props

| Prop | Meaning |
| --- | --- |
| `preview.show_in_builder` | Shows a sample notice in Etch builder preview. |
| `preview.notice_type` | Preview notice type. |
| `accessibility.aria_label` | Notice region accessible label. |
| `accessibility.live_region` | Live region politeness. |

## PlaceOrderButton Props

| Prop | Meaning |
| --- | --- |
| `content.label` | Button text. |
| `accessibility.aria_label` | Accessible label. |

`PlaceOrderButton` subscribes to checkout store state and disables itself while checkout is busy.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `checkout_success` | Required fields and payment method can submit a real Store API order. |
| `checkout_validation_error` | Known invalid fields are marked locally and Store API submit is blocked. |
| `checkout_terms_blocked` | Unchecked terms creates checkout notice and error state. |
| `checkout_terms_success` | Checked terms allows the success flow. |
| `lifecycle_checkout` | Checkout creates an order through native Store API checkout hooks. |

---

## Coupons

<!-- Sources: src/Components/Woo/CouponForm/CouponForm.php; src/Components/Woo/CouponAppliedList/CouponAppliedList.php; src/Components/Woo/CouponRemoveButton/CouponRemoveButton.php; client/src/domains/woo/components/coupon-form.ts; client/src/domains/woo/cart-store.ts; src/Woo/CartItemsDynamicSource.php; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts -->

# Coupons

This family applies, lists, and removes Woo cart coupons.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooCouponForm` | Applies a coupon code through Store API. |
| `OmeWooCouponAppliedList` | Renders active cart coupons. |
| `OmeWooCouponRemoveButton` | Removes the current coupon row. |

## Authoring Structure

```text
CouponForm
CouponAppliedList
  CouponRemoveButton
```

`CouponRemoveButton` belongs inside `CouponAppliedList` because the runtime injects the coupon code into each row and button.

## CouponForm Props

| Prop | Meaning |
| --- | --- |
| Input hint copy | Text shown inside the coupon code field before entry. |
| `content.button_label` | Submit button text. |
| `accessibility.input_aria_label` | Input accessible label. |
| `accessibility.button_aria_label` | Button accessible label. |

If the submitted code is empty, the form moves to `error` without calling Store API.

## CouponAppliedList Props

| Prop | Meaning |
| --- | --- |
| `content.show_empty_message` | Shows an empty message when no coupons are applied. |
| `content.empty_message` | Empty message text. |
| `preview.rows` | Number of coupon rows in builder preview. |
| `preview.empty_state` | Shows empty state in builder preview. |

Runtime state is `has-coupons` or `empty`.

## CouponRemoveButton Props

| Prop | Meaning |
| --- | --- |
| `content.label` | Button text. |
| `accessibility.aria_label` | Button accessible label. |

The runtime reads `data-ome-woo-coupon-remove-code` or `data-ome-woo-coupon-code` from the hydrated row.

## Runtime Behavior

Applying or removing a coupon calls Store API and refreshes the cart store. Woo Store API coupon mutations can omit totals, so `WooCartStore` refreshes the cart after coupon responses when totals are missing.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `cart_coupons` | Valid coupon creates a row, changes discount totals, invalid coupon renders notice text, and remove returns totals. |

---

## Order Summary

<!-- Sources: src/Components/Woo/OrderSummary/OrderSummary.php; src/Components/Woo/OrderSummary/OrderSummaryTotalsList.php; src/Components/Woo/CartItemTitle/CartItemTitle.php; src/Components/Woo/CartItemSubtotal/CartItemSubtotal.php; src/Components/Woo/CartAttributeList/CartAttributeList.php; src/Components/Woo/Shared/CartTotalProperties.php; client/src/domains/woo/components/order-summary.ts; client/src/domains/woo/components/cart-items.ts; src/Patterns/Testing/TestCheckoutDemo/TestCheckoutDemo.php; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Order Summary

`OrderSummary` renders checkout cart contents and totals. It is read-only by default and intentionally reuses cart item and total atoms.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooOrderSummary` | Summary shell backed by cart store. |
| `OmeWooOrderSummaryTotalsList` | Totals list container for checkout summary totals. |
| Cart item atoms | Optional product row atoms in `product_atoms` or `full_atoms` modes. |
| Total atoms | Optional totals row atoms in `full_atoms` mode. |

## Content Modes

| Mode | Meaning |
| --- | --- |
| `propped` | The component renders product rows and totals from its own props and internal structure. |
| `product_atoms` | Authors provide the products slot with cart item atoms; totals stay component-managed. |
| `full_atoms` | Authors provide both products and totals slots. |

`TestCheckoutDemo` uses `full_atoms` so the checkout summary can style product rows and total rows with the same atom components used elsewhere.

## Props

| Prop | Meaning |
| --- | --- |
| `content.mode` | Summary rendering mode. |
| `content.include_attributes` | Whether product titles include attributes in propped mode. |
| `content.variant_separator` | Separator for composed variant titles. |
| `accessibility.aria_label` | Summary region label. |

The totals list uses the same `structure.root_tag` and list class pattern as `CartTotalsList`.

## Runtime Behavior

`order-summary.ts` subscribes to the cart store and renders summary rows from current cart data. The main Woo runtime excludes order-summary total fields from the cart-page totals binder so the summary binding owns its own subtree.

When authors use atom modes, cart item atoms and totals atoms still read the summary cart data. The order summary is read-only unless authors deliberately place interactive atoms inside it.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `shipping_selector` | Order summary total changes after shipping selection. |
| `checkout_success` | Checkout can render order summary beside a real checkout form. |
| Lifecycle pricing test | Native Woo pricing hooks change totals rendered in cart and order summary. |
| `TestCheckoutDemo` | Full-atoms mode composes cart item title, attributes, subtotal, and all total atoms. |

---

## Payment Selector

<!-- Sources: src/Components/Woo/PaymentMethodSelector/PaymentMethodSelector.php; src/Woo/WooSelectorDynamicSource.php; client/src/domains/woo/components/payment-method-selector.ts; client/src/domains/woo/components/ui-choice-mode.ts; src/Woo/Woo.php; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Payment Selector

`PaymentMethodSelector` renders simple enabled Woo payment gateways and syncs the selected method into checkout form submission.

## Component

| Component key | Role |
| --- | --- |
| `OmeWooPaymentMethodSelector` | Renders payment method choices with UIChoice and checkout form radio inputs. |

## Props

| Prop | Meaning |
| --- | --- |
| `ui.mode` | `radio`, `button-radio`, or `select`. |
| `ui.aria_label` | Accessible selector label. |
| `ui.default_label` | Select trigger text before selection. |
| `content.show_description` | Shows or removes payment method descriptions. |

## Payment Method Source

Payment methods come from `WooSelectorDynamicSource::get_simple_payment_methods()` and are also localized in `OME_WOO.paymentMethods`.

The source includes only enabled gateways with no custom fields. Each row has:

| Field | Meaning |
| --- | --- |
| `id` | Woo payment gateway ID. |
| `label` | Cleaned gateway title. |
| `description` | Cleaned gateway description. |
| `selected` | Whether Woo reports it as the current chosen method. |

## Checkout Form Integration

Runtime ensures the radio group belongs to the nearest checkout form. If the form has no ID, the runtime assigns one and uses form-scoped radio names.

Select mode still uses hidden radio inputs. The visible trigger/listbox is UIChoice; the submitted checkout payload reads the transport input.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `payment_selector_button_radio` | Button-radio mode has radiogroup semantics and radio items. |
| `payment_selector_select` | Select mode uses trigger/listbox structure and updates selected label. |
| `checkout_success` | Selected `bacs` payment method is submitted in checkout. |
| `lifecycle_checkout` | Store API order summary confirms payment method `bacs`. |

---

## Product Purchase

<!-- Sources: src/Components/Woo/AddToCartForm/AddToCartForm.php; src/Components/Woo/AddToCartButton/AddToCartButton.php; src/Components/Woo/AttributeSelector/AttributeSelector.php; src/Components/Woo/BuyNowButton/BuyNowButton.php; client/src/domains/woo/components/add-to-cart-form.ts; client/src/domains/woo/components/add-to-cart-button.ts; client/src/domains/woo/components/attribute-selector.ts; client/src/domains/woo/components/buy-now-button.ts; client/src/domains/woo/helpers/variation-sync.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts -->

# Product Purchase

This family builds product add-to-cart UI. The parent is `AddToCartForm`; the usual children are `AttributeSelector`, `AddToCartButton`, and `BuyNowButton`.

## Components

| Component key | Role |
| --- | --- |
| `OmeWooAddToCartForm` | Owns the product ID, product type, variation ID, stock/availability flags, and submitted form state. |
| `OmeWooAttributeSelector` | Selects one variation attribute object from `omewoo.attributes`. |
| `OmeWooAddToCartButton` | Adds a product by itself in standalone mode, or submits the parent form in form-submit mode. |
| `OmeWooBuyNowButton` | Uses the parent form payload, adds the item, then redirects to checkout. |

## Authoring Structure

```text
AddToCartForm
  AttributeSelector loop over product attributes
  AddToCartButton with trigger=form_submit
  BuyNowButton
```

Use `AddToCartButton` as a standalone button only when it is outside an `AddToCartForm`.

## Quick Start

<CodeExample title="Variable product purchase form" language="jsx">
{`<OmeWooAddToCartForm product='{{"product_id":"{this.id}","product_type":"{this.omewoo.product.type}"}}'>
  {#slot default}
    {#loop this.omewoo.attributes as attribute}
      <OmeWooAttributeSelector target='{{"attribute":{attribute}}}' />
    {/loop}
    <OmeWooAddToCartButton behavior='{{"mode":"counter","trigger":"form_submit"}}' />
    <OmeWooBuyNowButton content='{{"label":"Buy now"}}' />
  {/slot}
</OmeWooAddToCartForm>`}
</CodeExample>

## AddToCartForm Props

| Prop | Meaning |
| --- | --- |
| `product.product_id` | Product ID. Use `{item.id}` in product loops and `{this.id}` on single product templates. |
| `product.product_type` | Product type, such as `simple` or `variable`. Use `omewoo.product.type` from product dynamic data. |
| `product.variation_id` | Optional fixed variation ID. Usually empty when selectors provide variation state. |
| `availability.unavailable` | Disables the form when authored or dynamic product availability says the product cannot be bought. |
| `availability.available` | Positive availability flag from dynamic data. |
| `availability.stock_status` | Stock status used by form sync and disabled state. |

Runtime blocks submit if the product is unavailable or if a required variable product option has not been selected.

## AddToCartButton Props

| Prop | Meaning |
| --- | --- |
| `behavior.mode` | `fixed` renders a normal button; `counter` renders quantity input plus button. |
| `behavior.trigger` | `standalone` sends its own Store API add request; `form_submit` submits the parent purchase form. |
| `behavior.product_id` | Required for standalone buttons. Ignored by form-submit buttons. |
| `quantity.default`, `min`, `max`, `step` | Quantity input defaults and bounds. Runtime clamps invalid values. |
| `content.label` | Button text. |
| `content.successMsg` | Temporary text after a successful add. |
| `accessibility.aria_label` | Button accessible label. |
| `accessibility.input_aria_label` | Quantity input accessible label in counter mode. |

E2E verifies standalone quick add updates `CartCount`, while a standalone-trigger button inside `AddToCartForm` does not accidentally submit the form.

## AttributeSelector Props

| Prop | Meaning |
| --- | --- |
| `target.attribute` | A full attribute object from `omewoo.attributes`. It contains key, label, required flag, and options. |
| `behavior.select_first_option` | Selects the first available option when nothing is selected. |
| `ui.mode` | `select`, `radio`, or `button-radio`. |
| `ui.aria_label` | Accessible selector name. |
| `ui.default_label` | Select trigger label before selection. |

Each option carries value, label, variation ID, availability, and stock status. Unavailable options are marked disabled and cannot be selected.

## BuyNowButton Props

| Prop | Meaning |
| --- | --- |
| `content.label` | Button text. |
| `accessibility.aria_label` | Optional accessible label. |
| `checkout.url` | Authored redirect target. If empty, runtime uses the localized Woo checkout URL. |

`BuyNowButton` must be inside an `AddToCartForm` because it serializes the form payload before redirecting.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `cart_count_add_to_cart` | Standalone add updates count and success state. |
| `add_to_cart_button_inside_form` | Standalone add button inside a form is skipped by runtime. |
| `product_archive_simple_add` | Product loop card form submits and updates cart count. |
| `product_single_simple_add` | Quantity input clamps to max and submitted quantity updates cart count. |
| `variable_product_requires_variation` | Variable product blocks submit until a variation option is selected. |
| `variation_selector_button_radio` | Button-radio selector selects available option and rejects unavailable option. |
| `buy_now_redirect` | Buy-now adds to cart then redirects to checkout. |
| `out_of_stock_product_disabled` | Out-of-stock form state disables the purchase button. |

---

## Shipping Selector

<!-- Sources: src/Components/Woo/ShippingMethodSelector/ShippingMethodSelector.php; src/Woo/WooSelectorDynamicSource.php; client/src/domains/woo/components/shipping-method-selector.ts; client/src/domains/woo/components/ui-choice-mode.ts; client/src/domains/woo/cart-store.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Shipping Selector

`ShippingMethodSelector` renders Woo shipping rates and lets the customer select one.

## Component

| Component key | Role |
| --- | --- |
| `OmeWooShippingMethodSelector` | Reads `shippingRates`, binds UIChoice, calls Store API to select a package rate, and refreshes totals. |

## Props

| Prop | Meaning |
| --- | --- |
| `ui.mode` | `radio`, `button-radio`, or `select`. Default is radio. |
| `ui.aria_label` | Accessible selector label. |
| `ui.default_label` | Select trigger text before selected rate is resolved. |
| `content.show_price` | Whether rate rows include formatted price text. |
| `content.price_separator` | Text between rate name and price. |

## Rate Values

Shipping selection is package-aware:

| Attribute | Value |
| --- | --- |
| `data-ome-value` | `{package_id}:{rate_id}` |
| Hidden radio `name` | `shipping_method_{package_id}` |
| Hidden radio `value` | Raw Woo `rate_id` |
| Runtime request | `select_shipping_rate(package_id, rate_id)` |

This preserves Woo's package-specific shipping behavior.

## Modes

| Mode | Behavior |
| --- | --- |
| `radio` | In-tree radiogroup with indicators. |
| `button-radio` | In-tree radiogroup without indicators. |
| `select` | Trigger plus hidden listbox content. Runtime positions list content through shared UIChoice helpers. |

If the cart does not need shipping, the selector state becomes `hidden` and no rate rows render.

## Runtime Behavior

The runtime:

1. Reads shipping packages and rates from the cart response.
2. Deduplicates package/rate keys.
3. Normalizes server-rendered rate rows when they exist.
4. Clones template rows when Store API data changes.
5. Updates selected input and UIChoice state.
6. Calls Store API on rate change and refreshes cart totals.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `shipping_selector` | Selecting free shipping updates selected rate, cart totals, and order summary totals. |
| `shipping_selector_button_radio` | Button-radio mode uses radiogroup semantics and updates totals. |
| `shipping_selector_select` | Select mode uses trigger/listbox structure and updates trigger label. |
| `shipping_selector_select_content_props` | `show_price: false` removes price display from row and trigger. |
| `no_shipping_selector` | No-shipping cart hides the selector. |
| Lifecycle pricing test | Native Woo pricing hooks still affect rendered totals around shipping selection. |

---

## Terms Checkbox

<!-- Sources: src/Components/Woo/TermsCheckbox/TermsCheckbox.php; client/src/domains/woo/components/terms-checkbox.ts; client/src/domains/woo/checkout-store.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts -->

# Terms Checkbox

`TermsCheckbox` renders checkout terms acceptance and tells the checkout store whether terms are accepted.

## Component

| Component key | Role |
| --- | --- |
| `OmeWooTermsCheckbox` | Renders the terms checkbox, optional label slot, and checkout terms state. |

## Props

| Prop | Meaning |
| --- | --- |
| `content.label` | Label text when using component-managed label copy. |
| `content.required_message` | Local error message when terms are required but unchecked. |
| `accessibility.aria_label` | Accessible checkbox label. |

The component also accepts a default slot, so authors can put richer terms copy next to the checkbox.

## Runtime Behavior

The runtime binds `input[data-ome-woo-terms-checkbox]` and updates the checkout store:

| Store flag | Meaning |
| --- | --- |
| `terms_required` | Checkout should block if the checkbox is unchecked. |
| `terms_accepted` | Current checkbox state. |

When terms are required and unchecked, `WooCheckoutStore.submit()` emits a local `terms_required` error, sets checkout state to `error`, and `CheckoutNotices` renders the message.

## Scenario Coverage

| Scenario | Covered behavior |
| --- | --- |
| `checkout_terms_blocked` | Unchecked terms blocks checkout and renders a checkout notice. |
| `checkout_terms_success` | Checked terms allows checkout success. |
| `lifecycle_checkout` | Terms accepted flow reaches Store API checkout and native order hooks. |

---

## Data Context and Dynamic Sources

<!-- Sources: src/Woo/ProductDynamicData.php; src/Woo/CartItemsDynamicSource.php; src/Woo/CartViewModel.php; src/Woo/CartItemAtomHydrator.php; src/Woo/WooSelectorDynamicSource.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.php; tests/e2e/components/woo/behavior.spec.ts -->

# Data Context and Dynamic Sources

Woo docs use the same data names that the code uses. This page explains where those names come from and when to use them.

## Product Context

`ProductDynamicData::extend_post_data()` adds an `omewoo` object to Etch post dynamic data when the current post is a Woo product.

| Expression | Use |
| --- | --- |
| `{item.omewoo.*}` | Product archive or product loop card. |
| `{this.omewoo.*}` | Single product template. |
| `{item.id}` or `{this.id}` | Product ID for `AddToCartForm.product.product_id`. |
| `{item.omewoo.product.type}` or `{this.omewoo.product.type}` | Product type for `AddToCartForm.product.product_type`. |
| `{item.omewoo.attributes}` or `{this.omewoo.attributes}` | Variation attribute loop for `AttributeSelector`. |

Product dynamic data includes product identity, price text, media, purchase availability, variation payloads, variation attributes, and option availability. See [Woo Dynamic Data Tree](./woo-dynamic-data-tree.mdx) for the full field-by-field reference for `this.omewoo`, `item.omewoo`, cart sources, and selector sources.

## Cart Dynamic Sources

`CartItemsDynamicSource` registers four source keys when the block tree contains cart-aware components or expressions:

| Source | Shape |
| --- | --- |
| `cartItems` | Cart item rows with `key`, `productId`, title fields, attributes, quantity, URL, price text, subtotal text, and image data. |
| `cartSummary` | `item_count`, `line_count`, and `state` where state is `has-items` or `empty`. |
| `cartTotals` | Total fields for subtotal/items, discount, shipping, tax, and final price. |
| `cartCoupons` | Applied coupon rows with `code`. |

The source registration is lazy. A page that does not render cart components does not register cart sources for that request.

## Cart Item Hydration

`CartItems` renders one authored row template. Server render and runtime both hydrate the row's atoms:

| Atom marker | Data field |
| --- | --- |
| `data-ome-woo-cart-item-field="image"` | Product image URL, srcset, and alt text with authored fallback. |
| `data-ome-woo-cart-item-field="title"` | Product title or composed variant title. |
| `data-ome-woo-cart-item-field="priceText"` | Unit price text. |
| `data-ome-woo-cart-item-field="subtotalText"` | Line subtotal text. |
| `data-ome-woo-cart-item-quantity` | Quantity input value and cart item key. |
| `data-ome-woo-cart-item-remove` | Remove button cart item key. |
| `data-ome-woo-cart-attribute-list` | Selected variation attributes cloned from the attribute template. |

This is why cart item atoms are meaningful only inside a cart item row or an order summary row.

## Selector Sources

`WooSelectorDynamicSource` registers selector rows while blocks render:

| Source | Used by |
| --- | --- |
| `shippingRates` | `ShippingMethodSelector` rows. |
| `paymentMethods` | `PaymentMethodSelector` rows and runtime config. |

Shipping rates use package-aware values. The row value is `{package_id}:{rate_id}`, while the hidden input keeps the raw Woo rate ID and package-specific input name. This lets Woo distinguish rates across packages.

Payment methods only include enabled simple gateways. Gateways with custom fields are skipped by `get_simple_payment_methods()`, because this selector renders simple radio/select choices rather than gateway-specific embedded forms.

## Checkout Field Schema

`CheckoutFieldSchema::build()` reads Woo countries, checkout fields, locale overrides, states, and store defaults. The runtime uses that schema to:

- Render country options.
- Switch state between select, text, and hidden modes.
- Apply Woo labels, required flags, hidden flags, field types, autocomplete, and priorities.
- Validate rendered fields before Store API submit.

Address forms still expose copy props, but `use_woo_defaults: true` keeps Woo's field copy as the default source.

## Dynamic Data Examples

Product archive:

```etch
{#loop products as item}
  <OmeWooAddToCartForm product='{{"product_id":"{item.id}","product_type":"{item.omewoo.product.type}"}}'>
    {#slot default}
      <OmeWooAddToCartButton behavior='{{"mode":"counter","trigger":"form_submit"}}' />
    {/slot}
  </OmeWooAddToCartForm>
{/loop}
```

Single product:

```etch
{#loop this.omewoo.attributes as attribute}
  <OmeWooAttributeSelector target='{{"attribute":{attribute}}}' />
{/loop}
```

---

## Cart Page Flow

<!-- 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. |

---

## Checkout Page Flow

<!-- Sources: src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Testing/E2E/Woo/WooScenarioProvider.php; src/Patterns/Testing/TestCheckoutDemo/TestCheckoutDemo.php; src/Patterns/Testing/TestCheckoutDemo/TestCheckoutDemo.css; src/Woo/CheckoutFieldSchema.php; src/Components/Woo/CheckoutProvider/CheckoutProvider.php; src/Components/Woo/CheckoutForm/CheckoutForm.php; src/Components/Woo/BillingAddressForm/BillingAddressForm.php; src/Components/Woo/ShippingAddressForm/ShippingAddressForm.php; src/Components/Woo/ShippingMethodSelector/ShippingMethodSelector.php; src/Components/Woo/PaymentMethodSelector/PaymentMethodSelector.php; src/Components/Woo/TermsCheckbox/TermsCheckbox.php; src/Components/Woo/CheckoutNotices/CheckoutNotices.php; src/Components/Woo/PlaceOrderButton/PlaceOrderButton.php; src/Components/Woo/OrderSummary/OrderSummary.php; client/src/domains/woo/checkout-store.ts; client/src/domains/woo/checkout-field-schema.ts; client/src/domains/woo/checkout-validation.ts; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Checkout Page Flow

The checkout page flow is built from `TestCheckoutDemo`. It combines form-controlled checkout primitives with a read-only order summary that reuses cart item and total atoms.

## Flow Structure

```text
CheckoutProvider
  CheckoutForm
    BillingAddressForm
    ShippingAddressForm
    ShippingMethodSelector
    PaymentMethodSelector
    TermsCheckbox
    CheckoutNotices
    PlaceOrderButton
  OrderSummary
    Product row slot
      CartItemTitle
      CartAttributeList
      CartItemSubtotal
    Totals slot
      OrderSummaryTotalsList
        TotalsSubtotal
        TotalsDiscount
        TotalsShipping
        TotalsTax
        TotalsTotal
```

`CheckoutProvider` scopes checkout state for the form and child controls. `CheckoutForm` owns the submit event and the final Store API checkout request.

## Address Forms

`BillingAddressForm` and `ShippingAddressForm` share address form props and markup generation. They render fields from the checkout field schema, not from hard-coded field lists in the docs.

The checkout runtime handles:

- required billing fields,
- email validation,
- country and state selectors,
- state field visibility when the selected country has no state options,
- the shipping-address toggle and its embedded field group,
- local blocking before Store API submit when known-invalid fields are present.

E2E verifies country/state refresh and local validation behavior before checkout requests are sent.

## Selectors

`ShippingMethodSelector` and `PaymentMethodSelector` use the shared UIChoice mode logic. Both support select and button-radio presentation. In checkout, selected values are written into checkout state before the form is submitted.

Shipping method options come from package-aware Store API rates. Payment options come from Store API payment methods. The demo checkout uses select mode for both.

## Terms, Notices, And Submit

`TermsCheckbox` blocks submit when it is required and unchecked. `CheckoutNotices` renders checkout-scoped error messages. `PlaceOrderButton` triggers the parent `CheckoutForm`.

The form sets `data-ome-state` during validation, pending submit, success, and error states so authors can style the visible state without replacing the native Woo order lifecycle.

## Order Summary

`OrderSummary` is read-only. It renders current cart products and totals inside checkout, but it does not submit or mutate checkout data. The demo uses the `full_atoms` mode so product rows and totals are authored through slots:

| Slot | Components used |
| --- | --- |
| `products` | `CartItemTitle`, `CartAttributeList`, `CartItemSubtotal`. |
| `totals` | `OrderSummaryTotalsList` with subtotal, discount, shipping, tax, and total atoms. |

This reuse keeps cart and checkout total display aligned with the same normalized cart data.

## Store API And Native Hooks

Checkout submission goes through Woo Store API checkout. Lifecycle E2E verifies native Woo hooks still run through this path, including `woocommerce_store_api_checkout_update_order_from_request` and `woocommerce_rest_checkout_process_payment_with_context`.

That means Etch components can be authored visually while Woo plugins that rely on native checkout hooks still see the checkout lifecycle.

## E2E Coverage

| Scenario | Verified behavior |
| --- | --- |
| `checkout_success` | A full checkout form submits a real order. |
| `checkout_validation_error` | Invalid required fields are marked locally. |
| `checkout_terms_blocked` | Required terms block checkout and render notices. |
| `checkout_terms_success` | Checked terms allow the normal success flow. |
| `payment_selector_button_radio` | Payment selector button-radio mode renders and selects values. |
| `payment_selector_select` | Payment selector select mode renders trigger/content and selected values. |
| `shipping_selector_select` | Checkout-compatible shipping selection works in select mode. |
| `lifecycle_checkout` | Store API checkout completes through native Woo lifecycle hooks. |

---

## Demo Store Preview Flow

<!-- Sources: src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Testing/E2E/Woo/WooDemoStoreAssets.php; src/Testing/E2E/Woo/WooDemoStoreProductSeeder.php; src/Testing/E2E/Woo/WooDemoStoreMediaSeeder.php; src/Testing/E2E/Woo/WooDemoStoreContentSync.php; src/Testing/E2E/Woo/WooDemoStoreResult.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.php; src/Patterns/Testing/TestCartDemo/TestCartDemo.php; src/Patterns/Testing/TestCheckoutDemo/TestCheckoutDemo.php; tests/e2e/components/woo/setup.ts -->

# Demo Store Preview Flow

The demo store preview flow is the repo-backed reference for how all Woo component families fit together. It is created by `WooDemoStoreBuilder`, which seeds products and registers Etch templates/pages built from Woo testing patterns.

## Builder Sequence

```text
WooDemoStoreBuilder::seed()
  reset Woo component family styles
  seed products and media
  register product archive template
  register single product template
  register cart page
  register checkout page
  register product loop preset
  register collected pattern styles
  configure Woo cart and checkout page IDs
  return product IDs, template IDs, page IDs, and preview URLs
```

The builder is intentionally a full flow instead of isolated fixture HTML. It registers real WordPress content and lets Woo render through the same runtime paths used by the component tests.

## Seeded Content

`WooDemoStoreProductSeeder` creates the products used by the archive, single product, cart, and checkout scenarios. `WooDemoStoreMediaSeeder` provides product media. The result object exposes product IDs by key so scenarios can target the same seeded products consistently.

The product loop preset uses the demo product marker meta, so the archive template only lists the seeded demo products.

## Registered Templates And Pages

| Registered content | Source pattern |
| --- | --- |
| Product archive template | `TestWooProductList` |
| Single product template | `TestSingleWooProductTemplate` |
| Cart page | `TestCartDemo` |
| Checkout page | `TestCheckoutDemo` |

The cart and checkout page IDs are also written into Woo options, which lets Woo native URLs and Store API redirects resolve to the demo pages.

## Style Reset And Pattern Styles

Before seeding, the builder resets mutable Woo component family style defaults. After building patterns, it registers all collected styles through the repo style builder. This keeps the demo pages aligned with current component defaults and current pattern CSS.

## Preview URLs

The builder returns preview URLs for:

- `archive`,
- `single`,
- `cart`,
- `checkout`.

The single product URL targets the seeded `ome-demo-shoe` product. The cart and checkout URLs are the registered demo pages. Tests can use those URLs for end-to-end preview flows, while component-level scenarios can still use `WooScenarioProvider` for smaller behavior cases.

## Why This Matters For Docs

The demo store proves the relationship between component families:

- product archive and single templates add items into shared cart state,
- cart page rows, coupons, shipping, and totals read and mutate the same Store API cart,
- checkout page consumes the same cart while submitting a Store API order,
- order summary reuses cart atoms in a read-only checkout context,
- native Woo hooks remain part of add-to-cart and checkout lifecycles.

Use this flow as the reference when deciding whether a component belongs to the product purchase, cart, totals, coupon, shipping, checkout, payment, terms, or order summary family.

---

## Product Archive Flow

<!-- Sources: src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Testing/E2E/Woo/WooDemoStoreAssets.php; src/Testing/E2E/Woo/WooScenarioProvider.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.css; src/Woo/ProductDynamicData.php; src/Components/Woo/AddToCartForm/AddToCartForm.php; src/Components/Woo/AddToCartButton/AddToCartButton.php; src/Components/Woo/AttributeSelector/AttributeSelector.php; src/Components/Woo/BuyNowButton/BuyNowButton.php; src/Components/Woo/CartCount/CartCount.php; src/Components/Woo/CartNotices/CartNotices.php; client/src/domains/woo/components/add-to-cart-form.ts; client/src/domains/woo/components/add-to-cart-button.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Product Archive Flow

The product archive flow is the canonical product-list purchase example. `WooDemoStoreBuilder` registers an archive template from `TestWooProductList` and a product loop preset that queries seeded demo products.

## Flow Structure

```text
Archive template
  CartCount
  CartNotices
  Product loop over product posts
    Product image from item.omewoo.media
    Product title and price
    AddToCartForm
      AttributeSelector loop over item.omewoo.attributes
      AddToCartButton
      BuyNowButton
    Simple-product quick AddToCartButton
```

The archive uses `{item.*}` because each card is inside a loop item. Product-level Woo dynamic data is available as `{item.omewoo.*}`.

## Product Loop Data

The demo loop preset is a normal `WP_Query` loop for `product` posts. It is scoped to the demo product marker meta used by `WooDemoStoreProductSeeder`, then sorted by menu order and title.

Inside each product card:

| Binding | Meaning |
| --- | --- |
| `{item.id}` | Current product ID. |
| `{item.title}` | Current product title. |
| `{item.omewoo.media.image.url}` | Product image URL. |
| `{item.omewoo.media.image.alt}` | Product image alt text. |
| `{item.omewoo.price.text}` | Formatted product price text. |
| `{item.omewoo.product.type}` | Product type used by purchase controls. |
| `{item.omewoo.attributes}` | Variable-product attribute objects for selector loops. |

## Purchase Behavior

The form path is used for the full purchase area. `AddToCartForm` receives the current product ID and product type, then `AddToCartButton` uses `trigger=form_submit` so the form owns the Store API payload. `BuyNowButton` is also inside the form and redirects after the add succeeds.

The same archive pattern also includes a simple-product quick add button outside the form. That button is guarded by a condition on `item.omewoo.product.type === simple`, so it can send a standalone add request with only the current product ID and quantity.

## Variation Selectors

Variable product selectors come from a nested loop over `item.omewoo.attributes`. Each loop item is passed to `AttributeSelector` through the `target.attribute` expression. The archive pattern uses select mode and lets the runtime synchronize selected attribute values back to the parent `AddToCartForm`.

If the user submits a variable product before selecting a required variation, the form stays invalid and the cart is not changed. E2E covers that behavior separately in `variable_product_requires_variation`.

## Cart State On The Archive

`CartCount` is placed above the product loop so successful add-to-cart actions from any card update one shared count. `CartNotices` is also outside the product cards, which gives the archive one live region for errors and success messages.

This pairing matters because product cards can be repeated many times, but cart state is global for the page.

## E2E Coverage

| Scenario | Verified behavior |
| --- | --- |
| `product_archive_simple_add` | Submitting a product-card form updates the cart count. |
| `cart_count_add_to_cart` | A standalone add button updates count and button state. |
| `add_to_cart_button_inside_form` | Runtime does not accidentally bind a standalone trigger inside a form. |
| `variable_product_requires_variation` | Required variation selection blocks submit until valid. |
| `buy_now_redirect` | Buy-now adds to cart and redirects to checkout. |
| `out_of_stock_product_disabled` | Unavailable product state disables purchase controls. |

---

## Single Product Flow

<!-- Sources: src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Testing/E2E/Woo/WooScenarioProvider.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.css; src/Woo/ProductDynamicData.php; src/Components/Woo/AddToCartForm/AddToCartForm.php; src/Components/Woo/AddToCartButton/AddToCartButton.php; src/Components/Woo/AttributeSelector/AttributeSelector.php; src/Components/Woo/BuyNowButton/BuyNowButton.php; client/src/domains/woo/helpers/variation-sync.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Single Product Flow

The single product flow is the current-product version of the purchase family. `WooDemoStoreBuilder` registers a single product template from `TestSingleWooProductTemplate`; the template reads from `{this.*}` instead of loop-item bindings.

## Flow Structure

```text
Single product template
  CartCount
  CartNotices
  Product image from this.omewoo.media
  Product title and price
  AddToCartForm
    AttributeSelector loop over this.omewoo.attributes
    AddToCartButton in counter mode
    BuyNowButton
```

The current product is the WordPress queried object. That makes `{this.id}`, `{this.title}`, and `{this.omewoo.*}` the correct bindings.

## Product Data Bindings

| Binding | Meaning |
| --- | --- |
| `{this.id}` | Current product ID. |
| `{this.title}` | Current product title. |
| `{this.omewoo.media.image.url}` | Main product image URL. |
| `{this.omewoo.media.image.alt}` | Main product image alt text. |
| `{this.omewoo.price.text}` | Formatted product price text. |
| `{this.omewoo.product.type}` | Product type passed into the form. |
| `{this.omewoo.attributes}` | Attribute objects used by variable product selectors. |

Use `{this.*}` only when the template is actually rendered in a product context. In loops, use `{item.*}` instead.

## Variable Product Form

The demo single-product template builds an `AddToCartForm` with:

| Form value | Source |
| --- | --- |
| `product_id` | `{this.id}` |
| `product_type` | `{this.omewoo.product.type}` |
| `variation_id` | Empty by default; selectors resolve selected variation state. |
| `available` / `unavailable` / `stock_status` | Product availability values passed into runtime state. |

`AttributeSelector` loops over `this.omewoo.attributes` and uses radio mode in the demo template. The runtime variation sync helper keeps the selected option values, availability, and final variation ID aligned with the parent form.

## Quantity And Submit

The demo uses `AddToCartButton` in counter mode. The button renders quantity controls and submits the parent form through `trigger=form_submit`. Quantity values are clamped to the authored min, max, and step before the Store API request is sent.

The `product_single_simple_add` scenario verifies this directly by entering a value above the max, then asserting the input value is clamped before the cart count changes.

## Buy Now

`BuyNowButton` belongs inside `AddToCartForm`. It serializes the same form payload as the add-to-cart submit path, sends the Store API add request, and redirects to the authored checkout URL or the localized Woo checkout URL.

Do not use `BuyNowButton` as a standalone checkout link. Its behavior depends on the parent form state, especially for variable products.

## E2E Coverage

| Scenario | Verified behavior |
| --- | --- |
| `product_single_simple_add` | Quantity bounds are enforced before add-to-cart. |
| `variable_product_requires_variation` | Missing required variation keeps the form invalid. |
| `variation_selector_button_radio` | Button-radio selectors set available options and reject unavailable options. |
| `buy_now_redirect` | Buy-now sends the add request and redirects. |
| `out_of_stock_product_disabled` | Product availability disables the form submit path. |

---

## How Woo Components Work

<!-- Sources: src/Woo/Woo.php; src/Woo/StoreApiExtension.php; src/Woo/CartItemsDynamicSource.php; src/Woo/WooSelectorDynamicSource.php; src/Woo/CartItemAtomHydrator.php; client/src/services/woo/index.ts; client/src/domains/woo/bootstrap.ts; client/src/domains/woo/woo-runtime.ts; client/src/domains/woo/cart-store.ts; client/src/domains/woo/checkout-store.ts; tests/e2e/components/woo/behavior.spec.ts -->

# How Woo Components Work

Woo components have two cooperating layers:

1. PHP component markup renders the authored Etch block tree, data attributes, slots, preview branches, and server-known dynamic data.
2. The Woo runtime binds those data attributes, reads Store API state, mutates Woo through Store API endpoints, and updates the same live DOM.

## Boot Flow

`Woo::maybe_boot()` registers the Woo service when WooCommerce is available. The service is triggered by any Woo component key listed in `Woo.php`, and it localizes:

| Localized key | Runtime use |
| --- | --- |
| `storeApiBase` | Base URL for `/wc/store/v1` requests. |
| `nonce` | Store API nonce header. |
| `checkoutUrl` | Fallback redirect target for `BuyNowButton`. |
| `isAvailable` and `diagnostics` | Runtime availability state. |
| `paymentMethods` | Simple enabled payment methods for `PaymentMethodSelector`. |
| `checkoutFields` | Woo checkout field rules, countries, states, locale overrides, and defaults. |

The browser service creates one `WooCartStore` and one `WooCheckoutStore`. Cart components subscribe to the cart store. Checkout components subscribe to the checkout store only when checkout UI is present.

## SSR and Runtime Updates

The Woo line follows this rule:

| Surface | First visible state |
| --- | --- |
| Product purchase forms | Authored server markup with product props and optional variation data. |
| Cart items and totals | Server dynamic sources when the block tree references cart data, then runtime refresh. |
| Shipping and payment selectors | Server rows when dynamic sources are available, then runtime normalization and selection binding. |
| Checkout fields | Server-authored fields, then runtime applies Woo field schema and country/state logic. |
| Notices | Runtime feedback regions. |

Server markup is not thrown away. The runtime updates text, input values, row state, and cloned rows in place. Templates remain inert blueprints for rows that need to be cloned after a Store API response.

## Store API Requests

The cart store serializes cart mutations through `RequestQueue`, then refreshes subscribers:

| Action | Store API endpoint |
| --- | --- |
| Add item | `POST /cart/add-item` |
| Update quantity | `POST /cart/update-item` |
| Remove item | `POST /cart/remove-item` |
| Apply coupon | `POST /cart/apply-coupon` |
| Remove coupon | `DELETE /cart/coupons?code=...` |
| Select shipping | `POST /cart/select-shipping-rate` |

The checkout store also serializes requests:

| Action | Store API endpoint |
| --- | --- |
| Load checkout | `GET /checkout` |
| Persist fields | `PUT /checkout?__experimental_calc_totals=true` |
| Place order | `POST /checkout` |

## Component Binding Order

`WooRuntime.boot()` binds display components, action components, product purchase controls, checkout components, and selectors. This order matters because some render callbacks re-bind child actions:

| Parent render | Follow-up binding |
| --- | --- |
| `CartItems` row render | Binds item quantity inputs and remove buttons in the rendered rows. |
| `CouponAppliedList` row render | Binds coupon remove buttons in the rendered rows. |
| `OrderSummary` render | Binds read-only summary rows and any row-level actions that are present. |

## Composition Rules

| Component | Needs |
| --- | --- |
| `AddToCartButton` with `trigger: standalone` | A direct `product_id` prop or a scoped product quantity input. It is ignored when placed inside `AddToCartForm`; the form owns submission there. |
| `AddToCartButton` with `trigger: form_submit` | A parent `AddToCartForm`; it renders as the form submit control. |
| `BuyNowButton` | A parent `AddToCartForm`; it serializes the form then redirects. |
| `AttributeSelector` | A parent purchase form and a bound `props.target.attribute` object. |
| Cart item atoms | A `CartItems` row or `OrderSummary` product row. |
| `CouponRemoveButton` | A `CouponAppliedList` row with a coupon code. |
| `PlaceOrderButton` | A parent checkout form scope. |

## Events

The runtime dispatches:

| Event | Fired from |
| --- | --- |
| `ome-woo:cart-loaded` | Cart count, totals, cart items, cart notices, or body after cart boot. |
| `ome-woo:checkout-loaded` | Checkout provider, checkout form, checkout notices, or body after checkout boot. |
| `ome-woo:checkout-started` | Checkout form before submit. |
| `ome-woo:checkout-complete` | Checkout form after Store API checkout success. |
| `ome-woo:checkout-error` | Checkout form after local validation or Store API failure. |

Product add events are dispatched by the add-item helpers after successful or failed add-to-cart actions.

---

## Woo Components

<!-- Sources: src/Components/Woo/**; src/Components/Woo/Shared/**; src/Woo/Woo.php; src/Woo/CartItemsDynamicSource.php; src/Woo/WooSelectorDynamicSource.php; client/src/domains/woo/woo-runtime.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# Woo Components

Woo components are Etch components that render WooCommerce product, cart, and checkout UI while keeping WooCommerce as the source of truth. They do not replace Woo's cart, checkout, product, shipping, payment, or order systems. They expose those systems as composable Etch blocks.

The docs are organized in three layers:

| Layer | Use it for |
| --- | --- |
| System docs | Runtime behavior, data sources, Store API flow, checkout fields, and native Woo hook compatibility. |
| Component families | Connected component clusters, such as product purchase, cart items, totals, coupons, and checkout shell. |
| Flow guides | Practical product archive, single product, cart, checkout, and demo-store compositions backed by E2E/demo fixtures. |

## Mental Model

Woo components split into four working areas:

| Area | Core components | Data source |
| --- | --- | --- |
| Product purchase | `AddToCartForm`, `AddToCartButton`, `AttributeSelector`, `BuyNowButton` | Product dynamic data from `omewoo` plus Store API cart mutations. |
| Cart state | `CartCount`, `CartNotices`, `CartItems`, cart item atoms, totals, coupons, shipping selector | Server-side `cartItems`, `cartSummary`, `cartTotals`, `cartCoupons`, then live Store API cart state. |
| Checkout | `CheckoutProvider`, `CheckoutForm`, address forms, payment selector, terms, notices, place order | Localized checkout field schema plus Store API checkout state. |
| Demo flow | Product archive, single product, cart page, checkout page | `WooDemoStoreBuilder` seeds products, variations, media, templates, pages, styles, and preview URLs. |

## Relationships

The most important rule is composition scope. Some components can work alone, and others read from a parent or a dynamic source.

| Component family | Relationship |
| --- | --- |
| Product purchase | `AddToCartForm` owns the submitted product and variation state. `AttributeSelector`, form-submit `AddToCartButton`, and `BuyNowButton` are authored inside its default slot. |
| Cart items | `CartItems` owns the item loop. `CartItemImage`, `CartItemTitle`, `CartItemPrice`, `CartItemSubtotal`, `CartItemQuantity`, `CartItemRemove`, and `CartAttributeList` read the current row. |
| Cart attributes | `CartAttributeList` loops the selected variation attributes for a cart item. `CartAttributeName` and `CartAttributeValue` read each attribute row. |
| Totals | `CartTotalsList` and `OrderSummaryTotalsList` provide layout. The total atoms render `total_items`, `total_discount`, `total_shipping`, `total_tax`, and `total_price`. |
| Coupons | `CouponForm` mutates the cart. `CouponAppliedList` renders active coupon rows. `CouponRemoveButton` belongs inside each coupon row. |
| Checkout | `CheckoutProvider` scopes checkout UI. `CheckoutForm` serializes fields and submits. Address forms, payment selector, terms, notices, and place-order controls belong inside that checkout scope. |
| Order summary | `OrderSummary` renders read-only cart rows and totals for checkout; it intentionally reuses cart item atoms and totals atoms. |

## Runtime Boundary

The first visible state is server-rendered whenever the component has enough Woo data during render. Runtime then updates live nodes in place from Store API responses. Repeated rows and inactive branches use `<template>` elements as inert blueprints, not as visible UI.

Notices are the main exception: `CartNotices` and `CheckoutNotices` are runtime-updated regions because they render user feedback from async Store API mutations and local validation.

## Native Woo Compatibility

The Woo components use the Store API for cart and checkout actions, but native Woo hooks still run. The lifecycle E2E suite verifies:

| Flow | Native hooks proved by E2E |
| --- | --- |
| Add to cart blocked | `woocommerce_add_to_cart_validation` can block mutation and render a Woo notice. |
| Add to cart allowed | `woocommerce_add_cart_item_data`, `woocommerce_add_to_cart_validation`, `woocommerce_add_cart_item`, and `woocommerce_add_to_cart` fire for Etch form submissions. |
| Pricing | `woocommerce_before_calculate_totals` and `woocommerce_cart_calculate_fees` change rendered totals. |
| Checkout | Store API order creation runs `woocommerce_store_api_checkout_update_order_from_request`, `woocommerce_new_order`, `woocommerce_rest_checkout_process_payment_with_context`, and order status hooks. |

## Start Here

- Read [How Woo Components Work](/woo/how-woo-components-work) for the request and render flow.
- Read [Data Context and Dynamic Sources](/woo/data-context-and-dynamic-sources) before composing loops or using `{item.*}` and `{this.*}`.
- Read [Component Families](/woo/component-families/product-purchase) when authoring a specific UI cluster.
- Read [Recipes](/woo/recipes) for scenario-backed examples.

---

## Woo Recipes

<!-- Sources: src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts; src/Testing/E2E/Woo/WooDemoStoreBuilder.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.php; src/Patterns/Testing/TestCartDemo/TestCartDemo.php; src/Patterns/Testing/TestCheckoutDemo/TestCheckoutDemo.php -->

# Woo Recipes

These recipes use scenario and demo-store structures that exist in the repo.

## Product Archive Card

Backed by `product_archive_simple_add` and `TestWooProductList`.

Use a product loop and bind each card with `{item.*}`:

<CodeExample title="Product archive purchase card" language="jsx">
{`{#loop products as item}
  <article class="product-card">
    <OmeWooAddToCartForm product='{{"product_id":"{item.id}","product_type":"{item.omewoo.product.type}"}}'>
      {#slot default}
        <OmeWooAddToCartButton behavior='{{"mode":"counter","trigger":"form_submit"}}' />
      {/slot}
    </OmeWooAddToCartForm>
  </article>
{/loop}`}
</CodeExample>

Why it works: the form owns product ID/type and form submission; the button is a submit control inside the form. The E2E archive scenario submits the form and verifies `CartCount` updates.

## Single Product Quantity

Backed by `product_single_simple_add`.

Use `{this.*}` on a single product template and set button quantity bounds:

<CodeExample title="Single product form with quantity bounds" language="jsx">
{`<OmeWooAddToCartForm product='{{"product_id":"{this.id}","product_type":"{this.omewoo.product.type}"}}'>
  {#slot default}
    <OmeWooAddToCartButton
      behavior='{{"mode":"counter","trigger":"form_submit"}}'
      quantity='{{"min":"1","max":"3","default":"2"}}'
    />
  {/slot}
</OmeWooAddToCartForm>`}
</CodeExample>

E2E fills `9`, dispatches change, and verifies the input clamps to `3` before the cart count updates.

## Variable Product Selector

Backed by `variable_product_requires_variation`, `variation_selector_button_radio`, and the demo single-product template.

Loop over product attributes and bind each `AttributeSelector` to the current attribute object:

<CodeExample title="Variation attribute selectors inside a purchase form" language="jsx">
{`<OmeWooAddToCartForm product='{{"product_id":"{this.id}","product_type":"{this.omewoo.product.type}"}}'>
  {#slot default}
    {#loop this.omewoo.attributes as attribute}
      <OmeWooAttributeSelector
        target='{{"attribute":{attribute}}}'
        ui='{{"mode":"radio","aria_label":"Choose {attribute.label}"}}'
      />
    {/loop}
    <OmeWooAddToCartButton behavior='{{"mode":"counter","trigger":"form_submit"}}' />
  {/slot}
</OmeWooAddToCartForm>`}
</CodeExample>

Why it works: the selector writes selected variation attribute state into the purchase form. The form blocks submit until a required variation option is selected, and unavailable options do not select.

## Cart Rows and Empty State

Backed by `cart_items_component_preview_contract`, `cart_page_update_and_remove`, and `cart_totals_and_empty_slot`.

Place cart item atoms inside the `CartItems` default slot and empty content inside the `empty` slot:

<CodeExample title="Cart item rows with empty fallback" language="jsx">
{`<OmeWooCartItems>
  {#slot default}
    <OmeWooCartItemImage />
    <OmeWooCartItemTitle />
    <OmeWooCartItemQuantity />
    <OmeWooCartItemRemove />
  {/slot}
  {#slot empty}
    Your cart is empty.
  {/slot}
</OmeWooCartItems>`}
</CodeExample>

E2E verifies row count, server-hydrated atom text, quantity updates, removal, totals refresh, and final empty state.

## Coupons

Backed by `cart_coupons`.

Use `CouponForm` to apply codes, `CouponAppliedList` to render current coupons, and `CouponRemoveButton` inside the coupon row:

<CodeExample title="Coupon apply and remove" language="jsx">
{`<OmeWooCouponForm />

<OmeWooCouponAppliedList>
  {#slot default}
    <OmeWooCouponRemoveButton />
  {/slot}
</OmeWooCouponAppliedList>`}
</CodeExample>

E2E applies `SAVE10`, verifies discount totals and coupon rows, then removes the coupon and verifies totals return.

## Shipping Methods

Backed by `shipping_selector`, `shipping_selector_button_radio`, `shipping_selector_select`, and `shipping_selector_select_content_props`.

Use `ShippingMethodSelector` wherever cart shipping selection should be available:

<CodeExample title="Shipping method selector in button-radio mode" language="jsx">
{`<OmeWooShippingMethodSelector
  ui='{{"mode":"button-radio","aria_label":"Choose a shipping method"}}'
  content='{{"show_price":true,"price_separator":" - "}}'
/>`}
</CodeExample>

The selector uses package-aware rate values. E2E verifies button-radio and select modes, hiding when no shipping is needed, and total/order summary refresh after selecting free shipping.

## Checkout Success

Backed by `checkout_success` and `TestCheckoutDemo`.

Use a provider, a form, address forms, selectors, terms, notices, and place order:

<CodeExample title="Checkout provider and form shell" language="jsx">
{`<OmeWooCheckoutProvider>
  {#slot default}
    <OmeWooCheckoutForm>
      {#slot default}
        <OmeWooBillingAddressForm />
        <OmeWooShippingAddressForm />
        <OmeWooPaymentMethodSelector />
        <OmeWooTermsCheckbox />
        <OmeWooCheckoutNotices />
        <OmeWooPlaceOrderButton />
      {/slot}
    </OmeWooCheckoutForm>
  {/slot}
</OmeWooCheckoutProvider>`}
</CodeExample>

E2E fills the required billing fields, selects a payment method, clicks place order, and waits for an order-received or order-pay URL.

## Native Hook Compatibility

Backed by `lifecycle_add_to_cart`, `shipping_selector` in pricing mode, and `lifecycle_checkout`.

Use the same components as normal. The important point is that Store API requests still run Woo hooks:

- Add-to-cart validation can block the Etch form and render a Woo notice.
- Add-to-cart hooks can inject cart item data.
- Pricing hooks can change totals rendered by cart and order summary components.
- Checkout hooks can update Store API orders and payment context.

---

## Shared Controls and Props

<!-- Sources: src/Components/Woo/Shared/AddressFormProperties.php; src/Components/Woo/Shared/CartTotalProperties.php; src/Components/Woo/Shared/TotalsListProperties.php; src/Components/Woo/ShippingMethodSelector/ShippingMethodSelector.php; src/Components/Woo/PaymentMethodSelector/PaymentMethodSelector.php; src/Components/Woo/AttributeSelector/AttributeSelector.php; client/src/domains/woo/components/ui-choice-mode.ts; tests/e2e/components/woo/behavior.spec.ts -->

# Shared Controls and Props

Several Woo families share the same authoring ideas. These props are shared because the runtime shares behavior, not because they are cosmetic conveniences.

## UIChoice Selectors

`AttributeSelector`, `ShippingMethodSelector`, address country/state fields, and `PaymentMethodSelector` all use the shared UIChoice runtime.

| Prop | Applies to | Meaning |
| --- | --- | --- |
| `ui.mode` | Attribute, shipping, payment | Selects the control structure. Supported modes depend on the component. |
| `ui.aria_label` | Attribute, shipping, payment | Accessible name on the selector root. |
| `ui.default_label` | Select mode selectors | Trigger text before a selected option is resolved. |
| `ui.html_tag` | UIChoice components that expose it | Root element tag for authored structure. |

Mode behavior:

| Mode | Markup and runtime |
| --- | --- |
| `select` | Renders a trigger and hidden listbox content. Runtime may move content into the shared UIChoice host for positioning. |
| `radio` | Renders an in-tree radiogroup with UIChoice indicators. |
| `button-radio` | Renders an in-tree radiogroup without the radio indicator. |

E2E covers button-radio and select modes for shipping and payment selectors, and select/button-radio modes for variation selection.

## Content Props

Content props control visible labels and fallback text:

| Prop group | Components | Notes |
| --- | --- | --- |
| `content.label` | Add-to-cart button, buy-now button, remove buttons, place-order button | Button text; ARIA labels can mirror it. |
| `content.successMsg` | Add-to-cart button | Temporary button text after successful add. |
| `content.show_price` and `content.price_separator` | Shipping selector | Controls shipping rate label composition. |
| `content.show_description` | Payment selector | Removes payment method descriptions when false. |
| `content.show_empty_message` and `content.empty_message` | Coupon applied list | Controls the empty coupon message. |
| `content.include_attributes` and `content.variant_separator` | Cart item title, order summary | Controls composed variant title text. |

## Structure Props

Structure props are for authored HTML semantics, not runtime targeting.

| Prop | Applies to | Meaning |
| --- | --- | --- |
| `structure.root_tag` | `CartItems`, `CartAttributeList`, totals lists | Root wrapper element. |
| `structure.item_tag` | `CartItems`, `CartAttributeList` | Row element for item or attribute loops. |
| `structure.empty_tag` | `CartItems` | Empty-state wrapper element. |
| `structure.html_tag` | Labeled total atoms | Wrapper element when a total atom shows a label. |

## Preview Props

Preview props affect deterministic Etch builder output. They do not change live Woo cart or checkout data.

| Prop | Applies to | Meaning |
| --- | --- | --- |
| `preview.rows` | `CartItems`, `CartAttributeList`, `CouponAppliedList` | Number of rows shown in builder preview. |
| `preview.empty_state` | `CartItems`, `CouponAppliedList` | Shows the authored empty state in builder preview. |
| `preview.show_in_builder` | Cart and checkout notices | Shows a sample notice in builder preview. |
| `preview.notice_type` | Cart and checkout notices | Sets the builder notice type sample. |
| `preview.state` | Address form fields | Shows idle or error state in builder preview. |
| `shipping_toggle.preview_checked` | Shipping address form | Initial builder state for the different-shipping toggle. |

## Class Props

Woo components rely heavily on class props so authors can style each atomic part without changing runtime selectors.

Runtime selectors use `data-ome-*` attributes. Class props should be treated as styling hooks only.

Important shared style groups:

| Group | Components |
| --- | --- |
| UIChoice styles | Attribute selector, shipping selector, payment selector, address country/state controls. |
| Control default styles | Coupon input and checkout fields. |
| Cart totals styles | `TotalsSubtotal`, `TotalsDiscount`, `TotalsShipping`, `TotalsTax`, `TotalsTotal`. |
| Address form field styles | Billing and shipping address forms. |

## State Attributes

Woo runtime state is reflected through `data-ome-state`.

| State | Common surfaces |
| --- | --- |
| `idle` | Ready forms, buttons, notice regions without active feedback. |
| `loading`, `updating`, `processing` | Checkout store states. |
| `success` | Successful add-to-cart, coupon, quantity, remove, and checkout submit actions. |
| `error` | Local validation, Store API errors, notice regions. |
| `has-items`, `empty` | Cart count, cart items, coupon list, quantity preview. |
| `ready`, `hidden`, `text` | Address fields and shipping selector availability. |
| `unavailable`, `invalid` | Product purchase forms. |

---

## Store API and Native Hooks

<!-- Sources: client/src/domains/woo/store-api-client.ts; client/src/domains/woo/cart-store.ts; client/src/domains/woo/checkout-store.ts; src/Woo/StoreApiExtension.php; src/Testing/E2E/Woo/WooLifecycleProbe.php; tests/e2e/components/woo/lifecycle.spec.ts; tests/e2e/components/woo/setup.ts -->

# Store API and Native Hooks

Woo components send cart and checkout mutations through WooCommerce Store API. That is important because Store API still runs Woo's native cart, pricing, checkout, payment, order, and status hooks.

The lifecycle E2E suite proves this with a test-only Woo hook probe.

## Cart Requests

`WooStoreApiClient` sends cart requests with a nonce and cart token. The cart store queues mutations so the UI is not racing multiple responses.

| UI action | Store API request | Native behavior tested |
| --- | --- | --- |
| Product add | `POST /cart/add-item` | Add-to-cart validation can block, add item data can be injected, and add actions fire. |
| Quantity change | `POST /cart/update-item` | Cart totals refresh after Woo recalculates cart state. |
| Remove item | `POST /cart/remove-item` | Cart item rows and totals refresh before empty state appears. |
| Apply coupon | `POST /cart/apply-coupon` | Discount totals and coupon rows update. |
| Remove coupon | `DELETE /cart/coupons?code=...` | Coupon rows and totals update. |
| Shipping selection | `POST /cart/select-shipping-rate` | Selected package rate and totals update. |

## Checkout Requests

`WooCheckoutStore` also queues requests:

| UI action | Store API request | State |
| --- | --- | --- |
| Boot checkout | `GET /checkout` | `loading` then `idle`. |
| Persist field changes | `PUT /checkout?__experimental_calc_totals=true` | `updating` then `idle`. |
| Place order | `POST /checkout` | `processing` then `success` or `error`. |

If a payment result has a redirect URL, the checkout form redirects after the successful response.

## Native Hook Coverage

`WooLifecycleProbe` records deterministic hook events. E2E then checks the order and visible UI effects.

| E2E scenario | What it proves |
| --- | --- |
| `lifecycle_add_to_cart` with block mode | `woocommerce_add_to_cart_validation` can block cart mutation and the Woo notice renders as text. |
| `lifecycle_add_to_cart` with allow mode | `woocommerce_add_cart_item_data`, `woocommerce_add_to_cart_validation`, `woocommerce_add_cart_item`, and `woocommerce_add_to_cart` fire for Etch form submissions. |
| `shipping_selector` with pricing mode | `woocommerce_before_calculate_totals` changes item price and `woocommerce_cart_calculate_fees` changes totals rendered by cart and order summary components. |
| `lifecycle_checkout` | Store API checkout creates an order through native hooks, writes order meta, records payment context, and reaches an order-received flow. |

## Error Handling

Store API errors are converted into safe notices:

- Cart errors become cart notices with a source such as `add-to-cart`, `quantity`, `remove`, `coupon`, `shipping`, `stock`, or `variation`.
- Checkout errors become checkout notices and field error markers when Woo exposes field keys.
- Known Woo checkout error codes are mapped to field keys when Store API does not include `data.params`.
- Notice message text is normalized and rendered with text content, not injected as HTML.

## Store API Extension Data

`StoreApiExtension` registers an `ohmyetch` namespace on the Store API cart endpoint when Woo Blocks APIs are available. It exposes capability metadata:

| Capability | Meaning |
| --- | --- |
| `cart_count` | OME cart count components are supported for the response. |
| `add_to_cart` | OME add-to-cart components are supported for the response. |

This metadata is read-only and does not replace Woo's native cart schema.

---

## Woo Dynamic Data Tree

<!-- Sources: src/Woo/ProductDynamicData.php; src/Support/EtchImageData.php; src/Woo/CartItemsDynamicSource.php; src/Woo/CartViewModel.php; src/Woo/CartItemTitleFormatter.php; src/Woo/WooSelectorDynamicSource.php; src/Components/Woo/AttributeSelector/AttributeSelector.php; src/Patterns/Testing/TestWooProductList/TestWooProductList.php; src/Patterns/Testing/TestSingleWooProductTemplate/TestSingleWooProductTemplate.php; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts -->

# Woo Dynamic Data Tree

Woo product dynamic data is exposed under `omewoo` on Etch post data when the post is a Woo product.

Use the same tree with different prefixes depending on context:

| Context | Prefix |
| --- | --- |
| Product archive or product loop | `{item.omewoo...}` |
| Single product template | `{this.omewoo...}` |

The examples below use `{this.omewoo...}`. In a product loop, replace `this` with `item`.

## Product Tree

| Expression | Type | Meaning |
| --- | --- | --- |
| `{this.omewoo.productType}` | string | Woo product type, such as `simple` or `variable`. |
| `{this.omewoo.productId}` | number | Woo product ID. |
| `{this.omewoo.priceText}` | string | Formatted current product price text. |
| `{this.omewoo.stockStatus}` | string | Woo stock status. |
| `{this.omewoo.available}` | boolean | `true` when the product is purchasable and in stock. |
| `{this.omewoo.product.id}` | number | Product identity ID. |
| `{this.omewoo.product.type}` | string | Product identity type. Use this for `AddToCartForm.product.product_type`. |
| `{this.omewoo.product.sku}` | string | Product SKU. |
| `{this.omewoo.product.name}` | string | Product display name. |

The top-level values are convenience aliases. The grouped objects are the more descriptive structure.

## Price Tree

| Expression | Type | Meaning |
| --- | --- | --- |
| `{this.omewoo.price.currencyCode}` | string | Store currency code. |
| `{this.omewoo.price.currencySymbol}` | string | Decoded store currency symbol. |
| `{this.omewoo.price.raw}` | string | Raw Woo price. |
| `{this.omewoo.price.regular}` | string | Raw regular price. |
| `{this.omewoo.price.sale}` | string | Raw sale price. |
| `{this.omewoo.price.text}` | string | Formatted price text. |

The demo archive and single-product patterns use `{item.omewoo.price.text}` and `{this.omewoo.price.text}` for visible price copy.

## Media Tree

| Expression | Type | Meaning |
| --- | --- | --- |
| `{this.omewoo.media.image.id}` | number | Attachment ID, or `0` when no attachment is available. |
| `{this.omewoo.media.image.url}` | string | Full image URL. |
| `{this.omewoo.media.image.alt}` | string | Attachment alt text, falling back to product or variant name. |
| `{this.omewoo.media.image.title}` | string | Attachment title. |
| `{this.omewoo.media.image.caption}` | string | Attachment caption. |
| `{this.omewoo.media.image.description}` | string | Attachment description. |
| `{this.omewoo.media.image.filename}` | string | Image filename. |
| `{this.omewoo.media.image.srcset}` | string | WordPress image `srcset`. |
| `{this.omewoo.media.image.width}` | number | Full image width. |
| `{this.omewoo.media.image.height}` | number | Full image height. |
| `{this.omewoo.media.image.filesize}` | number | Attachment filesize when available. |
| `{this.omewoo.media.image.mime_type}` | string | Attachment MIME type. |
| `{this.omewoo.media.image.sizes.full.url}` | string | Full-size URL when WordPress provides it. |
| `{this.omewoo.media.image.sizes.full.width}` | number | Full-size width. |
| `{this.omewoo.media.image.sizes.full.height}` | number | Full-size height. |

`sizes` is keyed by registered WordPress image size names. Common keys include `thumbnail`, `medium`, `large`, and `full`, but the available keys depend on the site.

## Purchase Tree

| Expression | Type | Meaning |
| --- | --- | --- |
| `{this.omewoo.purchase.available}` | boolean | Product can be purchased and is in stock. |
| `{this.omewoo.purchase.purchasable}` | boolean | Woo says the product is purchasable. |
| `{this.omewoo.purchase.inStock}` | boolean | Woo says the product is in stock. |
| `{this.omewoo.purchase.stockStatus}` | string | Woo stock status. |

`AddToCartForm` uses these values through its availability props. If the product is unavailable, the form disables its submit controls at runtime.

## Attribute Tree

Variable products expose variation attributes under `omewoo.attributes`. Simple products intentionally expose an empty array.

Loop target:

```etch
{#loop this.omewoo.attributes as attribute}
  ...
{/loop}
```

Each `attribute` row has this shape:

| Expression | Type | Meaning |
| --- | --- | --- |
| `{attribute.key}` | string | Store API variation attribute key, such as `attribute_pa_color`. |
| `{attribute.taxonomy}` | string | Woo taxonomy or local attribute name, such as `pa_color`. |
| `{attribute.label}` | string | Human-readable attribute label. |
| `{attribute.required}` | boolean | Current implementation marks variation attributes as required. |
| `{attribute.options}` | array | Selectable option rows for `AttributeSelector`. |

`AttributeSelector` expects the whole attribute object:

```etch
<OmeWooAttributeSelector target='{{"attribute":{attribute}}}' />
```

## Attribute Option Tree

Inside an attribute, options are available as `attribute.options`. `AttributeSelector` loops this tree internally through `props.target.attribute.options`, but authors can also inspect it in custom loops.

| Expression | Type | Meaning |
| --- | --- | --- |
| `{option.label}` | string | Option display label. |
| `{option.value}` | string | Option slug sent as the selected variation value. |
| `{option.variationId}` | number | Variation ID when a single-attribute product can map the option to one variant; otherwise `0`. |
| `{option.priceText}` | string | Variant price text when available from a single-attribute variant. |
| `{option.available}` | boolean | Whether the mapped option is available. |
| `{option.stockStatus}` | string | Mapped variant stock status. |
| `{option.image}` | object | Image payload using the same image shape as `media.image`. |

Runtime copies option availability into `data-ome-available`, `data-ome-unavailable`, and `data-ome-stock-status` so unavailable variation choices can disable the parent form.

## Variant Tree

Variable products expose all variation payloads under `omewoo.variants`. Simple products intentionally expose an empty array.

| Expression | Type | Meaning |
| --- | --- | --- |
| `{variant.id}` | number | Variation product ID. |
| `{variant.label}` | string | Label built from selected variation attribute values. |
| `{variant.sku}` | string | Variation SKU. |
| `{variant.priceText}` | string | Formatted variation price text. |
| `{variant.regularPrice}` | string | Raw regular variation price. |
| `{variant.available}` | boolean | Variation can be purchased and is in stock. |
| `{variant.stockStatus}` | string | Variation stock status. |
| `{variant.product.id}` | number | Variation identity ID. |
| `{variant.product.type}` | string | Variation product type. |
| `{variant.product.sku}` | string | Variation SKU from the nested identity object. |
| `{variant.product.name}` | string | Variation display name. |
| `{variant.price.*}` | object | Same price tree as product `omewoo.price`. |
| `{variant.media.image.*}` | object | Same image tree as product `omewoo.media.image`. |
| `{variant.purchase.*}` | object | Same purchase tree as product `omewoo.purchase`. |
| `{variant.attributes.attribute_pa_color}` | string | Selected value for a variation attribute key. Actual keys depend on the product. |
| `{variant.image.*}` | object | Legacy flat image alias retained for existing dynamic-data consumers. |

The variation `attributes` object is keyed by Store API variation attribute names. For taxonomy attributes this is typically `attribute_pa_{slug}`.

## Common Product Bindings

| Use case | Product loop | Single product |
| --- | --- | --- |
| Product ID | `{item.id}` or `{item.omewoo.productId}` | `{this.id}` or `{this.omewoo.productId}` |
| Product type | `{item.omewoo.product.type}` | `{this.omewoo.product.type}` |
| Product image URL | `{item.omewoo.media.image.url}` | `{this.omewoo.media.image.url}` |
| Product image alt | `{item.omewoo.media.image.alt}` | `{this.omewoo.media.image.alt}` |
| Product price | `{item.omewoo.price.text}` | `{this.omewoo.price.text}` |
| Variation attributes loop | `item.omewoo.attributes` | `this.omewoo.attributes` |

Use `item` inside loops and `this` on single product templates. If `this.omewoo.attributes` is empty in preview, confirm the preview product is a variable product.

## Related Cart Source Trees

These are not under `omewoo`, but they are the other Woo dynamic sources authors can target directly.

### `cartItems`

Loop target:

```etch
{#loop cartItems as item}
  ...
{/loop}
```

| Expression | Type | Meaning |
| --- | --- | --- |
| `{item.key}` | string | Woo cart item key. |
| `{item.productId}` | number | Product ID. |
| `{item.title}` | string | Composed title, including selected variation labels when present. |
| `{item.productTitle}` | string | Parent product title. |
| `{item.titleParts}` | array | Title parts used to compose `title`. |
| `{item.attributes}` | array | Selected cart item attribute rows. |
| `{item.quantity}` | number | Cart item quantity. |
| `{item.url}` | string | Product permalink. |
| `{item.priceRaw}` | string | Raw unit price. |
| `{item.priceText}` | string | Formatted unit price text. |
| `{item.subtotalRaw}` | string | Raw line subtotal. |
| `{item.subtotalText}` | string | Formatted line subtotal text. |
| `{item.media.image.*}` | object | Current item image payload. |
| `{item.image.*}` | object | Legacy flat image alias retained for existing dynamic-data consumers. |

Each `item.attributes` row has:

| Expression | Type | Meaning |
| --- | --- | --- |
| `{attribute.key}` | string | Attribute taxonomy key. |
| `{attribute.name}` | string | Human-readable attribute name. |
| `{attribute.taxonomy}` | string | Attribute taxonomy. |
| `{attribute.value}` | string | Human-readable selected attribute value. |

### `cartSummary`

| Expression | Type | Meaning |
| --- | --- | --- |
| `{cartSummary.item_count}` | number | Sum of cart quantities. |
| `{cartSummary.line_count}` | number | Number of cart lines. |
| `{cartSummary.state}` | string | `has-items` or `empty`. |

### `cartTotals`

| Expression | Type | Meaning |
| --- | --- | --- |
| `{cartTotals.total_price}` | string | Raw final total. |
| `{cartTotals.totalPriceText}` | string | Formatted final total. |
| `{cartTotals.total_items}` | string | Raw subtotal/items total. |
| `{cartTotals.totalItemsText}` | string | Formatted subtotal/items total. |
| `{cartTotals.total_discount}` | string | Raw discount total. |
| `{cartTotals.totalDiscountText}` | string | Formatted discount total. |
| `{cartTotals.total_shipping}` | string | Raw shipping total. |
| `{cartTotals.totalShippingText}` | string | Formatted shipping total. |
| `{cartTotals.total_tax}` | string | Raw tax total. |
| `{cartTotals.totalTaxText}` | string | Formatted tax total. |

### `cartCoupons`

| Expression | Type | Meaning |
| --- | --- | --- |
| `{coupon.code}` | string | Applied coupon code. |

## Related Selector Source Trees

### `shippingRates`

Loop target:

```etch
{#loop shippingRates as rate}
  ...
{/loop}
```

| Expression | Type | Meaning |
| --- | --- | --- |
| `{rate.key}` | string | Package-aware key in `{package_id}:{rate_id}` form. |
| `{rate.package_id}` | number | Shipping package index or package ID. |
| `{rate.rate_id}` | string | Raw Woo shipping rate ID. |
| `{rate.name}` | string | Shipping rate label. |
| `{rate.description}` | string | Shipping rate description. |
| `{rate.price}` | string | Raw shipping cost. |
| `{rate.priceText}` | string | Formatted shipping cost. |
| `{rate.selected}` | boolean | Whether Woo currently has the rate selected for the package. |

### `paymentMethods`

Loop target:

```etch
{#loop paymentMethods as method}
  ...
{/loop}
```

| Expression | Type | Meaning |
| --- | --- | --- |
| `{method.id}` | string | Payment gateway ID. |
| `{method.label}` | string | Payment gateway label. |
| `{method.description}` | string | Payment gateway description. |
| `{method.selected}` | boolean | Whether Woo currently has this gateway selected. |

Only enabled simple gateways are included. Gateways with custom embedded fields are skipped by this source.