Per-user duration display format preference

[KucharczykL]

Closes #486. Builds on #583.

What changed

Six ad-hoc format_duration() pattern strings had drifted apart across the session list, game pages, the navbar, and statistics — the same value rendered 3.2, 3 hours, 3 h 12 m, and 3h 12m depending on where you looked. All of it now goes through one preference.

Four profiles, selectable in /settings:

Value	45 minutes	1 h 12 m	83 h 12 m	1234 h
decimal_hours (default)	0.8 h	1.2 h	83.2 h	1,234.0 h
hours_minutes	45 m	1 h 12 m	83 h 12 m	1,234 h 00 m
whole_hours	1 hour	1 hour	83 hours	1,234 hours
adaptive	45 m	1 h 12 m	3 d 11 h	7 w 2 d

The default matches what the session list and game playtime already showed, so an untouched install looks unchanged.

Rules worth knowing

Round, never truncate, at each profile’s own resolution — truncation renders 59 minutes as "0 hours", which is a lie the popover should not have to repair.

Round the total once, then decompose. Rounding a component after the split renders 1 h 59 m 45 s as 2 h 60 m. The same rule makes adaptive re-pick its unit when rounding carries: 6 d 23 h 40 m is 1 w 0 d, never 6 d 24 h.

adaptive and hours_minutes are not interchangeable below a day. At 23 h 59 m 45 s they render 1 d 00 h and 24 h 00 m. That is why popover dedup compares rendered strings and never profile identity.

Locale owns grouping. USE_THOUSAND_SEPARATOR is unset project-wide and turning it on globally would retroactively regroup every price, so force_grouping is passed per call and override() is scoped to that call — the formatting locale is deliberately never activated request-wide.

The popover

Every duration offers the same value under the other profiles on hover, deduplicated so no line repeats another. The visible text is aria-hidden and a sibling sr-only span carries the value in words ("1 hour 12 minutes") — screen readers read 1.2 h as "one point two h". The panel drops aria-describedby for the same reason: it restates what the sr-only text already said.

Three surfaces could not take the popover in its plain form, all for the same reason — a popover trigger is a <button> and may not nest inside an <a>:

• Game detail stats row — solved. Duration splits into DurationText and DurationAlternates, and the existing stat popover renders the alternates in its own panel. One popover, full information.
• Navbar totals — solved via Popover(preface=…), in its own commit (d528381) so it can be reverted alone. The value stays a link and the popover moves to a sibling info glyph. Visual call is yours; see Navbar playtime totals show no alternate duration formats #587 for the alternatives.
• Stats playtime cells that are themselves links — render as DurationText. The standalone headline stats carry the full popover.

Layering

Formatting leaves the model layer: Session.duration_formatted(), duration_formatted_with_mark(), and Game.playtime_formatted() are gone, because a model method has no request and cannot resolve a per-user preference. Session.__str__ keeps a fixed decimal-hours rendering — it is a debug string. SessionQuerySet.total_duration_formatted() and calculated_duration_formatted() had no callers at all and are deleted rather than ported.

compute_stats() stays pure computation and now returns timedelta; stats_content formats. total_hours becomes a timedelta and the two per-game stats become timedelta | None — the old integer 0 fallback is gone.

Two places were computation wearing a formatter’s clothes and are now plain arithmetic on the raw value:

• the game-detail session average parsed a formatted string back into a float
• the play-event note default seeds text the user then saves, so it gets a fixed rendering — a display preference must not leak into stored data

format_duration() and the %H/%m mini-language are deleted outright.

Untouched

Stored values, GeneratedField computation, the API, filtering, sorting, the duration_manual form input, and the playtime_hours / duration_total_hours filter facets. The preference is display only.

Verification

make check green: lint, format-check, mypy, ts-check, vitest, and 2683 pytest tests including the full e2e suite. git diff --check clean.

New coverage includes a table test driven from the design’s rendering rules (every profile against zero, sub-minute, sub-hour, hour-plus, 24-hour-plus, week-plus, year-plus, plus the carry boundaries), locale tests asserting the cs NBSP separator explicitly, popover-id uniqueness on a list with two equal-duration rows, and four e2e tests covering the preference change, the popover contents, and the screen-reader text.

Still worth doing by hand: an Orca pass over a session list, to confirm each duration is announced once and in words.

Docs

docs/configuration.md gains a Duration format entry; the changelog gains an Unreleased section. The spec and plan for this work are deleted here — the rendering rules now live in tests/test_duration_presentation.py, which the file names as the specification.

🤖 Generated with Claude Code

[github-actions]

Staging deployment: https://timetracker-staging-claude-issue-486-duration-form.fly.dev