@base44/app-plugin-commerce 0.2.7 → 0.3.1

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,166 +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 value, setter, id,
- * `autoComplete` token and error, so the whole form is one map and every
- * element and attribute in it is yours:
- *
- *   const { fields } = useAddressForm("billing");
- *   {fields.map(f => (
- *     <div key={f.key} className="…">
- *       <label htmlFor={f.id}>{f.label}{f.required && " *"}</label>
- *       {f.isSelect ? (
- *         <select id={f.id} value={f.value} onChange={f.set}
- *                 autoComplete={f.autoComplete} className="…">
- *           <option value="">{f.placeholder}</option>
- *           {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
- *         </select>
- *       ) : <input id={f.id} type={f.type} value={f.value} onChange={f.set}
- *                  autoComplete={f.autoComplete} className="…" />}
- *       {f.error && <span role="alert" className="…">{f.error}</span>}
- *     </div>
- *   ))}
- *
- * ⚑ Keep `value={f.value}` + `onChange={f.set}` (the pair that binds the field
- * to checkout) and `autoComplete={f.autoComplete}` (browsers fill addresses in
- * one gesture with it, field by field without). `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 reports itself once it has been edited and left empty — untouched
- * fields stay quiet here and surface through the place-order `blockers`.
- *
- * `f.set` works with custom controls too — it accepts a value, the raw change
- * event (`onChange={f.set}`) or a `(key, value)` pair — as does 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, id: 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}>,
- *   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 edited —
-  // an untouched form must not open covered in "required" marks. (Fields never
-  // touched at all surface through the place-order blockers instead.)
-  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).
-      // The first edit marks the field visited, arming its required check.
-      const setField = (...args) => {
-        setVisited((v) => (v[f.key] ? v : { ...v, [f.key]: true }));
-        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;
-      return {
-        ...f,
-        id: `${which}-${f.key}`,
-        value,
-        set: setField,
-        error,
-        isSelect: f.type === "select",
-        placeholder:
-          f.type === "select"
-            ? f.key === "country" && countriesLoading
-              ? "Loading…"
-              : `Select ${f.label}`
-            : undefined,
-      };
-    });
-    // 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,63 +0,0 @@
-import { useCallback } from "react";
-import { useCheckoutContext } from "./useCheckout";
-import { useCheckoutBlockers } from "./useTotalsLines";
-
-/**
- * usePlaceOrder — the place-order gate as plain states and one handler. 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 type="button" onClick={order.placeOrder} disabled={order.disabled} className="…">
- *     {order.label}
- *   </button>
- *   {order.error && <p role="alert" 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"`.
- *
- * `disabled` is the gate plus in-flight (`!canPlaceOrder || placing`); `label`
- * follows `placing` and is overridable via `labels: { idle, placing }`.
- * `placeOrder` is safe as an `onClick` handler directly — a click event passed
- * to it is ignored (an explicit `extra` object is still forwarded). `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 {{placeOrder: (extra?: object) => Promise<object>, disabled: boolean,
- *   label: string, stage: "editing"|"placing"|"submitted", submitted: boolean,
- *   placing: boolean, canPlaceOrder: boolean, error: object|null,
- *   blockers: Array<{code: string, message: string, field: string|null}>}}
- */
-export function usePlaceOrder({ labels, blockerLabels } = {}) {
-  const checkout = useCheckoutContext();
-  const blockers = useCheckoutBlockers({ labels: blockerLabels });
-  const { canPlaceOrder, placing, submitted, stage, orderError, placeOrder } = checkout;
-
-  // Usable as onClick={order.placeOrder}: a DOM/React event is not `extra`.
-  const place = useCallback(
-    (extra) => {
-      const isEvent = extra && typeof extra === "object" && ("nativeEvent" in extra || "target" in extra);
-      return placeOrder(isEvent ? undefined : extra);
-    },
-    [placeOrder],
-  );
-
-  return {
-    placeOrder: place,
-    disabled: !canPlaceOrder || placing,
-    label: placing ? (labels?.placing ?? "Placing your order…") : (labels?.idle ?? "Place order"),
-    stage,
-    submitted,
-    placing,
-    canPlaceOrder,
-    error: orderError,
-    blockers,
-  };
-}

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,
-  };
-}

package/src/commerce/storefront/useProductPrice.js

@@ -1,58 +0,0 @@
-import { useCallback, useMemo } from "react";
-import { productPrice } from "@/commerce/utils";
-import { useFormatMoney, useStoreInfo } from "./StorefrontProvider";
-
-/**
- * Money formatting in the store's currency, with the pieces a custom price UI
- * needs (parity with the admin's `useMoney`).
- *
- * @returns {{format: (n: number) => string, formatRange: (a: number, b: number) => string,
- *   code: string|null, symbol: string, decimals: number}}
- */
-export function useMoney() {
-  const format = useFormatMoney();
-  const { settings } = useStoreInfo();
-  const code = settings?.currency ?? null;
-  const formatRange = useCallback((min, max) => `${format(min)} – ${format(max)}`, [format]);
-  const symbol = useMemo(() => {
-    if (!code) return "";
-    try {
-      // The currency part of a formatted zero — locale-correct, no symbol table.
-      return new Intl.NumberFormat(undefined, { style: "currency", currency: code })
-        .formatToParts(0)
-        .find((p) => p.type === "currency")?.value ?? code;
-    } catch {
-      return code;
-    }
-  }, [code]);
-  const decimals = useMemo(() => {
-    if (!code) return 2;
-    try {
-      return new Intl.NumberFormat(undefined, { style: "currency", currency: code })
-        .resolvedOptions().maximumFractionDigits ?? 2;
-    } catch {
-      return 2;
-    }
-  }, [code]);
-
-  return { format, formatRange, code, symbol, decimals };
-}
-
-/**
- * The rendered price of a product row **or** a resolved selection view, in the
- * store's currency:
- *
- *   const price = useProductPrice(row);    // a card:         "From €19.99"
- *   const price = useProductPrice(view);   // a product page: "€19.99 – €23.99"
- *                                          //   until the selection resolves
- *   <span>{price.label}</span>
- *   {price.compareAtLabel && <s>{price.compareAtLabel}</s>}
- *
- * One call for both views is the point — the from-price rule cannot be honoured
- * on the grid and forgotten on the product page. See `productPrice` for the
- * rules themselves.
- */
-export function useProductPrice(rowOrView) {
-  const formatMoney = useFormatMoney();
-  return useMemo(() => productPrice(rowOrView, { formatMoney }), [rowOrView, formatMoney]);
-}