@base44/app-plugin-commerce 0.1.0

package/src/commerce/utils/variants.js

@@ -0,0 +1,411 @@
+/**
+ * Variant selection helpers for the storefront product page.
+ *
+ * A variable product is defined on two levels: the parent's `attributes[]`
+ * entries with `variation: true` are the *axes* (Size, Color), and each record
+ * in `variations[]` is one combination of options on those axes. The product
+ * page must therefore present **one control per axis** — never a flat list of
+ * `Red-S`, `Red-M`, `Blue-S`, ... — and map the customer's selection onto a
+ * variation itself: the cart API does no attribute matching, it takes a
+ * `variation_id`. These helpers own that mapping in both directions.
+ *
+ * Framework-free, dependency-free, no I/O — feed them the `{ product,
+ * variations }` pair from `commerce/storefront-catalog` `get-product` (the
+ * admin's variation editor can use them too). See
+ * `skills/commerce/references/storefront-product-page.md` for the UI rules.
+ *
+ * A `selection` throughout is a plain object keyed by axis key (see
+ * `attributeKey`): `{ "<color-attr-id>": "Red", "<size-attr-id>": "M" }`.
+ */
+
+/** Availability of a single option, as returned by `optionAvailability`. */
+export const OPTION_AVAILABLE = "available";
+export const OPTION_OUT_OF_STOCK = "out_of_stock";
+export const OPTION_UNAVAILABLE = "unavailable";
+
+const PURCHASABLE_STOCK = new Set(["instock", "onbackorder"]);
+
+/**
+ * Stable key for an attribute or a variation-attribute entry.
+ *
+ * Global attributes carry an `attribute_id`; custom (product-local) ones have
+ * it empty, so an id-only key would collide across them — fall back to `name`.
+ *
+ * @param {{attribute_id?: string, name?: string}} attribute
+ * @returns {string}
+ */
+export function attributeKey(attribute) {
+  return attribute?.attribute_id || attribute?.name || "";
+}
+
+/**
+ * The product's variation axes: `attributes` with `variation: true`, ordered by
+ * `position`. These — and only these — become selectors on the product page;
+ * `visible: true` non-variation attributes belong in a spec table.
+ *
+ * @param {object} product
+ * @returns {Array<object>} the matching `product.attributes` entries
+ */
+export function variationAxes(product) {
+  return (product?.attributes ?? [])
+    .filter((a) => a?.variation)
+    .slice()
+    .sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+}
+
+/** The variation's option on one axis, or "" when it accepts any value. */
+function variationOption(variation, key) {
+  const entry = (variation?.attributes ?? []).find((a) => attributeKey(a) === key);
+  return entry?.option ?? "";
+}
+
+/** Variations that are actually offered (publishable). */
+function publishable(variations) {
+  return (variations ?? []).filter((v) => (v?.status ?? "publish") === "publish");
+}
+
+function isPurchasable(variation) {
+  return PURCHASABLE_STOCK.has(variation?.stock_status ?? "instock");
+}
+
+/**
+ * Does a variation satisfy a (possibly partial) selection? An empty option on
+ * the variation is a wildcard, and axes absent from `selection` are ignored —
+ * so a partial selection matches every variation still reachable from it.
+ *
+ * @param {object} product
+ * @param {object} variation
+ * @param {Record<string, string>} selection
+ * @returns {boolean}
+ */
+export function variationMatches(product, variation, selection) {
+  return variationAxes(product).every((axis) => {
+    const key = attributeKey(axis);
+    const chosen = selection?.[key];
+    if (!chosen) return true;
+    const option = variationOption(variation, key);
+    return !option || option === chosen;
+  });
+}
+
+/**
+ * Every publishable variation still reachable from a partial selection —
+ * the basis for narrowing images, price ranges and option availability before
+ * the customer has picked every axis.
+ *
+ * @returns {Array<object>}
+ */
+export function matchingVariations(product, variations, selection = {}) {
+  return publishable(variations).filter((v) => variationMatches(product, v, selection));
+}
+
+/** Has the customer picked an option on every axis? */
+export function isSelectionComplete(product, selection = {}) {
+  const axes = variationAxes(product);
+  return axes.length > 0 && axes.every((a) => Boolean(selection?.[attributeKey(a)]));
+}
+
+/**
+ * selection → variation. Returns the variation to add to the cart, or `null`
+ * while the selection is incomplete or matches nothing.
+ *
+ * @param {object} product
+ * @param {Array<object>} variations
+ * @param {Record<string, string>} selection
+ * @returns {object|null}
+ */
+export function findVariation(product, variations, selection = {}) {
+  if (!isSelectionComplete(product, selection)) return null;
+  return matchingVariations(product, variations, selection)[0] ?? null;
+}
+
+/**
+ * variation → selection. The inverse of `findVariation`: use it to hydrate the
+ * controls from a variation you already have (a cart line, an order item, a
+ * `?variation=` link).
+ *
+ * @param {object} product
+ * @param {object} variation
+ * @returns {Record<string, string>} omits axes the variation leaves as "any"
+ */
+export function selectionForVariation(product, variation) {
+  const selection = {};
+  for (const axis of variationAxes(product)) {
+    const key = attributeKey(axis);
+    const option = variationOption(variation, key);
+    if (option) selection[key] = option;
+  }
+  return selection;
+}
+
+/**
+ * The options to render per axis, in the parent's declared order, dropping any
+ * option no publishable variation offers (a stale `attributes[].options` entry
+ * would otherwise render a permanently dead choice).
+ *
+ * @returns {Array<{key: string, name: string, attribute_id: string, options: string[]}>}
+ */
+export function axisOptions(product, variations) {
+  const live = publishable(variations);
+  return variationAxes(product).map((axis) => {
+    const key = attributeKey(axis);
+    const offered = new Set();
+    let wildcard = false;
+    for (const v of live) {
+      const option = variationOption(v, key);
+      if (option) offered.add(option);
+      else wildcard = true; // a wildcard variation covers every declared option
+    }
+    const declared = axis.options ?? [];
+    const options = wildcard ? declared.slice() : declared.filter((o) => offered.has(o));
+    // options present on variations but missing from the parent's list, appended
+    for (const option of offered) if (!options.includes(option)) options.push(option);
+    return { key, name: axis.name ?? "", attribute_id: axis.attribute_id ?? "", options };
+  });
+}
+
+/**
+ * Per-option availability given the rest of the current selection, so the UI
+ * can disable rather than hide impossible choices:
+ *   `available`    — a purchasable variation exists
+ *   `out_of_stock` — the combination exists but every match is out of stock
+ *   `unavailable`  — no such combination
+ *
+ * @returns {Record<string, Record<string, string>>} `{ [axisKey]: { [option]: state } }`
+ */
+export function optionAvailability(product, variations, selection = {}) {
+  const out = {};
+  for (const axis of axisOptions(product, variations)) {
+    out[axis.key] = {};
+    for (const option of axis.options) {
+      const hypothetical = { ...selection, [axis.key]: option };
+      const hits = matchingVariations(product, variations, hypothetical);
+      out[axis.key][option] = !hits.length
+        ? OPTION_UNAVAILABLE
+        : hits.some(isPurchasable)
+          ? OPTION_AVAILABLE
+          : OPTION_OUT_OF_STOCK;
+    }
+  }
+  return out;
+}
+
+/**
+ * Apply a click to the current selection. Keeps the just-picked option and
+ * drops only the axes that now conflict, so the customer can always switch a
+ * colour without dead-ending on an unavailable size. Passing a falsy `option`
+ * clears the axis.
+ *
+ * @returns {Record<string, string>} the next selection (never mutates the input)
+ */
+export function selectOption(product, variations, selection, axisKey, option) {
+  if (!option) {
+    const { [axisKey]: _cleared, ...rest } = selection ?? {};
+    return rest;
+  }
+  const next = { ...(selection ?? {}), [axisKey]: option };
+  if (matchingVariations(product, variations, next).length) return next;
+
+  // Re-add the other axes one at a time, keeping only those that stay reachable.
+  const kept = { [axisKey]: option };
+  for (const axis of variationAxes(product)) {
+    const key = attributeKey(axis);
+    if (key === axisKey) continue;
+    const chosen = next[key];
+    if (!chosen) continue;
+    const candidate = { ...kept, [key]: chosen };
+    if (matchingVariations(product, variations, candidate).length) kept[key] = chosen;
+  }
+  return kept;
+}
+
+/**
+ * The initial selection for a freshly-opened product page: the merchant's
+ * `default_attributes`, plus any axis that has only one option. Options that
+ * lead nowhere are skipped, so the result is always reachable.
+ *
+ * @returns {Record<string, string>}
+ */
+export function defaultSelection(product, variations) {
+  let selection = {};
+  const axes = axisOptions(product, variations);
+  const byKey = new Map(axes.map((a) => [a.key, a]));
+
+  for (const preset of product?.default_attributes ?? []) {
+    const key = attributeKey(preset);
+    if (!preset.option || !byKey.has(key)) continue;
+    if (!byKey.get(key).options.includes(preset.option)) continue;
+    selection = selectOption(product, variations, selection, key, preset.option);
+  }
+  for (const axis of axes) {
+    if (selection[axis.key] || axis.options.length !== 1) continue;
+    selection = selectOption(product, variations, selection, axis.key, axis.options[0]);
+  }
+  return selection;
+}
+
+/**
+ * Price range across the variations still reachable from `selection` (all of
+ * them by default). Use this for a variable product's headline price: the
+ * backend rolls stock up to the parent but **not** price, so `product.price`
+ * is not a variable product's price.
+ *
+ * @returns {{min: number, max: number, on_sale: boolean, count: number}|null} `null` when nothing is priced
+ */
+export function priceRange(product, variations, selection = {}) {
+  const prices = [];
+  let onSale = false;
+  for (const v of matchingVariations(product, variations, selection)) {
+    const price = Number(v?.price ?? NaN);
+    if (!Number.isFinite(price)) continue;
+    prices.push(price);
+    if (v.on_sale) onSale = true;
+  }
+  if (!prices.length) return null;
+  return { min: Math.min(...prices), max: Math.max(...prices), on_sale: onSale, count: prices.length };
+}
+
+/**
+ * The fields to display for the current state, resolved variation-first with a
+ * fallback to the parent. `image` is the variation's own image when it has one
+ * — highlight it in the gallery rather than replacing the gallery.
+ *
+ * `image` is `{src, name, alt}`, or `null` when the product has no images at all
+ * — the one case needing a UI placeholder.
+ *
+ * @returns {{price: number|null, regular_price: number|null, sale_price: number|null,
+ *            on_sale: boolean, sku: string, stock_status: string,
+ *            stock_quantity: number|null, backorders: string, image: object|null,
+ *            weight: number|null, dimensions: object|null, description: string,
+ *            downloadable: boolean, virtual: boolean}}
+ */
+export function displayFields(product, variation) {
+  const pick = (key, fallback = null) => {
+    const v = variation?.[key];
+    if (v !== undefined && v !== null && v !== "") return v;
+    const p = product?.[key];
+    return p !== undefined && p !== null && p !== "" ? p : fallback;
+  };
+  return {
+    price: variation ? (variation.price ?? null) : (product?.price ?? null),
+    regular_price: pick("regular_price"),
+    sale_price: variation ? (variation.sale_price ?? null) : (product?.sale_price ?? null),
+    on_sale: Boolean(variation ? variation.on_sale : product?.on_sale),
+    sku: pick("sku", ""),
+    stock_status: pick("stock_status", "instock"),
+    stock_quantity: variation
+      ? (variation.manage_stock === "yes" ? (variation.stock_quantity ?? null) : (product?.stock_quantity ?? null))
+      : (product?.stock_quantity ?? null),
+    backorders: pick("backorders", "no"),
+    image: variation?.image?.src ? variation.image : (product?.images?.[0] ?? null),
+    weight: pick("weight"),
+    dimensions: pick("dimensions"),
+    description: variation?.description || product?.description || "",
+    downloadable: Boolean(variation ? variation.downloadable : product?.downloadable),
+    virtual: Boolean(variation ? variation.virtual : product?.virtual),
+  };
+}
+
+/**
+ * One-call view model for a product page. Recompute it on every selection
+ * change and render straight from the result.
+ *
+ * ```js
+ * const { product, variations } = await getProduct(slug);
+ * let selection = defaultSelection(product, variations);
+ * let view = resolveSelection(product, variations, selection);
+ * // on a click: selection = selectOption(product, variations, selection, axisKey, option)
+ * ```
+ *
+ * Branches on `product.type`, not on `variations` (pass `[]` for a simple
+ * product). A `variable` product never falls back to the parent, so one with no
+ * usable variations yields empty `axes[].options`, `purchasable: false` and
+ * `addToCart: null` — render it unavailable and guard the "select a …" label.
+ *
+ * @returns {{
+ *   isVariable: boolean, axes: Array<object>, selection: Record<string, string>,
+ *   complete: boolean, variation: object|null, candidates: Array<object>,
+ *   availability: Record<string, Record<string, string>>,
+ *   priceRange: {min: number, max: number, on_sale: boolean, count: number}|null,
+ *   display: object, purchasable: boolean, addToCart: {product_id: string, variation_id: string}|null,
+ *   missingAxes: Array<{key: string, name: string}>
+ * }}
+ */
+export function resolveSelection(product, variations, selection = {}) {
+  const isVariable = (product?.type ?? "simple") === "variable";
+  if (!isVariable) {
+    const display = displayFields(product, null);
+    return {
+      isVariable: false,
+      axes: [],
+      selection: {},
+      complete: true,
+      variation: null,
+      candidates: [],
+      availability: {},
+      priceRange: null,
+      display,
+      purchasable: PURCHASABLE_STOCK.has(display.stock_status),
+      addToCart: product?.id ? { product_id: product.id, variation_id: "" } : null,
+      missingAxes: [],
+    };
+  }
+
+  const axes = axisOptions(product, variations);
+  const variation = findVariation(product, variations, selection);
+  const display = displayFields(product, variation);
+  return {
+    isVariable: true,
+    axes,
+    selection: { ...selection },
+    complete: isSelectionComplete(product, selection),
+    variation,
+    candidates: matchingVariations(product, variations, selection),
+    availability: optionAvailability(product, variations, selection),
+    priceRange: priceRange(product, variations, selection),
+    display,
+    purchasable: Boolean(variation) && isPurchasable(variation),
+    addToCart: variation ? { product_id: product.id, variation_id: variation.id } : null,
+    missingAxes: axes
+      .filter((a) => !selection?.[a.key])
+      .map((a) => ({ key: a.key, name: a.name })),
+  };
+}
+
+/**
+ * Serialize a selection for a shareable URL, using attribute *names* (`?color=
+ * Red&size=M`) so links stay readable and survive an attribute-id change.
+ *
+ * @returns {Record<string, string>} query params, lowercase keys
+ */
+export function selectionToParams(product, selection = {}) {
+  const params = {};
+  for (const axis of variationAxes(product)) {
+    const key = attributeKey(axis);
+    const option = selection?.[key];
+    if (option && axis.name) params[axis.name.toLowerCase()] = option;
+  }
+  return params;
+}
+
+/**
+ * Hydrate a selection from URL params written by `selectionToParams`. Matches
+ * axis names and options case-insensitively and drops anything unreachable.
+ *
+ * @param {object} product
+ * @param {Array<object>} variations
+ * @param {Record<string, string>|URLSearchParams} params
+ * @returns {Record<string, string>}
+ */
+export function selectionFromParams(product, variations, params) {
+  const read = (name) =>
+    params instanceof URLSearchParams ? params.get(name) : params?.[name];
+  let selection = {};
+  for (const axis of axisOptions(product, variations)) {
+    const raw = read(axis.name?.toLowerCase?.() ?? "") ?? read(axis.name ?? "");
+    if (!raw) continue;
+    const option = axis.options.find((o) => o.toLowerCase() === String(raw).toLowerCase());
+    if (option) selection = selectOption(product, variations, selection, axis.key, option);
+  }
+  return selection;
+}