@sjolystinnovation/app-kit 0.9.0 → 0.11.0

package/README.md

@@ -309,6 +309,45 @@ export const POST = createRevalidateRoute({
 });
 ```
 
+### `@sjolystinnovation/app-kit/next-config`
+
+For `next.config.ts`. It imports nothing but Next's types, so Next loads it with no build step.
+
+`defineAppConfig(options, extra?)` gives the config every app shares: the standalone build, app-kit
+in `transpilePackages`, no `X-Powered-By`, `expireTime` of five minutes, image qualities 75 and 100,
+the incremental cache in memory, and the security headers on every page. `extra` is merged over it,
+with `transpilePackages`, `images`, `headers` and `rewrites` combined rather than replaced.
+
+```ts
+// next.config.ts
+import { defineAppConfig } from "@sjolystinnovation/app-kit/next-config";
+
+export default defineAppConfig({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL,
+  dev: process.env.NODE_ENV !== "production",
+  contentImages: true,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string \| undefined` | The API URL. Its origin is allowed in `connect-src`. |
+| `dev` | `boolean` | Development builds also allow `'unsafe-eval'`, which hot reload needs. |
+| `websocket` | `boolean` | Also allow `ws:` and `wss:` to the API origin, for SignalR. |
+| `imgFromApi` | `boolean` | Also allow images from the API origin. Not needed with `contentImages`. |
+| `contentImages` | `boolean` | Proxy `/content-images/*` to the API's `/content-images/*`, so the browser never contacts the API host. |
+| `connectSrc`, `imgSrc` | `string[]` | Extra sources for those directives. |
+| `frameSrc`, `objectSrc` | `string[]` | Sources for those directives. Both default to `'none'`. |
+| `pathHeaders` | `{ source, headers }[]` | Headers for particular paths, such as a file download. They come after the page headers and replace a page header of the same name. Every path keeps the rest. |
+| `permissionsPolicy` | `string` | Replaces `camera=(), microphone=(), geolocation=()`. |
+| `expireTime` | `number` | Seconds a cache may serve a stale page. Defaults to 300. Next's default is a year. |
+| `isrFlushToDisk` | `boolean` | Write revalidated pages to disk. Off by default, for a read-only root filesystem. |
+
+The pieces are exported too: `securityHeaders(options)`, `contentSecurityPolicy(options)`,
+`contentImagesRewrite(apiUrl, { source?, upstreamPath? })`, `apiOrigin(apiUrl)` and
+`apiBaseUrl(apiUrl)`. Scripts allow `'unsafe-inline'`, since a nonce would make every statically
+rendered page dynamic.
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
@@ -621,6 +660,70 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables. A clashing class wins or loses by the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
+### `ContentImage`
+
+From `@sjolystinnovation/app-kit/ui`. An uploaded image from the content API, as a plain `<img>`
+with a `srcset` of the widths the API serves. It goes through the content images rewrite from
+`defineAppConfig({ contentImages: true })`, so the browser never contacts the API host. It works in
+a server component.
+
+```tsx
+<ContentImage imageId={post.imageId} alt={post.title} sizes="(min-width: 768px) 50vw, 100vw" />
+<ContentImage imageId={hero.imageId} fallbackSrc="/hero.jpg" alt="" sizes="100vw" priority aria-hidden />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `imageId` | `string \| null` | | Uploaded image id. Null or empty shows `fallbackSrc` as it is, with no `srcset`. |
+| `alt` | `string` | | Empty for a decorative image. |
+| `sizes` | `string` | | Widths the image is shown at. Required, since a browser assumes `100vw` without it. |
+| `fallbackSrc` | `string` | | A static path for when there is no uploaded image. With neither, nothing renders. |
+| `priority` | `boolean` | `false` | For the one image visible without scrolling. It loads eagerly, at high priority. |
+| `width`, `height` | `number` | | Intrinsic size, to reserve space where the layout fixes no ratio. |
+| `base` | `string` | `"/content-images"` | Path the content images rewrite serves. |
+| `widths` | `number[]` | `CONTENT_IMAGE_WIDTHS` | Widths in the `srcset`. |
+| `className` | `string` | | Classes on the `<img>`. |
+
+`contentImagePath(id, base?)` and `contentImageSrcSet(id, widths?, base?)` build the same URLs for
+other uses, such as a CSS background or an Open Graph image.
+
+### `ErrorState`
+
+From `@sjolystinnovation/app-kit/ui`. What an `error.tsx` shows. It is a client component, as an
+error boundary has to be.
+
+```tsx
+"use client";
+
+export default function Error({ reset }: { error: Error; reset: () => void }) {
+  return <ErrorState reset={reset} homeHref="/" />;
+}
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `reset` | `() => void` | The `reset` Next passes to `error.tsx`. The try again button calls it. |
+| `homeHref` | `string` | Where the front page link goes, such as `/` or `/en`. |
+| `strings` | `TextOverrides<ErrorStateStrings>` | `title`, `body`, `tryAgain` and `home`. |
+| `className` | `string` | Classes for placing it, on the outer element. |
+
+The error itself is never shown.
+
+### `NotFoundState`
+
+From `@sjolystinnovation/app-kit/ui`. What a `not-found.tsx` shows: a large code, the message as
+the page's heading, and a link home. It works in a server component.
+
+```tsx
+<NotFoundState homeHref="/no" strings={{ body: dict.notFound, home: dict.toFrontPage }} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `homeHref` | `string` | Where the home link goes. |
+| `strings` | `TextOverrides<NotFoundStrings>` | `code`, `body` and `home`. |
+| `className` | `string` | Classes for placing it, on the outer element. |
+
 ### `PasswordInput`
 
 A labelled password field with a button that shows and hides the value. It also takes the other
@@ -728,6 +831,11 @@ selector such as `.dark` for a scoped theme:
 | `--color-dialog-bg` | white |
 | `--color-dialog-title` | gray 900 |
 | `--color-dialog-text` | gray 600 |
+| `--color-state-heading` | gray 900, the heading of an `ErrorState` |
+| `--color-state-text` | gray 600, the text of an `ErrorState` or `NotFoundState` |
+| `--color-state-code` | gray 900, the code of a `NotFoundState` |
+| `--font-state-code` | `inherit`, the font of that code |
+| `--color-state-link`, `-hover` | gray 900, the home link |
 
 A default that points at another variable is read once for the whole page. The focus ring and the
 primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.9.0",
+  "version": "0.11.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",
@@ -25,6 +25,7 @@
     "./ui": "./src/ui/index.ts",
     "./toast": "./src/toast/index.ts",
     "./validation": "./src/validation/index.ts",
+    "./next-config": "./src/next-config/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [

package/src/next-config/index.ts

@@ -0,0 +1,154 @@
+import type { NextConfig } from "next";
+
+/** A response header, as `next.config.ts` lists them. */
+export interface Header {
+  key: string;
+  value: string;
+}
+
+/** The API's origin, such as `https://api.example.com`. Empty when the URL is missing or invalid. */
+export function apiOrigin(apiUrl: string | undefined): string {
+  if (!apiUrl) return "";
+  try {
+    return new URL(apiUrl).origin;
+  } catch {
+    return "";
+  }
+}
+
+/** The API's base URL with its path, such as `https://api.example.com/api`, without a trailing slash. Empty when missing or invalid. */
+export function apiBaseUrl(apiUrl: string | undefined): string {
+  if (!apiUrl) return "";
+  try {
+    return new URL(apiUrl).toString().replace(/\/$/, "");
+  } catch {
+    return "";
+  }
+}
+
+export interface CspOptions {
+  /** The app's API URL, usually `process.env.NEXT_PUBLIC_API_URL`. Its origin may be fetched from. */
+  apiUrl: string | undefined;
+  /** Development builds also allow `'unsafe-eval'`, which hot reload needs. */
+  dev: boolean;
+  /** Also allow `ws:` and `wss:` to the API, for a WebSocket such as SignalR. */
+  websocket?: boolean | undefined;
+  /** Also allow images from the API origin. Not needed when images go through the content images rewrite. */
+  imgFromApi?: boolean | undefined;
+  /** Extra sources for `connect-src`. */
+  connectSrc?: readonly string[] | undefined;
+  /** Extra sources for `img-src`. */
+  imgSrc?: readonly string[] | undefined;
+  /** Sources for `frame-src`. Defaults to `'none'`, since no page embeds a frame. */
+  frameSrc?: readonly string[] | undefined;
+  /** Sources for `object-src`. Defaults to `'none'`, since no page embeds an object. */
+  objectSrc?: readonly string[] | undefined;
+}
+
+const sources = (list: readonly (string | false | undefined)[]) => list.filter(Boolean).join(" ");
+
+/**
+ * The Content-Security-Policy for an app's pages. Scripts allow `'unsafe-inline'`, because a nonce
+ * would make every statically rendered page dynamic.
+ */
+export function contentSecurityPolicy(o: CspOptions): string {
+  const origin = apiOrigin(o.apiUrl);
+  const wsOrigin = o.websocket ? origin.replace(/^https:/, "wss:").replace(/^http:/, "ws:") : "";
+  return [
+    "default-src 'self'",
+    o.dev ? "script-src 'self' 'unsafe-eval' 'unsafe-inline'" : "script-src 'self' 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline'",
+    `img-src ${sources(["'self'", o.imgFromApi && origin, "data:", "blob:", ...(o.imgSrc ?? [])])}`,
+    `connect-src ${sources(["'self'", origin, wsOrigin, ...(o.connectSrc ?? [])])}`,
+    `frame-src ${sources(o.frameSrc ?? ["'none'"])}`,
+    `object-src ${sources(o.objectSrc ?? ["'none'"])}`,
+    "font-src 'self'",
+    "base-uri 'self'",
+    "form-action 'self'",
+    "frame-ancestors 'none'",
+    "upgrade-insecure-requests",
+  ].join("; ");
+}
+
+/** The security headers for an app's pages, including the Content-Security-Policy. */
+export function securityHeaders(o: CspOptions & { permissionsPolicy?: string | undefined }): Header[] {
+  return [
+    { key: "X-Content-Type-Options", value: "nosniff" },
+    { key: "X-Frame-Options", value: "DENY" },
+    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+    { key: "X-DNS-Prefetch-Control", value: "on" },
+    { key: "Permissions-Policy", value: o.permissionsPolicy ?? "camera=(), microphone=(), geolocation=()" },
+    { key: "Strict-Transport-Security", value: "max-age=31536000; includeSubDomains" },
+    { key: "Content-Security-Policy", value: contentSecurityPolicy(o) },
+  ];
+}
+
+/**
+ * Content images, proxied so the browser never contacts the API host. A rewrite rather than a route
+ * handler, so the query string and the Accept header, which webp needs, pass through. No rewrite
+ * when the API URL is missing or invalid.
+ */
+export function contentImagesRewrite(apiUrl: string | undefined, o: { source?: string | undefined; upstreamPath?: string | undefined } = {}) {
+  const base = apiBaseUrl(apiUrl);
+  if (!base) return [];
+  const source = o.source ?? "/content-images";
+  const upstream = o.upstreamPath ?? "/content-images";
+  return [{ source: `${source}/:path*`, destination: `${base}${upstream}/:path*` }];
+}
+
+export interface AppConfigOptions extends CspOptions {
+  /** Proxy `/content-images/*` to the API. See `contentImagesRewrite`. */
+  contentImages?: boolean | undefined;
+  /**
+   * Headers for particular paths. Every path gets the page headers, and these come after them, so
+   * they replace a page header of the same name.
+   */
+  pathHeaders?: readonly { source: string; headers: Header[] }[] | undefined;
+  /** Replaces the default Permissions-Policy. */
+  permissionsPolicy?: string | undefined;
+  /**
+   * Seconds a cache may go on serving a page after it goes stale. Next's default is a year, long
+   * enough for a browser to hand back an old page and fetch the current one behind it. Defaults to
+   * 300, matching the client router cache's stale time.
+   */
+  expireTime?: number | undefined;
+  /**
+   * Write revalidated pages to disk. Off by default: with a read-only root filesystem Next cannot
+   * write to `.next/server/app`, so the incremental cache stays in memory.
+   */
+  isrFlushToDisk?: boolean | undefined;
+}
+
+/**
+ * The shared Next config for an app: the standalone build, app-kit transpiled, no `X-Powered-By`,
+ * the security headers on every page, and optionally the content images rewrite. `extra` is merged
+ * over it, with `transpilePackages` and `images` combined.
+ */
+export function defineAppConfig(o: AppConfigOptions, extra: NextConfig = {}): NextConfig {
+  const pageHeaders = securityHeaders(o);
+  const paths = o.pathHeaders ?? [];
+
+  const { transpilePackages, images, experimental, headers: extraHeaders, rewrites: extraRewrites, ...rest } = extra;
+  return {
+    output: "standalone",
+    poweredByHeader: false,
+    expireTime: o.expireTime ?? 300,
+    ...rest,
+    transpilePackages: [...new Set(["@sjolystinnovation/app-kit", ...(transpilePackages ?? [])])],
+    images: { qualities: [75, 100], ...images },
+    experimental: { isrFlushToDisk: o.isrFlushToDisk ?? false, ...experimental },
+    async headers() {
+      // Every path gets the page headers. Next lets a later rule replace a header of the same name,
+      // so a path's own headers come after them.
+      const own = [{ source: "/:path*", headers: pageHeaders }, ...paths.map(p => ({ source: p.source, headers: p.headers }))];
+      return [...own, ...((await extraHeaders?.()) ?? [])];
+    },
+    async rewrites() {
+      const own = o.contentImages ? contentImagesRewrite(o.apiUrl) : [];
+      const more = await extraRewrites?.();
+      if (!more) return own;
+      if (Array.isArray(more)) return [...own, ...more];
+      return { ...more, afterFiles: [...own, ...(more.afterFiles ?? [])] };
+    },
+  };
+}

package/src/styles.css

@@ -45,6 +45,13 @@
   --color-toggle-off: var(--color-gray-200);
   --color-toggle-thumb: var(--color-white);
 
+  --color-state-heading: var(--color-gray-900);
+  --color-state-text: var(--color-gray-600);
+  --color-state-code: var(--color-gray-900);
+  --font-state-code: inherit;
+  --color-state-link: var(--color-gray-900);
+  --color-state-link-hover: var(--color-gray-900);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);

package/src/ui/ContentImage.tsx

@@ -0,0 +1,73 @@
+/** The widths the API serves an uploaded image at, as webp. */
+export const CONTENT_IMAGE_WIDTHS: readonly number[] = [384, 640, 768, 1024, 1366, 1600];
+
+/** Where the browser fetches an uploaded image. Site-relative, through the app's content images rewrite. */
+export function contentImagePath(id: string, base = "/content-images"): string {
+  return `${base}/${encodeURIComponent(id)}`;
+}
+
+/**
+ * The `srcset` for an uploaded image. The API serves the nearest webp at or above the requested
+ * width, or the original when the browser does not accept webp.
+ */
+export function contentImageSrcSet(id: string, widths: readonly number[] = CONTENT_IMAGE_WIDTHS, base?: string): string {
+  return widths.map(w => `${contentImagePath(id, base)}?w=${w} ${w}w`).join(", ");
+}
+
+export interface ContentImageProps {
+  /** Uploaded image id. Null falls back to `fallbackSrc`, which is served as it is. */
+  imageId: string | null;
+  /** Empty for an image that carries no meaning of its own, such as a decorative backdrop. */
+  alt: string;
+  /** Widths the image is shown at. Required, since a browser assumes 100vw without it. */
+  sizes: string;
+  /** A static path for when there is no uploaded image. */
+  fallbackSrc?: string | undefined;
+  className?: string | undefined;
+  /** Intrinsic size, to reserve space. Only needed where the layout fixes no ratio. */
+  width?: number | undefined;
+  height?: number | undefined;
+  /** Set on the one image visible without scrolling. It loads eagerly, at high priority. */
+  priority?: boolean | undefined;
+  "aria-hidden"?: boolean | undefined;
+  /** Path the content images rewrite serves, `/content-images` by default. */
+  base?: string | undefined;
+  /** Widths in the `srcset`. Defaults to the widths the API serves. */
+  widths?: readonly number[] | undefined;
+}
+
+/** An image from the content API, served responsively from the `sizes` a call site declares. */
+export function ContentImage({
+  imageId,
+  alt,
+  sizes,
+  fallbackSrc,
+  className,
+  width,
+  height,
+  priority = false,
+  "aria-hidden": ariaHidden,
+  base,
+  widths,
+}: ContentImageProps) {
+  const uploaded = imageId != null && imageId !== "";
+  const src = uploaded ? contentImagePath(imageId, base) : fallbackSrc;
+  if (!src) return null;
+
+  return (
+    // A plain img, because the API already serves the sizes. next/image would resize them again.
+    <img
+      src={src}
+      srcSet={uploaded ? contentImageSrcSet(imageId, widths, base) : undefined}
+      sizes={uploaded ? sizes : undefined}
+      alt={alt}
+      className={className}
+      width={width}
+      height={height}
+      loading={priority ? "eager" : "lazy"}
+      fetchPriority={priority ? "high" : undefined}
+      decoding={priority ? "sync" : "async"}
+      aria-hidden={ariaHidden}
+    />
+  );
+}

package/src/ui/ErrorState.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import Link from "next/link";
+import { cx } from "./cx";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+export interface ErrorStateStrings {
+  title: string;
+  body: string;
+  tryAgain: string;
+  home: string;
+}
+
+export const defaultErrorStateStrings: ErrorStateStrings = {
+  title: "Temporarily unavailable",
+  body: "We can't reach the service right now. Please try again shortly.",
+  tryAgain: "Try again",
+  home: "Go to the front page",
+};
+
+export interface ErrorStateProps {
+  /** The `reset` Next passes to an `error.tsx`. It renders the page again. */
+  reset: () => void;
+  /** Where the front page link goes, such as `/` or `/en`. */
+  homeHref: string;
+  strings?: TextOverrides<ErrorStateStrings> | undefined;
+  /** Classes for placing it, on the outer element. */
+  className?: string | undefined;
+}
+
+/** What an `error.tsx` shows when a page cannot be rendered. The response is still a 500. */
+export function ErrorState({ reset, homeHref, strings, className }: ErrorStateProps) {
+  const text = withDefaults(defaultErrorStateStrings, strings);
+  return (
+    <div className={cx("min-h-[60vh] flex flex-col items-center justify-center gap-4 px-4 text-center", className)}>
+      <h1 className="text-3xl font-black text-state-heading">{text.title}</h1>
+      <p className="text-lg text-state-text max-w-md">{text.body}</p>
+      <div className="mt-2 flex flex-wrap items-center justify-center gap-4">
+        <button
+          type="button"
+          onClick={reset}
+          className="rounded-button bg-button-primary-bg text-button-primary-text font-semibold px-6 py-3 hover:brightness-95 transition"
+        >
+          {text.tryAgain}
+        </button>
+        <Link href={homeHref} className="font-semibold text-state-link hover:text-state-link-hover underline">
+          {text.home}
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/ui/NotFoundState.tsx

@@ -0,0 +1,37 @@
+import Link from "next/link";
+import { cx } from "./cx";
+import { withDefaults, type TextOverrides } from "./withDefaults";
+
+export interface NotFoundStrings {
+  code: string;
+  body: string;
+  home: string;
+}
+
+export const defaultNotFoundStrings: NotFoundStrings = {
+  code: "404",
+  body: "This page does not exist.",
+  home: "Go home",
+};
+
+export interface NotFoundStateProps {
+  /** Where the home link goes, such as `/` or `/en`. */
+  homeHref: string;
+  strings?: TextOverrides<NotFoundStrings> | undefined;
+  /** Classes for placing it, on the outer element. */
+  className?: string | undefined;
+}
+
+/** What a `not-found.tsx` shows. The message is the page's heading. */
+export function NotFoundState({ homeHref, strings, className }: NotFoundStateProps) {
+  const text = withDefaults(defaultNotFoundStrings, strings);
+  return (
+    <div className={cx("min-h-[60vh] flex flex-col items-center justify-center gap-4 px-4 text-center", className)}>
+      <span className="text-6xl font-black font-state-code text-state-code">{text.code}</span>
+      <h1 className="text-lg text-state-text">{text.body}</h1>
+      <Link href={homeHref} className="font-semibold text-state-link hover:text-state-link-hover underline">
+        {text.home}
+      </Link>
+    </div>
+  );
+}

package/src/ui/index.ts

@@ -1,9 +1,15 @@
 export { Alert } from "./Alert";
 export type { AlertProps } from "./Alert";
+export { ContentImage, CONTENT_IMAGE_WIDTHS, contentImagePath, contentImageSrcSet } from "./ContentImage";
+export type { ContentImageProps } from "./ContentImage";
 export { CredentialsForm } from "./CredentialsForm";
 export type { CredentialsFormProps } from "./CredentialsForm";
 export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsFormStrings";
 export type { CredentialsFormStrings } from "./credentialsFormStrings";
+export { ErrorState, defaultErrorStateStrings } from "./ErrorState";
+export type { ErrorStateProps, ErrorStateStrings } from "./ErrorState";
+export { NotFoundState, defaultNotFoundStrings } from "./NotFoundState";
+export type { NotFoundStateProps, NotFoundStrings } from "./NotFoundState";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
 export { TextArea } from "./TextArea";