@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useNavStyle.js

@@ -0,0 +1,219 @@
+/**
+ * Navigation settings -> CSS custom properties.
+ *
+ * Same contract as useThemeTokens: nothing in a template reads
+ * `settings.HEADER_MENU_GAP` directly, it reads `var(--osi-nav-gap)`. That's
+ * what lets the schema gain a field and the storefront follow without a
+ * component learning its name.
+ *
+ * Both functions read through useThemeGroup(), which falls back to its own
+ * DEFAULTS for any key the merchant's saved theme predates — so a theme
+ * installed before these settings existed renders the new defaults instead of
+ * `undefined` leaking into a style attribute.
+ */
+
+const FONT_VAR = {
+  HEADING: "var(--osi-font-heading)",
+  BODY: "var(--osi-font-body)",
+};
+
+const WEIGHT = {
+  LIGHT: 300,
+  REGULAR: 400,
+  MEDIUM: 500,
+  SEMIBOLD: 600,
+  BOLD: 700,
+};
+
+/** Accepts 'MEDIUM' or a raw 500, because enums get refactored. */
+function weightOf(value, fallback = 400) {
+  if (typeof value === "number") return value;
+  return WEIGHT[value] ?? (Number(value) || fallback);
+}
+
+function fontOf(role) {
+  return FONT_VAR[role] ?? FONT_VAR.BODY;
+}
+
+function transformOf(value) {
+  return !value || value === "NONE" ? "none" : String(value).toLowerCase();
+}
+
+/** Letter spacing is stored in hundredths of an em, matching text_style(). */
+function trackingOf(value) {
+  return `${(Number(value) || 0) / 100}em`;
+}
+
+/** #rrggbb + 0-100 -> rgba(). Hex only; the COLOR field never emits anything else. */
+function withAlpha(hex, percent) {
+  const alpha = Math.max(0, Math.min(100, Number(percent) ?? 100)) / 100;
+  const match = /^#?([\da-f]{6})$/i.exec(String(hex ?? ""));
+  if (!match) return `rgba(0, 0, 0, ${alpha})`;
+  const int = parseInt(match[1], 16);
+  return `rgba(${(int >> 16) & 255}, ${(int >> 8) & 255}, ${int & 255}, ${alpha})`;
+}
+
+/**
+ * Header inline navigation.
+ *
+ * Returns the variables plus the modifier classes for hover and active style,
+ * so SiteHeader binds one object and one array rather than assembling either.
+ */
+export function useHeaderNavStyle() {
+  const settings = useThemeGroup("HEADER");
+
+  const style = computed(() => {
+    const s = settings.value;
+    return {
+      // The gap applies to the nav element only. The header grid's own
+      // `gap: 1rem` between logo / nav / icons is untouched — a merchant
+      // setting link spacing to 0 must not glue the logo to the menu.
+      "--osi-nav-gap": `${s.HEADER_MENU_GAP}px`,
+      "--osi-nav-gap-row": `${s.HEADER_MENU_GAP_MOBILE}px`,
+      "--osi-nav-font": fontOf(s.HEADER_MENU_FONT),
+      "--osi-nav-size": `${s.HEADER_MENU_SIZE}px`,
+      "--osi-nav-weight": weightOf(s.HEADER_MENU_WEIGHT),
+      "--osi-nav-color": s.HEADER_MENU_COLOR || "var(--osi-text)",
+      "--osi-nav-hover-color": s.HEADER_MENU_HOVER_COLOR || "var(--osi-nav-color)",
+      "--osi-nav-tracking": trackingOf(s.HEADER_MENU_LETTER_SPACING),
+      "--osi-nav-transform": transformOf(s.HEADER_MENU_TRANSFORM),
+      "--osi-nav-active-color": s.HEADER_MENU_ACTIVE_COLOR || "var(--osi-nav-color)",
+      "--osi-nav-active-bg": s.HEADER_MENU_ACTIVE_BACKGROUND || "transparent",
+      "--osi-nav-underline-w": `${s.HEADER_MENU_ACTIVE_UNDERLINE_WIDTH}px`,
+      "--osi-nav-underline-offset": `${s.HEADER_MENU_ACTIVE_UNDERLINE_OFFSET}px`,
+      // Submenu (dropdown / mega menu) colours: the header's colour scheme
+      // unless the Menu block sets its own.
+      "--osi-dd-bg": s.HEADER_MENU_DROPDOWN_BG || "var(--osi-bg, #fff)",
+      "--osi-dd-text": s.HEADER_MENU_DROPDOWN_COLOR || "var(--osi-text, #111)",
+      ...(s.HEADER_MENU_DROPDOWN_HOVER_BG ? { "--osi-dd-hover-bg": s.HEADER_MENU_DROPDOWN_HOVER_BG } : {}),
+      ...(s.HEADER_MENU_DROPDOWN_HOVER_COLOR ? { "--osi-dd-hover-color": s.HEADER_MENU_DROPDOWN_HOVER_COLOR } : {}),
+    };
+  });
+
+  const navClass = computed(() => [
+    `osi-nav--hover-${String(settings.value.HEADER_MENU_HOVER_EFFECT).toLowerCase()}`,
+    `osi-nav--active-${String(settings.value.HEADER_MENU_ACTIVE_STYLE).toLowerCase()}`,
+  ]);
+
+  const buttonStyle = computed(() => {
+    const s = settings.value;
+    return {
+      "--osi-menu-btn-size": `${s.HEADER_MENU_BUTTON_SIZE}px`,
+      "--osi-menu-btn-radius": `${s.HEADER_MENU_BUTTON_RADIUS}px`,
+      "--osi-menu-btn-bg": s.HEADER_MENU_BUTTON_BACKGROUND || "transparent",
+      "--osi-menu-btn-hover-bg":
+        s.HEADER_MENU_BUTTON_HOVER_BACKGROUND || "var(--osi-menu-btn-bg)",
+    };
+  });
+
+  return { style, navClass, buttonStyle };
+}
+
+/**
+ * Which nav item represents the page we're on.
+ *
+ * Prefix match, not equality: /categories/shoes/boots should light up the
+ * "Shoes" link. Guarded against '/' , which prefixes everything and would
+ * otherwise mark the Home link active on every page of the store.
+ */
+export function useNavActive() {
+  const route = useRoute();
+
+  function isActive(item) {
+    if (!item?.url || item.external) return false;
+    const path = route.path.replace(/\/+$/, "") || "/";
+    const url = item.url.replace(/\/+$/, "") || "/";
+    if (url === "/") return path === "/";
+    if (path === url) return true;
+    if (path.startsWith(`${url}/`)) return true;
+    return (item.children ?? []).some(isActive);
+  }
+
+  return { isActive };
+}
+
+/**
+ * Sidebar / mobile navigation.
+ *
+ * Scheme first, overrides on top — the rule the header already follows. An
+ * override left empty resolves to the scheme's variable rather than to a
+ * hardcoded colour, so editing one palette still restyles the drawer.
+ */
+export function useSidebarStyle() {
+  const settings = useThemeGroup("SIDEBAR");
+  const scheme = useColorScheme(computed(() => settings.value.SIDEBAR_COLOR_SCHEME));
+
+  const enabled = computed(() => settings.value.SIDEBAR_ENABLED !== false);
+  const position = computed(() => settings.value.SIDEBAR_POSITION || "START");
+  const animation = computed(() => settings.value.SIDEBAR_ANIMATION || "SLIDE");
+  const submenuMode = computed(() => settings.value.SIDEBAR_SUBMENU_MODE || "ACCORDION");
+
+  const duration = computed(() =>
+    animation.value === "NONE" ? 0 : Number(settings.value.SIDEBAR_ANIMATION_DURATION) || 0
+  );
+
+  console.log("animation",animation.value)
+  console.log("duration",duration.value);
+  const style = computed(() => {
+    const s = settings.value;
+    const base = { ...scheme.value.style };
+
+    if (s.SIDEBAR_BACKGROUND) base["--osi-bg"] = s.SIDEBAR_BACKGROUND;
+    if (s.SIDEBAR_TEXT_COLOR) base["--osi-text"] = s.SIDEBAR_TEXT_COLOR;
+    if (s.SIDEBAR_BORDER_COLOR) base["--osi-border"] = s.SIDEBAR_BORDER_COLOR;
+
+    return {
+      ...base,
+
+      "--osi-sb-width": `${s.SIDEBAR_WIDTH}px`,
+      "--osi-sb-width-mobile": `${s.SIDEBAR_WIDTH_MOBILE}vw`,
+      "--osi-sb-duration": `${duration.value}ms`,
+      "--osi-sb-radius": `${s.SIDEBAR_RADIUS}px`,
+      "--osi-sb-border-width": s.SIDEBAR_SHOW_BORDER ? `${s.SIDEBAR_BORDER_WIDTH}px` : "0px",
+
+      "--osi-sb-muted": s.SIDEBAR_MUTED_COLOR || "color-mix(in srgb, var(--osi-text) 60%, transparent)",
+      "--osi-sb-link": s.SIDEBAR_LINK_COLOR || "var(--osi-text)",
+      "--osi-sb-link-hover": s.SIDEBAR_LINK_HOVER_COLOR || "var(--osi-sb-link)",
+      "--osi-sb-active": s.SIDEBAR_ACTIVE_COLOR || "var(--osi-sb-link)",
+      "--osi-sb-active-bg": s.SIDEBAR_ACTIVE_BACKGROUND || "transparent",
+      "--osi-sb-icon": s.SIDEBAR_ICON_COLOR || "var(--osi-text)",
+
+      "--osi-sb-pad-top": `${s.SIDEBAR_PADDING_TOP}px`,
+      "--osi-sb-pad-bottom": `${s.SIDEBAR_PADDING_BOTTOM}px`,
+      "--osi-sb-pad-x": `${s.SIDEBAR_PADDING_X}px`,
+      "--osi-sb-link-gap": `${s.SIDEBAR_LINK_GAP}px`,
+      "--osi-sb-link-pad-y": `${s.SIDEBAR_LINK_PADDING_Y}px`,
+      "--osi-sb-group-gap": `${s.SIDEBAR_GROUP_GAP}px`,
+      "--osi-sb-indent": `${s.SIDEBAR_SUBMENU_INDENT}px`,
+
+      "--osi-sb-font": fontOf(s.SIDEBAR_LINK_FONT),
+      "--osi-sb-size": `${s.SIDEBAR_LINK_SIZE}px`,
+      "--osi-sb-size-mobile": `${s.SIDEBAR_LINK_SIZE_MOBILE}px`,
+      "--osi-sb-weight": weightOf(s.SIDEBAR_LINK_WEIGHT, 500),
+      "--osi-sb-line-height": (Number(s.SIDEBAR_LINK_LINE_HEIGHT) || 130) / 100,
+      "--osi-sb-tracking": trackingOf(s.SIDEBAR_LINK_LETTER_SPACING),
+      "--osi-sb-transform": transformOf(s.SIDEBAR_LINK_TRANSFORM),
+
+      "--osi-sb-sub-size": `${s.SIDEBAR_SUBMENU_SIZE}px`,
+      "--osi-sb-sub-weight": weightOf(s.SIDEBAR_SUBMENU_WEIGHT),
+      "--osi-sb-sub-color": s.SIDEBAR_SUBMENU_COLOR || "var(--osi-sb-link)",
+
+      "--osi-sb-arrow-size": `${s.SIDEBAR_ARROW_SIZE}px`,
+      "--osi-sb-header-height": `${s.SIDEBAR_HEADER_HEIGHT}px`,
+      "--osi-sb-logo-width": `${s.SIDEBAR_LOGO_WIDTH}px`,
+    };
+  });
+
+  const overlayStyle = computed(() => ({
+    background: withAlpha(
+      settings.value.SIDEBAR_OVERLAY_COLOR || "#000000",
+      settings.value.SIDEBAR_OVERLAY_OPACITY
+    ),
+    transitionDuration: `${duration.value}ms`,
+  }));
+
+  return {
+    settings, scheme, style, overlayStyle,
+    enabled, position, animation, duration, submenuMode,
+  };
+}

package/app/composables/usePlaceholders.js

@@ -0,0 +1,294 @@
+// app/composables/usePlaceholders.js
+//
+// Dummy products and classifications for a store whose catalog is still empty,
+// so the builder shows a laid-out page instead of blank rows.
+//
+// Scope is exactly those two. Menus are real rows seeded at store creation, so
+// nothing here touches them, and section media is left alone — a hero with no
+// image is the merchant's own empty state to fill.
+//
+// Three rules hold this together:
+//
+// 1. Rendered, never stored. Nothing here is a Product, Category or Menu row.
+//    It cannot reach checkout, search, the sitemap, an export, or a save — the
+//    builder posts its own state back, and this never enters that state.
+//
+// 2. Builder iframe only. The gate is usePreviewOverlay().active, which
+//    useBuilderPreview.start() sets after confirming window.parent !== window.
+//    A live storefront with an empty catalog shows a real empty state, and an
+//    unpublished theme opened directly in a browser does too.
+//
+// 3. Raw shapes, not normalized ones. A placeholder category is shaped like a
+//    row out of the categories endpoint, and a placeholder product like one out
+//    of ProductListSerializer. They enter at useSectionData, upstream of
+//    useClassificationItems and ProductCard, so every consumer downstream —
+//    PARENTS_ONLY, LIMIT, HIDE_EMPTY, the URL table, the card styling — runs
+//    over them unchanged. Injecting normalized items instead would mean each of
+//    those had to learn about placeholders.
+//
+// Copy comes from the theme payload (default_theme.json -> `placeholders`) when
+// it's there, so wording can improve server-side without a storefront deploy.
+// The lists below are the fallback for a theme that doesn't carry the key.
+
+import { computed } from "vue";
+
+/**
+ * When empty lists get filled.
+ *
+ *   PREVIEW  only when the storefront is framed by the dashboard
+ *   ALWAYS   any time a list comes back empty, including on the real URL
+ *
+ * PREVIEW is the point of this file: a shopper on a live store must never see
+ * invented merchandise. ALWAYS exists for debugging the placeholder rendering
+ * itself outside the builder — it is not a mode to ship.
+ */
+const WHEN_EMPTY = "PREVIEW";
+
+const FALLBACK = {
+  products: [
+    { title: "Product title 1", price: 2900, compare_at_price: null },
+    { title: "Product title 2", price: 8900, compare_at_price: 11000 },
+    { title: "Product title 3", price: 4500, compare_at_price: null },
+    { title: "Product title 4", price: 12000, compare_at_price: null },
+    { title: "Product title 5", price: 6500, compare_at_price: 8000 },
+    { title: "Product title 6", price: 3800, compare_at_price: null },
+    { title: "Product title 7", price: 15000, compare_at_price: null },
+    { title: "Product title 8", price: 9500, compare_at_price: null },
+  ],
+  classifications: [
+    { title: "Category title 1" },
+    { title: "Category title 2" },
+    { title: "Category title 3" },
+    { title: "Category title 4" },
+    { title: "Category title 5" },
+    { title: "Category title 6" },
+  ],
+  currency: "USD",
+  price_divisor: 100,
+};
+
+/**
+ * The art on a placeholder card.
+ *
+ * An inline SVG rather than a remote URL: the preview runs in an iframe, and a
+ * placeholder that depends on the network is a placeholder that sometimes
+ * renders as a broken-image icon. useMediaUrl passes `data:` straight through,
+ * so this drops into any `:src` that expects a media path.
+ *
+ * The hue shifts per index so a grid of six doesn't read as one tile repeated.
+ */
+export function placeholderImage({ w = 1200, h = 900, index = 0, tone = "light" } = {}) {
+  const hue = (index * 47 + 210) % 360;
+  const bg = tone === "dark" ? `hsl(${hue} 14% 20%)` : `hsl(${hue} 18% 93%)`;
+  const fg = tone === "dark" ? `hsl(${hue} 12% 32%)` : `hsl(${hue} 16% 80%)`;
+
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="${w}" height="${h}">` +
+    `<rect width="${w}" height="${h}" fill="${bg}"/>` +
+    `<g fill="${fg}">` +
+    `<circle cx="${w * 0.34}" cy="${h * 0.32}" r="${Math.min(w, h) * 0.072}"/>` +
+    `<path d="M${w * 0.08} ${h * 0.82} L${w * 0.38} ${h * 0.42} L${w * 0.56} ${h * 0.64} ` +
+    `L${w * 0.7} ${h * 0.51} L${w * 0.92} ${h * 0.82} Z"/>` +
+    `</g></svg>`;
+
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+
+export function usePlaceholders() {
+  // Read the bootstrap state directly rather than through useStorefront(),
+  // which would pull in the preview overlay merge for a value we only need one
+  // key out of.
+  const data = useState("storefront", () => null);
+
+  const { active: isPreview } = usePreviewOverlay();
+  const route = useRoute();
+
+  /**
+   * Is this page being rendered inside the dashboard?
+   *
+   * Three signals, because the obvious one alone isn't enough:
+   *
+   *   isPreview      usePreviewOverlay().active, set by useBuilderPreview
+   *                  .start(). Authoritative, but it only flips once the READY
+   *                  handshake has been set up in app.vue's onMounted — so it
+   *                  is false during SSR and for the first moments after
+   *                  hydration, and any section that resolved its rows before
+   *                  then saw an empty catalog with placeholders switched off.
+   *
+   *   ?osi_preview   a query param on the iframe src. The only signal that
+   *                  exists during SSR, so it's the one that makes the first
+   *                  paint correct instead of empty-then-filled. Optional —
+   *                  add it to the iframe URL in the dashboard when you want
+   *                  the flash gone.
+   *
+   *   window.parent  the same framing test start() makes, done directly so it
+   *                  doesn't wait on the handshake. Client-only by nature.
+   */
+  const framed = computed(() => {
+    if (isPreview.value === true) return true;
+    if (
+      route?.query?.osi_preview !== undefined ||
+      route?.query?.preview !== undefined ||
+      route?.query?.builder !== undefined ||
+      route?.path?.includes("__builder-preview")
+    ) {
+      return true;
+    }
+    if (import.meta.client) {
+      try {
+        return window.self !== window.top || window.parent !== window;
+      } catch {
+        return true;
+      }
+    }
+    return false;
+  });
+
+  const allowed = computed(() => WHEN_EMPTY === "ALWAYS" || framed.value);
+
+  /**
+   * Theme copy wins per key, and only when it actually has rows.
+   *
+   * A plain spread was wrong: a theme shipping `placeholders: { products: [] }`
+   * overrode the fallback with nothing, and the grid stayed empty with no error
+   * anywhere. An empty list in the payload means "nothing to say here", not
+   * "render nothing".
+   */
+  const source = computed(() => {
+    const custom = data.value?.theme?.placeholders ?? {};
+    return {
+      ...FALLBACK,
+      ...custom,
+      products: custom.products?.length ? custom.products : FALLBACK.products,
+      classifications: custom.classifications?.length
+        ? custom.classifications
+        : FALLBACK.classifications,
+    };
+  });
+
+  const divisor = computed(() => Number(source.value.price_divisor) || 100);
+
+  /** Shaped like a row from the categories endpoint. */
+  function asClassificationRow(raw, index) {
+    return {
+      is_placeholder: true,
+      type: "CATEGORY",
+      id: `ph-cat-${index}`,
+      name: raw.title,
+      // No slug: classificationUrl falls through to "/" rather than building a
+      // path that would 404 the moment someone opened the preview in a tab.
+      slugified_name: null,
+      url: null,
+      featured: false,
+      image: { path: placeholderImage({ w: 900, h: 700, index }) },
+      order: index + 1,
+      parent_category: null,
+      // A real number, not 0: HIDE_EMPTY would filter the whole set away.
+      products_count: raw.products_count ?? 12,
+    };
+  }
+
+  /** Shaped like a row from ProductListSerializer. */
+  function asProductRow(raw, index) {
+    const media = { id: null, path: placeholderImage({ w: 800, h: 1000, index }) };
+    const price = Number(raw.price ?? 0) / divisor.value;
+    const compare = raw.compare_at_price
+      ? Number(raw.compare_at_price) / divisor.value
+      : null;
+
+    return {
+      is_placeholder: true,
+      id: `ph-prod-${index}`,
+      name: raw.title,
+      page_title: raw.title,
+      slugified_name: null,
+      url: null,
+      description: "",
+      status: "In Stock",
+      stock: null,
+      remaining_stock: 25,
+      quantity_unit: null,
+      quantity_step: 1,
+      sku: "",
+      price_range: String(compare ?? price),
+      discounted_price_range: compare ? String(price) : null,
+      main_image: media,
+      gallery: [{ id: null, media, order: 0, product: `ph-prod-${index}` }],
+      categories: [],
+      collections: [],
+      resources: [],
+      sections: [],
+      brand: null,
+      vary_by: [],
+      wishlisted: false,
+      product_variants: [
+        {
+          id: `ph-var-${index}`,
+          price,
+          compare_at_price: compare,
+          discounted_price_range: compare ? String(price) : null,
+          cost: null,
+          values: [],
+          gallery: [],
+          remaining_stock: 25,
+          discount: null,
+          sku: "",
+          max_quantity_per_user: null,
+          // False on purpose: a placeholder must never render as sold out, and
+          // the card reads stock off the variant.
+          track_inventory: false,
+          coming_soon: false,
+          restock_threshold: null,
+          allow_restock_notifications: false,
+          unlisted_at: null,
+          archived_at: null,
+          resources: [],
+          sales: [],
+        },
+      ],
+      published_at: null,
+      unlisted_at: null,
+      archived_at: null,
+      page_views: null,
+    };
+  }
+
+  /**
+   * Repeats the sample set when a section asks for more than we ship, so
+   * LIMIT: 12 doesn't silently render 8 and make the grid look broken.
+   */
+  function take(list, count, map) {
+    if (!list?.length || count <= 0) {
+      if (import.meta.dev && count > 0) {
+        console.warn(
+          "[usePlaceholders] nothing to render: the sample list is empty. " +
+            "Check theme.placeholders in the bootstrap payload."
+        );
+      }
+      return [];
+    }
+    return Array.from({ length: count }, (_, i) => map(list[i % list.length], i));
+  }
+
+  /**
+   * @param {Array} real  what the backend resolved
+   * @param {number} count how many the section wants
+   * @returns the real rows when there are any, placeholders when there aren't
+   *          and we're in the editor, an empty array otherwise
+   */
+  const products = (real, count) =>
+    real?.length
+      ? real
+      : allowed.value
+      ? take(source.value.products, count, asProductRow)
+      : [];
+
+  const classifications = (real, count) =>
+    real?.length
+      ? real
+      : allowed.value
+      ? take(source.value.classifications, count, asClassificationRow)
+      : [];
+
+  return { products, classifications, allowed };
+}

package/app/composables/usePolicies.js

@@ -0,0 +1,26 @@
+import PoliciesServices from "#osi/services/PoliciesServices";
+
+export function usePolicies() {
+  const policies = useState("store-policies-data", () => ({}));
+  const loading = useState("store-policies-loading", () => false);
+
+  async function fetchPolicies() {
+    if (Object.keys(policies.value).length > 0) return policies.value;
+    loading.value = true;
+    try {
+      const data = await PoliciesServices.getPolicies();
+      policies.value = data || {};
+    } catch (error) {
+      console.error("[usePolicies] Error loading policies:", error);
+    } finally {
+      loading.value = false;
+    }
+    return policies.value;
+  }
+
+  return {
+    policies,
+    loading,
+    fetchPolicies,
+  };
+}

package/app/composables/useProductCardMedia.js

@@ -0,0 +1,135 @@
+/**
+ * Which images a card shows, and the carousel around them.
+ *
+ * The image set is derived, not stored. It changes when quick-shop opens, when
+ * a variant is picked, and when a colour swatch is clicked — Terazar's
+ * `currentImages` computed handled all three and it's lifted whole here,
+ * because getting it subtly wrong shows the wrong colourway to a shopper.
+ *
+ * The three branches, in the order they're checked:
+ *
+ *  1. quick-shop open -> the selected variant's gallery; failing that, the
+ *     galleries of every variant matching any current selection; failing that,
+ *     the product's own main image + gallery
+ *  2. a colour selected on the closed card -> that colour's variant gallery,
+ *     or the main image alone
+ *  3. nothing selected -> main image + gallery
+ *
+ * `__mediaKey` exists because the same media object can arrive through both a
+ * variant gallery and the product gallery; without deduping, the carousel shows
+ * the same photo twice and the dots lie about how many images there are.
+ */
+export function useProductCardMedia({
+  product,
+  quickShopOpen,
+  selectedVariant,
+  selectedOptions,
+  selectedColor,
+}) {
+  const p = computed(() => toValue(product) ?? {});
+  const open = computed(() => !!toValue(quickShopOpen));
+
+  const { mediaUrl, posterUrl, mediaUrlAs } = useMediaUrl();
+  const { isImage, isVideo } = useMediaTypes();
+
+  const isHovering = ref(false);
+
+  const key = (media) => media?.id || media?.path;
+  const wrap = (media) => ({ ...media, __mediaKey: key(media) });
+
+  function productOwnImages() {
+    const images = [];
+    if (p.value.main_image) images.push(wrap(p.value.main_image));
+    if (p.value.gallery?.length) {
+      images.push(...p.value.gallery.map((g) => wrap(g.media)));
+    }
+    return images;
+  }
+
+  const currentImages = computed(() => {
+    let images = [];
+    const variant = toValue(selectedVariant);
+    const options = toValue(selectedOptions) ?? {};
+    const colour = toValue(selectedColor);
+
+    if (open.value) {
+      if (variant?.gallery?.length) {
+        images = variant.gallery.map((g) => wrap(g.media));
+      } else {
+        const selectedValues = Object.values(options);
+
+        if (selectedValues.length) {
+          const matching =
+            p.value.product_variants?.filter((v) =>
+              v.values.some((val) => selectedValues.includes(val.id))
+            ) ?? [];
+
+          matching.forEach((v) => {
+            v.gallery?.forEach((g) => images.push(wrap(g.media)));
+          });
+        }
+
+        if (!images.length) images = productOwnImages();
+      }
+    } else if (colour) {
+      const variantForColour = p.value.product_variants?.find((v) =>
+        v.values.some((val) => val.id === colour.id)
+      );
+
+      images = variantForColour?.gallery?.length
+        ? variantForColour.gallery.map((g) => wrap(g.media))
+        : p.value.main_image
+          ? [wrap(p.value.main_image)]
+          : [];
+    } else {
+      images = productOwnImages();
+    }
+
+    const seen = new Set();
+    return images.filter((image) => {
+      if (!image.__mediaKey || seen.has(image.__mediaKey)) return false;
+      seen.add(image.__mediaKey);
+      return true;
+    });
+  });
+
+  /** The second image, revealed on hover when the theme asks for it. */
+  const hoverImage = computed(() => currentImages.value[1] ?? null);
+
+  const carousel = useCarousel({
+    items: () => currentImages.value,
+    loop: () => currentImages.value.length > 1,
+    minLoopSlides: 3,
+  });
+
+  // Advance to the first image only when a variant was actually picked — not
+  // every time currentImages recomputes. Opening quick-shop with nothing
+  // selected recomputes it too, and jumping the carousel then looks like a bug.
+  watch(
+    () => toValue(selectedVariant),
+    (variant) => {
+      nextTick(() => {
+        carousel.update();
+        if (variant && open.value && currentImages.value.length > 1) {
+          carousel.goTo(0);
+        }
+      });
+    }
+  );
+
+  const src = (media) => mediaUrl(media);
+  const poster = (media) => posterUrl(media, media?.poster);
+  const sourceAs = (media, extension) => mediaUrlAs(media, extension);
+
+  return {
+    currentImages,
+    hoverImage,
+    isHovering,
+    isImage,
+    isVideo,
+    src,
+    poster,
+    sourceAs,
+    ...carousel,
+  };
+}