feat(01-03): add data hooks, utilities, UI store, and foundational components

- API fetch wrapper with error handling and multipart upload
- Weight/price formatters for display
- TanStack Query hooks for items, categories, and totals with cache invalidation
- Zustand UI store for panel and confirm dialog state
- TotalsBar, CategoryHeader, ItemCard, ConfirmDialog, ImageUpload components

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/client/components/CategoryHeader.tsx

@@ -0,0 +1,143 @@
+import { useState } from "react";
+import { formatWeight, formatPrice } from "../lib/formatters";
+import { useUpdateCategory, useDeleteCategory } from "../hooks/useCategories";
+
+interface CategoryHeaderProps {
+  categoryId: number;
+  name: string;
+  emoji: string;
+  totalWeight: number;
+  totalCost: number;
+  itemCount: number;
+}
+
+export function CategoryHeader({
+  categoryId,
+  name,
+  emoji,
+  totalWeight,
+  totalCost,
+  itemCount,
+}: CategoryHeaderProps) {
+  const [isEditing, setIsEditing] = useState(false);
+  const [editName, setEditName] = useState(name);
+  const [editEmoji, setEditEmoji] = useState(emoji);
+  const updateCategory = useUpdateCategory();
+  const deleteCategory = useDeleteCategory();
+
+  const isUncategorized = categoryId === 1;
+
+  function handleSave() {
+    if (!editName.trim()) return;
+    updateCategory.mutate(
+      { id: categoryId, name: editName.trim(), emoji: editEmoji },
+      { onSuccess: () => setIsEditing(false) },
+    );
+  }
+
+  function handleDelete() {
+    if (
+      confirm(`Delete category "${name}"? Items will be moved to Uncategorized.`)
+    ) {
+      deleteCategory.mutate(categoryId);
+    }
+  }
+
+  if (isEditing) {
+    return (
+      <div className="flex items-center gap-3 py-4">
+        <input
+          type="text"
+          value={editEmoji}
+          onChange={(e) => setEditEmoji(e.target.value)}
+          className="w-12 text-center text-xl border border-gray-200 rounded-md px-1 py-1"
+          maxLength={4}
+        />
+        <input
+          type="text"
+          value={editName}
+          onChange={(e) => setEditName(e.target.value)}
+          className="text-lg font-semibold border border-gray-200 rounded-md px-2 py-1"
+          onKeyDown={(e) => {
+            if (e.key === "Enter") handleSave();
+            if (e.key === "Escape") setIsEditing(false);
+          }}
+          autoFocus
+        />
+        <button
+          type="button"
+          onClick={handleSave}
+          className="text-sm text-blue-600 hover:text-blue-800 font-medium"
+        >
+          Save
+        </button>
+        <button
+          type="button"
+          onClick={() => setIsEditing(false)}
+          className="text-sm text-gray-400 hover:text-gray-600"
+        >
+          Cancel
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="group flex items-center gap-3 py-4">
+      <span className="text-xl">{emoji}</span>
+      <h2 className="text-lg font-semibold text-gray-900">{name}</h2>
+      <span className="text-sm text-gray-400">
+        {itemCount} {itemCount === 1 ? "item" : "items"} ·{" "}
+        {formatWeight(totalWeight)} · {formatPrice(totalCost)}
+      </span>
+      {!isUncategorized && (
+        <div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+          <button
+            type="button"
+            onClick={() => {
+              setEditName(name);
+              setEditEmoji(emoji);
+              setIsEditing(true);
+            }}
+            className="p-1 text-gray-400 hover:text-gray-600 rounded"
+            title="Edit category"
+          >
+            <svg
+              className="w-4 h-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M15.232 5.232l3.536 3.536m-2.036-5.036a2.5 2.5 0 113.536 3.536L6.5 21.036H3v-3.572L16.732 3.732z"
+              />
+            </svg>
+          </button>
+          <button
+            type="button"
+            onClick={handleDelete}
+            className="p-1 text-gray-400 hover:text-red-500 rounded"
+            title="Delete category"
+          >
+            <svg
+              className="w-4 h-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+              />
+            </svg>
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

src/client/components/ConfirmDialog.tsx

@@ -0,0 +1,61 @@
+import { useUIStore } from "../stores/uiStore";
+import { useDeleteItem } from "../hooks/useItems";
+import { useItems } from "../hooks/useItems";
+
+export function ConfirmDialog() {
+  const confirmDeleteItemId = useUIStore((s) => s.confirmDeleteItemId);
+  const closeConfirmDelete = useUIStore((s) => s.closeConfirmDelete);
+  const deleteItem = useDeleteItem();
+  const { data: items } = useItems();
+
+  if (confirmDeleteItemId == null) return null;
+
+  const item = items?.find((i) => i.id === confirmDeleteItemId);
+  const itemName = item?.name ?? "this item";
+
+  function handleDelete() {
+    if (confirmDeleteItemId == null) return;
+    deleteItem.mutate(confirmDeleteItemId, {
+      onSuccess: () => closeConfirmDelete(),
+    });
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div
+        className="absolute inset-0 bg-black/30"
+        onClick={closeConfirmDelete}
+        onKeyDown={(e) => {
+          if (e.key === "Escape") closeConfirmDelete();
+        }}
+      />
+      <div className="relative bg-white rounded-xl shadow-lg p-6 max-w-sm mx-4 w-full">
+        <h3 className="text-lg font-semibold text-gray-900 mb-2">
+          Delete Item
+        </h3>
+        <p className="text-sm text-gray-600 mb-6">
+          Are you sure you want to delete{" "}
+          <span className="font-medium">{itemName}</span>? This action cannot be
+          undone.
+        </p>
+        <div className="flex justify-end gap-3">
+          <button
+            type="button"
+            onClick={closeConfirmDelete}
+            className="px-4 py-2 text-sm font-medium text-gray-700 bg-gray-100 hover:bg-gray-200 rounded-lg transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleDelete}
+            disabled={deleteItem.isPending}
+            className="px-4 py-2 text-sm font-medium text-white bg-red-600 hover:bg-red-700 disabled:opacity-50 rounded-lg transition-colors"
+          >
+            {deleteItem.isPending ? "Deleting..." : "Delete"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/client/components/ImageUpload.tsx

@@ -0,0 +1,95 @@
+import { useState, useRef } from "react";
+import { apiUpload } from "../lib/api";
+
+interface ImageUploadProps {
+  value: string | null;
+  onChange: (filename: string | null) => void;
+}
+
+const MAX_SIZE_BYTES = 5 * 1024 * 1024; // 5MB
+const ACCEPTED_TYPES = ["image/jpeg", "image/png", "image/webp"];
+
+export function ImageUpload({ value, onChange }: ImageUploadProps) {
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  async function handleFileChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    setError(null);
+
+    if (!ACCEPTED_TYPES.includes(file.type)) {
+      setError("Please select a JPG, PNG, or WebP image.");
+      return;
+    }
+
+    if (file.size > MAX_SIZE_BYTES) {
+      setError("Image must be under 5MB.");
+      return;
+    }
+
+    setUploading(true);
+    try {
+      const result = await apiUpload<{ filename: string }>(
+        "/api/images",
+        file,
+      );
+      onChange(result.filename);
+    } catch {
+      setError("Upload failed. Please try again.");
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <div>
+      {value && (
+        <div className="mb-2 relative">
+          <img
+            src={`/uploads/${value}`}
+            alt="Item"
+            className="w-full h-32 object-cover rounded-lg"
+          />
+          <button
+            type="button"
+            onClick={() => onChange(null)}
+            className="absolute top-1 right-1 p-1 bg-white/80 hover:bg-white rounded-full text-gray-600 hover:text-gray-900"
+          >
+            <svg
+              className="w-4 h-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </button>
+        </div>
+      )}
+      <button
+        type="button"
+        onClick={() => inputRef.current?.click()}
+        disabled={uploading}
+        className="w-full py-2 px-3 border border-dashed border-gray-300 rounded-lg text-sm text-gray-500 hover:border-gray-400 hover:text-gray-600 transition-colors disabled:opacity-50"
+      >
+        {uploading ? "Uploading..." : value ? "Change image" : "Add image"}
+      </button>
+      <input
+        ref={inputRef}
+        type="file"
+        accept="image/jpeg,image/png,image/webp"
+        onChange={handleFileChange}
+        className="hidden"
+      />
+      {error && <p className="mt-1 text-xs text-red-500">{error}</p>}
+    </div>
+  );
+}

src/client/components/ItemCard.tsx

@@ -0,0 +1,62 @@
+import { formatWeight, formatPrice } from "../lib/formatters";
+import { useUIStore } from "../stores/uiStore";
+
+interface ItemCardProps {
+  id: number;
+  name: string;
+  weightGrams: number | null;
+  priceCents: number | null;
+  categoryName: string;
+  categoryEmoji: string;
+  imageFilename: string | null;
+}
+
+export function ItemCard({
+  id,
+  name,
+  weightGrams,
+  priceCents,
+  categoryName,
+  categoryEmoji,
+  imageFilename,
+}: ItemCardProps) {
+  const openEditPanel = useUIStore((s) => s.openEditPanel);
+
+  return (
+    <button
+      type="button"
+      onClick={() => openEditPanel(id)}
+      className="w-full text-left bg-white rounded-xl border border-gray-100 hover:border-gray-200 hover:shadow-sm transition-all overflow-hidden"
+    >
+      {imageFilename && (
+        <div className="aspect-[4/3] bg-gray-50">
+          <img
+            src={`/uploads/${imageFilename}`}
+            alt={name}
+            className="w-full h-full object-cover"
+          />
+        </div>
+      )}
+      <div className="p-4">
+        <h3 className="text-sm font-semibold text-gray-900 mb-2 truncate">
+          {name}
+        </h3>
+        <div className="flex flex-wrap gap-1.5">
+          {weightGrams != null && (
+            <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700">
+              {formatWeight(weightGrams)}
+            </span>
+          )}
+          {priceCents != null && (
+            <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-700">
+              {formatPrice(priceCents)}
+            </span>
+          )}
+          <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-gray-50 text-gray-600">
+            {categoryEmoji} {categoryName}
+          </span>
+        </div>
+      </div>
+    </button>
+  );
+}

src/client/components/TotalsBar.tsx

@@ -0,0 +1,38 @@
+import { useTotals } from "../hooks/useTotals";
+import { formatWeight, formatPrice } from "../lib/formatters";
+
+export function TotalsBar() {
+  const { data } = useTotals();
+
+  const global = data?.global;
+
+  return (
+    <div className="sticky top-0 z-10 bg-white border-b border-gray-100">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <div className="flex items-center justify-between h-14">
+          <h1 className="text-lg font-semibold text-gray-900">GearBox</h1>
+          <div className="flex items-center gap-6 text-sm text-gray-500">
+            <span>
+              <span className="font-medium text-gray-700">
+                {global?.itemCount ?? 0}
+              </span>{" "}
+              items
+            </span>
+            <span>
+              <span className="font-medium text-gray-700">
+                {formatWeight(global?.totalWeight ?? null)}
+              </span>{" "}
+              total
+            </span>
+            <span>
+              <span className="font-medium text-gray-700">
+                {formatPrice(global?.totalCost ?? null)}
+              </span>{" "}
+              spent
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/client/hooks/useCategories.ts

@@ -0,0 +1,53 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { apiGet, apiPost, apiPut, apiDelete } from "../lib/api";
+import type { Category, CreateCategory } from "../../shared/types";
+
+export function useCategories() {
+  return useQuery({
+    queryKey: ["categories"],
+    queryFn: () => apiGet<Category[]>("/api/categories"),
+  });
+}
+
+export function useCreateCategory() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: CreateCategory) =>
+      apiPost<Category>("/api/categories", data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["categories"] });
+    },
+  });
+}
+
+export function useUpdateCategory() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      id,
+      ...data
+    }: {
+      id: number;
+      name?: string;
+      emoji?: string;
+    }) => apiPut<Category>(`/api/categories/${id}`, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["categories"] });
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+      queryClient.invalidateQueries({ queryKey: ["totals"] });
+    },
+  });
+}
+
+export function useDeleteCategory() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (id: number) =>
+      apiDelete<{ success: boolean }>(`/api/categories/${id}`),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["categories"] });
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+      queryClient.invalidateQueries({ queryKey: ["totals"] });
+    },
+  });
+}

src/client/hooks/useItems.ts

@@ -0,0 +1,69 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { apiGet, apiPost, apiPut, apiDelete } from "../lib/api";
+import type { CreateItem } from "../../shared/types";
+
+interface ItemWithCategory {
+  id: number;
+  name: string;
+  weightGrams: number | null;
+  priceCents: number | null;
+  categoryId: number;
+  notes: string | null;
+  productUrl: string | null;
+  imageFilename: string | null;
+  createdAt: string;
+  updatedAt: string;
+  categoryName: string;
+  categoryEmoji: string;
+}
+
+export function useItems() {
+  return useQuery({
+    queryKey: ["items"],
+    queryFn: () => apiGet<ItemWithCategory[]>("/api/items"),
+  });
+}
+
+export function useItem(id: number | null) {
+  return useQuery({
+    queryKey: ["items", id],
+    queryFn: () => apiGet<ItemWithCategory>(`/api/items/${id}`),
+    enabled: id != null,
+  });
+}
+
+export function useCreateItem() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: CreateItem) =>
+      apiPost<ItemWithCategory>("/api/items", data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+      queryClient.invalidateQueries({ queryKey: ["totals"] });
+    },
+  });
+}
+
+export function useUpdateItem() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, ...data }: { id: number } & Partial<CreateItem>) =>
+      apiPut<ItemWithCategory>(`/api/items/${id}`, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+      queryClient.invalidateQueries({ queryKey: ["totals"] });
+    },
+  });
+}
+
+export function useDeleteItem() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (id: number) =>
+      apiDelete<{ success: boolean }>(`/api/items/${id}`),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+      queryClient.invalidateQueries({ queryKey: ["totals"] });
+    },
+  });
+}

src/client/hooks/useTotals.ts

@@ -0,0 +1,31 @@
+import { useQuery } from "@tanstack/react-query";
+import { apiGet } from "../lib/api";
+
+interface CategoryTotals {
+  categoryId: number;
+  categoryName: string;
+  categoryEmoji: string;
+  totalWeight: number;
+  totalCost: number;
+  itemCount: number;
+}
+
+interface GlobalTotals {
+  totalWeight: number;
+  totalCost: number;
+  itemCount: number;
+}
+
+interface TotalsResponse {
+  categories: CategoryTotals[];
+  global: GlobalTotals;
+}
+
+export type { CategoryTotals, GlobalTotals, TotalsResponse };
+
+export function useTotals() {
+  return useQuery({
+    queryKey: ["totals"],
+    queryFn: () => apiGet<TotalsResponse>("/api/totals"),
+  });
+}

src/client/lib/api.ts

@@ -0,0 +1,61 @@
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+async function handleResponse<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    let message = `Request failed with status ${res.status}`;
+    try {
+      const body = await res.json();
+      if (body.error) message = body.error;
+    } catch {
+      // Use default message
+    }
+    throw new ApiError(message, res.status);
+  }
+  return res.json() as Promise<T>;
+}
+
+export async function apiGet<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  return handleResponse<T>(res);
+}
+
+export async function apiPost<T>(url: string, body: unknown): Promise<T> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return handleResponse<T>(res);
+}
+
+export async function apiPut<T>(url: string, body: unknown): Promise<T> {
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return handleResponse<T>(res);
+}
+
+export async function apiDelete<T>(url: string): Promise<T> {
+  const res = await fetch(url, { method: "DELETE" });
+  return handleResponse<T>(res);
+}
+
+export async function apiUpload<T>(url: string, file: File): Promise<T> {
+  const formData = new FormData();
+  formData.append("file", file);
+  const res = await fetch(url, {
+    method: "POST",
+    body: formData,
+  });
+  return handleResponse<T>(res);
+}

src/client/lib/formatters.ts

@@ -0,0 +1,9 @@
+export function formatWeight(grams: number | null | undefined): string {
+  if (grams == null) return "--";
+  return `${Math.round(grams)}g`;
+}
+
+export function formatPrice(cents: number | null | undefined): string {
+  if (cents == null) return "--";
+  return `$${(cents / 100).toFixed(2)}`;
+}

src/client/stores/uiStore.ts

@@ -0,0 +1,25 @@
+import { create } from "zustand";
+
+interface UIState {
+  panelMode: "closed" | "add" | "edit";
+  editingItemId: number | null;
+  confirmDeleteItemId: number | null;
+
+  openAddPanel: () => void;
+  openEditPanel: (itemId: number) => void;
+  closePanel: () => void;
+  openConfirmDelete: (itemId: number) => void;
+  closeConfirmDelete: () => void;
+}
+
+export const useUIStore = create<UIState>((set) => ({
+  panelMode: "closed",
+  editingItemId: null,
+  confirmDeleteItemId: null,
+
+  openAddPanel: () => set({ panelMode: "add", editingItemId: null }),
+  openEditPanel: (itemId) => set({ panelMode: "edit", editingItemId: itemId }),
+  closePanel: () => set({ panelMode: "closed", editingItemId: null }),
+  openConfirmDelete: (itemId) => set({ confirmDeleteItemId: itemId }),
+  closeConfirmDelete: () => set({ confirmDeleteItemId: null }),
+}));