Merge feature/v2.3.0-per-action-settings: Named Calendars, configurable thresholds

Features:
- Named Calendars with friendly names in Settings (#5)
- Per-button calendar selection via dropdown
- Configurable warning thresholds (orange/red)
- Graceful calendar deletion migration

Closes #5

Author: pedrofuentes

.github/copilot-instructions.md

@@ -36,12 +36,92 @@ streamDeck.actions.registerAction(new TimeLeftAction());
 streamDeck.connect(); // Must come AFTER registration
 ```
 
+### SingletonAction Pattern (CRITICAL)
+
+**SingletonAction means ONE instance handles ALL buttons of that action type.**
+
+This is critical for state management:
+- Instance variables (`this.interval`, `this.actionRef`) would be shared/overwritten
+- Solution: Use `buttonStates: Map<string, ButtonState>` to track per-button state
+- Each method receives `actionId` to operate on the correct button's state
+- Subclasses maintain their own per-button state Maps for action-specific data
+
+```typescript
+// WRONG - shared state breaks with multiple buttons
+class MyAction extends SingletonAction {
+  private interval?: NodeJS.Timeout; // Overwrites when 2nd button appears!
+}
+
+// CORRECT - per-button state
+class MyAction extends SingletonAction {
+  private buttonStates: Map<string, ButtonState> = new Map();
+  
+  startTimerForButton(actionId: string, action: any) {
+    const state = this.buttonStates.get(actionId);
+    state.interval = setInterval(...);
+  }
+}
+```
+
 ### Property Inspector Communication
 
 PI uses WebSocket, not direct imports. Settings flow:
-1. PI calls `setGlobalSettings` via WebSocket
-2. Plugin receives via `onDidReceiveGlobalSettings`
-3. Plugin processes and updates cache
+1. PI calls `setGlobalSettings` via WebSocket for global settings
+2. PI calls `setSettings` via WebSocket for per-action settings
+3. Plugin receives via `onDidReceiveGlobalSettings` and `onDidReceiveSettings`
+4. Plugin processes and updates cache
+
+### Per-Action Settings (v2.3.0)
+
+Each button can select a calendar via `ActionSettings`:
+
+```typescript
+interface ActionSettings {
+  calendarId?: string;          // ID of named calendar to use (new in v2.3)
+  // Legacy fields (kept for backwards compatibility)
+  useCustomCalendar?: boolean;
+  customUrl?: string;
+  customLabel?: string;
+  customTimeWindow?: 1 | 3 | 5 | 7;
+  customExcludeAllDay?: boolean;
+}
+```
+
+**Named Calendars** in GlobalSettings:
+```typescript
+interface NamedCalendar {
+  id: string;           // Unique ID (e.g., "cal_abc123")
+  name: string;         // User-friendly name (e.g., "Work")
+  url: string;          // iCal URL
+  timeWindow?: number;  // Optional override (1, 3, 5, or 7 days)
+  excludeAllDay?: boolean;
+}
+
+interface GlobalSettings {
+  calendars?: NamedCalendar[];
+  defaultCalendarId?: string;
+  orangeThreshold?: number;   // Seconds for orange warning (default: 300 = 5 min)
+  redThreshold?: number;      // Seconds for red warning (default: 30)
+  // ... other settings
+}
+```
+
+**CalendarManager** handles multi-calendar support:
+- Calendars are deduplicated by URL (same URL = shared cache)
+- Reference counting for automatic cleanup
+- Each action registers via `calendarManager.registerAction(actionId, url, ...)`
+
+**BaseAction** provides:
+- `buttonStates: Map<string, ButtonState>` - Per-button state storage
+- `buttonSettings: Map<string, ActionSettings>` - Per-button settings for migration
+- `getEventsForButton(actionId)` - Returns events from the button's registered calendar
+- `getCacheStatusForButton(actionId)` - Returns status of the button's calendar
+- `startTimerForButton(actionId, action)` - Starts update timer for a specific button
+- `stopTimerForButton(actionId)` - Stops timer for a specific button
+- `setImage(actionId, action, imageName)` - Sets image for a specific button
+- `onDidReceiveSettings()` - Handles settings changes, re-registers calendar
+- `migrateButtonsWithDeletedCalendar(validIds)` - Migrates buttons when calendar deleted
+- `getRedZone()` / `getOrangeZone()` - Get configurable warning thresholds
 
 ## Build System
 
@@ -104,6 +184,21 @@ Excluded dates are parsed and passed to RRuleSet to skip specific occurrences.
 
 ## Testing Patterns
 
+### Testing Requirements (MANDATORY)
+
+**Every code change MUST include corresponding tests:**
+
+1. **New features** - Add unit tests covering happy path and edge cases
+2. **Bug fixes** - Add regression tests that would have caught the bug
+3. **Refactoring** - Ensure existing tests still pass, add tests for any new behavior
+
+**Before completing any task:**
+- Run `npm test` to verify all tests pass
+- Check test coverage for changed files
+- Add tests if coverage is insufficient
+
+**For agents:** Always verify tests are added/updated before marking a task complete.
+
 ### Test Fixtures
 
 Located in `__fixtures__/` organized by provider:
@@ -163,13 +258,16 @@ const flashEnabled = settings.flashOnMeetingStart === true;
 | Outlook times wrong | Windows timezone not mapped | Check `timezone-service.ts` mapping |
 | Buttons stuck on "Loading" | Startup race condition | `waitForCacheAndStart` uses 500ms polling with `actionRef` fallback |
 | Title shows for too long | Duration multiplied twice | `getTitleDisplayDuration()` returns seconds, caller multiplies by 1000 |
+| Calendar not loading | Named calendars not set up | Ensure at least one calendar is configured in Settings |
+| Button using deleted calendar | Calendar was removed | Buttons auto-migrate to default via `migrateDeletedCalendars()` |
+| Settings not persisting | Using wrong settings event | Global = `setGlobalSettings`, Per-action = `setSettings` |
 
 ## File Locations
 
 - **Actions**: `src/actions/` - Extend `BaseAction`
-- **Services**: `src/services/` - Business logic
-- **Types**: `src/types/index.ts` - All interfaces
-- **PI HTML**: `pi/setup.html` - Settings popup
+- **Services**: `src/services/` - Business logic (`calendar-manager.ts` for multi-calendar)
+- **Types**: `src/types/index.ts` - All interfaces (`ActionSettings`, `NamedCalendar`, `CalendarInstance`)
+- **PI HTML**: `pi/setup.html` - Settings popup (Named Calendars management)
 - **PI JS**: `pi/setup.js` - Settings logic (not TypeScript)
 - **Tests**: `tests/` - Vitest test files
 

README.md

@@ -6,6 +6,19 @@ iCal Plugin for [elgato Stream Deck](https://www.elgato.com/en/gaming/stream-dec
 
 This plugin is available on the Stream Deck store, you can also download [the last release](https://github.com/pedrofuentes/stream-deck-ical/releases) or build it yourself using the code on this repo.
 
+## ✨ New in v2.3
+
+- ✅ **Named Calendars**: Set up multiple calendars with friendly names in Settings (#5)
+  - Create a library of calendars (Work, Personal, Family, etc.)
+  - Each button can select which calendar to use from a dropdown
+  - Calendars sharing the same URL share a single cache (efficient!)
+- ✅ **Per-Button Settings**: Each button can have its own time window and all-day event preferences
+- ✅ **Configurable Warning Thresholds**: Customize when orange/red warnings appear
+  - Orange warning: Choose from 1, 2, 3, 5, 10, 15, or 30 minutes (default: 5 min)
+  - Red warning: Choose from 10, 15, 30, 45, or 60 seconds (default: 30 sec)
+- ✅ **Graceful Calendar Deletion**: Buttons using a deleted calendar automatically fall back to default
+- ✅ **Improved Settings UI**: Redesigned Property Inspector with collapsible help sections
+
 ## ✨ New in v2.2
 
 - ✅ **Smart Calendar Action**: New all-in-one action that automatically switches between modes (#10)
@@ -29,6 +42,9 @@ This plugin is available on the Stream Deck store, you can also download [the la
 - ✅ **Provider Compatibility**: Optimized for Google Calendar, Microsoft Outlook/Office 365, and Apple Calendar
 
 ## Features ##
+* ✅ **Named calendars** - Set up multiple calendars with friendly names, assign to buttons via dropdown
+* ✅ **Per-button settings** - Each button can use different calendar, time window, and all-day preferences
+* ✅ **Configurable warning thresholds** - Customize orange/red warning times
 * ✅ **Recurring events** with RRULE expansion and EXDATE handling
 * ✅ **Configurable time window** (1, 3, 5, or 7 days)
 * ✅ **Exclude all-day events** option (enabled by default)
@@ -41,8 +57,8 @@ This plugin is available on the Stream Deck store, you can also download [the la
 
 ### Time Left ###
 * Shows time left until the meeting ends
-* Changes icon color to orange when 5 minutes are left on the meeting
-* Changes icon color to red when 30 seconds are left on the meeting and goes up to 5 minutes after the meeting
+* Changes icon color to orange when time remaining reaches the orange threshold (default: 5 minutes)
+* Changes icon color to red when time remaining reaches the red threshold (default: 30 seconds)
 * When the meeting ends the counter will keep going and stay red for 5 minutes, if the user pushes the button it will show the next meeting if one is available
 * Supports multiple concurrent meetings, to switch between meeting just push the button
 * Shows meeting indicator (e.g., "1/3") when multiple meetings are active
@@ -56,7 +72,7 @@ This plugin is available on the Stream Deck store, you can also download [the la
   * Scrolling marquee for meeting titles (tap to show/hide)
   * Concurrent meeting support (tap to cycle through active meetings)
   * Flash alert when meetings start
-  * Color-coded countdown (orange at 5 min, red at 30 sec)
+  * Configurable warning thresholds (orange/red)
 * **Perfect for limited Stream Deck space** - one button does it all!
 
 ### Next Meeting ###
@@ -66,8 +82,8 @@ This plugin is available on the Stream Deck store, you can also download [the la
   * If the button is pushed while the text is showing it will go back to show the time left until the next meeting
   * At the end of the title animation, the button will go back to show the time left until the next meeting
 * **Optional flash alert** when meetings are about to start (disabled by default)
-* Changes icon color to orange when there are 5 minutes left for the next meeting to start
-* Changes icon color to red when there are 30 seconds left for the next meeting to start
+* Changes icon color to orange when time remaining reaches the orange threshold (default: 5 minutes)
+* Changes icon color to red when time remaining reaches the red threshold (default: 30 seconds)
 
 ## Calendar Provider Support
 
@@ -129,15 +145,29 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup instructions.
 
 ## Configuration
 
+### Global Settings (Settings Popup)
 1. Drag an action to your Stream Deck
 2. Click the action to open Property Inspector
 3. Click "Settings" button
-4. Enter your iCal URL
-5. Choose time window (1, 3, 5, or 7 days)
-6. Set title display duration (5, 10, 15, or 30 seconds)
-7. Optionally enable "Flash when meeting starts" for visual alerts
-8. Optionally uncheck "Exclude All-Day Events" to show all-day events
-9. Click "Save Settings"
+4. **Manage Calendars**: Add named calendars with friendly labels
+   - Click "Add Calendar" to create a new entry
+   - Give it a name (e.g., "Work", "Personal")
+   - Paste your iCal URL
+   - Set time window and all-day event preferences per calendar
+   - Click ★ to set as default calendar
+5. **Warning Thresholds**: Customize when color warnings appear
+   - Orange warning: 1-30 minutes (default: 5 min)
+   - Red warning: 10-60 seconds (default: 30 sec)
+6. **Other Options**:
+   - Title display duration (5, 10, 15, or 30 seconds)
+   - Flash on meeting start (optional visual alert)
+7. Click "Save Settings"
+
+### Per-Button Settings (Property Inspector)
+Each button can override the default calendar:
+1. Select the button on your Stream Deck
+2. In Property Inspector, use the "Calendar" dropdown to select which calendar this button should use
+3. The default calendar is indicated with "(Default)" in the dropdown
 
 ## Troubleshooting
 
@@ -185,6 +215,19 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
 
 ## Changelog
 
+### v2.3.0 (2026)
+- ✨ **Named Calendars**: Set up multiple calendars with friendly names in Settings (#5)
+- ✨ **Per-Button Calendar Selection**: Each button selects calendar from dropdown
+- ✨ **Configurable Warning Thresholds**: Customize orange (1-30 min) and red (10-60 sec) warnings
+- ✨ **Graceful Calendar Deletion**: Buttons auto-migrate to default when calendar is deleted
+- ✨ **Improved Settings UI**: Redesigned Property Inspector with collapsible help
+- ✨ Per-button time window and all-day event settings
+- ✨ URL-level caching: buttons sharing same URL share a single cache
+- 🐛 Fixed button state preservation with SingletonAction pattern
+- 🐛 Fixed calendar selection not persisting after Stream Deck restart
+- ✅ Added CalendarManager service with 31 tests
+- ✅ Added 104 new regression tests (529 total)
+
 ### v2.2.0 (2026)
 - ✨ **Smart Calendar Action**: New combined action that auto-switches between Time Left and Next Meeting (#10)
 - ✅ Added 22 tests for combined action behavior

manifest.json

@@ -13,6 +13,7 @@
       ], 
       "SupportedInMultiActions": false,
       "Tooltip": "Time left on the current meeting", 
+      "UserTitleEnabled": false,
       "UUID": "com.pedrofuentes.ical.timeleft"
     },
     {
@@ -27,6 +28,7 @@
       ], 
       "SupportedInMultiActions": false,
       "Tooltip": "Countdown until next meeting starts", 
+      "UserTitleEnabled": false,
       "UUID": "com.pedrofuentes.ical.nextmeeting"
     },
     {
@@ -41,6 +43,7 @@
       ], 
       "SupportedInMultiActions": false,
       "Tooltip": "Shows Time Left when in meeting, Next Meeting otherwise", 
+      "UserTitleEnabled": false,
       "UUID": "com.pedrofuentes.ical.combined"
     }
   ], 
@@ -54,7 +57,7 @@
   "CategoryIcon": "assets/icalIcon",
   "URL": "https://github.com/pedrofuentes/stream-deck-ical#readme",
   "PropertyInspectorPath": "pi.html",
-  "Version": "2.2.0.0",
+  "Version": "2.3.0.0",
   "Nodejs": {
     "Version": "20",
     "Debug": "enabled"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stream-deck-ical",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "An elgato Stream Deck plugin that displays information from your calendar using an iCal URL. Visual cues and a countdown will help you end meetings on time and be ready for the next one.",
   "private": true,
   "type": "module",

pi/pi.html

@@ -7,23 +7,37 @@
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
     <title>iCal Property Inspector</title>
     <link rel="stylesheet" href="css/sdpi.css">
+    <style>
+        .no-calendars-warning {
+            color: #f44336;
+            font-size: 11px;
+            margin-top: 4px;
+        }
+    </style>
 </head>
 <body>
     <div class="sdpi-wrapper">
+        <!-- Calendar Selection -->
         <div class="sdpi-item">
-            <div class="sdpi-item-label">iCal URL</div>
-            <input id="url" class="next-to-settings sdpi-item-value" type="text" value="" readonly />
-            <button class="settings" id="settings" value="Settings"><span>Settings</span></button>
+            <div class="sdpi-item-label">Calendar</div>
+            <select id="calendarSelect" class="sdpi-item-value select">
+                <option value="">Default Calendar</option>
+                <!-- Populated dynamically from global settings -->
+            </select>
+        </div>
+        
+        <div class="sdpi-item" id="noCalendarsContainer" style="display: none;">
+            <div class="sdpi-item-label"></div>
+            <div class="sdpi-item-value no-calendars-warning">
+                No calendars configured. Click Settings to add calendars.
+            </div>
         </div>
 
+        <hr class="sdpi-separator" style="margin: 10px 0; border-color: #3a3a3a;" />
+
         <div class="sdpi-item">
-            <div class="sdpi-item-label">Time Window</div>
-            <select id="timeWindow" class="sdpi-item-value select">
-                <option value="1">1 Day</option>
-                <option value="3" selected>3 Days</option>
-                <option value="5">5 Days</option>
-                <option value="7">7 Days</option>
-            </select>
+            <div class="sdpi-item-label">Settings</div>
+            <button class="sdpi-item-value" id="settings">⚙️ Manage Calendars & Settings</button>
         </div>
 
         <div class="sdpi-item" id="statusContainer" style="display: none;">