@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useProductVariants.js

@@ -0,0 +1,210 @@
+/**
+ * Variant selection for a product.
+ *
+ * Terazar had two copies of this: one in ProductCard for quick-shop
+ * (selectLocalVariant / findMatchingVariant / applyCombinationLogic) and one in
+ * the product detail page. They drifted — the card's version cleared
+ * selectedColor on deselect, the page's didn't. One composable, both callers.
+ *
+ * The data shape, since none of it is obvious from the names:
+ *   product.vary_by          [{ id, name: 'Color', values: [{ id, name, ... }] }]
+ *   product.product_variants [{ id, price, values: [{ id, type }], gallery, sales,
+ *                              track_inventory, remaining_stock }]
+ * A variant's `values[].type` is the vary_by id it belongs to. So a selection is
+ * a map of { [varyById]: valueId }, and a variant matches when every one of its
+ * values is selected.
+ *
+ * @param {object|Ref|(() => object)} product pass a getter — the card is
+ *   rendered in a v-for and the product prop changes identity on re-fetch.
+ */
+export function useProductVariants(product) {
+  const p = computed(() => toValue(product) ?? {});
+
+  const selectedOptions = ref({});
+  const selectedVariant = ref(null);
+  const selectedColor = ref(null);
+
+  const variantTypes = computed(() => p.value.vary_by ?? []);
+
+  const hasVariants = computed(
+    () =>
+      Array.isArray(p.value.product_variants) && p.value.product_variants.length > 1
+  );
+
+  const colorType = computed(
+    () => variantTypes.value.find((type) => type.name === "Color") ?? null
+  );
+
+  /** Distinct colour values that actually have a variant behind them. */
+  const availableColors = computed(() => {
+    if (!colorType.value) return [];
+
+    const fromVariants =
+      p.value.product_variants
+        ?.map((variant) => variant.values.find((v) => v.type === colorType.value.id))
+        .filter(Boolean) ?? [];
+
+    return fromVariants.filter(
+      (color, index, self) => index === self.findIndex((c) => c.id === color.id)
+    );
+  });
+
+  const isSelected = (value) => selectedOptions.value[value.type] === value.id;
+
+  /** Values of one type that exist on at least one variant. */
+  function getAvailableVariants(varyById) {
+    const type = variantTypes.value.find((v) => v.id === varyById);
+    if (!type) return [];
+
+    const present = new Set();
+    p.value.product_variants?.forEach((variant) => {
+      variant.values.forEach((value) => {
+        if (value.type === varyById) present.add(value.id);
+      });
+    });
+
+    return type.values.filter((value) => present.has(value.id));
+  }
+
+  /**
+   * Same list, each value flagged `isAvailable` against the *other* current
+   * selections — picking Red greys out the sizes Red doesn't come in. With
+   * nothing selected everything is available.
+   */
+  function applyCombinationLogic(varyById) {
+    if (Object.keys(selectedOptions.value).length === 0) {
+      return getAvailableVariants(varyById).map((value) => ({
+        ...value,
+        isAvailable: true,
+      }));
+    }
+
+    const others = Object.entries(selectedOptions.value)
+      .filter(([key]) => key !== varyById)
+      .map(([, value]) => value);
+
+    const matching =
+      p.value.product_variants?.filter((variant) =>
+        others.every((id) => variant.values.map((v) => v.id).includes(id))
+      ) ?? [];
+
+    return getAvailableVariants(varyById).map((value) => ({
+      ...value,
+      isAvailable: matching.some((variant) =>
+        variant.values.map((v) => v.id).includes(value.id)
+      ),
+    }));
+  }
+
+  /** Exact match only — a partial selection resolves to no variant. */
+  function findMatchingVariant() {
+    const selected = Object.values(selectedOptions.value);
+
+    const exact = p.value.product_variants?.find((variant) =>
+      variant.values.every((value) => selected.includes(value.id))
+    );
+
+    selectedVariant.value = exact ?? null;
+  }
+
+  /** Clicking the selected value deselects it — that's deliberate, not a bug. */
+  function selectVariant(value) {
+    const next = { ...selectedOptions.value };
+
+    if (next[value.type] === value.id) {
+      delete next[value.type];
+      selectedOptions.value = next;
+      selectedVariant.value = null;
+      if (colorType.value && value.type === colorType.value.id) {
+        selectedColor.value = null;
+      }
+    } else {
+      next[value.type] = value.id;
+      selectedOptions.value = next;
+      if (colorType.value && value.type === colorType.value.id) {
+        selectedColor.value = value;
+      }
+    }
+
+    findMatchingVariant();
+  }
+
+  const isSelectionComplete = computed(
+    () =>
+      variantTypes.value.length > 0 &&
+      Object.keys(selectedOptions.value).length === variantTypes.value.length
+  );
+
+  /** "size" — for the "Select a size" prompt. */
+  const missingVariantName = computed(() => {
+    const missing = variantTypes.value.find((type) => !selectedOptions.value[type.id]);
+    return missing ? missing.name.toLowerCase() : "";
+  });
+
+  function reset() {
+    selectedOptions.value = {};
+    selectedVariant.value = null;
+    selectedColor.value = null;
+  }
+
+  // --- stock ---------------------------------------------------------------
+
+  const isComingSoon = computed(() => !!p.value.coming_soon);
+
+  /**
+   * Stock, optionally for a specific variant.
+   *
+   * A function rather than a computed because the answer depends on whether a
+   * variant is in play, which only the caller knows: the card asks with the
+   * quick-shop selection while the panel is open, and without it when closed.
+   *
+   * Order matters — an explicit status wins over stock counts, and a variant
+   * that doesn't track inventory is always available.
+   */
+  function stockFor(variant = null) {
+    if (p.value.status === "Out of Stock") return true;
+    if (p.value.status === "In Stock") return false;
+
+    // A missing stock count (null) isn't 0 — not sold out.
+    const out = (n) => n !== null && n !== undefined && Number(n) <= 0;
+    if (variant) {
+      if (!variant.track_inventory) return false;
+      return out(variant.remaining_stock);
+    }
+
+    if (p.value.status === "On Demand") return false;
+    return out(p.value.remaining_stock);
+  }
+
+  /** Sale price for a variant, or null when it isn't on sale. */
+  function variantDiscountedPrice(variant) {
+    if (!variant) return null;
+    const sale = variant.sales?.[0];
+    if (!sale) return null;
+
+    return sale.sale_type === "Percentage"
+      ? +(variant.price * (1 - sale.discount_value / 100)).toFixed(2)
+      : +(variant.price - sale.discount_value).toFixed(2);
+  }
+
+  return {
+    selectedOptions,
+    selectedVariant,
+    selectedColor,
+    variantTypes,
+    availableColors,
+    colorType,
+    hasVariants,
+    isSelected,
+    getAvailableVariants,
+    applyCombinationLogic,
+    findMatchingVariant,
+    selectVariant,
+    isSelectionComplete,
+    missingVariantName,
+    reset,
+    isComingSoon,
+    stockFor,
+    variantDiscountedPrice,
+  };
+}

package/app/composables/useQuickShop.js

@@ -0,0 +1,115 @@
+import CartServices from "#osi/services/CartServices";
+
+/**
+ * Quick-shop: pick a variant and add to cart without leaving the grid.
+ *
+ * Desktop shows an overlay on the card, mobile a bottom sheet. They're the same
+ * state — Terazar tracked them as two independent booleans with two copies of
+ * the reset logic, and the mobile one wrote body overflow directly in three
+ * places (and cleared it unconditionally on unmount, unlocking the page under
+ * an open cart drawer).
+ *
+ * `mode` is 'DESKTOP' | 'MOBILE' | null, so `isOpen` is one derived value and
+ * closing resets once.
+ */
+/**
+ * closeOnAdd  false: the caller closes (after its own leave animation) —
+ *             QuickBuy does; ProductCard keeps the default.
+ */
+export function useQuickShop({ product, variants, onAdded, closeOnAdd = true } = {}) {
+  const p = computed(() => toValue(product) ?? {});
+
+  const mode = ref(null);
+  const isOpen = computed(() => mode.value !== null);
+  const adding = ref(false);
+  const errorMessage = ref("");
+
+  const { fetchCart } = useCart();
+  const { showApiError } = useApiErrorToast();
+
+  // Mobile only: the sheet covers the page, the desktop overlay doesn't.
+  useBodyScrollLock(() => mode.value === "MOBILE");
+
+  function open(next = "DESKTOP") {
+    mode.value = next;
+  }
+
+  function close() {
+    mode.value = null;
+    errorMessage.value = "";
+    variants?.reset();
+  }
+
+  let errorTimer = null;
+  function flashError(message) {
+    errorMessage.value = message;
+    clearTimeout(errorTimer);
+    errorTimer = setTimeout(() => {
+      errorMessage.value = "";
+    }, 2000);
+  }
+
+  /**
+   * Add a specific variant. Separate from the guard below so the product page
+   * can reuse it once its own selection is complete.
+   */
+  async function addVariant(variant, quantity) {
+    if (!variant?.id || adding.value) return false;
+    // An option with no price can't be bought.
+    if (!(Number(variant.price) > 0)) {
+      flashError("This option isn't available yet.");
+      return false;
+    }
+
+    adding.value = true;
+    try {
+      await CartServices.EditCart(
+        variant.id,
+        quantity ?? p.value.quantity_step ?? 1,
+        "add",
+        { product: p.value, variant }
+      );
+      await fetchCart();
+      onAdded?.(variant);
+      if (closeOnAdd) close();
+      return true;
+    } catch (error) {
+      // Stock and cart-limit errors come back as field errors, so they need the
+      // flattening — a bare error.message here would print "[object Object]".
+      flashError(showApiError(error, "Couldn't add that to your cart."));
+      return false;
+    } finally {
+      adding.value = false;
+    }
+  }
+
+  /** The panel's own button: refuse politely if the selection is incomplete. */
+  async function addSelected() {
+    if (!variants) return false;
+
+    if (!variants.isSelectionComplete.value) {
+      flashError(`Select a ${variants.missingVariantName.value}`);
+      return false;
+    }
+    if (!variants.selectedVariant.value) {
+      flashError("That combination isn't available.");
+      return false;
+    }
+
+    return addVariant(variants.selectedVariant.value);
+  }
+
+  onScopeDispose(() => clearTimeout(errorTimer));
+
+  return {
+    mode,
+    isOpen,
+    adding,
+    errorMessage,
+    open,
+    close,
+    addVariant,
+    addSelected,
+    flashError,
+  };
+}

package/app/composables/useRelatedProducts.js

@@ -0,0 +1,186 @@
+import CategoryServices from "#osi/services/CategoryServices";
+import ProductServices from "#osi/services/ProductServices";
+import { apiService } from "#osi/services/ApiServices";
+
+/**
+ * "You may also like".
+ *
+ * Client-side by design: it's below the fold and the least important thing on
+ * the page, so it stays out of the first render. If the backend resolved it
+ * (section.data.products), that wins and nothing is fetched.
+ *
+ * Where the products come from (SOURCE):
+ *   SAME_CATEGORY   the category the shopper browsed through, else the
+ *                   product's first category (the original behaviour)
+ *   CLASSIFICATION  one category or collection the merchant picked
+ *   LATEST          the newest products in the store
+ *   NONE            only the pinned ones
+ *
+ * Pinned products (PRODUCT blocks) always show, in the merchant's order,
+ * before whatever the source fills the rest of the row with. RANDOMIZE pulls a
+ * bigger pool and shuffles it, so the row differs between visits instead of
+ * showing the same four products forever.
+ */
+
+const shuffle = (rows) => {
+  const out = [...rows];
+  for (let i = out.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+};
+
+const rowsOf = (response) => (Array.isArray(response) ? response : response?.results ?? []);
+
+export function useRelatedProducts({
+  product,
+  limit = 4,
+  preloaded = null,
+  settings = null,
+  pinnedIds = null,
+} = {}) {
+  const route = useRoute();
+  const baseUrl = useState("base-url", () => "");
+
+  const p = computed(() => toValue(product) ?? null);
+  const max = computed(() => Number(toValue(limit)) || 4);
+  const s = computed(() => toValue(settings) ?? {});
+  const pins = computed(() => (toValue(pinnedIds) ?? []).filter(Boolean));
+
+  const source = computed(() => String(s.value.SOURCE || "SAME_CATEGORY").toUpperCase());
+  const randomize = computed(() => !!s.value.RANDOMIZE);
+  const pool = computed(() => Math.min(60, Math.max(max.value, Number(s.value.POOL_SIZE) || 24)));
+
+  const fetched = ref([]);
+  const pinned = ref([]);
+  const loading = ref(false);
+
+  const products = computed(() => {
+    const given = toValue(preloaded) ?? [];
+    // Preloaded data only matches the default source, and can't know about pins.
+    const usePreloaded = given.length && source.value === "SAME_CATEGORY" && !pins.value.length;
+    const rows = usePreloaded ? given : [...pinned.value, ...fetched.value];
+
+    const seen = new Set();
+    return rows
+      .filter((row) => {
+        if (!row?.id || row.id === p.value?.id || seen.has(row.id)) return false;
+        seen.add(row.id);
+        return true;
+      })
+      .slice(0, max.value);
+  });
+
+  /** The category the shopper came through, else the product's first. */
+  function categoryIdFor(current) {
+    const categories = current?.categories ?? [];
+    if (!categories.length) return null;
+    const slug = route.params.category;
+    const matched =
+      categories.find(
+        (entry) =>
+          entry.category?.slugified_name === slug ||
+          entry.category?.parent_category?.slugified_name === slug
+      ) ?? categories[0];
+    return matched?.category?.id ?? null;
+  }
+
+  /** The merchant's pick: { kind, id } or the encoded "CATEGORY:12". */
+  function pickedClassification() {
+    const raw = s.value.SOURCE_CLASSIFICATION;
+    if (!raw) return null;
+    if (typeof raw === "object") {
+      if (raw.id == null) return null;
+      const kind = String(raw.kind ?? raw.type ?? "CATEGORY").toUpperCase();
+      return { kind: kind.includes("COLLECTION") ? "COLLECTION" : "CATEGORY", id: raw.id };
+    }
+    const [kind, id] = String(raw).split(":");
+    if (!id) return null;
+    return {
+      kind: String(kind).toUpperCase().includes("COLLECTION") ? "COLLECTION" : "CATEGORY",
+      id: /^\d+$/.test(id) ? Number(id) : id,
+    };
+  }
+
+  function listProducts(params) {
+    const sp = new URLSearchParams(params);
+    return apiService(`${baseUrl.value}store/apis/products/?${sp.toString()}`, { method: "GET" });
+  }
+
+  let token = 0;
+
+  async function load() {
+    const current = p.value;
+    if (!current?.id || current.is_placeholder) return;
+
+    const mine = ++token;
+    loading.value = true;
+    const size = randomize.value ? pool.value : max.value + 1 + pins.value.length;
+
+    try {
+      // Pinned products, in the merchant's order.
+      if (pins.value.length) {
+        const response = await ProductServices.getProductsByIds(pins.value, baseUrl.value);
+        if (mine !== token) return;
+        const byId = new Map(rowsOf(response).map((row) => [String(row.id), row]));
+        pinned.value = pins.value.map((id) => byId.get(String(id))).filter(Boolean);
+      } else {
+        pinned.value = [];
+      }
+
+      if (source.value === "NONE" || pinned.value.length >= max.value) {
+        if (mine === token) fetched.value = [];
+        return;
+      }
+
+      let rows = [];
+      if (source.value === "CLASSIFICATION") {
+        const pick = pickedClassification();
+        if (pick) {
+          rows = rowsOf(
+            await listProducts({
+              [pick.kind === "COLLECTION" ? "collections" : "categories"]: pick.id,
+              page_size: size,
+            })
+          );
+        }
+      } else if (source.value === "LATEST") {
+        rows = rowsOf(await listProducts({ page_size: size, ordering: "-created_at" }));
+      } else {
+        const categoryId = categoryIdFor(current);
+        rows = categoryId
+          ? rowsOf(await CategoryServices.getCategoryProducts(categoryId, { pageSize: size }))
+          : [];
+      }
+
+      // Out-of-order responses: navigating A -> B -> C must not end up showing
+      // A's siblings because its request finished last.
+      if (mine !== token) return;
+      fetched.value = randomize.value ? shuffle(rows) : rows;
+    } catch (error) {
+      if (mine !== token) return;
+      console.warn("[useRelatedProducts] fetch failed:", error);
+      fetched.value = [];
+    } finally {
+      if (mine === token) loading.value = false;
+    }
+  }
+
+  if (import.meta.client) {
+    watch(
+      () =>
+        [
+          p.value?.id,
+          source.value,
+          pins.value.join(","),
+          JSON.stringify(s.value.SOURCE_CLASSIFICATION ?? null),
+          randomize.value,
+        ].join("|"),
+      load,
+      { immediate: true }
+    );
+  }
+
+  return { products, loading, reload: load };
+}

package/app/composables/useRenderContext.js

@@ -0,0 +1,45 @@
+/**
+ * The current route's render() payload, shared page -> sections.
+ *
+ * SectionRenderer passes each component only `section` and `index`. That's
+ * right for the twenty content types — they're self-contained. It isn't enough
+ * for a MAIN_* section: MainClassificationSection has to know *which* category
+ * it's showing, and that lives in the payload's `resource`, not in the section.
+ *
+ * Prop-drilling it through SectionRenderer would mean every section signature
+ * grows a field only four of them use, and it wouldn't work in the builder
+ * anyway — there the payload arrives over postMessage with no navigation, so
+ * there's no page render to drill from. Shared state covers both.
+ *
+ * useState, not a module ref: one Nuxt process serves every tenant.
+ *
+ * Pages set it; MAIN_* sections read it:
+ *
+ *   // pages/categories/[slug].vue
+ *   const { data } = await useAsyncData(key, () => render(path));
+ *   setRenderContext(data.value);
+ *
+ *   // theme/sections/MainClassificationSection.vue
+ *   const { resource } = useRenderContext();
+ */
+export function useRenderContext() {
+  const context = useState("render-context", () => null);
+
+  const template = computed(() => context.value?.template ?? null);
+
+  /**
+   * What this route resolved to, from the backend's resolve_path():
+   *   { type: 'CATEGORY'|'COLLECTION'|'PRODUCT'|'PAGE', id, name, slug, ... }
+   * null on INDEX, SEARCH, CART and ACCOUNT — those routes resolve no object.
+   */
+  const resource = computed(() => context.value?.resource ?? null);
+
+  const resourceType = computed(() => resource.value?.type ?? null);
+  const sections = computed(() => context.value?.sections ?? []);
+
+  function setRenderContext(payload) {
+    context.value = payload ?? null;
+  }
+
+  return { context, template, resource, resourceType, sections, setRenderContext };
+}

package/app/composables/useScopedCss.js

@@ -0,0 +1,106 @@
+/**
+ * Scope merchant-authored CSS to one element, and strip what shouldn't be there.
+ *
+ * Custom CSS is far safer than custom HTML or SVG — no script execution — but
+ * it isn't free:
+ *
+ *  - `</style>` breaks out of the tag and turns CSS into markup. Removed.
+ *  - `@import` fetches a third-party stylesheet on every page load: a
+ *    render-blocking request to a host the merchant doesn't control. Removed.
+ *  - `expression(` and `javascript:` are legacy IE script vectors. Removed.
+ *  - Unscoped, `.price { display: none }` would hit every price on the site.
+ *    Every top-level selector is prefixed with the caller's scope selector.
+ *
+ * The prefixer tracks brace depth rather than splitting on `}`, so conditional
+ * at-rules (`@media`, `@supports`, `@container`, `@layer`) scope the rules
+ * inside them. `@keyframes` is deliberately excluded — its children are `from`,
+ * `to` and percentages, and prefixing those produces `[data-x] from`, which is
+ * not a valid keyframe selector and silently kills the animation.
+ */
+const SCOPING_AT_RULES = /^@(media|supports|container|layer|scope)\b/i;
+
+export function scopeCss(css, scope) {
+  if (!css || typeof css !== "string" || !scope) return "";
+
+  const clean = css
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/<\/\s*style/gi, "")
+    .replace(/@import[^;]*;?/gi, "")
+    .replace(/expression\s*\(/gi, "(")
+    .replace(/javascript\s*:/gi, "");
+
+  const out = [];
+  let buffer = "";
+  let depth = 0;
+  // At each depth: does a rule opened here get its selectors scoped?
+  const scopeAt = [true];
+
+  for (const char of clean) {
+    if (char === "{") {
+      const head = buffer.trim();
+      buffer = "";
+
+      if (head.startsWith("@")) {
+        scopeAt[depth + 1] = SCOPING_AT_RULES.test(head);
+        out.push(`${head}{`);
+      } else if (scopeAt[depth]) {
+        scopeAt[depth + 1] = false;
+        out.push(`${prefixSelectors(head, scope)}{`);
+      } else {
+        scopeAt[depth + 1] = false;
+        out.push(`${head}{`);
+      }
+
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      out.push(buffer.trim(), "}");
+      buffer = "";
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    buffer += char;
+  }
+
+  return out.join("");
+}
+
+function prefixSelectors(selectorList, scope) {
+  return selectorList
+    .split(",")
+    .map((selector) => {
+      const trimmed = selector.trim();
+      if (!trimmed) return "";
+      // `&` lets a merchant target the scoped element itself: `& { border: … }`
+      if (trimmed.startsWith("&")) return trimmed.replace(/^&/, scope);
+      return `${scope} ${trimmed}`;
+    })
+    .filter(Boolean)
+    .join(",");
+}
+
+/**
+ * Scope a reactive CSS string and inject it once.
+ *
+ * `key` dedupes in useHead, so twenty cards sharing one stylesheet emit one
+ * <style> rather than twenty. Give each *section instance* its own key (the
+ * section id) but share one key across repeated components.
+ *
+ * @param {string|Ref|(() => string)} css
+ * @param {string|Ref|(() => string)} scope  e.g. '[data-osi-card]'
+ * @param {string} key
+ */
+export function useScopedCss(css, scope, key) {
+  const scoped = computed(() => scopeCss(toValue(css), toValue(scope)));
+
+  useHead({
+    style: computed(() =>
+      scoped.value ? [{ key, innerHTML: scoped.value }] : []
+    ),
+  });
+
+  return scoped;
+}

package/app/composables/useSearch.js

@@ -0,0 +1,35 @@
+import SearchServices from "#osi/services/SearchServices";
+
+export function useSearch() {
+  const route = useRoute();
+  const searchQuery = computed(() => route.query.q || "");
+  const products = useState("search-products", () => []);
+  const loading = useState("search-loading", () => false);
+
+  async function fetchResults() {
+    if (!searchQuery.value) return;
+    loading.value = true;
+    try {
+      const response = await SearchServices.search(searchQuery.value);
+      products.value = response.results || response || [];
+    } catch (error) {
+      console.error("[useSearch] Error fetching search results:", error);
+      products.value = [];
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  watch(() => route.query.q, (newQ) => {
+    if (route.path.startsWith("/search") && newQ) {
+      fetchResults();
+    }
+  });
+
+  return {
+    searchQuery,
+    products,
+    loading,
+    fetchResults,
+  };
+}