@tristan2828/ui-foundation 3.0.0

package/dist/hooks/table-url-changes.d.ts

@@ -0,0 +1,14 @@
+type Sort = readonly {
+    id: string;
+    desc: boolean;
+}[];
+export type UrlChanges = Record<string, string | string[] | null>;
+export type TableView<F extends string, M extends string> = {
+    filters?: Partial<Record<F, string>>;
+    multiFilters?: Partial<Record<M, string[]>>;
+    sort?: Sort;
+};
+export declare function serializeSort(next: Sort): string | null;
+export declare function applyUrlChanges(previous: URLSearchParams, changes: UrlChanges): URLSearchParams;
+export declare function viewToUrlChanges<F extends string, M extends string>(filterNames: readonly F[], multiFilterNames: readonly M[], view: TableView<F, M>): UrlChanges;
+export {};

package/dist/hooks/table-url-changes.js

@@ -0,0 +1,32 @@
+// The URL-building half of useTableUrlState (./use-table-url-state.ts),
+// kept free of React and of component imports so tests/ can unit-test it.
+export function serializeSort(next) {
+    return next[0] ? `${next[0].id}:${next[0].desc ? 'desc' : 'asc'}` : null;
+}
+// The next query string: each changed key is replaced outright. An array
+// repeats the key, and null or '' removes it. Keys not in `changes` are
+// kept, so unrelated params (and other tables' state) survive.
+export function applyUrlChanges(previous, changes) {
+    const next = new URLSearchParams(previous);
+    for (const [key, value] of Object.entries(changes)) {
+        next.delete(key);
+        if (Array.isArray(value))
+            for (const item of value)
+                next.append(key, item);
+        else if (value !== null && value !== '')
+            next.set(key, value);
+    }
+    return next;
+}
+// A view is "this combination and nothing else": every filter and the sort
+// are set, and any the view doesn't name are cleared. Merging over the
+// current state instead would let a leftover filter silently show something
+// other than the view. Decided with the developer on 2026-09-28.
+export function viewToUrlChanges(filterNames, multiFilterNames, view) {
+    return {
+        ...Object.fromEntries(filterNames.map((name) => [name, view.filters?.[name] ?? ''])),
+        ...Object.fromEntries(multiFilterNames.map((name) => [name, view.multiFilters?.[name] ?? []])),
+        sort: view.sort ? serializeSort(view.sort) : null,
+        page: null,
+    };
+}

package/dist/hooks/use-debounced-value.d.ts

@@ -0,0 +1 @@
+export declare function useDebouncedValue<T>(value: T, delayMs: number): T;

package/dist/hooks/use-debounced-value.js

@@ -0,0 +1,12 @@
+import { useEffect, useState } from 'react';
+// `value`, once it has stopped changing for `delayMs`. Used to keep a
+// search box from sending one request per keystroke; the input itself stays
+// bound to the live value so typing never lags.
+export function useDebouncedValue(value, delayMs) {
+    const [debounced, setDebounced] = useState(value);
+    useEffect(() => {
+        const timeout = setTimeout(() => setDebounced(value), delayMs);
+        return () => clearTimeout(timeout);
+    }, [value, delayMs]);
+    return debounced;
+}

package/dist/hooks/use-mobile.d.ts

@@ -0,0 +1 @@
+export declare function useIsMobile(): boolean;

package/dist/hooks/use-mobile.js

@@ -0,0 +1,14 @@
+import * as React from "react";
+const MOBILE_BREAKPOINT = 768;
+export function useIsMobile() {
+    const [isMobile, setIsMobile] = React.useState(() => window.innerWidth < MOBILE_BREAKPOINT);
+    React.useEffect(() => {
+        const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+        const onChange = () => {
+            setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+        };
+        mql.addEventListener("change", onChange);
+        return () => mql.removeEventListener("change", onChange);
+    }, []);
+    return isMobile;
+}

package/dist/hooks/use-table-url-state.d.ts

@@ -0,0 +1,14 @@
+import type { SortingState } from '../components/app/data-table.js';
+import { type TableView } from './table-url-changes.js';
+export declare function useTableUrlState<F extends string, M extends string = never>(filterNames: readonly F[], multiFilterNames?: readonly M[]): {
+    page: number;
+    sorting: SortingState;
+    filters: Record<F, string>;
+    multiFilters: Record<M, string[]>;
+    setPage: (next: number) => void;
+    setSorting: (next: SortingState) => void;
+    setFilter: (name: F, value: string) => void;
+    setFilters: (changes: Partial<Record<F, string>>) => void;
+    setMultiFilter: (name: M, values: string[]) => void;
+    applyView: (view: TableView<F, M>) => void;
+};

package/dist/hooks/use-table-url-state.js

@@ -0,0 +1,43 @@
+import { useSearchParams } from 'react-router';
+import { applyUrlChanges, serializeSort, viewToUrlChanges } from './table-url-changes.js';
+// A table's page, sort and filters, kept in the URL query string
+// (`?page=2&sort=name:asc&search=mouse&tags=fragile&tags=bulky`) instead of
+// component state, so they survive going to the edit form and back, a
+// refresh, or a shared link. Every update replaces the history entry rather
+// than pushing one — typing in a search box shouldn't fill the back button.
+//
+// Single-value filters are strings ('' when unset). Multi-value filters
+// (multi-choice fields) are string arrays, repeated in the URL the same way
+// the API takes them. Changing the sort or any filter returns to page 1.
+//
+// Every setter is one update(), and must stay one: see setFilters.
+export function useTableUrlState(filterNames, multiFilterNames = []) {
+    const [params, setParams] = useSearchParams();
+    const page = Math.max(1, Math.floor(Number(params.get('page'))) || 1);
+    const [sortField, sortDir] = (params.get('sort') ?? '').split(':');
+    const sorting = sortField ? [{ id: sortField, desc: sortDir === 'desc' }] : [];
+    const filters = Object.fromEntries(filterNames.map((name) => [name, params.get(name) ?? '']));
+    const multiFilters = Object.fromEntries(multiFilterNames.map((name) => [name, params.getAll(name)]));
+    function update(changes) {
+        setParams((previous) => applyUrlChanges(previous, changes), { replace: true });
+    }
+    return {
+        page,
+        sorting,
+        filters,
+        multiFilters,
+        setPage: (next) => update({ page: next > 1 ? String(next) : null }),
+        setSorting: (next) => update({ sort: serializeSort(next), page: null }),
+        setFilter: (name, value) => update({ [name]: value, page: null }),
+        // Several single-value filters in one call — for any user action that
+        // changes more than one (both ends of a date range, "clear all"). Two
+        // setFilter()s in the same tick lose all but the last: react-router
+        // hands each setSearchParams updater the params from the last render,
+        // not the ones the previous updater produced.
+        setFilters: (changes) => update({ ...changes, page: null }),
+        setMultiFilter: (name, values) => update({ [name]: values, page: null }),
+        // Replaces the whole filter + sort state at once — a saved view. See
+        // viewToUrlChanges() for why anything the view doesn't set is cleared.
+        applyView: (view) => update(viewToUrlChanges(filterNames, multiFilterNames, view)),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
+export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
+export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
+export { ErrorState } from './components/app/error-state.js';
+export { FoundationProviders } from './components/app/foundation-providers.js';
+export { MockModeBanner } from './components/app/mock-mode-banner.js';
+export { MultiChoice } from './components/app/multi-choice.js';
+export { PasswordInput } from './components/app/password-input.js';
+export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { ThemeProvider } from './components/theme-provider.js';
+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 { AppError, Page, QuerySpec } from './api/contracts.js';
+export { createQueryClient } from './api/query-client.js';
+export { useTableUrlState } from './hooks/use-table-url-state.js';
+export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
+export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useIsMobile } from './hooks/use-mobile.js';
+export { cn } from './lib/utils.js';

package/dist/index.js

@@ -0,0 +1,28 @@
+// `@tristan2828/ui-foundation` — the foundation-owned layer every app shares.
+// Primitives are imported one per path (`@tristan2828/ui-foundation/ui/button`);
+// the gateway seam, MSW support and Playwright suites have their own entry
+// points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
+// Composites
+export { AppShell } from './components/app/app-shell.js';
+export { DataTable } from './components/app/data-table.js';
+export { EntityForm } from './components/app/entity-form.js';
+export { ErrorState } from './components/app/error-state.js';
+export { FoundationProviders } from './components/app/foundation-providers.js';
+export { MockModeBanner } from './components/app/mock-mode-banner.js';
+export { MultiChoice } from './components/app/multi-choice.js';
+export { PasswordInput } from './components/app/password-input.js';
+export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { ThemeProvider } from './components/theme-provider.js';
+// Screens outside the app shell
+export { LoginRoute } from './routes/login.js';
+export { RegisterRoute } from './routes/register.js';
+export { returnPath } from './routes/return-path.js';
+// Auth — useAuth() is the only way to read it; the provider's internals stay private.
+export { AuthProvider, useAuth } from './auth/use-auth.js';
+export { createQueryClient } from './api/query-client.js';
+// Hooks
+export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useIsMobile } from './hooks/use-mobile.js';
+// Utilities
+export { cn } from './lib/utils.js';

package/dist/lib/utils.d.ts

@@ -0,0 +1 @@
+export { cn } from "cn";

package/dist/lib/utils.js

@@ -0,0 +1 @@
+export { cn } from "cn";

package/dist/mocks/auth.d.ts

@@ -0,0 +1,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 function isMockAuthenticated(): boolean;
+export declare function setMockAuthenticated(value: boolean): void;
+export declare function resetMockAuth(): void;
+export declare const authHandlers: import("msw").HttpHandler[];
+export {};

package/dist/mocks/auth.js

@@ -0,0 +1,79 @@
+// MSW handlers for the foundation's /auth/* contract (openapi/foundation.yaml),
+// against an in-memory session store. An app spreads `authHandlers` into its
+// own handler list and calls `resetMockAuth()` from its own reset, so every
+// app's mocks behave like the reference backend's auth without a copy of it.
+import { http, HttpResponse } from 'msw';
+// Same demo credentials as the reference backend's seeded dev user
+// (backend/app/config.py's SEED_USER_EMAIL/SEED_USER_PASSWORD defaults), so
+// 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';
+// 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;
+// Mirrors the backend's email-uniqueness check and its auto-login on
+// register: a new registration becomes the session's current user.
+let registeredUsers = new Map([[MOCK_USER.email, MOCK_USER]]);
+let currentUser = MOCK_USER;
+let nextUserId = 2;
+export function isMockAuthenticated() {
+    return authenticated;
+}
+export function setMockAuthenticated(value) {
+    authenticated = value;
+}
+export function resetMockAuth() {
+    authenticated = true;
+    registeredUsers = new Map([[MOCK_USER.email, MOCK_USER]]);
+    currentUser = MOCK_USER;
+    nextUserId = 2;
+}
+export const authHandlers = [
+    http.post('*/api/auth/register', async ({ request }) => {
+        const body = (await request.json());
+        // Mirrors the backend's register(): field validation, then the
+        // duplicate-email check, both landing on the same 422 {detail:[...]}.
+        const issues = [];
+        if (!body.name)
+            issues.push({ loc: ['body', 'name'], msg: 'field required', type: 'value_error.missing' });
+        if (!body.email)
+            issues.push({ loc: ['body', 'email'], msg: 'field required', type: 'value_error.missing' });
+        if (!body.password || body.password.length < 8) {
+            issues.push({
+                loc: ['body', 'password'],
+                msg: 'ensure this value has at least 8 characters',
+                type: 'value_error.any_str.min_length',
+            });
+        }
+        if (body.email && registeredUsers.has(body.email)) {
+            issues.push({ loc: ['body', 'email'], msg: 'email already registered', type: 'value_error.email_exists' });
+        }
+        if (issues.length > 0) {
+            return HttpResponse.json({ detail: issues }, { status: 422 });
+        }
+        const user = { id: nextUserId++, email: body.email, name: body.name };
+        registeredUsers.set(user.email, user);
+        currentUser = user;
+        authenticated = true;
+        return HttpResponse.json(user);
+    }),
+    http.post('*/api/auth/login', async ({ request }) => {
+        const body = (await request.json());
+        if (body.email !== MOCK_USER.email || body.password !== MOCK_PASSWORD) {
+            return HttpResponse.json({ detail: 'Invalid email or password' }, { status: 401 });
+        }
+        currentUser = MOCK_USER;
+        authenticated = true;
+        return HttpResponse.json(MOCK_USER);
+    }),
+    http.post('*/api/auth/logout', () => {
+        authenticated = false;
+        return new HttpResponse(null, { status: 204 });
+    }),
+    http.get('*/api/auth/me', () => {
+        if (!authenticated) {
+            return HttpResponse.json({ detail: 'Not authenticated' }, { status: 401 });
+        }
+        return HttpResponse.json(currentUser);
+    }),
+];

package/dist/mocks/e2e-hooks.d.ts

@@ -0,0 +1,3 @@
+import type { SetupWorker } from 'msw/browser';
+import './override.js';
+export declare function exposeMswForE2E(worker: SetupWorker): void;

package/dist/mocks/e2e-hooks.js

@@ -0,0 +1,28 @@
+// Exposes the running MSW worker, plus the handler-building functions, on
+// `window` so Playwright specs can force loading/empty/error/validation
+// states via worker.use(...), and applies a pre-navigation override if a
+// spec set one (see ./override.ts for the protocol).
+//
+// Only ever wired when MSW mocking itself is active (the app's main.tsx
+// checks mock mode first) — there is no real backend or real data behind
+// this in that mode, so there is nothing sensitive to expose.
+import { delay, http, HttpResponse } from 'msw';
+import './override.js';
+export function exposeMswForE2E(worker) {
+    window.__msw = { worker, http, HttpResponse, delay };
+    const override = window.__E2E_MSW_OVERRIDE__;
+    if (override) {
+        worker.use(http[override.method](override.path, async () => {
+            if (override.delayMs)
+                await delay(override.delayMs);
+            if (override.bodyBase64 !== undefined) {
+                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' },
+                });
+            }
+            return HttpResponse.json(override.body ?? {}, { status: override.status ?? 200 });
+        }));
+    }
+}

package/dist/mocks/index.d.ts

@@ -0,0 +1,3 @@
+export { authHandlers, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { exposeMswForE2E } from './e2e-hooks.js';
+export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -0,0 +1,5 @@
+// `@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, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/mocks/override.d.ts

@@ -0,0 +1,23 @@
+import type { SetupWorker } from 'msw/browser';
+import type { delay, http, HttpResponse } from 'msw';
+export type MswOverride = {
+    method: 'get' | 'post' | 'patch' | 'delete';
+    path: string;
+    status?: number;
+    body?: unknown;
+    delayMs?: number;
+    bodyBase64?: string;
+    contentType?: string;
+};
+export type MswHandle = {
+    worker: SetupWorker;
+    http: typeof http;
+    HttpResponse: typeof HttpResponse;
+    delay: typeof delay;
+};
+declare global {
+    interface Window {
+        __msw: MswHandle;
+        __E2E_MSW_OVERRIDE__?: MswOverride;
+    }
+}

package/dist/mocks/override.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const loginFormSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+}, z.core.$strip>;
+export type LoginFormValues = z.infer<typeof loginFormSchema>;
+export declare const LOGIN_FORM_DEFAULTS: LoginFormValues;

package/dist/routes/login-schema.js

@@ -0,0 +1,13 @@
+// Client-side form validation for the login screen. This does not replace
+// the wire-shaped LoginRequest generated into schema.d.ts (AGENTS.md
+// "NEVER hand-write an API type") — the gateway builds that shape itself
+// from these two plain strings.
+import { z } from 'zod';
+export const loginFormSchema = z.object({
+    email: z.string().trim().min(1, 'Email is required').pipe(z.email('Enter a valid email address')),
+    password: z.string().min(1, 'Password is required'),
+});
+export const LOGIN_FORM_DEFAULTS = {
+    email: '',
+    password: '',
+};

package/dist/routes/login.d.ts

@@ -0,0 +1,8 @@
+export type LoginRouteProps = {
+    /**
+     * Where "Create account" links. `null` hides the link, for an app with no
+     * self-service sign-up (accounts made by hand, no /register route).
+     */
+    registerPath?: string | null;
+};
+export declare function LoginRoute({ registerPath }?: LoginRouteProps): import("react").JSX.Element;

package/dist/routes/login.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Screen: /login. The one route AppShell's auth redirect never catches (an
+// app mounts it outside the AppShell route, see template/src/App.tsx). Not built
+// on the EntityForm composite — that's specifically create/edit-an-entity
+// 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").
+import { zodResolver } from '@hookform/resolvers/zod';
+import { 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 { Input } from '../components/ui/input.js';
+import { Spinner } from '../components/ui/spinner.js';
+import { LOGIN_FORM_DEFAULTS, loginFormSchema } from './login-schema.js';
+import { returnPath } from './return-path.js';
+export function LoginRoute({ registerPath = '/register' } = {}) {
+    const { login } = useAuth();
+    const navigate = useNavigate();
+    const location = useLocation();
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [submitError, setSubmitError] = useState(null);
+    const form = useForm({
+        resolver: zodResolver(loginFormSchema),
+        defaultValues: LOGIN_FORM_DEFAULTS,
+    });
+    const onSubmit = form.handleSubmit(async (values) => {
+        setSubmitError(null);
+        setIsSubmitting(true);
+        try {
+            await login(values.email, values.password);
+            navigate(returnPath(location.state), { replace: true });
+        }
+        catch (err) {
+            const error = err;
+            if (error.kind === 'validation' && error.fieldErrors) {
+                for (const [field, messages] of Object.entries(error.fieldErrors)) {
+                    form.setError(field, { message: messages[0] });
+                }
+            }
+            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.
+                setSubmitError(error);
+            }
+        }
+        finally {
+            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" }))] }) })] }) }));
+}

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

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const registerFormSchema: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+    confirmPassword: z.ZodString;
+}, z.core.$strip>;
+export type RegisterFormValues = z.infer<typeof registerFormSchema>;
+export declare const REGISTER_FORM_DEFAULTS: RegisterFormValues;

package/dist/routes/register-schema.js

@@ -0,0 +1,23 @@
+// Client-side form validation for the register screen — same pattern as
+// login-schema.ts. Mirrors RegisterRequest (email, name, password) plus one
+// addition beyond the wire shape: a client-only confirmPassword field, since
+// a mistyped password with no confirmation is a real, cheaply-prevented
+// failure mode.
+import { z } from 'zod';
+export const registerFormSchema = z
+    .object({
+    name: z.string().trim().min(1, 'Name is required').max(200, 'Name must be 200 characters or fewer'),
+    email: z.string().trim().min(1, 'Email is required').pipe(z.email('Enter a valid email address')),
+    password: z.string().min(8, 'Password must be at least 8 characters'),
+    confirmPassword: z.string().min(1, 'Confirm your password'),
+})
+    .refine((values) => values.password === values.confirmPassword, {
+    message: 'Passwords do not match',
+    path: ['confirmPassword'],
+});
+export const REGISTER_FORM_DEFAULTS = {
+    name: '',
+    email: '',
+    password: '',
+    confirmPassword: '',
+};

package/dist/routes/register.d.ts

@@ -0,0 +1 @@
+export declare function RegisterRoute(): import("react").JSX.Element;

package/dist/routes/register.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Screen: /register (self-service sign-up; an app without it doesn't mount
+// this route). Built the same way login.tsx was: FieldGroup/
+// Field directly, not EntityForm — a registration form has no "cancel"
+// destination either.
+import { zodResolver } from '@hookform/resolvers/zod';
+import { 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 { Input } from '../components/ui/input.js';
+import { Spinner } from '../components/ui/spinner.js';
+import { REGISTER_FORM_DEFAULTS, registerFormSchema } from './register-schema.js';
+import { returnPath } from './return-path.js';
+export function RegisterRoute() {
+    const { register } = useAuth();
+    const navigate = useNavigate();
+    const location = useLocation();
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [submitError, setSubmitError] = useState(null);
+    const form = useForm({
+        resolver: zodResolver(registerFormSchema),
+        defaultValues: REGISTER_FORM_DEFAULTS,
+    });
+    const onSubmit = form.handleSubmit(async (values) => {
+        setSubmitError(null);
+        setIsSubmitting(true);
+        try {
+            await register(values.email, values.name, values.password);
+            navigate(returnPath(location.state), { replace: true });
+        }
+        catch (err) {
+            const error = err;
+            if (error.kind === 'validation' && error.fieldErrors) {
+                for (const [field, messages] of Object.entries(error.fieldErrors)) {
+                    if (field in REGISTER_FORM_DEFAULTS) {
+                        form.setError(field, { message: messages[0] });
+                    }
+                    else {
+                        setSubmitError(error);
+                    }
+                }
+            }
+            else {
+                setSubmitError(error);
+            }
+        }
+        finally {
+            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: "Create an account" }) }) }), _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.name, children: [_jsx(FieldLabel, { htmlFor: "register-name", children: "Name" }), _jsx(Input, { id: "register-name", autoComplete: "name", "aria-invalid": !!form.formState.errors.name, ...form.register('name') }), _jsx(FieldError, { errors: [form.formState.errors.name] })] }), _jsxs(Field, { "data-invalid": !!form.formState.errors.email, children: [_jsx(FieldLabel, { htmlFor: "register-email", children: "Email" }), _jsx(Input, { id: "register-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: "register-password", children: "Password" }), _jsx(PasswordInput, { id: "register-password", autoComplete: "new-password", "aria-invalid": !!form.formState.errors.password, ...form.register('password') }), _jsx(FieldError, { errors: [form.formState.errors.password] })] }), _jsxs(Field, { "data-invalid": !!form.formState.errors.confirmPassword, children: [_jsx(FieldLabel, { htmlFor: "register-confirm-password", children: "Confirm password" }), _jsx(PasswordInput, { id: "register-confirm-password", autoComplete: "new-password", "aria-invalid": !!form.formState.errors.confirmPassword, ...form.register('confirmPassword') }), _jsx(FieldError, { errors: [form.formState.errors.confirmPassword] })] })] }), submitError && _jsx(ErrorState, { error: submitError }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), "Create account"] }), _jsx(Button, { variant: "link", size: "sm", nativeButton: false, render: _jsx(Link, { to: "/login", state: location.state }), children: "Sign in instead" })] }) })] }) }));
+}

package/dist/routes/return-path.d.ts

@@ -0,0 +1 @@
+export declare function returnPath(state: unknown): string;

package/dist/routes/return-path.js

@@ -0,0 +1,9 @@
+// Where to go after logging in or registering: the protected page AppShell
+// redirected away from (it passes `{ from }` as router state), else home.
+// Router state can't be set by a link, but only accept an in-app path
+// anyway ("/x", never "//host" or "https://..."), so this can't become an
+// open redirect if a future caller ever feeds it from a query param.
+export function returnPath(state) {
+    const from = state?.from;
+    return typeof from === 'string' && from.startsWith('/') && !from.startsWith('//') ? from : '/';
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,40 @@
+import { type Page } from '@playwright/test';
+import type { MswOverride } from '../mocks/override.js';
+export type { MswHandle, MswOverride } from '../mocks/override.js';
+/**
+ * Forces a response for the page's *first* load: set before navigation, so
+ * it wins the race against the app's own first fetch. For states forced
+ * after load, use `waitForMswReady` and then `window.__msw.worker.use(...)`.
+ */
+export declare function forceMswOverride(page: Page, override: MswOverride): Promise<void>;
+/** `window.__msw` is set only once the app's mocking has started — page.goto's load event doesn't wait for it. */
+export declare function waitForMswReady(page: Page): Promise<void>;
+/** Starts the page logged out: GET /auth/me answers 401 on first load. */
+export declare function forceLoggedOut(page: Page): Promise<void>;
+export declare function expectNoAxeViolations(page: Page): Promise<void>;
+export type A11ySuiteOptions = {
+    /**
+     * Form screens, which aren't in the sidebar: each entity's create route,
+     * plus an edit route when the form shows something only existing data has.
+     */
+    formRoutes: readonly string[];
+    /** Screens outside the app shell, e.g. '/login' (and '/register' if the app has it). */
+    loggedOutRoutes: readonly string[];
+};
+/**
+ * Accessibility of the real screens in light and dark mode: every page in
+ * the Primary nav (discovered, so a new entity's table is covered with no
+ * edit), the given form routes, and the logged-out screens. axe's
+ * color-contrast rule against the rendered dark DOM is also what keeps the
+ * dark-mode tokens readable. The theme follows the OS setting, so
+ * emulateMedia switches it.
+ */
+export declare function defineA11ySuite({ formRoutes, loggedOutRoutes }: A11ySuiteOptions): void;
+/**
+ * Mock mode is announced on every route, logged-out ones included — /login
+ * is where a mock session passing for a real one first cost someone time.
+ * The default Playwright run is MSW-backed, so the banner must be there.
+ */
+export declare function defineMockModeBannerSuite({ routes }: {
+    routes: readonly string[];
+}): void;