@usequeek/theme-kit 0.1.0

package/hooks/use-product-detail.ts

@@ -0,0 +1,69 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { getQueekClient } from '../sdk/queek-client';
+import { normalizeProduct } from '../utils/product-normalizer';
+import type { Product, LegacyProductLike } from '../types/product';
+
+interface UseProductDetailResult {
+  /** `listProduct` until the full fetch resolves, then the fetched detail. Null if `listProduct` is null. */
+  product: Product | null;
+  /** True only while a fetch the caller should show a loading state for is in flight. */
+  loadingDetail: boolean;
+}
+
+/**
+ * The product LIST/collection endpoint never returns `addons`, `options`, or
+ * `variants` — those only exist on the single-product "view" response
+ * (`ProductResource::buildBasePayload` vs `buildViewPayload`, queek_backend).
+ * Any quick-view/quick-add modal opened from a product card only has the
+ * list-shaped object, so it must re-fetch full detail before it can render
+ * or select an addon/option — rendering `listProduct.addons` directly always
+ * shows nothing, regardless of CSS or wiring.
+ *
+ * `isOpen` gates the fetch so a modal closed and reopened on a different
+ * product re-fetches instead of showing stale detail.
+ */
+export function useProductDetail(
+  listProduct: Product | null,
+  isOpen: boolean,
+  vendorSlug?: string | null,
+): UseProductDetailResult {
+  const [fullProduct, setFullProduct] = useState<Product | null>(null);
+  const [loadingDetail, setLoadingDetail] = useState(false);
+
+  useEffect(() => {
+    if (!isOpen || !listProduct) {
+      setFullProduct(null);
+      setLoadingDetail(false);
+      return;
+    }
+
+    let cancelled = false;
+    const needsDetail = listProduct.variants_count > 0 || listProduct.addons.length > 0;
+    if (needsDetail) {
+      setLoadingDetail(true);
+    }
+
+    const client = getQueekClient(vendorSlug ?? undefined);
+    client
+      .get<{ data?: LegacyProductLike } | LegacyProductLike>(`/client/store/products/${listProduct.slug}`)
+      .then((res) => {
+        if (cancelled) return;
+        const raw = (res as { data?: LegacyProductLike })?.data ?? res;
+        if (raw && typeof raw === 'object' && 'id' in raw) {
+          setFullProduct(normalizeProduct(raw as LegacyProductLike));
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (!cancelled) setLoadingDetail(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [isOpen, listProduct, vendorSlug]);
+
+  return { product: fullProduct ?? listProduct, loadingDetail };
+}

package/hooks/use-product-questions.ts

@@ -0,0 +1,77 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import { createBrowserClient } from '../sdk/client';
+import type { ProductQaBlockData, ProductQuestionItem } from '../types/block';
+
+interface ProductQuestionsResponse {
+  status: string;
+  data: {
+    product: { id: string; slug: string; title: string };
+    questions: ProductQuestionItem[];
+    pagination: { current_page: number; per_page: number; has_more: boolean };
+  };
+}
+
+export function useProductQuestions(options: ProductQaBlockData): {
+  questions: ProductQuestionItem[];
+  isLoading: boolean;
+} {
+  const { vendor, previewData } = useStorefront();
+  const [questions, setQuestions] = useState<ProductQuestionItem[]>(options._preview?.questions ?? []);
+  const [isLoading, setIsLoading] = useState(!options._preview && !previewData);
+
+  const { product_slug, limit } = options;
+
+  useEffect(() => {
+    // Preview mode: use inline preview data if provided, otherwise empty.
+    if (previewData) {
+      if (options._preview) {
+        setQuestions(options._preview.questions ?? []);
+      }
+      setIsLoading(false);
+      return;
+    }
+
+    if (!product_slug) {
+      setQuestions([]);
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const client = createBrowserClient(vendor.slug ?? undefined);
+
+    const query: Record<string, string | number> = {};
+    if (limit) query.limit = limit;
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+      try {
+        const response = await client.get<ProductQuestionsResponse>(
+          `/products/${product_slug}/questions`,
+          query,
+        );
+        if (!cancelled) {
+          setQuestions(response.data.questions ?? []);
+        }
+      } catch {
+        if (!cancelled) {
+          setQuestions([]);
+        }
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [vendor.slug, previewData, product_slug, limit]);
+
+  return { questions, isLoading };
+}

package/hooks/use-product-sections.ts

@@ -0,0 +1,165 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import type { Product, ApiResponse, LegacyProductLike } from '../types/product';
+import { createBrowserClient } from '../sdk/client';
+import { getActivePlatform } from '../sdk/platform';
+import { normalizeProduct } from '../utils/product-normalizer';
+
+export interface ProductSection {
+  category_id: string;
+  title: string;
+  products: Product[];
+  view_more?: boolean;
+}
+
+/** A collection referenced by a smart "rollup" tab's own collection_id rule
+ * (see MenuGroupCollections) — its own product ids, ready to list with no
+ * extra request. */
+export interface MenuGroupItem {
+  id: string;
+  name: string;
+  product_ids: string[];
+}
+
+/** A QR menu tab (Food/Drinks-style) — the vendor's own collection, resolved
+ * server-side into its product ids directly. Two shapes: 'products' (a
+ * manual collection, or a smart collection whose rule doesn't reference
+ * other collections) lists its own products immediately; 'collections' (a
+ * smart collection whose rule DOES reference other collections — a browsing
+ * umbrella, not a product filter) offers those referenced collections as
+ * tiles first. Every id here is already present in this same response's
+ * flat product pool, so resolving a tap is a pure client-side lookup — see
+ * VendorProductController::resolveQrTabGroups (queek_backend). */
+export type MenuGroup =
+  | { id: string; name: string; type: 'products'; product_ids: string[] }
+  | { id: string; name: string; type: 'collections'; items: MenuGroupItem[] };
+
+interface RawSection {
+  title: string;
+  category_id?: string;
+  data: LegacyProductLike[];
+  view_more?: boolean;
+}
+
+interface SectionsResult {
+  sections: ProductSection[];
+  groups: MenuGroup[];
+}
+
+const EMPTY_RESULT: SectionsResult = { sections: [], groups: [] };
+
+const sectionsCache = new Map<string, SectionsResult>();
+const inflightSections = new Map<string, Promise<SectionsResult>>();
+
+export function useProductSections(): {
+  sections: ProductSection[];
+  groups: MenuGroup[];
+  isLoading: boolean;
+} {
+  const { previewData, vendor } = useStorefront();
+  // Cache per vendor AND platform — the grouped catalogue can differ between
+  // storefront and instore_qr (the /qr page).
+  const cacheKey = `${vendor.slug ?? ''}::${getActivePlatform()}`;
+  const [result, setResult] = useState<SectionsResult>(() => sectionsCache.get(cacheKey) ?? EMPTY_RESULT);
+  const [isLoading, setIsLoading] = useState(!sectionsCache.has(cacheKey));
+
+  useEffect(() => {
+    let cancelled = false;
+    const previewProducts = previewData?.products;
+
+    if (Array.isArray(previewProducts)) {
+      const grouped = new Map<string, ProductSection>();
+
+      previewProducts.forEach((product) => {
+        const primaryCategory = product.categories[0];
+        const key = primaryCategory?.slug ?? '_all';
+        const title = primaryCategory?.name ?? 'All Products';
+
+        if (!grouped.has(key)) {
+          grouped.set(key, {
+            category_id: primaryCategory?.id ?? key,
+            title,
+            products: [],
+          });
+        }
+
+        grouped.get(key)?.products.push(product);
+      });
+
+      if (!cancelled) {
+        setResult({ sections: Array.from(grouped.values()), groups: [] });
+        setIsLoading(false);
+      }
+      return;
+    }
+
+    if (sectionsCache.has(cacheKey)) {
+      setResult(sectionsCache.get(cacheKey) ?? EMPTY_RESULT);
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+
+    // Deduplicate: reuse in-flight promise if another mount already started fetching.
+    let promise = inflightSections.get(cacheKey);
+    if (!promise) {
+      const client = createBrowserClient(vendor.slug ?? undefined);
+      promise = client
+        .get<ApiResponse<unknown>>('/products')
+        .then((response) => {
+          const data = response.data;
+          // instore_qr only — backend attaches this under meta.groups, never
+          // inside `data` (see resolveQrTabGroups): sectioned/menu-mode `data`
+          // is shared with the mobile app's response shape, so groups had to
+          // land somewhere additive instead.
+          const rawGroups = (response.meta as { groups?: MenuGroup[] } | undefined)?.groups;
+          const groups = Array.isArray(rawGroups) ? rawGroups : [];
+
+          if (!Array.isArray(data)) return { sections: [], groups };
+
+          const first = data[0] as Record<string, unknown> | undefined;
+          const isGrouped = first && Array.isArray(first.data) && typeof first.title === 'string';
+
+          if (isGrouped) {
+            const sections = (data as RawSection[]).map((group, idx) => ({
+              category_id: group.category_id ?? `section-${idx}`,
+              title: group.title,
+              products: group.data.map((p) => normalizeProduct(p)),
+              view_more: group.view_more ?? false,
+            }));
+            return { sections, groups };
+          }
+
+          const products = (data as LegacyProductLike[]).map((p) => normalizeProduct(p));
+          return {
+            sections: [{
+              category_id: '_all',
+              title: 'All Products',
+              products,
+            }],
+            groups: [],
+          };
+        })
+        .catch(() => EMPTY_RESULT)
+        .finally(() => {
+          inflightSections.delete(cacheKey);
+        });
+      inflightSections.set(cacheKey, promise);
+    }
+
+    promise.then((result) => {
+      sectionsCache.set(cacheKey, result);
+      if (!cancelled) {
+        setResult(result);
+        setIsLoading(false);
+      }
+    });
+
+    return () => { cancelled = true; };
+  }, [previewData?.products, vendor.slug, cacheKey]);
+
+  return { sections: result.sections, groups: result.groups, isLoading };
+}

package/hooks/use-products.ts

@@ -0,0 +1,216 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import type { Product } from '../types/product';
+import type { ApiResponse, LegacyProductLike, ProductListMeta } from '../types/product';
+import { createBrowserClient } from '../sdk/client';
+import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+
+type ProductQuery = {
+  collection?: string | null;
+  ids?: string[];
+  limit?: number;
+  sort?: 'latest' | 'popular' | 'price_low' | 'price_high';
+  hasVideo?: boolean;
+};
+
+function resolvePreviewProducts(products: Product[], options: ProductQuery): Product[] {
+  let next = [...products];
+
+  if (options.collection) {
+    next = next.filter((product) => product.categories.some((category) => category.slug === options.collection));
+  }
+
+  if (options.ids && options.ids.length > 0) {
+    next = next.filter((product) => options.ids?.includes(product.id));
+  }
+
+  if (options.hasVideo) {
+    next = next.filter((product) => Boolean(product.media.video_url));
+  }
+
+  if (options.sort === 'popular') {
+    next.sort((left, right) => right.review_summary.rating - left.review_summary.rating);
+  } else if (options.sort === 'price_low') {
+    next.sort((left, right) => left.pricing.sale_amount - right.pricing.sale_amount);
+  } else if (options.sort === 'price_high') {
+    next.sort((left, right) => right.pricing.sale_amount - left.pricing.sale_amount);
+  }
+
+  return typeof options.limit === 'number' ? next.slice(0, options.limit) : next;
+}
+
+export function useProducts(options?: ProductQuery & {
+  /** Backs the "video showcase" products variant. Deliberately incompatible
+   *  with `collection` (that path calls a different, collection-scoped
+   *  endpoint this filter isn't wired into) — has_video is ignored whenever
+   *  collection is also set. */
+  hasVideo?: boolean;
+}): { products: Product[]; isLoading: boolean } {
+  const { previewData, vendor } = useStorefront();
+  const hasPreviewProducts = Array.isArray(previewData?.products);
+  const [products, setProducts] = useState<Product[]>(() => (
+    options && hasPreviewProducts ? resolvePreviewProducts(previewData.products!, options) : []
+  ));
+  const [isLoading, setIsLoading] = useState(() => !options || !hasPreviewProducts);
+  // `undefined` is the caller's signal that it already has product data (e.g.
+  // server-seeded via `hydrateProductBlocks`, or a theme block's own
+  // `initialProducts`) and this hook has nothing to do — every call site in
+  // the codebase passes `undefined` specifically to mean that. Read outside
+  // the effect, as a plain boolean, so the effect keeps depending on
+  // `options`' individual fields rather than the object itself (a new object
+  // literal every render would otherwise re-run the fetch on every render).
+  const hasOptions = options !== undefined;
+
+  useEffect(() => {
+    if (!hasOptions) {
+      // Without this guard the hook fetched anyway and threw the result
+      // away, wasting a request on every mount.
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const previewProducts = previewData?.products;
+    const client = createBrowserClient(vendor.slug ?? undefined);
+
+    async function run(): Promise<void> {
+      try {
+        if (Array.isArray(previewProducts)) {
+          if (!cancelled) {
+            setProducts(resolvePreviewProducts(previewProducts, options!));
+            setIsLoading(false);
+          }
+          return;
+        }
+
+        setIsLoading(true);
+
+        let resolvedProducts: Product[];
+
+        if (options?.collection) {
+          const response = await client.get<ApiResponse<unknown>>(
+            `/collections/${options.collection}/products`,
+          );
+          resolvedProducts = extractProducts(response.data).map((p) => normalizeProduct(p));
+        } else {
+          const query: Record<string, string | number | string[]> = {};
+          if (options?.sort) query.sort = options.sort;
+          if (options?.limit) query.per_page = options.limit;
+          if (options?.hasVideo) query.has_video = 1;
+          // Ask the backend for exactly these products (whereIn) instead of
+          // fetching an arbitrary `per_page`-sized page of the default listing
+          // and hoping the requested ids happen to land in it — with a small
+          // limit (bundle/shop-the-look/featured's 1-3) they almost never did,
+          // silently dropping hand-picked products from the storefront.
+          if (options?.ids && options.ids.length > 0) query.ids = options.ids;
+
+          const response = await client.get<ApiResponse<unknown, ProductListMeta>>('/products', query);
+          resolvedProducts = extractProducts(response.data).map((p) => normalizeProduct(p));
+        }
+
+        let next = resolvedProducts;
+
+        if (options?.collection && options?.ids && options.ids.length > 0) {
+          // The collection endpoint has no ids filter of its own — this branch
+          // fetches the full collection unbounded, so a client-side filter here
+          // is safe (nothing was truncated before it ran).
+          next = next.filter((product) => options.ids?.includes(product.id));
+        }
+
+        if (typeof options?.limit === 'number') {
+          next = next.slice(0, options.limit);
+        }
+
+        if (!cancelled) {
+          setProducts(next);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [hasOptions, options?.collection, options?.ids, options?.limit, options?.sort, options?.hasVideo, previewData?.products, vendor.slug]);
+
+  return { products, isLoading };
+}
+
+/**
+ * Full product detail (the same `/products/{slug}` request the PDP itself
+ * uses), including the real `media.gallery` — the list/collection endpoints
+ * `useProducts` calls only ever return `media.{image,thumbnail}` (see
+ * Customer\ProductResource::buildBaseMediaPayload vs buildDetailMediaPayload
+ * in queek_backend). Single-product spotlight blocks (e.g. glow's `featured`
+ * variant) need this instead of substituting image/thumbnail as a fake
+ * 2-image gallery.
+ */
+/**
+ * Fetch one product by SLUG.
+ *
+ * Distinct from `useProductDetail` in hooks/use-product-detail.ts, which
+ * enriches a product you ALREADY hold from a list payload (that one takes the
+ * list product, an enabled flag and a vendor slug). Both were called
+ * `useProductDetail` until the public surface was written down and the clash
+ * surfaced — same name, unrelated signatures, one import path apart.
+ */
+export function useProductBySlug(slug: string | null | undefined): { product: Product | null; isLoading: boolean } {
+  const { previewData, vendor } = useStorefront();
+  const [product, setProduct] = useState<Product | null>(null);
+  const [isLoading, setIsLoading] = useState(!!slug);
+
+  useEffect(() => {
+    if (!slug) {
+      setProduct(null);
+      setIsLoading(false);
+      return;
+    }
+
+    // Preview/demo data has no separate detail endpoint to call — the list
+    // entry it already has is as good as it gets.
+    const previewProducts = previewData?.products;
+    if (Array.isArray(previewProducts)) {
+      setProduct(previewProducts.find((p) => p.slug === slug) ?? null);
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const client = createBrowserClient(vendor.slug ?? undefined);
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+      try {
+        const response = await client.get<ApiResponse<LegacyProductLike>>(`/products/${slug}`);
+        const products = extractProducts(response.data);
+        const payload = products[0] ?? response.data;
+        if (!cancelled) {
+          setProduct(payload ? normalizeProduct(payload as LegacyProductLike) : null);
+        }
+      } catch {
+        if (!cancelled) {
+          setProduct(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [slug, previewData?.products, vendor.slug]);
+
+  return { product, isLoading };
+}

package/hooks/use-related-products.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import type { Product } from '../types/product';
+import type { ApiResponse } from '../types/product';
+import { createBrowserClient } from '../sdk/client';
+import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+
+export function useRelatedProducts(
+  currentSlug: string,
+  limit = 4,
+): { products: Product[]; isLoading: boolean } {
+  const { vendor, previewData } = useStorefront();
+  const [products, setProducts] = useState<Product[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+      try {
+        if (previewData?.products) {
+          const others = (previewData.products as Product[])
+            .filter((p) => p.slug !== currentSlug)
+            .slice(0, limit);
+          if (!cancelled) setProducts(others);
+          return;
+        }
+
+        const client = createBrowserClient(vendor.slug ?? undefined);
+        const response = await client.get<ApiResponse<unknown>>(
+          `/products/${currentSlug}/related`,
+          { limit },
+        );
+
+        const raw = extractProducts(response.data);
+        const normalized = raw
+          .map((p) => normalizeProduct(p as Parameters<typeof normalizeProduct>[0]))
+          .slice(0, limit);
+
+        if (!cancelled) setProducts(normalized);
+      } catch {
+        // Non-critical — silently fail
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }
+
+    void run();
+    return () => { cancelled = true; };
+  }, [currentSlug, limit, vendor.slug, previewData?.products]);
+
+  return { products, isLoading };
+}

package/hooks/use-resolve-coordinates.ts

@@ -0,0 +1,48 @@
+'use client';
+
+import { useState } from 'react';
+import { useStorefront } from '../provider';
+import { getQueekClient } from '../sdk/queek-client';
+import { useLocationStore } from '../stores/location-store';
+
+interface CoordinatesResponse {
+  lat?: number;
+  lng?: number;
+  latitude?: number;
+  longitude?: number;
+  formatted_address?: string;
+  state_id?: string | null;
+}
+
+export function useResolveCoordinates(): {
+  resolve: (placeId: string, description: string) => Promise<boolean>;
+  resolving: boolean;
+} {
+  const { vendor } = useStorefront();
+  const setLocation = useLocationStore((s) => s.setLocation);
+  const [resolving, setResolving] = useState(false);
+
+  const resolve = async (placeId: string, description: string): Promise<boolean> => {
+    setResolving(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.post<CoordinatesResponse>('/client/geo/resolve', {
+        place_id: placeId,
+      });
+      const data = (res?.data ?? {}) as CoordinatesResponse;
+      const lat = data.lat ?? data.latitude;
+      const lng = data.lng ?? data.longitude;
+      if (typeof lat === 'number' && typeof lng === 'number') {
+        setLocation(lat, lng, data.formatted_address ?? description, data.state_id ?? null);
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    } finally {
+      setResolving(false);
+    }
+  };
+
+  return { resolve, resolving };
+}