@sjolystinnovation/app-kit 0.19.0 → 0.21.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
@@ -260,6 +243,17 @@ export const getRecipe = (id: number) =>
   request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
 ```
 
+`mergeCompanyInfo(data, fallback)` gives the company details for public pages: the API's
+`/company` answer, with the app's own value for each field it left blank or could not give. Only
+the fallback's name is required. The legal name falls back to the name, and VAT to not registered.
+`formatOrgNumber({ orgNumber, vatRegistered })` adds ` MVA` once the business is VAT registered,
+and gives an empty string without a number.
+
+```ts
+// src/lib/companyInfo.ts
+export const getCompanyInfo = async () => mergeCompanyInfo(await publicGetOptional<CompanyInfo>("/company"), COMPANY);
+```
+
 `requestRevalidate(target, endpoint?)` asks the app's revalidate route to purge the pages behind
 `target`, so an edit shows at once. It posts to `/api/revalidate` unless `endpoint` says otherwise.
 It never throws. On failure the pages' own revalidate window is the fallback.
@@ -338,6 +332,26 @@ export const POST = createRevalidateRoute({
 });
 ```
 
+`defineRevalidateTargets({ locales, targets })`, from `@sjolystinnovation/app-kit/api`, keeps the
+targets in one file that both sides import. `pages` are below each locale segment and `root` paths
+are not. It returns `targets` for fetch tags, `paths` for the route, and `revalidate(target)` for
+the admin services.
+
+```ts
+// src/lib/cacheTags.ts
+export const { targets: REVALIDATE_TARGETS, paths: TARGET_PATHS, revalidate: revalidateTarget } = defineRevalidateTargets({
+  locales: LOCALES,
+  targets: {
+    legal: { pages: ["/terms", "/privacy", "/cookies"], root: ["/sitemap.xml"] },
+    // Every page renders branding through the layout, so its tag reaches them all.
+    branding: {},
+  },
+});
+
+// src/app/api/revalidate/route.ts
+export const POST = createRevalidateRoute({ targets: TARGET_PATHS, role: ADMIN_ROLE });
+```
+
 ### `@sjolystinnovation/app-kit/next-config`
 
 For `next.config.ts`. It imports nothing but Next's types, so Next loads it with no build step.
@@ -448,10 +462,14 @@ The site gives:
 - `pageMetadata({ locale, path, title, description, images })` for a page: the canonical URL,
   hreflang, and Open Graph with the locale's share image unless `images` is given.
 - `localeEntries(path, { locales, lastModified })` for `sitemap.ts`: one entry per locale, each
-  listing the others. `lastModified` is left out when unknown.
+  listing the others. `lastModified` is left out when unknown. A site without locales gets one
+  entry per page.
+- `forEachLocale(load)` runs `load` for every locale at once and keys the results by locale.
+- `legalEntries({ keys, updatedAt })` gives the legal pages' entries, `/terms`, `/privacy` and
+  `/cookies` unless `keys` says otherwise, each dated by the timestamp `updatedAt` returns for it.
 - `robots({ privatePaths, privateRootPaths, indexable })` for `robots.ts`. The private paths are
   disallowed under every locale segment. A deployment that is not production disallows everything.
-- `organizationNode(company, { type, country, image, logo })`, `webSiteNode(locale)`,
+- `organizationNode(company, { type, sameAs, country, image, logo })`, `webSiteNode(locale)`,
   `breadcrumbNode(crumbs, pageUrl)`, `itemListNode(paths, pageUrl)`, `siteId(fragment)` and `ids`
   for structured data.
 
@@ -460,6 +478,15 @@ The site gives:
 export const dynamic = "force-dynamic";
 export default () => site.robots({ privatePaths: ["/admin", "/login"], privateRootPaths: ["/api/"] });
 
+// src/app/sitemap.ts
+export const revalidate = 3600;
+export default async () => [
+  ...site.localeEntries(""),
+  ...(await site.legalEntries({
+    updatedAt: async (key, locale) => (await publicGet<LegalPage>(`/content/legal/${key}?locale=${locale}`))?.updatedAt,
+  })),
+];
+
 // in a page
 <JsonLd nodes={[site.organizationNode(company), site.webSiteNode(locale)]} />
 ```
@@ -467,8 +494,8 @@ export default () => site.robots({ privatePaths: ["/admin", "/login"], privateRo
 `isIndexableEnvironment()` reads `SITE_ENV`. `prod`, `production` and unset or blank count as
 production, so a missing variable never deindexes the live site. `robots.ts` needs
 `dynamic = "force-dynamic"`, so it reads the variable per request. The package also exports
-`JsonLd`, `serializeGraph`, `ref`, `NOINDEX`, `SHARE_IMAGE_SIZE`, `normalizePath`, `latest` and
-`parseTimestamp`.
+`JsonLd`, `serializeGraph`, `ref`, `NOINDEX`, `LEGAL_PAGE_KEYS`, `SHARE_IMAGE_SIZE`,
+`normalizePath`, `latest` and `parseTimestamp`.
 
 ### `@sjolystinnovation/app-kit/seo/og`
 
@@ -594,6 +621,110 @@ if (loading) return <Spinner />;
 
 `formatNok(ore)` formats øre as kroner, such as `NOK 373,75`.
 
+### `@sjolystinnovation/app-kit/admin`
+
+`CompanySettingsForm` is the admin form for the business details the public pages show, saved
+through `createSettingsService`. Its children show below the form once the settings have loaded,
+such as the `BrandingManager`. `strings` holds every label, hint and message, English by default.
+
+```tsx
+<CompanySettingsForm service={SettingsService} strings={dict.companySettings}>
+  <BrandingManager save={BrandingService.update} />
+</CompanySettingsForm>
+```
+
+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>
+  );
+}
+```
+
+`StatHistoryChart` draws the admin stats over time: a line per series, a scale from zero to the
+highest value shown, and legend buttons that hide and show each line. `data` is one row per day,
+oldest first, with `date` as `YYYY-MM-DD`. A missing value counts as zero. Each series names the
+field it plots and its label, and takes the next colour in `STAT_SERIES_COLORS` unless it has its
+own. `strings` holds `empty`, shown when there are no days, and `chart`, the accessible name.
+
+```tsx
+<StatHistoryChart
+  data={history}
+  series={[
+    { key: "totalUsers", label: dict.stats.users },
+    { key: "contentImages", label: dict.stats.images },
+  ]}
+  strings={{ empty: dict.admin.noHistory, chart: dict.admin.overTime }}
+/>
+```
+
+`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. |
+
+`LegalPagesEditor` edits the legal pages one page and one locale at a time, through
+`createLegalService`. A locale tab whose page has no content yet gets a dot. `LocaleTabs` is the
+same tab bar on its own, for other translated forms.
+
+```tsx
+<LegalPagesEditor
+  service={LegalService}
+  keys={LEGAL_PAGE_KEYS}
+  keyLabels={{ terms: dict.footer.terms, privacy: dict.footer.privacy, cookies: dict.footer.cookies }}
+  locales={LOCALES}
+  localeLabels={LOCALE_LABELS}
+  strings={dict.legalEditor}
+/>
+```
+
+### `@sjolystinnovation/app-kit/legal`
+
+`LegalPageView` renders a terms, privacy or cookies page as an admin wrote it: the title, the date
+it last changed in `dateLocale`, and the Markdown body. With no page it shows `title` and says the
+page is missing. It is a server component and needs the same peers as `markdown`. The route file
+stays in the app, since Next reads `revalidate` and the metadata from it.
+
+```tsx
+// src/app/[locale]/terms/page.tsx
+export const revalidate = 3600;
+
+export default async function TermsPage({ params }: { params: Promise<{ locale: Locale }> }) {
+  const { locale } = await params;
+  const page = await publicGet<LegalPage>(`/content/legal/terms?locale=${locale}`, { tags: [REVALIDATE_TARGETS.legal] });
+  return <LegalPageView page={page} title={dict.footer.terms} homeHref={`/${locale}`} dateLocale="nb-NO" strings={dict.legal} />;
+}
+```
+
 ### `@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 +970,25 @@ 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
@@ -1068,6 +1218,39 @@ const parsed = contactSchema.safeParse(form);
 if (!parsed.success) setErrors(zodFieldErrors(parsed.error, { message: (issue) => issueMessage(issue, dict) }));
 ```
 
+### `@sjolystinnovation/app-kit/testing`
+
+Test doubles for the modules every app's tests mock: `next-auth/react`, `next/navigation`, `sonner`
+or `@sjolystinnovation/app-kit/toast`, and the app's axios instance. vitest hoists `vi.mock` above
+the file's imports, so the factory imports the helpers itself. The test imports the same module to
+set the state and read the spies. The state lasts for the whole file, so call `resetTestMocks`
+before each test. It needs vitest 5, as an optional peer dependency.
+
+```tsx
+import { makeSession, navigation, resetTestMocks, setSession } from "@sjolystinnovation/app-kit/testing";
+
+vi.mock("next-auth/react", async () => (await import("@sjolystinnovation/app-kit/testing")).nextAuthMock());
+vi.mock("next/navigation", async () => (await import("@sjolystinnovation/app-kit/testing")).nextNavigationMock());
+
+beforeEach(resetTestMocks);
+
+it("sends a user without the role away", () => {
+  navigation.pathname = "/no/admin";
+  setSession(makeSession({ roles: [] }));
+  render(<AdminLayout><p>admin work</p></AdminLayout>);
+  expect(navigation.router.replace).toHaveBeenCalledWith("/no");
+});
+```
+
+- `setSession(session | null | "loading")` and `makeSession({ roles, ...overrides })` set what
+  `useSession` returns. `auth.signIn`, `auth.signOut` and `auth.getSession` are the spies behind
+  next-auth's calls.
+- `navigation.pathname`, `navigation.searchParams` and `navigation.router` feed `usePathname`,
+  `useSearchParams` and `useRouter`.
+- `toastMock()` records every toast in `toastSpies`.
+- `axiosInstanceMock()` is a module whose default export is `axiosSpies`, for
+  `vi.mock("@/services/axiosInstance", ...)`.
+
 ## Theming
 
 The components draw every colour, corner radius and label size from theme variables with a light
@@ -1114,7 +1297,7 @@ 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 `ResetPasswordFlow` |
+| `--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 |
@@ -1122,6 +1305,13 @@ selector such as `.dark` for a scoped theme:
 | `--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 |
+| `--color-chart-grid` | gray 200, the scale lines of `StatHistoryChart` |
+| `--color-chart-label` | gray 400, the chart's numbers and dates |
 | `--radius-button` | `var(--radius-lg)` |
 | `--color-button-primary-bg` | `var(--color-primary)` |
 | `--color-button-primary-text` | `var(--color-primary-foreground)` |
@@ -1158,15 +1348,19 @@ with it and has to set the ones it uses itself.
 
 ## Requirements
 
-- Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
-  app installs itself.
+- Next.js 16 and React 19, as peer dependencies the app installs itself.
+- For the root entry, `auth`, `api`, `server`, `session/react`, `ui` and `admin`: next-auth 4.24
+  or later and axios 1.20 or later, as optional peer dependencies. A site without sign-in, which
+  uses only entries such as `seo`, `next-config`, `markdown`, `toast` or `validation`, leaves them
+  out.
 - For `@sjolystinnovation/app-kit/validation`: zod 4, as an optional peer dependency.
+- For `@sjolystinnovation/app-kit/testing`: vitest 5, as an optional peer dependency.
 - 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.19.0",
+  "version": "0.21.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,18 +20,24 @@
     "./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",
     "./markdown": "./src/markdown/index.ts",
+    "./legal": "./src/legal/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",
+    "./testing": "./src/testing/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -56,12 +62,22 @@
     "rehype-sanitize": "^6",
     "remark-gfm": "^4",
     "sonner": "^2",
+    "vitest": "^5",
     "zod": "^4"
   },
   "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    },
+    "next-auth": {
+      "optional": true
+    },
     "sonner": {
       "optional": true
     },
+    "vitest": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     },

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)} />;
+}