@atelic-action/ui 0.17.2 → 1.0.0

package/src/app/layout/AppPage.tsx

@@ -0,0 +1,268 @@
+import { Link } from "@tanstack/react-router";
+import { PanelRightClose, PanelRightOpen, Search, X } from "lucide-react";
+import type { ReactNode } from "react";
+import { useRail } from "../context/SidebarContext";
+import { cn } from "../lib/utils";
+import { OptionSelect } from "../ui/option-select";
+
+/**
+ * AppPage — the shared scaffold every redesigned authenticated surface renders
+ * through. It owns the page chrome: a header (crumb · title · live
+ * dot · subtitle · aside), an optional summary block, a toolbar slot, the page
+ * content, an optional footer, and a canonical right rail.
+ *
+ * The rail is the new primitive. On desktop (lg+) it is a true full-height
+ * column mirroring the left nav rail, scrolling independently beside the main
+ * column. On mobile it stacks inline beneath the header. It is optional — pages
+ * pass it only when they have an at-a-glance summary.
+ *
+ * AppPage does NOT render navigation; the app shell (AppLayout) owns the nav
+ * rail / tab bar from the single nav config. Styling lives in globals.css under
+ * "AppPage scaffold (SHARED) — ap-*".
+ */
+interface AppPageProps {
+	/** Breadcrumb trail, rendered above the title (pass the Breadcrumbs component). */
+	crumb?: ReactNode;
+	/** Optional content opposite the crumb (a status badge, attribution). */
+	aside?: ReactNode;
+	/** Optional icon before the title. */
+	icon?: ReactNode;
+	/** Page title. */
+	title: ReactNode;
+	/** Show the live (accent) dot beside the title. */
+	live?: boolean;
+	/** Optional one-line description below the title. */
+	subtitle?: ReactNode;
+	/** Optional block between the header and the toolbar (mobile + desktop). */
+	summary?: ReactNode;
+	/** Toolbar slot — typically an AppPageToolbar. */
+	toolbar?: ReactNode;
+	/** Optional at-a-glance rail. Full-height column on desktop, inline on mobile. */
+	rail?: ReactNode;
+	/** Optional footer below the content. */
+	footer?: ReactNode;
+	/** Page content. */
+	children: ReactNode;
+}
+
+function PageHeader({
+	crumb,
+	aside,
+	icon,
+	title,
+	live,
+	subtitle,
+	railToggle,
+}: Pick<AppPageProps, "crumb" | "aside" | "icon" | "title" | "live" | "subtitle"> & {
+	railToggle?: ReactNode;
+}) {
+	return (
+		<div className="ap-head">
+			{(crumb || aside || railToggle) && (
+				<div className="ap-crumb">
+					<div>{crumb}</div>
+					{(aside || railToggle) && (
+						<div className="ap-crumb-actions">
+							{aside}
+							{railToggle}
+						</div>
+					)}
+				</div>
+			)}
+			<div className="ap-title">
+				{icon && <span className="glyph">{icon}</span>}
+				<h1>{title}</h1>
+				{live && <span className="live" aria-hidden="true" />}
+			</div>
+			{subtitle && <p className="ap-sub">{subtitle}</p>}
+		</div>
+	);
+}
+
+export function AppPage({
+	crumb,
+	aside,
+	icon,
+	title,
+	live,
+	subtitle,
+	summary,
+	toolbar,
+	rail,
+	footer,
+	children,
+}: AppPageProps) {
+	const { isRailCollapsed, toggleRail } = useRail();
+
+	// The collapse toggle lives in the header and only exists when the page has a
+	// rail. It is desktop-only (hidden below lg via CSS), since the rail stacks
+	// inline on mobile where collapsing is meaningless.
+	const railToggle = rail ? (
+		<button
+			type="button"
+			className="ap-rail-toggle"
+			onClick={toggleRail}
+			aria-label={isRailCollapsed ? "Expand rail" : "Collapse rail"}
+			aria-expanded={!isRailCollapsed}
+			aria-controls="ap-right-rail"
+			title={isRailCollapsed ? "Expand rail" : "Collapse rail"}
+		>
+			{isRailCollapsed ? <PanelRightOpen size={18} /> : <PanelRightClose size={18} />}
+		</button>
+	) : undefined;
+
+	return (
+		<div className="ap-page">
+			<div className="ap-col">
+				<div className="ap-scroll">
+					<PageHeader
+						crumb={crumb}
+						aside={aside}
+						icon={icon}
+						title={title}
+						live={live}
+						subtitle={subtitle}
+						railToggle={railToggle}
+					/>
+					{rail && <div className="ap-rail-inline">{rail}</div>}
+					{summary}
+					{toolbar}
+					{children}
+					{footer}
+				</div>
+			</div>
+			{rail && (
+				<aside id="ap-right-rail" className={cn("ap-rail", isRailCollapsed && "is-collapsed")}>
+					{rail}
+				</aside>
+			)}
+		</div>
+	);
+}
+
+export interface ToolbarFilter {
+	value: string;
+	onChange: (value: string) => void;
+	options: { value: string; label: string; count?: number; disabled?: boolean }[];
+	ariaLabel?: string;
+}
+
+export interface ToolbarAction {
+	label?: string;
+	icon?: ReactNode;
+	/** Trailing muted timestamp (e.g. "9:38 am"). */
+	ago?: string;
+	onClick?: () => void;
+	variant?: "ghost" | "solid";
+	disabled?: boolean;
+	ariaLabel?: string;
+	/** Render the action as a router Link to this route instead of a button. */
+	to?: string;
+	/** Escape hatch: render this node verbatim in the action slot (e.g. a
+	 * tooltip-wrapped control). Takes precedence over to / button. */
+	node?: ReactNode;
+}
+
+interface AppPageToolbarProps {
+	search?: { value: string; onChange: (value: string) => void; placeholder?: string };
+	filters?: ToolbarFilter[];
+	actions?: ToolbarAction[];
+	/** Optional status line below the toolbar row (e.g. a sync-progress message). */
+	notice?: ReactNode;
+}
+
+/**
+ * AppPageToolbar — search + filter dropdown(s) + action button(s), matching the
+ * prototype's calm `ap-tools` row. Filters are native selects carrying live
+ * counts; actions use the house buttons (ghost / solid).
+ */
+export function AppPageToolbar({
+	search,
+	filters = [],
+	actions = [],
+	notice,
+}: AppPageToolbarProps) {
+	return (
+		<div className="ap-tools">
+			<div className="ap-toolrow">
+				{search && (
+					<label className="ap-search">
+						<Search size={17} aria-hidden="true" />
+						<input
+							type="search"
+							value={search.value}
+							onChange={(event) => search.onChange(event.target.value)}
+							placeholder={search.placeholder ?? "Search…"}
+							aria-label={search.placeholder ?? "Search"}
+						/>
+						{search.value && (
+							<button
+								type="button"
+								className="ap-search-clear"
+								onClick={() => search.onChange("")}
+								aria-label="Clear search"
+							>
+								<X size={15} />
+							</button>
+						)}
+					</label>
+				)}
+				{actions.length > 0 && (
+					<div className="ap-actions">
+						{actions.map((action, index) => {
+							const key = action.ariaLabel ?? action.label ?? action.to ?? index;
+							if (action.node) return <span key={key}>{action.node}</span>;
+							const className = `btn-${action.variant ?? "ghost"}`;
+							if (action.to) {
+								return (
+									<Link
+										key={key}
+										to={action.to}
+										disabled={action.disabled}
+										className={className}
+										aria-label={action.ariaLabel ?? action.label}
+									>
+										{action.icon}
+										{action.label}
+									</Link>
+								);
+							}
+							return (
+								<button
+									key={key}
+									type="button"
+									className={className}
+									onClick={action.onClick}
+									disabled={action.disabled}
+									aria-label={action.ariaLabel ?? action.label}
+								>
+									{action.icon}
+									{action.label}
+									{action.ago && <span className="ago">{action.ago}</span>}
+								</button>
+							);
+						})}
+					</div>
+				)}
+			</div>
+			{notice && <div className="ap-toolnotice">{notice}</div>}
+			{filters.length > 0 && (
+				<div className="ap-selects">
+					{filters.map((filter) => (
+						<OptionSelect
+							key={filter.ariaLabel ?? filter.options[0]?.value}
+							value={filter.value}
+							onValueChange={filter.onChange}
+							ariaLabel={filter.ariaLabel ?? "Filter"}
+							className="w-full sm:w-44"
+							options={filter.options.map((option) => ({
+								value: option.value,
+								label: option.count != null ? `${option.label} · ${option.count}` : option.label,
+							}))}
+						/>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}

package/src/app/layout/Breadcrumbs.tsx

@@ -0,0 +1,57 @@
+import { Link, type LinkProps } from "@tanstack/react-router";
+import { ChevronLeft } from "lucide-react";
+
+export interface Crumb {
+	label: string;
+	/** Route to link to. Omit for the current (last) crumb. */
+	to?: LinkProps["to"];
+}
+
+/**
+ * The breadcrumb trail rendered in AppPage's `crumb` slot, above the title.
+ * Every page passes one: section and root pages a single self crumb ("Eat"),
+ * sub pages and detail pages a "Section / Page" trail.
+ *
+ * Two renderings, one per breakpoint, so the trail reads on a phone:
+ *
+ * - Below lg, a trail with a parent collapses to one thumb sized back link to
+ *   the nearest linked ancestor ("‹ Recipes"). The current page is the title
+ *   directly beneath, so repeating it in a tiny wrapped line bought nothing,
+ *   and a root page's single self crumb shows nothing at all there.
+ * - At lg and up, the full "Eat / Recipes / Name" trail, the current page
+ *   truncated rather than wrapped.
+ */
+export function Breadcrumbs({ items }: { items: Crumb[] }) {
+	if (items.length === 0) {
+		return null;
+	}
+
+	// The nearest ancestor with a route; the back link on small screens.
+	const parent = [...items.slice(0, -1)].reverse().find((crumb) => crumb.to);
+
+	return (
+		<nav aria-label="Breadcrumb" className="crumbs">
+			{parent && (
+				<Link to={parent.to} className="crumbs-back" aria-label={`Back to ${parent.label}`}>
+					<ChevronLeft size={18} aria-hidden="true" />
+					<span>{parent.label}</span>
+				</Link>
+			)}
+			<ol className="crumbs-trail">
+				{items.map((crumb, index) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: a label may repeat in a trail, and a trail never reorders
+					<li key={`${crumb.label}-${index}`}>
+						{index > 0 && <span aria-hidden="true">/</span>}
+						{crumb.to ? (
+							<Link to={crumb.to} className="hover:underline">
+								{crumb.label}
+							</Link>
+						) : (
+							<span aria-current="page">{crumb.label}</span>
+						)}
+					</li>
+				))}
+			</ol>
+		</nav>
+	);
+}

package/src/app/layout/DesktopRail.tsx

@@ -0,0 +1,168 @@
+import { Link } from "@tanstack/react-router";
+import { PanelLeftClose, PanelLeftOpen } from "lucide-react";
+import { useAppConfig, useNav } from "../context/AppContext";
+import { cn } from "../lib/utils";
+import type { AppUser } from "../types";
+import { Button } from "../ui/button";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../ui/tooltip";
+import { isActivePath, isActiveSection, type NavItem } from "./nav";
+import { UserMenu } from "./UserMenu";
+
+export const RAIL_WIDTH = 256;
+export const RAIL_WIDTH_COLLAPSED = 80;
+
+interface DesktopRailProps {
+	pathname: string;
+	collapsed: boolean;
+	onToggle: () => void;
+	user: AppUser | null;
+	onLogout: () => void;
+}
+
+function RailLink({
+	item,
+	active,
+	collapsed,
+}: {
+	item: NavItem;
+	active: boolean;
+	collapsed: boolean;
+}) {
+	const Icon = item.icon;
+	const className = cn(
+		"flex items-center rounded-lg px-3 py-2.5 transition-colors duration-150 hover:bg-accent",
+		collapsed ? "justify-center" : "space-x-3 overflow-hidden",
+		active && "bg-primary/10 text-primary font-medium",
+	);
+	const link = (
+		<Link to={item.href} className={className} aria-current={active ? "page" : undefined}>
+			<Icon className="h-5 w-5 flex-shrink-0" />
+			{!collapsed && <span>{item.label}</span>}
+		</Link>
+	);
+	if (!collapsed) return link;
+	return (
+		<TooltipProvider>
+			<Tooltip delayDuration={0}>
+				<TooltipTrigger asChild>{link}</TooltipTrigger>
+				<TooltipContent side="right" className="font-medium text-sm">
+					<p>{item.label}</p>
+				</TooltipContent>
+			</Tooltip>
+		</TooltipProvider>
+	);
+}
+
+/**
+ * The desktop navigation rail (lg and up): brand, the sections, the active
+ * section's sub pages nested beneath it, and the user block at the foot.
+ * Collapsed, it is icons with tooltips and the sub pages fold away; the
+ * section landing page carries them as cards, so nothing is lost.
+ */
+export function DesktopRail({ pathname, collapsed, onToggle, user, onLogout }: DesktopRailProps) {
+	const appConfig = useAppConfig();
+	const navItems = useNav();
+	return (
+		<aside
+			aria-label="Main navigation"
+			style={{ width: collapsed ? RAIL_WIDTH_COLLAPSED : RAIL_WIDTH }}
+			className={cn(
+				"fixed left-0 top-0 z-40 h-screen bg-background border-r border-border/40",
+				"hidden lg:block transition-[width] duration-200 ease-out",
+			)}
+		>
+			<div className="flex h-full flex-col">
+				<div className="border-b border-border/40">
+					<div
+						className={cn(
+							"flex items-center px-6 py-5",
+							collapsed ? "flex-col space-y-3" : "justify-between",
+						)}
+					>
+						<Link
+							to="/"
+							className={cn(
+								"flex items-center overflow-hidden transition-opacity hover:opacity-80",
+								collapsed ? "justify-center" : "space-x-2",
+							)}
+							aria-label={`${appConfig.name} home`}
+						>
+							<span className="inline-block size-2 rounded-full bg-brand" aria-hidden="true" />
+							{!collapsed && (
+								<span className="text-lg font-medium tracking-tight">{appConfig.mark}</span>
+							)}
+						</Link>
+
+						<TooltipProvider>
+							<Tooltip delayDuration={0}>
+								<TooltipTrigger asChild>
+									<Button
+										variant="ghost"
+										size="icon"
+										onClick={onToggle}
+										className="flex-shrink-0 rounded-lg p-2 hover:bg-accent"
+										aria-label={collapsed ? "Expand sidebar" : "Collapse sidebar"}
+									>
+										{collapsed ? (
+											<PanelLeftOpen className="h-5 w-5" />
+										) : (
+											<PanelLeftClose className="h-5 w-5" />
+										)}
+									</Button>
+								</TooltipTrigger>
+								<TooltipContent
+									side={collapsed ? "right" : "bottom"}
+									className="font-medium text-sm"
+								>
+									<p>{collapsed ? "Expand sidebar" : "Collapse sidebar"}</p>
+								</TooltipContent>
+							</Tooltip>
+						</TooltipProvider>
+					</div>
+				</div>
+
+				<nav className="flex-1 space-y-1 px-4 py-6" aria-label="Primary navigation">
+					{navItems
+						.filter((item) => !item.mobileOnly)
+						.map((item) => {
+							const active = isActiveSection(pathname, item);
+							const showChildren = active && !collapsed && item.children?.length;
+							return (
+								<div key={item.href}>
+									<RailLink item={item} active={active} collapsed={collapsed} />
+									{showChildren ? (
+										<ul className="mt-1 space-y-0.5 pb-1" aria-label={`${item.label} pages`}>
+											{item.children?.map((child) => {
+												const childActive = isActivePath(pathname, child.href);
+												const ChildIcon = child.icon;
+												return (
+													<li key={child.href}>
+														<Link
+															to={child.href}
+															className={cn(
+																"flex items-center space-x-2.5 rounded-lg py-2 pl-11 pr-3 text-sm",
+																"text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground",
+																childActive && "bg-primary/10 text-primary font-medium",
+															)}
+															aria-current={childActive ? "page" : undefined}
+														>
+															<ChildIcon className="h-4 w-4 flex-shrink-0" />
+															<span>{child.label}</span>
+														</Link>
+													</li>
+												);
+											})}
+										</ul>
+									) : null}
+								</div>
+							);
+						})}
+				</nav>
+
+				<div className="border-t border-border/40 p-3">
+					<UserMenu user={user} onLogout={onLogout} collapsed={collapsed} />
+				</div>
+			</div>
+		</aside>
+	);
+}

package/src/app/layout/FormActionButtons.tsx

@@ -0,0 +1,69 @@
+import { Loader2 } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../ui/button";
+
+interface FormActionButtonsProps {
+	/** Submit handler (if not using form submission) */
+	onSave?: () => void;
+	/** Cancel handler */
+	onCancel: () => void;
+	/** Loading/submitting state */
+	isLoading?: boolean;
+	/** Disabled state */
+	disabled?: boolean;
+	/** Save button text */
+	saveText?: string;
+	/** Cancel button text */
+	cancelText?: string;
+	/** Additional className for the container */
+	className?: string;
+	/** Whether to show the cancel button */
+	showCancel?: boolean;
+}
+
+/**
+ * Standardized form action buttons for save/cancel operations.
+ * Responsive layout that stacks on mobile.
+ */
+export function FormActionButtons({
+	onSave,
+	onCancel,
+	isLoading = false,
+	disabled = false,
+	saveText = "Save",
+	cancelText = "Cancel",
+	className,
+	showCancel = true,
+}: FormActionButtonsProps) {
+	return (
+		<div className={cn("flex flex-col-reverse gap-3 sm:flex-row sm:justify-end", className)}>
+			{showCancel && (
+				<Button
+					type="button"
+					variant="outline"
+					onClick={onCancel}
+					disabled={isLoading}
+					className="w-full sm:w-auto"
+				>
+					{cancelText}
+				</Button>
+			)}
+			<Button
+				type={onSave ? "button" : "submit"}
+				variant="default"
+				disabled={disabled || isLoading}
+				onClick={onSave}
+				className="w-full sm:w-auto"
+			>
+				{isLoading ? (
+					<>
+						<Loader2 className="mr-2 h-4 w-4 animate-spin" />
+						Saving...
+					</>
+				) : (
+					saveText
+				)}
+			</Button>
+		</div>
+	);
+}