@sjolystinnovation/app-kit 0.14.0 → 0.15.0

package/README.md

@@ -28,7 +28,7 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui`, `markdown`, `branding` 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
@@ -523,6 +523,48 @@ fetch and revalidate the tag after a save, so a new icon shows at once. `iconVer
 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
@@ -1016,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.14.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",
@@ -31,6 +31,7 @@
     "./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/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);