Custom update notifications in SwiftUI

1. TL;DR

• Add a single compact “Update badge” SwiftUI accessory in the window titlebar (top-right) via NSTitlebarAccessoryViewController. It shows an icon/progress ring and opens a small popover for details/actions.
• Map all SPUUserDriver states to unobtrusive icon/pill variants; keep text out of the titlebar and put details in the popover. Reuse the reset-zoom accessory pattern (padding, layout, tab-bar workaround).

1. Recommended approach (simple path)
   A) SwiftUI views to create

• UpdateAccessoryView: The titlebar-hosted, ultra-compact badge view (22×22 target hit-area), with subtle background only when needed. Contains:
  • BadgeButton (icon-only; toggles popover)
  • InlineProgressRing (when progress states)
  • Optional mini-pill for “Install” when ready
  • Tooltip for all states
  • .popover for details and actionable controls
• UpdatePopoverView: Popover content; a small, focused panel that varies by state, with actions wired via closures to be implemented later by SPUUserDriver integration.
• Reusable small components:
  • ProgressRingView: Circular progress (0–1) with subtle animation
  • UpdatePill: Minimal pill with icon + short label (e.g., “Install”)
  • ErrorInlineView: Warning icon + short message line (used in popover)
  • ReleaseNotesPreview (optional): Simple text view area; initially a placeholder with “View release notes…” action

B) Titlebar appearance and UX

• Titlebar badge (top-right):
  • Default hidden (idle)
  • 22×22 icon button with .plain style; accent-colored glyph for high-signal states (update available, error); neutral/secondary color for passive states (checking)
  • Small circular progress ring replaces the icon (or overlays it) for downloading/extracting
  • When “Ready to install,” the badge shows a checkmark or arrow.triangle.2.circlepath.circle with a short “Install” pill on hover, else icon-only to stay unobtrusive
  • Tooltip reflects current state: “Checking for updates…”, “Update available”, “Downloading 42%…”, “Ready to install”, “Update failed”, etc.
  • On click, popover anchored to the badge; popover includes readable text and all actions
• Popover content (by state):
  • Permission request: Title “Enable automatic updates?” with “Allow” / “Not now,” plus small help text
  • User-initiated check: “Checking for updates…” with activity indicator and “Cancel”
  • Update found: Version info, “Install”, “Skip this version”, “Remind me later”, “Release notes…”
  • Download progress: Progress bar with percent, “Pause/Resume” (if you intend to support later) or “Cancel”
  • Extraction progress: Progress bar and message “Preparing…”
  • Ready to install: “Install and Relaunch” primary, “Later” secondary
  • Installing: Activity indicator + “Installing…”
  • Errors: brief message and “Retry”, plus “Details…” if needed
• Visuals/spacing:
  • Match ResetZoomAccessoryView padding strategy:
    • .padding(.top, hasToolbar ? 9–10 : 4–5) depending on OS
    • .padding(.trailing, 10)
  • Keep pill text minimal; most details live in the popover

C) State management (view model)

• Define a single ObservableObject used by the accessory:
  • class UpdateUIModel: ObservableObject
    • @Published var state: UpdateUIState
    • @Published var progress: Double? (0…1) // used in download/extract/check
    • @Published var details: UpdateDetails? // version, notes summary, etc.
    • @Published var error: UpdateErrorInfo? // message, code
  • enum UpdateUIState {
    case idle
    case permissionRequest
    case checking // user-initiated check
    case updateAvailable
    case downloading
    case extracting
    case readyToInstall
    case installing
    case notFound // “No updates found”
    case error
    }
  • struct UpdateDetails { version: String, build: String?, size: String?, date: Date?, notesSummary: String? }
  • struct UpdateErrorInfo { title: String, message: String }
• Actions protocol (closures injected; SPUUserDriver will implement later):
  • struct UpdateUIActions {
    let allowAutoChecks: () -> Void
    let denyAutoChecks: () -> Void
    let cancel: () -> Void
    let install: () -> Void
    let remindLater: () -> Void
    let skipThisVersion: () -> Void
    let showReleaseNotes: () -> Void
    let retry: () -> Void
    }
• The SwiftUI views never talk to Sparkle directly; they only mutate via UpdateUIModel and call actions

D) Integration with NSTitlebarAccessoryViewController

• In TerminalWindow:
  • Add a property: private let updateAccessory = NSTitlebarAccessoryViewController()
  • Add a window-scoped UpdateUIModel (similar to existing ViewModel storage)
  • In awakeFromNib (after styleMask.contains(.titled)):
    • updateAccessory.layoutAttribute = .right
    • updateAccessory.view = NSHostingView(rootView:
      UpdateAccessoryView(
      hasToolbar: viewModel.$hasToolbar,
      model: updateUIModel,
      actions: injectedActions // placeholder now
      )
      )
    • addTitlebarAccessoryViewController(updateAccessory)
    • updateAccessory.view.translatesAutoresizingMaskIntoConstraints = false
  • Respect the existing tab bar workaround:
    • On tabBarDidAppear: remove the SwiftUI accessory (same as reset zoom) to avoid the scaling bug
    • On tabBarDidDisappear: re-add it if missing
  • Ordering with reset zoom:
    • Use insertTitlebarAccessoryViewController(_:at:) to keep update badge as the right-most item; ensure consistent index relative to resetZoomAccessory
• Fullscreen and toolbar presence:
  • Share the same hasToolbar signal to align padding with ResetZoomAccessoryView

E) Animations/transitions (unobtrusive)

• Badge enters/exits with .opacity + slight .scale (0.95→1.0) over 0.15–0.2s
• Progress rings animate changes with .easeInOut(duration: 0.2)
• When update becomes available, do a single gentle pulse of the badge (e.g., opacity 0.8→1.0) to draw attention once, then remain steady
• Popover appears with default system animation; keep it small and focused

F) Example skeleton (minimal)

• enum UpdateUIState { … } and UpdateUIModel as above
• UpdateAccessoryView:
  • Takes hasToolbar: Binding, model: ObservedObject, actions: UpdateUIActions
  • Computes top padding as in ResetZoomAccessoryView
  • Renders:
    • if model.state == .idle: EmptyView()
    • else: VStack { BadgeButton or ProgressRingView; Spacer() }
      .padding(.top, topPadding)
      .padding(.trailing, 10)
      .popover(isPresented: $showPopover) { UpdatePopoverView(model: model, actions: actions) }
• ProgressRingView:
  • ZStack { Circle trimmed according to progress; background circle; overlay icon when appropriate }
• UpdatePopoverView:
  • Switch on model.state and render small controls; buttons just call actions.* closures

G) Mapping SPUUserDriver states → UI states

• Permission request → .permissionRequest (badge with questionmark.circle; popover asks “Enable automatic updates?”)
• User-initiated check (with progress) → .checking (spinner in badge; cancel in popover)
• Update found → .updateAvailable (badge with arrow.down.circle.fill; popover with Install/Skip/Remind/Notes)
• Download progress → .downloading(progress)
• Extraction progress → .extracting(progress)
• Ready to install → .readyToInstall (badge shows checkmark/“Install” pill; one-click installs; popover offers Later)
• Installing → .installing (spinner; disabled actions)
• Errors / not found → .error or .notFound (warning or info icon; popover shows message and Retry/OK)

Effort/scope

• S (0.5–1h): Define state model, actions protocol, and the basic UpdateAccessoryView + popover placeholders
• M (1–3h): Implement compact badge UI, progress ring, icons, popover skeletons per state
• L (1–2d): Polish visuals, accessibility, refine states, QA across toolbar/no-toolbar, fullscreen, and tabbed windows

1. Rationale and trade-offs

• Single compact badge keeps the titlebar clean and unobtrusive while still discoverable; details live in a popover to preserve space.
• Reusing NSTitlebarAccessoryViewController + NSHostingView mirrors the existing reset-zoom pattern, minimizing new infra and reducing risk.
• A single model + enum keeps logic simple and testable; wiring to SPUUserDriver later is straightforward via closures.

Alternative (only if needed)

• If you must show update UI while the tab bar is visible (where SwiftUI accessories cause scaling issues), replace the titlebar accessory with a lightweight NSView-based accessory for that condition only, or place a minimal AppKit button in tab.accessoryView. This deviates from the “SwiftUI-only” ask, so treat it as a fallback.

1. Risks and guardrails

• Known SwiftUI accessory + tab bar scaling bug: we will hide the accessory when the tab bar is visible (matching ResetZoom). Guardrail: keep menu- and command-initiated update flows functional; consider a transient NSAlert for critical errors if the badge is hidden.
• Touch targets: ensure 22×22 minimum; test on different titlebar heights with and without toolbars.
• Fullscreen/toolbar layout differences: use the existing hasToolbar signal to align correctly.
• Popover anchoring in titlebar: test in light/dark modes and different window sizes; ensure it doesn’t cover traffic lights.

1. When to consider the advanced path

• You need the badge visible even when a tab bar is present (user may miss notifications).
• You want richer content (inline release notes, longer text) in the titlebar itself.
• You need cross-window coordination (global update state across multiple windows).

1. Optional advanced path (brief)

• Build an UpdateUIHost that renders:
  • Titlebar SwiftUI accessory when no tab bar is present
  • AppKit NSView accessory (or tab.accessoryView item) when tab bar is present
  • A fallback floating HUD anchored to NSTitlebarView for critical states
• Add a shared UpdateCenter (singleton ObservableObject) to synchronize state across windows; each window hosts a small proxy model derived from the shared state.