Calendar/calendar-complete-specification.md

# Complete Calendar Component Specification

## 1. Project Overview

### Purpose
Build a professional calendar component with week, day, and month views, featuring drag-and-drop functionality, event management, and real-time synchronization.

### Technology Stack
- **Frontend**: Vanilla JavaScript (ES Modules), ready for TypeScript conversion
- **Styling**: CSS with nested selectors, CSS Grid/Flexbox
- **Backend** (planned): .NET Core with SignalR
- **Architecture**: Modular manager-based system with event-driven communication

### Design Principles
1. **Modularity**: Each manager handles one specific concern
2. **Loose Coupling**: Communication via custom events on document
3. **No External Dependencies**: Pure JavaScript implementation
4. **Custom HTML Tags**: Semantic markup without Web Components registration
5. **CSS-based Positioning**: Events positioned using CSS calc() and variables

## 2. What Has Been Implemented

### 2.1 Core Infrastructure

#### EventBus.js ✅
- Central event dispatcher for all calendar events
- Publish/subscribe pattern implementation
- Debug logging capabilities
- Event history tracking
- Priority-based listeners

#### CalendarConfig.js ✅
- Centralized configuration management
- Default values for all settings
- DOM data-attribute reading
- Computed value calculations (minuteHeight, totalSlots, etc.)
- Configuration change events

#### EventTypes.js ✅
- All event type constants defined
- Organized by category (view, CRUD, interaction, UI, data, state)
- Consistent naming convention

### 2.2 Managers

#### GridManager.js ✅
- Renders time axis with configurable hours
- Creates week headers with day names and dates
- Generates day columns for events
- Sets up grid interactions (click, dblclick)
- Updates CSS variables for dynamic styling
- Handles grid click position calculations with snap

#### DataManager.js ✅
- Mock data generation for testing
- API request preparation (ready for backend)
- Cache management
- Event CRUD operations
- Loading state management
- Sync status handling

### 2.3 Utilities

#### DateUtils.js ✅
- Week start/end calculations
- Date/time formatting (12/24 hour)
- Duration calculations
- Time-to-minutes conversions
- Week number calculation (ISO standard)
- Snap-to-interval logic

### 2.4 Styles

#### base.css ✅
- CSS reset and variables
- Color scheme definition
- Grid measurements
- Animation keyframes
- Utility classes

#### layout.css ✅
- Main calendar container structure
- CSS Grid layout for calendar
- Time axis styling
- Week headers with sticky positioning
- Scrollable content area
- Work hours background indication

#### navigation.css ✅
- Top navigation bar layout
- Button styling (prev/next/today)
- View selector (day/week/month)
- Search box with icons
- Week info display

#### events.css ✅
- Event card styling by type
- Hover and active states
- Resize handles design
- Multi-day event styling
- Sync status indicators
- CSS-based positioning system

#### popup.css ✅
- Event popup styling
- Chevron arrow positioning
- Action buttons
- Loading overlay
- Snap indicators

### 2.5 HTML Structure ✅
- Semantic custom HTML tags
- Modular component structure
- No inline styles or JavaScript
- Data attributes for configuration

## 3. Implementation Details

### 3.1 Event Positioning System
```css
swp-event {
  /* Position via CSS variables */
  top: calc(var(--start-minutes) * var(--minute-height));
  height: calc(var(--duration-minutes) * var(--minute-height));
}
```

### 3.2 Custom Event Flow
```javascript
// Example event flow for drag operation
1. User mousedown on event
2. DragManager → emit('calendar:dragstart')
3. ResizeManager → disable()
4. GridManager → show snap lines
5. User mousemove
6. DragManager → emit('calendar:dragmove')
7. EventRenderer → update ghost position
8. User mouseup
9. DragManager → emit('calendar:dragend')
10. EventManager → update event data
11. DataManager → sync to backend
```

### 3.3 Configuration Options
```javascript
{
  view: 'week',          // 'day' | 'week' | 'month'
  weekDays: 7,           // 4-7 days for week view
  dayStartHour: 7,       // Calendar start time
  dayEndHour: 19,        // Calendar end time
  workStartHour: 8,      // Work hours highlighting
  workEndHour: 17,
  snapInterval: 15,      // Minutes: 5, 10, 15, 30, 60
  hourHeight: 60,        // Pixels per hour
  showCurrentTime: true,
  allowDrag: true,
  allowResize: true,
  allowCreate: true
}
```

## 4. What Needs to Be Implemented

### 4.1 Missing Managers

#### CalendarManager.js 🔲
**Purpose**: Main coordinator for all managers
```javascript
class CalendarManager {
  - Initialize all managers in correct order
  - Handle app lifecycle (start, destroy)
  - Coordinate cross-manager operations
  - Global error handling
  - State persistence
}
```

#### ViewManager.js 🔲
**Purpose**: Handle view mode changes
```javascript
class ViewManager {
  - Switch between day/week/month views
  - Calculate visible date range
  - Update grid structure for view
  - Emit view change events
  - Handle view-specific settings
}
```

#### NavigationManager.js 🔲
**Purpose**: Handle navigation controls
```javascript
class NavigationManager {
  - Previous/Next period navigation
  - Today button functionality
  - Update week info display
  - Coordinate with animations
  - Handle navigation limits
}
```

#### EventManager.js 🔲
**Purpose**: Manage event lifecycle
```javascript
class EventManager {
  - Store events in memory
  - Handle event CRUD operations
  - Manage event selection
  - Calculate event overlaps
  - Validate event constraints
}
```

#### EventRenderer.js 🔲
**Purpose**: Render events in DOM
```javascript
class EventRenderer {
  - Create event DOM elements
  - Calculate pixel positions
  - Handle collision layouts
  - Render multi-day events
  - Update event appearance
}
```

#### DragManager.js 🔲
**Purpose**: Handle drag operations
```javascript
class DragManager {
  - Track drag state
  - Create ghost element
  - Calculate snap positions
  - Validate drop targets
  - Handle multi-select drag
}
```

#### ResizeManager.js 🔲
**Purpose**: Handle resize operations
```javascript
class ResizeManager {
  - Add/remove resize handles
  - Track resize direction
  - Calculate new duration
  - Enforce min/max limits
  - Snap to intervals
}
```

#### PopupManager.js 🔲
**Purpose**: Show event details popup
```javascript
class PopupManager {
  - Show/hide popup
  - Smart positioning (left/right)
  - Update popup content
  - Handle action buttons
  - Click-outside detection
}
```

#### SearchManager.js 🔲
**Purpose**: Search functionality
```javascript
class SearchManager {
  - Real-time search
  - Highlight matching events
  - Update transparency
  - Clear search
  - Search history
}
```

#### TimeManager.js 🔲
**Purpose**: Current time indicator
```javascript
class TimeManager {
  - Show red line at current time
  - Update position every minute
  - Auto-scroll to current time
  - Show/hide based on view
}
```

#### LoadingManager.js 🔲
**Purpose**: Loading states
```javascript
class LoadingManager {
  - Show/hide spinner
  - Block interactions
  - Show error states
  - Progress indication
}
```

### 4.2 Missing Utilities

#### PositionUtils.js 🔲
```javascript
- pixelsToMinutes(y, config)
- minutesToPixels(minutes, config)
- getEventBounds(element)
- detectCollisions(events)
- calculateOverlapGroups(events)
```

#### SnapUtils.js 🔲
```javascript
- snapToInterval(value, interval)
- getNearestSlot(position, interval)
- calculateSnapPoints(config)
- isValidSnapPosition(position)
```

#### DOMUtils.js 🔲
```javascript
- createElement(tag, attributes, children)
- toggleClass(element, className, force)
- findParent(element, selector)
- batchUpdate(updates)
```

### 4.3 Missing Features

#### Animation System 🔲
- Week-to-week slide transition (as shown in POC)
- Smooth state transitions
- Drag preview animations
- Loading animations

#### Collision Detection System 🔲
```javascript
// Two strategies needed:
1. Side-by-side: Events share column width
2. Overlay: Events stack with z-index
```

#### Multi-day Event Support 🔲
- Events spanning multiple days
- Visual continuation indicators
- Proper positioning in week header area

#### Touch Support 🔲
- Touch drag/drop
- Pinch to zoom
- Swipe navigation
- Long press for context menu

#### Keyboard Navigation 🔲
- Tab through events
- Arrow keys for selection
- Enter to edit
- Delete key support

#### Context Menu 🔲
- Right-click on events
- Right-click on empty slots
- Quick actions menu

#### Event Creation 🔲
- Double-click empty slot
- Drag to create
- Default duration
- Inline editing

#### Advanced Features 🔲
- Undo/redo stack
- Copy/paste events
- Bulk operations
- Print view
- Export (iCal, PDF)
- Recurring events UI
- Event templates
- Color customization
- Resource scheduling
- Timezone support

## 5. Integration Points

### 5.1 Backend API Endpoints
```
GET    /api/events?start={date}&end={date}&view={view}
POST   /api/events
PATCH  /api/events/{id}
DELETE /api/events/{id}
GET    /api/events/search?q={query}
```

### 5.2 SignalR Events
```
- EventCreated
- EventUpdated  
- EventDeleted
- EventsReloaded
```

### 5.3 Data Models
```typescript
interface CalendarEvent {
  id: string;
  title: string;
  start: string; // ISO 8601
  end: string;   // ISO 8601
  type: 'meeting' | 'meal' | 'work' | 'milestone';
  allDay: boolean;
  syncStatus: 'synced' | 'pending' | 'error';
  recurringId?: string;
  resources?: string[];
  metadata?: Record<string, any>;
}
```

## 6. Performance Considerations

1. **Virtual Scrolling**: For large date ranges
2. **Event Pooling**: Reuse DOM elements
3. **Throttled Updates**: During drag/resize
4. **Batch Operations**: For multiple changes
5. **Lazy Loading**: Load events as needed
6. **Web Workers**: For heavy calculations

## 7. Testing Strategy

1. **Unit Tests**: Each manager/utility
2. **Integration Tests**: Manager interactions
3. **E2E Tests**: User workflows
4. **Performance Tests**: Large datasets
5. **Accessibility Tests**: Keyboard/screen reader

## 8. Deployment Considerations

1. **Build Process**: Bundle modules
2. **Minification**: Reduce file size
3. **Code Splitting**: Load on demand
4. **CDN**: Static assets
5. **Monitoring**: Error tracking
6. **Analytics**: Usage patterns

## 9. Future Enhancements

1. **AI Integration**: Smart scheduling
2. **Mobile Apps**: Native wrappers
3. **Offline Support**: Service workers
4. **Collaboration**: Real-time cursors
5. **Advanced Analytics**: Usage insights
6. **Third-party Integrations**: Google Calendar, Outlook

## 10. Migration Path

### From POC to Production:
1. Extract animation logic from POC
2. Implement missing managers
3. Add error boundaries
4. Implement loading states
5. Add accessibility
6. Performance optimization
7. Security hardening
8. Documentation
9. Testing suite
10. Deployment pipeline