@base44/app-plugin-commerce 0.4.1 → 0.5.1

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

@@ -14,6 +14,7 @@ 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";
 
 /**
@@ -113,6 +114,7 @@ const Form = gate("Form", "form");
  */
 function AddressFields({
   which = "billing",
+  show,
   include,
   omit,
   inputRender: InputRender,
@@ -132,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}>
@@ -218,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>
   );
 }
 
@@ -268,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 ? (
@@ -380,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 ?? [];
@@ -394,23 +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>
-                {attributesLabel(item.attributes) ? (
+                {vis("attributes") && 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>
+              {vis("quantity") && (
+                <span data-part="quantity" className={classes?.quantity}>×{item.quantity}</span>
+              )}
+              {vis("lineTotal") && (
+                <span data-part="line-total" className={classes?.["line-total"]}>
+                  {formatMoney(item.total)}
+                </span>
+              )}
             </>
           )}
         </li>
@@ -451,10 +485,12 @@ function Blockers({ standalone = true, 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, hasOwnBlockers } = usePartsContext("PlaceOrder");
   const L = useResolvedLabels(partLabels);
@@ -474,12 +510,12 @@ 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 && !hasOwnBlockers && (
+      {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,19 +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>
-                {line.attributesLabel ? (
+                {vis("attributes") && line.attributesLabel ? (
                   <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
                 ) : null}
               </span>
-              <span data-part="quantity" className={classes?.quantity}>×{line.quantity}</span>
-              <span data-part="line-total" className={classes?.["line-total"]}>{line.totalLabel}</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>
+              )}
             </>
           )}
         </li>
@@ -97,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}>

package/src/commerce/storefront/parts/parts.css

@@ -3,11 +3,15 @@
  *
  * The parts render correct markup; this sheet makes that markup *lay out*
  * correctly: labels above full-width controls in a two-column address grid, a
- * cart row as media + content + controls, totals as label-left/value-right,
- * a drawer that is actually a right-hand panel over an overlay. Without it
- * every store re-derives the same geometry from scratch, and a storefront that
- * gets it wrong reads as broken (staggered input widths, a product thumbnail
- * blown up to the column width, "SetColor: Magenta1$89.00" with no gaps).
+ * cart row as media + content + controls, totals as label-left/value-right.
+ * Without it every store re-derives the same geometry from scratch, and a
+ * storefront that gets it wrong reads as broken (staggered input widths, a
+ * product thumbnail blown up to the column width, "SetColor: Magenta1$89.00"
+ * with no gaps).
+ *
+ * It stops at the edge of a part. Anything that arranges *sections* — where the
+ * cart drawer sits, how wide it is, how it animates, the space between the
+ * checkout's columns — is the store's, and nothing here touches it.
  *
  * What this sheet deliberately does NOT contain — the store's identity, and
  * the reason an unstyled storefront still looks unfinished rather than
@@ -27,8 +31,6 @@
  *     --commerce-gap-tight: 0.4rem;    label→control, name→attributes
  *     --commerce-field-columns: 2;     address-form columns (1 on narrow)
  *     --commerce-media-size: 4rem;     cart/summary thumbnail edge
- *     --commerce-drawer-width: 28rem;  drawer panel width
- *     --commerce-drawer-z: 50;         drawer stacking context
  *   }
  *
  * Loaded automatically: `@/commerce/storefront` imports this file. With a
@@ -208,25 +210,6 @@
   margin: 0;
 }
 
-/* ── cart drawer: a panel over an overlay, not a block in the header ───────── */
-:where([data-part="drawer"]) {
-  position: fixed;
-  inset: 0;
-  z-index: var(--commerce-drawer-z, 50);
-  display: flex;
-  justify-content: flex-end;
-}
-:where([data-part="overlay"]) {
-  position: absolute;
-  inset: 0;
-}
-:where([data-part="panel"]) {
-  position: relative;
-  display: flex;
-  flex-direction: column;
-  gap: var(--commerce-gap, 1rem);
-  inline-size: min(var(--commerce-drawer-width, 28rem), 100%);
-  max-inline-size: 100%;
-  block-size: 100%;
-  overflow-y: auto;
-}
+/* The cart drawer is deliberately absent: the store renders the overlay and
+   the panel and owns their side, width, padding and animation. `useCartUI()`
+   keeps the state and the behavior (focus, inert-while-closed, Esc). */

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

@@ -2,6 +2,7 @@ import React, { useState } from "react";
 import { cartTotalsLines } from "@/commerce/utils";
 import { useCart, useFormatMoney } from "../StorefrontProvider";
 import { label, useResolvedLabels } from "./labels";
+import { visible } from "./visibility";
 
 /**
  * Parts shared by the cart and the checkout (exported as `Cart.CouponField` /
@@ -15,8 +16,12 @@ import { label, useResolvedLabels } from "./labels";
  * 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).
+ *
+ * `inputRender({ value, onChange, onKeyDown, placeholder, disabled })` swaps the
+ * field for the store's own control; the apply button, the applied codes and the
+ * failure line stay wired around it.
  */
-export function CouponField({ className, classes, labels: partLabels }) {
+export function CouponField({ inputRender: InputRender, className, classes, labels: partLabels }) {
   const L = useResolvedLabels(partLabels);
   const { cart, applyCoupon, removeCoupon } = useCart();
   const [code, setCode] = useState("");
@@ -37,21 +42,25 @@ export function CouponField({ className, classes, labels: partLabels }) {
   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();
-          }
-        }}
-      />
+      {(() => {
+        const field = {
+          value: code,
+          placeholder: label(L, "coupon.placeholder"),
+          disabled: busy,
+          onChange: (e) => setCode(e?.target ? e.target.value : String(e ?? "")),
+          onKeyDown: (e) => {
+            if (e.key === "Enter") {
+              e.preventDefault();
+              submit();
+            }
+          },
+        };
+        return InputRender ? (
+          <InputRender {...field} />
+        ) : (
+          <input data-part="input" className={classes?.input} aria-label={field.placeholder} {...field} />
+        );
+      })()}
       <button
         type="button"
         data-part="apply"
@@ -85,17 +94,18 @@ export function CouponField({ className, classes, labels: partLabels }) {
 
 /**
  * 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.
+ * (discount and tax included), `data-emphasis` on the total. `show` picks the
+ * rows by key: `show={["subtotal"]}` for a drawer footer, `show={{ tax: false }}`
+ * to drop one. Row names come from `labels.totals`; amounts stay the engine's.
  */
-export function Totals({ pick, className, classes, labels: partLabels }) {
+export function Totals({ show, pick, className, classes, labels: partLabels }) {
+  const vis = visible(show ?? pick);
   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)),
+    (r) => !r.hidden && vis(r.key),
   );
   return (
     <dl data-part="totals" className={className}>

package/src/commerce/storefront/parts/visibility.js

@@ -0,0 +1,36 @@
+/**
+ * `show` — the parts' display settings: which of a part's sub-elements render,
+ * decided in JSX rather than hidden with CSS. Hiding with `display: none` leaves
+ * the element in the layout and in the accessibility tree (an empty thumbnail
+ * box, a screen reader still announcing a row's attributes); `show` renders
+ * nothing at all.
+ *
+ * Two shapes, both accepted everywhere:
+ *
+ *   show={{ media: false }}              // overrides on the part's defaults
+ *   show={["subtotal", "total"]}         // exactly these, nothing else
+ *
+ * Keys are the part's `data-part` names (`media`, `attributes`, `stepper`,
+ * `lineTotal`, `blockers`, a totals row key, an address field key) — the same
+ * vocabulary as `classes` and the CSS selectors, so there is one set of names
+ * to know. Per-part key lists: the commerce skill's install/02-storefront.md.
+ */
+
+/**
+ * Build the predicate a part asks for each sub-element.
+ *
+ * @param {object|string[]|undefined} show the part's `show` prop
+ * @param {Record<string, boolean>} [defaults] keys whose default is not `true`
+ * @returns {(key: string) => boolean}
+ */
+export function visible(show, defaults = {}) {
+  if (Array.isArray(show)) {
+    const only = new Set(show);
+    return (key) => only.has(key);
+  }
+  return (key) => {
+    const asked = show?.[key];
+    if (asked !== undefined) return Boolean(asked);
+    return defaults[key] ?? true;
+  };
+}

package/src/commerce/storefront/useCheckout.jsx

@@ -381,3 +381,30 @@ export function useCheckoutContext() {
 export function useCheckoutContextOptional() {
   return useContext(CheckoutContext);
 }
+
+/**
+ * Is this component rendering inside a checkout (`Checkout.Root`, or your own
+ * `<CheckoutProvider>`)? For the one component a store writes once and shows in
+ * three places — the drawer, the cart page and the checkout's order summary —
+ * where a merchandising block belongs in the first two and is a distraction (or
+ * a way out of the funnel) in the third:
+ *
+ *   function CartContents() {
+ *     const inCheckout = useInCheckout();
+ *     return (
+ *       <>
+ *         <Cart.Lines />
+ *         {!inCheckout && <UpsellRail />}   // your own upsell / related rail
+ *         <Cart.Totals />
+ *       </>
+ *     );
+ *   }
+ *
+ * A boolean, not a mode: nothing in the kit changes behavior from it. Prefer an
+ * explicit prop (`<CartContents showUpsell={false} />`) where the caller knows
+ * best; this is for the case where it doesn't — a shared component several
+ * pages deep.
+ */
+export function useInCheckout() {
+  return useContext(CheckoutContext) != null;
+}