@base44/app-plugin-commerce 0.2.4 → 0.2.6

package/src/commerce/storefront/useCartLine.js

@@ -20,6 +20,37 @@ import { useCart } from "./StorefrontProvider";
  * request per settle instead of one per click; and `sold_individually` is
  * respected, so a one-per-customer product has no working "+".
  *
+ * ## When `pending` settles — the exact window
+ *
+ * `pending` is this line's own flag, not the cart's, and it is **not** true for
+ * the whole gesture:
+ *
+ * 1. **Click → `pending` stays `false`.** `increase`/`decrease` only set the
+ *    optimistic `quantity` and (re)start a `debounceMs` (250ms) timer. Nothing
+ *    is in flight yet, and a further click restarts the timer, so a burst of
+ *    clicks sends **one** request for the final number.
+ * 2. **Debounce elapses → `pending` becomes `true`** and the request goes out.
+ *    `remove()` skips this step: it cancels the timer and goes `pending`
+ *    immediately.
+ * 3. **`pending` returns to `false` only after the server's new cart view has
+ *    been published to the provider** — the awaited mutation resolves through
+ *    the provider's serialized queue, which sets the shared cart state before
+ *    the await returns. So `pending === false` with `error === null` means this
+ *    row's quantity, the cart's totals and any dependent badge are settled, not
+ *    merely that the request finished.
+ *
+ * Two consequences worth designing for. **Disable and mark only this row**
+ * (`disabled={!l.canIncrease || l.pending}`) — `pending` says nothing about the
+ * other lines, and greying the whole cart because one stepper is busy makes a
+ * 250ms update look like a page-wide stall. And **`pending` is the only
+ * mutation-settled signal**: `useCart().status` never returns to `"loading"`
+ * for a mutation (see its doc comment), so a caller that needs to know an
+ * update landed — a script driving the page, a queued follow-up action — waits
+ * on this flag, per row, and not on cart `status`.
+ *
+ * On failure `pending` returns to `false`, the optimistic quantity rolls back
+ * to what the server still holds, and `error` is `{ code, message }`.
+ *
  * @param {object} line a decorated line from `useCart().lines` (a raw
  *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
  * @param {{debounceMs?: number}} [options]
@@ -104,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 ?? "",
   };
 }
 
@@ -117,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>
  *       )}

package/src/commerce/storefront/useCheckout.jsx

@@ -89,6 +89,12 @@ function resolvePaymentMethod(gateways, picked) {
  * `shipping_address_required`, `shipping_method_required`,
  * `shipping_not_available`, `payment_method_required`.
  *
+ * `stage` is `"editing" | "placing" | "submitted"` (`submitted` = the order was
+ * accepted; the navigation away is already in flight). **Guard on it before the
+ * cart's empty branch** — `placeOrder` clears the cart, so a page that checks
+ * only `cart.status` repaints "your bag is empty" over a just-placed order for
+ * the frames before the browser leaves. `usePlaceOrder` packages this gate.
+ *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
  * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
  * `orderReceivedPath` ("/order-received"; null disables the navigation).
@@ -113,6 +119,7 @@ export function useCheckout(options = {}) {
   const [syncing, setSyncing] = useState(false);
   const [syncedKey, setSyncedKey] = useState(undefined);
   const [placing, setPlacing] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
   const [orderError, setOrderError] = useState(null);
 
   const updateBilling = useCallback((patch) => setBilling((b) => ({ ...b, ...patch })), []);
@@ -216,6 +223,10 @@ export function useCheckout(options = {}) {
           ...(shipToDifferent ? { shipping } : {}),
           ...extra, // customer_note, success_url/cancel_url overrides, …
         });
+        // `submitted` flips BEFORE the cart clears, in the same commit — the
+        // page's `stage === "submitted"` guard is what stands between a placed
+        // order and a flash of "your bag is empty" while the browser navigates.
+        setSubmitted(true);
         clearCart(); // checkout consumed the cart
         if (
           redirectToPayment &&
@@ -280,6 +291,8 @@ export function useCheckout(options = {}) {
     blockers,
     canPlaceOrder,
     placing,
+    submitted,
+    stage: placing ? "placing" : submitted ? "submitted" : "editing",
     orderError,
     placeOrder,
     // underlying data, for convenience

package/src/commerce/storefront/useOrderReturn.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
-import { useStorefrontState } from "./StorefrontProvider";
+import { useFormatMoney, useStorefrontState } from "./StorefrontProvider";
 import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
@@ -19,9 +19,10 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  *   // "cancelled" → payment was cancelled — offer paymentLink.url or support
  *   // "error"     → render error.message with a retry via reload()
  *
- * `lines` are the order's items in the decorated cart-line shape, so the same
- * row markup renders the bag and the confirmation; totals come from
- * `useTotalsLines(order)`. The page is marked `noindex` automatically — a
+ * `lines` are the order's items in the decorated cart-line shape —
+ * `attributesLabel`, `image` as `{src, alt}|null`, `totalLabel` pre-formatted —
+ * so the same row markup renders the bag and the confirmation; totals come
+ * from `useTotalsLines(order)`. The page is marked `noindex` automatically — a
  * receipt carrying an order key must not rank (`seo: false` opts out).
  *
  * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
@@ -32,6 +33,7 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  */
 export function useOrderReturn({ auto = true, seo = true } = {}) {
   const { client } = useStorefrontState();
+  const formatMoney = useFormatMoney();
   const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
 
   const reload = useCallback(
@@ -61,7 +63,7 @@ export function useOrderReturn({ auto = true, seo = true } = {}) {
 
   useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
 
-  return { ...result, lines: orderLines(result.order ?? null), reload };
+  return { ...result, lines: orderLines(result.order ?? null, { formatMoney }), reload };
 }
 
 /**

package/src/commerce/storefront/usePlaceOrder.js

@@ -0,0 +1,55 @@
+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/useProduct.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   defaultSelection,
+  productSpecs,
   resolveSelection,
   selectOption,
   selectionFromParams,
@@ -9,6 +10,7 @@ import {
   storefrontErrorMessage,
 } from "@/commerce/utils";
 import { useCart, useStorefront } from "./StorefrontProvider";
+import { useCartUIOptional } from "./cartUI";
 import { useAsyncData } from "./internal/useAsyncData";
 import { useProductPrice } from "./useProductPrice";
 
@@ -226,49 +228,67 @@ export function useAddToCart() {
   return { add, adding, error, lastAdded, reset };
 }
 
+const BUY_LABELS = {
+  ready: "Add to bag",
+  adding: "Adding…",
+  sold_out: "Sold out",
+  needs_selection: "Select options",
+};
+
 /**
  * useAddToCartButton — the buy button's whole state machine, ready to bind to
  * markup you write. Pass the entire `useProduct` result:
  *
  *   const p = useProduct(slug);
- *   const buy = useAddToCartButton(p, { onAdded: () => navigate("/bag") });
- *   <button disabled={buy.disabled} onClick={buy.add}>
- *     {buy.adding ? "Adding…" : buy.soldOut ? "Sold out"
- *       : buy.needsSelection ? "Select options" : "Add to bag"}
- *   </button>
+ *   const buy = useAddToCartButton(p, { labels: { ready: "Add to bag" } });
+ *   <button {...buy.buttonProps} className="…">{buy.label}</button>
  *   {buy.error && <p role="alert">{buy.error.message}</p>}
  *
+ * `state` is `"ready" | "adding" | "sold_out" | "needs_selection"` — the
+ * precedence is resolved here, not in a ternary chain — and `label` follows it
+ * (override any of the four via `labels`; the words are still yours).
+ * `buttonProps` carries onClick, the purchasability gate and `aria-busy`. With
+ * a `<CartUIProvider>` mounted, a successful add opens the cart drawer by
+ * itself (its `openOnAdd`); `onAdded` remains for a navigate-to-bag flow.
+ *
  * What it wires so a hand-written buy box can't drop it: the button is gated on
  * `view.purchasable`; a rejected add (sold out, stale variant) lands in `error`
  * instead of leaving the button stuck on "Adding…"; a stale-variant rejection
  * reloads the product; and the quantity controls respect `sold_individually`
  * and tracked stock (`showQuantity` is false when only 1 can be bought — render
- * no stepper then). Every label and every element is yours.
+ * no stepper then).
  *
  * A not-yet-loaded product is fine (`disabled: true`), so call this next to
  * `useProduct` **above** the page's `loading`/`not_found` guards — a hook below
  * an early return breaks the hook order the next render.
  *
  * @param {object} product the whole `useProduct` result
- * @param {{onAdded?: (cart: object) => void}} [options]
+ * @param {{onAdded?: (cart: object) => void,
+ *   labels?: {ready?: string, adding?: string, sold_out?: string,
+ *   needs_selection?: string}}} [options]
  * @returns {{add: () => Promise<object>, adding: boolean, error: object|null,
  *   reset: () => void, disabled: boolean, soldOut: boolean,
  *   needsSelection: boolean, purchasable: boolean,
+ *   state: "ready"|"adding"|"sold_out"|"needs_selection", label: string,
+ *   buttonProps: object,
  *   quantity: number, setQuantity: (n: number) => void, increase: () => void,
  *   decrease: () => void, canIncrease: boolean, canDecrease: boolean,
  *   maxQuantity: number, showQuantity: boolean}}
  */
-export function useAddToCartButton(product, { onAdded } = {}) {
+export function useAddToCartButton(product, { onAdded, labels } = {}) {
   const { add, adding, error, reset } = useAddToCart();
+  const cartUI = useCartUIOptional();
   const view = product?.view ?? null;
 
   const submit = useCallback(async () => {
     if (!view) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };
     const res = await add(view.addToCart, product.quantity);
-    if (res.ok) onAdded?.(res.cart);
-    else if (res.error?.shouldReload) product.reload?.();
+    if (res.ok) {
+      cartUI?.onItemAdded?.();
+      onAdded?.(res.cart);
+    } else if (res.error?.shouldReload) product.reload?.();
     return res;
-  }, [add, view, product, onAdded]);
+  }, [add, view, product, onAdded, cartUI]);
 
   // A variable product with an incomplete selection isn't sold out — it needs
   // a pick; only a resolved (or simple) unpurchasable view reads as sold out.
@@ -277,16 +297,27 @@ export function useAddToCartButton(product, { onAdded } = {}) {
       ? view.complete && !view.purchasable
       : !view.purchasable
     : false;
+  const needsSelection = Boolean(view?.isVariable && !view.complete);
+  const state = adding ? "adding" : soldOut ? "sold_out" : needsSelection ? "needs_selection" : "ready";
+  const disabled = !view?.purchasable || adding;
 
   return {
     add: submit,
     adding,
     error,
     reset,
-    disabled: !view?.purchasable || adding,
+    disabled,
     soldOut,
-    needsSelection: Boolean(view?.isVariable && !view.complete),
+    needsSelection,
     purchasable: Boolean(view?.purchasable),
+    state,
+    label: labels?.[state] ?? BUY_LABELS[state],
+    buttonProps: {
+      type: "button",
+      onClick: submit,
+      disabled,
+      "aria-busy": adding || undefined,
+    },
     quantity: product?.quantity ?? 1,
     setQuantity: product?.setQuantity ?? (() => {}),
     increase: product?.incQuantity ?? (() => {}),
@@ -297,3 +328,52 @@ export function useAddToCartButton(product, { onAdded } = {}) {
     showQuantity: (product?.maxQuantity ?? 1) > 1,
   };
 }
+
+const normalizeSpecKey = (k) =>
+  String(k ?? "")
+    .toLowerCase()
+    .replace(/[\s_-]+/g, " ")
+    .trim();
+
+/**
+ * useProductSpecs — `productSpecs` plus the lookup every page that features
+ * specific specs needs, with the matching solved. **Never match spec rows by
+ * `label` string equality** — a row's `label` is the admin's meta key verbatim
+ * (`"light level"`, lowercase), so `specs.find(s => s.label === "Light")`
+ * silently never matches and the feature renders its fallback forever. `get`
+ * and `pick` here match case-, `_`- and `-`-insensitively.
+ *
+ *   const specs = useProductSpecs(product, { pick: ["light", "water", "humidity"] });
+ *   specs.picked                 // the requested rows, in your order (missing ones skipped)
+ *   specs.rest                   // everything else — safe to render as the remainder,
+ *                                //   the picked rows are already excluded
+ *   specs.get("light_level")     // one row or null
+ *   specs.rows                   // all rows (== productSpecs(product))
+ *
+ * Rows carry `titleLabel` (display-cased) next to the verbatim `label`, and the
+ * `type`/`number`/`unit`/`items` fields for type-driven rendering — see
+ * `productSpecs`.
+ *
+ * @param {object|null} product tolerates null/loading — call above status guards
+ * @param {{pick?: string[]}} [options]
+ * @returns {{rows: Array<object>, picked: Array<object>, rest: Array<object>,
+ *   get: (key: string) => object|null, has: (key: string) => boolean}}
+ */
+export function useProductSpecs(product, { pick = [] } = {}) {
+  const pickKey = JSON.stringify(pick);
+  return useMemo(() => {
+    const rows = productSpecs(product);
+    const byKey = new Map(rows.map((r) => [normalizeSpecKey(r.key), r]));
+    const get = (key) => byKey.get(normalizeSpecKey(key)) ?? null;
+    const picked = pick.map(get).filter(Boolean);
+    const pickedSet = new Set(picked);
+    return {
+      rows,
+      picked,
+      rest: rows.filter((r) => !pickedSet.has(r)),
+      get,
+      has: (key) => byKey.has(normalizeSpecKey(key)),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [product, pickKey]);
+}

package/src/commerce/storefront/useProductList.js

@@ -9,6 +9,7 @@ import { useAsyncData } from "./internal/useAsyncData";
  *   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
  *
  * A short strip is the same hook with a small `per_page` — a featured rail, a
  * "new in" row, four picks beside an article:
@@ -104,7 +105,18 @@ 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,

package/src/commerce/storefront/useUpsell.js

@@ -0,0 +1,90 @@
+import { useCallback } from "react";
+import { productImages } from "@/commerce/utils";
+import { useCart, useStorefront } from "./StorefrontProvider";
+import { useCartUIOptional } from "./cartUI";
+import { useAsyncData } from "./internal/useAsyncData";
+import { useAddToCart } from "./useProduct";
+import { useProductPrice } from "./useProductPrice";
+
+/**
+ * useUpsell — one product offered beside another surface (a cart drawer's
+ * "add the care kit", a checkout's "complete the set", a cross-sell strip
+ * entry), with the lifecycle solved:
+ *
+ *   const kit = useUpsell("care-kit");                    // slug or { id }…
+ *   const kit = useUpsell(p.crossSells[0]);               // …or a row you already have
+ *   {kit.show && (
+ *     <aside className="…">
+ *       {kit.image && <img src={kit.image.src} alt={kit.image.alt} className="…" />}
+ *       {kit.product.name} {kit.price.label}
+ *       <button type="button" onClick={kit.add} disabled={kit.adding}>Add</button>
+ *       {kit.error && <p role="alert">{kit.error.message}</p>}
+ *     </aside>
+ *   )}
+ *
+ * `show` is the one flag to branch on: it is false while loading, on a fetch
+ * failure, when the product is out of stock, and **when it is already in the
+ * cart** — matched by product id, never by display name (a rename must not
+ * break the match). Passing a row you already hold (`product.upsells` /
+ * `product.crossSells` from `useProduct`, or a `useProductList` row) skips the
+ * fetch entirely — prefer that when the row is on hand.
+ *
+ * `add()` never throws; a product with options can't be one-click added
+ * (`needsSelection` — link to its page instead). With `<CartUIProvider>`
+ * mounted, a successful add opens the drawer.
+ *
+ * @param {string|{id: string}|object} ref slug, `{ id }`, or a product row
+ * @param {{quantity?: number}} [options]
+ * @returns {{show: boolean, inCart: boolean, needsSelection: boolean,
+ *   product: object|null, image: {src: string, alt: string}|null,
+ *   price: object, add: () => Promise<object>, adding: boolean,
+ *   error: object|null}}
+ */
+export function useUpsell(ref, { quantity = 1 } = {}) {
+  const store = useStorefront();
+  const { cart } = useCart();
+  const cartUI = useCartUIOptional();
+
+  // A row (has id + name) is used as-is; a slug or { id } is fetched.
+  const isRow = Boolean(ref && typeof ref === "object" && ref.id && ref.name !== undefined);
+  const refKey = isRow ? `row:${ref.id}` : typeof ref === "string" ? ref : JSON.stringify(ref ?? null);
+
+  const { data, loading, error: fetchError } = useAsyncData(
+    () => (isRow || !ref ? Promise.resolve(null) : store.getProduct(ref)),
+    [store, refKey], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const product = isRow ? ref : (data?.product ?? null);
+  const needsSelection = isRow
+    ? (ref.attributes?.length ?? 0) > 0
+    : (data?.variations?.length ?? 0) > 0;
+
+  const price = useProductPrice(product);
+  const { add: rawAdd, adding, error, reset } = useAddToCart();
+
+  const add = useCallback(async () => {
+    if (!product) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };
+    if (needsSelection) {
+      return { ok: false, error: { code: "variation_required", message: "Choose an option first." } };
+    }
+    const res = await rawAdd({ product_id: product.id }, quantity);
+    if (res.ok) cartUI?.onItemAdded?.();
+    return res;
+  }, [product, needsSelection, rawAdd, quantity, cartUI]);
+
+  const inCart = Boolean(product) && (cart?.items ?? []).some((i) => i.product_id === product.id);
+  const busy = !isRow && Boolean(ref) && loading;
+
+  return {
+    show: !busy && !fetchError && Boolean(product) && !inCart && product?.stock_status !== "outofstock",
+    inCart,
+    needsSelection,
+    product,
+    image: productImages(product)[0] ?? null,
+    price,
+    add,
+    adding,
+    error,
+    reset,
+  };
+}

package/src/commerce/utils/index.js

@@ -25,8 +25,9 @@
  * - `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, keyed so each
- *   can be rendered its own way.
+ * - `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.
  *
  * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
  * layers headless hooks on top of this module, and a hook that pre-composes

package/src/commerce/utils/specs.js

@@ -1,32 +1,119 @@
 /**
  * Product spec rows — the descriptive properties a product page shows
- * (Material, Care, Fit, Provenance, Composition).
+ * (Material, Care, Fit, Provenance, Composition, Weight).
  *
  * These live in `product.meta_data` (the admin's *Modifiers* section) and are
  * **not** attributes and not ribbons: they describe the product, they don't
  * select a variant. Hidden keys (leading `_`) and empty values are skipped.
- * You render the rows yourself, and `key` is there so you don't have to render
- * them all the same way — a uniform list is the fallback, not the target:
  *
- *   const specs = productSpecs(product);
- *   {specs.length > 0 && <dl>{specs.map(s =>
- *     <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>)}</dl>}
+ * 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.
  *
- * Branch on `s.key` to give the ones that carry this product's meaning their
- * own treatment (a composition as bars, a provenance as a located line, a
- * weight set in the display face) and let the rest fall through to the row
- * above.
+ * ```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} />)}
+ * ```
+ *
+ * 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.
  *
  * @param {object} product
- * @returns {Array<{key: string, label: string, value: string}>} `[]` when the
- *   product has no visible meta_data — render nothing, not an empty section.
+ * @returns {Array<{key: string, label: string, titleLabel: string, value: string,
+ *   type: "numeric"|"duration"|"location"|"list"|"text",
+ *   number: number|null, unit: string|null, items: 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.
  */
 export function productSpecs(product) {
   return (product?.meta_data ?? [])
     .filter((m) => m?.key && !String(m.key).startsWith("_") && m.value != null && m.value !== "")
-    .map((m) => ({
-      key: String(m.key),
-      label: String(m.key).replace(/_/g, " "),
-      value: String(m.value),
-    }));
+    .map((m) => {
+      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>.
+      const titleLabel = label.replace(/(^|\s)\p{Ll}/gu, (c) => c.toUpperCase());
+      return { key, label, titleLabel, value, ...classify(key, 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;
+}
+
+/** "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;
 }