@carlonicora/nextjs-jsonapi 5.1.3 → 5.3.0

package/src/features/email-automation/hooks/useEmailAutomationTableStructure.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Badge, Link } from "../../../shadcnui";
+import { Modules } from "../../../core";
+import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../hooks";
+import { EmailAutomationFields } from "../data/email-automation.fields";
+import { EmailAutomationInterface } from "../data/EmailAutomationInterface";
+
+/**
+ * `context.triggerLabels` maps a trigger key to the label the API declares for
+ * it (EmailAutomationsList loads them). A key the app no longer declares falls
+ * back to the raw key, so a stale automation stays readable.
+ */
+export const useEmailAutomationTableStructure: UseTableStructureHook<
+  EmailAutomationInterface,
+  EmailAutomationFields
+> = (params) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const triggerLabels: Record<string, string> = params.context?.triggerLabels ?? {};
+
+  const tableData = useMemo(() => {
+    return params.data.map((automation: EmailAutomationInterface) => {
+      const entry: TableContent<EmailAutomationInterface> = { jsonApiData: automation };
+      params.fields.forEach((field) => {
+        entry[field] = (automation as any)[field as keyof EmailAutomationInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  // Typography role 15 (numeric): tabular-nums, end-aligned. NEVER
+  // font-mono — no monospace font is loaded in these apps.
+  const numericColumn = (
+    field: EmailAutomationFields,
+    header: string,
+    read: (a: EmailAutomationInterface) => number,
+  ) => ({
+    id: field,
+    accessorKey: field,
+    header: header,
+    cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+      const automation: EmailAutomationInterface = row.original.jsonApiData;
+      return <span className="block text-xs tabular-nums text-end">{read(automation) ?? 0}</span>;
+    },
+    enableSorting: false,
+    enableHiding: false,
+  });
+
+  const fieldColumnMap: Partial<Record<EmailAutomationFields, () => any>> = {
+    [EmailAutomationFields.name]: () => ({
+      id: "name",
+      accessorKey: "name",
+      header: t("emailAutomations.list.columns.name"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        return <Link href={generateUrl({ page: Modules.EmailAutomation, id: automation.id })}>{automation.name}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.trigger]: () => ({
+      id: "trigger",
+      accessorKey: "trigger",
+      header: t("emailAutomations.list.columns.trigger"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        if (!automation.trigger) return <span className="text-muted-foreground text-xs">—</span>;
+        return <span className="text-sm">{triggerLabels[automation.trigger] ?? automation.trigger}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("emailAutomations.list.columns.status"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        return automation.isActive ? (
+          <Badge variant="softGreen">{t("emailAutomations.list.status.on")}</Badge>
+        ) : (
+          <Badge variant="softGray">{t("emailAutomations.list.status.off")}</Badge>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.steps]: () =>
+      numericColumn(EmailAutomationFields.steps, t("emailAutomations.list.columns.steps"), (a) => a.stepCount),
+    [EmailAutomationFields.active]: () =>
+      numericColumn(EmailAutomationFields.active, t("emailAutomations.list.columns.active"), (a) => a.activeCount),
+    [EmailAutomationFields.completed]: () =>
+      numericColumn(
+        EmailAutomationFields.completed,
+        t("emailAutomations.list.columns.completed"),
+        (a) => a.completedCount,
+      ),
+    [EmailAutomationFields.unsubscribed]: () =>
+      numericColumn(
+        EmailAutomationFields.unsubscribed,
+        t("emailAutomations.list.columns.unsubscribed"),
+        (a) => a.unsubscribedCount,
+      ),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<EmailAutomationInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("email-automations", useEmailAutomationTableStructure);

package/src/features/email-automation/index.ts

@@ -0,0 +1,5 @@
+export * from "./EmailAutomationModule";
+export * from "./EmailAutomationStepModule";
+export * from "./EmailAutomationEnrollmentModule";
+export * from "./EmailAutomationTriggerModule";
+export * from "./data";

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>