@sjolystinnovation/app-kit 0.18.0 → 0.20.0

package/README.md

@@ -210,35 +210,18 @@ Two rules keep a refresh from being lost:
 - Run the app as one server process. Parallel session reads share one refresh only within a process.
   Two replicas can refresh the same token at once, with the same result.
 
-The package does not declare these fields on next-auth's types. The app declares them, so its own
-code can read them:
+The package declares these fields on next-auth's types in `@sjolystinnovation/app-kit/next-auth`. The
+app loads the declarations once, from one of its own `.d.ts` files, so its code can read them:
 
 ```ts
 // src/types/next-auth.d.ts
-import "next-auth";
-import "next-auth/jwt";
-
-declare module "next-auth" {
-  interface Session {
-    user: { id: string; name: string; email: string; roles: string[] };
-    accessToken: string;
-    error?: string | undefined;
-    absoluteExpiresAt?: number;
-  }
-}
-
-declare module "next-auth/jwt" {
-  interface JWT {
-    accessToken?: string;
-    refreshToken?: string;
-    refreshAt?: number;
-    loginAt?: number;
-    user?: { id: string; name: string; email: string; roles: string[] };
-    error?: string | undefined;
-  }
-}
+import "@sjolystinnovation/app-kit/next-auth";
 ```
 
+The session carries `user` (`id`, `name`, `email`, `roles`), `accessToken`, `error` and
+`absoluteExpiresAt`. The token carries `accessToken`, `refreshToken`, `refreshAt`, `loginAt`, `user`
+and `error`.
+
 ### `@sjolystinnovation/app-kit/api`
 
 `createApiClient(baseURL)` returns an axios instance for the signed-in API, for code that runs in
@@ -594,6 +577,50 @@ if (loading) return <Spinner />;
 
 `formatNok(ore)` formats øre as kroner, such as `NOK 373,75`.
 
+### `@sjolystinnovation/app-kit/admin`
+
+The admin area. `AdminShell` is the frame: a title and a tab bar above the page, behind a
+`RoleGate`. It takes `RoleGate`'s `role`, `fallback`, and `denied` or `deniedHref`. The tab whose
+`href` is the current path is active, with `aria-current="page"`.
+
+```tsx
+// src/app/[locale]/(protected)/admin/layout.tsx
+"use client";
+import { AdminShell } from "@sjolystinnovation/app-kit/admin";
+
+export default function AdminLayout({ children }: { children: React.ReactNode }) {
+  const { dict, locale } = useDictionary();
+  const tabs = [
+    { href: `/${locale}/admin/users`, label: dict.admin.users },
+    { href: `/${locale}/admin/legal`, label: dict.admin.legal },
+  ];
+  return (
+    <AdminShell role="Admin" title={dict.admin.title} tabs={tabs} deniedHref={`/${locale}`}>
+      {children}
+    </AdminShell>
+  );
+}
+```
+
+`AdminUsersPanel` is the users page. It lists every user with their roles, shows deleted users
+behind a toggle, gives and takes roles, deletes an account after a confirm, and invites a user by
+email. It calls the API through `createAdminUsersService`. `getRoles` returns the roles an admin
+may give. Inline functions are fine. The panel does not fetch again when they change. It reports
+with `toast`, so the app needs sonner and a `Toaster`.
+
+```tsx
+import { AdminUsersPanel } from "@sjolystinnovation/app-kit/admin";
+
+<AdminUsersPanel service={adminUsers} getRoles={AdminService.getRoles} strings={dict.adminUsers} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `service` | `ReturnType<typeof createAdminUsersService>` | The user admin calls. |
+| `getRoles` | `() => Promise<string[]>` | The roles an admin may give. |
+| `defaultInviteRole` | `string` | The role a new invite starts with. Defaults to `Admin`. |
+| `strings` | `TextOverrides<AdminUsersPanelStrings>` | The text, English by default. `{name}` and `{role}` are filled in where a text names them. |
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
@@ -839,6 +866,58 @@ A failed sign-in shows `signInUnavailable` for `SIGN_IN_ERRORS.unavailable` and
 `invalidCredentials` for any other error code. A request next-auth refuses without an error code,
 or one that throws, shows `somethingWentWrong`.
 
+### `LoginPage`
+
+From `@sjolystinnovation/app-kit/ui`. The sign-in page: a title, `CredentialsForm`, a link to reset
+the password and, when the app has sign-up, a link to it. A sign-in goes to `redirectTo` and refreshes
+the page's server data. It uses the same `auth` theme variables as `ResetPasswordFlow`.
+
+```tsx
+<LoginPage redirectTo="/admin" resetHref="/reset-password" strings={{ title: "Logg inn" }} formStrings={{ signIn: "Logg inn" }} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `redirectTo` | `string` | Where a signed-in user goes. |
+| `resetHref` | `string` | The password reset page. |
+| `registerHref` | `string` | The sign-up page. Without it there is no register link. |
+| `strings` | `TextOverrides<LoginPageStrings>` | The page's text: `title`, `forgotPassword`, `registerPrompt` (null leaves it out) and `register`. |
+| `formStrings` | `TextOverrides<CredentialsFormStrings>` | The form's text. |
+| `className` | `string` | Replaces the outer `max-w-md mx-auto px-4 py-16`. |
+
+### `ResetPasswordFlow`
+
+From `@sjolystinnovation/app-kit/ui`. The password reset page in two steps: the email asks for a
+code, then the code and a new password set it. The password is checked against the same rules as
+`passwordSchema` before it is sent, without loading zod. An emailed link with the email and code,
+such as an invite, opens it on the second step. Its colours and title size come from the `auth` and
+`button` theme variables, see [Theming](#theming).
+
+```tsx
+const params = useSearchParams();
+
+<ResetPasswordFlow
+  requestReset={UserService.requestPasswordReset}
+  reset={UserService.resetPassword}
+  loginHref="/login"
+  initialEmail={params.get("email") ?? ""}
+  initialCode={params.get("code") ?? ""}
+  strings={{ title: "Tilbakestill passord", signInPrompt: null }}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `requestReset` | `(data: { email }) => Promise<unknown>` | Asks the API to email a code. |
+| `reset` | `(data: { email, code, newPassword }) => Promise<unknown>` | Sets the password. A `message` in its answer is shown when it succeeds. |
+| `loginHref` | `string` | Where the sign-in links go. |
+| `initialEmail`, `initialCode` | `string` | From the emailed link. A code opens the second step. |
+| `className` | `string` | Replaces the outer `max-w-md mx-auto px-4 py-16`, such as to sit in the app's own card. |
+| `strings` | `TextOverrides<ResetPasswordFlowStrings>` | The page's text. `signInPrompt`, `intro`, `codeSent` and `passwordHint` set to null are left out. `done` set to null shows the API's message, or only the sign-in link when it sends none. `passwordInvalid` set to null lists every broken rule. |
+| `passwordStrings` | `TextOverrides<PasswordStrings>` | The rule messages, in the app's language. |
+
+A failure shows the error's message, or `somethingWentWrong` when it has none.
+
 `TextOverrides<T>`, from `@sjolystinnovation/app-kit/ui`, is the type of every `strings` prop. Each
 key is optional and may be `undefined`, and a missing or undefined key shows the English default.
 
@@ -1018,7 +1097,8 @@ const result = passwordSchema({ uppercase: "Ta med en stor bokstav fra A til Z."
 const gargeRule = passwordSchema().max(128, "Be at most 128 characters long.");
 ```
 
-`PASSWORD_MIN_LENGTH` holds the minimum, for hint text.
+`PASSWORD_MIN_LENGTH` holds the minimum, for hint text. `passwordProblems(password, strings?)` gives the
+message of every rule a password breaks, in the same order, without zod.
 
 ### `zodFieldErrors(error, options?)`
 
@@ -1080,6 +1160,19 @@ selector such as `.dark` for a scoped theme:
 | `--color-toggle-on` | `var(--color-primary)`, the track of a `Toggle` that is on |
 | `--color-toggle-off` | gray 200, the track of a `Toggle` that is off |
 | `--color-toggle-thumb` | white |
+| `--text-auth-title`, `--text-auth-title--line-height` | `var(--text-2xl)` and its line height, the title of `LoginPage` and `ResetPasswordFlow` |
+| `--font-weight-auth-title` | black |
+| `--color-auth-heading` | gray 900 |
+| `--color-auth-text` | gray 600, the line under the title and the intro |
+| `--color-auth-note` | gray 600, the note that a code was sent |
+| `--color-auth-hint` | gray 500, the hint under the password |
+| `--color-auth-link`, `-hover` | gray 900, the sign-in links |
+| `--font-weight-auth-link` | semibold |
+| `--color-admin-title` | gray 900, the title of `AdminShell` |
+| `--color-admin-border` | gray 200, the line under the tabs |
+| `--color-admin-tab`, `-hover` | gray 500 and gray 900 |
+| `--color-admin-tab-active` | gray 900 |
+| `--color-admin-tab-indicator` | `var(--color-primary)`, the line under the active tab |
 | `--radius-button` | `var(--radius-lg)` |
 | `--color-button-primary-bg` | `var(--color-primary)` |
 | `--color-button-primary-text` | `var(--color-primary-foreground)` |
@@ -1122,9 +1215,9 @@ with it and has to set the ones it uses itself.
 - For `@sjolystinnovation/app-kit/toast`: sonner 2, as an optional peer dependency. Install a single
   copy, because two copies keep two separate toast stores.
 - `jsonwebtoken` comes with the package. `@sjolystinnovation/app-kit/auth` uses it on the server.
-- For `@sjolystinnovation/app-kit/ui` and the components in `session/react`: Tailwind CSS 4 and
-  `@heroicons/react` 2. The focus ring and the primary button use the theme's `primary` and
-  `primary-foreground` colours, unless their own variables are set.
+- For `@sjolystinnovation/app-kit/ui`, `@sjolystinnovation/app-kit/admin` and the components in
+  `session/react`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring and the primary button
+  use the theme's `primary` and `primary-foreground` colours, unless their own variables are set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.18.0",
+  "version": "0.20.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",
@@ -20,9 +20,13 @@
     "./session/react": "./src/session/react/index.ts",
     "./forms": "./src/forms/index.ts",
     "./auth": "./src/auth/index.ts",
+    "./next-auth": {
+      "types": "./src/next-auth.d.ts"
+    },
     "./api": "./src/api/index.ts",
     "./server": "./src/server/index.ts",
     "./ui": "./src/ui/index.ts",
+    "./admin": "./src/admin/index.ts",
     "./toast": "./src/toast/index.ts",
     "./validation": "./src/validation/index.ts",
     "./next-config": "./src/next-config/index.ts",

package/src/admin/AdminShell.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { RoleGate, type RoleGateProps } from "../session/react/RoleGate";
+
+/** One tab in the admin navigation. */
+export interface AdminTab {
+  href: string;
+  label: string;
+}
+
+type GateProps = RoleGateProps extends infer P ? (P extends unknown ? Omit<P, "children"> : never) : never;
+
+export type AdminShellProps = GateProps & {
+  title: ReactNode;
+  tabs: readonly AdminTab[];
+  children: ReactNode;
+};
+
+/**
+ * The admin area's frame: a title and a tab bar above the page, for users with `role` only. The tab
+ * whose `href` is the current path shows as active. The gate props are `RoleGate`'s.
+ */
+export function AdminShell({ title, tabs, children, ...gate }: AdminShellProps) {
+  const pathname = usePathname();
+  const page = (
+    <div className="max-w-5xl mx-auto px-4 sm:px-6 py-10">
+      <h1 className="text-2xl font-black text-admin-title mb-4">{title}</h1>
+      <nav className="flex gap-1 border-b border-admin-border mb-8 overflow-x-auto overflow-y-hidden [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+        {tabs.map((tab) => {
+          const active = pathname === tab.href;
+          return (
+            <Link
+              key={tab.href}
+              href={tab.href}
+              aria-current={active ? "page" : undefined}
+              className={`px-4 py-2 text-sm font-medium border-b-2 -mb-px transition-colors shrink-0 whitespace-nowrap ${
+                active ? "border-admin-tab-indicator text-admin-tab-active" : "border-transparent text-admin-tab hover:text-admin-tab-hover"
+              }`}
+            >
+              {tab.label}
+            </Link>
+          );
+        })}
+      </nav>
+      {children}
+    </div>
+  );
+  // The gate props came in as one of RoleGate's two shapes, so they go back as that shape.
+  return <RoleGate {...({ ...gate, children: page } as RoleGateProps)} />;
+}

package/src/admin/AdminUsersPanel.tsx

@@ -0,0 +1,276 @@
+"use client";
+
+import { PlusIcon, TrashIcon, XMarkIcon } from "@heroicons/react/24/outline";
+import { useEffect, useRef, useState } from "react";
+import type { AdminUser, createAdminUsersService } from "../api/services";
+import { toast } from "../toast";
+import { TextInput } from "../ui/TextInput";
+import { Toggle } from "../ui/Toggle";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { defaultAdminUsersPanelStrings, type AdminUsersPanelStrings } from "./adminUsersPanelStrings";
+
+export interface AdminUsersPanelProps {
+  /** The user admin calls, such as `createAdminUsersService(api)`. */
+  service: ReturnType<typeof createAdminUsersService>;
+  /** The roles an admin may give, from the app's own endpoint. */
+  getRoles: () => Promise<string[]>;
+  /** The role a new invite starts with. `Admin` by default. */
+  defaultInviteRole?: string | undefined;
+  strings?: TextOverrides<AdminUsersPanelStrings> | undefined;
+}
+
+const fill = (text: string, values: Record<string, string>) =>
+  text.replace(/\{(\w+)\}/g, (match, key: string) => values[key] ?? match);
+
+const reason = (err: unknown, fallback: string) => (err instanceof Error && err.message ? err.message : fallback);
+
+/**
+ * The admin users page: every user with their roles, a toggle for deleted users, giving and taking
+ * roles, deleting an account after a confirm, and inviting a user by email.
+ */
+export function AdminUsersPanel({ service, getRoles, defaultInviteRole = "Admin", strings }: AdminUsersPanelProps) {
+  const text = withDefaults(defaultAdminUsersPanelStrings, strings);
+  const [users, setUsers] = useState<AdminUser[]>([]);
+  const [allRoles, setAllRoles] = useState<string[]>([]);
+  const [includeDeleted, setIncludeDeleted] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [addRoleFor, setAddRoleFor] = useState<string | null>(null);
+  const [selectedRole, setSelectedRole] = useState("");
+  const [roleLoading, setRoleLoading] = useState(false);
+  const [invite, setInvite] = useState({ email: "", firstName: "", lastName: "", role: defaultInviteRole });
+  const [inviting, setInviting] = useState(false);
+  // Bumped to fetch the list again after a change, through the same effect as every other load.
+  const [reloads, setReloads] = useState(0);
+  // The latest service, so an inline one does not fetch the list again on every render. The roles
+  // load once, so the first getRoles is enough.
+  const serviceRef = useRef(service);
+  useEffect(() => {
+    serviceRef.current = service;
+  }, [service]);
+  const getRolesRef = useRef(getRoles);
+
+  // Callers set `loading` before changing what to fetch, so the effect only sets state once the
+  // request settles. A request replaced by a newer one is ignored, so a slow answer to an earlier
+  // toggle cannot overwrite the list the toggle now shows.
+  useEffect(() => {
+    let replaced = false;
+    serviceRef.current
+      .getUsers(includeDeleted)
+      .then((list) => {
+        if (!replaced) setUsers(list);
+      })
+      .catch((err: unknown) => {
+        if (!replaced) toast.error(reason(err, text.usersLoadFailed));
+      })
+      .finally(() => {
+        if (!replaced) setLoading(false);
+      });
+    return () => {
+      replaced = true;
+    };
+  }, [includeDeleted, reloads, text.usersLoadFailed]);
+
+  useEffect(() => {
+    getRolesRef
+      .current()
+      .then(setAllRoles)
+      .catch(() => toast.error(text.rolesLoadFailed));
+  }, [text.rolesLoadFailed]);
+
+  const reload = () => {
+    setLoading(true);
+    setReloads((n) => n + 1);
+  };
+
+  const toggleDeleted = (deleted: boolean) => {
+    setLoading(true);
+    setIncludeDeleted(deleted);
+  };
+
+  const setRoles = (id: string, roles: string[]) => setUsers((prev) => prev.map((u) => (u.id === id ? { ...u, roles } : u)));
+
+  const assignRole = async (user: AdminUser) => {
+    if (!selectedRole) return;
+    setRoleLoading(true);
+    try {
+      await serviceRef.current.addRole(user.id, selectedRole);
+      setRoles(user.id, [...user.roles, selectedRole]);
+      toast.success(fill(text.roleAssigned, { name: user.firstName, role: selectedRole }));
+      setAddRoleFor(null);
+      setSelectedRole("");
+    } catch (err) {
+      toast.error(reason(err, text.roleAssignFailed));
+    } finally {
+      setRoleLoading(false);
+    }
+  };
+
+  const removeRole = async (user: AdminUser, role: string) => {
+    try {
+      await serviceRef.current.removeRole(user.id, role);
+      setRoles(user.id, user.roles.filter((r) => r !== role));
+      toast.success(fill(text.roleRemoved, { name: user.firstName, role }));
+    } catch (err) {
+      toast.error(reason(err, text.roleRemoveFailed));
+    }
+  };
+
+  const deleteUser = async (user: AdminUser) => {
+    const label = `${user.firstName} ${user.lastName}`.trim() || user.email;
+    if (!window.confirm(fill(text.confirmDelete, { name: label }))) return;
+    try {
+      await serviceRef.current.deleteUser(user.id);
+      toast.success(text.userDeleted);
+      reload();
+    } catch (err) {
+      toast.error(reason(err, text.userDeleteFailed));
+    }
+  };
+
+  const sendInvite = async () => {
+    if (!invite.email.trim() || !invite.firstName.trim() || !invite.lastName.trim()) {
+      toast.error(text.inviteIncomplete);
+      return;
+    }
+    setInviting(true);
+    try {
+      await serviceRef.current.invite(invite.email.trim(), invite.firstName.trim(), invite.lastName.trim(), invite.role);
+      toast.success(text.inviteSent);
+      setInvite({ email: "", firstName: "", lastName: "", role: invite.role });
+      reload();
+    } catch (err) {
+      toast.error(reason(err, text.inviteFailed));
+    } finally {
+      setInviting(false);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <h2 className="font-bold text-gray-900">{text.users}</h2>
+        <Toggle label={text.showDeleted} checked={includeDeleted} onChange={toggleDeleted} />
+      </div>
+
+      <div className="rounded-2xl border border-gray-200 p-4 space-y-3">
+        <h3 className="text-sm font-semibold text-gray-900">{text.inviteUser}</h3>
+        <div className="flex flex-wrap items-end gap-2">
+          <div className="w-40">
+            <TextInput label={text.firstName} value={invite.firstName} onChange={(e) => setInvite({ ...invite, firstName: e.target.value })} />
+          </div>
+          <div className="w-40">
+            <TextInput label={text.lastName} value={invite.lastName} onChange={(e) => setInvite({ ...invite, lastName: e.target.value })} />
+          </div>
+          <div className="flex-1 min-w-[14rem]">
+            <TextInput label={text.email} type="email" value={invite.email} onChange={(e) => setInvite({ ...invite, email: e.target.value })} />
+          </div>
+          <label className="text-xs text-gray-600">
+            {text.role}
+            <select
+              value={invite.role}
+              onChange={(e) => setInvite({ ...invite, role: e.target.value })}
+              className="mt-1 block rounded-lg border border-gray-300 px-3 py-2 text-sm"
+            >
+              {allRoles.map((role) => (
+                <option key={role} value={role}>
+                  {role}
+                </option>
+              ))}
+            </select>
+          </label>
+          <button
+            onClick={sendInvite}
+            disabled={inviting}
+            className="rounded-button bg-button-primary-bg text-button-primary-text font-semibold px-4 py-2 text-sm hover:brightness-95 disabled:opacity-60 transition"
+          >
+            {inviting ? text.sending : text.sendInvite}
+          </button>
+        </div>
+        <p className="text-xs text-gray-500">{text.inviteHint}</p>
+      </div>
+
+      {loading ? (
+        <p className="text-gray-500">{text.loading}</p>
+      ) : (
+        <ul className="divide-y divide-gray-100 rounded-2xl border border-gray-200">
+          {users.map((user) => {
+            const isAddingRole = addRoleFor === user.id;
+            const available = allRoles.filter((r) => !user.roles.includes(r));
+            return (
+              <li key={user.id} className="p-4 space-y-2">
+                <div className="flex items-start justify-between gap-3">
+                  <div className={user.isDeleted ? "text-gray-400" : "text-gray-800"}>
+                    <span className="font-medium">
+                      {user.firstName} {user.lastName}
+                    </span>
+                    <span className="ml-2 text-xs text-gray-500">{user.email}</span>
+                    {user.isDeleted && <span className="ml-2 text-xs text-gray-400">({text.deleted})</span>}
+                  </div>
+                  {!user.isDeleted && (
+                    <button
+                      onClick={() => deleteUser(user)}
+                      title={text.delete}
+                      className="shrink-0 p-2 rounded-lg text-red-500 hover:text-red-700 hover:bg-red-50 transition-colors"
+                    >
+                      <TrashIcon className="h-4 w-4" />
+                    </button>
+                  )}
+                </div>
+
+                <div className="flex flex-wrap items-center gap-1.5">
+                  {user.roles.map((role) => (
+                    <span key={role} className="flex items-center gap-1 pl-2 pr-1 py-0.5 bg-gray-100 border border-gray-200 rounded-lg text-xs text-gray-700">
+                      {role}
+                      <button onClick={() => removeRole(user, role)} className="hover:text-red-600 transition-colors" title={`${text.remove} ${role}`}>
+                        <XMarkIcon className="h-3 w-3" />
+                      </button>
+                    </span>
+                  ))}
+                  {user.roles.length === 0 && <span className="text-xs text-gray-400">{text.noRoles}</span>}
+                  {!isAddingRole && !user.isDeleted && available.length > 0 && (
+                    <button
+                      onClick={() => {
+                        setAddRoleFor(user.id);
+                        setSelectedRole(available[0] ?? "");
+                      }}
+                      className="flex items-center gap-1 px-2 py-0.5 bg-gray-50 hover:bg-gray-100 border border-gray-200 rounded-lg text-xs text-gray-500 hover:text-gray-800 transition"
+                    >
+                      <PlusIcon className="h-3 w-3" /> {text.addRole}
+                    </button>
+                  )}
+                </div>
+
+                {isAddingRole && (
+                  <div className="flex items-center gap-2">
+                    <select
+                      value={selectedRole}
+                      onChange={(e) => setSelectedRole(e.target.value)}
+                      aria-label={text.addRole}
+                      className="rounded-lg border border-gray-300 px-2 py-1 text-sm"
+                    >
+                      {available.map((r) => (
+                        <option key={r} value={r}>
+                          {r}
+                        </option>
+                      ))}
+                    </select>
+                    <button
+                      onClick={() => assignRole(user)}
+                      disabled={roleLoading}
+                      className="rounded-lg bg-gray-900 text-white text-xs px-3 py-1.5 hover:bg-gray-800 disabled:opacity-50 transition"
+                    >
+                      {roleLoading ? "…" : text.add}
+                    </button>
+                    <button onClick={() => setAddRoleFor(null)} className="rounded-lg border border-gray-300 text-gray-700 text-xs px-3 py-1.5 hover:bg-gray-50 transition">
+                      {text.cancel}
+                    </button>
+                  </div>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/admin/adminUsersPanelStrings.ts

@@ -0,0 +1,73 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The users panel's text. Pass the app's own language. The defaults are English. `{name}` and `{role}`
+ * are filled in where a text names them.
+ */
+export interface AdminUsersPanelStrings {
+  users: string;
+  showDeleted: string;
+  inviteUser: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  role: string;
+  sendInvite: string;
+  sending: string;
+  inviteHint: string;
+  loading: string;
+  /** The tag after a deleted user's name. */
+  deleted: string;
+  delete: string;
+  /** Before the role name on the button that takes a role away. */
+  remove: string;
+  noRoles: string;
+  addRole: string;
+  add: string;
+  cancel: string;
+  usersLoadFailed: string;
+  rolesLoadFailed: string;
+  roleAssigned: string;
+  roleAssignFailed: string;
+  roleRemoved: string;
+  roleRemoveFailed: string;
+  confirmDelete: string;
+  userDeleted: string;
+  userDeleteFailed: string;
+  inviteIncomplete: string;
+  inviteSent: string;
+  inviteFailed: string;
+}
+
+export const defaultAdminUsersPanelStrings: AdminUsersPanelStrings = {
+  users: "Users",
+  showDeleted: "Show deleted",
+  inviteUser: "Invite user",
+  firstName: "First name",
+  lastName: "Last name",
+  email: "Email",
+  role: "Role",
+  sendInvite: "Send invitation",
+  sending: "Sending…",
+  inviteHint: "The user gets an email with a code and sets a password on the forgotten password page.",
+  loading: "Loading…",
+  deleted: "deleted",
+  delete: "Delete",
+  remove: "Remove",
+  noRoles: "No roles",
+  addRole: "Add role",
+  add: "Add",
+  cancel: "Cancel",
+  usersLoadFailed: "Failed to load users",
+  rolesLoadFailed: "Failed to load roles",
+  roleAssigned: "Added {role} to {name}",
+  roleAssignFailed: "Failed to assign role",
+  roleRemoved: "Removed {role} from {name}",
+  roleRemoveFailed: "Failed to remove role",
+  confirmDelete: "Delete {name}? Their name, email and password are removed, and they cannot sign in again.",
+  userDeleted: "User deleted",
+  userDeleteFailed: "Failed to delete user",
+  inviteIncomplete: "Fill in the name and email",
+  inviteSent: "Invitation sent. The user gets a code to set a password.",
+  inviteFailed: "Failed to send the invitation",
+};

package/src/admin/index.ts

@@ -0,0 +1,6 @@
+export { AdminShell } from "./AdminShell";
+export type { AdminShellProps, AdminTab } from "./AdminShell";
+export { AdminUsersPanel } from "./AdminUsersPanel";
+export type { AdminUsersPanelProps } from "./AdminUsersPanel";
+export { defaultAdminUsersPanelStrings } from "./adminUsersPanelStrings";
+export type { AdminUsersPanelStrings } from "./adminUsersPanelStrings";

package/src/next-auth.d.ts

@@ -0,0 +1,24 @@
+// The session fields this package's auth options put on next-auth's session and token. An app loads
+// them with `import "@sjolystinnovation/app-kit/next-auth";` in one of its own .d.ts files.
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    user: { id: string; name: string; email: string; roles: string[] };
+    accessToken: string;
+    error?: string | undefined;
+    absoluteExpiresAt?: number;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    accessToken?: string;
+    refreshToken?: string;
+    refreshAt?: number;
+    loginAt?: number;
+    user?: { id: string; name: string; email: string; roles: string[] };
+    error?: string | undefined;
+  }
+}

package/src/styles.css

@@ -71,6 +71,24 @@
   --color-payment-secondary-hover-bg: var(--color-gray-200);
   --color-payment-secondary-text: var(--color-gray-700);
 
+  --text-auth-title: var(--text-2xl);
+  --text-auth-title--line-height: var(--text-2xl--line-height);
+  --font-weight-auth-title: var(--font-weight-black);
+  --color-auth-heading: var(--color-gray-900);
+  --color-auth-text: var(--color-gray-600);
+  --color-auth-note: var(--color-gray-600);
+  --color-auth-hint: var(--color-gray-500);
+  --color-auth-link: var(--color-gray-900);
+  --color-auth-link-hover: var(--color-gray-900);
+  --font-weight-auth-link: var(--font-weight-semibold);
+
+  --color-admin-title: var(--color-gray-900);
+  --color-admin-border: var(--color-gray-200);
+  --color-admin-tab: var(--color-gray-500);
+  --color-admin-tab-hover: var(--color-gray-900);
+  --color-admin-tab-active: var(--color-gray-900);
+  --color-admin-tab-indicator: var(--color-primary);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);

package/src/ui/LoginPage.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { authLinkClassName, authPageClassName, authTitleClassName } from "./authClasses";
+import { CredentialsForm } from "./CredentialsForm";
+import type { CredentialsFormStrings } from "./credentialsFormStrings";
+import { defaultLoginPageStrings, type LoginPageStrings } from "./loginPageStrings";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+export interface LoginPageProps {
+  /** Where a signed-in user goes. */
+  redirectTo: string;
+  /** The password reset page. */
+  resetHref: string;
+  /** The sign-up page. Without it the page has no register link. */
+  registerHref?: string | undefined;
+  strings?: TextOverrides<LoginPageStrings> | undefined;
+  /** The form's own text, passed to `CredentialsForm`. */
+  formStrings?: TextOverrides<CredentialsFormStrings> | undefined;
+  /** Replaces the page's outer spacing, such as when the page sits inside the app's own card. */
+  className?: string | undefined;
+}
+
+/**
+ * The sign-in page: a title, `CredentialsForm`, and links to reset the password and, when the app has
+ * one, to sign up. A sign-in goes to `redirectTo` and refreshes the page's server data.
+ */
+export function LoginPage({ redirectTo, resetHref, registerHref, strings, formStrings, className = authPageClassName }: LoginPageProps) {
+  const text = withDefaults(defaultLoginPageStrings, strings);
+  const router = useRouter();
+
+  return (
+    <div className={className}>
+      <h1 className={`${authTitleClassName} mb-6`}>{text.title}</h1>
+      <CredentialsForm
+        strings={formStrings}
+        onSignedIn={() => {
+          router.push(redirectTo);
+          router.refresh();
+        }}
+      />
+      <p className="mt-6 text-sm text-auth-text">
+        <Link href={resetHref} className={authLinkClassName}>{text.forgotPassword}</Link>
+      </p>
+      {registerHref && (
+        <p className="mt-2 text-sm text-auth-text">
+          {text.registerPrompt && <>{text.registerPrompt} </>}
+          <Link href={registerHref} className={authLinkClassName}>{text.register}</Link>
+        </p>
+      )}
+    </div>
+  );
+}

package/src/ui/ResetPasswordFlow.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import Link from "next/link";
+import { useState, type FormEvent } from "react";
+import { passwordProblems, type PasswordStrings } from "../validation/passwordRules";
+import { Alert } from "./Alert";
+import { authLinkClassName, authPageClassName, authTitleClassName } from "./authClasses";
+import { PasswordInput } from "./PasswordInput";
+import { defaultResetPasswordFlowStrings, type ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+import { TextInput } from "./TextInput";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+export interface ResetPasswordFlowProps {
+  /** Asks the API to email a reset code, such as `createUserService`'s `requestPasswordReset`. */
+  requestReset: (data: { email: string }) => Promise<unknown>;
+  /** Sets the new password with the code, such as `createUserService`'s `resetPassword`. */
+  reset: (data: { email: string; code: string; newPassword: string }) => Promise<{ message?: string } | unknown>;
+  /** Where the sign-in links go. */
+  loginHref: string;
+  /** From the emailed link. A code opens the flow on its last step. */
+  initialEmail?: string | undefined;
+  initialCode?: string | undefined;
+  strings?: TextOverrides<ResetPasswordFlowStrings> | undefined;
+  /** Replaces the page's outer spacing, such as when the flow sits inside the app's own card. */
+  className?: string | undefined;
+  /** The password rule messages, for the app's own language. */
+  passwordStrings?: TextOverrides<PasswordStrings> | undefined;
+}
+
+const button =
+  "w-full rounded-button bg-button-primary-bg text-button-primary-text font-semibold py-2.5 hover:brightness-95 disabled:opacity-60 transition";
+
+/**
+ * Password reset in two steps: the email asks for a code, then the code and a new password set it. The
+ * new password is checked against the API's rules before it is sent. A link with the email and code,
+ * such as an invite, opens on the second step.
+ */
+export function ResetPasswordFlow({
+  requestReset,
+  reset,
+  loginHref,
+  initialEmail = "",
+  initialCode = "",
+  strings,
+  className = authPageClassName,
+  passwordStrings,
+}: ResetPasswordFlowProps) {
+  const text = withDefaults(defaultResetPasswordFlowStrings, strings);
+  const [step, setStep] = useState<1 | 2>(initialCode ? 2 : 1);
+  const [email, setEmail] = useState(initialEmail);
+  const [code, setCode] = useState(initialCode);
+  const [newPassword, setNewPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [done, setDone] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const failure = (err: unknown) => (err instanceof Error && err.message ? err.message : text.somethingWentWrong);
+
+  const sendCode = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+    try {
+      await requestReset({ email });
+      setStep(2);
+    } catch (err) {
+      setError(failure(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const setPassword = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    const problems = passwordProblems(newPassword, passwordStrings);
+    if (problems.length > 0) {
+      setError(text.passwordInvalid ?? problems.join(" "));
+      return;
+    }
+    setLoading(true);
+    try {
+      const result = await reset({ email, code, newPassword });
+      const message = (result as { message?: unknown } | null | undefined)?.message;
+      setDone(text.done ?? (typeof message === "string" ? message : ""));
+    } catch (err) {
+      setError(failure(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className={className}>
+      <h1 className={`${authTitleClassName} mb-1`}>{text.title}</h1>
+      <p className="text-sm text-auth-text mb-6">
+        {text.signInPrompt && <>{text.signInPrompt} </>}
+        <Link href={loginHref} className={authLinkClassName}>{text.signIn}</Link>
+      </p>
+
+      {done !== null ? (
+        <Alert variant="success">
+          {done}
+          <Link href={loginHref} className={`block mt-3 ${authLinkClassName}`}>{text.backToSignIn}</Link>
+        </Alert>
+      ) : step === 1 ? (
+        <form onSubmit={sendCode} className="space-y-4">
+          {error && <Alert variant="error">{error}</Alert>}
+          {text.intro && <p className="text-sm text-auth-text">{text.intro}</p>}
+          <TextInput label={text.email} name="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+          <button type="submit" disabled={loading} className={button}>
+            {loading ? text.requestingCode : text.requestCode}
+          </button>
+        </form>
+      ) : (
+        <form onSubmit={setPassword} className="space-y-4">
+          {text.codeSent && <p className="text-sm text-auth-note">{text.codeSent}</p>}
+          {error && <Alert variant="error">{error}</Alert>}
+          <TextInput label={text.email} name="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+          <TextInput label={text.code} name="code" value={code} onChange={(e) => setCode(e.target.value)} required />
+          <PasswordInput label={text.newPassword} name="newPassword" value={newPassword} onChange={(e) => setNewPassword(e.target.value)} required />
+          {text.passwordHint && <p className="text-xs text-auth-hint">{text.passwordHint}</p>}
+          <button type="submit" disabled={loading} className={button}>
+            {loading ? text.settingPassword : text.setPassword}
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}

package/src/ui/authClasses.ts

@@ -0,0 +1,5 @@
+// The classes the sign-in and password reset pages share, drawn from the auth and button tokens.
+
+export const authPageClassName = "max-w-md mx-auto px-4 py-16";
+export const authTitleClassName = "text-auth-title font-auth-title text-auth-heading";
+export const authLinkClassName = "font-auth-link text-auth-link hover:text-auth-link-hover transition-colors";

package/src/ui/index.ts

@@ -8,10 +8,18 @@ export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsForm
 export type { CredentialsFormStrings } from "./credentialsFormStrings";
 export { ErrorState, defaultErrorStateStrings } from "./ErrorState";
 export type { ErrorStateProps, ErrorStateStrings } from "./ErrorState";
+export { LoginPage } from "./LoginPage";
+export type { LoginPageProps } from "./LoginPage";
+export { defaultLoginPageStrings } from "./loginPageStrings";
+export type { LoginPageStrings } from "./loginPageStrings";
 export { NotFoundState, defaultNotFoundStrings } from "./NotFoundState";
 export type { NotFoundStateProps, NotFoundStrings } from "./NotFoundState";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
+export { ResetPasswordFlow } from "./ResetPasswordFlow";
+export type { ResetPasswordFlowProps } from "./ResetPasswordFlow";
+export { defaultResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+export type { ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
 export { TextArea } from "./TextArea";
 export type { TextAreaProps } from "./TextArea";
 export { TextInput } from "./TextInput";

package/src/ui/loginPageStrings.ts

@@ -0,0 +1,17 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The sign-in page's text around the form. Pass the app's own language. The defaults are English. */
+export interface LoginPageStrings {
+  title: string;
+  forgotPassword: string;
+  /** Shown before the register link, such as "No account?". Null leaves it out. */
+  registerPrompt: string | null;
+  register: string;
+}
+
+export const defaultLoginPageStrings: LoginPageStrings = {
+  title: "Sign in",
+  forgotPassword: "Forgot your password?",
+  registerPrompt: "No account?",
+  register: "Create one",
+};

package/src/ui/resetPasswordFlowStrings.ts

@@ -0,0 +1,52 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The reset flow's text. Pass the app's own language. The defaults are English. A text that is null
+ * is left out of the page.
+ */
+export interface ResetPasswordFlowStrings {
+  title: string;
+  /** Shown before the sign-in link under the title, such as "Remembered it?". */
+  signInPrompt: string | null;
+  signIn: string;
+  /** The link back to sign-in once the password is set. */
+  backToSignIn: string;
+  /** Shown above the email field on the first step. */
+  intro: string | null;
+  /** Shown at the top of the second step, once a code is on its way. */
+  codeSent: string | null;
+  email: string;
+  code: string;
+  newPassword: string;
+  /** Shown under the new password field. */
+  passwordHint: string | null;
+  requestCode: string;
+  requestingCode: string;
+  setPassword: string;
+  settingPassword: string;
+  /** Shown when the password is set. Null shows the API's own message, or only the link when it sends none. */
+  done: string | null;
+  /** Shown for a password the rules refuse. Null lists each rule it breaks. */
+  passwordInvalid: string | null;
+  somethingWentWrong: string;
+}
+
+export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
+  title: "Reset password",
+  signInPrompt: "Remembered it?",
+  signIn: "Sign in",
+  backToSignIn: "Back to sign in →",
+  intro: null,
+  codeSent: "Check your email for the reset code.",
+  email: "Email",
+  code: "Reset code",
+  newPassword: "New password",
+  passwordHint: null,
+  requestCode: "Send reset code",
+  requestingCode: "Sending…",
+  setPassword: "Reset password",
+  settingPassword: "Resetting…",
+  done: null,
+  passwordInvalid: null,
+  somethingWentWrong: "Something went wrong",
+};

package/src/validation/index.ts

@@ -1,4 +1,4 @@
-export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordSchema } from "./password";
+export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordProblems, passwordSchema } from "./password";
 export type { PasswordStrings } from "./password";
 export { zodFieldErrors } from "./fieldErrors";
 export type { IssueMessage } from "./fieldErrors";

package/src/validation/password.ts

@@ -1,23 +1,9 @@
 import { z } from "zod";
 import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { PASSWORD_MIN_LENGTH, defaultPasswordStrings, type PasswordStrings } from "./passwordRules";
 
-/** The fewest characters a password may have. */
-export const PASSWORD_MIN_LENGTH = 8;
-
-/** The message for each password rule that fails. */
-export interface PasswordStrings {
-  tooShort: string;
-  lowercase: string;
-  uppercase: string;
-  digit: string;
-}
-
-export const defaultPasswordStrings: PasswordStrings = {
-  tooShort: `Use at least ${PASSWORD_MIN_LENGTH} characters.`,
-  lowercase: "Include a lowercase letter from a to z.",
-  uppercase: "Include an uppercase letter from A to Z.",
-  digit: "Include a digit from 0 to 9.",
-};
+export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordProblems } from "./passwordRules";
+export type { PasswordStrings } from "./passwordRules";
 
 /**
  * A zod schema for a new password, with the rules the APIs enforce through ASP.NET Identity. Identity

package/src/validation/passwordRules.ts

@@ -0,0 +1,35 @@
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+
+// No zod here, so the reset form in /ui can check a password without the optional zod peer.
+
+/** The fewest characters a password may have. */
+export const PASSWORD_MIN_LENGTH = 8;
+
+/** The message for each password rule that fails. */
+export interface PasswordStrings {
+  tooShort: string;
+  lowercase: string;
+  uppercase: string;
+  digit: string;
+}
+
+export const defaultPasswordStrings: PasswordStrings = {
+  tooShort: `Use at least ${PASSWORD_MIN_LENGTH} characters.`,
+  lowercase: "Include a lowercase letter from a to z.",
+  uppercase: "Include an uppercase letter from A to Z.",
+  digit: "Include a digit from 0 to 9.",
+};
+
+/**
+ * The message of every password rule the password breaks, in the order `passwordSchema` checks them.
+ * An empty list means the APIs accept it.
+ */
+export function passwordProblems(password: string, strings?: TextOverrides<PasswordStrings>): string[] {
+  const text = withDefaults(defaultPasswordStrings, strings);
+  const problems: string[] = [];
+  if (password.length < PASSWORD_MIN_LENGTH) problems.push(text.tooShort);
+  if (!/[a-z]/.test(password)) problems.push(text.lowercase);
+  if (!/[A-Z]/.test(password)) problems.push(text.uppercase);
+  if (!/[0-9]/.test(password)) problems.push(text.digit);
+  return problems;
+}