create-brainerce-store 1.50.5 → 1.52.0

package/templates/nextjs/base/src/core/hooks/use-home-data.ts

@@ -0,0 +1,51 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { Product, DiscountBanner } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+
+export interface UseHomeDataResult {
+  /** Newest products for the featured grid (max 8). */
+  products: Product[];
+  /** Active store-wide discount banners. */
+  banners: DiscountBanner[];
+  /** True while the initial fetch is in flight. */
+  loading: boolean;
+}
+
+/**
+ * Homepage data: featured products + discount banners.
+ * Pure data/behavior — rendering lives in `ui/home/`.
+ */
+export function useHomeData(): UseHomeDataResult {
+  const [products, setProducts] = useState<Product[]>([]);
+  const [banners, setBanners] = useState<DiscountBanner[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function load() {
+      try {
+        const client = getClient();
+        const [productsRes, bannersRes] = await Promise.allSettled([
+          client.getProducts({ limit: 8, sortBy: 'createdAt', sortOrder: 'desc' }),
+          client.getDiscountBanners(),
+        ]);
+
+        if (productsRes.status === 'fulfilled') {
+          setProducts(productsRes.value.data);
+        }
+        if (bannersRes.status === 'fulfilled') {
+          setBanners(bannersRes.value);
+        }
+      } catch (err) {
+        console.error('Failed to load home page data:', err);
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    load();
+  }, []);
+
+  return { products, banners, loading };
+}

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

@@ -0,0 +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,
+  };
+}

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

@@ -0,0 +1,278 @@
+'use client';
+
+import { useEffect, useState, useMemo } from 'react';
+import type {
+  Product,
+  ProductCustomizationField,
+  ProductImage,
+  ProductRecommendationsResponse,
+  ProductVariant,
+  InventoryInfo,
+  ModifierGroup,
+} from 'brainerce';
+import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
+import { useCart } from '@/core/providers/store-provider';
+import {
+  buildInitialSelections,
+  toModifierSelections,
+  validateCustomization,
+  validateSelections,
+  type CustomizationValues,
+} from '@/core/lib/product-options';
+
+export interface ProductPriceInfo {
+  price: number;
+  originalPrice: number;
+  isOnSale: boolean;
+  discountAmount?: number;
+  discountPercent: number;
+}
+
+export interface UseProductPageResult {
+  product: Product;
+  recommendations: ProductRecommendationsResponse | null;
+  /** Product image list. */
+  images: ProductImage[];
+  /** Index into `images`; -1 means "variant image not in the list". */
+  selectedImageIndex: number;
+  setSelectedImageIndex: (index: number) => void;
+  /** URL of the image to show as the main image (variant-aware). */
+  mainImageUrl: string | null;
+  /** Variant selection. */
+  selectedVariant: ProductVariant | null;
+  setSelectedVariant: (variant: ProductVariant | null) => void;
+  /** Effective price info (variant price + discount-rule overlay). */
+  priceInfo: ProductPriceInfo;
+  /** Variant inventory when a variant is selected, else product inventory. */
+  inventory: InventoryInfo | null;
+  canPurchase: boolean;
+  /** Resolved description content ({ html } or { text }). */
+  description: ReturnType<typeof getDescriptionContent> | null;
+  /** Quantity picker. */
+  quantity: number;
+  setQuantity: (update: number | ((q: number) => number)) => void;
+  /** Add-to-cart state machine. */
+  addingToCart: boolean;
+  addedMessage: boolean;
+  handleAddToCart: () => Promise<void>;
+  /** Customization (buyer input) sub-contract. */
+  customizationFields: ProductCustomizationField[];
+  customizationValues: CustomizationValues;
+  setCustomizationValues: (values: CustomizationValues) => void;
+  customizationErrors: Record<string, string>;
+  /** Modifier groups (toppings, sauce, …) sub-contract. */
+  modifierGroups: ModifierGroup[];
+  modifierSelections: Record<string, string[]>;
+  setModifierSelection: (groupId: string, next: string[]) => void;
+  modifierError: string | null;
+}
+
+/**
+ * Product-page behavior: variant selection, variant-aware image + price +
+ * inventory resolution, quantity, customization + modifier state and
+ * validation, and the add-to-cart state machine. Pure data/behavior —
+ * rendering lives in `ui/product/product-client-section.tsx`.
+ */
+export function useProductPage(initialProduct: Product): UseProductPageResult {
+  const { refreshCart } = useCart();
+
+  const product = initialProduct;
+  const recommendations = product?.recommendations ?? null;
+
+  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(
+    product.variants && product.variants.length > 0 ? product.variants[0] : null
+  );
+  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
+  const [quantity, setQuantity] = useState(1);
+  const [addingToCart, setAddingToCart] = useState(false);
+  const [addedMessage, setAddedMessage] = useState(false);
+  const customizationFields = product.customizationFields ?? [];
+  const [customizationValues, setCustomizationValues] = useState<CustomizationValues>(() => {
+    const initial: CustomizationValues = {};
+    for (const field of customizationFields) {
+      if (field.defaultValue != null) initial[field.key] = field.defaultValue;
+    }
+    return initial;
+  });
+  const [customizationErrors, setCustomizationErrors] = useState<Record<string, string>>({});
+
+  // Modifier groups (PRD §8.4) — only present on restaurant / build-your-own products.
+  const modifierGroups: ModifierGroup[] = useMemo(
+    () => (product as Product & { modifierGroups?: ModifierGroup[] }).modifierGroups ?? [],
+    [product]
+  );
+  const [modifierSelections, setModifierSelections] = useState<Record<string, string[]>>(() =>
+    buildInitialSelections(modifierGroups)
+  );
+  const [modifierError, setModifierError] = useState<string | null>(null);
+
+  function setModifierSelection(groupId: string, next: string[]) {
+    setModifierSelections((prev) => ({ ...prev, [groupId]: next }));
+  }
+
+  // Images list - switch main image when variant changes
+  const images: ProductImage[] = useMemo(() => {
+    return product?.images || [];
+  }, [product]);
+
+  // When variant changes, update selected image to variant image if available
+  useEffect(() => {
+    if (!selectedVariant?.image || !product) return;
+
+    const variantImgUrl =
+      typeof selectedVariant.image === 'string' ? selectedVariant.image : selectedVariant.image.url;
+
+    // Find if variant image exists in product images
+    const idx = images.findIndex((img) => img.url === variantImgUrl);
+    if (idx >= 0) {
+      setSelectedImageIndex(idx);
+    } else {
+      // Variant image not in product images - select index 0 as fallback
+      setSelectedImageIndex(-1);
+    }
+  }, [selectedVariant, images, product]);
+
+  // Determine which image to show
+  const mainImageUrl = useMemo(() => {
+    if (selectedImageIndex === -1 && selectedVariant?.image) {
+      const img = selectedVariant.image;
+      return typeof img === 'string' ? img : img.url;
+    }
+    return images[selectedImageIndex]?.url || null;
+  }, [selectedImageIndex, selectedVariant, images]);
+
+  // Price info - use variant price if selected, else product price
+  const priceInfo = useMemo(() => {
+    if (selectedVariant?.price) {
+      const variantBase = parseFloat(selectedVariant.price);
+      const variantSale = selectedVariant.salePrice ? parseFloat(selectedVariant.salePrice) : null;
+      const variantEffective =
+        variantSale != null && variantSale < variantBase ? variantSale : variantBase;
+
+      // Overlay any product-level discount rule onto the variant price using the rule's ratio
+      if (product.discount) {
+        const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
+        const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
+        const ratio = ruleOriginal > 0 ? ruleDiscounted / ruleOriginal : 1;
+        const discounted = variantEffective * ratio;
+        const amount = Math.max(0, variantEffective - discounted);
+        return {
+          price: discounted,
+          originalPrice: variantEffective,
+          isOnSale: discounted < variantEffective,
+          discountAmount: amount,
+          discountPercent: variantEffective > 0 ? Math.round((amount / variantEffective) * 100) : 0,
+        };
+      }
+
+      return {
+        price: variantEffective,
+        originalPrice: variantBase,
+        isOnSale: variantEffective < variantBase,
+        discountPercent:
+          variantEffective < variantBase && variantBase > 0
+            ? Math.round(((variantBase - variantEffective) / variantBase) * 100)
+            : 0,
+      };
+    }
+    return getProductPriceInfo(product);
+  }, [product, selectedVariant]);
+
+  // Inventory: use variant inventory if selected, else product inventory
+  const inventory = selectedVariant?.inventory ?? product?.inventory ?? null;
+  const canPurchase = inventory?.canPurchase !== false;
+
+  // Description
+  const description = useMemo(() => {
+    return product ? getDescriptionContent(product) : null;
+  }, [product]);
+
+  async function handleAddToCart() {
+    if (!product || addingToCart) return;
+
+    if (customizationFields.length > 0) {
+      const errs = validateCustomization(customizationFields, customizationValues);
+      if (Object.keys(errs).length > 0) {
+        setCustomizationErrors(errs);
+        return;
+      }
+    }
+    setCustomizationErrors({});
+
+    // Client-side modifier validation mirrors the server's checks. The server
+    // is authoritative — `MODIFIER_VALIDATION_FAILED` envelope on add-to-cart
+    // failure is the source of truth — but pre-flighting catches the obvious
+    // issues without a round-trip.
+    if (modifierGroups.length > 0) {
+      const error = validateSelections(modifierGroups, modifierSelections);
+      if (error) {
+        setModifierError(error);
+        return;
+      }
+    }
+    setModifierError(null);
+
+    const selections =
+      modifierGroups.length > 0
+        ? toModifierSelections(modifierGroups, modifierSelections)
+        : undefined;
+
+    try {
+      setAddingToCart(true);
+      const { getClient } = await import('@/core/lib/brainerce');
+      const client = getClient();
+      await client.smartAddToCart({
+        productId: product.id,
+        variantId: selectedVariant?.id,
+        quantity,
+        metadata:
+          customizationFields.length > 0 && Object.keys(customizationValues).length > 0
+            ? customizationValues
+            : undefined,
+        ...(selections && selections.length > 0 ? { selections } : {}),
+      });
+      await refreshCart();
+      setAddedMessage(true);
+      setTimeout(() => setAddedMessage(false), 2000);
+    } catch (err) {
+      // Surface the structured `MODIFIER_VALIDATION_FAILED` envelope when present.
+      const e = err as { details?: { code?: string; errors?: Array<{ message: string }> } };
+      const validationErrors = e?.details?.errors;
+      if (e?.details?.code === 'MODIFIER_VALIDATION_FAILED' && validationErrors?.length) {
+        setModifierError(validationErrors.map((v) => v.message).join('; '));
+      } else {
+        console.error('Failed to add to cart:', err);
+      }
+    } finally {
+      setAddingToCart(false);
+    }
+  }
+
+  return {
+    product,
+    recommendations,
+    images,
+    selectedImageIndex,
+    setSelectedImageIndex,
+    mainImageUrl,
+    selectedVariant,
+    setSelectedVariant,
+    priceInfo,
+    inventory,
+    canPurchase,
+    description,
+    quantity,
+    setQuantity,
+    addingToCart,
+    addedMessage,
+    handleAddToCart,
+    customizationFields,
+    customizationValues,
+    setCustomizationValues,
+    customizationErrors,
+    modifierGroups,
+    modifierSelections,
+    setModifierSelection,
+    modifierError,
+  };
+}

package/templates/nextjs/base/src/{hooks → core/hooks}/use-search.ts

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useRef, useCallback } from 'react';
 import type { SearchSuggestions } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
+import { getClient } from '@/core/lib/brainerce';
 
 const DEBOUNCE_MS = 300;
 const MIN_QUERY_LENGTH = 2;

package/templates/nextjs/base/src/{lib → core/lib}/brainerce.ts.ejs

@@ -1,6 +1,6 @@
 import { BrainerceClient } from 'brainerce';
 import { cache } from 'react';
-import { pickPublicStoreInfo, type PublicStoreInfo } from '@/lib/store-info';
+import { pickPublicStoreInfo, type PublicStoreInfo } from '@/core/lib/store-info';
 
 // Read either env var name. The new one is preferred; the old one is a soft
 // alias kept for backwards compatibility — both are accepted by the SDK.