@base44/app-plugin-commerce 0.4.0 → 0.5.0

package/skills/commerce/references/storefront-parts.md

@@ -0,0 +1,184 @@
+---
+read_when: "You are writing the store's copy file for the parts, the CSS for the cart/drawer/checkout/receipt, or swapping one of their controls for your own element."
+---
+
+# The parts' words and look
+
+The two inputs that make the commodity surfaces *this* store's: the copy file
+(every word the parts render) and the CSS (everything they look like). The parts
+themselves are contracted in install/02-storefront.md.
+
+## The copy file — every word, written once
+
+The parts ship **no customer-facing string and no fallback**: a label that isn't
+provided renders a visible `⟨copy: path⟩` placeholder and warns once in the
+console. Copy the map below into `src/copy.js`, pass it once
+(`<StorefrontProvider labels={STORE_COPY}>`), and ⚑ **rewrite every value in
+this store's voice** — the English here is *reference*; shipped verbatim it is
+how storefronts end up sounding alike (`aria.*` name controls for screen
+readers; templates take the item's name):
+
+```js
+export const STORE_COPY = {
+  placeOrder: { label: "Place order", placing: "Placing your order…" },
+  blockers: {
+    empty_cart: "Your bag is empty.", billing_incomplete: "Fill in your details above.",
+    shipping_address_incomplete: "Finish the delivery address.",
+    shipping_address_required: "Enter your address to see delivery options.",
+    shipping_method_required: "Choose a delivery option.",
+    shipping_not_available: "We can't deliver to that address.",
+    payment_method_required: "Choose how you'd like to pay.",
+    cart_loading: "One moment — loading your bag.", shipping_recalculating: "Updating delivery costs…",
+  },
+  shipping: {
+    missing_address: "Delivery options appear once your address is entered.",
+    none_available: "We don't deliver to that address yet.",
+    syncing: "Updating delivery options…",
+  },
+  payment: { none_available: "Checkout is unavailable right now — please try again later." },
+  coupon: { placeholder: "Gift or promo code", apply: "Apply", remove: "Remove" },
+  fields: {
+    first_name: "First name", last_name: "Last name", email: "Email", company: "Company",
+    address_1: "Address", address_2: "Apartment, suite (optional)", country: "Country",
+    city: "City", state: "State / Province", postcode: "Postal code",
+    phone: "Phone (optional)", select_placeholder: "Select…",
+  },
+  totals: { subtotal: "Subtotal", discount: "Discount", shipping: "Shipping", tax: "Tax", total: "Total" },
+  bank: { account_name: "Account name", account_number: "Account number", bank_name: "Bank",
+          sort_code: "Sort code", iban: "IBAN", bic: "BIC" },
+  aria: {
+    trigger: "Open your bag", drawer: "Your bag", close: "Close",
+    increase: (name) => `Add one more ${name}`, decrease: (name) => `Remove one ${name}`,
+    remove: (name) => `Remove ${name} from your bag`,
+    shipping_group: "Delivery options", payment_group: "Payment methods",
+  },
+};
+```
+
+Blocker lines are what a disabled place-order button says — one per code, naming
+the thing the customer can fix (`cart_loading`/`shipping_recalculating` are quiet
+transients, not errors); `shipping.*`/`payment.*` are the pickers' dead-ends,
+with the server's own message rendered instead where one exists. The key tree is
+frozen in code as `REQUIRED_LABEL_KEYS`, and a part or a page `Root` takes a
+`labels` slice of the same shape when one surface needs different wording.
+
+Headings, empty/loading/submitted screens, links and anything else in *your*
+markup are ordinary JSX — the copy file covers only what the parts render.
+
+## Styling the parts
+
+The parts ship **layout geometry and nothing else** (`src/commerce/storefront/parts/parts.css`,
+loaded automatically by `@/commerce/storefront`): field grids, labels above
+full-width controls, media as a fixed square, rows as media + content +
+controls with the money pushed right, totals as label-left/value-right. Nothing
+in it carries color, background, border, radius, shadow, font or text
+decoration — a release check enforces that — so an unstyled store reads as
+*unfinished*, never as broken, and the look is entirely yours.
+
+It also stops at the edge of a part: **arranging sections is yours** — the
+checkout's columns, the space between sections, and the cart drawer, whose
+overlay and panel you render and position yourself (`useCartUI()` keeps its
+state, focus handling and inert-while-closed; see install/02-storefront.md).
+
+**Every rule is wrapped in `:where()`, so its specificity is 0.** A plain
+`[data-part="row"] { display: grid }` in your stylesheet wins — no `!important`,
+no cascade fights, no need to know what the sheet did.
+
+## Two ways in, one vocabulary
+
+```css
+/* index.css — selectors, next to the store's design classes */
+[data-part="control"] { … }
+[data-part="option"][data-state="selected"] { … }
+[data-part="row"][data-pending] { opacity: .55; }
+```
+
+```jsx
+{/* or classes, keyed by the same data-part names */}
+<Cart.Lines className="bag" classes={{ row: "bag-row", media: "bag-thumb", "line-total": "price" }} />
+```
+
+Tailwind reaches inner parts with arbitrary variants
+(`className="[&_[data-part=option]]:choice-row"`) or `@apply` inside a design
+class. Either way the names are the ones below.
+
+## The minimum that makes a store look designed
+
+⚑ **Style the controls.** Browser-default inputs are a white box in a system
+font — on a dark or branded storefront that alone reads as unfinished:
+
+```css
+[data-part="control"], [data-part="input"] {
+  border: …; background: …; color: inherit; font: inherit; padding: …;
+}
+[data-part="control"]:focus-visible { outline: …; }      /* keep a visible focus ring */
+[data-part="field"][data-invalid] [data-part="control"] { border-color: …; }
+```
+
+Then, in the store's own values: the labels (`[data-part="label"]` — size,
+tracking, case), the option rows (`[data-part="option"]` — padding, border,
+and the `[data-state="selected"]` treatment, which is the one control customers
+look for), the totals (`[data-part="value"]`, `[data-emphasis]` for the total
+line), the buttons (`[data-part="place-order"]`, `apply`, `remove`,
+`increase`/`decrease`), and the notices (`[data-part="error"]`, `blocker`, `hint` —
+`[data-severity="error"]` marks the loud ones). The drawer's own surface and
+scrim are your elements, so they carry your classes, not `data-part` selectors.
+
+**The parts add no outer margins** — space *between* sections comes from the
+containers you wrap them in (`gap` on your checkout grid, your aside, your
+drawer panel's column).
+
+## Tuning the geometry
+
+Set these anywhere — `:root`, a page, one part — instead of rewriting the rules:
+
+| Custom property | Default | Controls |
+|---|---|---|
+| `--commerce-gap` | `1rem` | fields, rows, options, panel sections |
+| `--commerce-gap-tight` | `0.4rem` | label→control, name→attributes, stepper |
+| `--commerce-field-columns` | `2` | address-form columns (set `1` in a narrow aside or a media query) |
+| `--commerce-media-size` | `4rem` | cart/summary thumbnail edge |
+
+## `data-part` inventory
+
+| Part root | Inner `data-part`s | State attributes |
+|---|---|---|
+| `address-fields`; `ship-to-different` | field · label · required · control · error | `data-which`, `data-key`, `data-span`, `data-invalid` |
+| `shipping-methods` `payment-methods` | hint · option · option-input · option-label · option-cost / option-description · chosen | `data-state="selected"`, `data-syncing`, `data-severity` |
+| `lines` `items`; `notices` | row · media · content · name · attributes · controls · stepper · increase · decrease · quantity · remove · line-total · error; notice | `data-pending`, `data-empty`, `data-code` |
+| `totals`; `payment-instructions` | row · label · value; description · account | `data-key`, `data-emphasis` |
+| `coupon-field` | input · apply · error · applied · code · remove | `data-busy` |
+| `place-order` · `order-error` · `blockers` | blocker | `data-state="placing"`, `data-code` |
+| `trigger` · `close` | — (the drawer's layer, scrim and panel are your elements) | `data-state="open\|closed"` |
+
+`media` is an `<img>` when the line has an image and an empty `<div
+data-part="media" data-empty>` when it doesn't — same box either way, so style
+the placeholder (`[data-empty]`) rather than letting it render as a hole. ⚑ **A
+cart, summary or receipt that shows no thumbnails is a `media={false}` prop, not
+a CSS `display: none`** — the prop renders nothing at all, while hiding leaves an
+empty box in the layout and the accessibility tree.
+
+## Overrides — your element, the part's wiring
+
+CSS covers how a control *looks*; these cover the cases where the **element
+itself** is the design decision. Each one keeps the part's state, gating and
+accessibility wiring and hands you what to render from:
+
+| Prop | On | Receives | Replaces |
+|---|---|---|---|
+| `inputRender` | `AddressFields` | `{ field, id, value, onChange, onBlur, invalid, autoComplete, options }` | the input/select only (label, required mark and error stay) |
+| `fieldRender` | `AddressFields` | the same, plus `label` | the whole labeled block |
+| `controlRender` | `ShipToDifferent` | `{ checked, onChange, toggle }` | the checkbox — a switch, a segmented control, two buttons |
+| `optionRender` | `ShippingMethods`, `PaymentMethods` | the decorated option (`title`, `costLabel`/`description`, `selected`, `select()`) | **the whole option element**, radio included |
+| `stepperRender` | `Cart.Lines` | `(controls, item)` — the `useCartLine` set | the quantity control alone (a `<select>`, a number input, your buttons) |
+| `inputRender` | `CouponField` | `{ value, onChange, onKeyDown, placeholder, disabled }` | the code field; apply button and messages stay |
+| `lineRender` / `itemRender` | `Cart.Lines`, `Checkout.Items`, `OrderReceived.Items` | `(item, controls)` / `(item)` | a whole row |
+
+⚑ **A replaced control still owes its semantics.** The kit's defaults are real
+form controls; if yours are not, carry the equivalent — keyboard operability, a
+readable state (`role="radio"` + `aria-checked`, `role="switch"`), and an
+accessible name. `show` (above) is for *removing* an element; these are for
+*replacing* it.
+
+A whole section that needs different structure drops to its hook instead:
+[`./storefront-custom.md`](./storefront-custom.md).

package/src/commerce/storefront/cartUI.jsx

@@ -1,26 +1,45 @@
-import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { useLocation } from "react-router-dom";
 
 /**
- * Cart drawer/panel state, headless: `open` plus the handlers to change it,
- * and the two behaviors every drawer needs but a hand-written one forgets —
- * it closes when the route changes (`closeOnNavigate`) and it opens when an
- * item lands in the cart (`openOnAdd`, wired through `useAddToCart`; pass false
- * for a navigate-to-bag flow). Esc closes it. You own every element, class and
- * attribute.
+ * Cart drawer state and behavior, headless — **the drawer's surface is yours**:
+ * you render the overlay and the panel, and own their position, size, padding,
+ * animation and every class on them. What lives here is the part that is the
+ * same in every store and easy to get wrong:
+ *
+ * - `open` + `openCart`/`closeCart`/`toggleCart`.
+ * - Esc closes; the route changing closes (`closeOnNavigate`); an item landing
+ *   in the cart opens (`openOnAdd`, wired through `useAddToCart` — pass false
+ *   for a navigate-to-bag flow).
+ * - **Focus.** Attach `panelRef` to your panel element: focus moves into it
+ *   when the drawer opens and returns to whatever had it when the drawer
+ *   closes (give the panel `tabIndex={-1}` so it can receive it).
+ * - **A closed-but-mounted panel is made `inert`** while `panelRef` is
+ *   attached — the classic drawer bug is a panel translated off-screen whose
+ *   buttons stay clickable, tab-able and readable to screen readers. Animate
+ *   the slide freely; the closed panel stops being interactive by itself.
+ * - `panelId` — put it on your panel as `id`; the kit's `<CartDrawer.Trigger>`
+ *   already points `aria-controls` at it.
  *
  * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
- * layout; the layout then renders the panel off `open`.
+ * layout; the layout renders the drawer off `open`.
  *
- * ⚑ **Render the drawer conditionally — `{ui.open && …}`.** The classic drawer
- * bug is a panel translated off-screen but still mounted: its buttons stay
- * clickable, tab-able and visible to screen readers. Unmounting when closed is
- * the trivial fix; if you keep it mounted to animate the slide, that concern is
- * yours again — set the `inert` attribute while closed. The overlay is a
- * click-away surface (`aria-hidden`, no tab stop) — it is not the close control;
- * a named close button inside the panel is.
+ * ⚑ Your panel is the dialog: `role="dialog" aria-modal="true"` plus a name
+ * (`aria-label`/`aria-labelledby`). ⚑ The overlay is a click-away surface
+ * (`aria-hidden`, no tab stop) — it is *not* the close control; a named close
+ * button inside the panel is (`<CartDrawer.Close>`).
  *
- * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, panelRef, panelId }`.
  * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`
  * integrates without requiring the provider).
  *
@@ -29,6 +48,9 @@ import { useLocation } from "react-router-dom";
 
 const CartUIContext = createContext(null);
 
+/** Layout effect where there is a DOM; plain effect on the server (no warning). */
+const useDrawerEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
 /** Internal: closes the drawer whenever the route changes (needs a Router above). */
 function CloseOnNavigate({ close }) {
   const { pathname } = useLocation();
@@ -52,6 +74,9 @@ export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, child
   const openCart = useCallback(() => setOpen(true), []);
   const closeCart = useCallback(() => setOpen(false), []);
   const toggleCart = useCallback(() => setOpen((o) => !o), []);
+  const panelId = useId();
+  const panelRef = useRef(null);
+  const restoreRef = useRef(null);
 
   // Esc closes — the keyboard's way out is Esc and the named close button.
   useEffect(() => {
@@ -63,15 +88,36 @@ export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, child
     return () => window.removeEventListener("keydown", onKey);
   }, [open]);
 
+  // Focus into the store's panel on open, back where it came from on close, and
+  // a closed-but-mounted panel is inert — all on whatever element the store
+  // attached `panelRef` to, so the drawer's markup and animation stay theirs.
+  // Layout effect: before paint, so an animating panel is never briefly live.
+  useDrawerEffect(() => {
+    const node = panelRef.current;
+    if (open) {
+      restoreRef.current = typeof document !== "undefined" ? document.activeElement : null;
+      if (node) {
+        node.inert = false;
+        node.focus?.({ preventScroll: true });
+      }
+    } else {
+      if (node) node.inert = true;
+      restoreRef.current?.focus?.();
+      restoreRef.current = null;
+    }
+  }, [open]);
+
   const value = useMemo(
     () => ({
       open,
       openCart,
       closeCart,
       toggleCart,
+      panelRef,
+      panelId,
       onItemAdded: openOnAdd ? openCart : null,
     }),
-    [open, openCart, closeCart, toggleCart, openOnAdd],
+    [open, openCart, closeCart, toggleCart, panelId, openOnAdd],
   );
 
   return (

package/src/commerce/storefront/index.js

@@ -64,15 +64,19 @@
  * **Parts** — for the four commodity surfaces only (cart, drawer, checkout,
  * order-received), `Checkout.*` / `Cart.*` / `CartDrawer.*` /
  * `OrderReceived.*` render each section's correct semantic markup with zero
- * CSS, zero copy and zero navigation: you place them in YOUR layout, style
- * them via `data-part`/`data-state` selectors or `className`/`classes`, and
- * supply every word through `labels` (chain: part prop → page Root →
- * `<StorefrontProvider labels={…}>`; a missing key renders a visible
- * `⟨copy: …⟩` placeholder). Contract tables, the copy example and the
- * `data-part` inventory: the commerce skill's install/02-storefront.md — use
- * the parts from there, not from these files. They compose the hooks above,
- * so dropping one section down to its hook is normal; they are also the
- * app's own source, editable when a requirement outgrows their props.
+ * copy and zero navigation: you place them in YOUR layout, and supply every
+ * word through `labels` (chain: part prop → page Root → `<StorefrontProvider
+ * labels={…}>`; a missing key renders a visible `⟨copy: …⟩` placeholder).
+ * They carry **layout geometry and nothing else** (`parts/parts.css`: field
+ * grids, row and thumbnail sizing, totals rows, the drawer panel — no color,
+ * type or border, every rule at zero specificity), so an unstyled store looks
+ * unfinished but never broken; the look arrives as your CSS on
+ * `data-part`/`data-state`, or via `className`/`classes`. Contract tables, the
+ * copy example and the `data-part` inventory: the commerce skill's
+ * install/02-storefront.md — use the parts from there, not from these files.
+ * They compose the hooks above, so dropping one section down to its hook is
+ * normal; they are also the app's own source, editable when a requirement
+ * outgrows their props.
  */
 export {
   StorefrontProvider,
@@ -83,7 +87,7 @@ export {
   useCountries,
   useCart,
 } from "./StorefrontProvider";
-export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
+export { useCheckout, CheckoutProvider, useCheckoutContext, useInCheckout } from "./useCheckout";
 export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
 export { CartUIProvider, useCartUI } from "./cartUI";
@@ -95,6 +99,11 @@ export {
 } from "./address";
 
 // ── parts: guided sections for the commodity surfaces ──────────────────────
+// The parts' layout geometry (field grids, row/media sizing, totals rows, the
+// drawer panel) — structure only, no look, every rule at zero specificity so
+// the store's CSS wins. See parts/parts.css for the custom properties.
+import "./parts/parts.css";
+
 export { Checkout } from "./parts/checkout";
 export { Cart } from "./parts/cart";
 export { CartDrawer } from "./parts/drawer";

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

@@ -3,6 +3,7 @@ import { attributesLabel } from "@/commerce/utils";
 import { useCart, useFormatMoney } from "../StorefrontProvider";
 import { CartLine } from "../useCartLine";
 import { label, nameLabel, useResolvedLabels } from "./labels";
+import { visible } from "./visibility";
 import { CouponField, Totals } from "./shared";
 
 /**
@@ -34,10 +35,22 @@ const Ready = gate("Ready", "ready");
 /**
  * The line rows, with the interaction premade per row (optimistic quantity,
  * coalesced clicks, rollback, per-row `pending` — never a cart-wide busy
- * state). `lineRender(item, controls)` replaces a row wholesale; `item.slug`
- * is there when the store's row links to the product page.
+ * state).
+ *
+ * - `show` decides which of the row's elements render — `media`, `attributes`,
+ *   `stepper`, `remove`, `lineTotal` (`show={{ media: false }}` is a text-only
+ *   bag; `show={["media", "lineTotal"]}` is exactly those two). Nothing lands in
+ *   the DOM for a hidden element, so it costs no layout and no screen-reader
+ *   announcement. `stepper: false` still shows the quantity, as text.
+ * - `stepperRender(controls, item)` replaces the quantity control alone — a
+ *   `<select>`, a number input, the store's own buttons — while the row keeps its
+ *   layout (`controls` is the `useCartLine` set: `quantity`, `increase`,
+ *   `decrease`, `setQuantity`, `canIncrease`, `canDecrease`, `pending`).
+ * - `lineRender(item, controls)` replaces a row wholesale; `item.slug` is there
+ *   when the store's row links to the product page.
  */
-function Lines({ lineRender, className, classes, labels: partLabels }) {
+function Lines({ show, stepperRender, lineRender, className, classes, labels: partLabels }) {
+  const vis = visible(show);
   const { status, cart } = useCart();
   const formatMoney = useFormatMoney();
   const L = useResolvedLabels(partLabels);
@@ -56,53 +69,68 @@ function Lines({ lineRender, className, classes, labels: partLabels }) {
                 aria-busy={l.pending}
                 className={classes?.row}
               >
-                {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="name" className={classes?.name}>{item.name}</span>
-                {attributesLabel(item.attributes) ? (
-                  <span data-part="attributes" className={classes?.attributes}>
-                    {attributesLabel(item.attributes)}
-                  </span>
-                ) : null}
-                <span data-part="stepper" className={classes?.stepper}>
-                  <button
-                    type="button"
-                    data-part="decrease"
-                    className={classes?.decrease}
-                    onClick={l.decrease}
-                    disabled={!l.canDecrease || l.pending}
-                    aria-label={nameLabel(L, "aria.decrease", item.name)}
-                  >
-                    −
-                  </button>
-                  <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
-                  <button
-                    type="button"
-                    data-part="increase"
-                    className={classes?.increase}
-                    onClick={l.increase}
-                    disabled={!l.canIncrease || l.pending}
-                    aria-label={nameLabel(L, "aria.increase", item.name)}
-                  >
-                    +
-                  </button>
+                {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>
-                <button
-                  type="button"
-                  data-part="remove"
-                  className={classes?.remove}
-                  onClick={l.remove}
-                  disabled={l.pending}
-                  aria-label={nameLabel(L, "aria.remove", item.name)}
-                >
-                  ×
-                </button>
-                <span data-part="line-total" className={classes?.["line-total"]}>
-                  {formatMoney(item.total)}
+                <span data-part="controls" className={classes?.controls}>
+                  {vis("stepper") && stepperRender && stepperRender(l, item)}
+                  {vis("stepper") && !stepperRender && (
+                    <span data-part="stepper" className={classes?.stepper}>
+                      <button
+                        type="button"
+                        data-part="decrease"
+                        className={classes?.decrease}
+                        onClick={l.decrease}
+                        disabled={!l.canDecrease || l.pending}
+                        aria-label={nameLabel(L, "aria.decrease", item.name)}
+                      >
+                        −
+                      </button>
+                      <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
+                      <button
+                        type="button"
+                        data-part="increase"
+                        className={classes?.increase}
+                        onClick={l.increase}
+                        disabled={!l.canIncrease || l.pending}
+                        aria-label={nameLabel(L, "aria.increase", item.name)}
+                      >
+                        +
+                      </button>
+                    </span>
+                  )}
+                  {!vis("stepper") && (
+                    <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
+                  )}
+                  {vis("remove") && (
+                    <button
+                      type="button"
+                      data-part="remove"
+                      className={classes?.remove}
+                      onClick={l.remove}
+                      disabled={l.pending}
+                      aria-label={nameLabel(L, "aria.remove", item.name)}
+                    >
+                      ×
+                    </button>
+                  )}
                 </span>
+                {vis("lineTotal") && (
+                  <span data-part="line-total" className={classes?.["line-total"]}>
+                    {formatMoney(item.total)}
+                  </span>
+                )}
                 {l.error && (
                   <p data-part="error" role="alert" className={classes?.error}>{l.error.message}</p>
                 )}