@base44/app-plugin-commerce 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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/installation/install.md

@@ -12,6 +12,7 @@ carry_forward:
   - "Entities are dotted + bracket-syntax only (`base44.entities[\"commerce.X\"]`); the map is ../docs/entities.md — never scan base44/entities/."
   - "Payment gateways, currency and countries come from useStoreInfo() only — never off a cart (cart.payment_gateways is always undefined)."
   - "Cart page, drawer, checkout and order-received are SHIPPED components (@/commerce/storefront-ui): mount them, set the .sfui theme block in pairs + brand props, and build or edit nothing inside — day-2 changes go through ../references/storefront-ui.md, never file edits (kit updates re-copy the directory)."
+  - "A prompt naming a cart or checkout is describing the store, not ordering a custom one — mount the shipped component."
   - "<MiniCart /> mounts once in the layout, never on a route; the shipped coupon field appears by itself exactly when the store has coupons (sections.coupon \"auto\") — never wire your own."
   - "Branch list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
   - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
@@ -131,6 +132,8 @@ Record this file's `carry_forward` lines (front matter) in your working notes, t
 
 One split decides everything here — **who owns which surface**. The catalog — the list/collection and the product page — is yours end to end: every element, class, layout and **word**; its logic is premade as headless hooks (`@/commerce/storefront`) that render nothing. The **conversion surfaces — cart page, cart drawer, checkout, order received — ship finished** (`@/commerce/storefront-ui`, [below](#cart-drawer-checkout-order-received--shipped)): you mount them, set a theme block and brand wording, and build nothing inside. **Decide how the store looks as if this kit did not exist**, then encode it **once** as design classes ([below](#design-language--once-before-any-page)) — the snippets here are wiring reference, never design input.
 
+⚑ **Nearly every store prompt describes a cart and a checkout** — "customers add to a cart and pay at checkout" states what a store *is*; it is not an instruction to build those screens, and it is the sentence most likely to talk you out of mounting them. Only an ask to *change* a conversion surface is a request, and props or tokens answer it — never a hand-built page.
+
 **On the pages you build, states and codes — not copy.** Where a state needs words you get the *state* (`buy.state`) and write the words. So: never re-derive a state you were handed (a ternary chain over `adding`/`purchasable` re-implements `buy.state`, wrong), and never leave one unworded (a button with no text for `sold_out` renders empty). The hooks own variant resolution, cart state, pricing — **never re-implement what a hook does**; that is where storefront bugs cluster.
 
 **This file is the whole job.** Every shape you need is in ["What each hook resolves to"](#what-each-hook-resolves-to) — don't open the hook files while building; that is the most expensive way to answer a question this page already answers. Rules marked ⚑ must survive whatever design you build.
@@ -210,7 +213,7 @@ Everything below is already unwrapped — no `.data`, no envelope. `formatMoney`
 | `useProduct(slug)` | `{ status, product, view, price, selection, pick, quantity, setQuantity, incQuantity, decQuantity, maxQuantity, canIncrease, categories, ribbons, upsells, crossSells, reviews, reload }` — `status`: `"loading" \| "ready" \| "not_found" \| "error"`; `reviews` is `{ items, page, per_page, has_next }`. |
 | `useAddToCart(p)` | `{ state, disabled, addToCart, adding, error, soldOut, needsSelection, quantity, increase, decrease, canIncrease, canDecrease, showQuantity, reset }` — `state`: `"ready" \| "adding" \| "sold_out" \| "needs_selection"`. |
 | `variantAxes(view, pick)` | `[{ key, name, selectedOption, options: [{ value, selected, disabled, outOfStock, pick }] }]`. |
-| `productPrice(rowOrView, { formatMoney })` | `{ label, compareAtLabel, onSale, isFrom, isRange, min, max }` — `label` is what to render. |
+| `productPrice(rowOrView, { formatMoney, fromLabel })` | `{ label, compareAtLabel, onSale, isFrom, isRange, min, max }` — `label` is what to render. ⚑ `fromLabel` defaults to English "From": a store in another language passes its own word once, or every variant card ships one English word. |
 | `productImages(product)` | `[{ src, name, alt }]`, de-duplicated. `[]` is legitimate → render your placeholder. |
 | `productRibbons(product)` | `[{ id, name }]` — **objects**, and the field can be absent; takes a listing row or `useProduct().product`. |
 | `productSpecs(product)` | `[{ key, label, titleLabel, value, type, number, unit, items }]` from `meta_data` — `type` is `"numeric" \| "duration" \| "location" \| "list" \| "text"`, inferred, with `number`/`unit` split out for the first two and `items` for a list. `findSpec(rows, key)` looks one up ignoring case/spaces/`_`/`-`. Never match on `label` — meta keys are free text. |
@@ -227,7 +230,7 @@ import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPri
 
 ⚑ **Render paging whenever `hasNext` is true** — `{list.hasNext && <button type="button" onClick={list.next} disabled={list.busy}>…</button>}` (append mode: `list.loadMore`); a page that renders nothing for paging ships a catalog silently capped at `per_page`. Drive filters from `useCategories()`/`useRibbons()` data via `setParams`, never from hardcoded names — a renamed ribbon must not strand a dead button.
 
-A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, ABV — read off `productSpecs(row)`.
+A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price; on a non-English store pass `fromLabel` with the store's word), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, ABV — read off `productSpecs(row)`.
 
 ⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it. ⚑ **A ribbon link inside a card that is itself a link nests `<a>` in `<a>`** — invalid, React warns. In the grid use plain labels, or link the image and title rather than the whole card; keep ribbon links on the product page.
 
@@ -336,6 +339,7 @@ The components style themselves; with no block at all they follow the app's shad
   --sfui-border: #e5e0d5;
   --sfui-radius: 0.5rem;       /* panels; controls derive from it */
   --sfui-font-heading: "Fraunces", serif;   /* body text inherits the site's font by itself */
+  /* optional: --sfui-font-label — only if the site's labels/microcopy use a second face */
 }
 ```
 

package/skills/commerce/references/storefront-ui.md

@@ -37,6 +37,7 @@ then to safe literals — an app with no block at all is already correct.
 | `--sfui-border` | hairlines, control borders | `--border` |
 | `--sfui-radius` | panels/cards (controls derive ×0.6, or set `--sfui-radius-control`) | `--radius` → `0.75rem` |
 | `--sfui-font-heading` | headings only — body text always inherits the site font | `inherit` |
+| `--sfui-font-label` | section/field labels and microcopy — set only when the site gives labels their own face (e.g. a mono label idiom) | `inherit` |
 
 **Contrast guard**: on mount each active pair is measured; a pair under 3:1 is reset
 to its default (both sides) and a `console.warn` names it. So a "my colors aren't

package/src/commerce/storefront-ui/CheckoutPage.jsx

@@ -130,6 +130,23 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
 
   const disabled = !canPlaceOrder || placing || (termsCheckbox && !termsAccepted);
 
+  // AddressFields' built-in labels are English; the shipped checkout localizes
+  // them like every other label on the page.
+  const addressLabels = {
+    first_name: tt("checkout.address.first_name"),
+    last_name: tt("checkout.address.last_name"),
+    email: tt("checkout.address.email"),
+    company: tt("checkout.address.company"),
+    address_1: tt("checkout.address.address_1"),
+    address_2: tt("checkout.address.address_2"),
+    country: tt("checkout.address.country"),
+    city: tt("checkout.address.city"),
+    state: tt("checkout.address.state"),
+    postcode: tt("checkout.address.postcode"),
+    phone: tt(phone === "required" ? "checkout.address.phone" : "checkout.address.phoneOptional"),
+  };
+  const selectPlaceholder = tt("checkout.address.select");
+
   return (
     <SfuiRoot className="sfui-checkout" aria-labelledby="sfui-checkout-title">
       <div className="sfui-checkout-inner" data-layout={layout}>
@@ -140,7 +157,7 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
 
           <section className="sfui-section sfui-address" aria-label={tt("checkout.contactTitle")}>
             <h2 className="sfui-label">{tt("checkout.contactTitle")}</h2>
-            <AddressFields which="billing" includePhone={phone !== "hidden"} />
+            <AddressFields which="billing" includePhone={phone !== "hidden"} labels={addressLabels} selectPlaceholder={selectPlaceholder} />
             {allowsShipToDifferent(shipToDifferent) && (
               <label className="sfui-checkbox">
                 <input
@@ -154,7 +171,7 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
             {checkout.shipToDifferent && (
               <>
                 <h2 className="sfui-label">{tt("checkout.shippingAddressTitle")}</h2>
-                <AddressFields which="shipping" includePhone={false} />
+                <AddressFields which="shipping" includePhone={false} labels={addressLabels} selectPlaceholder={selectPlaceholder} />
               </>
             )}
           </section>

package/src/commerce/storefront-ui/i18n/locales/de.js

@@ -60,6 +60,19 @@ export default {
   "checkout.hint.none_available": "An diese Adresse können wir leider noch nicht liefern.",
   "checkout.hint.syncing": "Lieferoptionen werden aktualisiert…",
   "checkout.hint.payment_none": "Die Kasse ist vorübergehend nicht verfügbar — keine Zahlungsart aktiviert.",
+  "checkout.address.first_name": "Vorname",
+  "checkout.address.last_name": "Nachname",
+  "checkout.address.email": "E-Mail",
+  "checkout.address.company": "Firma",
+  "checkout.address.address_1": "Adresse",
+  "checkout.address.address_2": "Adresszusatz (optional)",
+  "checkout.address.country": "Land",
+  "checkout.address.city": "Stadt",
+  "checkout.address.state": "Bundesland / Region",
+  "checkout.address.postcode": "Postleitzahl",
+  "checkout.address.phone": "Telefon",
+  "checkout.address.phoneOptional": "Telefon (optional)",
+  "checkout.address.select": "Bitte wählen…",
   "checkout.blocker.cart_loading": "Ihr Warenkorb wird geladen…",
   "checkout.blocker.empty_cart": "Ihr Warenkorb ist leer.",
   "checkout.blocker.billing_incomplete": "Füllen Sie die erforderlichen Kontaktfelder aus.",

package/src/commerce/storefront-ui/i18n/locales/en.js

@@ -70,6 +70,19 @@ export default {
   "checkout.hint.none_available": "We can't deliver to that address yet.",
   "checkout.hint.syncing": "Updating delivery options…",
   "checkout.hint.payment_none": "Checkout is temporarily unavailable — no payment method is enabled.",
+  "checkout.address.first_name": "First name",
+  "checkout.address.last_name": "Last name",
+  "checkout.address.email": "Email",
+  "checkout.address.company": "Company",
+  "checkout.address.address_1": "Address",
+  "checkout.address.address_2": "Apartment, suite (optional)",
+  "checkout.address.country": "Country",
+  "checkout.address.city": "City",
+  "checkout.address.state": "State / Region",
+  "checkout.address.postcode": "Postal code",
+  "checkout.address.phone": "Phone",
+  "checkout.address.phoneOptional": "Phone (optional)",
+  "checkout.address.select": "Select…",
   "checkout.blocker.cart_loading": "Loading your cart…",
   "checkout.blocker.empty_cart": "Your cart is empty.",
   "checkout.blocker.billing_incomplete": "Fill in the required contact fields.",

package/src/commerce/storefront-ui/i18n/locales/es.js

@@ -60,6 +60,19 @@ export default {
   "checkout.hint.none_available": "Aún no podemos hacer entregas en esa dirección.",
   "checkout.hint.syncing": "Actualizando opciones de entrega…",
   "checkout.hint.payment_none": "El pago no está disponible por el momento — no hay ningún método de pago habilitado.",
+  "checkout.address.first_name": "Nombre",
+  "checkout.address.last_name": "Apellido",
+  "checkout.address.email": "Correo electrónico",
+  "checkout.address.company": "Empresa",
+  "checkout.address.address_1": "Dirección",
+  "checkout.address.address_2": "Departamento, interior (opcional)",
+  "checkout.address.country": "País",
+  "checkout.address.city": "Ciudad",
+  "checkout.address.state": "Estado / Región",
+  "checkout.address.postcode": "Código postal",
+  "checkout.address.phone": "Teléfono",
+  "checkout.address.phoneOptional": "Teléfono (opcional)",
+  "checkout.address.select": "Selecciona…",
   "checkout.blocker.cart_loading": "Cargando tu carrito…",
   "checkout.blocker.empty_cart": "Tu carrito está vacío.",
   "checkout.blocker.billing_incomplete": "Completa los campos de contacto obligatorios.",

package/src/commerce/storefront-ui/i18n/locales/fr.js

@@ -60,6 +60,19 @@ export default {
   "checkout.hint.none_available": "Nous ne livrons pas encore à cette adresse.",
   "checkout.hint.syncing": "Mise à jour des options de livraison…",
   "checkout.hint.payment_none": "Le paiement est temporairement indisponible — aucun moyen de paiement n'est activé.",
+  "checkout.address.first_name": "Prénom",
+  "checkout.address.last_name": "Nom",
+  "checkout.address.email": "E-mail",
+  "checkout.address.company": "Société",
+  "checkout.address.address_1": "Adresse",
+  "checkout.address.address_2": "Appartement, bâtiment (facultatif)",
+  "checkout.address.country": "Pays",
+  "checkout.address.city": "Ville",
+  "checkout.address.state": "État / Région",
+  "checkout.address.postcode": "Code postal",
+  "checkout.address.phone": "Téléphone",
+  "checkout.address.phoneOptional": "Téléphone (facultatif)",
+  "checkout.address.select": "Sélectionnez…",
   "checkout.blocker.cart_loading": "Chargement de votre panier…",
   "checkout.blocker.empty_cart": "Votre panier est vide.",
   "checkout.blocker.billing_incomplete": "Renseignez les champs de contact obligatoires.",

package/src/commerce/storefront-ui/i18n/locales/ja.js

@@ -60,6 +60,19 @@ export default {
   "checkout.hint.none_available": "申し訳ありませんが、その住所への配送はまだ承っておりません。",
   "checkout.hint.syncing": "配送方法を更新しています…",
   "checkout.hint.payment_none": "現在ご購入手続きをご利用いただけません — 有効なお支払い方法がありません。",
+  "checkout.address.first_name": "名",
+  "checkout.address.last_name": "姓",
+  "checkout.address.email": "メールアドレス",
+  "checkout.address.company": "会社名",
+  "checkout.address.address_1": "住所",
+  "checkout.address.address_2": "建物名・部屋番号（任意）",
+  "checkout.address.country": "国",
+  "checkout.address.city": "市区町村",
+  "checkout.address.state": "都道府県 / 地域",
+  "checkout.address.postcode": "郵便番号",
+  "checkout.address.phone": "電話番号",
+  "checkout.address.phoneOptional": "電話番号（任意）",
+  "checkout.address.select": "選択してください",
   "checkout.blocker.cart_loading": "カートを読み込んでいます…",
   "checkout.blocker.empty_cart": "カートは空です。",
   "checkout.blocker.billing_incomplete": "必須の連絡先項目をご入力ください。",

package/src/commerce/storefront-ui/i18n/locales/pt.js

@@ -60,6 +60,19 @@ export default {
   "checkout.hint.none_available": "Ainda não entregamos nesse endereço.",
   "checkout.hint.syncing": "Atualizando opções de entrega…",
   "checkout.hint.payment_none": "A finalização está temporariamente indisponível — nenhuma forma de pagamento habilitada.",
+  "checkout.address.first_name": "Nome",
+  "checkout.address.last_name": "Sobrenome",
+  "checkout.address.email": "E-mail",
+  "checkout.address.company": "Empresa",
+  "checkout.address.address_1": "Endereço",
+  "checkout.address.address_2": "Complemento (opcional)",
+  "checkout.address.country": "País",
+  "checkout.address.city": "Cidade",
+  "checkout.address.state": "Estado / Região",
+  "checkout.address.postcode": "Código postal",
+  "checkout.address.phone": "Telefone",
+  "checkout.address.phoneOptional": "Telefone (opcional)",
+  "checkout.address.select": "Selecione…",
   "checkout.blocker.cart_loading": "Carregando seu carrinho…",
   "checkout.blocker.empty_cart": "Seu carrinho está vazio.",
   "checkout.blocker.billing_incomplete": "Preencha os campos de contato obrigatórios.",

package/src/commerce/storefront-ui/storefront-ui.css

@@ -27,6 +27,7 @@
   --_radius: var(--sfui-radius, var(--radius, 0.75rem));
   --_radius-control: var(--sfui-radius-control, calc(var(--_radius) * 0.6));
   --_font-heading: var(--sfui-font-heading, inherit);
+  --_font-label: var(--sfui-font-label, inherit);
 
   background: transparent;
   color: var(--_on-surface);
@@ -47,6 +48,7 @@
 
 .sfui-label {
   display: block;
+  font-family: var(--_font-label);
   font-size: 0.6875rem;
   font-weight: 600;
   letter-spacing: 0.08em;
@@ -379,6 +381,7 @@
 }
 .sfui-address [data-part="label"] {
   display: block;
+  font-family: var(--_font-label);
   font-size: 0.8125rem;
   font-weight: 500;
   margin-block-end: 0.375rem;
@@ -400,8 +403,9 @@
 .sfui-choice[data-selected="true"] { border-color: var(--_accent); box-shadow: inset 0 0 0 1px var(--_accent); }
 .sfui-choice input { inline-size: 1rem; block-size: 1rem; min-height: 0; margin: 0; accent-color: var(--_accent); flex-shrink: 0; }
 .sfui-choice-main { flex: 1; min-inline-size: 0; }
-.sfui-choice-title { font-size: 0.9375rem; font-weight: 500; }
-.sfui-choice-desc { font-size: 0.8125rem; color: var(--_on-subtle); margin-block-start: 0.125rem; }
+/* block, not inline: a gateway's description must land under its title */
+.sfui-choice-title { display: block; font-size: 0.9375rem; font-weight: 500; }
+.sfui-choice-desc { display: block; font-size: 0.8125rem; color: var(--_on-subtle); margin-block-start: 0.125rem; }
 .sfui-choice-cost { font-size: 0.9375rem; font-weight: 600; white-space: nowrap; }
 .sfui-chosen-single {
   display: flex;

package/src/commerce/utils/price.js

@@ -34,13 +34,15 @@ const money = (fn, n) => (typeof fn === "function" ? fn(n) : String(n ?? ""));
  *
  * @param {object} rowOrView a `list-products`/`get-product` product, or a
  *   `resolveSelection` view
- * @param {{formatMoney?: (n: number) => string}} [opts]
+ * @param {{formatMoney?: (n: number) => string, fromLabel?: string}} [opts]
+ *   `fromLabel` is the from-price prefix — "From" by default, so a store in
+ *   another language MUST pass its own word or ship one English word per card.
  * @returns {{label: string, compareAtLabel: string|null, onSale: boolean,
  *   isFrom: boolean, isRange: boolean, min: number|null, max: number|null}}
  *   `label` is what to render as the price; `compareAtLabel` is the
  *   struck-through original, or null when the product is not on sale.
  */
-export function productPrice(rowOrView, { formatMoney } = {}) {
+export function productPrice(rowOrView, { formatMoney, fromLabel = "From" } = {}) {
   const fmt = (n) => money(formatMoney, n);
   const blank = {
     label: "", compareAtLabel: null, onSale: false, isFrom: false,
@@ -85,7 +87,7 @@ export function productPrice(rowOrView, { formatMoney } = {}) {
   const price = row.price ?? null;
   const onSale = Boolean(row.on_sale);
   return {
-    label: price == null ? "" : isFrom ? `From ${fmt(price)}` : fmt(price),
+    label: price == null ? "" : isFrom ? `${fromLabel} ${fmt(price)}` : fmt(price),
     compareAtLabel: onSale && row.regular_price != null ? fmt(row.regular_price) : null,
     onSale,
     isFrom,