@base44/app-plugin-commerce 0.2.5 → 0.2.6

package/src/commerce/storefront/cartUI.jsx

@@ -0,0 +1,190 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useLocation } from "react-router-dom";
+import { useCart } from "./StorefrontProvider";
+
+/**
+ * Cart drawer/panel state, headless. Every store with a cart drawer needs the
+ * same non-visual machinery, and it is where hand-written drawers reliably go
+ * wrong: the drawer must close on route change, be **inert** when closed (not
+ * merely invisible — hidden-but-mounted buttons stay clickable and tab-able),
+ * carry dialog semantics, close on Esc, and return focus to its trigger.
+ * `useCartUI` owns all of it; you own every pixel.
+ *
+ * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
+ * layout. Then the layout is three spreads:
+ *
+ *   function StoreLayout() {
+ *     const ui = useCartUI();
+ *     return (<>
+ *       <header>… <button {...ui.triggerProps} className="…">Bag ({itemCount})</button></header>
+ *       <Outlet />
+ *       <div {...ui.overlayProps} className={ui.open ? "…" : "…"} />
+ *       <aside {...ui.panelProps} className={ui.open ? "…translate-x-0" : "…translate-x-full"}>
+ *         <button {...ui.closeButtonProps} className="…">×</button>
+ *         {…your cart rows: useCart + CartLine…}
+ *       </aside>
+ *     </>);
+ *   }
+ *
+ * What each prop set carries:
+ * - `triggerProps` — onClick (toggle), `aria-expanded`/`aria-controls`/
+ *   `aria-haspopup`, an item-count `aria-label`, and the ref used to restore
+ *   focus on close. Spread your own `aria-label` after it to override.
+ * - `panelProps` — `role="dialog"`, `aria-modal`, `aria-label`, `data-state`
+ *   (`"open"|"closed"` — style/animate off it), focus target on open, and the
+ *   **inert** DOM property while closed, so a translated-off-screen drawer's
+ *   controls genuinely stop existing for clicks, Tab and screen readers. Keep
+ *   the panel mounted (animate with classes); don't also conditionally unmount.
+ * - `overlayProps` — click-to-close, `aria-hidden`, no tab stop. The overlay is
+ *   not a second "close" control; the named close button is `closeButtonProps`.
+ * - Esc closes; route changes close (`closeOnNavigate`); a successful
+ *   add-to-cart opens (`openOnAdd`, via `useAddToCartButton` — pass false for a
+ *   navigate-to-bag flow instead).
+ *
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, triggerProps,
+ * overlayProps, panelProps, closeButtonProps }`. `useCartUIOptional()` returns
+ * null instead of throwing (how `useAddToCartButton` integrates without
+ * requiring the provider).
+ *
+ * A store whose cart is a page, not a drawer, skips this provider entirely.
+ */
+
+const CartUIContext = createContext(null);
+
+/** Internal: closes the drawer whenever the route changes (needs a Router above). */
+function CloseOnNavigate({ close }) {
+  const { pathname } = useLocation();
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    close();
+  }, [pathname, close]);
+  return null;
+}
+
+/**
+ * @param {{closeOnNavigate?: boolean, openOnAdd?: boolean, label?: string,
+ *   children: React.ReactNode}} props `label` names the dialog for assistive
+ *   tech and the default trigger/close labels (default "Cart").
+ */
+export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, label = "Cart", children }) {
+  const [open, setOpen] = useState(false);
+  const openCart = useCallback(() => setOpen(true), []);
+  const closeCart = useCallback(() => setOpen(false), []);
+  const toggleCart = useCallback(() => setOpen((o) => !o), []);
+  const { itemCount } = useCart();
+
+  const panelId = useId();
+  const panelRef = useRef(null);
+  const triggerRef = useRef(null);
+  const openRef = useRef(open);
+  openRef.current = open;
+
+  // `inert` is set as a DOM property (not a JSX attribute): React 18 has no
+  // boolean `inert` support, and the property form works on 18 and 19 alike.
+  const setPanelRef = useCallback((node) => {
+    panelRef.current = node;
+    if (node) node.inert = !openRef.current;
+  }, []);
+  useEffect(() => {
+    if (panelRef.current) panelRef.current.inert = !open;
+  }, [open]);
+
+  // Esc closes — the keyboard's way out is Esc and the named close button.
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open]);
+
+  // Focus follows the dialog: into the panel on open, back to the trigger on
+  // close — without it, focus is stranded inside an inert subtree.
+  const wasOpen = useRef(false);
+  useEffect(() => {
+    if (open) {
+      wasOpen.current = true;
+      panelRef.current?.focus?.();
+    } else if (wasOpen.current) {
+      wasOpen.current = false;
+      triggerRef.current?.focus?.();
+    }
+  }, [open]);
+
+  const value = useMemo(() => {
+    const state = open ? "open" : "closed";
+    return {
+      open,
+      openCart,
+      closeCart,
+      toggleCart,
+      onItemAdded: openOnAdd ? openCart : null,
+      triggerProps: {
+        type: "button",
+        ref: triggerRef,
+        onClick: toggleCart,
+        "aria-haspopup": "dialog",
+        "aria-expanded": open,
+        "aria-controls": panelId,
+        "aria-label": `${label}, ${itemCount} ${itemCount === 1 ? "item" : "items"}`,
+      },
+      overlayProps: {
+        onClick: closeCart,
+        "aria-hidden": true,
+        tabIndex: -1,
+        "data-state": state,
+      },
+      panelProps: {
+        ref: setPanelRef,
+        id: panelId,
+        role: "dialog",
+        "aria-modal": true,
+        "aria-label": label,
+        tabIndex: -1,
+        "data-state": state,
+      },
+      closeButtonProps: {
+        type: "button",
+        onClick: closeCart,
+        "aria-label": `Close ${label.toLowerCase()}`,
+      },
+    };
+  }, [open, openCart, closeCart, toggleCart, openOnAdd, panelId, setPanelRef, label, itemCount]);
+
+  return (
+    <CartUIContext.Provider value={value}>
+      {closeOnNavigate && <CloseOnNavigate close={closeCart} />}
+      {children}
+    </CartUIContext.Provider>
+  );
+}
+
+/** The nearest <CartUIProvider>'s controls; throws without one. */
+export function useCartUI() {
+  const ctx = useContext(CartUIContext);
+  if (!ctx) {
+    throw new Error(
+      "useCartUI needs a <CartUIProvider> above it — mount it once inside <StorefrontProvider>, around your layout.",
+    );
+  }
+  return ctx;
+}
+
+/** Internal-ish: null instead of throwing, for optional integrations. */
+export function useCartUIOptional() {
+  return useContext(CartUIContext);
+}

package/src/commerce/storefront/index.js

@@ -27,32 +27,50 @@
  *   </Route>
  *   // no shared layout? <StorefrontProvider …> <Routes>…</Routes> </StorefrontProvider>
  *
+ * Most hooks hand back **ready-to-spread prop sets** next to the raw data —
+ * `f.inputProps`, `m.radioProps`, `buy.buttonProps`, `ui.panelProps`,
+ * `list.moreProps` — so your markup is elements + classes and the wiring
+ * (handlers, ids, aria, disabled logic) can't be re-derived wrong. Spread
+ * first, put your `className` after.
+ *
  * ## Hooks
  * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
  *     shared client, cached store info (the ONLY source of payment gateways,
  *     currency and countries), money in the store's currency.
- * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
- *     filters, `refreshing`, and failure as a visible state.
+ * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging
+ *     (`moreProps` — spread it and paging can't be dropped), filters,
+ *     `refreshing`, and failure as a visible state.
  * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `useProductPrice` /
- *     `useProductGallery` — the product page: fetch + variant selection +
- *     quantity + price + gallery, race-safe, with `status: "not_found"` and
- *     every add-to-cart failure handled. `variantAxes(view, pick)` (from
- *     `@/commerce/utils`, re-exported here) turns the resolved view into a
- *     render-ready model for the selector you write.
+ *     `useProductGallery` / `useProductSpecs` — the product page: fetch +
+ *     variant selection + quantity + price + gallery, race-safe, with
+ *     `status: "not_found"` and every add-to-cart failure handled; the buy
+ *     button as `buttonProps` + `state`/`label`. `variantAxes(view, pick)`
+ *     (from `@/commerce/utils`, re-exported here) turns the resolved view into
+ *     a render-ready model for the selector you write; `useProductSpecs` adds
+ *     normalized `pick`/`get` lookup over `productSpecs`.
  * - `useProductReviews` — the review list and the submit form, with the store's
  *     policy as a prop and field errors matching the server's codes.
  * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
- *     `status`, render `lines` and `notices`), quantity steppers that clamp and
- *     recover, and the coupon field a store with coupons must have.
+ *     `status`, render `lines` and `notices` — money pre-formatted per line),
+ *     quantity steppers that clamp and recover, and the coupon field a store
+ *     with coupons must have.
+ * - `useCartUI` + `<CartUIProvider>` — the cart drawer's non-visual machinery:
+ *     open state, trigger/overlay/panel/close prop sets with dialog semantics,
+ *     inert-when-closed, Esc, close-on-navigate, open-on-add.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
  *     checkout: address state with automatic debounced shipping/tax
  *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
  *     named blockers, `placeOrder` with both navigations handled (online →
  *     provider redirect, manual → `/order-received`).
+ * - `usePlaceOrder` — the gate as one surface: `buttonProps`, `label`,
+ *     `stage` (guards the just-placed-order frames), `blockers` in words.
  * - `useAddressForm` / `useCountries` / `useTotalsLines` /
- *     `useCheckoutBlockers` — the address form as a field spec you map to your
- *     own inputs (state included, country options never null), one totals
- *     projection for cart and order, and blocker codes turned into copy.
+ *     `useCheckoutBlockers` — the address form as a field spec with per-field
+ *     `inputProps`/`selectProps`/`labelProps`/`errorProps` (state included,
+ *     country options never null), one totals projection for cart and order,
+ *     and blocker codes turned into copy.
+ * - `useUpsell` — one product offered beside another surface: fetch-or-row,
+ *     already-in-cart matched by id, one-click add.
  * - `useOrderReturn` — the mandatory `/order-received` page in one hook:
  *     status, order, `lines`, `paymentLink`, `paymentInstructions`, noindex.
  * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
@@ -60,7 +78,8 @@
  *
  * ## Render-prop components (headless — children is a function, no markup ships)
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
- *     that are store data, never hardcoded, with their branching enumerated.
+ *     that are store data, never hardcoded; options arrive decorated with
+ *     `radioProps`/`labelProps`/`costLabel` and a single `hint` message.
  * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
  *     `lines.map(...)` never calls a hook in a loop.
  *
@@ -71,6 +90,8 @@
  *     inferred `type` (`numeric` with `number`/`unit` split out, `duration`,
  *     `location`, `list` with `items`, `text`), so a weight can be a figure and
  *     a composition bars instead of every modifier being one grey table row.
+ * - `productImages(product)` — images normalized to `{src, name, alt}` and
+ *     de-duplicated; `[]` means render your placeholder.
  */
 export {
   StorefrontProvider,
@@ -81,8 +102,10 @@ export {
   useCart,
 } from "./StorefrontProvider";
 export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
+export { usePlaceOrder } from "./usePlaceOrder";
 export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
+export { CartUIProvider, useCartUI } from "./cartUI";
 export {
   REQUIRED_BILLING_FIELDS,
   missingBillingFields,
@@ -92,7 +115,8 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart, useAddToCartButton } from "./useProduct";
+export { useProduct, useAddToCart, useAddToCartButton, useProductSpecs } from "./useProduct";
+export { useUpsell } from "./useUpsell";
 export { useProductPrice, useMoney } from "./useProductPrice";
 export { useProductGallery } from "./useProductGallery";
 export { useProductReviews } from "./useProductReviews";
@@ -106,4 +130,4 @@ export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotals
 export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
 
 // ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
-export { variantAxes, productSpecs } from "@/commerce/utils";
+export { variantAxes, productSpecs, productImages } from "@/commerce/utils";

package/src/commerce/storefront/pickers.jsx

@@ -1,5 +1,6 @@
 import React from "react";
 import { useCheckoutContextOptional } from "./useCheckout";
+import { useFormatMoney } from "./StorefrontProvider";
 
 /**
  * Headless pickers for the two checkout choices that are store data, never
@@ -7,6 +8,12 @@ import { useCheckoutContextOptional } from "./useCheckout";
  * whole UI — but they encode the branching every checkout must do, so a page
  * can't skip a `shipping_status` state or invent a payment method.
  *
+ * Every option comes **decorated with ready-to-spread prop sets**
+ * (`radioProps` / `labelProps`) and pre-formatted money (`costLabel`), so the
+ * child is markup + classes and nothing else. `hint` is the one message the
+ * picker wants shown right now (or null) — render it and the status branching
+ * is done.
+ *
  * Both read the nearest <CheckoutProvider>, or take an explicit `checkout`
  * prop when you called `useCheckout` yourself.
  */
@@ -24,25 +31,39 @@ function resolveCheckout(name, prop, ctx) {
  * the cart is loading; otherwise calls `children` with:
  *
  *   {
- *     status,        // "missing_address" | "choice_required" | "chosen" | "auto_selected"
- *     methods,       // [{ id, title, cost }] — what this address is offered
- *     chosen,        // the chosen/auto-selected entry (title + cost), or null
+ *     status,        // "missing_address" | "choice_required" | "chosen"
+ *                    //   | "auto_selected" | "none_available"
+ *     methods,       // [{ id, title, cost, costLabel, selected,
+ *                    //    radioProps, labelProps }] — what this address is offered
+ *     chosen,        // the chosen/auto-selected entry (with costLabel), or null
  *     selected,      // alias of `chosen` — the same name the payment picker uses
  *     choose,        // (id) => Promise — call with a method's id on pick
  *     mustChoose,    // status === "choice_required" → render methods as a picker
  *     single,        // exactly one method offered — already chosen; skip the
- *                    //   picker but still show `chosen.title` and its cost
+ *                    //   picker but still show `chosen.title` and `chosen.costLabel`
  *     syncing,       // an address edit is being repriced — show a subtle busy state
- *     addressError,  // { code, message } | null — "we don't ship there" belongs
- *   }                //   on the address fields
+ *     hint,          // { code, message, severity: "info"|"error" } | null — the
+ *                    //   one notice to show now (address missing / not deliverable
+ *                    //   / repricing); render `hint.message`, done
+ *     addressError,  // { code, message } | null — also surfaces on the address
+ *   }                //   form's country field
+ *
+ * The child's whole job:
+ *
+ *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>{hint.message}</p>}
+ *   {mustChoose && methods.map(m => (
+ *     <label key={m.id} {...m.labelProps} className="…">
+ *       <input {...m.radioProps} className="…" /> {m.title} <span>{m.costLabel}</span>
+ *     </label>
+ *   ))}
+ *   {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
  *
- * Render rules the child should follow: `missing_address` → say the options
- * appear once the address is entered; `mustChoose` → a picker of `methods`;
- * otherwise display `chosen.title` + its cost (never the raw id). `single` and
- * `mustChoose` are never both true, and `single` guarantees `chosen`.
+ * `single` and `mustChoose` are never both true, and `single` guarantees
+ * `chosen` — a single option still *shows* what it is, never a picker of one.
  */
 export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
+  const formatMoney = useFormatMoney();
   const {
     shippingStatus: status,
     shippingMethods: methods,
@@ -53,15 +74,40 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     addressError,
   } = checkout;
   if (!status || status === "not_needed") return null;
+  const decorate = (m) =>
+    m && {
+      ...m,
+      selected: m.id === chosen?.id,
+      costLabel: formatMoney(m.cost),
+      radioProps: {
+        type: "radio",
+        name: "shipping-method",
+        id: `shipping-method-${m.id}`,
+        value: m.id,
+        checked: m.id === chosen?.id,
+        onChange: () => choose(m.id),
+      },
+      labelProps: { htmlFor: `shipping-method-${m.id}` },
+    };
+  const hint =
+    status === "missing_address"
+      ? { code: "missing_address", severity: "info", message: "Delivery options appear once your address is entered." }
+      : status === "none_available" || addressError?.code === "shipping_not_available"
+        ? { code: "none_available", severity: "error", message: addressError?.message ?? "We don't deliver to that address yet." }
+        : syncing
+          ? { code: "syncing", severity: "info", message: "Updating delivery options…" }
+          : null;
+  const decoratedChosen = decorate(chosen) ?? null;
   return children({
     status,
-    methods,
-    chosen,
-    selected: chosen,
+    methods: methods.map(decorate),
+    chosen: decoratedChosen,
+    selected: decoratedChosen,
     choose,
     mustChoose: status === "choice_required",
     single: single ?? (methods.length === 1), // fallback: a hand-built checkout object
     syncing,
+    hint,
     addressError,
   });
 }
@@ -72,18 +118,30 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  * `children` with:
  *
  *   {
- *     gateways,   // [{ slug, title, description, online }] — admin-owned data
+ *     gateways,   // [{ slug, title, description, online, selected,
+ *                 //    radioProps, labelProps }] — admin-owned data, decorated
  *     value,      // the selected slug ("" while none)
  *     select,     // (slug) => void
  *     selected,   // the selected gateway entry, or null
  *     single,     // exactly one gateway — already selected; skip the picker but
- *   }             //   still show its title so the customer knows how they pay
+ *                 //   still show its title so the customer knows how they pay
+ *     hint,       // { code, message, severity } | null — set when there are no
+ *   }             //   gateways: checkout is unavailable, say so
+ *
+ * The child's whole job:
+ *
+ *   {hint && <p role="alert">{hint.message}</p>}
+ *   {!single && gateways.map(g => (
+ *     <label key={g.slug} {...g.labelProps} className="…">
+ *       <input {...g.radioProps} className="…" /> {g.title} <span>{g.description}</span>
+ *     </label>
+ *   ))}
+ *   {single && selected && <p>{selected.title} — {selected.description}</p>}
  *
- * Render rules: several gateways → a picker labeled with the admin's
- * title/description; `single` → just display it; zero gateways → say checkout
- * is unavailable instead of rendering a dead place-order button. `single`
- * guarantees `value` and `selected` — never render the one-gateway branch as
- * "nothing selected yet" — and both re-resolve when store info changes.
+ * `single` guarantees `value` and `selected` — never render the one-gateway
+ * branch as "nothing selected yet" — and both re-resolve when store info
+ * changes. Titles and descriptions are the admin's copy: render them, don't
+ * invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());
@@ -91,15 +149,32 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
     paymentMethods: gateways,
     paymentMethod: value,
     setPaymentMethod: select,
-    selectedGateway: selected,
     singlePaymentMethod: single,
   } = checkout;
   if (!gateways) return null;
+  const decorated = gateways.map((g) => ({
+    ...g,
+    selected: g.slug === value,
+    radioProps: {
+      type: "radio",
+      name: "payment-method",
+      id: `payment-method-${g.slug}`,
+      value: g.slug,
+      checked: g.slug === value,
+      onChange: () => select(g.slug),
+    },
+    labelProps: { htmlFor: `payment-method-${g.slug}` },
+  }));
+  const hint =
+    gateways.length === 0
+      ? { code: "none_available", severity: "error", message: "No payment method is available right now." }
+      : null;
   return children({
-    gateways,
+    gateways: decorated,
     value,
     select,
-    selected,
+    selected: decorated.find((g) => g.selected) ?? null,
     single: single ?? (gateways.length === 1), // fallback: a hand-built checkout object
+    hint,
   });
 }

package/src/commerce/storefront/useAddressForm.js

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { addressFieldSpec } from "@/commerce/utils";
 import { useStoreInfo } from "./StorefrontProvider";
 import { useCheckoutContext } from "./useCheckout";
@@ -42,26 +42,35 @@ function newValue(args) {
  * useAddressForm — the checkout address form as a field list bound to the
  * guided checkout. Needs a `<CheckoutProvider>` above it.
  *
- * Every field is **self-contained** — it carries its own setter, so a `.map`
- * never has to reach back out of the loop:
+ * Every field is **self-contained**: it carries its own setter AND its own
+ * ready-to-spread attribute sets, so the whole form is one map with your
+ * classes on it — never assemble `value`/`onChange`/`autoComplete` by hand:
  *
  *   const { fields } = useAddressForm("billing");
  *   {fields.map(f => (
- *     <label key={f.key}>
- *       {f.label}{f.required && " *"}
- *       {f.type === "select"
- *         ? <select value={f.value} onChange={e => f.set(e.target.value)}>
- *             {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
- *           </select>
- *         : <input type={f.type} value={f.value} autoComplete={f.autoComplete}
- *                  onChange={e => f.set(e.target.value)} />}
- *       {f.error && <span role="alert">{f.error}</span>}
- *     </label>
+ *     <div key={f.key} className="…">
+ *       <label {...f.labelProps}>{f.label}{f.required && " *"}</label>
+ *       {f.isSelect ? (
+ *         <select {...f.selectProps} className="…">
+ *           <option value="">{f.placeholder}</option>
+ *           {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
+ *         </select>
+ *       ) : <input {...f.inputProps} className="…" />}
+ *       {f.error && <span {...f.errorProps} className="…">{f.error}</span>}
+ *     </div>
  *   ))}
  *
- * `f.set` also accepts the raw event (`onChange={f.set}`) or a `(key, value)`
- * pair; the hook's top-level `set(key, value)` is still there for code that
- * writes a field outside the map.
+ * The prop sets carry id/name pairing, the `autoComplete` token, controlled
+ * `value` + `onChange`, `required`, blur tracking and the `aria-invalid` /
+ * `aria-describedby` wiring for the error line. `f.placeholder` resolves the
+ * select's empty option ("Select Country", or "Loading…" while countries
+ * arrive), so `countriesLoading` never needs handling by hand. `f.error` is
+ * per-field: "we don't ship there" lands on the country field, and a required
+ * field left empty reports itself after it has been visited.
+ *
+ * `f.set` is still there for custom controls — it accepts a value, the raw
+ * event (`onChange={f.set}`) or a `(key, value)` pair — as is the hook's
+ * top-level `set(key, value)`.
  *
  * Editing a field is all it takes to trigger the shipping/tax recalculation —
  * `useCheckout` debounces and calls `set-shipping-address` once the address is
@@ -74,7 +83,9 @@ function newValue(args) {
  * @param {{includeState?: boolean, includePhone?: boolean, includeCompany?: boolean}} [options]
  * @returns {{fields: Array<{key: string, label: string, type: string,
  *   value: string, required: boolean, options: Array<object>, error: string|null,
- *   autoComplete: string, colSpan: number, set: (...args: any[]) => void}>,
+ *   autoComplete: string, colSpan: number, set: (...args: any[]) => void,
+ *   isSelect: boolean, placeholder: string|undefined, inputProps: object,
+ *   selectProps: object, labelProps: object, errorProps: object}>,
  *   set: (key: string, value: any) => void, values: object, missing: Array<string>,
  *   complete: boolean, error: object|null, countriesLoading: boolean}}
  */
@@ -94,6 +105,10 @@ export function useAddressForm(which = "billing", options = {}) {
   // address is priced, not validated field-by-field.
   const missing = isBilling ? checkout.missingBillingFields : [];
 
+  // A required field reports itself as `error` only after it has been visited
+  // (blurred) — an untouched form must not open covered in "required" marks.
+  const [visited, setVisited] = useState({});
+
   const fields = useMemo(() => {
     const spec = addressFieldSpec({
       countries,
@@ -102,20 +117,51 @@ export function useAddressForm(which = "billing", options = {}) {
       includeEmail: isBilling, // one email per order, on billing
       ...options,
     });
-    return spec.map((f) => ({
-      ...f,
-      value: values?.[f.key] ?? "",
+    return spec.map((f) => {
+      const value = values?.[f.key] ?? "";
       // Self-contained: the field knows its own key, so a .map never has to
       // reach back out to the hook's set() (and can't pass the wrong key).
-      set: (...args) => set(f.key, newValue(args)),
+      const setField = (...args) => set(f.key, newValue(args));
       // The address-level error ("we don't ship there") belongs on country.
-      error:
+      const error =
         f.key === "country" && checkout.addressError?.code === "shipping_not_available"
           ? checkout.addressError.message
-          : null,
-    }));
+          : visited[f.key] && !value && missing.includes(f.key)
+            ? `${f.label} is required.`
+            : null;
+      const id = `${which}-${f.key}`;
+      const errorId = `${id}-error`;
+      const shared = {
+        id,
+        name: id,
+        value,
+        required: f.required,
+        autoComplete: f.autoComplete,
+        onChange: setField,
+        onBlur: () => setVisited((v) => (v[f.key] ? v : { ...v, [f.key]: true })),
+        "aria-invalid": error ? true : undefined,
+        "aria-describedby": error ? errorId : undefined,
+      };
+      return {
+        ...f,
+        value,
+        set: setField,
+        error,
+        isSelect: f.type === "select",
+        placeholder:
+          f.type === "select"
+            ? f.key === "country" && countriesLoading
+              ? "Loading…"
+              : `Select ${f.label}`
+            : undefined,
+        inputProps: { ...shared, type: f.type },
+        selectProps: shared,
+        labelProps: { htmlFor: id },
+        errorProps: { id: errorId, role: "alert" },
+      };
+    });
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [countries, values, isBilling, set, checkout.addressError, JSON.stringify(options)]);
+  }, [countries, countriesLoading, values, which, isBilling, set, checkout.addressError, visited, missing.join(","), JSON.stringify(options)]);
 
   return {
     fields,

package/src/commerce/storefront/useCartLine.js

@@ -135,6 +135,8 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
     atMin: quantity <= 1,
     attributesLabel: line?.attributesLabel ?? "",
     image: line?.image ?? null,
+    totalLabel: line?.totalLabel ?? "",
+    unitPriceLabel: line?.unitPriceLabel ?? "",
   };
 }
 
@@ -148,12 +150,15 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
  *   {lines.map(line => (
  *     <CartLine key={line.item_key} line={line}>
  *       {(l) => (
- *         <li>
+ *         <li aria-busy={l.pending}>
  *           {line.name} {line.attributesLabel}
- *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
+ *                   aria-label={`Decrease quantity of ${line.name}`}>−</button>
  *           {l.quantity}
- *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
- *           <button onClick={l.remove}>Remove</button>
+ *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
+ *                   aria-label={`Increase quantity of ${line.name}`}>+</button>
+ *           <button onClick={l.remove} aria-label={`Remove ${line.name}`}>Remove</button>
+ *           {l.totalLabel}
  *           {l.error && <p role="alert">{l.error.message}</p>}
  *         </li>
  *       )}