create-ailk 0.1.0 → 0.2.0

package/templates/apps/web/app/[locale]/flows/[slug]/results/[payload]/ResultsClient.tsx

@@ -0,0 +1,532 @@
+"use client";
+
+/**
+ * ResultsClient — the results permalink page's composition + view state
+ * machine (#4842): `results` → `checkout` | `save` → saved.
+ *
+ * Runs the already-shipped pure `recommend()` on the decoded answers and
+ * composes the LOCKED two-region frame (`FlowFrame`, DESIGN §2/§3/§7.2):
+ *
+ *   - **results** — side panel = `FlowSidePanel` `safe-default` (the top fit,
+ *     its shown price when the register can price it, the always-present
+ *     Book-a-Call rail, §7.3); active region = the fits as
+ *     `RecommendationCard` (first fit `emphasis: "recommended"`, each with a
+ *     per-offer terminal — D2) + `PairingCard` when one matched; bar
+ *     `leading` = "Email me this plan" (D5).
+ *   - **checkout** — Get Started performs DESIGN §7.6's panel FLIP: the
+ *     email step takes the frame's first (side) slot — "fields left" — and
+ *     the configurable `CheckoutPriceCard` (#4865, D3) takes the second
+ *     (active) slot — "price card right"; the card is controlled here, so its
+ *     seat / period / credit-stop state is EXACTLY what Pay sends. Below `md`
+ *     the frame stacks its slots in that same order, so the email step is
+ *     first on mobile and the card is the scroll-to. Bar `leading` = Back,
+ *     `trailing` = Pay.
+ *   - **save** — the same email step with the save framing; the side panel
+ *     stays the safe-default card (FR4); success renders the saved state.
+ *
+ * The three frame regions keep their DOM identity across every transition
+ * (#4806 FR7 — the frame is rendered once; only its slots change).
+ *
+ * Before a terminal or the save CTA is selected AND a valid email submitted,
+ * this component makes no request of any kind (FR5 / PRD L108): the only
+ * network call on the page is the server component's `flows.get`.
+ *
+ * `RecommendRegister` (D6, #4770) is a structural `Pick` of the five fields
+ * `recommend()` / `price()` read — `key`, `offers`, `pairings`, `rateTable`,
+ * `scoring` — so a `FlowConfig` needs only a `key` to satisfy it; the
+ * compiled config carries the register's own key on `experiment.key`.
+ */
+import type {
+  CheckoutConfiguration,
+  CheckoutPriceCardConfiguratorLabels,
+  CheckoutPriceCardLabels,
+  FlowSidePanelView,
+  RecommendationCardPrice,
+  RecommendationCardTerminal,
+} from "@working-theory/ui";
+import {
+  Button,
+  CheckoutPriceCard,
+  FlowFrame,
+  FlowSidePanel,
+  Heading,
+  PairingCard,
+  RecommendationCard,
+  Text,
+} from "@working-theory/ui";
+import type {
+  FlowConfig,
+  FlowSaveInput,
+  RecommendRegister,
+  WaitlistBillingPeriod,
+} from "@working-theory/validation";
+import { recommend, resolveLocalizedString } from "@working-theory/validation";
+import { useTranslations } from "next-intl";
+import type { ReactElement, ReactNode } from "react";
+import { useEffect, useMemo, useState } from "react";
+
+import type { StartCheckoutInput } from "../../checkout.actions";
+import {
+  saveRecommendationAction,
+  startCheckoutAction,
+} from "../../checkout.actions";
+
+import { ResultsEmailStep } from "./ResultsEmailStep";
+
+export type ResultsReturnState = "success" | "cancelled";
+
+interface Props {
+  config: FlowConfig;
+  locale: string;
+  answers: Record<string, string | string[]>;
+  slug: string;
+  /** The encoded permalink payload — the return URLs are built from it. */
+  payload: string;
+  /** FR7/D6 — the `?checkout=` return micro-state, validated by the page. */
+  returnState?: ResultsReturnState;
+}
+
+type View = "results" | "checkout" | "save";
+
+const EMAIL_FORM_ID = "flow-results-email";
+
+// Mirrors `FlowStepperClient.tsx` (#4707) — every path this component builds
+// passes its locale through the same build-time-baked allowlist, never the
+// raw route segment.
+const DEFAULT_LOCALE = "en";
+const ENABLED_LOCALES = (
+  process.env.NEXT_PUBLIC_ENABLED_LOCALES ?? DEFAULT_LOCALE
+).split(",");
+
+/** Validate a candidate locale against the configured set; unknown → default. */
+function resolveSafeLocale(candidate: string): string {
+  return ENABLED_LOCALES.includes(candidate) ? candidate : DEFAULT_LOCALE;
+}
+
+/**
+ * Next's redirect control-flow error (`redirect()` inside a Server Action),
+ * recognised by its digest — `NEXT_REDIRECT;<push|replace>;<url>;<status>;`
+ * (`next/dist/client/components/redirect-error.js`). Never a checkout failure.
+ */
+function isNextRedirect(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "digest" in err &&
+    typeof (err as { digest: unknown }).digest === "string" &&
+    (err as { digest: string }).digest.startsWith("NEXT_REDIRECT;")
+  );
+}
+
+/** D4 — the one `sessionStorage` key `FlowStepperClient` writes. */
+function flowSessionStorageKey(slug: string): string {
+  return `ailk:flow-session:${slug}`;
+}
+
+/** D2 — an offer is quotable iff the register names a currency AND a seat rate for it. */
+function firstSeatRatePeriod(
+  register: RecommendRegister,
+  offerKey: string,
+): WaitlistBillingPeriod | undefined {
+  const rateTable = register.rateTable;
+  if (rateTable?.currency === undefined) return undefined;
+  return rateTable.seatRates.find((rate) => rate.offer === offerKey)?.period;
+}
+
+export function ResultsClient({
+  config,
+  locale,
+  answers,
+  slug,
+  payload,
+  returnState,
+}: Props): ReactElement {
+  const t = useTranslations("flow");
+  const { defaultLocale, offers = [], recommendation } = config;
+
+  const register = useMemo<RecommendRegister>(
+    () => ({
+      key: config.experiment?.key ?? config.slug,
+      offers: config.offers,
+      pairings: config.pairings,
+      rateTable: config.rateTable,
+      scoring: config.scoring,
+    }),
+    [config],
+  );
+  const result = useMemo(() => recommend(register, answers), [register, answers]);
+  const currency = config.rateTable?.currency;
+
+  const [view, setView] = useState<View>("results");
+  const [selectedOfferKey, setSelectedOfferKey] = useState<string | undefined>();
+  const [configuration, setConfiguration] = useState<CheckoutConfiguration>({
+    seats: 1,
+    period: "annual",
+    creditStop: { kind: "none" },
+  });
+  const [breakdownOpen, setBreakdownOpen] = useState(false);
+  const [sessionId, setSessionId] = useState<string | undefined>();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+  const [saved, setSaved] = useState(false);
+
+  // D4 — read the walk's own session id; a privacy mode that throws, or no
+  // entry at all, degrades to cold (the key is simply omitted from the body).
+  useEffect(() => {
+    try {
+      const stored = window.sessionStorage.getItem(flowSessionStorageKey(slug));
+      if (stored) setSessionId(stored);
+    } catch {
+      // cold load
+    }
+  }, [slug]);
+
+  const resolve = (value: Parameters<typeof resolveLocalizedString>[0]): string =>
+    resolveLocalizedString(value, locale, defaultLocale);
+
+  const safeLocale = resolveSafeLocale(locale);
+  const bookCallHref = `/${safeLocale}/schedule`;
+
+  const periodLabels: Record<WaitlistBillingPeriod, string> = {
+    monthly: t("priceCard.periodLabels.monthly"),
+    annual: t("priceCard.periodLabels.annual"),
+    "one-time": t("priceCard.periodLabels.one-time"),
+  };
+
+  const priceCardLabels: CheckoutPriceCardLabels = {
+    eyebrow: t("priceCard.eyebrow"),
+    seatRowLabel: t("priceCard.seatRowLabel"),
+    creditRowLabel: t("priceCard.creditRowLabel"),
+    totalLabel: t("priceCard.totalLabel"),
+    dueTodayLabel: t("priceCard.dueTodayLabel"),
+    periodLabels,
+  };
+
+  const configuratorLabels: CheckoutPriceCardConfiguratorLabels = {
+    seatsLabel: t("priceCard.seatsLabel"),
+    decrementLabel: t("priceCard.decrementLabel"),
+    incrementLabel: t("priceCard.incrementLabel"),
+    periodLabel: t("priceCard.periodLabel"),
+    creditsLabel: t("priceCard.creditsLabel"),
+    creditNoneLabel: t("priceCard.creditNoneLabel"),
+    creditTierLabel: (credits) => t("priceCard.creditTierLabel", { credits }),
+    showBreakdownLabel: t("priceCard.showBreakdownLabel"),
+    hideBreakdownLabel: t("priceCard.hideBreakdownLabel"),
+  };
+
+  const topFit = result.fits[0];
+  const topOffer = topFit
+    ? offers.find((offer) => offer.key === topFit.offerKey)
+    : undefined;
+  const selectedOffer = selectedOfferKey
+    ? offers.find((offer) => offer.key === selectedOfferKey)
+    : undefined;
+
+  function startCheckout(offerKey: string): void {
+    const period = firstSeatRatePeriod(register, offerKey);
+    if (period === undefined) return; // D2 — never quotable → never reaches here
+    setSelectedOfferKey(offerKey);
+    setConfiguration({ seats: 1, period, creditStop: { kind: "none" } });
+    setBreakdownOpen(false);
+    setError(undefined);
+    setView("checkout");
+  }
+
+  function openSave(): void {
+    setError(undefined);
+    setSaved(false);
+    setView("save");
+  }
+
+  function back(): void {
+    setError(undefined);
+    setView("results");
+  }
+
+  function failureMessage(
+    kind: string,
+    retryAfterSeconds: number | undefined,
+    fallbackKey: "checkoutError" | "submitError",
+  ): string {
+    if (kind === "rate_limited" && retryAfterSeconds !== undefined) {
+      return t("rateLimited", { seconds: retryAfterSeconds });
+    }
+    return t(fallbackKey);
+  }
+
+  async function handlePay(email: string): Promise<void> {
+    if (selectedOfferKey === undefined) return;
+    setPending(true);
+    setError(undefined);
+    // The Stripe return URLs are built by the action from the app's own
+    // origin + this permalink (security review, #4875) — never sent from here.
+    const body: StartCheckoutInput = {
+      answers,
+      email,
+      locale,
+      offerKey: selectedOfferKey,
+      seats: configuration.seats,
+      period: configuration.period,
+      creditStop: configuration.creditStop,
+      payload,
+      ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+    try {
+      const outcome = await startCheckoutAction(slug, body);
+      // On success the action `redirect()`s — a returned value is always a
+      // failure.
+      if (outcome) {
+        setError(failureMessage(outcome.kind, outcome.retryAfterSeconds, "checkoutError"));
+        setPending(false);
+      }
+    } catch (err) {
+      // A NEXT_REDIRECT is the SUCCESS path — Stripe's hosted page. It is
+      // Next's control-flow error, never a checkout failure: the router is
+      // already navigating (the action response carried the redirect), so it
+      // is left alone — `pending` stays set and no error renders. Rethrowing
+      // from an event handler would reach no framework boundary; it would
+      // only be an unhandled rejection. Only a genuine transport failure
+      // lands in the error micro-state below.
+      if (isNextRedirect(err)) return;
+      setError(t("checkoutError"));
+      setPending(false);
+    }
+  }
+
+  async function handleSave(email: string): Promise<void> {
+    setPending(true);
+    setError(undefined);
+    const body: FlowSaveInput = {
+      answers,
+      email,
+      locale,
+      ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+    try {
+      const outcome = await saveRecommendationAction(slug, body);
+      if (outcome.ok) {
+        setSaved(true);
+      } else {
+        setError(failureMessage(outcome.kind, outcome.retryAfterSeconds, "submitError"));
+      }
+    } catch {
+      setError(t("submitError"));
+    } finally {
+      setPending(false);
+    }
+  }
+
+  // ── Side panel ──────────────────────────────────────────────────────────
+
+  const safeDefaultView: FlowSidePanelView | undefined = topOffer
+    ? {
+        kind: "safe-default",
+        anchorTitle: t("sidePanel.anchorTitle"),
+        offerName: resolve(topOffer.copy.name),
+        ...(currency !== undefined && topOffer.price.kind !== "label"
+          ? {
+              price: {
+                amountMinor: Math.round(topOffer.price.amount * 100),
+                currency,
+                locale,
+              },
+              showPrice: true,
+            }
+          : {}),
+        action: { kind: "link", href: bookCallHref, label: t("bookCall") },
+      }
+    : undefined;
+
+  // The frame's regions carry no inner padding of their own (FlowFrame.tsx
+  // :151/:159) — the consumer pads, exactly as FlowStepper does for its step
+  // body (`mx-auto w-full max-w-container-sm p-card`, FlowStepper.tsx:1280).
+  const REGION_CLASS = "mx-auto w-full max-w-container-sm p-card";
+
+  const safeDefaultPanel: ReactNode = safeDefaultView ? (
+    <div className={REGION_CLASS}>
+      <FlowSidePanel view={safeDefaultView} />
+    </div>
+  ) : undefined;
+
+  // DESIGN §7.6 — the configurable price card, rendered into the frame's
+  // SECOND slot (right at md+) on the checkout view; the email step takes the
+  // first slot. Composed once here, placed below.
+  let priceCard: ReactNode;
+  if (view === "checkout" && selectedOffer && currency !== undefined) {
+    priceCard = (
+      <div className={REGION_CLASS}>
+        <CheckoutPriceCard
+          offer={selectedOffer}
+          currency={currency}
+          locale={locale}
+          {...(defaultLocale !== undefined ? { defaultLocale } : {})}
+          labels={priceCardLabels}
+          configurator={{
+            register,
+            value: configuration,
+            onChange: setConfiguration,
+            breakdownOpen,
+            onBreakdownOpenChange: setBreakdownOpen,
+            labels: configuratorLabels,
+          }}
+          data-testid="checkout-price-card"
+        />
+      </div>
+    );
+  }
+
+  // ── Slots ────────────────────────────────────────────────────────────────
+  //
+  // `sidePanel` is the frame's FIRST slot (left at md+, first in the mobile
+  // stack); `active` is its SECOND. On the results and save views the safe-
+  // default card is first and the recommendation / email step second; on the
+  // checkout view the slots FLIP (DESIGN §7.6 / §2's Checkout row): the email
+  // step is first and the price card second.
+
+  let sidePanel: ReactNode = safeDefaultPanel;
+  let active: ReactNode;
+  let leading: ReactNode;
+  let trailing: ReactNode;
+
+  if (view === "results") {
+    const heading = recommendation ? resolve(recommendation.copy.title) : undefined;
+    const body = recommendation?.copy.body ? resolve(recommendation.copy.body) : undefined;
+
+    active = (
+      <div data-testid="flow-results">
+        {returnState !== undefined ? (
+          <div
+            role="status"
+            data-testid="flow-results-return-state"
+            className="mb-block-loose"
+          >
+            <Text variant="body-sm" tone="muted">
+              {t(returnState === "success" ? "checkoutSuccess" : "checkoutCancelled")}
+            </Text>
+          </div>
+        ) : null}
+        {heading ? <Heading level={1}>{heading}</Heading> : null}
+        {body ? (
+          <Text variant="body" tone="muted" className="mt-block-tight">
+            {body}
+          </Text>
+        ) : null}
+        <div className="mt-block-loose flex flex-col gap-4">
+          {result.fits.map((fit, index) => {
+            const offer = offers.find((o) => o.key === fit.offerKey);
+            if (!offer) return null;
+            const quotable = firstSeatRatePeriod(register, offer.key) !== undefined;
+            const terminal: RecommendationCardTerminal = quotable
+              ? {
+                  kind: "getStarted",
+                  label: t("getStarted"),
+                  onSelect: () => startCheckout(offer.key),
+                }
+              : {
+                  kind: "bookCall",
+                  label: t("bookCall"),
+                  onSelect: () => window.location.assign(bookCallHref),
+                };
+            const price: RecommendationCardPrice | undefined =
+              currency !== undefined
+                ? {
+                    ...offer.price,
+                    currency,
+                    locale,
+                    ...(defaultLocale !== undefined ? { defaultLocale } : {}),
+                    periodLabels,
+                    fromPrefix: t("price.fromPrefix"),
+                  }
+                : undefined;
+            return (
+              <RecommendationCard
+                key={fit.offerKey}
+                data-testid={`recommendation-card-${fit.offerKey}`}
+                title={resolve(offer.copy.name)}
+                {...(offer.copy.description
+                  ? { description: resolve(offer.copy.description) }
+                  : {})}
+                emphasis={index === 0 ? "recommended" : "default"}
+                {...(index === 0 ? { recommendedLabel: t("priceCard.eyebrow") } : {})}
+                {...(price !== undefined ? { price } : {})}
+                terminal={terminal}
+                whyThis={{ label: t("whyThis"), content: resolve(fit.reason) }}
+              />
+            );
+          })}
+          {result.pairing ? (
+            <PairingCard
+              title={t("pairingTitle")}
+              pairing={result.pairing}
+              offers={offers}
+              locale={locale}
+              {...(defaultLocale !== undefined ? { defaultLocale } : {})}
+              data-testid="recommendation-pairing"
+            />
+          ) : null}
+        </div>
+      </div>
+    );
+    leading = (
+      <Button type="button" variant="ghost" size="big" onClick={openSave}>
+        {t("emailMePlan")}
+      </Button>
+    );
+    trailing = undefined;
+  } else {
+    const isCheckout = view === "checkout";
+    const emailStep = (
+      <ResultsEmailStep
+        title={t(isCheckout ? "emailStepTitle" : "emailStepSaveTitle")}
+        formId={EMAIL_FORM_ID}
+        labels={{
+          invalidEmail: t("validationInvalidEmail"),
+          placeholder: t("emailPlaceholder"),
+          savedTitle: t("savedTitle"),
+          savedBody: t("savedBody"),
+        }}
+        onSubmit={isCheckout ? handlePay : handleSave}
+        pending={pending}
+        {...(error !== undefined ? { error } : {})}
+        saved={!isCheckout && saved}
+      />
+    );
+    if (isCheckout) {
+      sidePanel = <div className={REGION_CLASS}>{emailStep}</div>;
+      active = priceCard;
+    } else {
+      active = emailStep;
+    }
+    leading = (
+      <Button type="button" variant="ghost" size="big" onClick={back} disabled={pending}>
+        {t("back")}
+      </Button>
+    );
+    trailing =
+      !isCheckout && saved ? undefined : (
+        <Button
+          type="submit"
+          form={EMAIL_FORM_ID}
+          size="big"
+          disabled={pending}
+          data-testid={isCheckout ? "flow-results-pay" : "flow-results-save"}
+        >
+          {t(isCheckout ? "pay" : "emailMePlan")}
+        </Button>
+      );
+  }
+
+  return (
+    <FlowFrame
+      barMode="explicit"
+      value={1}
+      max={1}
+      sidePanel={sidePanel}
+      leading={leading}
+      trailing={trailing}
+      data-testid="flow-results-frame"
+    >
+      {view === "checkout" ? active : <div className={REGION_CLASS}>{active}</div>}
+    </FlowFrame>
+  );
+}

package/templates/apps/web/app/[locale]/flows/[slug]/results/[payload]/ResultsEmailStep.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * ResultsEmailStep — the results page's in-place email step (#4842 FR2/FR4),
+ * mirroring the FlowStepper single-field topology (#4806 FR1/FR4, DESIGN
+ * §7.4): the hero question is the visible `<Heading>` AND the field's own
+ * `sr-only` label — one visible question, one answer box, no second small
+ * label. Enter submits (a one-text-field form submits implicitly); the
+ * frame's bar button submits the same form by `form={formId}`.
+ *
+ * Client-side validation is the ONLY thing that happens before the caller's
+ * `onSubmit` fires: an invalid address renders the validation message and
+ * calls nothing (AC-1 — no request leaves on an invalid submit). The
+ * saved micro-state (FR4) renders in place of the field once `saved` is set.
+ *
+ * Every visible string is a prop (FR8 / `customer-facing-i18n`) — no bare
+ * JSX text node lives in this file (§5.2).
+ */
+import { Form, Heading, Input, Label, Text } from "@working-theory/ui";
+import { flowSaveInputSchema } from "@working-theory/validation";
+import type { FormEvent, ReactElement } from "react";
+import { useState } from "react";
+
+export interface ResultsEmailStepLabels {
+  /** The validation message for a malformed address. */
+  invalidEmail: string;
+  placeholder: string;
+  savedTitle: string;
+  savedBody: string;
+}
+
+export interface ResultsEmailStepProps {
+  /** The hero question — visible heading + the field's sr-only label. */
+  title: string;
+  /** The form's id, so a bar button outside it can submit it (`form={id}`). */
+  formId: string;
+  labels: ResultsEmailStepLabels;
+  /** Fires ONLY with a schema-valid email. */
+  onSubmit: (email: string) => void | Promise<void>;
+  pending: boolean;
+  /** A server-side failure message; rendered as an alert under the field. */
+  error?: string;
+  /** FR4 — the saved micro-state replaces the field. */
+  saved?: boolean;
+  "data-testid"?: string;
+}
+
+const emailSchema = flowSaveInputSchema.shape.email;
+
+export function ResultsEmailStep({
+  title,
+  formId,
+  labels,
+  onSubmit,
+  pending,
+  error,
+  saved = false,
+  "data-testid": dataTestId = "results-email-step",
+}: ResultsEmailStepProps): ReactElement {
+  const [email, setEmail] = useState("");
+  const [validationError, setValidationError] = useState<string | undefined>();
+  const inputId = `${formId}-email`;
+  const messageId = `${formId}-message`;
+
+  if (saved) {
+    return (
+      <div data-testid={`${dataTestId}-saved`} role="status">
+        <Heading level={2}>{labels.savedTitle}</Heading>
+        <Text variant="body" tone="muted" className="mt-block-tight">
+          {labels.savedBody}
+        </Text>
+      </div>
+    );
+  }
+
+  function handleSubmit(_event: FormEvent<HTMLFormElement>): void {
+    if (pending) return;
+    const parsed = emailSchema.safeParse(email);
+    if (!parsed.success) {
+      setValidationError(labels.invalidEmail);
+      return;
+    }
+    setValidationError(undefined);
+    void onSubmit(parsed.data);
+  }
+
+  const message = validationError ?? error;
+
+  return (
+    <div data-testid={dataTestId}>
+      <Heading level={2}>{title}</Heading>
+      <Form id={formId} className="mt-block-loose" onSubmit={handleSubmit}>
+        <Label htmlFor={inputId} className="sr-only">
+          {title}
+        </Label>
+        <Input
+          id={inputId}
+          name="email"
+          type="email"
+          size="big"
+          autoComplete="email"
+          inputMode="email"
+          placeholder={labels.placeholder}
+          value={email}
+          onChange={(event) => setEmail(event.target.value)}
+          disabled={pending}
+          aria-invalid={message !== undefined ? true : undefined}
+          aria-describedby={message !== undefined ? messageId : undefined}
+          {...(message !== undefined ? { variant: "error" as const } : {})}
+        />
+        {message !== undefined ? (
+          <div id={messageId} role="alert" className="mt-block-tight">
+            <Text variant="body-sm" className="text-(--color-error-fg)">
+              {message}
+            </Text>
+          </div>
+        ) : null}
+      </Form>
+    </div>
+  );
+}