@base44/app-plugin-commerce 0.2.6 → 0.2.7

package/src/commerce/storefront/useProduct.js

@@ -163,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);
@@ -236,27 +230,31 @@ const BUY_LABELS = {
 };
 
 /**
- * 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, { labels: { ready: "Add to bag" } });
- *   <button {...buy.buttonProps} className="…">{buy.label}</button>
+ *   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>}
  *
  * `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
+ * (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 wires so a hand-written buy box can't drop it: the button is gated on
- * `view.purchasable`; a rejected add (sold out, stale variant) lands in `error`
- * instead of leaving the button stuck on "Adding…"; a stale-variant rejection
- * reloads the product; and the quantity controls respect `sold_individually`
- * and tracked stock (`showQuantity` is false when only 1 can be bought — render
- * no stepper then).
+ * What it solves so a hand-written buy box can't drop it: `addToCart()` never
+ * throws — a rejected add (sold out, stale variant) lands in `error` instead
+ * of leaving the button stuck 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
@@ -266,21 +264,20 @@ const BUY_LABELS = {
  * @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,
+ * @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,
- *   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, labels } = {}) {
-  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) {
@@ -302,7 +299,7 @@ export function useAddToCartButton(product, { onAdded, labels } = {}) {
   const disabled = !view?.purchasable || adding;
 
   return {
-    add: submit,
+    addToCart,
     adding,
     error,
     reset,
@@ -312,12 +309,6 @@ export function useAddToCartButton(product, { onAdded, labels } = {}) {
     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 ?? (() => {}),

package/src/commerce/storefront/useProductList.js

@@ -9,7 +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 })
- *   <button {...list.moreProps} className="…">Load more</button>  // hides itself on the last page
+ *   {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:
@@ -105,18 +110,7 @@ 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,
@@ -124,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

@@ -3,7 +3,7 @@ import { productImages } from "@/commerce/utils";
 import { useCart, useStorefront } from "./StorefrontProvider";
 import { useCartUIOptional } from "./cartUI";
 import { useAsyncData } from "./internal/useAsyncData";
-import { useAddToCart } from "./useProduct";
+import { useAddItem } from "./useProduct";
 import { useProductPrice } from "./useProductPrice";
 
 /**
@@ -60,7 +60,7 @@ export function useUpsell(ref, { quantity = 1 } = {}) {
     : (data?.variations?.length ?? 0) > 0;
 
   const price = useProductPrice(product);
-  const { add: rawAdd, adding, error, reset } = useAddToCart();
+  const { add: rawAdd, adding, error, reset } = useAddItem();
 
   const add = useCallback(async () => {
     if (!product) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };