@base44/app-plugin-commerce 0.2.6 → 0.3.1

package/src/commerce/storefront/useProductList.js

@@ -7,25 +7,22 @@ import { useAsyncData } from "./internal/useAsyncData";
  * loading vs refreshing, and failure as a visible state.
  *
  *   const list = useProductList({ per_page: 12, sort: "-created_date" });
- *   // list.status: "loading" | "ready" | "empty" | "error"
- *   // list.products, list.hasNext, list.next(), list.setParams({ category_id })
- *   <button {...list.moreProps} className="…">Load more</button>  // hides itself on the last page
+ *   // status: "loading" | "ready" | "empty" | "error"
+ *   // products, hasNext, next(), loadMore(), busy, setParams({ category_id })
  *
- * A short strip is the same hook with a small `per_page` — a featured rail, a
- * "new in" row, four picks beside an article:
+ * A short strip is the same hook with a small `per_page` — a featured rail, four
+ * picks beside an article: `useProductList({ featured: true, per_page: 4 })`.
  *
- *   const featured = useProductList({ featured: true, per_page: 4 });
- *
- * What it fixes versus a hand-written fetch effect: `has_next` is honoured (so
- * the catalog isn't silently capped at one page), a failed request renders as
- * `status: "error"` instead of an empty grid, `isEmpty` is never true while
- * loading, changing a filter resets to page 1 and keeps the current rows on
- * screen while the new page loads, and the whole server-side filter surface
- * (`search`, `category_id`, `ribbon_id`, `featured`, `on_sale`, `min_price`,
- * `max_price`, `in_stock_only`, `sort`) is reachable through `setParams`.
- *
- * Any filter may legitimately match nothing — render from
- * `products.length`/`isEmpty`, never on the assumption that rows came back.
+ * ⚑ **Render a paging control whenever `hasNext` is true**, or the catalog is
+ * silently capped at one page (`next()` for pages, `loadMore()` in append mode).
+ * The rest of what it fixes versus a hand-written fetch effect: a failed request
+ * is `status: "error"`, not an empty grid; `isEmpty` is never true while loading;
+ * a filter change resets to page 1 and keeps the current rows on screen while
+ * the new page loads; and the whole server-side filter surface (`search`,
+ * `category_id`, `ribbon_id`, `featured`, `on_sale`, `min_price`, `max_price`,
+ * `in_stock_only`, `sort`) is reachable through `setParams`. Any filter may
+ * legitimately match nothing — render from `isEmpty`, never on the assumption
+ * that rows came back.
  *
  * @param {object} [initialParams] `list-products` params (page/per_page and any filter)
  * @param {{mode?: "pages"|"append", perPage?: number, keepPreviousData?: boolean}} [options]
@@ -105,18 +102,7 @@ export function useProductList(initialParams = {}, options = {}) {
   const isEmpty = !loading && !error && products.length === 0;
   const status = loading ? "loading" : error ? "error" : isEmpty ? "empty" : "ready";
 
-  // Spread on the "Load more" / "Next" button — it disables while a page is in
-  // flight and removes itself when there is no next page, so paging can't be
-  // silently dropped (`hasNext` unrendered = a catalog capped at one page).
-  const moreProps = {
-    type: "button",
-    onClick: appendMode ? loadMore : next,
-    disabled: loading || refreshing || !hasNext,
-    hidden: !hasNext,
-  };
-
   return {
-    moreProps,
     products,
     page: data?.page ?? params.page ?? 1,
     perPage: data?.per_page ?? params.per_page,
@@ -124,6 +110,7 @@ export function useProductList(initialParams = {}, options = {}) {
     totalLoaded: products.length,
     loading,
     refreshing,
+    busy: loading || refreshing,
     error,
     isEmpty,
     status,

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

@@ -1,5 +1,5 @@
 /**
- * The address form, as data. Framework-free; `useAddressForm` binds it to the
+ * The address form, as data. Framework-free; bind 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

package/src/commerce/utils/images.js

@@ -1,5 +1,5 @@
 /**
- * Product images, normalized. Framework-free; `useProductGallery` adds the
+ * Product images, normalized. Framework-free; a gallery adds the
  * gallery's index state on top.
  *
  * Every stored image is an **object** — `{ src, name, alt }` — never a URL

package/src/commerce/utils/index.js

@@ -25,16 +25,16 @@
  * - `address-spec.js` — `addressFieldSpec`: the checkout address form as data,
  *   with country/state options that are always arrays.
  * - `images.js` — `productImages`: images normalized to `{src, name, alt}`.
- * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows with an inferred
- *   `type` (numeric/duration/location/list/text), so each can be rendered as
- *   what it is rather than as another label/value row.
+ * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows (`key`, `label`,
+ *   `titleLabel`, `value`). Match rows by `key`, never by `label`.
  *
- * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
- * layers headless hooks on top of this module, and a hook that pre-composes
- * these helpers is the difference between a rule that holds and a rule you
- * have to remember. Neither layer ships any UI: all markup and styling belong
- * to the storefront you build. Use this module directly for non-React code,
- * and inside your own custom logic.
+ * Building the storefront in React? Import from **`@/commerce/storefront`** and
+ * nothing else — it adds the headless hooks and re-exports the helpers a page
+ * actually needs (`variantAxes`, `productPrice`, `productImages`,
+ * `productSpecs`, `attributesLabel`, `cartTotalsLines`, `orderTotalsLines`), so
+ * one import line covers a page. Neither layer ships any UI: all markup,
+ * styling and copy belong to the storefront you build. Use this module directly
+ * for non-React code and inside your own custom logic.
  */
 export * from "./storefront.js";
 export * from "./variants.js";

package/src/commerce/utils/price.js

@@ -1,6 +1,7 @@
 /**
  * Price presentation — the one place the store's pricing *rules* turn into
- * strings. Framework-free; `useProductPrice` binds it to the store currency.
+ * strings. Framework-free; pass `formatMoney` from `useFormatMoney()` to bind it to
+ * the store's currency.
  *
  * Two rules live here, and both are easy to get wrong in one view while
  * getting them right in another:

package/src/commerce/utils/specs.js

@@ -6,42 +6,29 @@
  * **not** attributes and not ribbons: they describe the product, they don't
  * select a variant. Hidden keys (leading `_`) and empty values are skipped.
  *
- * Each row carries a `type` — inferred from the value (and, for `"location"`,
- * the key) — so the rendering decision is already made for you. **A `.map()`
- * into one uniform label/value table is the fallback, not the target:** the
- * types exist because a carat weight and a care instruction are not the same
- * kind of fact and should not look alike.
- *
  * ```jsx
- * // ❌ every product in every store, identical: one grey table
- * <dl>{productSpecs(product).map((s) => (
- *   <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>))}</dl>
- *
- * // ✅ branch on type — the figures read as figures, the rest stays a row
- * {productSpecs(product).map((s) =>
- *   s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />
- * : s.type === "location" ? <Sourced key={s.key} place={s.value} />          // a located line, a pin
- * : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />          // composition, materials
- * : s.type === "duration" ? <Lead    key={s.key} label={s.label} value={s.value} />
- * :                         <Row     key={s.key} label={s.label} value={s.value} />)}
+ * const specs = productSpecs(product);
+ * const care = findSpec(specs, "care");   // not specs.find(s => s.label === "Care")
  * ```
  *
- * Design the two or three that carry *this* product's meaning (a weight set in
- * the display face, a provenance beside a map, a composition as bars) and let
- * the remainder fall through to the plain row. `key` is still there too, for
- * when one particular modifier of this catalog deserves its own treatment
- * regardless of type. And the rows need not sit in one block — a spec can go
- * under the gallery, beside the price, or inside the description.
+ * **Look rows up with `findSpec`, never by matching `label`.** Meta keys are
+ * free text typed by whoever set the product up, so the same fact is `care`,
+ * `Care`, `care_instructions` or `Care Instructions` across two catalogs — an
+ * equality test on `label` silently never matches and the feature renders its
+ * fallback forever (observed in a live store). `titleLabel` is the display-cased
+ * form, for when you do want to print the key as a heading.
+ *
+ * A `.map()` into one uniform label/value table is the fallback, not the
+ * target: a carat weight and a care instruction are not the same kind of fact
+ * and need not look alike. Which two or three of *this* catalog's modifiers
+ * carry meaning — and how each is rendered — is a design decision about this
+ * store, made from its own data. The rows need not sit in one block either: a
+ * spec can go under the gallery, beside the price, or inside the description.
  *
  * @param {object} product
- * @returns {Array<{key: string, label: string, titleLabel: string, value: string,
- *   type: "numeric"|"duration"|"location"|"list"|"text",
- *   number: number|null, unit: string|null, items: string[]}>}
+ * @returns {Array<{key: string, label: string, titleLabel: string, value: string}>}
  *   `[]` when the product has no visible meta_data — render nothing, not an
- *   empty section. `number`/`unit` are set for `numeric` and `duration`
- *   (`unit` is `""` for a bare number), `items` for `list`, and are
- *   `null`/`[]` otherwise. `value` is always the store's own text, unchanged —
- *   the extra fields are there to render *with*, never a replacement for it.
+ *   empty section. `value` is always the store's own text, unchanged.
  */
 export function productSpecs(product) {
   return (product?.meta_data ?? [])
@@ -50,70 +37,33 @@ export function productSpecs(product) {
       const key = String(m.key);
       const value = String(m.value);
       const label = key.replace(/_/g, " ");
-      // `label` is the admin's key verbatim ("light level"); `titleLabel` is
-      // the display-cased form ("Light Level") — no store wants a lowercase <dt>.
+      // `label` is the key with underscores opened up, in whatever case it was
+      // typed; `titleLabel` is the display-cased form, for printing as a <dt>.
       const titleLabel = label.replace(/(^|\s)\p{Ll}/gu, (c) => c.toUpperCase());
-      return { key, label, titleLabel, value, ...classify(key, value) };
+      return { key, label, titleLabel, value };
     });
 }
 
-const LOCATION_KEY =
-  /(origin|provenance|made[\s_-]?in|country|region|sourced|source|location|city|terroir|appellation|distillery|winery|atelier|workshop)/i;
-
-const DURATION_UNIT =
-  /^(sec|secs|second|seconds|min|mins|minute|minutes|hr|hrs|hour|hours|day|days|week|weeks|month|months|year|years|yr|yrs)$/i;
-
-/** Infer the render-relevant shape of one spec value. Never throws. */
-function classify(key, raw) {
-  const value = raw.trim();
-  const plain = { type: "text", number: null, unit: null, items: [] };
-
-  if (LOCATION_KEY.test(key)) return { ...plain, type: "location" };
-
-  const qty = parseQuantity(value);
-  if (qty) {
-    const type = DURATION_UNIT.test(qty.unit) ? "duration" : "numeric";
-    return { ...plain, type, number: qty.number, unit: qty.unit };
-  }
-
-  const items = parseList(value);
-  if (items) return { ...plain, type: "list", items };
-
-  return plain;
-}
-
-/** "0.75 ct" → {number: 0.75, unit: "ct"}; "18" → {number: 18, unit: ""}. */
-function parseQuantity(value) {
-  const m = /^([-+]?[\d.,]+)\s*(.*)$/.exec(value);
-  if (!m) return null;
-  const number = toNumber(m[1]);
-  if (number === null) return null;
-  const unit = m[2].trim();
-  // A unit is a word or two of symbols/letters. Anything longer is prose that
-  // happens to start with a number ("2 pieces, hand-cut in the studio").
-  if (unit && (!/^[\p{L}%°µ"'/²³.\- ]{1,12}$/u.test(unit) || unit.split(/\s+/).length > 2)) return null;
-  return { number, unit };
-}
-
-/** Grouped thousands are separators; a lone comma between digits is a decimal. */
-function toNumber(raw) {
-  let s = raw.replace(/\s/g, "");
-  if (/^[-+]?\d{1,3}(,\d{3})+(\.\d+)?$/.test(s)) s = s.replace(/,/g, "");
-  else if (/^[-+]?\d+,\d+$/.test(s)) s = s.replace(",", ".");
-  else if (s.includes(",")) return null;
-  const n = Number(s);
-  return Number.isFinite(n) ? n : null;
+/**
+ * Find one spec row by key, tolerantly: case, spaces, `_` and `-` are all
+ * ignored, so `findSpec(rows, "care_instructions")` matches a row the merchant
+ * typed as `Care Instructions`. Returns the row or `null`.
+ *
+ * This is the lookup to use whenever a page features *particular* specs (a
+ * weight rendered as a figure, a provenance beside its place), because meta
+ * keys are free text and an exact match on one spelling is a silent miss.
+ *
+ * @param {Array<{key: string}>} rows from `productSpecs(product)`
+ * @param {string} key the key you mean, in any spelling
+ */
+export function findSpec(rows, key) {
+  const want = normalizeSpecKey(key);
+  if (!want) return null;
+  return (rows ?? []).find((r) => normalizeSpecKey(r?.key) === want) ?? null;
 }
 
-/** "70% wool / 30% cashmere" → ["70% wool", "30% cashmere"]. */
-function parseList(value) {
-  const parts = value
-    .split(/\s*[,;|·•/]\s*/)
-    .map((p) => p.trim())
-    .filter(Boolean);
-  if (parts.length < 2) return null;
-  // Short fragments with words in them — not a sentence that happens to have commas.
-  if (parts.some((p) => p.length > 24 || p.split(/\s+/).length > 3 || /[.!?]/.test(p))) return null;
-  if (!parts.some((p) => /\p{L}/u.test(p))) return null;
-  return parts;
-}
+const normalizeSpecKey = (k) =>
+  String(k ?? "")
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "")
+    .trim();

package/src/commerce/utils/totals.js

@@ -90,10 +90,13 @@ export function orderTotalsLines(order, { formatMoney, labels = {} } = {}) {
 }
 
 /**
- * An order's line items in the same shape as decorated cart lines, so one
- * component renders the bag, the checkout summary and the confirmation —
- * `image` is `{src, alt}|null` and `totalLabel` is pre-formatted, exactly as
- * on `useCart().lines` (pass `formatMoney`; `useOrderReturn` does).
+ * An order's line items, pre-chewed for rendering so one component can serve
+ * the bag, the checkout summary and the confirmation — `image` is
+ * `{src, alt}|null` and `totalLabel` is pre-formatted, sparing a receipt the
+ * two traps of a raw `line_items` entry (an image stored as an object, money
+ * as a number). A cart row is the same shape once you derive it from
+ * `cart.items[n]` yourself — `attributesLabel(item.attributes)` and
+ * `formatMoney(item.total)`. Pass `formatMoney`; `useOrderReturn` does.
  *
  * @param {object} order
  * @param {{formatMoney?: (n: number) => string}} [opts]

package/src/commerce/storefront/useAddressForm.js

@@ -1,175 +0,0 @@
-import { useCallback, useMemo, useState } from "react";
-import { addressFieldSpec } from "@/commerce/utils";
-import { useStoreInfo } from "./StorefrontProvider";
-import { useCheckoutContext } from "./useCheckout";
-import { REQUIRED_BILLING_FIELDS } from "./address";
-
-/**
- * The store's country list, **always as an array**.
- *
- *   const { options, loading } = useCountries();
- *   <select>{options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}</select>
- *
- * `useStoreInfo().countries` is `null` until store info resolves, so mapping it
- * directly white-screens the checkout on a cold load — the most severe defect
- * observed in a generated storefront. Here the list is empty-then-full, never
- * null, and `loading` says which.
- */
-export function useCountries() {
-  const { countries, loading, error } = useStoreInfo();
-  const list = Array.isArray(countries) ? countries : [];
-  const options = useMemo(() => list.map((c) => ({ value: c.code, label: c.name })), [countries]); // eslint-disable-line react-hooks/exhaustive-deps
-  return { countries: list, options, loading, error };
-}
-
-/**
- * Read the new value out of whatever a field's `set` was handed. All three
- * forms an onChange is plausibly written as work, so a field setter can't be
- * called "wrong":
- *
- *   f.set(e.target.value)        // the value
- *   f.set(e)                     // the change event  (onChange={f.set})
- *   f.set(f.key, e.target.value) // key + value, mirroring the top-level set()
- */
-function newValue(args) {
-  if (args.length >= 2) return args[1];
-  const first = args[0];
-  if (first && typeof first === "object" && "target" in first) return first.target?.value ?? "";
-  return first;
-}
-
-/**
- * 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 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 => (
- *     <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>
- *   ))}
- *
- * 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
- * complete enough to price. Two things the field list gets right that a
- * hand-typed table did not: **`state` is present** (rates and taxes match on
- * country + state, and it switches to a select for countries with
- * subdivisions), and the country options are never null.
- *
- * @param {"billing"|"shipping"} [which]
- * @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,
- *   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}}
- */
-export function useAddressForm(which = "billing", options = {}) {
-  const checkout = useCheckoutContext();
-  const { countries, loading: countriesLoading } = useCountries();
-
-  const isBilling = which === "billing";
-  const values = isBilling ? checkout.billing : checkout.shipping;
-  const { updateBilling, updateShipping } = checkout;
-  const set = useCallback(
-    (key, value) => (isBilling ? updateBilling({ [key]: value }) : updateShipping({ [key]: value })),
-    [isBilling, updateBilling, updateShipping],
-  );
-
-  // `place-order` only enforces required fields on billing; a separate shipping
-  // 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,
-      country: values?.country,
-      required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
-      includeEmail: isBilling, // one email per order, on billing
-      ...options,
-    });
-    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).
-      const setField = (...args) => set(f.key, newValue(args));
-      // The address-level error ("we don't ship there") belongs on country.
-      const error =
-        f.key === "country" && checkout.addressError?.code === "shipping_not_available"
-          ? checkout.addressError.message
-          : 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, countriesLoading, values, which, isBilling, set, checkout.addressError, visited, missing.join(","), JSON.stringify(options)]);
-
-  return {
-    fields,
-    set,
-    values: values ?? {},
-    missing,
-    complete: missing.length === 0,
-    error: checkout.addressError ?? null,
-    countriesLoading,
-  };
-}

package/src/commerce/storefront/usePlaceOrder.js

@@ -1,55 +0,0 @@
-import { useCheckoutContext } from "./useCheckout";
-import { useCheckoutBlockers } from "./useTotalsLines";
-
-/**
- * usePlaceOrder — the place-order gate as one spreadable surface. Needs a
- * `<CheckoutProvider>` above it. The whole bottom of a checkout page:
- *
- *   const order = usePlaceOrder();
- *   if (order.stage === "submitted") return <p>Order placed — taking you to your receipt…</p>;
- *   …
- *   <button {...order.buttonProps} className="…">{order.label}</button>
- *   {order.error && <p {...order.errorProps} className="…">{order.error.message}</p>}
- *   {!order.canPlaceOrder && order.blockers.map(b => <p key={b.code}>{b.message}</p>)}
- *
- * ⚑ **The `stage === "submitted"` guard goes above the page's empty-cart
- * branch.** Placing an order clears the cart before the browser navigates
- * away; without the guard the page flashes "your bag is empty" over a
- * just-placed order. `stage` is `"editing" | "placing" | "submitted"`.
- *
- * `buttonProps` carries `onClick`, `disabled` (gate + in-flight) and
- * `aria-busy`; `label` follows `placing` and is overridable via
- * `labels: { idle, placing }`. `blockers` are the disabled button's reasons in
- * words (`useCheckoutBlockers`), each with a `field` to anchor it next to the
- * input that fixes it. Pass `blockerLabels` to override that copy per code.
- *
- * @param {{labels?: {idle?: string, placing?: string},
- *   blockerLabels?: Record<string, string>}} [options]
- * @returns {{buttonProps: object, label: string,
- *   stage: "editing"|"placing"|"submitted", submitted: boolean,
- *   placing: boolean, canPlaceOrder: boolean, error: object|null,
- *   errorProps: object, blockers: Array<{code: string, message: string,
- *   field: string|null}>, placeOrder: (extra?: object) => Promise<object>}}
- */
-export function usePlaceOrder({ labels, blockerLabels } = {}) {
-  const checkout = useCheckoutContext();
-  const blockers = useCheckoutBlockers({ labels: blockerLabels });
-  const { canPlaceOrder, placing, submitted, stage, orderError, placeOrder } = checkout;
-  return {
-    buttonProps: {
-      type: "button",
-      onClick: () => placeOrder(),
-      disabled: !canPlaceOrder || placing,
-      "aria-busy": placing || undefined,
-    },
-    label: placing ? (labels?.placing ?? "Placing your order…") : (labels?.idle ?? "Place order"),
-    stage,
-    submitted,
-    placing,
-    canPlaceOrder,
-    error: orderError,
-    errorProps: { role: "alert" },
-    blockers,
-    placeOrder,
-  };
-}

package/src/commerce/storefront/useProductGallery.js

@@ -1,78 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { imageIndex, productImages } from "@/commerce/utils";
-
-/**
- * useProductGallery — the gallery's non-visual state: normalized images, the
- * active index, and the variant-follows-selection behaviour.
- *
- *   const g = useProductGallery(product, view);
- *   {g.hasImages
- *     ? <img src={g.active.src} alt={g.active.alt} />
- *     : <MyPlaceholder />}
- *   {g.images.map((img, i) => <Thumb key={img.src} onClick={() => g.setActiveIndex(i)} …/>)}
- *
- * The aspect ratio, crossfade and thumbnail styling stay yours — only the state
- * moves here, and with it three details worth having by default: images are
- * normalized to `{src, name, alt}` (they are stored as objects, so a raw
- * `images[0]` as `src` renders broken), `hasImages: false` is an explicit
- * placeholder signal rather than a collapsed element, and **a selection change
- * moves the active image to the variation's own picture while a manual pick
- * still wins until the selection changes again** — highlight, not replace.
- *
- * A null/not-yet-loaded product is fine (`hasImages: false`), so call this with
- * the other hooks **above** the page's `loading`/`not_found` guards — a hook
- * below an early return breaks the hook order the next render.
- *
- * @param {object} product
- * @param {object|null} [view] a `resolveSelection` view; its
- *   `display.image` is the variation's image
- */
-export function useProductGallery(product, view = null) {
-  const images = useMemo(() => productImages(product), [product]);
-  const [activeIndex, setActiveIndex] = useState(0);
-  const manualPick = useRef(false);
-
-  const variationImage = view?.display?.image ?? null;
-  const variationIndex = useMemo(() => imageIndex(images, variationImage), [images, variationImage]);
-  const selectionKey = JSON.stringify(view?.selection ?? {});
-
-  // A new product resets everything; a new selection re-arms the follow.
-  useEffect(() => {
-    manualPick.current = false;
-    setActiveIndex(0);
-  }, [product?.id]);
-
-  useEffect(() => {
-    manualPick.current = false;
-  }, [selectionKey]);
-
-  useEffect(() => {
-    if (manualPick.current || variationIndex < 0) return;
-    setActiveIndex(variationIndex);
-  }, [variationIndex]);
-
-  const select = useCallback(
-    (index) => {
-      manualPick.current = true;
-      setActiveIndex(Math.max(0, Math.min(images.length - 1, index)));
-    },
-    [images.length],
-  );
-  const next = useCallback(() => select((activeIndex + 1) % Math.max(1, images.length)), [activeIndex, images.length, select]);
-  const prev = useCallback(
-    () => select((activeIndex - 1 + Math.max(1, images.length)) % Math.max(1, images.length)),
-    [activeIndex, images.length, select],
-  );
-
-  const safeIndex = Math.min(activeIndex, Math.max(0, images.length - 1));
-  return {
-    images,
-    activeIndex: safeIndex,
-    setActiveIndex: select,
-    next,
-    prev,
-    active: images[safeIndex] ?? null,
-    hasImages: images.length > 0,
-    variationIndex,
-  };
-}