@base44/app-plugin-commerce 0.1.20 → 0.2.1

package/src/commerce/storefront/useProduct.js

@@ -0,0 +1,227 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  defaultSelection,
+  resolveSelection,
+  selectOption,
+  selectionFromParams,
+  selectionToParams,
+  storefrontErrorCode,
+  storefrontErrorMessage,
+} from "@/commerce/utils";
+import { useCart, useStorefront } from "./StorefrontProvider";
+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
+ *
+ * It composes the variant helpers so their rules hold by default:
+ * `defaultSelection` seeds the merchant's defaults, `selectOption` applies a
+ * click without creating dead ends, `resolveSelection` recomputes the view, and
+ * `price` renders a *range* while the selection is incomplete instead of
+ * passing the parent's from-price off as the price.
+ *
+ * Three lifecycle facts a hand-written effect misses: **a missing product is
+ * `status: "not_found"`**, not a permanent spinner; a second `getProduct` in
+ * flight can never paint over a newer one; and the selection is mirrored to the
+ * URL (`?color=Ivory`) so a chosen variant is linkable and survives a reload.
+ *
+ * @param {string|{id: string}} ref slug or `{ id }`
+ * @param {{syncSelectionToUrl?: boolean, reviewsPerPage?: number,
+ *   initialSelection?: object}} [options]
+ */
+export function useProduct(ref, options = {}) {
+  const { syncSelectionToUrl = true, reviewsPerPage, initialSelection } = options;
+  const store = useStorefront();
+  const refKey = typeof ref === "string" ? ref : JSON.stringify(ref ?? null);
+
+  const { data, loading, error, reload } = useAsyncData(
+    () => store.getProduct(ref, reviewsPerPage ? { reviews_per_page: reviewsPerPage } : {}),
+    [store, refKey, reviewsPerPage],
+    { keepPreviousData: false },
+  );
+
+  const product = data?.product ?? null;
+  const variations = data?.variations ?? [];
+
+  // ── selection ──────────────────────────────────────────────────────────────
+  const [selection, setSelection] = useState(initialSelection ?? {});
+  const [touched, setTouched] = useState(false);
+
+  // Seed from the URL first (a shared link names a variant), then the
+  // merchant's defaults. Re-seeds when the product changes, never after a
+  // customer has started picking.
+  useEffect(() => {
+    if (!product || touched) return;
+    const fromUrl =
+      syncSelectionToUrl && typeof window !== "undefined"
+        ? selectionFromParams(product, variations, new URLSearchParams(window.location.search))
+        : null;
+    const seeded = { ...defaultSelection(product, variations), ...(fromUrl ?? {}) };
+    setSelection(initialSelection ?? seeded);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [product?.id]);
+
+  const view = useMemo(
+    () => (product ? resolveSelection(product, variations, selection) : null),
+    [product, variations, selection],
+  );
+
+  const pick = useCallback(
+    (axisKey, option) => {
+      if (!product) return;
+      setTouched(true);
+      setSelection((prev) => selectOption(product, variations, prev, axisKey, option));
+    },
+    [product, variations],
+  );
+  const resetSelection = useCallback(() => {
+    setTouched(false);
+    setSelection(product ? defaultSelection(product, variations) : {});
+  }, [product, variations]);
+
+  // Mirror the resolved selection into the URL without adding history entries.
+  useEffect(() => {
+    if (!syncSelectionToUrl || !product || typeof window === "undefined" || !touched) return;
+    const params = new URLSearchParams(window.location.search);
+    for (const [k, v] of Object.entries(selectionToParams(product, selection))) params.set(k, v);
+    const qs = params.toString();
+    window.history.replaceState(
+      window.history.state,
+      "",
+      `${window.location.pathname}${qs ? `?${qs}` : ""}${window.location.hash}`,
+    );
+  }, [syncSelectionToUrl, product, selection, touched]);
+
+  // ── quantity (respects sold_individually and the tracked stock) ─────────────
+  const [quantity, setQuantityState] = useState(1);
+  useEffect(() => setQuantityState(1), [product?.id, view?.variation?.id]);
+
+  const maxQuantity = useMemo(() => {
+    if (product?.sold_individually) return 1;
+    const stock = view?.display?.stock_quantity;
+    // Untracked stock (null) or backorders allowed means no ceiling to enforce.
+    if (stock == null || view?.display?.backorders !== "no") return Infinity;
+    return Math.max(1, stock);
+  }, [product?.sold_individually, view?.display?.stock_quantity, view?.display?.backorders]);
+
+  const setQuantity = useCallback(
+    (n) => setQuantityState(Math.max(1, Math.min(maxQuantity, Math.floor(Number(n) || 1)))),
+    [maxQuantity],
+  );
+  const incQuantity = useCallback(() => setQuantity(quantity + 1), [quantity, setQuantity]);
+  const decQuantity = useCallback(() => setQuantity(quantity - 1), [quantity, setQuantity]);
+
+  const price = useProductPrice(view);
+
+  const notFound = error?.code === "not_found";
+  const status = loading
+    ? "loading"
+    : notFound
+      ? "not_found"
+      : error
+        ? "error"
+        : product
+          ? "ready"
+          : "not_found";
+
+  return {
+    status,
+    loading,
+    error: notFound ? null : error,
+    notFound,
+    reload,
+    product,
+    variations,
+    categories: data?.categories ?? [],
+    ribbons: data?.ribbons ?? [],
+    upsells: data?.upsells ?? [],
+    crossSells: data?.cross_sells ?? [],
+    reviews: data?.reviews ?? null,
+    view,
+    selection,
+    pick,
+    setSelection,
+    resetSelection,
+    quantity,
+    setQuantity,
+    incQuantity,
+    decQuantity,
+    maxQuantity,
+    canIncrease: quantity < maxQuantity,
+    price,
+  };
+}
+
+/**
+ * useAddToCart — add-to-cart with its failure states handled.
+ *
+ *   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()`.
+ */
+export function useAddToCart() {
+  const { addItem } = useCart();
+  const [adding, setAdding] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastAdded, setLastAdded] = useState(null);
+
+  const add = useCallback(
+    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,
+        };
+        setError(err);
+        return { ok: false, error: err };
+      }
+      setAdding(true);
+      setError(null);
+      try {
+        const cart = await addItem(addToCartRef, quantity);
+        setLastAdded({ ...addToCartRef, quantity });
+        return { ok: true, cart };
+      } catch (e) {
+        const code = storefrontErrorCode(e) ?? "error";
+        const err = {
+          code,
+          message: storefrontErrorMessage(e),
+          shouldReload: code === "variation_not_found",
+        };
+        setError(err);
+        return { ok: false, error: err };
+      } finally {
+        setAdding(false);
+      }
+    },
+    [adding, addItem],
+  );
+
+  const reset = useCallback(() => {
+    setError(null);
+    setLastAdded(null);
+  }, []);
+
+  return { add, adding, error, lastAdded, reset };
+}

package/src/commerce/storefront/useProductGallery.js

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { imageIndex, productImages } from "@/commerce/utils";
+
+/**
+ * useProductGallery — the gallery's non-visual state: normalized images, the
+ * active index, and the variant-follows-selection behaviour.
+ *
+ *   const g = useProductGallery(product, view);
+ *   {g.hasImages
+ *     ? <img src={g.active.src} alt={g.active.alt} />
+ *     : <MyPlaceholder />}
+ *   {g.images.map((img, i) => <Thumb key={img.src} onClick={() => g.setActiveIndex(i)} …/>)}
+ *
+ * The aspect ratio, crossfade and thumbnail styling stay yours — only the state
+ * moves here, and with it three details worth having by default: images are
+ * normalized to `{src, name, alt}` (they are stored as objects, so a raw
+ * `images[0]` as `src` renders broken), `hasImages: false` is an explicit
+ * placeholder signal rather than a collapsed element, and **a selection change
+ * moves the active image to the variation's own picture while a manual pick
+ * still wins until the selection changes again** — highlight, not replace.
+ *
+ * @param {object} product
+ * @param {object|null} [view] a `resolveSelection` view; its
+ *   `display.image` is the variation's image
+ */
+export function useProductGallery(product, view = null) {
+  const images = useMemo(() => productImages(product), [product]);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const manualPick = useRef(false);
+
+  const variationImage = view?.display?.image ?? null;
+  const variationIndex = useMemo(() => imageIndex(images, variationImage), [images, variationImage]);
+  const selectionKey = JSON.stringify(view?.selection ?? {});
+
+  // A new product resets everything; a new selection re-arms the follow.
+  useEffect(() => {
+    manualPick.current = false;
+    setActiveIndex(0);
+  }, [product?.id]);
+
+  useEffect(() => {
+    manualPick.current = false;
+  }, [selectionKey]);
+
+  useEffect(() => {
+    if (manualPick.current || variationIndex < 0) return;
+    setActiveIndex(variationIndex);
+  }, [variationIndex]);
+
+  const select = useCallback(
+    (index) => {
+      manualPick.current = true;
+      setActiveIndex(Math.max(0, Math.min(images.length - 1, index)));
+    },
+    [images.length],
+  );
+  const next = useCallback(() => select((activeIndex + 1) % Math.max(1, images.length)), [activeIndex, images.length, select]);
+  const prev = useCallback(
+    () => select((activeIndex - 1 + Math.max(1, images.length)) % Math.max(1, images.length)),
+    [activeIndex, images.length, select],
+  );
+
+  const safeIndex = Math.min(activeIndex, Math.max(0, images.length - 1));
+  return {
+    images,
+    activeIndex: safeIndex,
+    setActiveIndex: select,
+    next,
+    prev,
+    active: images[safeIndex] ?? null,
+    hasImages: images.length > 0,
+    variationIndex,
+  };
+}

package/src/commerce/storefront/useProductList.js

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStorefront } from "./StorefrontProvider";
+import { useAsyncData } from "./internal/useAsyncData";
+
+/**
+ * useProductList — a catalog listing with its state solved: paging, filters,
+ * 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 })
+ *
+ * A short strip is the same hook with a small `per_page` — a featured rail, a
+ * "new in" row, four picks beside an article:
+ *
+ *   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.
+ *
+ * @param {object} [initialParams] `list-products` params (page/per_page and any filter)
+ * @param {{mode?: "pages"|"append", perPage?: number, keepPreviousData?: boolean}} [options]
+ *   `mode: "append"` accumulates pages for a "load more" / infinite-scroll
+ *   catalog; `loadMore()` is then the paging call.
+ */
+export function useProductList(initialParams = {}, options = {}) {
+  const { mode = "pages", perPage: perPageOption, keepPreviousData = true } = options;
+  const store = useStorefront();
+
+  const [params, setParamsState] = useState(() => ({
+    page: 1,
+    per_page: perPageOption ?? initialParams.per_page ?? 12,
+    ...initialParams,
+  }));
+  // In append mode the accumulated rows live here; `page` still drives fetching.
+  const [appended, setAppended] = useState([]);
+  const appendMode = mode === "append";
+  const paramsKey = JSON.stringify(params);
+  const lastFilterKey = useRef(null);
+
+  const { data, loading, refreshing, error, reload, reloadQuiet } = useAsyncData(
+    () => store.listProducts(params),
+    [store, paramsKey],
+    { keepPreviousData },
+  );
+
+  // In append mode `loadMore` accumulates the rows it already has; the only
+  // other thing to handle is a FILTER change (anything but the page), which must
+  // drop the accumulation — otherwise "load more" stacks unrelated result sets.
+  const { page: _page, ...filters } = params;
+  const filterKey = JSON.stringify(filters);
+  useEffect(() => {
+    if (!appendMode) return;
+    if (lastFilterKey.current === filterKey) return;
+    lastFilterKey.current = filterKey;
+    setAppended([]);
+  }, [appendMode, filterKey]);
+
+  const products = useMemo(() => {
+    const rows = data?.products ?? [];
+    if (!appendMode) return rows;
+    const byId = new Map();
+    for (const p of [...appended, ...rows]) byId.set(p.id, p);
+    return [...byId.values()];
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [appendMode, appended, data]);
+
+  /** Patch params; any change other than the page itself returns to page 1. */
+  const setParams = useCallback((patch) => {
+    setParamsState((prev) => {
+      const next = { ...prev, ...patch };
+      if (!("page" in patch)) next.page = 1;
+      return next;
+    });
+  }, []);
+  const resetParams = useCallback(() => {
+    setAppended([]);
+    setParamsState({ page: 1, per_page: perPageOption ?? initialParams.per_page ?? 12, ...initialParams });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [perPageOption]);
+
+  const goToPage = useCallback((page) => setParams({ page: Math.max(1, page) }), [setParams]);
+  const hasNext = Boolean(data?.has_next);
+  const next = useCallback(() => {
+    if (hasNext) setParamsState((p) => ({ ...p, page: (p.page ?? 1) + 1 }));
+  }, [hasNext]);
+  const prev = useCallback(() => {
+    setParamsState((p) => ({ ...p, page: Math.max(1, (p.page ?? 1) - 1) }));
+  }, []);
+  const loadMore = useCallback(() => {
+    if (!hasNext) return;
+    setAppended(products);
+    setParamsState((p) => ({ ...p, page: (p.page ?? 1) + 1 }));
+  }, [hasNext, products]);
+
+  const isEmpty = !loading && !error && products.length === 0;
+  const status = loading ? "loading" : error ? "error" : isEmpty ? "empty" : "ready";
+
+  return {
+    products,
+    page: data?.page ?? params.page ?? 1,
+    perPage: data?.per_page ?? params.per_page,
+    hasNext,
+    totalLoaded: products.length,
+    loading,
+    refreshing,
+    error,
+    isEmpty,
+    status,
+    params,
+    setParams,
+    resetParams,
+    next,
+    prev,
+    goToPage,
+    loadMore,
+    reload,
+    reloadQuiet,
+  };
+}
+
+/**
+ * The category tree — an ARRAY of root categories with subcategories nested
+ * under `children`. One cached call; use it for navigation and for the
+ * `category_id` filter on `useProductList`.
+ *
+ * @returns {{items: Array<object>, loading: boolean, error: object|null, reload: () => void}}
+ */
+export function useCategories() {
+  const store = useStorefront();
+  const { data, loading, error, reload } = useAsyncData(() => store.listCategories(), [store]);
+  return { items: data ?? [], loading, error, reload };
+}
+
+/**
+ * Ribbons — an ARRAY of `{ id, name, count }`. Labels like "Best Seller" for
+ * cards and the product page, and the `ribbon_id` filter's option list.
+ *
+ * @returns {{items: Array<object>, loading: boolean, error: object|null, reload: () => void}}
+ */
+export function useRibbons() {
+  const store = useStorefront();
+  const { data, loading, error, reload } = useAsyncData(() => store.listRibbons(), [store]);
+  return { items: data ?? [], loading, error, reload };
+}

package/src/commerce/storefront/useProductPrice.js

@@ -0,0 +1,58 @@
+import { useCallback, useMemo } from "react";
+import { productPrice } from "@/commerce/utils";
+import { useFormatMoney, useStoreInfo } from "./StorefrontProvider";
+
+/**
+ * Money formatting in the store's currency, with the pieces a custom price UI
+ * needs (parity with the admin's `useMoney`).
+ *
+ * @returns {{format: (n: number) => string, formatRange: (a: number, b: number) => string,
+ *   code: string|null, symbol: string, decimals: number}}
+ */
+export function useMoney() {
+  const format = useFormatMoney();
+  const { settings } = useStoreInfo();
+  const code = settings?.currency ?? null;
+  const formatRange = useCallback((min, max) => `${format(min)} – ${format(max)}`, [format]);
+  const symbol = useMemo(() => {
+    if (!code) return "";
+    try {
+      // The currency part of a formatted zero — locale-correct, no symbol table.
+      return new Intl.NumberFormat(undefined, { style: "currency", currency: code })
+        .formatToParts(0)
+        .find((p) => p.type === "currency")?.value ?? code;
+    } catch {
+      return code;
+    }
+  }, [code]);
+  const decimals = useMemo(() => {
+    if (!code) return 2;
+    try {
+      return new Intl.NumberFormat(undefined, { style: "currency", currency: code })
+        .resolvedOptions().maximumFractionDigits ?? 2;
+    } catch {
+      return 2;
+    }
+  }, [code]);
+
+  return { format, formatRange, code, symbol, decimals };
+}
+
+/**
+ * The rendered price of a product row **or** a resolved selection view, in the
+ * store's currency:
+ *
+ *   const price = useProductPrice(row);    // a card:         "From €19.99"
+ *   const price = useProductPrice(view);   // a product page: "€19.99 – €23.99"
+ *                                          //   until the selection resolves
+ *   <span>{price.label}</span>
+ *   {price.compareAtLabel && <s>{price.compareAtLabel}</s>}
+ *
+ * One call for both views is the point — the from-price rule cannot be honoured
+ * on the grid and forgotten on the product page. See `productPrice` for the
+ * rules themselves.
+ */
+export function useProductPrice(rowOrView) {
+  const formatMoney = useFormatMoney();
+  return useMemo(() => productPrice(rowOrView, { formatMoney }), [rowOrView, formatMoney]);
+}