@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/useSectionData.js

@@ -0,0 +1,462 @@
+import ProductServices from "#osi/services/ProductServices";
+import HomeServices from "#osi/services/HomeServices";
+import { flattenCategories } from "#osi/theme/categoryTree";
+import { cachedRequest } from "#osi/utils/requestCache";
+
+/**
+ * Access the rows a section needs.
+ *
+ * The backend resolves SOURCE into `section.data` before the payload leaves the
+ * server. That's deliberate: a six-section homepage is one request instead of
+ * seven, and SOURCE=MANUAL would otherwise be one request per block.
+ *
+ * So this is mostly an accessor. The fetch path exists for two cases:
+ *
+ *   1. Builder preview — STATE arrives over postMessage with no `data`, because
+ *      the editor never resolves products or classifications.
+ *   2. A CLASSIFICATION_LIST set to MANUAL whose blocks arrived without their
+ *      category/collection expanded (see resolveManualClassifications). On a
+ *      backend that resolves MANUAL server-side this never fires; until then it
+ *      is what makes manual selection render at all.
+ *
+ * CHANGED in this revision:
+ *   * isCollectionSource()'s eight-key heuristic is gone. SOURCE is now an
+ *     explicit MANUAL | ALL_CATEGORIES | ALL_COLLECTIONS, so guessing from
+ *     TYPE / TARGET / SELECTION / MODE / RESOURCE_TYPE is no longer needed. Two
+ *     legacy keys are still read for sections created before that landed.
+ *   * MANUAL is handled: picks are read off the blocks, and any that the
+ *     backend didn't expand are matched against the catalog lists, which are
+ *     fetched once per page and shared by every section on it.
+ *   * The `current.data` early return is now conditional — a live section can
+ *     carry `data` and still have unresolved manual picks.
+ *
+ * @param {object|Ref|(() => object)} section pass a ref/computed/getter (e.g.
+ *   `() => props.section`) — a plain object is captured once and won't see the
+ *   new section pushed over postMessage on the next builder edit.
+ */
+export function useSectionData(section) {
+  const fetched = ref(null);
+  const loading = ref(false);
+
+  /**
+   * Catalog rows, shared by every section on the page.
+   *
+   * useState, not a module-level ref: one Nuxt process serves every tenant, and
+   * a module ref would leak one store's categories into another store's SSR
+   * response. Only ever written on the client, where that can't happen anyway —
+   * but the rule holds regardless of where the write happens today.
+   */
+  const catalog = useState("osi-classification-catalog", () => ({
+    CATEGORY: null,
+    COLLECTION: null,
+  }));
+
+  /**
+   * Placeholders enter here and nowhere else.
+   *
+   * This is the one point every list section reads its rows from, and the rows
+   * are still in raw API shape at this stage — so useClassificationItems,
+   * ProductCard, PARENTS_ONLY, LIMIT and HIDE_EMPTY all treat a placeholder
+   * exactly like a real row and need no branch of their own. Filling further
+   * downstream would mean teaching each of them separately.
+   *
+   * usePlaceholders returns the real rows untouched whenever there are any, and
+   * returns nothing at all outside the builder iframe.
+   */
+  const placeholders = usePlaceholders();
+
+  const rawProducts = computed(
+    () => fetched.value?.products ?? toValue(section)?.data?.products ?? []
+  );
+
+  /**
+   * Categories are flattened whichever way they arrived. The client fetch
+   * always flattened; the backend's resolved `data.classifications` didn't, so
+   * on a first load (server data) subcategories nested under their parents
+   * were invisible, and only appeared once an edit in the dashboard triggered
+   * the client fetch — "Top-level only" off seemed to need clicking twice.
+   */
+  const rawClassifications = computed(() =>
+    flattenCategories(fetched.value?.classifications ?? toValue(section)?.data?.classifications ?? [])
+  );
+
+  const products = computed(() => {
+    const current = toValue(section);
+    if (current?.type !== "PRODUCT_LIST") return rawProducts.value;
+    return placeholders.products(
+      rawProducts.value,
+      Number(current.settings?.LIMIT) || 8
+    );
+  });
+
+  const classifications = computed(() => {
+    const current = toValue(section);
+    if (current?.type !== "CLASSIFICATION_LIST") return rawClassifications.value;
+
+    return placeholders.classifications(
+      rawClassifications.value,
+      Number(current.settings?.LIMIT) || 6
+    );
+  });
+
+  /**
+   * Manually picked product ids.
+   *
+   * Reads the relation and the setting. Which one a block carries depends on
+   * how the editor persisted the pick, and a preview that only understands one
+   * of them renders an empty grid while the panel shows products selected.
+   */
+  function manualProductIds(current) {
+    const idOf = (value) => (value && typeof value === "object" ? value.id : value);
+    // The panel's multi-select first (pick order), then older sections'
+    // PRODUCT blocks. Header and card blocks carry no product.
+    const ids = (current?.settings?.PRODUCTS ?? []).map(idOf).filter(Boolean);
+    for (const b of current?.blocks ?? []) {
+      if (b.type !== "PRODUCT") continue;
+      const id = idOf(b.relations?.product ?? b.settings?.PRODUCT ?? null);
+      if (id && !ids.some((x) => String(x) === String(id))) ids.push(id);
+    }
+    return ids;
+  }
+
+  /**
+   * A MANUAL product list whose resolved rows don't hold every pick — the
+   * backend resolved picks from PRODUCT blocks only, or the payload predates
+   * the pick. Fetched on the client, like manual classifications.
+   */
+  function needsManualProducts(current) {
+    if (current?.type !== "PRODUCT_LIST") return false;
+    if (String(current.settings?.SOURCE ?? "").toUpperCase() !== "MANUAL") return false;
+    const ids = manualProductIds(current);
+    if (!ids.length) return false;
+    const have = new Set((current.data?.products ?? []).map((p) => String(p.id)));
+    return ids.some((id) => !have.has(String(id)));
+  }
+
+  // ---------------------------------------------------------------- classification
+
+  function kindOf(value, fallback = "CATEGORY") {
+    return String(value ?? fallback)
+      .toUpperCase()
+      .includes("COLLECTION")
+      ? "COLLECTION"
+      : "CATEGORY";
+  }
+
+  function classificationSource(current) {
+    const s = current?.settings ?? {};
+    // CLASSIFICATION_TYPE and TYPE: sections created before SOURCE gained its
+    // MANUAL member. Everything else the old heuristic sniffed was speculative.
+    const raw = String(s.SOURCE ?? s.CLASSIFICATION_TYPE ?? s.TYPE ?? "").toUpperCase();
+
+    // FEATURED has no SOURCE field — it always resolves one explicit pick.
+    if (String(s.LAYOUT ?? "").toUpperCase() === "FEATURED") return "MANUAL";
+    // Picked in the panel: resolve exactly those (either kind), not a list.
+    if ((s.CLASSIFICATIONS ?? []).length) return "MANUAL";
+
+    if (raw === "MANUAL") return "MANUAL";
+    if (raw.includes("COLLECTION")) return "ALL_COLLECTIONS";
+    if (raw.includes("CATEGOR")) return "ALL_CATEGORIES";
+
+    // No source at all + blocks that point at a category / collection is the
+    // old manual behaviour. The header and card are blocks too — they don't.
+    const pointsAtOne = (b) =>
+      !!(b?.settings?.CLASSIFICATION || b?.relations?.category || b?.relations?.collection);
+    if ((current?.blocks ?? []).some(pointsAtOne)) return "MANUAL";
+    return "ALL_CATEGORIES";
+  }
+
+  /**
+   * Everything a merchant picked by hand, in render order.
+   *
+   * Three places, because there are three ways to pick:
+   *   FEATURED_CLASSIFICATION  the single pick for the featured layout
+   *   CLASSIFICATIONS          the panel's multi-select (the normal path)
+   *   blocks                   legacy, and where per-item overrides live
+   *
+   * Blocks go last and win nothing on their own — they're merged, not replaced,
+   * so a section created before the CLASSIFICATIONS field existed still renders.
+   */
+  function manualPicks(current) {
+    const settings = current?.settings ?? {};
+    const picks = [];
+
+    const single = settings.FEATURED_CLASSIFICATION;
+    if (single && typeof single === "object" && single.id != null) {
+      picks.push({ kind: kindOf(single.kind ?? single.type), id: single.id, resolved: !!single.name });
+    }
+
+    for (const entry of settings.CLASSIFICATIONS ?? []) {
+      if (!entry) continue;
+      if (typeof entry === "object") {
+        if (entry.id == null) continue;
+        picks.push({ kind: kindOf(entry.kind ?? entry.type), id: entry.id, resolved: !!entry.name });
+      } else {
+        // "CATEGORY:12" — the encoded form, in case a value was persisted
+        // straight off the select before decode() ran.
+        const [kind, id] = String(entry).split(":");
+        if (id) picks.push({ kind: kindOf(kind), id: /^\d+$/.test(id) ? Number(id) : id, resolved: false });
+      }
+    }
+
+    return [...picks, ...blockPicks(current)];
+  }
+
+  /** The { kind, id } a merchant picked on a block, in block order. */
+  function blockPicks(current) {
+    return (current?.blocks ?? [])
+      .map((block) => {
+        const relations = block.relations ?? {};
+        if (relations.category) {
+          return { kind: "CATEGORY", id: relations.category.id, resolved: true };
+        }
+        if (relations.collection) {
+          return { kind: "COLLECTION", id: relations.collection.id, resolved: true };
+        }
+
+        const raw = block.settings?.CLASSIFICATION ?? relations.classification ?? null;
+        if (!raw) return null;
+
+        if (typeof raw === "object") {
+          // The picker may have stored a snapshot rather than a bare reference.
+          // A row that already carries a name needs no lookup.
+          return { kind: kindOf(raw.kind ?? raw.type), id: raw.id, resolved: !!raw.name };
+        }
+        return { kind: "CATEGORY", id: raw, resolved: false };
+      })
+      .filter((pick) => pick && pick.id != null);
+  }
+
+  /**
+   * Categories come back as a tree; a merchant can pick a child.
+   * Flattens defensively — the key name for children differs between endpoints.
+   */
+  function flatten(rows) {
+    return flattenCategories(rows);
+  }
+
+  async function loadCatalog(kind) {
+    if (catalog.value[kind]) return catalog.value[kind];
+
+    try {
+      const response =
+        kind === "COLLECTION"
+          ? await HomeServices.getCollections()
+          : await HomeServices.getCategories();
+
+      const rows = flatten(response?.results ?? response ?? []).map((row) => ({
+        ...row,
+        // Stamp the kind: nothing downstream can tell a category row from a
+        // collection row by shape, and the URL prefix depends on it.
+        kind: row.kind ?? kind,
+      }));
+
+      catalog.value = { ...catalog.value, [kind]: rows };
+      return rows;
+    } catch (e) {
+      console.warn(`[useSectionData] loadCatalog(${kind}) failed (e.g. 404), using empty fallback:`, e);
+      catalog.value = { ...catalog.value, [kind]: [] };
+      return [];
+    }
+  }
+
+  /**
+   * Fill in manual picks the backend didn't expand.
+   *
+   * One request per kind, cached for the page — a homepage with three manual
+   * category rows costs one call, not one per row and certainly not one per
+   * picked category.
+   */
+  async function resolveManualClassifications(current) {
+    const picks = manualPicks(current);
+    if (!picks.length) return [];
+
+    const kinds = [...new Set(picks.filter((p) => !p.resolved).map((p) => p.kind))];
+    if (!kinds.length) return [];
+
+    const loaded = await Promise.all(kinds.map((kind) => loadCatalog(kind)));
+    const index = new Map();
+    loaded.flat().forEach((row) => index.set(`${row.kind}:${row.id}`, row));
+
+    // Block order is the merchant's order. Keep it.
+    return picks.map((pick) => index.get(`${pick.kind}:${pick.id}`)).filter(Boolean);
+  }
+
+  /**
+   * True when a section that already has `data` still needs a client-side
+   * lookup — a MANUAL list whose blocks arrived as bare references.
+   */
+  function needsManualResolve(current) {
+    if (current?.type !== "CLASSIFICATION_LIST") return false;
+    if (classificationSource(current) !== "MANUAL") return false;
+
+    const picks = manualPicks(current);
+    if (!picks.length) return false;
+    if (picks.every((pick) => pick.resolved)) return false;
+
+    // Already matched by an earlier run.
+    const known = new Set(
+      (current.data?.classifications ?? []).map((row) => `${kindOf(row.kind ?? row.type)}:${row.id}`)
+    );
+    return picks.some((pick) => !known.has(`${pick.kind}:${pick.id}`));
+  }
+
+  // ---------------------------------------------------------------- resolve
+
+  /**
+   * Everything that changes what should be on screen, as one string.
+   *
+   * Watching the section object itself would refetch on every keystroke in the
+   * heading field; watching SOURCE alone would miss a category being added to a
+   * MANUAL list.
+   */
+  const signature = computed(() => {
+    const current = toValue(section);
+    if (!current) return "";
+
+    if (current.type === "PRODUCT_LIST") {
+      if (current.data && !needsManualProducts(current)) return "";
+      const s = current.settings ?? {};
+      return JSON.stringify([
+        "PRODUCT_LIST",
+        s.SOURCE ?? "LATEST",
+        s.LIMIT ?? 8,
+        manualProductIds(current),
+      ]);
+    }
+
+    if (current.type === "CLASSIFICATION_LIST") {
+      if (current.data && !needsManualResolve(current)) return "";
+      const s = current.settings ?? {};
+      return JSON.stringify([
+        "CLASSIFICATION_LIST",
+        classificationSource(current),
+        s.LIMIT ?? null,
+        manualPicks(current).map((pick) => `${pick.kind}:${pick.id}`),
+      ]);
+    }
+
+    return "";
+  });
+
+  // Guards against an out-of-order response overwriting a newer one: the
+  // merchant drags the LIMIT slider, six requests go out, and without this the
+  // slowest one wins.
+  let requestToken = 0;
+  let debounceTimer = null;
+
+  async function resolve() {
+    const current = toValue(section);
+    if (!current) return;
+    if (current.type !== "PRODUCT_LIST" && current.type !== "CLASSIFICATION_LIST") return;
+    if (current.data && !needsManualResolve(current) && !needsManualProducts(current)) return;
+
+    const settings = current.settings ?? {};
+    const token = ++requestToken;
+
+    loading.value = true;
+
+    try {
+      if (current.type === "PRODUCT_LIST") {
+        const limit = Number(settings.LIMIT) || 8;
+        let response;
+
+        if (settings.SOURCE === "MANUAL") {
+          const ids = manualProductIds(current);
+          // Not a no-op: clearing the last block has to empty the grid, not
+          // leave the previous fetch's products sitting there.
+          if (!ids.length) {
+            if (token === requestToken) fetched.value = { products: [] };
+            return;
+          }
+          // Cached per tab (utils/requestCache): coming back to a page reuses it.
+          response = await cachedRequest(`products:ids:${ids.join(",")}`, () => ProductServices.getProductsByIds(ids));
+        } else {
+          const params = { page_size: limit };
+          // Best-effort mapping of the other sources. An unknown value falls
+          // through to the default ordering rather than erroring — the preview's
+          // job is to show layout, and being approximately right beats blank.
+          if (settings.SOURCE === "ON_SALE") params.on_sale = true;
+          if (settings.SOURCE === "BEST_SELLERS") params.ordering = "-sales_count";
+          if (settings.SOURCE === "LATEST") params.ordering = "-created_at";
+          response = await cachedRequest(`products:list:${JSON.stringify(params)}`, () => ProductServices.listProducts(params));
+        }
+
+        if (token !== requestToken) return;
+
+        const rows = response?.results ?? response ?? [];
+        fetched.value = {
+          products: settings.SOURCE === "MANUAL" ? rows : rows.slice(0, limit),
+        };
+        return;
+      }
+
+      // ---- CLASSIFICATION_LIST ----
+      const source = classificationSource(current);
+
+      if (source === "MANUAL") {
+        const rows = await resolveManualClassifications(current);
+        if (token !== requestToken) return;
+
+        // Merge with whatever the backend did expand, so a half-resolved
+        // section doesn't lose the half that worked.
+        const existing = current.data?.classifications ?? [];
+        const seen = new Set();
+        fetched.value = {
+          classifications: [...existing, ...rows].filter((row) => {
+            const key = `${kindOf(row.kind ?? row.type)}:${row.id}`;
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+          }),
+        };
+        return;
+      }
+
+      const kind = source === "ALL_COLLECTIONS" ? "COLLECTION" : "CATEGORY";
+      const rows = await loadCatalog(kind);
+      if (token !== requestToken) return;
+
+      // LIMIT and PARENTS_ONLY are applied in useClassificationItems, so the
+      // preview and the live page filter identically. Don't slice here.
+      fetched.value = { classifications: rows };
+    } catch (e) {
+      // A preview that can't reach the catalog should still show layout with dummy data.
+      if (token === requestToken) {
+        console.warn("[useSectionData] resolve failed:", e);
+        if (current.type === "PRODUCT_LIST") {
+          fetched.value = { products: [] };
+        } else if (current.type === "CLASSIFICATION_LIST") {
+          fetched.value = { classifications: [] };
+        }
+      }
+    } finally {
+      if (token === requestToken) loading.value = false;
+    }
+  }
+
+  if (import.meta.client) {
+    watch(
+      signature,
+      (value) => {
+        if (!value) return;
+        clearTimeout(debounceTimer);
+        // The editor pushes STATE on every slider frame; without this a drag
+        // across the LIMIT range fires a request per pixel.
+        debounceTimer = setTimeout(resolve, 200);
+      },
+      { immediate: true }
+    );
+
+    onScopeDispose(() => clearTimeout(debounceTimer));
+  }
+
+  return {
+    products,
+    classifications,
+    loading,
+    /** Kept for the existing onMounted calls in the section components. Now a
+     *  no-op in practice — the watcher above has already run. */
+    resolveForPreview: resolve,
+  };
+}

package/app/composables/useSectionShell.js

@@ -0,0 +1,113 @@
+/**
+ * SectionWidth -> max-width.
+ *
+ * Exported because the footer takes the same enum (FOOTER_CONTAINER) but isn't
+ * a section, so it can't go through useSectionShell. It previously carried its
+ * own copy with different values, which made a NARROW footer a different width
+ * from a NARROW section directly above it.
+ */
+export const SECTION_WIDTHS = {
+  NARROW: "720px",
+  NORMAL: "var(--osi-page-width)",
+  WIDE: "1600px",
+  FULL: "100%",
+};
+
+const WIDTHS = SECTION_WIDTHS;
+
+/**
+ * The settings every section shares.
+ *
+ * COMMON_STYLE_SETTINGS is spliced into nearly every schema on the backend —
+ * COLOR_SCHEME, CONTAINER, HEADING_ALIGNMENT, PADDING_*, BORDER_RADIUS,
+ * CUSTOM_CLASS. Handling them once here means a new section type only has to
+ * implement what makes it different.
+ *
+ * @param {object|Ref|(() => object)} section the section passed to every
+ *   section component. Pass a ref/computed/getter (e.g. `() => props.section`),
+ *   not the raw object — a plain object is captured once at call time and
+ *   never sees the new section pushed over postMessage on the next builder edit.
+ */
+export function useSectionShell(section) {
+  const t = useT();
+  const s = computed(() => toValue(section)?.settings ?? {});
+  const resolved = useColorScheme(computed(() => s.value.COLOR_SCHEME));
+
+  /**
+   * Padding, one value per side, with optional phone values.
+   *
+   *   PADDING_TOP / PADDING_BOTTOM        desktop
+   *   PADDING_LEFT / PADDING_RIGHT        desktop; empty = PADDING_X
+   *   PADDING_X                           both sides (older sections)
+   *   PADDING_*_MOBILE                    phones; empty = the desktop value
+   *
+   * Written as variables plus `padding: var(--osi-sec-p*-now, <desktop>)`. The
+   * -now variables are switched by a media query in app.vue, which is the only
+   * way an inline style can have a phone value. A section root without the
+   * osi-section class still gets its desktop padding from the fallback.
+   *
+   * LEFT/RIGHT are physical on purpose: the merchant sees "left" and "right"
+   * in the panel and expects exactly that side, in RTL too.
+   */
+  const px = (value) => {
+    if (value === undefined || value === null || value === "") return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? `${n}px` : undefined;
+  };
+
+  const padding = computed(() => {
+    const v = s.value;
+    const x = px(v.PADDING_X) ?? "16px";
+    const top = px(v.PADDING_TOP) ?? "48px";
+    const bottom = px(v.PADDING_BOTTOM) ?? "48px";
+    const left = px(v.PADDING_LEFT) ?? x;
+    const right = px(v.PADDING_RIGHT) ?? x;
+    return {
+      "--osi-sec-pt": top,
+      "--osi-sec-pb": bottom,
+      "--osi-sec-pl": left,
+      "--osi-sec-pr": right,
+      "--osi-sec-pt-m": px(v.PADDING_TOP_MOBILE),
+      "--osi-sec-pb-m": px(v.PADDING_BOTTOM_MOBILE),
+      "--osi-sec-pl-m": px(v.PADDING_LEFT_MOBILE),
+      "--osi-sec-pr-m": px(v.PADDING_RIGHT_MOBILE),
+      paddingTop: `var(--osi-sec-pt-now, ${top})`,
+      paddingBottom: `var(--osi-sec-pb-now, ${bottom})`,
+      paddingLeft: `var(--osi-sec-pl-now, ${left})`,
+      paddingRight: `var(--osi-sec-pr-now, ${right})`,
+    };
+  });
+
+  const shellStyle = computed(() => {
+    const style = {
+      ...resolved.value.style,
+      // BACKGROUND_COLOR overrides the scheme's background for this section
+      // only; text and button colours still come from the scheme.
+      ...(s.value.BACKGROUND_COLOR ? { "--osi-bg": s.value.BACKGROUND_COLOR } : {}),
+      background: "var(--osi-bg)",
+      color: "var(--osi-text)",
+      ...padding.value,
+      borderRadius: `${s.value.BORDER_RADIUS ?? 0}px`,
+    };
+    for (const key of Object.keys(style)) if (style[key] === undefined) delete style[key];
+    return style;
+  });
+
+  const innerStyle = computed(() => ({
+    maxWidth: WIDTHS[s.value.CONTAINER ?? "NORMAL"] ?? WIDTHS.NORMAL,
+    marginInline: "auto",
+  }));
+
+  // 'LEFT' | 'CENTER' | 'RIGHT' -> a CSS text-align value. Uses start/end so it
+  // flips correctly in Arabic instead of pinning to the physical left.
+  const align = computed(() => {
+    const value = s.value.HEADING_ALIGNMENT ?? "LEFT";
+    if (value === "CENTER") return "center";
+    return value === "RIGHT" ? "end" : "start";
+  });
+
+  const customClass = computed(() => s.value.CUSTOM_CLASS ?? "");
+  const heading = computed(() => t(s.value.HEADING));
+
+  return { s, t, shellStyle, innerStyle, align, customClass, heading, scheme: resolved };
+}

package/app/composables/useSidebar.js

@@ -0,0 +1,69 @@
+/**
+ * Cart drawer and mobile menu visibility.
+ *
+ * Two changes from the version this replaces:
+ *
+ *  - `process.client` -> `import.meta.client`. `process` isn't defined in the
+ *    browser bundle under Nuxt 3's default, so the old guard threw on the
+ *    client and the body was never locked at all.
+ *  - Scroll locking goes through useBodyScrollLock() instead of writing
+ *    `document.body.style.overflow` directly. Opening the cart over an open
+ *    mobile menu and closing one used to unlock the page under the other.
+ *
+ * State is useState, so the drawer survives a page component swapping out
+ * during navigation — closing it is a deliberate act (see the route watcher in
+ * the layout), not a side effect of the page unmounting.
+ */
+export function useSidebar() {
+  const isCartSidebarVisible = useState("cart-sidebar-visible", () => false);
+  const isMobileSidebarVisible = useState("mobile-sidebar-visible", () => false);
+
+  const anyOpen = computed(
+    () => isCartSidebarVisible.value || isMobileSidebarVisible.value
+  );
+
+  // SIDEBAR_LOCK_SCROLL is honoured for the mobile menu only. The cart drawer
+  // always locks: it has its own scrolling line-item list, and a page moving
+  // underneath it makes that list impossible to use on touch. Reading the
+  // setting through useThemeGroup means an older theme without the key falls
+  // back to true, which is the behaviour this replaces.
+  const sidebarSettings = useThemeGroup("SIDEBAR");
+  const shouldLock = computed(
+    () =>
+      isCartSidebarVisible.value ||
+      (isMobileSidebarVisible.value && sidebarSettings.value.SIDEBAR_LOCK_SCROLL !== false)
+  );
+
+  // One lock for both drawers: the page needs to stay locked while either is
+  // open, and unlock exactly once when the last one closes.
+  useBodyScrollLock(shouldLock);
+
+  function toggleCartSidebar(visible) {
+    isCartSidebarVisible.value =
+      typeof visible === "boolean" ? visible : !isCartSidebarVisible.value;
+
+    // Never both at once — they'd stack and the backdrop would trap focus.
+    if (isCartSidebarVisible.value) isMobileSidebarVisible.value = false;
+  }
+
+  function toggleMobileSidebar(visible) {
+    isMobileSidebarVisible.value =
+      typeof visible === "boolean" ? visible : !isMobileSidebarVisible.value;
+
+    if (isMobileSidebarVisible.value) isCartSidebarVisible.value = false;
+  }
+
+  function closeAll() {
+    isCartSidebarVisible.value = false;
+    isMobileSidebarVisible.value = false;
+  }
+
+  return {
+    isCartSidebarVisible,
+    isMobileSidebarVisible,
+    anyOpen,
+    toggleCartSidebar,
+    toggleMobileSidebar,
+    closeAll,
+  };
+}