@tristan2828/ui-foundation 3.0.0

package/dist/components/app/app-shell.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
+import { useTheme } from 'next-themes';
+import { useState } from 'react';
+import { NavLink, Navigate, Outlet, useLocation } from 'react-router';
+import { useAuth } from '../../auth/use-auth.js';
+import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
+import { Skeleton } from '../ui/skeleton.js';
+import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, } from '../ui/sidebar.js';
+import { Toaster } from '../ui/sonner.js';
+import { TooltipProvider } from '../ui/tooltip.js';
+// Must match SIDEBAR_COOKIE_NAME in ../ui/sidebar.tsx, which writes the
+// cookie on every toggle but never reads it back — that half is here.
+const SIDEBAR_COOKIE_NAME = 'sidebar_state';
+function storedSidebarOpen(fallback) {
+    const match = document.cookie.match(new RegExp(`(?:^|; )${SIDEBAR_COOKIE_NAME}=([^;]*)`));
+    return match ? match[1] === 'true' : fallback;
+}
+function ThemeToggle() {
+    const { resolvedTheme, setTheme } = useTheme();
+    const isDark = resolvedTheme === 'dark';
+    return (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Toggle dark mode", onClick: () => setTheme(isDark ? 'light' : 'dark'), children: isDark ? _jsx(SunIcon, {}) : _jsx(MoonIcon, {}) }));
+}
+function AppShellSkeleton() {
+    return (_jsxs("div", { className: "flex h-screen w-full gap-4 p-4", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-full w-56 shrink-0" }), _jsxs("div", { className: "flex-1 space-y-4 pt-2", children: [_jsx(Skeleton, { className: "h-8 w-64" }), _jsx(Skeleton, { className: "h-40 w-full" })] })] }));
+}
+export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }) {
+    const { user, status, error, retry, logout } = useAuth();
+    const location = useLocation();
+    // Set before logout starts, so the redirect below knows this was a
+    // deliberate logout. It can't be a follow-up navigate() after logout
+    // resolves: that runs before React re-renders, and the <Navigate> this
+    // component then renders starts a second navigation that wins.
+    const [isLoggingOut, setIsLoggingOut] = useState(false);
+    if (status === 'loading') {
+        return _jsx(AppShellSkeleton, {});
+    }
+    // The session check itself failed (backend down, network) — not the same
+    // as logged out, so don't send the user to a login form that can't work.
+    if (status === 'unavailable' && error) {
+        return (_jsx("div", { className: "flex min-h-screen items-center justify-center p-6", children: _jsx(ErrorState, { error: error, onRetry: retry }) }));
+    }
+    // Also covers `status === 'unauthenticated'` (user is always null then) —
+    // narrowing on `user` here, rather than `status`, is what lets TypeScript
+    // treat `user` as non-null for the rest of this component. `from` lets
+    // /login send the user back here afterwards; router state, not a query
+    // param, so it can't be used as an open redirect from a crafted link.
+    if (!user) {
+        // A deliberate logout lands on a clean /login — otherwise whoever signs
+        // in next would be sent back to the previous user's page.
+        const from = `${location.pathname}${location.search}${location.hash}`;
+        return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
+    }
+    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: "Navigation" }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: nav.map(({ to, label, icon: Icon, end }) => {
+                                                            const isActive = end
+                                                                ? location.pathname === to
+                                                                : location.pathname.startsWith(to);
+                                                            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(NavLink, { to: to, end: end }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
+                                                        }) }) })] }), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate text-xs text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+                                                    setIsLoggingOut(true);
+                                                    logout().catch(() => setIsLoggingOut(false));
+                                                }, children: _jsx(LogOutIcon, {}) })] }) })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));
+}

package/dist/components/app/data-table.d.ts

@@ -0,0 +1,56 @@
+import type { CellData, RowData, TableFeatures } from '@tanstack/react-table';
+import { type LegacyColumnDef } from '@tanstack/react-table/legacy';
+import type { AppError } from '../../api/contracts.js';
+export type SortingState = {
+    id: string;
+    desc: boolean;
+}[];
+declare module '@tanstack/table-core' {
+    interface ColumnMeta<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData> {
+        align?: 'center';
+    }
+}
+export type DataTableProps<TData extends Record<string, unknown>> = {
+    columns: LegacyColumnDef<TData, unknown>[];
+    data: TData[];
+    total: number;
+    /** 1-based, matching QuerySpec.page. */
+    page: number;
+    pageSize: number;
+    onPageChange: (page: number) => void;
+    sorting: SortingState;
+    onSortingChange: (sorting: SortingState) => void;
+    isLoading: boolean;
+    error?: AppError | null;
+    onRetry?: () => void;
+    emptyTitle: string;
+    emptyDescription?: string;
+    emptyAction?: React.ReactNode;
+    toolbar?: React.ReactNode;
+    getRowId?: (row: TData) => string;
+    /**
+     * Pins the first column so it stays put while the rest scrolls
+     * horizontally, and adds a second scrollbar stuck to the viewport's
+     * bottom edge. Opt in per table — a narrow table needs neither.
+     */
+    pinFirstColumn?: boolean;
+    /**
+     * Pins the last column to the right edge, the mirror of
+     * `pinFirstColumn`, for a table whose row actions sit there: on a wide
+     * table they otherwise scroll off-screen, so the control used most is
+     * the one that can't be seen. No second scrollbar of its own. Opt in per
+     * table.
+     */
+    pinLastColumn?: boolean;
+    /**
+     * Set false when the caller supplies a default sort it falls back to
+     * whenever `sorting` is empty. TanStack's cycle is asc → desc →
+     * unsorted, and that third click hands back `[]`, which such a caller
+     * immediately turns back into the same default — so the header looks
+     * stuck and can never advance past it. Leaving this undefined keeps
+     * TanStack's own behaviour, so a table with no default sort is
+     * unaffected. See conventions/docs/entity-plan-template.md "Default sort".
+     */
+    enableSortingRemoval?: boolean;
+};
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, }: DataTableProps<TData>): import("react").JSX.Element;

package/dist/components/app/data-table.js

@@ -0,0 +1,167 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Generic server-side data table: sorting, pagination and a toolbar slot for
+// filters, all driven externally (the caller owns the QuerySpec and re-fetches
+// via TanStack Query — this component never fetches).
+//
+// Built on @tanstack/react-table's useLegacyTable, not the v9 useTable +
+// tableFeatures() API. useLegacyTable is TanStack's own officially shipped,
+// fully-typed v8-compatibility layer (not a hand-rolled shim) — the v9
+// feature-slot architecture exists to make row models like sorting and
+// pagination tree-shakeable and independently swappable, which buys nothing
+// here: every row model is manual (the server sorts and pages), so this
+// table never uses TanStack's own sorted/paginated row models at all.
+import { useEffect, useRef, useState } from 'react';
+import { flexRender } from '@tanstack/react-table';
+import { cn } from 'cn';
+import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
+import { Skeleton } from '../ui/skeleton.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../ui/table.js';
+function TableSkeleton({ columnCount }) {
+    return (_jsx("div", { className: "flex flex-col gap-2 p-2", "data-state": "loading", children: Array.from({ length: 5 }, (_, row) => (_jsx("div", { className: "flex gap-4", children: Array.from({ length: columnCount }, (_, col) => (_jsx(Skeleton, { className: "h-8 flex-1" }, col))) }, row))) }));
+}
+// The pinned cell gets a flat `bg-background`, not `bg-inherit`: the zebra
+// stripe (table.tsx) is a *translucent* color, so inheriting it would let
+// the columns scrolling behind show through at 40% opacity — exactly the
+// bleed-through a solid background avoids. That also means the pinned
+// column shows no stripe, which is why it is the thing that carries the
+// hover highlight. --accent is only ~3% off the page background, so a
+// solid left edge marker carries the signal; an inset shadow rather than a
+// border, so nothing reflows.
+const PINNED_COLUMN_CLASS = 'sticky left-0 z-10 border-r bg-background group-hover/row:bg-accent ' +
+    'group-hover/row:shadow-[inset_3px_0_0_0_var(--primary)]';
+// The right-edge mirror, opaque for the same reason. Its edge marker points
+// inward from the right, so the two pinned columns bracket the row.
+const PINNED_LAST_COLUMN_CLASS = 'sticky right-0 z-10 border-l bg-background group-hover/row:bg-accent ' +
+    'group-hover/row:shadow-[inset_-3px_0_0_0_var(--primary)]';
+// Hover highlights the pinned cell, not the whole row. A row-level hover
+// cannot be made consistent against the zebra stripe: `tr:nth-child(even)`
+// is specificity (0,2,1) and `tr:hover` is (0,2,0), so the stripe wins and
+// even rows stay unlit — odd rows highlight, even rows don't.
+// `hover:bg-transparent` drops table.tsx's own `hover:bg-muted/50` via
+// tailwind-merge so no row hover is attempted at all. The pinned cell is
+// the better target anyway: it names the row, it sits on an opaque
+// background so it reads identically on striped and unstriped rows, and it
+// stays on screen when the table is scrolled right.
+const ROW_GROUP_CLASS = 'group/row hover:bg-transparent';
+// A second horizontal scrollbar, stuck to the viewport's bottom edge. The
+// real one sits directly under the last row, which on a full page is
+// off-screen until you have already scrolled past every row. Only rendered
+// once the content actually overflows.
+function useBottomScrollbar(containerRef, isSuccessView) {
+    const barRef = useRef(null);
+    const [scrollWidth, setScrollWidth] = useState(0);
+    const [clientWidth, setClientWidth] = useState(0);
+    const isOverflowing = scrollWidth > clientWidth;
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!isSuccessView || !container)
+            return;
+        const contentTable = container.querySelector('table');
+        if (!contentTable)
+            return;
+        const measure = () => {
+            setScrollWidth(container.scrollWidth);
+            setClientWidth(container.clientWidth);
+        };
+        measure();
+        // The inner <table> grows with column and content width; the container
+        // changes with the viewport and the sidebar. Either can change whether,
+        // and how far, there is to scroll.
+        const resizeObserver = new ResizeObserver(measure);
+        resizeObserver.observe(container);
+        resizeObserver.observe(contentTable);
+        return () => resizeObserver.disconnect();
+    }, [containerRef, isSuccessView]);
+    // Separate from the measuring effect: the bar only enters the DOM once
+    // `isOverflowing` is true, which that effect is what sets. Wiring the
+    // listeners there would read barRef.current before the bar had ever
+    // rendered and silently attach to nothing.
+    useEffect(() => {
+        const container = containerRef.current;
+        const bar = barRef.current;
+        if (!isSuccessView || !isOverflowing || !container || !bar)
+            return;
+        let isSyncing = false;
+        const syncBarFromContainer = () => {
+            if (isSyncing)
+                return;
+            isSyncing = true;
+            bar.scrollLeft = container.scrollLeft;
+            isSyncing = false;
+        };
+        const syncContainerFromBar = () => {
+            if (isSyncing)
+                return;
+            isSyncing = true;
+            container.scrollLeft = bar.scrollLeft;
+            isSyncing = false;
+        };
+        container.addEventListener('scroll', syncBarFromContainer);
+        bar.addEventListener('scroll', syncContainerFromBar);
+        return () => {
+            container.removeEventListener('scroll', syncBarFromContainer);
+            bar.removeEventListener('scroll', syncContainerFromBar);
+        };
+    }, [containerRef, isSuccessView, isOverflowing]);
+    return { barRef, isOverflowing, scrollWidth };
+}
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, }) {
+    const pageCount = Math.max(1, Math.ceil(total / pageSize));
+    const table = useLegacyTable({
+        data,
+        columns,
+        getRowId: getRowId,
+        state: {
+            sorting,
+            pagination: { pageIndex: page - 1, pageSize },
+        },
+        manualSorting: true,
+        ...(enableSortingRemoval === undefined ? {} : { enableSortingRemoval }),
+        manualPagination: true,
+        pageCount,
+        onSortingChange: (updater) => onSortingChange(typeof updater === 'function' ? updater(sorting) : updater),
+        onPaginationChange: (updater) => {
+            const next = typeof updater === 'function' ? updater({ pageIndex: page - 1, pageSize }) : updater;
+            onPageChange(next.pageIndex + 1);
+        },
+        getCoreRowModel: getCoreRowModel(),
+    });
+    // Past the last page — e.g. after deleting the only row on the last page,
+    // or a stale ?page= link. The server still reports rows (total > 0), so
+    // this is not "empty": go to the real last page instead of showing
+    // "No widgets yet" with data one click away.
+    const isPastLastPage = !isLoading && !error && data.length === 0 && total > 0 && page > pageCount;
+    useEffect(() => {
+        if (isPastLastPage)
+            onPageChange(pageCount);
+    }, [isPastLastPage, pageCount, onPageChange]);
+    const isEmpty = !isLoading && !error && data.length === 0 && !isPastLastPage;
+    const isSuccessView = !error && !isLoading && !isPastLastPage && !isEmpty;
+    const containerRef = useRef(null);
+    const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
+    return (_jsxs("div", { className: "flex flex-col gap-4", children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: columns.length })) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
+                        // With the sticky bar below as the visible scrollbar, hide the
+                        // container's own. It stays overflow-x-auto and fully
+                        // scrollable (wheel, trackpad, drag, and the sync effect); it
+                        // just no longer draws a bar directly under the last row.
+                        containerClassName: cn(pinFirstColumn &&
+                            '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden'), children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
+                                        const canSort = header.column.getCanSort();
+                                        const sortDirection = header.column.getIsSorted();
+                                        return (_jsx(TableHead, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
+                                                index === headerGroup.headers.length - 1 &&
+                                                PINNED_LAST_COLUMN_CLASS, header.column.columnDef.meta?.align === 'center' && 'text-center'), "aria-sort": !canSort
+                                                ? undefined
+                                                : sortDirection === 'asc'
+                                                    ? 'ascending'
+                                                    : sortDirection === 'desc'
+                                                        ? 'descending'
+                                                        : 'none', children: header.isPlaceholder ? null : canSort ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext())) }, header.id));
+                                    }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn((pinFirstColumn || pinLastColumn) && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
+                                            index === row.getVisibleCells().length - 1 &&
+                                            PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "text-sm text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "text-sm text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
+}

package/dist/components/app/entity-form.d.ts

@@ -0,0 +1,14 @@
+import type { FormEvent, ReactNode } from 'react';
+import type { AppError } from '../../api/contracts.js';
+export type EntityFormProps = {
+    title: string;
+    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    isSubmitting: boolean;
+    submitError?: AppError | null;
+    submitLabel: string;
+    onCancel: () => void;
+    /** An edit-only destructive action (e.g. delete), shown opposite Cancel/Submit. */
+    danger?: ReactNode;
+    children: ReactNode;
+};
+export declare function EntityForm({ title, onSubmit, isSubmitting, submitError, submitLabel, onCancel, danger, children, }: EntityFormProps): import("react").JSX.Element;

package/dist/components/app/entity-form.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
+import { FieldGroup } from '../ui/field.js';
+import { Spinner } from '../ui/spinner.js';
+export function EntityForm({ title, onSubmit, isSubmitting, submitError, submitLabel, onCancel, danger, children, }) {
+    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex max-w-xl flex-col gap-6", children: [_jsx("h1", { className: "text-lg font-semibold text-foreground", children: title }), _jsx(FieldGroup, { children: children }), submitError && (_jsx(ErrorState, { error: submitError, className: "border border-dashed border-destructive/30" })), _jsxs("div", { className: `flex items-center gap-2 ${danger ? 'justify-between' : 'justify-end'}`, children: [danger, _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: isSubmitting, children: "Cancel" }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), submitLabel] })] })] })] }));
+}

package/dist/components/app/error-state.d.ts

@@ -0,0 +1,6 @@
+import type { AppError } from '../../api/contracts.js';
+export declare function ErrorState({ error, onRetry, className, }: {
+    error: AppError;
+    onRetry?: () => void;
+    className?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The composite AGENTS.md's "Correct Patterns" section names directly:
+// `if (error) return <ErrorState error={error} />`. Renders an AppError —
+// never a raw response (the gateway translates every failure) —
+// using the same <Empty> primitive the "no rows" state uses, so a screen's
+// error and empty states read as one family instead of two unrelated
+// widgets.
+import { AlertCircleIcon } from 'lucide-react';
+import { Button } from '../ui/button.js';
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
+const TITLE_BY_KIND = {
+    network: 'Connection problem',
+    server: 'Something went wrong',
+    notfound: 'Not found',
+    auth: 'Not authorized',
+    validation: 'Check the form',
+};
+export function ErrorState({ error, onRetry, className, }) {
+    return (_jsxs(Empty, { className: className, "data-state": "error", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(AlertCircleIcon, { className: "text-destructive" }) }), _jsx(EmptyTitle, { children: TITLE_BY_KIND[error.kind] }), _jsx(EmptyDescription, { children: error.message })] }), onRetry && (_jsx(EmptyContent, { children: _jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }) }))] }));
+}

package/dist/components/app/foundation-providers.d.ts

@@ -0,0 +1,9 @@
+import { type QueryClient } from '@tanstack/react-query';
+import { type ReactNode } from 'react';
+export declare function FoundationProviders({ mockMode, queryClient, children, }: {
+    /** Whether the API is served by MSW — the app's own IS_MOCK_MODE. */
+    mockMode: boolean;
+    /** Defaults to createQueryClient(); pass one to share it with code outside React. */
+    queryClient?: QueryClient;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/components/app/foundation-providers.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { QueryClientProvider } from '@tanstack/react-query';
+import { useState } from 'react';
+import { createQueryClient } from '../../api/query-client.js';
+import { AuthProvider } from '../../auth/use-auth.js';
+import { MockModeBanner } from './mock-mode-banner.js';
+import { ThemeProvider } from '../theme-provider.js';
+// Everything an app's root needs around its router, in the order that
+// works: the theme outermost, the mock-mode banner above the router so it
+// shows on every route (/login included), and AuthProvider inside
+// QueryClientProvider because it queries /auth/me through TanStack Query.
+export function FoundationProviders({ mockMode, queryClient, children, }) {
+    const [client] = useState(() => queryClient ?? createQueryClient());
+    return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: children }) })] }));
+}

package/dist/components/app/mock-mode-banner.d.ts

@@ -0,0 +1,3 @@
+export declare function MockModeBanner({ active }: {
+    active: boolean;
+}): import("react").JSX.Element | null;

package/dist/components/app/mock-mode-banner.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { FlaskConicalIcon } from 'lucide-react';
+// Rendered above the router, so it shows on every route including /login —
+// which is the point. MSW's seeded user and small fixed fixture look
+// identical to a real signed-in session at a glance, and in the first app
+// built on this foundation that cost a real user real time chasing what
+// looked like a broken login before realising they were on the mock dev
+// server rather than the backend origin.
+//
+// `active` comes from the app (its src/lib/mock-mode.ts): VITE_API is baked
+// in when the *app* is built, so package code must not read it itself.
+export function MockModeBanner({ active }) {
+    if (!active)
+        return null;
+    return (_jsxs("div", { role: "status", className: "flex h-9 items-center justify-center gap-1.5 border-b border-border bg-warning px-4 text-sm font-semibold text-warning-foreground", children: [_jsx(FlaskConicalIcon, { className: "size-4", "aria-hidden": "true" }), "Mock data \u2014 not connected to the real backend"] }));
+}

package/dist/components/app/multi-choice.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+export declare function MultiChoice<T extends string>({ options, value, onValueChange, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+    /** Every allowed option, in display order. */
+    options: readonly T[];
+    value: T[];
+    onValueChange: (value: T[]) => void;
+    /** Id for the text input, so a <FieldLabel htmlFor> labels it. */
+    id?: string;
+    placeholder?: string;
+    /** For use without a visible label (e.g. a table toolbar filter). */
+    'aria-label'?: string;
+    'aria-invalid'?: boolean;
+    className?: string;
+}): React.JSX.Element;

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

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A multi-choice picker: selected options as removable chips, the rest in a
+// filterable dropdown. The one control for every "multi choice" field
+// (conventions/docs/entity-plan-template.md) — on a form (Widget Tags) and as a table
+// filter — so entities reuse it rather than re-assembling the combobox
+// primitive each time. Built on shadcn's Combobox `multiple` mode, following
+// its own ComboboxMultiple example.
+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, 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), children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: 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: option }, option)) })] })] }));
+}

package/dist/components/app/password-input.d.ts

@@ -0,0 +1,3 @@
+export declare function PasswordInput({ id, autoComplete, 'aria-invalid': ariaInvalid, ...props }: React.ComponentProps<'input'> & {
+    'aria-invalid'?: boolean;
+}): import("react").JSX.Element;

package/dist/components/app/password-input.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EyeIcon, EyeOffIcon } from 'lucide-react';
+import { useId, useState } from 'react';
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, } from '../ui/input-group.js';
+// A password field with a show/hide toggle. Composed from shadcn's
+// InputGroup rather than hand-rolled: shadcn has no dedicated password
+// input, but InputGroupAddon + InputGroupButton is exactly the
+// trailing-control shape, and AGENTS.md's Hard Rule is about not
+// re-implementing what shadcn ships, not about avoiding composition.
+//
+// Three fields need this (login, and register's password + confirmation),
+// which is why it is a component rather than repeated markup.
+//
+// One consequence worth knowing before writing a test against a password
+// field: the toggle's accessible name contains the word "password", so a
+// substring `getByLabel('Password')` now matches both the input and this
+// button and fails Playwright's strict mode. Use `{ exact: true }` — the
+// button's name is right for users, and the test should be the precise
+// one.
+export function PasswordInput({ id, autoComplete, 'aria-invalid': ariaInvalid, ...props }) {
+    const [isVisible, setIsVisible] = useState(false);
+    // The toggle's own accessible name changes with state, so a screen
+    // reader hears what the button will *do*, not what it is.
+    const Icon = isVisible ? EyeOffIcon : EyeIcon;
+    const describedById = useId();
+    return (_jsxs(InputGroup, { children: [_jsx(InputGroupInput, { id: id, type: isVisible ? 'text' : 'password', autoComplete: autoComplete, "aria-invalid": ariaInvalid, "aria-describedby": describedById, ...props }), _jsx(InputGroupAddon, { align: "inline-end", children: _jsx(InputGroupButton, { type: "button", "aria-label": isVisible ? 'Hide password' : 'Show password', 
+                    // aria-pressed would also be defensible; the changing label is
+                    // clearer, and announcing both is redundant.
+                    onClick: () => setIsVisible((shown) => !shown), children: _jsx(Icon, {}) }) }), _jsx("span", { id: describedById, className: "sr-only", children: "Password is hidden. Use the show password button to reveal it." })] }));
+}

package/dist/components/app/route-error-boundary.d.ts

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

package/dist/components/app/route-error-boundary.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TriangleAlertIcon } from 'lucide-react';
+import { isRouteErrorResponse, useRouteError } from 'react-router';
+import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
+export function RouteErrorBoundary() {
+    const error = useRouteError();
+    const message = isRouteErrorResponse(error)
+        ? `${error.status} ${error.statusText}`
+        : error instanceof Error
+            ? error.message
+            : 'Something went wrong.';
+    return (_jsx(Empty, { children: _jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(TriangleAlertIcon, {}) }), _jsx(EmptyTitle, { children: "This page hit an error" }), _jsx(EmptyDescription, { children: message })] }) }));
+}

package/dist/components/theme-provider.d.ts

@@ -0,0 +1,2 @@
+import { type ThemeProviderProps } from 'next-themes';
+export declare function ThemeProvider({ children, ...props }: ThemeProviderProps): import("react").JSX.Element;

package/dist/components/theme-provider.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+// Thin wrapper so the rest of the app imports from @/components/theme-provider
+// rather than next-themes directly. Toggles the .dark class that
+// src/styles/theme.css already keys its dark-mode block on.
+export function ThemeProvider({ children, ...props }) {
+    return _jsx(NextThemesProvider, { ...props, children: children });
+}

package/dist/components/ui/badge.d.ts

@@ -0,0 +1,7 @@
+import { useRender } from "@base-ui/react/use-render";
+import { type VariantProps } from "class-variance-authority";
+declare const badgeVariants: (props?: ({
+    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "outline-success" | "outline-warning" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export { Badge, badgeVariants };

package/dist/components/ui/badge.js

@@ -0,0 +1,50 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!", {
+    variants: {
+        variant: {
+            default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+            secondary: "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+            destructive: "bg-destructive text-destructive-foreground focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/90",
+            success: "bg-success text-success-foreground focus-visible:ring-success/20 dark:focus-visible:ring-success/40 [a]:hover:bg-success/90",
+            warning: "bg-warning text-warning-foreground focus-visible:ring-warning/20 dark:focus-visible:ring-warning/40 [a]:hover:bg-warning/90",
+            outline: "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
+            // Three tones x three styles. The *-text tokens, never the solid
+            // fill tokens: `border-destructive`/`text-destructive` would use
+            // the shade chosen to carry white text, which is too light to read
+            // against the page in light mode and too dark in dark mode. See
+            // styles/theme.css and conventions/docs/design-language.md.
+            "outline-success": "border-success-text text-success-text",
+            "outline-warning": "border-warning-text text-warning-text",
+            "outline-destructive": "border-destructive-text text-destructive-text",
+            // The fill is the solid token at low alpha (a wash of the tone),
+            // while the text is the *-text shade — mixing the two is the point.
+            // Dark mode needs a little more alpha for the wash to register
+            // against a near-black page.
+            "tinted-success": "bg-success/15 text-success-text dark:bg-success/20",
+            "tinted-warning": "bg-warning/15 text-warning-text dark:bg-warning/20",
+            "tinted-destructive": "bg-destructive/15 text-destructive-text dark:bg-destructive/20",
+            ghost: "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
+            link: "text-primary underline-offset-4 hover:underline",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+    },
+});
+function Badge({ className, variant = "default", render, ...props }) {
+    return useRender({
+        defaultTagName: "span",
+        props: mergeProps({
+            className: cn(badgeVariants({ variant }), className),
+        }, props),
+        render,
+        state: {
+            slot: "badge",
+            variant,
+        },
+    });
+}
+export { Badge, badgeVariants };

package/dist/components/ui/button.d.ts

@@ -0,0 +1,8 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { type VariantProps } from "class-variance-authority";
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react").JSX.Element;
+export { Button, buttonVariants };

package/dist/components/ui/button.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+const buttonVariants = cva("group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: "bg-primary text-primary-foreground hover:bg-primary/80",
+            outline: "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+            secondary: "bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+            ghost: "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+            destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40",
+            link: "text-primary underline-offset-4 hover:underline",
+        },
+        size: {
+            default: "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+            sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+            lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            icon: "size-8",
+            "icon-xs": "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+            "icon-sm": "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+            "icon-lg": "size-9",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+        size: "default",
+    },
+});
+function Button({ className, variant = "default", size = "default", ...props }) {
+    return (_jsx(ButtonPrimitive, { "data-slot": "button", className: cn(buttonVariants({ variant, size, className })), ...props }));
+}
+export { Button, buttonVariants };