@base44/app-plugin-commerce 0.1.19 → 0.2.1

package/src/commerce/storefront/blocks/AddressFieldsBlock.jsx

@@ -0,0 +1,96 @@
+import React from "react";
+import { useAddressForm } from "../useAddressForm";
+import { useCheckoutContext } from "../useCheckout";
+
+/**
+ * The checkout address form, rendered from the field spec — so `state` is
+ * collected (rates and taxes match on country + state), the country select
+ * never maps a null list, and browser autofill works.
+ *
+ *   <AddressFieldsBlock />                       // billing
+ *   <AddressFieldsBlock which="shipping" />      // a separate delivery address
+ *
+ * Needs a `<CheckoutProvider>` above it (`<CheckoutBlock/>` supplies one).
+ *
+ * @param {{which?: "billing"|"shipping", className?: string, legend?: string,
+ *   includeCompany?: boolean, includePhone?: boolean}} props
+ */
+export function AddressFieldsBlock({
+  which = "billing",
+  className = "",
+  legend,
+  includeCompany = false,
+  includePhone = true,
+}) {
+  const { fields, set, countriesLoading } = useAddressForm(which, { includeCompany, includePhone });
+
+  return (
+    <fieldset data-commerce={`address-${which}`} className={className}>
+      {legend && <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">{legend}</legend>}
+      <div className="grid grid-cols-2 gap-3">
+        {fields.map((f) => (
+          <label
+            key={f.key}
+            className={f.colSpan === 2 ? "col-span-2" : "col-span-2 sm:col-span-1"}
+          >
+            <span className="block text-xs text-muted-foreground">
+              {f.label}
+              {f.required && <span aria-hidden> *</span>}
+            </span>
+            {f.type === "select" ? (
+              <select
+                data-commerce={`address-field-${f.key}`}
+                value={f.value}
+                required={f.required}
+                onChange={(e) => set(f.key, e.target.value)}
+                autoComplete={f.autoComplete}
+                disabled={f.key === "country" && countriesLoading}
+                className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+              >
+                <option value="">
+                  {f.key === "country" && countriesLoading ? "Loading…" : `Select ${f.label.toLowerCase()}`}
+                </option>
+                {f.options.map((o) => (
+                  <option key={o.value} value={o.value}>
+                    {o.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <input
+                data-commerce={`address-field-${f.key}`}
+                type={f.type}
+                value={f.value}
+                required={f.required}
+                onChange={(e) => set(f.key, e.target.value)}
+                autoComplete={f.autoComplete}
+                className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+              />
+            )}
+            {f.error && (
+              <span role="alert" className="mt-1 block text-xs text-destructive">
+                {f.error}
+              </span>
+            )}
+          </label>
+        ))}
+      </div>
+      {which === "billing" && <ShipToDifferentToggle />}
+    </fieldset>
+  );
+}
+
+function ShipToDifferentToggle() {
+  const { shipToDifferent, setShipToDifferent } = useCheckoutContext();
+  return (
+    <label className="mt-3 flex items-center gap-2 text-sm">
+      <input
+        type="checkbox"
+        data-commerce="ship-to-different"
+        checked={shipToDifferent}
+        onChange={(e) => setShipToDifferent(e.target.checked)}
+      />
+      Deliver to a different address
+    </label>
+  );
+}

package/src/commerce/storefront/blocks/BreadcrumbsBlock.jsx

@@ -0,0 +1,52 @@
+import React from "react";
+
+/**
+ * Category breadcrumbs for a product page.
+ *
+ *   <BreadcrumbsBlock categories={categories} current={product.name} />
+ *
+ * Ribbons are deliberately NOT breadcrumbs — they are labels ("Best Seller"),
+ * not places in the catalog. Pass `renderLink` to use your router's `<Link>`
+ * instead of a plain anchor.
+ *
+ * @param {{categories?: Array<object>, current?: string, className?: string,
+ *   homeLabel?: string, homeHref?: string, categoryHref?: (c: object) => string,
+ *   renderLink?: (o: {href: string, label: string}) => React.ReactNode}} props
+ */
+export function BreadcrumbsBlock({
+  categories = [],
+  current,
+  className = "",
+  homeLabel = "Home",
+  homeHref = "/",
+  categoryHref = (c) => `/collection?category_id=${c.id}`,
+  renderLink,
+}) {
+  const crumbs = [
+    { href: homeHref, label: homeLabel },
+    ...categories.map((c) => ({ href: categoryHref(c), label: c.name })),
+  ];
+
+  const link = ({ href, label }) =>
+    renderLink ? (
+      renderLink({ href, label })
+    ) : (
+      <a href={href} className="underline-offset-2 hover:underline">
+        {label}
+      </a>
+    );
+
+  return (
+    <nav data-commerce="breadcrumbs" aria-label="Breadcrumb" className={`text-xs text-muted-foreground ${className}`}>
+      <ol className="flex flex-wrap items-center gap-1.5">
+        {crumbs.map((c) => (
+          <li key={`${c.href}-${c.label}`} className="flex items-center gap-1.5">
+            {link(c)}
+            <span aria-hidden>/</span>
+          </li>
+        ))}
+        {current && <li aria-current="page">{current}</li>}
+      </ol>
+    </nav>
+  );
+}

package/src/commerce/storefront/blocks/CartLinesBlock.jsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { useCart } from "../StorefrontProvider";
+import { useFormatMoney } from "../StorefrontProvider";
+import { QuantityStepper } from "./QuantityStepper";
+import { CouponFieldBlock } from "./CouponFieldBlock";
+
+/**
+ * The bag's line items: image, name, variant label, quantity stepper, line
+ * total — plus the notices that say what auto-dropped and why, and the coupon
+ * field.
+ *
+ *   <CartLinesBlock />
+ *
+ * Branches on the cart's `status`, so it never flashes an empty state while the
+ * cart is still loading. Pass `slots.empty` / `slots.loading` to brand those
+ * two states, or `renderLine` to take over a row entirely.
+ *
+ * **The coupon field is on by default** (`showCoupon`). A store whose codes have
+ * nowhere to be typed cannot honour its own discounts, and that has been the
+ * most-repeated omission in hand-built storefronts — so the default is the safe
+ * one. Turn it off for a store that has no coupons and doesn't want the field,
+ * or when your checkout carries the only one.
+ *
+ * @param {{className?: string, showNotices?: boolean, showCoupon?: boolean,
+ *   slots?: {empty?: React.ReactNode, loading?: React.ReactNode},
+ *   renderLine?: (line: object) => React.ReactNode}} props
+ */
+export function CartLinesBlock({
+  className = "",
+  showNotices = true,
+  showCoupon = true,
+  slots = {},
+  renderLine,
+}) {
+  const { status, lines, notices } = useCart();
+  const formatMoney = useFormatMoney();
+
+  if (status === "loading") {
+    return slots.loading ?? <p data-commerce="cart-loading" className="text-sm text-muted-foreground">Loading your bag…</p>;
+  }
+  if (status === "empty") {
+    return slots.empty ?? <p data-commerce="cart-empty" className="text-sm text-muted-foreground">Your bag is empty.</p>;
+  }
+
+  return (
+    <div data-commerce="cart-lines" className={className}>
+      {showNotices && notices.length > 0 && (
+        <ul data-commerce="cart-notices" className="mb-4 space-y-1">
+          {notices.map((n, i) => (
+            <li key={`${n.code}-${i}`} role="status" className="text-xs text-muted-foreground">
+              {n.message}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <ul className="divide-y divide-border">
+        {lines.map((line) =>
+          renderLine ? (
+            <React.Fragment key={line.item_key}>{renderLine(line)}</React.Fragment>
+          ) : (
+            <li
+              key={line.item_key}
+              data-commerce="line-item"
+              className="grid grid-cols-[64px_1fr_auto] items-start gap-4 py-4"
+            >
+              {line.image ? (
+                <img
+                  src={line.image.src}
+                  alt={line.image.alt}
+                  className="aspect-square w-16 object-cover"
+                  loading="lazy"
+                />
+              ) : (
+                <div aria-hidden className="aspect-square w-16 bg-muted" />
+              )}
+              <div className="min-w-0">
+                <p data-commerce="line-name" className="truncate text-sm">{line.name}</p>
+                {line.attributesLabel && (
+                  <p data-commerce="line-attributes" className="mt-0.5 text-xs text-muted-foreground">
+                    {line.attributesLabel}
+                  </p>
+                )}
+                {!line.purchasable && line.unavailableReason && (
+                  <p role="alert" className="mt-1 text-xs text-destructive">{line.unavailableReason}</p>
+                )}
+                <QuantityStepper line={line} className="mt-2" />
+              </div>
+              <p data-commerce="line-total" className="text-sm">{formatMoney(line.total)}</p>
+            </li>
+          ),
+        )}
+      </ul>
+
+      {showCoupon && <CouponFieldBlock className="mt-6" />}
+    </div>
+  );
+}

package/src/commerce/storefront/blocks/CheckoutBlock.jsx

@@ -0,0 +1,247 @@
+import React from "react";
+import { CheckoutProvider, useCheckoutContext } from "../useCheckout";
+import { PaymentMethodPicker, ShippingMethodPicker } from "../pickers";
+import { useCart, useFormatMoney } from "../StorefrontProvider";
+import { useCheckoutBlockers } from "../useTotalsLines";
+import { AddressFieldsBlock } from "./AddressFieldsBlock";
+import { CouponFieldBlock } from "./CouponFieldBlock";
+import { TotalsBlock } from "./TotalsBlock";
+
+/**
+ * The whole checkout: address → delivery → payment → summary → place order.
+ * It supplies its own `<CheckoutProvider>`, so this is a complete page body:
+ *
+ *   export default function Checkout() {
+ *     return <main className="mx-auto max-w-3xl px-6 py-16">
+ *       <h1 className="font-heading text-5xl">Checkout</h1>
+ *       <CheckoutBlock />
+ *     </main>;
+ *   }
+ *
+ * Correct with zero props in a default-seeded store (one manual gateway, one
+ * shipping rate), and every branch a checkout must handle is already wired:
+ * shipping recalculates from the address, a single shipping/payment option
+ * reads as selected, a store with no enabled gateway says so instead of
+ * rendering a dead button, the place-order gate explains itself, and an offline
+ * order's payment instructions are shown on the confirmation.
+ *
+ * Restyle it with `className`, replace one region with `slots`, or drop to the
+ * hooks (`useCheckout`, `useAddressForm`, the pickers, `useTotalsLines`) when
+ * the design needs different structure — this component is nothing but a
+ * composition of them.
+ *
+ * @param {{className?: string, showCoupon?: boolean, options?: object,
+ *   onPlaced?: (result: object) => void, orderReceivedPath?: string,
+ *   slots?: {address?, shipping?, payment?, summary?, submit?, empty?}}} props
+ *   `onPlaced` overrides the default post-order behaviour (navigating to
+ *   `orderReceivedPath` with the order's id + key, where `<OrderReceivedBlock/>`
+ *   renders the confirmation and any payment instructions).
+ */
+export function CheckoutBlock({
+  className = "",
+  showCoupon = true,
+  options,
+  onPlaced,
+  orderReceivedPath = "/order-received",
+  slots = {},
+}) {
+  return (
+    <CheckoutProvider options={options}>
+      <CheckoutBody
+        className={className}
+        showCoupon={showCoupon}
+        onPlaced={onPlaced}
+        orderReceivedPath={orderReceivedPath}
+        slots={slots}
+      />
+    </CheckoutProvider>
+  );
+}
+
+function CheckoutBody({ className, showCoupon, onPlaced, orderReceivedPath, slots }) {
+  const { status } = useCart();
+  const checkout = useCheckoutContext();
+
+  if (status === "loading") {
+    return <p data-commerce="checkout-loading" className="text-sm text-muted-foreground">Loading…</p>;
+  }
+  if (status === "empty") {
+    return (
+      slots.empty ?? (
+        <p data-commerce="checkout-empty" className="text-sm text-muted-foreground">
+          Your bag is empty — add something before checking out.
+        </p>
+      )
+    );
+  }
+
+  return (
+    <div data-commerce="checkout" className={`grid gap-10 md:grid-cols-[1fr_360px] ${className}`}>
+      <div className="space-y-8">
+        {slots.address ?? <AddressFieldsBlock legend="Your details" />}
+        {checkout.shipToDifferent && <AddressFieldsBlock which="shipping" legend="Delivery address" />}
+        {slots.shipping ?? <ShippingStep />}
+        {slots.payment ?? <PaymentStep />}
+      </div>
+
+      <aside className="space-y-6">
+        {slots.summary ?? (
+          <>
+            {showCoupon && <CouponFieldBlock />}
+            <TotalsBlock />
+          </>
+        )}
+        {slots.submit ?? <PlaceOrder onPlaced={onPlaced} orderReceivedPath={orderReceivedPath} />}
+      </aside>
+    </div>
+  );
+}
+
+function ShippingStep() {
+  const formatMoney = useFormatMoney();
+  return (
+    <ShippingMethodPicker>
+      {({ status, methods, chosen, choose, mustChoose, single, syncing }) => (
+        <fieldset data-commerce="shipping-step" className={syncing ? "opacity-60" : ""}>
+          <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">Delivery</legend>
+
+          {status === "missing_address" && (
+            <p className="text-sm text-muted-foreground">
+              Delivery options appear once your address is entered.
+            </p>
+          )}
+
+          {status === "none_available" && (
+            <p role="alert" className="text-sm text-destructive">
+              We don't deliver to that address yet.
+            </p>
+          )}
+
+          {mustChoose &&
+            methods.map((m) => (
+              <label key={m.id} data-commerce="shipping-method" data-commerce-cost={m.cost} className="flex items-center justify-between gap-4 py-1.5 text-sm">
+                <span className="flex items-center gap-2">
+                  <input
+                    type="radio"
+                    name="shipping_method"
+                    value={m.id}
+                    checked={chosen?.id === m.id}
+                    onChange={() => choose(m.id)}
+                  />
+                  {m.title}
+                </span>
+                <span>{formatMoney(m.cost)}</span>
+              </label>
+            ))}
+
+          {!mustChoose && chosen && (
+            <p data-commerce="shipping-method" data-commerce-cost={chosen.cost} className="flex justify-between gap-4 text-sm">
+              <span>{chosen.title}</span>
+              <span>{formatMoney(chosen.cost)}</span>
+            </p>
+          )}
+          {single && chosen && (
+            <p className="mt-1 text-xs text-muted-foreground">The only option for this address.</p>
+          )}
+        </fieldset>
+      )}
+    </ShippingMethodPicker>
+  );
+}
+
+function PaymentStep() {
+  return (
+    <PaymentMethodPicker>
+      {({ gateways, value, select, selected, single }) => (
+        <fieldset data-commerce="payment-step">
+          <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">Payment</legend>
+
+          {gateways.length === 0 && (
+            <p role="alert" className="text-sm text-destructive">
+              No payment method is available right now — please contact us to complete your order.
+            </p>
+          )}
+
+          {!single &&
+            gateways.map((g) => (
+              <label key={g.slug} data-commerce="payment-method" className="block py-1.5 text-sm">
+                <span className="flex items-center gap-2">
+                  <input
+                    type="radio"
+                    name="payment_method"
+                    value={g.slug}
+                    checked={value === g.slug}
+                    onChange={() => select(g.slug)}
+                  />
+                  {g.title}
+                </span>
+                {g.description && (
+                  <span className="ml-6 block text-xs text-muted-foreground">{g.description}</span>
+                )}
+              </label>
+            ))}
+
+          {single && selected && (
+            <div data-commerce="payment-method" className="text-sm">
+              <p>{selected.title}</p>
+              {selected.description && (
+                <p className="mt-0.5 text-xs text-muted-foreground">{selected.description}</p>
+              )}
+            </div>
+          )}
+        </fieldset>
+      )}
+    </PaymentMethodPicker>
+  );
+}
+
+function PlaceOrder({ onPlaced, orderReceivedPath }) {
+  const { canPlaceOrder, placing, placeOrder, orderError } = useCheckoutContext();
+  const blockers = useCheckoutBlockers();
+
+  const submit = async () => {
+    const res = await placeOrder();
+    if (!res.ok) return;
+    if (onPlaced) return onPlaced(res.result);
+    // An online gateway has already redirected. Everything else lands on the
+    // return page, which is also where a manual order's payment instructions
+    // are rendered — so the offline default confirms properly too.
+    if (!res.result.payment && typeof window !== "undefined") {
+      const q = new URLSearchParams({
+        order_id: res.result.order_id,
+        order_key: res.result.order_key,
+      });
+      window.location.assign(`${orderReceivedPath}?${q}`);
+    }
+  };
+
+  return (
+    <div>
+      <button
+        type="button"
+        data-commerce="place-order"
+        onClick={submit}
+        disabled={!canPlaceOrder || placing}
+        className="w-full bg-primary px-6 py-3 text-sm text-primary-foreground disabled:opacity-50"
+      >
+        {placing ? "Placing your order…" : "Place order"}
+      </button>
+
+      {orderError && (
+        <p data-commerce="order-error" role="alert" className="mt-2 text-sm text-destructive">
+          {orderError.message}
+        </p>
+      )}
+
+      {!canPlaceOrder && blockers.length > 0 && (
+        <ul data-commerce="checkout-blockers" className="mt-2 space-y-1">
+          {blockers.map((b) => (
+            <li key={b.code} className="text-xs text-muted-foreground">
+              {b.message}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/commerce/storefront/blocks/CouponFieldBlock.jsx

@@ -0,0 +1,84 @@
+import React from "react";
+import { useCoupon } from "../useCartLine";
+import { useFormatMoney } from "../StorefrontProvider";
+
+/**
+ * The coupon field. **If the store has any coupons, this has to exist
+ * somewhere** — in the cart or the checkout — because codes are admin-only
+ * data a customer can only redeem by typing them. A store that seeds coupons
+ * and ships no field advertises discounts it cannot honour.
+ *
+ *   <CouponFieldBlock />
+ *
+ * @param {{className?: string, label?: string, placeholder?: string,
+ *   applyLabel?: string}} props
+ */
+export function CouponFieldBlock({
+  className = "",
+  label = "Discount code",
+  placeholder = "Enter code",
+  applyLabel = "Apply",
+}) {
+  const c = useCoupon();
+
+  return (
+    <div data-commerce="coupon" className={className}>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          c.apply();
+        }}
+        className="flex items-end gap-2"
+      >
+        <label className="flex-1">
+          <span className="block text-xs uppercase tracking-wide text-muted-foreground">{label}</span>
+          <input
+            data-commerce="coupon-input"
+            value={c.code}
+            onChange={(e) => c.setCode(e.target.value)}
+            placeholder={placeholder}
+            autoComplete="off"
+            className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+          />
+        </label>
+        <button
+          type="submit"
+          data-commerce="coupon-apply"
+          disabled={c.applying}
+          className="border border-border px-4 py-2 text-sm disabled:opacity-50"
+        >
+          {c.applying ? "Applying…" : applyLabel}
+        </button>
+      </form>
+
+      {c.error && (
+        <p data-commerce="coupon-error" role="alert" className="mt-1 text-xs text-destructive">
+          {c.error.message}
+        </p>
+      )}
+
+      {c.applied.length > 0 && (
+        <ul data-commerce="coupon-applied" className="mt-2 space-y-1">
+          {c.applied.map((a) => (
+            <AppliedCoupon key={a.code} coupon={a} onRemove={() => c.remove(a.code)} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function AppliedCoupon({ coupon, onRemove }) {
+  const formatMoney = useFormatMoney();
+  return (
+    <li className="flex items-center justify-between gap-3 text-sm">
+      <span>
+        {coupon.code}
+        {coupon.freeShipping ? " · free shipping" : coupon.discount ? ` · −${formatMoney(coupon.discount)}` : ""}
+      </span>
+      <button type="button" onClick={onRemove} className="text-xs text-muted-foreground underline">
+        Remove
+      </button>
+    </li>
+  );
+}