@base44/app-plugin-commerce 0.10.3 → 0.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "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

@@ -119,7 +119,7 @@ Open a file when its work starts — not while planning.
 | [`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-ui.md`](./references/storefront-ui.md) | changing the shipped cart/drawer/checkout/order-received surfaces: props, slots, tokens, locales, restyling | 9K |
 | [`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/references/storefront-ui.md

@@ -89,6 +89,13 @@ on those two hooks is normal and supported.
   `termsCheckbox: true` gates place-order on an accepted checkbox worded by
   `brand.termsLabel`.
 - `continueHref="/"` — where the empty state sends people.
+- `slots`: `{ afterContact(ctx), beforeSubmit(ctx), aboveSummary(ctx) }` — your
+  markup at three fixed points: `afterContact` between the address and the
+  delivery choice, `beforeSubmit` at the end of the form column, `aboveSummary`
+  above the totals. Every slot receives `{ cart, checkout, note, setNote }`.
+  `setNote` is the one way a slot puts something on the order: it writes the
+  order note, which submits as `customer_note` and shows on the receipt and in
+  the admin's order view (`place-order` accepts no other free field).
 - `onPlaced={(order) => …}` — replaces the default `/order-received` navigation.
   Advanced: the default flow already handles the card redirect and the offline
   receipt; use this only when the user explicitly wants a custom post-order flow,
@@ -151,5 +158,10 @@ element itself** (`select[data-part="control"]`, never `[data-part="control"] in
   `useProduct(...)`'s `upsells`/`crossSells` with `useCart().addItem` — one-click
   Add only for products without attributes (variants answer `400 variation_required`).
 - **B2B-ish checkout**: `sections={{ phone: "required", termsCheckbox: true, notes: true }}`.
+- **Gift wrap + gift note** (any extra field the customer fills at checkout):
+  `slots={{ beforeSubmit: ({ note, setNote }) => <GiftOptions note={note} onChange={setNote} /> }}`
+  — a checkbox and a textarea that write `"Gift wrap: yes\nGift note: …"` into
+  the note. It lands on the order as `customer_note`. Never copy
+  `CheckoutPage.jsx` to add a field.
 - **Custom thank-you flow**: keep `/order-received` mounted (payment links return
   there), add `onPlaced` only for the extra hop the user asked for.

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

@@ -1,5 +1,5 @@
 ---
-read_when: "You are about to drive the storefront from a browser script — adding to the cart, stepping quantities, filling the checkout, placing an order."
+read_when: "You are about to drive the storefront from a browser script — adding to the cart, stepping quantities, opening the checkout."
 skip_when: "You are not scripting the storefront."
 ---
 
@@ -37,17 +37,13 @@ DOM is briefly right about the *intent* and wrong about the *state*.
   `/checkout` — URL plus a field of the form on screen — before emptying the
   cart or moving on. Tearing the cart down while still on the cart page, or
   mid-navigation, produces an empty checkout that reads as a routing bug.
-- **Filling the checkout.** Every field is a controlled React input, so writing
-  `el.value` changes nothing React sees. Use the harness's own fill (it
-  dispatches `input` + `change`) — never lift the native setter off
-  `HTMLInputElement.prototype` and call `descriptor.set(v)`: detached from the
-  element it throws `Illegal invocation`, and the workaround it is reaching for
-  is what the fill helper already does.
-- **`placeOrder` ends the page.** It navigates with `window.location.assign`,
-  so a script that placed an order loses its page context and can land back at
-  `/` — while the order itself was created normally. That is the hard
-  navigation, not a broken redirect. The confirmation is reachable at any time
-  from a fresh navigation to `orderReceivedUrl(result)`
-  (`/order-received?order_id=…&order_key=…` — the ids come back in
-  `placeOrder`'s result, and `commerce/admin-orders` `search` has the order
-  either way).
+- **The checkout is shipped code — never fill it, never place an order.** Its
+  logic is the kit's and already tested; what is yours is how it looks. Open
+  `/checkout` with items in the cart and check that: it renders inside the
+  store's chrome, the `.sfui` tokens took (colours, radius, heading face match
+  the rest of the site), the `brand` copy reads in the store's voice, and
+  nothing overflows on a phone-width viewport. Do not type into its fields and
+  do not submit — an order is real store data the owner sees in `/store-admin`,
+  and the platform's "delete the record you created" rule does not fit it (the
+  entities are admin-only; a raw delete skips the engine that releases stock).
+  Empty the cart when you are done.

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

@@ -48,6 +48,11 @@ const BRAND_KEYS = {
  *   phone: "optional"|"required"|"hidden", shipToDifferent: true,
  *   termsCheckbox: false }` — `phone: "required"` is enforced by marking the
  *   field required in the address spec via requiredBillingFields.
+ * @param {object} [props.slots] `{ afterContact?(ctx), beforeSubmit?(ctx),
+ *   aboveSummary?(ctx) }` — the store's own markup at three fixed points; every
+ *   slot receives `{ cart, checkout, note, setNote }`. `setNote` is the one way
+ *   a slot puts something on the order: it writes the order note, which submits
+ *   as `customer_note` (place-order accepts no other free field).
  * @param {string} [props.continueHref="/"] where the empty state sends people.
  * @param {(order) => void} [props.onPlaced] replaces the default
  *   order-received navigation (advanced; the default flow is complete).
@@ -56,6 +61,7 @@ export function CheckoutPage({
   brand,
   layout = "two-column",
   sections = {},
+  slots = {},
   continueHref = "/",
   onPlaced,
 }) {
@@ -75,6 +81,7 @@ export function CheckoutPage({
         brand={brand}
         layout={layout}
         sections={{ ...sections, phone, shipToDifferent: allowShipToDifferent }}
+        slots={slots}
         continueHref={continueHref}
         onPlaced={onPlaced}
       />
@@ -82,7 +89,7 @@ export function CheckoutPage({
   );
 }
 
-function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
+function CheckoutBody({ brand, layout, sections, slots, continueHref, onPlaced }) {
   const tt = makeT(brand, BRAND_KEYS);
   const checkout = useCheckoutContext();
   const { info } = useStoreInfo();
@@ -90,6 +97,11 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
   const [termsAccepted, setTermsAccepted] = useState(false);
   const { coupon = "auto", notes = false, phone, shipToDifferent, termsCheckbox = false } = sections;
   const { cart, stage, blockers, canPlaceOrder, placing, orderError } = checkout;
+  const updateNote = (value) => {
+    setNote(value);
+    writeOrderNote(value);
+  };
+  const slotArgs = { cart, checkout, note, setNote: updateNote };
 
   const submit = async () => {
     const extra = note.trim() ? { customer_note: note.trim() } : {};
@@ -175,6 +187,7 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
               </>
             )}
           </section>
+          {slots.afterContact && slots.afterContact(slotArgs)}
 
           <ShippingMethodPicker>
             {({ methods, mustChoose, single, chosen, hint }) => (
@@ -256,17 +269,16 @@ function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
                 id="sfui-checkout-note"
                 value={note}
                 placeholder={tt("checkout.notes.placeholder")}
-                onChange={(e) => {
-                  setNote(e.target.value);
-                  writeOrderNote(e.target.value);
-                }}
+                onChange={(e) => updateNote(e.target.value)}
               />
             </section>
           )}
+          {slots.beforeSubmit && slots.beforeSubmit(slotArgs)}
         </div>
 
         <aside className="sfui-panel sfui-summary" aria-label={tt("checkout.summaryTitle")}>
           <h2 className="sfui-heading sfui-h2">{tt("checkout.summaryTitle")}</h2>
+          {slots.aboveSummary && slots.aboveSummary(slotArgs)}
           {couponVisible(coupon, cart, info) && <CouponField tt={tt} />}
           <TotalsBlock cart={cart} tt={tt} />
           {termsCheckbox && (

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

@@ -54,10 +54,12 @@ export function CartLineRow({ item, tt, productHref, compact = false, lineExtra
   const formatMoney = useFormatMoney();
   const attrs = attributesLabel(item.attributes);
   const href = productHref ? productHref(item) : null;
+  // storefront-cart sends `image` as a bare URL string; order lines carry {src, alt}.
+  const imageSrc = typeof item.image === "string" ? item.image : item.image?.src;
   return (
     <li className="sfui-line" data-pending={line.pending || undefined} data-compact={compact || undefined}>
       <div className="sfui-line-media" aria-hidden="true">
-        {item.image?.src && <img src={item.image.src} alt="" loading="lazy" />}
+        {imageSrc && <img src={imageSrc} alt="" loading="lazy" />}
       </div>
       <div className="sfui-line-main">
         <p className="sfui-line-name">