@base44/app-plugin-commerce 0.3.4 → 0.4.0

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,186 @@
+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="name" className={classes?.name}>{line.name}</span>
+              {line.attributesLabel ? (
+                <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
+              ) : null}
+              <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/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"),
+  };
+}