264 lines
6.5 KiB
Markdown
264 lines
6.5 KiB
Markdown
# Web UI Implementation
|
|
|
|
## Overview
|
|
|
|
The Mosaic Stack web UI provides a PDA-friendly interface for managing tasks and events with Authentik OIDC authentication.
|
|
|
|
## Features
|
|
|
|
### Authentication
|
|
|
|
- **Login Page:** Clean landing page with Authentik OIDC integration
|
|
- **Session Management:** Automatic session refresh and validation
|
|
- **Protected Routes:** Automatic redirect for unauthenticated users
|
|
- **Logout:** Clean session termination
|
|
|
|
### Task Management
|
|
|
|
- **Task List View:** Grouped by date (Today, Tomorrow, This Week, etc.)
|
|
- **PDA-Friendly Language:** No demanding terms like "overdue" or "urgent"
|
|
- **Status Indicators:** Visual emoji-based status (🟢 In Progress, ⚪ Not Started, etc.)
|
|
- **Priority Badges:** Calm, non-aggressive priority display
|
|
|
|
### Calendar
|
|
|
|
- **Event List View:** Chronological event display
|
|
- **Time Display:** Clear start/end times with location
|
|
- **Date Grouping:** Same grouping as tasks for consistency
|
|
- **All-Day Events:** Proper handling of all-day events
|
|
|
|
### Navigation
|
|
|
|
- **Fixed Header:** Always accessible navigation
|
|
- **Active Route Highlighting:** Clear visual indication
|
|
- **User Display:** Shows logged-in user name/email
|
|
- **Responsive:** Mobile-friendly design
|
|
|
|
## PDA-Friendly Design Principles
|
|
|
|
### Language
|
|
|
|
- ❌ **Never Use:** OVERDUE, URGENT, CRITICAL, MUST DO, REQUIRED
|
|
- ✅ **Always Use:** Target passed, Approaching target, High priority, Recommended
|
|
|
|
### Status Indicators
|
|
|
|
- 🟢 In Progress / Active
|
|
- 🔵 Not Started / Upcoming
|
|
- ⏸️ Paused / On hold
|
|
- 💤 Archived / Inactive
|
|
- ✅ Completed
|
|
- ⚪ Default/Other
|
|
|
|
### Visual Design
|
|
|
|
- **10-second scannability:** Key info immediately visible
|
|
- **Visual chunking:** Clear sections with headers
|
|
- **Single-line items:** Compact, scannable lists
|
|
- **Progressive disclosure:** Details available on interaction
|
|
- **Calm colors:** No aggressive reds or warnings
|
|
|
|
## Technology Stack
|
|
|
|
- **Framework:** Next.js 16 with App Router
|
|
- **UI:** TailwindCSS + Shadcn/ui
|
|
- **State:** React Context + Hooks
|
|
- **Data Fetching:** @tanstack/react-query (prepared)
|
|
- **Date Handling:** date-fns
|
|
- **Type Safety:** TypeScript with @mosaic/shared types
|
|
- **Testing:** Vitest + React Testing Library
|
|
|
|
## File Structure
|
|
|
|
```
|
|
apps/web/src/
|
|
├── app/
|
|
│ ├── (auth)/
|
|
│ │ ├── login/ # Login page
|
|
│ │ └── callback/ # OAuth callback handler
|
|
│ ├── (authenticated)/
|
|
│ │ ├── layout.tsx # Protected route wrapper
|
|
│ │ ├── tasks/ # Task list page
|
|
│ │ └── calendar/ # Calendar page
|
|
│ ├── layout.tsx # Root layout with AuthProvider
|
|
│ └── page.tsx # Home redirect
|
|
├── components/
|
|
│ ├── auth/ # Login/Logout buttons
|
|
│ ├── tasks/ # TaskList, TaskItem
|
|
│ ├── calendar/ # Calendar, EventCard
|
|
│ └── layout/ # Navigation
|
|
├── lib/
|
|
│ ├── auth/ # Auth context and hooks
|
|
│ ├── api/ # API clients (tasks, events)
|
|
│ └── utils/ # Date formatting utilities
|
|
└── middleware.ts # (Future: Route protection)
|
|
```
|
|
|
|
## API Integration
|
|
|
|
### Authentication Endpoints
|
|
|
|
- `GET /auth/session` - Get current session
|
|
- `POST /auth/sign-out` - Logout
|
|
- `GET /auth/oauth2/callback/authentik` - OIDC callback
|
|
|
|
### Future Endpoints (Mock Data Ready)
|
|
|
|
- `GET /api/tasks` - List tasks
|
|
- `GET /api/events` - List events
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# API Connection
|
|
NEXT_PUBLIC_API_URL=http://localhost:3001
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Run development server
|
|
pnpm dev
|
|
|
|
# Build for production
|
|
pnpm build
|
|
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Run with coverage
|
|
pnpm test:coverage
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Test Coverage
|
|
|
|
- **API Client:** 100% coverage
|
|
- **Auth Context:** Comprehensive tests
|
|
- **Date Utilities:** All functions tested
|
|
- **Components:** Tests for all major components
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
pnpm test
|
|
|
|
# Watch mode
|
|
pnpm test:watch
|
|
|
|
# With coverage
|
|
pnpm test:coverage
|
|
```
|
|
|
|
## Usage
|
|
|
|
### For Users
|
|
|
|
1. **Login:**
|
|
- Visit `/login`
|
|
- Click "Sign In with Authentik"
|
|
- Authenticate via Authentik
|
|
- Redirected to tasks page
|
|
|
|
2. **View Tasks:**
|
|
- Navigate to "Tasks"
|
|
- See tasks grouped by date
|
|
- View status and priority
|
|
- Note: PDA-friendly language throughout
|
|
|
|
3. **View Calendar:**
|
|
- Navigate to "Calendar"
|
|
- See events grouped by date
|
|
- View event times and locations
|
|
|
|
4. **Logout:**
|
|
- Click "Sign Out" in navigation
|
|
- Session cleared
|
|
- Redirected to login
|
|
|
|
### For Developers
|
|
|
|
**Adding a New Component:**
|
|
|
|
1. Create component in appropriate directory
|
|
2. Write tests FIRST (TDD)
|
|
3. Implement component
|
|
4. Use PDA-friendly language
|
|
5. Export from index if needed
|
|
|
|
**Connecting Real API:**
|
|
|
|
```typescript
|
|
// Replace mock data with real API call
|
|
import { useQuery } from "@tanstack/react-query";
|
|
import { fetchTasks } from "@/lib/api/tasks";
|
|
|
|
const { data: tasks, isLoading } = useQuery({
|
|
queryKey: ["tasks"],
|
|
queryFn: fetchTasks,
|
|
});
|
|
```
|
|
|
|
**Using Shared Types:**
|
|
|
|
```typescript
|
|
import type { Task, Event, AuthUser } from "@mosaic/shared";
|
|
import { TaskStatus, TaskPriority } from "@mosaic/shared";
|
|
```
|
|
|
|
## Accessibility
|
|
|
|
- Semantic HTML structure
|
|
- Proper heading hierarchy
|
|
- ARIA labels for status indicators
|
|
- Keyboard navigation support
|
|
- Screen reader friendly
|
|
|
|
## Performance
|
|
|
|
- Static page generation where possible
|
|
- Code splitting with Next.js App Router
|
|
- Optimized images and assets
|
|
- Minimal bundle size
|
|
|
|
## Security
|
|
|
|
- Session-based authentication
|
|
- CSRF protection via cookies
|
|
- Protected routes
|
|
- No sensitive data in client
|
|
- Type-safe API integration
|
|
|
|
## Known Limitations
|
|
|
|
1. **Mock Data:** Tasks and events currently use mock data. Backend endpoints pending.
|
|
2. **CRUD Operations:** Currently read-only. Create/Update/Delete pending.
|
|
3. **Real-time Updates:** No WebSocket integration yet.
|
|
4. **Offline Support:** No PWA features yet.
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Task creation/editing UI
|
|
- [ ] Event creation/editing UI
|
|
- [ ] Real-time updates via WebSockets
|
|
- [ ] Drag-and-drop task reordering
|
|
- [ ] Calendar month view
|
|
- [ ] Search and filters
|
|
- [ ] Mobile app (React Native)
|
|
- [ ] Offline support (PWA)
|
|
- [ ] Notifications
|
|
- [ ] Collaboration features
|
|
|
|
## Resources
|
|
|
|
- [Next.js Documentation](https://nextjs.org/docs)
|
|
- [TailwindCSS Documentation](https://tailwindcss.com/docs)
|
|
- [React Testing Library](https://testing-library.com/react)
|
|
- [Mosaic Stack Project](../README.md)
|
|
- [PDA-Friendly Design Principles](./DESIGN-PRINCIPLES.md)
|