@base44/app-plugin-commerce 0.4.0 → 0.5.0

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

@@ -0,0 +1,215 @@
+/**
+ * Layout geometry for the commerce parts — **structure only, never a look.**
+ *
+ * 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.
+ * 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
+ * finished-and-generic: no color, no background, no border (beyond zeroing the
+ * ones the browser puts on elements the parts chose, like `fieldset`), no
+ * radius, no shadow, no font, no text decoration. A release check enforces
+ * that list, so this file cannot drift into a theme.
+ *
+ * **Overriding is free.** Every rule is wrapped in `:where()`, so its
+ * specificity is 0 — any selector the store writes wins without `!important`,
+ * including a bare `[data-part="row"] { … }`. Tune the built-in geometry
+ * through the custom properties below (set them on `:root`, a page, or one
+ * part), or replace a rule outright.
+ *
+ *   :root {
+ *     --commerce-gap: 1rem;            gap between fields, rows, options
+ *     --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
+ *   }
+ *
+ * Loaded automatically: `@/commerce/storefront` imports this file. With a
+ * bundler that does not take CSS imports from JS, delete that import line and
+ * `@import "@/commerce/storefront/parts/parts.css";` from the app's stylesheet
+ * instead.
+ */
+
+:where([data-part]) {
+  box-sizing: border-box;
+}
+
+/* ── address form ─────────────────────────────────────────────────────────── */
+:where([data-part="address-fields"]) {
+  display: grid;
+  grid-template-columns: repeat(var(--commerce-field-columns, 2), minmax(0, 1fr));
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="field"]) {
+  display: grid;
+  align-content: start;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="field"][data-span="2"]) {
+  grid-column: 1 / -1;
+}
+:where([data-part="label"]) {
+  display: block;
+}
+:where([data-part="control"]) {
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+:where([data-part="ship-to-different"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="ship-to-different"] [data-part="control"]) {
+  inline-size: auto;
+  flex: none;
+}
+
+/* ── shipping / payment choices ───────────────────────────────────────────── */
+:where([data-part="shipping-methods"], [data-part="payment-methods"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  /* the parts chose <fieldset>; neutralize what the browser draws on it */
+  margin: 0;
+  padding: 0;
+  border: 0;
+  min-inline-size: 0;
+}
+:where([data-part="option"], [data-part="chosen"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="option-input"]) {
+  flex: none;
+}
+:where([data-part="option-cost"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="option-description"]) {
+  flex-basis: 100%;
+}
+
+/* ── line rows: cart lines, checkout summary, receipt items ───────────────── */
+:where([data-part="lines"], [data-part="items"], [data-part="notices"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+:where([data-part="row"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="media"]) {
+  flex: none;
+  inline-size: var(--commerce-media-size, 4rem);
+  max-inline-size: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+}
+:where(img[data-part="media"]) {
+  display: block;
+  block-size: auto;
+}
+:where([data-part="content"]) {
+  display: grid;
+  align-content: center;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+  flex: 1 1 8rem;
+  min-inline-size: 0;
+}
+:where([data-part="controls"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  flex: none;
+}
+:where([data-part="stepper"]) {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="line-total"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="row"] [data-part="error"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+
+/* ── totals, payment instructions (label ↔ value pairs) ───────────────────── */
+:where([data-part="totals"], [data-part="account"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="totals"] > *, [data-part="account"] > *) {
+  display: flex;
+  align-items: baseline;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="value"]) {
+  margin: 0;
+  margin-inline-start: auto;
+}
+
+/* ── coupon field ─────────────────────────────────────────────────────────── */
+:where([data-part="coupon-field"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="coupon-field"] [data-part="input"]) {
+  flex: 1 1 10rem;
+  min-inline-size: 0;
+}
+:where([data-part="coupon-field"] [data-part="error"], [data-part="applied"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+:where([data-part="applied"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+
+/* ── place order + its reasons ─────────────────────────────────────────────── */
+:where([data-part="blockers"]) {
+  display: grid;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+}
+:where([data-part="blocker"], [data-part="order-error"], [data-part="hint"]) {
+  margin: 0;
+}
+
+/* ── payment instructions ─────────────────────────────────────────────────── */
+:where([data-part="payment-instructions"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="description"]) {
+  margin: 0;
+}
+
+/* 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;
+}