@usequeek/theme-kit 0.1.0

package/hooks/use-reviews.ts

@@ -0,0 +1,167 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import { createBrowserClient } from '../sdk/client';
+import type { ReviewItem, ReviewsBlockData, ReviewsSummary } from '../types/block';
+
+interface ReviewsResponse {
+  status: string;
+  message: string;
+  data: {
+    scope: string;
+    vendor_id: string;
+    summary: ReviewsSummary;
+    reviews: ReviewItem[];
+  };
+}
+
+const EMPTY_SUMMARY: ReviewsSummary = {
+  average_rating: 0,
+  total_reviews: 0,
+  rating_breakdown: { '5': 0, '4': 0, '3': 0, '2': 0, '1': 0 },
+};
+
+
+/**
+ * Preview-mode resolution, mirroring `resolvePreviewProducts` in use-products:
+ * apply the block's own filters to seeded reviews so a preview shows what the
+ * configured section would really show.
+ */
+function resolvePreviewReviews(reviews: ReviewItem[], options: ReviewsBlockData): ReviewItem[] {
+  let next = [...reviews];
+
+  if (options.product_slug) next = next.filter((review) => review.product?.slug === options.product_slug);
+  if (options.ids && options.ids.length > 0) next = next.filter((review) => options.ids?.includes(review.id));
+  if (options.min_rating) next = next.filter((review) => review.rating >= options.min_rating!);
+  if (options.verified_only) next = next.filter((review) => review.is_verified_purchase);
+  if (options.with_media) next = next.filter((review) => (review.media?.length ?? 0) > 0);
+
+  if (options.sort === 'highest') next.sort((left, right) => right.rating - left.rating);
+  else if (options.sort === 'newest') next.sort((left, right) => right.created_at.localeCompare(left.created_at));
+
+  return typeof options.limit === 'number' ? next.slice(0, options.limit) : next;
+}
+
+function summarize(reviews: ReviewItem[]): ReviewsSummary {
+  if (reviews.length === 0) return EMPTY_SUMMARY;
+
+  const breakdown = { ...EMPTY_SUMMARY.rating_breakdown };
+  let total = 0;
+  for (const review of reviews) {
+    total += review.rating;
+    const key = String(Math.round(review.rating)) as keyof typeof breakdown;
+    if (key in breakdown) breakdown[key] += 1;
+  }
+
+  return {
+    average_rating: Number((total / reviews.length).toFixed(1)),
+    total_reviews: reviews.length,
+    rating_breakdown: breakdown,
+  };
+}
+
+export function useReviews(options: ReviewsBlockData): {
+  reviews: ReviewItem[];
+  summary: ReviewsSummary;
+  isLoading: boolean;
+} {
+  const { vendor, previewData } = useStorefront();
+  const seeded = options._preview?.reviews ?? (previewData?.reviews ? resolvePreviewReviews(previewData.reviews, options) : []);
+  const [reviews, setReviews] = useState<ReviewItem[]>(seeded);
+  const [summary, setSummary] = useState<ReviewsSummary>(options._preview?.summary ?? summarize(seeded));
+  const [isLoading, setIsLoading] = useState(!options._preview && !previewData);
+
+  const {
+    scope,
+    product_slug,
+    ids,
+    min_rating,
+    verified_only,
+    with_media,
+    limit,
+    sort,
+  } = options;
+
+  useEffect(() => {
+    // Preview mode: use inline preview data if provided, otherwise empty.
+    if (previewData) {
+      if (options._preview) {
+        setReviews(options._preview.reviews ?? []);
+        setSummary(options._preview.summary ?? EMPTY_SUMMARY);
+      } else if (previewData.reviews) {
+        const resolved = resolvePreviewReviews(previewData.reviews, options);
+        setReviews(resolved);
+        setSummary(summarize(resolved));
+      }
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const client = createBrowserClient(vendor.slug ?? undefined);
+
+    const query: Record<string, string | number> = {};
+    if (scope) query.scope = scope;
+    if (product_slug) query.product_slug = product_slug;
+    if (min_rating) query.min_rating = min_rating;
+    if (verified_only === false) query.verified_only = 0;
+    if (with_media) query.with_media = 1;
+    if (limit) query.limit = limit;
+    if (sort) query.sort = sort;
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+      try {
+        let path = '/reviews';
+        if (ids && ids.length > 0) {
+          const params = new URLSearchParams();
+          for (const [key, value] of Object.entries(query)) {
+            params.set(key, String(value));
+          }
+          ids.forEach((id) => params.append('ids[]', id));
+          path = `/reviews?${params.toString()}`;
+          const response = await client.get<ReviewsResponse>(path);
+          if (!cancelled) {
+            setReviews(response.data.reviews ?? []);
+            setSummary(response.data.summary ?? EMPTY_SUMMARY);
+          }
+          return;
+        }
+
+        const response = await client.get<ReviewsResponse>('/reviews', query);
+        if (!cancelled) {
+          setReviews(response.data.reviews ?? []);
+          setSummary(response.data.summary ?? EMPTY_SUMMARY);
+        }
+      } catch {
+        if (!cancelled) {
+          setReviews([]);
+          setSummary(EMPTY_SUMMARY);
+        }
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    vendor.slug,
+    previewData,
+    scope,
+    product_slug,
+    JSON.stringify(ids ?? []),
+    min_rating,
+    verified_only,
+    with_media,
+    limit,
+    sort,
+  ]);
+
+  return { reviews, summary, isLoading };
+}

package/hooks/use-search.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { Product } from '../types/product';
+import type { Collection } from '../types/page';
+
+export interface SearchResults {
+  products: Product[];
+  categories: Array<[slug: string, name: string]>;
+  collections: Collection[];
+}
+
+export function useSearch(
+  query: string,
+  products: Product[],
+  collections: Collection[],
+): SearchResults {
+  const filteredProducts = useMemo(() => {
+    if (!query.trim()) return products.slice(0, 5);
+    const q = query.toLowerCase();
+    return products
+      .filter(
+        (p) =>
+          p.title.toLowerCase().includes(q) ||
+          p.categories.some((c) => c.name.toLowerCase().includes(q)),
+      )
+      .slice(0, 5);
+  }, [query, products]);
+
+  const filteredCategories = useMemo(() => {
+    const map = new Map<string, string>();
+    products.forEach((p) =>
+      p.categories.forEach((c) => {
+        if (c.slug && !map.has(c.slug)) map.set(c.slug, c.name);
+      }),
+    );
+    if (!query.trim()) return Array.from(map.entries()).slice(0, 4);
+    const q = query.toLowerCase();
+    return Array.from(map.entries())
+      .filter(([, name]) => name.toLowerCase().includes(q))
+      .slice(0, 4);
+  }, [query, products]);
+
+  const filteredCollections = useMemo(() => {
+    if (!query.trim()) return [];
+    const q = query.toLowerCase();
+    return collections.filter((c) => c.name.toLowerCase().includes(q)).slice(0, 2);
+  }, [query, collections]);
+
+  return {
+    products: filteredProducts,
+    categories: filteredCategories,
+    collections: filteredCollections,
+  };
+}

package/hooks/use-shop-cart.ts

@@ -0,0 +1,31 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useCartStore } from '../stores/cart-store';
+
+export function useShopCart(shopId: string | null | undefined): {
+  items: ReturnType<typeof useCartStore.getState>['items'];
+  count: number;
+  total: number;
+  setQuantity: ReturnType<typeof useCartStore.getState>['setQuantity'];
+  removeItem: ReturnType<typeof useCartStore.getState>['removeItem'];
+  clearShopCart: ReturnType<typeof useCartStore.getState>['clearShopCart'];
+} {
+  const resolvedShopId = shopId ?? '';
+  const allItems = useCartStore((state) => state.items);
+  const items = useMemo(
+    () => allItems.filter((entry) => entry.shop_id === resolvedShopId),
+    [allItems, resolvedShopId],
+  );
+  const count = items.reduce((sum, entry) => sum + entry.quantity, 0);
+  const total = items.reduce((sum, entry) => sum + entry.unit_price * entry.quantity, 0);
+
+  return {
+    items,
+    count,
+    total,
+    setQuantity: useCartStore((state) => state.setQuantity),
+    removeItem: useCartStore((state) => state.removeItem),
+    clearShopCart: useCartStore((state) => state.clearShopCart),
+  };
+}

package/hooks/use-shop-params.ts

@@ -0,0 +1,68 @@
+'use client';
+
+import { useCallback } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import type { ShopSort } from './use-shop';
+
+const SORTS: ShopSort[] = ['latest', 'popular', 'price_low', 'price_high'];
+
+export interface ShopParams {
+  categorySlug: string | null;
+  keyword: string;
+  sort: ShopSort;
+  page: number;
+  setCategory: (slug: string | null) => void;
+  setKeyword: (keyword: string) => void;
+  setSort: (sort: ShopSort) => void;
+  setPage: (page: number) => void;
+}
+
+/**
+ * Shop filter/search/sort/page state, persisted in the URL query string so it
+ * survives refresh and is shareable. Pair with `useShop` for the catalogue data.
+ *
+ * Query keys: `category` (slug), `q` (keyword), `sort`, `page`.
+ * Changing category, keyword or sort resets to page 1.
+ */
+export function useShopParams(): ShopParams {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  const categorySlug = searchParams.get('category');
+  const keyword = searchParams.get('q') ?? '';
+  const sortRaw = searchParams.get('sort');
+  const sort: ShopSort = SORTS.includes(sortRaw as ShopSort) ? (sortRaw as ShopSort) : 'latest';
+  const pageRaw = Number(searchParams.get('page'));
+  const page = Number.isFinite(pageRaw) && pageRaw > 1 ? Math.floor(pageRaw) : 1;
+
+  const apply = useCallback(
+    (next: { category?: string | null; q?: string | null; sort?: ShopSort; page?: number }) => {
+      const params = new URLSearchParams(searchParams.toString());
+      const set = (key: string, value: string | null | undefined): void => {
+        if (value === null || value === undefined || value === '') params.delete(key);
+        else params.set(key, value);
+      };
+      if ('category' in next) set('category', next.category);
+      if ('q' in next) set('q', next.q);
+      if ('sort' in next) set('sort', next.sort === 'latest' ? null : next.sort);
+      if ('page' in next) set('page', next.page && next.page > 1 ? String(next.page) : null);
+      const qs = params.toString();
+      router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });
+    },
+    [router, pathname, searchParams],
+  );
+
+  const setCategory = useCallback(
+    (slug: string | null) => apply({ category: slug, q: null, page: 1 }),
+    [apply],
+  );
+  const setKeyword = useCallback(
+    (value: string) => apply({ q: value.trim() || null, category: null, page: 1 }),
+    [apply],
+  );
+  const setSort = useCallback((value: ShopSort) => apply({ sort: value, page: 1 }), [apply]);
+  const setPage = useCallback((value: number) => apply({ page: value }), [apply]);
+
+  return { categorySlug, keyword, sort, page, setCategory, setKeyword, setSort, setPage };
+}

package/hooks/use-shop.ts

@@ -0,0 +1,186 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useStorefront } from '../provider';
+import type { Product, ApiResponse, LegacyProductLike } from '../types/product';
+import { createBrowserClient } from '../sdk/client';
+import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+
+export type ShopSort = 'latest' | 'popular' | 'price_low' | 'price_high';
+
+export interface ShopPagination {
+  currentPage: number;
+  lastPage: number;
+  perPage: number;
+  total: number;
+  from: number | null;
+  to: number | null;
+  hasMore: boolean;
+}
+
+const EMPTY_PAGINATION: ShopPagination = {
+  currentPage: 1,
+  lastPage: 1,
+  perPage: 24,
+  total: 0,
+  from: null,
+  to: null,
+  hasMore: false,
+};
+
+function sortProducts(list: Product[], sort: ShopSort): Product[] {
+  const copy = [...list];
+  switch (sort) {
+    case 'price_low':
+      return copy.sort((a, b) => a.pricing.sale_amount - b.pricing.sale_amount);
+    case 'price_high':
+      return copy.sort((a, b) => b.pricing.sale_amount - a.pricing.sale_amount);
+    case 'popular':
+      return copy.sort(
+        (a, b) => b.review_summary.review_count - a.review_summary.review_count,
+      );
+    default:
+      return copy;
+  }
+}
+
+function filterProducts(
+  all: Product[],
+  categorySlug: string | null,
+  keyword: string | null,
+): Product[] {
+  let list = all;
+  if (categorySlug) {
+    list = list.filter((product) =>
+      product.categories.some((category) => category.slug === categorySlug),
+    );
+  }
+  const term = keyword?.trim().toLowerCase();
+  if (term) {
+    list = list.filter(
+      (product) =>
+        product.title.toLowerCase().includes(term) ||
+        (product.excerpt ?? '').toLowerCase().includes(term),
+    );
+  }
+  return list;
+}
+
+/**
+ * Shop catalogue data source. Hits the live products endpoint in production.
+ * In preview (when the provider carries `previewData.products`) it filters,
+ * sorts and paginates the demo catalogue in-memory so themes render real cards.
+ *
+ * Page is controlled by the caller — pair with `useShopParams` for URL sync.
+ */
+export function useShop(options?: {
+  categorySlug?: string | null;
+  keyword?: string | null;
+  sort?: ShopSort;
+  page?: number;
+  perPage?: number;
+}): {
+  products: Product[];
+  isLoading: boolean;
+  pagination: ShopPagination;
+} {
+  const { vendor, previewData } = useStorefront();
+
+  const perPage = options?.perPage ?? 24;
+  const categorySlug = options?.categorySlug ?? null;
+  const keyword = options?.keyword ?? null;
+  const sort = options?.sort ?? 'latest';
+  const page = options?.page && options.page > 0 ? options.page : 1;
+
+  const previewProducts = previewData?.products;
+  const isPreview = Array.isArray(previewProducts);
+
+  const [products, setProducts] = useState<Product[]>([]);
+  const [isLoading, setIsLoading] = useState(!isPreview);
+  const [pagination, setPagination] = useState<ShopPagination>({
+    ...EMPTY_PAGINATION,
+    perPage,
+  });
+  const cancelRef = useRef<boolean>(false);
+
+  // Preview: derive everything synchronously from the demo catalogue.
+  const previewResult = useMemo(() => {
+    if (!isPreview) return null;
+    const filtered = sortProducts(
+      filterProducts(previewProducts as Product[], categorySlug, keyword),
+      sort,
+    );
+    const total = filtered.length;
+    const lastPage = Math.max(1, Math.ceil(total / perPage));
+    const safePage = Math.min(Math.max(1, page), lastPage);
+    const start = (safePage - 1) * perPage;
+    const slice = filtered.slice(start, start + perPage);
+    return {
+      products: slice,
+      pagination: {
+        currentPage: safePage,
+        lastPage,
+        perPage,
+        total,
+        from: total === 0 ? null : start + 1,
+        to: total === 0 ? null : start + slice.length,
+        hasMore: safePage < lastPage,
+      } satisfies ShopPagination,
+    };
+  }, [isPreview, previewProducts, categorySlug, keyword, sort, page, perPage]);
+
+  // Production: fetch the live catalogue.
+  useEffect(() => {
+    if (isPreview) return undefined;
+
+    cancelRef.current = false;
+    setIsLoading(true);
+
+    const client = createBrowserClient(vendor.slug ?? undefined);
+    const query: Record<string, string | number> = { per_page: perPage, page };
+    if (categorySlug) query.category_slug = categorySlug;
+    if (keyword?.trim()) query.keyword = keyword.trim();
+    if (sort) query.sort = sort;
+
+    async function run(): Promise<void> {
+      try {
+        const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>(
+          '/products',
+          query,
+        );
+        if (cancelRef.current) return;
+
+        const meta = (response.meta ?? {}) as Record<string, unknown>;
+        const nestedMeta = (meta.pagination ?? meta) as Record<string, unknown>;
+        setPagination({
+          currentPage: (nestedMeta.current_page as number) ?? page,
+          lastPage: (nestedMeta.last_page as number) ?? 1,
+          perPage: (nestedMeta.per_page as number) ?? perPage,
+          total: (nestedMeta.total as number) ?? 0,
+          from: (nestedMeta.from as number | null) ?? null,
+          to: (nestedMeta.to as number | null) ?? null,
+          hasMore: (nestedMeta.has_more as boolean) ?? false,
+        });
+        setProducts(
+          extractProducts(response.data).map((item) =>
+            normalizeProduct(item as LegacyProductLike),
+          ),
+        );
+      } finally {
+        if (!cancelRef.current) setIsLoading(false);
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelRef.current = true;
+    };
+  }, [isPreview, vendor.slug, categorySlug, keyword, sort, perPage, page]);
+
+  if (isPreview && previewResult) {
+    return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination };
+  }
+
+  return { products, isLoading, pagination };
+}

package/hooks/use-variant-selection.ts

@@ -0,0 +1,98 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import type { Product, ProductVariant } from '../types/product';
+import { matchVariant, productRequiresVariant } from '../utils/match-variant';
+
+export interface VariantSelection {
+  /** Current option name → value map, seeded from a real variant. */
+  selectedOptions: Record<string, string>;
+  /** Pick one option value. Pass to a theme's own swatch/button markup. */
+  selectOption: (optionName: string, value: string) => void;
+  /** The variant the current selection resolves to, or null if none matches. */
+  matchedVariant: ProductVariant | null;
+  /**
+   * THE ADD GATE. False while a variant-required product has no resolved
+   * variant. Every add/buy button must include `!variantSatisfied` in its
+   * disabled expression — a variant-required line with no variant fails the
+   * cart save server-side.
+   */
+  variantSatisfied: boolean;
+  activePrice: number;
+  activeCompare: number;
+  activeDiscount: number;
+  activeInStock: boolean;
+  activeHasDiscount: boolean;
+}
+
+/**
+ * The option-selection state machine every theme's product page used to
+ * hand-roll — six near-identical copies, all of which gated their add button
+ * on stock and addons but never on a resolved variant.
+ *
+ * Two things it fixes that the copies got wrong:
+ *
+ * 1. It seeds from a real variant (first in-stock, else first) rather than
+ *    from the first value of each option independently. On a sparse matrix —
+ *    Red/S is not stocked but Red/M and Blue/S are — first-value-of-each
+ *    produces a combination that matches nothing, so the page opened with an
+ *    unresolvable selection.
+ * 2. It exposes `variantSatisfied`, so a selection that resolves to nothing
+ *    (mid-change, or that sparse seed) disables the add instead of sending a
+ *    line the backend rejects.
+ *
+ * Themes keep their own option markup and call `selectOption` — core owns the
+ * state, the theme owns the design.
+ */
+/**
+ * The opening selection. Seeded from a variant that actually exists, so the
+ * initial state is always resolvable — preferring one in stock, since opening
+ * on a sold-out variant reads as "unavailable" for a product that is not.
+ */
+export function seedVariantOptions(product: Product): Record<string, string> {
+  const variants = product.variants ?? [];
+  const seed = variants.find((variant) => variant.inventory?.in_stock) ?? variants[0];
+  if (seed) {
+    return Object.fromEntries(seed.option_values.map((ov) => [ov.option_name, ov.value]));
+  }
+
+  // No variants (or none loaded yet): fall back to the first value of each
+  // declared option so a picker still renders something selected.
+  const initial: Record<string, string> = {};
+  for (const option of product.options ?? []) {
+    if (option.values.length > 0) initial[option.name] = option.values[0].value;
+  }
+  return initial;
+}
+
+/** Everything derived from a selection. Pure, so the rules are testable directly. */
+export function resolveVariantState(
+  product: Product,
+  selectedOptions: Record<string, string>,
+): Omit<VariantSelection, 'selectedOptions' | 'selectOption'> {
+  const matchedVariant = matchVariant(product.variants ?? [], selectedOptions);
+  const activePrice = matchedVariant?.pricing.sale_amount ?? product.pricing.sale_amount;
+  const activeCompare = matchedVariant?.pricing.compare_at_amount ?? product.pricing.compare_at_amount;
+
+  return {
+    matchedVariant,
+    variantSatisfied: !productRequiresVariant(product) || matchedVariant !== null,
+    activePrice,
+    activeCompare,
+    activeDiscount: matchedVariant?.pricing.discount_percent ?? product.pricing.discount_percent,
+    activeInStock: matchedVariant ? matchedVariant.inventory.in_stock : product.inventory.in_stock,
+    activeHasDiscount: activeCompare > activePrice,
+  };
+}
+
+export function useVariantSelection(product: Product): VariantSelection {
+  const [selectedOptions, setSelectedOptions] = useState<Record<string, string>>(() => seedVariantOptions(product));
+
+  const selectOption = useCallback((optionName: string, value: string): void => {
+    setSelectedOptions((previous) => ({ ...previous, [optionName]: value }));
+  }, []);
+
+  const derived = useMemo(() => resolveVariantState(product, selectedOptions), [product, selectedOptions]);
+
+  return { selectedOptions, selectOption, ...derived };
+}

package/index.ts

@@ -0,0 +1,49 @@
+/**
+ * The public surface a theme is allowed to build against.
+ *
+ * The package is `@usequeek/theme-kit`: what a theme is built AGAINST, named for
+ * the job rather than for our internals — "storefront core" describes where the
+ * code lives here, which is meaningless to someone who has never seen this repo.
+ *
+ * Themes currently import core through deep paths (`@/lib/core/hooks/use-cart`).
+ * These two barrels name which of those paths are API — the set that would ship
+ * as `@usequeek/theme-kit` — so the boundary is written down before it is
+ * published and frozen. Anything NOT re-exported here is core's own plumbing and
+ * may change without notice.
+ *
+ * Two entries because the split is real, not cosmetic: this one is types and
+ * pure functions, importable from anywhere including node tooling; `client.ts`
+ * is React state and components and needs a client boundary at the consumer.
+ * Core also holds one `next/headers` caller, which belongs in neither and is
+ * deliberately unreachable from both.
+ *
+ * THESE ARE A DECLARATION, NOT AN IMPORT PATH. Do not migrate themes onto them.
+ * Measured 9/9/26: pointing one theme's 28 files at `client.ts` fails the build
+ * outright — `theme:generate-registry` imports theme components under tsx, and
+ * through the barrel a gallery block transitively pulls the SDK, which does not
+ * resolve outside a bundler. It is the same reason a barrel would bloat every
+ * theme chunk: the stores call `create()` at import time and package.json
+ * declares no `sideEffects`, so webpack must treat every re-export as live and
+ * cannot drop the unused ones. Themes keep importing the exact module they use;
+ * when core is published it should expose SUBPATH exports
+ * (`@usequeek/theme-kit/hooks/use-cart`) and these barrels stay the
+ * machine-checkable statement of what is in the contract.
+ */
+
+export * from './types/theme';
+export * from './types/block';
+export * from './types/product';
+export * from './types/cart';
+export * from './types/order';
+export * from './types/page';
+export * from './types/menu';
+export * from './utils/format';
+export * from './utils/markdown';
+export * from './utils/menu-link';
+export * from './utils/product-media';
+export * from './utils/hero-content';
+export * from './utils/addon-selection';
+export * from './utils/contact-location';
+export * from './utils/benefit-icon';
+export * from './utils/video-embed';
+export * from './utils/match-variant';