From d4f1a3f3cd24ae0dae38bee6b6439d3c67a2e4bd Mon Sep 17 00:00:00 2001
From: Chuck Smith <eclectic-coding@users.noreply.github.com>
Date: Tue, 26 May 2026 17:07:47 -0400
Subject: [PATCH] feat: timezone-corrected timestamps via Stimulus controller

All timestamps across the dashboard are now rendered as <time datetime="ISO8601">
elements. A new timestamp_controller.js reformats each one to the browser's local
timezone using Intl.DateTimeFormat; relative timestamps use Intl.RelativeTimeFormat
with the full local time shown on hover. Degrades to UTC text without JS.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 .../solid_stack_web/application_helper.rb     | 13 ++++
 app/javascript/solid_stack_web/application.js |  4 +-
 .../solid_stack_web/timestamp_controller.js   | 59 +++++++++++++++++++
 .../solid_stack_web/cable/index.html.erb      |  2 +-
 .../cable_messages/index.html.erb             |  4 +-
 .../cache_entries/index.html.erb              |  2 +-
 .../cache_entries/show.html.erb               |  2 +-
 .../solid_stack_web/dashboard/index.html.erb  |  4 +-
 .../failed_jobs/index.html.erb                |  2 +-
 .../solid_stack_web/failed_jobs/show.html.erb |  2 +-
 .../solid_stack_web/history/index.html.erb    |  2 +-
 app/views/solid_stack_web/jobs/index.html.erb |  4 +-
 app/views/solid_stack_web/jobs/show.html.erb  |  8 +--
 .../solid_stack_web/processes/index.html.erb  |  2 +-
 .../solid_stack_web/queues/show.html.erb      |  2 +-
 .../recurring_tasks/index.html.erb            |  7 +--
 .../scheduled_jobs/update.turbo_stream.erb    |  2 +-
 config/importmap.rb                           |  1 +
 19 files changed, 99 insertions(+), 24 deletions(-)
 create mode 100644 app/javascript/solid_stack_web/timestamp_controller.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0a48eca..fb61ec9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Responsive layout
+- Timezone-corrected timestamps — all timestamps across jobs, failed jobs, history, processes, queues, recurring tasks, cache entries, cable channels, and the dashboard are now rendered as `<time datetime="ISO8601">` elements; a `timestamp` Stimulus controller reformats each one in the browser's local timezone using `Intl.DateTimeFormat`; relative timestamps (oldest cache entry, oldest cable message, cable message list) use `Intl.RelativeTimeFormat` and expose the full local timestamp as a hover title; degrades gracefully to UTC text when JS is unavailable
 
 ### Fixed
 
diff --git a/app/helpers/solid_stack_web/application_helper.rb b/app/helpers/solid_stack_web/application_helper.rb
index 5d5d401..20b7c36 100644
--- a/app/helpers/solid_stack_web/application_helper.rb
+++ b/app/helpers/solid_stack_web/application_helper.rb
@@ -1,5 +1,18 @@
 module SolidStackWeb
   module ApplicationHelper
+    def local_time(time, format: :short, placeholder: "—")
+      return placeholder if time.nil?
+
+      iso = time.utc.iso8601
+      fallback = case format
+      when :long     then time.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
+      when :relative then "#{time_ago_in_words(time)} ago"
+      else                time.utc.strftime("%b %-d %H:%M UTC")
+      end
+      tag.time(fallback, datetime: iso,
+               data: { controller: "timestamp", timestamp_format_value: format })
+    end
+
     def format_cache_value(raw)
       str = raw.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?")
       parsed = JSON.parse(str)
diff --git a/app/javascript/solid_stack_web/application.js b/app/javascript/solid_stack_web/application.js
index 4b84d2c..728ef60 100644
--- a/app/javascript/solid_stack_web/application.js
+++ b/app/javascript/solid_stack_web/application.js
@@ -5,10 +5,12 @@ import SearchController from "solid_stack_web/search_controller"
 import SelectionController from "solid_stack_web/selection_controller"
 import SparklineTooltipController from "solid_stack_web/sparkline_tooltip_controller"
 import ThemeController from "solid_stack_web/theme_controller"
+import TimestampController from "solid_stack_web/timestamp_controller"
 
 const application = Application.start()
 application.register("refresh", RefreshController)
 application.register("search", SearchController)
 application.register("selection", SelectionController)
 application.register("sparkline-tooltip", SparklineTooltipController)
-application.register("theme", ThemeController)
\ No newline at end of file
+application.register("theme", ThemeController)
+application.register("timestamp", TimestampController)
\ No newline at end of file
diff --git a/app/javascript/solid_stack_web/timestamp_controller.js b/app/javascript/solid_stack_web/timestamp_controller.js
new file mode 100644
index 0000000..7e3ae10
--- /dev/null
+++ b/app/javascript/solid_stack_web/timestamp_controller.js
@@ -0,0 +1,59 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = { format: { type: String, default: "short" } }
+
+  connect() {
+    const dt = this.element.getAttribute("datetime")
+    if (!dt) return
+    const date = new Date(dt)
+    if (isNaN(date.getTime())) return
+    this.element.textContent = this.formatDate(date)
+    if (this.formatValue === "relative") {
+      this.element.title = this.fullFormat(date)
+    }
+  }
+
+  formatDate(date) {
+    switch (this.formatValue) {
+      case "long":
+        return new Intl.DateTimeFormat(undefined, {
+          year: "numeric", month: "2-digit", day: "2-digit",
+          hour: "2-digit", minute: "2-digit", second: "2-digit"
+        }).format(date)
+      case "relative":
+        return this.relativeFormat(date)
+      default:
+        return new Intl.DateTimeFormat(undefined, {
+          month: "short", day: "numeric",
+          hour: "2-digit", minute: "2-digit"
+        }).format(date)
+    }
+  }
+
+  fullFormat(date) {
+    return new Intl.DateTimeFormat(undefined, {
+      year: "numeric", month: "short", day: "numeric",
+      hour: "2-digit", minute: "2-digit", second: "2-digit",
+      timeZoneName: "short"
+    }).format(date)
+  }
+
+  relativeFormat(date) {
+    const diff = date.getTime() - Date.now()
+    const absDiff = Math.abs(diff)
+    const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" })
+
+    const seconds = Math.floor(absDiff / 1000)
+    if (seconds < 60) return rtf.format(diff < 0 ? -seconds : seconds, "second")
+
+    const minutes = Math.floor(absDiff / 60000)
+    if (minutes < 60) return rtf.format(diff < 0 ? -minutes : minutes, "minute")
+
+    const hours = Math.floor(absDiff / 3600000)
+    if (hours < 24) return rtf.format(diff < 0 ? -hours : hours, "hour")
+
+    const days = Math.floor(absDiff / 86400000)
+    return rtf.format(diff < 0 ? -days : days, "day")
+  }
+}
\ No newline at end of file
diff --git a/app/views/solid_stack_web/cable/index.html.erb b/app/views/solid_stack_web/cable/index.html.erb
index 35c9d2b..cbf93c2 100644
--- a/app/views/solid_stack_web/cable/index.html.erb
+++ b/app/views/solid_stack_web/cable/index.html.erb
@@ -62,7 +62,7 @@
             <%= link_to channel[:channel], cable_channel_messages_path(channel[:channel_hash]), class: "sqw-link" %>
           </td>
           <td><%= channel[:message_count] %></td>
-          <td class="sqw-muted"><%= channel[:last_message_at]&.strftime("%b %d %H:%M") %></td>
+          <td class="sqw-muted"><%= local_time(channel[:last_message_at]) %></td>
         </tr>
       <% end %>
     </tbody>
diff --git a/app/views/solid_stack_web/cable_messages/index.html.erb b/app/views/solid_stack_web/cable_messages/index.html.erb
index 36036fe..1f3836b 100644
--- a/app/views/solid_stack_web/cable_messages/index.html.erb
+++ b/app/views/solid_stack_web/cable_messages/index.html.erb
@@ -35,8 +35,8 @@
           <td class="sqw-monospace sqw-truncate" title="<%= message.payload %>">
             <%= truncate(message.payload.to_s, length: 120) %>
           </td>
-          <td class="sqw-muted" title="<%= message.created_at.strftime("%b %d, %Y %H:%M:%S %Z") %>">
-            <%= time_ago_in_words(message.created_at) %> ago
+          <td class="sqw-muted">
+            <%= local_time(message.created_at, format: :relative) %>
           </td>
         </tr>
       <% end %>
diff --git a/app/views/solid_stack_web/cache_entries/index.html.erb b/app/views/solid_stack_web/cache_entries/index.html.erb
index f0c6ae7..a09a1c7 100644
--- a/app/views/solid_stack_web/cache_entries/index.html.erb
+++ b/app/views/solid_stack_web/cache_entries/index.html.erb
@@ -46,7 +46,7 @@
             <%= link_to entry.key, cache_entry_path(entry), class: "sqw-link" %>
           </td>
           <td><%= number_to_human_size(entry.byte_size) %></td>
-          <td class="sqw-muted"><%= entry.created_at.strftime("%b %d %H:%M") %></td>
+          <td class="sqw-muted"><%= local_time(entry.created_at) %></td>
           <td class="sqw-actions">
             <%= button_to "Delete",
                   cache_entry_path(entry, q: @search, column: @sort["column"], direction: @sort["direction"]),
diff --git a/app/views/solid_stack_web/cache_entries/show.html.erb b/app/views/solid_stack_web/cache_entries/show.html.erb
index c87e9f7..b639453 100644
--- a/app/views/solid_stack_web/cache_entries/show.html.erb
+++ b/app/views/solid_stack_web/cache_entries/show.html.erb
@@ -21,7 +21,7 @@
   </div>
   <div class="sqw-detail__row">
     <dt>Created</dt>
-    <dd class="sqw-muted"><%= @entry.created_at.strftime("%b %d, %Y %H:%M:%S %Z") %></dd>
+    <dd class="sqw-muted"><%= local_time(@entry.created_at, format: :long) %></dd>
   </div>
 </dl>
 
diff --git a/app/views/solid_stack_web/dashboard/index.html.erb b/app/views/solid_stack_web/dashboard/index.html.erb
index b21a546..79438fa 100644
--- a/app/views/solid_stack_web/dashboard/index.html.erb
+++ b/app/views/solid_stack_web/dashboard/index.html.erb
@@ -87,7 +87,7 @@
       <% if @cache_stats[:oldest_entry] %>
         <div class="sqw-inline-stat sqw-inline-stat--cache">
           <span class="sqw-inline-stat__label">Oldest</span>
-          <span class="sqw-inline-stat__value sqw-inline-stat__value--sm" title="<%= @cache_stats[:oldest_entry].strftime("%b %d, %Y %H:%M") %>"><%= time_ago_in_words(@cache_stats[:oldest_entry]) %></span>
+          <span class="sqw-inline-stat__value sqw-inline-stat__value--sm"><%= local_time(@cache_stats[:oldest_entry], format: :relative) %></span>
         </div>
       <% end %>
     </div>
@@ -114,7 +114,7 @@
       <% if @cable_stats[:oldest_message] %>
         <div class="sqw-inline-stat sqw-inline-stat--cable">
           <span class="sqw-inline-stat__label">Oldest</span>
-          <span class="sqw-inline-stat__value sqw-inline-stat__value--sm" title="<%= @cable_stats[:oldest_message].strftime("%b %d, %Y %H:%M") %>"><%= time_ago_in_words(@cable_stats[:oldest_message]) %></span>
+          <span class="sqw-inline-stat__value sqw-inline-stat__value--sm"><%= local_time(@cable_stats[:oldest_message], format: :relative) %></span>
         </div>
       <% end %>
     </div>
diff --git a/app/views/solid_stack_web/failed_jobs/index.html.erb b/app/views/solid_stack_web/failed_jobs/index.html.erb
index bebd9a0..f317c6e 100644
--- a/app/views/solid_stack_web/failed_jobs/index.html.erb
+++ b/app/views/solid_stack_web/failed_jobs/index.html.erb
@@ -50,7 +50,7 @@
               <td class="sqw-monospace"><%= link_to execution.job.class_name, failed_job_path(execution) %></td>
               <td><span class="sqw-badge sqw-badge--queue"><%= execution.job.queue_name %></span></td>
               <td class="sqw-muted sqw-truncate" title="<%= execution.exception_class %>: <%= execution.message %>"><%= execution.exception_class %></td>
-              <td class="sqw-muted"><%= execution.created_at.strftime("%b %d %H:%M") %></td>
+              <td class="sqw-muted"><%= local_time(execution.created_at) %></td>
               <td class="sqw-actions">
                 <%= button_to "Retry", retry_failed_job_path(execution),
                       method: :post, class: "sqw-btn sqw-btn--sm" %>
diff --git a/app/views/solid_stack_web/failed_jobs/show.html.erb b/app/views/solid_stack_web/failed_jobs/show.html.erb
index 744925b..349e0b2 100644
--- a/app/views/solid_stack_web/failed_jobs/show.html.erb
+++ b/app/views/solid_stack_web/failed_jobs/show.html.erb
@@ -29,7 +29,7 @@
       <dd class="sqw-monospace sqw-truncate" title="<%= @execution.job.active_job_id %>"><%= @execution.job.active_job_id.presence || "—" %></dd>
 
       <dt>Failed At</dt>
-      <dd class="sqw-monospace"><%= @execution.created_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></dd>
+      <dd class="sqw-monospace"><%= local_time(@execution.created_at, format: :long) %></dd>
 
       <dt>Error</dt>
       <dd class="sqw-monospace"><%= @execution.exception_class %></dd>
diff --git a/app/views/solid_stack_web/history/index.html.erb b/app/views/solid_stack_web/history/index.html.erb
index 33180e4..68bde62 100644
--- a/app/views/solid_stack_web/history/index.html.erb
+++ b/app/views/solid_stack_web/history/index.html.erb
@@ -61,7 +61,7 @@
                     class: "sqw-badge sqw-badge--queue" %>
             </td>
             <td class="sqw-monospace"><%= format_duration(job.finished_at - job.created_at) %></td>
-            <td class="sqw-muted"><%= job.finished_at.strftime("%b %d %H:%M:%S") %></td>
+            <td class="sqw-muted"><%= local_time(job.finished_at) %></td>
           </tr>
         <% end %>
       </tbody>
diff --git a/app/views/solid_stack_web/jobs/index.html.erb b/app/views/solid_stack_web/jobs/index.html.erb
index c5b5112..c7b43f7 100644
--- a/app/views/solid_stack_web/jobs/index.html.erb
+++ b/app/views/solid_stack_web/jobs/index.html.erb
@@ -121,9 +121,9 @@
               <td class="sqw-monospace"><%= link_to execution.job.class_name, job_path(execution.id, status: @status), data: { turbo_frame: "_top" } %></td>
               <td><span class="sqw-badge sqw-badge--queue"><%= execution.job.queue_name %></span></td>
               <td><%= execution.job.priority %></td>
-              <td class="sqw-muted"><%= execution.created_at.strftime("%b %d %H:%M") %></td>
+              <td class="sqw-muted"><%= local_time(execution.created_at) %></td>
               <% if @status == "scheduled" %>
-                <td id="scheduled_at_<%= execution.id %>" class="sqw-muted"><%= execution.scheduled_at&.strftime("%b %d %H:%M") %></td>
+                <td id="scheduled_at_<%= execution.id %>" class="sqw-muted"><%= local_time(execution.scheduled_at) %></td>
               <% end %>
               <td class="sqw-actions">
                 <% if @status == "scheduled" %>
diff --git a/app/views/solid_stack_web/jobs/show.html.erb b/app/views/solid_stack_web/jobs/show.html.erb
index 88852da..23a28e8 100644
--- a/app/views/solid_stack_web/jobs/show.html.erb
+++ b/app/views/solid_stack_web/jobs/show.html.erb
@@ -36,17 +36,17 @@
 
       <% if @status == "blocked" %>
         <dt>Blocked Until</dt>
-        <dd class="sqw-monospace"><%= @execution.expires_at ? @execution.expires_at.strftime("%Y-%m-%d %H:%M:%S UTC") : "—" %></dd>
+        <dd class="sqw-monospace"><%= local_time(@execution.expires_at, format: :long) %></dd>
       <% end %>
 
       <dt>Enqueued At</dt>
-      <dd class="sqw-monospace"><%= @execution.job.created_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></dd>
+      <dd class="sqw-monospace"><%= local_time(@execution.job.created_at, format: :long) %></dd>
 
       <dt>Scheduled At</dt>
-      <dd class="sqw-monospace"><%= @execution.job.scheduled_at ? @execution.job.scheduled_at.strftime("%Y-%m-%d %H:%M:%S UTC") : "—" %></dd>
+      <dd class="sqw-monospace"><%= local_time(@execution.job.scheduled_at, format: :long) %></dd>
 
       <dt>Finished At</dt>
-      <dd class="sqw-monospace"><%= @execution.job.finished_at ? @execution.job.finished_at.strftime("%Y-%m-%d %H:%M:%S UTC") : "—" %></dd>
+      <dd class="sqw-monospace"><%= local_time(@execution.job.finished_at, format: :long) %></dd>
     </dl>
   </div>
 
diff --git a/app/views/solid_stack_web/processes/index.html.erb b/app/views/solid_stack_web/processes/index.html.erb
index 3dbf02f..b8b5f36 100644
--- a/app/views/solid_stack_web/processes/index.html.erb
+++ b/app/views/solid_stack_web/processes/index.html.erb
@@ -22,7 +22,7 @@
           <td class="sqw-monospace"><%= process.name %></td>
           <td class="sqw-monospace"><%= process.pid %></td>
           <td class="sqw-muted"><%= process.hostname %></td>
-          <td class="sqw-muted"><%= process.last_heartbeat_at&.strftime("%b %d %H:%M:%S") %></td>
+          <td class="sqw-muted"><%= local_time(process.last_heartbeat_at) %></td>
         </tr>
       <% end %>
     </tbody>
diff --git a/app/views/solid_stack_web/queues/show.html.erb b/app/views/solid_stack_web/queues/show.html.erb
index cf0bf0e..1a3ea99 100644
--- a/app/views/solid_stack_web/queues/show.html.erb
+++ b/app/views/solid_stack_web/queues/show.html.erb
@@ -49,7 +49,7 @@
                   data: { turbo_frame: "_top" } %>
           </td>
           <td><%= execution.job.priority %></td>
-          <td class="sqw-muted"><%= execution.created_at.strftime("%b %d %H:%M") %></td>
+          <td class="sqw-muted"><%= local_time(execution.created_at) %></td>
           <td class="sqw-actions">
             <%= button_to "Discard", job_path(execution, status: "ready", queue: @queue_name),
                   method: :delete, class: "sqw-btn sqw-btn--danger sqw-btn--sm",
diff --git a/app/views/solid_stack_web/recurring_tasks/index.html.erb b/app/views/solid_stack_web/recurring_tasks/index.html.erb
index e3e3a8f..4651ba9 100644
--- a/app/views/solid_stack_web/recurring_tasks/index.html.erb
+++ b/app/views/solid_stack_web/recurring_tasks/index.html.erb
@@ -36,12 +36,11 @@
           </td>
           <td><span class="sqw-badge sqw-badge--queue"><%= task.queue_name.presence || "default" %></span></td>
           <td class="sqw-muted sqw-monospace">
-            <% next_run = begin; task.next_time.strftime("%b %d %H:%M"); rescue; nil; end %>
-            <%= next_run || "—" %>
+            <% next_run = begin; task.next_time; rescue; nil; end %>
+            <%= local_time(next_run) %>
           </td>
           <td class="sqw-muted sqw-monospace">
-            <% last_run = task.last_enqueued_time %>
-            <%= last_run ? last_run.strftime("%b %d %H:%M") : "—" %>
+            <%= local_time(task.last_enqueued_time) %>
           </td>
           <td>
             <% if task.static? %>
diff --git a/app/views/solid_stack_web/scheduled_jobs/update.turbo_stream.erb b/app/views/solid_stack_web/scheduled_jobs/update.turbo_stream.erb
index 57c99e2..f999ce6 100644
--- a/app/views/solid_stack_web/scheduled_jobs/update.turbo_stream.erb
+++ b/app/views/solid_stack_web/scheduled_jobs/update.turbo_stream.erb
@@ -3,7 +3,7 @@
 <% else %>
   <%= turbo_stream.replace "scheduled_at_#{@execution.id}" do %>
     <td id="scheduled_at_<%= @execution.id %>" class="sqw-muted">
-      <%= @execution.scheduled_at.strftime("%b %d %H:%M") %>
+      <%= local_time(@execution.scheduled_at) %>
     </td>
   <% end %>
 <% end %>
\ No newline at end of file
diff --git a/config/importmap.rb b/config/importmap.rb
index 3baec1d..4ae8f87 100644
--- a/config/importmap.rb
+++ b/config/importmap.rb
@@ -6,3 +6,4 @@
 pin "solid_stack_web/selection_controller", to: "solid_stack_web/selection_controller.js"
 pin "solid_stack_web/sparkline_tooltip_controller", to: "solid_stack_web/sparkline_tooltip_controller.js"
 pin "solid_stack_web/theme_controller", to: "solid_stack_web/theme_controller.js"
+pin "solid_stack_web/timestamp_controller", to: "solid_stack_web/timestamp_controller.js"