@base44/app-plugin-commerce 0.2.5 → 0.2.6

package/src/commerce/storefront/useCheckout.jsx

@@ -89,6 +89,12 @@ function resolvePaymentMethod(gateways, picked) {
  * `shipping_address_required`, `shipping_method_required`,
  * `shipping_not_available`, `payment_method_required`.
  *
+ * `stage` is `"editing" | "placing" | "submitted"` (`submitted` = the order was
+ * 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.
+ *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
  * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
  * `orderReceivedPath` ("/order-received"; null disables the navigation).
@@ -113,6 +119,7 @@ export function useCheckout(options = {}) {
   const [syncing, setSyncing] = useState(false);
   const [syncedKey, setSyncedKey] = useState(undefined);
   const [placing, setPlacing] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
   const [orderError, setOrderError] = useState(null);
 
   const updateBilling = useCallback((patch) => setBilling((b) => ({ ...b, ...patch })), []);
@@ -216,6 +223,10 @@ export function useCheckout(options = {}) {
           ...(shipToDifferent ? { shipping } : {}),
           ...extra, // 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
+        // order and a flash of "your bag is empty" while the browser navigates.
+        setSubmitted(true);
         clearCart(); // checkout consumed the cart
         if (
           redirectToPayment &&
@@ -280,6 +291,8 @@ export function useCheckout(options = {}) {
     blockers,
     canPlaceOrder,
     placing,
+    submitted,
+    stage: placing ? "placing" : submitted ? "submitted" : "editing",
     orderError,
     placeOrder,
     // underlying data, for convenience

package/src/commerce/storefront/useOrderReturn.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
-import { useStorefrontState } from "./StorefrontProvider";
+import { useFormatMoney, useStorefrontState } from "./StorefrontProvider";
 import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
@@ -19,9 +19,10 @@ 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, so the same
- * row markup renders the bag and the confirmation; totals come from
- * `useTotalsLines(order)`. The page is marked `noindex` automatically — a
+ * `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).
  *
  * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
@@ -32,6 +33,7 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  */
 export function useOrderReturn({ auto = true, seo = true } = {}) {
   const { client } = useStorefrontState();
+  const formatMoney = useFormatMoney();
   const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
 
   const reload = useCallback(
@@ -61,7 +63,7 @@ export function useOrderReturn({ auto = true, seo = true } = {}) {
 
   useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
 
-  return { ...result, lines: orderLines(result.order ?? null), reload };
+  return { ...result, lines: orderLines(result.order ?? null, { formatMoney }), reload };
 }
 
 /**

package/src/commerce/storefront/usePlaceOrder.js

@@ -0,0 +1,55 @@
+import { useCheckoutContext } from "./useCheckout";
+import { useCheckoutBlockers } from "./useTotalsLines";
+
+/**
+ * usePlaceOrder — the place-order gate as one spreadable surface. Needs a
+ * `<CheckoutProvider>` above it. The whole bottom of a checkout page:
+ *
+ *   const order = usePlaceOrder();
+ *   if (order.stage === "submitted") return <p>Order placed — taking you to your receipt…</p>;
+ *   …
+ *   <button {...order.buttonProps} className="…">{order.label}</button>
+ *   {order.error && <p {...order.errorProps} className="…">{order.error.message}</p>}
+ *   {!order.canPlaceOrder && order.blockers.map(b => <p key={b.code}>{b.message}</p>)}
+ *
+ * ⚑ **The `stage === "submitted"` guard goes above the page's empty-cart
+ * branch.** Placing an order clears the cart before the browser navigates
+ * away; without the guard the page flashes "your bag is empty" over a
+ * just-placed order. `stage` is `"editing" | "placing" | "submitted"`.
+ *
+ * `buttonProps` carries `onClick`, `disabled` (gate + in-flight) and
+ * `aria-busy`; `label` follows `placing` and is overridable via
+ * `labels: { idle, placing }`. `blockers` are the disabled button's reasons in
+ * words (`useCheckoutBlockers`), each with a `field` to anchor it next to the
+ * input that fixes it. Pass `blockerLabels` to override that copy per code.
+ *
+ * @param {{labels?: {idle?: string, placing?: string},
+ *   blockerLabels?: Record<string, string>}} [options]
+ * @returns {{buttonProps: object, label: string,
+ *   stage: "editing"|"placing"|"submitted", submitted: boolean,
+ *   placing: boolean, canPlaceOrder: boolean, error: object|null,
+ *   errorProps: object, blockers: Array<{code: string, message: string,
+ *   field: string|null}>, placeOrder: (extra?: object) => Promise<object>}}
+ */
+export function usePlaceOrder({ labels, blockerLabels } = {}) {
+  const checkout = useCheckoutContext();
+  const blockers = useCheckoutBlockers({ labels: blockerLabels });
+  const { canPlaceOrder, placing, submitted, stage, orderError, placeOrder } = checkout;
+  return {
+    buttonProps: {
+      type: "button",
+      onClick: () => placeOrder(),
+      disabled: !canPlaceOrder || placing,
+      "aria-busy": placing || undefined,
+    },
+    label: placing ? (labels?.placing ?? "Placing your order…") : (labels?.idle ?? "Place order"),
+    stage,
+    submitted,
+    placing,
+    canPlaceOrder,
+    error: orderError,
+    errorProps: { role: "alert" },
+    blockers,
+    placeOrder,
+  };
+}

package/src/commerce/storefront/useProduct.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   defaultSelection,
+  productSpecs,
   resolveSelection,
   selectOption,
   selectionFromParams,
@@ -9,6 +10,7 @@ import {
   storefrontErrorMessage,
 } from "@/commerce/utils";
 import { useCart, useStorefront } from "./StorefrontProvider";
+import { useCartUIOptional } from "./cartUI";
 import { useAsyncData } from "./internal/useAsyncData";
 import { useProductPrice } from "./useProductPrice";
 
@@ -226,49 +228,67 @@ 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:
  *
  *   const p = useProduct(slug);
- *   const buy = useAddToCartButton(p, { onAdded: () => navigate("/bag") });
- *   <button disabled={buy.disabled} onClick={buy.add}>
- *     {buy.adding ? "Adding…" : buy.soldOut ? "Sold out"
- *       : buy.needsSelection ? "Select options" : "Add to bag"}
- *   </button>
+ *   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>}
  *
+ * `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
+ * 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). Every label and every element is yours.
+ * 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}} [options]
+ * @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,
  *   quantity: number, setQuantity: (n: number) => void, increase: () => void,
  *   decrease: () => void, canIncrease: boolean, canDecrease: boolean,
  *   maxQuantity: number, showQuantity: boolean}}
  */
-export function useAddToCartButton(product, { onAdded } = {}) {
+export function useAddToCartButton(product, { onAdded, labels } = {}) {
   const { add, adding, error, reset } = useAddToCart();
+  const cartUI = useCartUIOptional();
   const view = product?.view ?? null;
 
   const submit = 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) onAdded?.(res.cart);
-    else if (res.error?.shouldReload) product.reload?.();
+    if (res.ok) {
+      cartUI?.onItemAdded?.();
+      onAdded?.(res.cart);
+    } else if (res.error?.shouldReload) product.reload?.();
     return res;
-  }, [add, view, product, onAdded]);
+  }, [add, view, product, onAdded, cartUI]);
 
   // A variable product with an incomplete selection isn't sold out — it needs
   // a pick; only a resolved (or simple) unpurchasable view reads as sold out.
@@ -277,16 +297,27 @@ export function useAddToCartButton(product, { onAdded } = {}) {
       ? view.complete && !view.purchasable
       : !view.purchasable
     : false;
+  const needsSelection = Boolean(view?.isVariable && !view.complete);
+  const state = adding ? "adding" : soldOut ? "sold_out" : needsSelection ? "needs_selection" : "ready";
+  const disabled = !view?.purchasable || adding;
 
   return {
     add: submit,
     adding,
     error,
     reset,
-    disabled: !view?.purchasable || adding,
+    disabled,
     soldOut,
-    needsSelection: Boolean(view?.isVariable && !view.complete),
+    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 ?? (() => {}),
@@ -297,3 +328,52 @@ export function useAddToCartButton(product, { onAdded } = {}) {
     showQuantity: (product?.maxQuantity ?? 1) > 1,
   };
 }
+
+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

@@ -9,6 +9,7 @@ import { useAsyncData } from "./internal/useAsyncData";
  *   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 })
+ *   <button {...list.moreProps} className="…">Load more</button>  // hides itself on the last page
  *
  * A short strip is the same hook with a small `per_page` — a featured rail, a
  * "new in" row, four picks beside an article:
@@ -104,7 +105,18 @@ export function useProductList(initialParams = {}, options = {}) {
   const isEmpty = !loading && !error && products.length === 0;
   const status = loading ? "loading" : error ? "error" : isEmpty ? "empty" : "ready";
 
+  // Spread on the "Load more" / "Next" button — it disables while a page is in
+  // flight and removes itself when there is no next page, so paging can't be
+  // silently dropped (`hasNext` unrendered = a catalog capped at one page).
+  const moreProps = {
+    type: "button",
+    onClick: appendMode ? loadMore : next,
+    disabled: loading || refreshing || !hasNext,
+    hidden: !hasNext,
+  };
+
   return {
+    moreProps,
     products,
     page: data?.page ?? params.page ?? 1,
     perPage: data?.per_page ?? params.per_page,

package/src/commerce/storefront/useUpsell.js

@@ -0,0 +1,90 @@
+import { useCallback } from "react";
+import { productImages } from "@/commerce/utils";
+import { useCart, useStorefront } from "./StorefrontProvider";
+import { useCartUIOptional } from "./cartUI";
+import { useAsyncData } from "./internal/useAsyncData";
+import { useAddToCart } from "./useProduct";
+import { useProductPrice } from "./useProductPrice";
+
+/**
+ * useUpsell — one product offered beside another surface (a cart drawer's
+ * "add the care kit", a checkout's "complete the set", a cross-sell strip
+ * entry), with the lifecycle solved:
+ *
+ *   const kit = useUpsell("care-kit");                    // slug or { id }…
+ *   const kit = useUpsell(p.crossSells[0]);               // …or a row you already have
+ *   {kit.show && (
+ *     <aside className="…">
+ *       {kit.image && <img src={kit.image.src} alt={kit.image.alt} className="…" />}
+ *       {kit.product.name} {kit.price.label}
+ *       <button type="button" onClick={kit.add} disabled={kit.adding}>Add</button>
+ *       {kit.error && <p role="alert">{kit.error.message}</p>}
+ *     </aside>
+ *   )}
+ *
+ * `show` is the one flag to branch on: it is false while loading, on a fetch
+ * failure, when the product is out of stock, and **when it is already in the
+ * cart** — matched by product id, never by display name (a rename must not
+ * break the match). Passing a row you already hold (`product.upsells` /
+ * `product.crossSells` from `useProduct`, or a `useProductList` row) skips the
+ * fetch entirely — prefer that when the row is on hand.
+ *
+ * `add()` never throws; a product with options can't be one-click added
+ * (`needsSelection` — link to its page instead). With `<CartUIProvider>`
+ * mounted, a successful add opens the drawer.
+ *
+ * @param {string|{id: string}|object} ref slug, `{ id }`, or a product row
+ * @param {{quantity?: number}} [options]
+ * @returns {{show: boolean, inCart: boolean, needsSelection: boolean,
+ *   product: object|null, image: {src: string, alt: string}|null,
+ *   price: object, add: () => Promise<object>, adding: boolean,
+ *   error: object|null}}
+ */
+export function useUpsell(ref, { quantity = 1 } = {}) {
+  const store = useStorefront();
+  const { cart } = useCart();
+  const cartUI = useCartUIOptional();
+
+  // A row (has id + name) is used as-is; a slug or { id } is fetched.
+  const isRow = Boolean(ref && typeof ref === "object" && ref.id && ref.name !== undefined);
+  const refKey = isRow ? `row:${ref.id}` : typeof ref === "string" ? ref : JSON.stringify(ref ?? null);
+
+  const { data, loading, error: fetchError } = useAsyncData(
+    () => (isRow || !ref ? Promise.resolve(null) : store.getProduct(ref)),
+    [store, refKey], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const product = isRow ? ref : (data?.product ?? null);
+  const needsSelection = isRow
+    ? (ref.attributes?.length ?? 0) > 0
+    : (data?.variations?.length ?? 0) > 0;
+
+  const price = useProductPrice(product);
+  const { add: rawAdd, adding, error, reset } = useAddToCart();
+
+  const add = useCallback(async () => {
+    if (!product) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };
+    if (needsSelection) {
+      return { ok: false, error: { code: "variation_required", message: "Choose an option first." } };
+    }
+    const res = await rawAdd({ product_id: product.id }, quantity);
+    if (res.ok) cartUI?.onItemAdded?.();
+    return res;
+  }, [product, needsSelection, rawAdd, quantity, cartUI]);
+
+  const inCart = Boolean(product) && (cart?.items ?? []).some((i) => i.product_id === product.id);
+  const busy = !isRow && Boolean(ref) && loading;
+
+  return {
+    show: !busy && !fetchError && Boolean(product) && !inCart && product?.stock_status !== "outofstock",
+    inCart,
+    needsSelection,
+    product,
+    image: productImages(product)[0] ?? null,
+    price,
+    add,
+    adding,
+    error,
+    reset,
+  };
+}

package/src/commerce/utils/specs.js

@@ -34,7 +34,7 @@
  * under the gallery, beside the price, or inside the description.
  *
  * @param {object} product
- * @returns {Array<{key: string, label: string, value: string,
+ * @returns {Array<{key: string, label: string, titleLabel: string, value: string,
  *   type: "numeric"|"duration"|"location"|"list"|"text",
  *   number: number|null, unit: string|null, items: string[]}>}
  *   `[]` when the product has no visible meta_data — render nothing, not an
@@ -49,7 +49,11 @@ export function productSpecs(product) {
     .map((m) => {
       const key = String(m.key);
       const value = String(m.value);
-      return { key, label: key.replace(/_/g, " "), value, ...classify(key, 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>.
+      const titleLabel = label.replace(/(^|\s)\p{Ll}/gu, (c) => c.toUpperCase());
+      return { key, label, titleLabel, value, ...classify(key, value) };
     });
 }
 

package/src/commerce/utils/totals.js

@@ -91,20 +91,31 @@ 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.
+ * 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).
  *
  * @param {object} order
+ * @param {{formatMoney?: (n: number) => string}} [opts]
  * @returns {Array<{name: string, attributesLabel: string, quantity: number,
- *   total: number, image: object|null, sku: string}>}
+ *   total: number, totalLabel: string, image: {src: string, alt: string}|null,
+ *   sku: string}>}
  */
-export function orderLines(order) {
-  return (order?.line_items ?? []).map((it) => ({
-    ...it,
-    name: it.name ?? "",
-    attributesLabel: attributesLabel(it.attributes ?? it.meta_data),
-    quantity: num(it.quantity),
-    total: num(it.total ?? it.subtotal),
-    image: it.image ?? null,
-    sku: it.sku ?? "",
-  }));
+export function orderLines(order, { formatMoney } = {}) {
+  return (order?.line_items ?? []).map((it) => {
+    const total = num(it.total ?? it.subtotal);
+    // An order item's image may be stored as a bare URL or an object — either
+    // way it leaves here as {src, alt}|null, the cart-line shape.
+    const src = typeof it.image === "string" ? it.image : it.image?.src;
+    return {
+      ...it,
+      name: it.name ?? "",
+      attributesLabel: attributesLabel(it.attributes ?? it.meta_data),
+      quantity: num(it.quantity),
+      total,
+      totalLabel: money(formatMoney, total),
+      image: src ? { src, alt: (typeof it.image === "object" ? it.image?.alt : "") || it.name || "" } : null,
+      sku: it.sku ?? "",
+    };
+  });
 }