@tribe-nest/forge 1.13.0

package/src/ui/styled/ReviewForm.tsx

@@ -0,0 +1,292 @@
+import { useState } from "react";
+import { CheckCircle2, Clock, Star } from "lucide-react";
+import { useReviewForm as useReviewFormFlow } from "../headless/reviews/useReviewForm";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { StarRow } from "./ReviewsSection";
+import { Button } from "./Button";
+import { Loading } from "./Loading";
+
+const a = (hex: string, al: number) => hex + Math.round(al * 255).toString(16).padStart(2, "0");
+
+export interface ReviewFormProps {
+  /** The review-request token from the emailed link. */
+  token?: string;
+  /** Extra class(es) appended to the root element. */
+  className?: string;
+  /** Inline style merged LAST into the root element. */
+  style?: React.CSSProperties;
+}
+
+/**
+ * Public review form behind an emailed token link (`/reviews/:token`). The
+ * token proves the verified purchase — no login required. Handles expired
+ * links, already-reviewed and edit-within-30-days states, and the spam-guard
+ * "held for moderation" outcome.
+ */
+export function ReviewForm({ token, className, style }: ReviewFormProps) {
+  const t = useThemeTokens();
+  const {
+    status,
+    request,
+    existingReview: existing,
+    rating,
+    setRating,
+    title,
+    setTitle,
+    body,
+    setBody,
+    reviewerName,
+    setReviewerName,
+    canSubmit,
+    isSubmitting,
+    submit,
+    errorMessage,
+    submitted,
+    isHeld,
+  } = useReviewFormFlow(token);
+  const [hoverRating, setHoverRating] = useState(0);
+
+  const rootStyle: React.CSSProperties = {
+    maxWidth: 560,
+    margin: "0 auto",
+    padding: "24px 16px",
+    color: t.text,
+    fontFamily: t.fontFamily,
+    ...style,
+  };
+
+  if (status === "loading") return <Loading fullPage />;
+
+  if (status === "invalid" || !request) {
+    return (
+      <div className={className} style={rootStyle}>
+        <Panel>
+          <h1 style={h1Style(t)}>This review link isn't valid</h1>
+          <p style={{ opacity: 0.75, lineHeight: 1.6 }}>
+            The link may have been mistyped or is no longer active. If you received it by email, try opening it again
+            from the original message.
+          </p>
+        </Panel>
+      </div>
+    );
+  }
+
+  if (status === "expired") {
+    return (
+      <div className={className} style={rootStyle}>
+        <Panel>
+          <Clock size={32} color={t.primary} />
+          <h1 style={h1Style(t)}>This review link has expired</h1>
+          <p style={{ opacity: 0.75, lineHeight: 1.6 }}>
+            Review links are only valid for a limited time after your purchase
+            {request.entityTitle ? ` of “${request.entityTitle}”` : ""}. Thanks anyway for your support!
+          </p>
+        </Panel>
+      </div>
+    );
+  }
+
+  const afterSubmit = submitted;
+  if (status === "submitted" && afterSubmit) {
+    const held = isHeld;
+    return (
+      <div className={className} style={rootStyle}>
+        <Panel>
+          <CheckCircle2 size={36} color={t.primary} />
+          <h1 style={h1Style(t)}>Thank you for your review!</h1>
+          <StarRow rating={afterSubmit.rating} size={20} />
+          {held ? (
+            <p style={{ opacity: 0.75, lineHeight: 1.6 }}>
+              Your review has been received and is awaiting approval — it will appear once it's been checked.
+            </p>
+          ) : (
+            <p style={{ opacity: 0.75, lineHeight: 1.6 }}>
+              Your review is now live{request.entityTitle ? ` on “${request.entityTitle}”` : ""}.
+            </p>
+          )}
+        </Panel>
+      </div>
+    );
+  }
+
+  if (status === "locked" && existing) {
+    return (
+      <div className={className} style={rootStyle}>
+        <Panel>
+          <CheckCircle2 size={32} color={t.primary} />
+          <h1 style={h1Style(t)}>You've already reviewed this</h1>
+          {request.entityTitle && <p style={{ fontWeight: 600 }}>{request.entityTitle}</p>}
+          <StarRow rating={existing.rating} size={20} />
+          {existing.title && <p style={{ fontWeight: 700, margin: 0 }}>{existing.title}</p>}
+          {existing.body && <p style={{ opacity: 0.85, lineHeight: 1.6, margin: 0 }}>{existing.body}</p>}
+          <p style={{ opacity: 0.6, fontSize: 13 }}>
+            Reviews can be edited for 30 days after they're written — this one can no longer be changed.
+          </p>
+        </Panel>
+      </div>
+    );
+  }
+
+  const displayStars = hoverRating || rating;
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await submit();
+  };
+
+  const inputStyle: React.CSSProperties = {
+    width: "100%",
+    padding: "10px 12px",
+    fontSize: 15,
+    fontFamily: t.fontFamily,
+    color: t.text,
+    background: t.surface,
+    border: `1px solid ${t.border}`,
+    borderRadius: t.cornerRadius,
+    outline: "none",
+    boxSizing: "border-box",
+  };
+
+  return (
+    <div className={className} style={rootStyle}>
+      <form
+        onSubmit={handleSubmit}
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: 18,
+          padding: 24,
+          border: `1px solid ${t.border}`,
+          borderRadius: t.cornerRadius,
+          background: t.surface,
+        }}
+      >
+        <div>
+          <h1 style={{ ...h1Style(t), marginBottom: 4 }}>
+            {existing ? "Edit your review" : "Leave a review"}
+          </h1>
+          {request.entityTitle && (
+            <p style={{ opacity: 0.75, margin: 0 }}>
+              How was <span style={{ fontWeight: 700 }}>{request.entityTitle}</span>?
+            </p>
+          )}
+          {existing && (
+            <p style={{ fontSize: 13, opacity: 0.6, marginTop: 6 }}>
+              You can edit your review within 30 days of writing it. Edits are re-checked before publishing.
+            </p>
+          )}
+        </div>
+
+        {/* Star picker */}
+        <div>
+          <label style={labelStyle}>Your rating *</label>
+          <div
+            style={{ display: "flex", gap: 6 }}
+            role="radiogroup"
+            aria-label="Rating"
+            onMouseLeave={() => setHoverRating(0)}
+          >
+            {[1, 2, 3, 4, 5].map((star) => (
+              <button
+                key={star}
+                type="button"
+                role="radio"
+                aria-checked={rating === star}
+                aria-label={`${star} star${star === 1 ? "" : "s"}`}
+                onClick={() => setRating(star)}
+                onMouseEnter={() => setHoverRating(star)}
+                style={{ background: "transparent", border: "none", padding: 2, cursor: "pointer", lineHeight: 0 }}
+              >
+                <Star
+                  size={30}
+                  fill={star <= displayStars ? t.primary : "transparent"}
+                  color={star <= displayStars ? t.primary : a(t.text, 0.3)}
+                />
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div>
+          <label htmlFor="review-title" style={labelStyle}>
+            Title <span style={{ opacity: 0.5, fontWeight: 400 }}>(optional)</span>
+          </label>
+          <input
+            id="review-title"
+            type="text"
+            maxLength={200}
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+            placeholder="Sum it up in a few words"
+            style={inputStyle}
+          />
+        </div>
+
+        <div>
+          <label htmlFor="review-body" style={labelStyle}>
+            Your review <span style={{ opacity: 0.5, fontWeight: 400 }}>(optional)</span>
+          </label>
+          <textarea
+            id="review-body"
+            rows={5}
+            maxLength={5000}
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder="What did you like or dislike?"
+            style={{ ...inputStyle, resize: "vertical" }}
+          />
+        </div>
+
+        <div>
+          <label htmlFor="review-name" style={labelStyle}>Display name</label>
+          <input
+            id="review-name"
+            type="text"
+            maxLength={100}
+            value={reviewerName}
+            onChange={(e) => setReviewerName(e.target.value)}
+            style={inputStyle}
+          />
+          <p style={{ fontSize: 12, opacity: 0.55, marginTop: 4 }}>Shown publicly next to your review.</p>
+        </div>
+
+        {errorMessage && (
+          <p style={{ fontSize: 14, color: "#b91c1c", background: "#b91c1c14", padding: "8px 12px", borderRadius: t.cornerRadius, margin: 0 }}>
+            {errorMessage}
+          </p>
+        )}
+
+        <Button type="submit" disabled={!canSubmit} loading={isSubmitting} fullWidth>
+          {existing ? "Update review" : "Submit review"}
+        </Button>
+      </form>
+    </div>
+  );
+}
+
+const labelStyle: React.CSSProperties = { display: "block", fontSize: 14, fontWeight: 600, marginBottom: 6 };
+
+function h1Style(t: { headingFontFamily?: string }): React.CSSProperties {
+  return { fontSize: 24, fontWeight: 800, fontFamily: t.headingFontFamily, margin: 0 };
+}
+
+function Panel({ children }: { children: React.ReactNode }) {
+  const t = useThemeTokens();
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        textAlign: "center",
+        gap: 12,
+        padding: 32,
+        border: `1px solid ${t.border}`,
+        borderRadius: t.cornerRadius,
+        background: t.surface,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/ui/styled/ReviewsSection.tsx

@@ -0,0 +1,260 @@
+import { BadgeCheck, MessageSquare, Star, ThumbsUp } from "lucide-react";
+import type { IPublicReview, IReviewAggregate, ReviewEntityType } from "../../types/models";
+import { useReviewsList } from "../headless/reviews/useReviewsList";
+import { useHelpfulVote } from "../headless/reviews/useHelpfulVote";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { Button } from "./Button";
+
+const a = (hex: string, al: number) => hex + Math.round(al * 255).toString(16).padStart(2, "0");
+
+export interface ReviewsSectionProps {
+  /** Which kind of entity these reviews belong to. */
+  entityType: ReviewEntityType;
+  /** The entity's id (product/course/coaching product UUID). */
+  entityId?: string;
+  /** Aggregate attached to the detail response — used for instant paint (SSR). */
+  initialAggregate?: IReviewAggregate | null;
+  /** Section heading. Default "Reviews". */
+  title?: string;
+  /** Reviews per page. Default 10. */
+  pageSize?: number;
+  /** Extra class(es) appended to the root element. */
+  className?: string;
+  /** Inline style merged LAST into the root element. */
+  style?: React.CSSProperties;
+}
+
+/** Row of 5 stars, filled up to `rating` (rounded to nearest half → nearest whole for fill). */
+export function StarRow({ rating, size = 16, color }: { rating: number; size?: number; color?: string }) {
+  const t = useThemeTokens();
+  const c = color ?? t.primary;
+  return (
+    <span style={{ display: "inline-flex", gap: 2, verticalAlign: "middle" }} aria-label={`${rating} out of 5 stars`}>
+      {[1, 2, 3, 4, 5].map((star) => (
+        <Star key={star} size={size} fill={star <= Math.round(rating) ? c : "transparent"} color={star <= Math.round(rating) ? c : a(c, 0.25)} />
+      ))}
+    </span>
+  );
+}
+
+/**
+ * Verified-purchase reviews section for detail pages: aggregate header (avg +
+ * count + distribution bars), sortable paginated list, verified badges, creator
+ * replies and helpful votes (logged-in members). Renders nothing until the
+ * entity has at least one published review.
+ */
+export function ReviewsSection({
+  entityType,
+  entityId,
+  initialAggregate,
+  title = "Reviews",
+  pageSize = 10,
+  className,
+  style,
+}: ReviewsSectionProps) {
+  const t = useThemeTokens();
+  const { reviews, aggregate, isEmpty, distributionMax, sort, setSort, sortOptions, hasMore, loadMore, isFetching } =
+    useReviewsList({ entityType, entityId, pageSize, initialAggregate });
+
+  // Nothing published yet — keep the page clean.
+  if (isEmpty || !aggregate) return null;
+
+  const maxBucket = distributionMax;
+
+  return (
+    <section
+      className={className}
+      style={{ marginTop: 40, color: t.text, fontFamily: t.fontFamily, ...style }}
+      aria-label={title}
+    >
+      <h2 style={{ fontSize: 22, fontWeight: 800, marginBottom: 16, fontFamily: t.headingFontFamily }}>{title}</h2>
+
+      {/* Aggregate header */}
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: 24,
+          alignItems: "center",
+          padding: 16,
+          border: `1px solid ${t.border}`,
+          borderRadius: t.cornerRadius,
+          background: t.surface,
+        }}
+      >
+        <div style={{ textAlign: "center", minWidth: 96 }}>
+          <div style={{ fontSize: 40, fontWeight: 800, lineHeight: 1.1 }}>{aggregate.avgRating.toFixed(1)}</div>
+          <StarRow rating={aggregate.avgRating} size={18} />
+          <div style={{ fontSize: 13, opacity: 0.7, marginTop: 4 }}>
+            {aggregate.reviewCount} review{aggregate.reviewCount === 1 ? "" : "s"}
+          </div>
+        </div>
+        <div style={{ flex: 1, minWidth: 220, display: "flex", flexDirection: "column", gap: 4 }}>
+          {([5, 4, 3, 2, 1] as const).map((star) => {
+            const count = aggregate.distribution[String(star) as keyof IReviewAggregate["distribution"]] ?? 0;
+            return (
+              <div key={star} style={{ display: "flex", alignItems: "center", gap: 8, fontSize: 13 }}>
+                <span style={{ width: 12, textAlign: "right", opacity: 0.8 }}>{star}</span>
+                <Star size={12} fill={t.primary} color={t.primary} style={{ flexShrink: 0 }} />
+                <div
+                  style={{
+                    flex: 1,
+                    height: 8,
+                    borderRadius: 4,
+                    background: a(t.text, 0.08),
+                    overflow: "hidden",
+                  }}
+                >
+                  <div
+                    style={{
+                      width: `${(count / maxBucket) * 100}%`,
+                      height: "100%",
+                      borderRadius: 4,
+                      background: t.primary,
+                      transition: "width .2s",
+                    }}
+                  />
+                </div>
+                <span style={{ width: 28, opacity: 0.7 }}>{count}</span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Sort */}
+      <div style={{ display: "flex", flexWrap: "wrap", gap: 8, margin: "16px 0" }}>
+        {sortOptions.map((s) => {
+          const on = sort === s.value;
+          return (
+            <button
+              key={s.value}
+              type="button"
+              onClick={() => setSort(s.value)}
+              style={{
+                padding: "6px 12px",
+                fontSize: 13,
+                fontWeight: 600,
+                borderRadius: 999,
+                cursor: "pointer",
+                color: on ? t.textPrimary : t.text,
+                background: on ? t.primary : "transparent",
+                border: `1px solid ${on ? t.primary : t.border}`,
+              }}
+            >
+              {s.label}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* List */}
+      <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {reviews.map((review) => (
+          <ReviewCard key={review.id} review={review} />
+        ))}
+      </div>
+
+      {hasMore && (
+        <div style={{ marginTop: 16 }}>
+          <Button variant="outline" size="sm" loading={isFetching} onClick={loadMore}>
+            Show more reviews
+          </Button>
+        </div>
+      )}
+    </section>
+  );
+}
+
+function ReviewCard({ review }: { review: IPublicReview }) {
+  const t = useThemeTokens();
+  const { voted, helpfulCount, toggle: toggleVote, canVote: isAuthenticated } = useHelpfulVote(review);
+
+  const date = review.publishedAt ?? review.createdAt;
+  const dateLabel = date
+    ? new Date(date).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" })
+    : "";
+
+  return (
+    <article
+      style={{
+        padding: 16,
+        border: `1px solid ${t.border}`,
+        borderRadius: t.cornerRadius,
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+      }}
+    >
+      <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 8 }}>
+        <StarRow rating={review.rating} size={14} />
+        {review.title && <span style={{ fontWeight: 700, fontSize: 15 }}>{review.title}</span>}
+      </div>
+
+      {review.body && <p style={{ fontSize: 14, lineHeight: 1.6, opacity: 0.9, margin: 0 }}>{review.body}</p>}
+
+      <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 10, fontSize: 13, opacity: 0.85 }}>
+        <span style={{ fontWeight: 600 }}>{review.reviewerName || "Verified Buyer"}</span>
+        {review.isVerified && (
+          <span
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              gap: 4,
+              fontSize: 12,
+              fontWeight: 600,
+              padding: "2px 8px",
+              borderRadius: 999,
+              color: t.primary,
+              background: a(t.primary, 0.1),
+              border: `1px solid ${a(t.primary, 0.3)}`,
+            }}
+          >
+            <BadgeCheck size={13} /> Verified purchase
+          </span>
+        )}
+        {dateLabel && <span style={{ opacity: 0.6 }}>{dateLabel}</span>}
+        <button
+          type="button"
+          onClick={toggleVote}
+          disabled={!isAuthenticated}
+          title={isAuthenticated ? (voted ? "Remove helpful vote" : "Mark as helpful") : "Log in to vote"}
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 5,
+            marginLeft: "auto",
+            padding: "4px 10px",
+            fontSize: 12,
+            fontWeight: 600,
+            borderRadius: 999,
+            cursor: isAuthenticated ? "pointer" : "default",
+            color: voted ? t.textPrimary : t.text,
+            background: voted ? t.primary : "transparent",
+            border: `1px solid ${voted ? t.primary : t.border}`,
+            opacity: isAuthenticated ? 1 : 0.55,
+          }}
+        >
+          <ThumbsUp size={13} /> Helpful{helpfulCount > 0 ? ` (${helpfulCount})` : ""}
+        </button>
+      </div>
+
+      {review.reply && (
+        <div
+          style={{
+            marginTop: 4,
+            padding: 12,
+            borderRadius: Math.max(6, t.cornerRadius - 2),
+            background: a(t.text, 0.05),
+            borderLeft: `3px solid ${t.primary}`,
+          }}
+        >
+          <div style={{ display: "flex", alignItems: "center", gap: 6, fontSize: 12, fontWeight: 700, marginBottom: 4 }}>
+            <MessageSquare size={13} color={t.primary} /> Response from the creator
+          </div>
+          <p style={{ fontSize: 13, lineHeight: 1.6, margin: 0, opacity: 0.9 }}>{review.reply.body}</p>
+        </div>
+      )}
+    </article>
+  );
+}

package/src/ui/styled/SectionedFormRenderer.tsx

@@ -0,0 +1,146 @@
+import { usePublicForm } from "../../data/queries/useForms";
+import { useSectionedForm } from "../headless/forms/useSectionedForm";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { readableTextOn } from "../theme/contrast";
+import { useForgeTheme } from "../theme/ForgeThemeProvider";
+import { Loading } from "./Loading";
+import { FormRenderer, FieldInput } from "./FormRenderer";
+
+export interface SectionedFormRendererProps {
+  formId: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/**
+ * Themed multi-section form wizard: renders one section (page) of fields at a
+ * time with Back/Next, in-page field visibility, per-section validation, and
+ * section→section branching — built on `useSectionedForm`. Forms with no
+ * sections fall back to the flat `<FormRenderer>`, so this is a safe drop-in for
+ * any form.
+ */
+export function SectionedFormRenderer({ formId, className, style }: SectionedFormRendererProps) {
+  const { data: form, isLoading } = usePublicForm(formId);
+  if (isLoading || !form) return <Loading fullPage />;
+  // No sections → the flat renderer (single page, one submit).
+  if (!form.sections || form.sections.length === 0) return <FormRenderer formId={formId} />;
+  return <Wizard formId={formId} className={className} style={style} />;
+}
+
+function Wizard({ formId, className, style }: SectionedFormRendererProps) {
+  const t = useThemeTokens();
+  const theme = useForgeTheme();
+  const {
+    form,
+    currentSection,
+    visibleFields,
+    answers,
+    setAnswer,
+    error,
+    next,
+    back,
+    canGoBack,
+    isSubmitStep,
+    isSubmitting,
+    isCompleted,
+    progress,
+  } = useSectionedForm(formId);
+
+  const settings = typeof form?.settings === "string" ? JSON.parse(form.settings) : form?.settings || {};
+  const wrap: React.CSSProperties = {
+    maxWidth: 560,
+    margin: "0 auto",
+    color: t.text,
+    fontFamily: t.fontFamily,
+    ...style,
+  };
+  const onPrimary = t.textPrimary || readableTextOn(t.primary);
+
+  if (isCompleted) {
+    return (
+      <div className={className} style={{ ...wrap, textAlign: "center" }}>
+        <h1 style={{ fontSize: 24, fontWeight: 700, marginBottom: 12, fontFamily: t.headingFontFamily }}>
+          {settings.thankYouTitle || "Thank you!"}
+        </h1>
+        <p style={{ opacity: 0.8 }}>{settings.thankYouMessage || "Your response has been recorded."}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={wrap}>
+      {/* Progress */}
+      {settings.showProgressBar !== false && (
+        <div style={{ height: 4, borderRadius: 2, background: `${t.primary}22`, marginBottom: 20 }}>
+          <div
+            style={{
+              width: `${Math.round(progress * 100)}%`,
+              height: "100%",
+              borderRadius: 2,
+              background: t.primary,
+              transition: "width .2s ease",
+            }}
+          />
+        </div>
+      )}
+
+      {currentSection?.title && (
+        <h2 style={{ fontSize: 22, fontWeight: 800, marginBottom: 6, fontFamily: t.headingFontFamily }}>
+          {currentSection.title}
+        </h2>
+      )}
+      {currentSection?.description && <p style={{ opacity: 0.7, marginBottom: 20 }}>{currentSection.description}</p>}
+
+      <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+        {visibleFields.map((field) => (
+          <FieldInput
+            key={field.id}
+            field={field}
+            value={answers[field.id] || ""}
+            onChange={(v) => setAnswer(field.id, v)}
+            theme={theme}
+          />
+        ))}
+      </div>
+
+      {error && <p style={{ color: "#dc2626", marginTop: 16 }}>{error}</p>}
+
+      <div style={{ display: "flex", justifyContent: "space-between", gap: 12, marginTop: 24 }}>
+        <button
+          type="button"
+          onClick={back}
+          disabled={!canGoBack || isSubmitting}
+          style={{
+            padding: "12px 20px",
+            borderRadius: t.cornerRadius,
+            border: `1px solid ${t.border}`,
+            background: "transparent",
+            color: t.text,
+            fontWeight: 600,
+            cursor: canGoBack ? "pointer" : "not-allowed",
+            opacity: canGoBack ? 1 : 0.4,
+          }}
+        >
+          Back
+        </button>
+        <button
+          type="button"
+          onClick={next}
+          disabled={isSubmitting}
+          style={{
+            padding: "12px 24px",
+            borderRadius: t.cornerRadius,
+            border: "none",
+            fontWeight: 600,
+            cursor: "pointer",
+            opacity: isSubmitting ? 0.5 : 1,
+            background: t.primary,
+            color: onPrimary,
+          }}
+        >
+          {isSubmitting ? "Submitting…" : isSubmitStep ? settings.submitButtonText || "Submit" : "Next"}
+        </button>
+      </div>
+    </div>
+  );
+}