TimeTracker/docs/CALENDAR_FEATURES_README.md

📅 TimeTracker Calendar Features - Complete Guide

Overview

The Calendar feature provides a comprehensive visual interface for viewing, creating, editing, and managing time entries. It includes drag-and-drop functionality, multiple views, filtering, recurring events, and export capabilities.

---

✨ Features

1. Multiple Calendar Views

• Day View: Hour-by-hour view of a single day
• Week View: 7-day week view with time slots (default)
• Month View: Monthly calendar with all-day event display
• Agenda View: List view grouped by date

2. Visual Event Management

• Color-coded events by project (10 distinct colors)
• Detailed event information on hover
• Event duration displayed in each block
• Real-time current time indicator
• Today highlighting in all views

3. Drag-and-Drop Editing

• Move events by dragging to different times/days
• Resize events by dragging edges to adjust duration
• Auto-save when events are moved or resized
• Smooth animations for all interactions

4. Advanced Filtering

• Filter by Project
• Filter by Task (dynamic based on selected project)
• Filter by Tags (with debounced search)
• Clear all filters with one click
• Filters apply across all views

5. Event Creation

• Click and drag to create new events
• New Event button for manual creation
• Pre-select project before creating
• Full form with:
  • Project selection (required)
  • Task selection (optional, dynamic)
  • Start/End date and time
  • Notes and tags
  • Billable flag

6. Event Details & Editing

• Click any event to view details
• Detailed modal showing:
  • Project and task information
  • Start/end times with formatted dates
  • Duration in hours
  • Notes and tags
  • Billable status
  • Source (manual vs automatic timer)
• Quick edit button to modify entry
• Delete button with confirmation

7. Recurring Events

• Manage recurring time blocks
• View all recurring templates
• See active/inactive status
• Edit or delete recurring blocks
• Automatic generation based on schedule
• Supports weekly recurrence with weekday selection

8. Export Functionality

• iCal format (.ics) - Import into Google Calendar, Outlook, Apple Calendar
• CSV format - Open in Excel, Google Sheets, or any spreadsheet software
• Exports respect current filters
• Exports current view's date range
• Includes all event details

9. Smart Time Slot Configuration

• Work hours: 6:00 AM to 10:00 PM
• 30-minute time slots
• Scrollable to any time
• Sticky header stays visible when scrolling

10. Responsive Design

• Desktop-optimized layout with side-by-side controls
• Tablet-friendly with collapsible controls
• Mobile-responsive with stacked layout
• Touch-optimized for mobile devices

---

🎯 Usage Guide

Accessing the Calendar

Navigate to the calendar via:

1. Main Navigation: Work → Calendar
2. Direct URL: /timer/calendar

Creating Time Entries

Method 1: Click and Drag

1. Select a project from the "Assign to project" dropdown
2. Click and drag on the calendar to select a time range
3. Form opens with pre-filled times
4. Fill in optional details (task, notes, tags)
5. Click "Create"

Method 2: New Event Button

1. Select a project from the "Assign to project" dropdown
2. Click the "New Event" button
3. Set start and end times manually
4. Fill in all details
5. Click "Create"

Editing Time Entries

Quick Edit (Drag and Drop)

1. Click and drag an event to move it to a different time/day
2. Drag the top or bottom edge to resize (change duration)
3. Changes save automatically

Full Edit

1. Click on any event to open details
2. Click "Edit" button
3. Opens the full edit form
4. Make changes and save

Deleting Time Entries

1. Click on any event
2. Click "Delete" button
3. Confirm deletion
4. Entry is removed from calendar

Using Filters

Filter by Project

1. Select a project from "All Projects" dropdown
2. Calendar updates to show only that project's entries
3. Task filter becomes available

Filter by Task

1. First select a project
2. Select a task from "All Tasks" dropdown
3. Calendar shows only entries for that project+task

Filter by Tags

1. Type tags in the "Filter by tags" field
2. Search is debounced (waits 500ms after typing)
3. Calendar shows entries matching any tag

Clear Filters

Click the "Clear" button to reset all filters

Changing Views

Calendar Views

• Click Day for day view
• Click Week for week view (default)
• Click Month for month view
• Click Today to jump to current date

Agenda View

1. Click Agenda button
2. View switches to list format
3. Events grouped by date
4. Click any event to see details

Exporting Calendar Data

Export as iCal

1. Click "Export" dropdown
2. Select "iCal Format"
3. Downloads .ics file
4. Import into your calendar app

Export as CSV

1. Click "Export" dropdown
2. Select "CSV Format"
3. Downloads .csv file
4. Open in Excel or Google Sheets

Note: Exports include the current view's date range and respect any active filters.

Managing Recurring Events

1. Click "Recurring" button
2. View all recurring time blocks
3. Each block shows:
   • Name and status
   • Associated project
   • Recurrence pattern
   • Time window
4. Click "Edit" to modify a block
5. Click "Delete" to remove a block
6. Click "New Recurring Block" to create one

---

🎨 Visual Design

Color Coding

Events are automatically color-coded by project:

• Project 1: Blue (#3b82f6)
• Project 2: Red (#ef4444)
• Project 3: Green (#10b981)
• Project 4: Amber (#f59e0b)
• Project 5: Purple (#8b5cf6)
• And so on... (10 colors rotate)

Event Display

Each event shows:

• Title: Project name • Task name (or note preview)
• Time: Start and end time
• Visual: Colored left border matching project
• Hover: Subtle lift animation

Status Indicators

• Billable: Green badge
• Non-billable: Gray badge
• Active Timer: Pulsing indicator
• Past Events: Slightly dimmed

---

⚙️ Technical Details

API Endpoints

Get Calendar Events

GET /api/calendar/events?start=<ISO>&end=<ISO>&project_id=<id>&task_id=<id>&tags=<string>

Query Parameters:

• start (required): ISO datetime for range start
• end (required): ISO datetime for range end
• project_id (optional): Filter by project
• task_id (optional): Filter by task
• tags (optional): Filter by tags (partial match)
• user_id (optional, admin only): View another user's calendar

Response:

{
  "events": [
    {
      "id": 123,
      "title": "Project Name • Task Name",
      "start": "2025-10-07T09:00:00",
      "end": "2025-10-07T11:00:00",
      "editable": true,
      "allDay": false,
      "backgroundColor": "#3b82f6",
      "borderColor": "#3b82f6",
      "extendedProps": {
        "project_id": 1,
        "project_name": "Project Name",
        "task_id": 5,
        "task_name": "Task Name",
        "notes": "Some notes",
        "tags": "tag1, tag2",
        "billable": true,
        "duration_hours": 2.0,
        "user_id": 1,
        "source": "manual"
      }
    }
  ]
}

Export Calendar

GET /api/calendar/export?start=<ISO>&end=<ISO>&format=<ical|csv>&project_id=<id>

Query Parameters:

• start (required): ISO datetime for range start
• end (required): ISO datetime for range end
• format (default: ical): Export format (ical or csv)
• project_id (optional): Filter by project

Response:

• iCal: .ics file download
• CSV: .csv file download

Update Event Time

PUT /api/entry/<id>
{
  "start_time": "2025-10-07T09:00:00",
  "end_time": "2025-10-07T11:00:00"
}

Delete Event

DELETE /api/entry/<id>

Get Recurring Blocks

GET /api/recurring-blocks

JavaScript Components

FullCalendar Configuration

{
  initialView: 'timeGridWeek',
  selectable: true,
  editable: true,
  nowIndicator: true,
  firstDay: 1,  // Monday
  slotDuration: '00:30:00',
  slotMinTime: '06:00:00',
  slotMaxTime: '22:00:00',
  eventResizableFromStart: true
}

Event Handlers

• select: Handle time range selection
• eventClick: Show event details
• eventDrop: Handle drag move
• eventResize: Handle resize

CSS Classes

Calendar Container:

• .calendar-header - Top control bar
• .calendar-controls - Button groups
• .calendar-filters - Filter controls
• .calendar-legend - Color legend

Events:

• .fc-event - Calendar event
• .fc-event:hover - Hover state

Modals:

• .event-modal - Modal overlay
• .event-modal-content - Modal dialog
• .event-modal-header - Modal header
• .event-modal-body - Modal content
• .event-modal-footer - Modal buttons

Agenda View:

• .agenda-view - Agenda container
• .agenda-date-group - Date grouping
• .agenda-event - Event item

---

🔧 Configuration

Customizing Colors

Edit the color array in app/routes/api.py:

def get_project_color(project_id):
    colors = [
        '#3b82f6',  # Blue
        '#ef4444',  # Red
        '#10b981',  # Green
        '#f59e0b',  # Amber
        '#8b5cf6',  # Purple
        # Add more colors...
    ]
    return colors[project_id % len(colors)]

Adjusting Time Slots

Edit FullCalendar config in templates/timer/calendar.html:

{
  slotDuration: '00:15:00',  // 15-minute slots
  slotMinTime: '08:00:00',   // Start at 8 AM
  slotMaxTime: '18:00:00',   // End at 6 PM
}

Changing First Day of Week

{
  firstDay: 0,  // 0 = Sunday, 1 = Monday
}

---

🚀 Performance

Optimization Features

1. Lazy Loading: Events load only for visible date range
2. Debounced Filters: Tag filter waits 500ms before searching
3. Efficient Queries: Database queries use indexes
4. Client-side Caching: FullCalendar caches rendered events
5. Minimal DOM Updates: Only changed events are re-rendered

Best Practices

1. Use filters to reduce displayed events
2. Shorter date ranges load faster
3. Avoid excessive drag operations in rapid succession
4. Close modals when not in use to free memory

---

📱 Mobile Support

Mobile Optimizations

1. Responsive Layout: Single-column on small screens
2. Touch Events: Optimized tap and drag handlers
3. Larger Touch Targets: Buttons sized for finger interaction
4. Simplified Views: Day/Month preferred over week on mobile
5. Collapsible Filters: Filters stack vertically

Mobile Limitations

• Drag-and-drop may be less precise on small touchscreens
• Week view can be cramped - use Day or Agenda instead
• Filter dropdowns may require scrolling

---

♿ Accessibility

Keyboard Navigation

• Tab: Navigate between controls
• Enter/Space: Activate buttons
• Escape: Close modals
• Arrow Keys: Navigate calendar (when focused)

Screen Reader Support

• ARIA labels on all interactive elements
• Semantic HTML structure
• Focus management in modals
• Descriptive button text

Visual Accessibility

• High contrast colors
• Large click targets
• Clear hover states
• Focus indicators

---

🐛 Troubleshooting

Events Not Loading

1. Check browser console for errors
2. Verify /api/calendar/events endpoint is accessible
3. Check date range parameters
4. Ensure user is authenticated

Drag-and-Drop Not Working

1. Ensure editable: true in calendar config
2. Check user permissions
3. Verify event is not an active timer
4. Check for JavaScript errors

Filters Not Applying

1. Clear browser cache
2. Check that filter dropdowns have values
3. Verify API endpoint supports filter parameters
4. Check network tab for API calls

Export Not Downloading

1. Check popup blocker settings
2. Verify /api/calendar/export endpoint
3. Ensure date range is valid
4. Check server logs for errors

Recurring Events Not Showing

1. Verify /api/recurring-blocks endpoint
2. Check that blocks are marked as active
3. Ensure date range includes block schedule
4. Verify block generation logic is running

---

🔜 Future Enhancements

Potential additions:

1. Multi-user View: See team calendars side-by-side
2. Calendar Sync: Two-way sync with Google Calendar/Outlook
3. Time Zone Support: Display events in multiple time zones
4. Template Events: Save and reuse common entries
5. Advanced Recurring: Support monthly, yearly patterns
6. Calendar Sharing: Share view-only calendar links
7. Event Conflicts: Visual indicators for overlapping entries
8. Batch Operations: Select multiple events for bulk actions
9. Calendar Widgets: Embeddable calendar for other pages
10. AI Suggestions: Smart event creation based on patterns

---

📚 Related Documentation

• Bulk Time Entry
• Task Management
• Project Management
• API Documentation

---

💡 Tips & Tricks

1. Quick Project Switch: Keep the project dropdown visible at all times for fast entry creation
2. Keyboard Shortcuts: Use ? to open command palette, or Ctrl+K to quickly search
3. Week View Default: Start each session in week view for best overview
4. Color Recognition: Learn your project colors to quickly identify entries
5. Agenda for Planning: Use agenda view for day planning and reviews
6. Export for Billing: Export filtered calendar as CSV for invoicing
7. Recurring Templates: Set up recurring blocks for regular meetings
8. Tag Consistently: Use consistent tags for powerful filtering
9. Notes for Context: Add notes to entries for future reference
10. Mobile Agenda: Use agenda view on mobile for better readability

---

📞 Support

Getting Help

1. Check this documentation
2. Review browser console for errors
3. Check network tab for failed API calls
4. Verify database connectivity

Common Issues

Issue: Calendar shows no events Solution: Check filters, verify date range, ensure you have time entries

Issue: Can't create new events Solution: Select a project first in the "Assign to project" dropdown

Issue: Drag-and-drop not saving Solution: Check network connectivity and server logs

Issue: Export downloads empty file Solution: Ensure date range has events, check server permissions

---

The Calendar feature is production-ready and provides a comprehensive visual interface for time tracking! 📅