@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/src/commerce/storefront/useProductReviews.js

@@ -0,0 +1,242 @@
+import { useCallback, useMemo, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { useStorefront } from "./StorefrontProvider";
+import { useAsyncData } from "./internal/useAsyncData";
+
+const EMPTY_FORM = Object.freeze({ reviewer: "", email: "", review: "", rating: 5 });
+
+/**
+ * useProductReviews — the review list AND the submit form, including the store
+ * policy, in one hook.
+ *
+ *   const r = useProductReviews(product, { policy: "open" });
+ *   // list:   r.items, r.averageRating, r.ratingCount, r.hasNext, r.loadMore()
+ *   // form:   r.form, r.setField("review", v), r.fieldErrors, r.valid, r.submit()
+ *   // after:  r.submitted && <p>{r.message}</p>
+ *
+ * The backend ships complete (public submission by email, moderation,
+ * auto-approve); everything that used to be hand-rolled around it lives here:
+ *
+ * - **The confirmation copy comes from the response.** `submit()` returns the
+ *   server's `status` — `"approved"` when the store has `auto_approve_reviews`
+ *   on, `"hold"` otherwise — and `message` follows it. A hardcoded "awaiting
+ *   approval" lies to half of all stores.
+ * - **Errors are field-level.** The three server codes (`email_required`,
+ *   `review_incomplete`, `invalid_rating`) land in `fieldErrors` rather than
+ *   rejecting into nothing, and `valid` gates the round trip.
+ * - **Submitting refreshes the list**, so an auto-approved review appears
+ *   instead of being invisible until the next page load.
+ * - **`requiresEmail` is false for a signed-in visitor** — the session's email
+ *   always wins server-side, so asking for it again is a field that does
+ *   nothing.
+ *
+ * `policy` replaces the prose patterns a storefront used to implement by hand:
+ * `"open"` (anyone with an email — the server's own default), `"login"` (only a
+ * signed-in visitor; `canReview` false with `reviewBlockedReason:
+ * "login_required"`), `"verified_buyers"` (only someone whose email has a
+ * completed order for this product — `"not_a_buyer"`). Policies are UI-side by
+ * design: the server accepts any valid email, so a stricter rule is exactly
+ * this gate.
+ *
+ * @param {object} product the product being reviewed (needs `id`, and `slug` to page)
+ * @param {{perPage?: number, policy?: "open"|"login"|"verified_buyers",
+ *   requireRating?: boolean, refreshOnSubmit?: boolean, user?: object|null,
+ *   initialReviews?: object}} [options]
+ *   `user` is your app's current user (Base44 auth) — pass it for the `login`
+ *   and `verified_buyers` policies and to drop the email field.
+ */
+export function useProductReviews(product, options = {}) {
+  const {
+    perPage = 10,
+    policy = "open",
+    requireRating = false,
+    refreshOnSubmit = true,
+    user = null,
+    initialReviews = null,
+  } = options;
+
+  const store = useStorefront();
+  const [page, setPage] = useState(1);
+  const [appended, setAppended] = useState(null);
+  const ref = product?.slug ? product.slug : product?.id ? { id: product.id } : null;
+
+  const { data, loading, refreshing, error, reload } = useAsyncData(
+    () => store.getProductReviews(ref, { page, per_page: perPage }),
+    [store, product?.id, page, perPage],
+    { enabled: Boolean(ref), initialData: page === 1 ? initialReviews : null },
+  );
+
+  const items = useMemo(() => {
+    const rows = data?.items ?? [];
+    if (!appended) return rows;
+    const byId = new Map();
+    for (const r of [...appended, ...rows]) byId.set(r.id ?? `${r.reviewer}-${r.date_created}`, r);
+    return [...byId.values()];
+  }, [data, appended]);
+
+  const hasNext = Boolean(data?.has_next);
+  const next = useCallback(() => {
+    if (hasNext) setPage((p) => p + 1);
+  }, [hasNext]);
+  const prev = useCallback(() => setPage((p) => Math.max(1, p - 1)), []);
+  const loadMore = useCallback(() => {
+    if (!hasNext) return;
+    setAppended(items);
+    setPage((p) => p + 1);
+  }, [hasNext, items]);
+
+  // ── the form ───────────────────────────────────────────────────────────────
+  const [form, setForm] = useState(() => ({
+    ...EMPTY_FORM,
+    reviewer: user?.full_name ?? "",
+    email: user?.email ?? "",
+  }));
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [submittedStatus, setSubmittedStatus] = useState(null);
+  const [serverError, setServerError] = useState(null);
+
+  const setField = useCallback((name, value) => {
+    setServerError(null);
+    setForm((f) => ({ ...f, [name]: value }));
+  }, []);
+  const reset = useCallback(() => {
+    setForm({ ...EMPTY_FORM, reviewer: user?.full_name ?? "", email: user?.email ?? "" });
+    setSubmitted(false);
+    setSubmittedStatus(null);
+    setServerError(null);
+  }, [user?.full_name, user?.email]);
+
+  // A signed-in visitor's email is taken from the session server-side.
+  const requiresEmail = !user?.email;
+
+  const fieldErrors = useMemo(() => {
+    const errs = {};
+    if (requiresEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(form.email ?? "").trim())) {
+      errs.email = "A valid email address is required.";
+    }
+    if (!String(form.review ?? "").trim()) errs.review = "Write a few words about the product.";
+    const rating = Number(form.rating);
+    if (requireRating && !(rating >= 1 && rating <= 5)) errs.rating = "Choose a rating.";
+    else if (form.rating != null && (rating < 0 || rating > 5)) errs.rating = "Rating must be 0–5.";
+    if (serverError) errs[serverErrorField(serverError.code)] = serverError.message;
+    return errs;
+  }, [form, requiresEmail, requireRating, serverError]);
+
+  // ── policy ─────────────────────────────────────────────────────────────────
+  // "Has this visitor bought it?" can only be answered from their own orders —
+  // public reviews carry no email (by design), so the answer comes from
+  // `my-orders`. Fetched only for the policy that needs it.
+  const needsPurchaseCheck = policy === "verified_buyers" && Boolean(user) && Boolean(product?.id);
+  const { data: myOrders, loading: purchaseLoading } = useAsyncData(
+    () => store.inv("commerce/storefront-account", { action: "my-orders", per_page: 50 }),
+    [store, user?.email, product?.id],
+    { enabled: needsPurchaseCheck },
+  );
+  const purchased = useMemo(() => {
+    if (!needsPurchaseCheck) return false;
+    return (myOrders?.orders ?? []).some(
+      (o) =>
+        ["completed", "processing"].includes(o.status) &&
+        (o.line_items ?? []).some((li) => li.product_id === product.id),
+    );
+  }, [needsPurchaseCheck, myOrders, product?.id]);
+
+  let reviewBlockedReason = null;
+  if ((policy === "login" || policy === "verified_buyers") && !user) {
+    reviewBlockedReason = "login_required";
+  } else if (policy === "verified_buyers" && !purchased && !purchaseLoading) {
+    reviewBlockedReason = "not_a_buyer";
+  }
+  const canReview = !reviewBlockedReason && !purchaseLoading && !submitted;
+
+  const valid = canReview && Object.keys(fieldErrors).length === 0;
+
+  const submit = useCallback(async () => {
+    if (submitting) return { ok: false, error: { code: "submitting", message: "Already submitting." } };
+    if (reviewBlockedReason) {
+      return { ok: false, error: { code: reviewBlockedReason, message: blockedMessage(reviewBlockedReason) } };
+    }
+    if (Object.keys(fieldErrors).length) {
+      return { ok: false, error: { code: "invalid_form", message: "Please complete the form." } };
+    }
+    setSubmitting(true);
+    setServerError(null);
+    try {
+      const res = await store.submitReview({
+        product_id: product?.id,
+        review: String(form.review).trim(),
+        rating: form.rating == null ? undefined : Number(form.rating),
+        reviewer: String(form.reviewer ?? "").trim() || undefined,
+        email: requiresEmail ? String(form.email).trim() : undefined,
+      });
+      setSubmitted(true);
+      setSubmittedStatus(res.status);
+      // An auto-approved review is live immediately — show it.
+      if (refreshOnSubmit && res.status === "approved") {
+        setAppended(null);
+        setPage(1);
+        reload();
+      }
+      return { ok: true, status: res.status, verified: res.verified };
+    } catch (e) {
+      const err = { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) };
+      setServerError(err);
+      return { ok: false, error: err };
+    } finally {
+      setSubmitting(false);
+    }
+  }, [submitting, reviewBlockedReason, fieldErrors, store, product?.id, form, requiresEmail, refreshOnSubmit, reload]);
+
+  const message = submitted
+    ? submittedStatus === "approved"
+      ? "Thanks — your review is published."
+      : "Thanks — your review has been submitted for approval."
+    : null;
+
+  return {
+    // list
+    items,
+    page,
+    perPage: data?.per_page ?? perPage,
+    hasNext,
+    next,
+    prev,
+    loadMore,
+    averageRating: data?.average_rating ?? product?.average_rating ?? 0,
+    ratingCount: data?.rating_count ?? product?.rating_count ?? 0,
+    loading,
+    refreshing,
+    error,
+    reload,
+    // submission
+    form,
+    setField,
+    reset,
+    fieldErrors,
+    valid,
+    submit,
+    submitting,
+    submitted,
+    submittedStatus,
+    message,
+    // policy
+    canReview,
+    reviewBlockedReason,
+    requiresEmail,
+  };
+}
+
+/** Server error code → the form field it belongs on. */
+function serverErrorField(code) {
+  if (code === "email_required") return "email";
+  if (code === "invalid_rating") return "rating";
+  if (code === "review_incomplete") return "review";
+  return "form";
+}
+
+function blockedMessage(reason) {
+  if (reason === "login_required") return "Please sign in to write a review.";
+  if (reason === "not_a_buyer") return "Only verified buyers can review this product.";
+  return "Reviews are closed.";
+}

package/src/commerce/storefront/useStorefrontSeo.js

@@ -0,0 +1,204 @@
+import { useEffect } from "react";
+
+/**
+ * Storefront SEO — titles, meta tags and product structured data, with no
+ * dependency (no react-helmet). A store whose every page shares one static
+ * `<title>` is invisible to search and unshareable on social; this is the
+ * cheapest possible fix, one line per page:
+ *
+ *   useStorefrontSeo(productSeo(product, view, { storeName, currency }));
+ *   useStorefrontSeo(collectionSeo({ title: "Gowns", products }));
+ *   useStorefrontSeo(orderSeo(order));     // noindex — a receipt must not rank
+ *
+ * Everything it sets is restored on unmount, so navigating away can't leave a
+ * product's title on the home page.
+ */
+
+/** Upsert one <meta>, returning a restore function. */
+function setMeta(attr, name, content) {
+  if (typeof document === "undefined") return () => {};
+  const selector = `meta[${attr}="${name}"]`;
+  let el = document.head.querySelector(selector);
+  const created = !el;
+  const previous = el?.getAttribute("content") ?? null;
+  if (!el) {
+    el = document.createElement("meta");
+    el.setAttribute(attr, name);
+    document.head.appendChild(el);
+  }
+  el.setAttribute("content", content ?? "");
+  return () => {
+    if (created) el.remove();
+    else if (previous != null) el.setAttribute("content", previous);
+  };
+}
+
+function setLink(rel, href) {
+  if (typeof document === "undefined") return () => {};
+  let el = document.head.querySelector(`link[rel="${rel}"]`);
+  const created = !el;
+  const previous = el?.getAttribute("href") ?? null;
+  if (!el) {
+    el = document.createElement("link");
+    el.setAttribute("rel", rel);
+    document.head.appendChild(el);
+  }
+  el.setAttribute("href", href);
+  return () => {
+    if (created) el.remove();
+    else if (previous != null) el.setAttribute("href", previous);
+  };
+}
+
+/**
+ * Apply page metadata. Pass the output of `productSeo`/`collectionSeo`/
+ * `orderSeo`, or your own object.
+ *
+ * @param {{title?: string, description?: string, image?: string,
+ *   canonical?: string, noindex?: boolean, jsonLd?: object}} seo
+ */
+export function useStorefrontSeo(seo) {
+  const { title, description, image, canonical, noindex, jsonLd } = seo ?? {};
+  const jsonLdKey = jsonLd ? JSON.stringify(jsonLd) : null;
+
+  useEffect(() => {
+    if (typeof document === "undefined") return undefined;
+    const undo = [];
+
+    if (title) {
+      const previous = document.title;
+      document.title = title;
+      undo.push(() => {
+        document.title = previous;
+      });
+    }
+    if (description) {
+      undo.push(setMeta("name", "description", description));
+      undo.push(setMeta("property", "og:description", description));
+    }
+    if (title) {
+      undo.push(setMeta("property", "og:title", title));
+      undo.push(setMeta("name", "twitter:title", title));
+    }
+    if (image) {
+      undo.push(setMeta("property", "og:image", image));
+      undo.push(setMeta("name", "twitter:card", "summary_large_image"));
+      undo.push(setMeta("name", "twitter:image", image));
+    }
+    if (canonical) undo.push(setLink("canonical", canonical));
+    if (noindex) undo.push(setMeta("name", "robots", "noindex,nofollow"));
+
+    if (jsonLdKey) {
+      const script = document.createElement("script");
+      script.type = "application/ld+json";
+      script.textContent = jsonLdKey;
+      document.head.appendChild(script);
+      undo.push(() => script.remove());
+    }
+
+    return () => undo.forEach((fn) => fn());
+  }, [title, description, image, canonical, noindex, jsonLdKey]);
+}
+
+const stripHtml = (html) =>
+  String(html ?? "")
+    .replace(/<[^>]*>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+const currentUrl = (url) =>
+  url ?? (typeof window !== "undefined" ? window.location.href.split("?")[0] : undefined);
+
+/**
+ * SEO for a product page, including schema.org `Product` + `Offer` structured
+ * data (price, availability, rating, sku) — what makes a product eligible for
+ * rich results.
+ *
+ * @param {object} product
+ * @param {object|null} [view] a `resolveSelection` view — its resolved price
+ *   and image are used when present
+ * @param {{storeName?: string, currency?: string, url?: string}} [opts]
+ */
+export function productSeo(product, view = null, { storeName, currency, url } = {}) {
+  if (!product) return {};
+  const display = view?.display ?? product;
+  const image = display?.image?.src ?? product.images?.[0]?.src;
+  const description =
+    stripHtml(product.short_description) || stripHtml(product.description).slice(0, 300);
+  const price = display?.price ?? product.price;
+  const inStock = ["instock", "onbackorder"].includes(display?.stock_status ?? product.stock_status);
+
+  return {
+    title: storeName ? `${product.name} — ${storeName}` : product.name,
+    description,
+    image,
+    canonical: currentUrl(url),
+    jsonLd: {
+      "@context": "https://schema.org",
+      "@type": "Product",
+      name: product.name,
+      description,
+      ...(image ? { image: [image] } : {}),
+      ...(display?.sku || product.sku ? { sku: display?.sku || product.sku } : {}),
+      ...(product.rating_count
+        ? {
+            aggregateRating: {
+              "@type": "AggregateRating",
+              ratingValue: product.average_rating,
+              reviewCount: product.rating_count,
+            },
+          }
+        : {}),
+      ...(price != null
+        ? {
+            offers: {
+              "@type": "Offer",
+              price,
+              ...(currency ? { priceCurrency: currency } : {}),
+              availability: `https://schema.org/${inStock ? "InStock" : "OutOfStock"}`,
+              ...(currentUrl(url) ? { url: currentUrl(url) } : {}),
+            },
+          }
+        : {}),
+    },
+  };
+}
+
+/**
+ * SEO for a catalog/collection page, with an `ItemList` of the products shown.
+ *
+ * @param {{title: string, description?: string, products?: Array<object>,
+ *   storeName?: string, url?: string}} opts
+ */
+export function collectionSeo({ title, description, products = [], storeName, url } = {}) {
+  return {
+    title: storeName && title ? `${title} — ${storeName}` : title,
+    description,
+    image: products[0]?.images?.[0]?.src,
+    canonical: currentUrl(url),
+    jsonLd: products.length
+      ? {
+          "@context": "https://schema.org",
+          "@type": "ItemList",
+          itemListElement: products.slice(0, 24).map((p, i) => ({
+            "@type": "ListItem",
+            position: i + 1,
+            name: p.name,
+          })),
+        }
+      : undefined,
+  };
+}
+
+/**
+ * SEO for `/order-received` — and for `/checkout`: both must be **noindex**.
+ * A receipt page carrying an order key has no business in a search index.
+ *
+ * @param {object} [order]
+ */
+export function orderSeo(order) {
+  return {
+    title: order?.order_number ? `Order ${order.order_number}` : "Order",
+    noindex: true,
+  };
+}

package/src/commerce/storefront/useTotalsLines.js

@@ -0,0 +1,109 @@
+import { useMemo } from "react";
+import { cartTotalsLines, orderTotalsLines } from "@/commerce/utils";
+import { useCart, useFormatMoney } from "./StorefrontProvider";
+import { useCheckoutContextOptional } from "./useCheckout";
+
+/**
+ * useTotalsLines — the summary lines for the shared cart, or for a placed order.
+ *
+ *   const lines = useTotalsLines();          // the cart (bag page, checkout summary)
+ *   const lines = useTotalsLines(order);     // a placed order (order-received)
+ *
+ *   {lines.filter(l => !l.hidden).map(l => (
+ *     <p key={l.key} className={l.emphasis ? "font-medium" : ""}>
+ *       <span>{l.label}</span><span>{l.formatted}</span>
+ *     </p>
+ *   ))}
+ *
+ * Always five keys — `subtotal` `discount` `shipping` `tax` `total` — with
+ * `hidden` set on a zero discount or tax. Rendering the array is what keeps a
+ * summary adding up once the store issues its first coupon or charges tax; a
+ * hand-written block reliably omits exactly those two rows. It also absorbs the
+ * cart-vs-order shape difference: a cart's totals are nested under
+ * `cart.totals`, an order's are flat on the order.
+ *
+ * @param {object} [order] pass a placed order to project it instead of the cart
+ */
+export function useTotalsLines(order) {
+  const formatMoney = useFormatMoney();
+  const { cart } = useCart();
+  return useMemo(
+    () =>
+      order
+        ? orderTotalsLines(order, { formatMoney })
+        : cart
+          ? cartTotalsLines(cart, { formatMoney })
+          : [],
+    [order, cart, formatMoney],
+  );
+}
+
+const BLOCKER_MESSAGES = {
+  cart_loading: "Loading your bag…",
+  empty_cart: "Your bag is empty.",
+  billing_incomplete: "Complete your details to continue.",
+  shipping_address_incomplete: "Enter the delivery address.",
+  shipping_recalculating: "Updating delivery options…",
+  shipping_address_required: "Enter your address to see delivery options.",
+  shipping_method_required: "Choose a delivery option.",
+  shipping_not_available: "We don't deliver to that address yet.",
+  payment_method_required: "Choose how you'd like to pay.",
+};
+
+const BLOCKER_FIELDS = {
+  billing_incomplete: "billing",
+  shipping_address_incomplete: "shipping",
+  shipping_address_required: "country",
+  shipping_not_available: "country",
+  shipping_method_required: "shipping_method",
+  payment_method_required: "payment_method",
+};
+
+/**
+ * A blocker code turned into customer-facing copy.
+ *
+ * @param {string} code one of `useCheckout().blockers`
+ * @param {{missingBillingFields?: string[], labels?: Record<string, string>}} [opts]
+ *   pass `missingBillingFields` and an incomplete-billing message names the
+ *   fields instead of saying "complete your details".
+ * @returns {string}
+ */
+export function blockerMessage(code, { missingBillingFields, labels } = {}) {
+  if (labels?.[code]) return labels[code];
+  if (code === "billing_incomplete" && missingBillingFields?.length) {
+    const names = missingBillingFields.map((f) => f.replace(/_/g, " ")).join(", ");
+    return `Still needed: ${names}.`;
+  }
+  return BLOCKER_MESSAGES[code] ?? "Something is still missing.";
+}
+
+/**
+ * useCheckoutBlockers — why the place-order button is disabled, in words.
+ *
+ *   const blockers = useCheckoutBlockers();
+ *   <button disabled={!canPlaceOrder}>Place order</button>
+ *   {blockers.map(b => <p key={b.code}>{b.message}</p>)}
+ *
+ * `useCheckout` already names every blocker; the reason they went unrendered in
+ * practice is that a code like `shipping_method_required` needs copy invented
+ * for it. This supplies the copy (overridable) plus the `field` each one points
+ * at, so a page can anchor the hint next to the input that fixes it — a
+ * disabled button with no explanation is the most common checkout dead end.
+ *
+ * Needs a `<CheckoutProvider>` above it; returns `[]` without one.
+ */
+export function useCheckoutBlockers({ labels } = {}) {
+  const checkout = useCheckoutContextOptional();
+  const blockers = checkout?.blockers ?? [];
+  const missing = checkout?.missingBillingFields;
+  return useMemo(
+    () =>
+      blockers.map((code) => ({
+        code,
+        message: blockerMessage(code, { missingBillingFields: missing, labels }),
+        field: BLOCKER_FIELDS[code] ?? null,
+      })),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(blockers), JSON.stringify(missing ?? []), labels],
+  );
+}

package/src/commerce/utils/address-spec.js

@@ -0,0 +1,89 @@
+/**
+ * The address form, as data. Framework-free; `useAddressForm` binds it to the
+ * checkout and the store's country list.
+ *
+ * Why a spec instead of markup: a hand-typed field table drifts from what the
+ * backend needs. Two failures come from that, and both are silent:
+ *
+ * - **`state` gets left out.** Shipping rates and taxes match on
+ *   **country + state** (Shipping & Tax Location regions are
+ *   continent/country/state — postcode and city are never matched), so a form
+ *   without a state field mis-prices every US/CA/AU order without erroring.
+ * - **The country `<select>` renders before the store's country list arrives.**
+ *   `useStoreInfo().countries` is `null` while store info loads; mapping over
+ *   it crashes the checkout on a cold load. Here `options` is **always an
+ *   array** — empty while loading, never null.
+ *
+ * Each field is `{ key, label, type, required, autoComplete, options?, colSpan }`
+ * — enough to render a real form (and to render it correctly on mobile, since
+ * `autoComplete` is what makes browser autofill work).
+ */
+
+/**
+ * Build the field list for an address form.
+ *
+ * @param {{countries?: Array<{code: string, name: string, states?: Array<{code: string, name: string}>}>,
+ *   country?: string, required?: string[], includeState?: boolean,
+ *   includePhone?: boolean, includeCompany?: boolean, includeEmail?: boolean}} opts
+ *   `country` is the currently-selected country — it decides whether `state`
+ *   renders as a select (US/CA/AU and any country carrying `states`) or as
+ *   free text.
+ * @returns {Array<{key: string, label: string, type: string, required: boolean,
+ *   autoComplete: string, options: Array<{value: string, label: string}>,
+ *   colSpan: number}>}
+ */
+export function addressFieldSpec({
+  countries,
+  country,
+  required = [],
+  includeState = true,
+  includePhone = true,
+  includeCompany = false,
+  includeEmail = true,
+} = {}) {
+  const list = Array.isArray(countries) ? countries : [];
+  const countryOptions = list.map((c) => ({ value: c.code, label: c.name }));
+  const states = list.find((c) => c.code === country)?.states ?? null;
+  const isRequired = (key) => required.includes(key);
+
+  const fields = [
+    { key: "first_name", label: "First name", type: "text", autoComplete: "given-name", colSpan: 1 },
+    { key: "last_name", label: "Last name", type: "text", autoComplete: "family-name", colSpan: 1 },
+    ...(includeEmail
+      ? [{ key: "email", label: "Email", type: "email", autoComplete: "email", colSpan: 2 }]
+      : []),
+    ...(includeCompany
+      ? [{ key: "company", label: "Company", type: "text", autoComplete: "organization", colSpan: 2 }]
+      : []),
+    { key: "address_1", label: "Address", type: "text", autoComplete: "address-line1", colSpan: 2 },
+    { key: "address_2", label: "Apartment, suite (optional)", type: "text", autoComplete: "address-line2", colSpan: 2 },
+    // Country before city/state: picking it re-shapes the state field and is
+    // what arms the shipping/tax recalculation.
+    { key: "country", label: "Country", type: "select", autoComplete: "country", options: countryOptions, colSpan: 1 },
+    { key: "city", label: "City", type: "text", autoComplete: "address-level2", colSpan: 1 },
+    ...(includeState
+      ? [{
+          key: "state",
+          label: states ? "State / Province" : "State / Region (optional)",
+          type: states ? "select" : "text",
+          autoComplete: "address-level1",
+          options: states ? states.map((s) => ({ value: s.code, label: s.name })) : [],
+          // A country with subdivisions prices on them, so the field is
+          // effectively required there even though `place-order` doesn't say so.
+          requiredOverride: Boolean(states),
+          colSpan: 1,
+        }]
+      : []),
+    { key: "postcode", label: "Postal code", type: "text", autoComplete: "postal-code", colSpan: 1 },
+    ...(includePhone
+      ? [{ key: "phone", label: "Phone (optional)", type: "tel", autoComplete: "tel", colSpan: 2 }]
+      : []),
+  ];
+
+  return fields.map((f) => ({
+    options: [],
+    ...f,
+    required: f.requiredOverride ?? isRequired(f.key),
+    requiredOverride: undefined,
+  }));
+}

package/src/commerce/utils/images.js

@@ -0,0 +1,45 @@
+/**
+ * Product images, normalized. Framework-free; `useProductGallery` adds the
+ * gallery's index state on top.
+ *
+ * Every stored image is an **object** — `{ src, name, alt }` — never a URL
+ * string, and a product can legitimately have none. Both facts have to survive
+ * into the markup: `<img src={product.images[0]}>` renders a broken image, and
+ * `{image?.src && <img …/>}` collapses the card to nothing instead of showing
+ * a placeholder. `productImages` hands back a clean array so a renderer can
+ * only get it right, and `hasImages === false` is the deliberate
+ * render-a-placeholder signal.
+ */
+import { normalizeImage } from "./variants.js";
+
+/**
+ * A product's renderable images, normalized and de-duplicated by `src`.
+ *
+ * @param {object} product
+ * @returns {Array<{src: string, name: string, alt: string}>} may be empty —
+ *   that is the "render your placeholder" case, not an error
+ */
+export function productImages(product) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of product?.images ?? []) {
+    const img = normalizeImage(raw);
+    if (!img?.src || seen.has(img.src)) continue;
+    seen.add(img.src);
+    out.push(img);
+  }
+  return out;
+}
+
+/**
+ * Where a variation's image sits inside the product's gallery, so a selection
+ * change can **highlight** that image rather than replacing the gallery.
+ *
+ * @param {Array<{src: string}>} images from `productImages`
+ * @param {object|null} image a normalized image (e.g. `view.display.image`)
+ * @returns {number} index, or -1 when the variation's image isn't in the gallery
+ */
+export function imageIndex(images, image) {
+  if (!image?.src) return -1;
+  return images.findIndex((i) => i.src === image.src);
+}