diff --git a/docs/unix-time-converter-enhanced-requirements.md b/docs/unix-time-converter-enhanced-requirements.md new file mode 100644 index 0000000..d9e4cd0 --- /dev/null +++ b/docs/unix-time-converter-enhanced-requirements.md @@ -0,0 +1,429 @@ +# Unix Time Converter - Enhanced Requirements & Mockup + +## Overview +Complete redesign of the Unix Time Converter to be a comprehensive time utility tool with 14+ advanced features. + +--- + +## 🎨 Visual Mockup + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ πŸ• Unix Time Converter [≑≑] β”‚ +β”‚ Convert, calculate, and manipulate timestamps with advanced utilities β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MODE: [Timestamp Converter β–Ό] [Time Calculator β–Ό] [Batch Mode β–Ό] β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ PRIMARY INPUT β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Unix Timestamp / Date String [πŸ• Now] β”‚ β”‚ +β”‚ β”‚ 1738412345 [πŸ“‹] β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ [β–Ά Timestamp: Seconds β–Ό] [β–Ά Source: Local Time β–Ό] β”‚ β”‚ +β”‚ β”‚ UTC-05:00 (EST) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ QUICK PRESETS (Click to Insert) β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Now β”‚ +1 Hour β”‚Tomorrow β”‚Next Weekβ”‚Start of β”‚End of β”‚ Unix β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ 9am β”‚ Mon 9am β”‚ Day β”‚ Day β”‚ Epoch β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ OUTPUT FORMATS β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ISO 8601 β”‚ β”‚ RFC 2822 β”‚ β”‚ SQL β”‚ β”‚ Custom β”‚ β”‚ +β”‚ β”‚ YYYY-MM-DD.. β”‚ β”‚ ddd, DD MMM..β”‚ β”‚ YYYY-MM-DD.. β”‚ β”‚ [Format...] β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ CONVERSION OUTPUTS β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 🌍 UTC Time (ISO 8601) β”‚ β”‚ πŸ“… Local Time (EST) β”‚ β”‚ +β”‚ β”‚ 2026-02-01T12:24:05.000Z [πŸ“‹] β”‚ β”‚ 2026-02-01 07:24:05 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ AM/PM: 07:24:05 AM β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Unix: 1738412345 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Millis: 1738412345000 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Nanos: 1738412345000000000 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ⏱️ RELATIVE TIME β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ 2 days, 5 hours, 30 minutes ago β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Breakdown: 56 hours β”‚ 3,390 minutes β”‚ 203,400 seconds β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ TIME CALCULATOR (Optional Section - Collapsible) β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Date A: 2026-02-01 12:00:00 [πŸ“‹] β”‚ β”‚ [+] 3 days β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ [-] 2 hours β”‚ β”‚ +β”‚ β”‚ Date B: 2026-02-05 09:30:00 [πŸ“‹] β”‚ β”‚ [+] 30 minutes β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ Difference: 3 days, 21 hours, 30 minutes (93.5 hours total) β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ TIMEZONE COMPARISON β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Tokyo β”‚ London β”‚ New York β”‚ India β”‚ Sydney β”‚ β”‚ +β”‚ β”‚ JST+9 β”‚ GMT+0 β”‚ EST-5 β”‚ IST+5:30 β”‚ AEST+10 β”‚ β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ Feb 2 02:24 β”‚ Feb 1 12:24 β”‚ Feb 1 07:24 β”‚ Feb 1 17:54 β”‚ Feb 1 23:24 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ VISUAL WIDGETS (Optional - Toggleable) β”‚ +β”‚ ═══════════════════════════════════════════════════════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ [πŸ“…] β”‚ β”‚ 12:24:05 β”‚ β”‚ +β”‚ β”‚ February β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ 2026 β”‚ β”‚ / 12 \ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ / β”Œβ”€β”€β”€β” β”Œβ”€β”€β”€β” \ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ 1 β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ \ β””β”€β”€β”€β”˜ β””β”€β”€β”€β”˜ / β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ \ 24 05 / β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## πŸ“‹ Feature Requirements + +### Core Features + +#### 1. **Timestamp Precision Support** +- **Seconds** (10 digits): `1738412345` +- **Milliseconds** (13 digits): `1738412345000` +- **Microseconds** (16 digits): `1738412345000000` +- **Nanoseconds** (19 digits): `1738412345000000000` +- Auto-detect precision from input length +- Toggle button to switch display precision + +#### 2. **Quick Presets Panel** +Clickable buttons for instant insertion: +- **Now** - Current timestamp +- **Start of Today** - 00:00:00 today +- **End of Today** - 23:59:59 today +- **Yesterday** - Same time yesterday +- **Tomorrow** - Same time tomorrow +- **Next Monday 9am** - Coming Monday at 9:00 AM +- **Start of Week** - Monday 00:00:00 +- **End of Week** - Sunday 23:59:59 +- **Unix Epoch** - January 1, 1970 00:00:00 UTC +- **+1 Hour** - Add 1 hour to current +- **+1 Day** - Add 1 day to current +- **+1 Week** - Add 1 week to current + +#### 3. **Date Arithmetic Mode** +Allow users to add/subtract time units: +- Input: Base date/timestamp +- Controls: + - Add/Subtract dropdown + - Value input (number) + - Unit selector (seconds, minutes, hours, days, weeks, months, years) +- Output: Calculated result timestamp and all formats + +#### 4. **Time Delta Calculator** +Compare two dates and show difference: +- Inputs: Date A and Date B (both support any format) +- Output breakdown: + - Days, Hours, Minutes, Seconds + - Total in each unit (e.g., "93.5 hours total") + - Business days (optional) +- Visual timeline/gantt representation + +#### 5. **Enhanced Relative Time Display** +Current: "2 hours ago" +Enhanced: +``` +2 days, 5 hours, 30 minutes ago + +Breakdown: +β€’ 56 hours total +β€’ 3,390 minutes total +β€’ 203,400 seconds total +β€’ 2,354 days since epoch +``` + +#### 6. **Batch Conversion Mode** +- Text area input (one timestamp per line) +- Supports mixed formats (some timestamps, some date strings) +- Output: Table with columns: + - Original Input + - Unix Timestamp + - ISO 8601 + - Local Time + - Relative Time +- Export to CSV/JSON option + +#### 7. **Timezone Comparison Grid** +- Show current time in multiple timezones simultaneously +- Default: Tokyo, London, New York, India, Sydney +- Customizable: Add/remove cities +- Shows offset from local (e.g., "+9 hours") +- Visual indicator for same-day vs different-day + +#### 8. **Multiple Output Formats (Tabbed)** +Instead of dropdown, show tabs for quick switching: +- ISO 8601 +- RFC 2822 (Email format) +- RFC 3339 +- SQL DateTime +- US Format (MM/DD/YYYY) +- EU Format (DD/MM/YYYY) +- Compact (YYYYMMDD-HHmmss) +- Custom (with format builder) + +**Custom Format Tokens:** +- `YYYY` - 4-digit year +- `MM` - 2-digit month +- `DD` - 2-digit day +- `HH` - 2-digit hour (24h) +- `hh` - 2-digit hour (12h) +- `mm` - 2-digit minute +- `ss` - 2-digit second +- `sss` - 3-digit millisecond +- `A` - AM/PM +- `ddd` - Short day name (Mon) +- `dddd` - Long day name (Monday) +- `ZZ` - Timezone offset (-0500) + +#### 9. **Copy Actions** +- Copy button on every output field +- "Copy All" button - copies all formats as JSON or CSV +- "Copy Share Link" - generates URL with timestamp parameter + +#### 10. **History & Recent** +- Store last 20 conversions +- Persist in localStorage +- Quick re-call from dropdown +- Clear history option + +#### 11. **Visual Calendar Widget** +- Mini calendar showing selected date +- Highlight selected day +- Click to pick different date +- Month/year navigation + +#### 12. **Analog Clock Widget** +- Visual clock face showing selected time +- Hour, minute, second hands +- AM/PM indicator +- Optional: Digital display below + +#### 13. **Smart Input Detection** +Auto-detect input type: +- Pure number β†’ Unix timestamp +- Contains `/` or `-` β†’ Date string +- Contains `:` β†’ Time string +- Contains `T` or `Z` β†’ ISO format +- Shows detected type as tag + +#### 14. **URL Share Support** +- Read timestamp from URL parameter: `?ts=1738412345` +- Generate shareable links +- Copy link button + +--- + +## 🎯 UI/UX Specifications + +### Layout Structure + +``` +ToolContainer (flex column) +β”œβ”€β”€ ToolHeader (title + description) +β”œβ”€β”€ ModeSelector (tabs: Converter | Calculator | Batch) +β”œβ”€β”€ PrimaryControls +β”‚ β”œβ”€β”€ InputSection +β”‚ β”‚ β”œβ”€β”€ TimestampInput + NowButton +β”‚ β”‚ β”œβ”€β”€ PrecisionToggle (s/ms/ΞΌs/ns) +β”‚ β”‚ └── SourceTimezone +β”‚ └── QuickPresets (horizontal scrollable row of chips) +β”œβ”€β”€ OutputFormatTabs (format selection) +β”œβ”€β”€ MainWorkspace (split pane) +β”‚ β”œβ”€β”€ LeftPane: PrimaryOutputs +β”‚ β”‚ β”œβ”€β”€ UTCTime (ISO format) +β”‚ β”‚ β”œβ”€β”€ LocalTime (with timezone) +β”‚ β”‚ └── AllPrecisions (s, ms, ΞΌs, ns) +β”‚ └── RightPane: SecondaryOutputs +β”‚ β”œβ”€β”€ RelativeTime (detailed) +β”‚ β”œβ”€β”€ TimezoneGrid +β”‚ └── VisualWidgets (calendar + clock) +└── OptionalSections (collapsible) + β”œβ”€β”€ TimeCalculator (Date A vs Date B) + β”œβ”€β”€ BatchResultsTable + └── HistoryList +``` + +### Responsive Behavior + +**Horizontal Layout (default):** +- Split pane: 50/50 input/output +- Quick presets: Horizontal row +- Timezone grid: 5 columns + +**Vertical Layout (toggled):** +- Stacked: Input β†’ Presets β†’ Output +- Quick presets: Wrap to 2 rows +- Timezone grid: 2-3 columns +- Visual widgets: Side by side or stacked + +### Color Coding + +- **Past dates**: Blue/gray tone +- **Future dates**: Green tone +- **Current/Now**: Orange highlight +- **Error/Invalid**: Red +- **Different day (timezone)**: Subtle background tint + +### Typography + +- All timestamps: `'IBM Plex Mono', monospace` +- Labels: Carbon label style (0.75rem) +- Relative time: Larger, prominent (1rem) +- Timezone offsets: Small, muted + +--- + +## πŸ§ͺ Use Cases + +### Developer Debugging +> "The log shows timestamp `1738412345000`. What time was that?" +β†’ Paste β†’ See all formats instantly + +### Meeting Scheduling +> "I'm in NY, they're in Tokyo. What time is 3pm their time?" +β†’ Use Timezone Grid to compare + +### Duration Calculation +> "How long between these two server events?" +β†’ Use Time Calculator mode + +### Data Processing +> "Convert this list of 100 timestamps to readable dates" +β†’ Use Batch Mode + +### Quick Reference +> "What was the Unix epoch again?" +β†’ Click Unix Epoch preset + +--- + +## πŸ“± State Management + +```typescript +interface UnixTimeState { + // Primary input + input: string; + detectedPrecision: 'seconds' | 'milliseconds' | 'microseconds' | 'nanoseconds'; + + // Timezones + sourceTimezone: string; + targetTimezone: string; + + // Display settings + outputFormat: string; + customFormat: string; + showVisualWidgets: boolean; + showTimezoneGrid: boolean; + + // Mode + activeMode: 'converter' | 'calculator' | 'batch'; + + // Calculator mode + calculator: { + dateA: string; + dateB: string; + operation: 'difference' | 'add' | 'subtract'; + value: number; + unit: TimeUnit; + }; + + // Batch mode + batchInput: string; + batchResults: BatchResult[]; + + // History + history: HistoryEntry[]; + + // Layout + direction: 'horizontal' | 'vertical'; +} +``` + +--- + +## πŸ”§ Implementation Phases + +### Phase 1: Core Enhancements +- [ ] Timestamp precision support (s/ms/ΞΌs/ns) +- [ ] Quick presets panel +- [ ] Enhanced relative time with breakdown +- [ ] Multiple output formats with tabs +- [ ] Copy buttons on all outputs + +### Phase 2: Advanced Features +- [ ] Time Delta Calculator mode +- [ ] Date Arithmetic controls +- [ ] Timezone comparison grid +- [ ] Batch conversion mode +- [ ] Visual calendar widget + +### Phase 3: Polish & UX +- [ ] Analog clock widget +- [ ] History persistence +- [ ] URL share support +- [ ] Smart input detection +- [ ] Comprehensive error handling + +--- + +## 🎨 Carbon Design System Compliance + +- βœ… Use `@carbon/react` components +- βœ… Theme tokens: `var(--cds-layer)`, `var(--cds-text-primary)` +- βœ… No hardcoded hex colors +- βœ… `useReducer` for state management +- βœ… `useCallback` for handlers +- βœ… Consistent spacing (0.5rem, 0.75rem, 1rem) +- βœ… Layout toggle (horizontal/vertical) +- βœ… Monospace fonts for all timestamps +- βœ… Copy buttons always visible +- βœ… ToolHeader + ToolControls + ToolPane pattern + +--- + +*Document Version: 1.0* +*Created: 2026-02-01* +*Tool Status: Planning Phase*