Timezone Meeting Planner - Project Plan

Goal

Develop a single-file, client-side web application that generates an interactive timezone comparison table to help distributed teams find optimal meeting times across 2-5 global locations, with exportable markdown formatting for easy sharing.

Users can generate a URL which includes the timezones they have added and the names they have assigned to each timezone. This link can be shared and viewed by anyone on the internet.

Requirements

MUST:

• Include minimum 2 timezones and maximum of 5 timezones
• Generate timezone HTML table and Markdown support
• Include UTC as an option
• Be fully async:
  • When a user adds or removes a timezone, table updates immediately
  • When a user changes a timezone or the name of the timezone, table updates immediately
• The button text in Generate Table should not use grey on blue which is very hard to read
• Support selecting multiple hours in the table, not just a single hour:
  • This should be done through holding the select key and selecting the rows
• Support a URL generate optional button which creates a URL with the timezones and the names assigned to each timezone:
  • The path of the URL should be encoded so it's not long like "/?zones=%5B%7B%22name%22%3A%22foo%22%2C%22timezone%22%3A%22Australia%2FMelbourne%22%7D%2C%7B%22name%22%3A%22abc%22%2C%22timezone%22%3A%22America%2FNew_York%22%7D%2C%7B%22name%22%3A%22mma%22%2C%22timezone%22%3A%22Asia%2FAmman%22%7D%5D&utc=false&selected=13%2C14%2C15%2C16%2C17". Instead it should be encoded with an encoding scheme such as base64.

SHOULD:

• Support custom names for timezones
• Include day-difference indicators (+1, -1) in both table and markdown
• Replace underscores with spaces in markdown headers (e.g., "Addis_Ababa" → "Addis Ababa")

Research

• Timezone Data Source: Leveraged Intl.supportedValuesOf('timeZone') for comprehensive, up-to-date timezone support without hardcoding
• Time Calculation Strategy: Used Date.toLocaleString() with timezone options to calculate offsets rather than manual offset math, handling DST transitions automatically
• UI Pattern: Searchable dropdown pattern (combobox) chosen over native select for improved UX with 400+ timezone options
• State Management: Simple in-memory state with auto-regeneration triggers on input changes rather than explicit submit actions
• Accessibility: Minimal but functional keyboard navigation (arrow keys, enter, escape) for dropdown interaction

Phases

Phase 1: Core Functionality ✅ Completed

Objective: Build the essential comparison and export features satisfying all initial MUST requirements.

• [x] Create single HTML file structure with embedded CSS/JS
• [x] Implement timezone search input with dynamic dropdown using Intl API
• [x] Build 24-hour comparison table starting from current hour of primary timezone
• [x] Add support for 2-5 timezone rows with optional custom naming
• [x] Implement day-difference indicators (+1, -1) for cross-date comparisons
• [x] Add "Include UTC" toggle functionality with auto-regeneration
• [x] Create markdown export with proper formatting (underscores to spaces, day indicators)
• [x] Implement copy-to-clipboard functionality
• [x] Add auto-regeneration on add/remove/timezone change/UTC toggle/name change
• [x] Style with minimal, usable design (responsive layout, sticky headers, hover states)
• [x] Add single row selection highlighting for specific time slots

Phase 2: Polish & Reliability ✅ Completed

Objective: Harden the application, improve UX edge cases, and implement new MUST requirements.

• [x] Fix button contrast: "Generate Table" button text uses white on blue (not grey on blue)
• [x] Implement multi-row selection with Ctrl/Cmd+click for toggling individual rows
• [x] Implement range selection with Shift+click for selecting contiguous rows
• [x] Debounce search input to prevent excessive rendering (150ms delay)
• [x] Add validation messaging instead of alert() dialogs (inline error display with timeout)
• [x] Preserve selected row highlight(s) during auto-regeneration
• [x] Add loading state for initial timezone list generation
• [x] Implement localStorage persistence for user preferences (selected timezones, names, UTC preference, selected hours)
• [x] Add keyboard shortcut (Ctrl/Cmd + Enter) to trigger manual refresh
• [x] Dark mode support (media query based with CSS variables)
• [x] Handle browser timezone detection as default first entry
• [x] Fix dropdown positioning on mobile screens (<400px width)
• [ ] Encode generated URL

Phase 3: Advanced Features (Future)

Objective: Extend functionality for power users.

• [ ] Drag-and-drop reordering of timezone columns
• [ ] Custom time range selection (not just 24h from now)
• [ ] "Working hours" overlay highlighting (9-5 local time for each zone)
• [ ] URL hash generation for sharing specific configurations
• [ ] Export to CSV/ICS (calendar invite) formats
• [ ] Mobile-native experience (touch-optimized inputs)
• [ ] Offline support (service worker caching timezone data)

Todo (Phase 2 Completion Tasks)

All Phase 2 tasks completed. Ready for Phase 3 planning or release.

Verification Checklist

All items verified and complete.