@base44/app-plugin-commerce 0.6.8 → 0.6.9

package/base44/entities/commerce.ProductReview.jsonc

@@ -24,7 +24,7 @@
     },
     "review": {
       "type": "string",
-      "description": "Review content"
+      "description": "Review text. May be empty for a stars-only review (submit-review requires text or a rating, not both)."
     },
     "rating": {
       "type": "integer",
@@ -38,7 +38,7 @@
       "description": "Derived: reviewer purchased the product. Set by commerce/storefront-catalog submit-review."
     }
   },
-  "required": ["product_id", "review"],
+  "required": ["product_id"],
   "rls": {
     "read": { "user_condition": { "role": "admin" } },
     "create": { "user_condition": { "role": "admin" } },

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -396,12 +396,16 @@ async function submitReview(sr: any, p: any, user: any): Promise<any> {
   const review = String(p.review ?? "").trim();
   const rating = p.rating == null ? null : Math.floor(Number(p.rating));
 
-  if (!review) {
-    throw new HttpError(400, "review is required.", "review_incomplete");
-  }
   if (rating != null && (rating < 0 || rating > 5)) {
     throw new HttpError(400, "Rating must be between 0 and 5.", "invalid_rating");
   }
+  // Text or stars — either alone is a valid review. Requiring text rejected
+  // every stars-only submission from a form that treats the write-up as
+  // optional, with a 400 the customer can't act on. Rating 0 is "unrated"
+  // (the aggregates ignore it), so it can't stand in for the missing text.
+  if (!review && !(rating != null && rating >= 1)) {
+    throw new HttpError(400, "A review needs text or a star rating.", "review_incomplete");
+  }
 
   const verified = await hasPurchased(sr, reviewerEmail, product.id);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "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,7 +118,7 @@ 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 | 36K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 37K |
 | [`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 |

package/skills/commerce/docs/api-storefront.md

@@ -114,14 +114,14 @@ This is the **only** way a storefront can enumerate ribbons (the entity is admin
 No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
-**Payload:** `{ product_id, email?, reviewer?, review, rating? }` — `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
+**Payload:** `{ product_id, email?, reviewer?, review?, rating? }` — at least one of `review` (text) or `rating` (1–5); `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
 
 > A React storefront reaches this call as `submitReview` (and the paginated list as `getProductReviews`) on the client from `@/commerce/storefront`'s `useStorefront()`, with the list itself already riding along on the product; policies and moderation are [`../references/reviews.md`](../references/reviews.md). Read on for the raw contract.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. **Text or stars — either alone is valid**: `rating` is 0–5 (0 = unrated, so a stars-only submission needs 1–5); `review_incomplete` fires only when both are missing. `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
-**Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
+**Errors:** `404 not_found`, `400 email_required|review_incomplete` (neither text nor stars)`|invalid_rating`.
 
 ---
 

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

@@ -156,9 +156,13 @@ Build your layout from — all optional, **not one component style**:
 - **Variant selector** — `variantAxes(view, p.pick)`, one entry per axis:
 
   ```jsx
+  const SWATCH = { Ivory: "#F2EDE4", "Obsidian Black": "#101014" };   // this catalog's colour names → CSS
   {variantAxes(view, p.pick).map((axis) => (
     <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
-      {axis.options.map((o) => (
+      {axis.options.map((o) => /colou?r/i.test(axis.name) ? (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}
+                className="swatch" style={{ background: SWATCH[o.value] }} title={o.value} aria-label={o.value} />
+      ) : (
         <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
           {o.value}{/* o.outOfStock → mark visibly */}
         </button>
@@ -167,7 +171,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 — 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.
+  ⚑ **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. ⚑ **Pick the control per attribute, as the branch above does**: a colour axis as colour circles (the name stays reachable — `title`, `aria-label`, and the axis label showing `selectedOption`), size chips beside a size guide, a select for a long list; a specialty control where it genuinely fits, not on every axis — but every axis as the same bare chip row is the flattest page this kit produces. 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 +194,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()`. ⚑ **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).
+- **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()` — text or stars, either alone submits. ⚑ **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

package/skills/commerce/references/reviews.md

@@ -17,7 +17,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
 
 - **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
-- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
+- **`submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
@@ -36,7 +36,7 @@ Which visitors may submit is a gate **you** render, in your own words — and **
 | **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.
+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). The server needs only one of text/stars — if your form makes either (or both) mandatory, validate before you call, so the customer meets your words rather than a raw 400. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 

package/src/commerce/admin/pages/products/Reviews.jsx

@@ -137,7 +137,10 @@ export default function Reviews() {
         label: "Review",
         render: (row) => (
           <div className="max-w-md">
-            <p className="line-clamp-2 text-sm">{row.review}</p>
+            {/* A rating-only review is valid — say so, or the row reads as blank. */}
+            {row.review
+              ? <p className="line-clamp-2 text-sm">{row.review}</p>
+              : <p className="text-sm italic text-muted-foreground">Rating only — no text</p>}
             {row.verified && <span className="text-xs text-green-700">✓ Verified owner</span>}
           </div>
         ),

package/src/commerce/utils/storefront.js

@@ -111,7 +111,9 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
     /**
      * Submit a review. `email` is required for a guest and ignored for a
      * signed-in caller (the session's email always wins, so nobody can
-     * review as someone else). `rating` is optional, 0–5.
+     * review as someone else). At least one of `review` (the text) or
+     * `rating` (1–5 stars) is required — a stars-only submission is valid,
+     * and so is text-only; only both missing rejects (`review_incomplete`).
      *
      * Resolves to `{ review_id, status, verified }` — **`status` is
      * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`