create-brainerce-store 1.50.1 → 1.51.0

package/templates/nextjs/ui-canvas/product/review-form.tsx

@@ -0,0 +1,269 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { getClient } from '@/core/lib/brainerce';
+import { checkAuthStatus } from '@/core/lib/auth';
+import type { MyProductReview, ProductReview } from 'brainerce';
+
+interface ReviewFormProps {
+  productId: string;
+}
+
+type Stage =
+  | { kind: 'loading' }
+  | { kind: 'signed_out' }
+  | { kind: 'not_eligible'; reason: MyProductReview['reason'] }
+  | { kind: 'submit' }
+  | { kind: 'edit'; review: ProductReview };
+
+/**
+ * Single component that decides which UI to render for a customer on a PDP:
+ * - Loading while we check auth state and eligibility
+ * - Signed out -> sign-in CTA
+ * - Signed in but not eligible -> "purchase this product to review"
+ * - Eligible without review -> submit form
+ * - Eligible with existing review -> edit/delete form (rating + body prefilled)
+ *
+ * DESIGN ME — review submit/edit form; auth via checkAuthStatus(), eligibility
+ * + existing review via getClient().getMyProductReview(productId).
+ */
+export function ReviewForm({ productId }: ReviewFormProps) {
+  const [stage, setStage] = useState<Stage>({ kind: 'loading' });
+
+  useEffect(() => {
+    let cancelled = false;
+    async function load() {
+      const auth = await checkAuthStatus();
+      if (cancelled) return;
+      if (!auth.isLoggedIn) {
+        setStage({ kind: 'signed_out' });
+        return;
+      }
+      try {
+        const me = await getClient().getMyProductReview(productId);
+        if (cancelled) return;
+        if (!me.eligible) {
+          setStage({ kind: 'not_eligible', reason: me.reason });
+          return;
+        }
+        if (me.myReview) {
+          setStage({ kind: 'edit', review: me.myReview });
+          return;
+        }
+        setStage({ kind: 'submit' });
+      } catch {
+        if (!cancelled) setStage({ kind: 'not_eligible', reason: 'product_not_found' });
+      }
+    }
+    void load();
+    return () => {
+      cancelled = true;
+    };
+  }, [productId]);
+
+  if (stage.kind === 'loading') {
+    return <p role="status">Loading…</p>;
+  }
+
+  if (stage.kind === 'signed_out') {
+    return (
+      <p>
+        <a href="/account/login">Sign in</a> to leave a review for this product.
+      </p>
+    );
+  }
+
+  if (stage.kind === 'not_eligible') {
+    return <NotEligibleMessage reason={stage.reason} />;
+  }
+
+  if (stage.kind === 'edit') {
+    return (
+      <EditReviewBlock
+        productId={productId}
+        initial={stage.review}
+        onDeleted={() => setStage({ kind: 'submit' })}
+      />
+    );
+  }
+
+  return <SubmitReviewBlock productId={productId} />;
+}
+
+function NotEligibleMessage({ reason }: { reason: MyProductReview['reason'] }) {
+  let message: string;
+  switch (reason) {
+    case 'no_eligible_order':
+      message = 'Only customers who purchased this product can leave a review.';
+      break;
+    case 'reviews_disabled':
+      message = 'Reviews are not enabled for this store.';
+      break;
+    default:
+      message = 'You cannot review this product right now.';
+  }
+  return <p>{message}</p>;
+}
+
+function SubmitReviewBlock({ productId }: { productId: string }) {
+  return <ReviewEditor productId={productId} mode="create" initialRating={5} initialBody="" />;
+}
+
+function EditReviewBlock({
+  productId,
+  initial,
+  onDeleted,
+}: {
+  productId: string;
+  initial: ProductReview;
+  onDeleted: () => void;
+}) {
+  const [deleting, setDeleting] = useState(false);
+  const [deleteError, setDeleteError] = useState<string | null>(null);
+
+  async function handleDelete() {
+    if (!window.confirm('Delete your review for this product?')) return;
+    setDeleting(true);
+    setDeleteError(null);
+    try {
+      await getClient().deleteMyProductReview(productId);
+      onDeleted();
+      window.location.reload();
+    } catch {
+      setDeleteError('Could not delete your review. Please try again.');
+    } finally {
+      setDeleting(false);
+    }
+  }
+
+  return (
+    <div>
+      <ReviewEditor
+        productId={productId}
+        mode="edit"
+        initialRating={initial.rating}
+        initialBody={initial.body ?? ''}
+      />
+      <div className="flex items-center gap-2">
+        <p>Want to start over? You can delete your review.</p>
+        <button type="button" onClick={handleDelete} disabled={deleting}>
+          {deleting ? 'Deleting…' : 'Delete review'}
+        </button>
+      </div>
+      {deleteError && <p role="alert">{deleteError}</p>}
+    </div>
+  );
+}
+
+/**
+ * The actual form. Same shape for create and edit — only the API method
+ * and the heading differ. Optimistic UX: success state + page reload to
+ * let the server-rendered reviews list pick up the change.
+ */
+function ReviewEditor({
+  productId,
+  mode,
+  initialRating,
+  initialBody,
+}: {
+  productId: string;
+  mode: 'create' | 'edit';
+  initialRating: number;
+  initialBody: string;
+}) {
+  const [rating, setRating] = useState(initialRating);
+  const [body, setBody] = useState(initialBody);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [success, setSuccess] = useState(false);
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setError(null);
+    setSubmitting(true);
+    try {
+      const client = getClient();
+      const input = { rating, body: body.trim() || undefined };
+      if (mode === 'edit') {
+        await client.updateMyProductReview(productId, input);
+      } else {
+        await client.submitProductReview(productId, input);
+      }
+      setSuccess(true);
+      setTimeout(() => window.location.reload(), 1200);
+    } catch (err) {
+      const status = (err as { status?: number })?.status;
+      if (status === 409) {
+        setError("You've already submitted a review for this product.");
+      } else if (status === 403) {
+        setError('Only customers who purchased this product can leave a review.');
+      } else if (status === 429) {
+        setError('Too many submissions. Please try again in a few minutes.');
+      } else {
+        setError(
+          mode === 'edit'
+            ? 'Could not update your review. Please try again.'
+            : 'Could not submit your review. Please try again.'
+        );
+      }
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  if (success) {
+    return (
+      <p role="status">
+        {mode === 'edit'
+          ? 'Thanks! Your review has been updated.'
+          : 'Thanks! Your review has been submitted.'}
+      </p>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h3>{mode === 'edit' ? 'Edit your review' : 'Write a review'}</h3>
+
+      <fieldset>
+        <legend>Your rating</legend>
+        <div className="inline-flex gap-1" role="radiogroup" aria-label="Star rating">
+          {[1, 2, 3, 4, 5].map((n) => (
+            <button
+              key={n}
+              type="button"
+              role="radio"
+              aria-checked={rating === n}
+              onClick={() => setRating(n)}
+            >
+              {n <= rating ? '★' : '☆'}
+            </button>
+          ))}
+        </div>
+      </fieldset>
+
+      <label className="block">
+        Your review <span>(optional)</span>
+        <textarea
+          value={body}
+          onChange={(event) => setBody(event.target.value)}
+          maxLength={5000}
+          rows={4}
+          className="block w-full"
+        />
+      </label>
+
+      {error && <p role="alert">{error}</p>}
+
+      <button type="submit" disabled={submitting}>
+        {submitting
+          ? mode === 'edit'
+            ? 'Saving…'
+            : 'Submitting…'
+          : mode === 'edit'
+            ? 'Save changes'
+            : 'Submit review'}
+      </button>
+    </form>
+  );
+}

package/templates/nextjs/ui-canvas/product/reviews-section.tsx

@@ -0,0 +1,78 @@
+import type { ProductReview } from 'brainerce';
+import { getServerClient } from '@/core/lib/brainerce';
+import { ReviewForm } from './review-form';
+
+interface ReviewsSectionProps {
+  productId: string;
+  initialReviews?: ProductReview[];
+  /** Where to send users back to after submit (defaults to the current product URL). */
+  returnUrl?: string;
+}
+
+/**
+ * Renders the visible reviews for a product plus a submit form.
+ *
+ * Server component — fetches with the SDK on the server so reviews are in
+ * the initial HTML payload (good for SEO; JSON-LD on the same page already
+ * carries `aggregateRating` when reviewCount > 0).
+ */
+export async function ReviewsSection({ productId, initialReviews }: ReviewsSectionProps) {
+  let reviews: ProductReview[] = initialReviews ?? [];
+
+  if (!initialReviews) {
+    try {
+      const result = await getServerClient().listProductReviews(productId, { page: 1, limit: 20 });
+      reviews = result.data;
+    } catch {
+      // Reviews disabled at store level or network error — render the form anyway.
+      reviews = [];
+    }
+  }
+
+  return (
+    <section aria-labelledby="reviews-heading">
+      {/* DESIGN ME — product reviews: server-fetched review list (SDK listProductReviews) + eligibility-aware submit form */}
+      <h2 id="reviews-heading">Reviews</h2>
+
+      {reviews.length === 0 ? (
+        <p>No reviews yet — be the first to share your experience.</p>
+      ) : (
+        <ul>
+          {reviews.map((review) => (
+            <ReviewCard key={review.id} review={review} />
+          ))}
+        </ul>
+      )}
+
+      <ReviewForm productId={productId} />
+    </section>
+  );
+}
+
+function ReviewCard({ review }: { review: ProductReview }) {
+  return (
+    <li>
+      <article>
+        <header className="flex flex-wrap items-center gap-2">
+          <Stars rating={review.rating} />
+          <span>{review.authorName}</span>
+          {review.verifiedPurchase && <span>Verified purchase</span>}
+          <time dateTime={review.createdAt}>{new Date(review.createdAt).toLocaleDateString()}</time>
+        </header>
+        {review.body && <p className="whitespace-pre-line break-words">{review.body}</p>}
+      </article>
+    </li>
+  );
+}
+
+function Stars({ rating }: { rating: number }) {
+  return (
+    <span aria-label={`${rating} of 5 stars`}>
+      {[1, 2, 3, 4, 5].map((n) => (
+        <span key={n} aria-hidden="true">
+          {n <= rating ? '★' : '☆'}
+        </span>
+      ))}
+    </span>
+  );
+}

package/templates/nextjs/ui-canvas/product/stock-badge.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import type { InventoryInfo } from 'brainerce';
+import { cn } from '@/core/lib/utils';
+import { useTranslations } from '@/core/lib/translations';
+
+interface StockBadgeProps {
+  inventory: InventoryInfo | null | undefined;
+  lowStockThreshold?: number;
+  className?: string;
+}
+
+/**
+ * DESIGN ME — stock status badge (in stock / low stock / out of stock);
+ * derives the label from the product/variant `inventory` prop. Keep the
+ * label logic; add your own tones per state.
+ */
+export function StockBadge({ inventory, lowStockThreshold = 5, className }: StockBadgeProps) {
+  const t = useTranslations('productDetail');
+  const label = getStockLabel(inventory, lowStockThreshold, t);
+
+  return <span className={cn(className)}>{label}</span>;
+}
+
+function getStockLabel(
+  inventory: InventoryInfo | null | undefined,
+  lowStockThreshold: number,
+  t: (key: string) => string
+): string {
+  if (!inventory) return t('outOfStock');
+
+  const { trackingMode, inStock, available } = inventory;
+
+  if (trackingMode === 'DISABLED') return t('unavailable');
+  if (!inStock) return t('outOfStock');
+  if (trackingMode === 'UNLIMITED') return t('inStock');
+
+  // TRACKED — show actual quantity
+  if (available <= lowStockThreshold) {
+    return t('onlyLeft').replace('{available}', String(available));
+  }
+  return t('availableInStock').replace('{available}', String(available));
+}

package/templates/nextjs/ui-canvas/product/variant-selector.tsx

@@ -0,0 +1,210 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { Product, ProductVariant } from 'brainerce';
+import { getVariantOptions, getProductSwatches, formatPrice } from 'brainerce';
+import type { InventoryInfo } from 'brainerce';
+import { useCurrency } from '@/core/lib/use-currency';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+
+interface VariantSelectorProps {
+  product: Product;
+  selectedVariant: ProductVariant | null;
+  onVariantChange: (variant: ProductVariant) => void;
+  className?: string;
+}
+
+interface AttributeGroup {
+  name: string;
+  displayType: string;
+  values: Array<{
+    value: string;
+    swatchColor?: string | null;
+    swatchColor2?: string | null;
+    swatchImageUrl?: string | null;
+    variants: ProductVariant[];
+  }>;
+}
+
+/**
+ * DESIGN ME — variant selector on the product page: one group per attribute
+ * (Size, Color, …) with selectable values. Selection state and the matching
+ * logic below are the contract; the merchant's swatch metadata
+ * (`displayType`, `swatchColor`, `swatchColor2`, `swatchImageUrl`) is
+ * computed per value — the skeleton renders plain buttons, use the swatch
+ * data to build color/image swatches in your design.
+ */
+export function VariantSelector({
+  product,
+  selectedVariant,
+  onVariantChange,
+  className,
+}: VariantSelectorProps) {
+  const t = useTranslations('productDetail');
+  const currency = useCurrency();
+  const variants = useMemo(() => product.variants || [], [product.variants]);
+
+  // Get swatch metadata from product attribute options
+  const swatchData = useMemo(() => getProductSwatches(product), [product]);
+  const swatchMap = useMemo(() => {
+    const map = new Map<
+      string,
+      {
+        displayType: string;
+        options: Map<
+          string,
+          {
+            swatchColor?: string | null;
+            swatchColor2?: string | null;
+            swatchImageUrl?: string | null;
+          }
+        >;
+      }
+    >();
+    for (const attr of swatchData) {
+      const optMap = new Map<
+        string,
+        {
+          swatchColor?: string | null;
+          swatchColor2?: string | null;
+          swatchImageUrl?: string | null;
+        }
+      >();
+      for (const opt of attr.options) {
+        optMap.set(opt.name, {
+          swatchColor: opt.swatchColor,
+          swatchColor2: opt.swatchColor2,
+          swatchImageUrl: opt.swatchImageUrl,
+        });
+      }
+      map.set(attr.attributeName, { displayType: attr.displayType, options: optMap });
+    }
+    return map;
+  }, [swatchData]);
+
+  // Build attribute groups from variant data, enriched with swatch info
+  const attributeGroups = useMemo<AttributeGroup[]>(() => {
+    const groups = new Map<string, Map<string, ProductVariant[]>>();
+
+    for (const variant of variants) {
+      const options = getVariantOptions(variant);
+      for (const { name, value } of options) {
+        if (!groups.has(name)) {
+          groups.set(name, new Map());
+        }
+        const valuesMap = groups.get(name)!;
+        if (!valuesMap.has(value)) {
+          valuesMap.set(value, []);
+        }
+        valuesMap.get(value)!.push(variant);
+      }
+    }
+
+    return Array.from(groups.entries()).map(([name, valuesMap]) => {
+      const attrSwatch = swatchMap.get(name);
+      return {
+        name,
+        displayType: attrSwatch?.displayType || 'DROPDOWN',
+        values: Array.from(valuesMap.entries()).map(([value, variantList]) => {
+          const optSwatch = attrSwatch?.options.get(value);
+          return {
+            value,
+            swatchColor: optSwatch?.swatchColor,
+            swatchColor2: optSwatch?.swatchColor2,
+            swatchImageUrl: optSwatch?.swatchImageUrl,
+            variants: variantList,
+          };
+        }),
+      };
+    });
+  }, [variants, swatchMap]);
+
+  // Get currently selected attribute values
+  const selectedOptions = useMemo(() => {
+    if (!selectedVariant) return new Map<string, string>();
+    const opts = getVariantOptions(selectedVariant);
+    return new Map(opts.map(({ name, value }) => [name, value]));
+  }, [selectedVariant]);
+
+  // Find the variant that matches all selected attributes
+  function findMatchingVariant(
+    attributeName: string,
+    newValue: string
+  ): ProductVariant | undefined {
+    const nextSelection = new Map(selectedOptions);
+    nextSelection.set(attributeName, newValue);
+
+    return variants.find((v) => {
+      const opts = getVariantOptions(v);
+      return Array.from(nextSelection.entries()).every(([name, value]) =>
+        opts.some((o) => o.name === name && o.value === value)
+      );
+    });
+  }
+
+  if (attributeGroups.length === 0) return null;
+
+  return (
+    <div className={cn(className)}>
+      {attributeGroups.map((group) => (
+        <fieldset key={group.name} data-display-type={group.displayType}>
+          <legend>
+            {group.name}
+            {selectedOptions.get(group.name) && <span>: {selectedOptions.get(group.name)}</span>}
+          </legend>
+          <div className="flex flex-wrap gap-2">
+            {group.values.map(({ value, variants: matchingVariants }) => {
+              const isSelected = selectedOptions.get(group.name) === value;
+              const matchedVariant = findMatchingVariant(group.name, value);
+              const isAvailable = matchedVariant?.inventory?.canPurchase !== false;
+
+              return (
+                <button
+                  key={value}
+                  type="button"
+                  disabled={!isAvailable}
+                  aria-pressed={isSelected}
+                  onClick={() => {
+                    const variant = matchedVariant || matchingVariants[0];
+                    if (variant) onVariantChange(variant);
+                  }}
+                >
+                  {value}
+                </button>
+              );
+            })}
+          </div>
+        </fieldset>
+      ))}
+
+      {/* Variant-specific info */}
+      {selectedVariant && (
+        <p>
+          {selectedVariant.price && (
+            <span>
+              {
+                formatPrice(selectedVariant.salePrice || selectedVariant.price, {
+                  currency,
+                }) as string
+              }
+            </span>
+          )}{' '}
+          <span>{getTranslatedStockStatus(selectedVariant.inventory, t)}</span>
+        </p>
+      )}
+    </div>
+  );
+}
+
+function getTranslatedStockStatus(
+  inventory: InventoryInfo | null | undefined,
+  t: (key: string) => string
+): string {
+  if (!inventory) return t('outOfStock');
+  const { trackingMode, inStock, available } = inventory;
+  if (trackingMode === 'DISABLED') return t('unavailable');
+  if (!inStock) return t('outOfStock');
+  if (trackingMode === 'UNLIMITED') return t('inStock');
+  return t('availableInStock').replace('{available}', String(available));
+}

package/templates/nextjs/ui-canvas/shared/cdn-image.tsx

@@ -0,0 +1,29 @@
+import Image, { type ImageProps } from 'next/image';
+import { OPTIMIZED_IMAGE_HOSTS } from '@/core/lib/image-hosts';
+
+const OPTIMIZED_HOSTS = new Set(OPTIMIZED_IMAGE_HOSTS);
+
+function isOptimizedHost(src: ImageProps['src']): boolean {
+  if (typeof src !== 'string') return true; // StaticImageData — always local
+  try {
+    return OPTIMIZED_HOSTS.has(new URL(src).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drop-in `next/image` replacement for Brainerce-sourced images (product
+ * photos, blog covers). Uploaded images get re-hosted onto cdn.brainerce.com
+ * by the backend's async image-import pipeline, but a product/variant can
+ * still carry a raw upstream-merchant URL while mid-import, or if that job
+ * failed. next/image throws if `src`'s host isn't in `images.remotePatterns`,
+ * so any host outside our known CDN falls back to `unoptimized` — an
+ * unresized, direct-from-origin fetch — instead of crashing the page.
+ *
+ * DESIGN ME — shared image wrapper; render ALL catalog images through this
+ * component (not raw next/image) so unknown hosts never crash the page.
+ */
+export function CdnImage({ unoptimized, ...props }: ImageProps) {
+  return <Image {...props} unoptimized={unoptimized ?? !isOptimizedHost(props.src)} />;
+}

package/templates/nextjs/ui-canvas/shared/loading-spinner.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+
+interface LoadingSpinnerProps {
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+/**
+ * DESIGN ME — loading indicator used by every page and async button. Bare
+ * text placeholder; replace with your own spinner/skeleton. Keep the
+ * `role="status"` + sr-only label, and keep the `size` prop (callers across
+ * the app pass sm/md/lg).
+ */
+export function LoadingSpinner({ size = 'md', className }: LoadingSpinnerProps) {
+  const t = useTranslations('common');
+  return (
+    <span role="status" data-size={size} className={cn(className)}>
+      <span aria-hidden="true">…</span>
+      <span className="sr-only">{t('loading')}</span>
+    </span>
+  );
+}