@base44/app-plugin-commerce 0.2.7 → 0.3.1

package/src/commerce/storefront/cartUI.jsx

@@ -5,39 +5,20 @@ import { useLocation } from "react-router-dom";
  * 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.
+ * 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 renders off `open`:
+ * layout; the layout then renders the panel off `open`.
  *
- *   function StoreLayout() {
- *     const ui = useCartUI();
- *     const { itemCount } = useCart();
- *     return (<>
- *       <header>… <button type="button" onClick={ui.toggleCart}
- *                         aria-expanded={ui.open}>Bag ({itemCount})</button></header>
- *       <Outlet />
- *       {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>
- *       </>)}
- *     </>);
- *   }
- *
- * ⚑ **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.
- *
- * 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.
+ * ⚑ **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.
  *
  * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
  * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`

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>
- *
- * 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
+ * - `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
- *     (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`.
- * - `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` + open/close/toggle handlers, Esc, close-on-navigate, open-on-add;
- *     render the drawer conditionally off `open`.
+ *     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: `placeOrder`, `disabled`,
- *     `label`, `stage` (guards the just-placed-order frames), `blockers` in
- *     words.
- * - `useAddressForm` / `useCountries` / `useTotalsLines` /
- *     `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,
- *     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
- *     `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.
+ * 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, 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

@@ -9,10 +9,24 @@ import { useFormatMoney } from "./StorefrontProvider";
  * 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.
+ * (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,40 +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,
- *                    //    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 `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} 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>}
+ *   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());
@@ -84,11 +83,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     };
   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({
@@ -106,35 +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,
- *                 //    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
- *     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} 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>}
+ *   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 }) {
@@ -153,7 +139,7 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   }));
   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,

package/src/commerce/storefront/useCartLine.js

@@ -20,39 +20,23 @@ import { useCart } from "./StorefrontProvider";
  * request per settle instead of one per click; and `sold_individually` is
  * respected, so a one-per-customer product has no working "+".
  *
- * ## When `pending` settles — the exact window
+ * **When `pending` settles.** It is this row's flag, not the cart's, and not
+ * true for the whole gesture: a click only sets the optimistic quantity and
+ * (re)starts the 250ms timer, so a burst of clicks sends **one** request;
+ * `pending` goes true when that request leaves (`remove()` skips the wait); it
+ * returns to false only after the server's new cart view has been published
+ * through the provider's queue. So `pending === false` with `error === null`
+ * means this row, the cart's totals and any badge are all settled — it is the
+ * only mutation-settled signal (`useCart().status` never returns to
+ * `"loading"` for a mutation), and what a script driving the page waits on.
+ * Scope the busy state to this row: greying the whole cart for a 250ms step
+ * reads as a page-wide stall. On failure the quantity rolls back to what the
+ * server still holds and `error` is `{ code, message }`.
  *
- * `pending` is this line's own flag, not the cart's, and it is **not** true for
- * the whole gesture:
+ * It owns the quantity only. The row's own content — name, `attributesLabel`,
+ * image, money — you render from the `cart.items[n]` you passed in.
  *
- * 1. **Click → `pending` stays `false`.** `increase`/`decrease` only set the
- *    optimistic `quantity` and (re)start a `debounceMs` (250ms) timer. Nothing
- *    is in flight yet, and a further click restarts the timer, so a burst of
- *    clicks sends **one** request for the final number.
- * 2. **Debounce elapses → `pending` becomes `true`** and the request goes out.
- *    `remove()` skips this step: it cancels the timer and goes `pending`
- *    immediately.
- * 3. **`pending` returns to `false` only after the server's new cart view has
- *    been published to the provider** — the awaited mutation resolves through
- *    the provider's serialized queue, which sets the shared cart state before
- *    the await returns. So `pending === false` with `error === null` means this
- *    row's quantity, the cart's totals and any dependent badge are settled, not
- *    merely that the request finished.
- *
- * Two consequences worth designing for. **Disable and mark only this row**
- * (`disabled={!l.canIncrease || l.pending}`) — `pending` says nothing about the
- * other lines, and greying the whole cart because one stepper is busy makes a
- * 250ms update look like a page-wide stall. And **`pending` is the only
- * mutation-settled signal**: `useCart().status` never returns to `"loading"`
- * for a mutation (see its doc comment), so a caller that needs to know an
- * update landed — a script driving the page, a queued follow-up action — waits
- * on this flag, per row, and not on cart `status`.
- *
- * On failure `pending` returns to `false`, the optimistic quantity rolls back
- * to what the server still holds, and `error` is `{ code, message }`.
- *
- * @param {object} line a decorated line from `useCart().lines` (a raw
- *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
+ * @param {object} line one `cart.items[n]` from `useCart()`
  * @param {{debounceMs?: number}} [options]
  */
 export function useCartLine(line, { debounceMs = 250 } = {}) {
@@ -133,10 +117,6 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
     maxQuantity,
     atMax: quantity >= maxQuantity,
     atMin: quantity <= 1,
-    attributesLabel: line?.attributesLabel ?? "",
-    image: line?.image ?? null,
-    totalLabel: line?.totalLabel ?? "",
-    unitPriceLabel: line?.unitPriceLabel ?? "",
   };
 }
 
@@ -144,29 +124,18 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
  * CartLine — headless per-line binding for the rows of a cart you render
  * yourself. It renders **nothing**: the render function you pass as `children`
  * receives the `useCartLine` controls for that line and returns your markup.
- * It exists so a `lines.map(...)` doesn't tempt a hook call inside a loop:
+ * It exists so an `items.map(...)` doesn't tempt a hook call inside a loop:
  *
- *   const { lines } = useCart();
- *   {lines.map(line => (
- *     <CartLine key={line.item_key} line={line}>
- *       {(l) => (
- *         <li aria-busy={l.pending}>
- *           {line.name} {line.attributesLabel}
- *           <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}
- *                   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>
- *       )}
+ *   {cart.items.map(item => (
+ *     <CartLine key={item.item_key} line={item}>
+ *       {(l) => <li aria-busy={l.pending}>…your row, using item and l…</li>}
  *     </CartLine>
  *   ))}
  *
- * Equivalent to extracting your own row component that calls `useCartLine` —
- * use whichever reads better in your page.
+ * Give each row's controls their own accessible name (`Remove ${item.name}`):
+ * three buttons all named "Remove" are ambiguous to a screen reader and to a
+ * script driving the page. Equivalent to extracting your own row component that
+ * calls `useCartLine` — use whichever reads better in your page.
  *
  * @param {{line: object, options?: {debounceMs?: number},
  *   children: (controls: object) => React.ReactNode}} props
@@ -179,79 +148,3 @@ export function CartLine({ line, options, children }) {
   if (!line) return null;
   return children(controls);
 }
-
-/**
- * useCoupon — the coupon field. Small, and the difference between a store that
- * can honour its own discounts and one that cannot.
- *
- *   const c = useCoupon();
- *   <input value={c.code} onChange={(e) => c.setCode(e.target.value)} />
- *   <button onClick={c.apply} disabled={c.applying}>Apply</button>
- *   {c.error && <p role="alert">{c.error.message}</p>}
- *   {c.applied.map(a => <Chip key={a.code} onRemove={() => c.remove(a.code)} …/>)}
- *
- * Coupons are admin-only data — a storefront cannot list codes, so a seeded
- * code is reachable **only** through a field the customer types it into. If the
- * store has any coupons, this field must exist somewhere in the cart or the
- * checkout, or those codes can never be redeemed.
- *
- * An invalid, expired or ineligible code is **expected flow**: `apply()`
- * resolves `{ ok: false, error }` and never throws — render `error.message`
- * inline next to the field.
- */
-export function useCoupon() {
-  const { cart, applyCoupon, removeCoupon } = useCart();
-  const [code, setCode] = useState("");
-  const [applying, setApplying] = useState(false);
-  const [error, setError] = useState(null);
-
-  const apply = useCallback(
-    async (explicit) => {
-      const value = String(explicit ?? code ?? "").trim();
-      if (!value) return { ok: false, error: { code: "empty", message: "Enter a code." } };
-      setApplying(true);
-      setError(null);
-      const res = await applyCoupon(value);
-      setApplying(false);
-      if (res.ok) {
-        setCode("");
-        return { ok: true, cart: res.cart };
-      }
-      const err = { code: res.code ?? "coupon_invalid", message: res.message };
-      setError(err);
-      return { ok: false, error: err };
-    },
-    [code, applyCoupon],
-  );
-
-  const remove = useCallback(
-    async (codeOrEntry) => {
-      const value = typeof codeOrEntry === "string" ? codeOrEntry : codeOrEntry?.code;
-      setError(null);
-      try {
-        await removeCoupon(value);
-        return { ok: true };
-      } catch (e) {
-        const err = { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) };
-        setError(err);
-        return { ok: false, error: err };
-      }
-    },
-    [removeCoupon],
-  );
-
-  return {
-    code,
-    setCode,
-    apply,
-    remove,
-    applied: (cart?.coupons ?? []).map((c) => ({
-      code: c.code,
-      discount: c.discount ?? 0,
-      freeShipping: Boolean(c.free_shipping),
-    })),
-    applying,
-    error,
-    discountTotal: cart?.totals?.discount_total ?? 0,
-  };
-}