@base44/app-plugin-commerce 0.3.4 → 0.4.1

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

@@ -0,0 +1,140 @@
+import React, { createContext, useContext, useMemo } from "react";
+
+/**
+ * Labels plumbing for the parts layer. The parts ship NO customer-facing
+ * string and no English fallback: every word resolves through this chain —
+ * part `labels` prop → nearest scope (`Checkout.Root`, `OrderReceived.Root`) →
+ * `<StorefrontProvider labels={…}>` — and a missing key renders a visible
+ * `⟨copy: path⟩` placeholder plus one console warning. The full key list and
+ * a copyable English reference map live in the commerce skill's
+ * install/02-storefront.md; the store rewrites every value in its own voice.
+ */
+
+/** Every label path the parts resolve. The docs' copy example must cover exactly these. */
+export const REQUIRED_LABEL_KEYS = [
+  "placeOrder.label",
+  "placeOrder.placing",
+  "blockers.empty_cart",
+  "blockers.billing_incomplete",
+  "blockers.shipping_address_incomplete",
+  "blockers.shipping_address_required",
+  "blockers.shipping_method_required",
+  "blockers.shipping_not_available",
+  "blockers.payment_method_required",
+  "blockers.cart_loading",
+  "blockers.shipping_recalculating",
+  "shipping.missing_address",
+  "shipping.none_available",
+  "shipping.syncing",
+  "payment.none_available",
+  "coupon.placeholder",
+  "coupon.apply",
+  "coupon.remove",
+  "fields.first_name",
+  "fields.last_name",
+  "fields.email",
+  "fields.company",
+  "fields.address_1",
+  "fields.address_2",
+  "fields.country",
+  "fields.city",
+  "fields.state",
+  "fields.postcode",
+  "fields.phone",
+  "fields.select_placeholder",
+  "totals.subtotal",
+  "totals.discount",
+  "totals.shipping",
+  "totals.tax",
+  "totals.total",
+  "bank.account_name",
+  "bank.account_number",
+  "bank.bank_name",
+  "bank.sort_code",
+  "bank.iban",
+  "bank.bic",
+  "aria.trigger",
+  "aria.drawer",
+  "aria.close",
+  "aria.increase",
+  "aria.decrease",
+  "aria.remove",
+  "aria.shipping_group",
+  "aria.payment_group",
+];
+
+const LabelsContext = createContext(null);
+
+/** Two-level merge: `override`'s groups merge over `base`'s, key by key. */
+export function mergeLabels(base, override) {
+  if (!base) return override ?? null;
+  if (!override) return base;
+  const out = { ...base };
+  for (const key of Object.keys(override)) {
+    const b = base[key];
+    const o = override[key];
+    out[key] =
+      b && o && typeof b === "object" && typeof o === "object" && !Array.isArray(b) && !Array.isArray(o)
+        ? { ...b, ...o }
+        : o;
+  }
+  return out;
+}
+
+/** Scope provider: merges `labels` over whatever is already in scope. */
+export function LabelsScope({ labels, children }) {
+  const parent = useContext(LabelsContext);
+  const merged = useMemo(() => mergeLabels(parent, labels), [parent, labels]);
+  return <LabelsContext.Provider value={merged}>{children}</LabelsContext.Provider>;
+}
+
+/** The labels in scope, with a part-level override merged on top. */
+export function useResolvedLabels(partLabels) {
+  const ctx = useContext(LabelsContext);
+  return useMemo(() => mergeLabels(ctx, partLabels), [ctx, partLabels]);
+}
+
+const warned = new Set();
+function missing(path) {
+  if (!warned.has(path)) {
+    warned.add(path);
+    if (typeof console !== "undefined") {
+      console.warn(
+        `[commerce] Missing label "${path}" — the page renders a placeholder until the store's copy provides it (the key list and a reference map are in the commerce skill's install/02-storefront.md).`,
+      );
+    }
+  }
+  return `⟨copy: ${path}⟩`;
+}
+
+function walk(labels, path) {
+  let v = labels;
+  for (const key of path.split(".")) {
+    if (v == null || typeof v !== "object") return undefined;
+    v = v[key];
+  }
+  return v;
+}
+
+/** A plain label string, or the visible placeholder when unprovided. */
+export function label(labels, path) {
+  const v = walk(labels, path);
+  return typeof v === "string" && v !== "" ? v : missing(path);
+}
+
+/**
+ * An accessible-name template resolved with the item's name — the stored
+ * value may be a function `(name) => string` or a string containing `{name}`.
+ */
+export function nameLabel(labels, path, name) {
+  const v = walk(labels, path);
+  if (typeof v === "function") {
+    try {
+      return String(v(name));
+    } catch {
+      return missing(path);
+    }
+  }
+  if (typeof v === "string" && v !== "") return v.replace("{name}", String(name ?? ""));
+  return missing(path);
+}

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

@@ -0,0 +1,188 @@
+import React, { createContext, useContext } from "react";
+import { orderTotalsLines } from "@/commerce/utils";
+import { useFormatMoney } from "../StorefrontProvider";
+import { useOrderReturn } from "../useOrderReturn";
+import { LabelsScope, label, useResolvedLabels } from "./labels";
+import { totalsLabels } from "./shared";
+
+/**
+ * Order-received parts — the mandatory receipt route as placeable sections.
+ * Provider-agnostic by construction: everything renders from the return
+ * payload (`order`, `payment_link`, `payment_instructions`) — no provider is
+ * imported or named, so the stub, the Stripe file, any other card-payment
+ * implementation and the manual methods all behave identically. Contract,
+ * styling and labels: the commerce skill's install/02-storefront.md.
+ */
+
+const OrderReturnContext = createContext(null);
+
+/** Resolves `useOrderReturn()` once and scopes `labels`; the gates below branch on it. */
+function Root({ labels, children }) {
+  const ret = useOrderReturn();
+  return (
+    <LabelsScope labels={labels}>
+      <OrderReturnContext.Provider value={ret}>{children}</OrderReturnContext.Provider>
+    </LabelsScope>
+  );
+}
+
+function useReturnCtx(name) {
+  const ctx = useContext(OrderReturnContext);
+  if (!ctx) throw new Error(`<OrderReceived.${name}> works inside <OrderReceived.Root> only.`);
+  return ctx;
+}
+
+/**
+ * Gates over the five return states. Render ALL five — a blank frame while
+ * "loading" or a wordless "error" strands a real customer. Children may be a
+ * node or a function of `{ order, paymentLink, paymentInstructions, error,
+ * reload }` (render `error.message`, retry via `reload()`).
+ */
+function gate(name, match) {
+  function Gate({ children }) {
+    const ret = useReturnCtx(name);
+    if (ret.status !== match) return null;
+    return typeof children === "function"
+      ? (children({
+          order: ret.order ?? null,
+          paymentLink: ret.paymentLink ?? null,
+          paymentInstructions: ret.paymentInstructions ?? null,
+          error: ret.error ?? null,
+          reload: ret.reload,
+        }) ?? null)
+      : (children ?? null);
+  }
+  Gate.displayName = `OrderReceived.${name}`;
+  return Gate;
+}
+
+const Loading = gate("Loading", "loading");
+const Paid = gate("Paid", "paid");
+const Unpaid = gate("Unpaid", "unpaid");
+const Cancelled = gate("Cancelled", "cancelled");
+const ErrorState = gate("Error", "error");
+
+/** The order's lines, already normalized (image is `{src, alt}|null`, money pre-formatted). */
+function Items({ itemRender, className, classes }) {
+  const ret = useReturnCtx("Items");
+  const lines = ret.lines ?? [];
+  if (!lines.length) return null;
+  return (
+    <ul data-part="items" className={className}>
+      {lines.map((line, i) => (
+        <li key={`${line.sku || line.name}-${i}`} data-part="row" className={classes?.row}>
+          {itemRender ? (
+            itemRender(line)
+          ) : (
+            <>
+              {line.image ? (
+                <img data-part="media" className={classes?.media} src={line.image.src} alt={line.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}>{line.name}</span>
+                {line.attributesLabel ? (
+                  <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
+                ) : null}
+              </span>
+              <span data-part="quantity" className={classes?.quantity}>×{line.quantity}</span>
+              <span data-part="line-total" className={classes?.["line-total"]}>{line.totalLabel}</span>
+            </>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** The receipt's summary rows — an order's totals are FLAT, and this part owns that trap. */
+function Totals({ pick, className, classes, labels: partLabels }) {
+  const ret = useReturnCtx("Totals");
+  const L = useResolvedLabels(partLabels);
+  const formatMoney = useFormatMoney();
+  if (!ret.order) return null;
+  const rows = orderTotalsLines(ret.order, { formatMoney, labels: totalsLabels(L) }).filter(
+    (r) => !r.hidden && (!pick || pick.includes(r.key)),
+  );
+  return (
+    <dl data-part="totals" className={className}>
+      {rows.map((r) => (
+        <div
+          key={r.key}
+          data-part="row"
+          data-key={r.key}
+          data-emphasis={r.emphasis || undefined}
+          className={classes?.row}
+        >
+          <dt data-part="label" className={classes?.label}>{r.label}</dt>
+          <dd data-part="value" className={classes?.value}>{r.formatted}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+const BANK_FIELDS = ["account_name", "account_number", "bank_name", "sort_code", "iban", "bic"];
+
+/**
+ * How a manual/offline order gets paid — the admin's description plus each
+ * configured account's details. These ARE the store's default payment flow:
+ * an unpaid manual order's receipt must place this part. Renders null when
+ * the order carries no instructions (e.g. a card order).
+ */
+function PaymentInstructions({ className, classes, labels: partLabels }) {
+  const ret = useReturnCtx("PaymentInstructions");
+  const L = useResolvedLabels(partLabels);
+  const pi = ret.paymentInstructions;
+  if (!pi) return null;
+  const accounts = Array.isArray(pi.account_details) ? pi.account_details : [];
+  return (
+    <div data-part="payment-instructions" className={className}>
+      {pi.description && (
+        <p data-part="description" className={classes?.description}>{pi.description}</p>
+      )}
+      {accounts.map((acc, i) => (
+        <dl key={i} data-part="account" className={classes?.account}>
+          {BANK_FIELDS.filter((k) => acc?.[k]).map((k) => (
+            <div key={k} data-part="row" data-key={k} className={classes?.row}>
+              <dt data-part="label" className={classes?.label}>{label(L, `bank.${k}`)}</dt>
+              <dd data-part="value" className={classes?.value}>{acc[k]}</dd>
+            </div>
+          ))}
+        </dl>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The navigation-wrapper pattern: renders its function child ONLY when the
+ * order has a live payment link (unpaid/cancelled card orders) — the element
+ * is entirely the store's: `{({ url }) => <a href={url}>…</a>}` or whatever
+ * the store navigates with. The kit never renders the link itself.
+ */
+function PaymentLink({ children }) {
+  const ret = useReturnCtx("PaymentLink");
+  const url = ret.paymentLink?.url;
+  if (!url) return null;
+  if (typeof children !== "function") {
+    throw new Error(
+      "<OrderReceived.PaymentLink> takes a function child: ({ url }) => your own element — the kit never renders navigation.",
+    );
+  }
+  return <>{children({ url })}</>;
+}
+
+export const OrderReceived = {
+  Root,
+  Loading,
+  Paid,
+  Unpaid,
+  Cancelled,
+  Error: ErrorState,
+  Items,
+  Totals,
+  PaymentInstructions,
+  PaymentLink,
+};

package/src/commerce/storefront/parts/parts.css

@@ -0,0 +1,232 @@
+/**
+ * Layout geometry for the commerce parts — **structure only, never a look.**
+ *
+ * The parts render correct markup; this sheet makes that markup *lay out*
+ * correctly: labels above full-width controls in a two-column address grid, a
+ * cart row as media + content + controls, totals as label-left/value-right,
+ * a drawer that is actually a right-hand panel over an overlay. Without it
+ * every store re-derives the same geometry from scratch, and a storefront that
+ * gets it wrong reads as broken (staggered input widths, a product thumbnail
+ * blown up to the column width, "SetColor: Magenta1$89.00" with no gaps).
+ *
+ * What this sheet deliberately does NOT contain — the store's identity, and
+ * the reason an unstyled storefront still looks unfinished rather than
+ * finished-and-generic: no color, no background, no border (beyond zeroing the
+ * ones the browser puts on elements the parts chose, like `fieldset`), no
+ * radius, no shadow, no font, no text decoration. A release check enforces
+ * that list, so this file cannot drift into a theme.
+ *
+ * **Overriding is free.** Every rule is wrapped in `:where()`, so its
+ * specificity is 0 — any selector the store writes wins without `!important`,
+ * including a bare `[data-part="row"] { … }`. Tune the built-in geometry
+ * through the custom properties below (set them on `:root`, a page, or one
+ * part), or replace a rule outright.
+ *
+ *   :root {
+ *     --commerce-gap: 1rem;            gap between fields, rows, options
+ *     --commerce-gap-tight: 0.4rem;    label→control, name→attributes
+ *     --commerce-field-columns: 2;     address-form columns (1 on narrow)
+ *     --commerce-media-size: 4rem;     cart/summary thumbnail edge
+ *     --commerce-drawer-width: 28rem;  drawer panel width
+ *     --commerce-drawer-z: 50;         drawer stacking context
+ *   }
+ *
+ * Loaded automatically: `@/commerce/storefront` imports this file. With a
+ * bundler that does not take CSS imports from JS, delete that import line and
+ * `@import "@/commerce/storefront/parts/parts.css";` from the app's stylesheet
+ * instead.
+ */
+
+:where([data-part]) {
+  box-sizing: border-box;
+}
+
+/* ── address form ─────────────────────────────────────────────────────────── */
+:where([data-part="address-fields"]) {
+  display: grid;
+  grid-template-columns: repeat(var(--commerce-field-columns, 2), minmax(0, 1fr));
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="field"]) {
+  display: grid;
+  align-content: start;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="field"][data-span="2"]) {
+  grid-column: 1 / -1;
+}
+:where([data-part="label"]) {
+  display: block;
+}
+:where([data-part="control"]) {
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+:where([data-part="ship-to-different"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="ship-to-different"] [data-part="control"]) {
+  inline-size: auto;
+  flex: none;
+}
+
+/* ── shipping / payment choices ───────────────────────────────────────────── */
+:where([data-part="shipping-methods"], [data-part="payment-methods"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  /* the parts chose <fieldset>; neutralize what the browser draws on it */
+  margin: 0;
+  padding: 0;
+  border: 0;
+  min-inline-size: 0;
+}
+:where([data-part="option"], [data-part="chosen"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="option-input"]) {
+  flex: none;
+}
+:where([data-part="option-cost"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="option-description"]) {
+  flex-basis: 100%;
+}
+
+/* ── line rows: cart lines, checkout summary, receipt items ───────────────── */
+:where([data-part="lines"], [data-part="items"], [data-part="notices"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+:where([data-part="row"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="media"]) {
+  flex: none;
+  inline-size: var(--commerce-media-size, 4rem);
+  max-inline-size: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+}
+:where(img[data-part="media"]) {
+  display: block;
+  block-size: auto;
+}
+:where([data-part="content"]) {
+  display: grid;
+  align-content: center;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+  flex: 1 1 8rem;
+  min-inline-size: 0;
+}
+:where([data-part="controls"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  flex: none;
+}
+:where([data-part="stepper"]) {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="line-total"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="row"] [data-part="error"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+
+/* ── totals, payment instructions (label ↔ value pairs) ───────────────────── */
+:where([data-part="totals"], [data-part="account"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="totals"] > *, [data-part="account"] > *) {
+  display: flex;
+  align-items: baseline;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="value"]) {
+  margin: 0;
+  margin-inline-start: auto;
+}
+
+/* ── coupon field ─────────────────────────────────────────────────────────── */
+:where([data-part="coupon-field"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="coupon-field"] [data-part="input"]) {
+  flex: 1 1 10rem;
+  min-inline-size: 0;
+}
+:where([data-part="coupon-field"] [data-part="error"], [data-part="applied"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+:where([data-part="applied"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+
+/* ── place order + its reasons ─────────────────────────────────────────────── */
+:where([data-part="blockers"]) {
+  display: grid;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+}
+:where([data-part="blocker"], [data-part="order-error"], [data-part="hint"]) {
+  margin: 0;
+}
+
+/* ── payment instructions ─────────────────────────────────────────────────── */
+:where([data-part="payment-instructions"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="description"]) {
+  margin: 0;
+}
+
+/* ── cart drawer: a panel over an overlay, not a block in the header ───────── */
+:where([data-part="drawer"]) {
+  position: fixed;
+  inset: 0;
+  z-index: var(--commerce-drawer-z, 50);
+  display: flex;
+  justify-content: flex-end;
+}
+:where([data-part="overlay"]) {
+  position: absolute;
+  inset: 0;
+}
+:where([data-part="panel"]) {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--commerce-gap, 1rem);
+  inline-size: min(var(--commerce-drawer-width, 28rem), 100%);
+  max-inline-size: 100%;
+  block-size: 100%;
+  overflow-y: auto;
+}

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

@@ -0,0 +1,127 @@
+import React, { useState } from "react";
+import { cartTotalsLines } from "@/commerce/utils";
+import { useCart, useFormatMoney } from "../StorefrontProvider";
+import { label, useResolvedLabels } from "./labels";
+
+/**
+ * Parts shared by the cart and the checkout (exported as `Cart.CouponField` /
+ * `Checkout.CouponField` and `Cart.Totals` / `Checkout.Totals` — one
+ * component each, both read the ONE shared cart). Contract, styling and
+ * labels: the commerce skill's install/02-storefront.md.
+ */
+
+/**
+ * The coupon input + apply + applied-codes row. A store with any coupons must
+ * place this once (cart or checkout) or its codes can never be redeemed. An
+ * invalid code renders the server's own message inline. Enter applies (no
+ * <form> is rendered, so it nests safely inside one).
+ */
+export function CouponField({ className, classes, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const { cart, applyCoupon, removeCoupon } = useCart();
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+
+  const submit = async () => {
+    const value = code.trim();
+    if (!value || busy) return;
+    setBusy(true);
+    setError(null);
+    const res = await applyCoupon(value); // resolves {ok:false} — never throws
+    if (res.ok) setCode("");
+    else setError(res);
+    setBusy(false);
+  };
+
+  const applied = cart?.coupon_codes ?? [];
+  return (
+    <div data-part="coupon-field" data-busy={busy || undefined} className={className}>
+      <input
+        data-part="input"
+        className={classes?.input}
+        value={code}
+        placeholder={label(L, "coupon.placeholder")}
+        aria-label={label(L, "coupon.placeholder")}
+        disabled={busy}
+        onChange={(e) => setCode(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            submit();
+          }
+        }}
+      />
+      <button
+        type="button"
+        data-part="apply"
+        className={classes?.apply}
+        onClick={submit}
+        disabled={busy || !code.trim()}
+      >
+        {label(L, "coupon.apply")}
+      </button>
+      {error && (
+        <p data-part="error" role="alert" className={classes?.error}>
+          {error.message}
+        </p>
+      )}
+      {applied.map((c) => (
+        <span key={c} data-part="applied" className={classes?.applied}>
+          <span data-part="code" className={classes?.code}>{c}</span>
+          <button
+            type="button"
+            data-part="remove"
+            className={classes?.remove}
+            onClick={() => removeCoupon(c).catch(() => {})}
+          >
+            {label(L, "coupon.remove")}
+          </button>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The cart's summary lines — every non-hidden row from `cartTotalsLines`
+ * (discount and tax included), `data-emphasis` on the total. `pick` narrows to
+ * a subset of row keys (`["subtotal"]` for a drawer footer). Row names come
+ * from `labels.totals`; amounts stay the engine's.
+ */
+export function Totals({ pick, className, classes, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const { cart } = useCart();
+  const formatMoney = useFormatMoney();
+  if (!cart) return null;
+  const rows = cartTotalsLines(cart, { formatMoney, labels: totalsLabels(L) }).filter(
+    (r) => !r.hidden && (!pick || pick.includes(r.key)),
+  );
+  return (
+    <dl data-part="totals" className={className}>
+      {rows.map((r) => (
+        <div
+          key={r.key}
+          data-part="row"
+          data-key={r.key}
+          data-emphasis={r.emphasis || undefined}
+          className={classes?.row}
+        >
+          <dt data-part="label" className={classes?.label}>{r.label}</dt>
+          <dd data-part="value" className={classes?.value}>{r.formatted}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/** The five static row names, resolved through the labels chain (never the utils' defaults). */
+export function totalsLabels(L) {
+  return {
+    subtotal: label(L, "totals.subtotal"),
+    discount: label(L, "totals.discount"),
+    shipping: label(L, "totals.shipping"),
+    tax: label(L, "totals.tax"),
+    total: label(L, "totals.total"),
+  };
+}