@sjolystinnovation/app-kit 0.1.0 → 0.2.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,62 @@ 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)`
+
+`(error: unknown, fallback: string) => 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`.
+
+```ts
+try {
+  await api.post("/users", form);
+} catch (error) {
+  setError(formatApiError(error, "Could not create the user."));
+}
+```
+
+### `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. |
+| `children` | `ReactNode` | | Content. |
+
+### `PasswordInput`
+
+A labelled password field with a button that shows and hides the value. Accepts every `<input>`
+attribute as well.
+
+```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, which also turns the border red. |
+| `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. |
+
+Pass the two toggle labels in the app's language. The defaults are English.
+
 ## 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.
 - 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.2.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,29 @@
+import axios from "axios";
+
+interface ApiErrorBody {
+  message?: string;
+  detail?: string;
+  title?: string;
+  errors?: Record<string, string[]>;
+}
+
+/**
+ * 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`.
+ */
+export function formatApiError(error: unknown, fallback: string): string {
+  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];
+    }
+    if (data?.detail) return data.detail;
+    if (data?.title) return data.title;
+  }
+  if (error instanceof Error) return error.message;
+  return fallback;
+}

package/src/index.ts

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

package/src/styles.css

@@ -0,0 +1,2 @@
+/* Adds this package's components to the files Tailwind scans for class names. */
+@source ".";

package/src/ui/Alert.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+
+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";
+  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",
+};
+
+export function Alert({ variant = "info", role = "alert", children }: AlertProps) {
+  return (
+    <div className={`rounded-lg border px-3 py-2 text-sm ${styles[variant]}`} role={role}>
+      {children}
+    </div>
+  );
+}

package/src/ui/PasswordInput.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
+import { useId, useState, type InputHTMLAttributes } from "react";
+
+export interface PasswordInputProps extends InputHTMLAttributes<HTMLInputElement> {
+  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;
+}
+
+export function PasswordInput({
+  label,
+  error,
+  id,
+  required,
+  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.
+  const generated = useId();
+  const inputId = id ?? props.name ?? generated;
+
+  return (
+    <div>
+      <label htmlFor={inputId} className="block text-sm font-medium text-gray-700 mb-1">
+        {label}
+        {required && <span className="text-red-600"> *</span>}
+      </label>
+      <div className="relative">
+        <input
+          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}
+        />
+        <button
+          type="button"
+          onClick={() => setVisible((v) => !v)}
+          className="absolute inset-y-0 right-0 px-3 text-gray-400 hover:text-gray-600"
+          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>}
+    </div>
+  );
+}

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";