@base44/app-plugin-commerce 0.2.5 → 0.2.7

package/src/commerce/storefront/index.js

@@ -27,32 +27,50 @@
  *   </Route>
  *   // no shared layout? <StorefrontProvider …> <Routes>…</Routes> </StorefrontProvider>
  *
+ * Every hook hands back **plain states and handlers** — strings, booleans,
+ * arrays, callbacks (`buy.label`, `buy.disabled`, `buy.addToCart`, `f.value`,
+ * `f.set`) — never ready-made prop objects to spread. You write every element
+ * and every attribute; the hook guarantees the values are right.
+ *
  * ## Hooks
  * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
  *     shared client, cached store info (the ONLY source of payment gateways,
  *     currency and countries), money in the store's currency.
- * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
- *     filters, `refreshing`, and failure as a visible state.
- * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `useProductPrice` /
- *     `useProductGallery` — the product page: fetch + variant selection +
+ * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging
+ *     (render the paging control off `hasNext` — a page that skips it caps the
+ *     catalog), filters, `refreshing`, and failure as a visible state.
+ * - `useProduct` / `useAddToCart` / `useProductPrice` / `useProductGallery` /
+ *     `useProductSpecs` — the product page: fetch + variant selection +
  *     quantity + price + gallery, race-safe, with `status: "not_found"` and
- *     every add-to-cart failure handled. `variantAxes(view, pick)` (from
- *     `@/commerce/utils`, re-exported here) turns the resolved view into a
- *     render-ready model for the selector you write.
+ *     every add-to-cart failure handled; the buy box as
+ *     `state`/`label`/`disabled`/`addToCart`. `variantAxes(view, pick)`
+ *     (from `@/commerce/utils`, re-exported here) turns the resolved view into
+ *     a render-ready model for the selector you write; `useProductSpecs` adds
+ *     normalized `pick`/`get` lookup over `productSpecs`.
  * - `useProductReviews` — the review list and the submit form, with the store's
  *     policy as a prop and field errors matching the server's codes.
  * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
- *     `status`, render `lines` and `notices`), quantity steppers that clamp and
- *     recover, and the coupon field a store with coupons must have.
+ *     `status`, render `lines` and `notices` — money pre-formatted per line),
+ *     quantity steppers that clamp and recover, and the coupon field a store
+ *     with coupons must have.
+ * - `useCartUI` + `<CartUIProvider>` — the cart drawer's non-visual machinery:
+ *     `open` + open/close/toggle handlers, Esc, close-on-navigate, open-on-add;
+ *     render the drawer conditionally off `open`.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
  *     checkout: address state with automatic debounced shipping/tax
  *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
  *     named blockers, `placeOrder` with both navigations handled (online →
  *     provider redirect, manual → `/order-received`).
+ * - `usePlaceOrder` — the gate as one surface: `placeOrder`, `disabled`,
+ *     `label`, `stage` (guards the just-placed-order frames), `blockers` in
+ *     words.
  * - `useAddressForm` / `useCountries` / `useTotalsLines` /
- *     `useCheckoutBlockers` — the address form as a field spec you map to your
- *     own inputs (state included, country options never null), one totals
- *     projection for cart and order, and blocker codes turned into copy.
+ *     `useCheckoutBlockers` — the address form as a field spec, each field
+ *     self-contained (`id`/`value`/`set`/`error`/`autoComplete`, `state`
+ *     included, country options never null), one totals projection for cart
+ *     and order, and blocker codes turned into copy.
+ * - `useUpsell` — one product offered beside another surface: fetch-or-row,
+ *     already-in-cart matched by id, one-click add.
  * - `useOrderReturn` — the mandatory `/order-received` page in one hook:
  *     status, order, `lines`, `paymentLink`, `paymentInstructions`, noindex.
  * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
@@ -60,7 +78,8 @@
  *
  * ## Render-prop components (headless — children is a function, no markup ships)
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
- *     that are store data, never hardcoded, with their branching enumerated.
+ *     that are store data, never hardcoded; options arrive decorated with
+ *     `selected`/`select()`/`costLabel` and a single `hint` message.
  * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
  *     `lines.map(...)` never calls a hook in a loop.
  *
@@ -71,6 +90,8 @@
  *     inferred `type` (`numeric` with `number`/`unit` split out, `duration`,
  *     `location`, `list` with `items`, `text`), so a weight can be a figure and
  *     a composition bars instead of every modifier being one grey table row.
+ * - `productImages(product)` — images normalized to `{src, name, alt}` and
+ *     de-duplicated; `[]` means render your placeholder.
  */
 export {
   StorefrontProvider,
@@ -81,8 +102,10 @@ export {
   useCart,
 } from "./StorefrontProvider";
 export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
+export { usePlaceOrder } from "./usePlaceOrder";
 export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
+export { CartUIProvider, useCartUI } from "./cartUI";
 export {
   REQUIRED_BILLING_FIELDS,
   missingBillingFields,
@@ -92,7 +115,8 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart, useAddToCartButton } from "./useProduct";
+export { useProduct, useAddToCart, useProductSpecs } from "./useProduct";
+export { useUpsell } from "./useUpsell";
 export { useProductPrice, useMoney } from "./useProductPrice";
 export { useProductGallery } from "./useProductGallery";
 export { useProductReviews } from "./useProductReviews";
@@ -106,4 +130,4 @@ export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotals
 export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
 
 // ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
-export { variantAxes, productSpecs } from "@/commerce/utils";
+export { variantAxes, productSpecs, productImages } from "@/commerce/utils";

package/src/commerce/storefront/pickers.jsx

@@ -1,5 +1,6 @@
 import React from "react";
 import { useCheckoutContextOptional } from "./useCheckout";
+import { useFormatMoney } from "./StorefrontProvider";
 
 /**
  * Headless pickers for the two checkout choices that are store data, never
@@ -7,6 +8,12 @@ import { useCheckoutContextOptional } from "./useCheckout";
  * whole UI — but they encode the branching every checkout must do, so a page
  * can't skip a `shipping_status` state or invent a payment method.
  *
+ * Every option comes decorated with plain states and one handler — `selected`
+ * (boolean), `select()` (pick it) and pre-formatted money (`costLabel`) — so
+ * the child is markup + classes and nothing else. `hint` is the one message
+ * the picker wants shown right now (or null) — render it and the status
+ * branching is done.
+ *
  * Both read the nearest <CheckoutProvider>, or take an explicit `checkout`
  * prop when you called `useCheckout` yourself.
  */
@@ -24,25 +31,40 @@ function resolveCheckout(name, prop, ctx) {
  * the cart is loading; otherwise calls `children` with:
  *
  *   {
- *     status,        // "missing_address" | "choice_required" | "chosen" | "auto_selected"
- *     methods,       // [{ id, title, cost }] — what this address is offered
- *     chosen,        // the chosen/auto-selected entry (title + cost), or null
+ *     status,        // "missing_address" | "choice_required" | "chosen"
+ *                    //   | "auto_selected" | "none_available"
+ *     methods,       // [{ id, title, cost, costLabel, selected,
+ *                    //    select }] — what this address is offered
+ *     chosen,        // the chosen/auto-selected entry (with costLabel), or null
  *     selected,      // alias of `chosen` — the same name the payment picker uses
  *     choose,        // (id) => Promise — call with a method's id on pick
  *     mustChoose,    // status === "choice_required" → render methods as a picker
  *     single,        // exactly one method offered — already chosen; skip the
- *                    //   picker but still show `chosen.title` and its cost
+ *                    //   picker but still show `chosen.title` and `chosen.costLabel`
  *     syncing,       // an address edit is being repriced — show a subtle busy state
- *     addressError,  // { code, message } | null — "we don't ship there" belongs
- *   }                //   on the address fields
+ *     hint,          // { code, message, severity: "info"|"error" } | null — the
+ *                    //   one notice to show now (address missing / not deliverable
+ *                    //   / repricing); render `hint.message`, done
+ *     addressError,  // { code, message } | null — also surfaces on the address
+ *   }                //   form's country field
+ *
+ * The child's whole job:
+ *
+ *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>{hint.message}</p>}
+ *   {mustChoose && methods.map(m => (
+ *     <label key={m.id} className="…">
+ *       <input type="radio" name="shipping-method" checked={m.selected} onChange={m.select}
+ *              className="…" /> {m.title} <span>{m.costLabel}</span>
+ *     </label>
+ *   ))}
+ *   {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
  *
- * Render rules the child should follow: `missing_address` → say the options
- * appear once the address is entered; `mustChoose` → a picker of `methods`;
- * otherwise display `chosen.title` + its cost (never the raw id). `single` and
- * `mustChoose` are never both true, and `single` guarantees `chosen`.
+ * `single` and `mustChoose` are never both true, and `single` guarantees
+ * `chosen` — a single option still *shows* what it is, never a picker of one.
  */
 export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
+  const formatMoney = useFormatMoney();
   const {
     shippingStatus: status,
     shippingMethods: methods,
@@ -53,15 +75,32 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     addressError,
   } = checkout;
   if (!status || status === "not_needed") return null;
+  const decorate = (m) =>
+    m && {
+      ...m,
+      selected: m.id === chosen?.id,
+      costLabel: formatMoney(m.cost),
+      select: () => choose(m.id),
+    };
+  const hint =
+    status === "missing_address"
+      ? { code: "missing_address", severity: "info", message: "Delivery options appear once your address is entered." }
+      : status === "none_available" || addressError?.code === "shipping_not_available"
+        ? { code: "none_available", severity: "error", message: addressError?.message ?? "We don't deliver to that address yet." }
+        : syncing
+          ? { code: "syncing", severity: "info", message: "Updating delivery options…" }
+          : null;
+  const decoratedChosen = decorate(chosen) ?? null;
   return children({
     status,
-    methods,
-    chosen,
-    selected: chosen,
+    methods: methods.map(decorate),
+    chosen: decoratedChosen,
+    selected: decoratedChosen,
     choose,
     mustChoose: status === "choice_required",
     single: single ?? (methods.length === 1), // fallback: a hand-built checkout object
     syncing,
+    hint,
     addressError,
   });
 }
@@ -72,18 +111,31 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  * `children` with:
  *
  *   {
- *     gateways,   // [{ slug, title, description, online }] — admin-owned data
+ *     gateways,   // [{ slug, title, description, online, selected,
+ *                 //    select }] — admin-owned data, decorated
  *     value,      // the selected slug ("" while none)
  *     select,     // (slug) => void
  *     selected,   // the selected gateway entry, or null
  *     single,     // exactly one gateway — already selected; skip the picker but
- *   }             //   still show its title so the customer knows how they pay
+ *                 //   still show its title so the customer knows how they pay
+ *     hint,       // { code, message, severity } | null — set when there are no
+ *   }             //   gateways: checkout is unavailable, say so
+ *
+ * The child's whole job:
+ *
+ *   {hint && <p role="alert">{hint.message}</p>}
+ *   {!single && gateways.map(g => (
+ *     <label key={g.slug} className="…">
+ *       <input type="radio" name="payment-method" checked={g.selected} onChange={g.select}
+ *              className="…" /> {g.title} <span>{g.description}</span>
+ *     </label>
+ *   ))}
+ *   {single && selected && <p>{selected.title} — {selected.description}</p>}
  *
- * Render rules: several gateways → a picker labeled with the admin's
- * title/description; `single` → just display it; zero gateways → say checkout
- * is unavailable instead of rendering a dead place-order button. `single`
- * guarantees `value` and `selected` — never render the one-gateway branch as
- * "nothing selected yet" — and both re-resolve when store info changes.
+ * `single` guarantees `value` and `selected` — never render the one-gateway
+ * branch as "nothing selected yet" — and both re-resolve when store info
+ * changes. Titles and descriptions are the admin's copy: render them, don't
+ * invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());
@@ -91,15 +143,24 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
     paymentMethods: gateways,
     paymentMethod: value,
     setPaymentMethod: select,
-    selectedGateway: selected,
     singlePaymentMethod: single,
   } = checkout;
   if (!gateways) return null;
+  const decorated = gateways.map((g) => ({
+    ...g,
+    selected: g.slug === value,
+    select: () => select(g.slug),
+  }));
+  const hint =
+    gateways.length === 0
+      ? { code: "none_available", severity: "error", message: "No payment method is available right now." }
+      : null;
   return children({
-    gateways,
+    gateways: decorated,
     value,
     select,
-    selected,
+    selected: decorated.find((g) => g.selected) ?? null,
     single: single ?? (gateways.length === 1), // fallback: a hand-built checkout object
+    hint,
   });
 }

package/src/commerce/storefront/useAddressForm.js

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { addressFieldSpec } from "@/commerce/utils";
 import { useStoreInfo } from "./StorefrontProvider";
 import { useCheckoutContext } from "./useCheckout";
@@ -42,26 +42,38 @@ function newValue(args) {
  * useAddressForm — the checkout address form as a field list bound to the
  * guided checkout. Needs a `<CheckoutProvider>` above it.
  *
- * Every field is **self-contained** — it carries its own setter, so a `.map`
- * never has to reach back out of the loop:
+ * Every field is **self-contained**: it carries its own value, setter, id,
+ * `autoComplete` token and error, so the whole form is one map and every
+ * element and attribute in it is yours:
  *
  *   const { fields } = useAddressForm("billing");
  *   {fields.map(f => (
- *     <label key={f.key}>
- *       {f.label}{f.required && " *"}
- *       {f.type === "select"
- *         ? <select value={f.value} onChange={e => f.set(e.target.value)}>
- *             {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
- *           </select>
- *         : <input type={f.type} value={f.value} autoComplete={f.autoComplete}
- *                  onChange={e => f.set(e.target.value)} />}
- *       {f.error && <span role="alert">{f.error}</span>}
- *     </label>
+ *     <div key={f.key} className="…">
+ *       <label htmlFor={f.id}>{f.label}{f.required && " *"}</label>
+ *       {f.isSelect ? (
+ *         <select id={f.id} value={f.value} onChange={f.set}
+ *                 autoComplete={f.autoComplete} className="…">
+ *           <option value="">{f.placeholder}</option>
+ *           {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
+ *         </select>
+ *       ) : <input id={f.id} type={f.type} value={f.value} onChange={f.set}
+ *                  autoComplete={f.autoComplete} className="…" />}
+ *       {f.error && <span role="alert" className="…">{f.error}</span>}
+ *     </div>
  *   ))}
  *
- * `f.set` also accepts the raw event (`onChange={f.set}`) or a `(key, value)`
- * pair; the hook's top-level `set(key, value)` is still there for code that
- * writes a field outside the map.
+ * ⚑ Keep `value={f.value}` + `onChange={f.set}` (the pair that binds the field
+ * to checkout) and `autoComplete={f.autoComplete}` (browsers fill addresses in
+ * one gesture with it, field by field without). `f.placeholder` resolves the
+ * select's empty option ("Select Country", or "Loading…" while countries
+ * arrive), so `countriesLoading` never needs handling by hand. `f.error` is
+ * per-field: "we don't ship there" lands on the country field, and a required
+ * field reports itself once it has been edited and left empty — untouched
+ * fields stay quiet here and surface through the place-order `blockers`.
+ *
+ * `f.set` works with custom controls too — it accepts a value, the raw change
+ * event (`onChange={f.set}`) or a `(key, value)` pair — as does the hook's
+ * top-level `set(key, value)`.
  *
  * Editing a field is all it takes to trigger the shipping/tax recalculation —
  * `useCheckout` debounces and calls `set-shipping-address` once the address is
@@ -72,9 +84,10 @@ function newValue(args) {
  *
  * @param {"billing"|"shipping"} [which]
  * @param {{includeState?: boolean, includePhone?: boolean, includeCompany?: boolean}} [options]
- * @returns {{fields: Array<{key: string, label: string, type: string,
+ * @returns {{fields: Array<{key: string, id: string, label: string, type: string,
  *   value: string, required: boolean, options: Array<object>, error: string|null,
- *   autoComplete: string, colSpan: number, set: (...args: any[]) => void}>,
+ *   autoComplete: string, colSpan: number, set: (...args: any[]) => void,
+ *   isSelect: boolean, placeholder: string|undefined}>,
  *   set: (key: string, value: any) => void, values: object, missing: Array<string>,
  *   complete: boolean, error: object|null, countriesLoading: boolean}}
  */
@@ -94,6 +107,11 @@ export function useAddressForm(which = "billing", options = {}) {
   // address is priced, not validated field-by-field.
   const missing = isBilling ? checkout.missingBillingFields : [];
 
+  // A required field reports itself as `error` only after it has been edited —
+  // an untouched form must not open covered in "required" marks. (Fields never
+  // touched at all surface through the place-order blockers instead.)
+  const [visited, setVisited] = useState({});
+
   const fields = useMemo(() => {
     const spec = addressFieldSpec({
       countries,
@@ -102,20 +120,39 @@ export function useAddressForm(which = "billing", options = {}) {
       includeEmail: isBilling, // one email per order, on billing
       ...options,
     });
-    return spec.map((f) => ({
-      ...f,
-      value: values?.[f.key] ?? "",
+    return spec.map((f) => {
+      const value = values?.[f.key] ?? "";
       // Self-contained: the field knows its own key, so a .map never has to
       // reach back out to the hook's set() (and can't pass the wrong key).
-      set: (...args) => set(f.key, newValue(args)),
+      // The first edit marks the field visited, arming its required check.
+      const setField = (...args) => {
+        setVisited((v) => (v[f.key] ? v : { ...v, [f.key]: true }));
+        set(f.key, newValue(args));
+      };
       // The address-level error ("we don't ship there") belongs on country.
-      error:
+      const error =
         f.key === "country" && checkout.addressError?.code === "shipping_not_available"
           ? checkout.addressError.message
-          : null,
-    }));
+          : visited[f.key] && !value && missing.includes(f.key)
+            ? `${f.label} is required.`
+            : null;
+      return {
+        ...f,
+        id: `${which}-${f.key}`,
+        value,
+        set: setField,
+        error,
+        isSelect: f.type === "select",
+        placeholder:
+          f.type === "select"
+            ? f.key === "country" && countriesLoading
+              ? "Loading…"
+              : `Select ${f.label}`
+            : undefined,
+      };
+    });
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [countries, values, isBilling, set, checkout.addressError, JSON.stringify(options)]);
+  }, [countries, countriesLoading, values, which, isBilling, set, checkout.addressError, visited, missing.join(","), JSON.stringify(options)]);
 
   return {
     fields,

package/src/commerce/storefront/useCartLine.js

@@ -135,6 +135,8 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
     atMin: quantity <= 1,
     attributesLabel: line?.attributesLabel ?? "",
     image: line?.image ?? null,
+    totalLabel: line?.totalLabel ?? "",
+    unitPriceLabel: line?.unitPriceLabel ?? "",
   };
 }
 
@@ -148,12 +150,15 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
  *   {lines.map(line => (
  *     <CartLine key={line.item_key} line={line}>
  *       {(l) => (
- *         <li>
+ *         <li aria-busy={l.pending}>
  *           {line.name} {line.attributesLabel}
- *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
+ *                   aria-label={`Decrease quantity of ${line.name}`}>−</button>
  *           {l.quantity}
- *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
- *           <button onClick={l.remove}>Remove</button>
+ *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
+ *                   aria-label={`Increase quantity of ${line.name}`}>+</button>
+ *           <button onClick={l.remove} aria-label={`Remove ${line.name}`}>Remove</button>
+ *           {l.totalLabel}
  *           {l.error && <p role="alert">{l.error.message}</p>}
  *         </li>
  *       )}

package/src/commerce/storefront/useCheckout.jsx

@@ -89,6 +89,12 @@ function resolvePaymentMethod(gateways, picked) {
  * `shipping_address_required`, `shipping_method_required`,
  * `shipping_not_available`, `payment_method_required`.
  *
+ * `stage` is `"editing" | "placing" | "submitted"` (`submitted` = the order was
+ * accepted; the navigation away is already in flight). **Guard on it before the
+ * cart's empty branch** — `placeOrder` clears the cart, so a page that checks
+ * only `cart.status` repaints "your bag is empty" over a just-placed order for
+ * the frames before the browser leaves. `usePlaceOrder` packages this gate.
+ *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
  * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
  * `orderReceivedPath` ("/order-received"; null disables the navigation).
@@ -113,6 +119,7 @@ export function useCheckout(options = {}) {
   const [syncing, setSyncing] = useState(false);
   const [syncedKey, setSyncedKey] = useState(undefined);
   const [placing, setPlacing] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
   const [orderError, setOrderError] = useState(null);
 
   const updateBilling = useCallback((patch) => setBilling((b) => ({ ...b, ...patch })), []);
@@ -216,6 +223,10 @@ export function useCheckout(options = {}) {
           ...(shipToDifferent ? { shipping } : {}),
           ...extra, // customer_note, success_url/cancel_url overrides, …
         });
+        // `submitted` flips BEFORE the cart clears, in the same commit — the
+        // page's `stage === "submitted"` guard is what stands between a placed
+        // order and a flash of "your bag is empty" while the browser navigates.
+        setSubmitted(true);
         clearCart(); // checkout consumed the cart
         if (
           redirectToPayment &&
@@ -280,6 +291,8 @@ export function useCheckout(options = {}) {
     blockers,
     canPlaceOrder,
     placing,
+    submitted,
+    stage: placing ? "placing" : submitted ? "submitted" : "editing",
     orderError,
     placeOrder,
     // underlying data, for convenience

package/src/commerce/storefront/useOrderReturn.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
-import { useStorefrontState } from "./StorefrontProvider";
+import { useFormatMoney, useStorefrontState } from "./StorefrontProvider";
 import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
@@ -19,9 +19,10 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  *   // "cancelled" → payment was cancelled — offer paymentLink.url or support
  *   // "error"     → render error.message with a retry via reload()
  *
- * `lines` are the order's items in the decorated cart-line shape, so the same
- * row markup renders the bag and the confirmation; totals come from
- * `useTotalsLines(order)`. The page is marked `noindex` automatically — a
+ * `lines` are the order's items in the decorated cart-line shape —
+ * `attributesLabel`, `image` as `{src, alt}|null`, `totalLabel` pre-formatted —
+ * so the same row markup renders the bag and the confirmation; totals come
+ * from `useTotalsLines(order)`. The page is marked `noindex` automatically — a
  * receipt carrying an order key must not rank (`seo: false` opts out).
  *
  * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
@@ -32,6 +33,7 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  */
 export function useOrderReturn({ auto = true, seo = true } = {}) {
   const { client } = useStorefrontState();
+  const formatMoney = useFormatMoney();
   const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
 
   const reload = useCallback(
@@ -61,7 +63,7 @@ export function useOrderReturn({ auto = true, seo = true } = {}) {
 
   useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
 
-  return { ...result, lines: orderLines(result.order ?? null), reload };
+  return { ...result, lines: orderLines(result.order ?? null, { formatMoney }), reload };
 }
 
 /**

package/src/commerce/storefront/usePlaceOrder.js

@@ -0,0 +1,63 @@
+import { useCallback } from "react";
+import { useCheckoutContext } from "./useCheckout";
+import { useCheckoutBlockers } from "./useTotalsLines";
+
+/**
+ * usePlaceOrder — the place-order gate as plain states and one handler. Needs
+ * a `<CheckoutProvider>` above it. The whole bottom of a checkout page:
+ *
+ *   const order = usePlaceOrder();
+ *   if (order.stage === "submitted") return <p>Order placed — taking you to your receipt…</p>;
+ *   …
+ *   <button type="button" onClick={order.placeOrder} disabled={order.disabled} className="…">
+ *     {order.label}
+ *   </button>
+ *   {order.error && <p role="alert" className="…">{order.error.message}</p>}
+ *   {!order.canPlaceOrder && order.blockers.map(b => <p key={b.code}>{b.message}</p>)}
+ *
+ * ⚑ **The `stage === "submitted"` guard goes above the page's empty-cart
+ * branch.** Placing an order clears the cart before the browser navigates
+ * away; without the guard the page flashes "your bag is empty" over a
+ * just-placed order. `stage` is `"editing" | "placing" | "submitted"`.
+ *
+ * `disabled` is the gate plus in-flight (`!canPlaceOrder || placing`); `label`
+ * follows `placing` and is overridable via `labels: { idle, placing }`.
+ * `placeOrder` is safe as an `onClick` handler directly — a click event passed
+ * to it is ignored (an explicit `extra` object is still forwarded). `blockers`
+ * are the disabled button's reasons in words (`useCheckoutBlockers`), each
+ * with a `field` to anchor it next to the input that fixes it. Pass
+ * `blockerLabels` to override that copy per code.
+ *
+ * @param {{labels?: {idle?: string, placing?: string},
+ *   blockerLabels?: Record<string, string>}} [options]
+ * @returns {{placeOrder: (extra?: object) => Promise<object>, disabled: boolean,
+ *   label: string, stage: "editing"|"placing"|"submitted", submitted: boolean,
+ *   placing: boolean, canPlaceOrder: boolean, error: object|null,
+ *   blockers: Array<{code: string, message: string, field: string|null}>}}
+ */
+export function usePlaceOrder({ labels, blockerLabels } = {}) {
+  const checkout = useCheckoutContext();
+  const blockers = useCheckoutBlockers({ labels: blockerLabels });
+  const { canPlaceOrder, placing, submitted, stage, orderError, placeOrder } = checkout;
+
+  // Usable as onClick={order.placeOrder}: a DOM/React event is not `extra`.
+  const place = useCallback(
+    (extra) => {
+      const isEvent = extra && typeof extra === "object" && ("nativeEvent" in extra || "target" in extra);
+      return placeOrder(isEvent ? undefined : extra);
+    },
+    [placeOrder],
+  );
+
+  return {
+    placeOrder: place,
+    disabled: !canPlaceOrder || placing,
+    label: placing ? (labels?.placing ?? "Placing your order…") : (labels?.idle ?? "Place order"),
+    stage,
+    submitted,
+    placing,
+    canPlaceOrder,
+    error: orderError,
+    blockers,
+  };
+}