@base44/app-plugin-commerce 0.3.4 → 0.4.1

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

@@ -0,0 +1,150 @@
+---
+read_when: "A cart row, checkout section or receipt region needs structure the parts' props can't express, and you are about to build it on the raw hooks."
+---
+
+# Custom sections on the raw hooks
+
+The parts (`Cart.*`, `CartDrawer.*`, `Checkout.*`, `OrderReceived.*`) are thin
+compositions over the hooks below — same providers, same shared state — so
+**replacing one section while keeping the others is normal**: a bespoke
+shipping selector between `<Checkout.AddressFields>` and
+`<Checkout.PaymentMethods>` reads the same checkout the parts do.
+
+Work down this ladder; each rung is cheaper than the next:
+
+1. **`classes` / CSS** on `data-part` — almost every "the part looks wrong" is this rung.
+2. **Labels** — a wording problem is a copy-file problem, never a code problem.
+3. **`…Render` overrides** — `optionRender`, `lineRender`, `itemRender`, `inputRender`/`fieldRender`: your element, the part's wiring.
+4. **This file** — rebuild one section on its hook.
+5. **Edit the part's source** (`src/commerce/storefront/parts/`) — legitimate when a *user requirement* exceeds the props; the edited part is the store's code to maintain.
+
+Never re-implement what a hook does (quantity clamps, totals math, repricing,
+drawer state) — that is where storefront bugs cluster. And keep the parts'
+guarantees when you replace them: every state worded, busy scoped to the row,
+a disabled button that says why.
+
+## What the custom-section hooks resolve to
+
+| Call | Resolves to |
+|---|---|
+| `useCartLine(item)` | `{ quantity, setQuantity, increase, decrease, remove, pending, error, canIncrease, canDecrease, maxQuantity, atMax, atMin }` — optimistic quantity, clicks coalesced (~250ms), rollback on rejection. `pending` is **this row's** flag: true while its request is out, false only after the new cart view lands — the only mutation-settled signal (`useCart().status` never returns to `"loading"`). |
+| `useCartUI()` | `{ open, openCart, closeCart, toggleCart }` — the drawer state on `<CartUIProvider>` (Esc, open-on-add, close-on-navigate included). |
+| `useCheckoutContext()` | the address (`billing`, `updateBilling`, `shipping`, `updateShipping`, `shipToDifferent`, `setShipToDifferent`, `missingBillingFields`, `addressError`), the choices (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`, `paymentMethods`, `paymentMethod`, `setPaymentMethod`, `selectedGateway`), and the gate (`blockers`, `canPlaceOrder`, `placing`, `stage`, `orderError`, `placeOrder`) — plus `cart`. Works under `<Checkout.Root>` (or your own `<CheckoutProvider>`). |
+| `useOrderReturn()` | `{ status, order, lines, paymentLink, paymentInstructions, error, reload }` — `status`: `"loading" \| "paid" \| "unpaid" \| "cancelled" \| "error"`; `lines` normalized (`image` is `{src, alt}\|null`, `totalLabel` pre-formatted); an order's totals are **flat** (`order.total`, no `order.totals`). |
+| `cartTotalsLines(cart, { formatMoney, labels })` / `orderTotalsLines(order, …)` | `[{ key, label, amount, formatted, hidden, emphasis }]` — keys `subtotal` `discount` `shipping` `tax` `total`; discount/tax are produced and flagged `hidden` when zero, so a mapping renderer can't drop them. |
+| `addressFieldSpec({ countries, country, required, includeEmail })` | `[{ key, label, type, required, autoComplete, options, colSpan }]` — the state field appears (as a select where the country carries states) once `country` is passed. |
+| `ShippingMethodPicker` / `PaymentMethodPicker` | render-prop components the parts wrap — `children({ status, methods, chosen, mustChoose, single, syncing, hint, … })` / `children({ gateways, selected, single, hint })`; every option decorated with `selected`, `select()`, `costLabel`. |
+
+## Reference wiring
+
+Words below come from the same copy file the parts read (`STORE_COPY`) — a
+custom section never hardcodes them.
+
+**A custom cart row** — `<CartLine>` binds `useCartLine` per row without a
+hook-in-a-loop:
+
+```jsx
+{cart.items.map((item) => (
+  <CartLine key={item.item_key} line={item}>
+    {(l) => (
+      <li aria-busy={l.pending}>          {/* busy scope is THIS row, never the cart */}
+        {item.name} {attributesLabel(item.attributes)} {formatMoney(item.total)}
+        <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
+                aria-label={STORE_COPY.aria.decrease(item.name)}>−</button>
+        {l.quantity}
+        <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
+                aria-label={STORE_COPY.aria.increase(item.name)}>+</button>
+        <button onClick={l.remove} disabled={l.pending}
+                aria-label={STORE_COPY.aria.remove(item.name)}>×</button>
+        {l.error && <p role="alert">{l.error.message}</p>}
+      </li>
+    )}
+  </CartLine>
+))}
+```
+
+Give repeated controls unique accessible names (the item's name in the label)
+— three identical "Remove" buttons are ambiguous to a screen reader and to a
+script driving the page.
+
+**A custom shipping step** — the picker encodes the branching a checkout must
+not skip:
+
+```jsx
+<ShippingMethodPicker>
+  {({ hint, mustChoose, methods, chosen }) => (
+    <fieldset>{/* renders null for a virtual cart */}
+      {hint && <p role={hint.severity === "error" ? "alert" : "status"}>
+        {hint.serverMessage ?? STORE_COPY.shipping[hint.code]}</p>}
+      {mustChoose && methods.map((m) => (
+        <label key={m.id}>
+          <input type="radio" name="ship" checked={m.selected} onChange={m.select} />
+          {m.title} {m.costLabel}
+        </label>
+      ))}
+      {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+    </fieldset>
+  )}
+</ShippingMethodPicker>
+```
+
+Never render `cart.chosen_shipping_method` directly — it is a rate id; `chosen`
+arrives resolved. A single option still *shows* what it is, never a picker of
+one. `PaymentMethodPicker` is the same shape over `gateways` (titles and
+descriptions are the admin's copy — render them, don't invent your own).
+
+**A custom address form** — bind the spec, never a hand-typed field list:
+
+```jsx
+function AddressFields({ which }) {
+  const c = useCheckoutContext();
+  const { countries } = useCountries();     // [] until store info lands — never null
+  const isBilling = which === "billing";
+  const values = isBilling ? c.billing : c.shipping;
+  const set = isBilling ? c.updateBilling : c.updateShipping;
+  const fields = addressFieldSpec({
+    countries, country: values.country,
+    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+    includeEmail: isBilling,                // one email per order, on billing
+  });
+  return fields.map((f) => (
+    <div key={f.key}>
+      <label htmlFor={`${which}-${f.key}`}>{STORE_COPY.fields[f.key]}{f.required && " *"}</label>
+      {f.type === "select" ? (
+        <select id={`${which}-${f.key}`} value={values[f.key] ?? ""} autoComplete={f.autoComplete}
+                onChange={(e) => set({ [f.key]: e.target.value })}>
+          <option value="">{STORE_COPY.fields.select_placeholder}</option>
+          {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+        </select>
+      ) : (
+        <input id={`${which}-${f.key}`} type={f.type} value={values[f.key] ?? ""}
+               autoComplete={f.autoComplete} onChange={(e) => set({ [f.key]: e.target.value })} />
+      )}
+      {/* "we don't ship there" is an address-level error — it belongs on country */}
+      {f.key === "country" && c.addressError && <span role="alert">{c.addressError.message}</span>}
+    </div>
+  ));
+}
+```
+
+⚑ Passing `country` is what makes the state/province field appear — rates and
+taxes match on country *plus* state, so a form without it silently mis-prices
+US/CA/AU orders. ⚑ Keep every `autoComplete` token — it is what makes browser
+autofill work.
+
+**A custom place-order region** — the gate explains itself:
+
+```jsx
+<button type="button" onClick={c.placeOrder} disabled={!c.canPlaceOrder || c.placing}>
+  {c.placing ? STORE_COPY.placeOrder.placing : STORE_COPY.placeOrder.label}
+</button>
+{c.orderError && <p role="alert">{c.orderError.message}</p>}
+{!c.canPlaceOrder && c.blockers.map((code) => <p key={code}>{STORE_COPY.blockers[code]}</p>)}
+```
+
+`placeOrder` is safe as a direct `onClick` handler (an event is not read as
+order fields) and resolves `{ ok, result }` / `{ ok: false, error }` without
+throwing. ⚑ Keep the `stage === "submitted"` guard above any empty-cart branch
+— placing an order clears the cart, and without the guard the page flashes
+"your bag is empty" over a just-placed order (`Checkout.Root`'s gates encode
+this ordering; a fully hand-built page must re-encode it).

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

@@ -0,0 +1,99 @@
+---
+read_when: "You are writing the CSS for the cart, drawer, checkout or receipt — the parts' look."
+---
+
+# Styling the parts
+
+The parts ship **layout geometry and nothing else** (`src/commerce/storefront/parts/parts.css`,
+loaded automatically by `@/commerce/storefront`): field grids, labels above
+full-width controls, media as a fixed square, rows as media + content +
+controls with the money pushed right, totals as label-left/value-right, the
+drawer as a right-hand panel over a full-viewport overlay. Nothing in it
+carries color, background, border, radius, shadow, font or text decoration — a
+release check enforces that — so an unstyled store reads as *unfinished*, never
+as broken, and the look is entirely yours.
+
+**Every rule is wrapped in `:where()`, so its specificity is 0.** A plain
+`[data-part="row"] { display: grid }` in your stylesheet wins — no `!important`,
+no cascade fights, no need to know what the sheet did.
+
+## Two ways in, one vocabulary
+
+```css
+/* index.css — selectors, next to the store's design classes */
+[data-part="control"] { … }
+[data-part="option"][data-state="selected"] { … }
+[data-part="row"][data-pending] { opacity: .55; }
+```
+
+```jsx
+{/* or classes, keyed by the same data-part names */}
+<Cart.Lines className="bag" classes={{ row: "bag-row", media: "bag-thumb", "line-total": "price" }} />
+```
+
+Tailwind reaches inner parts with arbitrary variants
+(`className="[&_[data-part=option]]:choice-row"`) or `@apply` inside a design
+class. Either way the names are the ones below.
+
+## The minimum that makes a store look designed
+
+⚑ **Style the controls.** Browser-default inputs are a white box in a system
+font — on a dark or branded storefront that alone reads as unfinished:
+
+```css
+[data-part="control"], [data-part="input"] {
+  border: …; background: …; color: inherit; font: inherit; padding: …;
+}
+[data-part="control"]:focus-visible { outline: …; }      /* keep a visible focus ring */
+[data-part="field"][data-invalid] [data-part="control"] { border-color: …; }
+```
+
+Then, in the store's own values: the labels (`[data-part="label"]` — size,
+tracking, case), the option rows (`[data-part="option"]` — padding, border,
+and the `[data-state="selected"]` treatment, which is the one control customers
+look for), the totals (`[data-part="value"]`, `[data-emphasis]` for the total
+line), the buttons (`[data-part="place-order"]`, `apply`, `remove`,
+`increase`/`decrease`), the notices (`[data-part="error"]`, `blocker`, `hint` —
+`[data-severity="error"]` marks the loud ones), and the drawer surface
+(`[data-part="panel"]` needs a background of its own, `[data-part="overlay"]` a
+scrim).
+
+**The parts add no outer margins** — space *between* sections comes from the
+containers you wrap them in (`gap` on your checkout grid, your aside, your
+drawer panel's column).
+
+## Tuning the built-in geometry
+
+Set these anywhere — `:root`, a page, one part — instead of rewriting the rules:
+
+| Custom property | Default | Controls |
+|---|---|---|
+| `--commerce-gap` | `1rem` | fields, rows, options, panel sections |
+| `--commerce-gap-tight` | `0.4rem` | label→control, name→attributes, stepper |
+| `--commerce-field-columns` | `2` | address-form columns (set `1` in a narrow aside or a media query) |
+| `--commerce-media-size` | `4rem` | cart/summary thumbnail edge |
+| `--commerce-drawer-width` | `28rem` | drawer panel width |
+| `--commerce-drawer-z` | `50` | drawer stacking order (raise above a sticky header) |
+
+## `data-part` inventory
+
+| Part root | Inner `data-part`s | State attributes |
+|---|---|---|
+| `address-fields`; `ship-to-different` | field · label · required · control · error | `data-which`, `data-key`, `data-span`, `data-invalid` |
+| `shipping-methods` `payment-methods` | hint · option · option-input · option-label · option-cost / option-description · chosen | `data-state="selected"`, `data-syncing`, `data-severity` |
+| `lines` `items`; `notices` | row · media · content · name · attributes · controls · stepper · increase · decrease · quantity · remove · line-total · error; notice | `data-pending`, `data-empty`, `data-code` |
+| `totals`; `payment-instructions` | row · label · value; description · account | `data-key`, `data-emphasis` |
+| `coupon-field` | input · apply · error · applied · code · remove | `data-busy` |
+| `place-order` · `order-error` · `blockers` | blocker | `data-state="placing"`, `data-code` |
+| `trigger` · `drawer` | overlay · panel; `close` | `data-state="open\|closed"` |
+
+`media` is an `<img>` when the line has an image and an empty `<div
+data-part="media" data-empty>` when it doesn't — same box either way, so style
+the placeholder (`[data-empty]`) rather than letting it render as a hole.
+
+## When CSS isn't enough
+
+A control that needs different markup takes the part's render override
+(`inputRender`, `optionRender`, `lineRender`, `itemRender`, `fieldRender`) —
+your element, the part's wiring. A whole section that needs different structure
+drops to its hook: [`./storefront-custom.md`](./storefront-custom.md).

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

@@ -51,3 +51,7 @@ DOM is briefly right about the *intent* and wrong about the *state*.
   (`/order-received?order_id=…&order_key=…` — the ids come back in
   `placeOrder`'s result, and `commerce/admin-orders` `search` has the order
   either way).
+- **Sweep for unfinished copy.** A part whose label is missing renders a
+  visible `⟨copy: some.path⟩` placeholder. `⟨copy:` must appear on **no**
+  page the script visits — finding one means the store's copy file is
+  incomplete, a build defect on par with a broken button.

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -12,6 +12,7 @@ import {
   storefrontErrorCode,
   storefrontErrorMessage,
 } from "@/commerce/utils";
+import { LabelsScope } from "./parts/labels";
 
 /**
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
@@ -26,7 +27,9 @@ import {
  *   it, so the cart badge and the cart page read different carts.
  *
  * Pass `base44`, or `store={createStorefront(base44)}` when other modules need
- * the same client.
+ * the same client. `labels` (optional) is the store's copy map for the parts
+ * layer — pass it once here and every part resolves its words from it (the
+ * key list and example live in the skill's install/02-storefront.md).
  *
  * What lives here, and why it must not be duplicated per page: the client (it
  * owns the cart_token lifecycle); store info, cached for the session —
@@ -38,7 +41,7 @@ import {
 
 const StorefrontContext = createContext(null);
 
-export function StorefrontProvider({ base44, store, children }) {
+export function StorefrontProvider({ base44, store, labels, children }) {
   const client = useMemo(
     () => store ?? createStorefront(base44),
     [store, base44],
@@ -109,7 +112,11 @@ export function StorefrontProvider({ base44, store, children }) {
     () => ({ client, info, infoError, cart, cartError, mutationError, runCart, clearCart }),
     [client, info, infoError, cart, cartError, mutationError, runCart, clearCart],
   );
-  return <StorefrontContext.Provider value={value}>{children}</StorefrontContext.Provider>;
+  return (
+    <StorefrontContext.Provider value={value}>
+      <LabelsScope labels={labels}>{children}</LabelsScope>
+    </StorefrontContext.Provider>
+  );
 }
 
 /** Advanced escape hatch: the raw provider state. Prefer the hooks below. */

package/src/commerce/storefront/index.js

@@ -60,6 +60,23 @@
  *
  * The catalog and product surfaces are where the design freedom lives: these
  * hooks hand you resolved data, and the rendering is entirely yours.
+ *
+ * **Parts** — for the four commodity surfaces only (cart, drawer, checkout,
+ * order-received), `Checkout.*` / `Cart.*` / `CartDrawer.*` /
+ * `OrderReceived.*` render each section's correct semantic markup with zero
+ * copy and zero navigation: you place them in YOUR layout, and supply every
+ * word through `labels` (chain: part prop → page Root → `<StorefrontProvider
+ * labels={…}>`; a missing key renders a visible `⟨copy: …⟩` placeholder).
+ * They carry **layout geometry and nothing else** (`parts/parts.css`: field
+ * grids, row and thumbnail sizing, totals rows, the drawer panel — no color,
+ * type or border, every rule at zero specificity), so an unstyled store looks
+ * unfinished but never broken; the look arrives as your CSS on
+ * `data-part`/`data-state`, or via `className`/`classes`. Contract tables, the
+ * copy example and the `data-part` inventory: the commerce skill's
+ * install/02-storefront.md — use the parts from there, not from these files.
+ * They compose the hooks above, so dropping one section down to its hook is
+ * normal; they are also the app's own source, editable when a requirement
+ * outgrows their props.
  */
 export {
   StorefrontProvider,
@@ -81,6 +98,18 @@ export {
   isShippingAddressComplete,
 } from "./address";
 
+// ── parts: guided sections for the commodity surfaces ──────────────────────
+// The parts' layout geometry (field grids, row/media sizing, totals rows, the
+// drawer panel) — structure only, no look, every rule at zero specificity so
+// the store's CSS wins. See parts/parts.css for the custom properties.
+import "./parts/parts.css";
+
+export { Checkout } from "./parts/checkout";
+export { Cart } from "./parts/cart";
+export { CartDrawer } from "./parts/drawer";
+export { OrderReceived } from "./parts/orderReceived";
+export { REQUIRED_LABEL_KEYS } from "./parts/labels";
+
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
 export { useProduct, useAddToCart } from "./useProduct";

package/src/commerce/storefront/parts/cart.jsx

@@ -0,0 +1,167 @@
+import React from "react";
+import { attributesLabel } from "@/commerce/utils";
+import { useCart, useFormatMoney } from "../StorefrontProvider";
+import { CartLine } from "../useCartLine";
+import { label, nameLabel, useResolvedLabels } from "./labels";
+import { CouponField, Totals } from "./shared";
+
+/**
+ * Cart parts — the bag's sections, unstyled and unworded, for a cart page or
+ * a drawer's contents alike. Contract, styling (`data-part`), labels and
+ * placement: the commerce skill's install/02-storefront.md. These read the
+ * ONE shared cart on `<StorefrontProvider>`; there is no `Cart.Root`.
+ *
+ * `Loading` / `Empty` / `Ready` are gates: children render only in the
+ * matching cart status, so branching on emptiness-while-loading cannot be
+ * written. Children may be a node or a function of `{ cart, itemCount }`.
+ * The checkout link belongs in the store's own markup inside `<Cart.Ready>` —
+ * no part renders navigation.
+ */
+function gate(name, match) {
+  function Gate({ children }) {
+    const { status, cart, itemCount } = useCart();
+    if (status !== match) return null;
+    return typeof children === "function" ? (children({ cart, itemCount }) ?? null) : (children ?? null);
+  }
+  Gate.displayName = `Cart.${name}`;
+  return Gate;
+}
+
+const Loading = gate("Loading", "loading");
+const Empty = gate("Empty", "empty");
+const Ready = gate("Ready", "ready");
+
+/**
+ * The line rows, with the interaction premade per row (optimistic quantity,
+ * coalesced clicks, rollback, per-row `pending` — never a cart-wide busy
+ * state). `lineRender(item, controls)` replaces a row wholesale; `item.slug`
+ * is there when the store's row links to the product page.
+ */
+function Lines({ lineRender, className, classes, labels: partLabels }) {
+  const { status, cart } = useCart();
+  const formatMoney = useFormatMoney();
+  const L = useResolvedLabels(partLabels);
+  if (status !== "ready") return null;
+  return (
+    <ul data-part="lines" className={className}>
+      {cart.items.map((item) => (
+        <CartLine key={item.item_key} line={item}>
+          {(l) =>
+            lineRender ? (
+              lineRender(item, l)
+            ) : (
+              <li
+                data-part="row"
+                data-pending={l.pending || undefined}
+                aria-busy={l.pending}
+                className={classes?.row}
+              >
+                {item.image ? (
+                  <img data-part="media" className={classes?.media} src={item.image} alt="" loading="lazy" />
+                ) : (
+                  <div data-part="media" data-empty="" className={classes?.media} />
+                )}
+                <span data-part="content" className={classes?.content}>
+                  <span data-part="name" className={classes?.name}>{item.name}</span>
+                  {attributesLabel(item.attributes) ? (
+                    <span data-part="attributes" className={classes?.attributes}>
+                      {attributesLabel(item.attributes)}
+                    </span>
+                  ) : null}
+                </span>
+                <span data-part="controls" className={classes?.controls}>
+                  <span data-part="stepper" className={classes?.stepper}>
+                    <button
+                      type="button"
+                      data-part="decrease"
+                      className={classes?.decrease}
+                      onClick={l.decrease}
+                      disabled={!l.canDecrease || l.pending}
+                      aria-label={nameLabel(L, "aria.decrease", item.name)}
+                    >
+                      −
+                    </button>
+                    <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
+                    <button
+                      type="button"
+                      data-part="increase"
+                      className={classes?.increase}
+                      onClick={l.increase}
+                      disabled={!l.canIncrease || l.pending}
+                      aria-label={nameLabel(L, "aria.increase", item.name)}
+                    >
+                      +
+                    </button>
+                  </span>
+                  <button
+                    type="button"
+                    data-part="remove"
+                    className={classes?.remove}
+                    onClick={l.remove}
+                    disabled={l.pending}
+                    aria-label={nameLabel(L, "aria.remove", item.name)}
+                  >
+                    ×
+                  </button>
+                </span>
+                <span data-part="line-total" className={classes?.["line-total"]}>
+                  {formatMoney(item.total)}
+                </span>
+                {l.error && (
+                  <p data-part="error" role="alert" className={classes?.error}>{l.error.message}</p>
+                )}
+                {item.purchasable && !item.purchasable.ok && (
+                  <p data-part="error" data-code={item.purchasable.code} role="alert" className={classes?.error}>
+                    {item.purchasable.error}
+                  </p>
+                )}
+              </li>
+            )
+          }
+        </CartLine>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * What auto-dropped and why, in the server's own words — expired coupons
+ * (`coupon_notices`) and vanished products (`removed_items`). Renders null
+ * when there is nothing to say; place it above the lines so a disappearing
+ * row never goes unexplained.
+ */
+function Notices({ className, classes }) {
+  const { cart } = useCart();
+  const notices = [
+    ...(cart?.coupon_notices ?? []).map((n, i) => ({
+      key: `coupon-${n.code ?? i}`,
+      code: n.error_code,
+      text: n.error,
+    })),
+    ...(cart?.removed_items ?? []).map((r, i) => ({
+      key: `removed-${r.item_key ?? i}`,
+      code: r.code,
+      text: r.reason,
+    })),
+  ];
+  if (!notices.length) return null;
+  return (
+    <ul data-part="notices" role="status" className={className}>
+      {notices.map((n) => (
+        <li key={n.key} data-part="notice" data-code={n.code} className={classes?.notice}>
+          {n.text}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export const Cart = {
+  Loading,
+  Empty,
+  Ready,
+  Lines,
+  Notices,
+  CouponField,
+  Totals,
+};