# Four — Daily Focus Planner A local-first daily task manager that limits users to four active priorities, helping them choose, focus on, and complete meaningful work. ## Masterplan - **Vision:** Replace overwhelming task lists with a calm, intentional “four priorities” daily planning ritual. - **Target users:** Individuals who want lightweight daily focus without accounts, collaboration, or complex project management. - **Core value:** Users can create, color-code, complete, edit, delete, and focus on up to four active priorities at once. - **Current scope:** Single-device browser app with seeded example tasks and `localStorage` persistence; there is no backend, authentication, sync, notifications, or true scheduled reminder system. - **Branding note:** Although the original app prompt calls this “Quick Task Manager,” the implemented product is branded **Four** throughout `index.html`, `src/components/AppShell.tsx`, and page metadata. ## Tech Stack & Architecture - **React + TypeScript** application bootstrapped with **Vite**. - **React Router DOM** uses `HashRouter` in `src/App.tsx`. Routes work on static hosting without server-side route rewrites: - `#/` — dashboard - `#/settings` — settings - unmatched routes — not-found page - **Tailwind-style utility classes** are used throughout JSX. Shared visual tokens, custom component classes, animations, chart colors, and responsive styling live in `src/styles/main.css`. - **Lucide React** supplies all interface icons. - **Google Fonts** loaded in `index.html`: - `Manrope` for UI/headings - `DM Mono` for dates, numbering, and labels - `clsx` and `tailwind-merge` are wrapped by `cn()` in `src/lib/utils.ts` to safely compose conditional class names. ### Component and state architecture `src/main.tsx` imports global CSS, mounts React in `StrictMode`, and wraps the entire app in `AppErrorBoundary`. Provider hierarchy in `src/App.tsx`: ```tsx ``` - `TaskProvider` (`src/context/TaskContext.tsx`) is the single source of truth for tasks, settings, and current focus selection. - `ToastProvider` (`src/components/ToastProvider.tsx`) handles transient success, info, and error messages. - Page-local UI state, such as whether a modal is open or which task is being edited, stays in `DashboardPage.tsx`. - Persistence is deliberately asynchronous at the context boundary even though current `localStorage` calls are synchronous. Keep mutation methods returning `Promise` so storage can later be replaced by an API without changing consumers. ### Persistence `src/lib/storage.ts` is the app’s only persistence layer. | Key | Contents | |---|---| | `four-priorities.tasks` | Serialized `PriorityTask[]` | | `four-priorities.settings` | Serialized `Settings` | Storage loaders validate parsed data and fall back to seed data on missing, malformed, or inaccessible storage. Do not bypass `saveTasks()` or `saveSettings()` from components. ## File Structure ```text index.html # Root document, metadata, Google font imports, React mount node. src/main.tsx # Imports CSS; mounts App inside AppErrorBoundary and StrictMode. src/App.tsx # Hash routes and global ToastProvider/TaskProvider composition. src/types.ts # PriorityTask, Settings, and TaskTone domain types. src/context/TaskContext.tsx # Task/settings state, persistence orchestration, focus state, toast feedback. src/lib/storage.ts # localStorage keys, validation, seed tasks/settings, save/load functions. src/lib/utils.ts # cn(), greeting, and locale-formatted current-date helpers. src/hooks/usePageMeta.ts # Updates document title and meta description per page. src/pages/DashboardPage.tsx # Main daily planner: hero, tasks, focus panel, dialogs, reset flow. src/pages/SettingsPage.tsx # User settings screen; edits persisted name and displayed reset time. src/pages/NotFoundPage.tsx # Fallback route for invalid hash paths. src/components/AppShell.tsx # Shared header/nav/footer around routed pages. src/components/AppErrorBoundary.tsx# Render-crash containment and reload action. src/components/Button.tsx # Shared button variants, loading state, focus/disabled behavior. src/components/TaskCard.tsx # Individual priority card and task actions. src/components/TaskDialog.tsx # Add/edit priority modal with title, note, and marker validation. src/components/ConfirmDialog.tsx # Destructive-action confirmation modal. src/components/Modal.tsx # Accessible modal foundation: focus trap, Escape, scroll lock. src/components/EmptyState.tsx # Dashboard zero-task state and add-task CTA. src/components/ToastProvider.tsx # Context API plus rendered, auto-dismissing toast stack. src/styles/main.css # Global tokens, base styles, visual utilities, task-tone styles, animation. vite.config.ts # Vite build/development configuration. package.json # Scripts and frontend dependencies. ``` ## Key Features ### Daily priorities The app manages `PriorityTask` records defined in `src/types.ts`: ```ts type PriorityTask = { id: string title: string note: string tone: 'coral' | 'indigo' | 'gold' | 'mint' completed: boolean createdAt: string } ``` Requirements implemented by `TaskContext` and `TaskDialog`: - A task title is required, trimmed before saving, and capped at 80 characters. - Notes are optional, trimmed before saving, and capped at 180 characters. - Each task has one marker tone: `coral`, `indigo`, `gold`, or `mint`. - New tasks receive `crypto.randomUUID()` IDs and ISO `createdAt` timestamps. - The app limits **active/incomplete** tasks to four. Completed tasks remain visible and do not consume an active slot. - The dashboard Add button is disabled when four active tasks exist. - The context also enforces the limit, so callers cannot circumvent it by invoking `addTask()` directly. - Tasks can be toggled complete/incomplete, edited, and deleted. - Deleting a task or completing the currently focused task clears active focus. ### Focus mode The dashboard chooses one incomplete task for the “Focus now” panel: 1. Use `activeFocusId` if it points to an incomplete task. 2. Otherwise use the first incomplete task. 3. Show an empty-focus state when no active tasks remain. “Focus here” changes only in-memory focus selection; it is not persisted between reloads. “Clear focus” sets `activeFocusId` to `null`, after which the UI falls back to the first active task by design. ### Progress and reset - Dashboard progress is calculated from all stored tasks: `completed / tasks.length`. - “Reset day” restores the fixed `seedTasks` array from `src/lib/storage.ts`. - Reset does **not** clear settings. - Seed task dates are static sample values, not generated daily. - `resetAt` is a saved display preference in `Settings`; no automatic timed reset is currently implemented. ### Settings `Settings` is intentionally small: ```ts type Settings = { name: string resetAt: string } ``` The dashboard greeting reads `settings.name`; `resetAt` represents the user’s preferred reset time. Settings are persisted under `four-priorities.settings`. ### Feedback and failure handling - Successful task and settings mutations show toasts. - Persistence failures are converted into user-facing error toasts and rejected promises. - `TaskDialog` catches failed saves and displays an inline retry message. - `AppErrorBoundary` prevents an uncaught render error from blanking the app and offers a full-page reload. - Toasts auto-dismiss after 4.2 seconds, are capped at four visible items, and may be dismissed manually. ### External integrations There are no APIs, backend services, authentication providers, analytics calls, notification services, or database integrations. Browser `localStorage`, Web Crypto (`crypto.randomUUID()`), `Intl.DateTimeFormat`, and Google-hosted fonts are the only runtime platform/external dependencies. ## Design Guidelines - **Tone:** Calm, focused, friendly, and editorial—not dense or productivity-dashboard-like. - **Layout:** Wide centered content (`max-w-7xl`) with generous spacing, rounded cards, thin borders, and subtle shadows. - **Primary visual motif:** The number “4,” four-color task markers, a dot-grid dashboard decoration, and a dedicated primary-color focus panel. - **Typography:** - `Manrope`: primary UI font; heavy/extrabold headings. - `DM Mono`: metadata such as dates, task numbers, and compact labels. - **Color semantics:** Use existing CSS semantic classes (`bg-primary`, `text-muted-foreground`, `bg-card`, `bg-destructive`, etc.), not hard-coded color values in components. - **Task tones:** Match `TaskTone` to existing CSS classes such as `tone-coral` and chart color utilities. Adding a tone requires changes to: 1. `TaskTone` in `src/types.ts` 2. validation in `isTask()` in `src/lib/storage.ts` 3. tone choices in `src/components/TaskDialog.tsx` 4. CSS tone styling in `src/styles/main.css` - **Responsive behavior:** - Header navigation hides text labels below `sm`, retaining icons. - Task cards become a two-column grid from `sm`. - Dashboard main content uses a sidebar at `lg`. - Modals appear bottom-aligned on small screens and centered from `sm`. - **Accessibility:** Preserve visible focus rings, labeled icon buttons, dialog semantics, Escape-to-close behavior, focus trapping, body scroll locking, and focus return to the element that opened a dialog. ## App Flow ### Primary journey 1. User opens `#/` and sees a date-aware greeting, task count, current focus, and saved priorities. 2. User selects **Add priority**. 3. `TaskDialog` validates the required title and saves through `addTask()`. 4. The new task persists to `localStorage`, appears in the grid, and triggers a success toast. 5. User may select **Focus here**, complete the task, edit it, or delete it. 6. Completion updates progress and removes that task from focus if necessary. ### Empty state If all tasks are deleted, `EmptyState` replaces the task grid and opens the same add-task dialog. A user can add tasks until four incomplete priorities exist. ### Reset journey 1. User chooses **Reset day** on the dashboard. 2. A `ConfirmDialog` requests confirmation. 3. Confirming replaces all stored tasks with `seedTasks`, clears manual focus, and shows a toast. ### Navigation `AppShell.tsx` provides two route buttons: - **Today** → `/` - **Settings** → `/settings` Use `useNavigate()` rather than raw anchors for internal app navigation so hash routing remains consistent. ### Key edge cases - Invalid or corrupted storage silently falls back to seeds. - A fifth active task is rejected even if a UI caller bypasses the disabled Add button. - Completed tasks remain editable and can be reopened. - A completed task cannot be focused. - Closing a dialog by overlay click, close button, or Escape restores focus to its trigger. - Do not assume `activeFocusId` is valid: tasks may be deleted or completed after it is selected. ## Conventions - Use TypeScript types from `src/types.ts`; do not redefine task shapes in individual components. - Use `useTasks()` for all task/settings mutations and `useToast()` for non-domain notifications. - Keep persistence and business rules in `TaskContext`, not page components. - Use `cn()` from `src/lib/utils.ts` for conditional Tailwind class composition. - Component files use PascalCase (`TaskCard.tsx`); hooks use camelCase with `use` prefix (`usePageMeta.ts`). - Prefer controlled form inputs and async submit handlers, matching `TaskDialog.tsx`. - Reuse `Button`, `Modal`, and `ConfirmDialog` rather than duplicating button/loading, modal, or confirmation behavior. - All newly added pages should call `usePageMeta()` and be registered in `src/App.tsx`. - For a new feature: 1. Add or extend domain types in `src/types.ts`. 2. Add persistence validation/migration behavior in `src/lib/storage.ts` if data is stored. 3. Expose mutations/state via `TaskContext.tsx`. 4. Build page-local UI from shared components. 5. Add route/navigation only when the feature needs its own page. 6. Maintain focus, keyboard, error, and toast behavior for all mutation paths. ## 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.