@base44/app-plugin-commerce 0.9.4 → 0.10.0

package/README.md

@@ -12,7 +12,8 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated. Renders in the store's own theme, with a topbar toggle to a neutral Base44-dashboard palette and font for stores whose site theme makes the back office hard to read (colors and fonts only; remembered per browser). Localized — ships in English (default), German, Spanish, French, Japanese and Portuguese, switched by one line of code, with a documented recipe for adding any other language (no i18n dependency; see [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) and the skill's `references/admin-localization.md`).
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` and `ribbons.js` normalize the two catalog fields that are arrays of objects (`{src, name, alt}` images, `{id, name}` ribbons) rather than strings; `types.js` writes the catalog shapes down as JSDoc typedefs (`StorefrontProduct` and the rest), so what a field holds is answerable from the frontend; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
-- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings), one deliberately rendered-but-unstyled component (`AddressFields` — the checkout address form, whose state/province and `autoComplete` mechanics are where hand-rolled forms break; it ships no CSS and styles via `data-part` selectors or class props), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …) and names its return type from `storefront/types.js`, so a page reads a field's shape off the hook instead of off a backend function. Needs React and nothing else.
+- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the catalog pages you build is yours, so a brief like "make it feel like <site>" applies to the pages that carry the store's identity. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings), one deliberately rendered-but-unstyled component (`AddressFields` — the checkout address form, whose state/province and `autoComplete` mechanics are where hand-rolled forms break; it ships no CSS and styles via `data-part` selectors or class props), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …) and names its return type from `storefront/types.js`, so a page reads a field's shape off the hook instead of off a backend function. Needs React and nothing else.
+- **Shipped conversion surfaces** (`src/commerce/storefront-ui/`) — **the four pages that must convert, finished**: `<CartPage />`, `<MiniCart />` (a real dialog: portal, focus trap, scroll-lock, opens on add-to-cart), `<CheckoutPage />` (addresses, shipping/payment choice, blockers, offline instructions and card redirect) and `<OrderReceivedPage />` (all return states incl. payment instructions), plus an optional `<CartButton />` header trigger. Built on the headless layer above; themed through a paired `--sfui-*` token block with shadcn-variable fallbacks and a runtime contrast guard (an unreadable pair falls back to the defaults), functional labels localized in six languages (`storefront-ui/i18n/`), brand wording via `brand` props, behavior via `sections`/`slots`. Kit-owned and re-copied on updates — customization goes through tokens/props/slots ([`skills/commerce/references/storefront-ui.md`](./skills/commerce/references/storefront-ui.md)), never file edits.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
@@ -32,8 +33,10 @@ base44-commerce-template/
 │   └── commerce/
 │       ├── admin/      React admin UI (copy into your app's src/commerce/)
 │       ├── utils/      storefront helpers — API client, variants, price/totals rules
-│       └── storefront/ storefront React layer — headless hooks (catalog, cart,
-│                       checkout, receipt); no markup, CSS or copy ships
+│       ├── storefront/ storefront React layer — headless hooks (catalog, cart,
+│       │               checkout, receipt); no markup, CSS or copy ships
+│       └── storefront-ui/ shipped conversion surfaces — CartPage, MiniCart,
+│                       CheckoutPage, OrderReceivedPage; tokens + brand props
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/

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

@@ -352,6 +352,10 @@ async function listAttributes(sr: any): Promise<any> {
 async function getStoreInfo(sr: any): Promise<any> {
   const settings = await getSettings(sr);
   const gateways = (await sr.entities["commerce.PaymentGateway"].filter({ enabled: true }, "order", 50)) ?? [];
+  // `has_coupons` lets a storefront decide whether to render a coupon field
+  // without knowing the seed: existence only, so day-2 coupons created in the
+  // admin start showing the field with no storefront change.
+  const anyCoupon = (await sr.entities["commerce.Coupon"].filter({}, undefined, 1)) ?? [];
   // Every enabled gateway is returned — the admin's Payments settings are the
   // single switch. `online: true` marks the card option (place-order answers
   // with a payment page to redirect to); everything else settles manually.
@@ -363,6 +367,7 @@ async function getStoreInfo(sr: any): Promise<any> {
       description: g.description ?? "",
       online: isCardGateway(g.slug),
     })),
+    has_coupons: anyCoupon.length > 0,
     countries: COUNTRIES,
     currencies: CURRENCIES,
   };

package/package.json

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

package/scripts/install.js

@@ -198,6 +198,9 @@
     // headless shipping/payment pickers, order-received hook. Logic only, no
     // visual components: the shopfront's look stays the app's to design.
     { label: "storefront", from: ["src", "commerce", "storefront"], to: ["src", "commerce", "storefront"] },
+    // Shipped conversion surfaces — cart page, cart drawer, checkout,
+    // order-received — complete and tested; themed via tokens + brand props.
+    { label: "storefront-ui", from: ["src", "commerce", "storefront-ui"], to: ["src", "commerce", "storefront-ui"] },
     // Commerce skill — SKILL.md, install/post-install guides, references/
     // and docs/, the guidance agents read before working on the store.
     { label: "skills", from: ["skills", "commerce"], to: [".agents", "skills", "commerce"] },

package/skills/commerce/SKILL.md

@@ -54,56 +54,52 @@ and stop — never edit admin screens. Other:
   takes manual (`offline`) payment and works end to end; cards are a late,
   deliberate step ([`installation/install.md`](./installation/install.md)).
 
-## The storefront: logic is premade, UI never is
-
-**The UI is yours, all of it** — every page, element, class and word of copy.
-The kit deliberately ships **no markup and no CSS anywhere**; a brief like
-"make it feel like <site>" is your work, done as you would with no kit. Encode
-that identity **once** — design classes in `index.css`, spent across every
-page — not as decoration re-typed on every element;
-[`installation/install.md`](./installation/install.md) opens with the
-method.
-
-**The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
-repricing, variant resolution, cart state, coupon redemption, order-return
-verification, cart-drawer state. Each returns **plain states and handlers**
-(`status` to branch on, arrays to map, callbacks) — you write every element and
-attribute from them. **Never re-implement what a hook does** — that is where
-storefront bugs cluster.
-
-One deliberate exception: **the checkout address form ships rendered**, as the
-unstyled `<AddressFields>` component (the state/province field, `autoComplete`
-tokens and address errors are exactly where hand-rolled forms break). Style it
-with your classes; everything around it stays yours.
-
-It ships **no copy**, either: where a state needs words you get the state
-(`buy.state`, `hint.code`, `blockers`) and write the words in the store's voice.
-A kit sentence rendered into every store is how storefronts end up alike.
+## The storefront: the catalog is yours, the conversion surfaces ship
+
+**The catalog UI — collection and product page — is yours, all of it**: every
+element, class and word of copy. A brief like "make it feel like <site>" is your
+work, done as you would with no kit. Encode that identity **once** — design
+classes in `index.css`, spent across every page — not as decoration re-typed on
+every element; [`installation/install.md`](./installation/install.md) opens with
+the method. Its logic ships as **headless hooks** (`@/commerce/storefront`) —
+variant resolution, cart state, pricing — returning plain states and handlers
+(`status` to branch on, arrays to map); **never re-implement what a hook does**,
+and where a state needs words you get the state (`buy.state`) and write them in
+the store's voice.
+
+**The conversion surfaces — cart page, cart drawer, checkout, order received —
+ship finished** (`@/commerce/storefront-ui`): complete components with every
+state handled and worded in six locales. Your job there is mounting them,
+one `.sfui` theme-token block (paired colors — invisible text is structurally
+impossible), and `brand` wording props. Never rebuild one, never edit their
+files (kit updates re-copy the directory); day-2 changes go through
+[`references/storefront-ui.md`](./references/storefront-ui.md).
 
 ```jsx
-import { useCart, CartLine } from "@/commerce/storefront";
-const { status, cart } = useCart();   // branch on status, map cart.items into YOUR rows
+import { useProductList } from "@/commerce/storefront";        // catalog: YOUR pages on the hooks
+import { CheckoutPage } from "@/commerce/storefront-ui";       // conversion: mount, theme, brand
 ```
 
 The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
 restyle it, add pages, rework flows ([`docs/api-admin.md`](./docs/api-admin.md)
 is the backend it talks to).
 
-Four rules the API enforces — a storefront that skips them cannot complete a
-purchase. In React the hooks implement all four; your markup renders what they
-hand back (API-level statements for non-React clients:
+Three rules the API enforces on the pages you build — plus what the shipped
+surfaces already cover (API-level statements for non-React clients:
 [`docs/api-storefront.md`](./docs/api-storefront.md)):
 
 1. A product with variants needs **one selector per attribute**, resolved to a
    `variation_id` (`useProduct` + `variantAxes`).
-2. Checkout must **recalculate shipping from the address and send a choice**
-   (`useCheckout` — automatic).
-3. **`/order-received` must exist** and render the return state, including a
-   manual order's payment instructions (`useOrderReturn`).
-4. **Never advertise what isn't configured** — no free-shipping banner without
-   a real rate, no coupon codes without a field to redeem them in.
-
-A fifth that breaks nothing but flattens the catalog, and is skipped most often:
+2. **`/order-received` must exist** — mount the shipped `<OrderReceivedPage />`;
+   every payment link returns there.
+3. **Never advertise what isn't configured** — no free-shipping banner without a
+   real rate, no coupon codes named in your copy (the shipped surfaces show the
+   redemption field by themselves when coupons exist).
+
+Shipping recalculation, payment choice, blockers and the offline/card order
+flows are the shipped checkout's job — not rules for you anymore.
+
+A rule that breaks nothing but flattens the catalog, and is skipped most often:
 **ribbons belong in both the grid and the product page**, each linking to its
 filtered listing. They are the merchant's own merchandising.
 
@@ -123,11 +119,12 @@ as one file and arrive with the installer (above).
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`installation/install.md`](./installation/install.md) | installing — all three stages: admin mount, storefront pages, then the seed payload | 59K |
+| [`installation/install.md`](./installation/install.md) | installing — all three stages: admin mount, storefront pages, then the seed payload | 51K |
 | [`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 stage 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 | 10K |
+| [`references/storefront-ui.md`](./references/storefront-ui.md) | changing the shipped cart/drawer/checkout/order-received surfaces: props, slots, tokens, locales, restyling | 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 (open by default; login-gated, verified buyers), moderation | 6K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |

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

@@ -2,7 +2,7 @@
 
 The raw HTTP/SDK surface behind a customer-facing shopfront. **A React storefront should not call most of it directly** — `src/commerce/storefront/` ships the logic layer, and this file is the reference for what lies beyond it, for non-React and headless clients, and for the exact payloads and error codes.
 
-**Logic is premade, UI never is.** In a React app every surface here — listing, product page, cart, checkout, the receipt, reviews — has a headless hook in `@/commerce/storefront` ([`../installation/install.md`](../installation/install.md) is the surface, one line per export). The hooks own the API calls and the branching below and hand you a view-model; **all markup, styling and copy are yours** — nothing in the kit renders UI or ships a word of customer-facing text. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
+**Logic is premade.** In a React app every surface here — listing, product page, cart, checkout, the receipt, reviews — has a headless hook in `@/commerce/storefront` ([`../installation/install.md`](../installation/install.md) is the surface, one line per export), and the conversion surfaces (cart page, drawer, checkout, order received) additionally ship as **finished components** in `@/commerce/storefront-ui` — a React app mounts those rather than building them. The hooks own the API calls and the branching below and hand you a view-model; on the pages you build, markup, styling and copy are yours. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
 
 Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)