@sjolystinnovation/app-kit 0.2.0 → 0.3.0

package/README.md

@@ -91,20 +91,36 @@ resolveJwtSecret(sessionConfig, {});
 The environment is a parameter rather than a read of `process.env`, which keeps Node types out of a
 package that also runs in the browser.
 
-### `formatApiError(error, fallback)`
+### `formatApiError(error, fallback, statusMessages?)`
 
-`(error: unknown, fallback: string) => string`
+`(error: unknown, fallback: string, statusMessages?: StatusMessages) => string`
 
-Turns a failed request into one line a user can read. For an axios error it takes the first of
-`message`, the first validation error, `detail` and `title` from the response body, which covers
-plain JSON errors and ASP.NET Core problem details alike. Otherwise it uses the error's own message,
-then `fallback`.
+Turns a failed request into one line a user can read.
+
+On a 4xx response it uses the first of:
+
+1. The body's own message: a text body, such as the one `BadRequest("...")` sends from ASP.NET Core,
+   or `message`, the first validation error or `detail` from a JSON body.
+2. The entry in `statusMessages` for the status.
+3. `fallback`.
+
+On a 5xx response the entry in `statusMessages` comes first, then the body, then `fallback`. A 5xx
+body can come from a proxy, such as "Bad Gateway", so the caller's own words win when it has them.
+
+A problem details `title` is never shown. ASP.NET Core fills it with generic text, such as "Bad
+Request" or "An error occurred while processing your request.", which says less than `fallback`.
+
+Key `0` in `statusMessages` covers a request that got no response, because of a dropped connection
+or a timeout. Only text on a single line counts as a message. Axios's own message, such as "Request
+failed with status code 500", is never shown, and a cancelled request gives `fallback`. Any other
+`Error` gives its own message. A body requested as an `arraybuffer` or a `blob`, as for a file
+download, is not read, so a failed download gets `statusMessages` or `fallback`.
 
 ```ts
 try {
   await api.post("/users", form);
 } catch (error) {
-  setError(formatApiError(error, "Could not create the user."));
+  setError(formatApiError(error, "Could not create the user.", { 409: "That email is taken." }));
 }
 ```
 
@@ -120,12 +136,14 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | --- | --- | --- | --- |
 | `variant` | `"error" \| "success" \| "info" \| "warning"` | `"info"` | Colour of the box. |
 | `role` | `"alert" \| "status"` | `"alert"` | Use `status` for text that keeps changing, such as a countdown, so a screen reader does not announce every change. |
+| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables instead, since whether a clashing class wins depends on the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
 ### `PasswordInput`
 
-A labelled password field with a button that shows and hides the value. Accepts every `<input>`
-attribute as well.
+A labelled password field with a button that shows and hides the value. It also takes the other
+`<input>` attributes, apart from `type`, which the component switches itself. `className` goes on
+the outer element, see below.
 
 ```tsx
 import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
@@ -136,17 +154,69 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `label` | `string` | | Visible label, tied to the input. |
-| `error` | `string` | | Message shown under the field, which also turns the border red. |
+| `error` | `string` | | Message shown under the field. It turns the border red, marks the input invalid and is read out with it by screen readers. |
 | `showPasswordLabel` | `string` | `"Show password"` | Accessible name of the toggle while the value is hidden. |
 | `hidePasswordLabel` | `string` | `"Hide password"` | Accessible name of the toggle while the value is visible. |
+| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables instead. |
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
+## Theming
+
+The components draw every colour, corner radius and label size from theme variables with a light
+default. Set any of them in the app's own `@theme` to restyle every component at once, or in a
+selector such as `.dark` for a scoped theme:
+
+```css
+/* src/app/globals.css */
+@import "tailwindcss";
+@import "@sjolystinnovation/app-kit/styles.css";
+
+@theme {
+  --color-alert-error-bg: color-mix(in oklab, var(--color-red-500) 10%, transparent);
+  --color-alert-error-text: var(--color-red-400);
+  --radius-alert: var(--radius-xl);
+  --color-input-focus-ring: var(--color-sky-500);
+}
+```
+
+| Variable | Default |
+| --- | --- |
+| `--radius-alert` | `var(--radius-lg)` |
+| `--color-alert-error-bg`, `-border`, `-text` | red 50, 200, 700 |
+| `--color-alert-success-bg`, `-border`, `-text` | green 50, 200, 700 |
+| `--color-alert-info-bg`, `-border`, `-text` | gray 50, 200, 700 |
+| `--color-alert-warning-bg`, `-border`, `-text` | amber 50, 200, 900 |
+| `--text-field-label`, `--text-field-label--line-height` | `var(--text-sm)` and its line height. Set both together. |
+| `--color-field-label-text` | gray 700 |
+| `--spacing-field-label` | gap under the label, `calc(var(--spacing) * 1)` |
+| `--color-field-required` | red 600, the asterisk on a required field |
+| `--color-field-error` | red 600, the message under a field |
+| `--radius-input` | `var(--radius-lg)` |
+| `--spacing-input-y` | `calc(var(--spacing) * 2)` |
+| `--color-input-bg` | `transparent` |
+| `--color-input-border` | gray 300 |
+| `--color-input-border-error` | red 400 |
+| `--color-input-focus-border` | gray 300 |
+| `--color-input-text` | gray 900 |
+| `--color-input-placeholder` | gray 400 |
+| `--color-input-focus-ring` | `var(--color-primary)` |
+| `--input-focus-ring-width` | `2px` |
+| `--color-input-toggle` | gray 400, the show password icon |
+| `--color-input-toggle-hover` | gray 600 |
+
+A default that points at another variable, such as `--color-input-focus-ring` at `--color-primary`,
+is read once for the whole page. A scoped theme that changes `--color-primary` should set
+`--color-input-focus-ring` in the same selector.
+
+An app that clears a whole Tailwind namespace, such as `--color-*: initial`, clears these variables
+with it and has to set the ones it uses itself.
+
 ## Requirements
 
 - Next.js 16, React 19, next-auth 4 and axios 1, as peer dependencies the app installs itself.
-- For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 with a `primary` colour in the theme, which the
-  focus ring uses, and `@heroicons/react` 2.
+- For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring uses
+  the theme's `primary` colour unless `--color-input-focus-ring` is 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.2.0",
+  "version": "0.3.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",

package/src/errors.ts

@@ -1,29 +1,108 @@
-import axios from "axios";
+import axios, { type AxiosResponse } from "axios";
 
-interface ApiErrorBody {
-  message?: string;
-  detail?: string;
-  title?: string;
-  errors?: Record<string, string[]>;
-}
+/**
+ * Messages to show for a status code. On a 4xx they are used when the response carries no specific
+ * message of its own. On a 5xx they win over the body. Key 0 covers a request that got no response,
+ * because of a dropped connection or a timeout.
+ */
+export type StatusMessages = Partial<Record<number, string>>;
+
+/**
+ * Axios codes for a request that never got a response from the network. A browser reports every
+ * network failure as ERR_NETWORK. On the server, Node reports the cause instead.
+ */
+const NO_RESPONSE_CODES = new Set([
+  "ERR_NETWORK",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+]);
 
 /**
- * Turns a failed request into one line a user can read. Takes the first of `message`, the first
- * validation error, `detail` and `title` from the response body, so it reads both plain JSON
- * errors and ASP.NET Core problem details. Falls back to the error's own message, then to
- * `fallback`.
+ * Turns a failed request into one line a user can read.
+ *
+ * On a 4xx response the body's own message comes first: a text body, then `message`, the first
+ * validation error and `detail` from a JSON body. After that come `statusMessages` for the status
+ * and `fallback`. On a 5xx the caller's status message comes first, because the body may be a
+ * proxy's "Bad Gateway" rather than the API's own words. A problem details `title` is never used:
+ * ASP.NET Core fills it with generic text such as "Bad Request", which says less than `fallback`.
+ *
+ * Only single line text counts as a message. Axios's own message, such as "Request failed with
+ * status code 500", is never shown, and a cancelled request gives `fallback`. Any other `Error`
+ * gives its message.
  */
-export function formatApiError(error: unknown, fallback: string): string {
+export function formatApiError(
+  error: unknown,
+  fallback: string,
+  statusMessages: StatusMessages = {},
+): string {
+  if (axios.isCancel(error)) return fallback;
   if (axios.isAxiosError(error)) {
-    const data = error.response?.data as ApiErrorBody | undefined;
-    if (data?.message) return data.message;
-    if (data?.errors) {
-      const first = Object.values(data.errors)[0];
-      if (first && first.length) return first[0];
+    const response = error.response;
+    if (!response) {
+      return NO_RESPONSE_CODES.has(error.code ?? "") ? (statusMessages[0] ?? fallback) : fallback;
     }
-    if (data?.detail) return data.detail;
-    if (data?.title) return data.title;
+    const message = readBody(response);
+    const forStatus = statusMessages[response.status];
+    if (response.status >= 500) return forStatus ?? message ?? fallback;
+    return message ?? forStatus ?? fallback;
   }
-  if (error instanceof Error) return error.message;
+  if (error instanceof Error) return singleLine(error.message) ?? fallback;
   return fallback;
 }
+
+/** The message the body carries for this failure, if it carries one. */
+function readBody(response: AxiosResponse): string | undefined {
+  const data = parseIfJson(response.data);
+  if (typeof data === "string") return singleLine(data);
+  // Only a parsed JSON object has fields to read. A Document, Blob or ArrayBuffer does not.
+  if (!isPlainObject(data)) return undefined;
+  return firstText(data.message) ?? firstValidationError(data.errors) ?? singleLine(data.detail);
+}
+
+/**
+ * Axios leaves a JSON body as a string when the request asked for text, so parse it here. Plain text
+ * such as "Invalid email or password." is not valid JSON and stays as it is.
+ */
+function parseIfJson(data: unknown): unknown {
+  if (typeof data !== "string") return data;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Reads the first message from `errors`, whether its values are string arrays or strings. */
+function firstValidationError(errors: unknown): string | undefined {
+  if (!errors || typeof errors !== "object") return undefined;
+  for (const value of Object.values(errors)) {
+    const message = firstText(value);
+    if (message) return message;
+  }
+  return undefined;
+}
+
+/** A single line of text, or the first entry when the value is a list of them. */
+function firstText(value: unknown): string | undefined {
+  return singleLine(Array.isArray(value) ? value[0] : value);
+}
+
+/** The trimmed text, when it is one line of text and not HTML. */
+function singleLine(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  if (!text || /[\r\n\u2028\u2029]/.test(text) || text.startsWith("<")) return undefined;
+  return text;
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export { defineSessionConfig, resolveJwtSecret } from "./config";
 export type { SessionConfig } from "./config";
 export { formatApiError } from "./errors";
+export type { StatusMessages } from "./errors";

package/src/styles.css

@@ -1,2 +1,43 @@
 /* Adds this package's components to the files Tailwind scans for class names. */
 @source ".";
+
+/*
+ * Design tokens for the components. Each default matches a stock Tailwind value, so an app that
+ * sets none of them gets the look below. Set any of them in the app's own @theme to restyle, or in
+ * a selector such as .dark for a scoped theme.
+ */
+@theme default {
+  --radius-alert: var(--radius-lg);
+  --color-alert-error-bg: var(--color-red-50);
+  --color-alert-error-border: var(--color-red-200);
+  --color-alert-error-text: var(--color-red-700);
+  --color-alert-success-bg: var(--color-green-50);
+  --color-alert-success-border: var(--color-green-200);
+  --color-alert-success-text: var(--color-green-700);
+  --color-alert-info-bg: var(--color-gray-50);
+  --color-alert-info-border: var(--color-gray-200);
+  --color-alert-info-text: var(--color-gray-700);
+  --color-alert-warning-bg: var(--color-amber-50);
+  --color-alert-warning-border: var(--color-amber-200);
+  --color-alert-warning-text: var(--color-amber-900);
+
+  --text-field-label: var(--text-sm);
+  --text-field-label--line-height: var(--text-sm--line-height);
+  --color-field-label-text: var(--color-gray-700);
+  --spacing-field-label: calc(var(--spacing) * 1);
+  --color-field-required: var(--color-red-600);
+  --color-field-error: var(--color-red-600);
+
+  --radius-input: var(--radius-lg);
+  --spacing-input-y: calc(var(--spacing) * 2);
+  --color-input-bg: transparent;
+  --color-input-border: var(--color-gray-300);
+  --color-input-border-error: var(--color-red-400);
+  --color-input-focus-border: var(--color-gray-300);
+  --color-input-text: var(--color-gray-900);
+  --color-input-placeholder: var(--color-gray-400);
+  --color-input-focus-ring: var(--color-primary);
+  --input-focus-ring-width: 2px;
+  --color-input-toggle: var(--color-gray-400);
+  --color-input-toggle-hover: var(--color-gray-600);
+}

package/src/ui/Alert.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { cx } from "./cx";
 
 export interface AlertProps {
   variant?: "error" | "success" | "info" | "warning";
@@ -7,19 +8,25 @@ export interface AlertProps {
    * changing, such as a countdown, so it is not announced on every tick.
    */
   role?: "alert" | "status";
+  /**
+   * Classes for placing the alert, such as a margin. Restyle it through the theme variables
+   * instead: whether a class that clashes with the alert's own wins depends on the order Tailwind
+   * emits them in.
+   */
+  className?: string;
   children: ReactNode;
 }
 
 const styles: Record<NonNullable<AlertProps["variant"]>, string> = {
-  error: "bg-red-50 border-red-200 text-red-700",
-  success: "bg-green-50 border-green-200 text-green-700",
-  info: "bg-gray-50 border-gray-200 text-gray-700",
-  warning: "bg-amber-50 border-amber-200 text-amber-900",
+  error: "bg-alert-error-bg border-alert-error-border text-alert-error-text",
+  success: "bg-alert-success-bg border-alert-success-border text-alert-success-text",
+  info: "bg-alert-info-bg border-alert-info-border text-alert-info-text",
+  warning: "bg-alert-warning-bg border-alert-warning-border text-alert-warning-text",
 };
 
-export function Alert({ variant = "info", role = "alert", children }: AlertProps) {
+export function Alert({ variant = "info", role = "alert", className, children }: AlertProps) {
   return (
-    <div className={`rounded-lg border px-3 py-2 text-sm ${styles[variant]}`} role={role}>
+    <div className={cx("rounded-alert border px-3 py-2 text-sm", styles[variant], className)} role={role}>
       {children}
     </div>
   );

package/src/ui/PasswordInput.tsx

@@ -2,14 +2,21 @@
 
 import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
 import { useId, useState, type InputHTMLAttributes } from "react";
+import { cx } from "./cx";
 
-export interface PasswordInputProps extends InputHTMLAttributes<HTMLInputElement> {
+/** The input's type is left out: the component switches it to show and hide the value. */
+export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
   label: string;
   error?: string;
   /** Accessible name of the toggle while the password is hidden. */
   showPasswordLabel?: string;
   /** Accessible name of the toggle while the password is visible. */
   hidePasswordLabel?: string;
+  /**
+   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
+   * label, the input and the error. Restyle the field through the theme variables instead.
+   */
+  className?: string;
 }
 
 export function PasswordInput({
@@ -17,44 +24,53 @@ export function PasswordInput({
   error,
   id,
   required,
+  className,
   showPasswordLabel = "Show password",
   hidePasswordLabel = "Hide password",
   ...props
 }: PasswordInputProps) {
   const [visible, setVisible] = useState(false);
-  // Fall back to a generated id so the label is always tied to its control. Without it, a call
-  // site that passes neither id nor name renders a label pointing at nothing, which leaves
-  // screen reader users with an unidentified field.
+  // Fall back to a generated id so the label is always tied to its own control. Not the name: two
+  // fields named "password" on one page, such as sign in next to sign up, would share an id.
   const generated = useId();
-  const inputId = id ?? props.name ?? generated;
+  const inputId = id ?? generated;
+  // Built from useId rather than the name, since an id list in aria-describedby splits on spaces.
+  const errorId = `${generated}-error`;
 
   return (
-    <div>
-      <label htmlFor={inputId} className="block text-sm font-medium text-gray-700 mb-1">
+    <div className={className}>
+      <label htmlFor={inputId} className="block text-field-label font-medium text-field-label-text mb-field-label">
         {label}
-        {required && <span className="text-red-600"> *</span>}
+        {required && <span className="text-field-required"> *</span>}
       </label>
       <div className="relative">
         <input
+          {...props}
           id={inputId}
           type={visible ? "text" : "password"}
           required={required}
-          aria-required={required || undefined}
-          className={`w-full rounded-lg border px-3 py-2 pr-10 text-sm text-gray-900 placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-primary ${
-            error ? "border-red-400" : "border-gray-300"
-          }`}
-          {...props}
+          aria-required={required ? true : props["aria-required"]}
+          aria-invalid={error ? true : props["aria-invalid"]}
+          aria-describedby={cx(props["aria-describedby"], error && errorId) || undefined}
+          className={cx(
+            "w-full rounded-input border px-3 py-input-y pr-10 text-sm bg-input-bg text-input-text placeholder-input-placeholder focus:outline-hidden focus:ring-(length:--input-focus-ring-width) focus:ring-input-focus-ring",
+            error ? "border-input-border-error" : "border-input-border focus:border-input-focus-border",
+          )}
         />
         <button
           type="button"
           onClick={() => setVisible((v) => !v)}
-          className="absolute inset-y-0 right-0 px-3 text-gray-400 hover:text-gray-600"
+          className="absolute inset-y-0 right-0 px-3 text-input-toggle hover:text-input-toggle-hover"
           aria-label={visible ? hidePasswordLabel : showPasswordLabel}
         >
           {visible ? <EyeSlashIcon className="h-4 w-4" /> : <EyeIcon className="h-4 w-4" />}
         </button>
       </div>
-      {error && <p className="mt-1 text-xs text-red-600">{error}</p>}
+      {error && (
+        <p id={errorId} className="mt-1 text-xs text-field-error">
+          {error}
+        </p>
+      )}
     </div>
   );
 }

package/src/ui/cx.ts

@@ -0,0 +1,4 @@
+/** Joins class names, skipping empty ones. */
+export function cx(...classes: Array<string | false | null | undefined>): string {
+  return classes.filter(Boolean).join(" ");
+}