From 1622531a85ccf06237a277a78e13c7818aaef8cb Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:06:07 -0700
Subject: [PATCH] feat(status-bar): add tooltips explaining Detailed vs Compact
 usage modes

The Detailed/Compact density picker in the usage popover named both modes
but didn't explain what they change. Add hover tooltips via a new optional
`tooltip` field on SettingsSegmentedControl's options (no behavior change
for existing segmented controls).
---
 .../components/settings/SettingsFormControls.tsx   | 14 +++++++++++++-
 .../src/components/status-bar/UsageRosterPanel.tsx | 12 ++++++++++--
 src/renderer/src/i18n/locales/en.json              |  2 ++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/renderer/src/components/settings/SettingsFormControls.tsx b/src/renderer/src/components/settings/SettingsFormControls.tsx
index 7c55b38899c..a05146f51f0 100644
--- a/src/renderer/src/components/settings/SettingsFormControls.tsx
+++ b/src/renderer/src/components/settings/SettingsFormControls.tsx
@@ -7,6 +7,7 @@ import { ScrollArea } from '../ui/scroll-area'
 import { Input } from '../ui/input'
 import { Label } from '../ui/label'
 import { Popover, PopoverAnchor, PopoverContent } from '../ui/popover'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
 import { Check, ChevronsUpDown, CircleX } from 'lucide-react'
 import { normalizeColor, type TerminalThemeOption } from '@/lib/terminal-theme'
 import { MAX_THEME_RESULTS } from './SettingsConstants'
@@ -138,6 +139,8 @@ type SegmentedOption<T extends string | number> = {
   label: React.ReactNode
   disabled?: boolean
   ariaLabel?: string
+  /** Optional hover label describing what the option does. */
+  tooltip?: React.ReactNode
 }
 
 type SettingsSegmentedControlProps<T extends string | number> = {
@@ -169,7 +172,7 @@ export function SettingsSegmentedControl<T extends string | number>({
     >
       {options.map((opt) => {
         const active = opt.value === value
-        return (
+        const button = (
           <button
             key={String(opt.value)}
             type="button"
@@ -196,6 +199,15 @@ export function SettingsSegmentedControl<T extends string | number>({
             {opt.label}
           </button>
         )
+        if (opt.tooltip == null) {
+          return button
+        }
+        return (
+          <Tooltip key={String(opt.value)}>
+            <TooltipTrigger asChild>{button}</TooltipTrigger>
+            <TooltipContent>{opt.tooltip}</TooltipContent>
+          </Tooltip>
+        )
       })}
     </div>
   )
diff --git a/src/renderer/src/components/status-bar/UsageRosterPanel.tsx b/src/renderer/src/components/status-bar/UsageRosterPanel.tsx
index fa11825d140..25e4394a4d3 100644
--- a/src/renderer/src/components/status-bar/UsageRosterPanel.tsx
+++ b/src/renderer/src/components/status-bar/UsageRosterPanel.tsx
@@ -236,11 +236,19 @@ export function UsageRosterPanel({
           options={[
             {
               value: 'verbose',
-              label: translate('auto.components.status.bar.UsageRosterPanel.detailed', 'Detailed')
+              label: translate('auto.components.status.bar.UsageRosterPanel.detailed', 'Detailed'),
+              tooltip: translate(
+                'auto.components.status.bar.UsageRosterPanel.detailedTooltip',
+                'Full usage with bars, labels, and percentages in the status bar'
+              )
             },
             {
               value: 'compact',
-              label: translate('auto.components.status.bar.UsageRosterPanel.compact', 'Compact')
+              label: translate('auto.components.status.bar.UsageRosterPanel.compact', 'Compact'),
+              tooltip: translate(
+                'auto.components.status.bar.UsageRosterPanel.compactTooltip',
+                'Condensed usage — just the tightest window'
+              )
             }
           ]}
         />
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 95a9c72f64c..933ce4b36a7 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -3310,6 +3310,8 @@
             "noUsageData": "No usage data",
             "detailed": "Detailed",
             "compact": "Compact",
+            "detailedTooltip": "Full usage with bars, labels, and percentages in the status bar",
+            "compactTooltip": "Condensed usage — just the tightest window",
             "footerDetailAria": "Usage footer detail"
           }
         }