feat: Centralize percentage formatting with smart truncation for large delta values across all dashboard components

aree6 · aree6 · commit 17224c605a03 · 2026-01-03T11:53:10.000+08:00
diff --git a/frontend/DELTA_FORMATTING_REFERENCE.md b/frontend/DELTA_FORMATTING_REFERENCE.md
@@ -0,0 +1,36 @@
+# Delta Percentage Formatting Reference
+
+## Logic Explanation
+
+The "x" format represents **total performance multiplier**, not the increase amount.
+
+**Formula**: `Total Multiplier = 1 + (Percentage Increase / 100)`
+
+## Conversion Table
+
+| Percentage Increase | Total Performance | Display Format |
+|-------------------|-------------------|----------------|
+| 0% increase | 1.0x baseline | 0% (below threshold) |
+| 50% increase | 1.5x baseline | 50% (below threshold) |
+| 100% increase | 2.0x baseline | 100% (below threshold) |
+| 149% increase | 2.49x baseline | 149% (below threshold) |
+| **150% increase** | **2.5x baseline** | **2.5x** ✨ |
+| 175% increase | 2.75x baseline | 2.8x ✨ |
+| **200% increase** | **3.0x baseline** | **3x** ✨ |
+| 250% increase | 3.5x baseline | 3.5x ✨ |
+| **300% increase** | **4.0x baseline** | **4x** ✨ |
+
+## Key Points
+
+- **< 150%**: Shows as regular percentage (e.g., "100%", "125%")
+- **≥ 150%**: Shows as total multiplier (e.g., "2.5x", "3x")
+- **Units always present**: Either "%" or "x"
+- **Logic**: "x" = baseline (1x) + increase (percentage/100)
+
+## Examples
+
+- **100% increase** → Performance doubled → **2x total**
+- **200% increase** → Performance tripled → **3x total**  
+- **300% increase** → Performance quadrupled → **4x total**
+
+This makes the "x" format intuitive: it directly tells you how many times better the performance is compared to baseline.
diff --git a/frontend/components/HistoryView.tsx b/frontend/components/HistoryView.tsx
@@ -24,6 +24,7 @@ import { WeightUnit } from '../utils/storage/localStorage';
 import { convertWeight } from '../utils/format/units';
 import { formatSignedNumber } from '../utils/format/formatters';
 import { formatDisplayVolume } from '../utils/format/volumeDisplay';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../utils/format/deltaFormat';
 import { formatRelativeWithDate, getEffectiveNowFromWorkoutData, getSessionKey } from '../utils/date/dateUtils';
 import { parseHevyDateString } from '../utils/date/parseHevyDateString';
 import { LazyRender } from './LazyRender';
@@ -64,15 +65,18 @@ const SessionDeltaBadge: React.FC<{ current: number; previous: number; suffix?:
   const isPositive = delta > 0;
   const Icon = isPositive ? TrendingUp : TrendingDown;
   const colorClass = isPositive ? 'text-emerald-400' : 'text-rose-400';
-  const pct = Math.round((delta / previous) * 100);
+  const deltaPercent = Math.round((delta / previous) * 100);
+  
+  // Use centralized formatting for better UX with large percentages
+  const formattedPercent = formatDeltaPercentage(deltaPercent, getDeltaFormatPreset('badge'));
   
   return (
     <span
       className={`relative -top-[2px] inline-flex items-center gap-0.5 ml-1 text-[10px] font-bold leading-none ${colorClass}`}
-      title={`${pct}% ${label} ${context}`}
+      title={`${deltaPercent}% ${label} ${context}`}
     >
       <Icon className={`w-3 h-3 ${colorClass}`} />
-      <span>{pct}%</span>
+      <span>{formattedPercent}</span>
     </span>
   );
 };
diff --git a/frontend/components/InsightCards.tsx b/frontend/components/InsightCards.tsx
@@ -17,6 +17,7 @@ import { WeightUnit } from '../utils/storage/localStorage';
 import { convertWeight } from '../utils/format/units';
 import { formatHumanReadableDate } from '../utils/date/dateUtils';
 import { formatNumber } from '../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../utils/format/deltaFormat';
 
 // Simple monochrome SVG for Gemini (Google) that inherits color via currentColor
 const GeminiIcon: React.FC<{ className?: string }> = ({ className }) => (
@@ -102,15 +103,15 @@ const DeltaBadge: React.FC<{ delta: DeltaResult; suffix?: string; showPercent?:
   showPercent = true,
   context = ''
 }) => {
-  const { direction, deltaPercent } = delta;
+  const { direction, formattedPercent } = delta;
   
   if (direction === 'same') {
     return (
       <span className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded bg-slate-500/10 text-slate-400">
         <Minus className="w-3 h-3" />
         <span className="text-[10px] font-bold">
           Stable
-          {showPercent ? ` (${deltaPercent}%)` : ''}
+          {showPercent ? ` (${delta.deltaPercent}%)` : ''}
         </span>
         {context && <span className="text-[9px] opacity-75">{context}</span>}
       </span>
@@ -126,8 +127,7 @@ const DeltaBadge: React.FC<{ delta: DeltaResult; suffix?: string; showPercent?:
     <span className={`inline-flex items-center gap-1 px-1.5 py-0.5 rounded ${bgClass} ${colorClass}`}>
       <Icon className="w-3 h-3" />
       <span className="text-[10px] font-bold">
-        {isUp ? '+' : ''}
-        {showPercent ? `${deltaPercent}%` : formatNumber(delta.delta, { maxDecimals: 2 })}
+        {formattedPercent}
         {suffix}
       </span>
       {context && <span className="text-[9px] opacity-75">{context}</span>}
diff --git a/frontend/components/MuscleAnalysis.tsx b/frontend/components/MuscleAnalysis.tsx
@@ -28,6 +28,7 @@ import {
 import { TrendingUp, TrendingDown, Dumbbell, X, Activity, Layers, PersonStanding, BicepsFlexed } from 'lucide-react';
 import { normalizeMuscleGroup, type NormalizedMuscleGroup } from '../utils/muscle/muscleNormalization';
 import { LazyRender } from './LazyRender';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../utils/format/deltaFormat';
 import { ChartSkeleton } from './ChartSkeleton';
 import { Tooltip as HoverTooltip, TooltipData } from './Tooltip';
 import { CHART_TOOLTIP_STYLE } from '../utils/ui/uiConstants';
@@ -493,11 +494,15 @@ export const MuscleAnalysis: React.FC<MuscleAnalysisProps> = ({ data, filtersSlo
     const delta = Number((current - previous).toFixed(1));
     const deltaPercent = Math.round((delta / previous) * 100);
     
+    // Use centralized formatting for better UX with large percentages
+    const formattedPercent = formatDeltaPercentage(deltaPercent, getDeltaFormatPreset('badge'));
+    
     return {
       current,
       previous,
       delta,
       deltaPercent,
+      formattedPercent,
       direction: delta > 0 ? 'up' : delta < 0 ? 'down' : 'same' as 'up' | 'down' | 'same',
     };
   }, [trendData]);
@@ -851,7 +856,7 @@ export const MuscleAnalysis: React.FC<MuscleAnalysisProps> = ({ data, filtersSlo
                     : 'bg-rose-500/10 text-rose-400'
                 }`}>
                   {volumeDelta.direction === 'up' ? <TrendingUp className="w-3 h-3" /> : <TrendingDown className="w-3 h-3" />}
-                  {volumeDelta.direction === 'up' ? '+' : ''}{volumeDelta.deltaPercent}% vs prev {trendPeriod === 'weekly' ? 'wk' : trendPeriod === 'monthly' ? 'mo' : 'day'}
+                  {volumeDelta.formattedPercent} vs prev {trendPeriod === 'weekly' ? 'wk' : trendPeriod === 'monthly' ? 'mo' : 'day'}
                 </span>
               )}
             </div>
diff --git a/frontend/components/dashboard/IntensityEvolutionCard.tsx b/frontend/components/dashboard/IntensityEvolutionCard.tsx
@@ -26,6 +26,7 @@ import {
 import { LazyRender } from '../LazyRender';
 import { ChartSkeleton } from '../ChartSkeleton';
 import { formatNumber, formatSignedNumber } from '../../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../../utils/format/deltaFormat';
 import { addEmaSeries, DEFAULT_EMA_HALF_LIFE_DAYS } from '../../utils/analysis/ema';
 
 type IntensityView = 'area' | 'stackedBar';
@@ -266,11 +267,11 @@ export const IntensityEvolutionCard = ({
                     key={s.short}
                     label={
                       <BadgeLabel
-                        main={`${s.short} ${s.pct.toFixed(0)}%`}
+                        main={`${s.short} ${formatDeltaPercentage(s.pct, getDeltaFormatPreset('badge'))}`}
                         meta={
                           <ShiftedMeta>
                             <TrendIcon direction={s.delta.direction} />
-                            <span>{`${formatSigned(s.delta.deltaPercent)}% vs prev mo`}</span>
+                            <span>{formatDeltaPercentage(s.delta.deltaPercent, getDeltaFormatPreset('badge'))} vs prev mo</span>
                           </ShiftedMeta>
                         }
                       />
diff --git a/frontend/components/dashboard/MuscleTrendCard.tsx b/frontend/components/dashboard/MuscleTrendCard.tsx
@@ -17,6 +17,7 @@ import { ChartSkeleton } from '../ChartSkeleton';
 import { normalizeMuscleGroup } from '../../utils/muscle/muscleNormalization';
 import { MUSCLE_COLORS } from '../../utils/domain/categories';
 import { formatSignedNumber } from '../../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../../utils/format/deltaFormat';
 import {
   BadgeLabel,
   ChartDescription,
@@ -39,7 +40,7 @@ type MuscleTrendInsight = {
 
 const formatSigned = (n: number) => formatSignedNumber(n, { maxDecimals: 2 });
 const formatSignedPctWithNoun = (pct: number, noun: string) =>
-  `${formatSignedNumber(pct, { maxDecimals: 0 })}% ${noun}`;
+  `${formatDeltaPercentage(pct, getDeltaFormatPreset('badge'))} ${noun}`;
 
 export const MuscleTrendCard = ({
   isMounted,
diff --git a/frontend/components/dashboard/PrTrendCard.tsx b/frontend/components/dashboard/PrTrendCard.tsx
@@ -13,6 +13,7 @@ import {
 } from 'recharts';
 import type { TimeFilterMode } from '../../utils/storage/localStorage';
 import { formatSignedNumber } from '../../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../../utils/format/deltaFormat';
 import { addEmaSeries, DEFAULT_EMA_HALF_LIFE_DAYS } from '../../utils/analysis/ema';
 import {
   BadgeLabel,
@@ -188,7 +189,7 @@ export const PrTrendCard = ({
                   main={
                     <span className="inline-flex items-center gap-1">
                       <TrendIcon direction={prTrendDelta.direction} />
-                      <span>{`${formatSigned(prTrendDelta.deltaPercent)}%`}</span>
+                      <span>{formatDeltaPercentage(prTrendDelta.deltaPercent, getDeltaFormatPreset('badge'))}</span>
                     </span>
                   }
                   meta="vs prev mo"
@@ -207,7 +208,7 @@ export const PrTrendCard = ({
                   main={
                     <span className="inline-flex items-center gap-1">
                       <TrendIcon direction={prTrendDelta7d.direction} />
-                      <span>{`${formatSigned(prTrendDelta7d.deltaPercent)}%`}</span>
+                      <span>{formatDeltaPercentage(prTrendDelta7d.deltaPercent, getDeltaFormatPreset('badge'))}</span>
                     </span>
                   }
                   meta="vs prev 7d"
diff --git a/frontend/components/dashboard/TopExercisesCard.tsx b/frontend/components/dashboard/TopExercisesCard.tsx
@@ -12,6 +12,7 @@ import {
 } from 'recharts';
 import type { ExerciseAsset } from '../../utils/data/exerciseAssets';
 import { formatSignedNumber } from '../../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../../utils/format/deltaFormat';
 import { LazyRender } from '../LazyRender';
 import { ChartSkeleton } from '../ChartSkeleton';
 import {
@@ -68,7 +69,7 @@ export const TopExercisesCard = ({
   assetsLowerMap: Map<string, ExerciseAsset> | null;
 }) => {
   const formatSignedPctWithNoun = (pct: number, noun: string) =>
-    `${formatSignedNumber(pct, { maxDecimals: 0 })}% ${noun}`;
+    `${formatDeltaPercentage(pct, getDeltaFormatPreset('badge'))} ${noun}`;
 
   const pie = pieColors;
 
@@ -451,7 +452,7 @@ export const TopExercisesCard = ({
               )}
               {topExercisesInsight.top && (
                 <TrendBadge
-                  label={<BadgeLabel main={`${topExercisesInsight.topShare.toFixed(0)}%`} meta="of shown" />}
+                  label={<BadgeLabel main={`${formatDeltaPercentage(topExercisesInsight.topShare)}`} meta="of shown" />}
                   tone="neutral"
                 />
               )}
@@ -481,7 +482,7 @@ export const TopExercisesCard = ({
               )}
               {topExercisesInsight.top && (
                 <TrendBadge
-                  label={<BadgeLabel main={`${topExercisesInsight.topShare.toFixed(0)}%`} meta="of shown" />}
+                  label={<BadgeLabel main={`${formatDeltaPercentage(topExercisesInsight.topShare)}`} meta="of shown" />}
                   tone={topExercisesInsight.topShare >= 45 ? 'bad' : topExercisesInsight.topShare >= 30 ? 'neutral' : 'good'}
                 />
               )}
diff --git a/frontend/components/dashboard/VolumeDensityCard.tsx b/frontend/components/dashboard/VolumeDensityCard.tsx
@@ -13,6 +13,7 @@ import {
 } from 'recharts';
 import type { TimeFilterMode, WeightUnit } from '../../utils/storage/localStorage';
 import { formatNumber, formatSignedNumber } from '../../utils/format/formatters';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../../utils/format/deltaFormat';
 import { addEmaSeries, DEFAULT_EMA_HALF_LIFE_DAYS } from '../../utils/analysis/ema';
 import {
   BadgeLabel,
@@ -208,7 +209,7 @@ export const VolumeDensityCard = ({
                     main={
                       <span className="inline-flex items-center gap-1">
                         <TrendIcon direction={volumeDensityTrend.delta.direction} />
-                        <span>{`${formatSigned(volumeDensityTrend.delta.deltaPercent)}%`}</span>
+                        <span>{formatDeltaPercentage(volumeDensityTrend.delta.deltaPercent, getDeltaFormatPreset('badge'))}</span>
                       </span>
                     }
                     meta="vs prev mo"
diff --git a/frontend/components/dashboard/WeeklyRhythmCard.tsx b/frontend/components/dashboard/WeeklyRhythmCard.tsx
@@ -14,6 +14,7 @@ import {
   XAxis,
   YAxis,
 } from 'recharts';
+import { formatDeltaPercentage } from '../../utils/format/deltaFormat';
 import {
   BadgeLabel,
   ChartDescription,
@@ -124,8 +125,8 @@ export const WeeklyRhythmCard = ({
         <InsightLine>
           {weeklyRhythmInsight ? (
             <>
-              <TrendBadge label={<BadgeLabel main={`Top ${weeklyRhythmInsight.top.subject} ${weeklyRhythmInsight.top.share.toFixed(0)}%`} />} tone="info" />
-              <TrendBadge label={<BadgeLabel main={`Low ${weeklyRhythmInsight.bottom.subject} ${weeklyRhythmInsight.bottom.share.toFixed(0)}%`} />} tone="neutral" />
+              <TrendBadge label={<BadgeLabel main={`Top ${weeklyRhythmInsight.top.subject} ${formatDeltaPercentage(weeklyRhythmInsight.top.share)}`} />} tone="info" />
+              <TrendBadge label={<BadgeLabel main={`Low ${weeklyRhythmInsight.bottom.subject} ${formatDeltaPercentage(weeklyRhythmInsight.bottom.share)}`} />} tone="neutral" />
               <TrendBadge label={<BadgeLabel main={weeklyRhythmInsight.rhythmLabel} />} tone={weeklyRhythmInsight.rhythmTone} />
             </>
           ) : (
diff --git a/frontend/components/dashboard/WeeklySetsCard.tsx b/frontend/components/dashboard/WeeklySetsCard.tsx
@@ -16,6 +16,7 @@ import {
   ResponsiveContainer,
   Tooltip,
 } from 'recharts';
+import { formatDeltaPercentage } from '../../utils/format/deltaFormat';
 import { BodyMap, type BodyMapGender } from '../BodyMap';
 import { LazyRender } from '../LazyRender';
 import { ChartSkeleton } from '../ChartSkeleton';
@@ -335,7 +336,7 @@ export const WeeklySetsCard = ({
                 tone="neutral"
               />
               <TrendBadge
-                label={`Top3 ${weeklySetsInsight.top3Share.toFixed(0)}%`}
+                label={`Top3 ${formatDeltaPercentage(weeklySetsInsight.top3Share)}`}
                 tone={
                   weeklySetsInsight.top3Share >= 70
                     ? 'bad'
diff --git a/frontend/test-delta-format.ts b/frontend/test-delta-format.ts
@@ -0,0 +1,50 @@
+import { formatDeltaPercentage, getDeltaFormatPreset, DELTA_FORMAT_PRESETS } from '../utils/format/deltaFormat';
+
+// Test cases to verify the delta formatting works correctly
+console.log('=== Delta Percentage Formatting Tests ===');
+
+// Test regular percentages
+console.log('Regular percentages:');
+console.log(`50%: ${formatDeltaPercentage(50)}`);
+console.log(`-25%: ${formatDeltaPercentage(-25)}`);
+console.log(`0%: ${formatDeltaPercentage(0)}`);
+
+// Test large percentages with compact format (now at 150% threshold)
+console.log('\nLarge percentages (compact format at 150% threshold):');
+console.log(`100%: ${formatDeltaPercentage(100, { compact: true })} (should be 100% - below threshold)`);
+console.log(`125%: ${formatDeltaPercentage(125, { compact: true })} (should be 125% - below threshold)`);
+console.log(`150%: ${formatDeltaPercentage(150, { compact: true })} (should be 2.5x - 150% increase = 2.5x total)`);
+console.log(`175%: ${formatDeltaPercentage(175, { compact: true })} (should be 2.8x - 175% increase = 2.8x total)`);
+console.log(`200%: ${formatDeltaPercentage(200, { compact: true })} (should be 3x - 200% increase = 3x total)`);
+console.log(`250%: ${formatDeltaPercentage(250, { compact: true })} (should be 3.5x - 250% increase = 3.5x total)`);
+console.log(`300%: ${formatDeltaPercentage(300, { compact: true })} (should be 4x - 300% increase = 4x total)`);
+
+// Test with plus sign
+console.log('\nWith plus sign:');
+console.log(`50%: ${formatDeltaPercentage(50, { showPlus: true })}`);
+console.log(`150%: ${formatDeltaPercentage(150, { showPlus: true, compact: true })}`);
+
+// Test presets
+console.log('\nPresets:');
+console.log(`Badge preset 50%: ${formatDeltaPercentage(50, DELTA_FORMAT_PRESETS.COMPACT)}`);
+console.log(`Badge preset 100%: ${formatDeltaPercentage(100, DELTA_FORMAT_PRESETS.COMPACT)}`);
+console.log(`Badge preset 150%: ${formatDeltaPercentage(150, DELTA_FORMAT_PRESETS.COMPACT)} (should be 2.5x)`);
+console.log(`Badge preset 200%: ${formatDeltaPercentage(200, DELTA_FORMAT_PRESETS.COMPACT)} (should be 3x)`);
+console.log(`Chart preset 200%: ${formatDeltaPercentage(200, getDeltaFormatPreset('chart'))}`);
+console.log(`Tooltip preset 200%: ${formatDeltaPercentage(200, getDeltaFormatPreset('tooltip'))}`);
+
+// Test edge cases
+console.log('\nEdge cases:');
+console.log(`Infinity: ${formatDeltaPercentage(Infinity)}`);
+console.log(`NaN: ${formatDeltaPercentage(NaN)}`);
+console.log(`Very large: ${formatDeltaPercentage(1000)}`);
+
+export default function testDeltaFormatting() {
+  // This function can be used for manual testing
+  return {
+    regular: formatDeltaPercentage(50),
+    compact: formatDeltaPercentage(200, { compact: true }),
+    withPlus: formatDeltaPercentage(150, { showPlus: true, compact: true }),
+    badge: formatDeltaPercentage(250, getDeltaFormatPreset('badge'))
+  };
+}
diff --git a/frontend/utils/analysis/insights.ts b/frontend/utils/analysis/insights.ts
@@ -5,6 +5,7 @@ import { getSessionKey } from '../date/dateUtils';
 import { isWarmupSet } from './setClassification';
 import { WeightUnit } from '../storage/localStorage';
 import { convertWeight, getStandardWeightIncrementKg } from '../format/units';
+import { formatDeltaPercentage, getDeltaFormatPreset } from '../format/deltaFormat';
 
 // ============================================================================
 // DELTA CALCULATIONS - Show movement vs previous periods
@@ -24,6 +25,7 @@ export interface DeltaResult {
   previous: number;
   delta: number;
   deltaPercent: number;
+  formattedPercent: string;
   direction: 'up' | 'down' | 'same';
 }
 
@@ -65,11 +67,15 @@ export const calculateDelta = (current: number, previous: number): DeltaResult =
   const deltaPercent = previous > 0 ? Math.round((delta / previous) * 100) : (current > 0 ? 100 : 0);
   const direction: 'up' | 'down' | 'same' = delta > 0 ? 'up' : delta < 0 ? 'down' : 'same';
   
+  // Use centralized formatting for better UX with large percentages
+  const formattedPercent = formatDeltaPercentage(deltaPercent, getDeltaFormatPreset('badge'));
+  
   return { 
     current: Number(current.toFixed(2)), 
     previous: Number(previous.toFixed(2)), 
     delta, 
     deltaPercent, 
+    formattedPercent,
     direction 
   };
 };
diff --git a/frontend/utils/format/deltaFormat.ts b/frontend/utils/format/deltaFormat.ts
