@atelic-action/ui 0.17.2 → 1.1.0

package/src/app/layout/MobileMenu.tsx

@@ -0,0 +1,156 @@
+import { Link } from "@tanstack/react-router";
+import { LogOut, Menu } from "lucide-react";
+import { useEffect, useState } from "react";
+import { useAppConfig, useNav } from "../context/AppContext";
+import { cn } from "../lib/utils";
+import type { AppUser } from "../types";
+import { Avatar, AvatarFallback, AvatarImage } from "../ui/avatar";
+import { Button } from "../ui/button";
+import { Sheet, SheetContent, SheetDescription, SheetTitle, SheetTrigger } from "../ui/sheet";
+import { avatarInitials, displayName } from "./identity";
+import { isActivePath, isActiveSection } from "./nav";
+
+interface MobileMenuProps {
+	pathname: string;
+	user: AppUser | null;
+	onLogout: () => void;
+}
+
+const ROW =
+	"flex min-h-12 items-center gap-3 rounded-lg px-3 text-base transition-colors duration-150 active:bg-accent";
+
+/**
+ * The hamburger menu for phones and tablets: a right side sheet holding the
+ * whole map (every section with its sub pages beneath it) and, at the foot,
+ * the signed in user with Profile and Log out. The tab bar stays the fast
+ * path between sections; this is where everything else lives. It closes
+ * itself on navigation.
+ */
+export function MobileMenu({ pathname, user, onLogout }: MobileMenuProps) {
+	const appConfig = useAppConfig();
+	const profileHref = appConfig.profileHref ?? "/profile";
+	const navItems = useNav();
+	const [open, setOpen] = useState(false);
+	const name = displayName(user);
+
+	// Any navigation, by tap or by history, shuts the sheet.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: pathname is the trigger, not a dependency of the effect body
+	useEffect(() => {
+		setOpen(false);
+	}, [pathname]);
+
+	return (
+		<Sheet open={open} onOpenChange={setOpen}>
+			<SheetTrigger asChild>
+				<Button
+					variant="ghost"
+					size="icon"
+					className="-mr-2 h-11 w-11 text-foreground hover:bg-accent"
+					aria-label="Open menu"
+					aria-expanded={open}
+				>
+					<Menu className="h-6 w-6" />
+				</Button>
+			</SheetTrigger>
+			<SheetContent side="right" className="flex w-[84vw] max-w-sm flex-col gap-0 p-0">
+				<SheetTitle className="sr-only">Menu</SheetTitle>
+				<SheetDescription className="sr-only">
+					Every page in the app, and your account.
+				</SheetDescription>
+
+				<div className="flex h-14 items-center border-b border-border/40 px-5">
+					<Link
+						onClick={() => setOpen(false)}
+						to="/"
+						className="flex items-center space-x-2"
+						aria-label={`${appConfig.name} home`}
+					>
+						<span className="inline-block size-2 rounded-full bg-brand" aria-hidden="true" />
+						<span className="text-lg font-medium tracking-tight">{appConfig.mark}</span>
+					</Link>
+				</div>
+
+				<nav className="flex-1 overflow-y-auto px-2 py-3" aria-label="Menu">
+					<ul className="space-y-0.5">
+						{navItems.map((item) => {
+							const Icon = item.icon;
+							const active = isActiveSection(pathname, item);
+							// A section with sub pages lights its row only on its own landing
+							// page; deeper in, the sub page row carries the highlight.
+							const exact = pathname === item.href;
+							return (
+								<li key={item.href}>
+									<Link
+										onClick={() => setOpen(false)}
+										to={item.href}
+										className={cn(
+											ROW,
+											"font-medium",
+											active && !item.children?.length
+												? "bg-primary/10 text-primary"
+												: "text-foreground",
+											item.children && exact && "bg-primary/10 text-primary",
+										)}
+										aria-current={exact ? "page" : undefined}
+									>
+										<Icon className="h-5 w-5 flex-shrink-0" />
+										<span>{item.label}</span>
+									</Link>
+									{item.children ? (
+										<ul className="mb-1 mt-0.5 space-y-0.5" aria-label={`${item.label} pages`}>
+											{item.children.map((child) => {
+												const ChildIcon = child.icon;
+												const childActive = isActivePath(pathname, child.href);
+												return (
+													<li key={child.href}>
+														<Link
+															onClick={() => setOpen(false)}
+															to={child.href}
+															className={cn(
+																ROW,
+																"min-h-11 pl-11 text-[15px]",
+																childActive
+																	? "bg-primary/10 font-medium text-primary"
+																	: "text-muted-foreground",
+															)}
+															aria-current={childActive ? "page" : undefined}
+														>
+															<ChildIcon className="h-4 w-4 flex-shrink-0" />
+															<span>{child.label}</span>
+														</Link>
+													</li>
+												);
+											})}
+										</ul>
+									) : null}
+								</li>
+							);
+						})}
+					</ul>
+				</nav>
+
+				<div className="border-t border-border/40 px-2 py-3 pb-[max(0.75rem,env(safe-area-inset-bottom))]">
+					<Link
+						onClick={() => setOpen(false)}
+						to={profileHref}
+						className={cn(ROW, "min-h-14", pathname.startsWith(profileHref) && "bg-primary/10")}
+						aria-current={pathname.startsWith(profileHref) ? "page" : undefined}
+					>
+						<Avatar className="h-9 w-9 flex-shrink-0 border border-border/40">
+							<AvatarImage src={user?.avatar ?? undefined} alt={name} />
+							<AvatarFallback className="text-sm">{avatarInitials(name)}</AvatarFallback>
+						</Avatar>
+						<span className="flex min-w-0 flex-col">
+							<span className="truncate text-sm font-medium">{name}</span>
+							<span className="text-xs text-muted-foreground">Profile</span>
+						</span>
+					</Link>
+					<button type="button" onClick={onLogout} className={cn(ROW, "w-full text-destructive")}>
+						<LogOut className="h-5 w-5 flex-shrink-0" />
+						<span>Log out</span>
+					</button>
+				</div>
+			</SheetContent>
+		</Sheet>
+	);
+}

package/src/app/layout/MobileTabBar.tsx

@@ -0,0 +1,43 @@
+import { Link } from "@tanstack/react-router";
+import { useNav } from "../context/AppContext";
+import { cn } from "../lib/utils";
+import { isActiveSection } from "./nav";
+
+/**
+ * The bottom tab bar below the desktop breakpoint: one tab per section, the
+ * fast path between them. Sub pages live in the menu sheet and on each
+ * section's landing page. Padded for the home indicator on notched phones.
+ */
+export function MobileTabBar({ pathname }: { pathname: string }) {
+	const navItems = useNav();
+	return (
+		<nav
+			className="fixed bottom-0 left-0 right-0 z-40 border-t border-border/40 bg-background pb-[env(safe-area-inset-bottom)] shadow-[0_-2px_10px_rgba(0,0,0,0.06)] lg:hidden"
+			aria-label="Mobile navigation"
+		>
+			<div className="flex h-16 items-center justify-around">
+				{navItems
+					.filter((item) => !item.desktopOnly)
+					.map((item) => {
+						const Icon = item.icon;
+						const active = isActiveSection(pathname, item);
+						return (
+							<Link
+								key={item.href}
+								to={item.href}
+								className={cn(
+									"flex h-full flex-1 flex-col items-center justify-center py-2 transition-colors duration-150 active:bg-accent",
+									active ? "bg-primary/5 text-primary" : "text-muted-foreground",
+								)}
+								aria-current={active ? "page" : undefined}
+								aria-label={item.label}
+							>
+								<Icon className={cn("mb-1 h-5 w-5", active && "text-primary")} />
+								<span className={cn("text-xs", active && "font-medium")}>{item.label}</span>
+							</Link>
+						);
+					})}
+			</div>
+		</nav>
+	);
+}

package/src/app/layout/PageError.tsx

@@ -0,0 +1,30 @@
+import { AlertCircle } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Card, CardContent } from "../ui/card";
+
+interface PageErrorProps {
+	/** Error message to display */
+	message: string;
+	/** Optional title (defaults to "Error") */
+	title?: string;
+	/** Additional className */
+	className?: string;
+}
+
+/**
+ * Standardized error state for pages.
+ * Provides consistent error display across the application.
+ */
+export function PageError({ message, title = "Error", className }: PageErrorProps) {
+	return (
+		<Card className={cn("border-destructive/50", className)}>
+			<CardContent className="flex items-center gap-3 py-6">
+				<AlertCircle className="h-5 w-5 flex-shrink-0 text-destructive" />
+				<div>
+					<p className="font-medium text-destructive">{title}</p>
+					<p className="text-sm text-muted-foreground">{message}</p>
+				</div>
+			</CardContent>
+		</Card>
+	);
+}

package/src/app/layout/PageSkeleton.tsx

@@ -0,0 +1,65 @@
+import { cn } from "../lib/utils";
+import { Card, CardContent, CardHeader } from "../ui/card";
+
+interface PageSkeletonProps {
+	/** Show header skeleton with title and subtitle */
+	showHeader?: boolean;
+	/** Show action button skeleton in header */
+	showHeaderAction?: boolean;
+	/** Number of card skeletons to show */
+	cardCount?: number;
+	/** Layout for cards: single column, two columns, or grid */
+	cardLayout?: "single" | "two-column" | "grid";
+	/** Additional className */
+	className?: string;
+}
+
+/**
+ * Standardized loading skeleton for pages.
+ * Provides consistent loading states across the application.
+ */
+export function PageSkeleton({
+	showHeader = true,
+	showHeaderAction = false,
+	cardCount = 3,
+	cardLayout = "single",
+	className,
+}: PageSkeletonProps) {
+	const gridClasses = {
+		single: "space-y-6",
+		"two-column": "grid grid-cols-1 gap-6 lg:grid-cols-2",
+		grid: "grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3",
+	};
+
+	return (
+		<div className={cn("animate-pulse", className)}>
+			{showHeader && (
+				<div className="mb-6 sm:mb-8">
+					<div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+						<div className="space-y-2">
+							<div className="h-8 w-48 rounded bg-muted sm:h-9" />
+							<div className="h-4 w-64 rounded bg-muted sm:h-5" />
+						</div>
+						{showHeaderAction && <div className="h-10 w-32 rounded bg-muted" />}
+					</div>
+				</div>
+			)}
+
+			<div className={gridClasses[cardLayout]}>
+				{Array.from({ length: cardCount }).map((_, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: Static skeleton items never reorder
+					<Card key={i}>
+						<CardHeader>
+							<div className="h-6 w-2/3 rounded bg-muted" />
+							<div className="h-4 w-1/2 rounded bg-muted" />
+						</CardHeader>
+						<CardContent className="space-y-3">
+							<div className="h-4 w-full rounded bg-muted" />
+							<div className="h-4 w-3/4 rounded bg-muted" />
+						</CardContent>
+					</Card>
+				))}
+			</div>
+		</div>
+	);
+}

package/src/app/layout/SectionCards.tsx

@@ -0,0 +1,33 @@
+import { Link } from "@tanstack/react-router";
+
+import { useNav } from "../context/AppContext";
+
+/**
+ * A section's sub pages as cards on its landing page, read from the nav
+ * config so the rail, the menu sheet, and the landing page never disagree.
+ * Renders nothing for a section without children.
+ */
+export function SectionCards({ section }: { section: string }) {
+	const navItems = useNav();
+	const item = navItems.find((candidate) => candidate.href === section);
+	if (!item?.children?.length) return null;
+
+	return (
+		<nav className="ap-sections" aria-label={`${item.label} pages`}>
+			{item.children.map((child) => {
+				const Icon = child.icon;
+				return (
+					<Link key={child.href} to={child.href} className="ap-section-card">
+						<span className="ic">
+							<Icon size={20} />
+						</span>
+						<span className="flex flex-col gap-1">
+							<span className="lb">{child.label}</span>
+							<span className="bl">{child.blurb}</span>
+						</span>
+					</Link>
+				);
+			})}
+		</nav>
+	);
+}

package/src/app/layout/UserMenu.tsx

@@ -0,0 +1,104 @@
+import { Link } from "@tanstack/react-router";
+import { ChevronDown, LogOut, User as UserIcon } from "lucide-react";
+import { useState } from "react";
+import { useAppConfig } from "../context/AppContext";
+import { cn } from "../lib/utils";
+import type { AppUser } from "../types";
+import { Avatar, AvatarFallback, AvatarImage } from "../ui/avatar";
+import { Button } from "../ui/button";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuSeparator,
+	DropdownMenuTrigger,
+} from "../ui/dropdown-menu";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../ui/tooltip";
+import { avatarInitials, displayName } from "./identity";
+
+interface UserMenuProps {
+	user: AppUser | null;
+	onLogout: () => void;
+	/** Icon only, for the collapsed desktop rail. */
+	collapsed?: boolean;
+}
+
+/**
+ * The signed in user's block at the foot of the desktop rail: avatar and name
+ * opening a small menu with Profile and Log out. Collapsed, it is the avatar
+ * alone with the name in a tooltip.
+ */
+export function UserMenu({ user, onLogout, collapsed = false }: UserMenuProps) {
+	const profileHref = useAppConfig().profileHref ?? "/profile";
+	const [open, setOpen] = useState(false);
+	const name = displayName(user);
+	const initials = avatarInitials(name);
+
+	const avatar = (
+		<Avatar className="h-9 w-9 border border-border/40 flex-shrink-0">
+			<AvatarImage src={user?.avatar ?? undefined} alt={name} />
+			<AvatarFallback className="text-sm">{initials}</AvatarFallback>
+		</Avatar>
+	);
+
+	const trigger = collapsed ? (
+		<Button
+			variant="ghost"
+			size="sm"
+			className="w-full p-2 hover:bg-accent"
+			aria-label="User menu"
+			aria-expanded={open}
+			aria-haspopup="true"
+		>
+			{avatar}
+		</Button>
+	) : (
+		<Button
+			variant="ghost"
+			className="w-full justify-between px-3 py-2.5 h-auto hover:bg-accent overflow-hidden"
+			aria-label="User menu"
+			aria-expanded={open}
+			aria-haspopup="true"
+		>
+			<div className="flex items-center space-x-3 min-w-0">
+				{avatar}
+				<span className="text-sm font-medium truncate">{name}</span>
+			</div>
+			<ChevronDown
+				className={cn("h-4 w-4 text-muted-foreground transition-transform", open && "rotate-180")}
+			/>
+		</Button>
+	);
+
+	return (
+		<DropdownMenu open={open} onOpenChange={setOpen}>
+			{collapsed ? (
+				<TooltipProvider>
+					<Tooltip delayDuration={0}>
+						<TooltipTrigger asChild>
+							<DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
+						</TooltipTrigger>
+						<TooltipContent side="right" className="font-medium text-sm">
+							<p>{name}</p>
+						</TooltipContent>
+					</Tooltip>
+				</TooltipProvider>
+			) : (
+				<DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
+			)}
+			<DropdownMenuContent align="end" className="w-56">
+				<DropdownMenuItem asChild>
+					<Link to={profileHref} className="cursor-pointer">
+						<UserIcon className="mr-2 h-4 w-4" />
+						<span>Profile</span>
+					</Link>
+				</DropdownMenuItem>
+				<DropdownMenuSeparator />
+				<DropdownMenuItem onClick={onLogout} className="cursor-pointer text-destructive">
+					<LogOut className="mr-2 h-4 w-4" />
+					<span>Log out</span>
+				</DropdownMenuItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}

package/src/app/layout/identity.ts

@@ -0,0 +1,22 @@
+import type { AppUser } from "../types";
+
+/** The name the shell shows for the signed in user: "First Last", "First", or
+ * a neutral fallback while the profile is still loading. */
+export function displayName(user: Pick<AppUser, "firstName" | "lastName"> | null | undefined) {
+	if (user?.firstName && user?.lastName) return `${user.firstName} ${user.lastName}`;
+	if (user?.firstName) return user.firstName;
+	return "User";
+}
+
+/** Up to two initials for the avatar fallback, "MF" for "Matthew Fornaciari". */
+export function avatarInitials(name: string) {
+	return (
+		name
+			.split(" ")
+			.map((part) => part[0])
+			.filter(Boolean)
+			.slice(0, 2)
+			.join("")
+			.toUpperCase() || "U"
+	);
+}

package/src/app/layout/index.ts

@@ -0,0 +1,20 @@
+export { ActionButton } from "./ActionButton";
+export { AppLayout } from "./AppLayout";
+export {
+	AppPage,
+	AppPageToolbar,
+	type ToolbarAction,
+	type ToolbarFilter,
+} from "./AppPage";
+export { Breadcrumbs, type Crumb } from "./Breadcrumbs";
+export { FormActionButtons } from "./FormActionButtons";
+export {
+	activeSection,
+	isActivePath,
+	isActiveSection,
+	type NavChild,
+	type NavItem,
+} from "./nav";
+export { PageError } from "./PageError";
+export { PageSkeleton } from "./PageSkeleton";
+export { SectionCards } from "./SectionCards";

package/src/app/layout/nav.ts

@@ -0,0 +1,52 @@
+import type { ComponentType } from "react";
+
+/**
+ * Canonical navigation — the single source of truth for every nav
+ * surface the app shell renders: the desktop rail, the mobile tab bar, the
+ * mobile menu sheet, and a section's landing cards. Active state is derived
+ * from the current route against each item's `href`, so there is one place to
+ * add or reorder a destination. The items are the app's, handed to
+ * `AppProvider` as `nav`; this module holds the types and the active path
+ * helpers.
+ */
+export interface NavChild {
+	label: string;
+	href: string;
+	icon: ComponentType<{ className?: string; size?: number }>;
+	/** One line for the section landing card. */
+	blurb: string;
+}
+
+export interface NavItem {
+	label: string;
+	href: string;
+	icon: ComponentType<{ className?: string; size?: number }>;
+	/** Sub destinations inside this section, rendered beneath it in the rail
+	 * and the menu sheet, and as cards on the section's landing page. */
+	children?: NavChild[];
+	/** Show only in the mobile tab bar. */
+	mobileOnly?: boolean;
+	/** Show only in the desktop nav rail. */
+	desktopOnly?: boolean;
+	/** Other paths that belong to this section though they sit outside its
+	 * `href`, such as a record's own page at a short top level path. */
+	matches?: string[];
+}
+
+/** True when `pathname` is `href` or sits beneath it. The root ("/") only
+ * matches itself, since every path sits beneath it. */
+export function isActivePath(pathname: string, href: string): boolean {
+	if (href === "/") return pathname === "/";
+	return pathname === href || pathname.startsWith(`${href}/`);
+}
+
+/** True when `pathname` belongs to the section: its `href` or one of its
+ * `matches`, or anything beneath them. */
+export function isActiveSection(pathname: string, item: NavItem): boolean {
+	return [item.href, ...(item.matches ?? [])].some((href) => isActivePath(pathname, href));
+}
+
+/** The section (top level nav item) the current path belongs to, if any. */
+export function activeSection(pathname: string, items: NavItem[]): NavItem | undefined {
+	return items.find((item) => isActiveSection(pathname, item));
+}

package/src/app/lib/dates.ts

@@ -0,0 +1,57 @@
+// Local calendar helpers shared across features. Everything here works on ISO
+// date strings (YYYY-MM-DD) or local date parts, never on an ISO instant, so a
+// date never shifts a day across time zones.
+
+export const MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec",
+];
+
+// Today as a local YYYY-MM-DD string, for lexical comparison against other ISO
+// dates and for asking the api about the day the user is standing in. `now` is
+// injectable for tests.
+export function todayIso(now: Date = new Date()): string {
+	const month = String(now.getMonth() + 1).padStart(2, "0");
+	const day = String(now.getDate()).padStart(2, "0");
+	return `${now.getFullYear()}-${month}-${day}`;
+}
+
+// The IANA zone the browser is running in, which is the zone the user is
+// standing in for anything read from the app. Undefined where the runtime
+// cannot say, so the caller can leave the parameter off and let the api resolve
+// the zone from the user's own record instead of asserting UTC.
+export function localTimeZone(): string | undefined {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// Format an ISO date without constructing a Date. "2026-06-08" -> "Jun 8, 2026".
+// Returns the input untouched when it does not parse, so a bad value is visible
+// rather than blank.
+export function formatIsoDate(iso: string | null): string | null {
+	if (!iso) return null;
+	const [year, month, day] = iso.split("-").map(Number);
+	if (!year || !month || !day || month < 1 || month > 12) return iso;
+	return `${MONTHS[month - 1]} ${day}, ${year}`;
+}
+
+// "Jun 8" from an ISO date, no year. Null on a bad or absent input.
+export function monthDay(iso: string | null): string | null {
+	if (!iso) return null;
+	const [year, month, day] = iso.split("-").map(Number);
+	if (!year || !month || !day || month < 1 || month > 12) return null;
+	return `${MONTHS[month - 1]} ${day}`;
+}

package/src/app/lib/env.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+/**
+ * The environment variables an app on this shell reads, with runtime
+ * validation. The package never reads `import.meta.env` itself, since a
+ * bundler replaces it in the app's own code and not reliably inside a
+ * dependency: the app parses its own, once, and hands the api's base URL to
+ * the shell through its config.
+ *
+ * ```ts
+ * // src/app/env.ts
+ * export const env = parseEnv(import.meta.env);
+ * ```
+ */
+export const envSchema = z.object({
+	VITE_API_BASE_URL: z.string().url().optional(),
+	VITE_APP_URL: z.string().url().optional(),
+	VITE_SENTRY_DSN: z.string().optional(),
+});
+
+export type AppEnv = z.infer<typeof envSchema>;
+
+/** Validate the environment. Throws, naming each bad variable, so the app fails at startup. */
+export function parseEnv(source: Record<string, unknown>): AppEnv {
+	const result = envSchema.safeParse(source);
+
+	if (!result.success) {
+		const errors = result.error.flatten().fieldErrors;
+		const errorMessage = Object.entries(errors)
+			.map(([key, messages]) => `  ${key}: ${messages?.join(", ")}`)
+			.join("\n");
+
+		throw new Error(`Environment validation failed:\n${errorMessage}`);
+	}
+
+	return result.data;
+}