create-ailk 0.22.0 → 0.24.0

package/templates/apps/web/app/[locale]/flows/[slug]/FlowStepperClient.tsx

@@ -44,6 +44,26 @@
  * URL the walk navigates to (NFR1), and each link sits in a Session-Replay
  * `data-sentry-block` element, since the scrub cannot reach a DOM `href`.
  *
+ * The standard magnet's parts (#8840 D9): the consent registry is the
+ * platform default with the locale's `/terms` and `/privacy` links
+ * (`consentPoliciesFor`, the map every agreement surface uses); a `message`
+ * step is shown but not counted in "Step N of M"; `hiddenValues` and `header`
+ * pass through from the page. When the config carries an `ending`, it is the
+ * one ending: `onCompleted` is not passed (so neither `thankYou` nor a
+ * recommending flow's permalink runs), and on the completing response the
+ * client picks the outcome from the answers it accumulated
+ * (`selectFlowEndingOutcome`) — a screen in the stepper's finished card,
+ * `{name}` filled from the walk, or a redirect to a site path. Every
+ * destination is re-checked against `flowSitePathSchema` before it renders or
+ * navigates (the served config is not re-parsed, SEC-8840-H).
+ *
+ * The deliverable (#8848 D8): a completing response's `deliverable` is drawn
+ * after the ending screen — the reader link for a file (its grant in `?g=`,
+ * inside a `data-sentry-block` element), an inline player for a video, a link
+ * for a page or an outside address — each target re-checked before it
+ * renders. A redirect ending never runs when the response carries one, and a
+ * gated file walk whose response has none says the link is in the email.
+ *
  * Locale validation before interpolation (AILK #4707, security review on
  * samhenry PR #163): the `[locale]` route segment is a Next.js dynamic
  * segment — the framework matches ANY string there, and next-intl's
@@ -58,29 +78,46 @@
  * bundle, the same reasoning `middleware.ts` already documents for the
  * Edge runtime) before it ever reaches the template literal.
  */
-import { Button, Link } from "@working-theory/ui";
+import { Button, Heading, Link, localeHref, Text } from "@working-theory/ui";
+import { VideoEmbed } from "@working-theory/ui/blocks";
 import {
   FlowStepper,
   type FlowStepperMessages,
   type FlowStepSubmitPayload,
   type FlowStepSubmitResult,
 } from "@working-theory/ui-signal-collectors";
-import type { AeoScoreResult, FlowConfig, FlowState } from "@working-theory/validation";
+import type {
+  AeoScoreResult,
+  FlowConfig,
+  FlowEndingOutcome,
+  FlowState,
+  FlowStepDeliverable,
+} from "@working-theory/validation";
 import {
   deriveFlags,
   encodePermalink,
+  fillEndingName,
   flattenState,
+  flowHttpsUrlSchema,
+  flowSitePathSchema,
+  flowStepDeliverableSchema,
   flowStepNextSchema,
   hiddenAnswers,
   PERMALINK_VERSION,
   pruneHiddenState,
+  resolveLocalizedString,
   resolveThankYouSlug,
+  selectFlowEndingOutcome,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+  visitorNameOf,
 } from "@working-theory/validation";
 import { useRouter } from "next/navigation";
 import { useMessages, useTranslations } from "next-intl";
-import type { ReactElement } from "react";
+import type { ReactElement, ReactNode } from "react";
 import { useRef, useState } from "react";
 
+import { consentPoliciesFor } from "../../../../lib/consent-policies";
+
 import { accountInviteLinkAction } from "./account-invite.actions";
 import { submitFlowStepAction } from "./flow.actions";
 
@@ -88,6 +125,10 @@ interface Props {
   config: FlowConfig;
   locale: string;
   slug: string;
+  /** #8840 D9 — page-supplied `hidden` field values (a posting's slug). */
+  hiddenValues?: Readonly<Record<string, string>>;
+  /** #8840 D9 — the walk's back arrow, above the step. */
+  header?: ReactNode;
 }
 
 const DEFAULT_LOCALE = "en";
@@ -122,6 +163,24 @@ function mappedEmailOf(
   return undefined;
 }
 
+/**
+ * #8848 D8 — the completing response's `deliverable`, each target re-checked:
+ * a video whose `src` is refused is nothing, a refused `poster` is dropped;
+ * every other kind must parse whole.
+ */
+function safeDeliverable(raw: unknown): FlowStepDeliverable | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const video = raw as { kind?: unknown; src?: unknown; poster?: unknown };
+  if (video.kind === "video") {
+    const src = flowHttpsUrlSchema.safeParse(video.src);
+    if (!src.success) return undefined;
+    const poster = flowHttpsUrlSchema.safeParse(video.poster);
+    return { kind: "video", src: src.data, ...(poster.success ? { poster: poster.data } : {}) };
+  }
+  const parsed = flowStepDeliverableSchema.safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+}
+
 /**
  * D7 (#4770) — every question `name` contributed by a `segmentation`-typed
  * step. This is the allowlist the encoded permalink is filtered to: a
@@ -140,10 +199,23 @@ function segmentationQuestionNames(config: FlowConfig): Set<string> {
   return names;
 }
 
+/**
+ * #8840 D9 — the answers the ending is chosen from, assembled as the
+ * permalink path assembles them: the visible steps' answers flattened, then
+ * the hidden segmentation steps' `whenHidden` answers.
+ */
+function walkAnswers(config: FlowConfig, state: FlowState): Record<string, unknown> {
+  const flags = deriveFlags(config, state);
+  const flat = flattenState(pruneHiddenState(config, state, flags));
+  return Object.assign(flat, hiddenAnswers(config, state, flags));
+}
+
 export function FlowStepperClient({
   config,
   locale,
   slug,
+  hiddenValues,
+  header,
 }: Props): ReactElement {
   const t = useTranslations("flow");
   const router = useRouter();
@@ -171,6 +243,13 @@ export function FlowStepperClient({
   const inviteHrefRef = useRef<string | null>(null);
   const [inviteHref, setInviteHref] = useState<string | null>(null);
   const tContact = useTranslations("contact");
+  // #8840 D9 — a config with an `ending` ends on it, never on `thankYou` or
+  // the permalink; the chosen screen is drawn in the finished card.
+  const endingWins = config.ending !== undefined;
+  const [endingContent, setEndingContent] = useState<ReactNode | undefined>(undefined);
+  // #8848 D8 — the deliverable's action, drawn after the ending screen.
+  const tReports = useTranslations("reports");
+  const [deliverableContent, setDeliverableContent] = useState<ReactNode | undefined>(undefined);
 
   async function handleSubmitStep(
     payload: FlowStepSubmitPayload,
@@ -185,6 +264,8 @@ export function FlowStepperClient({
       emailRef.current = mappedEmailOf(config, payload) ?? emailRef.current;
       if (result.response.completed) {
         await resolveInviteLink(result.response);
+        const delivered = showDeliverable((result.response as { deliverable?: unknown }).deliverable);
+        if (endingWins) showEnding(delivered);
       }
     } else if (result.kind === "step_conflict") {
       answersRef.current = {};
@@ -212,6 +293,133 @@ export function FlowStepperClient({
     }
   }
 
+  // #8848 D8 — draw the response's deliverable (true when there is one), or,
+  // for a gated file walk that minted no grant, the by-email line.
+  function showDeliverable(raw: unknown): boolean {
+    const deliverable = safeDeliverable(raw);
+    if (deliverable !== undefined) {
+      setDeliverableContent(deliverableAction(deliverable));
+      return true;
+    }
+    const block = config.deliverable;
+    setDeliverableContent(
+      raw === undefined && block?.kind === "file" && block.gated ? (
+        <Text className="mt-block-tight" data-testid="flow-deliverable-by-email">
+          {tReports("fileByEmail")}
+        </Text>
+      ) : undefined,
+    );
+    return false;
+  }
+
+  function deliverableAction(deliverable: FlowStepDeliverable): ReactNode {
+    const pick = (value: Record<string, string> | undefined): string | undefined =>
+      value === undefined ? undefined : resolveLocalizedString(value, locale, config.defaultLocale);
+    const label = pick(config.deliverable?.cta);
+    if (deliverable.kind === "video") {
+      return (
+        <div className="mt-block-loose" data-testid="flow-deliverable-video">
+          <VideoEmbed
+            sources={[{ src: deliverable.src }]}
+            {...(deliverable.poster !== undefined ? { poster: deliverable.poster } : {})}
+            label={pick(config.deliverable?.title) ?? tReports("openFile")}
+          />
+        </div>
+      );
+    }
+    const href =
+      deliverable.kind === "file"
+        ? localeHref(locale, `/reports/${slug}?g=${encodeURIComponent(deliverable.grantId)}`)
+        : deliverable.kind === "page"
+          ? localeHref(locale, deliverable.href)
+          : deliverable.href;
+    const fallback = deliverable.kind === "external" ? tReports("openExternal") : tReports("openFile");
+    const link = (
+      <Button asChild variant="default" className="min-h-11">
+        <Link
+          href={href}
+          variant="bare"
+          {...(deliverable.kind === "external" ? { external: true } : {})}
+          data-testid="flow-deliverable-action"
+        >
+          {label ?? fallback}
+        </Link>
+      </Button>
+    );
+    // Session Replay records `href`s; the file's carries a bearer grant.
+    return deliverable.kind === "file" ? (
+      <div data-sentry-block className="mt-block-loose flex justify-center">
+        {link}
+      </div>
+    ) : (
+      <div className="mt-block-loose flex justify-center">{link}</div>
+    );
+  }
+
+  // #8840 D9 — the ending for the walk's answers: a redirect to a site path,
+  // else a screen; a destination the schema refuses is never rendered or
+  // pushed (a refused redirect falls back to a screen `default`, else to the
+  // stepper's own finished panel). #8848 D8 — with a deliverable in hand a
+  // redirect never runs, so the deliverable is never lost to a navigation.
+  function showEnding(delivered = false): void {
+    const answers = walkAnswers(config, answersRef.current);
+    const segmentationNames = segmentationQuestionNames(config);
+    const choices: Record<string, string | string[]> = {};
+    for (const [name, value] of Object.entries(answers)) {
+      if (segmentationNames.has(name) && (typeof value === "string" || Array.isArray(value))) {
+        choices[name] = value as string | string[];
+      }
+    }
+    const outcome = selectFlowEndingOutcome(config, choices);
+    if (outcome === undefined) return;
+    if (outcome.kind === "redirect") {
+      if (!delivered && flowSitePathSchema.safeParse(outcome.href).success) {
+        setEndingContent(<></>);
+        router.push(`/${resolveSafeLocale(locale)}${outcome.href}`);
+        return;
+      }
+      const fallback = config.ending?.default;
+      if (fallback?.kind === "screen") setEndingContent(endingScreen(fallback, answers));
+      return;
+    }
+    setEndingContent(endingScreen(outcome, answers));
+  }
+
+  function endingScreen(
+    outcome: Extract<FlowEndingOutcome, { kind: "screen" }>,
+    answers: Record<string, unknown>,
+  ): ReactNode {
+    const name = visitorNameOf(config, answers);
+    const text = (value: Record<string, string>) =>
+      fillEndingName(resolveLocalizedString(value, locale, config.defaultLocale), name);
+    const ctas = (outcome.ctas ?? []).filter(
+      (cta) => flowSitePathSchema.safeParse(cta.href).success,
+    );
+    return (
+      <div data-testid="flow-ending">
+        <Heading level={2}>{text(outcome.headline)}</Heading>
+        {outcome.body !== undefined ? (
+          <Text className="mt-block-tight">{text(outcome.body)}</Text>
+        ) : null}
+        {ctas.length > 0 ? (
+          <div className="mt-block-loose flex flex-wrap justify-center gap-4">
+            {ctas.map((cta) => (
+              <Button key={cta.href} asChild variant="default" className="min-h-11">
+                <Link
+                  href={localeHref(locale, cta.href)}
+                  variant="bare"
+                  data-testid="flow-ending-cta"
+                >
+                  {text(cta.label)}
+                </Link>
+              </Button>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    );
+  }
+
   // #4663 D11 — `aeoScore` passes through untouched: this repo's segment
   // redirect is unchanged; C2's results page (on samhenry) is the consumer
   // of the score.
@@ -342,7 +550,7 @@ export function FlowStepperClient({
   // Session Replay records the DOM, so the link (it carries the email) is
   // blocked from it; `Link` does not forward an undeclared data-* attribute.
   const completedAction =
-    inviteHref !== null && thankYou === undefined && !isRecommending ? (
+    inviteHref !== null && (endingWins || thankYou === undefined) && !isRecommending ? (
       <div data-sentry-block>
         <Button asChild variant="outline" className="mt-4 min-h-11">
           <Link
@@ -356,16 +564,40 @@ export function FlowStepperClient({
       </div>
     ) : undefined;
 
+  // #8848 D8 — the ending screen, then the deliverable; with no ending the
+  // stepper's own finished copy heads the action.
+  const completedContent =
+    deliverableContent !== undefined ? (
+      <>
+        {endingContent ?? (
+          <>
+            <Heading level={2}>{t("completedTitle")}</Heading>
+            <Text className="mt-block-tight">{t("completedBody")}</Text>
+          </>
+        )}
+        {deliverableContent}
+      </>
+    ) : (
+      endingContent
+    );
+
   return (
     <FlowStepper
       config={config}
       locale={locale}
       messages={messages}
       onSubmitStep={handleSubmitStep}
-      {...(thankYou !== undefined || isRecommending
+      {...(!endingWins && (thankYou !== undefined || isRecommending)
         ? { onCompleted: handleCompleted }
         : {})}
       {...(completedAction !== undefined ? { completedAction } : {})}
+      // #8840 D9 — the locale's policy links, the input-step count, and the
+      // page's hidden values, header and ending.
+      consentConfig={{ ...SITE_CONSENT_CONFIG_DEFAULTS, policies: consentPoliciesFor(locale) }}
+      uncountedStepKeys={config.steps.filter((step) => step.type === "message").map((step) => step.key)}
+      {...(hiddenValues !== undefined ? { hiddenValues } : {})}
+      {...(header !== undefined ? { header } : {})}
+      {...(completedContent !== undefined ? { completedContent } : {})}
     />
   );
 }

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/FlowStepperClient.count.test.tsx

@@ -0,0 +1,43 @@
+// oss: false
+/**
+ * #8840 D9, AC-3 — unmocked: with the real FlowStepper, a walk of three input
+ * steps and a closing message reads "Step 1 of 3" — the closing message is
+ * shown but not counted.
+ */
+import { render, screen } from "@testing-library/react";
+import type { FlowConfig } from "@working-theory/validation";
+
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: jest.fn() }),
+}));
+
+jest.mock("next-intl", () => ({
+  useTranslations: () => (key: string, values?: Record<string, unknown>) =>
+    key === "progress" ? `Step ${String(values?.["current"])} of ${String(values?.["total"])}` : key,
+  useMessages: () => ({}),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- the boundary under test is the client wiring, not the actions
+jest.mock("../flow.actions", () => ({ submitFlowStepAction: jest.fn() }));
+// eslint-disable-next-line no-restricted-syntax -- see above
+jest.mock("../account-invite.actions", () => ({ accountInviteLinkAction: jest.fn() }));
+
+import { FlowStepperClient } from "../FlowStepperClient";
+
+const en = (s: string) => ({ en: s });
+const field = (key: string) => ({
+  key,
+  type: "field" as const,
+  copy: { title: en(key) },
+  fields: [{ name: key, inputType: "text" as const, copy: { label: en(key) } }],
+});
+
+it("counts the three input steps and not the closing message", () => {
+  const config = {
+    slug: "three",
+    defaultLocale: "en",
+    steps: [field("one"), field("two"), field("three"), { key: "bye", type: "message", copy: { title: en("Bye") } }],
+  } as FlowConfig;
+  render(<FlowStepperClient config={config} locale="en" slug="three" />);
+  expect(screen.getByTestId("flow-stepper-progress-label").textContent).toBe("Step 1 of 3");
+});

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/FlowStepperClient.deliverable.test.tsx

@@ -0,0 +1,200 @@
+// oss: false
+/**
+ * #8848 D8, AC-5 — the ending delivers the deliverable by kind. FlowStepper
+ * is the ending suite's stub: it submits the configured steps through the
+ * real `onSubmitStep` and renders the `completedContent` it is given.
+ */
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { FlowConfig } from "@working-theory/validation";
+import type { ReactElement, ReactNode } from "react";
+
+const mockPush = jest.fn();
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: mockPush }),
+}));
+
+jest.mock("next-intl", () => ({
+  useTranslations: (namespace?: string) => (key: string) => (namespace ? `${namespace}.${key}` : key),
+  useMessages: () => ({}),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- the boundary under test is the client wiring, not the actions
+jest.mock("../flow.actions", () => ({ submitFlowStepAction: jest.fn() }));
+// eslint-disable-next-line no-restricted-syntax -- see above
+jest.mock("../account-invite.actions", () => ({ accountInviteLinkAction: jest.fn() }));
+
+interface StubProps {
+  onSubmitStep: (payload: { stepKey: string; values: Record<string, unknown> }) => Promise<unknown>;
+  completedContent?: ReactNode;
+}
+
+jest.mock("@working-theory/ui-signal-collectors", () => ({
+  FlowStepper: (props: StubProps) => {
+    const react = require("react");
+    return react.createElement(
+      "div",
+      { "data-testid": "mock-card" },
+      react.createElement(
+        "button",
+        {
+          "data-testid": "mock-submit",
+          onClick: () => props.onSubmitStep({ stepKey: "contact", values: { email: "ana@example.com" } }),
+        },
+        "Submit",
+      ),
+      props.completedContent,
+    ) as ReactElement;
+  },
+}));
+
+import { submitFlowStepAction } from "../flow.actions";
+import { FlowStepperClient } from "../FlowStepperClient";
+
+const mockSubmit = submitFlowStepAction as jest.MockedFunction<typeof submitFlowStepAction>;
+const en = (s: string) => ({ en: s });
+
+/**
+ * A served config (#8848 D2): a gated block's target is projected out, which
+ * `FlowConfig` (the type `flows.get` answers with) cannot express — the one
+ * cast lives here.
+ */
+function config(extra: Record<string, unknown> = {}): FlowConfig {
+  const served = {
+    slug: "q3",
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "contact",
+        type: "field",
+        copy: { title: en("Get the report") },
+        fields: [{ name: "email", inputType: "email", required: true, mapsTo: "email", copy: { label: en("Email") } }],
+      },
+    ],
+    deliverable: {
+      kind: "file",
+      gated: true,
+      title: en("Q3 report"),
+      cta: en("Read the report"),
+      geometry: "letter",
+      pages: 3,
+    },
+    deliverables: { assets: [{ assetKey: "q3.pdf" }], copy: { subject: en("s"), body: en("b") } },
+    ...extra,
+  };
+  // eslint-disable-next-line no-restricted-syntax -- a served gated block omits its target, which FlowConfig cannot express (see above)
+  return served as unknown as FlowConfig;
+}
+
+function respondWith(deliverable?: unknown): void {
+  mockSubmit.mockResolvedValue({
+    ok: true,
+    response: {
+      sessionId: "s1",
+      landed: "contact",
+      nextStepKey: null,
+      completed: true,
+      ...(deliverable !== undefined ? { deliverable } : {}),
+    },
+  } as Awaited<ReturnType<typeof submitFlowStepAction>>);
+}
+
+async function walk(cfg: FlowConfig, locale = "en"): Promise<void> {
+  render(<FlowStepperClient config={cfg} locale={locale} slug="q3" />);
+  await userEvent.setup().click(screen.getByTestId("mock-submit"));
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe("the ending delivers the deliverable (#8848 D8, AC-5)", () => {
+  it("a file response links the reader with its grant, labelled the block's cta", async () => {
+    respondWith({ kind: "file", grantId: "dgrant_x" });
+    await walk(config());
+
+    const action = await screen.findByTestId("flow-deliverable-action");
+    // `localeHref`: the default locale is unprefixed (`localePrefix: "as-needed"`).
+    expect(action.getAttribute("href")).toBe("/reports/q3?g=dgrant_x");
+    expect(action.textContent).toBe("Read the report");
+    expect(action.closest("[data-sentry-block]")).not.toBeNull();
+  });
+
+  it("prefixes another locale's reader link", async () => {
+    respondWith({ kind: "file", grantId: "dgrant_x" });
+    await walk(config(), "fr");
+
+    expect((await screen.findByTestId("flow-deliverable-action")).getAttribute("href")).toBe(
+      "/fr/reports/q3?g=dgrant_x",
+    );
+  });
+
+  it("a redirect ending never navigates away from the deliverable", async () => {
+    respondWith({ kind: "file", grantId: "dgrant_x" });
+    await walk(config({ ending: { default: { kind: "redirect", href: "/pricing" } } }));
+
+    expect(await screen.findByTestId("flow-deliverable-action")).toBeTruthy();
+    expect(mockPush).not.toHaveBeenCalled();
+  });
+
+  it("a screen ending renders first, then the action", async () => {
+    respondWith({ kind: "file", grantId: "dgrant_x" });
+    await walk(config({ ending: { default: { kind: "screen", headline: en("Done") } } }));
+
+    const ending = await screen.findByTestId("flow-ending");
+    const action = screen.getByTestId("flow-deliverable-action");
+    expect(ending.compareDocumentPosition(action) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it("a file walk with no deliverable in the response shows the by-email line and no link", async () => {
+    respondWith();
+    await walk(config());
+
+    expect(await screen.findByText("reports.fileByEmail")).toBeTruthy();
+    expect(screen.queryByTestId("flow-deliverable-action")).toBeNull();
+  });
+
+  it("a video response embeds the player", async () => {
+    respondWith({ kind: "video", src: "https://cdn.example/v.mp4" });
+    await walk(config({ deliverable: { kind: "video", gated: true, title: en("Talk") }, deliverables: undefined }));
+
+    const box = await screen.findByTestId("flow-deliverable-video");
+    await userEvent.setup().click(screen.getByTestId("video-embed-play-button"));
+    expect(box.querySelector("video source")?.getAttribute("src")).toBe("https://cdn.example/v.mp4");
+  });
+
+  it("a page response links the site page", async () => {
+    respondWith({ kind: "page", href: "/calc" });
+    await walk(config({ deliverable: { kind: "page", gated: true, title: en("Calc") }, deliverables: undefined }));
+
+    expect((await screen.findByTestId("flow-deliverable-action")).getAttribute("href")).toBe("/calc");
+  });
+
+  it.each([
+    { kind: "page", href: "//evil.example" },
+    { kind: "external", href: "javascript:alert(1)" },
+    { kind: "video", src: "http://cdn.example/v.mp4" },
+  ])("renders no link and no video for an unsafe target: %j", async (deliverable) => {
+    respondWith(deliverable);
+    await walk(
+      config({
+        deliverable: { kind: deliverable.kind, gated: true, title: en("X") },
+        deliverables: undefined,
+      }),
+    );
+
+    await screen.findByTestId("mock-card");
+    expect(screen.queryByTestId("flow-deliverable-action")).toBeNull();
+    expect(screen.queryByTestId("flow-deliverable-video")).toBeNull();
+    expect(document.querySelector("video")).toBeNull();
+  });
+
+  it("a config with no deliverable and no response key renders today's card", async () => {
+    respondWith();
+    await walk(config({ deliverable: undefined, deliverables: undefined }));
+
+    await screen.findByTestId("mock-card");
+    expect(screen.queryByTestId("flow-deliverable-action")).toBeNull();
+    expect(screen.queryByText("reports.fileByEmail")).toBeNull();
+  });
+});