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.