feat!: honor user display preferences across all UI surfaces

Phase A–H sweep: plumb user display preferences (units, currency,
decimal precision, gas unit, range type, locale, time/date format)
end-to-end through the entire frontend so user-facing values respect
Settings consistently. Telemetry ingestion remains unchanged — this
only affects how stored SI values are rendered.

Highlights:
- New/extended hooks: useFormatting (locale-aware currency + energy
  cost), useUnits (distance/speed/temperature/pressure/energy/power/
  duration), useDateFormat, usePreferredRange, usePressureFormat.
- New reusable Range format component and preferredRange helper.
- FormatterPrefsBridge syncs settings.decimal_precision into
  fmtNumber/fmtInt/fmtPercent/fmtCompact/fmtWithUnit globals.
- chargingAggregation accepts currencySymbol; messages use fmtNumber.
- Removed Google Maps API Key field from Settings UI.
- Migrated 100+ user-visible surfaces to honor prefs: charging
  cost/cards/charts/maps, dashboard widgets, year-review slides,
  weekly digest, fleet/lifetime/timeline/true-cost analytics,
  battery cells/projected range/sleep/energy, climate, maintenance,
  drive-detail/trip-planner/shared-drive, system status (uptime,
  SLO, Tesla API usage, scheduled maintenance, telemetry pipeline),
  alert/notification surfaces, signal viewer, vehicle hero/detail.
- toFixed sweep on production numeric displays → fmtNumber/fmtPercent.

useFormatting.formatCurrency(amount) and formatEnergyCost(kwh) now
default to settings.decimal_precision instead of hardcoded 2. Callers
passing an explicit decimals value are unaffected. Several i18n keys
also changed to drop the hardcoded "$" prefix (currency symbol now
embedded in the substituted value via formatCurrency) — affected keys
live in SystemStatusPage templates and require translation re-keying
for non-English locales.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: atulmgupta

web/src/components/charts/SmallMultiplesChart.tsx

@@ -44,6 +44,7 @@ import { ChartTooltip } from '@/components/charts/ChartTooltip';
 import { CHART_COLORS } from '@/lib/colors';
 import { cn } from '@/lib/cn';
 import { useInView } from '@/hooks/useInView';
+import { useDateFormat } from '@/hooks/useDateFormat';
 
 export interface SmallMultiplesChartProps<T extends Record<string, unknown> = Record<string, unknown>> {
   /** Time-ordered rows. Each row holds `timestamp` + arbitrary series keys. */
@@ -220,6 +221,7 @@ function SmallMultiplesCell({
   noData,
   onCellClick,
 }: SmallMultiplesCellProps) {
+  const { formatTime } = useDateFormat();
   const { ref, inView } = useInView<HTMLDivElement>({ rootMargin: '300px' });
   const cellInteractive = Boolean(onCellClick);
   return (
@@ -288,12 +290,7 @@ function SmallMultiplesCell({
             <XAxis
               dataKey={xKey}
               tick={{ fill: 'var(--text-muted)', fontSize: 9 }}
-              tickFormatter={(v: string) => {
-                const d = new Date(v);
-                return Number.isNaN(d.getTime())
-                  ? String(v)
-                  : d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
-              }}
+              tickFormatter={(v: string) => formatTime(v)}
               minTickGap={24}
               tickLine={false}
             />

web/src/components/data-display/DataFreshness.tsx

@@ -4,6 +4,7 @@ import { RefreshCw, Wifi, WifiOff } from 'lucide-react';
 import type { UseQueryResult } from '@tanstack/react-query';
 import { cn } from '@/lib/cn';
 import { useMotionPreference } from '@/hooks/useMotionPreference';
+import { useDateFormat } from '@/hooks/useDateFormat';
 
 /**
  * `<DataFreshness>` — query-result-driven freshness chip.
@@ -119,6 +120,7 @@ export function DataFreshness({
 }: DataFreshnessProps) {
   const { t } = useTranslation();
   const { reduce } = useMotionPreference();
+  const { formatTime } = useDateFormat();
   const [, setTick] = useState(0);
 
   // Re-render every second to keep relative time accurate
@@ -167,7 +169,7 @@ export function DataFreshness({
     ? t('freshness.updatingTooltip', 'Updating…')
     : updatedAt
       ? t('freshness.lastUpdated', 'Last updated: {{time}}', {
-          time: new Date(updatedAt).toLocaleTimeString(),
+          time: formatTime(new Date(updatedAt)),
         })
       : t('freshness.neverUpdated', 'Never updated');
 

web/src/components/data-display/InsightsEngine.test.tsx

@@ -1,7 +1,19 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { InsightsEngine } from './InsightsEngine'
 
+vi.mock('@/hooks/useFormatting', () => ({
+  useFormatting: () => ({
+    formatCurrency: (amount: number, decimals = 2) =>
+      `$${Number(amount).toFixed(decimals)}`,
+    formatEnergyCost: (kwh: number) => `$${(kwh * 0.12).toFixed(2)}`,
+    currencySymbol: '$',
+    costPerKwh: 0.12,
+    costPerDistanceUnit: () => null,
+    estimateGasCost: () => null,
+  }),
+}))
+
 describe('InsightsEngine', () => {
   it('renders nothing with empty data', () => {
     const { container } = render(<InsightsEngine data={{}} />)

web/src/components/data-display/InsightsEngine.tsx

@@ -8,6 +8,7 @@ import {
 import { GlassPanel } from '@/components/ui'
 import { FadeIn } from '@/components/motion'
 import { fmtNumber } from '@/lib/numberFormat'
+import { useFormatting } from '@/hooks/useFormatting'
 import { trendColor } from '@/lib/colors'
 import type {
   Drive, ChargingSession, EnergyStats, BatteryReport,
@@ -55,7 +56,7 @@ const TREND_ICON: Record<Trend, { Icon: React.ElementType; color: string }> = {
 
 // ─── Analysis helpers ─────────────────────────────────────────
 
-function analyzeChargingCost(sessions: ChargingSession[]): Insight | null {
+function analyzeChargingCost(sessions: ChargingSession[], formatCurrency: (amount: number, decimals?: number) => string): Insight | null {
   const withCost = sessions.filter(s => s.cost != null && s.charge_energy_added > 0)
   if (withCost.length < 2) return null
 
@@ -72,7 +73,7 @@ function analyzeChargingCost(sessions: ChargingSession[]): Insight | null {
   const homeCost = home.length > 0 ? avgCost(home) : null
   const scCost = supercharger.length > 0 ? avgCost(supercharger) : null
 
-  let description = `Your average charging cost is $${fmtNumber(overall, 2)}/kWh.`
+  let description = `Your average charging cost is ${formatCurrency(overall, 2)}/kWh.`
   let trend: Trend = 'neutral'
   let trendGood = true
 
@@ -268,7 +269,7 @@ function analyzeDrivingPatterns(drives: Drive[]): Insight | null {
   }
 }
 
-function analyzeCostSavings(energy: EnergyStats): Insight | null {
+function analyzeCostSavings(energy: EnergyStats, formatCurrency: (amount: number, decimals?: number) => string): Insight | null {
   if (energy.total_energy_used_kwh <= 0) return null
 
   // Average gas car: 8.5 L/100km, avg gas price ~$1.50/L
@@ -282,7 +283,7 @@ function analyzeCostSavings(energy: EnergyStats): Insight | null {
     id: 'cost-savings',
     icon: Leaf,
     title: 'EV Cost Savings',
-    description: `You've saved approximately $${fmtNumber(savings, 0)} vs. gasoline based on ${fmtNumber(energy.total_energy_used_kwh, 0)} kWh consumed over ${fmtNumber(energy.total_distance_km, 0)} km. That's also ${fmtNumber(energy.co2_saved_kg, 0)} kg of CO₂ saved!`,
+    description: `You've saved approximately ${formatCurrency(savings, 0)} vs. gasoline based on ${fmtNumber(energy.total_energy_used_kwh, 0)} kWh consumed over ${fmtNumber(energy.total_distance_km, 0)} km. That's also ${fmtNumber(energy.co2_saved_kg, 0)} kg of CO₂ saved!`,
     trend: 'up',
     trendGood: true,
     severity: 'success',
@@ -319,11 +320,12 @@ function analyzeRangeOptimization(energy: EnergyStats, battery?: BatteryReport):
 // ─── Main component ───────────────────────────────────────────
 
 export function InsightsEngine({ data }: { data: InsightData }) {
+  const { formatCurrency } = useFormatting()
   const insights = useMemo(() => {
     const results: Insight[] = []
 
     if (data.chargingSessions?.length) {
-      const c = analyzeChargingCost(data.chargingSessions)
+      const c = analyzeChargingCost(data.chargingSessions, formatCurrency)
       if (c) results.push(c)
     }
     if (data.drives?.length) {
@@ -347,7 +349,7 @@ export function InsightsEngine({ data }: { data: InsightData }) {
       if (p) results.push(p)
     }
     if (data.energyStats) {
-      const s = analyzeCostSavings(data.energyStats)
+      const s = analyzeCostSavings(data.energyStats, formatCurrency)
       if (s) results.push(s)
     }
     if (data.energyStats) {
@@ -356,7 +358,7 @@ export function InsightsEngine({ data }: { data: InsightData }) {
     }
 
     return results
-  }, [data])
+  }, [data, formatCurrency])
 
   if (insights.length === 0) return null
 

web/src/components/data-display/TimeStamp.tsx

@@ -1,6 +1,7 @@
 import { Tooltip } from '@/components/ui';
-import { formatDateTime, formatRelative } from '@/lib/dateFormat';
+import { useDateFormat } from '@/hooks/useDateFormat';
 import { useTimeFormatPreference } from '@/hooks/useTimeFormatPreference';
+import type { TzMode } from '@/lib/timezone';
 
 export type TimeStampFormat = 'relative' | 'absolute' | 'auto';
 
@@ -13,6 +14,14 @@ export interface TimeStampProps {
    * 'absolute' overrides it for a specific surface.
    */
   format?: TimeStampFormat;
+  /**
+   * Optional timezone-display mode override. When unset the component
+   * defaults to `settings.tz_display_default` ('vehicle' out of the
+   * box). Passing `'utc'` is useful for forensic/audit surfaces that
+   * must always render in UTC regardless of the user's preference.
+   * Mirrors the `in` prop on `<DateTime>`.
+   */
+  in?: TzMode;
   className?: string;
 }
 
@@ -23,11 +32,16 @@ export interface TimeStampProps {
  * global Settings preference. The tooltip always shows the OTHER format
  * so power users can flip between perspectives without leaving the page.
  *
+ * Honors `settings.locale` and the resolved IANA timezone (defaults to
+ * `settings.tz_display_default`, overridable via the `in` prop) when
+ * formatting both the visible body and the tooltip alternate.
+ *
  * Renders the universal "—" placeholder (no tooltip) when `value` is
  * null, undefined, or an unparseable timestamp. (Phase-45 / Prompt 22.)
  */
-export function TimeStamp({ value, format = 'auto', className }: TimeStampProps) {
+export function TimeStamp({ value, format = 'auto', in: mode, className }: TimeStampProps) {
   const pref = useTimeFormatPreference();
+  const { formatDateTime, formatRelative } = useDateFormat(mode);
 
   if (value == null) {
     return <span className={className}>—</span>;

web/src/components/data-display/__tests__/DataFreshness.test.tsx

@@ -6,6 +6,16 @@ import {
   FRESHNESS_COLORS,
   type FreshnessQuery,
 } from '../DataFreshness'
+import {
+  formatDate,
+  formatDateTime,
+  formatTime,
+  formatDateShort,
+  formatDateWithDay,
+  formatRelative,
+  formatRelativeTime,
+  formatRelativeDays,
+} from '@/lib/dateFormat'
 
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({
@@ -28,6 +38,25 @@ vi.mock('framer-motion', () => ({
   useReducedMotion: () => reducedMotionMock(),
 }))
 
+// `<DataFreshness>` reads locale + tz via `useDateFormat()` for its
+// `title` attribute. Mock the hook so tests don't need a TanStack Query
+// provider or a Router (both required by `useSettings` + `useTimezone`).
+vi.mock('@/hooks/useDateFormat', () => ({
+  useDateFormat: () => ({
+    opts: {},
+    tz: 'UTC',
+    locale: 'en-US',
+    formatDate,
+    formatDateTime,
+    formatTime,
+    formatDateShort,
+    formatDateWithDay,
+    formatRelative,
+    formatRelativeTime,
+    formatRelativeDays,
+  }),
+}))
+
 describe('FRESHNESS_COLORS', () => {
   it('exposes a dot + text color tier for every status', () => {
     expect(FRESHNESS_COLORS.fresh.dot).toBe('bg-emerald-400')

web/src/components/data-display/__tests__/TimeStamp.test.tsx

@@ -3,11 +3,42 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render } from '@testing-library/react';
 import { TimeStamp } from '../TimeStamp';
 import { useTimeFormatPreference } from '@/hooks/useTimeFormatPreference';
+import {
+  formatDate,
+  formatDateTime,
+  formatTime,
+  formatDateShort,
+  formatDateWithDay,
+  formatRelative,
+  formatRelativeTime,
+  formatRelativeDays,
+} from '@/lib/dateFormat';
 
 vi.mock('@/hooks/useTimeFormatPreference', () => ({
   useTimeFormatPreference: vi.fn(),
 }));
 
+// `<TimeStamp>` now reads locale + tz via `useDateFormat()`, which in turn
+// subscribes to `useSettings()` (TanStack Query) and `useTimezone()` (router).
+// The component's behavior under test is the relative/absolute branching
+// and the tooltip swap, NOT the locale/tz plumbing — so we mock the hook
+// to return the pure lib helpers and keep the test render-tree minimal.
+vi.mock('@/hooks/useDateFormat', () => ({
+  useDateFormat: () => ({
+    opts: {},
+    tz: 'UTC',
+    locale: 'en-US',
+    formatDate,
+    formatDateTime,
+    formatTime,
+    formatDateShort,
+    formatDateWithDay,
+    formatRelative,
+    formatRelativeTime,
+    formatRelativeDays,
+  }),
+}));
+
 const mockedPref = vi.mocked(useTimeFormatPreference);
 
 beforeEach(() => {

web/src/components/data-display/format/Range.tsx

@@ -0,0 +1,44 @@
+import { useTranslation } from 'react-i18next'
+import { useUnits } from '@/hooks/useUnits'
+import { usePreferredRange, type PreferredRangeFields } from '@/hooks/usePreferredRange'
+
+interface RangeProps {
+  /** Vehicle/charge state snapshot with `rated_range` + `ideal_range` in SI metres. */
+  state: PreferredRangeFields | null | undefined
+  /** Optional decimal precision override for the value. */
+  precision?: number
+  className?: string
+}
+
+/**
+ * Reusable "primary range" renderer that respects both the user's
+ * distance-unit preference (km vs mi via `useUnits`) and the user's
+ * `preferred_range` preference (rated vs ideal via `usePreferredRange`).
+ *
+ * Use on surfaces that show "the range" generically — Glance, vehicle
+ * list cards, fleet summary, charge status, the dashboard hero. Do NOT
+ * use on explicit comparison surfaces (RangeBarWidget,
+ * RangeEstimateWidget, BatteryRangePanel) which render BOTH ranges
+ * side-by-side regardless of preference.
+ */
+export function Range({ state, precision = 0, className }: RangeProps) {
+  const { formatDistance } = useUnits()
+  const { meters } = usePreferredRange(state)
+
+  if (meters == null) return <span className={className}>—</span>
+
+  return <span className={className}>{formatDistance(meters, { precision })}</span>
+}
+
+/**
+ * Companion hook returning the localized "Rated Range" / "Ideal Range"
+ * label honoring the user's `preferred_range` preference. Use when you
+ * need the label separate from the value — e.g. inside a stat tile that
+ * renders the label and value in different elements.
+ */
+export function useRangeLabel(state: PreferredRangeFields | null | undefined): string {
+  const { t } = useTranslation()
+  const { labelKey, defaultLabel } = usePreferredRange(state)
+  return t(`common.${labelKey}`, defaultLabel)
+}
+

web/src/components/data-display/format/index.ts

@@ -13,3 +13,4 @@ export { Percentage } from './Percentage';
 export { FormattedNumber } from './Number';
 export { Duration } from './Duration';
 export type { DurationVariant } from './Duration';
+export { Range, useRangeLabel } from './Range';

web/src/components/data-display/index.ts

@@ -108,5 +108,7 @@ export {
   Percentage,
   FormattedNumber,
   Duration,
+  Range,
+  useRangeLabel,
 } from './format';
 export type { DateTimeVariant, DurationVariant } from './format';