ICS Export Architecture¶

This document details the architectural design and implementation of the ICS Export feature in Full Calendar Remastered. The feature provides functionality to serialize the in-memory event cache into a standard .ics (iCalendar RFC 5545) document.

Architectural Workflow¶

The pipeline for selecting, serializing, and writing calendar cache entries as .ics is outlined below:

[IcsExportModal] ──► Query Event Cache (retrieves active events)
       │
       ▼
[Filter & Compile] ──► Filter by user-selected Calendars
       │
       ▼
[formatter.ts: eventsToIcs] ──► Map each event to VEVENT/VTODO
       │
       ├──► [Save to Vault] ──► Write to selected folder in vault (app.vault)
       │
       └──► [Direct Download] ──► Generate Blob & trigger browser download

Key Components¶

1. Multi-Event Formatter (`src/providers/ics/formatter.ts`)¶

We extend the existing iCal formatter (formatter.ts) by introducing and exporting eventsToIcs(events: OFCEvent[]): string: - Instantiates a single top-level ical.Component('vcalendar') envelope. - Loops through the compiled OFCEvent list. - Calls the internal createVEventComponent (for standard events) or createVTodoComponent (for tasks) to format each event. - Serializes the entire component tree into a single standard .ics string.

2. User Interface Modal (`src/features/export/IcsExportModal.ts`)¶

The IcsExportModal orchestrates the user interaction: - Calendar Registry Integration: Retrieves all active calendars using PluginState.getProviderRegistry().getAllSources(). - Toggle Settings: Renders toggle items for each calendar so users can selectively export subsets of calendars. - Export Paths: Persists default export folder path configurations to the icsExportPath plugin settings. - Advanced Filtration Controls: - Export Period: Options for "Export All Events" (entire history) or "Specific Date Range" (with side-by-side date pickers). - Daily Time Range Filter: Restricts exported timed events to a daily time window (with side-by-side time pickers). - Include All-Day Events: Toggle to include or exclude all-day events/tasks. - Exclude Weekends: Toggle to filter out weekend occurrences. - Categories to Include: Checklist dynamically populated from unique categories present in the event store. - Include Types & Task Completion: Dropdowns to filter by events, tasks, and task completion status. - Save to Vault Pipeline: Resolves file paths, automatically creates target subfolders if they do not exist, checks for file existence, and writes to disk utilizing app.vault. - Direct Download Pipeline: Uses standard HTML5 Blob ObjectURLs (URL.createObjectURL) to trigger local browser download prompts, working seamlessly across desktop and mobile.

3. Settings Rendering (`src/features/export/ui/renderExportSettings.ts`)¶

Exposes settings for default export configuration: - Placed in the "Integrations" section of the main settings panel (SettingsTab.tsx). - Allows editing the default icsExportPath vault directory folder.

Data Model and iCalendar Mapping¶

The mapping from the plugin's canonical OFCEvent model to standard iCalendar structures is handled as follows:

`OFCEvent` Property	iCalendar Component	Property Type	Details
`title`	`VEVENT`/`VTODO`	`SUMMARY`	Cleaned title string
`description`	`VEVENT`/`VTODO`	`DESCRIPTION`	Markdown/text
`date`/`startTime`/`timezone`	`VEVENT`/`VTODO`	`DTSTART`	Formatted based on all-day and timezone settings
`endDate`/`endTime`/`timezone`	`VEVENT`/`VTODO`	`DTEND` / `DUE`	Formatted based on all-day and timezone settings
`completed` (task)	`VTODO`	`STATUS` / `COMPLETED`	Marks `COMPLETED` or `NEEDS-ACTION`
`alarms`	`VEVENT`/`VTODO`	`VALARM`	Nested alarm triggers
`rrule`/`recurring`	`VEVENT`/`VTODO`	`RRULE`	Recurrence rules
`skipDates`	`VEVENT`/`VTODO`	`EXDATE`	Exception dates