create-brainerce-store 1.50.5 → 1.52.0

package/templates/nextjs/ui-canvas/product/frequently-bought-together.tsx

@@ -0,0 +1,168 @@
+'use client';
+
+import { useState } from 'react';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import type { Product, ProductRecommendation } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { useCart, useStoreInfo } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+
+interface FrequentlyBoughtTogetherProps {
+  items: ProductRecommendation[];
+  currentProduct: Product;
+  className?: string;
+}
+
+function getEffectivePrice(item: { basePrice: string; salePrice?: string | null }): number {
+  const sale = item.salePrice ? parseFloat(item.salePrice) : null;
+  const base = parseFloat(item.basePrice);
+  return sale != null && sale < base ? sale : base;
+}
+
+function ProductThumb({
+  name,
+  imageUrl,
+  price,
+  currency,
+  checked,
+  onToggle,
+  disabled,
+}: {
+  name: string;
+  imageUrl: string | null;
+  price: number;
+  currency: string;
+  checked: boolean;
+  onToggle?: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <label className="inline-flex items-center gap-2">
+      {onToggle && <input type="checkbox" checked={checked} onChange={onToggle} disabled={disabled} />}
+      {/* `relative` + fixed box are layout-critical for next/image fill */}
+      <span className="relative block h-20 w-20">
+        {imageUrl ? <Image src={imageUrl} alt={name} fill sizes="80px" /> : null}
+      </span>
+      <span>{name}</span>
+      <span>{formatPrice(price, { currency }) as string}</span>
+    </label>
+  );
+}
+
+/**
+ * DESIGN ME — "frequently bought together" bundle on the product page:
+ * current product + selectable cross-sells + combined total + add-all button;
+ * items come from useProductPage().recommendations.crossSells, the feature
+ * gate from useStoreInfo().upsell.
+ *
+ * Building blocks: shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons are installed and ready to compose with.
+ */
+export function FrequentlyBoughtTogether({
+  items,
+  currentProduct,
+  className,
+}: FrequentlyBoughtTogetherProps) {
+  // Hooks must be called unconditionally and in the same order on every
+  // render — keep all of them above any early `return null` branch.
+  const { storeInfo } = useStoreInfo();
+  const { refreshCart } = useCart();
+  const t = useTranslations('productDetail');
+  const currency = useCurrency();
+
+  // Only show up to 3 cross-sells
+  const crossSells = items.slice(0, 3);
+
+  const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
+  const [adding, setAdding] = useState(false);
+
+  if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
+  if (crossSells.length === 0) return null;
+
+  const currentPrice = getEffectivePrice(currentProduct);
+  const currentImage = currentProduct.images?.[0];
+  const currentImageUrl = currentImage
+    ? typeof currentImage === 'string'
+      ? currentImage
+      : currentImage.url
+    : null;
+
+  const totalPrice = crossSells
+    .filter((item) => selected.has(item.id))
+    .reduce((sum, item) => sum + getEffectivePrice(item), currentPrice);
+
+  const toggleItem = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  async function handleAddAll() {
+    if (adding || selected.size === 0) return;
+    try {
+      setAdding(true);
+      const { getClient } = await import('@/core/lib/brainerce');
+      const client = getClient();
+      const selectedItems = crossSells.filter((item) => selected.has(item.id));
+      for (const item of selectedItems) {
+        await client.smartAddToCart({ productId: item.id, quantity: 1 });
+      }
+      await refreshCart();
+    } catch (err) {
+      console.error('Failed to add items to cart:', err);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <section className={cn(className)}>
+      <h2>{t('frequentlyBoughtTogether')}</h2>
+
+      <div className="flex flex-wrap items-center gap-3">
+        {/* Current product (always included, no checkbox) */}
+        <ProductThumb
+          name={currentProduct.name}
+          imageUrl={currentImageUrl}
+          price={currentPrice}
+          currency={currency}
+          checked={true}
+          disabled
+        />
+
+        {crossSells.map((item) => {
+          const img = item.images?.[0];
+          const imgUrl = img ? (typeof img === 'string' ? img : img.url) : null;
+          return (
+            <div key={item.id} className="flex items-center gap-3">
+              <span aria-hidden="true">+</span>
+              <ProductThumb
+                name={item.name}
+                imageUrl={imgUrl}
+                price={getEffectivePrice(item)}
+                currency={currency}
+                checked={selected.has(item.id)}
+                onToggle={() => toggleItem(item.id)}
+              />
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Total + Add button */}
+      <div className="flex flex-wrap items-center gap-4">
+        <span>{t('totalPrice', { price: formatPrice(totalPrice, { currency }) as string })}</span>
+        <button type="button" onClick={handleAddAll} disabled={adding || selected.size === 0}>
+          {adding ? t('addingAll') : t('addSelectedToCart')}
+        </button>
+      </div>
+    </section>
+  );
+}

package/templates/nextjs/ui-canvas/product/modifier-group-selector.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+/**
+ * <ModifierGroupSelector> — bare-skeleton renderer for a single modifier
+ * group (toppings, sauce, bread type, …) per PRD §8.4.
+ *
+ * DESIGN ME — modifier group on the product page; the group + selections
+ * come from useProductPage() via props. The data contract is what matters:
+ *
+ *   - SINGLE   → renders as <input type="radio">,    max picks = 1
+ *   - MULTIPLE → renders as <input type="checkbox">, picks bounded by min..max
+ *   - effectiveMax === 0 → group is hidden entirely (variant-disable convention)
+ *   - available === false → modifier is disabled with "Sold out" badge
+ *   - free counter shows "{used} of {freeQuantity} free" when freeQuantity > 0
+ *   - defaultModifierIds + isDefault drive first-render checked state
+ *   - client-side guards mirror min/max (UX); the SERVER is authoritative — wire
+ *     `MODIFIER_VALIDATION_FAILED` errors back to the user when add-to-cart fails
+ *
+ * The price-delta side: this component does NOT compute totals. The server
+ * runs the free-allocation policy and returns the line's `unitPrice` /
+ * `modifiers[]` / `modifiersTotal` snapshot — render those after add-to-cart.
+ *
+ * Building blocks: shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons are installed and ready to compose with.
+ */
+
+import type { Modifier, ModifierGroup } from 'brainerce';
+
+// The pure selection logic (defaults, validation, wire-format adapter) lives
+// in core (zero markup) so that `core/hooks/use-product-page` never imports
+// from `ui/`. Re-exported here for backward compatibility with existing imports.
+export {
+  buildInitialSelections,
+  toModifierSelections,
+  validateSelections,
+} from '@/core/lib/product-options';
+
+interface ModifierGroupSelectorProps {
+  /**
+   * Effective group as returned by `GET /products/:id` (overrides already
+   * applied — `min`, `max`, `freeQuantity`, etc. are the values the server
+   * will validate against for the active variant).
+   */
+  group: ModifierGroup;
+  /** Currently-selected modifier IDs in click-order. */
+  value: string[];
+  onChange: (next: string[]) => void;
+  /** Disable all controls (e.g., while add-to-cart is in flight). */
+  disabled?: boolean;
+}
+
+export function ModifierGroupSelector({
+  group,
+  value,
+  onChange,
+  disabled = false,
+}: ModifierGroupSelectorProps) {
+  // PRD §7.2.2: variant-disable convention — group with effectiveMax=0 is hidden.
+  if (group.max === 0) return null;
+
+  const isSingle = group.selectionType === 'SINGLE';
+  // Client-side bound — server is authoritative.
+  const effectiveMax = isSingle ? 1 : (group.max ?? Infinity);
+
+  const handleToggle = (modifierId: string, checked: boolean) => {
+    if (disabled) return;
+
+    if (isSingle) {
+      // Radio behavior: replace the selection.
+      onChange(checked ? [modifierId] : []);
+      return;
+    }
+
+    if (checked) {
+      if (value.length >= effectiveMax) return; // would exceed max — ignore the click
+      if (value.includes(modifierId)) return;
+      onChange([...value, modifierId]);
+    } else {
+      onChange(value.filter((id) => id !== modifierId));
+    }
+  };
+
+  const sortedModifiers = [...group.modifiers].sort((a, b) => a.position - b.position);
+
+  // Counter: how many of the picked items are within the "free" window.
+  const usedFreeSlots = Math.min(value.length, group.freeQuantity);
+  const showFreeCounter = group.freeQuantity > 0;
+
+  return (
+    <fieldset>
+      <legend>
+        <span>{group.name}</span>
+        {group.required && <span aria-hidden="true"> *</span>}
+        <span> {ruleSummary(group)}</span>
+      </legend>
+
+      {group.description && <p>{group.description}</p>}
+
+      {showFreeCounter && (
+        <p aria-live="polite">
+          {usedFreeSlots} of {group.freeQuantity} free
+        </p>
+      )}
+
+      <ul>
+        {sortedModifiers.map((modifier) => {
+          const isChecked = value.includes(modifier.id);
+          const isAtCap = !isSingle && !isChecked && value.length >= effectiveMax;
+          const isDisabled = disabled || !modifier.available || isAtCap;
+
+          return (
+            <li key={modifier.id}>
+              <label className="inline-flex items-center gap-2">
+                <input
+                  type={isSingle ? 'radio' : 'checkbox'}
+                  name={`modifier-group-${group.id}`}
+                  value={modifier.id}
+                  checked={isChecked}
+                  disabled={isDisabled}
+                  onChange={(e) => handleToggle(modifier.id, e.target.checked)}
+                />
+                <span>{modifier.name}</span>
+                <ModifierPriceLabel modifier={modifier} />
+                {!modifier.available && <span aria-label="Sold out">Sold out</span>}
+              </label>
+              {modifier.description && <p>{modifier.description}</p>}
+            </li>
+          );
+        })}
+      </ul>
+    </fieldset>
+  );
+}
+
+/**
+ * Renders the modifier's price contribution next to its name.
+ *
+ * Negative deltas display with a leading minus sign (downsell modifiers per
+ * PRD §6.3.4); zero-delta modifiers render nothing — silence is the right
+ * affordance for a free option.
+ */
+function ModifierPriceLabel({ modifier }: { modifier: Modifier }) {
+  const delta = parseFloat(modifier.priceDelta);
+  if (Number.isNaN(delta) || delta === 0) return null;
+  const sign = delta > 0 ? '+' : '';
+  return (
+    <span>
+      {sign}
+      {modifier.priceDelta}
+    </span>
+  );
+}
+
+function ruleSummary(group: ModifierGroup): string {
+  const parts: string[] = [];
+  if (group.selectionType === 'SINGLE') {
+    parts.push('Pick one');
+  } else if (group.max != null) {
+    if (group.min === 0) parts.push(`Up to ${group.max}`);
+    else if (group.min === group.max) parts.push(`Pick exactly ${group.min}`);
+    else parts.push(`${group.min}–${group.max}`);
+  } else if (group.min > 0) {
+    parts.push(`At least ${group.min}`);
+  }
+  return parts.length ? `(${parts.join(', ')})` : '';
+}

package/templates/nextjs/ui-canvas/product/price-display.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import { formatPrice } from 'brainerce';
+import { useCurrency } from '@/core/lib/use-currency';
+import { cn } from '@/core/lib/utils';
+
+interface PriceDisplayProps {
+  price: string | number;
+  salePrice?: string | number | null;
+  currency?: string;
+  className?: string;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * DESIGN ME — price renderer used by cards, product page and recommendations;
+ * computes sale state + discount % from props (currency via useCurrency()).
+ * Never hardcode currency symbols — formatPrice handles them.
+ *
+ * Building blocks: shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons are installed and ready to compose with.
+ */
+export function PriceDisplay({
+  price,
+  salePrice,
+  currency,
+  className,
+  size = 'md',
+}: PriceDisplayProps) {
+  const currencyCode = useCurrency(currency);
+
+  const basePrice = typeof price === 'string' ? parseFloat(price) : price;
+  const sale =
+    salePrice != null ? (typeof salePrice === 'string' ? parseFloat(salePrice) : salePrice) : null;
+  const isOnSale = sale !== null && sale < basePrice;
+
+  const discountPercent =
+    isOnSale && basePrice > 0 ? Math.round(((basePrice - sale!) / basePrice) * 100) : 0;
+
+  return (
+    <span data-size={size} className={cn('inline-flex items-center gap-2', className)}>
+      {isOnSale ? (
+        <>
+          <span>{formatPrice(sale!, { currency: currencyCode }) as string}</span>
+          <s>{formatPrice(basePrice, { currency: currencyCode }) as string}</s>
+          {discountPercent > 0 && <span>-{discountPercent}%</span>}
+        </>
+      ) : (
+        <span>{formatPrice(basePrice, { currency: currencyCode }) as string}</span>
+      )}
+    </span>
+  );
+}

package/templates/nextjs/ui-canvas/product/product-card.tsx

@@ -0,0 +1,197 @@
+'use client';
+
+import { useState } from 'react';
+import { Link, useRouter } from '@/core/lib/navigation';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import type { Product } from 'brainerce';
+import { getProductPriceInfo, getVariantPrice, formatPrice } from 'brainerce';
+import { useTranslations } from '@/core/lib/translations';
+import { PriceDisplay } from '@/ui/product/price-display';
+import { StockBadge } from '@/ui/product/stock-badge';
+import { DiscountBadge } from '@/ui/product/discount-badge';
+import { useCart } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
+import { cn } from '@/core/lib/utils';
+
+interface ProductCardProps {
+  product: Product;
+  className?: string;
+}
+
+/**
+ * Pick the price + currency to render for a given product (PRD §23 FX overlay).
+ *
+ * When the storefront passed `regionId` to `getProducts({ regionId })` AND the
+ * region currency differs from the store currency, the backend attaches
+ * additive `displayPrice` / `displayCurrency` fields. Otherwise we fall back
+ * to the canonical store-currency `basePrice` / `salePrice`. Either way the
+ * cart still charges in the store currency — this only affects display.
+ */
+function pickDisplayPrice(
+  product: Product,
+  fallbackCurrency: string
+): { price: number | undefined; salePrice: number | null; currency: string } {
+  if (product.displayPrice != null && product.displayCurrency) {
+    const sale =
+      product.displaySalePrice != null ? parseFloat(product.displaySalePrice) : null;
+    return {
+      // `displayPrice` is the base price converted to the region currency —
+      // it goes into the PriceDisplay `price` (base) slot, NOT the sale slot.
+      price: parseFloat(product.displayPrice),
+      salePrice: sale != null && !Number.isNaN(sale) ? sale : null,
+      currency: product.displayCurrency,
+    };
+  }
+  // Same-currency fallback. `getProductPriceInfo.price` is the EFFECTIVE
+  // charged amount (= salePrice when on sale, base otherwise); `originalPrice`
+  // is the base. Map them to PriceDisplay's (price = base, salePrice = sale).
+  const { price: effective, originalPrice, isOnSale } = getProductPriceInfo(product);
+  return {
+    price: originalPrice,
+    salePrice: isOnSale ? effective : null,
+    currency: fallbackCurrency,
+  };
+}
+
+function VariantPriceRange({ product }: { product: Product }) {
+  const currency = useCurrency();
+
+  let min: number;
+  let max: number;
+  if (product.priceMin && product.priceMax) {
+    min = parseFloat(product.priceMin);
+    max = parseFloat(product.priceMax);
+  } else {
+    const variants = product.variants ?? [];
+    if (variants.length === 0) return null;
+    const prices = variants.map((v) => getVariantPrice(v, product.basePrice));
+    min = Math.min(...prices);
+    max = Math.max(...prices);
+  }
+
+  if (isNaN(min) || isNaN(max)) return null;
+
+  return (
+    <span>
+      {min === max
+        ? (formatPrice(min, { currency }) as string)
+        : `${formatPrice(min, { currency })} – ${formatPrice(max, { currency })}`}
+    </span>
+  );
+}
+
+export function ProductCard({ product, className }: ProductCardProps) {
+  const t = useTranslations('common');
+  const tp = useTranslations('productDetail');
+  const tProd = useTranslations('products');
+  const router = useRouter();
+  const { refreshCart } = useCart();
+  const fallbackCurrency = useCurrency();
+  // FX overlay (PRD §23): prefer the region-converted display values when the
+  // storefront passed regionId to getProducts. Otherwise fall back to the
+  // canonical store-currency basePrice / salePrice.
+  const display = pickDisplayPrice(product, fallbackCurrency);
+  const { price, originalPrice, isOnSale } = getProductPriceInfo(product);
+  const mainImage = product.images?.[0];
+  const imageUrl = mainImage?.url || null;
+  const slug = product.slug || product.id;
+  const isVariable = product.type === 'VARIABLE';
+
+  const [adding, setAdding] = useState(false);
+  const [added, setAdded] = useState(false);
+
+  const canPurchase = product.inventory?.canPurchase !== false;
+
+  async function handleAddToCart(e: React.MouseEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+
+    if (isVariable) {
+      router.push(`/products/${slug}`);
+      return;
+    }
+
+    if (adding || !canPurchase) return;
+
+    try {
+      setAdding(true);
+      const { getClient } = await import('@/core/lib/brainerce');
+      const client = getClient();
+      await client.smartAddToCart({ productId: product.id, quantity: 1 });
+      await refreshCart();
+      setAdded(true);
+      setTimeout(() => setAdded(false), 2000);
+    } catch (err) {
+      console.error('Failed to add to cart:', err);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <article className={cn(className)}>
+      {/* DESIGN ME — product card (grid/listing unit): image, badges, name, price, stock, add-to-cart; product data arrives as a prop from useHomeData()/useProductListing(). Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
+      <figure>
+        <Link href={`/products/${slug}`}>
+          {/* `relative` + `aspect-square` are layout-critical for next/image fill */}
+          <div className="relative aspect-square">
+            {imageUrl ? (
+              <Image
+                src={imageUrl}
+                alt={mainImage?.alt || product.name}
+                fill
+                sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 25vw"
+              />
+            ) : (
+              <span className="sr-only">{product.name}</span>
+            )}
+          </div>
+        </Link>
+        <figcaption className="sr-only">{product.name}</figcaption>
+      </figure>
+
+      {/* Badges */}
+      <div className="flex flex-wrap gap-1">
+        {isOnSale && <span>{t('sale')}</span>}
+        <DiscountBadge discount={product.discount} />
+        {product.isDownloadable && <span>{tp('digitalProduct')}</span>}
+      </div>
+
+      {/* Categories */}
+      {product.categories && product.categories.length > 0 && (
+        <ul className="flex flex-wrap gap-1">
+          {product.categories.slice(0, 2).map((cat) => (
+            <li key={cat.id}>{cat.name}</li>
+          ))}
+        </ul>
+      )}
+
+      {/* Name — clickable */}
+      <h3>
+        <Link href={`/products/${slug}`}>{product.name}</Link>
+      </h3>
+
+      {/* Price */}
+      {isVariable ? (
+        <VariantPriceRange product={product} />
+      ) : (
+        <PriceDisplay
+          price={display.price ?? originalPrice}
+          salePrice={display.salePrice ?? (isOnSale ? price : undefined)}
+          currency={display.currency}
+          size="sm"
+        />
+      )}
+
+      {/* Stock */}
+      <StockBadge inventory={product.inventory} />
+
+      {/* Add to cart (variable products route to the product page for option selection) */}
+      {(isVariable || canPurchase) && (
+        <button type="button" onClick={handleAddToCart} disabled={adding}>
+          {added ? tp('addedToCart') : isVariable ? tProd('selectOptions') : tp('addToCart')}
+        </button>
+      )}
+    </article>
+  );
+}