@sjolystinnovation/app-kit 0.13.0 → 0.15.0

package/README.md

@@ -28,7 +28,7 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui`, `markdown` and `session/react` are styled with Tailwind CSS.
+The components in `@sjolystinnovation/app-kit/ui`, `markdown`, `branding`, `payments` and `session/react` are styled with Tailwind CSS.
 Import the package's stylesheet after Tailwind:
 
 ```css
@@ -460,6 +460,111 @@ export async function GET(_request: Request, { params }: { params: Promise<{ loc
 It is a route rather than the `opengraph-image` file convention, since a page's own `openGraph`
 block replaces that image.
 
+### `@sjolystinnovation/app-kit/branding`
+
+The logo and favicon an admin uploads, as the API's `/branding` endpoint returns them.
+
+`BrandingProvider` holds them for the components below it. It takes the branding the server
+rendered with, loads it on mount when there is none, and loads it again every five minutes, so an
+open tab picks up a change. A failed load keeps what it has. `useBranding()` gives `branding`,
+`logoUrl` as a `data:` URL or null, and `refresh()`.
+
+```tsx
+"use client";
+import { BrandingProvider, useBranding } from "@sjolystinnovation/app-kit/branding";
+
+<BrandingProvider load={BrandingService.get} initial={initialBranding}>{children}</BrandingProvider>;
+
+const { logoUrl } = useBranding();
+<img src={logoUrl ?? "/logo.png"} alt="" />;
+```
+
+`BrandingManager` is the admin form for uploading or removing them. It needs a `BrandingProvider`
+above it, and refreshes it after a save.
+
+```tsx
+<BrandingManager save={form => BrandingService.update(form)} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `save` | `(form: FormData) => Promise<unknown>` | Sends `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw to show the error's message. |
+| `strings` | `TextOverrides<BrandingManagerStrings>` | The form's text. |
+
+`toDataUrl(data, contentType)` turns base64 bytes into a `data:` URL.
+
+### `@sjolystinnovation/app-kit/branding/server`
+
+`brandingIcon({ load, fallbackPath, fallbackType })` is the response for an `app/icon.ts` route:
+the favicon set in admin settings when it is a PNG, JPEG, WebP, GIF or ICO, or the bundled file
+otherwise, since an SVG or HTML upload could run script on the site's origin. Both carry `nosniff`
+and a sandbox CSP, which a CSP header from the app's `next.config` replaces. When the branding cannot be
+loaded it answers 503 with `no-store`, since a browser would cache the bundled icon in place of the
+one set in settings.
+
+```ts
+// src/app/icon.ts
+import { join } from "node:path";
+import { brandingIcon } from "@sjolystinnovation/app-kit/branding/server";
+
+export const dynamic = "force-dynamic";
+
+export default function Icon() {
+  return brandingIcon({
+    load: () => publicGet<Branding>("/branding", { tags: ["branding"] }),
+    fallbackPath: join(process.cwd(), "public", "icon.png"),
+    fallbackType: "image/png",
+  });
+}
+```
+
+The route needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment. Tag the
+fetch and revalidate the tag after a save, so a new icon shows at once. `iconVersion(data)` is a
+short digest of the icon bytes, for a manifest icon URL such as `/icon?v=<digest>`, since Android
+refreshes a home screen icon only when the manifest changes.
+
+### `@sjolystinnovation/app-kit/payments`
+
+The page a user comes back to from a payment provider, such as after approving a Vipps payment or
+agreement. The .NET side of the Vipps calls is `SjolystInnovation.AppKit.Vipps` on NuGet.
+
+`usePollUntilFinal(fetcher, isFinal, { retries, delayMs })` fetches until the value is final, since
+the provider may confirm a moment after the user is back. It polls every 4 seconds, 8 more times at
+most, and stops on a failed fetch and on unmount. It gives `data`, `loading` and `refresh()`, and
+each fetch uses the latest `fetcher` and `isFinal`.
+
+`PaymentReturn` shows the outcome: confirmed, still pending, or failed. It takes the text and the way
+on for each state, and a refresh button while pending when given `onRefresh`.
+
+```tsx
+"use client";
+import { PaymentReturn, usePollUntilFinal } from "@sjolystinnovation/app-kit/payments";
+
+const { data: order, loading, refresh } = usePollUntilFinal(
+  () => ShopService.getOrder(orderId),
+  o => o != null && o.status !== "Pending",
+);
+if (loading) return <Spinner />;
+
+<PaymentReturn
+  state={order?.status === "Paid" ? "success" : order?.status === "Pending" ? "pending" : "failed"}
+  success={{ title: "Payment received!", body: "Your order is confirmed.", href: "/shop", cta: "Back to shop" }}
+  pending={{ title: "Payment pending", body: "Vipps is confirming it.", note: "We'll email a receipt.", href: "/profile/billing", cta: "View billing" }}
+  failed={{ title: "Payment failed", body: "No charge was made.", href: "/shop", cta: "Try again" }}
+  onRefresh={refresh}
+/>;
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `state` | `"success" \| "pending" \| "failed"` | Which content to show. |
+| `success`, `pending`, `failed` | `{ title, body, href, cta, note?, extra? }` | The text, the button's target and text, a smaller note line and anything more, per state. |
+| `onRefresh` | `() => void` | Shows a refresh button while pending. |
+| `refreshLabel` | `string` | Its text. Defaults to `Check again`. |
+| `className` | `string` | Classes for placing it, on the outer element. |
+
+`formatNok(ore)` formats øre as kroner, such as `NOK 373,75`.
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
@@ -953,6 +1058,10 @@ selector such as `.dark` for a scoped theme:
 | `--color-markdown-link-hover` | gray 600 |
 | `--color-markdown-border` | gray 200, rules, quotes and table lines |
 | `--color-markdown-code-bg`, `-code-text` | gray 100, gray 900 |
+| `--radius-payment-button` | `var(--radius-button)`, the buttons on a `PaymentReturn` |
+| `--color-payment-success`, `-pending`, `-failed` | green 600, amber 500, red 600, the icon on a `PaymentReturn` |
+| `--color-payment-title`, `-text`, `-note` | gray 900, 600, 500 |
+| `--color-payment-secondary-bg`, `-hover-bg`, `-text` | gray 100, 200, 700, its secondary link |
 
 A default that points at another variable is read once for the whole page. The focus ring and the
 primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -29,6 +29,9 @@
     "./markdown": "./src/markdown/index.ts",
     "./seo": "./src/seo/index.ts",
     "./seo/og": "./src/seo/og/index.tsx",
+    "./branding": "./src/branding/index.ts",
+    "./branding/server": "./src/branding/server.ts",
+    "./payments": "./src/payments/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [

package/src/branding/BrandingManager.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { ArrowUpTrayIcon, TrashIcon } from "@heroicons/react/24/outline";
+import { useEffect, useRef, useState } from "react";
+import { toast } from "../toast";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { useBranding } from "./BrandingProvider";
+import { toDataUrl } from "./types";
+
+export interface BrandingManagerStrings {
+  title: string;
+  logo: string;
+  logoHint: string;
+  icon: string;
+  iconHint: string;
+  none: string;
+  choose: string;
+  remove: string;
+  save: string;
+  saving: string;
+  saved: string;
+  saveFailed: string;
+}
+
+export const defaultBrandingManagerStrings: BrandingManagerStrings = {
+  title: "Branding",
+  logo: "Logo",
+  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
+  icon: "Icon (favicon)",
+  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
+  none: "none",
+  choose: "Choose",
+  remove: "Remove",
+  save: "Save branding",
+  saving: "Saving…",
+  saved: "Branding saved",
+  saveFailed: "Failed to save branding",
+};
+
+export interface BrandingManagerProps {
+  /**
+   * Sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw
+   * to show the error's message, such as one from `formatApiError`.
+   */
+  save: (form: FormData) => Promise<unknown>;
+  strings?: TextOverrides<BrandingManagerStrings> | undefined;
+}
+
+/** A preview is an object URL for the chosen file or a data URL of a raster image. Anything else shows none. */
+const PREVIEW_URL = /^(blob:|data:image\/(png|jpeg|webp|gif|x-icon|vnd\.microsoft\.icon);base64,)/i;
+const previewUrl = (url: string | null): string | null => (url !== null && PREVIEW_URL.test(url) ? url : null);
+
+interface SlotProps {
+  label: string;
+  hint: string;
+  currentUrl: string | null;
+  file: File | null;
+  onPick: (file: File | null) => void;
+  onClear: () => void;
+  text: BrandingManagerStrings;
+}
+
+function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [objectUrl, setObjectUrl] = useState<string | null>(null);
+
+  // An object URL is an outside resource with a lifetime, which is what an effect is for. Creating
+  // it during render instead leaks the second URL that StrictMode builds when it renders twice.
+  /* eslint-disable react-hooks/set-state-in-effect */
+  useEffect(() => {
+    if (!file) {
+      setObjectUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(file);
+    setObjectUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [file]);
+  /* eslint-enable react-hooks/set-state-in-effect */
+
+  const preview = previewUrl(objectUrl ?? currentUrl);
+  return (
+    <div>
+      <label className="block text-sm font-medium text-gray-700 mb-1">{label}</label>
+      <div className="flex items-center gap-3">
+        <div className="h-14 w-14 rounded-lg border border-gray-200 bg-gray-50 flex items-center justify-center overflow-hidden">
+          {preview ? (
+            <img src={preview} alt={label} className="max-h-full max-w-full object-contain" />
+          ) : (
+            <span className="text-xs text-gray-400">{text.none}</span>
+          )}
+        </div>
+        <input
+          ref={inputRef}
+          type="file"
+          accept="image/*"
+          aria-label={label}
+          className="hidden"
+          onChange={e => onPick(e.target.files?.[0] ?? null)}
+        />
+        <button
+          type="button"
+          onClick={() => inputRef.current?.click()}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-3 py-2 text-sm hover:bg-gray-200"
+        >
+          <ArrowUpTrayIcon className="h-4 w-4" /> {text.choose}
+        </button>
+        {(currentUrl || file) && (
+          <button type="button" onClick={onClear} className="p-2 rounded-lg text-red-500 hover:bg-red-50" title={text.remove} aria-label={`${text.remove} ${label}`}>
+            <TrashIcon className="h-4 w-4" />
+          </button>
+        )}
+      </div>
+      <p className="mt-1 text-xs text-gray-500">{hint}</p>
+    </div>
+  );
+}
+
+/** The admin form for uploading or removing the logo and the favicon. Needs a `BrandingProvider` above it. */
+export function BrandingManager({ save, strings }: BrandingManagerProps) {
+  const text = withDefaults(defaultBrandingManagerStrings, strings);
+  const { branding, refresh } = useBranding();
+  const [logo, setLogo] = useState<File | null>(null);
+  const [icon, setIcon] = useState<File | null>(null);
+  const [removeLogo, setRemoveLogo] = useState(false);
+  const [removeIcon, setRemoveIcon] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  const currentLogo = removeLogo ? null : toDataUrl(branding.logoData, branding.logoContentType);
+  const currentIcon = removeIcon ? null : toDataUrl(branding.iconData, branding.iconContentType);
+
+  const submit = async () => {
+    setSaving(true);
+    try {
+      const form = new FormData();
+      if (logo) form.append("logo", logo);
+      if (icon) form.append("icon", icon);
+      if (removeLogo) form.append("removeLogo", "true");
+      if (removeIcon) form.append("removeIcon", "true");
+      await save(form);
+      setLogo(null);
+      setIcon(null);
+      setRemoveLogo(false);
+      setRemoveIcon(false);
+      refresh();
+      toast.success(text.saved);
+    } catch (err) {
+      toast.error(err instanceof Error && err.message ? err.message : text.saveFailed);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md space-y-5 border-t border-gray-200 pt-6">
+      <h2 className="font-bold text-gray-900">{text.title}</h2>
+      <Slot
+        label={text.logo}
+        hint={text.logoHint}
+        currentUrl={currentLogo}
+        file={logo}
+        onPick={f => { setLogo(f); setRemoveLogo(false); }}
+        onClear={() => { setLogo(null); setRemoveLogo(true); }}
+        text={text}
+      />
+      <Slot
+        label={text.icon}
+        hint={text.iconHint}
+        currentUrl={currentIcon}
+        file={icon}
+        onPick={f => { setIcon(f); setRemoveIcon(false); }}
+        onClear={() => { setIcon(null); setRemoveIcon(true); }}
+        text={text}
+      />
+      <button
+        type="button"
+        onClick={submit}
+        disabled={saving || (!logo && !icon && !removeLogo && !removeIcon)}
+        className="rounded-button bg-button-primary-bg text-button-primary-text font-semibold px-5 py-2.5 hover:brightness-95 disabled:opacity-60 transition"
+      >
+        {saving ? text.saving : text.save}
+      </button>
+    </div>
+  );
+}

package/src/branding/BrandingProvider.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { toDataUrl, type Branding } from "./types";
+
+export interface BrandingContextValue {
+  branding: Branding;
+  /** The logo as a `data:` URL, or null when none is set. */
+  logoUrl: string | null;
+  /** Loads the branding again, such as after saving it. */
+  refresh: () => void;
+}
+
+const BrandingContext = createContext<BrandingContextValue>({ branding: {}, logoUrl: null, refresh: () => {} });
+
+/** The branding from the nearest `BrandingProvider`. Empty outside one. */
+export const useBranding = () => useContext(BrandingContext);
+
+/** How often the provider loads the branding again, so an open tab picks up a change. */
+export const BRANDING_REFRESH_MS = 5 * 60 * 1000;
+
+export interface BrandingProviderProps {
+  children: ReactNode;
+  /** Loads the branding, such as a GET of `/branding`. A failure keeps the branding it has. */
+  load: () => Promise<Branding>;
+  /** The branding the server rendered with. Without it, the provider loads it on mount. */
+  initial?: Branding | undefined;
+}
+
+/** Holds the logo and favicon for the components below it, and loads them again every five minutes. */
+export function BrandingProvider({ children, load, initial }: BrandingProviderProps) {
+  const [branding, setBranding] = useState<Branding>(initial ?? {});
+  // The latest load, so an inline function does not restart the refresh timer on every render.
+  const loadRef = useRef(load);
+  useEffect(() => {
+    loadRef.current = load;
+  }, [load]);
+  const hasInitial = initial !== undefined;
+
+  const refresh = useCallback(() => {
+    loadRef.current().then(setBranding).catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    if (!hasInitial) refresh();
+    const id = setInterval(refresh, BRANDING_REFRESH_MS);
+    return () => clearInterval(id);
+  }, [refresh, hasInitial]);
+
+  const logoUrl = toDataUrl(branding.logoData, branding.logoContentType);
+
+  return <BrandingContext.Provider value={{ branding, logoUrl, refresh }}>{children}</BrandingContext.Provider>;
+}

package/src/branding/index.ts

@@ -0,0 +1,14 @@
+export {
+  BrandingManager,
+  defaultBrandingManagerStrings,
+  type BrandingManagerProps,
+  type BrandingManagerStrings,
+} from "./BrandingManager";
+export {
+  BRANDING_REFRESH_MS,
+  BrandingProvider,
+  useBranding,
+  type BrandingContextValue,
+  type BrandingProviderProps,
+} from "./BrandingProvider";
+export { toDataUrl, type Branding } from "./types";

package/src/branding/server.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import type { Branding } from "./types";
+
+export interface BrandingIconOptions {
+  /** Loads the branding, such as a cached GET of `/branding`. Throws when the API cannot be reached. */
+  load: () => Promise<Branding | null | undefined>;
+  /** The bundled icon for when none is set, such as `public/icon.png`. */
+  fallbackPath: string;
+  /** Its content type, such as `image/png` or `image/svg+xml`. */
+  fallbackType: string;
+}
+
+/**
+ * The response for an `app/icon.ts` route: the favicon set in admin settings when it is a PNG,
+ * JPEG, WebP, GIF or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox CSP
+ * that a CSP header from the app's `next.config` replaces.
+ * When the branding cannot be loaded it answers 503 with `no-store`, not the
+ * bundled icon, since a browser would cache that in place of the one set in settings. The route
+ * needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment.
+ */
+export async function brandingIcon({ load, fallbackPath, fallbackType }: BrandingIconOptions): Promise<Response> {
+  let branding: Branding | null | undefined;
+  try {
+    branding = await load();
+  } catch {
+    return new Response(null, { status: 503, headers: { "Cache-Control": "no-store" } });
+  }
+
+  const type = branding?.iconContentType?.trim().toLowerCase();
+  if (branding?.iconData && type && RASTER_TYPES.has(type)) {
+    return new Response(new Uint8Array(Buffer.from(branding.iconData, "base64")), {
+      headers: { "Content-Type": type, ...HARDENING },
+    });
+  }
+
+  return new Response(new Uint8Array(await readFile(fallbackPath)), { headers: { "Content-Type": fallbackType, ...HARDENING } });
+}
+
+/**
+ * The uploaded types the icon route serves. An SVG or HTML upload could carry script and would run
+ * on the site's origin, so anything else gives the bundled icon instead.
+ */
+const RASTER_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif", "image/x-icon", "image/vnd.microsoft.icon"]);
+
+/** Keeps a browser from sniffing the bytes as another type, and from running anything in them where the app sets no CSP. */
+const HARDENING = { "X-Content-Type-Options": "nosniff", "Content-Security-Policy": "default-src 'none'; sandbox" };
+
+/**
+ * A short digest of icon bytes, for a URL that changes when the icon does, such as
+ * `/icon?v=<digest>` in the web app manifest. Android refreshes a home screen icon only when the
+ * manifest changes.
+ */
+export const iconVersion = (data: string | Buffer): string => createHash("sha256").update(data).digest("hex").slice(0, 12);

package/src/branding/types.ts

@@ -0,0 +1,13 @@
+/** The logo and favicon set in admin settings, as the API's `/branding` endpoint returns them. */
+export interface Branding {
+  /** Base64 image bytes. */
+  logoData?: string | null | undefined;
+  logoContentType?: string | null | undefined;
+  /** Base64 image bytes. */
+  iconData?: string | null | undefined;
+  iconContentType?: string | null | undefined;
+}
+
+/** A `data:` URL for base64 image bytes, or null when either part is missing. */
+export const toDataUrl = (data?: string | null, contentType?: string | null): string | null =>
+  data && contentType ? `data:${contentType};base64,${data}` : null;

package/src/payments/PaymentReturn.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { ArrowPathIcon, CheckCircleIcon, ClockIcon, XCircleIcon } from "@heroicons/react/24/outline";
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { cx } from "../ui/cx";
+
+export type PaymentReturnState = "success" | "pending" | "failed";
+
+/** The text and the way on for one state. */
+export interface PaymentReturnContent {
+  title: string;
+  body: string;
+  /** Where the button goes. */
+  href: string;
+  /** The button's text. */
+  cta: string;
+  /** A smaller line under the body. */
+  note?: string | undefined;
+  /** Anything more under the body, such as a receipt link. */
+  extra?: ReactNode;
+}
+
+export interface PaymentReturnProps {
+  state: PaymentReturnState;
+  success: PaymentReturnContent;
+  pending: PaymentReturnContent;
+  failed: PaymentReturnContent;
+  /** Checks the status again. Shows a button for it while pending. */
+  onRefresh?: (() => void) | undefined;
+  /** The refresh button's text. Defaults to `Check again`. */
+  refreshLabel?: string | undefined;
+  /** Classes for placing it, on the outer element. */
+  className?: string | undefined;
+}
+
+const ICONS = { success: CheckCircleIcon, pending: ClockIcon, failed: XCircleIcon } as const;
+const ICON_COLOURS = { success: "text-payment-success", pending: "text-payment-pending", failed: "text-payment-failed" } as const;
+
+const primary = "px-5 py-2.5 rounded-payment-button bg-button-primary-bg text-button-primary-text hover:brightness-110 text-sm font-medium transition";
+const refresh = "px-4 py-2.5 rounded-payment-button bg-button-primary-bg/80 text-button-primary-text hover:bg-button-primary-bg text-sm font-medium transition-colors flex items-center gap-2";
+const secondary = "py-2.5 rounded-payment-button bg-payment-secondary-bg hover:bg-payment-secondary-hover-bg text-payment-secondary-text text-sm transition-colors";
+
+/**
+ * What a user sees on coming back from a payment provider: confirmed, still pending, or failed.
+ * The app decides the state, such as with `usePollUntilFinal`.
+ */
+export function PaymentReturn({ state, success, pending, failed, onRefresh, refreshLabel = "Check again", className }: PaymentReturnProps) {
+  const content = { success, pending, failed }[state];
+  const Icon = ICONS[state];
+  return (
+    <div className={cx("max-w-md mx-auto px-4 py-12 flex flex-col items-center gap-5 text-center", className)}>
+      <Icon className={cx("h-16 w-16", ICON_COLOURS[state])} aria-hidden />
+      <h1 className="text-xl font-bold text-payment-title">{content.title}</h1>
+      <p className="text-sm text-payment-text">{content.body}</p>
+      {content.note && <p className="text-xs text-payment-note">{content.note}</p>}
+      {content.extra}
+      {state === "pending" ? (
+        <div className="flex gap-2">
+          {onRefresh && (
+            <button type="button" onClick={onRefresh} className={refresh}>
+              <ArrowPathIcon className="h-4 w-4" aria-hidden />
+              {refreshLabel}
+            </button>
+          )}
+          <Link href={content.href} className={cx(secondary, "px-4")}>{content.cta}</Link>
+        </div>
+      ) : (
+        <Link href={content.href} className={state === "success" ? primary : cx(secondary, "px-5")}>{content.cta}</Link>
+      )}
+    </div>
+  );
+}

package/src/payments/formatNok.ts

@@ -0,0 +1,4 @@
+/** An amount in øre as Norwegian kroner, such as `NOK 373,75`. */
+export function formatNok(ore: number): string {
+  return `NOK ${(ore / 100).toFixed(2).replace(".", ",")}`;
+}

package/src/payments/index.ts

@@ -0,0 +1,3 @@
+export { formatNok } from "./formatNok";
+export { PaymentReturn, type PaymentReturnContent, type PaymentReturnProps, type PaymentReturnState } from "./PaymentReturn";
+export { usePollUntilFinal, type PollOptions, type PollResult } from "./usePollUntilFinal";

package/src/payments/usePollUntilFinal.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface PollResult<T> {
+  /** The latest value, or null before the first answer. */
+  data: T | null;
+  /** True until a final value, the last retry or a failed fetch. */
+  loading: boolean;
+  /** Polls again from the start, with the spinner showing. */
+  refresh: () => void;
+}
+
+export interface PollOptions {
+  /** How many more times to fetch after the first. Defaults to 8. */
+  retries?: number | undefined;
+  /** Milliseconds between fetches. Defaults to 4000. */
+  delayMs?: number | undefined;
+}
+
+/**
+ * Fetches until the value is final, such as an order a payment provider has not confirmed yet when
+ * the user comes back from it. Stops after the retries, on a failed fetch and on unmount. Each fetch
+ * uses the latest `fetcher` and `isFinal` given.
+ */
+export function usePollUntilFinal<T>(
+  fetcher: () => Promise<T | null>,
+  isFinal: (value: T | null) => boolean,
+  { retries = 8, delayMs = 4000 }: PollOptions = {},
+): PollResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const latest = useRef({ fetcher, isFinal });
+  useEffect(() => {
+    latest.current = { fetcher, isFinal };
+  }, [fetcher, isFinal]);
+  const run = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const start = useCallback(() => {
+    const id = ++run.current;
+    let attempt = 0;
+    const tick = async () => {
+      try {
+        const value = await latest.current.fetcher();
+        if (id !== run.current) return;
+        setData(value);
+        if (latest.current.isFinal(value) || attempt >= retries) {
+          setLoading(false);
+          return;
+        }
+        attempt += 1;
+        timer.current = setTimeout(tick, delayMs);
+      } catch {
+        if (id === run.current) setLoading(false);
+      }
+    };
+    void tick();
+  }, [retries, delayMs]);
+
+  // `loading` starts true, so the first poll needs no flag of its own.
+  useEffect(() => {
+    start();
+    return () => {
+      // A new run number cancels whichever run is current, including one a refresh started.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      run.current++;
+      clearTimeout(timer.current);
+    };
+  }, [start]);
+
+  const refresh = useCallback(() => {
+    clearTimeout(timer.current);
+    setLoading(true);
+    start();
+  }, [start]);
+
+  return { data, loading, refresh };
+}

package/src/styles.css

@@ -60,6 +60,17 @@
   --color-markdown-code-bg: var(--color-gray-100);
   --color-markdown-code-text: var(--color-gray-900);
 
+  --radius-payment-button: var(--radius-button);
+  --color-payment-success: var(--color-green-600);
+  --color-payment-pending: var(--color-amber-500);
+  --color-payment-failed: var(--color-red-600);
+  --color-payment-title: var(--color-gray-900);
+  --color-payment-text: var(--color-gray-600);
+  --color-payment-note: var(--color-gray-500);
+  --color-payment-secondary-bg: var(--color-gray-100);
+  --color-payment-secondary-hover-bg: var(--color-gray-200);
+  --color-payment-secondary-text: var(--color-gray-700);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);