@base44/app-plugin-commerce 0.2.7 → 0.3.1

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,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: