@carlonicora/nextjs-jsonapi 5.1.2 → 5.2.0

package/src/features/auth/data/auth.interface.ts

@@ -1,4 +1,5 @@
 import { ApiDataInterface } from "../../../core";
+import { SignupSource } from "../../signup-source/signup-source";
 import { UserInterface } from "../../user";
 
 export type AuthInput = {
@@ -14,6 +15,7 @@ export type AuthInput = {
   marketingConsentAt?: string | null;
   inviteCode?: string;
   referralCode?: string;
+  source?: SignupSource;
 };
 
 export type AuthQuery = {

package/src/features/auth/data/auth.ts

@@ -52,6 +52,16 @@ export class Auth extends AbstractApiData implements AuthInterface {
     if (data.inviteCode !== undefined) response.data.attributes.inviteCode = data.inviteCode;
     if (data.referralCode !== undefined) response.data.attributes.referralCode = data.referralCode;
 
+    if (data.source !== undefined) {
+      const attributes = response.data.attributes;
+      if (data.source.sourceRef !== undefined) attributes.sourceRef = data.source.sourceRef;
+      if (data.source.sourceUtmSource !== undefined) attributes.sourceUtmSource = data.source.sourceUtmSource;
+      if (data.source.sourceUtmMedium !== undefined) attributes.sourceUtmMedium = data.source.sourceUtmMedium;
+      if (data.source.sourceUtmCampaign !== undefined) attributes.sourceUtmCampaign = data.source.sourceUtmCampaign;
+      if (data.source.sourceReferrer !== undefined) attributes.sourceReferrer = data.source.sourceReferrer;
+      if (data.source.sourceLandingPath !== undefined) attributes.sourceLandingPath = data.source.sourceLandingPath;
+    }
+
     return response;
   }
 }

package/src/features/signup-source/SignupSourceCapture.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { usePathname, useSearchParams } from "next/navigation";
+import { useEffect } from "react";
+
+import { captureSignupSource } from "./signup-source";
+
+/**
+ * SignupSourceCapture records where a visitor came from (ref, UTM, external referrer, landing path).
+ *
+ * Behavior:
+ * - Captures on mount and on every client navigation (pathname/search change)
+ * - First touch wins: an existing in-memory value or cookie is never overwritten
+ * - Writes the `signup_source` cookie only when `persist` is true (cookie consent accepted);
+ *   when `persist` flips to true later, the in-memory value is written then
+ * - Renders nothing (null)
+ */
+export function SignupSourceCapture({ persist }: { persist: boolean }): null {
+  const searchParams = useSearchParams();
+  const pathname = usePathname();
+
+  useEffect(() => {
+    captureSignupSource({ persist });
+  }, [pathname, searchParams, persist]);
+
+  return null;
+}

package/src/features/signup-source/__tests__/signup-source.spec.ts

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type SignupSourceModule = typeof import("../signup-source");
+
+let cookieStore: Record<string, string>;
+let cookieWrites: string[];
+
+function stubBrowser(params: { href: string; referrer?: string }) {
+  const url = new URL(params.href);
+  vi.stubGlobal("window", { location: { href: url.href, host: url.host } });
+  vi.stubGlobal("document", {
+    referrer: params.referrer ?? "",
+    get cookie() {
+      return Object.entries(cookieStore)
+        .map(([name, value]) => `${name}=${value}`)
+        .join("; ");
+    },
+    set cookie(cookieString: string) {
+      cookieWrites.push(cookieString);
+      const [nameValue] = cookieString.split(";");
+      const separator = nameValue.indexOf("=");
+      cookieStore[nameValue.slice(0, separator).trim()] = nameValue.slice(separator + 1);
+    },
+  });
+}
+
+async function loadModule(): Promise<SignupSourceModule> {
+  return import("../signup-source");
+}
+
+describe("signup-source", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    cookieStore = {};
+    cookieWrites = [];
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("readSignupSourceFromLocation()", () => {
+    it("reads the ref param and the landing path", async () => {
+      const { readSignupSourceFromLocation } = await loadModule();
+      expect(
+        readSignupSourceFromLocation({ url: "https://wyrd.li/?ref=discord-embed", referrer: "", ownHost: "wyrd.li" }),
+      ).toEqual({ sourceRef: "discord-embed", sourceLandingPath: "/" });
+    });
+
+    it("reads the UTM params", async () => {
+      const { readSignupSourceFromLocation } = await loadModule();
+      expect(
+        readSignupSourceFromLocation({
+          url: "https://wyrd.li/it/pricing?utm_source=reddit&utm_medium=social&utm_campaign=r_rpg",
+          referrer: "",
+          ownHost: "wyrd.li",
+        }),
+      ).toEqual({
+        sourceUtmSource: "reddit",
+        sourceUtmMedium: "social",
+        sourceUtmCampaign: "r_rpg",
+        sourceLandingPath: "/it/pricing",
+      });
+    });
+
+    it("keeps the host of an external referrer", async () => {
+      const { readSignupSourceFromLocation } = await loadModule();
+      const source = readSignupSourceFromLocation({
+        url: "https://wyrd.li/",
+        referrer: "https://www.enworld.org/threads/1",
+        ownHost: "wyrd.li",
+      });
+      expect(source?.sourceReferrer).toBe("www.enworld.org");
+    });
+
+    it("returns undefined for an own-host referrer and no params", async () => {
+      const { readSignupSourceFromLocation } = await loadModule();
+      expect(
+        readSignupSourceFromLocation({
+          url: "https://wyrd.li/",
+          referrer: "https://wyrd.li/pricing",
+          ownHost: "wyrd.li",
+        }),
+      ).toBeUndefined();
+    });
+
+    it("truncates values to 200 characters", async () => {
+      const { readSignupSourceFromLocation } = await loadModule();
+      const source = readSignupSourceFromLocation({
+        url: `https://wyrd.li/?ref=${"a".repeat(500)}`,
+        referrer: "",
+        ownHost: "wyrd.li",
+      });
+      expect(source?.sourceRef).toHaveLength(200);
+    });
+  });
+
+  describe("captureSignupSource()", () => {
+    it("persist false never writes the cookie", async () => {
+      stubBrowser({ href: "https://wyrd.li/?ref=x" });
+      const { captureSignupSource, getSignupSource } = await loadModule();
+
+      captureSignupSource({ persist: false });
+
+      expect(getSignupSource()).toEqual({ sourceRef: "x", sourceLandingPath: "/" });
+      expect(document.cookie).not.toContain("signup_source");
+      expect(cookieWrites).toHaveLength(0);
+    });
+
+    it("persist true writes the cookie once", async () => {
+      stubBrowser({ href: "https://wyrd.li/?ref=x" });
+      const { captureSignupSource } = await loadModule();
+
+      captureSignupSource({ persist: true });
+      captureSignupSource({ persist: true });
+
+      expect(cookieWrites).toHaveLength(1);
+      expect(cookieWrites[0]).toContain("signup_source=");
+      expect(cookieWrites[0]).toContain("max-age=2592000");
+      expect(cookieWrites[0]).toContain("SameSite=Lax");
+      expect(cookieWrites[0]).toContain("path=/");
+    });
+
+    it("first touch wins over an existing cookie", async () => {
+      cookieStore["signup_source"] = encodeURIComponent(JSON.stringify({ sourceRef: "discord-embed" }));
+      stubBrowser({ href: "https://wyrd.li/?utm_source=reddit" });
+      const { captureSignupSource, getSignupSource } = await loadModule();
+
+      captureSignupSource({ persist: true });
+
+      expect(getSignupSource()?.sourceRef).toBe("discord-embed");
+      expect(getSignupSource()?.sourceUtmSource).toBeUndefined();
+      expect(cookieWrites).toHaveLength(0);
+    });
+
+    it("a later persist=true writes the in-memory value", async () => {
+      stubBrowser({ href: "https://wyrd.li/?ref=x" });
+      const { captureSignupSource } = await loadModule();
+
+      captureSignupSource({ persist: false });
+      expect(cookieWrites).toHaveLength(0);
+
+      stubBrowser({ href: "https://wyrd.li/pricing" });
+      captureSignupSource({ persist: true });
+
+      expect(cookieWrites).toHaveLength(1);
+      expect(JSON.parse(decodeURIComponent(cookieStore["signup_source"]))).toEqual({
+        sourceRef: "x",
+        sourceLandingPath: "/",
+      });
+    });
+
+    it("treats a malformed cookie as absent", async () => {
+      cookieStore["signup_source"] = "not-json%";
+      stubBrowser({ href: "https://wyrd.li/" });
+      const { getSignupSource } = await loadModule();
+
+      expect(getSignupSource()).toBeUndefined();
+    });
+  });
+});

package/src/features/signup-source/index.ts

@@ -0,0 +1,9 @@
+// Client component SignupSourceCapture is exported from the /components entry point.
+export {
+  SIGNUP_SOURCE_COOKIE,
+  SIGNUP_SOURCE_COOKIE_MAX_AGE,
+  captureSignupSource,
+  getSignupSource,
+  readSignupSourceFromLocation,
+} from "./signup-source";
+export type { SignupSource } from "./signup-source";

package/src/features/signup-source/signup-source.ts

@@ -0,0 +1,135 @@
+export type SignupSource = {
+  sourceRef?: string;
+  sourceUtmSource?: string;
+  sourceUtmMedium?: string;
+  sourceUtmCampaign?: string;
+  sourceReferrer?: string;
+  sourceLandingPath?: string;
+};
+
+export const SIGNUP_SOURCE_COOKIE = "signup_source";
+export const SIGNUP_SOURCE_COOKIE_MAX_AGE = 2592000;
+
+/** The six source fields, in display order. */
+export const SIGNUP_SOURCE_FIELDS: readonly (keyof SignupSource)[] = [
+  "sourceRef",
+  "sourceUtmSource",
+  "sourceUtmMedium",
+  "sourceUtmCampaign",
+  "sourceReferrer",
+  "sourceLandingPath",
+];
+
+const SIGNUP_SOURCE_MAX_LENGTH = 200;
+
+// First touch for the current page session. Survives client navigations, lost on a full reload.
+let memorySource: SignupSource | undefined;
+
+function clean(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  return trimmed.slice(0, SIGNUP_SOURCE_MAX_LENGTH);
+}
+
+function sanitise(input: unknown): SignupSource | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const result: SignupSource = {};
+  for (const field of SIGNUP_SOURCE_FIELDS) {
+    const value = clean((input as Record<string, unknown>)[field]);
+    if (value !== undefined) result[field] = value;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * Pure. Reads ref and utm_source/medium/campaign from the URL, the referrer host when it is not ownHost,
+ * and the landing path. Returns undefined for a direct visit (no ref, no UTM, no external referrer).
+ */
+export function readSignupSourceFromLocation(params: {
+  url: string;
+  referrer: string;
+  ownHost: string;
+}): SignupSource | undefined {
+  let url: URL;
+  try {
+    url = new URL(params.url);
+  } catch {
+    return undefined;
+  }
+
+  const sourceRef = clean(url.searchParams.get("ref"));
+  const sourceUtmSource = clean(url.searchParams.get("utm_source"));
+  const sourceUtmMedium = clean(url.searchParams.get("utm_medium"));
+  const sourceUtmCampaign = clean(url.searchParams.get("utm_campaign"));
+
+  let sourceReferrer: string | undefined;
+  if (params.referrer) {
+    try {
+      const referrerHost = new URL(params.referrer).host;
+      if (referrerHost && referrerHost !== params.ownHost) sourceReferrer = clean(referrerHost);
+    } catch {
+      sourceReferrer = undefined;
+    }
+  }
+
+  if (!sourceRef && !sourceUtmSource && !sourceUtmMedium && !sourceUtmCampaign && !sourceReferrer) return undefined;
+
+  return sanitise({
+    sourceRef,
+    sourceUtmSource,
+    sourceUtmMedium,
+    sourceUtmCampaign,
+    sourceReferrer,
+    sourceLandingPath: url.pathname,
+  });
+}
+
+function readSignupSourceCookie(): SignupSource | undefined {
+  if (typeof document === "undefined") return undefined;
+  const cookies = document.cookie ? document.cookie.split("; ") : [];
+  for (const cookie of cookies) {
+    const separator = cookie.indexOf("=");
+    if (separator === -1) continue;
+    if (cookie.slice(0, separator) !== SIGNUP_SOURCE_COOKIE) continue;
+    const value = cookie.slice(separator + 1);
+    if (!value) return undefined;
+    try {
+      return sanitise(JSON.parse(decodeURIComponent(value)));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function writeSignupSourceCookie(source: SignupSource): void {
+  document.cookie = `${SIGNUP_SOURCE_COOKIE}=${encodeURIComponent(JSON.stringify(source))}; path=/; max-age=${SIGNUP_SOURCE_COOKIE_MAX_AGE}; SameSite=Lax`;
+}
+
+/**
+ * First touch: an existing in-memory value or cookie is never overwritten.
+ * Writes the cookie only when persist is true and no cookie exists yet.
+ */
+export function captureSignupSource(params: { persist: boolean }): void {
+  if (typeof window === "undefined" || typeof document === "undefined") return;
+
+  const existingCookie = readSignupSourceCookie();
+
+  if (!memorySource) {
+    memorySource =
+      existingCookie ??
+      readSignupSourceFromLocation({
+        url: window.location.href,
+        referrer: document.referrer,
+        ownHost: window.location.host,
+      });
+  }
+
+  if (params.persist && !existingCookie && memorySource) writeSignupSourceCookie(memorySource);
+}
+
+/** The in-memory value, else the cookie value, else undefined. */
+export function getSignupSource(): SignupSource | undefined {
+  return memorySource ?? readSignupSourceCookie();
+}

package/src/features/waitlist/components/forms/WaitlistForm.tsx

@@ -11,6 +11,7 @@ import { errorToast, FormInput, GdprConsentCheckbox } from "../../../../componen
 import { Button, Form, Link } from "../../../../shadcnui";
 import { SectionHeader } from "../../../../components/typography";
 import { getWaitlistConfig } from "../../config/waitlist.config";
+import { getSignupSource } from "../../../signup-source/signup-source";
 import { WaitlistService } from "../../data/WaitlistService";
 import { WaitlistQuestionnaireRenderer } from "./WaitlistQuestionnaireRenderer";
 
@@ -110,6 +111,7 @@ export function WaitlistForm({ onSuccess }: WaitlistFormProps) {
         marketingConsent: values.marketingConsent ?? false,
         marketingConsentAt: values.marketingConsent ? now : undefined,
         questionnaire: values.questionnaire,
+        source: getSignupSource(),
       });
 
       setIsSuccess(true);

package/src/features/waitlist/components/forms/WaitlistQuestionnaireRenderer.tsx

@@ -2,7 +2,7 @@
 
 import { FieldValues, Path, UseFormReturn } from "react-hook-form";
 import { FormInput, FormTextarea, FormSelect, FormCheckbox } from "../../../../components";
-import { QuestionnaireField } from "../../config/waitlist.config";
+import { QuestionnaireField, useWaitlistText } from "../../config/waitlist.config";
 
 interface WaitlistQuestionnaireRendererProps<T extends FieldValues> {
   form: UseFormReturn<T>;
@@ -15,6 +15,8 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
   fields,
   fieldPrefix = "questionnaire",
 }: WaitlistQuestionnaireRendererProps<T>) {
+  const text = useWaitlistText();
+
   if (!fields || fields.length === 0) {
     return null;
   }
@@ -31,8 +33,8 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
                 key={field.id}
                 form={form}
                 id={fieldId}
-                name={field.label}
-                placeholder={field.placeholder}
+                name={text(field.label) ?? field.label}
+                placeholder={text(field.placeholder)}
                 isRequired={field.required}
               />
             );
@@ -43,8 +45,8 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
                 key={field.id}
                 form={form}
                 id={fieldId}
-                name={field.label}
-                placeholder={field.placeholder}
+                name={text(field.label) ?? field.label}
+                placeholder={text(field.placeholder)}
                 className="min-h-24"
               />
             );
@@ -58,10 +60,10 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
                 key={field.id}
                 form={form}
                 id={fieldId}
-                name={field.label}
+                name={text(field.label) ?? field.label}
                 values={field.options.map((opt) => ({
                   id: opt.value,
-                  text: opt.label,
+                  text: text(opt.label) ?? opt.label,
                 }))}
               />
             );
@@ -73,8 +75,8 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
                   key={field.id}
                   form={form}
                   id={fieldId}
-                  name={field.label}
-                  description={field.description}
+                  name={text(field.label) ?? field.label}
+                  description={text(field.description)}
                   isRequired={field.required}
                 />
               );
@@ -83,18 +85,18 @@ export function WaitlistQuestionnaireRenderer<T extends FieldValues>({
             return (
               <div key={field.id} className="space-y-2">
                 <span className="text-sm font-medium">
-                  {field.label}
+                  {text(field.label) ?? field.label}
                   {field.required && <span className="ms-1 text-destructive">*</span>}
                 </span>
-                {field.description && <p className="text-muted-foreground text-xs">{field.description}</p>}
+                {field.description && <p className="text-muted-foreground text-xs">{text(field.description)}</p>}
                 <div className="space-y-2">
                   {field.options.map((option) => (
                     <FormCheckbox
                       key={option.value}
                       form={form}
                       id={`${fieldId}.${option.value}` as Path<T>}
-                      name={option.label}
-                      description={option.description}
+                      name={text(option.label) ?? option.label}
+                      description={text(option.description)}
                     />
                   ))}
                 </div>

package/src/features/waitlist/components/lists/WaitlistList.tsx

@@ -2,7 +2,7 @@
 
 import { RefreshCw } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { ContentListTable, errorToast } from "../../../../components";
 import { Modules } from "../../../../core";
 import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
@@ -11,6 +11,7 @@ import { showToast } from "../../../../utils/toast";
 import { WaitlistFields } from "../../data/waitlist.fields";
 import { WaitlistInterface } from "../../data/WaitlistInterface";
 import { WaitlistService } from "../../data/WaitlistService";
+import { WaitlistStatsInterface } from "../../data/waitlist-stats.interface";
 
 type WaitlistListProps = {
   /**
@@ -25,6 +26,7 @@ type WaitlistListProps = {
 export function WaitlistList({ fullWidth }: WaitlistListProps = {}) {
   const t = useTranslations();
   const [statusFilter, setStatusFilter] = useState<string>("all");
+  const [stats, setStats] = useState<WaitlistStatsInterface | undefined>(undefined);
 
   const data: DataListRetriever<WaitlistInterface> = useDataListRetriever({
     retriever: (params) => WaitlistService.findMany(params),
@@ -32,11 +34,28 @@ export function WaitlistList({ fullWidth }: WaitlistListProps = {}) {
     module: Modules.Waitlist,
   });
 
+  const loadStats = useCallback(async () => {
+    try {
+      setStats(await WaitlistService.getStats());
+    } catch (error) {
+      errorToast({ title: t("common.errors.error"), error });
+    }
+  }, [t]);
+
+  useEffect(() => {
+    void loadStats();
+  }, [loadStats]);
+
+  const refresh = () => {
+    void data.refresh();
+    void loadStats();
+  };
+
   const handleInvite = async (entry: WaitlistInterface) => {
     try {
       await WaitlistService.invite(entry.id);
       showToast(t("waitlist.admin.invite_sent", { email: entry.email }));
-      void data.refresh();
+      refresh();
     } catch (error) {
       errorToast({ title: t("common.errors.error"), error });
     }
@@ -74,31 +93,50 @@ export function WaitlistList({ fullWidth }: WaitlistListProps = {}) {
         </SelectContent>
       </Select>
 
-      <Button variant="outline" size="icon" onClick={() => void data.refresh()} disabled={!data.isLoaded}>
+      <Button variant="outline" size="icon" onClick={refresh} disabled={!data.isLoaded}>
         <RefreshCw className={`h-4 w-4 ${!data.isLoaded ? "animate-spin" : ""}`} />
       </Button>
     </div>
   );
 
+  const totals = [
+    { key: "total", label: t("waitlist.admin.total"), value: stats?.total },
+    { key: "pending", label: t("waitlist.admin.status.pending"), value: stats?.pending },
+    { key: "confirmed", label: t("waitlist.admin.status.confirmed"), value: stats?.confirmed },
+    { key: "invited", label: t("waitlist.admin.status.invited"), value: stats?.invited },
+    { key: "registered", label: t("waitlist.admin.status.registered"), value: stats?.registered },
+  ];
+
   return (
-    <ContentListTable
-      data={data}
-      fields={[
-        WaitlistFields.email,
-        WaitlistFields.status,
-        WaitlistFields.createdAt,
-        WaitlistFields.questionnaire,
-        WaitlistFields.actions,
-      ]}
-      tableGeneratorType={Modules.Waitlist}
-      title={t("waitlist.admin.title")}
-      filters={filters}
-      /* The waitlist endpoint takes no search term, so rendering the box would
-         give the page a control that silently does nothing. */
-      allowSearch={false}
-      context={{ onInvite: handleInvite }}
-      fullWidth={fullWidth}
-      emptyState={t("waitlist.admin.empty")}
-    />
+    <div className="flex flex-col gap-4">
+      <dl className="grid grid-cols-5 divide-x divide-border rounded-md border" data-testid="waitlist-totals">
+        {totals.map((total) => (
+          <div key={total.key} className="flex flex-col-reverse items-center gap-1 p-3">
+            <dt className="text-muted-foreground text-xs">{total.label}</dt>
+            <dd className="text-primary text-xl font-semibold tabular-nums">{total.value ?? "-"}</dd>
+          </div>
+        ))}
+      </dl>
+      <ContentListTable
+        data={data}
+        fields={[
+          WaitlistFields.email,
+          WaitlistFields.status,
+          WaitlistFields.createdAt,
+          WaitlistFields.source,
+          WaitlistFields.questionnaire,
+          WaitlistFields.actions,
+        ]}
+        tableGeneratorType={Modules.Waitlist}
+        title={t("waitlist.admin.title")}
+        filters={filters}
+        /* The waitlist endpoint takes no search term, so rendering the box would
+           give the page a control that silently does nothing. */
+        allowSearch={false}
+        context={{ onInvite: handleInvite }}
+        fullWidth={fullWidth}
+        emptyState={t("waitlist.admin.empty")}
+      />
+    </div>
   );
 }

package/src/features/waitlist/components/sections/WaitlistHeroSection.tsx

@@ -1,11 +1,12 @@
 "use client";
 
 import { CheckCircle } from "lucide-react";
-import { getWaitlistConfig } from "../../config/waitlist.config";
+import { getWaitlistConfig, useWaitlistText } from "../../config/waitlist.config";
 import { WaitlistForm } from "../forms/WaitlistForm";
 
 export function WaitlistHeroSection() {
   const config = getWaitlistConfig();
+  const text = useWaitlistText();
 
   return (
     <section className="relative overflow-hidden py-16 md:py-24">
@@ -15,12 +16,12 @@ export function WaitlistHeroSection() {
           <div className="space-y-8">
             <div className="space-y-4">
               {config.heroTitle && (
-                <h1 className="text-4xl font-bold tracking-tight md:text-5xl lg:text-6xl">{config.heroTitle}</h1>
+                <h1 className="text-4xl font-bold tracking-tight md:text-5xl lg:text-6xl">{text(config.heroTitle)}</h1>
               )}
               {config.heroSubtitle && (
-                <p className="text-muted-foreground text-xl md:text-2xl">{config.heroSubtitle}</p>
+                <p className="text-muted-foreground text-xl md:text-2xl">{text(config.heroSubtitle)}</p>
               )}
-              {config.heroDescription && <p className="text-muted-foreground">{config.heroDescription}</p>}
+              {config.heroDescription && <p className="text-muted-foreground">{text(config.heroDescription)}</p>}
             </div>
 
             {/* Benefits */}
@@ -29,7 +30,7 @@ export function WaitlistHeroSection() {
                 {config.benefits.map((benefit, index) => (
                   <li key={index} className="flex items-start gap-3">
                     <CheckCircle className="text-primary mt-0.5 h-5 w-5 shrink-0" />
-                    <span>{benefit}</span>
+                    <span>{text(benefit)}</span>
                   </li>
                 ))}
               </ul>

package/src/features/waitlist/config/waitlist.config.ts

@@ -1,3 +1,5 @@
+import { useI18nTranslations } from "../../../i18n";
+
 export type QuestionnaireFieldType = "text" | "textarea" | "select" | "checkbox";
 
 export interface QuestionnaireOption {
@@ -22,6 +24,13 @@ export interface WaitlistConfig {
   heroSubtitle?: string;
   heroDescription?: string;
   benefits?: string[];
+  /**
+   * When true, every text above (hero title, subtitle, description, benefits and
+   * the questionnaire's labels, descriptions, placeholders and option labels) is
+   * a message key and renders through `t()`. Defaults to false: the strings
+   * render as given.
+   */
+  translate?: boolean;
 }
 
 let _waitlistConfig: WaitlistConfig = {};
@@ -33,3 +42,17 @@ export function configureWaitlist(config: WaitlistConfig): void {
 export function getWaitlistConfig(): WaitlistConfig {
   return _waitlistConfig;
 }
+
+/**
+ * Resolves a waitlist config text: `t(value)` when the config sets
+ * `translate`, the value itself otherwise. Empty values stay undefined.
+ */
+export function useWaitlistText(): (value?: string) => string | undefined {
+  const t = useI18nTranslations();
+  const translate = getWaitlistConfig().translate === true;
+
+  return (value?: string) => {
+    if (!value) return undefined;
+    return translate ? t(value) : value;
+  };
+}