@base44/app-plugin-commerce 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/post-installation.md

@@ -220,7 +220,7 @@ Shipping cost on the cart page: a store with exactly **one shipping location** s
 
 - **address form state** (`billing`/`updateBilling`, an optional separate `shipping`/`updateShipping` behind `setShipToDifferent`), with `missingBillingFields` tracking what `place-order` would reject;
 - **automatic shipping/tax recalculation**: the moment the address is complete enough to price (default: country + city), the hook debounces and calls `set-shipping-address`, repricing every shipping option, its cost and the taxes — half-typed addresses are never sent, an unchanged address is never re-sent, and an address the store doesn't ship to surfaces as `addressError` to show **on the address fields**;
-- **the shipping choice** (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`) and **the payment choice** (`paymentMethods` from store info — their only source; a store with exactly one enabled gateway gets it pre-selected);
+- **the shipping choice** (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`) and **the payment choice** (`paymentMethods` from store info — their only source); on both, **a single option is a selected option** — one shipping rate arrives already applied as `chosenShippingMethod`, one enabled gateway is `selectedGateway` from the first render that has store info, and both re-resolve when the data changes (`singleShippingMethod` / `singlePaymentMethod` flag the case);
 - **the gate**: `canPlaceOrder` + named `blockers`, and `placeOrder` with the online-payment redirect handled.
 
 Share one instance across the page's components with `CheckoutProvider` and build each step as your own markup:
@@ -264,16 +264,17 @@ const { billing, updateBilling, missingBillingFields,
 The two store-data choices — **never hardcode either** — come pre-branched through the headless pickers (they render nothing themselves; the render prop is the whole UI):
 
 ```jsx
-<ShippingMethodPicker>{({ status, methods, chosen, choose, mustChoose, syncing }) => (
+<ShippingMethodPicker>{({ status, methods, chosen, choose, mustChoose, single, syncing }) => (
   // renders null for you on virtual carts (status "not_needed")
   // status "missing_address" → say options appear once the address is entered
   // mustChoose → render methods [{ id, title, cost }] as a picker → choose(m.id)
+  // single     → already selected; skip the picker, still show chosen.title + cost
   // otherwise  → display chosen.title + chosen.cost (never a raw id); dim while syncing
 )}</ShippingMethodPicker>
 
 <PaymentMethodPicker>{({ gateways, value, select, selected, single }) => (
   // several → picker labeled with the admin's title/description → select(g.slug)
-  // single  → pre-selected; skip the picker but still show selected.title
+  // single  → already selected; skip the picker but still show selected.title
   // none    → checkout cannot complete — say so instead of rendering a dead button
 )}</PaymentMethodPicker>
 ```

package/src/commerce/storefront/pickers.jsx

@@ -27,15 +27,19 @@ function resolveCheckout(name, prop, ctx) {
  *     status,        // "missing_address" | "choice_required" | "chosen" | "auto_selected"
  *     methods,       // [{ id, title, cost }] — what this address is offered
  *     chosen,        // the chosen/auto-selected entry (title + cost), or null
+ *     selected,      // alias of `chosen` — the same name the payment picker uses
  *     choose,        // (id) => Promise — call with a method's id on pick
  *     mustChoose,    // status === "choice_required" → render methods as a picker
+ *     single,        // exactly one method offered — already chosen; skip the
+ *                    //   picker but still show `chosen.title` and its cost
  *     syncing,       // an address edit is being repriced — show a subtle busy state
  *     addressError,  // { code, message } | null — "we don't ship there" belongs
  *   }                //   on the address fields
  *
  * Render rules the child should follow: `missing_address` → say the options
  * appear once the address is entered; `mustChoose` → a picker of `methods`;
- * otherwise display `chosen.title` + its cost (never the raw id).
+ * otherwise display `chosen.title` + its cost (never the raw id). `single` and
+ * `mustChoose` are never both true, and `single` guarantees `chosen`.
  */
 export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
@@ -43,6 +47,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     shippingStatus: status,
     shippingMethods: methods,
     chosenShippingMethod: chosen,
+    singleShippingMethod: single,
     chooseShippingMethod: choose,
     shippingSyncing: syncing,
     addressError,
@@ -52,8 +57,10 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     status,
     methods,
     chosen,
+    selected: chosen,
     choose,
     mustChoose: status === "choice_required",
+    single: single ?? (methods.length === 1), // fallback: a hand-built checkout object
     syncing,
     addressError,
   });
@@ -69,22 +76,30 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *     value,      // the selected slug ("" while none)
  *     select,     // (slug) => void
  *     selected,   // the selected gateway entry, or null
- *     single,     // exactly one gateway — pre-selected; skip the picker but
+ *     single,     // exactly one gateway — already selected; skip the picker but
  *   }             //   still show its title so the customer knows how they pay
  *
  * Render rules: several gateways → a picker labeled with the admin's
  * title/description; `single` → just display it; zero gateways → say checkout
- * is unavailable instead of rendering a dead place-order button.
+ * is unavailable instead of rendering a dead place-order button. `single`
+ * guarantees `value` and `selected` — never render the one-gateway branch as
+ * "nothing selected yet" — and both re-resolve when store info changes.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());
-  const { paymentMethods: gateways, paymentMethod: value, setPaymentMethod: select, selectedGateway: selected } = checkout;
+  const {
+    paymentMethods: gateways,
+    paymentMethod: value,
+    setPaymentMethod: select,
+    selectedGateway: selected,
+    singlePaymentMethod: single,
+  } = checkout;
   if (!gateways) return null;
   return children({
     gateways,
     value,
     select,
     selected,
-    single: gateways.length === 1,
+    single: single ?? (gateways.length === 1), // fallback: a hand-built checkout object
   });
 }

package/src/commerce/storefront/useCheckout.jsx

@@ -21,6 +21,18 @@ const EMPTY_ADDRESS = Object.freeze({
   phone: "",
 });
 
+/**
+ * The gateway a checkout is actually paying with: the customer's pick while it
+ * is still an enabled gateway, otherwise the only gateway there is — one option
+ * is not a choice. Derived on every render from the current store info, so it
+ * follows the data instead of trailing it by an effect.
+ */
+function resolvePaymentMethod(gateways, picked) {
+  if (!gateways?.length) return "";
+  if (picked && gateways.some((g) => g.slug === picked)) return picked;
+  return gateways.length === 1 ? gateways[0].slug : "";
+}
+
 /**
  * useCheckout — the guided checkout state machine. It owns the parts every
  * checkout must get right, so the page you build is only markup around it:
@@ -38,8 +50,15 @@ const EMPTY_ADDRESS = Object.freeze({
  *   `chosenShippingMethod`), `chosen`, `choice_required` (render
  *   `shippingMethods` and call `chooseShippingMethod(id)`), `missing_address`
  *   (collect the address), `not_needed` (virtual cart — render nothing).
+ *   `singleShippingMethod` flags the one-option case, and `chosenShippingMethod`
+ *   is filled for it — a single option is never left unselected.
  * - **Payment choice.** `paymentMethods` come from store info (their ONLY
- *   source); a store with exactly one enabled gateway gets it pre-selected.
+ *   source); a store with exactly one enabled gateway gets it selected
+ *   (`singlePaymentMethod`, with `selectedGateway` filled) from the first
+ *   render that has store info. The selection is derived from the current
+ *   gateway list, not remembered: when store info changes, a gateway that is
+ *   no longer enabled is dropped and a list that is down to one gateway
+ *   selects it — the customer's own pick survives as long as it stays enabled.
  * - **The gate.** `canPlaceOrder` + `blockers` say exactly what still stands
  *   between the customer and the order — drive the button's disabled state
  *   and the "what's missing" hints from them instead of re-deriving.
@@ -70,7 +89,7 @@ export function useCheckout(options = {}) {
   const [billing, setBilling] = useState({ ...EMPTY_ADDRESS, email: "" });
   const [shipping, setShipping] = useState({ ...EMPTY_ADDRESS });
   const [shipToDifferent, setShipToDifferent] = useState(false);
-  const [paymentMethod, setPaymentMethod] = useState("");
+  const [pickedPaymentMethod, setPaymentMethod] = useState("");
   const [addressError, setAddressError] = useState(null);
   const [syncing, setSyncing] = useState(false);
   const [syncedKey, setSyncedKey] = useState(undefined);
@@ -124,24 +143,30 @@ export function useCheckout(options = {}) {
   // ── shipping choice (from the shared cart view) ──────────────────────────
   const shippingStatus = cart?.shipping_status ?? null;
   const shippingMethods = cart?.available_shipping_methods ?? [];
+  const singleShippingMethod = shippingMethods.length === 1;
+  // The backend auto-selects when it offers exactly one rate (`auto_selected`)
+  // and echoes it back on the cart, so the lookup normally finds it. The
+  // fallback covers the seam where a freshly repriced address offers one rate
+  // the cart's stored id hasn't caught up with: a single option is selected,
+  // and must read as selected, from the moment it is offered.
   const chosenShippingMethod =
-    shippingMethods.find((m) => m.id === cart?.chosen_shipping_method) ?? null;
+    shippingMethods.find((m) => m.id === cart?.chosen_shipping_method) ??
+    (singleShippingMethod ? shippingMethods[0] : null);
   const chooseShippingMethod = useCallback(
     (methodId) => runCart(() => client.chooseShippingMethod(methodId)),
     [client, runCart],
   );
 
   // ── payment choice (gateways live on store info ONLY) ────────────────────
+  // The pick is state; the *method* is derived, so a lone gateway is selected
+  // on the very first render that has store info (never a frame of "nothing
+  // selected", never a wasted effect pass) and every one of these re-resolves
+  // the moment the gateway list changes — a gateway the admin just disabled
+  // drops out, and if that leaves exactly one, it takes over immediately.
   const paymentMethods = info?.payment_gateways ?? null;
-  useEffect(() => {
-    if (!paymentMethods) return;
-    if (paymentMethod && !paymentMethods.some((g) => g.slug === paymentMethod)) {
-      setPaymentMethod("");
-    } else if (!paymentMethod && paymentMethods.length === 1) {
-      setPaymentMethod(paymentMethods[0].slug); // one option is not a choice
-    }
-  }, [paymentMethods, paymentMethod]);
+  const paymentMethod = resolvePaymentMethod(paymentMethods, pickedPaymentMethod);
   const selectedGateway = paymentMethods?.find((g) => g.slug === paymentMethod) ?? null;
+  const singlePaymentMethod = paymentMethods?.length === 1;
 
   // ── the gate ─────────────────────────────────────────────────────────────
   const missingBilling = missingBillingFields(billing, requiredBillingFields);
@@ -220,12 +245,14 @@ export function useCheckout(options = {}) {
     shippingStatus,
     shippingMethods,
     chosenShippingMethod,
+    singleShippingMethod,
     chooseShippingMethod,
     // payment choice
     paymentMethods,
     paymentMethod,
     setPaymentMethod,
     selectedGateway,
+    singlePaymentMethod,
     // the gate + the order
     blockers,
     canPlaceOrder,