@base44/app-plugin-commerce 0.1.20 → 0.2.1

package/src/commerce/storefront/blocks/index.js

@@ -0,0 +1,44 @@
+/**
+ * Storefront blocks — working default markup for the parts of a shopfront that
+ * are the same in every store.
+ *
+ * The split is deliberate:
+ *
+ * - **Identity surfaces are yours**: home, collection/grid, the product page's
+ *   layout, the product card, the theme. That is where "make it look like X"
+ *   lives, and no markup ships for it.
+ * - **Commodity surfaces ship as blocks**: checkout, cart lines, totals, the
+ *   coupon field, reviews, order-received, and the product page's internals
+ *   (variant selector, gallery, specs, breadcrumbs, strips). Every store's
+ *   version of these is functionally identical, and hand-writing them is where
+ *   storefront bugs cluster.
+ *
+ * Blocks are thin compositions of the hooks in this package, styled by
+ * inheritance: semantic markup, theme tokens (`border-border`, `text-muted-
+ * foreground`, `bg-primary`), and a stable `data-commerce="…"` attribute on
+ * every meaningful element — so your CSS can restyle any part of them, and
+ * tests can target them. Each takes `className` and, where there is more than
+ * one region, `slots`. When a design needs different *structure*, drop to the
+ * hooks the block uses and rewrite that one region.
+ *
+ * A whole checkout page:
+ *
+ *   import { CheckoutBlock } from "@/commerce/storefront";
+ *   export default function Checkout() {
+ *     return <main className="mx-auto max-w-3xl px-6 py-16"><CheckoutBlock /></main>;
+ *   }
+ */
+export { CartLinesBlock } from "./CartLinesBlock";
+export { CheckoutBlock } from "./CheckoutBlock";
+export { AddressFieldsBlock } from "./AddressFieldsBlock";
+export { CouponFieldBlock } from "./CouponFieldBlock";
+export { TotalsBlock } from "./TotalsBlock";
+export { QuantityStepper } from "./QuantityStepper";
+export { OrderReceivedBlock } from "./OrderReceivedBlock";
+export { ReviewsBlock } from "./ReviewsBlock";
+export { VariantSelectorBlock } from "./VariantSelectorBlock";
+export { AddToCartBlock } from "./AddToCartBlock";
+export { ProductGalleryBlock } from "./ProductGalleryBlock";
+export { ProductSpecsBlock } from "./ProductSpecsBlock";
+export { BreadcrumbsBlock } from "./BreadcrumbsBlock";
+export { ProductStripBlock } from "./ProductStripBlock";

package/src/commerce/storefront/index.js

@@ -1,10 +1,15 @@
 /**
- * Storefront React layer — hooks + headless helpers for the cart, checkout
- * and order-received parts of the shopfront you build. Ships with the Base44
- * Commerce Template next to the framework-free `@/commerce/utils` (which it
- * builds on); needs React and nothing else. NO visual components ship here —
- * every pixel stays yours. The hooks own the contracts that are easy to get
- * subtly wrong; you own the markup.
+ * Storefront React layer — hooks and ready-made blocks for the shopfront you
+ * build. Ships with the Base44 Commerce Template next to the framework-free
+ * `@/commerce/utils` (which it builds on); needs React and nothing else.
+ *
+ * **Two tiers.** The *identity* surfaces are yours to design — home, the
+ * collection grid, the product page's layout, the product card, the theme. The
+ * *commodity* surfaces ship as working blocks that inherit your theme —
+ * checkout, cart lines, totals, coupon field, reviews, order-received, and the
+ * product page's internals. Restyle or replace them; never hand-roll their
+ * logic. Blocks are compositions of the hooks below, so outgrowing one means
+ * rewriting a single region against an API you already know.
  *
  * Setup (once, above every storefront route — it wraps <Routes>; placed as a
  * child of <Routes> React Router throws "is not a <Route> component"):
@@ -13,25 +18,40 @@
  *   import { base44 } from "@/api/base44Client";
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * - `StorefrontProvider` / `useStorefront` / `useStoreInfo` / `useFormatMoney`
- *     — one client, cached store info (the ONLY source of payment gateways,
- *     currency, countries), money formatting in the store's currency.
- * - `useCart` — the shared cart: state + every mutation, serialized so
- *     responses never apply out of order; a header badge, a cart drawer and
- *     the checkout all see the same view.
+ * ## Blocks (drop in, then restyle)
+ * `CheckoutBlock` · `CartLinesBlock` · `TotalsBlock` · `CouponFieldBlock` ·
+ * `QuantityStepper` · `OrderReceivedBlock` · `ReviewsBlock` ·
+ * `AddressFieldsBlock` · `VariantSelectorBlock` · `AddToCartBlock` ·
+ * `ProductGalleryBlock` · `ProductSpecsBlock` · `BreadcrumbsBlock` ·
+ * `ProductStripBlock` (needs your `renderCard` — no default card ships).
+ *
+ * ## Hooks
+ * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
+ *     shared client, cached store info (the ONLY source of payment gateways,
+ *     currency and countries), money in the store's currency.
+ * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
+ *     filters, `refreshing`, and failure as a visible state.
+ * - `useProduct` / `useAddToCart` / `useProductPrice` / `useProductGallery` —
+ *     the product page: fetch + variant selection + quantity + price + gallery,
+ *     race-safe, with `status: "not_found"` and add-to-cart errors handled.
+ * - `useProductReviews` — the review list and the submit form, with the store's
+ *     policy as a prop.
+ * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
+ *     `status`, render `lines` and `notices`), quantity steppers that clamp and
+ *     recover, and the coupon field a store with coupons must have.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
- *     checkout: address form state with automatic debounced shipping/tax
- *     recalculation once the address is complete, shipping-method choice,
- *     payment-method choice, a `canPlaceOrder` gate with named blockers, and
- *     `placeOrder` with the online-payment redirect handled.
+ *     checkout: address state with automatic debounced shipping/tax
+ *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
+ *     named blockers, `placeOrder` with the online-payment redirect handled.
+ * - `useAddressForm` / `useCountries` / `useTotalsLines` /
+ *     `useCheckoutBlockers` — the address form as fields (state included,
+ *     country options never null), one totals projection for cart and order,
+ *     and blocker codes turned into copy.
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — headless (render-prop)
  *     wrappers over the two choices that are store data, never hardcoded.
  * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
- * - `address.js` — framework-free address-completeness rules (also exported).
- *
- * Catalog calls (product list, product page) intentionally stay thin — use
- * `useStorefront()` for the client plus the variant helpers from
- * `@/commerce/utils`; those views are where the design freedom lives.
+ * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
+ *     meta and product structured data; receipts are `noindex`.
  */
 export {
   StorefrontProvider,
@@ -50,3 +70,21 @@ export {
   shippingSlice,
   isShippingAddressComplete,
 } from "./address";
+
+// ── catalog ────────────────────────────────────────────────────────────────
+export { useProductList, useCategories, useRibbons } from "./useProductList";
+export { useProduct, useAddToCart } from "./useProduct";
+export { useProductPrice, useMoney } from "./useProductPrice";
+export { useProductGallery } from "./useProductGallery";
+export { useProductReviews } from "./useProductReviews";
+
+// ── cart & checkout ────────────────────────────────────────────────────────
+export { useCartLine, useCoupon } from "./useCartLine";
+export { useAddressForm, useCountries } from "./useAddressForm";
+export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotalsLines";
+
+// ── SEO ────────────────────────────────────────────────────────────────────
+export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
+
+// ── blocks (default markup for the commodity surfaces) ─────────────────────
+export * from "./blocks";

package/src/commerce/storefront/internal/useAsyncData.js

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+
+/**
+ * Internal async primitive for the storefront hooks — the storefront twin of
+ * the admin's `useAsync`/`usePagedList`. Not exported from the package: it
+ * exists so every catalog hook gets the same three properties for free, each
+ * of which a hand-written `useEffect` reliably misses:
+ *
+ * - **Race-safety.** Only the newest request may publish. Two `getProduct`
+ *   calls in flight (the customer clicked a second product) can otherwise
+ *   resolve out of order and paint the wrong page.
+ * - **`loading` vs `refreshing`.** First load is `loading`; a reload caused by
+ *   changed params is `refreshing` with the previous data still on screen, so
+ *   a filter change doesn't flash an empty grid.
+ * - **Failure is a state, not a silence.** An error sets `error` and (with
+ *   `keepPreviousData`) leaves the last good data in place — the common
+ *   hand-rolled shape, `.finally(() => setLoading(false))`, renders a failed
+ *   fetch as a legitimately empty result.
+ *
+ * @param {(signal: {cancelled: boolean}) => Promise<any>} fn the request
+ * @param {Array<any>} deps re-runs when these change (like useEffect's)
+ * @param {{keepPreviousData?: boolean, enabled?: boolean, initialData?: any}} [opts]
+ */
+export function useAsyncData(fn, deps, { keepPreviousData = true, enabled = true, initialData = null } = {}) {
+  const [state, setState] = useState({
+    data: initialData,
+    loading: enabled,
+    refreshing: false,
+    error: null,
+  });
+  // Monotonic request id: a response may only publish if it is still the newest.
+  const requestId = useRef(0);
+  const hasData = useRef(initialData != null);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  const run = useCallback(
+    async ({ quiet = false } = {}) => {
+      if (!enabled) return;
+      const id = ++requestId.current;
+      const firstLoad = !hasData.current;
+      if (!quiet) {
+        setState((s) => ({
+          ...s,
+          loading: firstLoad,
+          refreshing: !firstLoad,
+          data: keepPreviousData ? s.data : firstLoad ? s.data : null,
+        }));
+      }
+      try {
+        const data = await fnRef.current();
+        if (id !== requestId.current) return; // a newer request won
+        hasData.current = true;
+        setState({ data, loading: false, refreshing: false, error: null });
+      } catch (e) {
+        if (id !== requestId.current) return;
+        setState((s) => ({
+          data: keepPreviousData ? s.data : null,
+          loading: false,
+          refreshing: false,
+          error: { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) },
+        }));
+      }
+    },
+    [enabled, keepPreviousData],
+  );
+
+  useEffect(() => {
+    run();
+    // Bump the id on unmount/dep-change so an in-flight response can't publish.
+    return () => {
+      requestId.current += 1;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [run, ...deps]);
+
+  const reload = useCallback(() => run(), [run]);
+  const reloadQuiet = useCallback(() => run({ quiet: true }), [run]);
+  const setData = useCallback((next) => {
+    hasData.current = true;
+    setState((s) => ({ ...s, data: typeof next === "function" ? next(s.data) : next }));
+  }, []);
+
+  return { ...state, reload, reloadQuiet, setData };
+}

package/src/commerce/storefront/useAddressForm.js

@@ -0,0 +1,96 @@
+import { useMemo } from "react";
+import { addressFieldSpec } from "@/commerce/utils";
+import { useStoreInfo } from "./StorefrontProvider";
+import { useCheckoutContext } from "./useCheckout";
+import { REQUIRED_BILLING_FIELDS } from "./address";
+
+/**
+ * The store's country list, **always as an array**.
+ *
+ *   const { options, loading } = useCountries();
+ *   <select>{options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}</select>
+ *
+ * `useStoreInfo().countries` is `null` until store info resolves, so mapping it
+ * directly white-screens the checkout on a cold load — the most severe defect
+ * observed in a generated storefront. Here the list is empty-then-full, never
+ * null, and `loading` says which.
+ */
+export function useCountries() {
+  const { countries, loading, error } = useStoreInfo();
+  const list = Array.isArray(countries) ? countries : [];
+  const options = useMemo(() => list.map((c) => ({ value: c.code, label: c.name })), [countries]); // eslint-disable-line react-hooks/exhaustive-deps
+  return { countries: list, options, loading, error };
+}
+
+/**
+ * useAddressForm — the checkout address form as a field list bound to the
+ * guided checkout. Needs a `<CheckoutProvider>` above it.
+ *
+ *   const { fields, set } = useAddressForm("billing");
+ *   {fields.map(f => (
+ *     <label key={f.key}>
+ *       {f.label}{f.required && " *"}
+ *       {f.type === "select"
+ *         ? <select value={f.value} onChange={e => set(f.key, e.target.value)}>
+ *             {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
+ *           </select>
+ *         : <input type={f.type} value={f.value} autoComplete={f.autoComplete}
+ *                  onChange={e => set(f.key, e.target.value)} />}
+ *       {f.error && <span role="alert">{f.error}</span>}
+ *     </label>
+ *   ))}
+ *
+ * Editing a field is all it takes to trigger the shipping/tax recalculation —
+ * `useCheckout` debounces and calls `set-shipping-address` once the address is
+ * complete enough to price. Two things the field list gets right that a
+ * hand-typed table did not: **`state` is present** (rates and taxes match on
+ * country + state, and it switches to a select for countries with
+ * subdivisions), and the country options are never null.
+ *
+ * @param {"billing"|"shipping"} [which]
+ * @param {{includeState?: boolean, includePhone?: boolean, includeCompany?: boolean}} [options]
+ */
+export function useAddressForm(which = "billing", options = {}) {
+  const checkout = useCheckoutContext();
+  const { countries, loading: countriesLoading } = useCountries();
+
+  const isBilling = which === "billing";
+  const values = isBilling ? checkout.billing : checkout.shipping;
+  const set = isBilling
+    ? (key, value) => checkout.updateBilling({ [key]: value })
+    : (key, value) => checkout.updateShipping({ [key]: value });
+
+  // `place-order` only enforces required fields on billing; a separate shipping
+  // address is priced, not validated field-by-field.
+  const missing = isBilling ? checkout.missingBillingFields : [];
+
+  const fields = useMemo(() => {
+    const spec = addressFieldSpec({
+      countries,
+      country: values?.country,
+      required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+      includeEmail: isBilling, // one email per order, on billing
+      ...options,
+    });
+    return spec.map((f) => ({
+      ...f,
+      value: values?.[f.key] ?? "",
+      // The address-level error ("we don't ship there") belongs on country.
+      error:
+        f.key === "country" && checkout.addressError?.code === "shipping_not_available"
+          ? checkout.addressError.message
+          : null,
+    }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [countries, values, isBilling, checkout.addressError, JSON.stringify(options)]);
+
+  return {
+    fields,
+    set,
+    values: values ?? {},
+    missing,
+    complete: missing.length === 0,
+    error: checkout.addressError ?? null,
+    countriesLoading,
+  };
+}

package/src/commerce/storefront/useCartLine.js

@@ -0,0 +1,184 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { useCart } from "./StorefrontProvider";
+
+/**
+ * useCartLine — one cart line's quantity control, with the interaction solved.
+ *
+ *   const l = useCartLine(line);
+ *   <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *   <span>{l.quantity}</span>
+ *   <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
+ *   <button onClick={l.remove}>Remove</button>
+ *   {l.error && <p role="alert">{l.error.message}</p>}
+ *
+ * What the obvious version (`onClick={() => updateItem(key, qty + 1)}`) gets
+ * wrong, and this does not: the mutation is **awaited and caught**, so a stock
+ * rejection shows as `error` instead of an unhandled rejection with the number
+ * silently snapping back; the displayed quantity is **optimistic** and rolls
+ * back only if the server disagrees; rapid clicks are **coalesced** into one
+ * request per settle instead of one per click; and `sold_individually` is
+ * respected, so a one-per-customer product has no working "+".
+ *
+ * @param {object} line a decorated line from `useCart().lines` (a raw
+ *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
+ * @param {{debounceMs?: number}} [options]
+ */
+export function useCartLine(line, { debounceMs = 250 } = {}) {
+  const { updateItem, removeItem } = useCart();
+  const serverQuantity = line?.quantity ?? 1;
+  const maxQuantity = line?.maxQuantity ?? (line?.sold_individually ? 1 : Infinity);
+
+  const [optimistic, setOptimistic] = useState(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState(null);
+  const timer = useRef(null);
+  const target = useRef(null);
+
+  // The server is the truth: whenever its quantity lands, drop the optimistic
+  // value (whether it agreed with us or not).
+  useEffect(() => {
+    setOptimistic(null);
+  }, [serverQuantity]);
+
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const quantity = optimistic ?? serverQuantity;
+
+  const commit = useCallback(async () => {
+    const next = target.current;
+    if (next == null || next === serverQuantity) return;
+    setPending(true);
+    setError(null);
+    try {
+      await updateItem(line.item_key, next);
+    } catch (e) {
+      setOptimistic(null); // roll back to what the server still holds
+      setError({ code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) });
+    } finally {
+      setPending(false);
+      target.current = null;
+    }
+  }, [line?.item_key, serverQuantity, updateItem]);
+
+  const setQuantity = useCallback(
+    (n) => {
+      const clamped = Math.max(1, Math.min(maxQuantity, Math.floor(Number(n) || 1)));
+      setOptimistic(clamped);
+      setError(null);
+      target.current = clamped;
+      clearTimeout(timer.current);
+      timer.current = setTimeout(commit, debounceMs);
+    },
+    [maxQuantity, commit, debounceMs],
+  );
+
+  const increase = useCallback(() => setQuantity(quantity + 1), [quantity, setQuantity]);
+  const decrease = useCallback(() => setQuantity(quantity - 1), [quantity, setQuantity]);
+
+  const remove = useCallback(async () => {
+    clearTimeout(timer.current);
+    setPending(true);
+    setError(null);
+    try {
+      await removeItem(line.item_key);
+    } catch (e) {
+      setError({ code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) });
+    } finally {
+      setPending(false);
+    }
+  }, [line?.item_key, removeItem]);
+
+  return {
+    quantity,
+    setQuantity,
+    increase,
+    decrease,
+    remove,
+    pending,
+    error,
+    canIncrease: quantity < maxQuantity,
+    canDecrease: quantity > 1,
+    maxQuantity,
+    atMax: quantity >= maxQuantity,
+    atMin: quantity <= 1,
+    attributesLabel: line?.attributesLabel ?? "",
+    image: line?.image ?? null,
+  };
+}
+
+/**
+ * useCoupon — the coupon field. Small, and the difference between a store that
+ * can honour its own discounts and one that cannot.
+ *
+ *   const c = useCoupon();
+ *   <input value={c.code} onChange={(e) => c.setCode(e.target.value)} />
+ *   <button onClick={c.apply} disabled={c.applying}>Apply</button>
+ *   {c.error && <p role="alert">{c.error.message}</p>}
+ *   {c.applied.map(a => <Chip key={a.code} onRemove={() => c.remove(a.code)} …/>)}
+ *
+ * Coupons are admin-only data — a storefront cannot list codes, so a seeded
+ * code is reachable **only** through a field the customer types it into. If the
+ * store has any coupons, this field must exist somewhere in the cart or the
+ * checkout, or those codes can never be redeemed.
+ *
+ * An invalid, expired or ineligible code is **expected flow**: `apply()`
+ * resolves `{ ok: false, error }` and never throws — render `error.message`
+ * inline next to the field.
+ */
+export function useCoupon() {
+  const { cart, applyCoupon, removeCoupon } = useCart();
+  const [code, setCode] = useState("");
+  const [applying, setApplying] = useState(false);
+  const [error, setError] = useState(null);
+
+  const apply = useCallback(
+    async (explicit) => {
+      const value = String(explicit ?? code ?? "").trim();
+      if (!value) return { ok: false, error: { code: "empty", message: "Enter a code." } };
+      setApplying(true);
+      setError(null);
+      const res = await applyCoupon(value);
+      setApplying(false);
+      if (res.ok) {
+        setCode("");
+        return { ok: true, cart: res.cart };
+      }
+      const err = { code: res.code ?? "coupon_invalid", message: res.message };
+      setError(err);
+      return { ok: false, error: err };
+    },
+    [code, applyCoupon],
+  );
+
+  const remove = useCallback(
+    async (codeOrEntry) => {
+      const value = typeof codeOrEntry === "string" ? codeOrEntry : codeOrEntry?.code;
+      setError(null);
+      try {
+        await removeCoupon(value);
+        return { ok: true };
+      } catch (e) {
+        const err = { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) };
+        setError(err);
+        return { ok: false, error: err };
+      }
+    },
+    [removeCoupon],
+  );
+
+  return {
+    code,
+    setCode,
+    apply,
+    remove,
+    applied: (cart?.coupons ?? []).map((c) => ({
+      code: c.code,
+      discount: c.discount ?? 0,
+      freeShipping: Boolean(c.free_shipping),
+    })),
+    applying,
+    error,
+    discountTotal: cart?.totals?.discount_total ?? 0,
+  };
+}