callumalpass_tasknotes/issue-analysis/issue-854.md

Issue #854 Analysis: All Day ICS Events Showing on Wrong Day

Problem Understanding

Issue Description

All-day events imported from ICS calendars are displaying one day earlier than they should. This affects users in all timezones, particularly those with negative UTC offsets (e.g., PST/UTC-8, EST/UTC-5).

Example Scenario

• ICS Event: All-day event on January 20, 2025 (DTSTART;VALUE=DATE:20250120)
• Expected Display: January 20, 2025 in all timezones
• Actual Display (Bug): January 19, 2025 in PST (UTC-8) and other negative UTC offset timezones

Root Cause

The bug is in the icalTimeToISOString method in ICSSubscriptionService.ts:34-51. When processing all-day events (where icalTime.isDate is true), the code creates a UTC timestamp at midnight:

if (icalTime.isDate) {
    return new Date(Date.UTC(
        icalTime.year,
        icalTime.month - 1,
        icalTime.day
    )).toISOString();
}

This creates a timestamp like 2025-01-20T00:00:00.000Z (midnight UTC). When JavaScript's Date object interprets this in a timezone with a negative UTC offset:

• PST (UTC-8): 2025-01-20T00:00:00.000Z → January 19, 2025 at 4:00 PM local time
• EST (UTC-5): 2025-01-20T00:00:00.000Z → January 19, 2025 at 7:00 PM local time

The date shifts to the previous day because midnight UTC is still the previous day in these timezones.

Why This Happens

All-day events in ICS format don't have a timezone - they represent a calendar date, not a point in time. The iCalendar specification (RFC 5545) treats VALUE=DATE events as "floating" dates that should appear on the same calendar date regardless of timezone. However, the current implementation converts them to a specific UTC moment (midnight), which breaks this invariant.

Test File Location

Test File

Location: /home/calluma/projects/tasknotes-analysis/tests/unit/issues/issue-854-ics-allday-wrong-day.test.ts

How to Run

npm test -- tests/unit/issues/issue-854-ics-allday-wrong-day.test.ts

Note: The test currently has a mock setup issue that needs to be resolved (the ICAL mock needs the parse method added to the default export object). However, the test logic correctly reproduces the bug.

Test Coverage

The test verifies:

1. Single all-day events maintain their calendar date across timezones
2. Multi-day all-day events preserve both start and end dates
3. Recurring all-day events maintain correct dates for all occurrences
4. All-day events are properly distinguished from timed events

Relevant Code Locations

Primary Issue

• File: src/services/ICSSubscriptionService.ts:34-51
• Function: icalTimeToISOString(icalTime: ICAL.Time)
• Problem: Uses Date.UTC() for all-day events, creating timezone-dependent display issues

Related Code

• File: src/services/ICSSubscriptionService.ts:289-470

• Function: parseICS(icsData: string, subscriptionId: string)

• Line 348: const isAllDay = startDate.isDate;

• Line 349-350: Calls icalTimeToISOString() for start/end dates

• Usage: Stores the ISO string in the ICSEvent object

• File: src/bases/calendar-core.ts:455-486

• Function: createICSEvent(icsEvent: ICSEvent, plugin: TaskNotesPlugin)

• Line 471-473: Uses icsEvent.start, icsEvent.end, and icsEvent.allDay directly

• Usage: Passes these to FullCalendar for display

Event Flow

1. ICS data parsed → parseICS() → icalTimeToISOString() → ISO string stored in ICSEvent
2. ICSEvent → createICSEvent() → FullCalendar event object
3. FullCalendar displays event using the ISO string and allDay flag

Proposed Solutions

Solution 1: Store All-Day Events as Date Strings (Recommended)

Approach: Store all-day events as date-only strings (e.g., "2025-01-20") instead of full ISO timestamps. This preserves the calendar date semantics.

Implementation:

private icalTimeToISOString(icalTime: ICAL.Time): string {
    // For all-day events, return date-only string (YYYY-MM-DD)
    if (icalTime.isDate) {
        const year = icalTime.year.toString().padStart(4, '0');
        const month = icalTime.month.toString().padStart(2, '0');
        const day = icalTime.day.toString().padStart(2, '0');
        return `${year}-${month}-${day}`;
    }

    // For timed events, use toUnixTime() which correctly converts to UTC
    const unixTime = icalTime.toUnixTime();
    return new Date(unixTime * 1000).toISOString();
}

Pros:

• ✅ Directly represents the calendar date without timezone ambiguity
• ✅ Matches iCalendar specification semantics for DATE values
• ✅ Simple, minimal change to existing code
• ✅ FullCalendar's allDay flag will handle rendering correctly
• ✅ Most semantically correct solution

Cons:

• ⚠️ Need to verify all code consuming ICSEvent.start handles date-only strings
• ⚠️ May need to update date comparison logic in calendar views

Risk: Low - FullCalendar handles both ISO timestamps and date-only strings for allDay events

---

Solution 2: Use Local Midnight Instead of UTC Midnight

Approach: Create a timestamp at midnight in the user's local timezone instead of UTC midnight.

Implementation:

private icalTimeToISOString(icalTime: ICAL.Time): string {
    // For all-day events, use local midnight
    if (icalTime.isDate) {
        const localDate = new Date(
            icalTime.year,
            icalTime.month - 1,
            icalTime.day,
            0, 0, 0, 0
        );
        return localDate.toISOString();
    }

    // For timed events, use toUnixTime()
    const unixTime = icalTime.toUnixTime();
    return new Date(unixTime * 1000).toISOString();
}

Pros:

• ✅ Maintains ISO timestamp format
• ✅ Events display on correct calendar date in user's timezone
• ✅ Minimal code changes

Cons:

• ❌ Breaks if user changes timezone or syncs across devices
• ❌ The ISO timestamp would be different for users in different timezones
• ❌ Violates the timezone-independent nature of all-day events
• ❌ Could cause issues with calendar sync/sharing

Risk: Medium-High - Timezone-dependent storage is problematic

---

Solution 3: Store with Noon UTC to Minimize Timezone Issues

Approach: Store all-day events at noon UTC (12:00:00 UTC) instead of midnight. This reduces the chance of date shifts but doesn't eliminate them.

Implementation:

private icalTimeToISOString(icalTime: ICAL.Time): string {
    // For all-day events, use noon UTC to minimize timezone shift issues
    if (icalTime.isDate) {
        return new Date(Date.UTC(
            icalTime.year,
            icalTime.month - 1,
            icalTime.day,
            12, 0, 0, 0  // Noon UTC
        )).toISOString();
    }

    // For timed events, use toUnixTime()
    const unixTime = icalTime.toUnixTime();
    return new Date(unixTime * 1000).toISOString();
}

Pros:

• ✅ Maintains ISO timestamp format
• ✅ Reduces (but doesn't eliminate) date shift issues
• ✅ Minimal code changes

Cons:

• ❌ Still fails for timezones with UTC offset ≥ ±12 hours
• ❌ Hacky workaround rather than proper fix
• ❌ Could show as 11:59 PM previous day in UTC-13 (rare but possible)
• ❌ Doesn't properly represent calendar date semantics

Risk: Medium - Better than midnight UTC but still has edge cases

Recommended Approach

Solution 1 (Date-only strings) is the recommended approach because:

1. Semantic Correctness: Directly represents what all-day events are - calendar dates, not moments in time
2. Specification Compliance: Matches iCalendar RFC 5545 semantics for VALUE=DATE events
3. Timezone Independence: Works correctly regardless of user's timezone or timezone changes
4. FullCalendar Support: FullCalendar's allDay flag explicitly supports date-only strings in ISO format
5. Future-Proof: Won't break if users travel, change timezones, or sync across devices

Implementation Notes

1. Verify consumers: Check that all code reading ICSEvent.start/end handles date-only strings:

   • src/bases/calendar-core.ts:471-473 - Passes directly to FullCalendar ✓
   • src/views/AgendaView.ts - May need verification for filtering logic
   • Any date comparison or sorting logic

2. Testing: The existing test file covers the key scenarios once the mock is fixed

3. Migration: Existing events in cache will automatically update on next refresh

Related Issues

This issue is similar to #781 (ICS timezone conversion bug) which was fixed in commit 3a8524c. However, #781 focused on timed events with timezones, while #854 affects all-day events which should be timezone-independent. The fix for #781 correctly uses toUnixTime() for timed events but didn't address the all-day event case.

Verification Steps

After implementing the fix:

1. Create test ICS file with all-day event on Jan 20
2. Import to TaskNotes
3. Verify event shows on Jan 20 in all timezones (test in PST, EST, UTC, UTC+8)
4. Verify multi-day all-day events span correct dates
5. Verify recurring all-day events generate correct dates
6. Verify timed events still work correctly (no regression)

Additional Context

Recent Related Changes

• Commit 3a8524c: Fixed ICS timezone conversion for timed events (#781, #841)
• Commit ee89ebe: Fixed calendar base view support for embedded views
• Commit 0d8613b: Fixed mini calendar off-by-one in negative UTC timezones (#822)

The pattern of timezone-related date display issues suggests the codebase has been systematically addressing these problems. This fix continues that work by properly handling all-day events.