@sjolystinnovation/app-kit 0.1.0 → 0.3.0

package/README.md

@@ -3,12 +3,11 @@
 [![npm](https://img.shields.io/npm/v/@sjolystinnovation/app-kit.svg)](https://www.npmjs.com/package/@sjolystinnovation/app-kit)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 
-> Session configuration for Next.js apps that sign in against a JWT API through next-auth
+> Building blocks for Next.js apps that sign in against a JWT API through next-auth
 
-Several apps sharing one API also share the session plumbing around it: which environment variable
-holds the signing secret, where an expired session sends the browser, what prefixes the draft keys in
-`localStorage`. This package keeps those as one typed config, so the code around them can be shared
-instead of copied.
+Several apps sharing one API also share the code around it: the session plumbing, how a failed
+request becomes a message a user can read, and the form controls on the sign in page. This package
+holds that code once, so the apps install it instead of each keeping a copy.
 
 ## Install
 
@@ -25,6 +24,15 @@ const nextConfig: NextConfig = {
 };
 ```
 
+The components in `@sjolystinnovation/app-kit/ui` are styled with Tailwind CSS. Import the
+package's stylesheet after Tailwind:
+
+```css
+/* src/app/globals.css */
+@import "tailwindcss";
+@import "@sjolystinnovation/app-kit/styles.css";
+```
+
 ## Usage
 
 Declare the values that differ between apps once, then pass that config wherever it is needed. One
@@ -83,9 +91,132 @@ 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, statusMessages?)`
+
+`(error: unknown, fallback: string, statusMessages?: StatusMessages) => string`
+
+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.", { 409: "That email is taken." }));
+}
+```
+
+### `Alert`
+
+```tsx
+import { Alert } from "@sjolystinnovation/app-kit/ui";
+
+<Alert variant="error">{message}</Alert>;
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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. 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";
+
+<PasswordInput label="Password" name="password" required error={errors.password} />;
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | | Visible label, tied to the input. |
+| `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 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,7 +1,7 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.1.0",
-  "description": "Session configuration for Next.js apps that sign in against a JWT API through next-auth",
+  "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",
   "repository": {
@@ -11,9 +11,13 @@
   },
   "homepage": "https://github.com/sondresjolyst/si-web-packages#readme",
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./styles.css": "./src/styles.css"
   },
   "files": [
     "src",
@@ -27,6 +31,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
+    "@heroicons/react": "^2",
     "axios": "^1",
     "next": "^16",
     "next-auth": "^4.24",
@@ -34,6 +39,7 @@
     "react-dom": "^19"
   },
   "devDependencies": {
+    "@heroicons/react": "^2.2.0",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
@@ -54,6 +60,7 @@
     "next-auth",
     "session",
     "jwt",
-    "react"
+    "react",
+    "tailwindcss"
   ]
 }

package/src/errors.ts

@@ -0,0 +1,108 @@
+import axios, { type AxiosResponse } from "axios";
+
+/**
+ * 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.
+ *
+ * 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,
+  statusMessages: StatusMessages = {},
+): string {
+  if (axios.isCancel(error)) return fallback;
+  if (axios.isAxiosError(error)) {
+    const response = error.response;
+    if (!response) {
+      return NO_RESPONSE_CODES.has(error.code ?? "") ? (statusMessages[0] ?? fallback) : fallback;
+    }
+    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 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,2 +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

@@ -0,0 +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

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import { cx } from "./cx";
+
+export interface AlertProps {
+  variant?: "error" | "success" | "info" | "warning";
+  /**
+   * Defaults to alert, which a screen reader interrupts for. Use status for text that keeps
+   * 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-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", className, children }: AlertProps) {
+  return (
+    <div className={cx("rounded-alert border px-3 py-2 text-sm", styles[variant], className)} role={role}>
+      {children}
+    </div>
+  );
+}

package/src/ui/PasswordInput.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
+import { useId, useState, type InputHTMLAttributes } from "react";
+import { cx } from "./cx";
+
+/** 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({
+  label,
+  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 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 ?? generated;
+  // Built from useId rather than the name, since an id list in aria-describedby splits on spaces.
+  const errorId = `${generated}-error`;
+
+  return (
+    <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-field-required"> *</span>}
+      </label>
+      <div className="relative">
+        <input
+          {...props}
+          id={inputId}
+          type={visible ? "text" : "password"}
+          required={required}
+          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-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 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(" ");
+}

package/src/ui/index.ts

@@ -0,0 +1,4 @@
+export { Alert } from "./Alert";
+export type { AlertProps } from "./Alert";
+export { PasswordInput } from "./PasswordInput";
+export type { PasswordInputProps } from "./PasswordInput";