@base44/app-plugin-commerce 0.2.6 → 0.3.1

package/src/commerce/storefront/cartUI.jsx

@@ -1,59 +1,28 @@
-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`; 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; the layout then renders the panel off `open`.
  *
- *   function StoreLayout() {
- *     const ui = useCartUI();
- *     return (<>
- *       <header>… <button {...ui.triggerProps} className="…">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>
- *     </>);
- *   }
+ * ⚑ **Render the drawer conditionally — `{ui.open && …}`.** The classic drawer
+ * bug is a panel translated off-screen but still mounted: its buttons stay
+ * clickable, tab-able and visible to screen readers. Unmounting 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. The overlay is a
+ * click-away surface (`aria-hidden`, no tab stop) — it is not the close control;
+ * a named close button inside the panel is.
  *
- * 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).
- *
- * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, triggerProps,
- * overlayProps, panelProps, closeButtonProps }`. `useCartUIOptional()` returns
- * null instead of throwing (how `useAddToCartButton` integrates without
- * requiring the provider).
+ * `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 +44,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 +63,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

@@ -1,97 +1,56 @@
 /**
  * Storefront React layer — **headless**: hooks and render-prop components that
- * own the store's logic and hand you the data; they render nothing and carry
- * no styling. Every element, class and word of copy in the storefront is
- * written by you, against these APIs. Ships with the Base44 Commerce Template
- * next to the framework-free `@/commerce/utils` (which it builds on); needs
- * React and nothing else.
+ * own the store's logic and hand you the data. They render nothing, carry no
+ * styling, and ship no customer-facing copy — every element, class and word in
+ * the storefront is written by you, against these APIs. Ships with the Base44
+ * Commerce Plugin next to the framework-free `@/commerce/utils` (which it
+ * builds on); needs React and nothing else.
  *
  * The split: **logic is premade, UI never is.** Checkout repricing, variant
- * resolution, cart state, review policies, order-return verification — done
- * here, and hand-rolling any of it is where storefront bugs cluster. What a
- * checkout or a product page *looks like* is the store's identity, and no two
- * stores should share it — so nothing here emits markup. Each hook returns a
- * complete view-model (statuses to branch on, ready-to-map arrays, handlers,
- * error objects), and each doc comment states the render rules that keep the
- * store correct (e.g. an unbuyable variant option renders *disabled, not
- * hidden*; a receipt page must render `paymentInstructions`).
+ * resolution, cart state, order-return verification — done here, and
+ * hand-rolling any of it is where storefront bugs cluster. What a checkout or a
+ * product page *looks like* is the store's identity, and no two stores should
+ * share it — so nothing here emits markup, and every state arrives as a **code**
+ * (`state`, `status`, `hint.code`, `blockers`) that you write the words for.
  *
- * Setup (once, above every storefront route — on a pathless layout route,
- * wrapping the layout that renders <Outlet/>; as a child of <Routes> React
- * Router throws "is not a <Route> component"):
+ * `StorefrontProvider` mounts once, above every storefront route (see its own
+ * doc comment — getting the mounting wrong is the one setup error worth
+ * knowing). Each hook's doc comment is its contract; the map:
  *
- *   import { StorefrontProvider } from "@/commerce/storefront";
- *   import { base44 } from "@/api/base44Client";
- *   <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
- *     <Route path="/" element={<Home />} /> …
- *   </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.
- *
- * ## Hooks
- * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
+ * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useCountries` — 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)`
- *     (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` — 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 state, trigger/overlay/panel/close prop sets with dialog semantics,
- *     inert-when-closed, Esc, close-on-navigate, open-on-add.
+ *     currency and countries), money in the store's currency, and the country
+ *     list as an array that is never null.
+ * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
+ *     the whole server-side filter surface, and failure as a visible state.
+ * - `useProduct` / `useAddToCart` — the product page: fetch + variant selection
+ *     + quantity, race-safe; the buy box as `state`/`disabled`/`addToCart`.
+ * - `useCart` / `useCartLine` / `CartLine` — the shared cart (branch on
+ *     `status`, map `cart.items` into your own rows) plus quantity steppers that
+ *     clamp, coalesce rapid clicks and roll back on rejection.
+ * - `useCartUI` + `<CartUIProvider>` — a cart drawer's non-visual state.
  * - `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.
- * - `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.
- * - `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,
- *     meta and product structured data; receipts are `noindex`.
+ *     checkout: automatic shipping/tax recalculation, shipping and payment
+ *     choice, a `canPlaceOrder` gate with named blockers, `placeOrder`.
+ * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
+ * - `ShippingMethodPicker` / `PaymentMethodPicker` — render-prop components for
+ *     the two checkout choices that are store data, never hardcoded.
  *
- * ## 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.
- * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
- *     `lines.map(...)` never calls a hook in a loop.
+ * Re-exported from `@/commerce/utils` so one import line covers a page:
+ * `variantAxes` (axes → options with selected/disabled/stock derived),
+ * `productPrice` (the from-price and incomplete-selection range rules),
+ * `productImages` + `imageIndex` (an image's position in that list — how a
+ * gallery follows the variant selection without owning a second copy of it),
+ * `productSpecs` + `findSpec` (meta keys are free text, so featuring a
+ * particular spec needs a tolerant lookup, not an equality test),
+ * `attributesLabel`, `cartTotalsLines` / `orderTotalsLines`,
+ * `addressFieldSpec` (the checkout's field list, including the state/province
+ * field that silently mis-prices US/CA/AU orders when it is left out), and
+ * `storefrontErrorCode` / `storefrontErrorMessage` for the calls you make
+ * yourself — every rejection from the client carries a code worth branching on.
  *
- * ## Helpers re-exported from `@/commerce/utils`
- * - `variantAxes(view, pick)` — axes → options with selected/disabled/stock
- *     state derived, for the variant selector you write.
- * - `productSpecs(product)` — `meta_data` → descriptive rows carrying an
- *     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.
+ * The catalog and product surfaces are where the design freedom lives: these
+ * hooks hand you resolved data, and the rendering is entirely yours.
  */
 export {
   StorefrontProvider,
@@ -99,10 +58,10 @@ export {
   useStorefront,
   useStoreInfo,
   useFormatMoney,
+  useCountries,
   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";
@@ -115,19 +74,23 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart, useAddToCartButton, useProductSpecs } from "./useProduct";
-export { useUpsell } from "./useUpsell";
-export { useProductPrice, useMoney } from "./useProductPrice";
-export { useProductGallery } from "./useProductGallery";
-export { useProductReviews } from "./useProductReviews";
+export { useProduct, useAddToCart } from "./useProduct";
 
-// ── cart & checkout ────────────────────────────────────────────────────────
-export { useCartLine, useCoupon, CartLine } from "./useCartLine";
-export { useAddressForm, useCountries } from "./useAddressForm";
-export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotalsLines";
-
-// ── SEO ────────────────────────────────────────────────────────────────────
-export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
+// ── cart ───────────────────────────────────────────────────────────────────
+export { useCartLine, CartLine } from "./useCartLine";
 
 // ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
-export { variantAxes, productSpecs, productImages } from "@/commerce/utils";
+export {
+  variantAxes,
+  productPrice,
+  productImages,
+  imageIndex,
+  productSpecs,
+  findSpec,
+  attributesLabel,
+  cartTotalsLines,
+  orderTotalsLines,
+  addressFieldSpec,
+  storefrontErrorCode,
+  storefrontErrorMessage,
+} from "@/commerce/utils";

package/src/commerce/storefront/pickers.jsx

@@ -8,11 +8,25 @@ 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 money formatted in the store's currency
+ * (`costLabel`) — so the child is markup + classes and nothing else.
+ *
+ * `hint` is the one thing the picker needs said right now, as a **code**, never
+ * as copy: `{ code, severity: "info"|"error", serverMessage }`. The words are
+ * the store's — write one line per code (there are three) in the store's own
+ * voice. `serverMessage` is set only when the backend explained the situation
+ * itself (an undeliverable address); it is more specific than anything you can
+ * write, so prefer it when present:
+ *
+ *   const SHIPPING_HINTS = {            // your words, once, near the checkout
+ *     missing_address: "Enter your address to see delivery options.",
+ *     none_available:  "We can't deliver to that address yet.",
+ *     syncing:         "Updating delivery options…",
+ *   };
+ *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>
+ *     {hint.serverMessage ?? SHIPPING_HINTS[hint.code]}
+ *   </p>}
  *
  * Both read the nearest <CheckoutProvider>, or take an explicit `checkout`
  * prop when you called `useCheckout` yourself.
@@ -27,39 +41,25 @@ function resolveCheckout(name, prop, ctx) {
 }
 
 /**
- * Shipping options. Renders null for a virtual cart (`not_needed`) and while
- * the cart is loading; otherwise calls `children` with:
- *
- *   {
- *     status,        // "missing_address" | "choice_required" | "chosen"
- *                    //   | "auto_selected" | "none_available"
- *     methods,       // [{ id, title, cost, costLabel, selected,
- *                    //    radioProps, labelProps }] — 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 `chosen.costLabel`
- *     syncing,       // an address edit is being repriced — show a subtle busy state
- *     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
+ * Shipping options. Renders null for a virtual cart (`not_needed`) and while the
+ * cart is loading; otherwise calls `children` with:
  *
- * The child's whole job:
- *
- *   {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>
- *   ))}
- *   {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+ *   status         "missing_address" | "choice_required" | "chosen"
+ *                  | "auto_selected" | "none_available"
+ *   methods        [{ id, title, cost, costLabel, selected, select }]
+ *   chosen         the chosen/auto-selected entry, or null
+ *   selected       alias of `chosen` (the name the payment picker uses)
+ *   choose         (id) => Promise
+ *   mustChoose     status === "choice_required" → render methods as a picker
+ *   single         exactly one method offered — already chosen
+ *   syncing        an address edit is being repriced
+ *   hint           { code, severity, serverMessage } | null (see above)
+ *   addressError   { code, message } | null — the server's own words
  *
  * `single` and `mustChoose` are never both true, and `single` guarantees
- * `chosen` — a single option still *shows* what it is, never a picker of one.
+ * `chosen` — a single option still *shows* what it is (title + `costLabel`),
+ * never a picker of one. Never render `cart.chosen_shipping_method` directly:
+ * it is the rate's id, which is why `chosen` is handed to you resolved.
  */
 export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
@@ -79,23 +79,15 @@ 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"
-      ? { code: "missing_address", severity: "info", message: "Delivery options appear once your address is entered." }
+      ? { code: "missing_address", severity: "info", serverMessage: null }
       : status === "none_available" || addressError?.code === "shipping_not_available"
-        ? { code: "none_available", severity: "error", message: addressError?.message ?? "We don't deliver to that address yet." }
+        ? { code: "none_available", severity: "error", serverMessage: addressError?.message ?? null }
         : syncing
-          ? { code: "syncing", severity: "info", message: "Updating delivery options…" }
+          ? { code: "syncing", severity: "info", serverMessage: null }
           : null;
   const decoratedChosen = decorate(chosen) ?? null;
   return children({
@@ -113,34 +105,22 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
 }
 
 /**
- * Payment methods — every gateway the admin has ENABLED, from store info
- * (their only source). Renders null while store info loads; otherwise calls
- * `children` with:
- *
- *   {
- *     gateways,   // [{ slug, title, description, online, selected,
- *                 //    radioProps, labelProps }] — 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
- *     hint,       // { code, message, severity } | null — set when there are no
- *   }             //   gateways: checkout is unavailable, say so
- *
- * The child's whole job:
+ * Payment methods — every gateway the admin has ENABLED, from store info (their
+ * only source). Renders null while store info loads; otherwise calls `children`
+ * with:
  *
- *   {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>
- *   ))}
- *   {single && selected && <p>{selected.title} — {selected.description}</p>}
+ *   gateways   [{ slug, title, description, online, selected, select }]
+ *   value      the selected slug ("" while none)
+ *   select     (slug) => void
+ *   selected   the selected gateway entry, or null
+ *   single     exactly one gateway — already selected
+ *   hint       { code: "none_available", severity, serverMessage } | null —
+ *              no gateways at all: say checkout is unavailable, in your words
  *
  * `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
+ * changes. A default-seeded store offers `offline` only, so never hardcode a
+ * card option. Titles and descriptions are the admin's copy: render them, don't
  * invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
@@ -155,19 +135,11 @@ 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
-      ? { code: "none_available", severity: "error", message: "No payment method is available right now." }
+      ? { code: "none_available", severity: "error", serverMessage: null }
       : null;
   return children({
     gateways: decorated,