create-ailk 0.7.0 → 0.8.0

package/templates/apps/web/app/[locale]/contact/__tests__/page-renderer-migration.test.tsx

@@ -1,42 +1,25 @@
 /**
- * HTML snapshot regression tests for contact/page.tsx → @working-theory/page-renderer migration.
+ * contact/page.tsx — render regression + the #6730 D8 contract.
  *
- * Contact uses sections mode (not bodyMode: "mdx-body") with a
- * ConversationalIntakeWrapper wrapper:
- *   <>{renderPage output}<ConversationalIntakeWrapper /></>
+ * Contact uses sections mode (not bodyMode: "mdx-body"). Since #6730 the page
+ * places ONE contact surface, first match wins: into the page's first
+ * `contact-form` section; else into a leading split hero; else after the
+ * page. The surface is the shared `LeadCaptureForm` block — or, when the API
+ * says this deployment accepts no contact message, `ContactFallback` with the
+ * site's contact email and NO form. A failed status read (unreachable API)
+ * renders the form: its submit then reports honestly.
  *
- * Two-commit strategy:
- *   Commit 1: this file added; snapshots captured against pre-migration route (RED-passing).
- *   Commit 2: route migrated; same snapshots verify diff=0 (GREEN).
- *
- * #4534 (epic #4521's integration leg) swapped the page's direct
- * `<ContactForm/>` mount for `<ConversationalIntakeWrapper/>` (which itself
- * renders the existing ContactForm on Skip or a failed auto-submit — see
- * that component's own doc-comment). The mock below + the snapshots'
- * `contact-form-stub` testid moved with it, deliberately — this is the one
- * legitimate case the file's own "DO NOT regenerate to pass" warning
- * doesn't cover: the page's actual composition changed, not the renderer.
- *
- * Two states tested:
- *   - empty: getMdxSource returns null → renderPage empty-state + wrapper present
- *   - populated: getMdxSource returns populated source → renderPage sections + wrapper present
- *
- * Note on ConversationalIntakeWrapper in tests: it composes ContactForm
- * (skip/fallback surface), which is a "use client" component using
- * useFormState/useFormStatus hooks — jsdom does not support these hooks.
- * The wrapper renders as an opaque stub via the next-intl and react-dom
- * mocks below. The snapshot asserts the wrapper is present in the output
- * (non-null).
- *
- * Failure = snapshot diff > 0 bytes beyond the deliberate #4534 rename.
+ * Boundaries mocked: `@working-theory/ui` (the renderer's section tree is a
+ * stub that renders each section's slotted node, so placement is visible),
+ * `@working-theory/api-client` (`leads.captureStatus`), `next-intl/server`,
+ * the `_site.mdx` contact-email read, and the Server Action module.
  */
 import React from "react";
-import { render } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
 
-// ── @working-theory/ui mock ─────────────────────────────────────────────────────────────
+// ── @working-theory/ui mock ─────────────────────────────────────────────────
 jest.mock("@working-theory/ui", () => ({
-  // #4446/#4447: renderPage's own fallback/empty-state title now composes
-  // Heading (mobile type-budget classes, #4417) instead of a bare <h1>.
+  // #4446/#4447: renderPage's own fallback/empty-state title composes Heading.
   Heading: ({
     children,
     level,
@@ -44,72 +27,232 @@ jest.mock("@working-theory/ui", () => ({
     children: React.ReactNode;
     level: number;
   }): React.ReactElement => React.createElement(`h${level}`, null, children),
-  SectionRenderer: ({ sections }: { sections: unknown[] }) =>
-    React.createElement("div", {
-      "data-testid": "section-renderer",
-      "data-section-count": String(sections.length),
-    }),
+  SectionRenderer: ({
+    sections,
+    sectionSlots,
+  }: {
+    sections: Array<{ id: string }>;
+    sectionSlots?: Record<string, React.ReactNode>;
+  }) =>
+    React.createElement(
+      "div",
+      {
+        "data-testid": "section-renderer",
+        "data-section-count": String(sections.length),
+      },
+      sections.map((s) =>
+        React.createElement(
+          "div",
+          { key: s.id, "data-section-id": s.id },
+          sectionSlots?.[s.id],
+        ),
+      ),
+    ),
+  localeHref: (locale: string, path: string) => `/${locale}${path}`,
+  LeadCaptureForm: (props: {
+    fields?: Array<{ name: string }>;
+    submitLabel?: string;
+    fallbackEmail?: string;
+    termsHref: string;
+  }) =>
+    React.createElement(
+      "div",
+      {
+        "data-testid": "lead-capture-form",
+        "data-fields": (props.fields ?? []).map((f) => f.name).join(","),
+        "data-fallback-email": props.fallbackEmail ?? "",
+        "data-terms-href": props.termsHref,
+      },
+      React.createElement("button", { "data-testid": "contact-submit" }, props.submitLabel ?? "Send"),
+    ),
+  ContactFallback: (props: { email?: string; text?: { noEmail?: string } }) =>
+    React.createElement(
+      "div",
+      { "data-testid": "contact-fallback" },
+      props.email
+        ? React.createElement("a", { href: `mailto:${props.email}` }, props.email)
+        : props.text?.noEmail,
+    ),
 }));
 
-// ── ConversationalIntakeWrapper mock ────────────────────────────────────────
-// ConversationalIntakeWrapper composes ContactForm ("use client",
-// useFormState/useFormStatus — crashes in jsdom) as its skip/fallback
-// surface. Mock the wrapper itself as a deterministic stub so the snapshot
-// is stable; the wrapper's own submission/skip/analytics wiring is covered
-// by ConversationalIntakeWrapper.test.tsx.
-// eslint-disable-next-line no-restricted-syntax -- test-seam mock required; composes ContactForm, which uses useFormState/useFormStatus that crash in jsdom; internal-module mock is the narrowest possible scope; tracked in #507
-jest.mock("../ContactForm", () => ({
-  ContactForm: () =>
-    React.createElement("div", { "data-testid": "contact-form-stub" }),
+jest.mock("@working-theory/api-client", () => ({
+  leads: { captureStatus: jest.fn(), submit: jest.fn() },
 }));
 
+// The real English catalog, so renderPage's own strings render as they ship.
+jest.mock("next-intl/server", () => {
+  const messages = jest.requireActual("../../../../messages/en.json") as Record<
+    string,
+    Record<string, unknown>
+  >;
+  return {
+    getTranslations: async (arg: string | { namespace: string }) => {
+      const ns = messages[typeof arg === "string" ? arg : arg.namespace] ?? {};
+      return (key: string) => (ns[key] ?? key) as string;
+    },
+  };
+});
+
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: the real read is a node:fs frontmatter parse of content/_site.mdx; narrowest possible scope
+jest.mock("../site-contact-email", () => ({
+  readSiteContactEmail: jest.fn(),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: the Server Action module is a "use server" boundary; the page only passes it through
+jest.mock("../contact.actions", () => ({
+  captureLeadAction: jest.fn(),
+}));
+
+import { leads } from "@working-theory/api-client";
+
 import ContactPage from "../page";
+import { readSiteContactEmail } from "../site-contact-email";
+
+const mockCaptureStatus = leads.captureStatus as jest.Mock;
+const mockContactEmail = readSiteContactEmail as jest.Mock;
 
-const getMdxSourceEmpty = jest.fn().mockResolvedValue(null);
-const getPageSectionsEmpty = jest.fn().mockResolvedValue([]);
+const ACCEPTING = { ok: true, status: 200, body: { ok: true, data: { contact: true, newsletter: false } } };
+const REFUSING = { ok: true, status: 200, body: { ok: true, data: { contact: false, newsletter: false } } };
+
+const source = {
+  frontmatter: {
+    type: "ContactPage" as const,
+    slug: "contact",
+    title: "Contact Us",
+    description: "Get in touch.",
+  },
+  body: "",
+};
+
+const splitHero = { id: "hero", type: "hero", data: { variant: "split", headline: "Hi" } };
+const contactFormSection = {
+  id: "contact-form",
+  type: "contact-form",
+  data: {
+    fields: [
+      { name: "email", label: "Email", type: "email" },
+      { name: "plan", label: "Plan", type: "select", options: ["free", "pro"] },
+    ],
+    submitLabel: "Request a demo",
+  },
+};
+
+async function renderWith(sections: unknown[] | null) {
+  const element = await ContactPage({
+    params: Promise.resolve({ locale: "en" }),
+    getMdxSource: jest.fn().mockResolvedValue(sections === null ? null : source),
+    getPageSections: jest.fn().mockResolvedValue(sections ?? []),
+  });
+  return render(element);
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockCaptureStatus.mockResolvedValue(ACCEPTING);
+  mockContactEmail.mockReturnValue(undefined);
+});
 
 describe("ContactPage — snapshot regression", () => {
-  it("empty state renders deterministic HTML (renderPage empty-state + ContactForm present)", async () => {
-    const element = await ContactPage({
-      params: Promise.resolve({ locale: "en" }),
-      getMdxSource: getMdxSourceEmpty,
-      getPageSections: getPageSectionsEmpty,
-    });
-    const { container } = render(element);
-    // ContactForm must be present even in empty-state
-    expect(
-      container.querySelector('[data-testid="contact-form-stub"]'),
-    ).not.toBeNull();
+  it("empty state renders deterministic HTML (renderPage empty-state + the form after it)", async () => {
+    const { container } = await renderWith(null);
     expect(container.innerHTML).toMatchInlineSnapshot(
-      `"<main id="main"><h1>Contact</h1><p data-testid="section-empty-state">Contact page content coming soon.</p></main><div data-testid="contact-form-stub"></div>"`,
+      `"<main id="main"><h1>Contact</h1><p data-testid="section-empty-state">Contact page content coming soon.</p></main><div data-testid="lead-capture-form" data-fields="" data-fallback-email="" data-terms-href="/en/terms"><button data-testid="contact-submit">Send</button></div>"`,
     );
   });
 
-  it("populated state renders deterministic HTML (renderPage sections + ContactForm present)", async () => {
-    const source = {
-      frontmatter: {
-        type: "ContactPage" as const,
-        slug: "contact",
-        title: "Contact Us",
-        description: "Get in touch.",
-      },
-      body: "",
-    };
-    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
-    const getPageSectionsPopulated = jest.fn().mockResolvedValue([]);
-
-    const element = await ContactPage({
-      params: Promise.resolve({ locale: "en" }),
-      getMdxSource: getMdxSourcePopulated,
-      getPageSections: getPageSectionsPopulated,
-    });
-    const { container } = render(element);
-    // ContactForm must be present in populated state too
+  it("populated state renders deterministic HTML (renderPage sections + the form after it)", async () => {
+    const { container } = await renderWith([]);
+    expect(container.innerHTML).toMatchInlineSnapshot(
+      `"<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"ContactPage","inLanguage":"en","name":"Contact Us","description":"Get in touch.","mainEntity":{"@type":"ContactPoint","contactType":"customer support"}}</script><main id="main"><h1>Contact Us</h1><p data-testid="contact-description">Get in touch.</p><div data-testid="section-renderer" data-section-count="0"></div></main><div data-testid="lead-capture-form" data-fields="" data-fallback-email="" data-terms-href="/en/terms"><button data-testid="contact-submit">Send</button></div>"`,
+    );
+  });
+});
+
+describe("ContactPage — placement (#6730 D8)", () => {
+  it("a contact-form section hosts the form, with that section's fields and label", async () => {
+    const { container } = await renderWith([splitHero, contactFormSection]);
+
+    const slot = container.querySelector("[data-section-id='contact-form']")!;
+    const form = slot.querySelector("[data-testid='lead-capture-form']");
+    expect(form).not.toBeNull();
+    expect(form).toHaveAttribute("data-fields", "email,plan");
+    expect(slot).toHaveTextContent("Request a demo");
+    expect(screen.getAllByTestId("lead-capture-form")).toHaveLength(1);
+  });
+
+  it("no contact-form section + a leading split hero → inside the hero", async () => {
+    const { container } = await renderWith([splitHero]);
+
     expect(
-      container.querySelector('[data-testid="contact-form-stub"]'),
+      container.querySelector("[data-section-id='hero'] [data-testid='lead-capture-form']"),
     ).not.toBeNull();
-    expect(container.innerHTML).toMatchInlineSnapshot(
-      `"<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"ContactPage","inLanguage":"en","name":"Contact Us","description":"Get in touch.","mainEntity":{"@type":"ContactPoint","contactType":"customer support"}}</script><main id="main"><h1>Contact Us</h1><p data-testid="contact-description">Get in touch.</p><div data-testid="section-renderer" data-section-count="0"></div></main><div data-testid="contact-form-stub"></div>"`,
+    expect(screen.getAllByTestId("lead-capture-form")).toHaveLength(1);
+  });
+
+  it("neither → after the page", async () => {
+    const { container } = await renderWith([
+      { id: "faq", type: "faq", data: { items: [] } },
+    ]);
+
+    expect(container.querySelector("main [data-testid='lead-capture-form']")).toBeNull();
+    expect(screen.getAllByTestId("lead-capture-form")).toHaveLength(1);
+  });
+
+  it("passes the site's contact email to the form's unavailable state", async () => {
+    mockContactEmail.mockReturnValue("hi@example.com");
+    await renderWith([]);
+    expect(screen.getByTestId("lead-capture-form")).toHaveAttribute(
+      "data-fallback-email",
+      "hi@example.com",
     );
   });
 });
+
+describe("ContactPage — no lead destination (#6730 D8)", () => {
+  it("status contact:false + a contactEmail → the fallback with a mailto link, and no form", async () => {
+    mockCaptureStatus.mockResolvedValue(REFUSING);
+    mockContactEmail.mockReturnValue("hi@example.com");
+
+    await renderWith([]);
+
+    const fallback = screen.getByTestId("contact-fallback");
+    expect(fallback.querySelector("a[href='mailto:hi@example.com']")).not.toBeNull();
+    expect(screen.queryByTestId("contact-submit")).toBeNull();
+    expect(screen.queryByTestId("lead-capture-form")).toBeNull();
+  });
+
+  it("status contact:false + no contactEmail → the no-email copy, and no form", async () => {
+    mockCaptureStatus.mockResolvedValue(REFUSING);
+
+    await renderWith([]);
+
+    expect(screen.getByTestId("contact-fallback")).toHaveTextContent(
+      "Contact details for this site haven't been published yet.",
+    );
+    expect(screen.queryByTestId("contact-submit")).toBeNull();
+  });
+
+  it("the fallback takes the contact-form section's place too", async () => {
+    mockCaptureStatus.mockResolvedValue(REFUSING);
+    mockContactEmail.mockReturnValue("hi@example.com");
+
+    const { container } = await renderWith([contactFormSection]);
+
+    expect(
+      container.querySelector("[data-section-id='contact-form'] [data-testid='contact-fallback']"),
+    ).not.toBeNull();
+  });
+
+  it.each([
+    ["rejects (unreachable API)", () => mockCaptureStatus.mockRejectedValue(new Error("ECONNREFUSED"))],
+    ["404 (older API)", () => mockCaptureStatus.mockResolvedValue({ ok: false, status: 404, body: {} })],
+    ["5xx", () => mockCaptureStatus.mockResolvedValue({ ok: false, status: 503, body: {} })],
+  ])("status %s → the form renders", async (_label, arrange) => {
+    arrange();
+
+    await renderWith([]);
+
+    expect(screen.getByTestId("contact-submit")).toBeInTheDocument();
+    expect(screen.queryByTestId("contact-fallback")).toBeNull();
+  });
+});

package/templates/apps/web/app/[locale]/contact/contact-form-text.ts

@@ -0,0 +1,50 @@
+/**
+ * contactFormText — the `contact` message namespace mapped onto the shared
+ * `LeadCaptureForm` block's copy (#6730 D8).
+ *
+ * One pure mapping, shared by the RSC page (`getTranslations`) and the client
+ * `ConversationalIntakeWrapper` (`useTranslations`), so the two surfaces that
+ * render the form can never label it differently. `unavailableBody` keeps
+ * its `{email}` placeholder (interpolated back to itself): the block fills
+ * it, since only the block knows the address it is showing.
+ */
+
+import type { LeadCaptureFormText } from "@working-theory/ui";
+
+type ContactTextKey =
+  | "nameLabel"
+  | "emailLabel"
+  | "messageLabel"
+  | "sendMessage"
+  | "sending"
+  | "successMessage"
+  | "genericError"
+  | "consentStatement"
+  | "unavailableHeading"
+  | "unavailableBody"
+  | "unavailableNoEmail";
+
+/** The subset of a `contact`-namespace translator this mapping reads. */
+export type ContactTranslator = (
+  key: ContactTextKey,
+  values?: { email: string },
+) => string;
+
+/** Keeps the `{email}` placeholder for the block to fill. */
+const KEEP_EMAIL_PLACEHOLDER = { email: "{email}" };
+
+export function contactFormText(t: ContactTranslator): LeadCaptureFormText {
+  return {
+    nameLabel: t("nameLabel"),
+    emailLabel: t("emailLabel"),
+    messageLabel: t("messageLabel"),
+    submit: t("sendMessage"),
+    sending: t("sending"),
+    success: t("successMessage"),
+    genericError: t("genericError"),
+    consentStatement: t("consentStatement"),
+    unavailableHeading: t("unavailableHeading"),
+    unavailableBody: t("unavailableBody", KEEP_EMAIL_PLACEHOLDER),
+    unavailableNoEmail: t("unavailableNoEmail"),
+  };
+}

package/templates/apps/web/app/[locale]/contact/contact.actions.ts

@@ -5,12 +5,25 @@
  *
  * Validates contact-form input with submitLeadInputSchema (shared schema per
  * ADR 0013), calls POST /v1/leads/submit via @working-theory/api-client, and returns
- * a discriminated ActionResult suitable for useFormState.
+ * the shared `LeadCaptureForm` block's `LeadCaptureFormState`.
  *
  * Canonical filename: contact.actions.ts (*.actions.ts per ADR 0013 / U0 spec
  * parity-test regex `ACTION_FILE_RE = /\.actions\.ts$/`).
  *
- * Honeypot + rate-limit enforcement lives in apps/api; no duplication here.
+ * Rate-limit enforcement lives in apps/api; the honeypot is checked here.
+ *
+ * Outcome (#6730 D8): the API's 503 `lead_capture_not_configured` — this
+ * deployment has nowhere to put a lead — maps to `{ kind: "unavailable" }`,
+ * which the shared `LeadCaptureForm` renders as the site's contact email.
+ * Every other non-2xx and every thrown error is the generic `error`; only a
+ * 2xx is ever `success`.
+ *
+ * Extra fields (#6730 D8a): a `contact-form` section can declare fields
+ * beyond name/email/message/phone (a `select`, say). Every other string
+ * field that is not reserved and not a Next internal (`$ACTION_…`) is carried
+ * into `payload` — at most `MAX_EXTRA_FIELDS` keys, each at most
+ * `MAX_EXTRA_FIELD_LENGTH` characters, else a form-level error. A reserved
+ * name can never override `name`/`email`/`source`.
  *
  * `source` (#4534, epic #4521's integration leg): an optional hidden
  * FormData field so `ConversationalIntakeWrapper` can tag leads it submits
@@ -25,21 +38,62 @@
  */
 
 import { leads } from "@working-theory/api-client";
+import { LEAD_CAPTURE_HONEYPOT, type LeadCaptureFormState } from "@working-theory/ui";
 import { submitLeadInputSchema } from "@working-theory/validation";
 
-export type ActionResult =
-  | { kind: "success" }
-  | {
-      kind: "error";
-      message?: string;
-      fieldErrors?: Record<string, string>;
-    }
-  | null;
+const GENERIC_ERROR = "Something went wrong, please try again.";
+
+/** Field names the action reads itself — never copied into `payload`. */
+const RESERVED_FIELDS = new Set([
+  "name",
+  "email",
+  "message",
+  "phone",
+  "consent",
+  LEAD_CAPTURE_HONEYPOT,
+  "source",
+]);
+const MAX_EXTRA_FIELDS = 20;
+const MAX_EXTRA_FIELD_LENGTH = 2000;
+
+/**
+ * The declared extra fields, or `null` when they exceed the bounds. Non-string
+ * entries (files) and Next's own `$ACTION_…` keys are skipped.
+ */
+function extraFields(formData: FormData): Record<string, string> | null {
+  const extra: Record<string, string> = {};
+  let count = 0;
+  for (const [key, value] of formData.entries()) {
+    if (RESERVED_FIELDS.has(key) || key.startsWith("$ACTION")) continue;
+    if (typeof value !== "string") continue;
+    if (value.length > MAX_EXTRA_FIELD_LENGTH) return null;
+    if (!Object.hasOwn(extra, key)) count += 1;
+    if (count > MAX_EXTRA_FIELDS) return null;
+    extra[key] = value;
+  }
+  return extra;
+}
+
+/** A 503 whose body names `lead_capture_not_configured`. */
+function isNotConfigured(res: { status: number; body: unknown }): boolean {
+  return (
+    res.status === 503 &&
+    typeof res.body === "object" &&
+    res.body !== null &&
+    (res.body as { error?: unknown }).error === "lead_capture_not_configured"
+  );
+}
 
 export async function captureLeadAction(
-  _prevState: ActionResult,
+  _prevState: LeadCaptureFormState,
   formData: FormData,
-): Promise<ActionResult> {
+): Promise<LeadCaptureFormState> {
+  // Honeypot: people never see `LEAD_CAPTURE_HONEYPOT`; a bot that fills it
+  // gets the same answer a person would, and nothing is sent. The API does
+  // not check it.
+  const honeypot = formData.get(LEAD_CAPTURE_HONEYPOT);
+  if (typeof honeypot === "string" && honeypot !== "") return { kind: "success" };
+
   const raw = {
     name: formData.get("name"),
     email: formData.get("email"),
@@ -59,6 +113,9 @@ export async function captureLeadAction(
     return { kind: "error", fieldErrors };
   }
 
+  const extra = extraFields(formData);
+  if (extra === null) return { kind: "error", message: GENERIC_ERROR };
+
   const { name, email, message, phone } = parsed.data;
   const siteId = process.env.AILK_SITE_ID ?? "default";
   const source = (formData.get("source") as string | null) || "web";
@@ -67,6 +124,7 @@ export async function captureLeadAction(
     source,
     email,
     payload: {
+      ...extra,
       name,
       ...(message !== undefined && { message }),
       ...(phone !== undefined && { phone }),
@@ -76,10 +134,8 @@ export async function captureLeadAction(
   try {
     const res = await leads.submit(body);
     if (!res.ok) {
-      return {
-        kind: "error",
-        message: "Something went wrong, please try again.",
-      };
+      if (isNotConfigured(res)) return { kind: "unavailable" };
+      return { kind: "error", message: GENERIC_ERROR };
     }
     return { kind: "success" };
   } catch (err) {
@@ -89,9 +145,6 @@ export async function captureLeadAction(
     // itself is safe — no submitted form fields (name/email/message/phone)
     // are included.
     console.error("[captureLeadAction]", err);
-    return {
-      kind: "error",
-      message: "Something went wrong, please try again.",
-    };
+    return { kind: "error", message: GENERIC_ERROR };
   }
 }