@base44/app-plugin-commerce 0.5.1 → 0.6.1

package/src/commerce/storefront/AddressFields.jsx

@@ -0,0 +1,150 @@
+import React, { useId, useState } from "react";
+import { addressFieldSpec } from "@/commerce/utils";
+import { useCheckoutContext } from "./useCheckout";
+import { useCountries } from "./StorefrontProvider";
+import { REQUIRED_BILLING_FIELDS } from "./address";
+
+/**
+ * The checkout address form, headless — the one storefront section that ships
+ * as a component rather than as wiring reference, because hand-rolling it is
+ * where checkouts break: the state/province field must appear with the right
+ * options once a country is picked (shipping and taxes match on country *plus*
+ * state, so a form without it silently mis-prices US/CA/AU orders),
+ * `autoComplete` tokens are what make browser autofill work, and the server's
+ * "we don't ship there" belongs on the country field.
+ *
+ * It renders semantic fields and nothing else — no CSS ships with it. Every
+ * element carries `data-part` (`field`, `label`, `control`, `required`,
+ * `error`) plus `data-key`/`data-span`/`data-invalid`, so the store's own
+ * classes attach via `className`/`classes` props or `[data-part]` selectors.
+ * Field labels come from `addressFieldSpec` (plain conventions — rename any of
+ * them via `labels`). Required marks arm on first blur, never on load.
+ *
+ * Works inside `<CheckoutProvider>` (it reads `useCheckoutContext()`).
+ * `which="shipping"` renders null until `shipToDifferent` is on — the
+ * deliver-elsewhere checkbox itself stays yours, wired to
+ * `checkout.shipToDifferent` / `checkout.setShipToDifferent`.
+ *
+ * @param {object} props
+ * @param {"billing"|"shipping"} [props.which] which address this form edits.
+ * @param {boolean} [props.includeCompany] add the company field (default false).
+ * @param {boolean} [props.includePhone] keep the phone field (default true).
+ * @param {string[]} [props.omit] field keys to drop entirely.
+ * @param {Record<string, string>} [props.labels] label text per field key,
+ *   merged over the spec's defaults (e.g. `{ postcode: "ZIP code" }`).
+ * @param {string} [props.selectPlaceholder] the selects' empty-option text.
+ * @param {Function} [props.inputRender] `({ field, options, invalid, ...dom })`
+ *   — swaps the control only; spread `dom` onto your input.
+ * @param {Function} [props.fieldRender] `({ field, label, invalid, options, ...dom })`
+ *   — replaces the whole labeled block.
+ * @param {string} [props.className] class for the wrapping element.
+ * @param {{field?: string, label?: string, control?: string, error?: string}} [props.classes]
+ */
+export function AddressFields({
+  which = "billing",
+  includeCompany = false,
+  includePhone = true,
+  omit,
+  labels,
+  selectPlaceholder = "Select…",
+  inputRender: InputRender,
+  fieldRender,
+  className,
+  classes,
+}) {
+  const checkout = useCheckoutContext();
+  const { countries } = useCountries();
+  const idBase = useId();
+  const [touched, setTouched] = useState({});
+
+  const isBilling = which === "billing";
+  if (!isBilling && !checkout.shipToDifferent) return null;
+
+  const values = isBilling ? checkout.billing : checkout.shipping;
+  const set = isBilling ? checkout.updateBilling : checkout.updateShipping;
+  const omitted = new Set(omit ?? []);
+  const fields = addressFieldSpec({
+    countries,
+    country: values.country,
+    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+    includeEmail: isBilling, // one email per order, on billing
+    includeCompany,
+    includePhone,
+  }).filter((f) => !omitted.has(f.key));
+
+  return (
+    <div data-part="address-fields" data-which={which} className={className}>
+      {fields.map((f) => {
+        const id = `${idBase}-${which}-${f.key}`;
+        const value = values[f.key] ?? "";
+        const invalid = Boolean(touched[f.key] && f.required && !String(value).trim());
+        const dom = {
+          id,
+          value,
+          autoComplete: f.autoComplete,
+          onChange: (e) => set({ [f.key]: e && e.target ? e.target.value : e }),
+          onBlur: () => setTouched((t) => (t[f.key] ? t : { ...t, [f.key]: true })),
+        };
+        const labelText = labels?.[f.key] ?? f.label;
+        if (fieldRender) {
+          return (
+            <React.Fragment key={f.key}>
+              {fieldRender({ field: f, label: labelText, invalid, options: f.options, ...dom })}
+            </React.Fragment>
+          );
+        }
+        return (
+          <div
+            key={f.key}
+            data-part="field"
+            data-key={f.key}
+            data-span={f.colSpan}
+            data-invalid={invalid || undefined}
+            className={classes?.field}
+          >
+            <label data-part="label" className={classes?.label} htmlFor={id}>
+              {labelText}
+              {f.required && (
+                <span data-part="required" aria-hidden="true">
+                  *
+                </span>
+              )}
+            </label>
+            {InputRender ? (
+              <InputRender field={f} options={f.options} invalid={invalid} {...dom} />
+            ) : f.type === "select" ? (
+              <select
+                data-part="control"
+                className={classes?.control}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              >
+                <option value="">{selectPlaceholder}</option>
+                {f.options.map((o) => (
+                  <option key={o.value} value={o.value}>
+                    {o.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <input
+                data-part="control"
+                className={classes?.control}
+                type={f.type}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              />
+            )}
+            {f.key === "country" && checkout.addressError && (
+              <p data-part="error" role="alert" className={classes?.error}>
+                {checkout.addressError.message}
+              </p>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -12,7 +12,6 @@ import {
   storefrontErrorCode,
   storefrontErrorMessage,
 } from "@/commerce/utils";
-import { LabelsScope } from "./parts/labels";
 
 /**
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
@@ -27,9 +26,7 @@ import { LabelsScope } from "./parts/labels";
  *   it, so the cart badge and the cart page read different carts.
  *
  * Pass `base44`, or `store={createStorefront(base44)}` when other modules need
- * the same client. `labels` (optional) is the store's copy map for the parts
- * layer — pass it once here and every part resolves its words from it (the
- * key list and example live in the skill's install/02-storefront.md).
+ * the same client.
  *
  * What lives here, and why it must not be duplicated per page: the client (it
  * owns the cart_token lifecycle); store info, cached for the session —
@@ -41,7 +38,7 @@ import { LabelsScope } from "./parts/labels";
 
 const StorefrontContext = createContext(null);
 
-export function StorefrontProvider({ base44, store, labels, children }) {
+export function StorefrontProvider({ base44, store, children }) {
   const client = useMemo(
     () => store ?? createStorefront(base44),
     [store, base44],
@@ -112,11 +109,7 @@ export function StorefrontProvider({ base44, store, labels, children }) {
     () => ({ client, info, infoError, cart, cartError, mutationError, runCart, clearCart }),
     [client, info, infoError, cart, cartError, mutationError, runCart, clearCart],
   );
-  return (
-    <StorefrontContext.Provider value={value}>
-      <LabelsScope labels={labels}>{children}</LabelsScope>
-    </StorefrontContext.Provider>
-  );
+  return <StorefrontContext.Provider value={value}>{children}</StorefrontContext.Provider>;
 }
 
 /** Advanced escape hatch: the raw provider state. Prefer the hooks below. */

package/src/commerce/storefront/cartUI.jsx

@@ -1,45 +1,26 @@
-import React, {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 
 /**
- * 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.
+ * 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.
  *
  * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
- * layout; the layout renders the drawer off `open`.
+ * layout; the layout then renders the panel off `open`.
  *
- * ⚑ 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>`).
+ * ⚑ **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.
  *
- * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, panelRef, panelId }`.
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
  * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`
  * integrates without requiring the provider).
  *
@@ -48,9 +29,6 @@ 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();
@@ -74,9 +52,6 @@ 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(() => {
@@ -88,36 +63,15 @@ 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, panelId, openOnAdd],
+    [open, openCart, closeCart, toggleCart, openOnAdd],
   );
 
   return (

package/src/commerce/storefront/index.js

@@ -35,6 +35,10 @@
  * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — render-prop components for
  *     the two checkout choices that are store data, never hardcoded.
+ * - `AddressFields` — the ONE rendered component in the layer: the checkout
+ *     address form (state/province appears per country, `autoComplete` kept,
+ *     required marks arm on blur). Unstyled; style it via `data-part`
+ *     selectors or its `className`/`classes` props.
  *
  * Re-exported from `@/commerce/utils` so one import line covers a page:
  * `variantAxes` (axes → options with selected/disabled/stock derived),
@@ -62,23 +66,6 @@
  *
  * The catalog and product surfaces are where the design freedom lives: these
  * hooks hand you resolved data, and the rendering is entirely yours.
- *
- * **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
- * 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,
@@ -89,9 +76,10 @@ export {
   useCountries,
   useCart,
 } from "./StorefrontProvider";
-export { useCheckout, CheckoutProvider, useCheckoutContext, useInCheckout } from "./useCheckout";
+export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
 export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
+export { AddressFields } from "./AddressFields";
 export { CartUIProvider, useCartUI } from "./cartUI";
 export {
   REQUIRED_BILLING_FIELDS,
@@ -100,18 +88,6 @@ export {
   isShippingAddressComplete,
 } 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";
-export { OrderReceived } from "./parts/orderReceived";
-export { REQUIRED_LABEL_KEYS } from "./parts/labels";
-
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
 export { useProduct, useAddToCart } from "./useProduct";

package/src/commerce/storefront/useCheckout.jsx

@@ -381,30 +381,3 @@ 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;
-}

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

@@ -1,150 +0,0 @@
----
-read_when: "A cart row, checkout section or receipt region needs structure the parts' props can't express, and you are about to build it on the raw hooks."
----
-
-# Custom sections on the raw hooks
-
-The parts (`Cart.*`, `CartDrawer.*`, `Checkout.*`, `OrderReceived.*`) are thin
-compositions over the hooks below — same providers, same shared state — so
-**replacing one section while keeping the others is normal**: a bespoke
-shipping selector between `<Checkout.AddressFields>` and
-`<Checkout.PaymentMethods>` reads the same checkout the parts do.
-
-Work down this ladder; each rung is cheaper than the next:
-
-1. **`classes` / CSS** on `data-part` — almost every "the part looks wrong" is this rung.
-2. **Labels** — a wording problem is a copy-file problem, never a code problem.
-3. **`…Render` overrides** — `optionRender`, `lineRender`, `itemRender`, `inputRender`/`fieldRender`: your element, the part's wiring.
-4. **This file** — rebuild one section on its hook.
-5. **Edit the part's source** (`src/commerce/storefront/parts/`) — legitimate when a *user requirement* exceeds the props; the edited part is the store's code to maintain.
-
-Never re-implement what a hook does (quantity clamps, totals math, repricing,
-drawer state) — that is where storefront bugs cluster. And keep the parts'
-guarantees when you replace them: every state worded, busy scoped to the row,
-a disabled button that says why.
-
-## What the custom-section hooks resolve to
-
-| Call | Resolves to |
-|---|---|
-| `useCartLine(item)` | `{ quantity, setQuantity, increase, decrease, remove, pending, error, canIncrease, canDecrease, maxQuantity, atMax, atMin }` — optimistic quantity, clicks coalesced (~250ms), rollback on rejection. `pending` is **this row's** flag: true while its request is out, false only after the new cart view lands — the only mutation-settled signal (`useCart().status` never returns to `"loading"`). |
-| `useCartUI()` | `{ open, openCart, closeCart, toggleCart, panelRef, panelId }` — drawer state and behavior on `<CartUIProvider>` (Esc, open-on-add, close-on-navigate; `panelRef` moves focus in/out and makes a closed-but-mounted panel `inert`). The drawer's overlay and panel are your markup. |
-| `useCheckoutContext()` | the address (`billing`, `updateBilling`, `shipping`, `updateShipping`, `shipToDifferent`, `setShipToDifferent`, `missingBillingFields`, `addressError`), the choices (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`, `paymentMethods`, `paymentMethod`, `setPaymentMethod`, `selectedGateway`), and the gate (`blockers`, `canPlaceOrder`, `placing`, `stage`, `orderError`, `placeOrder`) — plus `cart`. Works under `<Checkout.Root>` (or your own `<CheckoutProvider>`). |
-| `useOrderReturn()` | `{ status, order, lines, paymentLink, paymentInstructions, error, reload }` — `status`: `"loading" \| "paid" \| "unpaid" \| "cancelled" \| "error"`; `lines` normalized (`image` is `{src, alt}\|null`, `totalLabel` pre-formatted); an order's totals are **flat** (`order.total`, no `order.totals`). |
-| `cartTotalsLines(cart, { formatMoney, labels })` / `orderTotalsLines(order, …)` | `[{ key, label, amount, formatted, hidden, emphasis }]` — keys `subtotal` `discount` `shipping` `tax` `total`; discount/tax are produced and flagged `hidden` when zero, so a mapping renderer can't drop them. |
-| `addressFieldSpec({ countries, country, required, includeEmail })` | `[{ key, label, type, required, autoComplete, options, colSpan }]` — the state field appears (as a select where the country carries states) once `country` is passed. |
-| `ShippingMethodPicker` / `PaymentMethodPicker` | render-prop components the parts wrap — `children({ status, methods, chosen, mustChoose, single, syncing, hint, … })` / `children({ gateways, selected, single, hint })`; every option decorated with `selected`, `select()`, `costLabel`. |
-
-## Reference wiring
-
-Words below come from the same copy file the parts read (`STORE_COPY`) — a
-custom section never hardcodes them.
-
-**A custom cart row** — `<CartLine>` binds `useCartLine` per row without a
-hook-in-a-loop:
-
-```jsx
-{cart.items.map((item) => (
-  <CartLine key={item.item_key} line={item}>
-    {(l) => (
-      <li aria-busy={l.pending}>          {/* busy scope is THIS row, never the cart */}
-        {item.name} {attributesLabel(item.attributes)} {formatMoney(item.total)}
-        <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
-                aria-label={STORE_COPY.aria.decrease(item.name)}>−</button>
-        {l.quantity}
-        <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
-                aria-label={STORE_COPY.aria.increase(item.name)}>+</button>
-        <button onClick={l.remove} disabled={l.pending}
-                aria-label={STORE_COPY.aria.remove(item.name)}>×</button>
-        {l.error && <p role="alert">{l.error.message}</p>}
-      </li>
-    )}
-  </CartLine>
-))}
-```
-
-Give repeated controls unique accessible names (the item's name in the label)
-— three identical "Remove" buttons are ambiguous to a screen reader and to a
-script driving the page.
-
-**A custom shipping step** — the picker encodes the branching a checkout must
-not skip:
-
-```jsx
-<ShippingMethodPicker>
-  {({ hint, mustChoose, methods, chosen }) => (
-    <fieldset>{/* renders null for a virtual cart */}
-      {hint && <p role={hint.severity === "error" ? "alert" : "status"}>
-        {hint.serverMessage ?? STORE_COPY.shipping[hint.code]}</p>}
-      {mustChoose && methods.map((m) => (
-        <label key={m.id}>
-          <input type="radio" name="ship" checked={m.selected} onChange={m.select} />
-          {m.title} {m.costLabel}
-        </label>
-      ))}
-      {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
-    </fieldset>
-  )}
-</ShippingMethodPicker>
-```
-
-Never render `cart.chosen_shipping_method` directly — it is a rate id; `chosen`
-arrives resolved. A single option still *shows* what it is, never a picker of
-one. `PaymentMethodPicker` is the same shape over `gateways` (titles and
-descriptions are the admin's copy — render them, don't invent your own).
-
-**A custom address form** — bind the spec, never a hand-typed field list:
-
-```jsx
-function AddressFields({ which }) {
-  const c = useCheckoutContext();
-  const { countries } = useCountries();     // [] until store info lands — never null
-  const isBilling = which === "billing";
-  const values = isBilling ? c.billing : c.shipping;
-  const set = isBilling ? c.updateBilling : c.updateShipping;
-  const fields = addressFieldSpec({
-    countries, country: values.country,
-    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
-    includeEmail: isBilling,                // one email per order, on billing
-  });
-  return fields.map((f) => (
-    <div key={f.key}>
-      <label htmlFor={`${which}-${f.key}`}>{STORE_COPY.fields[f.key]}{f.required && " *"}</label>
-      {f.type === "select" ? (
-        <select id={`${which}-${f.key}`} value={values[f.key] ?? ""} autoComplete={f.autoComplete}
-                onChange={(e) => set({ [f.key]: e.target.value })}>
-          <option value="">{STORE_COPY.fields.select_placeholder}</option>
-          {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
-        </select>
-      ) : (
-        <input id={`${which}-${f.key}`} type={f.type} value={values[f.key] ?? ""}
-               autoComplete={f.autoComplete} onChange={(e) => set({ [f.key]: e.target.value })} />
-      )}
-      {/* "we don't ship there" is an address-level error — it belongs on country */}
-      {f.key === "country" && c.addressError && <span role="alert">{c.addressError.message}</span>}
-    </div>
-  ));
-}
-```
-
-⚑ Passing `country` is what makes the state/province field appear — rates and
-taxes match on country *plus* state, so a form without it silently mis-prices
-US/CA/AU orders. ⚑ Keep every `autoComplete` token — it is what makes browser
-autofill work.
-
-**A custom place-order region** — the gate explains itself:
-
-```jsx
-<button type="button" onClick={c.placeOrder} disabled={!c.canPlaceOrder || c.placing}>
-  {c.placing ? STORE_COPY.placeOrder.placing : STORE_COPY.placeOrder.label}
-</button>
-{c.orderError && <p role="alert">{c.orderError.message}</p>}
-{!c.canPlaceOrder && c.blockers.map((code) => <p key={code}>{STORE_COPY.blockers[code]}</p>)}
-```
-
-`placeOrder` is safe as a direct `onClick` handler (an event is not read as
-order fields) and resolves `{ ok, result }` / `{ ok: false, error }` without
-throwing. ⚑ Keep the `stage === "submitted"` guard above any empty-cart branch
-— placing an order clears the cart, and without the guard the page flashes
-"your bag is empty" over a just-placed order (`Checkout.Root`'s gates encode
-this ordering; a fully hand-built page must re-encode it).