@sjolystinnovation/app-kit 1.0.1 → 1.0.2

package/README.md

@@ -20,6 +20,7 @@ security headers. Each part is a separate entry point, so an app imports only wh
 - [`auth`](#sjolystinnovationapp-kitauth) and [`next-auth`](#sjolystinnovationapp-kitnext-auth)
 - [`session`](#sjolystinnovationapp-kitsession) and [`session/react`](#sjolystinnovationapp-kitsessionreact)
 - [`api`](#sjolystinnovationapp-kitapi) and [`server`](#sjolystinnovationapp-kitserver)
+- [`company`](#sjolystinnovationapp-kitcompany)
 - [`forms`](#sjolystinnovationapp-kitforms), [`toast`](#sjolystinnovationapp-kittoast), and [`validation`](#sjolystinnovationapp-kitvalidation)
 - [`ui`](#sjolystinnovationapp-kitui)
 - [`admin`](#sjolystinnovationapp-kitadmin)
@@ -51,12 +52,12 @@ ones the entry points you import need:
 | `react-markdown` 10, `remark-gfm` 4, and `rehype-sanitize` 6 | `markdown`, `legal`, and `sections` |
 | `vitest` 5 | `testing` |
 
-Every other entry point, such as the root entry, `next-config`, `seo`, `forms`, `legal`, or
-`locales/nb`, works without `@heroicons/react`. Install a single copy of `sonner`, because two
+Every other entry point, such as the root entry, `next-config`, `seo`, `forms`, `legal`, `company`,
+or `locales/nb`, works without `@heroicons/react`. Install a single copy of `sonner`, because two
 copies keep two separate toast stores. `jsonwebtoken` comes with the package.
 
-For a site without sign-in, which uses only entries such as the root entry, `ui`, `seo`, or
-`next-config`:
+For a site without sign-in, which uses only entries such as the root entry, `ui`, `seo`, `company`,
+or `next-config`:
 
 ```sh
 npm install @sjolystinnovation/app-kit next react react-dom @heroicons/react
@@ -101,6 +102,7 @@ The components use Tailwind CSS 4. Import the package's stylesheet after Tailwin
 | [`@sjolystinnovation/app-kit/session`](#sjolystinnovationapp-kitsession) | Session error codes and the re-sign-in prompt flag. Safe on the server. |
 | [`@sjolystinnovation/app-kit/session/react`](#sjolystinnovationapp-kitsessionreact) | The session provider, gates, expiry guard, sign-in form, and login page. |
 | [`@sjolystinnovation/app-kit/api`](#sjolystinnovationapp-kitapi) | The axios clients, error messages, field errors, and services for the API's endpoints. |
+| [`@sjolystinnovation/app-kit/company`](#sjolystinnovationapp-kitcompany) | `mergeCompanyInfo`, `formatOrgNumber`, and the `CompanyInfo` type. Imports no peer dependency. |
 | [`@sjolystinnovation/app-kit/server`](#sjolystinnovationapp-kitserver) | Cached public GETs and the revalidate route. Server only. |
 | [`@sjolystinnovation/app-kit/forms`](#sjolystinnovationapp-kitforms) | `useFormDraft`, which keeps form values in `localStorage`. |
 | [`@sjolystinnovation/app-kit/toast`](#sjolystinnovationapp-kittoast) | sonner's `toast`, quiet on errors while the re-sign-in prompt is open. |
@@ -615,24 +617,8 @@ The package also exports the response types `UserProfile`, `AdminUser`, `SiteSet
 
 ### `mergeCompanyInfo` and `formatOrgNumber`
 
-`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
-import { formatOrgNumber, mergeCompanyInfo, type CompanyInfo } from "@sjolystinnovation/app-kit/api";
-
-export const getCompanyInfo = async () =>
-  mergeCompanyInfo(await publicGetOptional<CompanyInfo>("/company"), { name: "Example AS" });
-
-export const orgLine = (company: CompanyInfo) => formatOrgNumber(company);
-```
-
-The `CompanyInfo` and `CompanyFallback` types describe the two shapes.
+`./api` also exports the [`company`](#sjolystinnovationapp-kitcompany) helpers and types, so
+existing imports keep working.
 
 ### `defineRevalidateTargets`
 
@@ -661,7 +647,8 @@ The package also exports the `RevalidateTargetsConfig` and `RevalidateTargetPath
 
 ## `@sjolystinnovation/app-kit/server`
 
-For server components and route handlers only. It imports `next/cache` and `next/server`.
+For server components and route handlers only. It imports `next/cache`, `next/constants`, and
+`next/server`.
 
 ### `createPublicApi`
 
@@ -688,6 +675,19 @@ export const { publicGet, publicGetOptional, publicGetWithMeta } = createPublicA
 );
 ```
 
+`next build` prerenders the pages that call these, so by default a build fails when the API is down.
+Set `nullOnFailureDuringBuild: true` to build those pages empty instead. During the build, an
+unreachable API or an error answer gives `null` and logs a warning with the path and status, so the
+empty page shows in the build log. ISR fills the page on its first revalidate once the API answers.
+At runtime a failure still throws, so a working page is never replaced by an empty one.
+
+```ts
+export const { publicGet, publicGetOptional, publicGetWithMeta } = createPublicApi(
+  requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+  { nullOnFailureDuringBuild: true },
+);
+```
+
 The package also exports the `PublicApiOptions`, `PublicGetOptions`, and `PublicResponse` types.
 
 ### `createRevalidateRoute`
@@ -714,6 +714,30 @@ export const POST = createRevalidateRoute({ targets: TARGET_PATHS, role: "Admin"
 `{ builds: ["/builds", "/builds/[slug]", "/sitemap.xml"] }`. The package also exports the
 `RevalidateRouteOptions` type.
 
+## `@sjolystinnovation/app-kit/company`
+
+The company details for public pages, such as a footer or a contact page. The entry imports no
+peer dependency, so a static site without axios or next-auth can use it.
+
+`mergeCompanyInfo(data, fallback)` gives the company details: 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
+import { formatOrgNumber, mergeCompanyInfo, type CompanyInfo } from "@sjolystinnovation/app-kit/company";
+
+export const getCompanyInfo = async () =>
+  mergeCompanyInfo(await publicGetOptional<CompanyInfo>("/company"), { name: "Example AS" });
+
+export const orgLine = (company: CompanyInfo) => formatOrgNumber(company);
+```
+
+The `CompanyInfo` and `CompanyFallback` types describe the two shapes.
+
 ## `@sjolystinnovation/app-kit/forms`
 
 `useFormDraft(config, options)` keeps a form's values in `localStorage`, so a sign-out, reload, or
@@ -981,7 +1005,7 @@ const params = useSearchParams();
 | `loginHref` | `string` | Where the sign-in links go. |
 | `initialEmail`, `initialCode` | `string` | The values 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. The English defaults include an intro, the password rules as `passwordHint`, and a `done` text. Set `signInPrompt`, `intro`, `codeSent`, or `passwordHint` to `null` to leave it 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. `validation` and `errors` may name only some codes. |
+| `strings` | `TextOverrides<ResetPasswordFlowStrings>` | The page's text. The English defaults include an intro, the password rules as `passwordHint`, and a `done` text. Set `signInPrompt`, `intro`, `codeSent`, or `passwordHint` to `null` to leave it out. The hint gives way to the new password's error while one shows, since the default `passwordInvalid` repeats the rules. `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. `validation` and `errors` may name only some codes. |
 | `passwordStrings` | `TextOverrides<PasswordStrings>` | The rule messages, in the app's language. |
 
 A password that breaks the rules is marked under the new password field, without a call to the API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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",
@@ -27,6 +27,7 @@
       "types": "./src/next-auth.d.ts"
     },
     "./api": "./src/api/index.ts",
+    "./company": "./src/company/index.ts",
     "./server": "./src/server/index.ts",
     "./ui": "./src/ui/index.ts",
     "./admin": "./src/admin/index.ts",
@@ -111,7 +112,7 @@
     "@vitejs/plugin-react": "^6.1.2",
     "axios": "^1.20.0",
     "jsdom": "^30.1.1",
-    "next": "^16.3.6",
+    "next": "^16.4.0",
     "next-auth": "^4.24.15",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",

package/src/api/index.ts

@@ -1,7 +1,7 @@
 export { apiErrorCode } from "./apiErrorCode";
 export { apiFieldErrors } from "./apiFieldErrors";
-export { formatOrgNumber, mergeCompanyInfo } from "./company";
-export type { CompanyFallback, CompanyInfo } from "./company";
+export { formatOrgNumber, mergeCompanyInfo } from "../company";
+export type { CompanyFallback, CompanyInfo } from "../company";
 export { createApiClient } from "./createApiClient";
 export { formatApiError } from "./formatApiError";
 export type { StatusMessages } from "./formatApiError";

package/src/{api → company}/company.ts

@@ -1,3 +1,5 @@
+// Imports nothing, so the company entry works without axios or next-auth.
+
 /** The business as SjolystInnovation.AppKit.SiteSettings's public `/company` endpoint describes it. */
 export interface CompanyInfo {
   name: string;

package/src/company/index.ts

@@ -0,0 +1,2 @@
+export { formatOrgNumber, mergeCompanyInfo } from "./company";
+export type { CompanyFallback, CompanyInfo } from "./company";

package/src/server/publicApi.ts

@@ -1,3 +1,5 @@
+import { PHASE_PRODUCTION_BUILD } from "next/constants";
+
 /** A response from `publicGetWithMeta`, with its `Last-Modified` date. */
 export interface PublicResponse<T> {
   data: T;
@@ -15,6 +17,12 @@ export interface PublicGetOptions {
 export interface PublicApiOptions {
   /** The seconds a cached response stays fresh. Defaults to `60`. */
   revalidate?: number | undefined;
+  /**
+   * Whether a failed fetch gives `null` with a warning, in place of `PublicApiError`, while
+   * `next build` prerenders. The page then builds empty and ISR fills it on its first revalidate.
+   * Outside the build a failure still throws. Defaults to `false`.
+   */
+  nullOnFailureDuringBuild?: boolean | undefined;
 }
 
 /** Thrown when the API could not be reached, or answered with no usable content. */
@@ -43,7 +51,8 @@ function lastModifiedOf(response: Response): Date | null {
  * handlers.
  *
  * A 404 returns null. An unreachable or failing API throws `PublicApiError`, so a failed fetch is
- * never cached as an empty page in place of a working one.
+ * never cached as an empty page in place of a working one. With `nullOnFailureDuringBuild`, a
+ * failure during `next build` gives null instead, so the build does not depend on the API.
  */
 export function createPublicApi(baseUrl: string, options: PublicApiOptions = {}) {
   if (!baseUrl) {
@@ -68,6 +77,19 @@ export function createPublicApi(baseUrl: string, options: PublicApiOptions = {})
   }
 
   async function publicGetWithMeta<T>(path: string, opts: PublicGetOptions = {}): Promise<PublicResponse<T> | null> {
+    try {
+      return await fetchWithMeta<T>(path, opts);
+    } catch (error) {
+      // Read at call time, since next build sets the phase for the process that prerenders.
+      if (!options.nullOnFailureDuringBuild || !(error instanceof PublicApiError) || process.env.NEXT_PHASE !== PHASE_PRODUCTION_BUILD) {
+        throw error;
+      }
+      console.warn(`${error.message} during next build. The page builds without it until it revalidates.`);
+      return null;
+    }
+  }
+
+  async function fetchWithMeta<T>(path: string, opts: PublicGetOptions): Promise<PublicResponse<T> | null> {
     const url = urlFor(path);
     if (url == null) return null;
     let response: Response;

package/src/ui/ResetPasswordFlow.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import Link from "next/link";
-import { useState, type FormEvent } from "react";
+import { useId, useState, type FormEvent } from "react";
 import { errorText, fieldErrorTexts } from "../api/fieldErrorText";
 import { passwordProblems, type PasswordStrings } from "../validation/passwordRules";
 import { Alert } from "./Alert";
@@ -76,6 +76,7 @@ export function ResetPasswordFlow({
   const [fieldErrors, setFieldErrors] = useState<Record<string, string[]>>({});
   const [done, setDone] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
+  const hintId = `${useId()}-hint`;
 
   // Field errors go under the fields this step shows, and the message holds the rest.
   const fail = (err: unknown, shown: readonly string[]) => {
@@ -91,6 +92,10 @@ export function ResetPasswordFlow({
   };
 
   const fieldError = (field: string) => fieldErrors[field]?.join(" ");
+  // The error under the new password says what to fix, and by default it holds the rules, so the
+  // hint steps aside while it shows.
+  const passwordError = fieldError("newPassword");
+  const showHint = Boolean(text.passwordHint) && !passwordError;
 
   const sendCode = async (event: FormEvent) => {
     event.preventDefault();
@@ -159,12 +164,13 @@ export function ResetPasswordFlow({
           <PasswordInput
             label={text.newPassword}
             name="newPassword"
-            error={fieldError("newPassword")}
+            error={passwordError}
+            aria-describedby={showHint ? hintId : undefined}
             value={newPassword}
             onChange={(e) => setNewPassword(e.target.value)}
             required
           />
-          {text.passwordHint && <p className="text-xs text-auth-hint">{text.passwordHint}</p>}
+          {showHint && <p id={hintId} className="text-xs text-auth-hint">{text.passwordHint}</p>}
           <button type="submit" disabled={loading} className={button}>
             {loading ? text.settingPassword : text.setPassword}
           </button>

package/src/ui/resetPasswordFlowStrings.ts

@@ -50,7 +50,7 @@ export interface ResetPasswordFlowStrings {
   email: string;
   code: string;
   newPassword: string;
-  /** The text shown under the new password field. */
+  /** The text shown under the new password field. It gives way to the field's error while one shows. */
   passwordHint: string | null;
   requestCode: string;
   requestingCode: string;