@base44/app-plugin-commerce 0.4.0 → 0.5.0

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

@@ -1,10 +1,20 @@
-import React, { createContext, useCallback, useContext, useId, useMemo, useState } from "react";
+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 { visible } from "./visibility";
 import { CouponField, Totals } from "./shared";
 
 /**
@@ -19,6 +29,9 @@ import { CouponField, Totals } from "./shared";
 
 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
@@ -53,7 +66,16 @@ function RootPhase({ onPlaced, children }) {
         : status === "empty"
           ? "empty"
           : "form";
-  const value = useMemo(() => ({ phase, onPlaced }), [phase, onPlaced]);
+  // 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>;
 }
 
@@ -92,6 +114,7 @@ const Form = gate("Form", "form");
  */
 function AddressFields({
   which = "billing",
+  show,
   include,
   omit,
   inputRender: InputRender,
@@ -111,14 +134,21 @@ function AddressFields({
 
   const values = isBilling ? checkout.billing : checkout.shipping;
   const set = isBilling ? checkout.updateBilling : checkout.updateShipping;
+  // `show` is the current form (keys are field keys); `include`/`omit` are the
+  // older spelling and fold into the same predicate.
+  const vis = visible(show, {
+    company: include?.includes("company") ?? false,
+    phone: include ? include.includes("phone") : true,
+    ...Object.fromEntries((omit ?? []).map((k) => [k, false])),
+  });
   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));
+    includeEmail: isBilling && vis("email"),
+    includeCompany: vis("company"),
+    includePhone: vis("phone"),
+  }).filter((f) => vis(f.key));
 
   return (
     <div data-part="address-fields" data-which={which} className={className}>
@@ -197,20 +227,36 @@ function AddressFields({
   );
 }
 
-/** The deliver-elsewhere toggle. Children are its label — the store's words. */
-function ShipToDifferent({ children, className, classes }) {
+/**
+ * The deliver-elsewhere toggle. Children are its label — the store's words.
+ * `controlRender({ checked, onChange, toggle })` replaces the checkbox with
+ * whatever the design wants (a switch, a segmented control, a pair of buttons);
+ * keep it operable from the keyboard and give it a checked state a screen reader
+ * can read (`role="switch"` + `aria-checked`, or a real input inside).
+ */
+function ShipToDifferent({ children, controlRender, className, classes }) {
   const checkout = useCheckoutContext();
+  const checked = checkout.shipToDifferent;
+  const set = checkout.setShipToDifferent;
+  const control = controlRender ? (
+    controlRender({ checked, onChange: (e) => set(e?.target ? e.target.checked : Boolean(e)), toggle: () => set(!checked) })
+  ) : (
+    <input
+      data-part="control"
+      className={classes?.control}
+      type="checkbox"
+      checked={checked}
+      onChange={(e) => set(e.target.checked)}
+    />
+  );
+  // Without the kit's own input there is nothing for a <label> to label, so the
+  // store's control stands on its own (it carries its own accessible name).
+  const Wrapper = controlRender ? "div" : "label";
   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)}
-      />
+    <Wrapper data-part="ship-to-different" className={className}>
+      {control}
       <span data-part="label" className={classes?.label}>{children}</span>
-    </label>
+    </Wrapper>
   );
 }
 
@@ -247,30 +293,28 @@ function ShippingMethods({ optionRender, className, classes, labels: partLabels
               </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>
-              ))}
+              methods.map((m) =>
+                optionRender ? (
+                  <React.Fragment key={m.id}>{optionRender(m)}</React.Fragment>
+                ) : (
+                  <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(() => {})}
+                    />
+                    <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 ? (
@@ -359,8 +403,14 @@ function PaymentMethods({ optionRender, className, classes, labels: partLabels }
   );
 }
 
-/** The mini summary: read-only rows of what is being bought. `itemRender(item)` replaces a row. */
-function Items({ itemRender, className, classes }) {
+/**
+ * The mini summary: read-only rows of what is being bought. `show` decides which
+ * elements render — `media`, `attributes`, `quantity`, `lineTotal` (a dense
+ * summary column often wants `show={{ media: false }}`); `itemRender(item)`
+ * replaces a row.
+ */
+function Items({ show, itemRender, className, classes }) {
+  const vis = visible(show);
   const checkout = useCheckoutContext();
   const formatMoney = useFormatMoney();
   const items = checkout.cart?.items ?? [];
@@ -373,21 +423,28 @@ function Items({ itemRender, className, classes }) {
             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} />
+              {vis("media") &&
+                (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>
+                {vis("attributes") && attributesLabel(item.attributes) ? (
+                  <span data-part="attributes" className={classes?.attributes}>
+                    {attributesLabel(item.attributes)}
+                  </span>
+                ) : null}
+              </span>
+              {vis("quantity") && (
+                <span data-part="quantity" className={classes?.quantity}>×{item.quantity}</span>
               )}
-              <span data-part="name" className={classes?.name}>{item.name}</span>
-              {attributesLabel(item.attributes) ? (
-                <span data-part="attributes" className={classes?.attributes}>
-                  {attributesLabel(item.attributes)}
+              {vis("lineTotal") && (
+                <span data-part="line-total" className={classes?.["line-total"]}>
+                  {formatMoney(item.total)}
                 </span>
-              ) : null}
-              <span data-part="quantity" className={classes?.quantity}>{item.quantity}</span>
-              <span data-part="line-total" className={classes?.["line-total"]}>
-                {formatMoney(item.total)}
-              </span>
+              )}
             </>
           )}
         </li>
@@ -399,12 +456,20 @@ function Items({ itemRender, className, classes }) {
 /**
  * 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 itself; use this part only to place them
- * elsewhere (then pass `showBlockers={false}` to the button).
+ * `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({ className, classes, labels: partLabels }) {
+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}>
@@ -420,12 +485,14 @@ function Blockers({ className, classes, labels: partLabels }) {
 /**
  * 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
+ * server's own words. `show={{ blockers: false }}` moves the reasons elsewhere
+ * (place `Checkout.Blockers` yourself — it also suppresses these on its own). On success `Checkout.Root`'s `onPlaced` fires (when the
  * page owns the post-order step).
  */
-function PlaceOrder({ showBlockers = true, className, classes, labels: partLabels }) {
+function PlaceOrder({ show, showBlockers = true, className, classes, labels: partLabels }) {
+  const vis = visible(show, { blockers: showBlockers });
   const checkout = useCheckoutContext();
-  const { onPlaced } = usePartsContext("PlaceOrder");
+  const { onPlaced, hasOwnBlockers } = usePartsContext("PlaceOrder");
   const L = useResolvedLabels(partLabels);
   const place = useCallback(async () => {
     const res = await checkout.placeOrder(); // resolves {ok:false} — never throws
@@ -443,12 +510,14 @@ function PlaceOrder({ showBlockers = true, className, classes, labels: partLabel
       >
         {checkout.placing ? label(L, "placeOrder.placing") : label(L, "placeOrder.label")}
       </button>
-      {checkout.orderError && (
+      {vis("orderError") && checkout.orderError && (
         <p data-part="order-error" role="alert" className={classes?.["order-error"]}>
           {checkout.orderError.message}
         </p>
       )}
-      {showBlockers && <Blockers className={classes?.blockers} labels={partLabels} />}
+      {vis("blockers") && !hasOwnBlockers && (
+        <Blockers standalone={false} className={classes?.blockers} labels={partLabels} />
+      )}
     </>
   );
 }

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

@@ -1,24 +1,43 @@
-import React, { useEffect, useRef } from "react";
+import React 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.
+ * The cart drawer's two wired *elements* — nothing more. **The drawer itself is
+ * the store's**: you render the overlay and the panel, and own where they sit,
+ * how wide they are, their padding and their animation. There is deliberately
+ * no `Panel` part: a kit that positions the drawer gets it wrong for half the
+ * designs it lands in (and there is no version of "which side, how wide, how it
+ * moves" that isn't the store's decision).
+ *
+ * The state and the fiddly behavior stay premade in `useCartUI()` (open/close,
+ * Esc, close-on-navigate, open-on-add, focus in and back out, inert while
+ * closed, `panelId`) — see `cartUI.jsx`. The shape of a drawer, then, is:
+ *
+ *   const ui = useCartUI();
+ *   …
+ *   <CartDrawer.Trigger className="…">{({ count }) => …}</CartDrawer.Trigger>
+ *   {ui.open && (
+ *     <div className="…your fixed layer…">
+ *       <div className="…your scrim…" aria-hidden="true" onClick={ui.closeCart} />
+ *       <aside id={ui.panelId} ref={ui.panelRef} tabIndex={-1}
+ *              role="dialog" aria-modal="true" aria-label="…"
+ *              className="…your panel: side, width, padding, transition…">
+ *         <CartDrawer.Close>…your glyph…</CartDrawer.Close>
+ *         …Cart.* parts…
+ *       </aside>
+ *     </div>
+ *   )}
+ *
+ * Contract, rules 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.
+ * The header's cart button, wired: toggles the drawer, reports `aria-expanded`,
+ * and points `aria-controls` at `useCartUI().panelId` (put that on your panel).
+ * The icon is the store's — 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);
@@ -33,7 +52,7 @@ function Trigger({ children, className, labels: partLabels }) {
       className={className}
       aria-haspopup="dialog"
       aria-expanded={ui.open}
-      aria-controls={PANEL_ID}
+      aria-controls={ui.panelId}
       aria-label={label(L, "aria.trigger")}
       onClick={ui.toggleCart}
     >
@@ -43,59 +62,9 @@ function Trigger({ children, className, labels: partLabels }) {
 }
 
 /**
- * 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]`.
+ * The named close control — the drawer's keyboard and screen-reader way out
+ * (a click-away scrim is not one). Children are the store's icon or text.
  */
-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();
@@ -114,6 +83,5 @@ function Close({ children, className, labels: partLabels }) {
 
 export const CartDrawer = {
   Trigger,
-  Panel,
   Close,
 };

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

@@ -3,6 +3,7 @@ import { orderTotalsLines } from "@/commerce/utils";
 import { useFormatMoney } from "../StorefrontProvider";
 import { useOrderReturn } from "../useOrderReturn";
 import { LabelsScope, label, useResolvedLabels } from "./labels";
+import { visible } from "./visibility";
 import { totalsLabels } from "./shared";
 
 /**
@@ -62,8 +63,13 @@ 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 }) {
+/**
+ * The order's lines, already normalized (image is `{src, alt}|null`, money
+ * pre-formatted). `show` decides which elements render (`media`, `attributes`,
+ * `quantity`, `lineTotal`); `itemRender(line)` replaces a row.
+ */
+function Items({ show, itemRender, className, classes }) {
+  const vis = visible(show);
   const ret = useReturnCtx("Items");
   const lines = ret.lines ?? [];
   if (!lines.length) return null;
@@ -75,17 +81,24 @@ function Items({ itemRender, className, classes }) {
             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} />
+              {vis("media") &&
+                (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>
+                {vis("attributes") && line.attributesLabel ? (
+                  <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
+                ) : null}
+              </span>
+              {vis("quantity") && (
+                <span data-part="quantity" className={classes?.quantity}>×{line.quantity}</span>
+              )}
+              {vis("lineTotal") && (
+                <span data-part="line-total" className={classes?.["line-total"]}>{line.totalLabel}</span>
               )}
-              <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>
@@ -95,13 +108,14 @@ function Items({ itemRender, className, classes }) {
 }
 
 /** The receipt's summary rows — an order's totals are FLAT, and this part owns that trap. */
-function Totals({ pick, className, classes, labels: partLabels }) {
+function Totals({ show, pick, className, classes, labels: partLabels }) {
+  const vis = visible(show ?? pick);
   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)),
+    (r) => !r.hidden && vis(r.key),
   );
   return (
     <dl data-part="totals" className={className}>