@sjolystinnovation/app-kit 0.3.0 → 0.4.0

package/README.md

@@ -64,14 +64,14 @@ const secret = resolveJwtSecret(sessionConfig, process.env);
 | --- | --- | --- |
 | `jwtSecretEnvVar` | `string` | Name of the environment variable holding the API JWT secret, such as `API_JWT_SECRET`. |
 | `loginRoute` | `string` | Where an expired session sends the browser, such as `/en/login` or `/login`. |
-| `draftStoragePrefix` | `string` | Prefix for the `localStorage` keys holding form drafts. |
+| `draftStoragePrefix` | `string` | Bare name for the `localStorage` keys holding form drafts, such as `example`. Drafts are stored under `example:draft:<owner>:<scope>`. |
 
 ### `defineSessionConfig(config)`
 
 `(config: SessionConfig) => SessionConfig`
 
 Returns the config unchanged, so TypeScript checks its shape where it is declared rather than at
-every call site.
+every call site. Throws when `draftStoragePrefix` is empty or contains a colon.
 
 ### `resolveJwtSecret(config, env)`
 
@@ -124,6 +124,151 @@ try {
 }
 ```
 
+### `@sjolystinnovation/app-kit/session`
+
+Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
+callbacks.
+
+The gate reads `session.error`. The app's `jwt` callback sets `token.error`, and its `session`
+callback copies it across:
+
+```ts
+callbacks: {
+  session({ session, token }) {
+    session.error = token.error;
+    return session;
+  },
+},
+```
+
+For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+the app's existing next-auth type declarations, or create them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    error?: string | undefined;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    error?: string | undefined;
+  }
+}
+```
+
+`SESSION_ERRORS` holds the values the jwt callback puts in `token.error` when the session cannot be
+recovered: `AbsoluteSessionExpired`, `RefreshTokenRejected` and `NoRefreshToken`. `SessionError`
+is their union type. `isTerminalSessionError(error)` is true for those three only, so a transient
+refresh failure keeps the session.
+
+The re-sign-in prompt is a flag outside React, so an axios interceptor can raise it:
+
+| Function | Description |
+| --- | --- |
+| `openSessionPrompt()` | Asks the user to sign in again without leaving the page. |
+| `closeSessionPrompt()` | Hides the prompt. Call it when the component showing the prompt unmounts, or the flag stays open and the gate never redirects. |
+| `subscribeSessionPrompt(listener)` | Calls `listener` when the prompt opens or closes. Returns an unsubscribe function. |
+| `getSessionPromptOpen()` | Whether the prompt is showing. |
+
+Copies of the package installed side by side share the one flag, as long as their releases use the
+same prompt state format. A release that changes the format says so in its changelog. An app's own
+copy of these functions does not, so an app moving to them moves every import at once: the
+interceptor, the prompt and every gate.
+
+### `useSessionGate()`
+
+From `@sjolystinnovation/app-kit/session/react`. Tells a protected page whether it may render. It
+reads `useSession`, so it needs a `SessionProvider` above it.
+
+A page that rendered on a healthy session stays rendered when the session gets a terminal error,
+while the session is re-read and while the prompt recovers it, so an open form keeps its values. A
+session that turns signed out with no prompt open blanks the page. A page the user opens
+on a dead session does not render. Use `mayRender` in every gate and layout on the way down, so
+none of them blanks a page that another one kept.
+
+The hook does not navigate. The gate sends the user to the login page itself, and never while the
+prompt is open. The app passes the login URL in, so an app with a locale in the path can build it
+for the current locale:
+
+```tsx
+"use client";
+
+import { useSessionGate } from "@sjolystinnovation/app-kit/session/react";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+
+export function ProtectedGate({
+  loginHref,
+  children,
+}: {
+  loginHref: string;
+  children: React.ReactNode;
+}) {
+  const router = useRouter();
+  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
+
+  useEffect(() => {
+    if (promptOpen) return;
+    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
+      router.push(loginHref);
+    }
+  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+
+  return mayRender ? children : <p>Loading…</p>;
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `mayRender` | Whether the page may render. |
+| `session`, `status` | As `useSession` returns them. |
+| `usable` | The session is signed in and has no terminal error. |
+| `wasUsable` | This page has rendered on a usable session. |
+| `promptOpen` | The re-sign-in prompt is showing. |
+| `recovering` | The prompt is showing over a page that was usable. |
+
+`SessionGate` is the type of the result.
+
+### `useFormDraft(config, options)`
+
+From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
+reload or closed tab does not lose them. Values are written half a second after the last change, so
+only that last half second is at risk.
+
+```tsx
+// userId is the signed-in user's id, from wherever the app's session keeps it.
+const draft = useFormDraft(sessionConfig, {
+  owner: userId,
+  scope: recipe ? `recipe:${recipe.id}` : "recipe:new",
+  value: form,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `owner` | `string \| undefined` | The signed-in user's id. Drafts are stored per user, and nothing is stored until it is known. The last known owner is kept when the session stops reporting one. |
+| `scope` | `string` | The form and the entity it edits, such as `recipe:42`. |
+| `value` | `T` | The form's current values. They must survive `JSON.stringify`. |
+
+Mount an edit form once the entity has loaded, with its values already in `value`. The hook treats
+the values it first sees under a key as the untouched form, so values that arrive later count as an
+edit and are written over the draft being offered.
+
+It returns `pending`, the stored draft, which the page offers instead of applying. It is read when the
+owner is first known and again whenever the owner or `scope` changes, so it can appear after the form mounts. It
+also returns `dismiss()` to stop offering it, and `clear()` to drop the stored draft after a
+successful save.
+
+Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook throws when
+`draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
+removed when its form next reads it.
+
 ### `Alert`
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -16,6 +16,9 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./session": "./src/session/index.ts",
+    "./session/react": "./src/session/react/index.ts",
+    "./forms": "./src/forms/index.ts",
     "./ui": "./src/ui/index.ts",
     "./styles.css": "./src/styles.css"
   },

package/src/config.ts

@@ -13,15 +13,35 @@ export interface SessionConfig {
    * something like "/en/login", one without uses "/login".
    */
   loginRoute: string;
-  /** Prefix for the localStorage keys holding form drafts. */
+  /**
+   * Prefix for the localStorage keys holding form drafts, usually the app's name, such as
+   * "example". Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
+   * has no trailing colon.
+   */
   draftStoragePrefix: string;
 }
 
-/** Identity helper, so an app can declare its config as a typed constant. */
+/**
+ * Declares an app's config as a typed constant. Throws when `draftStoragePrefix` is not a bare name,
+ * so a bad value fails when the app starts rather than when a form first opens.
+ */
 export function defineSessionConfig(config: SessionConfig): SessionConfig {
+  draftPrefix(config);
   return config;
 }
 
+/**
+ * The key prefix for form drafts. A colon or an empty name builds keys such as "app:draft::draft:",
+ * which match none of the drafts already saved under "app:draft:".
+ */
+export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
+  const name = config.draftStoragePrefix;
+  if (!name || name.includes(":")) {
+    throw new Error(`draftStoragePrefix must be a bare name such as "example", not "${name}".`);
+  }
+  return `${name}:draft:`;
+}
+
 /**
  * Reads the API JWT secret named by the config. Throws rather than returning undefined, because a
  * missing secret silently breaks token verification at runtime instead of at boot.

package/src/forms/index.ts

@@ -0,0 +1,2 @@
+export { useFormDraft } from "./useFormDraft";
+export type { FormDraft, FormDraftOptions } from "./useFormDraft";

package/src/forms/useFormDraft.ts

@@ -0,0 +1,133 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { draftPrefix, type SessionConfig } from "../config";
+
+const WRITE_DELAY_MS = 500;
+
+// How long a draft is offered. Long enough to outlive an expired session or a closed tab, short
+// enough that week-old work is not offered as if it were current. An expired draft is removed when
+// its form next reads it.
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+interface Envelope<T> {
+  savedAt: number;
+  value: T;
+}
+
+function read<T>(storageKey: string): T | null {
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw == null) return null;
+
+    const envelope = JSON.parse(raw) as Envelope<T> | null;
+    const fresh =
+      typeof envelope?.savedAt === "number" && Date.now() - envelope.savedAt <= MAX_AGE_MS;
+    if (!fresh || envelope?.value === undefined) {
+      window.localStorage.removeItem(storageKey);
+      return null;
+    }
+    return envelope.value;
+  } catch {
+    return null;
+  }
+}
+
+export interface FormDraftOptions<T> {
+  /**
+   * The signed-in user's id. A browser profile can be shared, so the draft is stored per user.
+   * Without that, the next person to sign in is offered the previous one's work. The last known
+   * owner is kept, because a lost cookie reports nobody and that is the moment the draft matters
+   * most. Nothing is stored until an owner is known.
+   */
+  owner: string | undefined;
+  /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
+  scope: string;
+  /** The form's current values. They must survive `JSON.stringify`. */
+  value: T;
+}
+
+export interface FormDraft<T> {
+  /**
+   * The stored draft, while it is still waiting to be restored or dismissed. Read once the owner is
+   * known and again whenever the owner or scope changes, so it can appear after mount.
+   */
+  pending: T | null;
+  /** Stop offering the draft. The caller applies the values it wants. */
+  dismiss: () => void;
+  /** Drop the stored draft after a successful save. */
+  clear: () => void;
+}
+
+/**
+ * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
+ * Values are written half a second after the last change, so only that last half second is at risk.
+ *
+ * A draft found at mount is offered for restore rather than applied, so an edit form never silently
+ * overwrites what the API returned. Saving starts immediately either way. The offer is held in
+ * memory, so the newest work is always the thing in storage.
+ */
+export function useFormDraft<T>(
+  config: Pick<SessionConfig, "draftStoragePrefix">,
+  { owner, scope, value }: FormDraftOptions<T>,
+): FormDraft<T> {
+  // Adjusted during render rather than in an effect, which is the supported way to derive state
+  // from changing inputs.
+  const [lastOwner, setLastOwner] = useState<string | undefined>(undefined);
+  if (owner && owner !== lastOwner) setLastOwner(owner);
+
+  // Checked before the owner is known, so a bad prefix fails on the first render, signed in or not.
+  const prefix = draftPrefix(config);
+  const key = lastOwner ? `${prefix}${lastOwner}:${scope}` : null;
+
+  const [pending, setPending] = useState<T | null>(null);
+  const json = JSON.stringify(value);
+  const untouched = useRef(json);
+  const writeTimer = useRef<number | null>(null);
+
+  useEffect(() => {
+    // Re-base on a key change too. The values on screen belong to the old key, and writing them
+    // under the new one would put this form's work in another form's draft.
+    untouched.current = json;
+    // Reading the store is an external-system read, which is what an effect is for.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setPending(key == null ? null : read<T>(key));
+    // Keyed on the draft key alone on purpose. Re-reading whenever the values change would
+    // re-offer a draft the user has already answered.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  useEffect(() => {
+    if (key == null) return;
+    // Write only once the form differs from how it opened. Writing the pristine form would
+    // overwrite the draft being offered before the user has answered.
+    if (json === untouched.current) return;
+    const timer = window.setTimeout(() => {
+      try {
+        window.localStorage.setItem(key, JSON.stringify({ savedAt: Date.now(), value }));
+      } catch {
+        // A full or blocked store must not break the form.
+      }
+    }, WRITE_DELAY_MS);
+    writeTimer.current = timer;
+    return () => window.clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, json]);
+
+  const clear = useCallback(() => {
+    if (key == null) return;
+    // Cancel a write that is already scheduled, and treat the current values as the new baseline.
+    // Otherwise a save is followed by the draft being written back.
+    if (writeTimer.current != null) window.clearTimeout(writeTimer.current);
+    untouched.current = json;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // The draft is a convenience, not state anything depends on.
+    }
+  }, [key, json]);
+
+  const dismiss = useCallback(() => setPending(null), []);
+
+  return { pending, dismiss, clear };
+}

package/src/session/expiry.ts

@@ -0,0 +1,66 @@
+/**
+ * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
+ * transient refresh failure, such as a network error or an API restart, sets no error, so the
+ * session keeps working and a later session read retries the refresh.
+ */
+export const SESSION_ERRORS = {
+  absoluteExpiry: "AbsoluteSessionExpired",
+  refreshRejected: "RefreshTokenRejected",
+  noRefreshToken: "NoRefreshToken",
+} as const;
+
+/** One of the values in `SESSION_ERRORS`. */
+export type SessionError = (typeof SESSION_ERRORS)[keyof typeof SESSION_ERRORS];
+
+const TERMINAL: ReadonlySet<string> = new Set(Object.values(SESSION_ERRORS));
+
+/** Whether a session error means the user has to sign in again. */
+export function isTerminalSessionError(error: string | undefined): boolean {
+  return error != null && TERMINAL.has(error);
+}
+
+// Whether the re-sign-in prompt is showing. It lives outside React because the axios interceptor
+// that raises it is a plain module, and because the page gate has to know: it must not redirect to
+// the login page while the prompt is recovering the session in place.
+//
+// Kept on globalThis under a registered symbol, so two copies of this module, such as two installed
+// versions of the package, still share one prompt. Separate state would let a prompt raised through
+// one copy go unseen by a gate reading the other, and the gate would redirect away from the form.
+interface PromptState {
+  open: boolean;
+  listeners: Set<() => void>;
+}
+
+// The shape of PromptState is a contract between releases. A release that changes it must also
+// change this key, so it never reads state in a shape it does not expect.
+const STATE_KEY = Symbol.for("@sjolystinnovation/app-kit/session-prompt/v1");
+const shared = globalThis as typeof globalThis & { [STATE_KEY]?: PromptState };
+const state: PromptState = (shared[STATE_KEY] ??= { open: false, listeners: new Set() });
+
+function emit(): void {
+  for (const listener of [...state.listeners]) listener();
+}
+
+/** Ask the user to sign in again without leaving the page. */
+export function openSessionPrompt(): void {
+  if (state.open) return;
+  state.open = true;
+  emit();
+}
+
+export function closeSessionPrompt(): void {
+  if (!state.open) return;
+  state.open = false;
+  emit();
+}
+
+export function subscribeSessionPrompt(listener: () => void): () => void {
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function getSessionPromptOpen(): boolean {
+  return state.open;
+}

package/src/session/index.ts

@@ -0,0 +1,9 @@
+export {
+  SESSION_ERRORS,
+  closeSessionPrompt,
+  getSessionPromptOpen,
+  isTerminalSessionError,
+  openSessionPrompt,
+  subscribeSessionPrompt,
+} from "./expiry";
+export type { SessionError } from "./expiry";

package/src/session/react/index.ts

@@ -0,0 +1,2 @@
+export { useSessionGate } from "./useSessionGate";
+export type { SessionGate } from "./useSessionGate";

package/src/session/react/useSessionGate.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useSession } from "next-auth/react";
+import { usePathname } from "next/navigation";
+import { useState, useSyncExternalStore } from "react";
+import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt } from "../expiry";
+
+/**
+ * Whether a protected page may render, and whether it must stay rendered.
+ *
+ * Every gate on the way down should use this, so they agree. A nested layout that decides on its
+ * own to blank the page undoes the in-place recovery the re-sign-in prompt exists for, and the user
+ * loses the form anyway.
+ */
+export function useSessionGate() {
+  const { data: session, status } = useSession();
+  const pathname = usePathname();
+  const promptOpen = useSyncExternalStore(
+    subscribeSessionPrompt,
+    getSessionPromptOpen,
+    () => false,
+  );
+
+  // The jwt callback copies its error onto the session. Read it without requiring the app to have
+  // added `error` to next-auth's Session type.
+  const error = (session as { error?: string } | null)?.error;
+  const usable = status === "authenticated" && !isTerminalSessionError(error);
+
+  // Which page last rendered on a healthy session. Keyed by path, so each page starts the check
+  // again and a session that died on the previous page cannot carry a stale pass into a fresh form.
+  // Adjusted during render rather than in an effect, which is the supported way to derive state
+  // from changing inputs.
+  // Undefined until then rather than null, because usePathname can itself return null.
+  const [usableAt, setUsableAt] = useState<string | null | undefined>(undefined);
+  if (usable && usableAt !== pathname) setUsableAt(pathname);
+  const wasUsable = usableAt === pathname;
+
+  // The page is already open and the prompt is recovering the session in place.
+  const recovering = promptOpen && wasUsable;
+
+  return {
+    session,
+    status,
+    promptOpen,
+    usable,
+    wasUsable,
+    recovering,
+    /**
+     * The one answer every gate on the way down uses. A layout that decides this again can blank
+     * the page that the gate above it chose to keep.
+     */
+    mayRender:
+      recovering ||
+      !(
+        (status === "loading" && !wasUsable) ||
+        status === "unauthenticated" ||
+        (!usable && !wasUsable)
+      ),
+  };
+}
+
+/** What `useSessionGate` returns. */
+export type SessionGate = ReturnType<typeof useSessionGate>;