@base44/app-plugin-commerce 0.2.6 → 0.2.7

package/src/commerce/storefront/cartUI.jsx

@@ -1,59 +1,47 @@
-import React, {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
-import { useCart } from "./StorefrontProvider";
 
 /**
- * Cart drawer/panel state, headless. Every store with a cart drawer needs the
- * same non-visual machinery, and it is where hand-written drawers reliably go
- * wrong: the drawer must close on route change, be **inert** when closed (not
- * merely invisible — hidden-but-mounted buttons stay clickable and tab-able),
- * carry dialog semantics, close on Esc, and return focus to its trigger.
- * `useCartUI` owns all of it; you own every pixel.
+ * Cart drawer/panel state, headless: `open` plus the handlers to change it,
+ * and the two behaviors every drawer needs but a hand-written one forgets —
+ * it closes when the route changes (`closeOnNavigate`) and it opens when an
+ * item lands in the cart (`openOnAdd`, wired through `useAddToCart` /
+ * `useUpsell`; pass false for a navigate-to-bag flow). Esc closes it. You own
+ * every element, class and attribute.
  *
  * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
- * layout. Then the layout is three spreads:
+ * layout. Then the layout renders off `open`:
  *
  *   function StoreLayout() {
  *     const ui = useCartUI();
+ *     const { itemCount } = useCart();
  *     return (<>
- *       <header>… <button {...ui.triggerProps} className="…">Bag ({itemCount})</button></header>
+ *       <header>… <button type="button" onClick={ui.toggleCart}
+ *                         aria-expanded={ui.open}>Bag ({itemCount})</button></header>
  *       <Outlet />
- *       <div {...ui.overlayProps} className={ui.open ? "…" : "…"} />
- *       <aside {...ui.panelProps} className={ui.open ? "…translate-x-0" : "…translate-x-full"}>
- *         <button {...ui.closeButtonProps} className="…">×</button>
- *         {…your cart rows: useCart + CartLine…}
- *       </aside>
+ *       {ui.open && (<>
+ *         <div onClick={ui.closeCart} aria-hidden="true" className="…" />
+ *         <aside role="dialog" aria-modal="true" aria-label="Cart" className="…">
+ *           <button type="button" onClick={ui.closeCart} aria-label="Close cart">×</button>
+ *           {…your cart rows: useCart + CartLine…}
+ *         </aside>
+ *       </>)}
  *     </>);
  *   }
  *
- * What each prop set carries:
- * - `triggerProps` — onClick (toggle), `aria-expanded`/`aria-controls`/
- *   `aria-haspopup`, an item-count `aria-label`, and the ref used to restore
- *   focus on close. Spread your own `aria-label` after it to override.
- * - `panelProps` — `role="dialog"`, `aria-modal`, `aria-label`, `data-state`
- *   (`"open"|"closed"` — style/animate off it), focus target on open, and the
- *   **inert** DOM property while closed, so a translated-off-screen drawer's
- *   controls genuinely stop existing for clicks, Tab and screen readers. Keep
- *   the panel mounted (animate with classes); don't also conditionally unmount.
- * - `overlayProps` — click-to-close, `aria-hidden`, no tab stop. The overlay is
- *   not a second "close" control; the named close button is `closeButtonProps`.
- * - Esc closes; route changes close (`closeOnNavigate`); a successful
- *   add-to-cart opens (`openOnAdd`, via `useAddToCartButton` — pass false for a
- *   navigate-to-bag flow instead).
+ * ⚑ **Render the drawer conditionally (`{ui.open && …}`), as above.** The
+ * classic drawer bug is a panel that is translated off-screen but still
+ * mounted: its buttons stay clickable, tab-able and visible to screen readers.
+ * Unmounting it when closed is the trivial fix. If you keep it mounted to
+ * animate the slide, that concern is yours again — set the `inert` attribute
+ * while closed.
  *
- * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, triggerProps,
- * overlayProps, panelProps, closeButtonProps }`. `useCartUIOptional()` returns
- * null instead of throwing (how `useAddToCartButton` integrates without
- * requiring the provider).
+ * The overlay is a click-away surface (`aria-hidden`, no tab stop needed) —
+ * it is not the close control; a named close button inside the panel is.
+ *
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
+ * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`
+ * integrates without requiring the provider).
  *
  * A store whose cart is a page, not a drawer, skips this provider entirely.
  */
@@ -75,32 +63,14 @@ function CloseOnNavigate({ close }) {
 }
 
 /**
- * @param {{closeOnNavigate?: boolean, openOnAdd?: boolean, label?: string,
- *   children: React.ReactNode}} props `label` names the dialog for assistive
- *   tech and the default trigger/close labels (default "Cart").
+ * @param {{closeOnNavigate?: boolean, openOnAdd?: boolean,
+ *   children: React.ReactNode}} props
  */
-export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, label = "Cart", children }) {
+export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, children }) {
   const [open, setOpen] = useState(false);
   const openCart = useCallback(() => setOpen(true), []);
   const closeCart = useCallback(() => setOpen(false), []);
   const toggleCart = useCallback(() => setOpen((o) => !o), []);
-  const { itemCount } = useCart();
-
-  const panelId = useId();
-  const panelRef = useRef(null);
-  const triggerRef = useRef(null);
-  const openRef = useRef(open);
-  openRef.current = open;
-
-  // `inert` is set as a DOM property (not a JSX attribute): React 18 has no
-  // boolean `inert` support, and the property form works on 18 and 19 alike.
-  const setPanelRef = useCallback((node) => {
-    panelRef.current = node;
-    if (node) node.inert = !openRef.current;
-  }, []);
-  useEffect(() => {
-    if (panelRef.current) panelRef.current.inert = !open;
-  }, [open]);
 
   // Esc closes — the keyboard's way out is Esc and the named close button.
   useEffect(() => {
@@ -112,58 +82,16 @@ export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, label
     return () => window.removeEventListener("keydown", onKey);
   }, [open]);
 
-  // Focus follows the dialog: into the panel on open, back to the trigger on
-  // close — without it, focus is stranded inside an inert subtree.
-  const wasOpen = useRef(false);
-  useEffect(() => {
-    if (open) {
-      wasOpen.current = true;
-      panelRef.current?.focus?.();
-    } else if (wasOpen.current) {
-      wasOpen.current = false;
-      triggerRef.current?.focus?.();
-    }
-  }, [open]);
-
-  const value = useMemo(() => {
-    const state = open ? "open" : "closed";
-    return {
+  const value = useMemo(
+    () => ({
       open,
       openCart,
       closeCart,
       toggleCart,
       onItemAdded: openOnAdd ? openCart : null,
-      triggerProps: {
-        type: "button",
-        ref: triggerRef,
-        onClick: toggleCart,
-        "aria-haspopup": "dialog",
-        "aria-expanded": open,
-        "aria-controls": panelId,
-        "aria-label": `${label}, ${itemCount} ${itemCount === 1 ? "item" : "items"}`,
-      },
-      overlayProps: {
-        onClick: closeCart,
-        "aria-hidden": true,
-        tabIndex: -1,
-        "data-state": state,
-      },
-      panelProps: {
-        ref: setPanelRef,
-        id: panelId,
-        role: "dialog",
-        "aria-modal": true,
-        "aria-label": label,
-        tabIndex: -1,
-        "data-state": state,
-      },
-      closeButtonProps: {
-        type: "button",
-        onClick: closeCart,
-        "aria-label": `Close ${label.toLowerCase()}`,
-      },
-    };
-  }, [open, openCart, closeCart, toggleCart, openOnAdd, panelId, setPanelRef, label, itemCount]);
+    }),
+    [open, openCart, closeCart, toggleCart, openOnAdd],
+  );
 
   return (
     <CartUIContext.Provider value={value}>

package/src/commerce/storefront/index.js

@@ -27,24 +27,23 @@
  *   </Route>
  *   // no shared layout? <StorefrontProvider …> <Routes>…</Routes> </StorefrontProvider>
  *
- * Most hooks hand back **ready-to-spread prop sets** next to the raw data —
- * `f.inputProps`, `m.radioProps`, `buy.buttonProps`, `ui.panelProps`,
- * `list.moreProps` — so your markup is elements + classes and the wiring
- * (handlers, ids, aria, disabled logic) can't be re-derived wrong. Spread
- * first, put your `className` after.
+ * 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
- *     (`moreProps` — spread it and paging can't be dropped), filters,
- *     `refreshing`, and failure as a visible state.
- * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `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; the buy
- *     button as `buttonProps` + `state`/`label`. `variantAxes(view, pick)`
+ *     (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; 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`.
@@ -55,20 +54,21 @@
  *     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 state, trigger/overlay/panel/close prop sets with dialog semantics,
- *     inert-when-closed, Esc, close-on-navigate, open-on-add.
+ *     `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: `buttonProps`, `label`,
- *     `stage` (guards the just-placed-order frames), `blockers` in words.
+ * - `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 with per-field
- *     `inputProps`/`selectProps`/`labelProps`/`errorProps` (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:
@@ -79,7 +79,7 @@
  * ## Render-prop components (headless — children is a function, no markup ships)
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
  *     that are store data, never hardcoded; options arrive decorated with
- *     `radioProps`/`labelProps`/`costLabel` and a single `hint` message.
+ *     `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.
  *
@@ -115,7 +115,7 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart, useAddToCartButton, useProductSpecs } from "./useProduct";
+export { useProduct, useAddToCart, useProductSpecs } from "./useProduct";
 export { useUpsell } from "./useUpsell";
 export { useProductPrice, useMoney } from "./useProductPrice";
 export { useProductGallery } from "./useProductGallery";

package/src/commerce/storefront/pickers.jsx

@@ -8,11 +8,11 @@ import { useFormatMoney } from "./StorefrontProvider";
  * 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 ready-to-spread prop sets**
- * (`radioProps` / `labelProps`) 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.
+ * 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.
@@ -34,7 +34,7 @@ function resolveCheckout(name, prop, ctx) {
  *     status,        // "missing_address" | "choice_required" | "chosen"
  *                    //   | "auto_selected" | "none_available"
  *     methods,       // [{ id, title, cost, costLabel, selected,
- *                    //    radioProps, labelProps }] — what this address is offered
+ *                    //    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
@@ -52,8 +52,9 @@ function resolveCheckout(name, prop, ctx) {
  *
  *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>{hint.message}</p>}
  *   {mustChoose && methods.map(m => (
- *     <label key={m.id} {...m.labelProps} className="…">
- *       <input {...m.radioProps} className="…" /> {m.title} <span>{m.costLabel}</span>
+ *     <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>}
@@ -79,15 +80,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
       ...m,
       selected: m.id === chosen?.id,
       costLabel: formatMoney(m.cost),
-      radioProps: {
-        type: "radio",
-        name: "shipping-method",
-        id: `shipping-method-${m.id}`,
-        value: m.id,
-        checked: m.id === chosen?.id,
-        onChange: () => choose(m.id),
-      },
-      labelProps: { htmlFor: `shipping-method-${m.id}` },
+      select: () => choose(m.id),
     };
   const hint =
     status === "missing_address"
@@ -119,7 +112,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *
  *   {
  *     gateways,   // [{ slug, title, description, online, selected,
- *                 //    radioProps, labelProps }] — admin-owned data, decorated
+ *                 //    select }] — admin-owned data, decorated
  *     value,      // the selected slug ("" while none)
  *     select,     // (slug) => void
  *     selected,   // the selected gateway entry, or null
@@ -132,8 +125,9 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *
  *   {hint && <p role="alert">{hint.message}</p>}
  *   {!single && gateways.map(g => (
- *     <label key={g.slug} {...g.labelProps} className="…">
- *       <input {...g.radioProps} className="…" /> {g.title} <span>{g.description}</span>
+ *     <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>}
@@ -155,15 +149,7 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const decorated = gateways.map((g) => ({
     ...g,
     selected: g.slug === value,
-    radioProps: {
-      type: "radio",
-      name: "payment-method",
-      id: `payment-method-${g.slug}`,
-      value: g.slug,
-      checked: g.slug === value,
-      onChange: () => select(g.slug),
-    },
-    labelProps: { htmlFor: `payment-method-${g.slug}` },
+    select: () => select(g.slug),
   }));
   const hint =
     gateways.length === 0

package/src/commerce/storefront/useAddressForm.js

@@ -42,34 +42,37 @@ 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 AND its own
- * ready-to-spread attribute sets, so the whole form is one map with your
- * classes on it — never assemble `value`/`onChange`/`autoComplete` by hand:
+ * 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 => (
  *     <div key={f.key} className="…">
- *       <label {...f.labelProps}>{f.label}{f.required && " *"}</label>
+ *       <label htmlFor={f.id}>{f.label}{f.required && " *"}</label>
  *       {f.isSelect ? (
- *         <select {...f.selectProps} className="…">
+ *         <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 {...f.inputProps} className="…" />}
- *       {f.error && <span {...f.errorProps} className="…">{f.error}</span>}
+ *       ) : <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>
  *   ))}
  *
- * The prop sets carry id/name pairing, the `autoComplete` token, controlled
- * `value` + `onChange`, `required`, blur tracking and the `aria-invalid` /
- * `aria-describedby` wiring for the error line. `f.placeholder` resolves the
+ * ⚑ 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 left empty reports itself after it has been visited.
+ * 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` is still there for custom controls — it accepts a value, the raw
- * event (`onChange={f.set}`) or a `(key, value)` pair — as is the hook's
+ * `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 —
@@ -81,11 +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,
- *   isSelect: boolean, placeholder: string|undefined, inputProps: object,
- *   selectProps: object, labelProps: object, errorProps: object}>,
+ *   isSelect: boolean, placeholder: string|undefined}>,
  *   set: (key: string, value: any) => void, values: object, missing: Array<string>,
  *   complete: boolean, error: object|null, countriesLoading: boolean}}
  */
@@ -105,8 +107,9 @@ 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 visited
-  // (blurred) — an untouched form must not open covered in "required" marks.
+  // 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(() => {
@@ -121,7 +124,11 @@ export function useAddressForm(which = "billing", options = {}) {
       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).
-      const setField = (...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.
       const error =
         f.key === "country" && checkout.addressError?.code === "shipping_not_available"
@@ -129,21 +136,9 @@ export function useAddressForm(which = "billing", options = {}) {
           : visited[f.key] && !value && missing.includes(f.key)
             ? `${f.label} is required.`
             : null;
-      const id = `${which}-${f.key}`;
-      const errorId = `${id}-error`;
-      const shared = {
-        id,
-        name: id,
-        value,
-        required: f.required,
-        autoComplete: f.autoComplete,
-        onChange: setField,
-        onBlur: () => setVisited((v) => (v[f.key] ? v : { ...v, [f.key]: true })),
-        "aria-invalid": error ? true : undefined,
-        "aria-describedby": error ? errorId : undefined,
-      };
       return {
         ...f,
+        id: `${which}-${f.key}`,
         value,
         set: setField,
         error,
@@ -154,10 +149,6 @@ export function useAddressForm(which = "billing", options = {}) {
               ? "Loading…"
               : `Select ${f.label}`
             : undefined,
-        inputProps: { ...shared, type: f.type },
-        selectProps: shared,
-        labelProps: { htmlFor: id },
-        errorProps: { id: errorId, role: "alert" },
       };
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/commerce/storefront/usePlaceOrder.js

@@ -1,15 +1,18 @@
+import { useCallback } from "react";
 import { useCheckoutContext } from "./useCheckout";
 import { useCheckoutBlockers } from "./useTotalsLines";
 
 /**
- * usePlaceOrder — the place-order gate as one spreadable surface. Needs a
- * `<CheckoutProvider>` above it. The whole bottom of a checkout page:
+ * 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 {...order.buttonProps} className="…">{order.label}</button>
- *   {order.error && <p {...order.errorProps} className="…">{order.error.message}</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
@@ -17,39 +20,44 @@ import { useCheckoutBlockers } from "./useTotalsLines";
  * away; without the guard the page flashes "your bag is empty" over a
  * just-placed order. `stage` is `"editing" | "placing" | "submitted"`.
  *
- * `buttonProps` carries `onClick`, `disabled` (gate + in-flight) and
- * `aria-busy`; `label` follows `placing` and is overridable via
- * `labels: { idle, placing }`. `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.
+ * `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 {{buttonProps: object, label: string,
- *   stage: "editing"|"placing"|"submitted", submitted: boolean,
+ * @returns {{placeOrder: (extra?: object) => Promise<object>, disabled: boolean,
+ *   label: string, stage: "editing"|"placing"|"submitted", submitted: boolean,
  *   placing: boolean, canPlaceOrder: boolean, error: object|null,
- *   errorProps: object, blockers: Array<{code: string, message: string,
- *   field: string|null}>, placeOrder: (extra?: object) => Promise<object>}}
+ *   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;
-  return {
-    buttonProps: {
-      type: "button",
-      onClick: () => placeOrder(),
-      disabled: !canPlaceOrder || placing,
-      "aria-busy": placing || undefined,
+
+  // 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,
-    errorProps: { role: "alert" },
     blockers,
-    placeOrder,
   };
 }