@tristan2828/ui-foundation 3.0.0

package/conventions/docs/entity-plan-template.md

@@ -0,0 +1,67 @@
+# <Entity> — entity plan
+
+The input to the entity playbook (`docs/foundation/add-an-entity.md`, which any AI
+tool can follow; Claude Code's `/new-entity` is a shortcut). It builds
+exactly what this file says — no invented fields, options or rules. Copy
+this file to `docs/entities/<entity>.md` (kebab-case, singular: `game.md`)
+and fill it in, or ask your AI tool to plan the entity with you and it
+will talk it through and write this file. `docs/entities/widget.md` (the
+template's demo entity, until you delete it) is a filled-in example.
+
+## Purpose
+
+One or two sentences: what one record is, and who uses the screens.
+
+## Fields
+
+| Field | Label | Type | Required | Options / rules | List | Filter |
+|---|---|---|---|---|---|---|
+| title | Title | text | yes | 1–200 chars | column, sortable | search |
+| status | Status | single choice | yes | Backlog, Playing, Finished; default Backlog | column, sortable | yes |
+| priority | Priority | single choice | no | Low, Normal, High; empty means not set | column, sortable | yes |
+
+- **Field**: camelCase, as it appears in the API (`releaseDate`).
+- **Type** — what the foundation supports today:
+  - *Demonstrated by the Widget reference* (copied directly): `text` (one
+    line), `long text`, `decimal` (fixed places — say how many),
+    `date-time`, `email`, `single choice` (list the options, in display
+    order; see the note below if it is *optional*), `multi choice` (list
+    the options; any number can be picked —
+    chips on the form, badges in the table, an any-of filter), `reference`
+    (to another entity — name it; a searchable combobox).
+  - *Close variants* (built by a small, stated change to the nearest
+    pattern): `integer` (from decimal), `url` (from email — a format
+    check), `date` (from date-time — no time part).
+  - *Not supported yet:* boolean, file, and anything else.
+    Write it anyway with a note; the playbook will stop and raise it
+    rather than improvise.
+- **Required**: `yes`, or `no` (then say whether empty means "unknown").
+  An **optional `single choice`** needs one extra decision: the label for
+  "not set" (`Not checked`, `Any`, `None`…), because the form shows it as
+  a real option rather than a blank. Say it in the Options column. Widget
+  has no optional choice field, so the playbook builds this one from the
+  worked example in `docs/foundation/add-an-entity.md` step 6 rather than by copying
+  a screen — a Base UI `Select` can't take `""` as an item value, so the
+  pattern needs a sentinel and gets the display wrong without one.
+- **List**: `column` if it shows in the table, and `sortable` if you can
+  sort by it; blank if it's form-only.
+- **Filter**: `search` (the text search box), `yes` (a filter control), or
+  blank.
+
+## List screen
+
+- Default sort:
+- Page size: 10 unless there's a reason.
+- Anything else the table must show or do:
+
+## Screens and access
+
+- Screens: list, create, edit, delete (the only shape the playbook builds
+  today).
+- Ownership: **shared** (every signed-in user sees every record) or
+  **per-user** (each user sees only their own).
+
+## Open questions
+
+Anything not decided yet. The playbook won't start while this section has
+an unresolved item.

package/dist/api/contracts.d.ts

@@ -0,0 +1,20 @@
+export type Page<T> = {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+};
+export type AppError = {
+    kind: "validation" | "notfound" | "auth" | "server" | "network";
+    message: string;
+    fieldErrors?: Record<string, string[]>;
+};
+export type QuerySpec = {
+    page: number;
+    pageSize: number;
+    sort?: {
+        field: string;
+        dir: "asc" | "desc";
+    };
+    filters?: Record<string, unknown>;
+};

package/dist/api/contracts.js

@@ -0,0 +1,4 @@
+// UI-owned types. The gateway translates every backend response into these;
+// nothing above the gateway may see a wire-shaped response (the
+// anti-corruption layer — docs/ARCHITECTURE.md "The layers").
+export {};

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

@@ -0,0 +1,9 @@
+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>;
+export declare function register(input: RegisterRequest): Promise<User>;
+export declare function logout(): Promise<void>;
+export declare function getCurrentUser(): Promise<User>;
+export {};

package/dist/api/gateway/auth.js

@@ -0,0 +1,37 @@
+import { safeFetch, toAppError } from "./errors.js";
+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 !== 200)
+        throw toAppError(res.status, res.body);
+    return 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
+// the gateway shape is identical to login's: a User on 200, AppError
+// otherwise (a duplicate email arrives as kind:'validation' with
+// fieldErrors.email, same as any other field error).
+export async function register(input) {
+    const res = await safeFetch("/auth/register", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body);
+    return res.body;
+}
+export async function logout() {
+    const res = await safeFetch("/auth/logout", { method: "POST" });
+    if (res.status !== 204)
+        throw toAppError(res.status, res.body);
+}
+export async function getCurrentUser() {
+    const res = await safeFetch("/auth/me");
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body);
+    return res.body;
+}

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

@@ -0,0 +1,5 @@
+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;
+export declare function networkError(): AppError;

package/dist/api/gateway/errors.js

@@ -0,0 +1,36 @@
+// Shared wire-error -> AppError translation for the gateway, plus a thin
+// wrapper that turns a rejected apiFetch (network-level failure) into
+// AppError{kind:'network'} instead of letting a raw fetch error escape. This
+// is the anti-corruption layer's error seam (docs/ARCHITECTURE.md).
+import { apiFetch } from "../transport/index.js";
+export async function safeFetch(path, init) {
+    try {
+        return await apiFetch(path, init);
+    }
+    catch {
+        throw networkError();
+    }
+}
+export function toAppError(status, body) {
+    if (status === 422) {
+        const detail = body?.detail ?? [];
+        const fieldErrors = {};
+        for (const issue of detail) {
+            // The field is the last *string* segment: integer segments index into
+            // an array field (["body", "tags", 0] is a bad tag), and a form binds
+            // errors by field name, never by position.
+            const field = String([...issue.loc].reverse().find((segment) => typeof segment === "string") ?? issue.loc[issue.loc.length - 1]);
+            (fieldErrors[field] ??= []).push(issue.msg);
+        }
+        return { kind: "validation", message: "Validation failed", fieldErrors };
+    }
+    const message = body?.detail ?? `Request failed with status ${status}`;
+    if (status === 404)
+        return { kind: "notfound", message };
+    if (status === 401)
+        return { kind: "auth", message };
+    return { kind: "server", message };
+}
+export function networkError() {
+    return { kind: "network", message: "Network error — check your connection and try again." };
+}

package/dist/api/query-client.d.ts

@@ -0,0 +1,2 @@
+import { QueryClient } from "@tanstack/react-query";
+export declare function createQueryClient(): QueryClient;

package/dist/api/query-client.js

@@ -0,0 +1,19 @@
+// The default QueryClient retries every failed query 3x with exponential
+// backoff (~7s total) regardless of why it failed. That's right for a
+// network blip but wrong for a 404, 401, or 422 — the gateway already
+// classifies those as AppError.kind values that will never change on
+// retry, so retrying just makes the user wait ~7s to see an error the
+// first response already told us was final.
+import { QueryClient } from "@tanstack/react-query";
+function isTransient(error) {
+    return error.kind === "network";
+}
+export function createQueryClient() {
+    return new QueryClient({
+        defaultOptions: {
+            queries: {
+                retry: (failureCount, error) => isTransient(error) && failureCount < 2,
+            },
+        },
+    });
+}

package/dist/api/schema.d.ts

@@ -0,0 +1,246 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/auth/login": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Log in with email and password, receiving a session cookie */
+        post: operations["login"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/register": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Create an account and immediately log in, receiving a session cookie */
+        post: operations["register"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/logout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Clear the current session */
+        post: operations["logout"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/me": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** The currently authenticated user */
+        get: operations["getCurrentUser"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        User: {
+            readonly id: number;
+            /** Format: email */
+            email: string;
+            name: string;
+        };
+        LoginRequest: {
+            /** Format: email */
+            email: string;
+            password: string;
+        };
+        RegisterRequest: {
+            email: components["schemas"]["User"]["email"];
+            name: components["schemas"]["User"]["name"];
+            password: components["schemas"]["LoginRequest"]["password"];
+        };
+        /** @description FastAPI's default 422 shape (RequestValidationError). */
+        ValidationErrorBody: {
+            detail: {
+                loc: (string | number)[];
+                msg: string;
+                type: string;
+            }[];
+        };
+        /** @description FastAPI's default HTTPException shape. */
+        HTTPErrorBody: {
+            detail: string;
+        };
+    };
+    responses: {
+        /** @description Validation failed on one or more fields. */
+        ValidationError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ValidationErrorBody"];
+            };
+        };
+        /** @description Resource not found. */
+        NotFoundError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["HTTPErrorBody"];
+            };
+        };
+        /** @description Missing or invalid credentials. */
+        UnauthorizedError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["HTTPErrorBody"];
+            };
+        };
+        /** @description Unhandled server error. */
+        ServerError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["HTTPErrorBody"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    login: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LoginRequest"];
+            };
+        };
+        responses: {
+            /** @description Authenticated. Sets the session_id cookie. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            422: components["responses"]["ValidationError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    register: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RegisterRequest"];
+            };
+        };
+        responses: {
+            /** @description Registered and authenticated. Sets the session_id cookie. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            422: components["responses"]["ValidationError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    logout: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Logged out (always, whether or not a session existed). */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            500: components["responses"]["ServerError"];
+        };
+    };
+    getCurrentUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+}

package/dist/api/schema.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+export type ApiResponse = {
+    status: number;
+    body: unknown;
+};
+export declare function apiFetch(path: string, init?: RequestInit): Promise<ApiResponse>;

package/dist/api/transport/index.js

@@ -0,0 +1,14 @@
+// The only file allowed to call fetch directly — see AGENTS.md ("NEVER
+// import from api/transport/ outside api/gateway/") and the matching
+// no-restricted-imports / no-restricted-syntax rules in eslint.config.js.
+// Owns the base URL and the raw HTTP call; knows nothing about widgets,
+// pagination, or error shapes — that translation is the gateway's job.
+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 };
+    }
+    const body = await response.json().catch(() => undefined);
+    return { status: response.status, body };
+}

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

@@ -0,0 +1,19 @@
+import type { AppError } from '../api/contracts.js';
+export type AuthUser = {
+    id: number;
+    name: string;
+    email: string;
+};
+export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable';
+export type AuthContextValue = {
+    user: AuthUser | null;
+    status: AuthStatus;
+    /** Why the session check failed; set only when status is 'unavailable'. */
+    error: AppError | null;
+    /** Re-runs the session check (the 'unavailable' state's retry). */
+    retry: () => void;
+    login: (email: string, password: string) => Promise<void>;
+    logout: () => Promise<void>;
+    register: (email: string, name: string, password: string) => Promise<void>;
+};
+export declare const AuthContext: import("react").Context<AuthContextValue>;

package/dist/auth/auth-context.js

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+// Session-cookie auth against the backend. auth-provider.tsx is the only
+// file that knows how any of this works; see AGENTS.md's hard rule.
+export const AuthContext = createContext({
+    user: null,
+    status: 'loading',
+    error: null,
+    retry: () => { },
+    login: async () => { },
+    logout: async () => { },
+    register: async () => { },
+});

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

@@ -0,0 +1,4 @@
+import { type ReactNode } from 'react';
+export declare function AuthProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/auth/auth-provider.js

@@ -0,0 +1,101 @@
+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 { AuthContext } from './auth-context.js';
+// TanStack Query, not useEffect — AGENTS.md's "NEVER fetch in useEffect"
+// rule applies here too. A 401 here just means "not logged in", which the
+// global QueryClient retry policy (api/query-client.ts) already treats as
+// final rather than retrying.
+const AUTH_QUERY_KEY = ['auth', 'me'];
+function isAuthError(error) {
+    return error?.kind === 'auth';
+}
+// Every cached query except the session itself belongs to whoever was
+// logged in when it ran. Dropped on every session change so the next user
+// never sees the previous user's rows — widgets are per-user on the
+// backend. `removeQueries` with a predicate, not `clear()`: clear() would
+// also drop the auth query this provider's own useQuery observes, and that
+// observer wouldn't pick up the replacement setQueryData creates.
+function removeUserScopedQueries(queryClient) {
+    queryClient.removeQueries({ predicate: (query) => query.queryKey[0] !== AUTH_QUERY_KEY[0] });
+}
+function startSession(queryClient, user) {
+    removeUserScopedQueries(queryClient);
+    queryClient.setQueryData(AUTH_QUERY_KEY, user);
+}
+function endSession(queryClient) {
+    removeUserScopedQueries(queryClient);
+    queryClient.setQueryData(AUTH_QUERY_KEY, null);
+}
+// This is the only file that knows how auth works — everything else
+// consumes useAuth() from ./use-auth, and the package exports nothing else
+// of it (docs/ARCHITECTURE.md "The layers").
+export function AuthProvider({ children }) {
+    const queryClient = useQueryClient();
+    const { data: user, error, isLoading, refetch, } = useQuery({
+        queryKey: AUTH_QUERY_KEY,
+        queryFn: getCurrentUser,
+    });
+    // A session can expire while the app is open: the next request for any
+    // other resource comes back 401. End the session here, once, rather than
+    // leaving each screen to show a "Not authorized" error inside a shell
+    // that still thinks it's logged in — AppShell then redirects to /login.
+    // A subscription, not a fetch; the auth query's own 401 is excluded (it
+    // is already the "logged out" signal).
+    useEffect(() => {
+        const onError = (error) => {
+            // Deferred: mutating the cache from inside its own notify callback
+            // would re-enter the cache mid-dispatch.
+            if (isAuthError(error))
+                queueMicrotask(() => endSession(queryClient));
+        };
+        const unsubscribeQueries = queryClient.getQueryCache().subscribe((event) => {
+            if (event.type === 'updated' &&
+                event.action.type === 'error' &&
+                event.query.queryKey[0] !== AUTH_QUERY_KEY[0]) {
+                onError(event.action.error);
+            }
+        });
+        const unsubscribeMutations = queryClient.getMutationCache().subscribe((event) => {
+            if (event.type === 'updated' && event.action.type === 'error') {
+                onError(event.action.error);
+            }
+        });
+        return () => {
+            unsubscribeQueries();
+            unsubscribeMutations();
+        };
+    }, [queryClient]);
+    // A 401 always means logged out, even if a user was cached from before
+    // (a background refetch of /auth/me after the session expired). Any other
+    // failure with no user is 'unavailable', not logged out.
+    const status = isLoading
+        ? 'loading'
+        : isAuthError(error)
+            ? 'unauthenticated'
+            : user
+                ? 'authenticated'
+                : error
+                    ? 'unavailable'
+                    : 'unauthenticated';
+    async function login(email, password) {
+        startSession(queryClient, await loginRequest({ email, password }));
+    }
+    async function logout() {
+        await logoutRequest();
+        endSession(queryClient);
+    }
+    async function register(email, name, password) {
+        startSession(queryClient, await registerRequest({ email, name, password }));
+    }
+    return (_jsx(AuthContext.Provider, { value: {
+            user: status === 'authenticated' ? (user ?? null) : null,
+            status,
+            error: status === 'unavailable' ? error : null,
+            retry: () => void refetch(),
+            login,
+            logout,
+            register,
+        }, children: children }));
+}

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

@@ -0,0 +1,2 @@
+export { AuthProvider } from './auth-provider.js';
+export declare function useAuth(): import("./auth-context.js").AuthContextValue;

package/dist/auth/use-auth.js

@@ -0,0 +1,9 @@
+import { useContext } from 'react';
+import { AuthContext } from './auth-context.js';
+// Re-exported so the app root can mount the provider without importing
+// auth-provider.tsx directly — this file is the one boundary everything
+// else, including main.tsx, is allowed to import auth from.
+export { AuthProvider } from './auth-provider.js';
+export function useAuth() {
+    return useContext(AuthContext);
+}

package/dist/components/app/app-shell.d.ts

@@ -0,0 +1,28 @@
+import { type ComponentType, type ReactNode } from 'react';
+export type NavItem = {
+    /** The route this entry links to. */
+    to: string;
+    label: string;
+    icon: ComponentType;
+    /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
+    end?: boolean;
+};
+export type AppShellProps = {
+    /** Shown at the top of the sidebar (hidden on the collapsed icon rail). */
+    title: string;
+    /** The app's primary navigation, in order. */
+    nav: readonly NavItem[];
+    /**
+     * More sidebar groups under the primary nav — reference links, say. Built
+     * from the sidebar primitives (`@tristan2828/ui-foundation/ui/sidebar`).
+     * Rendered inside the Primary landmark, so keep it navigation.
+     */
+    sidebarExtra?: ReactNode;
+    /**
+     * Whether the sidebar starts expanded for someone who has never toggled
+     * it. After the first toggle their choice is remembered (the sidebar
+     * primitive writes a cookie, read back here). A wide table wants false.
+     */
+    defaultSidebarOpen?: boolean;
+};
+export declare function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen }: AppShellProps): import("react").JSX.Element;