pgbus 0.17.1 → 0.17.3

data/app/helpers/pgbus/application_helper.rb

@@ -1,21 +1,34 @@
 # frozen_string_literal: true
 
-require "time"
-
 module Pgbus
   module ApplicationHelper
-    def pgbus_time_ago(time)
-      return "—" unless time
+    # A moment as "5m ago" / "in 2h" / "now", with the exact value in the
+    # tooltip and the UTC value in datetime (issue #497). clock: true adds
+    # the wall-clock time: "in 2h (21:40)".
+    def pgbus_time(value, clock: false)
+      return Web::TimeFormat::NONE if value.blank?
 
-      time = Time.parse(time) if time.is_a?(String)
-      seconds = (Time.now - time).to_i
+      relative = Web::TimeFormat.relative(value)
+      return value.to_s unless relative
 
-      case seconds
-      when 0..59 then "#{seconds}s ago"
-      when 60..3599 then "#{seconds / 60}m ago"
-      when 3600..86_399 then "#{seconds / 3600}h ago"
-      else "#{seconds / 86_400}d ago"
-      end
+      text = clock ? "#{relative} (#{Web::TimeFormat.clock(value)})" : relative
+      tag.time(text, datetime: Web::TimeFormat.iso(value), title: Web::TimeFormat.absolute(value))
+    end
+
+    # The exact moment, then the relative one: for expanded rows and show
+    # pages, where the absolute is what an operator debugs with.
+    def pgbus_timestamp(value)
+      return Web::TimeFormat::NONE if value.blank?
+      return value.to_s unless Web::TimeFormat.coerce(value)
+
+      safe_join([pgbus_absolute_time(value), " (#{Web::TimeFormat.relative(value)})"])
+    end
+
+    def pgbus_absolute_time(value)
+      return Web::TimeFormat::NONE if value.blank?
+      return value.to_s unless Web::TimeFormat.coerce(value)
+
+      tag.time(Web::TimeFormat.absolute(value), datetime: Web::TimeFormat.iso(value))
     end
 
     def pgbus_number(n)
@@ -29,43 +42,6 @@ module Pgbus
       end
     end
 
-    # Order the rate keys are rendered in, and their i18n label suffixes.
-    WORKER_RATE_KEYS = %w[processed failed dequeued].freeze
-
-    # Metadata keys rendered specially elsewhere (throughput badge, health
-    # status) and therefore excluded from the generic key/value dump.
-    WORKER_INTERNAL_METADATA_KEYS = %w[rates jobs_processed jobs_failed in_flight loop_tick_at].freeze
-
-    # The subset of a process's metadata to render as generic key/value badges:
-    # everything except the throughput/health keys that have dedicated rendering.
-    def pgbus_display_metadata(metadata)
-      return {} unless metadata.is_a?(Hash)
-
-      metadata.reject { |k, _| WORKER_INTERNAL_METADATA_KEYS.include?(k.to_s) }
-    end
-
-    # Render a worker's per-second throughput rates (from heartbeat metadata)
-    # as a compact human-readable string, e.g. "12.4/s processed · 0.2/s failed".
-    # Zero rates are omitted; returns nil when there are no non-zero rates so
-    # callers can fall back to the raw metadata rendering.
-    def pgbus_worker_rates(metadata)
-      return nil unless metadata.is_a?(Hash)
-
-      rates = metadata["rates"]
-      return nil unless rates.is_a?(Hash)
-
-      parts = WORKER_RATE_KEYS.filter_map do |key|
-        value = rates[key].to_f
-        next if value.zero?
-
-        label = I18n.t("pgbus.processes.processes_table.rates.#{key}", default: key)
-        "#{value}/s #{label}"
-      end
-      return nil if parts.empty?
-
-      parts.join(" · ")
-    end
-
     def pgbus_status_badge(healthy_or_status)
       status = case healthy_or_status
                when true then :healthy
@@ -76,59 +52,45 @@ module Pgbus
       case status
       when :healthy
         tag.span(I18n.t("pgbus.helpers.status_badge.healthy"),
-                 class: "inline-flex items-center rounded-full bg-green-100 px-2.5 py-0.5 text-xs font-medium text-green-800")
+                 class: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium " \
+                        "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400")
       when :stalled
         tag.span(I18n.t("pgbus.helpers.status_badge.stalled"),
-                 class: "inline-flex items-center rounded-full bg-yellow-100 px-2.5 py-0.5 text-xs font-medium text-yellow-800")
+                 class: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium " \
+                        "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400")
       else
         tag.span(I18n.t("pgbus.helpers.status_badge.stale"),
-                 class: "inline-flex items-center rounded-full bg-red-100 px-2.5 py-0.5 text-xs font-medium text-red-800")
+                 class: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium " \
+                        "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400")
       end
     end
 
     def pgbus_queue_badge(name)
       if name.to_s.end_with?("_dlq")
         tag.span(I18n.t("pgbus.helpers.queue_badge.dlq"),
-                 class: "inline-flex items-center rounded-full bg-red-100 px-2 py-0.5 text-xs font-medium text-red-700")
+                 class: "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium " \
+                        "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400")
       else
         tag.span(I18n.t("pgbus.helpers.queue_badge.queue"),
-                 class: "inline-flex items-center rounded-full bg-blue-100 px-2 py-0.5 text-xs font-medium text-blue-700")
+                 class: "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium " \
+                        "bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400")
       end
     end
 
     def pgbus_duration(seconds)
-      return "—" unless seconds
-
-      seconds = seconds.to_i
-      if seconds < 60
-        "#{seconds}s"
-      elsif seconds < 3600
-        "#{seconds / 60}m #{seconds % 60}s"
-      elsif seconds < 86_400
-        "#{seconds / 3600}h #{(seconds % 3600) / 60}m"
-      else
-        "#{seconds / 86_400}d #{(seconds % 86_400) / 3600}h"
-      end
+      Web::TimeFormat.duration(seconds)
     end
 
     def pgbus_ms_duration(millis)
-      return "—" unless millis
-
-      millis = millis.to_i
-      if millis < 1000
-        "#{millis}ms"
-      elsif millis < 60_000
-        "#{(millis / 1000.0).round(1)}s"
-      else
-        "#{(millis / 60_000.0).round(1)}m"
-      end
+      Web::TimeFormat.ms_duration(millis)
     end
 
     def pgbus_paused_badge(paused)
       return unless paused
 
       tag.span(I18n.t("pgbus.helpers.paused_badge"),
-               class: "inline-flex items-center rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-800")
+               class: "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium " \
+                      "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400")
     end
 
     BATCH_BADGE_BASE = "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium"
@@ -143,6 +105,117 @@ module Pgbus
       tag.span(I18n.t("pgbus.helpers.batch_status.#{status}", default: status), class: css)
     end
 
+    JOB_STATE_BADGE_CSS = {
+      blue: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
+      gray: "bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300",
+      indigo: "bg-indigo-100 text-indigo-800 dark:bg-indigo-900/30 dark:text-indigo-300",
+      yellow: "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400",
+      purple: "bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-400",
+      green: "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400"
+    }.freeze
+
+    def pgbus_job_state_badge(state)
+      tone = Pgbus::Web::JobState::BADGE_TONES.fetch(state.to_s, :gray)
+      tag.span(I18n.t("pgbus.jobs.list.states.#{state}"), class: "#{BATCH_BADGE_BASE} #{JOB_STATE_BADGE_CSS[tone]}")
+    end
+
+    # A JobState::Result's reason in words. :time is a future moment
+    # ("in 2h (21:40)"), :ago a past one ("5m ago"), both as <time>. The
+    # _html key lets them through; translate escapes every other argument.
+    def pgbus_job_reason(result)
+      translate("pgbus.jobs.list.reasons.#{result.reason_key}_html", **pgbus_reason_args(result.reason_args))
+    end
+
+    # Reason arguments ready for an _html key: :time (future) and :ago (past)
+    # as <time>, everything else as given for translate to escape.
+    def pgbus_reason_args(args)
+      args.to_h do |key, value|
+        case key
+        when :time then [key, pgbus_time(value, clock: true)]
+        when :ago then [key, pgbus_time(value)]
+        else [key, value]
+        end
+      end
+    end
+
+    # A QueueSummary::Line in words. :ago is a past moment and :time a future
+    # one, both as <time>; :age is a wait in seconds. The _html key lets the
+    # <time> elements through; translate escapes every other argument.
+    def pgbus_queue_summary_line(line)
+      args = line.args.to_h do |key, value|
+        case key
+        when :ago then [key, pgbus_time(value)]
+        when :time then [key, pgbus_time(value, clock: true)]
+        when :age then [key, pgbus_duration(value)]
+        else [key, value]
+        end
+      end
+      translate("pgbus.queues.show.summary.#{line.key}_html", **args)
+    end
+
+    QUEUE_SUMMARY_TONE_CSS = {
+      yellow: "bg-yellow-50 text-yellow-800 ring-yellow-200 dark:bg-yellow-900/30 dark:text-yellow-200 dark:ring-yellow-800",
+      red: "bg-red-50 text-red-800 ring-red-200 dark:bg-red-900/30 dark:text-red-200 dark:ring-red-800",
+      gray: "bg-gray-50 text-gray-700 ring-gray-200 dark:bg-gray-900/40 dark:text-gray-200 dark:ring-gray-700"
+    }.freeze
+
+    def pgbus_queue_summary_classes(tone)
+      QUEUE_SUMMARY_TONE_CSS.fetch(tone, QUEUE_SUMMARY_TONE_CSS[:gray])
+    end
+
+    # "2/5" for a job's delivery attempts against max_retries; "—" when the
+    # row was never delivered (blocked).
+    def pgbus_job_attempts(row, max_retries)
+      return "—" if row[:read_ct].nil?
+
+      "#{row[:read_ct]}/#{max_retries}"
+    end
+
+    # A DeadLetterReason::Result in words (issue #495). With filter_path
+    # (->(extra) { url }) the error class becomes a link that filters the list
+    # to it. The _html keys let that link through; translate escapes the
+    # error message and every other argument.
+    def pgbus_dead_letter_reason(result, filter_path: nil)
+      args = result.reason_args.dup
+      if args[:error_class] && filter_path
+        args[:error_class] = pgbus_link_to(
+          result.error_class, filter_path.call(error_class: result.error_class, page: nil),
+          title: t("pgbus.dead_letter.filters.filter_error_class", error_class: result.error_class),
+          data: { turbo_frame: "_top" }
+        )
+      end
+      sentence = translate("pgbus.dead_letter.reasons.#{result.reason_key}_html", **args)
+      return sentence unless result.retried_before.to_i.positive?
+
+      note = t("pgbus.dead_letter.reasons.retried_before", count: result.retried_before)
+      safe_join([sentence, tag.span(note, class: "mt-1 block text-xs text-gray-600 dark:text-gray-300")])
+    end
+
+    def pgbus_dead_letter_attempts(result)
+      return "—" if result.attempts.nil?
+
+      "#{result.attempts}/#{result.max_retries}"
+    end
+
+    # The Job column: an ActiveJob's class, or a dead event's routing key.
+    # Reads the raw message like the Events page: both are identifiers, and
+    # PayloadFilter's default /_key$/ pattern would mask routing_key.
+    def pgbus_dead_letter_job(message)
+      payload = message.is_a?(String) ? JSON.parse(message) : message
+      return "—" unless payload.is_a?(Hash)
+
+      headers = payload["headers"]
+      payload["job_class"].presence || (headers["routing_key"].presence if headers.is_a?(Hash)) ||
+        payload["routing_key"].presence || "—"
+    rescue JSON::ParserError
+      "—"
+    end
+
+    # A tab's count, with "+" when a capped fragment made it a lower bound.
+    def pgbus_job_count(counts, state)
+      "#{number_with_delimiter(counts[state])}#{"+" if counts.capped?(state)}"
+    end
+
     # Persisted Current attributes for a job payload, as
     # { "Current" => { "tenant" => "gid://…", ... } } or nil (issue #430).
     # Goes through pgbus_parse_message so PayloadFilter redaction applies.
@@ -175,45 +248,20 @@ module Pgbus
       Pgbus.configuration.web_refresh_interval
     end
 
-    def pgbus_time_ago_future(time)
-      return "—" unless time
-
-      time = Time.parse(time) if time.is_a?(String)
-      seconds = (time - Time.now).to_i
-
-      if seconds <= 0
-        "now"
-      elsif seconds < 60
-        "in #{seconds}s"
-      elsif seconds < 3600
-        "in #{seconds / 60}m"
-      elsif seconds < 86_400
-        "in #{seconds / 3600}h"
-      else
-        "in #{seconds / 86_400}d"
-      end
-    end
-
     def pgbus_recurring_health_badge(task)
       if task[:last_run_at].nil?
         tag.span(I18n.t("pgbus.helpers.recurring_health.pending"),
-                 class: "inline-flex items-center rounded-full bg-yellow-100 px-2.5 py-0.5 text-xs font-medium text-yellow-800")
+                 class: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium " \
+                        "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400")
       else
         tag.span(I18n.t("pgbus.helpers.recurring_health.active"),
-                 class: "inline-flex items-center rounded-full bg-green-100 px-2.5 py-0.5 text-xs font-medium text-green-800")
+                 class: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium " \
+                        "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400")
       end
     end
 
     def pgbus_time_range_label(minutes)
-      minutes = [minutes.to_i, 1].max
-
-      if minutes > 1440 && (minutes % 1440).zero?
-        pgbus_pluralize_unit(minutes / 1440, "day")
-      elsif minutes >= 60 && (minutes % 60).zero?
-        pgbus_pluralize_unit(minutes / 60, "hour")
-      else
-        pgbus_pluralize_unit(minutes, "minute")
-      end
+      Web::TimeFormat.range_label(minutes)
     end
 
     def pgbus_nav_link(label, path)
@@ -272,11 +320,5 @@ module Pgbus
       else "\u{1F310}"
       end
     end
-
-    private
-
-    def pgbus_pluralize_unit(count, unit)
-      count == 1 ? "1 #{unit}" : "#{count} #{unit}s"
-    end
   end
 end

data/app/helpers/pgbus/button_helper.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Every button and action link on the dashboard (issue #496): one class table
+  # with light and dark colours, a focus ring, and a 24 px minimum target
+  # (WCAG 2.5.8) in every size. Class lists are spelled out in full so Tailwind
+  # and the static specs (dark_mode_contrast_spec, compiled_css_coverage_spec)
+  # can see every token; never interpolate a colour name.
+  module ButtonHelper
+    BASE = "inline-flex items-center min-h-6 font-medium focus-visible:outline-2 focus-visible:outline-offset-2 " \
+           "focus-visible:outline-indigo-600 dark:focus-visible:outline-indigo-400"
+
+    VARIANTS = {
+      # Hover goes darker, never lighter: white on red-500 is 3.8:1, on
+      # green-600 3.3:1, both under 4.5:1 for these small labels.
+      primary: "bg-indigo-600 text-white hover:bg-indigo-700",
+      danger: "bg-red-600 text-white hover:bg-red-700",
+      # Permanent and irreversible (Delete queue), set apart from danger.
+      destructive: "bg-red-800 text-white hover:bg-red-900",
+      success: "bg-green-700 text-white hover:bg-green-800",
+      # White on yellow fails; yellow buttons carry dark text in both themes.
+      warning: "bg-yellow-400 text-yellow-950 hover:bg-yellow-300",
+      secondary: "bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-200 hover:bg-gray-200 dark:hover:bg-gray-600",
+      # Bordered, on the card's own surface (the pager).
+      outline: "border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-800 text-gray-700 dark:text-gray-300 " \
+               "hover:bg-gray-50 dark:hover:bg-gray-700",
+      # A row in a dropdown menu (the Events reroute picker).
+      menu: "w-full justify-start text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-700",
+      link: nil
+    }.freeze
+
+    # Link colours. Dark text is -300: 12 px row actions sit on the hovered row
+    # tint (dark:hover:bg-gray-700/50), where -400 drops below 4.5:1.
+    TONES = {
+      indigo: "text-indigo-600 dark:text-indigo-300 hover:text-indigo-800 dark:hover:text-indigo-200",
+      red: "text-red-600 dark:text-red-300 hover:text-red-800 dark:hover:text-red-200",
+      green: "text-green-700 dark:text-green-300 hover:text-green-900 dark:hover:text-green-200",
+      yellow: "text-yellow-700 dark:text-yellow-300 hover:text-yellow-900 dark:hover:text-yellow-200"
+    }.freeze
+
+    SIZES = {
+      sm: "rounded-md px-3 py-1.5 text-xs",
+      md: "rounded-md px-3 py-2 text-sm"
+    }.freeze
+
+    # Links keep their type size; the padding on sm gives the 24 px target.
+    LINK_SIZES = {
+      sm: "rounded px-1.5 py-1 text-xs",
+      md: "text-sm"
+    }.freeze
+
+    def pgbus_button_classes(variant, size = :md, tone: :indigo, extra: nil)
+      raise ArgumentError, "unknown button variant: #{variant.inspect}" unless VARIANTS.key?(variant)
+      raise ArgumentError, "unknown button size: #{size.inspect}" unless SIZES.key?(size)
+
+      colours = variant == :link ? TONES.fetch(tone) { raise ArgumentError, "unknown link tone: #{tone.inspect}" } : VARIANTS[variant]
+      sizing = variant == :link ? LINK_SIZES[size] : SIZES[size]
+      [BASE, sizing, colours, extra].compact.join(" ")
+    end
+
+    def pgbus_button_to(label, path, variant: :primary, size: :md, tone: :indigo, confirm: nil, **options)
+      options[:class] = pgbus_button_classes(variant, size, tone: tone, extra: options[:class])
+      options[:data] = pgbus_confirm_data(options[:data], confirm)
+      button_to(label, path, options)
+    end
+
+    def pgbus_link_to(label, path, variant: :link, size: :md, tone: :indigo, **options)
+      options[:class] = pgbus_button_classes(variant, size, tone: tone, extra: options[:class])
+      link_to(label, path, options)
+    end
+
+    # A submit button outside its form (form: "bulk-…"), for the bulk actions.
+    def pgbus_button_tag(label, variant: :primary, size: :md, tone: :indigo, confirm: nil, **options)
+      options[:class] = pgbus_button_classes(variant, size, tone: tone, extra: options[:class])
+      options[:data] = pgbus_confirm_data(options[:data], confirm)
+      content_tag(:button, label, type: "submit", **options)
+    end
+
+    private
+
+    # application.js's confirm dialog reads data-turbo-confirm.
+    def pgbus_confirm_data(data, confirm)
+      data = (data || {}).dup
+      data[:turbo_confirm] = confirm if confirm
+      data.presence
+    end
+  end
+end

data/app/helpers/pgbus/dashboard_helper.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # The home page's words (issue #492): the health verdict strip, the card
+  # sentences built from DataSource#dashboard_signals, the queue rows'
+  # QueueSummary line and the Queue Health thresholds from HealthVerdict.
+  module DashboardHelper
+    PART_SEPARATOR = " · "
+
+    # Every home card is a link to the page that explains it.
+    CARD_CSS = "block rounded-lg bg-white dark:bg-gray-800 p-5 shadow ring-1 ring-gray-200 dark:ring-gray-700 " \
+               "hover:ring-gray-300 dark:hover:ring-gray-600"
+    CARD_NUMBER_CSS = "mt-1 text-3xl font-semibold text-gray-900 dark:text-white"
+
+    VERDICT_CSS = {
+      "OK" => "bg-green-50 text-green-800 ring-green-200 dark:bg-green-900/30 dark:text-green-200 dark:ring-green-800",
+      "DEGRADED" => "bg-yellow-50 text-yellow-800 ring-yellow-200 dark:bg-yellow-900/30 dark:text-yellow-200 " \
+                    "dark:ring-yellow-800",
+      "STALLED" => "bg-red-50 text-red-800 ring-red-200 dark:bg-red-900/30 dark:text-red-200 dark:ring-red-800"
+    }.freeze
+    VERDICT_UNKNOWN_CSS = "bg-gray-50 text-gray-700 ring-gray-200 dark:bg-gray-900/40 dark:text-gray-200 dark:ring-gray-700"
+
+    # Stat numbers are text-3xl, so the -600 shades meet the 3:1 large-text ratio.
+    HEALTH_NUMBER_CSS = {
+      ok: "mt-1 text-3xl font-semibold text-green-600 dark:text-green-400",
+      warn: "mt-1 text-3xl font-semibold text-amber-600 dark:text-amber-400",
+      critical: "mt-1 text-3xl font-semibold text-red-600 dark:text-red-400",
+      unknown: "mt-1 text-3xl font-semibold text-gray-900 dark:text-white"
+    }.freeze
+    HEALTH_WORDS_CSS = {
+      ok: "text-xs text-gray-600 dark:text-gray-300",
+      warn: "text-xs text-amber-700 dark:text-amber-300",
+      critical: "text-xs text-red-700 dark:text-red-300",
+      unknown: "text-xs text-gray-600 dark:text-gray-300"
+    }.freeze
+    QUEUE_STATUS_CSS = {
+      red: "text-red-700 dark:text-red-300",
+      yellow: "text-yellow-800 dark:text-yellow-200",
+      gray: "text-gray-600 dark:text-gray-300"
+    }.freeze
+
+    def pgbus_verdict_css(verdict)
+      VERDICT_CSS.fetch(verdict&.dig(:status).to_s, VERDICT_UNKNOWN_CSS)
+    end
+
+    # Where the verdict's reasons are explained, from the signals rather than
+    # the (English, unlocalised) reason strings.
+    def pgbus_verdict_links(signals)
+      processes = signals[:processes]
+      links = []
+      if (processes[:stalled] + processes[:stale]).positive?
+        links << pgbus_link_to(t("pgbus.dashboard.verdict.links.processes"), pgbus.processes_path,
+                               data: { turbo_frame: "_top" })
+      end
+      if signals[:dlq][:depth].positive?
+        links << pgbus_link_to(t("pgbus.dashboard.verdict.links.dlq"), pgbus.dead_letter_index_path, data: { turbo_frame: "_top" })
+      end
+      links
+    end
+
+    def pgbus_queue_card_words(queues)
+      parts = [t("pgbus.dashboard.stats_cards.queues_detail", paused: queues[:paused], dlq: queues[:dlq])]
+      parts << t("pgbus.dashboard.stats_cards.queues_undrained", count: queues[:undrained]) if queues[:undrained].positive?
+      safe_join(parts, PART_SEPARATOR)
+    end
+
+    def pgbus_enqueued_card_words(queues)
+      parts = [t("pgbus.dashboard.stats_cards.enqueued_detail", claimable: number_with_delimiter(queues[:claimable]),
+                                                                waiting: number_with_delimiter(queues[:waiting]))]
+      parts << t("pgbus.dashboard.stats_cards.enqueued_paused", count: queues[:paused_depth]) if queues[:paused_depth].positive?
+      safe_join(parts, PART_SEPARATOR)
+    end
+
+    def pgbus_process_card_words(processes)
+      return t("pgbus.dashboard.stats_cards.processes_none") if processes[:total].zero?
+
+      words = t("pgbus.dashboard.stats_cards.processes_detail", **processes.slice(:healthy, :stalled, :stale))
+      return words unless processes[:stale].positive?
+
+      safe_join([words, t("pgbus.dashboard.stats_cards.processes_stale")], " — ")
+    end
+
+    def pgbus_retrying_card_words(retrying)
+      return t("pgbus.dashboard.stats_cards.retrying_none") if retrying[:count].zero?
+
+      parts = []
+      if retrying[:next_attempt_at]
+        parts << t("pgbus.dashboard.stats_cards.retrying_next_html", time: pgbus_time(retrying[:next_attempt_at], clock: true))
+      end
+      if retrying[:due_now_count].positive?
+        # Past the per-queue cap the due count is a lower bound, like the total.
+        due = retrying[:capped] ? "#{number_with_delimiter(retrying[:due_now_count])}+" : retrying[:due_now_count]
+        parts << t("pgbus.dashboard.stats_cards.retrying_due", count: due)
+      end
+      parts << t("pgbus.dashboard.stats_cards.retrying_newest", error_class: retrying[:newest_error_class]) if retrying[:newest_error_class]
+      safe_join(parts, PART_SEPARATOR)
+    end
+
+    def pgbus_retrying_count(retrying)
+      "#{number_with_delimiter(retrying[:count])}#{"+" if retrying[:capped]}"
+    end
+
+    # The newest dead letter's reason, read as the DLQ page reads it (#495).
+    def pgbus_dlq_card_words(dlq)
+      return t("pgbus.dashboard.stats_cards.dlq_none") if dlq[:depth].zero?
+      return t("pgbus.dashboard.stats_cards.dlq_see_why") unless dlq[:newest]
+
+      reason = Web::DeadLetterReason.present(dlq[:newest])
+      args = { job: pgbus_dead_letter_job(dlq[:newest][:message]), ago: pgbus_time(reason.died_at) }
+      return t("pgbus.dashboard.stats_cards.dlq_newest_legacy_html", **args) if reason.legacy?
+      return t("pgbus.dashboard.stats_cards.dlq_newest_no_error_html", **args) unless reason.error_class
+
+      t("pgbus.dashboard.stats_cards.dlq_newest_html", error_class: reason.error_class, **args)
+    end
+
+    def pgbus_queue_status(line)
+      return Web::TimeFormat::NONE unless line
+
+      tag.span(pgbus_queue_summary_line(line), class: QUEUE_STATUS_CSS.fetch(line.tone, QUEUE_STATUS_CSS[:gray]))
+    end
+
+    # A HealthVerdict::Entry in words. Bloat thresholds are ratios, the
+    # vacuum and transaction ones seconds.
+    def pgbus_health_words(entry)
+      percent = entry.key.start_with?("bloat.")
+      args = entry.args.to_h do |key, value|
+        case key
+        when :table then [key, value]
+        when :count, :limit then [key, number_with_delimiter(value)]
+        else [key, percent ? pgbus_percent(value) : pgbus_duration(value)]
+        end
+      end
+      tag.p(t("pgbus.dashboard.queue_health.words.#{entry.key}", **args), class: HEALTH_WORDS_CSS.fetch(entry.level))
+    end
+
+    def pgbus_health_number_css(entry) = HEALTH_NUMBER_CSS.fetch(entry.level)
+
+    def pgbus_percent(ratio)
+      number_to_percentage(ratio.to_f * 100, precision: 1, strip_insignificant_zeros: true)
+    end
+
+    # "4 / 5" for a failed row: the attempt that failed against max_retries.
+    def pgbus_failure_attempt(row)
+      "#{row["retry_count"].to_i + 1} / #{Pgbus.configuration.max_retries}"
+    end
+
+    # The payload arrives as a JSON string or, when the column is typecast,
+    # an already-parsed Hash.
+    def pgbus_failure_job(row)
+      payload = row["payload"]
+      payload = JSON.parse(payload.to_s) unless payload.is_a?(Hash)
+      (payload["job_class"] if payload.is_a?(Hash)).presence || row["handler_class"].presence || Web::TimeFormat::NONE
+    rescue JSON::ParserError
+      row["handler_class"].presence || Web::TimeFormat::NONE
+    end
+  end
+end

data/app/helpers/pgbus/events_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # The Events page's words (issue #494): EventState results as badges and
+  # sentences, in the jobs list's vocabulary and colours.
+  module EventsHelper
+    def pgbus_event_state_badge(state)
+      tone = Pgbus::Web::JobState::BADGE_TONES.fetch(state.to_s, :gray)
+      tag.span(t("pgbus.events.list.states.#{state}"),
+               class: "#{ApplicationHelper::BATCH_BADGE_BASE} #{ApplicationHelper::JOB_STATE_BADGE_CSS[tone]}")
+    end
+
+    # An EventState::Result in words. The _html key lets the <time> elements
+    # through; translate escapes the handler, pattern and error.
+    def pgbus_event_reason(result)
+      translate("pgbus.events.list.reasons.#{result.reason_key}_html", **pgbus_reason_args(result.reason_args))
+    end
+
+    def pgbus_processed_event_badge(result)
+      tag.span(t("pgbus.events.processed.states.#{result.state}"),
+               class: "#{ApplicationHelper::BATCH_BADGE_BASE} #{ApplicationHelper::JOB_STATE_BADGE_CSS[result.badge_tone]}")
+    end
+
+    def pgbus_processed_event_reason(result)
+      translate("pgbus.events.processed.reasons.#{result.reason_key}_html", **pgbus_reason_args(result.reason_args))
+    end
+
+    # The routing key from the raw message: PayloadFilter's default /_key$/
+    # pattern would mask it in the parsed (filtered) payload.
+    def pgbus_event_routing_key(message)
+      payload = message.is_a?(String) ? JSON.parse(message) : message
+      return "—" unless payload.is_a?(Hash)
+
+      headers = payload["headers"]
+      (headers["routing_key"].presence if headers.is_a?(Hash)) || payload["routing_key"].presence || "—"
+    rescue JSON::ParserError, TypeError
+      "—"
+    end
+  end
+end

data/app/helpers/pgbus/insights_helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # The Insights charts' words (issue #492): one sentence per chart, used as
+  # its figcaption and as the chart's accessible name.
+  module InsightsHelper
+    def pgbus_job_stat_status(status)
+      t("pgbus.insights.show.statuses.#{status}", default: status.to_s.humanize)
+    end
+
+    def pgbus_throughput_caption(chart, minutes)
+      t("pgbus.insights.show.charts.captions.throughput_html",
+        total: number_with_delimiter(chart.total), range: pgbus_time_range_label(minutes),
+        peak: number_with_delimiter(chart.peak), at: pgbus_time(chart.peak_at, clock: true))
+    end
+
+    def pgbus_status_caption(chart)
+      t("pgbus.insights.show.charts.captions.status", success: number_with_delimiter(chart[:success]),
+                                                      failed: number_with_delimiter(chart[:failed]),
+                                                      dead_lettered: number_with_delimiter(chart[:dead_lettered]))
+    end
+
+    def pgbus_latency_caption(summary)
+      t("pgbus.insights.show.charts.captions.latency", avg: pgbus_ms_duration(summary[:avg_latency_ms]),
+                                                       p95: pgbus_ms_duration(summary[:p95_latency_ms]))
+    end
+
+    # The labels charts.js puts on the series and the donut legend.
+    def pgbus_chart_i18n
+      {
+        seriesName: t("pgbus.insights.show.charts.series_name"),
+        latencyAvg: t("pgbus.insights.show.charts.latency_avg"),
+        latencyP95: t("pgbus.insights.show.charts.latency_p95"),
+        milliseconds: t("pgbus.helpers.time.units.milliseconds", count: "%n"),
+        statuses: Web::InsightsCharts::STATUS_ORDER.index_with { |status| pgbus_job_stat_status(status) }
+      }
+    end
+  end
+end