@base44/app-plugin-commerce 0.2.7 → 0.3.2

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,18 +161,21 @@ export function useProduct(ref, options = {}) {
 }
 
 /**
- * useAddItem — internal: the raw add-to-cart call with its failure states
- * handled. `add(addToCartRef, quantity)` **never throws** and always resolves —
+ * 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 on "Adding…" 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()`.
+ * 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()`.
  *
- * Pages use `useAddToCart(product)` below; this is the shared plumbing it and
- * `useUpsell` build on.
+ * `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.
+ *
+ * Pages use `useAddToCart(product)` below.
  */
-export function useAddItem() {
+function useAddItem() {
   const { addItem } = useCart();
   const [adding, setAdding] = useState(false);
   const [error, setError] = useState(null);
@@ -184,11 +185,7 @@ export function useAddItem() {
     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 };
       }
@@ -222,57 +219,53 @@ export function useAddItem() {
   return { add, adding, error, lastAdded, reset };
 }
 
-const BUY_LABELS = {
-  ready: "Add to bag",
-  adding: "Adding…",
-  sold_out: "Sold out",
-  needs_selection: "Select options",
-};
-
 /**
  * useAddToCart — the buy box's whole state machine as plain states and
- * handlers; every element and attribute of the markup is yours. Pass the
- * entire `useProduct` result:
+ * 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 = useAddToCart(p, { labels: { ready: "Add to bag" } });
+ *   const buy = useAddToCart(p);
  *   <button type="button" onClick={buy.addToCart} disabled={buy.disabled} className="…">
- *     {buy.label}
+ *     {BUY[buy.state]}
  *   </button>
- *   {buy.error && <p role="alert">{buy.error.message}</p>}
+ *   {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). ⚑ Render
- * `{buy.label}` as the button's text and gate it with `disabled={buy.disabled}`
- * — a button without both shows nothing or stays clickable while sold out.
+ * 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 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 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).
+ * 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]
+ * @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", label: string,
+ *   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 useAddToCart(product, { onAdded, labels } = {}) {
+export function useAddToCart(product, { onAdded } = {}) {
   const { add, adding, error, reset } = useAddItem();
   const cartUI = useCartUIOptional();
   const view = product?.view ?? null;
@@ -308,7 +301,6 @@ export function useAddToCart(product, { onAdded, labels } = {}) {
     needsSelection,
     purchasable: Boolean(view?.purchasable),
     state,
-    label: labels?.[state] ?? BUY_LABELS[state],
     quantity: product?.quantity ?? 1,
     setQuantity: product?.setQuantity ?? (() => {}),
     increase: product?.incQuantity ?? (() => {}),
@@ -320,51 +312,3 @@ export function useAddToCart(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]);
-}

package/src/commerce/storefront/useProductList.js

@@ -7,30 +7,22 @@ import { useAsyncData } from "./internal/useAsyncData";
  * loading vs refreshing, and failure as a visible state.
  *
  *   const list = useProductList({ per_page: 12, sort: "-created_date" });
- *   // list.status: "loading" | "ready" | "empty" | "error"
- *   // list.products, list.hasNext, list.next(), list.setParams({ category_id })
- *   {list.hasNext && (
- *     <button type="button" onClick={list.next} disabled={list.busy} className="…">Next</button>
- *   )}
- *   // append mode: onClick={list.loadMore} — same hasNext gate. ⚑ Render the
- *   // paging control whenever `hasNext` is true, or the catalog is silently
- *   // capped at one page.
+ *   // status: "loading" | "ready" | "empty" | "error"
+ *   // products, hasNext, next(), loadMore(), busy, setParams({ category_id })
  *
- * A short strip is the same hook with a small `per_page` — a featured rail, a
- * "new in" row, four picks beside an article:
+ * A short strip is the same hook with a small `per_page` — a featured rail, four
+ * picks beside an article: `useProductList({ featured: true, per_page: 4 })`.
  *
- *   const featured = useProductList({ featured: true, per_page: 4 });
- *
- * What it fixes versus a hand-written fetch effect: `has_next` is honoured (so
- * the catalog isn't silently capped at one page), a failed request renders as
- * `status: "error"` instead of an empty grid, `isEmpty` is never true while
- * loading, changing a filter resets to page 1 and keeps the current rows on
- * screen while the new page loads, and the whole server-side filter surface
- * (`search`, `category_id`, `ribbon_id`, `featured`, `on_sale`, `min_price`,
- * `max_price`, `in_stock_only`, `sort`) is reachable through `setParams`.
- *
- * Any filter may legitimately match nothing — render from
- * `products.length`/`isEmpty`, never on the assumption that rows came back.
+ * ⚑ **Render a paging control whenever `hasNext` is true**, or the catalog is
+ * silently capped at one page (`next()` for pages, `loadMore()` in append mode).
+ * The rest of what it fixes versus a hand-written fetch effect: a failed request
+ * is `status: "error"`, not an empty grid; `isEmpty` is never true while loading;
+ * a filter change resets to page 1 and keeps the current rows on screen while
+ * the new page loads; and the whole server-side filter surface (`search`,
+ * `category_id`, `ribbon_id`, `featured`, `on_sale`, `min_price`, `max_price`,
+ * `in_stock_only`, `sort`) is reachable through `setParams`. Any filter may
+ * legitimately match nothing — render from `isEmpty`, never on the assumption
+ * that rows came back.
  *
  * @param {object} [initialParams] `list-products` params (page/per_page and any filter)
  * @param {{mode?: "pages"|"append", perPage?: number, keepPreviousData?: boolean}} [options]

package/src/commerce/utils/address-spec.js

@@ -1,5 +1,5 @@
 /**
- * The address form, as data. Framework-free; `useAddressForm` binds it to the
+ * The address form, as data. Framework-free; bind it to the
  * checkout and the store's country list.
  *
  * Why a spec instead of markup: a hand-typed field table drifts from what the

package/src/commerce/utils/images.js

@@ -1,5 +1,5 @@
 /**
- * Product images, normalized. Framework-free; `useProductGallery` adds the
+ * Product images, normalized. Framework-free; a gallery adds the
  * gallery's index state on top.
  *
  * Every stored image is an **object** — `{ src, name, alt }` — never a URL

package/src/commerce/utils/index.js

@@ -25,16 +25,16 @@
  * - `address-spec.js` — `addressFieldSpec`: the checkout address form as data,
  *   with country/state options that are always arrays.
  * - `images.js` — `productImages`: images normalized to `{src, name, alt}`.
- * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows with an inferred
- *   `type` (numeric/duration/location/list/text), so each can be rendered as
- *   what it is rather than as another label/value row.
+ * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows (`key`, `label`,
+ *   `titleLabel`, `value`). Match rows by `key`, never by `label`.
  *
- * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
- * layers headless hooks on top of this module, and a hook that pre-composes
- * these helpers is the difference between a rule that holds and a rule you
- * have to remember. Neither layer ships any UI: all markup and styling belong
- * to the storefront you build. Use this module directly for non-React code,
- * and inside your own custom logic.
+ * Building the storefront in React? Import from **`@/commerce/storefront`** and
+ * nothing else — it adds the headless hooks and re-exports the helpers a page
+ * actually needs (`variantAxes`, `productPrice`, `productImages`,
+ * `productSpecs`, `attributesLabel`, `cartTotalsLines`, `orderTotalsLines`), so
+ * one import line covers a page. Neither layer ships any UI: all markup,
+ * styling and copy belong to the storefront you build. Use this module directly
+ * for non-React code and inside your own custom logic.
  */
 export * from "./storefront.js";
 export * from "./variants.js";

package/src/commerce/utils/price.js

@@ -1,6 +1,7 @@
 /**
  * Price presentation — the one place the store's pricing *rules* turn into
- * strings. Framework-free; `useProductPrice` binds it to the store currency.
+ * strings. Framework-free; pass `formatMoney` from `useFormatMoney()` to bind it to
+ * the store's currency.
  *
  * Two rules live here, and both are easy to get wrong in one view while
  * getting them right in another:

package/src/commerce/utils/specs.js

@@ -6,42 +6,29 @@
  * **not** attributes and not ribbons: they describe the product, they don't
  * select a variant. Hidden keys (leading `_`) and empty values are skipped.
  *
- * Each row carries a `type` — inferred from the value (and, for `"location"`,
- * the key) — so the rendering decision is already made for you. **A `.map()`
- * into one uniform label/value table is the fallback, not the target:** the
- * types exist because a carat weight and a care instruction are not the same
- * kind of fact and should not look alike.
- *
  * ```jsx
- * // ❌ every product in every store, identical: one grey table
- * <dl>{productSpecs(product).map((s) => (
- *   <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>))}</dl>
- *
- * // ✅ branch on type — the figures read as figures, the rest stays a row
- * {productSpecs(product).map((s) =>
- *   s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />
- * : s.type === "location" ? <Sourced key={s.key} place={s.value} />          // a located line, a pin
- * : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />          // composition, materials
- * : s.type === "duration" ? <Lead    key={s.key} label={s.label} value={s.value} />
- * :                         <Row     key={s.key} label={s.label} value={s.value} />)}
+ * const specs = productSpecs(product);
+ * const care = findSpec(specs, "care");   // not specs.find(s => s.label === "Care")
  * ```
  *
- * Design the two or three that carry *this* product's meaning (a weight set in
- * the display face, a provenance beside a map, a composition as bars) and let
- * the remainder fall through to the plain row. `key` is still there too, for
- * when one particular modifier of this catalog deserves its own treatment
- * regardless of type. And the rows need not sit in one block — a spec can go
- * under the gallery, beside the price, or inside the description.
+ * **Look rows up with `findSpec`, never by matching `label`.** Meta keys are
+ * free text typed by whoever set the product up, so the same fact is `care`,
+ * `Care`, `care_instructions` or `Care Instructions` across two catalogs — an
+ * equality test on `label` silently never matches and the feature renders its
+ * fallback forever (observed in a live store). `titleLabel` is the display-cased
+ * form, for when you do want to print the key as a heading.
+ *
+ * A `.map()` into one uniform label/value table is the fallback, not the
+ * target: a carat weight and a care instruction are not the same kind of fact
+ * and need not look alike. Which two or three of *this* catalog's modifiers
+ * carry meaning — and how each is rendered — is a design decision about this
+ * store, made from its own data. The rows need not sit in one block either: a
+ * spec can go under the gallery, beside the price, or inside the description.
  *
  * @param {object} product
- * @returns {Array<{key: string, label: string, titleLabel: string, value: string,
- *   type: "numeric"|"duration"|"location"|"list"|"text",
- *   number: number|null, unit: string|null, items: string[]}>}
+ * @returns {Array<{key: string, label: string, titleLabel: string, value: string}>}
  *   `[]` when the product has no visible meta_data — render nothing, not an
- *   empty section. `number`/`unit` are set for `numeric` and `duration`
- *   (`unit` is `""` for a bare number), `items` for `list`, and are
- *   `null`/`[]` otherwise. `value` is always the store's own text, unchanged —
- *   the extra fields are there to render *with*, never a replacement for it.
+ *   empty section. `value` is always the store's own text, unchanged.
  */
 export function productSpecs(product) {
   return (product?.meta_data ?? [])
@@ -50,70 +37,33 @@ export function productSpecs(product) {
       const key = String(m.key);
       const value = String(m.value);
       const label = key.replace(/_/g, " ");
-      // `label` is the admin's key verbatim ("light level"); `titleLabel` is
-      // the display-cased form ("Light Level") — no store wants a lowercase <dt>.
+      // `label` is the key with underscores opened up, in whatever case it was
+      // typed; `titleLabel` is the display-cased form, for printing as a <dt>.
       const titleLabel = label.replace(/(^|\s)\p{Ll}/gu, (c) => c.toUpperCase());
-      return { key, label, titleLabel, value, ...classify(key, value) };
+      return { key, label, titleLabel, value };
     });
 }
 
-const LOCATION_KEY =
-  /(origin|provenance|made[\s_-]?in|country|region|sourced|source|location|city|terroir|appellation|distillery|winery|atelier|workshop)/i;
-
-const DURATION_UNIT =
-  /^(sec|secs|second|seconds|min|mins|minute|minutes|hr|hrs|hour|hours|day|days|week|weeks|month|months|year|years|yr|yrs)$/i;
-
-/** Infer the render-relevant shape of one spec value. Never throws. */
-function classify(key, raw) {
-  const value = raw.trim();
-  const plain = { type: "text", number: null, unit: null, items: [] };
-
-  if (LOCATION_KEY.test(key)) return { ...plain, type: "location" };
-
-  const qty = parseQuantity(value);
-  if (qty) {
-    const type = DURATION_UNIT.test(qty.unit) ? "duration" : "numeric";
-    return { ...plain, type, number: qty.number, unit: qty.unit };
-  }
-
-  const items = parseList(value);
-  if (items) return { ...plain, type: "list", items };
-
-  return plain;
-}
-
-/** "0.75 ct" → {number: 0.75, unit: "ct"}; "18" → {number: 18, unit: ""}. */
-function parseQuantity(value) {
-  const m = /^([-+]?[\d.,]+)\s*(.*)$/.exec(value);
-  if (!m) return null;
-  const number = toNumber(m[1]);
-  if (number === null) return null;
-  const unit = m[2].trim();
-  // A unit is a word or two of symbols/letters. Anything longer is prose that
-  // happens to start with a number ("2 pieces, hand-cut in the studio").
-  if (unit && (!/^[\p{L}%°µ"'/²³.\- ]{1,12}$/u.test(unit) || unit.split(/\s+/).length > 2)) return null;
-  return { number, unit };
-}
-
-/** Grouped thousands are separators; a lone comma between digits is a decimal. */
-function toNumber(raw) {
-  let s = raw.replace(/\s/g, "");
-  if (/^[-+]?\d{1,3}(,\d{3})+(\.\d+)?$/.test(s)) s = s.replace(/,/g, "");
-  else if (/^[-+]?\d+,\d+$/.test(s)) s = s.replace(",", ".");
-  else if (s.includes(",")) return null;
-  const n = Number(s);
-  return Number.isFinite(n) ? n : null;
+/**
+ * Find one spec row by key, tolerantly: case, spaces, `_` and `-` are all
+ * ignored, so `findSpec(rows, "care_instructions")` matches a row the merchant
+ * typed as `Care Instructions`. Returns the row or `null`.
+ *
+ * This is the lookup to use whenever a page features *particular* specs (a
+ * weight rendered as a figure, a provenance beside its place), because meta
+ * keys are free text and an exact match on one spelling is a silent miss.
+ *
+ * @param {Array<{key: string}>} rows from `productSpecs(product)`
+ * @param {string} key the key you mean, in any spelling
+ */
+export function findSpec(rows, key) {
+  const want = normalizeSpecKey(key);
+  if (!want) return null;
+  return (rows ?? []).find((r) => normalizeSpecKey(r?.key) === want) ?? null;
 }
 
-/** "70% wool / 30% cashmere" → ["70% wool", "30% cashmere"]. */
-function parseList(value) {
-  const parts = value
-    .split(/\s*[,;|·•/]\s*/)
-    .map((p) => p.trim())
-    .filter(Boolean);
-  if (parts.length < 2) return null;
-  // Short fragments with words in them — not a sentence that happens to have commas.
-  if (parts.some((p) => p.length > 24 || p.split(/\s+/).length > 3 || /[.!?]/.test(p))) return null;
-  if (!parts.some((p) => /\p{L}/u.test(p))) return null;
-  return parts;
-}
+const normalizeSpecKey = (k) =>
+  String(k ?? "")
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "")
+    .trim();

package/src/commerce/utils/totals.js

@@ -90,10 +90,13 @@ export function orderTotalsLines(order, { formatMoney, labels = {} } = {}) {
 }
 
 /**
- * An order's line items in the same shape as decorated cart lines, so one
- * component renders the bag, the checkout summary and the confirmation —
- * `image` is `{src, alt}|null` and `totalLabel` is pre-formatted, exactly as
- * on `useCart().lines` (pass `formatMoney`; `useOrderReturn` does).
+ * An order's line items, pre-chewed for rendering so one component can serve
+ * the bag, the checkout summary and the confirmation — `image` is
+ * `{src, alt}|null` and `totalLabel` is pre-formatted, sparing a receipt the
+ * two traps of a raw `line_items` entry (an image stored as an object, money
+ * as a number). A cart row is the same shape once you derive it from
+ * `cart.items[n]` yourself — `attributesLabel(item.attributes)` and
+ * `formatMoney(item.total)`. Pass `formatMoney`; `useOrderReturn` does.
  *
  * @param {object} order
  * @param {{formatMoney?: (n: number) => string}} [opts]