@cartbase/storefront 0.1.0

package/src/reviews-ui/review-wizard.tsx

@@ -0,0 +1,560 @@
+"use client"
+
+import { useCallback, useState } from "react"
+import Link from "next/link"
+import { Check, Copy, Gift, Star, X } from "lucide-react"
+import type { StorefrontClient } from "../api/http"
+import {
+  attachReviewPhoto,
+  submitReview,
+  type TokenValidation,
+} from "../api/reviews"
+import { StoreApiError } from "../api/types"
+import { cn } from "../lib/utils"
+import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
+import { MAX_BODY, firstNameOf, formatLabel } from "./helpers"
+import {
+  canSubmitRating,
+  resolveWizardEntry,
+  submitErrorKeyFor,
+  type WizardStep,
+} from "./wizard-state"
+import {
+  ReviewPhotoUpload,
+  readyMedia,
+  type LocalMedia,
+} from "./photo-upload"
+
+/**
+ * The review token wizard — everything behind `<review_link_base>/<token>`.
+ * Ported from the Alenika production storefront: the /review/[token]
+ * server page's branching (page.tsx) AND the two-step client form
+ * (review-form.tsx), merged into one component over the barter SDK:
+ *
+ *   entry:   `resolveWizardEntry(validation)` — invalid/expired panels,
+ *            the terminal "already submitted" panel, or the form at the
+ *            right step. THE RESUME RULE: a consumed token with a review
+ *            row and `reward_code` null resumes at the photo step;
+ *            `reward_code` set opens at done, showing the code.
+ *   rate:    stars + body → `api/reviews.submitReview` (consumes the
+ *            token; the rating is LOCKED IN even if the customer bails
+ *            on step 2). Errors map via status: 429/409/410 → the
+ *            labels' error copy (`submitErrorKeyFor`).
+ *   photo:   optional media upsell (`<ReviewPhotoUpload>`; signed R2
+ *            PUTs) → `api/reviews.attachReviewPhoto` mints the
+ *            single-use reward code. Skippable — skipping keeps the
+ *            rating, just no code. `code: null` in a 200 = media saved
+ *            but the mint failed → the "write to us" note, NEVER an
+ *            error state (production rule).
+ *   done:    thank-you + the code with one-tap copy (select-all backup
+ *            for blocked clipboards).
+ *
+ * The reward is for ATTACHING A PHOTO, never for a positive rating.
+ *
+ * VALIDATE SERVER-SIDE: fetch `api/reviews.validateToken(client, token)`
+ * in the page server component and pass `validation` — rendering the
+ * form before discovering the token is dead would flash a usable form
+ * (production UX rule). The page should also be noindex/nofollow (private
+ * per-customer URL).
+ *
+ * Settings: reward_enabled / reward_percentage (admin → Settings →
+ * Reviews) — the store surface does not expose the percentage, so the
+ * app passes `rewardPct` (default 10, the platform default); moderation
+ * `hold` changes nothing here (the thanks copy stays true — the review
+ * is received; visibility is the store's call).
+ */
+export interface ReviewWizardProps {
+  client: StorefrontClient
+  token: string
+  /** Server-fetched `validateToken` result. */
+  validation: TokenValidation
+  /** Reward percentage shown in the copy (Settings → Reviews). */
+  rewardPct?: number
+  /** Store support email for the failure copy (labels `{email}`). */
+  supportEmail?: string
+  /** Base for the "view product" CTA; joined with the product handle. */
+  productHrefBase?: string
+  /** The "back to the store" CTA target. */
+  storeHref?: string
+  labels?: Partial<ReviewsUiLabels>
+}
+
+export function ReviewWizard({
+  client,
+  token,
+  validation,
+  rewardPct = 10,
+  supportEmail = "",
+  productHrefBase = "/products",
+  storeHref = "/",
+  labels,
+}: ReviewWizardProps) {
+  const l = { ...defaultReviewsUiLabels, ...labels }
+  const entry = resolveWizardEntry(validation)
+
+  // ── Invalid / expired ────────────────────────────────────────────────
+  if (entry.kind === "invalid") {
+    const expired = entry.reason === "expired"
+    return (
+      <StatePanel
+        heading={expired ? l.expiredTitle : l.invalidTitle}
+        sub={formatLabel(expired ? l.expiredBody : l.invalidBody, {
+          email: supportEmail,
+        })}
+      >
+        <Link
+          href={storeHref}
+          className="inline-flex items-center justify-center px-5 py-2.5 rounded-[2px] bg-primary text-primary-foreground text-sm font-medium hover:opacity-90 transition-opacity"
+        >
+          {l.toStore}
+        </Link>
+      </StatePanel>
+    )
+  }
+
+  // (valid:true branches below — narrow once for product/name access)
+  const v = validation as Extract<TokenValidation, { valid: true }>
+  const product = v.product
+
+  // ── Consumed token, no review row — terminal thanks ──────────────────
+  if (entry.kind === "already-submitted") {
+    return (
+      <StatePanel
+        heading={l.alreadyTitle}
+        sub={
+          product
+            ? formatLabel(l.alreadyBodyWithProduct, { name: product.title })
+            : l.alreadyBody
+        }
+      >
+        <div className="flex flex-col sm:flex-row gap-3 justify-center">
+          {product?.handle && (
+            <Link
+              href={`${productHrefBase}/${product.handle}`}
+              className="inline-flex items-center justify-center px-5 py-2.5 rounded-[2px] bg-primary text-primary-foreground text-sm font-medium hover:opacity-90 transition-opacity"
+            >
+              {l.viewProduct}
+            </Link>
+          )}
+          <Link
+            href={storeHref}
+            className="inline-flex items-center justify-center px-5 py-2.5 rounded-[2px] border border-border text-sm font-medium hover:bg-muted transition-colors"
+          >
+            {l.toStore}
+          </Link>
+        </div>
+      </StatePanel>
+    )
+  }
+
+  return (
+    <section className="max-w-2xl mx-auto px-4 sm:px-6 py-10 sm:py-16">
+      {entry.step !== "done" && (
+        <header className="mb-8">
+          <p className="text-xs uppercase tracking-wider text-muted-foreground mb-3">
+            {l.greeting}
+            {v.customer_name ? `, ${firstNameOf(v.customer_name)}` : ""}
+          </p>
+          <h1 className="text-2xl sm:text-3xl font-semibold text-foreground leading-tight">
+            {entry.step === "photo" ? l.headingPhoto : l.headingRate}
+          </h1>
+          <p className="text-sm text-muted-foreground mt-2 leading-relaxed">
+            {entry.step === "photo"
+              ? formatLabel(l.introPhoto, { pct: rewardPct })
+              : l.introRate}
+          </p>
+        </header>
+      )}
+
+      {product && entry.step !== "done" && (
+        <div className="flex items-center gap-4 p-3 rounded-[2px] border border-border bg-muted/30 mb-8">
+          {product.thumbnail ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={product.thumbnail}
+              alt=""
+              width={64}
+              height={64}
+              className="w-16 h-16 object-cover rounded-[2px] bg-muted"
+            />
+          ) : (
+            <div className="w-16 h-16 rounded-[2px] bg-muted" />
+          )}
+          <div className="min-w-0 flex-1">
+            <p className="text-xs uppercase tracking-wider text-muted-foreground">
+              {l.productLabel}
+            </p>
+            <p className="text-sm font-medium truncate text-foreground">
+              {product.title}
+            </p>
+          </div>
+        </div>
+      )}
+
+      <ReviewWizardForm
+        client={client}
+        token={token}
+        productHandle={product?.handle ?? null}
+        productHrefBase={productHrefBase}
+        storeHref={storeHref}
+        rewardPct={rewardPct}
+        supportEmail={supportEmail}
+        initialStep={entry.step}
+        initialReviewId={entry.reviewId}
+        initialRewardCode={entry.rewardCode}
+        labels={l}
+      />
+    </section>
+  )
+}
+
+function StatePanel({
+  heading,
+  sub,
+  children,
+}: {
+  heading: string
+  sub: string
+  children: React.ReactNode
+}) {
+  return (
+    <section className="max-w-md mx-auto px-4 sm:px-6 py-16 sm:py-24 text-center">
+      <h1 className="text-2xl sm:text-3xl font-semibold text-foreground leading-tight">
+        {heading}
+      </h1>
+      <p className="text-sm text-muted-foreground mt-3 leading-relaxed">{sub}</p>
+      <div className="mt-8">{children}</div>
+    </section>
+  )
+}
+
+/** The two-step form (rate → photo → done). Port of review-form.tsx. */
+export function ReviewWizardForm({
+  client,
+  token,
+  productHandle,
+  productHrefBase = "/products",
+  storeHref = "/",
+  rewardPct = 10,
+  supportEmail = "",
+  initialStep = "rate",
+  initialReviewId = null,
+  initialRewardCode = null,
+  labels,
+}: {
+  client: StorefrontClient
+  token: string
+  productHandle: string | null
+  productHrefBase?: string
+  storeHref?: string
+  rewardPct?: number
+  supportEmail?: string
+  initialStep?: WizardStep
+  initialReviewId?: string | null
+  initialRewardCode?: string | null
+  labels?: Partial<ReviewsUiLabels>
+}) {
+  const l = { ...defaultReviewsUiLabels, ...labels }
+  const [step, setStep] = useState<WizardStep>(initialStep)
+  const [rating, setRating] = useState<number>(0)
+  const [hoverRating, setHoverRating] = useState<number>(0)
+  const [body, setBody] = useState("")
+  const [media, setMedia] = useState<LocalMedia[]>([])
+  const [submitting, setSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [reviewId, setReviewId] = useState<string | null>(initialReviewId)
+  const [rewardCode, setRewardCode] = useState<string | null>(initialRewardCode)
+  const [copied, setCopied] = useState(false)
+  // Photo saved but the reward code couldn't be minted (rare). Distinguishes
+  // "no code because they skipped" from "no code because generation failed".
+  const [codeUnavailable, setCodeUnavailable] = useState(false)
+
+  // One-tap copy on the thank-you step. The code is also select-all, so a
+  // blocked clipboard (rare, permissions) still leaves manual copy working.
+  const copyCode = useCallback(async () => {
+    if (!rewardCode) return
+    try {
+      await navigator.clipboard.writeText(rewardCode)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch {
+      /* clipboard blocked — select-all fallback covers it */
+    }
+  }, [rewardCode])
+
+  const uploading = media.some((m) => m._uploading)
+  const hasReadyMedia = media.some((m) => !m._uploading && !m._failed)
+
+  // ── Step 1: submit the rating (locks it in) ──────────────────────────
+  const submitRating = async () => {
+    if (!canSubmitRating(rating, body) || submitting) return
+    setSubmitting(true)
+    setError(null)
+    try {
+      const result = await submitReview(client, {
+        token,
+        rating,
+        body: body.trim(),
+      })
+      setReviewId(result.id)
+      setStep("photo")
+    } catch (err) {
+      const status = err instanceof StoreApiError ? err.status : 0
+      setError(l[submitErrorKeyFor(status)])
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  // ── Step 2: attach the photo(s) + claim the reward ───────────────────
+  const submitPhoto = async () => {
+    if (!reviewId || submitting || uploading) return
+    const ready = readyMedia(media)
+    if (ready.length === 0) return
+
+    setSubmitting(true)
+    setError(null)
+    try {
+      const result = await attachReviewPhoto(client, reviewId, {
+        token,
+        media: ready,
+      })
+      setRewardCode(result.code)
+      setCodeUnavailable(result.code === null)
+      setStep("done")
+    } catch {
+      // 400 invalid_data / 403 forbidden / 404 not_found — one user-facing
+      // copy: the photo could not be saved (the media itself is retryable).
+      setError(l.errPhotoSave)
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  const skipPhoto = () => setStep("done")
+
+  // ── Step: done ───────────────────────────────────────────────────────
+  if (step === "done") {
+    return (
+      <div className="rounded-[2px] border border-border bg-muted/30 p-6 text-center">
+        <p className="text-lg font-medium text-foreground">{l.thanksTitle}</p>
+        <p className="text-sm text-muted-foreground mt-2">{l.thanksBody}</p>
+
+        {rewardCode && (
+          <div className="mt-6 rounded-[2px] border border-border bg-background p-5">
+            <div className="inline-flex items-center gap-2 text-sm font-medium text-foreground">
+              <Gift className="w-4 h-4" />
+              {formatLabel(l.rewardTitle, { pct: rewardPct })}
+            </div>
+            <div className="mt-3 flex items-center justify-center gap-2">
+              <span className="select-all font-mono text-lg font-semibold tracking-wider text-foreground">
+                {rewardCode}
+              </span>
+              <button
+                type="button"
+                onClick={copyCode}
+                aria-label={l.copyAria}
+                className="inline-flex items-center gap-1.5 rounded-[2px] border border-border px-2.5 py-1.5 text-xs font-medium text-foreground hover:bg-muted transition-colors"
+              >
+                {copied ? (
+                  <>
+                    <Check className="w-3.5 h-3.5" />
+                    {l.copied}
+                  </>
+                ) : (
+                  <>
+                    <Copy className="w-3.5 h-3.5" />
+                    {l.copy}
+                  </>
+                )}
+              </button>
+            </div>
+            <p className="text-xs text-muted-foreground mt-2">{l.rewardNote}</p>
+          </div>
+        )}
+
+        {!rewardCode && codeUnavailable && (
+          <p className="mt-6 text-sm text-muted-foreground">
+            {formatLabel(l.codeUnavailable, { email: supportEmail })}
+          </p>
+        )}
+
+        <div className="mt-6 flex flex-col sm:flex-row gap-3 justify-center">
+          {productHandle && (
+            <Link
+              href={`${productHrefBase}/${productHandle}`}
+              className="inline-flex items-center justify-center px-5 py-2.5 rounded-[2px] bg-primary text-primary-foreground text-sm font-medium hover:opacity-90 transition-opacity"
+            >
+              {l.viewProduct}
+            </Link>
+          )}
+          <Link
+            href={storeHref}
+            className="inline-flex items-center justify-center px-5 py-2.5 rounded-[2px] border border-border text-sm font-medium hover:bg-muted transition-colors"
+          >
+            {l.toStore}
+          </Link>
+        </div>
+      </div>
+    )
+  }
+
+  // ── Step: photo upsell ───────────────────────────────────────────────
+  if (step === "photo") {
+    return (
+      <div className="relative rounded-[2px] border border-border bg-background p-5 sm:p-6">
+        <button
+          type="button"
+          onClick={skipPhoto}
+          aria-label={l.skipAria}
+          className="absolute top-3 right-3 w-9 h-9 rounded-full hover:bg-muted text-muted-foreground flex items-center justify-center"
+        >
+          <X className="w-5 h-5" />
+        </button>
+
+        <div className="inline-flex items-center gap-1.5 rounded-full bg-primary/10 px-3 py-1 text-xs font-bold uppercase tracking-wider text-primary">
+          <Gift className="w-3.5 h-3.5" />
+          {l.bonusBadge}
+        </div>
+        <h2 className="text-xl sm:text-2xl font-semibold text-foreground mt-3 leading-tight">
+          {formatLabel(l.photoTitle, { pct: rewardPct })}
+        </h2>
+        <p className="text-sm text-muted-foreground mt-2 leading-relaxed">
+          {formatLabel(l.photoSubtitle, { pct: rewardPct })}
+        </p>
+
+        <ReviewPhotoUpload
+          client={client}
+          token={token}
+          media={media}
+          onChange={setMedia}
+          onError={setError}
+          labels={l}
+        />
+
+        {error && (
+          <div className="mt-4 rounded-[2px] border border-destructive/40 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+            {error}
+          </div>
+        )}
+
+        <div className="mt-6 flex items-center justify-between gap-4">
+          <button
+            type="button"
+            onClick={skipPhoto}
+            className="text-sm text-muted-foreground hover:text-foreground transition-colors"
+          >
+            {l.skip}
+          </button>
+          <button
+            type="button"
+            onClick={submitPhoto}
+            disabled={!hasReadyMedia || submitting || uploading}
+            className={cn(
+              "inline-flex items-center justify-center px-6 py-3 rounded-[2px] bg-primary text-primary-foreground text-sm font-medium transition-opacity flex-shrink-0",
+              !hasReadyMedia || submitting || uploading
+                ? "opacity-50 cursor-not-allowed"
+                : "hover:opacity-90"
+            )}
+          >
+            {submitting
+              ? l.submitting
+              : uploading
+                ? l.waitingUpload
+                : formatLabel(l.submitPhoto, { pct: rewardPct })}
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  // ── Step: rate (default) ─────────────────────────────────────────────
+  return (
+    <div className="space-y-6">
+      {/* Star picker */}
+      <div>
+        <label className="block text-xs uppercase tracking-wider text-muted-foreground mb-2">
+          {l.ratingLabel}
+        </label>
+        <div
+          className="flex items-center gap-1.5"
+          onMouseLeave={() => setHoverRating(0)}
+        >
+          {[1, 2, 3, 4, 5].map((v) => {
+            const filled = v <= (hoverRating || rating)
+            return (
+              <button
+                key={v}
+                type="button"
+                onMouseEnter={() => setHoverRating(v)}
+                onClick={() => setRating(v)}
+                aria-label={formatLabel(l.ratingAria, { n: v })}
+                className="p-1 transition-transform hover:scale-110"
+              >
+                <Star
+                  className={cn(
+                    "w-8 h-8",
+                    filled
+                      ? "fill-warning text-warning"
+                      : "fill-muted text-muted-foreground"
+                  )}
+                  strokeWidth={0}
+                />
+              </button>
+            )
+          })}
+          {rating > 0 && (
+            <span className="ml-3 text-sm text-muted-foreground">
+              {formatLabel(l.ratingOutOf, { n: rating })}
+            </span>
+          )}
+        </div>
+      </div>
+
+      {/* Body */}
+      <div>
+        <label
+          htmlFor="review-body"
+          className="block text-xs uppercase tracking-wider text-muted-foreground mb-2"
+        >
+          {l.bodyLabel}
+        </label>
+        <textarea
+          id="review-body"
+          value={body}
+          onChange={(e) => setBody(e.target.value.slice(0, MAX_BODY))}
+          maxLength={MAX_BODY}
+          rows={5}
+          placeholder={l.bodyPlaceholder}
+          className="w-full px-4 py-2.5 rounded-[2px] border border-border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30 resize-y"
+        />
+        <div className="text-xs text-muted-foreground mt-1 text-right">
+          {body.length} / {MAX_BODY}
+        </div>
+      </div>
+
+      {error && (
+        <div className="rounded-[2px] border border-destructive/40 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+          {error}
+        </div>
+      )}
+
+      <div className="flex items-center justify-between gap-4">
+        <p className="text-xs text-muted-foreground">{l.consentNote}</p>
+        <button
+          type="button"
+          onClick={submitRating}
+          disabled={!canSubmitRating(rating, body) || submitting}
+          className={cn(
+            "inline-flex items-center justify-center px-6 py-3 rounded-[2px] bg-primary text-primary-foreground text-sm font-medium transition-opacity flex-shrink-0",
+            !canSubmitRating(rating, body) || submitting
+              ? "opacity-50 cursor-not-allowed"
+              : "hover:opacity-90"
+          )}
+        >
+          {submitting ? l.submitting : l.continue}
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/reviews-ui/star-badge.tsx

@@ -0,0 +1,104 @@
+import { Star } from "lucide-react"
+import { cn } from "../lib/utils"
+import type { ReviewAggregate } from "../api/reviews"
+import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
+import { reviewCountLabel } from "./helpers"
+
+/**
+ * Star primitives + the PDP aggregate badge. Ported from the Alenika
+ * reviews section header (src/components/product/reviews-list.tsx —
+ * `StarRow` + the overall-score block). Pure render, server-safe: data
+ * arrives via props (`api/reviews.getAggregate` / `getWidget().aggregate`).
+ */
+
+/** Five-star row, filled to `Math.round(rating)`. */
+export function StarRow({
+  rating,
+  className,
+}: {
+  rating: number
+  className?: string
+}) {
+  return (
+    <span className={cn("inline-flex items-center gap-0.5", className)}>
+      {Array.from({ length: 5 }).map((_, i) => (
+        <Star
+          key={i}
+          className={cn(
+            "w-3.5 h-3.5",
+            i < Math.round(rating)
+              ? "fill-warning text-warning"
+              : "fill-muted text-muted-foreground"
+          )}
+          strokeWidth={0}
+        />
+      ))}
+    </span>
+  )
+}
+
+export interface StarBadgeProps {
+  aggregate: Pick<ReviewAggregate, "count" | "avg_rating">
+  labels?: Pick<ReviewsUiLabels, "reviewSingular" | "reviewPlural">
+  className?: string
+}
+
+/**
+ * The big score badge: filled star + avg (1 decimal) + "{n} reviews".
+ * Renders nothing when there are no reviews (matching the production
+ * "hide the section entirely" rule).
+ */
+export function StarBadge({ aggregate, labels, className }: StarBadgeProps) {
+  const l = { ...defaultReviewsUiLabels, ...labels }
+  if (!aggregate.count) return null
+  return (
+    <div className={cn("flex items-center gap-3 shrink-0", className)}>
+      <Star className="w-10 h-10 fill-warning text-warning" strokeWidth={0} />
+      <div>
+        <div className="text-3xl font-bold text-foreground leading-none">
+          {aggregate.avg_rating.toFixed(1)}
+        </div>
+        <div className="text-sm text-muted-foreground mt-1.5">
+          {reviewCountLabel(aggregate.count, l)}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export interface RatingDistributionProps {
+  distribution: ReviewAggregate["distribution"]
+  /** Total review count (bar percentages). */
+  total: number
+  className?: string
+}
+
+/** The 5→1 distribution bars block from the section header. */
+export function RatingDistribution({
+  distribution,
+  total,
+  className,
+}: RatingDistributionProps) {
+  return (
+    <div className={cn("w-full md:max-w-sm space-y-1.5", className)}>
+      {([5, 4, 3, 2, 1] as const).map((s) => {
+        const c = distribution[String(s) as "1" | "2" | "3" | "4" | "5"] ?? 0
+        const pct = total > 0 ? Math.round((c / total) * 100) : 0
+        return (
+          <div key={s} className="flex items-center gap-3">
+            <StarRow rating={s} className="shrink-0" />
+            <div className="flex-1 h-2 rounded-full bg-muted overflow-hidden">
+              <div
+                className="h-full bg-foreground/80"
+                style={{ width: `${pct}%` }}
+              />
+            </div>
+            <span className="w-9 text-right text-xs text-muted-foreground tabular-nums">
+              ({c})
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}