# 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)