@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useClassificationPage.js

@@ -0,0 +1,545 @@
+import HomeServices from "#osi/services/HomeServices";
+import CategoryServices from "#osi/services/CategoryServices";
+import { apiService } from "#osi/services/ApiServices";
+import { childrenOf as treeChildren, isOn, parentIdOf } from "#osi/theme/categoryTree";
+
+/**
+ * Everything the category / collection page needs, for both kinds.
+ *
+ * Categories and collections render the same page — a heading, a way to move
+ * between siblings, a filterable product grid — and differ only in which query
+ * parameter narrows the products (`categories` vs `collections`) and where the
+ * navigation comes from (a tree vs a flat list). So there is one page
+ * (pages/categories/[slug].vue, aliased to /collections/:slug) and one section
+ * (MAIN_CLASSIFICATION), and this is the only place that knows the difference.
+ *
+ * `/collections/all` (or `/categories/all`) is the "All products" page: kind ALL,
+ * no narrowing parameter.
+ *
+ * The search page (MAIN_SEARCH, /search?q=…) is the same listing: kind SEARCH,
+ * narrowed by `search`. No item, no category navigation; nothing is fetched
+ * until something is searched.
+ */
+
+export const ALL_SLUG = "all";
+
+/* ------------------------------------------------------------------ catalog */
+
+function rowsOf(response) {
+  if (Array.isArray(response)) return response;
+  return response?.results ?? [];
+}
+
+function slugOf(row) {
+  return row?.slugified_name || row?.slug || row?.handle || null;
+}
+
+/**
+ * Walks the category tree once into lookups. `children` is what the categories
+ * endpoint nests; `parent` / `parent_category` are read too for flat payloads.
+ */
+function indexTree(roots) {
+  const bySlug = new Map();
+  const byId = new Map();
+  const parentOf = new Map();
+
+  const walk = (list, parent) => {
+    for (const row of list ?? []) {
+      if (!row) continue;
+      const slug = slugOf(row);
+      if (slug) bySlug.set(slug, row);
+      if (row.id != null) byId.set(row.id, row);
+      if (parent) parentOf.set(row.id, parent);
+      walk(treeChildren(row), row);
+    }
+  };
+  walk(roots, null);
+
+  // Flat payloads: resolve parent ids after the fact.
+  for (const row of byId.values()) {
+    if (parentOf.has(row.id)) continue;
+    const pid = parentIdOf(row);
+    if (pid != null && byId.has(pid)) parentOf.set(row.id, byId.get(pid));
+  }
+
+  const childrenOf = (row) => {
+    if (!row) return [];
+    const nested = treeChildren(row);
+    if (nested.length) return nested;
+    return [...byId.values()].filter((r) => parentOf.get(r.id)?.id === row.id);
+  };
+
+  const roots_ = (roots ?? []).filter((r) => !parentOf.has(r.id));
+
+  return { bySlug, byId, parentOf, childrenOf, roots: roots_ };
+}
+
+/**
+ * Categories + collections, fetched once per page load and shared (same
+ * useAsyncData keys everywhere, so the page and the section don't double up).
+ */
+export function useClassificationCatalog() {
+  const baseUrl = useState("base-url", () => "");
+
+  const categories = useAsyncData(
+    "osi-catalog:categories",
+    () => HomeServices.getCategories(baseUrl.value).then(rowsOf).catch(() => []),
+    { default: () => [] }
+  );
+  const collections = useAsyncData(
+    "osi-catalog:collections",
+    () => HomeServices.getCollections(baseUrl.value).then(rowsOf).catch(() => []),
+    { default: () => [] }
+  );
+
+  const tree = computed(() => indexTree(categories.data.value ?? []));
+  const collectionBySlug = computed(() => {
+    const map = new Map();
+    for (const row of collections.data.value ?? []) {
+      const slug = slugOf(row);
+      if (slug) map.set(slug, row);
+    }
+    return map;
+  });
+
+  function find(kind, slug) {
+    if (!slug) return null;
+    return kind === "COLLECTION"
+      ? collectionBySlug.value.get(slug) ?? null
+      : tree.value.bySlug.get(slug) ?? null;
+  }
+
+  const ready = Promise.all([categories, collections]);
+
+  return { categories, collections, tree, collectionBySlug, find, ready };
+}
+
+/** Depth-first: each parent followed by its children. */
+function flattenTree(roots, childrenOf) {
+  const out = [];
+  const walk = (list) => {
+    for (const row of list ?? []) {
+      out.push(row);
+      walk(childrenOf(row));
+    }
+  };
+  walk(roots);
+  return out;
+}
+
+/* -------------------------------------------------------------- the page */
+
+const SORTS = {
+  FEATURED: { label: "Featured", value: "" },
+  PRICE_ASC: { label: "Price, low to high", value: "min_price" },
+  PRICE_DESC: { label: "Price, high to low", value: "-max_price" },
+  NEWEST: { label: "Newest", value: "-created_at" },
+  NAME_ASC: { label: "Alphabetically, A-Z", value: "name" },
+  NAME_DESC: { label: "Alphabetically, Z-A", value: "-name" },
+};
+
+const asArray = (v) => (Array.isArray(v) ? v : v == null || v === "" ? [] : [v]);
+
+/**
+ * @param {() => object} section  the MAIN_CLASSIFICATION section (getter)
+ */
+export function useClassificationPage(section) {
+  const route = useRoute();
+  const router = useRouter();
+  const t = useT();
+  const { mediaUrl } = useMediaUrl();
+  const { classificationUrl } = useClassificationUrl();
+  const { resource } = useRenderContext();
+  const placeholders = usePlaceholders();
+  const baseUrl = useState("base-url", () => "");
+  const catalog = useClassificationCatalog();
+  const { isPreview } = useBuilderPreview();
+
+  const s = computed(() => toValue(section)?.settings ?? {});
+  const sectionKey = computed(() => toValue(section)?.key ?? "main");
+  const isSearch = computed(() => toValue(section)?.type === "MAIN_SEARCH");
+  /** What was searched (/search?q=…). */
+  const terms = computed(() => (isSearch.value ? String(route.query.q ?? "").trim() : ""));
+
+  /* ---------------------------------------------------------- current item */
+
+  const kind = computed(() => {
+    if (isSearch.value) return "SEARCH";
+    const slug = route.params.slug ?? resource.value?.slug;
+    if (slug === ALL_SLUG || resource.value?.type === "ALL") return "ALL";
+    // Dashboard preview: no route, no resource. The CLASSIFICATION template is
+    // previewed as /categories/all — every product, the real catalog.
+    if (!slug && !resource.value?.id) return "ALL";
+    const rt = String(resource.value?.type ?? "").toUpperCase();
+    if (rt === "COLLECTION") return "COLLECTION";
+    if (rt === "CATEGORY") return "CATEGORY";
+    return route.path.startsWith("/collections") ? "COLLECTION" : "CATEGORY";
+  });
+
+  const slug = computed(
+    () =>
+      route.params.slug ||
+      resource.value?.slug ||
+      resource.value?.slugified_name ||
+      null
+  );
+
+  /**
+   * The full row (image, description, children) for the current page. The
+   * render payload's `resource` is used when the catalog doesn't have the row,
+   * and in the builder — which has no route — the first category stands in so
+   * the merchant sees a real page while designing.
+   */
+  const current = computed(() => {
+    if (kind.value === "SEARCH") return { id: null, name: terms.value, slugified_name: null };
+    if (kind.value === "ALL") {
+      return { id: null, name: t(s.value.ALL_TITLE) || "All products", slugified_name: ALL_SLUG };
+    }
+    const row = catalog.find(kind.value, slug.value);
+    if (row) return row;
+    return resource.value ?? null;
+  });
+
+  const title = computed(() => current.value?.name || current.value?.title || "");
+  const description = computed(() => current.value?.description || "");
+  const image = computed(() =>
+    mediaUrl(
+      s.value.BANNER_IMAGE ??
+        current.value?.banner ??
+        current.value?.main_image ??
+        current.value?.image ??
+        null
+    )
+  );
+
+  const parent = computed(() =>
+    kind.value === "CATEGORY" && current.value?.id != null
+      ? catalog.tree.value.parentOf.get(current.value.id) ?? null
+      : null
+  );
+
+  const breadcrumbs = computed(() => {
+    const trail = [];
+    let node = parent.value;
+    while (node) {
+      trail.unshift({ title: node.name, url: classificationUrl({ ...node, kind: "CATEGORY" }) });
+      node = catalog.tree.value.parentOf.get(node.id) ?? null;
+    }
+    return [{ title: t(s.value.BREADCRUMB_HOME_LABEL) || "Home", url: "/" }, ...trail, { title: title.value, url: null }];
+  });
+
+  /* -------------------------------------------------------------- nav items */
+
+  /**
+   * Which prefix the current URL uses. "All products" stays under it, so a
+   * shopper browsing /categories/... gets /categories/all, not /collections/all.
+   */
+  const onCollectionsPath = computed(() => route.path.startsWith("/collections"));
+
+  /** The "All products" link for a nav listing rows of `rowKind`. */
+  function allUrlFor(rowKind) {
+    if (rowKind === "COLLECTION") return `/collections/${ALL_SLUG}`;
+    if (rowKind === "CATEGORY") return `/categories/${ALL_SLUG}`;
+    return `/${onCollectionsPath.value ? "collections" : "categories"}/${ALL_SLUG}`;
+  }
+
+  function toItem(row, rowKind) {
+    const rowSlug = slugOf(row);
+    return {
+      key: `${rowKind}-${row.id ?? rowSlug}`,
+      id: row.id,
+      title: row.name || row.title || "",
+      image: mediaUrl(row.main_image ?? row.image ?? row.media ?? null),
+      url: classificationUrl({ ...row, kind: rowKind }, rowKind),
+      count: row.products_count ?? row.product_count ?? null,
+      active: rowKind === kind.value && rowSlug != null && rowSlug === slug.value,
+      isAll: false,
+    };
+  }
+
+  /** Which rows the navigation lists, per NAV_SOURCE. */
+  const navSource = computed(() => {
+    const mode = String(s.value.NAV_SOURCE || "AUTO").toUpperCase();
+    const tree = catalog.tree.value;
+    const cur = current.value;
+    const children = kind.value === "CATEGORY" ? tree.childrenOf(cur) : [];
+    const siblings = parent.value ? tree.childrenOf(parent.value) : tree.roots;
+    const collections = catalog.collections.data.value ?? [];
+
+    switch (mode) {
+      case "NONE":
+        return { rows: [], rowKind: "CATEGORY", allTarget: null };
+      case "CHILDREN":
+        return { rows: children, rowKind: "CATEGORY", allTarget: "CURRENT" };
+      case "SIBLINGS":
+        return { rows: siblings, rowKind: "CATEGORY", allTarget: parent.value ? "PARENT" : "ALL" };
+      case "TOP_LEVEL":
+        return { rows: tree.roots, rowKind: "CATEGORY", allTarget: "ALL" };
+      case "ALL_CATEGORIES":
+        // Same switch as the home page's category list: top level only, or
+        // every category at every level (parents followed by their children).
+        return {
+          rows: isOn(s.value.NAV_PARENTS_ONLY, true) ? tree.roots : flattenTree(tree.roots, tree.childrenOf),
+          rowKind: "CATEGORY",
+          allTarget: "ALL",
+        };
+      case "COLLECTIONS":
+        return { rows: collections, rowKind: "COLLECTION", allTarget: "ALL" };
+      default: {
+        // AUTO: a collection page lists collections; a category page lists
+        // its children, or its siblings when it has none — so a leaf category
+        // still lets the shopper step sideways.
+        // /collections/all lists collections; /categories/all lists categories.
+        if (kind.value === "COLLECTION" || (kind.value === "ALL" && onCollectionsPath.value))
+          return { rows: collections, rowKind: "COLLECTION", allTarget: "ALL" };
+        if (kind.value === "CATEGORY" && children.length)
+          return { rows: children, rowKind: "CATEGORY", allTarget: "CURRENT" };
+        return { rows: siblings, rowKind: "CATEGORY", allTarget: parent.value ? "PARENT" : "ALL" };
+      }
+    }
+  });
+
+  const navItems = computed(() => {
+    if (kind.value === "SEARCH") return [];
+    const { rows, rowKind, allTarget } = navSource.value;
+    const mode = String(s.value.NAV_SOURCE || "AUTO").toUpperCase();
+    // Editor with an empty catalog: sample rows so the nav is designable.
+    const source = rows?.length || mode === "NONE" ? rows : placeholders.classifications([], 6);
+    let items = (source ?? []).filter(Boolean).map((row) => toItem(row, rowKind));
+
+    if (s.value.NAV_HIDE_EMPTY) items = items.filter((i) => i.count == null || i.count > 0);
+    const limit = Number(s.value.NAV_LIMIT);
+    if (limit > 0) items = items.slice(0, limit);
+
+    if (items.length && s.value.NAV_SHOW_ALL !== false && allTarget) {
+      let url = allUrlFor(rowKind);
+      let active = kind.value === "ALL";
+      let image = mediaUrl(s.value.NAV_ALL_IMAGE ?? null);
+      if (allTarget === "CURRENT") {
+        url = classificationUrl({ ...current.value, kind: kind.value }, kind.value);
+        active = true;
+        image = image || mediaUrl(current.value?.main_image ?? current.value?.image ?? null);
+      } else if (allTarget === "PARENT") {
+        url = classificationUrl({ ...parent.value, kind: "CATEGORY" }, "CATEGORY");
+        active = false;
+        image = image || mediaUrl(parent.value?.main_image ?? parent.value?.image ?? null);
+      }
+      // "All" is only highlighted when nothing more specific is.
+      if (items.some((i) => i.active)) active = false;
+      items = [
+        { key: "nav-all", id: null, title: t(s.value.NAV_ALL_LABEL) || "All", image, url, count: null, active, isAll: true },
+        ...items,
+      ];
+    }
+    return items;
+  });
+
+  /* ------------------------------------------------------------ sort/filter */
+
+  const sortOptions = computed(() => {
+    const keys = ["FEATURED", "PRICE_ASC", "PRICE_DESC"];
+    if (s.value.SORT_SHOW_NEWEST) keys.push("NEWEST");
+    if (s.value.SORT_SHOW_NAME) keys.push("NAME_ASC", "NAME_DESC");
+    return keys.map((k) => ({
+      key: k,
+      ...SORTS[k],
+      // Unsorted search results come back by relevance.
+      ...(k === "FEATURED" && kind.value === "SEARCH" ? { label: "Relevance" } : {}),
+    }));
+  });
+
+  const defaultOrdering = computed(() => {
+    const configured = SORTS[s.value.DEFAULT_SORT]?.value;
+    if (configured) return configured;
+    // "Featured" = the merchant's manual order inside the category.
+    return kind.value === "CATEGORY" ? "product_category_order" : "";
+  });
+
+  const ordering = computed(() => String(route.query.ordering ?? ""));
+  const selectedValues = computed(() => asArray(route.query.value).map(String));
+  const perPage = computed(() => Math.max(1, Number(s.value.PRODUCTS_PER_PAGE) || 12));
+  const pagination = computed(() => String(s.value.PAGINATION || "INFINITE").toUpperCase());
+  const page = computed(() =>
+    pagination.value === "PAGES" ? Math.max(1, Number(route.query.page) || 1) : 1
+  );
+
+  const filtersData = useAsyncData(
+    "osi-catalog:variant-types",
+    () => CategoryServices.getFilters(baseUrl.value).then(rowsOf).catch(() => []),
+    { default: () => [], server: false, lazy: true }
+  );
+
+  const filters = computed(() => {
+    const hidden = String(s.value.FILTER_HIDE ?? "")
+      .split(",")
+      .map((x) => x.trim().toLowerCase())
+      .filter(Boolean);
+    return (filtersData.data.value ?? [])
+      .filter((f) => f?.values?.length)
+      .filter((f) => !hidden.includes(String(f.name ?? "").toLowerCase()))
+      .map((f) => ({
+        id: f.id,
+        name: f.name,
+        isColor: String(f.display_type ?? "").toLowerCase() === "color",
+        values: f.values.map((v) => ({
+          id: String(v.id),
+          name: v.name,
+          color: v.hex_code || null,
+          image: v.image?.path ? mediaUrl(v.image) : null,
+        })),
+      }));
+  });
+
+  const activeFilters = computed(() => {
+    const byId = new Map();
+    for (const f of filters.value) for (const v of f.values) byId.set(v.id, { ...v, group: f.name });
+    return selectedValues.value.map((id) => byId.get(id) ?? { id, name: id, group: "" });
+  });
+
+  function pushQuery(patch) {
+    const next = { ...route.query, ...patch };
+    for (const k of Object.keys(next)) {
+      const v = next[k];
+      if (v == null || v === "" || (Array.isArray(v) && !v.length)) delete next[k];
+    }
+    return router.push({ path: route.path, query: next });
+  }
+
+  function setOrdering(value) {
+    return pushQuery({ ordering: value || undefined, page: undefined });
+  }
+  function setValues(ids) {
+    return pushQuery({ value: [...new Set(ids.map(String))], page: undefined });
+  }
+  function toggleValue(id) {
+    const set = new Set(selectedValues.value);
+    const key = String(id);
+    set.has(key) ? set.delete(key) : set.add(key);
+    return setValues([...set]);
+  }
+  function clearFilters() {
+    return pushQuery({ value: undefined, ordering: undefined, page: undefined });
+  }
+  function goToPage(n) {
+    return pushQuery({ page: n > 1 ? n : undefined });
+  }
+
+  /* --------------------------------------------------------------- products */
+
+  function fetchPage(n) {
+    const sp = new URLSearchParams();
+    const id = current.value?.id;
+    if (kind.value === "CATEGORY" && id != null) sp.append("categories", id);
+    if (kind.value === "COLLECTION" && id != null) sp.append("collections", id);
+    if (kind.value === "SEARCH" && terms.value) sp.set("search", terms.value);
+    sp.set("page", n);
+    sp.set("page_size", perPage.value);
+    const order = ordering.value || defaultOrdering.value;
+    if (order) sp.set("ordering", order);
+    for (const v of selectedValues.value) sp.append("variant_values", v);
+    return apiService(`${baseUrl.value}store/apis/products/?${sp.toString()}`, { method: "GET" });
+  }
+
+  const queryKey = computed(() =>
+    [kind.value, current.value?.id, terms.value, ordering.value, selectedValues.value.join("."), page.value, perPage.value].join("|")
+  );
+
+  const canFetch = computed(() => {
+    // The editor (no ?q=) shows the catalog, so the grid and card can be
+    // designed with real products.
+    if (kind.value === "SEARCH") return !!terms.value || isPreview.value;
+    return kind.value === "ALL" || (current.value?.id != null && !current.value?.is_placeholder);
+  });
+
+  const first = useAsyncData(
+    `plp:${route.path}:${sectionKey.value}`,
+    () =>
+      canFetch.value
+        ? fetchPage(page.value).catch(() => ({ results: [], count: 0, next: null }))
+        : Promise.resolve({ results: [], count: 0, next: null }),
+    { watch: [queryKey], default: () => ({ results: [], count: 0, next: null }) }
+  );
+
+  const extra = ref([]);
+  const nextPage = ref(2);
+  const loadingMore = ref(false);
+  const lastHadNext = ref(null);
+
+  watch(queryKey, () => {
+    extra.value = [];
+    nextPage.value = 2;
+    lastHadNext.value = null;
+  });
+
+  const total = computed(() => Number(first.data.value?.count) || 0);
+
+  const products = computed(() => {
+    const rows = [...(first.data.value?.results ?? []), ...extra.value];
+    if (rows.length || !canFetch.value) {
+      // Builder / placeholder category: show dummy cards so the grid is designable.
+      return rows.length ? rows : placeholders.products([], perPage.value);
+    }
+    return rows;
+  });
+
+  const hasMore = computed(() => {
+    if (pagination.value === "PAGES") return false;
+    if (lastHadNext.value !== null) return lastHadNext.value;
+    if (first.data.value?.next != null) return !!first.data.value.next;
+    return products.value.length < total.value;
+  });
+
+  const pageCount = computed(() => Math.max(1, Math.ceil(total.value / perPage.value)));
+
+  async function loadMore() {
+    if (loadingMore.value || !hasMore.value || !canFetch.value) return;
+    loadingMore.value = true;
+    try {
+      const res = await fetchPage(nextPage.value);
+      extra.value = [...extra.value, ...(res?.results ?? [])];
+      nextPage.value += 1;
+      lastHadNext.value = res?.next != null ? !!res.next : extra.value.length + (first.data.value?.results?.length ?? 0) < total.value;
+    } catch {
+      lastHadNext.value = false;
+    } finally {
+      loadingMore.value = false;
+    }
+  }
+
+  return {
+    s,
+    kind,
+    terms,
+    slug,
+    current,
+    title,
+    description,
+    image,
+    parent,
+    breadcrumbs,
+    navItems,
+    sortOptions,
+    ordering,
+    defaultOrdering,
+    selectedValues,
+    filters,
+    filtersPending: filtersData.pending,
+    activeFilters,
+    setOrdering,
+    setValues,
+    toggleValue,
+    clearFilters,
+    goToPage,
+    products,
+    total,
+    page,
+    pageCount,
+    perPage,
+    pagination,
+    pending: first.pending,
+    hasMore,
+    loadingMore,
+    loadMore,
+    catalog,
+  };
+}

package/app/composables/useClassificationUrl.js

@@ -0,0 +1,63 @@
+/**
+ * The href for a category or a collection.
+ *
+ * There were three copies of this before: useMenu().itemUrl(), a private
+ * classificationUrl() inside ClassificationListSection, and viewAllUrl() inside
+ * ProductListSection. Three copies of a route table is three chances to disagree
+ * with the backend's resolve_path(), and the failure is silent — a path the
+ * backend doesn't recognise falls through to NOT_FOUND, which renders a real
+ * page with the wrong content.
+ *
+ * The table, unchanged, from builder's resolve_path():
+ *
+ *   /categories/<slug>    CLASSIFICATION  (resource.type = CATEGORY)
+ *   /collections/<slug>   CLASSIFICATION  (resource.type = COLLECTION)
+ *
+ * Deciding which prefix an item takes is the whole job, and it can't be guessed
+ * from the shape of the object — categories and collections serialize almost
+ * identically. So `kind` is carried explicitly on every normalized item (see
+ * useClassificationItems), and this only falls back to sniffing when it's
+ * missing on a raw API row.
+ */
+export function useClassificationUrl() {
+  /**
+   * 'CATEGORY' | 'COLLECTION' for anything the API or the editor hands over.
+   *
+   * The editor stores a pick as { kind, id }; the storefront API returns rows
+   * that may carry `type`; a row read out of data.classifications may carry
+   * neither, in which case the caller already knew which endpoint it came from
+   * and should have stamped it. Defaults to CATEGORY because that's the older
+   * behaviour, and a wrong guess is at least a consistent wrong guess.
+   */
+  function classificationKind(item, fallback = "CATEGORY") {
+    const raw = String(
+      item?.kind ?? item?.type ?? item?.resource_type ?? fallback
+    ).toUpperCase();
+    return raw.includes("COLLECTION") ? "COLLECTION" : "CATEGORY";
+  }
+
+  function classificationSlug(item) {
+    return item?.slugified_name || item?.slug || item?.handle || null;
+  }
+
+  /**
+   * @param {object} item  a normalized item, an API row, or an editor pick
+   * @param {string} [fallbackKind]  used when the item carries no kind at all
+   */
+  function classificationUrl(item, fallbackKind = "CATEGORY") {
+    if (!item) return "/";
+
+    // A backend that pre-resolved the path wins — it knows about routing
+    // changes this file may not.
+    if (item.url) return item.url;
+
+    const slug = classificationSlug(item);
+    if (!slug) return "/";
+
+    return classificationKind(item, fallbackKind) === "COLLECTION"
+      ? `/collections/${slug}`
+      : `/categories/${slug}`;
+  }
+
+  return { classificationUrl, classificationKind, classificationSlug };
+}

package/app/composables/useColorScheme.js

@@ -0,0 +1,44 @@
+const FALLBACK = {
+  id: "SCHEME_1",
+  background: "#ffffff",
+  text: "#121212",
+  button: "#121212",
+  button_label: "#ffffff",
+  border: "#e5e5e5",
+};
+
+/**
+ * Resolve a section's COLOR_SCHEME id against the theme's palette list.
+ *
+ * A section stores "SCHEME_1", never a colour. That indirection is the whole
+ * reason a merchant can restyle every section at once by editing one palette.
+ *
+ * Falls back rather than throwing: a merchant can delete a scheme that sections
+ * still reference, and a missing palette must not blank the page.
+ *
+ * No preview handling here — useStorefront().theme already carries the
+ * builder's unsaved edits, so editing a palette repaints every section live.
+ *
+ * @param {string|Ref<string>} schemeId
+ */
+export function useColorScheme(schemeId) {
+  const { theme } = useStorefront();
+
+  return computed(() => {
+    const active = theme.value ?? {};
+    const id = unref(schemeId) || active.DEFAULT_SCHEME || "SCHEME_1";
+    const list = active.COLOR_SCHEMES ?? [];
+    const scheme = list.find((s) => s.id === id) ?? list[0] ?? FALLBACK;
+
+    return {
+      scheme,
+      style: {
+        "--osi-bg": scheme.background,
+        "--osi-text": scheme.text,
+        "--osi-btn-bg": scheme.button,
+        "--osi-btn-text": scheme.button_label,
+        "--osi-border": scheme.border,
+      },
+    };
+  });
+}