create-brainerce-store 1.50.5 → 1.52.0

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

@@ -0,0 +1,99 @@
+'use client';
+
+import { Link } from '@/core/lib/navigation';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import type { ProductRecommendation } from 'brainerce';
+import { PriceDisplay } from '@/ui/product/price-display';
+import { cn } from '@/core/lib/utils';
+
+interface RecommendationCardProps {
+  item: ProductRecommendation;
+  className?: string;
+}
+
+function RecommendationCard({ item, className }: RecommendationCardProps) {
+  const firstImage = item.images?.[0];
+  const imageUrl = typeof firstImage === 'string' ? firstImage : firstImage?.url || null;
+  const slug = item.slug || item.id;
+  const basePrice = parseFloat(item.basePrice);
+  const salePrice = item.salePrice ? parseFloat(item.salePrice) : undefined;
+  const isOnSale = salePrice != null && salePrice < basePrice;
+
+  return (
+    <Link href={`/products/${slug}`} className={cn(className)}>
+      {/* `relative` + `aspect-square` are layout-critical for next/image fill */}
+      <span className="relative block aspect-square">
+        {imageUrl ? (
+          <Image
+            src={imageUrl}
+            alt={item.name}
+            fill
+            sizes="(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 20vw"
+          />
+        ) : null}
+      </span>
+      <span className="block">
+        <span className="block">{item.name}</span>
+        <PriceDisplay price={basePrice} salePrice={isOnSale ? salePrice : undefined} size="sm" />
+      </span>
+    </Link>
+  );
+}
+
+interface RecommendationSectionProps {
+  title: string;
+  items: ProductRecommendation[];
+  className?: string;
+}
+
+/**
+ * DESIGN ME — recommendation strip on the product page (upsells / related);
+ * items come from useProductPage().recommendations, title is passed in.
+ *
+ * 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 RecommendationSection({ title, items, className }: RecommendationSectionProps) {
+  if (items.length === 0) return null;
+
+  return (
+    <section className={cn(className)}>
+      <h2>{title}</h2>
+      <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
+        {items.map((item) => (
+          <RecommendationCard key={item.id} item={item} />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+interface CartRecommendationSectionProps {
+  title: string;
+  items: ProductRecommendation[];
+  className?: string;
+}
+
+/**
+ * DESIGN ME — cross-sell strip on the cart page ("you might also need");
+ * items come from useCartPage().cartRecs.
+ *
+ * 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 CartRecommendationSection({
+  title,
+  items,
+  className,
+}: CartRecommendationSectionProps) {
+  if (items.length === 0) return null;
+
+  return (
+    <section className={cn(className)}>
+      <h2>{title}</h2>
+      <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
+        {items.map((item) => (
+          <RecommendationCard key={item.id} item={item} />
+        ))}
+      </div>
+    </section>
+  );
+}

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

@@ -0,0 +1,266 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { getClient } from '@/core/lib/brainerce';
+import { checkAuthStatus } from '@/core/lib/auth';
+import { useTranslations } from '@/core/lib/translations';
+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).
+ *
+ * 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 ReviewForm({ productId }: ReviewFormProps) {
+  const [stage, setStage] = useState<Stage>({ kind: 'loading' });
+  const t = useTranslations('reviews');
+
+  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">{t('loading')}</p>;
+  }
+
+  if (stage.kind === 'signed_out') {
+    return (
+      <p>
+        <a href="/account/login">{t('signIn')}</a> {t('signInSuffix')}
+      </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'] }) {
+  const t = useTranslations('reviews');
+  let message: string;
+  switch (reason) {
+    case 'no_eligible_order':
+      message = t('onlyPurchasers');
+      break;
+    case 'reviews_disabled':
+      message = t('reviewsDisabled');
+      break;
+    default:
+      message = t('cannotReview');
+  }
+  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 t = useTranslations('reviews');
+  const [deleteError, setDeleteError] = useState<string | null>(null);
+
+  async function handleDelete() {
+    if (!window.confirm(t('confirmDelete'))) return;
+    setDeleting(true);
+    setDeleteError(null);
+    try {
+      await getClient().deleteMyProductReview(productId);
+      onDeleted();
+      window.location.reload();
+    } catch {
+      setDeleteError(t('deleteFailed'));
+    } finally {
+      setDeleting(false);
+    }
+  }
+
+  return (
+    <div>
+      <ReviewEditor
+        productId={productId}
+        mode="edit"
+        initialRating={initial.rating}
+        initialBody={initial.body ?? ''}
+      />
+      <div className="flex items-center gap-2">
+        <p>{t('startOver')}</p>
+        <button type="button" onClick={handleDelete} disabled={deleting}>
+          {deleting ? t('deleting') : t('deleteReview')}
+        </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 t = useTranslations('reviews');
+  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(t('alreadySubmitted'));
+      } else if (status === 403) {
+        setError(t('onlyPurchasers'));
+      } else if (status === 429) {
+        setError(t('tooMany'));
+      } else {
+        setError(mode === 'edit' ? t('updateFailed') : t('submitFailed'));
+      }
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  if (success) {
+    return <p role="status">{mode === 'edit' ? t('thanksUpdated') : t('thanksSubmitted')}</p>;
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h3>{mode === 'edit' ? t('editYourReview') : t('writeReview')}</h3>
+
+      <fieldset>
+        <legend>{t('yourRating')}</legend>
+        <div className="inline-flex gap-1" role="radiogroup" aria-label={t('starRating')}>
+          {[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">
+        {t('yourReview')} <span>({t('optionalField')})</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'
+            ? t('saving')
+            : t('submittingBtn')
+          : mode === 'edit'
+            ? t('saveChanges')
+            : t('submitReview')}
+      </button>
+    </form>
+  );
+}

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

@@ -0,0 +1,96 @@
+import type { ProductReview } from 'brainerce';
+import { getServerClient } from '@/core/lib/brainerce';
+<% if (i18nEnabled) { %>import { getMessages, defaultLocale } from '@/i18n';<% } else { %>import { defaultLocale, messages } from '@/i18n';<% } %>
+import { ReviewForm } from './review-form';
+
+// Server component — it renders before any client i18n context exists, so the
+// wrapper strings (title / empty state / verified badge) are read straight
+// from the `reviews` namespace in messages/, keyed by the store locale.
+type ReviewStrings = Record<string, string>;
+
+<% if (i18nEnabled) { %>async function getReviewStrings(locale: string): Promise<ReviewStrings> {
+  return ((await getMessages(locale)).reviews ?? {}) as ReviewStrings;
+}<% } else { %>async function getReviewStrings(_locale: string): Promise<ReviewStrings> {
+  return messages.reviews as ReviewStrings;
+}<% } %>
+
+interface ReviewsSectionProps {
+  productId: string;
+  initialReviews?: ProductReview[];
+  locale?: string;
+  /** 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,
+  locale = defaultLocale,
+}: ReviewsSectionProps) {
+  const t = await getReviewStrings(locale);
+  let reviews: ProductReview[] = initialReviews ?? [];
+
+  if (!initialReviews) {
+    try {
+      const result = await getServerClient().listProductReviews(productId, { page: 1, limit: 20 });
+      reviews = result.data;
+    } catch {
+      // Review listing 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. Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
+      <h2 id="reviews-heading">{t.title}</h2>
+
+      {reviews.length === 0 ? (
+        <p>{t.noReviews}</p>
+      ) : (
+        <ul>
+          {reviews.map((review) => (
+            <ReviewCard key={review.id} review={review} verifiedLabel={t.verifiedPurchase} />
+          ))}
+        </ul>
+      )}
+
+      <ReviewForm productId={productId} />
+    </section>
+  );
+}
+
+function ReviewCard({ review, verifiedLabel }: { review: ProductReview; verifiedLabel: string }) {
+  return (
+    <li>
+      <article>
+        <header className="flex flex-wrap items-center gap-2">
+          <Stars rating={review.rating} />
+          <span>{review.authorName}</span>
+          {review.verifiedPurchase && <span>{verifiedLabel}</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,45 @@
+'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.
+ *
+ * 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 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));
+}