@base44/app-plugin-commerce 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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/SKILL.md

@@ -118,14 +118,14 @@ batch (above).
 | Topic | Open when | Size |
 |---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 35K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 36K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
-| [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
+| [`references/reviews.md`](./references/reviews.md) | review policies (open by default; login-gated, verified buyers), moderation | 6K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |
 | [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, the log | 5K |
 | [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | 6K |

package/skills/commerce/install/02-storefront.md

@@ -71,7 +71,7 @@ function StoreLayout() {
 
 The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row`, a heading scale, a price style — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.**
 
-⚑ **Two `@apply` forms Tailwind rejects, and each breaks the whole build.** An opacity modifier on an arbitrary value is not a class (`text-[var(--ink)]/40`) — write plain CSS: `color: color-mix(in srgb, var(--ink) 40%, transparent)`. And `@apply group` is invalid; `group` is a marker for the element's `className`. Either is a postcss error that fails Vite, so *every* page renders blank — which reads as a broken import and sends you into `src/commerce/`. **Nothing rendering? Read `index.css` first.**
+⚑ **Two `@apply` forms Tailwind rejects, and each breaks the whole build.** **Any** `/opacity` on a bracketed value is not a class — `text-[var(--ink)]/40` and `border-[#1B2422]/8` fail alike — so write plain CSS: `border-color: color-mix(in srgb, var(--ink) 40%, transparent)`. Translucent brand colours are the commonest thing a `.panel`/`.field` class wants, so reach for `color-mix` first. And `@apply group` is invalid; `group` is a marker for the element's `className`. Either is a postcss error that fails Vite, so *every* page renders blank — which reads as a broken import and sends you into `src/commerce/`. **Nothing rendering? Read `index.css` first.**
 
 The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show. It is the half of a store's identity a kit cannot ship.
 
@@ -167,7 +167,7 @@ Build your layout from — all optional, **not one component style**:
   ))}
   ```
 
-  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. **Render each axis by what it is** — swatches for a colour axis, chips with a size guide beside a size axis; every axis as the identical chip row is a generated-page tell. That differentiation is semantic — what the control *shows* — built from your classes, not extra chrome around each row.
+  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. **Render each axis by what it is — pick the control per attribute**: a colour axis as colour circles with the name as a hint (a swatch alone leaves "Ivory" vs "Sand" unguessable), size chips with a size guide, a select for a long list — a specialty control where it genuinely fits, not on every axis; yet every axis as the identical chip row is a generated-page tell. Any control keeps the contract: disabled, out-of-stock marked, selection visible.
 - **Buy box** — one button, and **you supply its four words**:
 
   ```jsx
@@ -190,7 +190,7 @@ Build your layout from — all optional, **not one component style**:
 
   ⚑ **Never `.map()` the whole list into one grey label/value table** — that is the single most reliable tell of a generated product page. Design the two or three rows that carry *this* catalog's meaning as what they are (a weight set in the display face, a composition as bars, a provenance beside its place); let the rest fall through to the plain row, and don't feel obliged to keep them in one block — a spec can sit under the gallery, beside the price, or inside the description. Branch on `s.key` too where one particular modifier deserves its own treatment regardless of type. ⚑ **Look a spec up with `findSpec(rows, "care")`** (ignores case, spaces, `_`, `-`): meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. `[]` means no section at all.
 - **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
-- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
+- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`. ⚑ **The form renders for every visitor by default** (guests supply an email; hide the field when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
 - **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
 
 ## Cart / bag
@@ -249,7 +249,7 @@ import { CheckoutProvider, useCheckoutContext, AddressFields, ShippingMethodPick
 
 `useCheckout` reprices shipping/tax from the address automatically (debounced, never on a half-typed address), derives the shipping and payment choices, gates the button, and `placeOrder()` handles **both** navigations — online gateway → provider redirect, everything else → `/order-received` — as **full page loads** (`<CheckoutProvider options={{ orderReceivedPath: null }}>` for a router transition instead). `CheckoutProvider` shares it across the page's regions.
 
-⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
+⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". ⚑ Picks are instant: both pickers reflect a click immediately (shipping optimistically), and `mustChoose` stays true after a choice — the radios keep rendering, still changeable; never disable options while `syncing`/`choosing` (the hint covers it). Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
 
 ⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` (bag is empty) · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (this address can't be delivered to) · `payment_method_required` (choose how to pay) · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
 
@@ -282,7 +282,7 @@ function CheckoutForm() {
                 {m.title} {m.costLabel}
               </label>
             ))}
-            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}{/* the lone option */}
           </fieldset>
         )}
       </ShippingMethodPicker>

package/skills/commerce/references/reviews.md

@@ -5,6 +5,7 @@ skip_when: "The product page already renders `p.reviews` and submits through `su
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
   - "Reviews are part of the happy path: the list arrives with the product, submitting is one client call. The confirmation copy must come from the submit response's `status`, never hardcoded."
+  - "The review form renders for every visitor by default — guests included, with an email field. Login-gating is an explicit store request, implemented as one conditional around the form."
 ---
 
 # Reviews
@@ -25,14 +26,14 @@ Both live on the storefront client in `@/commerce/utils` — in React, `useStore
 - `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
 - moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
 
-## The policy is the store's
+## The policy is the store's — and open is the default
 
-Which visitors may submit is a gate **you** render, in your own words. The three patterns worth knowing:
+Which visitors may submit is a gate **you** render, in your own words — and **the default is no gate at all**. Build the form for every visitor, signed in or not (that is the server's own rule); a review form a guest cannot use is a policy the store has to ask for, never something to add on your own initiative. The two stricter patterns are each one small change away when the store does ask:
 
 | Policy | Who may submit | How you implement it |
 |---|---|---|
-| **Open** (the server's own rule) | anyone with a valid email | render the form for everyone; the email field is required for guests |
-| **Login-gated** | a signed-in visitor only | render the form only when your app has a user; otherwise your "sign in to review" line |
+| **Open — the default** | anyone with a valid email | render the form for everyone; the email field is required for guests, hidden when signed in |
+| **Login-gated** | a signed-in visitor only | one conditional around the same form: render it when your app has a user, otherwise your "sign in to review" line |
 | **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
 Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.

package/src/commerce/admin/layout/Sidebar.jsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef, useState } from "react";
-import { NavLink, useLocation } from "react-router-dom";
+import { Link, NavLink, useLocation } from "react-router-dom";
 import { Badge } from "@/components/ui/badge";
 import {
   BadgePercent,
@@ -9,6 +9,7 @@ import {
   Settings,
   ShoppingCart,
   Sparkles,
+  Store,
   Users,
 } from "lucide-react";
 import { call } from "../lib/api";
@@ -105,8 +106,17 @@ export default function Sidebar({ onNavigate, onOpenBot }) {
           </div>
         ))}
       </nav>
-      {onOpenBot && (
-        <div className="border-t p-3">
+      <div className="space-y-0.5 border-t p-3">
+        {/* The way back out — the storefront the merchant is managing. */}
+        <Link
+          to="/"
+          onClick={onNavigate}
+          className="flex items-center gap-2.5 rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        >
+          <Store className="h-4 w-4 shrink-0" />
+          <span className="flex-1">View storefront</span>
+        </Link>
+        {onOpenBot && (
           <button
             type="button"
             onClick={onOpenBot}
@@ -115,8 +125,8 @@ export default function Sidebar({ onNavigate, onOpenBot }) {
             <Sparkles className="h-4 w-4 shrink-0 text-primary" />
             <span className="flex-1 text-left">StoreAdmin bot</span>
           </button>
-        </div>
-      )}
+        )}
+      </div>
     </div>
   );
 }

package/src/commerce/storefront/pickers.jsx

@@ -50,12 +50,20 @@ function resolveCheckout(name, prop, ctx) {
  *   chosen         the chosen/auto-selected entry, or null
  *   selected       alias of `chosen` (the name the payment picker uses)
  *   choose         (id) => Promise
- *   mustChoose     status === "choice_required" → render methods as a picker
+ *   mustChoose     more than one method → render methods as a picker
  *   single         exactly one method offered — already chosen
+ *   choosing       a pick is in flight — `selected` already reflects it
  *   syncing        an address edit is being repriced
  *   hint           { code, severity, serverMessage } | null (see above)
  *   addressError   { code, message } | null — the server's own words
  *
+ * `mustChoose` stays true after a choice is made — with several methods the
+ * radios keep rendering, the chosen one checked, so the customer can change
+ * their mind; collapsing a made choice to static text strands it. A pick
+ * reflects in `selected` from the click (optimistically, while the priced view
+ * catches up), so never disable the options while `choosing`/`syncing` — the
+ * hint line is the affordance for that, not a locked control.
+ *
  * `single` and `mustChoose` are never both true, and `single` guarantees
  * `chosen` — a single option still *shows* what it is (title + `costLabel`),
  * never a picker of one. Never render `cart.chosen_shipping_method` directly:
@@ -70,6 +78,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     chosenShippingMethod: chosen,
     singleShippingMethod: single,
     chooseShippingMethod: choose,
+    shippingChoicePending: choosing,
     shippingSyncing: syncing,
     addressError,
   } = checkout;
@@ -96,8 +105,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     chosen: decoratedChosen,
     selected: decoratedChosen,
     choose,
-    mustChoose: status === "choice_required",
+    // True whenever there is a real choice — including after one is made, so a
+    // made choice stays changeable instead of collapsing to static text.
+    mustChoose: status === "choice_required" || methods.length > 1,
     single: single ?? (methods.length === 1), // fallback: a hand-built checkout object
+    choosing: choosing ?? false,
     syncing,
     hint,
     addressError,
@@ -119,9 +131,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *
  * `single` guarantees `value` and `selected` — never render the one-gateway
  * branch as "nothing selected yet" — and both re-resolve when store info
- * changes. A default-seeded store offers `offline` only, so never hardcode a
- * card option. Titles and descriptions are the admin's copy: render them, don't
- * invent your own.
+ * changes. A pick is plain local state: it reflects the instant it is clicked,
+ * with no server round trip — so never disable these options while the cart is
+ * repricing elsewhere. A default-seeded store offers `offline` only, so never
+ * hardcode a card option. Titles and descriptions are the admin's copy: render
+ * them, don't invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());

package/src/commerce/storefront/useCheckout.jsx

@@ -69,6 +69,10 @@ function resolvePaymentMethod(gateways, picked) {
  *   `not_needed` (virtual cart — render nothing). `singleShippingMethod` flags
  *   the one-option case and `chosenShippingMethod` is filled for it, so a single
  *   option is never left unselected and never rendered as a picker of one.
+ *   **A pick applies optimistically**: `chosenShippingMethod` reflects it from
+ *   the click, while the priced view catches up in the background
+ *   (`shippingChoicePending` is true for that window) — a radio that waits for
+ *   the server to look checked reads as a picker that ignored the click.
  * - **Payment choice.** `paymentMethods` come from store info (their ONLY
  *   source — `cart.payment_gateways` is always undefined). One enabled gateway
  *   is selected from the first render that has store info. The selection is
@@ -193,18 +197,33 @@ export function useCheckout(options = {}) {
   const shippingStatus = cart?.shipping_status ?? null;
   const shippingMethods = cart?.available_shipping_methods ?? [];
   const singleShippingMethod = shippingMethods.length === 1;
+  // The optimistic pick: `choose-shipping-method` is a priced round trip, and a
+  // radio that only looks checked once the response lands reads as a picker
+  // that ignored the click. The pick covers exactly the in-flight window — it
+  // clears when its own call settles, so the confirmed view (or, on failure,
+  // the cart's stored choice) takes back over without a flicker.
+  const [pickedShippingMethod, setPickedShippingMethod] = useState("");
   // 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 === pickedShippingMethod) ??
     shippingMethods.find((m) => m.id === cart?.chosen_shipping_method) ??
     (singleShippingMethod ? shippingMethods[0] : null);
   const chooseShippingMethod = useCallback(
-    (methodId) => runCart(() => client.chooseShippingMethod(methodId)),
+    (methodId) => {
+      setPickedShippingMethod(methodId);
+      return runCart(() => client.chooseShippingMethod(methodId)).finally(() =>
+        // Only the call's own pick is cleared — a newer click stays optimistic
+        // until its own call settles (the queue serializes them in order).
+        setPickedShippingMethod((cur) => (cur === methodId ? "" : cur)),
+      );
+    },
     [client, runCart],
   );
+  const shippingChoicePending = !!pickedShippingMethod;
 
   // ── payment choice (gateways live on store info ONLY) ────────────────────
   // The pick is state; the *method* is derived, so a lone gateway is selected
@@ -224,9 +243,14 @@ export function useCheckout(options = {}) {
   else if (!cart || !cart.items?.length) blockers.push("empty_cart");
   if (missingBilling.length) blockers.push("billing_incomplete");
   if (shipToDifferent && !complete) blockers.push("shipping_address_incomplete");
-  if (syncPending || syncing) blockers.push("shipping_recalculating");
+  if (syncPending || syncing || shippingChoicePending) blockers.push("shipping_recalculating");
   if (shippingStatus === "missing_address") blockers.push("shipping_address_required");
-  if (shippingStatus === "choice_required") blockers.push("shipping_method_required");
+  // A pick in flight already shows as selected — flagging "choose one" over a
+  // visibly chosen radio contradicts the screen; the transient code above
+  // covers the window, and the blocker returns if the pick fails.
+  if (shippingStatus === "choice_required" && !shippingChoicePending) {
+    blockers.push("shipping_method_required");
+  }
   if (shippingStatus === "none_available" || addressError?.code === "shipping_not_available") {
     blockers.push("shipping_not_available");
   }
@@ -322,6 +346,7 @@ export function useCheckout(options = {}) {
     chosenShippingMethod,
     singleShippingMethod,
     chooseShippingMethod,
+    shippingChoicePending,
     // payment choice
     paymentMethods,
     paymentMethod,