@startsimpli/billing 0.4.23 → 0.4.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/CurrentPlanCard.tsx

@@ -16,6 +16,7 @@
 
 import React from "react";
 import type { OfferFeature, SubscriptionInfo, UsageMap } from "../types";
+import { formatFeatureLabel, formatPrice } from "../utils/format";
 
 export interface CurrentPlanCardProps {
   subscription: SubscriptionInfo;
@@ -32,8 +33,7 @@ export interface CurrentPlanCardProps {
 
 function priceLabel(offer: SubscriptionInfo["offer"]): string {
   if (offer.isFree) return "Free";
-  const n = Math.floor(parseFloat(offer.unitPrice) || 0);
-  return `$${n}`;
+  return formatPrice(offer.unitPrice, offer.currency);
 }
 
 function isProgressBarFeature(f: OfferFeature): boolean {
@@ -42,13 +42,7 @@ function isProgressBarFeature(f: OfferFeature): boolean {
 
 function featureLabel(f: OfferFeature): string | null {
   if (f.value === false) return null;
-  if (typeof f.value === "number" || typeof f.limit === "number") {
-    const limit = typeof f.limit === "number" ? f.limit
-                : typeof f.value === "number" ? (f.value as number) : null;
-    if (limit === -1) return `Unlimited ${f.name.toLowerCase()}`;
-    if (limit !== null && limit > 0) return `Up to ${limit} ${f.name.toLowerCase()}`;
-  }
-  return f.name;
+  return formatFeatureLabel(f);
 }
 
 function StatusBadge({ status, trialEnd }: { status: string; trialEnd: string | null }) {
@@ -277,7 +271,8 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
         ) : (
           <span aria-label={`${priceLabel(offer)} ${offer.intervalDisplay}`}>
             <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">{priceLabel(offer)}</span>
-            <span aria-hidden="true" className="text-base text-gray-500 ml-1">{offer.intervalDisplay}</span>
+            {" "}
+            <span aria-hidden="true" className="text-base text-gray-500">{offer.intervalDisplay}</span>
           </span>
         )}
       </div>

package/src/components/IntervalToggle.tsx

@@ -0,0 +1,113 @@
+/**
+ * Monthly / Annual switch for plan pickers (crochet_patterns-34n7).
+ *
+ * Every plan list pairs each tier's monthly and annual offers and shows one
+ * card per tier for the chosen interval. Monthly by default — unless the
+ * viewer's current plan is an annual offer, so their card reads "Current
+ * plan" without a click. Nothing is remembered.
+ */
+import React, { useMemo, useState } from "react";
+import type { ProductOffer } from "../types";
+import {
+  annualSavings,
+  groupOffersByTier,
+  tierOffer,
+  type BillingInterval,
+  type OfferTier,
+} from "../utils/tiers";
+import { formatPrice } from "../utils/format";
+
+export interface IntervalEntry {
+  tier: OfferTier;
+  offer: ProductOffer;
+}
+
+export function useIntervalOffers(offers: ProductOffer[], currentOfferId: string | null = null) {
+  // Null until the viewer picks one, so the default can follow a plan that
+  // loads after the first render.
+  const [chosen, setInterval] = useState<BillingInterval | null>(null);
+  const currentIsAnnual = offers.some((o) => o.id === currentOfferId && o.intervalUnit === "year");
+  const interval: BillingInterval = chosen ?? (currentIsAnnual ? "annual" : "monthly");
+  const tiers = useMemo(() => groupOffersByTier(offers), [offers]);
+  const hasChoice = tiers.some((t) => t.monthly !== null && t.annual !== null);
+  const entries: IntervalEntry[] = tiers.map((tier) => ({ tier, offer: tierOffer(tier, interval) }));
+  return { interval, setInterval, hasChoice, tiers, entries };
+}
+
+export function IntervalToggle({
+  interval,
+  onChange,
+}: {
+  interval: BillingInterval;
+  onChange: (interval: BillingInterval) => void;
+}) {
+  const option = (value: BillingInterval, label: string) => {
+    const selected = interval === value;
+    return (
+      <button
+        type="button"
+        role="radio"
+        aria-checked={selected}
+        onClick={() => onChange(value)}
+        className={`px-4 py-1.5 text-sm font-semibold rounded-full transition-colors cursor-pointer ${
+          selected ? "bg-white text-gray-900 shadow-sm" : "text-gray-500 hover:text-gray-800"
+        }`}
+      >
+        {label}
+      </button>
+    );
+  };
+  return (
+    <div className="flex justify-center">
+      <div
+        role="radiogroup"
+        aria-label="Billing interval"
+        data-testid="interval-toggle"
+        className="inline-flex items-center gap-1 rounded-full bg-gray-100 p-1"
+      >
+        {option("monthly", "Monthly")}
+        {option("annual", "Annual")}
+      </div>
+    </div>
+  );
+}
+
+/** "$2.42/month billed yearly · Save 19%" under an annual price. */
+export function AnnualNote({ entry, className = "" }: { entry: IntervalEntry; className?: string }) {
+  if (entry.offer !== entry.tier.annual) return null;
+  const savings = annualSavings(entry.tier);
+  if (!savings) return null;
+  return (
+    <p data-testid="annual-note" className={`text-xs text-gray-500 ${className}`}>
+      {formatPrice(savings.perMonth, entry.offer.currency)}/month billed yearly
+      {savings.percent > 0 && <span className="font-semibold text-green-700"> · Save {savings.percent}%</span>}
+    </p>
+  );
+}
+
+/** The price line every card shares: "$2.99 per month", or "Free". */
+export function OfferPrice({
+  offer,
+  amountClassName,
+  intervalClassName = "text-gray-500",
+}: {
+  offer: ProductOffer;
+  amountClassName: string;
+  intervalClassName?: string;
+}) {
+  if (offer.isFree) {
+    return (
+      <span aria-label="Free">
+        <span aria-hidden="true" className={amountClassName}>Free</span>
+      </span>
+    );
+  }
+  const price = formatPrice(offer.unitPrice, offer.currency);
+  return (
+    <span aria-label={`${price} ${offer.intervalDisplay}`}>
+      <span aria-hidden="true" className={amountClassName}>{price}</span>
+      {" "}
+      <span aria-hidden="true" className={intervalClassName}>{offer.intervalDisplay}</span>
+    </span>
+  );
+}

package/src/components/PlanChange.crochet.test.tsx

@@ -0,0 +1,274 @@
+/**
+ * Choosing a plan when you already have one (crochets.site design review,
+ * 2026-10-18):
+ * - crochet_patterns-anw61 / -ep670: a paying Lite user was offered "Start
+ *   Free Trial" under a "7-day free trial" pill. The backend switches Lite to
+ *   Pro in place and charges the prorated difference at once: no trial.
+ * - crochet_patterns-kigcj / -lr7mj: "Get Started" / "Downgrade to Free"
+ *   ended a paid plan (at period end) or a complimentary one (now) on one
+ *   click, with no confirmation.
+ * - crochet_patterns-aijez: a complimentary Pro viewer saw no plan of theirs
+ *   on /pricing.
+ * - crochet_patterns-nag60: "Subscription activated successfully!" beside
+ *   "You're on the Free plan" after paying.
+ * - crochet_patterns-9e9o: a second click started a second checkout.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { SubscriptionManager } from "./SubscriptionManager";
+import { PricingDetailPage } from "./PricingDetailPage";
+import { UpgradeModal } from "./UpgradeModal";
+import type { ProductOffer, SubscriptionInfo } from "../types";
+import { crochetProduct, crochetLite, crochetFree, subscriptionTo } from "./__fixtures__/crochetProduct";
+
+const text = (el: Element) => (el.textContent ?? "").replace(/\s+/g, " ");
+
+const comp: ProductOffer = {
+  ...crochetFree,
+  id: "comp-id",
+  name: "Pro (complimentary)",
+  slug: "crochet-comp",
+  isActive: false,
+  sortOrder: 99,
+  features: [{ key: "pro_designs", name: "Pro designs", value: true }],
+};
+
+type Preview = Record<string, unknown>;
+
+/** Serves product + subscription, and the plan-change preview per offer id
+ * (snake_case, as Django sends it). Records every request. */
+function fetcherFor(subscription: SubscriptionInfo | null, previews: Record<string, Preview> = {}) {
+  const fn = vi.fn((url: string, init?: RequestInit) => {
+    const ok = (body: unknown, status = 200) =>
+      Promise.resolve({ ok: true, status, json: () => Promise.resolve(body) });
+    if (url.includes("/billing/subscription/current/")) {
+      return subscription === null
+        ? Promise.resolve({ ok: false, status: 404, json: () => Promise.resolve({}) })
+        : ok(subscription);
+    }
+    if (url.includes("/billing/products/")) return ok(crochetProduct);
+    if (url.includes("/billing/usage/")) return ok({});
+    if (url.includes("/billing/plan-change-preview/")) {
+      const { offer_id } = JSON.parse(String(init?.body ?? "{}"));
+      return previews[offer_id] ? ok(previews[offer_id]) : Promise.resolve({ ok: false, status: 404, json: () => Promise.resolve({}) });
+    }
+    if (url.includes("/billing/subscribe-free/")) return ok({ subscription_id: "s", status: "active", scheduled_downgrade: true, effective_at: "2026-11-17T20:23:09Z" });
+    if (url.includes("/billing/success-sync/")) return ok({ status: "active" });
+    return Promise.resolve({ ok: false, status: 404, json: () => Promise.resolve({}) });
+  });
+  return fn;
+}
+
+function renderWith(ui: React.ReactElement, fetcher: ReturnType<typeof fetcherFor>) {
+  return render(
+    <BillingProvider apiBaseUrl="https://api.test/api/v1" fetcher={fetcher as unknown as typeof fetch}>
+      {ui}
+    </BillingProvider>,
+  );
+}
+
+const calls = (f: ReturnType<typeof fetcherFor>, path: string) =>
+  f.mock.calls.filter((c) => String(c[0]).includes(path));
+
+const LITE_TO_PRO: Preview = {
+  mode: "immediate", offer_id: "pro-id", amount_due: "5.80", currency: "usd",
+  effective_at: "2026-10-18T22:00:00Z", trial_days: 0,
+  current_offer: { slug: "crochet-lite", name: "Lite", is_listed: true },
+};
+const LITE_TO_FREE: Preview = {
+  mode: "at_period_end", offer_id: "free-id", amount_due: "0.00", currency: "usd",
+  effective_at: "2026-11-17T20:23:09Z", trial_days: 0,
+  current_offer: { slug: "crochet-lite", name: "Lite", is_listed: true },
+};
+const COMP_TO_FREE: Preview = {
+  mode: "immediate", offer_id: "free-id", amount_due: "0.00", currency: "usd",
+  effective_at: "2026-10-18T22:00:00Z", trial_days: 0,
+  current_offer: { slug: "crochet-comp", name: "Pro (complimentary)", is_listed: false },
+};
+
+const signedIn = (subscription: SubscriptionInfo | null) => ({ signedIn: true, subscription });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// /pricing
+// ─────────────────────────────────────────────────────────────────────────────
+describe("/pricing for a paying Lite subscriber", () => {
+  const lite = subscriptionTo(crochetLite);
+
+  it("offers Pro as an upgrade, with no trial pill or trial line, and Free as a downgrade", async () => {
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(lite)} />, fetcherFor(lite));
+    const pro = await screen.findByTestId("detail-card-crochet-pro");
+    expect(within(pro).getByRole("button").textContent).toBe("Upgrade to Pro");
+    expect(text(pro)).not.toMatch(/free trial/i);
+    expect(screen.queryByTestId("trial-pill-crochet-pro")).toBeNull();
+    expect(screen.getByTestId("detail-cta-crochet-free").textContent).toBe("Downgrade to Free");
+    expect(screen.getByTestId("detail-cta-crochet-lite").textContent).toBe("Current plan");
+  });
+
+  it("upgrading asks first, showing what is charged today, then proceeds with the preview", async () => {
+    const onSelectOffer = vi.fn();
+    const f = fetcherFor(lite, { "pro-id": LITE_TO_PRO });
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(lite)} onSelectOffer={onSelectOffer} />, f);
+    await userEvent.click(await screen.findByTestId("detail-cta-crochet-pro"));
+
+    const dialog = await screen.findByTestId("plan-change-confirm");
+    expect(text(dialog)).toContain("$5.80 today");
+    expect(text(dialog)).toContain("then $9 per month");
+    expect(text(dialog)).toMatch(/no free trial/i);
+    expect(onSelectOffer).not.toHaveBeenCalled();
+
+    await userEvent.click(within(dialog).getByTestId("plan-change-confirm-button"));
+    expect(onSelectOffer).toHaveBeenCalledTimes(1);
+    expect(onSelectOffer.mock.calls[0][0].slug).toBe("crochet-pro");
+    expect(onSelectOffer.mock.calls[0][1]).toMatchObject({ mode: "immediate", amountDue: "5.80" });
+  });
+
+  it("Downgrade to Free says the date Lite ends, and Keep my plan changes nothing", async () => {
+    const onSelectOffer = vi.fn();
+    const f = fetcherFor(lite, { "free-id": LITE_TO_FREE });
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(lite)} onSelectOffer={onSelectOffer} />, f);
+    await userEvent.click(await screen.findByTestId("detail-cta-crochet-free"));
+
+    const dialog = await screen.findByTestId("plan-change-confirm");
+    expect(text(dialog)).toContain("Your Lite plan ends on November 17, 2026");
+    await userEvent.click(within(dialog).getByTestId("plan-change-cancel"));
+    expect(screen.queryByTestId("plan-change-confirm")).toBeNull();
+    expect(onSelectOffer).not.toHaveBeenCalled();
+  });
+});
+
+describe("/pricing for a complimentary Pro account", () => {
+  const sub = subscriptionTo(comp);
+
+  it("says which plan they are on, and Free is a downgrade that warns it can't be had back", async () => {
+    const onSelectOffer = vi.fn();
+    const f = fetcherFor(sub, { "free-id": COMP_TO_FREE });
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(sub)} onSelectOffer={onSelectOffer} />, f);
+
+    const banner = await screen.findByTestId("current-plan-unlisted");
+    expect(text(banner)).toContain("You're on Pro (complimentary)");
+    const free = screen.getByTestId("detail-cta-crochet-free");
+    expect(free.textContent).toBe("Downgrade to Free");
+
+    await userEvent.click(free);
+    const dialog = await screen.findByTestId("plan-change-confirm");
+    expect(text(dialog)).toContain("ends now");
+    expect(text(dialog)).toMatch(/can't get it back/);
+    expect(onSelectOffer).not.toHaveBeenCalled();
+  });
+});
+
+describe("/pricing for a new buyer", () => {
+  it("Free user: Pro still sells its trial, and goes straight to checkout without a preview", async () => {
+    const onSelectOffer = vi.fn();
+    const f = fetcherFor(null);
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(null)} onSelectOffer={onSelectOffer} />, f);
+    const cta = await screen.findByTestId("detail-cta-crochet-pro");
+    expect(cta.textContent).toBe("Start Free Trial");
+    expect(screen.getByTestId("trial-pill-crochet-pro")).toBeDefined();
+
+    await userEvent.click(cta);
+    expect(onSelectOffer).toHaveBeenCalledTimes(1);
+    expect(calls(f, "/billing/plan-change-preview/")).toHaveLength(0);
+  });
+
+  it("a second click while the first is in flight does nothing", async () => {
+    const onSelectOffer = vi.fn(() => "navigating");
+    renderWith(<PricingDetailPage productId="crochet-patterns" currentPlan={signedIn(null)} onSelectOffer={onSelectOffer} />, fetcherFor(null));
+    const cta = await screen.findByTestId("detail-cta-crochet-pro");
+    await userEvent.click(cta);
+    await userEvent.click(cta);
+    await userEvent.click(screen.getByTestId("detail-cta-crochet-lite"));
+    expect(onSelectOffer).toHaveBeenCalledTimes(1);
+    expect((cta as HTMLButtonElement).disabled).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// /settings/billing
+// ─────────────────────────────────────────────────────────────────────────────
+describe("/settings/billing for a paying Lite subscriber", () => {
+  const lite = subscriptionTo(crochetLite);
+  const manager = (props: Partial<React.ComponentProps<typeof SubscriptionManager>> = {}) => (
+    <SubscriptionManager productId="crochet-patterns" returnUrl="https://t/s" {...props} />
+  );
+
+  it("Pro reads Upgrade to Pro with no trial copy", async () => {
+    renderWith(manager(), fetcherFor(lite));
+    const card = await screen.findByTestId("plan-card-crochet-pro");
+    expect(within(card).getByRole("button").textContent).toBe("Upgrade to Pro");
+    expect(within(card).queryByTestId("trial-copy")).toBeNull();
+    expect(text(card)).not.toMatch(/free trial/i);
+  });
+
+  it("Downgrade to Free calls subscribe-free only after the viewer confirms", async () => {
+    const f = fetcherFor(lite, { "free-id": LITE_TO_FREE });
+    renderWith(manager(), f);
+    await userEvent.click(await screen.findByTestId("upgrade-cta-crochet-free"));
+    const dialog = await screen.findByTestId("plan-change-confirm");
+    expect(text(dialog)).toContain("November 17, 2026");
+    expect(calls(f, "/billing/subscribe-free/")).toHaveLength(0);
+
+    await userEvent.click(within(dialog).getByTestId("plan-change-confirm-button"));
+    await waitFor(() => expect(calls(f, "/billing/subscribe-free/")).toHaveLength(1));
+    await waitFor(() => expect(screen.queryByTestId("plan-change-confirm")).toBeNull());
+  });
+
+  it("a failed downgrade says so in the dialog instead of vanishing", async () => {
+    const f = fetcherFor(lite, { "free-id": LITE_TO_FREE });
+    const base = f.getMockImplementation()!;
+    f.mockImplementation((url: string, init?: RequestInit) =>
+      String(url).includes("/billing/subscribe-free/")
+        ? Promise.resolve({ ok: false, status: 502, json: () => Promise.resolve({ detail: "We couldn't change your plan just now." }) })
+        : base(url, init));
+    renderWith(manager(), f);
+    await userEvent.click(await screen.findByTestId("upgrade-cta-crochet-free"));
+    await userEvent.click(await screen.findByTestId("plan-change-confirm-button"));
+    expect((await screen.findByTestId("plan-change-confirm-error")).textContent).toContain("couldn't change your plan");
+  });
+});
+
+describe("/settings/billing back from checkout", () => {
+  it("shows Activating, not activated beside Free, while the paid plan is not found", async () => {
+    const f = fetcherFor(null);
+    renderWith(<SubscriptionManager productId="crochet-patterns" returnUrl="https://t/s" statusMessage="success" checkoutSessionId="cs_test_1" />, f);
+    await screen.findByTestId("status-banner-activating");
+    expect(screen.queryByTestId("status-banner-success")).toBeNull();
+    expect(screen.queryByTestId("free-by-default")).toBeNull();
+    // The sync is told which checkout was paid.
+    await waitFor(() => expect(calls(f, "/billing/success-sync/")).toHaveLength(1));
+    expect(JSON.parse(String(calls(f, "/billing/success-sync/")[0][1]?.body))).toEqual({
+      session_id: "cs_test_1", product_slug: "crochet-patterns",
+    });
+  });
+
+  it("shows activated once the paid plan is there", async () => {
+    renderWith(<SubscriptionManager productId="crochet-patterns" returnUrl="https://t/s" statusMessage="success" checkoutSessionId="cs_test_1" />,
+      fetcherFor(subscriptionTo(crochetLite)));
+    await screen.findByTestId("status-banner-success");
+    expect(screen.queryByTestId("status-banner-activating")).toBeNull();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Upgrade modal (pattern pages)
+// ─────────────────────────────────────────────────────────────────────────────
+describe("UpgradeModal for a paying Lite subscriber", () => {
+  it("Upgrade to Pro, no trial pill, confirm before charging", async () => {
+    const lite = subscriptionTo(crochetLite);
+    const onSelectOffer = vi.fn();
+    renderWith(
+      <UpgradeModal productId="crochet-patterns" open onClose={() => {}} onSelectOffer={onSelectOffer} currentPlan={signedIn(lite)} />,
+      fetcherFor(lite, { "pro-id": LITE_TO_PRO }),
+    );
+    const cta = await screen.findByTestId("upgrade-cta-crochet-pro");
+    expect(cta.textContent).toBe("Upgrade to Pro");
+    expect(screen.queryByTestId("trial-pill-crochet-pro")).toBeNull();
+    await userEvent.click(cta);
+    expect(text(await screen.findByTestId("plan-change-confirm"))).toContain("$5.80 today");
+    expect(onSelectOffer).not.toHaveBeenCalled();
+  });
+});
+

package/src/components/PlanChangeConfirm.tsx

@@ -0,0 +1,193 @@
+/**
+ * PlanChangeConfirm — the step between a plan button and a plan change that
+ * charges now, ends a plan, or changes one at period end
+ * (crochet_patterns-anw61, -kigcj, -lr7mj). It says what happens, from the
+ * backend's preview: the amount charged today, or the date the change takes
+ * effect, or that a plan which is not for sale cannot be had back.
+ */
+
+import React, { useEffect, useRef } from "react";
+import type { ProductOffer } from "../types";
+import type { PlanChangeConfirmState } from "../hooks/usePlanChange";
+import { formatPrice } from "../utils/format";
+
+export interface PlanChangeConfirmProps {
+  state: PlanChangeConfirmState | null;
+  confirming: boolean;
+  error: string | null;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+function formatDay(iso: string | null | undefined): string | null {
+  if (!iso) return null;
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric", timeZone: "UTC" });
+}
+
+function recurring(offer: ProductOffer): string {
+  const price = formatPrice(offer.unitPrice, offer.currency);
+  return offer.intervalDisplay ? `${price} ${offer.intervalDisplay}` : price;
+}
+
+interface Copy {
+  title: string;
+  body: string[];
+  action: string;
+}
+
+/** The dialog's words. Exported for tests. */
+export function planChangeCopy(state: PlanChangeConfirmState): Copy {
+  const { offer, preview, currentName, leavingUnlisted } = state;
+  const current = currentName ?? "your current plan";
+  const date = formatDay(preview?.effectiveAt);
+  const mode = preview?.mode ?? null;
+
+  if (offer.isFree) {
+    const title = `Downgrade to ${offer.name}?`;
+    if (mode === "at_period_end") {
+      return {
+        title,
+        body: [
+          date
+            ? `Your ${current} plan ends on ${date}. You keep everything in it until then, and you won't be charged again.`
+            : `Your ${current} plan ends at the end of this billing period. You keep everything in it until then, and you won't be charged again.`,
+          `After that you're on ${offer.name}, and lose what ${current} includes.`,
+        ],
+        action: `Downgrade to ${offer.name}`,
+      };
+    }
+    if (leavingUnlisted) {
+      return {
+        title,
+        body: [
+          `Your ${current} plan ends now, and you lose what it includes.`,
+          `${current} isn't a plan you can buy, so once it ends you can't get it back.`,
+        ],
+        action: `End ${current}`,
+      };
+    }
+    if (mode === "immediate") {
+      return {
+        title,
+        body: [`Your ${current} plan ends now, and you lose what it includes.`],
+        action: `Downgrade to ${offer.name}`,
+      };
+    }
+    return {
+      title,
+      body: [
+        `Your ${current} plan will end. If it is a paid plan you keep it until the end of the period you've paid for.`,
+      ],
+      action: `Downgrade to ${offer.name}`,
+    };
+  }
+
+  if (mode === "at_period_end") {
+    return {
+      title: `Switch to ${offer.name}?`,
+      body: [
+        date
+          ? `You keep ${current} until ${date}. Then your plan changes to ${offer.name} at ${recurring(offer)}.`
+          : `You keep ${current} until the end of this billing period. Then your plan changes to ${offer.name} at ${recurring(offer)}.`,
+        "Nothing is charged today.",
+      ],
+      action: `Switch to ${offer.name}`,
+    };
+  }
+
+  if (!preview) {
+    // The preview could not be had: say only what the rules guarantee.
+    return {
+      title: `Change to ${offer.name}?`,
+      body: [
+        `${offer.name} is ${recurring(offer)}. Moving to a more expensive plan is charged today for the rest of this billing period (prorated); moving to a cheaper one takes effect when this period ends.`,
+        "There's no free trial when you're already on a paid plan.",
+      ],
+      action: `Change to ${offer.name}`,
+    };
+  }
+
+  const amount = preview?.amountDue != null ? formatPrice(preview.amountDue, preview.currency.toUpperCase()) : null;
+  return {
+    title: `Upgrade to ${offer.name}?`,
+    body: [
+      amount
+        ? `You'll be charged ${amount} today for the rest of this billing period, then ${recurring(offer)}.`
+        : `You'll be charged today for the rest of this billing period (prorated), then ${recurring(offer)}.`,
+      `Your plan changes from ${current} to ${offer.name} now. There's no free trial when you're already on a paid plan.`,
+    ],
+    action: amount ? `Upgrade and pay ${amount}` : `Upgrade to ${offer.name}`,
+  };
+}
+
+export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCancel }: PlanChangeConfirmProps) {
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (state) cancelRef.current?.focus();
+  }, [state]);
+  useEffect(() => {
+    if (!state) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onCancel();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [state, onCancel]);
+
+  if (!state) return null;
+  const copy = planChangeCopy(state);
+  const destructive = state.offer.isFree;
+
+  return (
+    <div className="fixed inset-0 z-[60] flex items-center justify-center p-4">
+      <div className="absolute inset-0 bg-black/40" aria-hidden="true" onClick={confirming ? undefined : onCancel} />
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="plan-change-confirm-title"
+        data-testid="plan-change-confirm"
+        className="relative w-full max-w-md rounded-2xl bg-white p-6 shadow-xl"
+      >
+        <h2 id="plan-change-confirm-title" className="text-lg font-bold text-gray-900 mb-3">
+          {copy.title}
+        </h2>
+        <div className="space-y-2 mb-5">
+          {copy.body.map((line) => (
+            <p key={line} className="text-sm text-gray-700">{line}</p>
+          ))}
+        </div>
+        {error && (
+          <p data-testid="plan-change-confirm-error" role="alert" className="mb-4 rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-700">
+            {error}
+          </p>
+        )}
+        <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+          <button
+            ref={cancelRef}
+            type="button"
+            data-testid="plan-change-cancel"
+            onClick={onCancel}
+            disabled={confirming}
+            className="px-4 py-2.5 text-sm font-semibold rounded-xl border border-gray-300 bg-white text-gray-700 hover:bg-gray-50 cursor-pointer disabled:cursor-not-allowed disabled:opacity-60"
+          >
+            {destructive ? "Keep my plan" : "Cancel"}
+          </button>
+          <button
+            type="button"
+            data-testid="plan-change-confirm-button"
+            onClick={onConfirm}
+            disabled={confirming}
+            aria-busy={confirming || undefined}
+            className={`px-4 py-2.5 text-sm font-bold rounded-xl text-white cursor-pointer disabled:cursor-not-allowed disabled:opacity-60 ${
+              destructive ? "bg-red-600 hover:bg-red-700" : "bg-blue-600 hover:bg-blue-700"
+            }`}
+          >
+            {confirming ? "Working…" : copy.action}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}