@base44/app-plugin-commerce 0.9.5 → 0.10.0

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

@@ -0,0 +1,33 @@
+import React from "react";
+import { useCart, useCartUI } from "@/commerce/storefront";
+import { t } from "./i18n/index.js";
+
+/**
+ * Optional header trigger for the MiniCart: a bag icon with a live item-count
+ * badge, wired to the cart drawer. The header itself stays the store's brand
+ * surface — use this for the wiring and restyle it via .sfui-cart-button /
+ * .sfui-cart-badge (or replace it with your own button calling
+ * `useCartUI().toggleCart` and rendering `useCart().itemCount`).
+ */
+export function CartButton({ className = "", label }) {
+  const { toggleCart } = useCartUI();
+  const { itemCount } = useCart();
+  return (
+    <button
+      type="button"
+      className={`sfui sfui-cart-button ${className}`}
+      onClick={toggleCart}
+      aria-label={label ?? t("minicart.button")}
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" aria-hidden="true">
+        <path d="M6 7h12l-1 13H7L6 7Z" strokeLinejoin="round" />
+        <path d="M9 9V6a3 3 0 0 1 6 0v3" strokeLinecap="round" />
+      </svg>
+      {itemCount > 0 && (
+        <span className="sfui-cart-badge" aria-hidden="true">
+          {itemCount > 99 ? "99+" : itemCount}
+        </span>
+      )}
+    </button>
+  );
+}

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

@@ -0,0 +1,140 @@
+import React, { useState } from "react";
+import { Link } from "react-router-dom";
+import { useCart, useStoreInfo } from "@/commerce/storefront";
+import { makeT } from "./i18n/index.js";
+import {
+  CartLineRow,
+  CouponField,
+  ErrorState,
+  LoadingState,
+  SfuiRoot,
+  TotalsBlock,
+  couponVisible,
+  readOrderNote,
+  writeOrderNote,
+} from "./internal.jsx";
+
+const BRAND_KEYS = {
+  title: "cart.title",
+  summaryTitle: "cart.summaryTitle",
+  checkoutCta: "cart.checkoutCta",
+  continueShopping: "cart.continueShopping",
+  emptyTitle: "cart.empty.title",
+  emptyBody: "cart.empty.body",
+  emptyCta: "cart.empty.cta",
+  note: "cart.taxNote",
+};
+
+/**
+ * The routed cart page — complete: line rows with row-scoped quantity editing,
+ * the full totals breakdown, coupons, optional order notes, a designed empty
+ * state. Mount it on a route inside the store's layout; everything inside is
+ * shipped and tested.
+ *
+ * @param {object} props
+ * @param {Record<string,string>} [props.brand] wording overrides (title,
+ *   summaryTitle, checkoutCta, continueShopping, emptyTitle, emptyBody,
+ *   emptyCta, note) — the store's voice; labels beyond these are localized
+ *   via ./i18n.
+ * @param {object} [props.sections] `{ coupon: "auto"|true|false, notes: false,
+ *   continueShopping: true, taxNote: true }`
+ * @param {string} [props.checkoutHref="/checkout"]
+ * @param {string} [props.continueHref="/"]
+ * @param {(item) => string} [props.productHref] line names link to the product
+ *   when given; plain text otherwise (never a guessed route).
+ * @param {object} [props.slots] `{ lineExtra?({item,line}), aboveSummary?(),
+ *   emptyState?() }`
+ */
+export function CartPage({
+  brand,
+  sections = {},
+  checkoutHref = "/checkout",
+  continueHref = "/",
+  productHref,
+  slots = {},
+}) {
+  const tt = makeT(brand, BRAND_KEYS);
+  const cartApi = useCart();
+  const { info } = useStoreInfo();
+  const [note, setNote] = useState(readOrderNote);
+  const { status, cart } = cartApi;
+  const {
+    coupon = "auto",
+    notes = false,
+    continueShopping = true,
+    taxNote = true,
+  } = sections;
+
+  return (
+    <SfuiRoot className="sfui-cart" aria-labelledby="sfui-cart-title">
+      <div className="sfui-cart-inner">
+        <div>
+          <h1 id="sfui-cart-title" className="sfui-heading sfui-h1" style={{ marginBlockEnd: "1rem" }}>
+            {tt("cart.title")}
+          </h1>
+          {status === "loading" && <LoadingState />}
+          {status === "empty" &&
+            (slots.emptyState ? (
+              slots.emptyState()
+            ) : (
+              <div className="sfui-state">
+                <h2 className="sfui-heading sfui-h2">{tt("cart.empty.title")}</h2>
+                <p className="sfui-muted">{tt("cart.empty.body")}</p>
+                <Link className="sfui-btn sfui-btn-inline" to={continueHref}>
+                  {tt("cart.empty.cta")}
+                </Link>
+              </div>
+            ))}
+          {status === "ready" && cartApi.error && <ErrorState onRetry={cartApi.refresh} />}
+          {status === "ready" && (
+            <ul className="sfui-lines">
+              {cart.items.map((item) => (
+                <CartLineRow
+                  key={item.item_key}
+                  item={item}
+                  tt={tt}
+                  productHref={productHref}
+                  lineExtra={slots.lineExtra}
+                />
+              ))}
+            </ul>
+          )}
+        </div>
+
+        {status === "ready" && (
+          <aside className="sfui-panel sfui-summary" aria-label={tt("cart.summaryTitle")}>
+            <h2 className="sfui-heading sfui-h2">{tt("cart.summaryTitle")}</h2>
+            {slots.aboveSummary && slots.aboveSummary()}
+            {couponVisible(coupon, cart, info) && <CouponField tt={tt} />}
+            {notes && (
+              <div>
+                <label className="sfui-label" htmlFor="sfui-cart-note">
+                  {tt("cart.notes.label")}
+                </label>
+                <textarea
+                  id="sfui-cart-note"
+                  value={note}
+                  placeholder={tt("cart.notes.placeholder")}
+                  onChange={(e) => {
+                    setNote(e.target.value);
+                    writeOrderNote(e.target.value);
+                  }}
+                />
+              </div>
+            )}
+            <TotalsBlock cart={cart} tt={tt} />
+            {taxNote && <p className="sfui-note">{tt("cart.taxNote")}</p>}
+            <Link className="sfui-btn" to={checkoutHref}>
+              {tt("cart.checkoutCta")}
+            </Link>
+            {continueShopping && (
+              <Link className="sfui-btn sfui-btn-ghost" to={continueHref}>
+                {tt("cart.continueShopping")}
+              </Link>
+            )}
+          </aside>
+        )}
+      </div>
+    </SfuiRoot>
+  );
+}

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

@@ -0,0 +1,287 @@
+import React, { useState } from "react";
+import { Link } from "react-router-dom";
+import {
+  AddressFields,
+  CheckoutProvider,
+  PaymentMethodPicker,
+  ShippingMethodPicker,
+  useCheckoutContext,
+  useStoreInfo,
+} from "@/commerce/storefront";
+import { makeT } from "./i18n/index.js";
+import {
+  CouponField,
+  LoadingState,
+  SfuiRoot,
+  TotalsBlock,
+  couponVisible,
+  readOrderNote,
+  writeOrderNote,
+} from "./internal.jsx";
+
+const BRAND_KEYS = {
+  title: "checkout.title",
+  contactTitle: "checkout.contactTitle",
+  shippingTitle: "checkout.shippingTitle",
+  paymentTitle: "checkout.paymentTitle",
+  summaryTitle: "checkout.summaryTitle",
+  submitLabel: "checkout.placeOrder",
+  termsLabel: "checkout.terms",
+  emptyTitle: "checkout.empty.title",
+  emptyCta: "checkout.empty.cta",
+};
+
+/**
+ * The complete checkout: contact + billing address (AddressFields), optional
+ * separate delivery address, shipping choice, payment choice, order summary,
+ * blockers, placeOrder — with the offline payment-instructions flow and the
+ * card payment-link redirect handled by useCheckout. Mount it on a route; a
+ * store customizes it through the theme tokens, `brand` wording and
+ * `sections`, never by editing this file.
+ *
+ * @param {object} props
+ * @param {Record<string,string>} [props.brand] wording overrides (title,
+ *   contactTitle, shippingTitle, paymentTitle, summaryTitle, submitLabel,
+ *   termsLabel, emptyTitle, emptyCta).
+ * @param {"two-column"|"single"} [props.layout="two-column"]
+ * @param {object} [props.sections] `{ coupon: "auto"|true|false, notes: false,
+ *   phone: "optional"|"required"|"hidden", shipToDifferent: true,
+ *   termsCheckbox: false }` — `phone: "required"` is enforced by marking the
+ *   field required in the address spec via requiredBillingFields.
+ * @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).
+ */
+export function CheckoutPage({
+  brand,
+  layout = "two-column",
+  sections = {},
+  continueHref = "/",
+  onPlaced,
+}) {
+  const {
+    phone = "optional",
+    shipToDifferent: allowShipToDifferent = true,
+  } = sections;
+  const options = {
+    ...(onPlaced ? { orderReceivedPath: null } : {}),
+    ...(phone === "required"
+      ? { requiredBillingFields: ["first_name", "last_name", "address_1", "city", "country", "email", "phone"] }
+      : {}),
+  };
+  return (
+    <CheckoutProvider options={options}>
+      <CheckoutBody
+        brand={brand}
+        layout={layout}
+        sections={{ ...sections, phone, shipToDifferent: allowShipToDifferent }}
+        continueHref={continueHref}
+        onPlaced={onPlaced}
+      />
+    </CheckoutProvider>
+  );
+}
+
+function CheckoutBody({ brand, layout, sections, continueHref, onPlaced }) {
+  const tt = makeT(brand, BRAND_KEYS);
+  const checkout = useCheckoutContext();
+  const { info } = useStoreInfo();
+  const [note, setNote] = useState(readOrderNote);
+  const [termsAccepted, setTermsAccepted] = useState(false);
+  const { coupon = "auto", notes = false, phone, shipToDifferent, termsCheckbox = false } = sections;
+  const { cart, stage, blockers, canPlaceOrder, placing, orderError } = checkout;
+
+  const submit = async () => {
+    const extra = note.trim() ? { customer_note: note.trim() } : {};
+    const res = await checkout.placeOrder(extra);
+    if (res.ok) {
+      writeOrderNote("");
+      if (onPlaced) onPlaced(res.result);
+    }
+  };
+
+  // The submitted guard renders BEFORE the empty-cart branch: placeOrder clears
+  // the cart, so checking cart state first repaints "empty" over a just-placed
+  // order for the frames before the browser navigates away.
+  if (stage === "submitted") {
+    return (
+      <SfuiRoot className="sfui-checkout">
+        <div className="sfui-checkout-inner">
+          <LoadingState label={tt("checkout.submitted")} />
+        </div>
+      </SfuiRoot>
+    );
+  }
+
+  if (cart === null || (cart && !cart.items?.length)) {
+    return (
+      <SfuiRoot className="sfui-checkout">
+        <div className="sfui-checkout-inner">
+          <div className="sfui-state">
+            <h1 className="sfui-heading sfui-h1">{tt("checkout.empty.title")}</h1>
+            <Link className="sfui-btn sfui-btn-inline" to={continueHref}>
+              {tt("checkout.empty.cta")}
+            </Link>
+          </div>
+        </div>
+      </SfuiRoot>
+    );
+  }
+
+  const disabled = !canPlaceOrder || placing || (termsCheckbox && !termsAccepted);
+
+  return (
+    <SfuiRoot className="sfui-checkout" aria-labelledby="sfui-checkout-title">
+      <div className="sfui-checkout-inner" data-layout={layout}>
+        <div className="sfui-checkout-form">
+          <h1 id="sfui-checkout-title" className="sfui-heading sfui-h1">
+            {tt("checkout.title")}
+          </h1>
+
+          <section className="sfui-section sfui-address" aria-label={tt("checkout.contactTitle")}>
+            <h2 className="sfui-label">{tt("checkout.contactTitle")}</h2>
+            <AddressFields which="billing" includePhone={phone !== "hidden"} />
+            {allowsShipToDifferent(shipToDifferent) && (
+              <label className="sfui-checkbox">
+                <input
+                  type="checkbox"
+                  checked={checkout.shipToDifferent}
+                  onChange={(e) => checkout.setShipToDifferent(e.target.checked)}
+                />
+                {tt("checkout.shipToDifferent")}
+              </label>
+            )}
+            {checkout.shipToDifferent && (
+              <>
+                <h2 className="sfui-label">{tt("checkout.shippingAddressTitle")}</h2>
+                <AddressFields which="shipping" includePhone={false} />
+              </>
+            )}
+          </section>
+
+          <ShippingMethodPicker>
+            {({ methods, mustChoose, single, chosen, hint }) => (
+              <section className="sfui-section" aria-label={tt("checkout.shippingTitle")}>
+                <h2 className="sfui-label">{tt("checkout.shippingTitle")}</h2>
+                {mustChoose && (
+                  <div className="sfui-choices" role="radiogroup" aria-label={tt("checkout.shippingTitle")}>
+                    {methods.map((m) => (
+                      <label key={m.id} className="sfui-choice" data-selected={m.selected || undefined}>
+                        <input type="radio" name="sfui-shipping" checked={m.selected} onChange={m.select} />
+                        <span className="sfui-choice-main">
+                          <span className="sfui-choice-title">{m.title}</span>
+                        </span>
+                        <span className="sfui-choice-cost">
+                          {m.cost === 0 ? tt("common.free") : m.costLabel}
+                        </span>
+                      </label>
+                    ))}
+                  </div>
+                )}
+                {single && chosen && (
+                  <div className="sfui-chosen-single">
+                    <span>{chosen.title}</span>
+                    <span>{chosen.cost === 0 ? tt("common.free") : chosen.costLabel}</span>
+                  </div>
+                )}
+                {hint && (
+                  <p
+                    className={hint.severity === "error" ? "sfui-error" : "sfui-note"}
+                    role={hint.severity === "error" ? "alert" : "status"}
+                  >
+                    {hint.serverMessage ?? tt(`checkout.hint.${hint.code}`)}
+                  </p>
+                )}
+              </section>
+            )}
+          </ShippingMethodPicker>
+
+          <PaymentMethodPicker>
+            {({ gateways, mustChoose, single, selected, hint }) => (
+              <section className="sfui-section" aria-label={tt("checkout.paymentTitle")}>
+                <h2 className="sfui-label">{tt("checkout.paymentTitle")}</h2>
+                {mustChoose && (
+                  <div className="sfui-choices" role="radiogroup" aria-label={tt("checkout.paymentTitle")}>
+                    {gateways.map((g) => (
+                      <label key={g.slug} className="sfui-choice" data-selected={g.selected || undefined}>
+                        <input type="radio" name="sfui-payment" checked={g.selected} onChange={g.select} />
+                        <span className="sfui-choice-main">
+                          <span className="sfui-choice-title">{g.title}</span>
+                          {g.description && <span className="sfui-choice-desc">{g.description}</span>}
+                        </span>
+                      </label>
+                    ))}
+                  </div>
+                )}
+                {single && selected && (
+                  <div className="sfui-chosen-single">
+                    <span className="sfui-choice-main">
+                      <span className="sfui-choice-title">{selected.title}</span>
+                      {selected.description && <span className="sfui-choice-desc">{selected.description}</span>}
+                    </span>
+                  </div>
+                )}
+                {hint && (
+                  <p className="sfui-error" role="alert">
+                    {tt("checkout.hint.payment_none")}
+                  </p>
+                )}
+              </section>
+            )}
+          </PaymentMethodPicker>
+
+          {notes && (
+            <section className="sfui-section">
+              <label className="sfui-label" htmlFor="sfui-checkout-note">
+                {tt("checkout.notes.label")}
+              </label>
+              <textarea
+                id="sfui-checkout-note"
+                value={note}
+                placeholder={tt("checkout.notes.placeholder")}
+                onChange={(e) => {
+                  setNote(e.target.value);
+                  writeOrderNote(e.target.value);
+                }}
+              />
+            </section>
+          )}
+        </div>
+
+        <aside className="sfui-panel sfui-summary" aria-label={tt("checkout.summaryTitle")}>
+          <h2 className="sfui-heading sfui-h2">{tt("checkout.summaryTitle")}</h2>
+          {couponVisible(coupon, cart, info) && <CouponField tt={tt} />}
+          <TotalsBlock cart={cart} tt={tt} />
+          {termsCheckbox && (
+            <label className="sfui-checkbox">
+              <input type="checkbox" checked={termsAccepted} onChange={(e) => setTermsAccepted(e.target.checked)} />
+              {tt("checkout.terms")}
+            </label>
+          )}
+          <button type="button" className="sfui-btn" onClick={submit} disabled={disabled}>
+            {placing ? tt("checkout.placing") : tt("checkout.placeOrder")}
+          </button>
+          {/* A disabled button must say why: one line per blocker, localized. */}
+          {!canPlaceOrder && blockers.length > 0 && (
+            <ul className="sfui-blockers" aria-live="polite">
+              {blockers.map((code) => (
+                <li key={code}>{tt(`checkout.blocker.${code}`)}</li>
+              ))}
+            </ul>
+          )}
+          {orderError && (
+            <p className="sfui-error" role="alert">
+              {orderError.code === "card_payment_in_preview"
+                ? tt("checkout.error.card_payment_in_preview")
+                : orderError.message}
+            </p>
+          )}
+        </aside>
+      </div>
+    </SfuiRoot>
+  );
+}
+
+function allowsShipToDifferent(section) {
+  return section !== false;
+}

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

@@ -0,0 +1,128 @@
+import React, { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { Link } from "react-router-dom";
+import { useCart, useCartUI, useFormatMoney } from "@/commerce/storefront";
+import { makeT } from "./i18n/index.js";
+import { CartLineRow, LoadingState, SfuiRoot } from "./internal.jsx";
+
+const BRAND_KEYS = {
+  title: "minicart.title",
+  checkoutLabel: "minicart.checkout",
+  viewCartLabel: "minicart.viewCart",
+  emptyTitle: "minicart.empty.title",
+  emptyCta: "minicart.empty.cta",
+};
+
+/**
+ * The cart drawer — a complete overlay: portal, backdrop, dialog semantics,
+ * focus trap, body scroll-lock. Mount it ONCE inside the store's layout (never
+ * on a route); it opens and closes through <CartUIProvider>'s state, so
+ * `useAddToCart` flows and the store's cart button drive it with no extra
+ * wiring. Escape and close-on-navigate are the provider's job already.
+ *
+ * @param {object} props
+ * @param {Record<string,string>} [props.brand] wording overrides (title,
+ *   checkoutLabel, viewCartLabel, emptyTitle, emptyCta).
+ * @param {"right"|"left"} [props.side="right"]
+ * @param {string} [props.checkoutHref="/checkout"]
+ * @param {string} [props.cartHref] renders a "view cart" link when given.
+ * @param {(item) => string} [props.productHref]
+ */
+export function MiniCart({ brand, side = "right", checkoutHref = "/checkout", cartHref, productHref }) {
+  const tt = makeT(brand, BRAND_KEYS);
+  const { open, closeCart } = useCartUI();
+  const { status, cart, itemCount } = useCart();
+  const formatMoney = useFormatMoney();
+  const panelRef = useRef(null);
+  const restoreRef = useRef(null);
+
+  // Focus management + scroll lock, for exactly the open window.
+  useEffect(() => {
+    if (!open) return;
+    restoreRef.current = document.activeElement;
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
+    const trap = (e) => {
+      if (e.key !== "Tab" || !panelRef.current) return;
+      const focusables = panelRef.current.querySelectorAll(
+        'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])',
+      );
+      if (!focusables.length) return;
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", trap);
+    return () => {
+      document.removeEventListener("keydown", trap);
+      document.body.style.overflow = prevOverflow;
+      restoreRef.current?.focus?.();
+    };
+  }, [open]);
+
+  if (!open || typeof document === "undefined") return null;
+
+  return createPortal(
+    <SfuiRoot as="div">
+      <div className="sfui-drawer-backdrop" onClick={closeCart} aria-hidden="true" />
+      <div
+        className="sfui-drawer"
+        data-side={side}
+        role="dialog"
+        aria-modal="true"
+        aria-label={tt("minicart.title")}
+        tabIndex={-1}
+        ref={panelRef}
+      >
+        <div className="sfui-drawer-head">
+          <h2 className="sfui-heading sfui-h2">{tt("minicart.title")}</h2>
+          <button type="button" className="sfui-drawer-close" onClick={closeCart} aria-label={tt("minicart.close")}>
+            ×
+          </button>
+        </div>
+        <div className="sfui-drawer-body">
+          {status === "loading" && <LoadingState />}
+          {status === "empty" && (
+            <div className="sfui-state">
+              <h3 className="sfui-heading sfui-h2">{tt("minicart.empty.title")}</h3>
+              <button type="button" className="sfui-btn sfui-btn-ghost sfui-btn-inline" onClick={closeCart}>
+                {tt("minicart.empty.cta")}
+              </button>
+            </div>
+          )}
+          {status === "ready" && (
+            <ul className="sfui-lines">
+              {cart.items.map((item) => (
+                <CartLineRow key={item.item_key} item={item} tt={tt} productHref={productHref} compact />
+              ))}
+            </ul>
+          )}
+        </div>
+        {status === "ready" && (
+          <div className="sfui-drawer-foot">
+            <div className="sfui-drawer-subtotal">
+              <span>{tt("minicart.subtotal")}</span>
+              <span>{formatMoney(cart.totals?.subtotal)}</span>
+            </div>
+            <Link className="sfui-btn" to={checkoutHref} onClick={closeCart}>
+              {tt("minicart.checkout")}
+            </Link>
+            {cartHref && (
+              <Link className="sfui-btn sfui-btn-ghost" to={cartHref} onClick={closeCart}>
+                {tt("minicart.viewCart")} {itemCount ? `(${itemCount})` : ""}
+              </Link>
+            )}
+          </div>
+        )}
+      </div>
+    </SfuiRoot>,
+    document.body,
+  );
+}