feat: PopoverMainView redesign (#296) (design-branch-2)

.gitignore

@@ -0,0 +1,2 @@
+.build
+dist

.swiftlint.yml

@@ -8,7 +8,7 @@ excluded:
   - .build
   - Package.swift
 
-# ── Opt-in rules ────────────────────────────────────────────────────────────────────────
+# ── Opt-in rules ────────────────────────────────────────────────────────────────────────────────────
 opt_in_rules:
   - missing_docs           # require /// on all internal/public declarations
   - closure_spacing        # consistent spacing inside closure braces
@@ -23,7 +23,7 @@ opt_in_rules:
   - empty_collection_literal  # prefer isEmpty over == []
   - first_where            # prefer first(where:) over filter().first
 
-# ── Rule configuration ───────────────────────────────────────────────────────────────────
+# ── Rule configuration ─────────────────────────────────────────────────────────────────────────────────────
 missing_docs:
   warning:
     - internal
@@ -40,7 +40,7 @@ line_length:
   ignores_urls: true
 
 file_length:
-  warning: 400
+  warning: 500
   error: 600
 
 type_body_length:
@@ -61,7 +61,7 @@ nesting:
   function_level:
     warning: 3
 
-# ── Disabled rules ───────────────────────────────────────────────────────────────────────
+# ── Disabled rules ──────────────────────────────────────────────────────────────────────────────────────
 disabled_rules:
   - todo          # TODOs are acceptable during active development
   - trailing_comma  # SwiftPM/Xcode auto-formatter conflicts with this

Sources/RunnerBar/ActionDetailView.swift

@@ -7,16 +7,24 @@ import SwiftUI
 // ═══════════════════════════════════════════════════════════════════════════════
 //
 // ── FRAME CONTRACT ──────────────────────────────────────────────────────────────────────────────────────
-//   Receives the same FIXED frame from AppDelegate as JobDetailView.
-//   Sized once at openPopover() from mainView()'s fittingSize; never changes.
-//   ScrollView absorbs overflow — do NOT fight the frame.
+//   Architecture 1: sizingOptions = .preferredContentSize.
+//   Root: .frame(maxWidth: .infinity, alignment: .top) — NO maxHeight: .infinity
+//   ScrollView: .frame(maxHeight: 75% of visible screen) — REQUIRED to prevent side-jump (#370)
+//
+// ── WHY THE ScrollView CAP IS REQUIRED ──────────────────────────────────────────────────────────────────
+//   Without .frame(maxHeight:), ScrollView reports its full content height as ideal height.
+//   NSHostingController publishes this as preferredContentSize.height.
+//   NSPopover re-anchors on any contentSize change → side-jump on every navigation.
+//   The cap makes preferredContentSize.height predictable and stable.
 //
 // ── LAYOUT RULES ────────────────────────────────────────────────────────────────────────────────────────
-//   ✔ Root: .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
+//   ✔ Root: .frame(maxWidth: .infinity, alignment: .top) — NO maxHeight: .infinity
+//   ✔ ScrollView: .frame(maxHeight: NSScreen.main.map { $0.visibleFrame.height * 0.75 } ?? 600)
 //   ✔ Job list MUST be inside ScrollView
 //   ✔ Header (back button + title + Divider) MUST be OUTSIDE ScrollView
 //   ❌ NEVER put header inside ScrollView
 //   ❌ NEVER add .idealWidth or .frame(height:) to root
+//   ❌ NEVER remove the .frame(maxHeight:) from ScrollView — side-jump regression #370
 //   ❌ NEVER call navigate() directly — use onBack / onSelectJob callbacks
 // ═══════════════════════════════════════════════════════════════════════════════
 
@@ -124,6 +132,9 @@ struct ActionDetailView: View {
             Divider()
 
             // ── Jobs list: INSIDE ScrollView
+            // ⚠️ .frame(maxHeight:) is REQUIRED — do NOT remove.
+            // Without it, ScrollView reports full content height as ideal height,
+            // causing preferredContentSize.height to spike → NSPopover side-jump (#370).
             ScrollView(.vertical, showsIndicators: true) {
                 VStack(alignment: .leading, spacing: 0) {
                     if group.jobs.isEmpty {
@@ -136,9 +147,12 @@ struct ActionDetailView: View {
                         ForEach(group.jobs) { job in
                             Button(action: { onSelectJob(job) }, label: {
                                 HStack(spacing: 8) {
-                                    Circle()
-                                        .fill(jobDotColor(for: job))
-                                        .frame(width: 7, height: 7)
+                                    // ⚠️ PieProgressView — not plain Circle().
+                                    PieProgressView(
+                                        progress: job.progressFraction,
+                                        color: jobDotColor(for: job),
+                                        size: 7
+                                    )
                                     Text(job.name)
                                         .font(.system(size: 12))
                                         .foregroundColor(job.isDimmed ? .secondary : .primary)
@@ -174,8 +188,13 @@ struct ActionDetailView: View {
                 }
                 .frame(maxWidth: .infinity, alignment: .leading)
             }
+            // ⚠️ REQUIRED — caps preferredContentSize.height under Architecture 1.
+            // Prevents NSPopover side-jump on navigation (#370).
+            // ❌ NEVER remove this modifier.
+            .frame(maxHeight: NSScreen.main.map { $0.visibleFrame.height * 0.75 } ?? 600)
         }
-        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
+        // ⚠️ NO maxHeight: .infinity — height is driven by preferredContentSize via sizingOptions
+        .frame(maxWidth: .infinity, alignment: .top)
         .onAppear {
             tickTimer?.invalidate()
             tickTimer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in tick += 1 }
@@ -191,20 +210,33 @@ struct ActionDetailView: View {
     // MARK: - Job row helpers
 
     private func jobDotColor(for job: ActiveJob) -> Color {
-        if job.isDimmed { return .secondary }
-        return job.status == "in_progress" ? .yellow : .gray
+        switch job.status {
+        case "in_progress": return .yellow
+        case "queued":      return group.groupStatus == .inProgress ? .yellow : .blue
+        default:
+            if job.isDimmed { return .gray }
+            return job.conclusion == "success" ? .green : .red
+        }
     }
 
+    /// Returns the status label for a job without a conclusion.
+    /// Per spec #178: queued jobs inside an in-progress group show "In Progress"
+    /// because they are part of an active workflow run.
     private func jobStatusLabel(for job: ActiveJob) -> String {
         switch job.status {
         case "in_progress": return "In Progress"
-        case "queued":      return "Queued"
-        default:            return "Pending"
+        case "queued":
+            return group.groupStatus == .inProgress ? "In Progress" : "Queued"
+        default: return "Pending"
         }
     }
 
     private func jobStatusColor(for job: ActiveJob) -> Color {
-        job.status == "in_progress" ? .yellow : .secondary
+        switch job.status {
+        case "in_progress": return .yellow
+        case "queued":      return group.groupStatus == .inProgress ? .yellow : .secondary
+        default:            return .secondary
+        }
     }
 
     private func conclusionLabel(_ c: String) -> String {

Sources/RunnerBar/ActionGroup.swift

@@ -1,5 +1,5 @@
 import Foundation
-// swiftlint:disable opening_brace identifier_name missing_docs orphaned_doc_comment
+// swiftlint:disable opening_brace identifier_name orphaned_doc_comment missing_docs
 
 // MARK: - GroupStatus
 
@@ -20,10 +20,15 @@ enum GroupStatus {
 /// Holds only the data needed for display and job fetching — deliberately
 /// minimal so the full job list lives on the parent ActionGroup instead.
 struct WorkflowRunRef: Identifiable {
+    /// Unique GitHub run identifier.
     let id: Int
-    let name: String         // workflow file name, e.g. "SonarQube", "vitest"
+    /// Workflow file name, e.g. "SonarQube", "vitest".
+    let name: String
+    /// Current run status: `queued`, `in_progress`, or `completed`.
     let status: String
+    /// Final outcome when status is `completed`.
     let conclusion: String?
+    /// URL to the run's page on github.com.
     let htmlUrl: String?
 }
 
@@ -36,7 +41,7 @@ struct WorkflowRunRef: Identifiable {
 /// Hierarchy: ActionGroup → jobs (flat across all sibling runs) → JobStep → log.
 /// `ActionDetailView` drills into the flat job list; `JobDetailView`/`StepLogView`
 /// are reused unchanged below that.
-struct ActionGroup: Identifiable {
+struct ActionGroup: Identifiable, Equatable {
     let headSha: String         // head_sha — kept as the underlying group identity
     let label: String           // "#1270" if PR, else "d6281b" (sha[:7])
     let title: String           // commit/PR message first line (≤40 chars)
@@ -58,6 +63,7 @@ struct ActionGroup: Identifiable {
     /// Timestamps derived from job data, not run-level API fields.
     /// Mirrors ci-dash.py's `first_job_started_at` / `last_job_completed_at`.
     var firstJobStartedAt: Date?
+    /// Last job completion time across all runs in this group.
     var lastJobCompletedAt: Date?
 
     /// Fallback creation time from the representative run.
@@ -116,77 +122,57 @@ struct ActionGroup: Identifiable {
 
     /// Name of the first in-progress job, or first queued, or "—".
     var currentJobName: String {
-        if let j = jobs.first(where: { $0.status == "in_progress" }) { return j.name }
-        if let j = jobs.first(where: { $0.status == "queued" })      { return j.name }
+        if let job = jobs.first(where: { $0.status == "in_progress" }) { return job.name }
+        if let job = jobs.first(where: { $0.status == "queued" })      { return job.name }
         return "—"
     }
 
+    /// How long ago the group started, as a short human string, e.g. "3m ago", "1h ago".
+    /// Uses `firstJobStartedAt` when available, falls back to `createdAt`.
+    /// Returns "—" if neither timestamp is available.
+    /// Delegates to `RelativeTimeFormatter` for testable, injectable formatting.
+    var startedAgo: String {
+        guard let ref = firstJobStartedAt ?? createdAt else { return "—" }
+        return RelativeTimeFormatter.string(from: ref)
+    }
+
     /// Elapsed time derived from min(job.startedAt) → max(job.completedAt).
     var elapsed: String {
         if let start = firstJobStartedAt {
             let end = lastJobCompletedAt ?? Date()
             let sec = Int(end.timeIntervalSince(start))
             guard sec >= 0 else { return "00:00" }
-            let m = sec / 60; let s = sec % 60
-            return String(format: "%02d:%02d", m, s)
+            let minutes = sec / 60; let seconds = sec % 60
+            return String(format: "%02d:%02d", minutes, seconds)
         }
         guard let start = createdAt else { return "00:00" }
         let sec = Int(Date().timeIntervalSince(start))
         guard sec >= 0 else { return "00:00" }
-        let m = sec / 60; let s = sec % 60
-        return String(format: "%02d:%02d", m, s)
+        let minutes = sec / 60; let seconds = sec % 60
+        return String(format: "%02d:%02d", minutes, seconds)
     }
-}
-
-// MARK: - Codable helpers (private to this file)
 
-private struct ActionRunsResponse: Codable {
-    let workflowRuns: [RunPayload]
-    enum CodingKeys: String, CodingKey { case workflowRuns = "workflow_runs" }
-}
-
-private struct RunPayload: Codable {
-    let id: Int
-    let name: String
-    let status: String
-    let conclusion: String?
-    let headBranch: String?
-    let headSha: String
-    let displayTitle: String?
-    let createdAt: String?
-    let updatedAt: String?
-    let htmlUrl: String?
-    let headCommit: HeadCommit?
-    let pullRequests: [PRRef]?
-
-    enum CodingKeys: String, CodingKey {
-        case id, name, status, conclusion
-        case headBranch = "head_branch"
-        case headSha = "head_sha"
-        case displayTitle = "display_title"
-        case createdAt = "created_at"
-        case updatedAt = "updated_at"
-        case htmlUrl = "html_url"
-        case headCommit = "head_commit"
-        case pullRequests = "pull_requests"
+    // MARK: - Progress fraction (model layer — keeps view bodies clean)
+
+    /// Completion fraction 0.0–1.0 for the pie-progress dot, or `nil` (indeterminate)
+    /// when status is queued or no job data is available.
+    ///
+    /// - `nil`  → indeterminate (queued / no jobs loaded yet)
+    /// - `1.0`  → completed
+    /// - `0..<1` → partial (jobsDone / jobsTotal)
+    var progressFraction: Double? {
+        switch groupStatus {
+        case .queued:    return nil
+        case .completed: return 1.0
+        case .inProgress:
+            guard jobsTotal > 0 else { return nil }
+            return Double(jobsDone) / Double(jobsTotal)
+        }
     }
-}
-
-private struct HeadCommit: Codable { let message: String }
-private struct PRRef: Codable { let number: Int }
-
-// MARK: - PR label
 
-/// Derives the short identifier for an action group row.
-/// Priority: PR number → branch-embedded number → sha[:7].
-private func prLabel(from run: RunPayload) -> String {
-    if let pr = run.pullRequests?.first { return "#\(pr.number)" }
-    if let branch = run.headBranch,
-       let range = branch.range(of: #"/(\d+)/"#, options: .regularExpression) {
-        let digits = branch[range].filter { $0.isNumber }
-        return "#\(digits)"
+    static func == (lhs: ActionGroup, rhs: ActionGroup) -> Bool {
+        lhs.id == rhs.id && lhs.isDimmed == rhs.isDimmed && lhs.jobs == rhs.jobs && lhs.runs.map({ $0.id }) == rhs.runs.map({ $0.id })
     }
-    return String(run.headSha.prefix(7))
 }
 
 // MARK: - Fetch + Group
@@ -299,27 +285,27 @@ func fetchActionGroups(for scope: String, cache: [String: ActionGroup] = [:]) ->
 // MARK: - Private helpers
 
 /// Constructs an `ActiveJob` from a decoded `JobPayload`.
-func makeActiveJob(from j: JobPayload, iso: ISO8601DateFormatter,
+func makeActiveJob(from payload: JobPayload, iso: ISO8601DateFormatter,
                    isDimmed: Bool = false) -> ActiveJob {
-    let steps: [JobStep] = (j.steps ?? []).enumerated().map { idx, s in
+    let steps: [JobStep] = (payload.steps ?? []).enumerated().map { idx, step in
         JobStep(
             id: idx + 1,
-            name: s.name,
-            status: s.status,
-            conclusion: s.conclusion,
-            startedAt: s.startedAt.flatMap { iso.date(from: $0) },
-            completedAt: s.completedAt.flatMap { iso.date(from: $0) }
+            name: step.name,
+            status: step.status,
+            conclusion: step.conclusion,
+            startedAt: step.startedAt,
+            completedAt: step.completedAt
         )
     }
     return ActiveJob(
-        id: j.id,
-        name: j.name,
-        status: j.status,
-        conclusion: j.conclusion,
-        startedAt: j.startedAt.flatMap { iso.date(from: $0) },
-        createdAt: j.createdAt.flatMap { iso.date(from: $0) },
-        completedAt: j.completedAt.flatMap { iso.date(from: $0) },
-        htmlUrl: j.htmlUrl,
+        id: payload.id,
+        name: payload.name,
+        status: payload.status,
+        conclusion: payload.conclusion,
+        startedAt: payload.startedAt.flatMap { iso.date(from: $0) },
+        createdAt: payload.createdAt.flatMap { iso.date(from: $0) },
+        completedAt: payload.completedAt.flatMap { iso.date(from: $0) },
+        htmlUrl: payload.htmlUrl,
         isDimmed: isDimmed,
         steps: steps
     )
@@ -381,4 +367,4 @@ private func statusPriority(_ status: GroupStatus) -> Int {
     case .completed:  return 2
     }
 }
-// swiftlint:enable opening_brace identifier_name missing_docs orphaned_doc_comment
+// swiftlint:enable opening_brace identifier_name orphaned_doc_comment missing_docs