From 720460852c5956220a19e47fd3fffc4c9f2d412f Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Mon, 6 Apr 2026 08:02:59 +0200
Subject: [PATCH] feat(20-02): add FabMenu and CatalogSearchOverlay components

- FabMenu with animated mini menu (Add to Collection, Start Thread, New Setup)
- CatalogSearchOverlay with debounced search, tag chip filtering, result cards
- Loading skeleton grid and empty state
- Framer Motion animations for menu entrance/exit and overlay transitions
---
 .../components/CatalogSearchOverlay.tsx       | 262 ++++++++++++++++++
 src/client/components/FabMenu.tsx             | 115 ++++++++
 2 files changed, 377 insertions(+)
 create mode 100644 src/client/components/CatalogSearchOverlay.tsx
 create mode 100644 src/client/components/FabMenu.tsx

diff --git a/src/client/components/CatalogSearchOverlay.tsx b/src/client/components/CatalogSearchOverlay.tsx
new file mode 100644
index 0000000..913096b
--- /dev/null
+++ b/src/client/components/CatalogSearchOverlay.tsx
@@ -0,0 +1,262 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { ArrowLeft } from "lucide-react";
+import { useEffect, useState } from "react";
+import { useFormatters } from "../hooks/useFormatters";
+import { useGlobalItems } from "../hooks/useGlobalItems";
+import { useTags } from "../hooks/useTags";
+import { useUIStore } from "../stores/uiStore";
+
+export function CatalogSearchOverlay() {
+	const catalogSearchOpen = useUIStore((s) => s.catalogSearchOpen);
+	const catalogSearchMode = useUIStore((s) => s.catalogSearchMode);
+	const closeCatalogSearch = useUIStore((s) => s.closeCatalogSearch);
+
+	const [searchInput, setSearchInput] = useState("");
+	const [debouncedQuery, setDebouncedQuery] = useState("");
+	const [selectedTags, setSelectedTags] = useState<string[]>([]);
+
+	const { weight, price } = useFormatters();
+	const { data: tags } = useTags();
+	const { data: items, isLoading } = useGlobalItems(
+		debouncedQuery || undefined,
+		selectedTags.length > 0 ? selectedTags : undefined,
+	);
+
+	// Debounce search input
+	useEffect(() => {
+		const timer = setTimeout(() => {
+			setDebouncedQuery(searchInput);
+		}, 300);
+		return () => clearTimeout(timer);
+	}, [searchInput]);
+
+	// Lock body scroll when overlay is open
+	useEffect(() => {
+		if (catalogSearchOpen) {
+			document.body.style.overflow = "hidden";
+		} else {
+			document.body.style.overflow = "";
+		}
+		return () => {
+			document.body.style.overflow = "";
+		};
+	}, [catalogSearchOpen]);
+
+	// Reset state when overlay closes
+	useEffect(() => {
+		if (!catalogSearchOpen) {
+			setSearchInput("");
+			setDebouncedQuery("");
+			setSelectedTags([]);
+		}
+	}, [catalogSearchOpen]);
+
+	function toggleTag(tagName: string) {
+		setSelectedTags((prev) =>
+			prev.includes(tagName)
+				? prev.filter((t) => t !== tagName)
+				: [...prev, tagName],
+		);
+	}
+
+	function handleAddStub() {
+		// Stub: actual add-to-collection / add-to-thread wired in Phase 21
+	}
+
+	const contextText =
+		catalogSearchMode === "collection"
+			? "Adding to Collection"
+			: "Starting a Thread";
+
+	return (
+		<AnimatePresence>
+			{catalogSearchOpen && (
+				<motion.div
+					className="fixed inset-0 z-50 bg-white flex flex-col"
+					initial={{ opacity: 0, y: 20 }}
+					animate={{ opacity: 1, y: 0 }}
+					exit={{ opacity: 0, y: 20 }}
+					transition={{ duration: 0.2, ease: "easeOut" }}
+				>
+					{/* Header */}
+					<div className="border-b border-gray-100">
+						<div className="flex items-center gap-3 px-4 py-3">
+							<button
+								type="button"
+								onClick={closeCatalogSearch}
+								className="p-1 -ml-1 text-gray-500 hover:text-gray-700 transition-colors"
+							>
+								<ArrowLeft className="w-5 h-5" />
+							</button>
+							<span className="text-sm font-medium text-gray-500">
+								{contextText}
+							</span>
+						</div>
+
+						{/* Search input */}
+						<div className="px-4 pb-3">
+							<input
+								type="text"
+								value={searchInput}
+								onChange={(e) => setSearchInput(e.target.value)}
+								placeholder="Search the catalog..."
+								className="w-full text-lg px-4 py-3 border border-gray-200 rounded-lg text-gray-900 placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-gray-200 focus:border-gray-300 transition-colors"
+								autoFocus
+							/>
+						</div>
+
+						{/* Tag chips */}
+						{tags && tags.length > 0 && (
+							<div className="flex gap-2 overflow-x-auto px-4 pb-3 no-scrollbar">
+								{tags.map((tag) => {
+									const isActive = selectedTags.includes(tag.name);
+									return (
+										<button
+											key={tag.id}
+											type="button"
+											onClick={() => toggleTag(tag.name)}
+											className={`rounded-full px-3 py-1.5 text-sm font-medium cursor-pointer transition-colors whitespace-nowrap ${
+												isActive
+													? "bg-blue-100 text-blue-700"
+													: "bg-gray-100 text-gray-500"
+											}`}
+										>
+											{tag.name}
+										</button>
+									);
+								})}
+							</div>
+						)}
+					</div>
+
+					{/* Results */}
+					<div className="flex-1 overflow-y-auto">
+						{isLoading ? (
+							<SkeletonGrid />
+						) : items && items.length > 0 ? (
+							<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 p-4">
+								{items.map((item) => (
+									<div
+										key={item.id}
+										className="bg-white rounded-xl border border-gray-100 overflow-hidden"
+									>
+										<div className="aspect-[4/3] bg-gray-50">
+											{item.imageUrl ? (
+												<img
+													src={item.imageUrl}
+													alt={`${item.brand} ${item.model}`}
+													className="w-full h-full object-cover"
+												/>
+											) : (
+												<div className="w-full h-full flex items-center justify-center">
+													<svg
+														className="w-9 h-9 text-gray-300"
+														fill="none"
+														stroke="currentColor"
+														viewBox="0 0 24 24"
+													>
+														<path
+															strokeLinecap="round"
+															strokeLinejoin="round"
+															strokeWidth={1.5}
+															d="M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4"
+														/>
+													</svg>
+												</div>
+											)}
+										</div>
+										<div className="p-4">
+											<p className="text-xs font-medium text-gray-400 uppercase tracking-wide mb-0.5">
+												{item.brand}
+											</p>
+											<h3 className="text-sm font-semibold text-gray-900 truncate mb-2">
+												{item.model}
+											</h3>
+											<div className="flex flex-wrap gap-1.5 mb-3">
+												{item.weightGrams != null && (
+													<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-400">
+														{weight(item.weightGrams)}
+													</span>
+												)}
+												{item.priceCents != null && (
+													<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-500">
+														{price(item.priceCents)}
+													</span>
+												)}
+												{item.category && (
+													<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-gray-50 text-gray-600">
+														{item.category}
+													</span>
+												)}
+											</div>
+											<button
+												type="button"
+												onClick={handleAddStub}
+												className="bg-gray-700 text-white rounded-lg px-3 py-1.5 text-xs font-medium hover:bg-gray-800 transition-colors"
+											>
+												Add
+											</button>
+										</div>
+									</div>
+								))}
+							</div>
+						) : (
+							<EmptyState
+								hasQuery={!!debouncedQuery || selectedTags.length > 0}
+							/>
+						)}
+					</div>
+				</motion.div>
+			)}
+		</AnimatePresence>
+	);
+}
+
+function SkeletonGrid() {
+	return (
+		<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 p-4">
+			{[1, 2, 3, 4, 5, 6].map((id) => (
+				<div
+					key={id}
+					className="bg-white rounded-xl border border-gray-100 overflow-hidden animate-pulse"
+				>
+					<div className="aspect-[4/3] bg-gray-100" />
+					<div className="p-4 space-y-2">
+						<div className="h-3 bg-gray-100 rounded w-16" />
+						<div className="h-4 bg-gray-100 rounded w-32" />
+						<div className="flex gap-1.5">
+							<div className="h-5 bg-gray-100 rounded-full w-14" />
+							<div className="h-5 bg-gray-100 rounded-full w-14" />
+						</div>
+						<div className="h-7 bg-gray-100 rounded-lg w-12 mt-2" />
+					</div>
+				</div>
+			))}
+		</div>
+	);
+}
+
+function EmptyState({ hasQuery }: { hasQuery: boolean }) {
+	return (
+		<div className="flex flex-col items-center justify-center py-20 px-4">
+			<svg
+				className="w-12 h-12 text-gray-300 mb-4"
+				fill="none"
+				stroke="currentColor"
+				viewBox="0 0 24 24"
+			>
+				<path
+					strokeLinecap="round"
+					strokeLinejoin="round"
+					strokeWidth={1.5}
+					d="M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4"
+				/>
+			</svg>
+			<p className="text-sm text-gray-500 text-center">
+				{hasQuery
+					? "No items found matching your search"
+					: "Search the catalog to find gear"}
+			</p>
+		</div>
+	);
+}
diff --git a/src/client/components/FabMenu.tsx b/src/client/components/FabMenu.tsx
new file mode 100644
index 0000000..2b76c8f
--- /dev/null
+++ b/src/client/components/FabMenu.tsx
@@ -0,0 +1,115 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { Package, Plus, Search } from "lucide-react";
+import { useUIStore } from "../stores/uiStore";
+
+interface FabMenuProps {
+	isSetupsPage: boolean;
+}
+
+const spring = { type: "spring", stiffness: 400, damping: 25 } as const;
+
+interface MenuItem {
+	label: string;
+	icon: React.ReactNode;
+	onClick: () => void;
+}
+
+export function FabMenu({ isSetupsPage }: FabMenuProps) {
+	const fabMenuOpen = useUIStore((s) => s.fabMenuOpen);
+	const openFabMenu = useUIStore((s) => s.openFabMenu);
+	const closeFabMenu = useUIStore((s) => s.closeFabMenu);
+	const openCatalogSearch = useUIStore((s) => s.openCatalogSearch);
+	const catalogSearchOpen = useUIStore((s) => s.catalogSearchOpen);
+
+	// Hide FAB when catalog search overlay is open
+	if (catalogSearchOpen) return null;
+
+	const menuItems: MenuItem[] = [
+		{
+			label: "Add to Collection",
+			icon: <Package className="w-5 h-5 text-gray-600" />,
+			onClick: () => openCatalogSearch("collection"),
+		},
+		{
+			label: "Start New Thread",
+			icon: <Search className="w-5 h-5 text-gray-600" />,
+			onClick: () => openCatalogSearch("thread"),
+		},
+	];
+
+	if (isSetupsPage) {
+		menuItems.push({
+			label: "New Setup",
+			icon: <Plus className="w-5 h-5 text-gray-600" />,
+			onClick: () => {
+				closeFabMenu();
+				// Stub: setup creation is handled by the setups page itself
+			},
+		});
+	}
+
+	function handleFabClick() {
+		if (fabMenuOpen) {
+			closeFabMenu();
+		} else {
+			openFabMenu();
+		}
+	}
+
+	return (
+		<>
+			{/* Backdrop */}
+			<AnimatePresence>
+				{fabMenuOpen && (
+					<motion.div
+						className="fixed inset-0 z-10 bg-black/20"
+						initial={{ opacity: 0 }}
+						animate={{ opacity: 1 }}
+						exit={{ opacity: 0 }}
+						transition={{ duration: 0.15 }}
+						onClick={closeFabMenu}
+					/>
+				)}
+			</AnimatePresence>
+
+			{/* Menu items */}
+			<AnimatePresence>
+				{fabMenuOpen && (
+					<div className="fixed bottom-24 right-6 z-20 flex flex-col-reverse gap-3">
+						{menuItems.map((item, index) => (
+							<motion.button
+								key={item.label}
+								type="button"
+								className="flex items-center gap-3 bg-white shadow-lg rounded-full px-4 py-3 hover:bg-gray-50 transition-colors"
+								initial={{ opacity: 0, y: 10, scale: 0.9 }}
+								animate={{ opacity: 1, y: 0, scale: 1 }}
+								exit={{ opacity: 0, y: 10, scale: 0.9 }}
+								transition={{
+									...spring,
+									delay: index * 0.05,
+								}}
+								onClick={item.onClick}
+							>
+								{item.icon}
+								<span className="text-sm font-medium text-gray-700 whitespace-nowrap">
+									{item.label}
+								</span>
+							</motion.button>
+						))}
+					</div>
+				)}
+			</AnimatePresence>
+
+			{/* FAB button */}
+			<motion.button
+				type="button"
+				className="fixed bottom-6 right-6 z-20 w-14 h-14 bg-gray-700 hover:bg-gray-800 text-white rounded-full shadow-lg hover:shadow-xl transition-colors flex items-center justify-center"
+				onClick={handleFabClick}
+				animate={{ rotate: fabMenuOpen ? 45 : 0 }}
+				transition={spring}
+			>
+				<Plus className="w-6 h-6" />
+			</motion.button>
+		</>
+	);
+}