@base44/app-plugin-commerce 0.3.4 → 0.4.1

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

@@ -0,0 +1,504 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
+import { addressFieldSpec, attributesLabel } from "@/commerce/utils";
+import { CheckoutProvider, useCheckoutContext } from "../useCheckout";
+import { ShippingMethodPicker, PaymentMethodPicker } from "../pickers";
+import { useCart, useCountries, useFormatMoney } from "../StorefrontProvider";
+import { REQUIRED_BILLING_FIELDS } from "../address";
+import { LabelsScope, label, useResolvedLabels } from "./labels";
+import { CouponField, Totals } from "./shared";
+
+/**
+ * Checkout parts — the checkout's sections as unstyled, unworded components
+ * the store places into ITS OWN layout markup. Contract, styling
+ * (`data-part`), labels and placement: the commerce skill's
+ * install/02-storefront.md. Each part is a thin composition over `useCheckout`
+ * and the pickers; mixing a part with a custom section built on
+ * `useCheckoutContext()` is normal, and the parts are the app's source —
+ * editable when a requirement outgrows their props.
+ */
+
+const CheckoutPartsContext = createContext(null);
+
+/** Layout effect where there is a DOM; plain effect on the server (no warning). */
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * Mounts `CheckoutProvider`, resolves the page's phase once (`submitted` >
+ * `loading` > `empty` > `form` — the ordering that kills the empty-bag flash
+ * over a just-placed order), and scopes `labels`. `orderReceivedPath` is
+ * REQUIRED: the one navigation this flow performs is an explicit decision —
+ * pass the store's own receipt route, or `null` (+ `onPlaced(result)`) to own
+ * the step entirely.
+ */
+function Root({ labels, orderReceivedPath, onPlaced, options, checkout, children }) {
+  if (checkout == null && orderReceivedPath === undefined) {
+    throw new Error(
+      "<Checkout.Root> requires orderReceivedPath — the route the store's order-received page is mounted at (or null, with onPlaced, to handle the post-order step yourself). The kit never assumes a route.",
+    );
+  }
+  return (
+    <CheckoutProvider checkout={checkout} options={{ ...options, orderReceivedPath }}>
+      <LabelsScope labels={labels}>
+        <RootPhase onPlaced={onPlaced}>{children}</RootPhase>
+      </LabelsScope>
+    </CheckoutProvider>
+  );
+}
+
+function RootPhase({ onPlaced, children }) {
+  const checkout = useCheckoutContext();
+  const { status } = useCart();
+  const phase =
+    checkout.stage === "submitted"
+      ? "submitted"
+      : status === "loading"
+        ? "loading"
+        : status === "empty"
+          ? "empty"
+          : "form";
+  // A page that places <Checkout.Blockers> itself must not ALSO get the copy
+  // `PlaceOrder` renders by default — the same three reasons printed twice is a
+  // real defect an eval caught. Standalone instances register here (before
+  // paint), and the button's own copy stands down while one exists.
+  const [ownBlockers, setOwnBlockers] = useState(0);
+  const registerBlockers = useCallback((delta) => setOwnBlockers((n) => n + delta), []);
+  const value = useMemo(
+    () => ({ phase, onPlaced, hasOwnBlockers: ownBlockers > 0, registerBlockers }),
+    [phase, onPlaced, ownBlockers, registerBlockers],
+  );
+  return <CheckoutPartsContext.Provider value={value}>{children}</CheckoutPartsContext.Provider>;
+}
+
+function usePartsContext(name) {
+  const ctx = useContext(CheckoutPartsContext);
+  if (!ctx) throw new Error(`<Checkout.${name}> works inside <Checkout.Root> only.`);
+  return ctx;
+}
+
+/** Gates: children render only in the matching phase (node, or function of `{ checkout, cart }`). */
+function gate(name, match) {
+  function Gate({ children }) {
+    const { phase } = usePartsContext(name);
+    const checkout = useCheckoutContext();
+    if (phase !== match) return null;
+    return typeof children === "function"
+      ? (children({ checkout, cart: checkout.cart }) ?? null)
+      : (children ?? null);
+  }
+  Gate.displayName = `Checkout.${name}`;
+  return Gate;
+}
+
+const Submitted = gate("Submitted", "submitted");
+const Loading = gate("Loading", "loading");
+const Empty = gate("Empty", "empty");
+const Form = gate("Form", "form");
+
+/**
+ * The address form off `addressFieldSpec`: state/province appears with the
+ * right options once a country is picked, `autoComplete` tokens stay on,
+ * required marks arm on first blur, and the server's "we don't ship there"
+ * lands on the country field. `which="shipping"` renders null until
+ * `shipToDifferent`. Overrides: `inputRender` swaps the control only,
+ * `fieldRender` the whole labeled block.
+ */
+function AddressFields({
+  which = "billing",
+  include,
+  omit,
+  inputRender: InputRender,
+  fieldRender,
+  className,
+  classes,
+  labels: partLabels,
+}) {
+  const checkout = useCheckoutContext();
+  const L = useResolvedLabels(partLabels);
+  const { countries } = useCountries();
+  const idBase = useId();
+  const [touched, setTouched] = useState({});
+
+  const isBilling = which === "billing";
+  if (!isBilling && !checkout.shipToDifferent) return null;
+
+  const values = isBilling ? checkout.billing : checkout.shipping;
+  const set = isBilling ? checkout.updateBilling : checkout.updateShipping;
+  const fields = addressFieldSpec({
+    countries,
+    country: values.country,
+    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+    includeEmail: isBilling,
+    includeCompany: include ? include.includes("company") : false,
+    includePhone: include ? include.includes("phone") : true,
+  }).filter((f) => !(omit ?? []).includes(f.key));
+
+  return (
+    <div data-part="address-fields" data-which={which} className={className}>
+      {fields.map((f) => {
+        const id = `${idBase}-${which}-${f.key}`;
+        const value = values[f.key] ?? "";
+        const invalid = Boolean(touched[f.key] && f.required && !String(value).trim());
+        const dom = {
+          id,
+          value,
+          autoComplete: f.autoComplete,
+          onChange: (e) => set({ [f.key]: e && e.target ? e.target.value : e }),
+          onBlur: () => setTouched((t) => (t[f.key] ? t : { ...t, [f.key]: true })),
+        };
+        const labelText = label(L, `fields.${f.key}`);
+        if (fieldRender) {
+          return (
+            <React.Fragment key={f.key}>
+              {fieldRender({ field: f, label: labelText, invalid, options: f.options, ...dom })}
+            </React.Fragment>
+          );
+        }
+        return (
+          <div
+            key={f.key}
+            data-part="field"
+            data-key={f.key}
+            data-span={f.colSpan}
+            data-invalid={invalid || undefined}
+            className={classes?.field}
+          >
+            <label data-part="label" className={classes?.label} htmlFor={id}>
+              {labelText}
+              {f.required && (
+                <span data-part="required" aria-hidden="true">
+                  *
+                </span>
+              )}
+            </label>
+            {InputRender ? (
+              <InputRender field={f} options={f.options} invalid={invalid} {...dom} />
+            ) : f.type === "select" ? (
+              <select
+                data-part="control"
+                className={classes?.control}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              >
+                <option value="">{label(L, "fields.select_placeholder")}</option>
+                {f.options.map((o) => (
+                  <option key={o.value} value={o.value}>
+                    {o.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <input
+                data-part="control"
+                className={classes?.control}
+                type={f.type}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              />
+            )}
+            {f.key === "country" && checkout.addressError && (
+              <p data-part="error" role="alert" className={classes?.error}>
+                {checkout.addressError.message}
+              </p>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/** The deliver-elsewhere toggle. Children are its label — the store's words. */
+function ShipToDifferent({ children, className, classes }) {
+  const checkout = useCheckoutContext();
+  return (
+    <label data-part="ship-to-different" className={className}>
+      <input
+        data-part="control"
+        className={classes?.control}
+        type="checkbox"
+        checked={checkout.shipToDifferent}
+        onChange={(e) => checkout.setShipToDifferent(e.target.checked)}
+      />
+      <span data-part="label" className={classes?.label}>{children}</span>
+    </label>
+  );
+}
+
+/**
+ * The delivery choice, every branch premade: the hint line (`serverMessage`
+ * preferred over the store's own words), a radio list while there is a real
+ * choice, the chosen/auto-selected method *displayed* when there is one option
+ * (never a picker of one), null for a virtual cart. `optionRender(option)`
+ * replaces an option's content; the radio stays wired.
+ */
+function ShippingMethods({ optionRender, className, classes, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const groupName = useId();
+  return (
+    <ShippingMethodPicker>
+      {({ status, methods, chosen, syncing, hint }) => {
+        const showList = methods.length > 1;
+        return (
+          <fieldset
+            data-part="shipping-methods"
+            data-state={status}
+            data-syncing={syncing || undefined}
+            className={className}
+            aria-label={label(L, "aria.shipping_group")}
+          >
+            {hint && (
+              <p
+                data-part="hint"
+                data-severity={hint.severity}
+                className={classes?.hint}
+                role={hint.severity === "error" ? "alert" : "status"}
+              >
+                {hint.serverMessage ?? label(L, `shipping.${hint.code}`)}
+              </p>
+            )}
+            {showList &&
+              methods.map((m) => (
+                <label
+                  key={m.id}
+                  data-part="option"
+                  data-state={m.selected ? "selected" : undefined}
+                  className={classes?.option}
+                >
+                  <input
+                    data-part="option-input"
+                    type="radio"
+                    name={groupName}
+                    checked={m.selected}
+                    onChange={() => Promise.resolve(m.select()).catch(() => {})}
+                  />
+                  {optionRender ? (
+                    optionRender(m)
+                  ) : (
+                    <>
+                      <span data-part="option-label" className={classes?.["option-label"]}>{m.title}</span>
+                      <span data-part="option-cost" className={classes?.["option-cost"]}>{m.costLabel}</span>
+                    </>
+                  )}
+                </label>
+              ))}
+            {!showList && chosen && (
+              <p data-part="chosen" className={classes?.chosen}>
+                {optionRender ? (
+                  optionRender(chosen)
+                ) : (
+                  <>
+                    <span data-part="option-label" className={classes?.["option-label"]}>{chosen.title}</span>
+                    <span data-part="option-cost" className={classes?.["option-cost"]}>{chosen.costLabel}</span>
+                  </>
+                )}
+              </p>
+            )}
+          </fieldset>
+        );
+      }}
+    </ShippingMethodPicker>
+  );
+}
+
+/**
+ * How to pay — every ENABLED gateway, titles and descriptions in the admin's
+ * own words. One gateway renders as the selection it already is; none renders
+ * the store's checkout-unavailable line. `optionRender(gateway)` replaces an
+ * option's content; the radio stays wired.
+ */
+function PaymentMethods({ optionRender, className, classes, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const groupName = useId();
+  return (
+    <PaymentMethodPicker>
+      {({ gateways, selected, single, hint }) => (
+        <fieldset data-part="payment-methods" className={className} aria-label={label(L, "aria.payment_group")}>
+          {hint && (
+            <p data-part="hint" data-severity={hint.severity} className={classes?.hint} role="alert">
+              {label(L, "payment.none_available")}
+            </p>
+          )}
+          {!single &&
+            gateways.map((g) => (
+              <label
+                key={g.slug}
+                data-part="option"
+                data-state={g.selected ? "selected" : undefined}
+                className={classes?.option}
+              >
+                <input
+                  data-part="option-input"
+                  type="radio"
+                  name={groupName}
+                  checked={g.selected}
+                  onChange={g.select}
+                />
+                {optionRender ? (
+                  optionRender(g)
+                ) : (
+                  <>
+                    <span data-part="option-label" className={classes?.["option-label"]}>{g.title}</span>
+                    {g.description && (
+                      <span data-part="option-description" className={classes?.["option-description"]}>
+                        {g.description}
+                      </span>
+                    )}
+                  </>
+                )}
+              </label>
+            ))}
+          {single && selected && (
+            <p data-part="chosen" className={classes?.chosen}>
+              {optionRender ? (
+                optionRender(selected)
+              ) : (
+                <>
+                  <span data-part="option-label" className={classes?.["option-label"]}>{selected.title}</span>
+                  {selected.description && (
+                    <span data-part="option-description" className={classes?.["option-description"]}>
+                      {selected.description}
+                    </span>
+                  )}
+                </>
+              )}
+            </p>
+          )}
+        </fieldset>
+      )}
+    </PaymentMethodPicker>
+  );
+}
+
+/** The mini summary: read-only rows of what is being bought. `itemRender(item)` replaces a row. */
+function Items({ itemRender, className, classes }) {
+  const checkout = useCheckoutContext();
+  const formatMoney = useFormatMoney();
+  const items = checkout.cart?.items ?? [];
+  if (!items.length) return null;
+  return (
+    <ul data-part="items" className={className}>
+      {items.map((item) => (
+        <li key={item.item_key} data-part="row" className={classes?.row}>
+          {itemRender ? (
+            itemRender(item)
+          ) : (
+            <>
+              {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="quantity" className={classes?.quantity}>×{item.quantity}</span>
+              <span data-part="line-total" className={classes?.["line-total"]}>
+                {formatMoney(item.total)}
+              </span>
+            </>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * The blocker lines — what still stands between the customer and the order,
+ * one line per code in the store's words, gone when the order can be placed.
+ * `PlaceOrder` renders these next to the button by default; placing this part
+ * anywhere under `Checkout.Root` moves them there instead — the button's own
+ * copy stands down automatically, so the reasons are never printed twice.
+ */
+function Blockers({ standalone = true, className, classes, labels: partLabels }) {
+  const checkout = useCheckoutContext();
+  const { registerBlockers } = usePartsContext("Blockers");
+  const L = useResolvedLabels(partLabels);
+  // Registered before paint, so the button's built-in copy never flashes.
+  useCommitEffect(() => {
+    if (!standalone) return undefined;
+    registerBlockers(1);
+    return () => registerBlockers(-1);
+  }, [standalone, registerBlockers]);
+  if (checkout.canPlaceOrder) return null;
+  return (
+    <div data-part="blockers" className={className}>
+      {checkout.blockers.map((code) => (
+        <p key={code} data-part="blocker" data-code={code} className={classes?.blocker}>
+          {label(L, `blockers.${code}`)}
+        </p>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The gate, the button and the reasons, together so a disabled button always
+ * says why. Label and placing-label are the store's; the order error is the
+ * server's own words. On success `Checkout.Root`'s `onPlaced` fires (when the
+ * page owns the post-order step).
+ */
+function PlaceOrder({ showBlockers = true, className, classes, labels: partLabels }) {
+  const checkout = useCheckoutContext();
+  const { onPlaced, hasOwnBlockers } = usePartsContext("PlaceOrder");
+  const L = useResolvedLabels(partLabels);
+  const place = useCallback(async () => {
+    const res = await checkout.placeOrder(); // resolves {ok:false} — never throws
+    if (res?.ok && onPlaced) onPlaced(res.result);
+  }, [checkout, onPlaced]);
+  return (
+    <>
+      <button
+        type="button"
+        data-part="place-order"
+        data-state={checkout.placing ? "placing" : undefined}
+        className={className}
+        disabled={!checkout.canPlaceOrder || checkout.placing}
+        onClick={place}
+      >
+        {checkout.placing ? label(L, "placeOrder.placing") : label(L, "placeOrder.label")}
+      </button>
+      {checkout.orderError && (
+        <p data-part="order-error" role="alert" className={classes?.["order-error"]}>
+          {checkout.orderError.message}
+        </p>
+      )}
+      {showBlockers && !hasOwnBlockers && (
+        <Blockers standalone={false} className={classes?.blockers} labels={partLabels} />
+      )}
+    </>
+  );
+}
+
+export const Checkout = {
+  Root,
+  Submitted,
+  Loading,
+  Empty,
+  Form,
+  AddressFields,
+  ShipToDifferent,
+  ShippingMethods,
+  PaymentMethods,
+  Items,
+  CouponField,
+  Totals,
+  PlaceOrder,
+  Blockers,
+};

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

@@ -0,0 +1,119 @@
+import React, { useEffect, useRef } from "react";
+import { useCart } from "../StorefrontProvider";
+import { useCartUI } from "../cartUI";
+import { label, useResolvedLabels } from "./labels";
+
+/**
+ * Cart-drawer parts. The open/close state (plus Esc, open-on-add and
+ * close-on-navigate) stays on `<CartUIProvider>` — mount it as before; these
+ * parts render the trigger and the dialog correctly so the classic drawer
+ * bugs (a hidden panel that stays clickable, an unnamed icon button, focus
+ * lost on close) cannot be written. Everything inside the panel is the
+ * store's markup — typically `Cart.*` parts plus its own checkout link.
+ * Contract, styling and labels: the commerce skill's install/02-storefront.md.
+ */
+
+const PANEL_ID = "commerce-cart-drawer";
+
+/**
+ * The header's cart button, wired (toggle, `aria-expanded`, dialog name from
+ * `labels.aria.trigger`). The icon is the store's: pass children, or a render
+ * prop `({ count, open }) => …` to badge it with the live item count.
+ */
+function Trigger({ children, className, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const ui = useCartUI();
+  const { itemCount } = useCart();
+  const content = typeof children === "function" ? children({ count: itemCount, open: ui.open }) : children;
+  return (
+    <button
+      type="button"
+      data-part="trigger"
+      data-state={ui.open ? "open" : "closed"}
+      className={className}
+      aria-haspopup="dialog"
+      aria-expanded={ui.open}
+      aria-controls={PANEL_ID}
+      aria-label={label(L, "aria.trigger")}
+      onClick={ui.toggleCart}
+    >
+      {content}
+    </button>
+  );
+}
+
+/**
+ * The dialog done right: click-away overlay (not the close control — put a
+ * named `<CartDrawer.Close>` inside), `role="dialog"` + `aria-modal`, focus
+ * moved in on open and restored on close. Unmounted while closed by default;
+ * pass `keepMounted` to animate the slide and the closed panel is made
+ * `inert` for you. Position, size and motion are entirely the store's CSS on
+ * `[data-part="panel"]` / `[data-state]`.
+ */
+function Panel({ children, keepMounted = false, className, classes, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const ui = useCartUI();
+  const open = ui.open;
+  const rootRef = useRef(null);
+  const panelRef = useRef(null);
+  const restoreRef = useRef(null);
+
+  // Focus in on open; hand it back on close.
+  useEffect(() => {
+    if (open) {
+      restoreRef.current = typeof document !== "undefined" ? document.activeElement : null;
+      panelRef.current?.focus?.();
+    } else if (restoreRef.current) {
+      restoreRef.current.focus?.();
+      restoreRef.current = null;
+    }
+  }, [open]);
+
+  // keepMounted: a closed panel must not be clickable, tab-able or readable.
+  useEffect(() => {
+    if (!keepMounted || !rootRef.current) return;
+    rootRef.current.inert = !open;
+  }, [keepMounted, open]);
+
+  if (!keepMounted && !open) return null;
+  return (
+    <div ref={rootRef} data-part="drawer" data-state={open ? "open" : "closed"} className={className}>
+      <div data-part="overlay" className={classes?.overlay} aria-hidden="true" onClick={ui.closeCart} />
+      <aside
+        ref={panelRef}
+        id={PANEL_ID}
+        data-part="panel"
+        className={classes?.panel}
+        role="dialog"
+        aria-modal="true"
+        aria-label={label(L, "aria.drawer")}
+        tabIndex={-1}
+      >
+        {children}
+      </aside>
+    </div>
+  );
+}
+
+/** The named close control. Children are the store's icon or text. */
+function Close({ children, className, labels: partLabels }) {
+  const L = useResolvedLabels(partLabels);
+  const ui = useCartUI();
+  return (
+    <button
+      type="button"
+      data-part="close"
+      className={className}
+      aria-label={label(L, "aria.close")}
+      onClick={ui.closeCart}
+    >
+      {children}
+    </button>
+  );
+}
+
+export const CartDrawer = {
+  Trigger,
+  Panel,
+  Close,
+};