# Checkout Shell

> CheckoutProvider, CheckoutForm, CheckoutNotices, PlaceOrderButton, and checkout runtime state.

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