@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/react/workflows/AffiliatePayoutEditor.tsx

@@ -0,0 +1,201 @@
+"use client";
+import { useId, useMemo, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type AffiliateCommissionTerm = "forever" | "one_time";
+export type AffiliatePayoutUpdate = {
+  affiliateCommissionTerm?: AffiliateCommissionTerm | null;
+  affiliateBasisPoints: number | null;
+  /** Major units of the sale currency, for example 5 means EUR 5 on a EUR sale. */
+  affiliateFixedAmount: number | null;
+  expectedVersion: number;
+};
+export type AffiliatePayoutEditorState = {
+  term: AffiliateCommissionTerm | "inherit";
+  setTerm: (term: AffiliateCommissionTerm | "inherit") => void;
+  value: string;
+  mode: "percentage" | "fixed";
+  currencySymbol: string;
+  setValue: (value: string) => void;
+  setMode: (mode: "percentage" | "fixed") => void;
+  effectiveLabel: string;
+  save: () => Promise<unknown>;
+  clear: () => Promise<unknown>;
+  isPending: boolean;
+  error: string | null;
+  message: string | undefined;
+};
+export type AffiliatePayoutEditorProps = {
+  scopeKey: string;
+  affiliateCommissionTerm?: AffiliateCommissionTerm | null;
+  affiliateBasisPoints: number | null;
+  affiliateFixedAmount?: number | null;
+  effectiveCommissionTerm?: AffiliateCommissionTerm;
+  effectiveBasisPoints: number;
+  effectiveFixedAmount?: number | null;
+  source?: "plan" | "product" | "price" | "store" | "global" | "none";
+  currency?: string;
+  version: number;
+  onSave: (update: AffiliatePayoutUpdate) => Promise<unknown>;
+  children?: (state: AffiliatePayoutEditorState) => ReactNode;
+};
+function initialFields(props: AffiliatePayoutEditorProps) {
+  return {
+    scope: `${props.scopeKey}:${props.version}`,
+    term: props.affiliateCommissionTerm ?? ("inherit" as const),
+    mode:
+      props.affiliateFixedAmount != null
+        ? ("fixed" as const)
+        : ("percentage" as const),
+    value:
+      props.affiliateFixedAmount != null
+        ? String(props.affiliateFixedAmount)
+        : props.affiliateBasisPoints == null
+          ? ""
+          : String(props.affiliateBasisPoints / 100),
+  };
+}
+/** Unstyled inline payout editor. Clear saves inheritance; explicit zero disables payouts. */
+export function AffiliatePayoutEditor(props: AffiliatePayoutEditorProps) {
+  const id = useId();
+  const currency = (props.currency ?? "usd").toUpperCase();
+  const formatter = useMemo(
+    () =>
+      new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency,
+        currencyDisplay: "narrowSymbol",
+      }),
+    [currency],
+  );
+  const currencySymbol =
+    formatter.formatToParts(0).find((part) => part.type === "currency")
+      ?.value ?? currency;
+  const scope = `${props.scopeKey}:${props.version}`;
+  const initial = initialFields(props);
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const action = useWorkflowAction(async (clear = false) => {
+    const value = clear ? "" : fields.value.trim();
+    const amount = value === "" ? null : Number(value);
+    if (
+      amount !== null &&
+      (!/^\d+(\.\d{1,2})?$/.test(value) ||
+        !Number.isSafeInteger(Math.round(amount * 100)) ||
+        amount < 0 ||
+        (fields.mode === "percentage" && amount > 100))
+    )
+      throw new Error(
+        "Enter a non-negative amount with at most two decimals, or a percentage from 0 to 100.",
+      );
+    await props.onSave({
+      affiliateCommissionTerm:
+        clear || fields.term === "inherit" ? null : fields.term,
+      affiliateBasisPoints:
+        fields.mode === "percentage" && amount !== null
+          ? Math.round(amount * 100)
+          : null,
+      affiliateFixedAmount: fields.mode === "fixed" ? amount : null,
+      expectedVersion: props.version,
+    });
+    if (clear)
+      setFields((previous) =>
+        previous.scope === scope
+          ? { ...previous, value: "", term: "inherit" }
+          : previous,
+      );
+    return clear
+      ? "Affiliate payout cleared. Using the inherited default."
+      : "Affiliate payout saved.";
+  }, props.scopeKey);
+  const state: AffiliatePayoutEditorState = {
+    ...fields,
+    currencySymbol,
+    setTerm: (term) => setFields((previous) => ({ ...previous, term })),
+    setValue: (value) => setFields((previous) => ({ ...previous, value })),
+    setMode: (mode) => setFields((previous) => ({ ...previous, mode })),
+    effectiveLabel: `Commission term: ${(props.effectiveCommissionTerm ?? "forever") === "forever" ? "Forever" : "One-time"}. Effective payout: ${props.effectiveFixedAmount != null ? formatter.format(props.effectiveFixedAmount) : `${props.effectiveBasisPoints / 100}%`}${props.source && props.source !== "none" ? ` from ${props.source === "plan" ? "store plan" : props.source}` : ""}.`,
+    save: () => action.run(false),
+    clear: () => action.run(true),
+    isPending: action.isPending,
+    error: action.error,
+    message: action.result,
+  };
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        void state.save();
+      }}
+    >
+      <label htmlFor={id}>Affiliate payout</label>
+      <input
+        id={id}
+        inputMode="decimal"
+        value={state.value}
+        disabled={state.isPending}
+        onChange={(event) => state.setValue(event.target.value)}
+      />
+      <button
+        type="button"
+        aria-label="Percentage"
+        aria-pressed={state.mode === "percentage"}
+        disabled={state.isPending}
+        onClick={() => state.setMode("percentage")}
+      >
+        %
+      </button>
+      <button
+        type="button"
+        aria-label={`Fixed amount in ${currency}`}
+        aria-pressed={state.mode === "fixed"}
+        disabled={state.isPending}
+        onClick={() => state.setMode("fixed")}
+      >
+        {currencySymbol}
+      </button>
+      <label htmlFor={`${id}-term`}>Commission term</label>
+      <select
+        id={`${id}-term`}
+        value={state.term}
+        disabled={state.isPending}
+        onChange={(event) =>
+          state.setTerm(
+            event.target.value as AffiliateCommissionTerm | "inherit",
+          )
+        }
+      >
+        <option value="inherit">Inherited term</option>
+        <option value="forever">Forever</option>
+        <option value="one_time">One-time</option>
+      </select>
+      <button type="submit" disabled={state.isPending}>
+        Save
+      </button>
+      <button
+        type="button"
+        aria-label="Clear affiliate payout"
+        disabled={state.isPending}
+        onClick={() => void state.clear()}
+      >
+        <svg
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          aria-hidden="true"
+        >
+          <path d="M18 6 6 18M6 6l12 12" />
+        </svg>
+      </button>
+      <p>
+        {state.effectiveLabel} Blank inherits the default. Fixed payouts are
+        capped at proceeds after fees.
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.message && <p role="status">{state.message}</p>}
+    </form>
+  );
+}

package/src/react/workflows/AffiliateRateEditor.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { AffiliateRateEditor } from "./AffiliateRateEditor.js";
+afterEach(cleanup);
+it("saves a percentage, clears to inherit, and rejects invalid decimals", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <AffiliateRateEditor
+      scopeKey="price"
+      affiliateBasisPoints={null}
+      effectiveBasisPoints={2000}
+      source="plan"
+      version={0}
+      onSave={save}
+    />,
+  );
+  const input = screen.getByLabelText("Affiliate payout (%)");
+  await userEvent.type(input, "12.5");
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: 1250,
+    expectedVersion: 0,
+  });
+  await userEvent.clear(input);
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: null,
+    expectedVersion: 0,
+  });
+  await userEvent.type(input, "100.001");
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenCalledTimes(2);
+  expect(screen.getByRole("alert").textContent).toMatch(/percentage/i);
+});

package/src/react/workflows/AffiliateRateEditor.tsx

@@ -0,0 +1,92 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type AffiliateRateUpdate = {
+  affiliateBasisPoints: number | null;
+  expectedVersion: number;
+};
+export type AffiliateRateEditorState = {
+  percentage: string;
+  setPercentage: (value: string) => void;
+  effectiveLabel: string;
+  isPending: boolean;
+  error: string | null;
+  message: string | undefined;
+  save: () => Promise<unknown>;
+};
+export type AffiliateRateEditorProps = {
+  scopeKey: string;
+  affiliateBasisPoints: number | null;
+  effectiveBasisPoints: number;
+  source: "plan" | "product" | "price" | "store" | "global" | "none";
+  version: number;
+  onSave: (update: AffiliateRateUpdate) => Promise<unknown>;
+  children?: (state: AffiliateRateEditorState) => ReactNode;
+};
+/** Unstyled nullable commission editor. Blank inherits the next applicable rate. */
+export function AffiliateRateEditor(props: AffiliateRateEditorProps) {
+  const id = useId();
+  const scope = `${props.scopeKey}:${props.version}`;
+  const initial = {
+    scope,
+    percentage:
+      props.affiliateBasisPoints === null
+        ? ""
+        : String(props.affiliateBasisPoints / 100),
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const action = useWorkflowAction(async () => {
+    const value = fields.percentage.trim();
+    const rate = value === "" ? null : Math.round(Number(value) * 100);
+    if (
+      rate !== null &&
+      (!/^\d+(\.\d{1,2})?$/.test(value) ||
+        !Number.isSafeInteger(rate) ||
+        rate < 0 ||
+        rate > 10000)
+    )
+      throw new Error(
+        "Enter a percentage from 0 to 100 with at most two decimal places, or leave it blank to inherit.",
+      );
+    await props.onSave({
+      affiliateBasisPoints: rate,
+      expectedVersion: props.version,
+    });
+    return "Affiliate payout saved.";
+  }, props.scopeKey);
+  const state: AffiliateRateEditorState = {
+    percentage: fields.percentage,
+    setPercentage: (percentage) =>
+      setFields((previous) => ({ ...previous, percentage })),
+    effectiveLabel: `Effective payout: ${props.effectiveBasisPoints / 100}% from ${props.source === "plan" ? "store plan" : props.source}.`,
+    isPending: action.isPending,
+    error: action.error,
+    message: action.result,
+    save: action.run,
+  };
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        void state.save();
+      }}
+    >
+      <label htmlFor={id}>Affiliate payout (%)</label>
+      <input
+        id={id}
+        inputMode="decimal"
+        value={state.percentage}
+        disabled={state.isPending}
+        onChange={(event) => state.setPercentage(event.target.value)}
+      />
+      <p>{state.effectiveLabel} Leave blank to inherit.</p>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.message && <p role="status">{state.message}</p>}
+      <button type="submit" disabled={state.isPending}>
+        {state.isPending ? "Saving…" : "Save payout"}
+      </button>
+    </form>
+  );
+}

package/src/react/workflows/Checkout.test.tsx

@@ -83,6 +83,9 @@ it("exposes creation errors and retries without losing the selected integration"
   await userEvent.click(screen.getByRole("button", { name: "Retry" }));
   await screen.findByText("Stripe iframe");
   await waitFor(() => expect(createSession).toHaveBeenCalledTimes(2));
+  expect(createSession.mock.calls[1][0].requestId).toBe(
+    createSession.mock.calls[0][0].requestId,
+  );
 });
 it("rejects missing session secrets and initializes Payment Intents through their own callback", async () => {
   const { unmount } = render(
@@ -116,3 +119,30 @@ it("rejects missing session secrets and initializes Payment Intents through thei
     requestId: expect.any(String),
   });
 });
+
+it("keeps an explicit request identity through rerenders and replaces generated identity for a new order", async () => {
+  const createSession = vi
+    .fn()
+    .mockResolvedValue({ stripeSessionId: "cs_test", clientSecret: "secret" });
+  const props = {
+    mode: "embedded" as const,
+    orderKey: "order_one",
+    publishableKey: "pk_test",
+    returnUrl: "https://app.test/receipt",
+    createSession,
+  };
+  const { rerender } = render(
+    <Checkout {...props} requestId="persisted-order" />,
+  );
+  await screen.findByText("Stripe iframe");
+  expect(createSession.mock.calls[0][0].requestId).toBe("persisted-order");
+  rerender(<Checkout {...props} requestId="persisted-order" />);
+  expect(createSession).toHaveBeenCalledTimes(1);
+  rerender(<Checkout {...props} orderKey="order_two" />);
+  await waitFor(() => expect(createSession).toHaveBeenCalledTimes(2));
+  const second = createSession.mock.calls[1][0].requestId;
+  expect(second).not.toBe("persisted-order");
+  rerender(<Checkout {...props} orderKey="order_three" />);
+  await waitFor(() => expect(createSession).toHaveBeenCalledTimes(3));
+  expect(createSession.mock.calls[2][0].requestId).not.toBe(second);
+});

package/src/react/workflows/Checkout.tsx

@@ -1,5 +1,5 @@
 "use client";
-import type { ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { EmbeddedCheckout } from "../components/EmbeddedCheckout.js";
 import { useWorkflowResource } from "./useWorkflowResource.js";
 import {
@@ -36,6 +36,8 @@ type Common = CheckoutFormOptions & {
   publishableKey: string;
   /** Changes when the price, signed-in customer, or referral attribution changes. */
   orderKey: string;
+  /** Optional durable logical-order identity, persisted by the host app. */
+  requestId?: string;
   returnUrl: string;
   onNavigate?: (url: string) => void;
   children?: (state: CheckoutRenderProps) => ReactNode;
@@ -57,11 +59,16 @@ export type CheckoutProps = Common &
   );
 /** All checkout integrations share one unstyled lifecycle. Callbacks must authenticate and validate prices on the server. */
 export function Checkout(props: CheckoutProps) {
-  return <CheckoutBody key={`${props.orderKey}:${props.mode}`} {...props} />;
+  return (
+    <CheckoutBody
+      key={`${props.orderKey}:${props.mode}:${props.requestId ?? ""}`}
+      {...props}
+    />
+  );
 }
 function CheckoutBody(props: CheckoutProps) {
+  const [requestId] = useState(() => props.requestId ?? crypto.randomUUID());
   const state = useWorkflowResource(async () => {
-    const requestId = crypto.randomUUID();
     const result =
       props.mode === "payment-intent"
         ? await props.createPaymentIntent({ requestId })

package/src/react/workflows/CheckoutForms.test.tsx

@@ -4,6 +4,7 @@ import userEvent from "@testing-library/user-event";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import type { ReactNode } from "react";
 const mocks = vi.hoisted(() => ({
+  sessionEmail: null as string | null,
   updateEmail: vi.fn(),
   confirm: vi.fn(),
   submit: vi.fn(),
@@ -21,6 +22,7 @@ vi.mock("@stripe/react-stripe-js/checkout", () => ({
     type: "success",
     checkout: {
       id: "cs_test",
+      email: mocks.sessionEmail,
       canConfirm: false,
       updateEmail: mocks.updateEmail,
       confirm: mocks.confirm,
@@ -36,6 +38,7 @@ import { CheckoutElementsForm, PaymentIntentForm } from "./CheckoutForms.js";
 afterEach(cleanup);
 beforeEach(() => {
   vi.clearAllMocks();
+  mocks.sessionEmail = null;
   mocks.updateEmail.mockResolvedValue({ type: "success" });
   mocks.confirm.mockResolvedValue({
     type: "error",
@@ -53,6 +56,27 @@ const props = {
   email: "buyer@example.com",
   onNavigate: vi.fn(),
 };
+it("confirms a session with a server-set email without attempting to update it", async () => {
+  mocks.sessionEmail = "account@example.com";
+  mocks.updateEmail.mockResolvedValue({
+    type: "error",
+    error: { message: "You cannot update the email" },
+  });
+  mocks.confirm.mockResolvedValue({ type: "success" });
+  const navigate = vi.fn();
+  render(<CheckoutElementsForm {...props} onNavigate={navigate} />);
+  const input = screen.getByRole("textbox", {
+    name: "Email for your receipt",
+  }) as HTMLInputElement;
+  expect(input.value).toBe("account@example.com");
+  expect(input.readOnly).toBe(true);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(mocks.updateEmail).not.toHaveBeenCalled();
+  expect(mocks.confirm).toHaveBeenCalledOnce();
+  expect(navigate).toHaveBeenCalledWith(
+    "https://app.test/receipt?session_id=cs_test",
+  );
+});
 it("sends the email before confirming, including when canConfirm is initially false", async () => {
   render(<CheckoutElementsForm {...props} />);
   await userEvent.click(screen.getByRole("button", { name: "Pay" }));
@@ -70,6 +94,22 @@ it("does not confirm after Stripe rejects the email", async () => {
   expect(screen.getByRole("alert").textContent).toContain("Invalid email");
   expect(mocks.confirm).not.toHaveBeenCalled();
 });
+it("keeps a guest email editable after a declined payment", async () => {
+  mocks.updateEmail.mockImplementation(async (email: string) => {
+    mocks.sessionEmail = email;
+    return { type: "success" };
+  });
+  render(<CheckoutElementsForm {...props} />);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  await screen.findByText("Card declined");
+  const input = screen.getByRole("textbox", { name: "Email for your receipt" });
+  expect((input as HTMLInputElement).readOnly).toBe(false);
+  await userEvent.clear(input);
+  await userEvent.type(input, "other@example.com");
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(mocks.updateEmail).toHaveBeenLastCalledWith("other@example.com");
+  expect(mocks.confirm).toHaveBeenCalledTimes(2);
+});
 it("disables confirmation while Stripe is processing and supports a new attempt after failure", async () => {
   let resolve!: (value: unknown) => void;
   mocks.confirm.mockImplementationOnce(

package/src/react/workflows/CheckoutForms.tsx

@@ -24,6 +24,8 @@ import { StripeProvider } from "../components/StripeProvider.js";
 import { useWorkflowAction } from "./useWorkflowAction.js";
 export type CheckoutFormState = {
   email: string;
+  /** Stripe supplied this email when the session loaded; do not edit it. */
+  emailReadOnly?: boolean;
   setEmail: (email: string) => void;
   emailInputId: string;
   isPending: boolean;
@@ -44,6 +46,7 @@ export type CheckoutFormProps = CheckoutFormOptions & {
 };
 function NativeForm({
   email,
+  emailReadOnly,
   setEmail,
   emailInputId,
   paymentElement,
@@ -65,6 +68,7 @@ function NativeForm({
         required
         autoComplete="email"
         value={email}
+        readOnly={emailReadOnly}
         onChange={(event) => setEmail(event.target.value)}
       />
       {paymentElement}
@@ -86,31 +90,48 @@ export function CheckoutElementsForm(props: CheckoutFormProps) {
     </CheckoutSessionProvider>
   );
 }
-function SessionForm({
+function SessionForm(props: CheckoutFormProps) {
+  const checkout = useCheckout();
+  if (checkout.type === "loading")
+    return <p role="status">Loading checkout…</p>;
+  if (checkout.type === "error")
+    return <p role="alert">{checkout.error.message}</p>;
+  return (
+    <ReadySessionForm
+      key={checkout.checkout.id}
+      {...props}
+      checkout={checkout.checkout}
+    />
+  );
+}
+function ReadySessionForm({
+  checkout,
   email: initialEmail = "",
   returnUrl,
   onNavigate,
   renderForm,
-}: CheckoutFormProps) {
-  const checkout = useCheckout();
-  const [email, setEmail] = useState(initialEmail);
+}: CheckoutFormProps & {
+  checkout: Extract<
+    ReturnType<typeof useCheckout>,
+    { type: "success" }
+  >["checkout"];
+}) {
+  // Snapshot once per session: a guest update must not lock their input on retry.
+  const [sessionEmail] = useState(() => checkout.email);
+  const [email, setEmail] = useState(sessionEmail ?? initialEmail);
   const emailInputId = useId();
   const action = useWorkflowAction(async () => {
-    if (checkout.type !== "success") throw new Error("Checkout is not ready.");
-    const updated = await checkout.checkout.updateEmail(email);
-    if (updated.type === "error") throw new Error(updated.error.message);
-    const confirmed = await checkout.checkout.confirm();
+    if (!sessionEmail) {
+      const updated = await checkout.updateEmail(email);
+      if (updated.type === "error") throw new Error(updated.error.message);
+    }
+    const confirmed = await checkout.confirm();
     if (confirmed.type === "error") throw new Error(confirmed.error.message);
-    onNavigate(
-      returnUrl.replace("{CHECKOUT_SESSION_ID}", checkout.checkout.id),
-    );
+    onNavigate(returnUrl.replace("{CHECKOUT_SESSION_ID}", checkout.id));
   });
-  if (checkout.type === "loading")
-    return <p role="status">Loading checkout…</p>;
-  if (checkout.type === "error")
-    return <p role="alert">{checkout.error.message}</p>;
   const state: CheckoutFormState = {
-    email,
+    email: sessionEmail ?? email,
+    emailReadOnly: !!sessionEmail,
     setEmail,
     emailInputId,
     paymentElement: <PaymentElement />,

package/src/react/workflows/IntegrationSwitch.test.tsx

@@ -34,3 +34,28 @@ it("allows an uncontrolled choice without requiring a router", async () => {
   expect(screen.getByText("Stripe component")).toBeTruthy();
   expect(screen.queryByText("API controls")).toBeNull();
 });
+it("names API, BetterStripe components, and Stripe UI distinctly while preserving mode values", async () => {
+  const changed = vi.fn();
+  render(
+    <IntegrationSwitch
+      views={{
+        headless: <p>API controls</p>,
+        components: <p>Package UI</p>,
+        embedded: <p>Stripe embed</p>,
+        hosted: <p>Stripe portal</p>,
+      }}
+      onValueChange={changed}
+    />,
+  );
+  expect(screen.getByRole("button", { name: "via API" })).toBeTruthy();
+  expect(screen.getByRole("button", { name: "Stripe embedded" })).toBeTruthy();
+  expect(screen.getByRole("button", { name: "Stripe hosted" })).toBeTruthy();
+  await userEvent.click(
+    screen.getByRole("button", { name: "BetterStripe components" }),
+  );
+  expect(changed).toHaveBeenLastCalledWith("components");
+  expect(screen.getByText("Package UI")).toBeTruthy();
+  await userEvent.click(screen.getByRole("button", { name: "via API" }));
+  expect(changed).toHaveBeenLastCalledWith("headless");
+  expect(screen.queryByRole("button", { name: "Headless" })).toBeNull();
+});

package/src/react/workflows/IntegrationSwitch.tsx

@@ -2,8 +2,8 @@
 import { useState, type ReactNode } from "react";
 export type IntegrationMode = "headless" | "components" | "embedded" | "hosted";
 const labels: Record<IntegrationMode, string> = {
-  headless: "Headless",
-  components: "Components",
+  headless: "via API",
+  components: "BetterStripe components",
   embedded: "Stripe embedded",
   hosted: "Stripe hosted",
 };

package/src/react/workflows/Pagination.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it } from "vitest";
+import { Pagination, useCursorPagination } from "./Pagination.js";
+afterEach(cleanup);
+it("navigates cursor history and resets when the account changes", async () => {
+  function View({ account }: { account: string }) {
+    const state = useCursorPagination(account);
+    return (
+      <>
+        <output>{state.cursor ?? "first"}</output>
+        <Pagination
+          page={state.page}
+          canPrevious={state.canPrevious}
+          canNext={state.page < 3}
+          onPrevious={state.previous}
+          onNext={() => state.next(`cursor-${state.page}`)}
+        />
+      </>
+    );
+  }
+  const { rerender } = render(<View account="a" />);
+  expect(
+    screen.getByRole("button", { name: "Previous" }).hasAttribute("disabled"),
+  ).toBe(true);
+  await userEvent.click(screen.getByRole("button", { name: "Next" }));
+  expect(screen.getByText("cursor-1")).toBeTruthy();
+  await userEvent.click(screen.getByRole("button", { name: "Next" }));
+  expect(screen.getByText("Page 3")).toBeTruthy();
+  expect(
+    screen.getByRole("button", { name: "Next" }).hasAttribute("disabled"),
+  ).toBe(true);
+  await userEvent.click(screen.getByRole("button", { name: "Previous" }));
+  expect(screen.getByText("cursor-1")).toBeTruthy();
+  rerender(<View account="b" />);
+  expect(screen.getByText("Page 1")).toBeTruthy();
+  expect(screen.getByText("first")).toBeTruthy();
+});
+it("disables navigation while a page is loading", () => {
+  render(
+    <Pagination
+      page={2}
+      canPrevious
+      canNext
+      isLoading
+      onPrevious={() => {}}
+      onNext={() => {}}
+    />,
+  );
+  for (const button of screen.getAllByRole("button"))
+    expect(button.hasAttribute("disabled")).toBe(true);
+});