@tristan2828/ui-foundation 3.30.0 → 4.0.0

package/conventions/docs/cell-patterns.md

@@ -688,6 +688,12 @@ Save button, no Undo:
 | `choice`: a select, a switch, a single reference | the pick (its list opens with the field, non-modal) | closes the list with nothing picked: gives up |
 | `multi`: a multi reference | leaving it, or Ctrl/Cmd+Enter (Enter picks) | closes the list first; Esc again gives up |
 
+In either multi picker (`MultiChoice`, `MultiReference`), on a form, in
+a toolbar filter or in place, Escape never removes a pick: it closes the
+list when it's open and leaves the value alone when it's closed (Base UI
+would empty it). A pick comes off only by its chip's remove button,
+Backspace in the empty input, or unpicking it in the list.
+
 Leaving means clicking or tabbing anywhere else. Unchanged closes with no
 request; a value the form's schema refuses never leaves the browser and
 shows the schema's message. Opening another value saves the open one

package/dist/api/contracts.d.ts

@@ -5,9 +5,14 @@ export type Page<T> = {
     pageSize: number;
 };
 export type AppError = {
-    kind: "validation" | "notfound" | "auth" | "server" | "network";
+    kind: "validation" | "notfound" | "auth" | "rate_limited" | "server" | "network";
     message: string;
     fieldErrors?: Record<string, string[]>;
+    /**
+     * kind "rate_limited" (a 429): seconds until another attempt is allowed,
+     * from the response's Retry-After. Absent when the server didn't say.
+     */
+    retryAfterSeconds?: number;
 };
 export type QuerySpec = {
     page: number;

package/dist/api/gateway/auth.d.ts

@@ -2,7 +2,25 @@ import type { components } from "../schema.js";
 type User = components["schemas"]["User"];
 type LoginRequest = components["schemas"]["LoginRequest"];
 type RegisterRequest = components["schemas"]["RegisterRequest"];
-export declare function login(input: LoginRequest): Promise<User>;
+type TotpLoginRequest = components["schemas"]["TotpLoginRequest"];
+/** Signed in (200), or the password was right and a TOTP code is next (202). */
+export type LoginStep = {
+    user: User;
+} | {
+    next: "totp";
+};
+export declare function login(input: LoginRequest): Promise<LoginStep>;
+/**
+ * Signed in, or the pending sign-in is gone (410: expired, or out of tries)
+ * and it starts again from the password, with the server's reason. A wrong
+ * code is an AppError of kind 'auth' (401).
+ */
+export type TotpStep = {
+    user: User;
+} | {
+    restart: string;
+};
+export declare function loginTotp(input: TotpLoginRequest): Promise<TotpStep>;
 export declare function register(input: RegisterRequest): Promise<User>;
 export declare function logout(): Promise<void>;
 export declare function getCurrentUser(): Promise<User>;

package/dist/api/gateway/auth.js

@@ -1,13 +1,31 @@
 import { safeFetch, toAppError } from "./errors.js";
+// A 429 (too many failed attempts) is an AppError of kind 'rate_limited'
+// with the Retry-After seconds, as on every endpoint (toAppError).
 export async function login(input) {
     const res = await safeFetch("/auth/login", {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(input),
     });
+    if (res.status === 202)
+        return { next: "totp" };
     if (res.status !== 200)
-        throw toAppError(res.status, res.body);
-    return res.body;
+        throw toAppError(res.status, res.body, res.headers);
+    return { user: res.body };
+}
+export async function loginTotp(input) {
+    const res = await safeFetch("/auth/login/totp", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    if (res.status === 410) {
+        const detail = res.body?.detail;
+        return { restart: detail ?? "Your sign-in timed out. Enter your email and password again." };
+    }
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body, res.headers);
+    return { user: res.body };
 }
 // Auto-logs in on success — the backend sets the same session cookie
 // /auth/login does (see backend/app/routers/auth.py's _start_session), so

package/dist/api/gateway/errors.d.ts

@@ -1,5 +1,9 @@
 import { type ApiResponse } from "../transport/index.js";
 import type { AppError } from "../contracts.js";
 export declare function safeFetch(path: string, init?: RequestInit): Promise<ApiResponse>;
-export declare function toAppError(status: number, body: unknown): AppError;
+/**
+ * Pass the response's `headers` so a 429 carries its Retry-After
+ * (`retryAfterSeconds`); without them it's still `rate_limited`.
+ */
+export declare function toAppError(status: number, body: unknown, headers?: Headers): AppError;
 export declare function networkError(): AppError;

package/dist/api/gateway/errors.js

@@ -11,7 +11,11 @@ export async function safeFetch(path, init) {
         throw networkError();
     }
 }
-export function toAppError(status, body) {
+/**
+ * Pass the response's `headers` so a 429 carries its Retry-After
+ * (`retryAfterSeconds`); without them it's still `rate_limited`.
+ */
+export function toAppError(status, body, headers) {
     if (status === 422) {
         // A rule the server enforces (a cap, a status the change needs) is
         // often refused with FastAPI's HTTPException shape: a sentence, not a
@@ -32,8 +36,25 @@ export function toAppError(status, body) {
         return { kind: "notfound", message };
     if (status === 401)
         return { kind: "auth", message };
+    if (status === 429) {
+        const retryAfterSeconds = parseRetryAfter(headers?.get("retry-after") ?? null);
+        return retryAfterSeconds === undefined
+            ? { kind: "rate_limited", message }
+            : { kind: "rate_limited", message, retryAfterSeconds };
+    }
     return { kind: "server", message };
 }
+// Retry-After is either whole seconds or an HTTP date (RFC 9110 10.2.3).
+function parseRetryAfter(value) {
+    if (value === null || value.trim() === "")
+        return undefined;
+    if (/^\d+$/.test(value.trim()))
+        return Number(value.trim());
+    const at = Date.parse(value);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
 // The key a form binds a 422 to (react-hook-form's field path):
 // - ["body", "price"] → "price"
 // - ["body", "tags", 0] → "tags": an item of a list of values is the list's

package/dist/api/schema.d.ts

@@ -20,6 +20,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/login/totp": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * The second step of a sign-in, a code from an authenticator app or a recovery code
+         * @description Needs the pending_login cookie a 202 from POST /auth/login set. A right code starts the session as a 200 from /auth/login does.
+         */
+        post: operations["loginTotp"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/register": {
         parameters: {
             query?: never;
@@ -110,6 +130,17 @@ export interface components {
             email: string;
             password: string;
         };
+        LoginNextStep: {
+            /**
+             * @description The step the sign-in still needs.
+             * @enum {string}
+             */
+            next: "totp";
+        };
+        TotpLoginRequest: {
+            /** @description The 6-digit code from the authenticator app, or a recovery code. */
+            code: string;
+        };
         RegisterRequest: {
             email: components["schemas"]["User"]["email"];
             name: components["schemas"]["User"]["name"];
@@ -156,6 +187,26 @@ export interface components {
                 "application/json": components["schemas"]["HTTPErrorBody"];
             };
         };
+        /** @description Too many failed attempts. Try again after Retry-After seconds. */
+        RateLimitedError: {
+            headers: {
+                /** @description Seconds until another attempt is allowed. */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["HTTPErrorBody"];
+            };
+        };
+        /** @description The pending sign-in is missing, expired or out of tries. Start again with POST /auth/login. */
+        SignInExpiredError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["HTTPErrorBody"];
+            };
+        };
         /** @description Unhandled server error. */
         ServerError: {
             headers: {
@@ -185,6 +236,43 @@ export interface operations {
                 "application/json": components["schemas"]["LoginRequest"];
             };
         };
+        responses: {
+            /** @description Authenticated. Sets the session_id cookie. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            /** @description The password is right and the account has a second step. No session yet: sets a short-lived, single-use pending_login cookie for POST /auth/login/totp. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LoginNextStep"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            422: components["responses"]["ValidationError"];
+            429: components["responses"]["RateLimitedError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    loginTotp: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TotpLoginRequest"];
+            };
+        };
         responses: {
             /** @description Authenticated. Sets the session_id cookie. */
             200: {
@@ -196,7 +284,9 @@ export interface operations {
                 };
             };
             401: components["responses"]["UnauthorizedError"];
+            410: components["responses"]["SignInExpiredError"];
             422: components["responses"]["ValidationError"];
+            429: components["responses"]["RateLimitedError"];
             500: components["responses"]["ServerError"];
         };
     };

package/dist/api/transport/index.d.ts

@@ -1,5 +1,7 @@
 export type ApiResponse = {
     status: number;
     body: unknown;
+    /** The response's headers (a 429's Retry-After, for one). */
+    headers: Headers;
 };
 export declare function apiFetch(path: string, init?: RequestInit): Promise<ApiResponse>;

package/dist/api/transport/index.js

@@ -7,8 +7,8 @@ const BASE_URL = "/api";
 export async function apiFetch(path, init) {
     const response = await fetch(`${BASE_URL}${path}`, init);
     if (response.status === 204) {
-        return { status: response.status, body: undefined };
+        return { status: response.status, body: undefined, headers: response.headers };
     }
     const body = await response.json().catch(() => undefined);
-    return { status: response.status, body };
+    return { status: response.status, body, headers: response.headers };
 }

package/dist/auth/auth-context.d.ts

@@ -5,6 +5,24 @@ export type AuthUser = {
     email: string;
 };
 export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable';
+/**
+ * Where a sign-in stands after `login` or `submitTotp`:
+ * - `signed-in`: the session started.
+ * - `totp`: the password was right; the account wants a code next
+ *   (`submitTotp`), and no session exists yet.
+ * - `restart`: the sign-in waiting for its code is gone (it expired, or
+ *   ran out of tries); start again from the password. `message` says why.
+ * Anything else (a wrong password or code, too many attempts, the server
+ * down) rejects with an AppError.
+ */
+export type SignInResult = {
+    status: 'signed-in';
+} | {
+    status: 'totp';
+} | {
+    status: 'restart';
+    message: string;
+};
 export type AuthContextValue = {
     user: AuthUser | null;
     status: AuthStatus;
@@ -12,7 +30,9 @@ export type AuthContextValue = {
     error: AppError | null;
     /** Re-runs the session check (the 'unavailable' state's retry). */
     retry: () => void;
-    login: (email: string, password: string) => Promise<void>;
+    login: (email: string, password: string) => Promise<SignInResult>;
+    /** The second step, after `login` answered `totp`: an authenticator code or a recovery code. */
+    submitTotp: (code: string) => Promise<SignInResult>;
     logout: () => Promise<void>;
     register: (email: string, name: string, password: string) => Promise<void>;
 };

package/dist/auth/auth-context.js

@@ -6,7 +6,8 @@ export const AuthContext = createContext({
     status: 'loading',
     error: null,
     retry: () => { },
-    login: async () => { },
+    login: async () => ({ status: 'signed-in' }),
+    submitTotp: async () => ({ status: 'signed-in' }),
     logout: async () => { },
     register: async () => { },
 });

package/dist/auth/auth-provider.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { getCurrentUser, login as loginRequest, logout as logoutRequest, register as registerRequest, } from '../api/gateway/auth.js';
+import { getCurrentUser, login as loginRequest, loginTotp as loginTotpRequest, logout as logoutRequest, register as registerRequest, } from '../api/gateway/auth.js';
 import { DATA_LABEL_QUERY_KEY } from '../hooks/use-data-label.js';
 import { AuthContext } from './auth-context.js';
 // TanStack Query, not useEffect — AGENTS.md's "NEVER fetch in useEffect"
@@ -83,8 +83,21 @@ export function AuthProvider({ children }) {
                 : error
                     ? 'unavailable'
                     : 'unauthenticated';
+    // With TOTP on, the password alone starts nothing: the server holds a
+    // pending sign-in (its own short-lived cookie) until the code arrives.
     async function login(email, password) {
-        startSession(queryClient, await loginRequest({ email, password }));
+        const step = await loginRequest({ email, password });
+        if ('next' in step)
+            return { status: 'totp' };
+        startSession(queryClient, step.user);
+        return { status: 'signed-in' };
+    }
+    async function submitTotp(code) {
+        const step = await loginTotpRequest({ code });
+        if ('restart' in step)
+            return { status: 'restart', message: step.restart };
+        startSession(queryClient, step.user);
+        return { status: 'signed-in' };
     }
     // Logged out on screen even when the request fails (network down): the
     // person asked to leave, and a shell that still shows them signed in is
@@ -106,6 +119,7 @@ export function AuthProvider({ children }) {
             error: status === 'unavailable' ? error : null,
             retry: () => void refetch(),
             login,
+            submitTotp,
             logout,
             register,
         }, children: children }));

package/dist/components/app/error-state.js

@@ -18,6 +18,7 @@ const TITLE_BY_KIND = {
     server: 'Something went wrong',
     notfound: 'Not found',
     auth: 'Not authorized',
+    rate_limited: 'Too many attempts',
     validation: 'Check the form',
 };
 export function ErrorState({ error, onRetry, size = 'default', className, }) {

package/dist/components/app/multi-choice.js

@@ -13,5 +13,17 @@ import * as React from 'react';
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
 export function MultiChoice({ options, value, onValueChange, getLabel = String, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
     const anchor = useComboboxAnchor();
-    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next) => onValueChange(next), itemToStringLabel: getLabel, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: getLabel(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: getLabel(option) }, option)) })] })] }));
+    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next, details) => {
+            // Base UI empties the value on Escape while the list is closed, so
+            // a second Escape after a pick wiped every chip (issue #123). Escape
+            // never removes picks here: a chip's remove button, Backspace or
+            // unpicking in the list does. Let the key go on, so a dialog or an
+            // edit in place gets its own Escape.
+            if (details.reason === 'escape-key') {
+                details.cancel();
+                details.allowPropagation();
+                return;
+            }
+            onValueChange(next);
+        }, itemToStringLabel: getLabel, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: getLabel(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: getLabel(option) }, option)) })] })] }));
 }

package/dist/components/app/multi-reference.js

@@ -27,7 +27,19 @@ export function MultiReference({ options, value, onValueChange, getLabel, onSear
     return (_jsxs(Combobox, { multiple: true, autoHighlight: true, 
         // Ids, not {id,label} objects: Base UI compares items to the value
         // with Object.is, so the items must have the value's own shape.
-        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, readOnly: readOnly, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, onKeyDown: (event) => {
+        items: options.map((option) => option.id), value: value, onValueChange: (next, details) => {
+            // Base UI empties the value on Escape while the list is closed, so
+            // a second Escape after a pick wiped every chip (issue #123). Escape
+            // never removes picks here: a chip's remove button, Backspace or
+            // unpicking in the list does. Let the key go on, so a dialog or an
+            // edit in place gets its own Escape.
+            if (details.reason === 'escape-key') {
+                details.cancel();
+                details.allowPropagation();
+                return;
+            }
+            onValueChange(next);
+        }, onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, readOnly: readOnly, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, onKeyDown: (event) => {
                                     if (searching && event.key === 'Enter') {
                                         event.preventDefault();
                                         event.preventBaseUIHandler();

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.js';
 export { returnPath } from './routes/return-path.js';
 export { AuthProvider, useAuth } from './auth/use-auth.js';
-export type { AuthContextValue, AuthStatus, AuthUser } from './auth/auth-context.js';
+export type { AuthContextValue, AuthStatus, AuthUser, SignInResult } from './auth/auth-context.js';
 export type { AppError, Page, QuerySpec } from './api/contracts.js';
 export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';

package/dist/mocks/auth.d.ts

@@ -2,6 +2,9 @@ import type { components } from '../api/schema.js';
 type User = components['schemas']['User'];
 export declare const MOCK_USER: User;
 export declare const MOCK_PASSWORD = "dev-password-123";
+export declare const MOCK_TOTP_USER: User;
+export declare const MOCK_TOTP_CODE = "123456";
+export declare const MOCK_RECOVERY_CODE = "abcd-efgh";
 export declare function isMockAuthenticated(): boolean;
 export declare function setMockAuthenticated(value: boolean): void;
 /**

package/dist/mocks/auth.js

@@ -8,6 +8,14 @@ import { http, HttpResponse } from 'msw';
 // logging in behaves the same whether MSW or the real API answers.
 export const MOCK_USER = { id: 1, email: 'dev@example.com', name: 'Dev User' };
 export const MOCK_PASSWORD = 'dev-password-123';
+// An account with two-step sign-in, for an app's e2e test of both steps:
+// MOCK_PASSWORD, then MOCK_TOTP_CODE (always right, as a fixed clock would
+// make it) or MOCK_RECOVERY_CODE (once per reset). Five wrong codes end
+// the pending sign-in (410), as the reference backend does.
+export const MOCK_TOTP_USER = { id: 1001, email: 'two-step@example.com', name: 'Two Step User' };
+export const MOCK_TOTP_CODE = '123456';
+export const MOCK_RECOVERY_CODE = 'abcd-efgh';
+const PENDING_MAX_TRIES = 5;
 // Signed in by default: screen specs assume access, and only auth specs
 // exercise the logged-out path (by overriding GET /auth/me to 401).
 let authenticated = true;
@@ -16,6 +24,10 @@ let authenticated = true;
 let registeredUsers = new Map([[MOCK_USER.email, MOCK_USER]]);
 let currentUser = MOCK_USER;
 let nextUserId = 2;
+// The pending sign-in after MOCK_TOTP_USER's password: wrong codes so far,
+// or null when none is waiting.
+let pendingTries = null;
+let recoveryCodeUsed = false;
 export function isMockAuthenticated() {
     return authenticated;
 }
@@ -36,6 +48,8 @@ export function resetMockAuth() {
     registeredUsers = new Map([[MOCK_USER.email, MOCK_USER]]);
     currentUser = MOCK_USER;
     nextUserId = 2;
+    pendingTries = null;
+    recoveryCodeUsed = false;
 }
 export const authHandlers = [
     http.post('*/api/auth/register', async ({ request }) => {
@@ -68,6 +82,10 @@ export const authHandlers = [
     }),
     http.post('*/api/auth/login', async ({ request }) => {
         const body = (await request.json());
+        if (body.email === MOCK_TOTP_USER.email && body.password === MOCK_PASSWORD) {
+            pendingTries = 0;
+            return HttpResponse.json({ next: 'totp' }, { status: 202 });
+        }
         if (body.email !== MOCK_USER.email || body.password !== MOCK_PASSWORD) {
             return HttpResponse.json({ detail: 'Invalid email or password' }, { status: 401 });
         }
@@ -75,6 +93,27 @@ export const authHandlers = [
         authenticated = true;
         return HttpResponse.json(MOCK_USER);
     }),
+    http.post('*/api/auth/login/totp', async ({ request }) => {
+        const { code } = (await request.json());
+        if (pendingTries === null) {
+            return HttpResponse.json({ detail: 'Your sign-in timed out. Enter your email and password again.' }, { status: 410 });
+        }
+        const recovery = !recoveryCodeUsed && code.trim().toLowerCase() === MOCK_RECOVERY_CODE;
+        if (code.trim() === MOCK_TOTP_CODE || recovery) {
+            if (recovery)
+                recoveryCodeUsed = true;
+            pendingTries = null;
+            currentUser = MOCK_TOTP_USER;
+            authenticated = true;
+            return HttpResponse.json(MOCK_TOTP_USER);
+        }
+        pendingTries += 1;
+        if (pendingTries >= PENDING_MAX_TRIES) {
+            pendingTries = null;
+            return HttpResponse.json({ detail: 'Too many wrong codes. Enter your email and password again.' }, { status: 410 });
+        }
+        return HttpResponse.json({ detail: "That code isn't right. Check it and try again." }, { status: 401 });
+    }),
     http.post('*/api/auth/logout', () => {
         authenticated = false;
         return new HttpResponse(null, { status: 204 });

package/dist/mocks/e2e-hooks.js

@@ -19,10 +19,10 @@ export function exposeMswForE2E(worker) {
                 const bytes = Uint8Array.from(atob(override.bodyBase64), (character) => character.charCodeAt(0));
                 return new HttpResponse(bytes, {
                     status: override.status ?? 200,
-                    headers: { 'Content-Type': override.contentType ?? 'application/octet-stream' },
+                    headers: { 'Content-Type': override.contentType ?? 'application/octet-stream', ...override.headers },
                 });
             }
-            return HttpResponse.json(override.body ?? {}, { status: override.status ?? 200 });
+            return HttpResponse.json(override.body ?? {}, { status: override.status ?? 200, headers: override.headers });
         }));
     }
 }

package/dist/mocks/index.d.ts

@@ -1,4 +1,4 @@
-export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { environmentHandlers } from './environment.js';
 export { exposeMswForE2E } from './e2e-hooks.js';
 export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -1,6 +1,6 @@
 // `@tristan2828/ui-foundation/mocks` — MSW support. A separate entry point
 // so msw (an optional peer dependency) never reaches an app's main bundle
 // unless it imports this.
-export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { environmentHandlers } from './environment.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/mocks/override.d.ts

@@ -8,6 +8,8 @@ export type MswOverride = {
     delayMs?: number;
     bodyBase64?: string;
     contentType?: string;
+    /** Response headers, e.g. a 429's `Retry-After`. */
+    headers?: Record<string, string>;
 };
 export type MswHandle = {
     worker: SetupWorker;

package/dist/routes/login-schema.d.ts

@@ -5,3 +5,10 @@ export declare const loginFormSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type LoginFormValues = z.infer<typeof loginFormSchema>;
 export declare const LOGIN_FORM_DEFAULTS: LoginFormValues;
+export declare const totpCodeFormSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+export declare const recoveryCodeFormSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+export type CodeFormValues = z.infer<typeof totpCodeFormSchema>;

package/dist/routes/login-schema.js

@@ -11,3 +11,11 @@ export const LOGIN_FORM_DEFAULTS = {
     email: '',
     password: '',
 };
+// The second step, when the account has TOTP: six digits from an
+// authenticator app, or (switched to) one of the account's recovery codes.
+export const totpCodeFormSchema = z.object({
+    code: z.string().trim().regex(/^\d{6}$/, 'Enter the 6-digit code from your authenticator app'),
+});
+export const recoveryCodeFormSchema = z.object({
+    code: z.string().trim().min(1, 'Enter a recovery code').max(64, 'That is longer than a recovery code'),
+});

package/dist/routes/login.js

@@ -5,26 +5,71 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // chrome (title + Cancel + Submit), and a login screen has no "cancel"
 // destination — so this uses the same mandated FieldGroup/Field primitives
 // directly (AGENTS.md "Correct Patterns").
+//
+// Two steps when the account has TOTP (4.0): the password, then a code
+// from an authenticator app or a recovery code. No session exists between
+// them; the server keeps a pending sign-in for a few minutes, and when it
+// has gone (expired, out of tries) the screen goes back to the password
+// with the reason.
 import { zodResolver } from '@hookform/resolvers/zod';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { Link, useLocation, useNavigate } from 'react-router';
 import { useAuth } from '../auth/use-auth.js';
 import { ErrorState } from '../components/app/error-state.js';
 import { PasswordInput } from '../components/app/password-input.js';
 import { Button } from '../components/ui/button.js';
-import { Card, CardContent, CardHeader, CardTitle } from '../components/ui/card.js';
-import { Field, FieldError, FieldGroup, FieldLabel } from '../components/ui/field.js';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../components/ui/card.js';
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from '../components/ui/field.js';
 import { Input } from '../components/ui/input.js';
 import { Spinner } from '../components/ui/spinner.js';
-import { LOGIN_FORM_DEFAULTS, loginFormSchema } from './login-schema.js';
+import { LOGIN_FORM_DEFAULTS, loginFormSchema, recoveryCodeFormSchema, totpCodeFormSchema, } from './login-schema.js';
 import { returnPath } from './return-path.js';
+// A refusal for too many attempts holds the submit button until the
+// server's Retry-After has passed, so the screen never offers a retry it
+// knows will be refused.
+function useRateLimitHold(error) {
+    // The refusal whose wait has passed; the button holds until it's this one.
+    const [released, setReleased] = useState(null);
+    useEffect(() => {
+        if (error?.kind !== 'rate_limited')
+            return;
+        const seconds = error.retryAfterSeconds ?? 60;
+        const timer = window.setTimeout(() => setReleased(error), seconds * 1000);
+        return () => window.clearTimeout(timer);
+    }, [error]);
+    return error?.kind === 'rate_limited' && released !== error;
+}
 export function LoginRoute({ registerPath = '/register' } = {}) {
-    const { login } = useAuth();
     const navigate = useNavigate();
     const location = useLocation();
+    const [step, setStep] = useState('password');
+    // Why the screen came back to the password from the code step.
+    const [restartReason, setRestartReason] = useState(null);
+    const onResult = (result) => {
+        if (result.status === 'signed-in') {
+            navigate(returnPath(location.state), { replace: true });
+        }
+        else if (result.status === 'totp') {
+            setRestartReason(null);
+            setStep('code');
+        }
+        else {
+            setRestartReason(result.message);
+            setStep('password');
+        }
+    };
+    return (_jsx("main", { className: "flex min-h-screen items-center justify-center bg-background p-6", children: _jsxs(Card, { className: "w-full max-w-sm", children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { className: "text-lg", children: _jsx("h1", { children: "Sign in" }) }), step === 'code' && _jsx(CardDescription, { children: "Your account has two-step sign-in." })] }), _jsx(CardContent, { children: step === 'password' ? (_jsx(PasswordStep, { registerPath: registerPath, restartReason: restartReason, onResult: onResult })) : (_jsx(CodeStep, { onResult: onResult, onStartOver: () => {
+                            setRestartReason(null);
+                            setStep('password');
+                        } })) })] }) }));
+}
+function PasswordStep({ registerPath, restartReason, onResult, }) {
+    const { login } = useAuth();
+    const location = useLocation();
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [submitError, setSubmitError] = useState(null);
+    const held = useRateLimitHold(submitError);
     const form = useForm({
         resolver: zodResolver(loginFormSchema),
         defaultValues: LOGIN_FORM_DEFAULTS,
@@ -33,8 +78,7 @@ export function LoginRoute({ registerPath = '/register' } = {}) {
         setSubmitError(null);
         setIsSubmitting(true);
         try {
-            await login(values.email, values.password);
-            navigate(returnPath(location.state), { replace: true });
+            onResult(await login(values.email, values.password));
         }
         catch (err) {
             const error = err;
@@ -46,7 +90,46 @@ export function LoginRoute({ registerPath = '/register' } = {}) {
             else {
                 // 401 lands here as one form-level message — never bound to the
                 // email or password field individually, so a failed attempt can't
-                // be used to confirm which part was wrong.
+                // be used to confirm which part was wrong. So does a 429.
+                setSubmitError(error);
+            }
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    });
+    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex flex-col gap-6", children: [restartReason && _jsx(FieldError, { children: restartReason }), _jsxs(FieldGroup, { children: [_jsxs(Field, { "data-invalid": !!form.formState.errors.email, children: [_jsx(FieldLabel, { htmlFor: "login-email", children: "Email" }), _jsx(Input, { id: "login-email", type: "email", autoComplete: "username", "aria-invalid": !!form.formState.errors.email, ...form.register('email') }), _jsx(FieldError, { errors: [form.formState.errors.email] })] }), _jsxs(Field, { "data-invalid": !!form.formState.errors.password, children: [_jsx(FieldLabel, { htmlFor: "login-password", children: "Password" }), _jsx(PasswordInput, { id: "login-password", autoComplete: "current-password", "aria-invalid": !!form.formState.errors.password, ...form.register('password') }), _jsx(FieldError, { errors: [form.formState.errors.password] })] })] }), submitError && _jsx(ErrorState, { error: submitError }), _jsxs(Button, { type: "submit", disabled: isSubmitting || held, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), "Sign in"] }), registerPath !== null && (_jsx(Button, { variant: "link", size: "sm", nativeButton: false, render: _jsx(Link, { to: registerPath, state: location.state }), children: "Create account" }))] }));
+}
+function CodeStep({ onResult, onStartOver, }) {
+    const [recovery, setRecovery] = useState(false);
+    // A fresh form per mode: its own schema, an empty field, and the
+    // browser's one-time-code autofill and numeric keypad following the mode.
+    return (_jsx(CodeForm, { recovery: recovery, onSwitchMode: () => setRecovery((value) => !value), onResult: onResult, onStartOver: onStartOver }, recovery ? 'recovery' : 'totp'));
+}
+function CodeForm({ recovery, onSwitchMode, onResult, onStartOver, }) {
+    const { submitTotp } = useAuth();
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [submitError, setSubmitError] = useState(null);
+    const held = useRateLimitHold(submitError);
+    const form = useForm({
+        resolver: zodResolver(recovery ? recoveryCodeFormSchema : totpCodeFormSchema),
+        defaultValues: { code: '' },
+    });
+    // The field takes the caret when the step (or the mode) appears.
+    useEffect(() => form.setFocus('code'), [form]);
+    const onSubmit = form.handleSubmit(async (values) => {
+        setSubmitError(null);
+        setIsSubmitting(true);
+        try {
+            onResult(await submitTotp(values.code));
+        }
+        catch (err) {
+            const error = err;
+            if (error.kind === 'auth' || (error.kind === 'validation' && error.fieldErrors?.code)) {
+                // A wrong code is the field's error: the code is the only thing typed.
+                form.setError('code', { message: error.fieldErrors?.code?.[0] ?? error.message }, { shouldFocus: true });
+            }
+            else {
                 setSubmitError(error);
             }
         }
@@ -54,5 +137,8 @@ export function LoginRoute({ registerPath = '/register' } = {}) {
             setIsSubmitting(false);
         }
     });
-    return (_jsx("main", { className: "flex min-h-screen items-center justify-center bg-background p-6", children: _jsxs(Card, { className: "w-full max-w-sm", children: [_jsx(CardHeader, { children: _jsx(CardTitle, { className: "text-lg", children: _jsx("h1", { children: "Sign in" }) }) }), _jsx(CardContent, { children: _jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex flex-col gap-6", children: [_jsxs(FieldGroup, { children: [_jsxs(Field, { "data-invalid": !!form.formState.errors.email, children: [_jsx(FieldLabel, { htmlFor: "login-email", children: "Email" }), _jsx(Input, { id: "login-email", type: "email", autoComplete: "username", "aria-invalid": !!form.formState.errors.email, ...form.register('email') }), _jsx(FieldError, { errors: [form.formState.errors.email] })] }), _jsxs(Field, { "data-invalid": !!form.formState.errors.password, children: [_jsx(FieldLabel, { htmlFor: "login-password", children: "Password" }), _jsx(PasswordInput, { id: "login-password", autoComplete: "current-password", "aria-invalid": !!form.formState.errors.password, ...form.register('password') }), _jsx(FieldError, { errors: [form.formState.errors.password] })] })] }), submitError && _jsx(ErrorState, { error: submitError }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), "Sign in"] }), registerPath !== null && (_jsx(Button, { variant: "link", size: "sm", nativeButton: false, render: _jsx(Link, { to: registerPath, state: location.state }), children: "Create account" }))] }) })] }) }));
+    const invalid = !!form.formState.errors.code;
+    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex flex-col gap-6", children: [_jsx(FieldGroup, { children: _jsxs(Field, { "data-invalid": invalid, children: [_jsx(FieldLabel, { htmlFor: "login-code", children: recovery ? 'Recovery code' : 'Authentication code' }), _jsx(Input, { id: "login-code", autoComplete: recovery ? 'off' : 'one-time-code', inputMode: recovery ? 'text' : 'numeric', spellCheck: false, "aria-invalid": invalid, "aria-describedby": "login-code-description", ...form.register('code') }), _jsx(FieldDescription, { id: "login-code-description", children: recovery
+                                ? 'One of the recovery codes you saved when two-step sign-in was turned on. Each works once.'
+                                : 'The 6-digit code your authenticator app shows for this account.' }), _jsx(FieldError, { errors: [form.formState.errors.code] })] }) }), submitError && _jsx(ErrorState, { error: submitError }), _jsxs(Button, { type: "submit", disabled: isSubmitting || held, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), "Verify"] }), _jsxs("div", { className: "flex flex-wrap justify-between gap-2", children: [_jsx(Button, { type: "button", variant: "link", size: "sm", onClick: onSwitchMode, children: recovery ? 'Use your authenticator app' : 'Use a recovery code' }), _jsx(Button, { type: "button", variant: "link", size: "sm", onClick: onStartOver, children: "Start over" })] })] }));
 }

package/openapi/foundation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: UI Foundation — the contract every app shares
-  version: "3.0.0"
+  version: "4.0.0"
   description: >
     The part of an app's API contract that the foundation package's own code
     calls: session-cookie auth under /auth/*, and the two error envelopes the
@@ -30,6 +30,39 @@ paths:
         content:
           application/json:
             schema: { $ref: "#/components/schemas/LoginRequest" }
+      responses:
+        "200":
+          description: Authenticated. Sets the session_id cookie.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "202":
+          description: >
+            The password is right and the account has a second step. No
+            session yet: sets a short-lived, single-use pending_login cookie
+            for POST /auth/login/totp.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LoginNextStep" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "429": { $ref: "#/components/responses/RateLimitedError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /auth/login/totp:
+    x-optional: true
+    post:
+      operationId: loginTotp
+      summary: The second step of a sign-in, a code from an authenticator app or a recovery code
+      description: >
+        Needs the pending_login cookie a 202 from POST /auth/login set. A
+        right code starts the session as a 200 from /auth/login does.
+      tags: [auth]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/TotpLoginRequest" }
       responses:
         "200":
           description: Authenticated. Sets the session_id cookie.
@@ -37,7 +70,9 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/User" }
         "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "410": { $ref: "#/components/responses/SignInExpiredError" }
         "422": { $ref: "#/components/responses/ValidationError" }
+        "429": { $ref: "#/components/responses/RateLimitedError" }
         "500": { $ref: "#/components/responses/ServerError" }
 
   /auth/register:
@@ -127,7 +162,26 @@ components:
       required: [email, password]
       properties:
         email: { type: string, format: email }
-        password: { type: string, minLength: 8 }
+        password: { type: string, minLength: 8, maxLength: 1024 }
+
+    LoginNextStep:
+      type: object
+      required: [next]
+      properties:
+        next:
+          type: string
+          enum: [totp]
+          description: The step the sign-in still needs.
+
+    TotpLoginRequest:
+      type: object
+      required: [code]
+      properties:
+        code:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: The 6-digit code from the authenticator app, or a recovery code.
 
     RegisterRequest:
       type: object
@@ -178,6 +232,20 @@ components:
       content:
         application/json:
           schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    RateLimitedError:
+      description: Too many failed attempts. Try again after Retry-After seconds.
+      headers:
+        Retry-After:
+          description: Seconds until another attempt is allowed.
+          schema: { type: integer, minimum: 1 }
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    SignInExpiredError:
+      description: The pending sign-in is missing, expired or out of tries. Start again with POST /auth/login.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
     ServerError:
       description: Unhandled server error.
       content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.30.0",
+  "version": "4.0.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {