@base44/app-plugin-commerce 0.2.6 → 0.3.1

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,
-  };
-}

package/src/commerce/storefront/useCheckout.jsx

@@ -39,50 +39,44 @@ function resolvePaymentMethod(gateways, picked) {
  * checkout must get right, so the page you build is only markup around it:
  *
  * - **Address → shipping/tax recalculation, automatic.** Edit the billing (or
- *   separate shipping) address through `updateBilling`/`updateShipping`; the
- *   moment the address is complete enough to price (default: country + city —
- *   see `isShippingAddressComplete`), the hook debounces and calls
- *   `set-shipping-address`, which recalculates every shipping option, its
- *   cost and the taxes. Half-typed addresses are never sent, an unchanged
- *   address is never re-sent, and an address the store doesn't ship to
- *   surfaces as `addressError` — show it on the address fields.
- * - **Shipping choice.** `shippingStatus` mirrors the cart's state:
- *   `auto_selected` (one option, already applied — just display
- *   `chosenShippingMethod`), `chosen`, `choice_required` (render
- *   `shippingMethods` and call `chooseShippingMethod(id)`), `missing_address`
- *   (collect the address), `not_needed` (virtual cart — render nothing).
- *   `singleShippingMethod` flags the one-option case, and `chosenShippingMethod`
- *   is filled for it — a single option is never left unselected.
+ *   separate shipping) address through `updateBilling`/`updateShipping`; once
+ *   the address is complete enough to price (default: country + city, see
+ *   `isShippingAddressComplete`), the hook debounces and calls
+ *   `set-shipping-address`, recalculating every option, its cost and the taxes.
+ *   Half-typed addresses are never sent, an unchanged address is never re-sent,
+ *   and an address the store doesn't ship to surfaces as `addressError` (the
+ *   server's own words) — render it on the address fields.
+ * - **Shipping choice.** `shippingStatus` mirrors the cart: `auto_selected`
+ *   (one option, already applied — display `chosenShippingMethod`), `chosen`,
+ *   `choice_required` (render `shippingMethods`, call
+ *   `chooseShippingMethod(id)`), `missing_address`, `none_available`,
+ *   `not_needed` (virtual cart — render nothing). `singleShippingMethod` flags
+ *   the one-option case and `chosenShippingMethod` is filled for it, so a single
+ *   option is never left unselected and never rendered as a picker of one.
  * - **Payment choice.** `paymentMethods` come from store info (their ONLY
- *   source); a store with exactly one enabled gateway gets it selected
- *   (`singlePaymentMethod`, with `selectedGateway` filled) from the first
- *   render that has store info. The selection is derived from the current
- *   gateway list, not remembered: when store info changes, a gateway that is
- *   no longer enabled is dropped and a list that is down to one gateway
- *   selects it — the customer's own pick survives as long as it stays enabled.
- * - **The gate.** `canPlaceOrder` + `blockers` say exactly what still stands
- *   between the customer and the order — drive the button's disabled state
- *   and the "what's missing" hints from them instead of re-deriving.
- * - **placeOrder.** Sends the order, clears the shared cart, and navigates:
- *   an online gateway redirects to the provider's payment page
- *   (`redirectToPayment`), everything else lands on the order-received page
- *   (`orderReceivedPath`, default `/order-received`) — which is where a manual
- *   order's payment instructions are rendered, so the offline default confirms
- *   properly with no extra wiring. Resolves to `{ ok: true, result }` or
- *   `{ ok: false, error }`. Pass `orderReceivedPath: null` to handle the
- *   result yourself (a manual-gateway result carries
+ *   source — `cart.payment_gateways` is always undefined). One enabled gateway
+ *   is selected from the first render that has store info. The selection is
+ *   derived from the current list, not remembered: a gateway the admin disables
+ *   drops out, and if that leaves one, it takes over.
+ * - **The gate.** `canPlaceOrder` + `blockers` say what still stands between the
+ *   customer and the order — drive the button's disabled state and the
+ *   what's-missing lines from them instead of re-deriving.
+ * - **placeOrder.** Sends the order, clears the shared cart, and navigates: an
+ *   online gateway redirects to the provider (`redirectToPayment`), everything
+ *   else lands on `orderReceivedPath` (default `/order-received`) — which is
+ *   where a manual order's payment instructions are rendered, so the offline
+ *   default confirms properly with no extra wiring. Resolves `{ ok: true,
+ *   result }` or `{ ok: false, error }`. Pass `orderReceivedPath: null` to
+ *   handle the result yourself (a manual result carries
  *   `result.payment_instructions`).
  *
- *   Both navigations are **full page loads** (`window.location.assign`), not
- *   router transitions: the provider hop has to leave the app, and the
- *   order-received page is built to boot from the URL alone (`order_id` +
- *   `order_key`), so a reload there is correct and shareable. Consequences
- *   worth knowing: React state does not survive it, and a browser script
- *   driving checkout loses its page context at this point — the order is
- *   still placed, so verify by navigating fresh to
- *   `orderReceivedUrl(result)`. For a client-side transition instead, pass
- *   `orderReceivedPath: null` and `navigate(orderReceivedUrl(result))`
- *   yourself.
+ *   Both navigations are **full page loads** (`window.location.assign`): the
+ *   provider hop leaves the app, and the receipt boots from the URL alone
+ *   (`order_id` + `order_key`), so a reload there is correct and shareable.
+ *   React state does not survive it, and a browser script driving checkout
+ *   loses its page context here — the order *is* placed, so verify by
+ *   navigating fresh to `orderReceivedUrl(result)`. For a client-side
+ *   transition, pass `orderReceivedPath: null` and navigate yourself.
  *
  * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
  * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
@@ -93,7 +87,14 @@ function resolvePaymentMethod(gateways, picked) {
  * 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.
+ * the frames before the browser leaves.
+ *
+ * The button is `disabled={!canPlaceOrder || placing}`, and `placeOrder` works
+ * as an `onClick` handler directly (a click event is not read as order fields).
+ * A disabled button must still say why: render one line per `blockers` code, in
+ * the store's own words — the silent disabled button is the most common
+ * checkout dead end. The codes are listed above; each maps to one thing the
+ * customer can fix.
  *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
  * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
@@ -214,6 +215,12 @@ export function useCheckout(options = {}) {
   const placeOrder = useCallback(
     async (extra = {}) => {
       if (placing) return { ok: false, error: { code: "placing", message: "Order already being placed." } };
+      // Safe as `onClick={checkout.placeOrder}`: a DOM/React event is not
+      // `extra`. Spreading one into the order payload would send a circular
+      // SyntheticEvent as order fields — an explicit object still forwards.
+      const isEvent =
+        extra && typeof extra === "object" && ("nativeEvent" in extra || "target" in extra);
+      const fields = isEvent ? {} : extra;
       setPlacing(true);
       setOrderError(null);
       try {
@@ -221,7 +228,7 @@ export function useCheckout(options = {}) {
           payment_method: paymentMethod,
           billing,
           ...(shipToDifferent ? { shipping } : {}),
-          ...extra, // customer_note, success_url/cancel_url overrides, …
+          ...fields, // 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

package/src/commerce/storefront/useOrderReturn.js

@@ -1,7 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useFormatMoney, useStorefrontState } from "./StorefrontProvider";
-import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
  * useOrderReturn — the whole `/order-received` page in one hook. Mount the
@@ -19,11 +18,12 @@ 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 —
- * `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).
+ * `lines` are the order's items normalized for rendering — `attributesLabel`,
+ * `image` as `{src, alt}|null`, `totalLabel` pre-formatted — because a receipt
+ * reusing cart-row markup otherwise reads `item.image` as an object and paints
+ * a broken image. Totals: `orderTotalsLines(order, { formatMoney })` from
+ * `@/commerce/utils`. 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
  * with the payment provider server-side — safe and idempotent on every visit.
@@ -61,7 +61,17 @@ export function useOrderReturn({ auto = true, seo = true } = {}) {
     if (auto) reload();
   }, [auto, reload]);
 
-  useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
+  // A receipt's URL carries an order key, so the page must not rank. One meta
+  // tag, added on mount and removed on unmount; the rest of this page's head —
+  // title, description — is yours to set. `seo: false` opts out entirely.
+  useEffect(() => {
+    if (!seo || typeof document === "undefined") return undefined;
+    const tag = document.createElement("meta");
+    tag.setAttribute("name", "robots");
+    tag.setAttribute("content", "noindex, nofollow");
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  }, [seo]);
 
   return { ...result, lines: orderLines(result.order ?? null, { formatMoney }), reload };
 }

package/src/commerce/storefront/useProduct.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   defaultSelection,
-  productSpecs,
+  productPrice,
   resolveSelection,
   selectOption,
   selectionFromParams,
@@ -9,20 +9,17 @@ import {
   storefrontErrorCode,
   storefrontErrorMessage,
 } from "@/commerce/utils";
-import { useCart, useStorefront } from "./StorefrontProvider";
+import { useCart, useFormatMoney, useStorefront } from "./StorefrontProvider";
 import { useCartUIOptional } from "./cartUI";
 import { useAsyncData } from "./internal/useAsyncData";
-import { useProductPrice } from "./useProductPrice";
 
 /**
  * useProduct — the product page's whole data and selection lifecycle.
  *
- *   const { status, product, view, pick, price, quantity, incQuantity } =
- *     useProduct(slug);
- *   if (status === "loading")   return <Skeleton />;
- *   if (status === "not_found") return <NotFound />;
- *   // render: price.label, view.axes (one control each), view.availability,
- *   //         view.purchasable, view.addToCart
+ *   const { status, product, view, pick, price, quantity } = useProduct(slug);
+ *   // status: "loading" | "ready" | "not_found" | "error"
+ *   // then: price.label, view.axes (one control each — variantAxes(view, pick)
+ *   // makes them render-ready), view.purchasable, view.addToCart
  *
  * It composes the variant helpers so their rules hold by default:
  * `defaultSelection` seeds the merchant's defaults, `selectOption` applies a
@@ -121,7 +118,8 @@ export function useProduct(ref, options = {}) {
   const incQuantity = useCallback(() => setQuantity(quantity + 1), [quantity, setQuantity]);
   const decQuantity = useCallback(() => setQuantity(quantity - 1), [quantity, setQuantity]);
 
-  const price = useProductPrice(view);
+  const formatMoney = useFormatMoney();
+  const price = useMemo(() => productPrice(view, { formatMoney }), [view, formatMoney]);
 
   const notFound = error?.code === "not_found";
   const status = loading
@@ -163,24 +161,21 @@ export function useProduct(ref, options = {}) {
 }
 
 /**
- * useAddToCart — add-to-cart with its failure states handled.
+ * Internal: the raw add-to-cart call with its failure states handled.
+ * `add(addToCartRef, quantity)` **never throws** and always resolves —
+ * `{ ok: true, cart }` or `{ ok: false, error: { code, message, shouldReload } }`.
+ * That matters because the natural hand-written version (`await addItem(...)`
+ * with no catch) leaves a button stuck mid-add forever the first time a variant
+ * sells out. `shouldReload` is set for `variation_not_found` — the page's data
+ * is stale, so call the product's `reload()`.
  *
- *   const { add, adding, error } = useAddToCart();
- *   <button disabled={!view.purchasable || adding}
- *           onClick={() => add(view.addToCart, quantity)}>
- *     {adding ? "Adding…" : "Add to bag"}
- *   </button>
- *   {error && <p role="alert">{error.message}</p>}
- *
- * `add()` **never throws** and always resolves — `{ ok: true, cart }` or
- * `{ ok: false, error: { code, message, shouldReload } }`. That matters because
- * the natural hand-written version (`await addItem(...)` with no catch) leaves
- * the button stuck on "Adding…" forever the first time a variant sells out.
+ * `error.message` is the server's own words when the server rejected the add;
+ * for the local `variation_required` guard it is null, because `useAddToCart`'s
+ * `state === "needs_selection"` is what a page renders for that.
  *
- * `shouldReload` is set for `variation_not_found` — the page's data is stale,
- * so call the product's `reload()`.
+ * Pages use `useAddToCart(product)` below.
  */
-export function useAddToCart() {
+function useAddItem() {
   const { addItem } = useCart();
   const [adding, setAdding] = useState(false);
   const [error, setError] = useState(null);
@@ -190,11 +185,7 @@ export function useAddToCart() {
     async (addToCartRef, quantity = 1) => {
       if (adding) return { ok: false, error: { code: "adding", message: "Already adding." } };
       if (!addToCartRef) {
-        const err = {
-          code: "variation_required",
-          message: "Choose an option first.",
-          shouldReload: false,
-        };
+        const err = { code: "variation_required", message: null, shouldReload: false };
         setError(err);
         return { ok: false, error: err };
       }
@@ -228,59 +219,58 @@ export function useAddToCart() {
   return { add, adding, error, lastAdded, reset };
 }
 
-const BUY_LABELS = {
-  ready: "Add to bag",
-  adding: "Adding…",
-  sold_out: "Sold out",
-  needs_selection: "Select options",
-};
-
 /**
- * useAddToCartButton — the buy button's whole state machine, ready to bind to
- * markup you write. Pass the entire `useProduct` result:
+ * useAddToCart — the buy box's whole state machine as plain states and
+ * handlers; every element, attribute and **word** of the markup is yours. Pass
+ * the entire `useProduct` result:
  *
+ *   const BUY = {                      // your words, written once per store
+ *     ready: "Add to bag", adding: "Adding…",
+ *     sold_out: "Sold out", needs_selection: "Choose a size",
+ *   };
  *   const p = useProduct(slug);
- *   const buy = useAddToCartButton(p, { labels: { ready: "Add to bag" } });
- *   <button {...buy.buttonProps} className="…">{buy.label}</button>
- *   {buy.error && <p role="alert">{buy.error.message}</p>}
+ *   const buy = useAddToCart(p);
+ *   <button type="button" onClick={buy.addToCart} disabled={buy.disabled} className="…">
+ *     {BUY[buy.state]}
+ *   </button>
+ *   {buy.error?.message && <p role="alert">{buy.error.message}</p>}
  *
  * `state` is `"ready" | "adding" | "sold_out" | "needs_selection"` — the
- * precedence is resolved here, not in a ternary chain — and `label` follows it
- * (override any of the four via `labels`; the words are still yours).
- * `buttonProps` carries onClick, the purchasability gate and `aria-busy`. With
- * a `<CartUIProvider>` mounted, a successful add opens the cart drawer by
+ * precedence is resolved here, not in a ternary chain you have to get right.
+ * ⚑ The button needs text for **every** state and `disabled={buy.disabled}`, or
+ * it renders empty or stays clickable while sold out. The kit ships no labels on
+ * purpose: "Add to bag" in every store built from it is how stores end up
+ * looking like each other.
+ * With a `<CartUIProvider>` mounted, a successful add opens the cart drawer by
  * itself (its `openOnAdd`); `onAdded` remains for a navigate-to-bag flow.
  *
- * What it wires so a hand-written buy box can't drop it: the button is gated on
- * `view.purchasable`; a rejected add (sold out, stale variant) lands in `error`
- * instead of leaving the button stuck on "Adding…"; a stale-variant rejection
- * reloads the product; and the quantity controls respect `sold_individually`
- * and tracked stock (`showQuantity` is false when only 1 can be bought — render
- * no stepper then).
+ * What it solves so a hand-written buy box can't drop it: `addToCart()` never
+ * throws — a rejected add (sold out, stale variant) lands in `error` instead
+ * of leaving the button stuck mid-add; a stale-variant rejection reloads the
+ * product; and the quantity controls respect `sold_individually` and tracked
+ * stock (`showQuantity` is false when only 1 can be bought — render no stepper
+ * then).
  *
  * A not-yet-loaded product is fine (`disabled: true`), so call this next to
  * `useProduct` **above** the page's `loading`/`not_found` guards — a hook below
  * an early return breaks the hook order the next render.
  *
  * @param {object} product the whole `useProduct` result
- * @param {{onAdded?: (cart: object) => void,
- *   labels?: {ready?: string, adding?: string, sold_out?: string,
- *   needs_selection?: string}}} [options]
- * @returns {{add: () => Promise<object>, adding: boolean, error: object|null,
- *   reset: () => void, disabled: boolean, soldOut: boolean,
- *   needsSelection: boolean, purchasable: boolean,
- *   state: "ready"|"adding"|"sold_out"|"needs_selection", label: string,
- *   buttonProps: object,
+ * @param {{onAdded?: (cart: object) => void}} [options]
+ * @returns {{addToCart: () => Promise<object>, adding: boolean,
+ *   error: object|null, reset: () => void, disabled: boolean,
+ *   soldOut: boolean, needsSelection: boolean, purchasable: boolean,
+ *   state: "ready"|"adding"|"sold_out"|"needs_selection",
  *   quantity: number, setQuantity: (n: number) => void, increase: () => void,
  *   decrease: () => void, canIncrease: boolean, canDecrease: boolean,
  *   maxQuantity: number, showQuantity: boolean}}
  */
-export function useAddToCartButton(product, { onAdded, labels } = {}) {
-  const { add, adding, error, reset } = useAddToCart();
+export function useAddToCart(product, { onAdded } = {}) {
+  const { add, adding, error, reset } = useAddItem();
   const cartUI = useCartUIOptional();
   const view = product?.view ?? null;
 
-  const submit = useCallback(async () => {
+  const addToCart = useCallback(async () => {
     if (!view) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };
     const res = await add(view.addToCart, product.quantity);
     if (res.ok) {
@@ -302,7 +292,7 @@ export function useAddToCartButton(product, { onAdded, labels } = {}) {
   const disabled = !view?.purchasable || adding;
 
   return {
-    add: submit,
+    addToCart,
     adding,
     error,
     reset,
@@ -311,13 +301,6 @@ export function useAddToCartButton(product, { onAdded, labels } = {}) {
     needsSelection,
     purchasable: Boolean(view?.purchasable),
     state,
-    label: labels?.[state] ?? BUY_LABELS[state],
-    buttonProps: {
-      type: "button",
-      onClick: submit,
-      disabled,
-      "aria-busy": adding || undefined,
-    },
     quantity: product?.quantity ?? 1,
     setQuantity: product?.setQuantity ?? (() => {}),
     increase: product?.incQuantity ?? (() => {}),
@@ -329,51 +312,3 @@ export function useAddToCartButton(product, { onAdded, labels } = {}) {
   };
 }
 
-const normalizeSpecKey = (k) =>
-  String(k ?? "")
-    .toLowerCase()
-    .replace(/[\s_-]+/g, " ")
-    .trim();
-
-/**
- * useProductSpecs — `productSpecs` plus the lookup every page that features
- * specific specs needs, with the matching solved. **Never match spec rows by
- * `label` string equality** — a row's `label` is the admin's meta key verbatim
- * (`"light level"`, lowercase), so `specs.find(s => s.label === "Light")`
- * silently never matches and the feature renders its fallback forever. `get`
- * and `pick` here match case-, `_`- and `-`-insensitively.
- *
- *   const specs = useProductSpecs(product, { pick: ["light", "water", "humidity"] });
- *   specs.picked                 // the requested rows, in your order (missing ones skipped)
- *   specs.rest                   // everything else — safe to render as the remainder,
- *                                //   the picked rows are already excluded
- *   specs.get("light_level")     // one row or null
- *   specs.rows                   // all rows (== productSpecs(product))
- *
- * Rows carry `titleLabel` (display-cased) next to the verbatim `label`, and the
- * `type`/`number`/`unit`/`items` fields for type-driven rendering — see
- * `productSpecs`.
- *
- * @param {object|null} product tolerates null/loading — call above status guards
- * @param {{pick?: string[]}} [options]
- * @returns {{rows: Array<object>, picked: Array<object>, rest: Array<object>,
- *   get: (key: string) => object|null, has: (key: string) => boolean}}
- */
-export function useProductSpecs(product, { pick = [] } = {}) {
-  const pickKey = JSON.stringify(pick);
-  return useMemo(() => {
-    const rows = productSpecs(product);
-    const byKey = new Map(rows.map((r) => [normalizeSpecKey(r.key), r]));
-    const get = (key) => byKey.get(normalizeSpecKey(key)) ?? null;
-    const picked = pick.map(get).filter(Boolean);
-    const pickedSet = new Set(picked);
-    return {
-      rows,
-      picked,
-      rest: rows.filter((r) => !pickedSet.has(r)),
-      get,
-      has: (key) => byKey.has(normalizeSpecKey(key)),
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [product, pickKey]);
-}