# Task Tracker Full-stack task tracker with an Express in-memory API plus a React + TypeScript single-page dashboard that currently persists UI tasks in browser `localStorage`. ## Masterplan - Provide a lightweight personal task workflow for adding, filtering, completing, and deleting tasks without database setup. - Preserve the original Express API example in `server.js` with ephemeral `let tasks = []` storage for backend learning/demo use. - Deliver a polished SPA with validation, loading states, empty states, toast feedback, and responsive task controls. - Include an in-browser “Download all code” feature that generates the original Express + vanilla HTML/CSS/JS deliverable as a ZIP. ## Tech Stack & Architecture - **Backend:** Node.js, Express, `cors`, `crypto.randomUUID()` in `server.js`; listens on port `3000`. - **Frontend:** React 18, TypeScript, Vite, React Router `HashRouter`, Tailwind CSS v4 through `@tailwindcss/vite`. - **UI libraries:** `lucide-react` icons, `clsx` + `tailwind-merge` via `src/lib/cn.ts`. - **ZIP generation:** `jszip` in `src/lib/sourcePackage.ts`. - **Routing:** `src/App.tsx` wraps the app in `ToastProvider`, then `HashRouter`; only route is `/` → `TaskTrackerPage`. - **Frontend state:** local React state in `src/pages/TaskTrackerPage.tsx`; no global task store. Toast state lives in `src/components/ToastProvider.tsx`. - **Persistence gotcha:** although `server.js` implements a real API, the current frontend API client in `src/lib/api.ts` uses `window.localStorage`, not HTTP. `API_BASE_URL` is set to the descriptive string `localStorage://task-tracker/tasks`. - **Entrypoints:** - `index.html` mounts React into `#root` and loads `/src/main.tsx`. - `src/main.tsx` imports `src/styles/main.css`, validates `#root`, and renders ``. - `server.js` can be run separately for the Express API demo. ## File Structure ```text . ├── README.md # Setup/run notes, API table, and current project summary ├── index.html # Vite HTML entry, metadata, #root mount, generated visual-edit style block ├── package.json # npm scripts/dependencies for Vite, Express, Tailwind, JSZip ├── server.js # Express API on :3000 with CORS, JSON parsing, in-memory tasks ├── vite.config.ts # Vite React + Tailwind plugins; dev server host 0.0.0.0 port 5173 ├── tsconfig.json # Strict TS config for frontend and Vite config └── src/ ├── main.tsx # React bootstrap; throws if #root missing ├── App.tsx # ToastProvider + HashRouter + single route ├── pages/ │ └── TaskTrackerPage.tsx # Main dashboard: task CRUD UI, filters, counts, download ZIP ├── components/ │ ├── Button.tsx # Shared variant/size button with loading spinner │ ├── EmptyState.tsx # First-run and no-results panels │ ├── FetchErrorBlock.tsx # Retry panel; text still references Express server │ ├── InputField.tsx # Labeled accessible input with helper/error text │ └── ToastProvider.tsx # Toast context, auto-dismiss, manual dismiss ├── lib/ │ ├── api.ts # Current task persistence via localStorage CRUD helpers │ ├── cn.ts # Tailwind class merge utility │ └── sourcePackage.ts # JSZip source archive generator for vanilla deliverable ├── styles/ │ └── main.css # Tailwind import, light/dark design tokens, base styles, toast animation └── types/ └── task.ts # Task and TaskFilter TypeScript types ``` ## Key Features ### Task Data Model Shared frontend model in `src/types/task.ts`: ```ts interface Task { id: string; title: string; completed: boolean; } type TaskFilter = "all" | "active" | "completed"; ``` ### Current Frontend Persistence Implemented in `src/lib/api.ts`. - Reads/writes JSON at `localStorage` key `task-tracker.tasks`. - Creates IDs with `window.crypto.randomUUID()` when available, otherwise timestamp/random fallback. - All methods are `async` to preserve an API-like calling pattern even though operations are local. - Validation mirrors backend behavior: - empty/whitespace title throws `"Task title is required."` - missing ID throws `"Task not found."` - non-boolean `completed` throws `"Completed must be a boolean."` Functions: ```ts fetchTasks(): Promise createTask(title: string): Promise updateTask(id: string, updates: Partial>): Promise deleteTask(id: string): Promise getErrorMessage(error: unknown): string ``` ### Express API Implemented in `server.js`. Storage is intentionally ephemeral: ```js let tasks = []; ``` API surface: | Method | Path | Behavior | | --- | --- | --- | | `GET` | `/tasks` | Returns all tasks. | | `POST` | `/tasks` | Creates `{ id, title: trimmedTitle, completed: false }`; returns `400` for empty/non-string title. | | `PATCH` | `/tasks/:id` | Updates `title` and/or `completed`; validates both; returns `404` for missing task. | | `DELETE` | `/tasks/:id` | Deletes task; returns `204`; returns `404` for missing task. | Important: the React app does **not** currently call these endpoints. To switch back to HTTP, replace `src/lib/api.ts` internals with `fetch("http://localhost:3000/tasks")` calls and keep the exported function signatures stable. ### Dashboard UI Implemented in `src/pages/TaskTrackerPage.tsx`. Requirements: - Heading/dashboard page for Task Tracker. - Add-task form with controlled input, trim validation, touched-state error display, submit loading state. - Task list with: - completion toggle, - completed/active visual state, - delete action with per-task loading state, - toast feedback for create/update/delete failures and successes. - Filters: All, Active, Completed. - Counts for total, active, and completed tasks. - Empty states: - first-run when no tasks exist, - no-results when current filter has no matches. - Document metadata is updated on mount to “Task Tracker Dashboard for Teams” and browser-storage description. ### Download Source ZIP Implemented by `src/lib/sourcePackage.ts` and triggered from `TaskTrackerPage`. - Archive name: `task-tracker-express-vanilla.zip`. - Uses JSZip entirely in the browser. - Generates a separate original-style deliverable containing: - `README.md` - `package.json` - `server.js` - `frontend/index.html` - This ZIP is not a copy of the React app; it is a vanilla HTML/CSS/JS + Express version matching the original prompt. ## Design Guidelines - **Style:** modern card-based dashboard with soft borders, rounded corners, subtle shadows, and a radial blue background accent. - **Color tokens:** defined in `src/styles/main.css` as HSL CSS variables and mapped into Tailwind v4 `@theme`. - Primary blue: `--primary` - Destructive red: `--destructive` - Muted surfaces: `--muted`, `--secondary`, `--accent` - **Dark mode:** automatic via `@media (prefers-color-scheme: dark)`; do not add manual theme state unless the whole token strategy is updated. - **Typography:** system sans stack with Inter first: `Inter, ui-sans-serif, system-ui, ...`. - **Components:** use Tailwind utility classes directly in components; merge conditional classes with `cn()`. - **Responsive behavior:** main dashboard controls should stack on small screens and use horizontal layouts at `sm`/larger breakpoints. Toasts are fixed top-right, full-width minus margins on small screens. - **Accessibility:** keep labels on inputs, `aria-busy` for loading buttons, `aria-live` toast region, `role="alert"` for fetch/input errors, and screen-reader labels for icon-only states. ## App Flow 1. **Initial load** - `src/main.tsx` renders `App`. - `TaskTrackerPage` updates metadata and calls `loadTasks()`. - `fetchTasks()` reads `task-tracker.tasks` from browser storage. - UI shows loading, then tasks or first-run empty state. 2. **Create task** - User enters a title and submits. - Whitespace-only values show `"Task title is required."` and focus the input. - `createTask()` trims and stores the task. - Page reloads tasks from storage, clears input, and shows a success toast. 3. **Filter tasks** - User selects All/Active/Completed. - Filtering is derived with `useMemo`; no persistence of filter. - If no tasks match, `EmptyState` offers a clear-filter action. 4. **Toggle completion** - User clicks completion control. - Task ID is added to `updatingIds` for per-row loading/disabled behavior. - `updateTask()` persists the new `completed` value. - Local state is patched with the returned task. 5. **Delete task** - User clicks delete. - Task ID is added to `deletingIds`. - `deleteTask()` removes from storage. - Local state filters out the task and shows a toast. 6. **Download source** - User clicks the download code action. - `downloadSourceCodeZip()` builds a ZIP Blob in-browser and triggers a download link. - Toast confirms success/failure. Edge cases: - Corrupt `localStorage` JSON currently causes `JSON.parse` to throw and surface through `fetchError`. - `FetchErrorBlock.tsx` still instructs users to run `npm run server`; that message is stale for localStorage failures but useful if `api.ts` is switched back to HTTP. - Backend task data resets on every `server.js` restart; frontend localStorage data does not. - Generated `data-genmb-id` attributes and the visual-edit style block in `index.html` should not be treated as app logic. ## Conventions - Use `PascalCase` for React components and filenames under `src/components` and `src/pages`. - Use named exports for utility functions and types; default exports for React components. - Keep task operations centralized behind `src/lib/api.ts`; UI code should not access `localStorage` or `fetch` directly. - Keep `Task` shape synchronized between `src/types/task.ts`, `src/lib/api.ts`, `server.js`, and `src/lib/sourcePackage.ts`. - Use `Set` state for per-task mutation tracking (`deletingIds`, `updatingIds`) and always replace with a new `Set` to trigger React updates. - New shared UI should be added under `src/components/` and styled with Tailwind utilities plus existing CSS tokens. - To add a new page: 1. create `src/pages/NewPage.tsx`; 2. import it in `src/App.tsx`; 3. add a `} />`; 4. keep `HashRouter` unless deployment is changed to support history fallback. - To add a new task field: 1. update `src/types/task.ts`; 2. update validation/persistence in `src/lib/api.ts`; 3. update Express handlers in `server.js`; 4. update rendered rows/forms in `TaskTrackerPage.tsx`; 5. update generated vanilla files in `src/lib/sourcePackage.ts` if the downloadable deliverable must match. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.

Task Tracker App