@atelic-action/ui 0.17.2 → 1.1.0

package/src/app/context/UserContext.tsx

@@ -0,0 +1,139 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createContext, type ReactNode, useContext, useEffect, useRef } from "react";
+import { session } from "../lib/session";
+import type { UnitPreferences } from "../lib/units";
+import { useAuthStore } from "../stores/authStore";
+import { DEFAULT_SYSTEMS, useUnitsStore } from "../stores/unitsStore";
+import type { AppUser, RegisteredUser } from "../types";
+
+export interface UserContextValue<U extends AppUser = RegisteredUser> {
+	user: U | null;
+	isLoading: boolean;
+	error: Error | null;
+}
+
+const UserContext = createContext<UserContextValue | null>(null);
+
+export function UserProvider({ children }: { children: ReactNode }) {
+	const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
+	const authUser = useAuthStore((state) => state.user);
+	const queryClient = useQueryClient();
+
+	// Every way out (the menu, a 401, a failed refresh) lands here: a signed out
+	// shell holds no copy of the last person, so the next account never sees it.
+	useEffect(() => {
+		if (!isAuthenticated) queryClient.removeQueries({ queryKey: ["user", "me"] });
+	}, [isAuthenticated, queryClient]);
+
+	const {
+		data: apiUser,
+		isLoading,
+		error,
+	} = useQuery({
+		queryKey: ["user", "me"],
+		queryFn: () => session.me(),
+		enabled: isAuthenticated,
+	});
+
+	// Use auth store user as fallback while fetching, or API user when available
+	const user = isAuthenticated ? (apiUser ?? authUser) : null;
+
+	useUnitsSync(apiUser ?? null);
+
+	const value: UserContextValue = {
+		user,
+		isLoading: isAuthenticated && isLoading,
+		error: error as Error | null,
+	};
+
+	return <UserContext.Provider value={value}>{children}</UserContext.Provider>;
+}
+
+const sameSystems = (a: Partial<UnitPreferences> | undefined, b: UnitPreferences) =>
+	(Object.keys(b) as (keyof UnitPreferences)[]).every((measure) => a?.[measure] === b[measure]);
+
+/** The account's snapshot as last hydrated into the store, or null while signed out. */
+interface Hydrated {
+	id: string;
+	units: Partial<UnitPreferences> | undefined;
+}
+
+const sameSnapshot = (
+	a: Hydrated | null,
+	id: string,
+	units: Partial<UnitPreferences> | undefined,
+) =>
+	a !== null &&
+	a.id === id &&
+	(Object.keys(DEFAULT_SYSTEMS) as (keyof UnitPreferences)[]).every(
+		(measure) => a.units?.[measure] === units?.[measure],
+	);
+
+/**
+ * Keeps the units store and the person's account in step. When the api user
+ * arrives, or comes back from a refetch holding a different choice (made on
+ * another device), their saved choices hydrate the store; from then on a
+ * change in the store is written back, so the same choice follows them to
+ * every device and to what the api itself writes in their units (a Strava
+ * description). Nothing is written while signed out, and nothing is written
+ * for a change the account already holds, so hydration never echoes.
+ *
+ * Saves go one at a time, in order, and only the newest one's response lands
+ * in the query cache: each save carries the whole snapshot, so an older
+ * response arriving late would otherwise hydrate the store backwards. A save
+ * outlives no account: after a sign out or a switch, what the old account
+ * queued is dropped and what it had in flight is not written to the cache.
+ */
+function useUnitsSync(apiUser: AppUser | null) {
+	const queryClient = useQueryClient();
+	const hydrated = useRef<Hydrated | null>(null);
+	const account = useRef<string | null>(null);
+	const queue = useRef<Promise<unknown>>(Promise.resolve());
+	const latest = useRef(0);
+	const { mutate: save } = useMutation({
+		// A save belongs to the account that made it: one still queued when
+		// that account signs out is dropped rather than written to the next.
+		mutationFn: (units: UnitPreferences) => {
+			const owner = account.current;
+			const run = queue.current.then(() =>
+				owner !== null && owner === account.current ? session.updateUnits(units) : null,
+			);
+			queue.current = run.catch(() => undefined);
+			return run;
+		},
+		onMutate: () => ({ seq: ++latest.current, owner: account.current }),
+		onSuccess: (saved, _units, context) => {
+			if (saved && context.seq === latest.current && context.owner === account.current) {
+				queryClient.setQueryData(["user", "me"], saved);
+			}
+		},
+	});
+
+	useEffect(() => {
+		account.current = apiUser?.id ?? null;
+		if (!apiUser) {
+			hydrated.current = null;
+			return;
+		}
+		if (!sameSnapshot(hydrated.current, apiUser.id, apiUser.units)) {
+			hydrated.current = { id: apiUser.id, units: apiUser.units };
+			useUnitsStore.getState().hydrate(apiUser.units);
+		}
+		return useUnitsStore.subscribe((state) => {
+			if (!sameSystems(apiUser.units, state.systems)) save(state.systems);
+		});
+	}, [apiUser, save]);
+}
+
+/**
+ * The signed in user: the api's copy once it arrives, the one stored at sign
+ * in until then. Typed as the app's registered user; pass a type to narrow it
+ * further at one call site.
+ */
+export function useUser<U extends AppUser = RegisteredUser>(): UserContextValue<U> {
+	const context = useContext(UserContext);
+	if (!context) {
+		throw new Error("useUser must be used within a UserProvider");
+	}
+	return context as unknown as UserContextValue<U>;
+}

package/src/app/hooks/useDebounce.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+export function useDebounce<T>(value: T, delayMs: number): T {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+
+	useEffect(() => {
+		const timer = setTimeout(() => setDebouncedValue(value), delayMs);
+		return () => clearTimeout(timer);
+	}, [value, delayMs]);
+
+	return debouncedValue;
+}

package/src/app/hooks/useIsDesktop.ts

@@ -0,0 +1,31 @@
+import { useSyncExternalStore } from "react";
+
+/** The shell's one breakpoint: the desktop rail appears at Tailwind's `lg`.
+ * Every layout decision keyed on viewport reads this, so CSS and React agree. */
+export const DESKTOP_QUERY = "(min-width: 1024px)";
+
+function subscribe(onChange: () => void) {
+	if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+		return () => {};
+	}
+	const media = window.matchMedia(DESKTOP_QUERY);
+	media.addEventListener("change", onChange);
+	return () => media.removeEventListener("change", onChange);
+}
+
+function getSnapshot() {
+	if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+		return false;
+	}
+	return window.matchMedia(DESKTOP_QUERY).matches;
+}
+
+/**
+ * True at the desktop breakpoint (lg and up), false below it and in any
+ * environment without matchMedia (jsdom), where the mobile layout is the safe
+ * default. Backed by matchMedia rather than a resize listener so it flips
+ * exactly when the CSS does and never lags a debounce.
+ */
+export function useIsDesktop(): boolean {
+	return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}

package/src/app/hooks/useWakeLock.ts

@@ -0,0 +1,49 @@
+import { useEffect } from "react";
+
+/**
+ * Keep the screen awake while the consuming surface is mounted (the cook view:
+ * saucy fingers should never have to tap a dimming screen). Progressive
+ * enhancement over the Screen Wake Lock API:
+ * - Silently no-ops where unsupported (Firefox, older Safari).
+ * - The browser auto-releases the lock when the tab is hidden, so a
+ *   visibilitychange listener re-acquires it when the user returns.
+ */
+export function useWakeLock(): void {
+	useEffect(() => {
+		if (!("wakeLock" in navigator)) return;
+
+		let sentinel: WakeLockSentinel | null = null;
+		let released = false;
+		let acquiring = false;
+
+		const acquire = async () => {
+			// Guard against overlapping requests (rapid visibility flips) and
+			// redundant ones while a lock is already held.
+			if (acquiring || (sentinel && !sentinel.released)) return;
+			acquiring = true;
+			try {
+				const lock = await navigator.wakeLock.request("screen");
+				sentinel = lock;
+				// The effect may have cleaned up while the request was in flight.
+				if (released) await lock.release();
+			} catch {
+				// Denied (low battery, permissions policy) — cook on without it.
+			} finally {
+				acquiring = false;
+			}
+		};
+
+		const onVisibilityChange = () => {
+			if (document.visibilityState === "visible") void acquire();
+		};
+
+		void acquire();
+		document.addEventListener("visibilitychange", onVisibilityChange);
+
+		return () => {
+			released = true;
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			void sentinel?.release().catch(() => {});
+		};
+	}, []);
+}

package/src/app/index.ts

@@ -0,0 +1,64 @@
+/**
+ * The app shell: the frame (rail, tab bar, menu sheet), the `AppPage`
+ * scaffold, the provider that hands the shell the app's config and nav, the
+ * signed in user, the transport and session, and the stores they share. The
+ * shadcn kit is its own entry, `@atelic-action/ui/app/ui`.
+ */
+
+// The provider, the config, and the frame
+export { AppProvider, type AppProviderProps } from "./AppProvider";
+export { AuthGuard } from "./AuthGuard";
+export { CardErrorBoundary } from "./CardErrorBoundary";
+export { type AppConfig, getAppConfig } from "./config";
+export { configureApp } from "./configure";
+export {
+	AppConfigProvider,
+	type AppConfigProviderProps,
+	useAppConfig,
+	useNav,
+} from "./context/AppContext";
+export { SidebarProvider, useRail, useSidebar } from "./context/SidebarContext";
+export { type UserContextValue, UserProvider, useUser } from "./context/UserContext";
+export { ErrorFallback, type ErrorFallbackProps } from "./ErrorFallback";
+export { GoogleGlyph } from "./GoogleGlyph";
+// Hooks
+export { useDebounce } from "./hooks/useDebounce";
+export { DESKTOP_QUERY, useIsDesktop } from "./hooks/useIsDesktop";
+export { useWakeLock } from "./hooks/useWakeLock";
+export * from "./layout";
+export { avatarInitials, displayName } from "./layout/identity";
+// The library: dates and phrasing, the transport, the session, units
+export * from "./lib/dates";
+export { type AppEnv, envSchema, parseEnv } from "./lib/env";
+export * from "./lib/format";
+export { apiFetch, buildQueryString, publicFetch, uploadFormData } from "./lib/http";
+export { type LastAuth, readLastAuth, writeLastAuth } from "./lib/lastAuth";
+export { postNavigate, startGoogleAuth } from "./lib/oauth";
+export { isPublicPage, isPublicRoute } from "./lib/publicRoutes";
+export { queryClient } from "./lib/queryClient";
+export { matchesSearch } from "./lib/search";
+export { session } from "./lib/session";
+export {
+	ensureValidToken,
+	handleUnauthorized,
+	refreshAccessToken,
+	resetRefreshState,
+} from "./lib/tokenRefresh";
+export { toSnakeCase, transformKeys } from "./lib/transformKeys";
+export * from "./lib/units";
+export * from "./lib/unwrap";
+export { cn } from "./lib/utils";
+// The stores
+export { type AuthState, DEFAULT_EXPIRY_BUFFER_MS, useAuthStore } from "./stores/authStore";
+export { DEFAULT_SYSTEMS, type UnitsState, useUnitsStore } from "./stores/unitsStore";
+// The wire protocol and the user
+export type {
+	AppUser,
+	PaginatedResponse,
+	PaginationLinks,
+	RefreshResponse,
+	Register,
+	RegisteredUser,
+	TokenResponse,
+} from "./types";
+export type { ToastMeta } from "./types/query";

package/src/app/layout/ActionButton.tsx

@@ -0,0 +1,67 @@
+import type { LucideIcon } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../ui/button";
+
+interface ActionButtonProps {
+	/** Lucide icon component */
+	icon: LucideIcon;
+	/** Button label (visible on larger screens) */
+	label: string;
+	/** Click handler */
+	onClick?: () => void;
+	/** Button variant */
+	variant?: "default" | "outline" | "ghost" | "destructive" | "secondary";
+	/** Additional className */
+	className?: string;
+	/** Disabled state */
+	disabled?: boolean;
+	/** Loading state */
+	loading?: boolean;
+	/** Accessible label (defaults to label) */
+	"aria-label"?: string;
+	/** For use with Link components */
+	asChild?: boolean;
+	/** Button type */
+	type?: "button" | "submit" | "reset";
+	/** Children (for asChild usage) */
+	children?: React.ReactNode;
+}
+
+/**
+ * Standardized responsive action button.
+ * Shows icon only on mobile, icon + text on larger screens.
+ */
+export function ActionButton({
+	icon: Icon,
+	label,
+	onClick,
+	variant = "outline",
+	className,
+	disabled,
+	loading,
+	"aria-label": ariaLabel,
+	asChild,
+	type = "button",
+	children,
+}: ActionButtonProps) {
+	return (
+		<Button
+			variant={variant}
+			onClick={onClick}
+			className={cn("gap-2", className)}
+			aria-label={ariaLabel || label}
+			disabled={disabled || loading}
+			asChild={asChild}
+			type={type}
+		>
+			{asChild ? (
+				children
+			) : (
+				<>
+					<Icon className={cn("h-4 w-4 flex-shrink-0", loading && "animate-spin")} />
+					<span className="hidden sm:inline">{label}</span>
+				</>
+			)}
+		</Button>
+	);
+}

package/src/app/layout/AppLayout.tsx

@@ -0,0 +1,110 @@
+import { Link, useLocation, useNavigate } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+
+import { useAppConfig } from "../context/AppContext";
+import { useSidebar } from "../context/SidebarContext";
+import { useIsDesktop } from "../hooks/useIsDesktop";
+import { isPublicPage } from "../lib/publicRoutes";
+import { cn } from "../lib/utils";
+import { useAuthStore } from "../stores/authStore";
+import { DesktopRail, RAIL_WIDTH, RAIL_WIDTH_COLLAPSED } from "./DesktopRail";
+import { MobileMenu } from "./MobileMenu";
+import { MobileTabBar } from "./MobileTabBar";
+
+interface AppLayoutProps {
+	children: ReactNode;
+}
+
+/**
+ * The chrome around a public page for a visitor who is not signed in: the
+ * brand on the left, a sign in link on the right, and the page. No rail, no
+ * tab bar, nothing that assumes an account.
+ */
+function PublicShell({ children }: AppLayoutProps) {
+	const appConfig = useAppConfig();
+	return (
+		<div className="min-h-screen bg-background">
+			<header className="sticky top-0 z-30 border-b border-border/40 bg-background">
+				<div className="flex h-14 items-center justify-between px-4 lg:px-6">
+					<Link
+						to="/"
+						className="flex items-center space-x-2 transition-opacity hover:opacity-80"
+						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>
+					<Link to="/" className="text-sm font-medium text-muted-foreground hover:text-foreground">
+						Sign in
+					</Link>
+				</div>
+			</header>
+			<main className="flex min-h-[calc(100vh-3.5rem)] flex-col">{children}</main>
+		</div>
+	);
+}
+
+/**
+ * The app shell around every authenticated page. Mobile first: below the
+ * desktop breakpoint it is a slim top bar (brand, hamburger menu) over the
+ * page with the section tab bar pinned to the bottom. At lg and up the top
+ * bar and tab bar give way to the navigation rail on the left. Every nav
+ * surface reads the one nav the app hands `AppProvider`.
+ */
+export function AppLayout({ children }: AppLayoutProps) {
+	const appConfig = useAppConfig();
+	const navigate = useNavigate();
+	const { pathname } = useLocation();
+	const { isCollapsed, toggleSidebar } = useSidebar();
+	const isDesktop = useIsDesktop();
+	const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
+	const user = useAuthStore((state) => state.user);
+	const logout = useAuthStore((state) => state.logout);
+
+	const handleLogout = () => {
+		logout();
+		navigate({ to: "/", replace: true });
+	};
+
+	if (!isAuthenticated) {
+		return isPublicPage(pathname) ? <PublicShell>{children}</PublicShell> : children;
+	}
+
+	return (
+		<div className="min-h-screen bg-background">
+			<DesktopRail
+				pathname={pathname}
+				collapsed={isCollapsed}
+				onToggle={toggleSidebar}
+				user={user}
+				onLogout={handleLogout}
+			/>
+
+			<div
+				style={{ paddingLeft: isDesktop ? (isCollapsed ? RAIL_WIDTH_COLLAPSED : RAIL_WIDTH) : 0 }}
+				className={cn(
+					"flex min-h-screen flex-col transition-[padding-left] duration-200 ease-out",
+					"pb-16 lg:pb-0",
+				)}
+			>
+				<header className="sticky top-0 z-30 border-b border-border/40 bg-background lg:hidden">
+					<div className="flex h-14 items-center justify-between px-4">
+						<Link
+							to="/"
+							className="flex items-center space-x-2 transition-opacity hover:opacity-80"
+							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>
+						<MobileMenu pathname={pathname} user={user} onLogout={handleLogout} />
+					</div>
+				</header>
+
+				<main className="flex flex-1 flex-col">{children}</main>
+			</div>
+
+			{!isDesktop && <MobileTabBar pathname={pathname} />}
+		</div>
+	);
+}