samplez/rippr-flutter-src/docs/v3/V3-03-units.md

V3-03 — Distance and speed units

Phase Foundations · Depends on V3-02 · Size S · Status Done

Goal

Imperial as well as metric, chosen once and applied everywhere.

Context

Everything is hardcoded metric: formatDistance switches m/km at 1000, formatSpeed prints km/h, elevation prints metres. Fine in Canada, useless to anyone in the US or UK.

Cheap, and the kind of thing that makes an app feel unfinished when missing.

Design

A UnitSystem enum (metric, imperial) in Config, defaulting from the device locale on first launch.

Conversion belongs in formatting only. Storage stays SI — metres, km/h, metres of altitude — forever. Converting at the storage layer would corrupt every existing ride and break the parity harness.

Value	Metric	Imperial
Distance	m / km	ft / mi
Speed	km/h	mph
Elevation	m	ft

Implementation

1. UnitSystem in Config; default from Platform.localeName
2. Extend ui/format.dart — every formatter takes the unit system
3. Thread it through: record screen, trips list, trip detail, charts, map legend
4. Exports stay SI regardless. GPX is metres by specification; changing that breaks consumers.

Acceptance criteria

• Switching units updates every screen immediately
• Stored values are unchanged — verified by exporting before and after
• GPX/GeoJSON output is byte-identical across the two settings
• First launch picks a sensible default from the locale

Tests

• Formatter tests for both systems, including the m→km and ft→mi boundaries
• A test asserting export output does not change with the unit setting
• Widget test toggling units and checking a rendered label

Risks

The obvious trap is converting too deep in the stack. Guard it with the export test.

Out of scope

Temperature, pace (min/km) — pace is arguably right for running, revisit after V3-01.

Outcome

Built ahead of V3-02 in execution order, despite the ticket table listing it as depending on V3-02 — the Settings screen needed something real to control, and the formatting/Config plumbing itself has zero dependency on a screen existing. Both are done; the numbering is unchanged.

UnitSystem lives in domain/models.dart, not ui/format.dart as first drafted — Config (a data/preferences-layer class) needed the enum too, and having it depend on ui/ read backwards. Moved to the domain layer alongside Activity, which every other cross-cutting preference-like enum in this codebase already does.

Reactivity reuses the exact pattern mapEnabledProvider already established — unitSystemProvider, a StateProvider<UnitSystem> seeded from Config once and then read/written directly by the UI — rather than introducing the heavier ConfigNotifier class the ticket's implementation notes proposed. Config mutates its own backing SharedPreferences in place, so a widget re-assigning the same Config instance to configProvider was never going to notify anything; this sidesteps that without a new abstraction.

Threaded through all three screens plus the speed histogram's bucket labels, which convert-and-round for display (formatSpeedRangeLabel) without changing how speedHistogram itself bins — binning stays km/h always, matching the invariant that storage and computation never see the display unit. Export was the one place explicitly not touched: gpx()/geoJson() take no UnitSystem parameter at all, which is a stronger guarantee than validating one.

One real finding: config_test.dart's locale-default test deliberately does not assert a specific value, because it cannot know the test runner's own locale — and that caution was immediately vindicated. settings_screen_test.dart first asserted a fresh Config defaults to metric and failed, because this dev machine's own locale resolves to a region in the imperial set. Fixed by seeding an explicit value before asserting, the same technique already used elsewhere for exactly this reason.

22 tests: 13 format_test.dart, 9 config_test.dart.