@osimart/create-storefront 0.0.0-stage → 1.0.1

package/app/composables/useProductGallery.js

@@ -0,0 +1,166 @@
+/**
+ * The product page's media column.
+ *
+ * Five desktop layouts, one mobile carousel, one lightbox — all driven by
+ * MAIN_PRODUCT settings, so a merchant gets Shopify's media choices without a
+ * theme fork:
+ *
+ *   STACKED            one image per row, full width (Maqui's layout)
+ *   GRID_2             two-up mosaic, first image spanning both columns
+ *   THUMBNAILS_START   large image with a thumbnail rail beside it
+ *   THUMBNAILS_BELOW   large image with the rail underneath
+ *   CAROUSEL           one image, swipeable, arrows + counter
+ *
+ * The carousel is only wired for CAROUSEL / thumbnail layouts and for mobile;
+ * the stacked layouts don't need Swiper at all, so they don't pay for it.
+ *
+ * Ratios go out as CSS variables rather than classes for the same reason the
+ * card does it: adding a ratio shouldn't mean another branch in the template.
+ */
+
+const RATIOS = {
+  NATURAL: "auto",
+  PORTRAIT: "3 / 4",
+  SQUARE: "1 / 1",
+  LANDSCAPE: "4 / 3",
+  SCREEN: "auto", // paired with a height below
+};
+
+/**
+ * @param {object} options
+ * @param {Array|Ref|(() => Array)} options.images  media rows: { id, path, alt }
+ * @param {object|Ref|(() => object)} options.settings  the section's settings
+ */
+export function useProductGallery({ images, settings = {} } = {}) {
+  const list = computed(() => toValue(images) ?? []);
+  const s = computed(() => toValue(settings) ?? {});
+
+  const { mediaUrl, posterUrl, mediaUrlAs } = useMediaUrl();
+  const { isVideo } = useMediaTypes();
+
+  const layout = computed(() => s.value.MEDIA_LAYOUT || "STACKED");
+  const mobileLayout = computed(() => s.value.MOBILE_MEDIA_LAYOUT || "CAROUSEL");
+  const zoom = computed(() => s.value.MEDIA_ZOOM || "LIGHTBOX");
+
+  const usesThumbnails = computed(() =>
+    ["THUMBNAILS_START", "THUMBNAILS_BELOW"].includes(layout.value)
+  );
+  const usesCarousel = computed(
+    () => usesThumbnails.value || layout.value === "CAROUSEL"
+  );
+
+  const showCounter = computed(() => s.value.MEDIA_SHOW_COUNTER !== false);
+  const showArrows = computed(() => s.value.MEDIA_SHOW_ARROWS !== false);
+  const showDots = computed(() => !!s.value.MEDIA_SHOW_DOTS);
+
+  const galleryStyle = computed(() => {
+    const ratio = s.value.MEDIA_RATIO || "PORTRAIT";
+    const style = {
+      "--osi-pdp-media-ratio": RATIOS[ratio] ?? RATIOS.PORTRAIT,
+      // Phones: a portrait crop takes the whole screen, so the merchant can
+      // pick a shorter one there.
+      "--osi-pdp-media-ratio-mobile":
+        RATIOS[s.value.MEDIA_RATIO_MOBILE] ?? RATIOS[ratio] ?? RATIOS.PORTRAIT,
+      "--osi-pdp-media-fit": s.value.MEDIA_FIT === "CONTAIN" ? "contain" : "cover",
+      "--osi-pdp-media-gap": `${Number(s.value.MEDIA_GAP ?? 4)}px`,
+      "--osi-pdp-media-radius": `${Number(s.value.MEDIA_RADIUS ?? 0)}px`,
+      "--osi-pdp-thumb-size": `${Number(s.value.MEDIA_THUMBNAIL_SIZE ?? 84)}px`,
+      // SCREEN is the one ratio that's a height, not an aspect — a full-bleed
+      // editorial gallery can't be expressed as a ratio because it has to match
+      // the viewport whatever the photo is.
+      "--osi-pdp-media-height": ratio === "SCREEN" ? "100vh" : "auto",
+    };
+    if (s.value.MEDIA_BACKGROUND) style["--osi-pdp-media-bg"] = s.value.MEDIA_BACKGROUND;
+    return style;
+  });
+
+  /* ------------------------------------------------------------- carousel */
+
+  const carousel = useCarousel({
+    items: () => list.value,
+    loop: () => list.value.length > 1,
+    minLoopSlides: 3,
+  });
+
+  const current = computed(() => carousel.activeIndex.value ?? 0);
+
+  // A variant switch replaces the image set; leaving the carousel on slide 4 of
+  // the old set shows an unrelated photo for one frame and then jumps.
+  watch(
+    () => list.value.map((image) => image.path).join("|"),
+    () => {
+      nextTick(() => {
+        carousel.update();
+        carousel.goTo(0, 0);
+      });
+    }
+  );
+
+  /* ------------------------------------------------------------- lightbox */
+
+  const lightboxOpen = ref(false);
+  const lightboxIndex = ref(0);
+
+  useBodyScrollLock(() => lightboxOpen.value);
+
+  function openLightbox(index = 0) {
+    if (zoom.value === "NONE") return;
+    lightboxIndex.value = index;
+    lightboxOpen.value = true;
+  }
+
+  function closeLightbox() {
+    lightboxOpen.value = false;
+  }
+
+  function onKeydown(event) {
+    if (!lightboxOpen.value) return;
+    if (event.key === "Escape") closeLightbox();
+    if (event.key === "ArrowRight") {
+      lightboxIndex.value = Math.min(lightboxIndex.value + 1, list.value.length - 1);
+    }
+    if (event.key === "ArrowLeft") {
+      lightboxIndex.value = Math.max(lightboxIndex.value - 1, 0);
+    }
+  }
+
+  if (import.meta.client) {
+    window.addEventListener("keydown", onKeydown);
+    onScopeDispose(() => window.removeEventListener("keydown", onKeydown));
+  }
+
+  /* ----------------------------------------------------------------- media */
+
+  const src = (image) => mediaUrl(image);
+  const poster = (image) => posterUrl(image, image?.poster);
+  const sourceAs = (image, extension) => mediaUrlAs(image, extension);
+
+  return {
+    images: list,
+    layout,
+    mobileLayout,
+    zoom,
+    usesThumbnails,
+    usesCarousel,
+    showCounter,
+    showArrows,
+    showDots,
+    galleryStyle,
+
+    // carousel
+    ...carousel,
+    current,
+
+    // lightbox
+    lightboxOpen,
+    lightboxIndex,
+    openLightbox,
+    closeLightbox,
+
+    // media
+    isVideo,
+    src,
+    poster,
+    sourceAs,
+  };
+}

package/app/composables/useProductItems.js

@@ -0,0 +1,270 @@
+/**
+ * PRODUCT_LIST's items — products in the one shape the card template reads.
+ *
+ * The card parts (image, title, price, swatches, description, button) are
+ * drawn by ContentNode from an `item`, the same way CLASSIFICATION_LIST's are.
+ * Everything product-specific — price ranges, sale / sold out, the second
+ * image, option swatches, quick buy, add to cart, wishlist — is worked out here once per
+ * product, so ContentNode stays a layout component and the per-card cost is a
+ * plain object, not a stack of composables per card.
+ *
+ * Which products, in which order:
+ *   SOURCE = MANUAL   settings.PRODUCTS (ids, pick order); older sections kept
+ *                     their picks on PRODUCT blocks, read after those
+ *   anything else     the rows the backend resolved (or the preview fetched),
+ *                     cut to LIMIT
+ * PRODUCT blocks (older sections) still override TITLE / MEDIA / BADGE.
+ *
+ * @param {object|Ref|(() => object)} section  pass a getter
+ * @param {Ref<Array>} products                from useSectionData
+ * @param {{ all?: boolean }} options          all: every row as given, no
+ *                                             SOURCE / LIMIT — the classification
+ *                                             grid, which pages itself
+ */
+import { cardOffers, tierText, rangeString } from "#osi/utils/productOffers";
+
+export function useProductItems(section, products, options = {}) {
+  const t = useT();
+  const { mediaUrl } = useMediaUrl();
+  const { productUrl } = useProductUrl();
+  const { store } = useStorefront();
+  const { isPreview } = useBuilderPreview();
+  const { handleAddToCart } = useAddToCart();
+  const { addToWishlist, wishlistStatus } = useWishlist();
+  const analytics = useAnalytics();
+  const route = useRoute();
+  const { resource } = useRenderContext();
+
+  const settings = computed(() => toValue(section)?.settings ?? {});
+  const isManual = computed(() => String(settings.value.SOURCE ?? "").toUpperCase() === "MANUAL");
+
+  const currency = computed(
+    () => store.value?.default_currency?.symbol || store.value?.default_currency?.code || "$"
+  );
+
+  /* ------------------------------------------------------------------ price */
+
+  // price_range / discounted_price_range arrive as a number, a numeric string,
+  // or "min - max" when variants differ in price.
+  function priceParts(value) {
+    if (value === null || value === undefined || value === "") return [];
+    if (typeof value === "number") return Number.isFinite(value) ? [value] : [];
+    return String(value)
+      .split("-")
+      .map((part) => parseFloat(part))
+      .filter((n) => Number.isFinite(n));
+  }
+  function formatPrice(value) {
+    const parts = priceParts(value);
+    if (!parts.some((n) => n > 0)) return "";
+    return parts.map((n) => `${currency.value}${n}`).join(" - ");
+  }
+
+  /* ------------------------------------------------------------------ picks */
+
+  const idOf = (value) => (value && typeof value === "object" ? value.id : value);
+
+  /** Legacy PRODUCT blocks: { productId -> block settings }, in block order. */
+  const blockPicks = computed(() =>
+    (toValue(section)?.blocks ?? [])
+      .filter((b) => b.type === "PRODUCT" && !b.disabled)
+      .map((b) => ({ id: idOf(b.relations?.product ?? b.settings?.PRODUCT), overrides: b.settings ?? {} }))
+      .filter((pick) => pick.id != null)
+  );
+
+  const pickedIds = computed(() => {
+    const ids = (settings.value.PRODUCTS ?? []).map(idOf).filter((id) => id != null);
+    for (const pick of blockPicks.value) if (!ids.some((id) => String(id) === String(pick.id))) ids.push(pick.id);
+    return ids;
+  });
+
+  const rows = computed(() => {
+    const all = products.value ?? [];
+    if (options.all) return all;
+    if (!isManual.value || !pickedIds.value.length) {
+      const limit = Number(settings.value.LIMIT) || 8;
+      return isManual.value ? all : all.slice(0, limit);
+    }
+    // Manual: pick order. Placeholders (an empty store in the editor) have no
+    // matching ids — show them as they are rather than nothing.
+    const byId = new Map(all.map((row) => [String(row.id), row]));
+    const ordered = pickedIds.value.map((id) => byId.get(String(id))).filter(Boolean);
+    return ordered.length ? ordered : all.filter((row) => row.is_placeholder);
+  });
+
+  /* -------------------------------------------------------------- analytics */
+
+  // Every product list the storefront draws goes through here (PRODUCT_LIST,
+  // the category / collection grid, product highlight), so this is the one
+  // place that reports them: view_item_list when the products render, and the
+  // list remembered so a card click can say where it came from.
+  if (import.meta.client) {
+    watch(
+      rows,
+      (list) => {
+        if (isPreview.value || !list?.length) return;
+        const sec = toValue(section) ?? {};
+        const heading = String(t(sec.settings?.HEADING) ?? "").trim();
+        const res = resource.value;
+        const isClassification = !!options.all;
+        analytics.viewItemList({
+          id: isClassification
+            ? `${String(res?.type ?? "list").toLowerCase()}:${res?.slug ?? route.path}`
+            : `${route.path}#${sec.key ?? "products"}`,
+          name: isClassification ? res?.name || route.path : heading || sec.key || "Products",
+          products: list,
+          category: isClassification && ["CATEGORY", "COLLECTION"].includes(res?.type),
+        });
+      },
+      { immediate: true, flush: "post" }
+    );
+  }
+
+  /* ------------------------------------------------------------------ items */
+
+  function imagesOf(product) {
+    const out = [];
+    if (product.main_image) out.push(product.main_image);
+    for (const g of product.gallery ?? []) if (g?.media) out.push(g.media);
+    const seen = new Set();
+    return out.filter((m) => {
+      const k = m?.id ?? m?.path ?? m;
+      if (!k || seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+  }
+
+  /**
+   * Sold out only when the product says so: "Out of Stock", or a stock count
+   * of 0. A missing count (null) isn't 0, and a product with no price isn't
+   * sold out — it just can't be bought yet (its button is disabled).
+   */
+  function soldOutOf(product) {
+    if (product.status === "Out of Stock") return true;
+    if (product.status === "In Stock" || product.status === "On Demand") return false;
+    if (product.remaining_stock === null || product.remaining_stock === undefined) return false;
+    return Number(product.remaining_stock) <= 0;
+  }
+
+  const isColorName = (name) => ["color", "colour"].includes(String(name).toLowerCase());
+
+  /**
+   * Every option (Color, Size, …) with the values that have a variant behind
+   * them. A colour value with a hex / colour draws as a dot; anything else —
+   * sizes, a colour without one — as text.
+   */
+  function optionsOf(product) {
+    return (product.vary_by ?? [])
+      .map((type) => {
+        const seen = new Set();
+        const values = [];
+        for (const variant of product.product_variants ?? []) {
+          const value = (variant.values ?? []).find((v) => v.type === type.id);
+          if (!value || seen.has(value.id)) continue;
+          seen.add(value.id);
+          const color = isColorName(type.name) ? value.hex_code || "" : "";
+          values.push({ key: value.id, name: value.name || value.value || "", color });
+        }
+        return { key: type.id, name: type.name, isColor: isColorName(type.name), values };
+      })
+      .filter((option) => option.values.length);
+  }
+
+  // The one quick buy open in this list: { key, mode } — SHEET | POPUP.
+  const quickBuy = ref(null);
+
+  const plain = (html) =>
+    String(html || "").replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+
+  const items = computed(() => {
+    const overrides = new Map(blockPicks.value.map((pick) => [String(pick.id), pick.overrides]));
+    return rows.value.map((product, i) => {
+      const o = overrides.get(String(product.id)) ?? {};
+      const images = imagesOf(product);
+      const title = t(o.TITLE) || product.name || product.page_title || "";
+      // Shopify's rules (utils/productOffers): the price for one item — only a
+      // 1-item sale lowers it — and the quantity tiers as boxes. Older rows
+      // without the variants' sales keep the API's ranges.
+      const offers = cardOffers(product);
+      let now, was;
+      if (offers) {
+        now = formatPrice(rangeString(offers.now));
+        was = offers.was ? formatPrice(rangeString(offers.was)) : "";
+      } else {
+        const base = product.price_range;
+        const sale = product.discounted_price_range;
+        now = formatPrice(sale ?? base);
+        was = sale && base && String(sale) !== String(base) ? formatPrice(base) : "";
+      }
+      const soldOut = soldOutOf(product);
+      const placeholder = product.is_placeholder === true;
+      const hasOptions = (product.product_variants?.length ?? 0) > 1;
+      const item = {
+        key: `${product.id ?? "p"}-${i}`,
+        id: product.id,
+        kind: "PRODUCT",
+        title,
+        description: plain(product.description),
+        url: placeholder ? null : productUrl(product),
+        image: mediaUrl(o.MEDIA ?? images[0] ?? null),
+        imageAlt: title,
+        hoverImage: o.MEDIA ? "" : images[1] ? mediaUrl(images[1]) : "",
+        price: now,
+        compareAt: was,
+        onSale: offers ? offers.sale : !!was,
+        // For the image's brand / category badges (BADGE_BRAND / BADGE_CATEGORIES).
+        brand: typeof product.brand === "object" ? product.brand?.name || "" : "",
+        categories: (product.categories ?? [])
+          .map((c) => c?.category?.name ?? c?.name ?? "")
+          .filter(Boolean),
+        // Quantity-tier sales (2+ items): badges on the image when there's no
+        // 1-item sale (that one shows "Sale").
+        offers: (offers?.tiers ?? []).map((tier) => ({ id: tier.id, text: tierText(tier, formatPrice, { short: true }) })),
+        soldOut,
+        comingSoon: !!product.coming_soon,
+        hasOptions,
+        badge: t(o.BADGE) || "",
+        options: optionsOf(product),
+        quickBuy: quickBuy.value?.key === `${product.id ?? "p"}-${i}` ? quickBuy.value.mode : null,
+        count: null,
+        wishlisted: wishlistStatus.value[product.id] ?? product.wishlisted ?? false,
+        isPlaceholder: placeholder,
+        raw: product,
+      };
+      // Card parts call these (ContentNode has no product code of its own).
+      item.addToCart = () => addToCart(item);
+      item.toggleWishlist = () => toggleWishlist(item);
+      item.openQuickBuy = (mode) => {
+        if (!inert(item) && !item.soldOut) quickBuy.value = { key: item.key, mode };
+      };
+      item.closeQuickBuy = () => {
+        if (quickBuy.value?.key === item.key) quickBuy.value = null;
+      };
+      return item;
+    });
+  });
+
+  /* ---------------------------------------------------------------- actions */
+
+  // In the editor a click selects the block — it must never add to a real
+  // cart or wishlist. Placeholders aren't real products either.
+  const inert = (item) => isPreview.value || !item || item.isPlaceholder;
+
+  async function addToCart(item) {
+    if (inert(item) || item.soldOut || !item.price) return;
+    try {
+      // Opens the cart itself; a product with options goes to its page.
+      await handleAddToCart(item.raw);
+    } catch {
+      // handleAddToCart shows its own error.
+    }
+  }
+
+  function toggleWishlist(item) {
+    if (inert(item)) return;
+    addToWishlist(item.raw);
+  }
+
+  return { items, addToCart, toggleWishlist };
+}

package/app/composables/useProductUrl.js

@@ -0,0 +1,60 @@
+/**
+ * The href for a product.
+ *
+ * One place, because getting it wrong is invisible: a path the backend doesn't
+ * resolve falls through to NOT_FOUND and renders the wrong template while
+ * looking perfectly fine in the grid.
+ *
+ * ── Route shape ────────────────────────────────────────────────────────────
+ *
+ * `/<category-slug>/<product-slug>` — Terazar's nested form, and what the
+ * merchant-facing URLs are expected to look like.
+ *
+ * ⚠ The builder backend's `resolve_path()` currently maps `/products/<slug>`
+ * to the PRODUCT template and nothing else. Until it also matches a two-segment
+ * `/<category>/<product>` path, every link this produces 404s. That change has
+ * to land before this ships:
+ *
+ *     /categories/<slug>   CLASSIFICATION   (already matched)
+ *     /collections/<slug>  CLASSIFICATION   (already matched)
+ *     /pages/<handle>      PAGE             (already matched)
+ *     /<category>/<slug>   PRODUCT          ← needs adding, matched LAST so it
+ *                                             can't shadow the prefixes above
+ *
+ * That ordering matters: a bare two-segment matcher placed first would swallow
+ * `/categories/shoes` and try to resolve a product called "shoes" in a category
+ * called "categories".
+ *
+ * ── Uncategorised products ─────────────────────────────────────────────────
+ *
+ * A product with no categories has no first segment. Terazar read
+ * `categories[0].category.slugified_name` unguarded, which is why an
+ * uncategorised product threw in search results rather than rendering. Here it
+ * falls back to `/products/<slug>`, which the backend already resolves — so the
+ * link works instead of crashing the page. Keep that route matched.
+ */
+export function useProductUrl() {
+  /** Handles both `[{ category: { slugified_name } }]` and a flat `[{ slugified_name }]`. */
+  function categorySlug(product) {
+    const first = product?.categories?.[0];
+    if (!first) return null;
+
+    return (
+      first.category?.slugified_name ||
+      first.category?.slug ||
+      first.slugified_name ||
+      first.slug ||
+      null
+    );
+  }
+
+  function productUrl(product) {
+    const slug = product?.slugified_name || product?.slug;
+    if (!slug) return "/";
+
+    const category = categorySlug(product);
+    return category ? `/${category}/${slug}` : `/products/${slug}`;
+  }
+
+  return { productUrl, categorySlug };
+}