@base44/app-plugin-commerce 0.2.5 → 0.2.7

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";
 
@@ -161,24 +163,18 @@ export function useProduct(ref, options = {}) {
 }
 
 /**
- * useAddToCart — add-to-cart with its failure states handled.
+ * useAddItem — 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()`.
  *
- *   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.
- *
- * `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.
  */
-export function useAddToCart() {
+export function useAddItem() {
   const { addItem } = useCart();
   const [adding, setAdding] = useState(false);
   const [error, setError] = useState(null);
@@ -226,49 +222,70 @@ 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 and attribute of the markup is yours. 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"}
+ *   const buy = useAddToCart(p, { labels: { ready: "Add to bag" } });
+ *   <button type="button" onClick={buy.addToCart} disabled={buy.disabled} className="…">
+ *     {buy.label}
  *   </button>
  *   {buy.error && <p role="alert">{buy.error.message}</p>}
  *
- * 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.
+ * `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.
+ * 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).
  *
  * 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]
- * @returns {{add: () => Promise<object>, adding: boolean, error: object|null,
- *   reset: () => void, disabled: boolean, soldOut: boolean,
- *   needsSelection: boolean, purchasable: boolean,
+ * @param {{onAdded?: (cart: object) => void,
+ *   labels?: {ready?: string, adding?: string, sold_out?: string,
+ *   needs_selection?: string}}} [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,
  *   quantity: number, setQuantity: (n: number) => void, increase: () => void,
  *   decrease: () => void, canIncrease: boolean, canDecrease: boolean,
  *   maxQuantity: number, showQuantity: boolean}}
  */
-export function useAddToCartButton(product, { onAdded } = {}) {
-  const { add, adding, error, reset } = useAddToCart();
+export function useAddToCart(product, { onAdded, labels } = {}) {
+  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) 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 +294,21 @@ 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,
+    addToCart,
     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],
     quantity: product?.quantity ?? 1,
     setQuantity: product?.setQuantity ?? (() => {}),
     increase: product?.incQuantity ?? (() => {}),
@@ -297,3 +319,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,12 @@ 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 })
+ *   {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.
  *
  * A short strip is the same hook with a small `per_page` — a featured rail, a
  * "new in" row, four picks beside an article:
@@ -112,6 +118,7 @@ export function useProductList(initialParams = {}, options = {}) {
     totalLoaded: products.length,
     loading,
     refreshing,
+    busy: loading || refreshing,
     error,
     isEmpty,
     status,

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 { useAddItem } 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 } = useAddItem();
+
+  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 ?? "",
+    };
+  });
 }