@sjolystinnovation/app-kit 0.8.0 → 0.10.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
@@ -566,6 +605,46 @@ From `@sjolystinnovation/app-kit/ui`. A labelled text field with the same look a
 <TextInput label="Email" name="email" type="email" required error={errors.email} />
 ```
 
+### `TextArea`
+
+From `@sjolystinnovation/app-kit/ui`. A labelled multi-line field with the same look, label and
+error handling as `TextInput`. It takes the other `<textarea>` attributes too, and works controlled
+or uncontrolled.
+
+```tsx
+<TextArea label="Description" name="description" rows={4} maxRows={10} error={errors.description} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | | Visible label, tied to the text area. |
+| `error` | `string` | | Message shown under the field, read out with it by screen readers. |
+| `autoGrow` | `boolean` | `true` | Grows with its text from `rows` lines up to `maxRows`, and has no resize handle. With `false` it keeps its size and shows the handle. |
+| `rows` | `number` | `3` | Lines shown when empty. |
+| `maxRows` | `number` | `12` | The most lines an auto-growing box shows before it scrolls. |
+| `className` | `string` | | Classes for placing the field, on the outer element. |
+
+### `Toggle`
+
+From `@sjolystinnovation/app-kit/ui`. An on and off switch for a setting that takes effect at once.
+It takes the other `<button>` attributes too.
+
+```tsx
+<Toggle label="Email notifications" checked={enabled} onChange={setEnabled} />
+<Toggle aria-label="VAT" checked={vat} onChange={setVat} disabled={saving} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `checked` | `boolean` | Whether the switch is on. |
+| `onChange` | `(checked: boolean) => void` | Called with the new state. A callback that ignores it also fits. |
+| `label` | `string` | Visible text after the switch. It names the switch, and a click on it flips the switch. |
+| `aria-label` | `string` | The switch's name when there is no `label`. One of the two is required. |
+| `disabled` | `boolean` | Greys the switch out and ignores clicks. |
+| `className` | `string` | Classes for placing it, on the outer element. |
+
+An `onClick` that calls `event.preventDefault()` stops the change.
+
 ### `Alert`
 
 ```tsx
@@ -674,6 +753,9 @@ selector such as `.dark` for a scoped theme:
 | `--input-focus-ring-width` | `2px` |
 | `--color-input-toggle` | gray 400, the show password icon |
 | `--color-input-toggle-hover` | gray 600 |
+| `--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 |
 | `--radius-button` | `var(--radius-lg)` |
 | `--color-button-primary-bg` | `var(--color-primary)` |
 | `--color-button-primary-text` | `var(--color-primary-foreground)` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.8.0",
+  "version": "0.10.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

@@ -41,6 +41,10 @@
   --color-input-toggle: var(--color-gray-400);
   --color-input-toggle-hover: var(--color-gray-600);
 
+  --color-toggle-on: var(--color-primary);
+  --color-toggle-off: var(--color-gray-200);
+  --color-toggle-thumb: var(--color-white);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);

package/src/ui/TextArea.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback, useEffect, useRef, type TextareaHTMLAttributes } from "react";
+import { FieldError, FieldLabel, inputClass, useField } from "./field";
+
+export interface TextAreaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label: string;
+  error?: string | undefined;
+  /**
+   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
+   * label, the text area and the error. Restyle the field through the theme variables.
+   */
+  className?: string | undefined;
+  /** Grows with its text, from `rows` lines up to `maxRows` lines. On by default. */
+  autoGrow?: boolean | undefined;
+  /** The most lines an auto-growing box shows before it scrolls. Defaults to 12. */
+  maxRows?: number | undefined;
+}
+
+export function TextArea({ label, error, className, autoGrow = true, maxRows = 12, rows = 3, onInput, ...props }: TextAreaProps) {
+  const field = useField(props, error);
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  const resize = useCallback(() => {
+    const el = ref.current;
+    if (!el || !autoGrow) return;
+    const style = getComputedStyle(el);
+    const lineHeight = parseFloat(style.lineHeight) || 20;
+    const padding = parseFloat(style.paddingTop) + parseFloat(style.paddingBottom);
+    // scrollHeight covers the content and padding. A border-box height also needs the border.
+    const border = parseFloat(style.borderTopWidth) + parseFloat(style.borderBottomWidth);
+    const boxFor = (lines: number) => lineHeight * lines + padding + border;
+    el.style.height = "auto";
+    el.style.height = `${Math.min(Math.max(el.scrollHeight + border, boxFor(Number(rows))), boxFor(maxRows))}px`;
+  }, [autoGrow, rows, maxRows]);
+
+  // A controlled box grows when its value changes. An uncontrolled one grows as it is typed in.
+  useEffect(resize, [resize, props.value]);
+
+  const handleInput = (event: Parameters<NonNullable<TextAreaProps["onInput"]>>[0]) => {
+    onInput?.(event);
+    resize();
+  };
+
+  return (
+    <div className={className}>
+      <FieldLabel htmlFor={field.inputId} required={props.required}>
+        {label}
+      </FieldLabel>
+      <textarea
+        {...props}
+        {...field.inputProps}
+        ref={ref}
+        rows={rows}
+        onInput={handleInput}
+        // An auto-growing box has no resize handle. The next keystroke would undo the drag.
+        className={inputClass(error, autoGrow ? "leading-relaxed resize-none" : "leading-relaxed resize-y")}
+      />
+      <FieldError id={field.errorId} error={error} />
+    </div>
+  );
+}

package/src/ui/Toggle.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import type { ButtonHTMLAttributes, MouseEvent } from "react";
+import { cx } from "./cx";
+
+type ToggleBase = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "role" | "type" | "aria-checked"> & {
+  checked: boolean;
+  /** Called with the new state when the switch is flipped. */
+  onChange: (checked: boolean) => void;
+};
+
+/** A switch needs a name. Either a visible `label`, or an `aria-label` when there is none. */
+export type ToggleProps = ToggleBase & ({ label: string } | { label?: undefined; "aria-label": string });
+
+/** An on and off switch, for a setting that takes effect at once. */
+export function Toggle({ checked, onChange, label, className, disabled, onClick, ...props }: ToggleProps) {
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (!event.defaultPrevented) onChange(!checked);
+  };
+
+  const button = (
+    <button
+      {...props}
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      disabled={disabled}
+      onClick={handleClick}
+      className={cx(
+        "relative inline-flex h-6 w-11 shrink-0 items-center rounded-full transition-colors focus:outline-hidden focus-visible:ring-(length:--input-focus-ring-width) focus-visible:ring-input-focus-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+        checked ? "bg-toggle-on" : "bg-toggle-off",
+        label === undefined && className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className={cx(
+          "inline-block h-5 w-5 rounded-full bg-toggle-thumb shadow-sm transition-transform motion-reduce:transition-none",
+          checked ? "translate-x-5" : "translate-x-0.5",
+        )}
+      />
+    </button>
+  );
+
+  if (label === undefined) return button;
+
+  // The label wraps the switch, so the text names it and a click on the text flips it.
+  return (
+    <label className={cx("inline-flex items-center gap-2.5 text-field-label font-medium text-field-label-text select-none", disabled ? "cursor-not-allowed" : "cursor-pointer", className)}>
+      {button}
+      {label}
+    </label>
+  );
+}

package/src/ui/field.tsx

@@ -1,10 +1,16 @@
 "use client";
 
-import { useId, type InputHTMLAttributes, type ReactNode } from "react";
+import { useId, type AriaAttributes, type ReactNode } from "react";
 import { cx } from "./cx";
 
+/** The props of a field control that useField reads. An `<input>` and a `<textarea>` both have them. */
+export type FieldControlProps = Pick<AriaAttributes, "aria-required" | "aria-invalid" | "aria-describedby"> & {
+  id?: string | undefined;
+  required?: boolean | undefined;
+};
+
 /** The ids and aria attributes a labelled input needs, from the caller's own props. */
-export function useField(props: Pick<InputHTMLAttributes<HTMLInputElement>, "id" | "required" | "aria-required" | "aria-invalid" | "aria-describedby">, error: string | undefined) {
+export function useField(props: FieldControlProps, error: string | undefined) {
   // A generated id ties the label to its own control, even when two fields on a page share a name.
   const generated = useId();
   const inputId = props.id ?? generated;

package/src/ui/index.ts

@@ -6,6 +6,10 @@ export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsForm
 export type { CredentialsFormStrings } from "./credentialsFormStrings";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
+export { TextArea } from "./TextArea";
+export type { TextAreaProps } from "./TextArea";
 export { TextInput } from "./TextInput";
 export type { TextInputProps } from "./TextInput";
+export { Toggle } from "./Toggle";
+export type { ToggleProps } from "./Toggle";
 export type { TextOverrides } from "./withDefaults";