create-brainerce-store 1.62.0 → 1.63.0

package/templates/nextjs/base/src/core/hooks/use-product-listing.ts

@@ -1,295 +1,295 @@
-'use client';
-
-import { useEffect, useMemo, useState, useCallback } from 'react';
-import { useSearchParams } from 'next/navigation';
-import { useRouter } from '@/core/lib/navigation';
-import type { Product, ProductQueryParams, PublicMetafieldDefinition } from 'brainerce';
-import { getClient } from '@/core/lib/brainerce';
-
-const PAGE_SIZE = 20;
-
-/**
- * Metafield (custom-field) values are passed in the URL as `mf_<key>=v1,v2`
- * for readability (no JSON encoding). The SDK assembles them back into
- * `{ [key]: string[] }` before calling `client.getProducts`.
- *
- * Only definitions with `filterable: true` of type SELECT / MULTI_SELECT /
- * BOOLEAN are honored server-side — the storefront renders facets only for
- * those.
- */
-const METAFIELD_URL_PREFIX = 'mf_';
-const FILTERABLE_TYPES = new Set(['SELECT', 'MULTI_SELECT', 'BOOLEAN']);
-
-export type SortOption = {
-  labelKey: 'sortNewest' | 'sortNameAZ' | 'sortNameZA' | 'sortPriceLow' | 'sortPriceHigh';
-  sortBy: ProductQueryParams['sortBy'];
-  sortOrder: ProductQueryParams['sortOrder'];
-};
-
-export const sortOptions: SortOption[] = [
-  { labelKey: 'sortNewest', sortBy: 'createdAt', sortOrder: 'desc' },
-  { labelKey: 'sortNameAZ', sortBy: 'name', sortOrder: 'asc' },
-  { labelKey: 'sortNameZA', sortBy: 'name', sortOrder: 'desc' },
-  { labelKey: 'sortPriceLow', sortBy: 'price', sortOrder: 'asc' },
-  { labelKey: 'sortPriceHigh', sortBy: 'price', sortOrder: 'desc' },
-];
-
-export interface CategoryNode {
-  id: string;
-  name: string;
-  image?: string | null;
-  parentId?: string | null;
-  children: CategoryNode[];
-}
-
-/** Collect all descendant IDs (including self) */
-export function getAllDescendantIds(node: CategoryNode): string[] {
-  const ids = [node.id];
-  for (const child of node.children) {
-    ids.push(...getAllDescendantIds(child));
-  }
-  return ids;
-}
-
-/** Check if a category or any of its descendants matches the selected ID */
-export function isActiveInTree(node: CategoryNode, selectedId: string): boolean {
-  if (node.id === selectedId) return true;
-  return node.children.some((child) => isActiveInTree(child, selectedId));
-}
-
-export interface UseProductListingResult {
-  /** Loaded products (accumulates across "load more" pages). */
-  products: Product[];
-  loading: boolean;
-  loadingMore: boolean;
-  page: number;
-  totalPages: number;
-  total: number;
-  /** Facet sources. */
-  categories: CategoryNode[];
-  brands: Array<{ id: string; name: string }>;
-  tags: Array<{ id: string; name: string }>;
-  metafieldDefs: PublicMetafieldDefinition[];
-  /** Current URL filter state. */
-  searchQuery: string;
-  categoryId: string;
-  brandId: string;
-  tagId: string;
-  sortIndex: number;
-  /** Handlers. */
-  handleLoadMore: () => void;
-  /** Set/clear a raw URL query param (`category`, `brand`, `tag`, `sort`, …). */
-  updateParam: (key: string, value: string) => void;
-  handleCategorySelect: (id: string) => void;
-  /** Read the currently-selected values for a given metafield definition. */
-  getSelectedMetafieldValues: (key: string) => string[];
-  /** Replace the selected values of a metafield facet. */
-  setMetafieldValue: (key: string, values: string[]) => void;
-}
-
-/**
- * Product-listing behavior: URL-driven filters (search / category / brand /
- * tag / sort / metafield facets), product loading, and load-more pagination.
- * Pure data/behavior — rendering lives in `ui/product/product-listing.tsx`.
- *
- * Must be rendered inside a `<Suspense>` boundary (uses `useSearchParams`).
- */
-export function useProductListing(): UseProductListingResult {
-  const searchParams = useSearchParams();
-  const router = useRouter();
-
-  const searchQuery = searchParams.get('search') || '';
-  const categoryId = searchParams.get('category') || '';
-  const brandId = searchParams.get('brand') || '';
-  const tagId = searchParams.get('tag') || '';
-  const sortParam = searchParams.get('sort') || '0';
-
-  const [products, setProducts] = useState<Product[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [loadingMore, setLoadingMore] = useState(false);
-  const [page, setPage] = useState(1);
-  const [totalPages, setTotalPages] = useState(1);
-  const [total, setTotal] = useState(0);
-  const [categories, setCategories] = useState<CategoryNode[]>([]);
-  const [brands, setBrands] = useState<Array<{ id: string; name: string }>>([]);
-  const [tags, setTags] = useState<Array<{ id: string; name: string }>>([]);
-  const [metafieldDefs, setMetafieldDefs] = useState<PublicMetafieldDefinition[]>([]);
-
-  const sortIndex = parseInt(sortParam, 10) || 0;
-  const currentSort = sortOptions[sortIndex] || sortOptions[0];
-
-  // Load categories, brands, tags, and metafield definitions (for custom-field facets).
-  // The metafield-definitions endpoint already returns only definitions
-  // published to this sales channel; we filter client-side to the ones flagged
-  // `filterable: true` and of a UI-renderable type.
-  useEffect(() => {
-    async function loadFilters() {
-      const client = getClient();
-      const [catRes, brandRes, tagRes, mfRes] = await Promise.allSettled([
-        client.getCategories(),
-        client.getBrands(),
-        client.getTags(),
-        client.getPublicMetafieldDefinitions(),
-      ]);
-      if (catRes.status === 'fulfilled') setCategories(catRes.value.categories as CategoryNode[]);
-      if (brandRes.status === 'fulfilled') setBrands(brandRes.value.brands);
-      if (tagRes.status === 'fulfilled') setTags(tagRes.value.tags);
-      if (mfRes.status === 'fulfilled') {
-        setMetafieldDefs(
-          mfRes.value.definitions.filter(
-            (d) => d.filterable === true && FILTERABLE_TYPES.has(d.type)
-          )
-        );
-      }
-    }
-    loadFilters();
-  }, []);
-
-  // Stable serialized signature of the selected metafield facets — used as
-  // the `loadProducts` dependency (and to derive the SDK shape). When no
-  // facets are selected, this is `''` so the SDK call omits `metafields`
-  // entirely and the backend short-circuits the filter branch.
-  const metafieldsKey = useMemo(() => {
-    if (metafieldDefs.length === 0) return '';
-    const parts: string[] = [];
-    for (const def of metafieldDefs) {
-      const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${def.key}`);
-      if (raw) parts.push(`${def.key}=${raw}`);
-    }
-    return parts.sort().join('&');
-  }, [metafieldDefs, searchParams]);
-
-  // Load products when filters change
-  const loadProducts = useCallback(
-    async (pageNum: number, append: boolean) => {
-      try {
-        if (append) {
-          setLoadingMore(true);
-        } else {
-          setLoading(true);
-        }
-
-        const client = getClient();
-        const params: ProductQueryParams = {
-          page: pageNum,
-          limit: PAGE_SIZE,
-          sortBy: currentSort.sortBy,
-          sortOrder: currentSort.sortOrder,
-        };
-
-        if (searchQuery) params.search = searchQuery;
-        if (categoryId) params.categories = categoryId;
-        if (brandId) params.brands = brandId;
-        if (tagId) params.tags = tagId;
-        // Build the `metafields` shape from `metafieldsKey` (each segment is
-        // `key=v1,v2`). Equivalent to reading the URL params directly but
-        // tied to the stable signature already in this callback's deps.
-        if (metafieldsKey) {
-          const mf: Record<string, string[]> = {};
-          for (const segment of metafieldsKey.split('&')) {
-            const eq = segment.indexOf('=');
-            if (eq < 0) continue;
-            const k = segment.slice(0, eq);
-            const v = segment
-              .slice(eq + 1)
-              .split(',')
-              .map((s) => s.trim())
-              .filter(Boolean);
-            if (v.length > 0) mf[k] = v;
-          }
-          if (Object.keys(mf).length > 0) params.metafields = mf;
-        }
-
-        const result = await client.getProducts(params);
-
-        if (append) {
-          setProducts((prev) => [...prev, ...result.data]);
-        } else {
-          setProducts(result.data);
-        }
-        setTotalPages(result.meta.totalPages);
-        setTotal(result.meta.total);
-        setPage(pageNum);
-      } catch (err) {
-        console.error('Failed to load products:', err);
-      } finally {
-        setLoading(false);
-        setLoadingMore(false);
-      }
-    },
-    [
-      searchQuery,
-      categoryId,
-      brandId,
-      tagId,
-      currentSort.sortBy,
-      currentSort.sortOrder,
-      metafieldsKey,
-    ]
-  );
-
-  useEffect(() => {
-    loadProducts(1, false);
-  }, [loadProducts]);
-
-  function handleLoadMore() {
-    if (page < totalPages && !loadingMore) {
-      loadProducts(page + 1, true);
-    }
-  }
-
-  function updateParam(key: string, value: string) {
-    const params = new URLSearchParams(searchParams.toString());
-    if (value) {
-      params.set(key, value);
-    } else {
-      params.delete(key);
-    }
-    router.push(`/products?${params.toString()}`);
-  }
-
-  function handleCategorySelect(id: string) {
-    updateParam('category', id);
-  }
-
-  /** Read the currently-selected values for a given metafield definition. */
-  function getSelectedMetafieldValues(key: string): string[] {
-    const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${key}`);
-    if (!raw) return [];
-    return raw
-      .split(',')
-      .map((v) => v.trim())
-      .filter(Boolean);
-  }
-
-  /**
-   * Toggle one value on/off in a metafield facet's URL param. Multi-select
-   * adds/removes from the list; single-select / boolean replace the value.
-   */
-  function setMetafieldValue(key: string, values: string[]) {
-    updateParam(`${METAFIELD_URL_PREFIX}${key}`, values.join(','));
-  }
-
-  return {
-    products,
-    loading,
-    loadingMore,
-    page,
-    totalPages,
-    total,
-    categories,
-    brands,
-    tags,
-    metafieldDefs,
-    searchQuery,
-    categoryId,
-    brandId,
-    tagId,
-    sortIndex,
-    handleLoadMore,
-    updateParam,
-    handleCategorySelect,
-    getSelectedMetafieldValues,
-    setMetafieldValue,
-  };
-}
+'use client';
+
+import { useEffect, useMemo, useState, useCallback } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { useRouter } from '@/core/lib/navigation';
+import type { Product, ProductQueryParams, PublicMetafieldDefinition } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+
+const PAGE_SIZE = 20;
+
+/**
+ * Metafield (custom-field) values are passed in the URL as `mf_<key>=v1,v2`
+ * for readability (no JSON encoding). The SDK assembles them back into
+ * `{ [key]: string[] }` before calling `client.getProducts`.
+ *
+ * Only definitions with `filterable: true` of type SELECT / MULTI_SELECT /
+ * BOOLEAN are honored server-side — the storefront renders facets only for
+ * those.
+ */
+const METAFIELD_URL_PREFIX = 'mf_';
+const FILTERABLE_TYPES = new Set(['SELECT', 'MULTI_SELECT', 'BOOLEAN']);
+
+export type SortOption = {
+  labelKey: 'sortNewest' | 'sortNameAZ' | 'sortNameZA' | 'sortPriceLow' | 'sortPriceHigh';
+  sortBy: ProductQueryParams['sortBy'];
+  sortOrder: ProductQueryParams['sortOrder'];
+};
+
+export const sortOptions: SortOption[] = [
+  { labelKey: 'sortNewest', sortBy: 'createdAt', sortOrder: 'desc' },
+  { labelKey: 'sortNameAZ', sortBy: 'name', sortOrder: 'asc' },
+  { labelKey: 'sortNameZA', sortBy: 'name', sortOrder: 'desc' },
+  { labelKey: 'sortPriceLow', sortBy: 'price', sortOrder: 'asc' },
+  { labelKey: 'sortPriceHigh', sortBy: 'price', sortOrder: 'desc' },
+];
+
+export interface CategoryNode {
+  id: string;
+  name: string;
+  image?: string | null;
+  parentId?: string | null;
+  children: CategoryNode[];
+}
+
+/** Collect all descendant IDs (including self) */
+export function getAllDescendantIds(node: CategoryNode): string[] {
+  const ids = [node.id];
+  for (const child of node.children) {
+    ids.push(...getAllDescendantIds(child));
+  }
+  return ids;
+}
+
+/** Check if a category or any of its descendants matches the selected ID */
+export function isActiveInTree(node: CategoryNode, selectedId: string): boolean {
+  if (node.id === selectedId) return true;
+  return node.children.some((child) => isActiveInTree(child, selectedId));
+}
+
+export interface UseProductListingResult {
+  /** Loaded products (accumulates across "load more" pages). */
+  products: Product[];
+  loading: boolean;
+  loadingMore: boolean;
+  page: number;
+  totalPages: number;
+  total: number;
+  /** Facet sources. */
+  categories: CategoryNode[];
+  brands: Array<{ id: string; name: string }>;
+  tags: Array<{ id: string; name: string }>;
+  metafieldDefs: PublicMetafieldDefinition[];
+  /** Current URL filter state. */
+  searchQuery: string;
+  categoryId: string;
+  brandId: string;
+  tagId: string;
+  sortIndex: number;
+  /** Handlers. */
+  handleLoadMore: () => void;
+  /** Set/clear a raw URL query param (`category`, `brand`, `tag`, `sort`, …). */
+  updateParam: (key: string, value: string) => void;
+  handleCategorySelect: (id: string) => void;
+  /** Read the currently-selected values for a given metafield definition. */
+  getSelectedMetafieldValues: (key: string) => string[];
+  /** Replace the selected values of a metafield facet. */
+  setMetafieldValue: (key: string, values: string[]) => void;
+}
+
+/**
+ * Product-listing behavior: URL-driven filters (search / category / brand /
+ * tag / sort / metafield facets), product loading, and load-more pagination.
+ * Pure data/behavior — rendering lives in `ui/product/product-listing.tsx`.
+ *
+ * Must be rendered inside a `<Suspense>` boundary (uses `useSearchParams`).
+ */
+export function useProductListing(): UseProductListingResult {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+
+  const searchQuery = searchParams.get('search') || '';
+  const categoryId = searchParams.get('category') || '';
+  const brandId = searchParams.get('brand') || '';
+  const tagId = searchParams.get('tag') || '';
+  const sortParam = searchParams.get('sort') || '0';
+
+  const [products, setProducts] = useState<Product[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [page, setPage] = useState(1);
+  const [totalPages, setTotalPages] = useState(1);
+  const [total, setTotal] = useState(0);
+  const [categories, setCategories] = useState<CategoryNode[]>([]);
+  const [brands, setBrands] = useState<Array<{ id: string; name: string }>>([]);
+  const [tags, setTags] = useState<Array<{ id: string; name: string }>>([]);
+  const [metafieldDefs, setMetafieldDefs] = useState<PublicMetafieldDefinition[]>([]);
+
+  const sortIndex = parseInt(sortParam, 10) || 0;
+  const currentSort = sortOptions[sortIndex] || sortOptions[0];
+
+  // Load categories, brands, tags, and metafield definitions (for custom-field facets).
+  // The metafield-definitions endpoint already returns only definitions
+  // published to this sales channel; we filter client-side to the ones flagged
+  // `filterable: true` and of a UI-renderable type.
+  useEffect(() => {
+    async function loadFilters() {
+      const client = getClient();
+      const [catRes, brandRes, tagRes, mfRes] = await Promise.allSettled([
+        client.getCategories(),
+        client.getBrands(),
+        client.getTags(),
+        client.getPublicMetafieldDefinitions(),
+      ]);
+      if (catRes.status === 'fulfilled') setCategories(catRes.value.categories as CategoryNode[]);
+      if (brandRes.status === 'fulfilled') setBrands(brandRes.value.brands);
+      if (tagRes.status === 'fulfilled') setTags(tagRes.value.tags);
+      if (mfRes.status === 'fulfilled') {
+        setMetafieldDefs(
+          mfRes.value.definitions.filter(
+            (d) => d.filterable === true && FILTERABLE_TYPES.has(d.type)
+          )
+        );
+      }
+    }
+    loadFilters();
+  }, []);
+
+  // Stable serialized signature of the selected metafield facets — used as
+  // the `loadProducts` dependency (and to derive the SDK shape). When no
+  // facets are selected, this is `''` so the SDK call omits `metafields`
+  // entirely and the backend short-circuits the filter branch.
+  const metafieldsKey = useMemo(() => {
+    if (metafieldDefs.length === 0) return '';
+    const parts: string[] = [];
+    for (const def of metafieldDefs) {
+      const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${def.key}`);
+      if (raw) parts.push(`${def.key}=${raw}`);
+    }
+    return parts.sort().join('&');
+  }, [metafieldDefs, searchParams]);
+
+  // Load products when filters change
+  const loadProducts = useCallback(
+    async (pageNum: number, append: boolean) => {
+      try {
+        if (append) {
+          setLoadingMore(true);
+        } else {
+          setLoading(true);
+        }
+
+        const client = getClient();
+        const params: ProductQueryParams = {
+          page: pageNum,
+          limit: PAGE_SIZE,
+          sortBy: currentSort.sortBy,
+          sortOrder: currentSort.sortOrder,
+        };
+
+        if (searchQuery) params.search = searchQuery;
+        if (categoryId) params.categories = categoryId;
+        if (brandId) params.brands = brandId;
+        if (tagId) params.tags = tagId;
+        // Build the `metafields` shape from `metafieldsKey` (each segment is
+        // `key=v1,v2`). Equivalent to reading the URL params directly but
+        // tied to the stable signature already in this callback's deps.
+        if (metafieldsKey) {
+          const mf: Record<string, string[]> = {};
+          for (const segment of metafieldsKey.split('&')) {
+            const eq = segment.indexOf('=');
+            if (eq < 0) continue;
+            const k = segment.slice(0, eq);
+            const v = segment
+              .slice(eq + 1)
+              .split(',')
+              .map((s) => s.trim())
+              .filter(Boolean);
+            if (v.length > 0) mf[k] = v;
+          }
+          if (Object.keys(mf).length > 0) params.metafields = mf;
+        }
+
+        const result = await client.getProducts(params);
+
+        if (append) {
+          setProducts((prev) => [...prev, ...result.data]);
+        } else {
+          setProducts(result.data);
+        }
+        setTotalPages(result.meta.totalPages);
+        setTotal(result.meta.total);
+        setPage(pageNum);
+      } catch (err) {
+        console.error('Failed to load products:', err);
+      } finally {
+        setLoading(false);
+        setLoadingMore(false);
+      }
+    },
+    [
+      searchQuery,
+      categoryId,
+      brandId,
+      tagId,
+      currentSort.sortBy,
+      currentSort.sortOrder,
+      metafieldsKey,
+    ]
+  );
+
+  useEffect(() => {
+    loadProducts(1, false);
+  }, [loadProducts]);
+
+  function handleLoadMore() {
+    if (page < totalPages && !loadingMore) {
+      loadProducts(page + 1, true);
+    }
+  }
+
+  function updateParam(key: string, value: string) {
+    const params = new URLSearchParams(searchParams.toString());
+    if (value) {
+      params.set(key, value);
+    } else {
+      params.delete(key);
+    }
+    router.push(`/products?${params.toString()}`);
+  }
+
+  function handleCategorySelect(id: string) {
+    updateParam('category', id);
+  }
+
+  /** Read the currently-selected values for a given metafield definition. */
+  function getSelectedMetafieldValues(key: string): string[] {
+    const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${key}`);
+    if (!raw) return [];
+    return raw
+      .split(',')
+      .map((v) => v.trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Toggle one value on/off in a metafield facet's URL param. Multi-select
+   * adds/removes from the list; single-select / boolean replace the value.
+   */
+  function setMetafieldValue(key: string, values: string[]) {
+    updateParam(`${METAFIELD_URL_PREFIX}${key}`, values.join(','));
+  }
+
+  return {
+    products,
+    loading,
+    loadingMore,
+    page,
+    totalPages,
+    total,
+    categories,
+    brands,
+    tags,
+    metafieldDefs,
+    searchQuery,
+    categoryId,
+    brandId,
+    tagId,
+    sortIndex,
+    handleLoadMore,
+    updateParam,
+    handleCategorySelect,
+    getSelectedMetafieldValues,
+    setMetafieldValue,
+  };
+}

package/templates/nextjs/base/src/core/hooks/use-product-page.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState, useMemo } from 'react';
+import { useEffect, useRef, useState, useMemo } from 'react';
 import type {
   Product,
   ProductCustomizationField,
@@ -11,7 +11,8 @@ import type {
   ModifierGroup,
 } from 'brainerce';
 import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
-import { useCart } from '@/core/providers/store-provider';
+import { useCart, useStoreInfo } from '@/core/providers/store-provider';
+import { trackAddToCart, trackProductView } from '@/core/lib/tracking';
 import {
   buildInitialSelections,
   toModifierSelections,
@@ -75,6 +76,8 @@ export interface UseProductPageResult {
  */
 export function useProductPage(initialProduct: Product): UseProductPageResult {
   const { refreshCart } = useCart();
+  const { storeInfo } = useStoreInfo();
+  const currency = storeInfo?.currency;
 
   const product = initialProduct;
   const recommendations = product?.recommendations ?? null;
@@ -187,6 +190,17 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
     return product ? getDescriptionContent(product) : null;
   }, [product]);
 
+  // `view_item` — the event Meta and Google build remarketing audiences from.
+  // The ref keeps it to once per product rather than once per render: the
+  // shopper is looking at one product, and re-firing on every swatch click or
+  // quantity change would inflate the audience with phantom views.
+  const viewedProductIdRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!product || viewedProductIdRef.current === product.id) return;
+    viewedProductIdRef.current = product.id;
+    trackProductView(product, selectedVariant, priceInfo.price, currency);
+  }, [product, selectedVariant, priceInfo.price, currency]);
+
   async function handleAddToCart() {
     if (!product || addingToCart) return;
 
@@ -232,6 +246,10 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
         ...(selections && selections.length > 0 ? { selections } : {}),
       });
       await refreshCart();
+      // Report only after the server accepted the line — an add that failed
+      // validation is not an add-to-cart, and feeding the ad platforms events
+      // that never became cart lines poisons their conversion modelling.
+      trackAddToCart(product, selectedVariant, quantity, priceInfo.price, currency);
       setAddedMessage(true);
       setTimeout(() => setAddedMessage(false), 2000);
     } catch (err) {

package/templates/nextjs/base/src/core/lib/image-hosts.ts

@@ -1,7 +1,7 @@
-/**
- * Single source of truth for which hostnames Brainerce serves optimized
- * (CDN-hosted, WebP) images from. Shared between `next.config.ts`
- * (`images.remotePatterns`) and `CdnImage` (per-instance `unoptimized`
- * fallback) so the two lists can't drift apart.
- */
-export const OPTIMIZED_IMAGE_HOSTS = ['cdn.brainerce.com'];
+/**
+ * Single source of truth for which hostnames Brainerce serves optimized
+ * (CDN-hosted, WebP) images from. Shared between `next.config.ts`
+ * (`images.remotePatterns`) and `CdnImage` (per-instance `unoptimized`
+ * fallback) so the two lists can't drift apart.
+ */
+export const OPTIMIZED_IMAGE_HOSTS = ['cdn.brainerce.com'];