@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useProductDetail.js

@@ -0,0 +1,982 @@
+import ProductServices from "#osi/services/ProductServices";
+import CartServices from "#osi/services/CartServices";
+
+/**
+ * Product detail state — the whole of Terazar/Maqui's product page logic, lifted
+ * out of the page and made shareable.
+ *
+ * Why a context rather than a page:
+ *
+ * The product page is theme-driven. MAIN_PRODUCT owns the layout, and the info
+ * column is an ordered list of merchant-arranged blocks (title, price, variant
+ * picker, quantity, buy buttons, collapsible rows, …) exactly like Shopify's
+ * main-product section. Those blocks are separate components, and every one of
+ * them needs the same selection: the price a block renders has to be the price
+ * the buy button adds. Prop-drilling that through a v-for over blocks means
+ * every block signature carries ten props it mostly ignores.
+ *
+ * So MainProductSection calls createProductDetail() once and provides it; every
+ * block calls useProductDetail() and reads the same refs.
+ *
+ * ── What was kept from the original page, deliberately ─────────────────────
+ *
+ *  * exactMatchVariant has NO early return on an empty selection. For a product
+ *    with no options, `variant.values` is [] and `.every()` on it is trivially
+ *    true, so the single default variant matches immediately. Bailing out early
+ *    is what used to break "Add to cart" on option-less products.
+ *
+ *  * selectedVariant falls back to a dummy `{ gallery }` object while the
+ *    selection is partial, so picking a colour swaps the gallery before a size
+ *    is chosen.
+ *
+ *  * Deselect-on-second-click, the partial-selection price range, the
+ *    discounted_price_range parsing, "Buy N & Save X off", the coming-soon and
+ *    per-variant track_inventory stock rules, quantity_step arithmetic, and the
+ *    Web Share -> clipboard -> execCommand share chain are all as they were.
+ *
+ * ── What changed, and why ──────────────────────────────────────────────────
+ *
+ *  * `${BASE_URL}${image.path}` is gone. One Nuxt process serves every tenant,
+ *    so a build-time base URL is wrong here — media goes through useMediaUrl().
+ *  * The hand-rolled productCache / inFlight Maps are gone. useAsyncData keyed
+ *    by slug already dedupes, survives SSR->client, and cancels stale results.
+ *  * Option state (selectedOptions, applyCombinationLogic, isSelected) is
+ *    delegated to useProductVariants so the card's quick-shop and this page
+ *    can't drift apart again.
+ */
+
+export const PRODUCT_DETAIL_KEY = Symbol("osi-product-detail");
+
+/* ------------------------------------------------------------------ utils */
+
+/** "10-20" -> { min: 10, max: 20 } ; "10" -> { min: 10, max: 10 } */
+export function parsePriceRange(value) {
+  if (value === null || value === undefined || value === "") {
+    return { min: 0, max: 0 };
+  }
+  const [rawMin, rawMax] = String(value).split("-").map(Number);
+  const min = Number.isFinite(rawMin) ? rawMin : 0;
+  const max = Number.isFinite(rawMax) ? rawMax : min;
+  return { min, max };
+}
+
+/* ------------------------------------------------------------- the source */
+
+/**
+ * The full product for the current route.
+ *
+ * Two calls, because the list endpoint is the only one that takes a slug and
+ * the detail endpoint is the only one that returns variants and the full
+ * gallery. Merged rather than replaced — the list row carries fields
+ * (categories, price_range) the detail response doesn't always repeat.
+ */
+async function loadProduct(slug) {
+  const list = await ProductServices.getProductId(slug);
+  const summary = list?.results?.[0];
+
+  if (!summary?.id) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Product not found",
+      fatal: true,
+    });
+  }
+
+  // A failure here must not 404 a product that exists — the summary alone is
+  // enough to render a card-level page.
+  const detail = await ProductServices.getProductDetail(summary.id).catch(() => null);
+  return detail?.id ? { ...summary, ...detail } : summary;
+}
+
+/**
+ * Resolve the route's product, SSR included.
+ *
+ * Call it from the page (awaited, so the payload is in the server render) and
+ * again from MainProductSection (not awaited — same key, so it reads the cached
+ * payload instead of firing a second request). In the builder there is no route
+ * product at all, so it falls back to a placeholder.
+ */
+/**
+ * @param {object} [options]
+ * @param {() => (number|string|object|null)} [options.productId]
+ *   An explicit product (FEATURED_PRODUCT's picker): an id, or the picked
+ *   object. When given, the route is ignored and the store's first product is
+ *   only used while nothing is picked, in the editor.
+ */
+export function useProductResource(options = {}) {
+  const route = useRoute();
+  const explicit = computed(() => {
+    const raw = toValue(options.productId ?? null);
+    if (raw == null || raw === "") return null;
+    return typeof raw === "object" ? raw.id ?? null : raw;
+  });
+  const isFeatured = options.productId !== undefined;
+  const { resource } = useRenderContext();
+  const placeholders = usePlaceholders();
+
+  const slug = computed(
+    () =>
+      isFeatured ? null :
+      route.params.product ||
+      route.params.slug ||
+      resource.value?.slug ||
+      resource.value?.slugified_name ||
+      null
+  );
+
+  const key = isFeatured
+    ? `product:id:${explicit.value ?? "first"}`
+    : `product:${slug.value ?? "preview"}`;
+
+  // The raw AsyncData is returned as well as its refs: the page awaits it so
+  // the product is in the SSR payload, and MainProductSection calls this again
+  // without awaiting — same key, so it reads that payload instead of firing a
+  // second request.
+  /**
+   * The dashboard previews the PRODUCT template with no product routed. Rather
+   * than the stand-in, show the store's first real product: the merchant is
+   * designing against their own photos, title length and variants, which is
+   * where a layout actually breaks. The stand-in stays for a store whose
+   * catalog is still empty.
+   */
+  async function loadFirstProduct() {
+    const list = await ProductServices.listProducts({ page_size: 1 }).catch(() => null);
+    const summary = list?.results?.[0];
+    if (!summary?.id) return null;
+    const detail = await ProductServices.getProductDetail(summary.id).catch(() => null);
+    return detail?.id ? { ...summary, ...detail } : summary;
+  }
+
+  async function loadById(id) {
+    const detail = await ProductServices.getProductDetail(id).catch(() => null);
+    return detail?.id ? detail : null;
+  }
+
+  const asyncData = useAsyncData(
+    key,
+    () =>
+      explicit.value != null
+        ? loadById(explicit.value)
+        : slug.value
+          ? loadProduct(slug.value)
+          : loadFirstProduct(),
+    {
+      watch: [slug, explicit],
+      default: () => null,
+      getCachedData: (cacheKey, nuxtApp) =>
+        nuxtApp.payload.data[cacheKey] ?? nuxtApp.static.data[cacheKey],
+    }
+  );
+
+  const { data, pending, error, refresh } = asyncData;
+
+  /**
+   * A product-shaped stand-in for the editor.
+   *
+   * Three placeholder rows folded into one so the gallery has something to
+   * stack; a single-image product page reads as broken layout rather than as an
+   * empty catalog. Never reachable on a live storefront — usePlaceholders only
+   * fills when the page is framed by the dashboard.
+   */
+  const placeholder = computed(() => {
+    const rows = placeholders.products([], 3);
+    if (!rows.length) return null;
+
+    const [first, ...rest] = rows;
+    return {
+      ...first,
+      name: "Product title",
+      description:
+        "<p>This is where the product description will appear. Add one from the " +
+        "products area to replace this text.</p>",
+      gallery: [
+        ...(first.gallery ?? []),
+        ...rest.flatMap((row) => row.gallery ?? []),
+      ],
+    };
+  });
+
+  const product = computed(() => data.value ?? placeholder.value ?? null);
+
+  // pending is true on the very first client-side navigation before the fetch
+  // settles; a placeholder standing in for a real product isn't "loaded".
+  const loading = computed(() => pending.value && !data.value);
+
+  return {
+    product,
+    loading,
+    error,
+    refresh,
+    slug,
+    asyncData,
+    isPlaceholder: computed(() => !data.value),
+  };
+}
+
+/* --------------------------------------------------------------- the state */
+
+/**
+ * @param {object} options
+ * @param {object|Ref|(() => object)} options.product
+ * @param {object|Ref|(() => object)} [options.settings] MAIN_PRODUCT settings
+ * @param {boolean|Ref} [options.loading]
+ */
+export function createProductDetail({ product, settings = {}, loading = false } = {}) {
+  const p = computed(() => toValue(product) ?? null);
+  const s = computed(() => toValue(settings) ?? {});
+  const isLoading = computed(() => !!toValue(loading));
+
+  const route = useRoute();
+  const router = useRouter();
+  const { store, cartType } = useStorefront();
+  const { mediaUrl } = useMediaUrl();
+  const { fetchCart } = useCart();
+  const { toggleCartSidebar } = useSidebar();
+  const { showApiError } = useApiErrorToast();
+  const { policies, fetchPolicies } = usePolicies();
+
+  const variants = useProductVariants(product);
+
+  /* ---------------------------------------------------------------- money */
+
+  const currency = computed(
+    () => store.value?.currency_symbol || store.value?.currency_sign || "$"
+  );
+
+  /** Matches the card's convention: "50.00" -> "$50", "49.99" -> "$49.99". */
+  /** "50.00" -> "$50". No price (null, empty, 0) -> "" — never "$0". */
+  function formatMoney(value) {
+    if (value === null || value === undefined || value === "") return "";
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) return "";
+    return `${currency.value}${Number(n.toFixed(2))}`;
+  }
+
+  function formatRange(range) {
+    if (!range) return "";
+    const { min, max } = range;
+    const low = formatMoney(min);
+    const high = formatMoney(max);
+    if (!low || !high || min === max) return low || high;
+    return `${low} – ${high}`;
+  }
+
+  /* ------------------------------------------------------------- variants */
+
+  const variantTypes = computed(() => p.value?.vary_by ?? []);
+  const allVariants = computed(() => p.value?.product_variants ?? []);
+  const selectedValueIds = computed(() => Object.values(variants.selectedOptions.value));
+
+  const hasOptions = computed(() => variantTypes.value.length > 0);
+
+  /**
+   * Complete when every option type has a value. With no option types that's
+   * 0 === 0, i.e. true — which is what lets an option-less product be added.
+   */
+  const isSelectionComplete = computed(
+    () => selectedValueIds.value.length === variantTypes.value.length
+  );
+
+  const missingVariantName = computed(() => {
+    const missing = variantTypes.value.find(
+      (type) => !variants.selectedOptions.value[type.id]
+    );
+    return missing?.name?.toLowerCase() ?? "";
+  });
+
+  /** See the header note — no early return on an empty selection. */
+  const exactMatchVariant = computed(
+    () =>
+      allVariants.value.find((variant) =>
+        (variant.values ?? []).every((value) =>
+          selectedValueIds.value.includes(value.id)
+        )
+      ) ?? null
+  );
+
+  /** Variants sharing at least one selected value — the partial-selection set. */
+  const partialVariants = computed(() => {
+    if (!selectedValueIds.value.length) return [];
+    return allVariants.value.filter((variant) =>
+      (variant.values ?? []).some((value) => selectedValueIds.value.includes(value.id))
+    );
+  });
+
+  /**
+   * The real variant, or a dummy carrying only a merged gallery while the
+   * selection is partial. Image preview reads `.gallery`; anything that adds to
+   * a cart must read exactMatchVariant instead.
+   */
+  const selectedVariant = computed(() => {
+    if (exactMatchVariant.value) return exactMatchVariant.value;
+    if (!selectedValueIds.value.length) return null;
+
+    const unique = [];
+    partialVariants.value.forEach((variant) => {
+      (variant.gallery ?? []).forEach((image) => {
+        const id = image?.media?.id ?? image?.id;
+        if (!id) return;
+        if (unique.some((existing) => (existing?.media?.id ?? existing?.id) === id)) return;
+        unique.push(image);
+      });
+    });
+
+    // Keep the product's own gallery order — a variant gallery that reorders
+    // the same photos makes the column jump on every swatch click.
+    const order = (image) => {
+      const id = image?.media?.id ?? image?.id;
+      return (
+        p.value?.gallery?.findIndex(
+          (candidate) => (candidate?.media?.id ?? candidate?.id) === id
+        ) ?? -1
+      );
+    };
+
+    return { gallery: [...unique].sort((a, b) => order(a) - order(b)) };
+  });
+
+  function selectVariant(value) {
+    if (value?.isAvailable === false) return;
+    variants.selectVariant(value);
+    showError.value = false;
+  }
+
+  const isSelected = (value) => variants.isSelected(value);
+  const applyCombinationLogic = (typeId) => variants.applyCombinationLogic(typeId);
+
+  /** Shopify preselects; the original page didn't. Off unless the theme asks. */
+  function preselectFirstAvailable() {
+    if (!s.value.PRESELECT_FIRST_VARIANT) return;
+    if (selectedValueIds.value.length) return;
+
+    const first = allVariants.value.find(
+      (variant) => !variant.track_inventory || variant.remaining_stock > 0
+    );
+    (first?.values ?? []).forEach((value) => variants.selectVariant(value));
+  }
+
+  /* -------------------------------------------------------------- pricing */
+
+  /* Quantity lives up here: the price depends on it (quantity-tier sales). */
+  const quantityStep = computed(() => Number(p.value?.quantity_step) || 1);
+  const quantityUnit = computed(() => p.value?.quantity_unit?.abbreviation ?? "");
+  const quantity = ref(quantityStep.value);
+
+  watch(quantityStep, (step) => {
+    quantity.value = step;
+  });
+
+  /**
+   * Sales, the way Shopify applies discounts:
+   *  - a 1-item sale (required_quantity 1) is a markdown on every item — the
+   *    unit price itself drops ("save $4" → each item $4 less);
+   *  - a quantity tier (required_quantity 2+) comes off the TOTAL once the
+   *    quantity reaches it, once per order: "buy 12, save $4" is $4 off the
+   *    whole line, not per item and not again at 24; a percentage tier is that
+   *    percentage off the total;
+   *  - discounts don't combine: the one saving the most at the quantity picked
+   *    wins (Shopify's default, no combinations).
+   * So the unit price only changes for a 1-item sale; a tier shows as its box
+   * and in the total line. (The API's discounted_price_range treats tiers as
+   * per-item prices, so it isn't used.)
+   */
+  function activeSales(variant) {
+    const now = Date.now();
+    return (variant?.sales ?? []).filter(
+      (sale) =>
+        Number(sale.discount_value) > 0 &&
+        (!sale.start_date || Date.parse(sale.start_date) <= now) &&
+        (!sale.end_date || Date.parse(sale.end_date) > now)
+    );
+  }
+  const requiredOf = (v) => Math.max(1, Number(Array.isArray(v) ? v[0] : v) || 1);
+  const round2 = (n) => Math.round(n * 100) / 100;
+
+  /**
+   * A variant's discounts, each with what it saves on `qty` items:
+   * { id, required, perItem, saving(qty), label, sale }.
+   */
+  function offersOf(variant) {
+    const price = Number(variant?.price);
+    if (!variant || !(price > 0)) return [];
+    const offers = activeSales(variant).map((sale) => {
+      const required = requiredOf(sale.required_quantity);
+      const pct = sale.sale_type === "Percentage";
+      const value = Number(sale.discount_value);
+      const perItem = required <= 1;
+      const saving = (qty) => {
+        if (qty < required) return 0;
+        if (pct) return round2(qty * price * Math.min(value, 100) / 100);
+        return perItem ? round2(qty * Math.min(value, price)) : Math.min(value, round2(qty * price));
+      };
+      return {
+        id: sale.id, required, perItem, saving,
+        label: pct ? `${value}%` : formatMoney(value),
+      };
+    });
+    // The newer `discount` shape: a discounted unit price from a quantity.
+    const d = variant.discount;
+    if (d?.discounted_price !== undefined && d?.discounted_price !== null && Number(d.discounted_price) < price) {
+      const required = requiredOf(d.required_quantity);
+      const off = round2(price - Number(d.discounted_price));
+      offers.push({
+        id: `discount-${variant.id}`, required, perItem: required <= 1,
+        saving: (qty) => (qty < required ? 0 : required <= 1 ? round2(qty * off) : off),
+        label: d.discount ?? formatMoney(off),
+      });
+    }
+    return offers;
+  }
+
+  /** The discount applied to `qty` of a variant: the biggest saving, or null. */
+  function bestOffer(variant, qty) {
+    let best = null;
+    for (const offer of offersOf(variant)) {
+      const saving = offer.saving(qty);
+      if (saving > 0 && (!best || saving > best.saving)) best = { ...offer, saving };
+    }
+    return best;
+  }
+
+  /** A variant at a quantity: unit price shown, and the line total before / after. */
+  function lineOf(variant, qty) {
+    const price = Number(variant?.price) || 0;
+    const best = bestOffer(variant, qty);
+    const before = round2(price * qty);
+    const after = round2(before - (best?.saving ?? 0));
+    // Only a 1-item markdown changes the unit price.
+    const unit = best?.perItem ? round2(after / qty) : price;
+    // Display only: never a sale on its own.
+    const compare = Number(variant?.compare_at_price) || 0;
+    return { price, compare, unit, before, after, best };
+  }
+
+  /**
+   * The sale boxes under the price: one per quantity tier (2+ items) — a
+   * 1-item sale is already in the price, so it gets no box. Each once, fewest
+   * items first; `applied` when it's the discount the cart will apply.
+   */
+  function tierBadges(list, qty, appliedIds) {
+    const seen = new Map();
+    for (const variant of list ?? []) {
+      for (const offer of offersOf(variant)) {
+        if (offer.perItem || seen.has(offer.id)) continue;
+        seen.set(offer.id, {
+          id: offer.id,
+          required: offer.required,
+          text: `Buy ${offer.required}, save ${offer.label} on the total`,
+          reached: qty >= offer.required,
+          applied: appliedIds.has(offer.id),
+        });
+      }
+    }
+    return [...seen.values()].sort((a, b) => a.required - b.required);
+  }
+
+  /** Products whose discount only comes at product level (no variant sales). */
+  function productLevel(product, qty) {
+    const original = parsePriceRange(product.price_range);
+    const d = product.discounted_price_range;
+    if (d && typeof d === "object" && d.discounted_price_range && (d.discount ?? []).length) {
+      const required = Math.min(...(d.required_quantity ?? [1]).map((n) => requiredOf(n)));
+      const price = typeof d.discounted_price_range === "string" ? parsePriceRange(d.discounted_price_range) : original;
+      const perItem = required <= 1;
+      return {
+        original,
+        price: perItem ? price : original,
+        badges: perItem
+          ? []
+          : [{ id: "product", required, text: `Buy ${required}, save ${d.discount[0]} on the total`, reached: qty >= required, applied: qty >= required }],
+        total: null,
+      };
+    }
+    return { original, price: original, badges: [], total: null };
+  }
+
+  const pricing = computed(() => {
+    const product = p.value;
+    const empty = { original: { min: 0, max: 0 }, price: { min: 0, max: 0 }, badges: [], total: null };
+    if (!product) return empty;
+    const qty = Number(quantity.value) || 1;
+
+    const list = (exactMatchVariant.value
+      ? [exactMatchVariant.value]
+      : selectedValueIds.value.length
+        ? partialVariants.value
+        : allVariants.value
+    ).filter((v) => Number(v?.price) > 0);
+
+    if (!list.length) return productLevel(product, qty);
+    if (!exactMatchVariant.value && !list.some((v) => offersOf(v).length || Number(v.compare_at_price) > Number(v.price))) {
+      const level = productLevel(product, qty);
+      if (level.badges.length || level.price.min !== level.original.min) return level;
+    }
+
+    const lines = list.map((v) => lineOf(v, qty));
+    const span = (pick) => ({ min: Math.min(...lines.map(pick)), max: Math.max(...lines.map(pick)) });
+    const applied = new Set(lines.map((l) => l.best?.id).filter(Boolean));
+
+    // The total line: for one price (a variant picked, or every variant the
+    // same price), from 2 items.
+    const one = lines.every((l) => l.price === lines[0].price && l.after === lines[0].after);
+    const first = lines[0];
+    const total = one && qty > 1
+      ? { quantity: qty, before: first.before, after: first.after, saving: round2(first.before - first.after) }
+      : null;
+
+    return {
+      original: span((l) => l.price),
+      // What is struck through: compare_at_price when above the price, else the pre-sale price.
+      was: lines.some((l) => l.compare > l.unit || l.price > l.unit)
+        ? span((l) => (l.compare > l.unit ? l.compare : l.price > l.unit ? l.price : l.unit))
+        : null,
+      price: span((l) => l.unit),
+      badges: tierBadges(list, qty, applied),
+      total,
+    };
+  });
+
+  const priceRange = computed(() => pricing.value.price);
+  const originalPriceRange = computed(() => pricing.value.original);
+  /** The sale boxes under the price (tiers of 2+ items), each { id, text, reached, applied }. */
+  const discountBadges = computed(() => pricing.value.badges ?? []);
+  /**
+   * The line total for the quantity picked — { quantity, before, after, saving,
+   * text: { before, after, saving } } — or null (1 item, or no single price).
+   */
+  const lineTotal = computed(() => {
+    const t = pricing.value.total;
+    if (!t) return null;
+    return {
+      ...t,
+      text: { before: formatMoney(t.before), after: formatMoney(t.after), saving: formatMoney(t.saving) },
+    };
+  });
+  /** The same, as one line (older callers). */
+  const discountMessage = computed(() => discountBadges.value.map((b) => b.text).join(" · ") || null);
+
+  const isOnSale = computed(
+    () =>
+      originalPriceRange.value.min > 0 &&
+      priceRange.value.min > 0 &&
+      originalPriceRange.value.min !== priceRange.value.min
+  );
+
+  const savingsPercent = computed(() => {
+    if (!isOnSale.value) return 0;
+    const was = originalPriceRange.value.min;
+    const now = priceRange.value.min;
+    return Math.round(((was - now) / was) * 100);
+  });
+
+  const priceText = computed(() => formatRange(priceRange.value));
+
+  /**
+   * Whether the selection has a real price. A product (or variant) with no
+   * price — null, empty, 0 — shows no price and can't be bought.
+   */
+  const hasPrice = computed(() => {
+    const r = priceRange.value;
+    return Number(r?.max ?? 0) > 0 || Number(r?.min ?? 0) > 0;
+  });
+  const comparePriceText = computed(() =>
+    pricing.value.was
+      ? formatRange(pricing.value.was)
+      : isOnSale.value
+        ? formatRange(originalPriceRange.value)
+        : ""
+  );
+
+  /* ---------------------------------------------------------------- stock */
+
+  const isComingSoon = computed(() => !!p.value?.coming_soon);
+
+  const isOutOfStock = computed(() => {
+    const product = p.value;
+    if (!product) return false;
+
+    // A missing stock count (null) isn't 0 — not sold out.
+    const out = (n) => n !== null && n !== undefined && Number(n) <= 0;
+    const variant = exactMatchVariant.value;
+    if (variant?.id) {
+      if (!variant.track_inventory) return false;
+      return out(variant.remaining_stock);
+    }
+
+    if (product.status === "In Stock") return false;
+    if (product.status === "Out of Stock") return true;
+    if (product.status === "On Demand") return false;
+
+    return out(product.remaining_stock);
+  });
+
+  /** Units left on the current selection, or null when nothing tracks it. */
+  const remainingStock = computed(() => {
+    const variant = exactMatchVariant.value;
+    if (variant?.id) return variant.track_inventory ? variant.remaining_stock : null;
+    return p.value?.remaining_stock ?? null;
+  });
+
+  const isLowStock = computed(() => {
+    const threshold = Number(s.value.LOW_STOCK_THRESHOLD) || 0;
+    if (!threshold || remainingStock.value === null) return false;
+    return remainingStock.value > 0 && remainingStock.value <= threshold;
+  });
+
+  const sku = computed(() => exactMatchVariant.value?.sku || p.value?.sku || "");
+
+  /* --------------------------------------------------------------- images */
+
+  /**
+   * The gallery for the current selection: the variant's own images when there
+   * are any, otherwise the product's main image followed by its gallery.
+   * Deduped on path — the same photo reaches this list through both routes.
+   */
+  const activeImages = computed(() => {
+    const product = p.value;
+    if (!product) return [];
+
+    let images = [];
+    const variantGallery = selectedVariant.value?.gallery;
+
+    if (variantGallery?.length) {
+      images = variantGallery.map((entry) => ({
+        id: entry.media?.id ?? entry.id,
+        path: entry.media?.path ?? entry.path,
+        alt: entry.media?.alt ?? entry.alt ?? product.name,
+      }));
+    } else {
+      if (product.main_image) {
+        images.push({
+          id: product.main_image.id,
+          path: product.main_image.path,
+          alt: product.main_image.alt ?? product.name,
+        });
+      }
+      (product.gallery ?? []).forEach((entry) => {
+        images.push({
+          id: entry.media?.id ?? entry.id,
+          path: entry.media?.path ?? entry.path,
+          alt: entry.media?.alt ?? entry.alt ?? product.name,
+        });
+      });
+    }
+
+    const seen = new Set();
+    return images.filter((image) => {
+      if (!image.path || seen.has(image.path)) return false;
+      seen.add(image.path);
+      return true;
+    });
+  });
+
+  const imageUrl = (image) => mediaUrl(image);
+
+  /* ------------------------------------------------------------- quantity */
+
+  // quantityStep / quantityUnit / quantity are declared with the pricing.
+
+  const maxQuantity = computed(() => {
+    const perUser = exactMatchVariant.value?.max_quantity_per_user;
+    const stock = remainingStock.value;
+    const limits = [perUser, stock].filter((value) => Number.isFinite(Number(value)) && value > 0);
+    return limits.length ? Math.min(...limits.map(Number)) : null;
+  });
+
+  function increment() {
+    const next = quantity.value + quantityStep.value;
+    if (maxQuantity.value && next > maxQuantity.value) return;
+    quantity.value = next;
+  }
+
+  function decrement() {
+    if (quantity.value > quantityStep.value) quantity.value -= quantityStep.value;
+  }
+
+  function setQuantity(value) {
+    const step = quantityStep.value;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < step) {
+      quantity.value = step;
+      return;
+    }
+    // Snap to the step: a typed 7 on a step of 5 is rejected by the API anyway.
+    const snapped = Math.round(n / step) * step;
+    quantity.value = maxQuantity.value ? Math.min(snapped, maxQuantity.value) : snapped;
+  }
+
+  /* ----------------------------------------------------------------- cart */
+
+  const isAddingToCart = ref(false);
+  const showError = ref(false);
+  let errorTimer = null;
+
+  function flashSelectionError() {
+    showError.value = true;
+    clearTimeout(errorTimer);
+    errorTimer = setTimeout(() => {
+      showError.value = false;
+    }, 3000);
+  }
+
+  function openCartUi() {
+    if (cartType.value === "PAGE") router.push("/cart");
+    else toggleCartSidebar(true);
+  }
+
+  /**
+   * @param {object} [options]
+   * @param {boolean} [options.buyNow] straight to checkout instead of the drawer
+   * @returns {Promise<boolean>} whether the line was added
+   */
+  async function addToCart({ buyNow = false } = {}) {
+    if (isAddingToCart.value) return false;
+    if (isComingSoon.value || isOutOfStock.value || !hasPrice.value) return false;
+
+    if (!isSelectionComplete.value || !exactMatchVariant.value) {
+      flashSelectionError();
+      return false;
+    }
+
+    if (quantity.value % quantityStep.value !== 0) {
+      showApiError(
+        { message: `Enter a quantity in multiples of ${quantityStep.value}.` },
+        `Enter a quantity in multiples of ${quantityStep.value}.`
+      );
+      return false;
+    }
+
+    isAddingToCart.value = true;
+    try {
+      await CartServices.EditCart(exactMatchVariant.value.id, quantity.value, "add", {
+        product: p.value,
+        variant: exactMatchVariant.value,
+      });
+      await fetchCart();
+
+      if (buyNow) router.push("/checkout");
+      else openCartUi();
+
+      return true;
+    } catch (error) {
+      showApiError(error, "Couldn't add that to your cart.");
+      return false;
+    } finally {
+      isAddingToCart.value = false;
+    }
+  }
+
+  const buyDisabled = computed(
+    () =>
+      isComingSoon.value || isOutOfStock.value || !hasPrice.value || isAddingToCart.value || isLoading.value
+  );
+
+  const buyLabel = computed(() => {
+    if (isComingSoon.value) return "Coming soon";
+    if (isOutOfStock.value) return "Sold out";
+    if (isAddingToCart.value) return "Adding…";
+    return null; // the block supplies its own default label
+  });
+
+  /* ---------------------------------------------------------------- share */
+
+  const stripHtml = (html) => String(html ?? "").replace(/<[^>]*>?/gm, "").trim();
+
+  function legacyCopy(text) {
+    const input = document.createElement("textarea");
+    input.value = text;
+    input.style.position = "fixed";
+    input.style.opacity = "0";
+    document.body.appendChild(input);
+    input.focus();
+    input.select();
+    let copied = false;
+    try {
+      copied = document.execCommand("copy");
+    } catch {
+      copied = false;
+    }
+    document.body.removeChild(input);
+    return copied;
+  }
+
+  const shareState = ref("");
+
+  async function shareProduct() {
+    if (!import.meta.client) return;
+
+    const url = window.location.href;
+    const data = {
+      title: p.value?.name,
+      text: stripHtml(p.value?.description),
+      url,
+    };
+
+    try {
+      if (navigator.share) {
+        await navigator.share(data);
+        return;
+      }
+      throw new Error("Web Share unavailable");
+    } catch (error) {
+      // The shopper closing the native sheet isn't a failure.
+      if (error?.name === "AbortError") return;
+
+      try {
+        if (navigator.clipboard?.writeText) {
+          await navigator.clipboard.writeText(url);
+        } else if (!legacyCopy(url)) {
+          throw new Error("Clipboard unavailable");
+        }
+        shareState.value = "Link copied";
+        setTimeout(() => {
+          shareState.value = "";
+        }, 2000);
+      } catch (copyError) {
+        showApiError(copyError, "Couldn't share this product.");
+      }
+    }
+  }
+
+  /* ---------------------------------------------------------- breadcrumbs */
+
+  const breadcrumbs = computed(() => {
+    const categories = p.value?.categories ?? [];
+    if (!categories.length) return [];
+
+    // The route's category segment is the path the shopper actually came
+    // through; fall back to the product's first category on a flat URL.
+    const routeSlug = route.params.category;
+    const matched =
+      categories.find((entry) => entry.category?.slugified_name === routeSlug) ??
+      categories[0];
+
+    const category = matched?.category;
+    if (!category) return [];
+
+    const items = [{ name: "Home", path: "/" }];
+
+    if (category.parent_category) {
+      items.push({
+        name: category.parent_category.name,
+        path: `/categories/${category.parent_category.slugified_name}`,
+      });
+    }
+
+    items.push({
+      name: category.name,
+      path: `/categories/${category.slugified_name}`,
+    });
+    items.push({ name: p.value?.name });
+
+    return items;
+  });
+
+  /* -------------------------------------------------------------- lifecycle */
+
+  function resetSelections() {
+    variants.reset();
+    quantity.value = quantityStep.value;
+    showError.value = false;
+  }
+
+  watch(
+    () => p.value?.id,
+    () => {
+      resetSelections();
+      preselectFirstAvailable();
+    }
+  );
+
+  onMounted(() => {
+    fetchPolicies();
+    preselectFirstAvailable();
+  });
+
+  onScopeDispose(() => clearTimeout(errorTimer));
+
+  return {
+    // source
+    product: p,
+    settings: s,
+    loading: isLoading,
+
+    // options
+    variants,
+    variantTypes,
+    hasOptions,
+    selectedOptions: variants.selectedOptions,
+    selectedVariant,
+    exactMatchVariant,
+    isSelected,
+    selectVariant,
+    applyCombinationLogic,
+    isSelectionComplete,
+    missingVariantName,
+    showError,
+    resetSelections,
+
+    // price
+    pricing,
+    priceRange,
+    originalPriceRange,
+    discountMessage,
+    discountBadges,
+    lineTotal,
+    isOnSale,
+    savingsPercent,
+    priceText,
+    hasPrice,
+    comparePriceText,
+    formatMoney,
+    formatRange,
+    currency,
+
+    // stock
+    isComingSoon,
+    isOutOfStock,
+    remainingStock,
+    isLowStock,
+    sku,
+
+    // media
+    activeImages,
+    imageUrl,
+
+    // quantity
+    quantity,
+    quantityStep,
+    quantityUnit,
+    maxQuantity,
+    increment,
+    decrement,
+    setQuantity,
+
+    // cart
+    addToCart,
+    isAddingToCart,
+    buyDisabled,
+    buyLabel,
+
+    // misc
+    policies,
+    shareProduct,
+    shareState,
+    breadcrumbs,
+    stripHtml,
+  };
+}
+
+export function provideProductDetail(context) {
+  provide(PRODUCT_DETAIL_KEY, context);
+  return context;
+}
+
+/**
+ * Read the context MainProductSection provided. Returns null outside a product
+ * section rather than throwing, so a block dropped somewhere odd renders
+ * nothing instead of taking the page down.
+ */
+export function useProductDetail() {
+  return inject(PRODUCT_DETAIL_KEY, null);
+}