@osimart/create-storefront 0.0.0-stage → 1.0.1

package/app/composables/useCarousel.js

@@ -0,0 +1,160 @@
+/**
+ * Shared Swiper wiring.
+ *
+ * The same instance handling was written five times in Terazar (announcement
+ * bar, category rail, recommended rail, product card, product gallery) with
+ * subtly different bug fixes in each. All of them are folded in here:
+ *
+ *  - shallowRef + markRaw. A plain ref() deep-proxies the Swiper instance,
+ *    which breaks its internal identity checks and leaves `animating` stuck
+ *    true, so the carousel silently stops responding after one swipe.
+ *  - update() on nextTick after init. Skeleton -> carousel swaps happen in the
+ *    same tick, so Swiper measures a 0-width container, reports isEnd === true,
+ *    and permanently disables the next arrow.
+ *  - Loop padding. Swiper's loop relocates real slides rather than cloning
+ *    them, so a list shorter than the visible count leaves nothing to move and
+ *    the edge goes blank mid-transition. Duplicating the list up to
+ *    `minLoopSlides` is what fixes it.
+ *  - `destroyed` guards. Swiper nulls its internals on destroy; anything
+ *    touching the instance from a watcher or timeout after unmount throws.
+ *
+ * Section components pass their settings in rather than hardcoding constants:
+ *   const { slides, onSwiper, goPrev, goNext, isBeginning, isEnd } =
+ *     useCarousel({ items: () => products.value, loop: () => s.LOOP });
+ */
+export function useCarousel(options = {}) {
+  const {
+    items = () => [],
+    loop = false,
+    minLoopSlides = 0,
+    breakpoints = null,
+  } = options;
+
+  const read = (value) => (typeof value === "function" ? value() : unref(value));
+
+  const swiper = shallowRef(null);
+  const activeIndex = ref(0);
+  const isBeginning = ref(true);
+  const isEnd = ref(false);
+
+  const source = computed(() => read(items) ?? []);
+  const loopEnabled = computed(() => !!read(loop) && source.value.length > 1);
+
+  /**
+   * The list actually rendered. Identical to `items` unless looping needs
+   * padding — see the loop note above.
+   */
+  const slides = computed(() => {
+    const list = source.value;
+    const minimum = read(minLoopSlides) ?? 0;
+    if (!list.length || !loopEnabled.value || list.length >= minimum) return list;
+
+    const copies = Math.max(1, Math.ceil(minimum / list.length));
+    return Array.from({ length: copies }, () => list).flat();
+  });
+
+  const alive = () => swiper.value && !swiper.value.destroyed;
+
+  /** Refresh the arrow disabled-state from the instance. */
+  function sync(instance) {
+    const s = instance || swiper.value;
+    if (!s || s.destroyed) return;
+    isBeginning.value = s.isBeginning;
+    isEnd.value = s.isEnd;
+    activeIndex.value = s.realIndex ?? s.activeIndex ?? 0;
+  }
+
+  /** Bind to Swiper's `@swiper` event. */
+  function onSwiper(instance) {
+    swiper.value = markRaw(instance);
+    sync(instance);
+
+    nextTick(() => {
+      if (instance.destroyed) return;
+      instance.update();
+      sync(instance);
+    });
+  }
+
+  /** Bind to `@slideChange`. */
+  function onSlideChange(instance) {
+    sync(instance);
+  }
+
+  function goPrev() {
+    if (alive()) swiper.value.slidePrev();
+  }
+
+  function goNext() {
+    if (alive()) swiper.value.slideNext();
+  }
+
+  /** Jump to a slide, honouring loop mode so thumbnails map to the right image. */
+  function goTo(index, speed = 300) {
+    if (!alive()) return;
+    const instance = swiper.value;
+    if (loopEnabled.value && typeof instance.slideToLoop === "function") {
+      instance.slideToLoop(index, speed);
+    } else {
+      instance.slideTo(index, speed);
+    }
+  }
+
+  function update() {
+    if (!alive()) return;
+    swiper.value.update();
+    sync();
+  }
+
+  /**
+   * Toggle arrows at runtime — the announcement bar enables navigation on
+   * mobile only, and Swiper needs init()/destroy() called on the module, not
+   * just the param flipped.
+   */
+  function setNavigationEnabled(enabled) {
+    if (!alive() || !import.meta.client) return;
+    const instance = swiper.value;
+    if (instance.params?.navigation) instance.params.navigation.enabled = enabled;
+
+    const navigation = instance.navigation;
+    if (!navigation) return;
+    if (enabled) {
+      navigation.init();
+      navigation.update();
+    } else {
+      navigation.destroy();
+    }
+  }
+
+  // The rendered list changing (filters applied, variant switched) invalidates
+  // Swiper's measurements; without this the last slides are unreachable.
+  watch(slides, () => nextTick(update));
+
+  if (import.meta.client) {
+    const onResize = () => update();
+    window.addEventListener("resize", onResize, { passive: true });
+    onScopeDispose(() => window.removeEventListener("resize", onResize));
+  }
+
+  onScopeDispose(() => {
+    swiper.value = null;
+  });
+
+  return {
+    swiper,
+    slides,
+    activeIndex,
+    isBeginning,
+    isEnd,
+    loopEnabled,
+    breakpoints,
+    onSwiper,
+    onSlideChange,
+    goPrev,
+    goNext,
+    goTo,
+    update,
+    sync,
+    setNavigationEnabled,
+  };
+}

package/app/composables/useCart.js

@@ -0,0 +1,109 @@
+import CartServices from "#osi/services/CartServices";
+import { clearCartToken } from "#osi/services/CartToken";
+
+export function useCart() {
+  // The raw server payload. Checkout needs it to build its order lines, so
+  // it's kept rather than discarded after mapping.
+  const cart = useState("cart-raw", () => null);
+  const cartItems = useState("cart-items", () => []);
+  const cartTotal = useState("cart-total", () => 0);
+  const loading = useState("cart-loading", () => false);
+  const updatingIds = useState("cart-updating-ids", () => []);
+
+  /**
+   * Single write path. Every mutation endpoint returns the whole cart, so
+   * there's never a reason to follow an edit with a second fetch.
+   */
+  function apply(response) {
+    if (!response) return response;
+    cart.value = response;
+    cartTotal.value = response.total_price || 0;
+    cartItems.value = Object.entries(response.cart || {}).map(([id, item]) => ({
+      id,
+      ...item,
+    }));
+    return response;
+  }
+
+  const isUpdating = (item) => {
+    const id = item?.id ?? item;
+    return updatingIds.value.includes(id);
+  };
+
+  function markUpdating(id, busy) {
+    updatingIds.value = busy
+      ? [...updatingIds.value, id]
+      : updatingIds.value.filter((existing) => existing !== id);
+  }
+
+  async function fetchCart() {
+    loading.value = true;
+    try {
+      return apply(await CartServices.fetchCart());
+    } catch (error) {
+      console.error("[useCart] Error fetching cart:", error);
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  /**
+   * Add or remove quantity on one line. Per-line busy state, not a single
+   * global flag — one slow line shouldn't freeze the controls on the others.
+   *
+   * Throws on failure so the caller can decide how to surface it (the drawer
+   * has useApiErrorToast, checkout has its own extractErrorMessage).
+   */
+  async function editItem(item, action, quantity) {
+    const id = item?.id ?? item;
+    if (!id || isUpdating(id)) return null;
+
+    const step = quantity ?? item?.quantity_step ?? 1;
+    markUpdating(id, true);
+    try {
+      return apply(await CartServices.EditCart(id, step, action));
+    } finally {
+      markUpdating(id, false);
+    }
+  }
+
+  const increaseItem = (item) => editItem(item, "add");
+  const decreaseItem = (item) => editItem(item, "remove");
+  // Remove is a decrease by the full quantity — the API has no delete verb.
+  const removeItem = (item) => editItem(item, "remove", item?.quantity);
+
+  /**
+   * Call only once the server has confirmed there's nothing left to pay. The
+   * guest cart lives server-side keyed by the token, so dropping the token is
+   * what actually detaches this browser from the converted cart; the next
+   * fetch gets a fresh one.
+   */
+  function clear() {
+    clearCartToken();
+    cart.value = null;
+    cartItems.value = [];
+    cartTotal.value = 0;
+    updatingIds.value = [];
+  }
+
+  const count = computed(() =>
+    cartItems.value.reduce((total, item) => total + (item.quantity || 0), 0),
+  );
+
+  return {
+    cart,
+    cartItems,
+    cartTotal,
+    loading,
+    count,
+    isUpdating,
+    fetchCart,
+    editItem,
+    increaseItem,
+    decreaseItem,
+    removeItem,
+    apply,
+    clear,
+  };
+}

package/app/composables/useCheckout.js

@@ -0,0 +1,76 @@
+import CheckoutServices from "#osi/services/CheckoutServices";
+import UtilsServices from "#osi/services/UtilsServices";
+import UserServices from "#osi/services/UserServices";
+import { authBus } from "#osi/services/AuthBus";
+import { useToast } from "vue-toastification";
+
+export function useCheckout() {
+  const router = useRouter();
+  const isLoading = useState("checkout-loading", () => false);
+  const cartData = useState("checkout-cart-data", () => null);
+  const countries = useState("checkout-countries", () => []);
+  const paymentMethods = useState("checkout-payment-methods", () => []);
+  const promoCodeData = useState("checkout-promo-code", () => null);
+
+  const isLoggedIn = computed(() => authBus.isLoggedIn);
+
+  async function loadCheckoutData() {
+    isLoading.value = true;
+    try {
+      const [cartRes, countriesRes, paymentsRes] = await Promise.allSettled([
+        CheckoutServices.fetchCart(),
+        UtilsServices.getCountries(),
+        UtilsServices.getAvailablePaymentMethods(),
+      ]);
+
+      if (cartRes.status === "fulfilled") cartData.value = cartRes.value;
+      if (countriesRes.status === "fulfilled") countries.value = countriesRes.value?.results || countriesRes.value || [];
+      if (paymentsRes.status === "fulfilled") paymentMethods.value = paymentsRes.value?.results || paymentsRes.value || [];
+    } catch (error) {
+      console.error("[useCheckout] Error loading checkout data:", error);
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  async function applyPromoCode(code) {
+    const toast = useToast();
+    try {
+      const res = await CheckoutServices.promoCode(code);
+      promoCodeData.value = res;
+      toast.success("Promo code applied successfully!");
+      return res;
+    } catch (error) {
+      toast.error(error?.data?.detail || "Invalid promo code");
+      throw error;
+    }
+  }
+
+  async function submitOrder(orderPayload) {
+    const toast = useToast();
+    isLoading.value = true;
+    try {
+      const response = await CheckoutServices.placeOrder(orderPayload);
+      toast.success("Order placed successfully!");
+      router.push(`/ordersummary?order_id=${response.id || response.order_id}`);
+      return response;
+    } catch (error) {
+      toast.error(error?.data?.detail || "Failed to place order");
+      throw error;
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  return {
+    isLoading,
+    cartData,
+    countries,
+    paymentMethods,
+    promoCodeData,
+    isLoggedIn,
+    loadCheckoutData,
+    applyPromoCode,
+    submitOrder,
+  };
+}

package/app/composables/useClassificationItems.js

@@ -0,0 +1,269 @@
+import { isOn, isTopLevel } from "#osi/theme/categoryTree";
+
+/**
+ * One item shape for every classification layout.
+ *
+ * The grid, the carousel and the featured block all render the same thing — a
+ * picture, a name, maybe a count, a link. What differs is arrangement. So the
+ * "which of the six places does this field live in" problem is solved once,
+ * here, and the three layout components receive a plain array.
+ *
+ * Two sources feed it:
+ *
+ *   SOURCE = MANUAL          the section's blocks, in the merchant's order
+ *   SOURCE = ALL_CATEGORIES  section.data.classifications, resolved by the
+ *   SOURCE = ALL_COLLECTIONS backend before the payload left the server
+ *
+ * For a manual block, the item's data can arrive three ways, in this order of
+ * preference:
+ *
+ *   1. block.relations.category / .collection — the op engine resolved the pick
+ *      into a real FK and the serializer expanded it. This is the normal path
+ *      on a live storefront, and it's why the storefront never has to fetch a
+ *      manually picked category by id.
+ *   2. block.data — same idea, if your serializer nests it there instead.
+ *   3. a row matched out of `classifications` by id — the fallback
+ *      useSectionData fills in when neither of the above is present (builder
+ *      preview, or a backend that doesn't resolve MANUAL yet).
+ *
+ * Block settings always win over the resolved object: TITLE, MEDIA and
+ * DESCRIPTION are deliberate merchant overrides.
+ *
+ * @param {object|Ref|(() => object)} section  pass a getter, not the object
+ * @param {Ref<Array>} classifications         from useSectionData
+ */
+export function useClassificationItems(section, classifications) {
+  const t = useT();
+  const { mediaUrl } = useMediaUrl();
+  const { classificationUrl, classificationKind } = useClassificationUrl();
+
+  const settings = computed(() => toValue(section)?.settings ?? {});
+
+  const isFeatured = computed(
+    () => String(settings.value.LAYOUT ?? "GRID").toUpperCase() === "FEATURED"
+  );
+
+  /**
+   * MANUAL is explicit now. The legacy fallback exists because sections created
+   * before SOURCE had a MANUAL member stored blocks with no source at all —
+   * ignoring them would blank a live storefront on deploy.
+   */
+  const isManual = computed(() => {
+    // Featured never lists — it always renders one explicitly chosen item.
+    if (isFeatured.value) return true;
+    // Picked in the panel: exactly those, in that order. Empty = all.
+    if ((settings.value.CLASSIFICATIONS ?? []).length) return true;
+
+    const source = String(settings.value.SOURCE ?? "").toUpperCase();
+    if (source === "MANUAL") return true;
+    if (source) return false;
+    // No source at all: an old section whose blocks were the picks. Only blocks
+    // that point at something count — the header and card are blocks too.
+    return (toValue(section)?.blocks ?? []).some((b) => sourceOf(b));
+  });
+
+  /** The kind an auto source produces, used when a row doesn't carry its own. */
+  const sourceKind = computed(() =>
+    String(settings.value.SOURCE ?? "").toUpperCase().includes("COLLECTION")
+      ? "COLLECTION"
+      : "CATEGORY"
+  );
+
+  /** Index the resolved rows so a manual block can find its object by id. */
+  const rowsByKey = computed(() => {
+    const map = new Map();
+    for (const row of classifications.value ?? []) {
+      if (row?.id == null) continue;
+      map.set(`${classificationKind(row, sourceKind.value)}:${row.id}`, row);
+    }
+    return map;
+  });
+
+  /** Decode one stored pick — { kind, id } or the encoded "CATEGORY:12". */
+  function decodePick(raw) {
+    if (!raw) return null;
+    if (typeof raw === "object") {
+      return raw.id == null ? null : { kind: classificationKind(raw), id: raw.id };
+    }
+    const [kind, id] = String(raw).split(":");
+    if (!id) return null;
+    return { kind: classificationKind({ kind }), id: /^\d+$/.test(id) ? Number(id) : id };
+  }
+
+  /** The resolved row behind a pick, whichever way it arrived. */
+  function rowFor(pick) {
+    return pick ? rowsByKey.value.get(`${pick.kind}:${pick.id}`) ?? null : null;
+  }
+
+  /** The resolved category/collection behind a block. */
+  function sourceOf(block) {
+    const relations = block?.relations ?? {};
+    if (relations.category) return { kind: "CATEGORY", data: relations.category };
+    if (relations.collection) return { kind: "COLLECTION", data: relations.collection };
+    if (block?.data?.classification) {
+      const data = block.data.classification;
+      return { kind: classificationKind(data), data };
+    }
+
+    const pick = decodePick(block?.settings?.CLASSIFICATION ?? relations.classification);
+    const row = rowFor(pick);
+    return row ? { kind: pick.kind, data: row } : null;
+  }
+
+   function normalize({ key, kind, data, overrides = {} }) {
+    if (!data) return null;
+
+    const title = t(overrides.TITLE) || data.name || data.title || "";
+    const description = t(overrides.DESCRIPTION) || data.description || "";
+    const image = mediaUrl(
+      overrides.MEDIA ?? data.main_image ?? data.image ?? data.media ?? null
+    );
+
+    return {
+      key,
+      id: data.id,
+      kind,
+      title,
+      description,
+      image,
+      // Category art is rarely decorative — it's the only label some cards have
+      // when the title is hidden — but repeating the title verbatim would make a
+      // screen reader announce it twice on cards that show both.
+      imageAlt: title,
+      count: data.products_count ?? data.product_count ?? null,
+      url: classificationUrl({ ...data, kind }, kind),
+      // Carried so a card can tell a dummy row from a real one. Nothing styles
+      // off it today; it exists so the distinction is available without
+      // sniffing the id.
+      isPlaceholder: data.is_placeholder === true,
+      raw: data,
+    };
+  }
+  const items = computed(() => {
+    const current = toValue(section);
+    if (!current) return [];
+
+    let list;
+
+    if (isFeatured.value) {
+      // FEATURED renders one item, and which one is an explicit setting — not
+      // "whatever happened to be first", which is what made the layout feel
+      // random when the source changed.
+      const pick =
+        decodePick(settings.value.FEATURED_CLASSIFICATION) ??
+        decodePick((settings.value.CLASSIFICATIONS ?? [])[0]) ??
+        null;
+
+      const data = rowFor(pick) ?? sourceOf((current.blocks ?? [])[0])?.data ?? null;
+
+      const item = normalize({
+        key: pick ? `${pick.kind}-${pick.id}` : "featured",
+        kind: pick?.kind ?? classificationKind(data, sourceKind.value),
+        data,
+        // A category is catalog structure and usually has no marketing copy.
+        // These overrides are where the promo's headline and body actually
+        // come from most of the time; the item's own values are the fallback.
+        overrides: {
+          TITLE: settings.value.FEATURED_TITLE,
+          DESCRIPTION: settings.value.FEATURED_DESCRIPTION,
+        },
+      });
+
+      if (item) return [item];
+
+      const fallbackRow = classifications.value?.[0];
+      if (fallbackRow) {
+        const phItem = normalize({
+          key: "featured-placeholder",
+          kind: classificationKind(fallbackRow, sourceKind.value),
+          data: fallbackRow,
+          overrides: {
+            TITLE: settings.value.FEATURED_TITLE,
+            DESCRIPTION: settings.value.FEATURED_DESCRIPTION,
+          },
+        });
+        if (phItem) return [phItem];
+      }
+
+      return [];
+    }
+
+    if (isManual.value) {
+      list = (settings.value.CLASSIFICATIONS ?? [])
+        .map((entry) => {
+          const pick = decodePick(entry);
+          const data = rowFor(pick);
+          return data
+            ? normalize({ key: `${pick.kind}-${pick.id}`, kind: pick.kind, data })
+            : null;
+        })
+        .filter(Boolean);
+
+      // Blocks are merged, not appended blindly: a block that points at an
+      // item already picked in the panel is an override of it, so it replaces
+      // that entry in place rather than rendering the same category twice.
+      for (const block of current.blocks ?? []) {
+        const resolved = sourceOf(block);
+        if (!resolved) continue;
+
+        const item = normalize({
+          key: block.key ?? `${resolved.kind}-${resolved.data?.id}`,
+          kind: resolved.kind,
+          data: resolved.data,
+          overrides: block.settings ?? {},
+        });
+        if (!item) continue;
+
+        const at = list.findIndex((row) => row.kind === item.kind && row.id === item.id);
+        if (at === -1) list.push(item);
+        else list[at] = item;
+      }
+
+      if (!list.length && classifications.value?.length) {
+        list = (classifications.value ?? [])
+          .map((row) =>
+            normalize({
+              key: `${classificationKind(row, sourceKind.value)}-${row?.id}`,
+              kind: classificationKind(row, sourceKind.value),
+              data: row,
+            })
+          )
+          .filter(Boolean);
+      }
+    } else {
+      list = (classifications.value ?? [])
+        .map((row) =>
+          normalize({
+            key: `${classificationKind(row, sourceKind.value)}-${row?.id}`,
+            kind: classificationKind(row, sourceKind.value),
+            data: row,
+          })
+        )
+        .filter(Boolean);
+    }
+
+    // These three also run on the backend where it resolves the source. Running
+    // them again is idempotent, and it's what keeps the builder preview — which
+    // fetches the raw lists client-side — showing the same thing the live page
+    // will show.
+    const isUsingPlaceholders = list.some((item) => item.isPlaceholder);
+    if (!isManual.value || isUsingPlaceholders) {
+      if (isOn(settings.value.PARENTS_ONLY, true) && sourceKind.value === "CATEGORY") {
+        list = list.filter((item) => isTopLevel(item.raw ?? {}));
+      }
+
+      const limit = Number(settings.value.LIMIT);
+      if (Number.isFinite(limit) && limit > 0) list = list.slice(0, limit);
+    }
+
+    if (settings.value.HIDE_EMPTY) {
+      // Only when the count is actually known — an API that doesn't return
+      // products_count would otherwise hide everything.
+      list = list.filter((item) => item.count == null || item.count > 0);
+    }
+
+    return list;
+  });
+
+  return { items, isManual, isFeatured, sourceKind };
+}