feat(android): Phase 1 timeline — day sections, scope toggle, pull-to-refresh + complete i18n #1118

Merged
chris merged 4 commits from ux-android-timeline into main 2026-10-11 18:09:48 +02:00
Owner

Phase 1 of spec 055 (T004 + the T003 i18n remainder): the Fotos tab now scrolls as
labelled day sections instead of a flat cursor list, and every user-visible string
in the app is in strings.xml with de/da/en translations.

Rebased onto current main and reconciled with #1116 (viewer actions) — see
Reconciling with #1116.

Day-sectioned timeline

The server already exposes the two-layer day API (ADR 0048), so this is a client
switch, not a backend change:

  • GET /api/timeline/days returns every day's metadata in one cheap call.
  • GET /api/timeline/days/{dayKey}/items hydrates one day's media on demand.

TimelineViewModel keeps the full day list internally but only exposes the first
4 days; scrolling calls loadMore() and appends the next batch, then hydrates it.
A large library never pays for the whole timeline up front. A generation counter
bumps on every reset, so a slow response from a previous scope or refresh is
dropped rather than resurrecting stale state.

Undated items go to one trailing Ohne Datum section. orderedForDisplay()
partitions capture days from undated ones and always emits undated last — a
property of the client, not just of the server's capture_rank ordering — so
undated media is never interleaved with dated days.

Day headers are formatted client-side from the date in the day key, using
DateTimeFormatter.ofLocalizedDate(FULL) with the composition's Configuration
locale. They deliberately do not use the server's label/eyebrow, which are
English-only hardcodes ("Friday, 10 October 2026" / "Without date") and would
render English day headers on a German-default app under a Danish device locale.

Scope toggle ships Alle / Meine. Gruppe is deferred — see below.

Pull-to-refresh uses Material3 PullToRefreshBox. Content stays on screen
during a refresh: every loaded day keeps its thumbnails but drops back to
PENDING, so the re-request genuinely re-fetches while nothing blanks. A failed
refresh is non-destructive too — content and the day list survive, the error
arrives as an inline banner, and loadMore() keeps working. Only a cold load or
a scope switch clears the grid.

previewStatus placeholders: pending renders a bare surfaceVariant scrim;
failed/not_supported render a low-contrast BrokenImage glyph. A still-cooking
or never-coming rendition never shows a broken-image state.

Viewer entry point keeps working unchanged. state.items is a derived flat
list in day order, so the pager's indexOf/itemAt resolve against exactly what
the grid shows — a day still loading contributes nothing, keeping the start index
honest.

Reconciling with #1116

#1116 landed TimelineViewModel.removeItem() — trash removes an item from the
list so the pager keeps its index and the next photo slides into place — written
against the flat cursor list this PR replaces. Both features have to keep working,
so removeItem() is re-implemented over day sections rather than dropped. Trashing
still removes the item from the flat list; the owning day's itemCount drops with
it so the header stays honest.

Two things the flat list could not express needed deciding. A day left holding no
media leaves the stored day list too, not just the rendered one — loadMore()
rebuilds sections from that list, so a day removed only from the UI would
reappear empty on the next scroll. And removing a day inside the exposed window
shifts that window left by one, so the day sliding into its place is fetched next
instead of being silently skipped.

The three removeItem tests the rebase surfaced as failing are re-seated on the
day model, and a fourth pins the resurrection case explicitly.

i18n completion (T003)

The three resource files now carry identical key sets apart from app_name, the
brand name, which stays untranslated on purpose (plural resources match too).

  • ViewModels return @StringRes ids, not Strings. TimelineViewModel,
    AlbumsViewModel and BackupStatusViewModel carried English fallbacks built
    from failure.message ?: "Could not load the timeline" / "...read device albums" / "...read backup state". They now return a resource id resolved by
    the screen, matching the pattern LoginViewModel already used — a ViewModel
    has no Context, so it cannot localize.
  • AuthRepository messages become resource ids. The expired-login snackbar was
    hardcoded Danish ("Login udløbet. Log ind igen."), so a German or English
    device showed a Danish string on the most common recovery path. onUnauthorized()
    now emits R.string.session_expired; MemoriesApp resolves it during composition
    via stringResource rather than context.getString, which is not
    configuration-aware (and which lint flags). The pending id is rememberSaveable
    so an unacknowledged expiry notice survives a rotation.
  • LoginFailure.Unexpected stops carrying a message. Its three constructors
    built English literals ("Login failed (HTTP 500)", "Unexpected server response")
    which the login screen surfaced verbatim. It now carries a @StringRes template
    plus an optional status code; the HTTP code is still interpolated into the
    localized template, so a self-hosted operator keeps the one detail that is
    actionable and language-neutral.
  • MediaStore bucket names. AndroidMediaStoreScanner fell back to the English
    "Unknown" for a bucket with no display name, and that was rendered directly as
    an album row. The scanner now returns blank and BackupScreen substitutes the
    localized backup_album_unknown, keeping UI copy out of the sync layer.

Scope toggle: why only Alle/Meine

scope=group pins the query to a concrete sharingGroupId
(SHARED_MEDIA_JOIN_GROUP matches c.sharing_group_id = :sharingGroupId, so a
null id matches nothing). The app has no way to pick a group — the only source is
GET /api/sharing-groups, which needs a picker surface. Shipping a third chip
would render a control that silently returns nothing, so Gruppe is deferred and
logged as ISSUE-120 rather than shipped broken.

Known issues

ISSUE-119 (pre-existing, low): lintDebug fails on the branch baseline with
16 errors — 8 × UnsafeOptInUsageError in ui/timeline/ViewerPage.kt, 7 ×
LocalContextGetResourceValueCall in ui/timeline/MediaViewerScreen.kt and 1 ×
MissingTranslation for app_name, all introduced by the viewer PRs #1112/#1116.
Neither viewer file is touched here, and lintDebug is not a CI gate — the
workflow runs only :app:testDebugUnitTest and :app:assembleDebug, both green.
This branch adds no new lint errors: the two it initially introduced
(NonObservableLocale, LocalContextGetResourceValueCall in MemoriesApp) are
fixed.

Verification

./gradlew :app:testDebugUnitTest :app:assembleDebug   # BUILD SUCCESSFUL, 166 tests, 0 failed
./gradlew :app:lintDebug                              # same 16 baseline errors, none new

Tests cover the day-section state machine (first-batch hydration, loadMore
appending without duplication, undated trailing, scope switch dropping the old
scope, refresh no-blanking, per-day failure + retry, 401 mid-hydration, the
non-destructive failed refresh) and the days-page JSON shape. Both bugs the new
tests caught during development — loadMore duplicating already-exposed days, and
a refresh discarding the day list — are pinned by explicit assertions.

Out of scope for this PR, unchanged: search, server albums, people, and the
viewer screens/actions (#1116).

Phase 1 of spec 055 (T004 + the T003 i18n remainder): the Fotos tab now scrolls as labelled day sections instead of a flat cursor list, and every user-visible string in the app is in `strings.xml` with de/da/en translations. Rebased onto current `main` and reconciled with #1116 (viewer actions) — see [Reconciling with #1116](#reconciling-with-1116). ## Day-sectioned timeline The server already exposes the two-layer day API (`ADR 0048`), so this is a client switch, not a backend change: - **`GET /api/timeline/days`** returns every day's metadata in one cheap call. - **`GET /api/timeline/days/{dayKey}/items`** hydrates one day's media on demand. `TimelineViewModel` keeps the full day list internally but only *exposes* the first 4 days; scrolling calls `loadMore()` and appends the next batch, then hydrates it. A large library never pays for the whole timeline up front. A generation counter bumps on every reset, so a slow response from a previous scope or refresh is dropped rather than resurrecting stale state. **Undated items** go to one trailing `Ohne Datum` section. `orderedForDisplay()` partitions capture days from undated ones and always emits undated last — a property of the client, not just of the server's `capture_rank` ordering — so undated media is never interleaved with dated days. **Day headers** are formatted client-side from the date in the day key, using `DateTimeFormatter.ofLocalizedDate(FULL)` with the composition's `Configuration` locale. They deliberately do *not* use the server's `label`/`eyebrow`, which are English-only hardcodes (`"Friday, 10 October 2026"` / `"Without date"`) and would render English day headers on a German-default app under a Danish device locale. **Scope toggle** ships `Alle` / `Meine`. `Gruppe` is deferred — see below. **Pull-to-refresh** uses Material3 `PullToRefreshBox`. Content stays on screen during a refresh: every loaded day keeps its thumbnails but drops back to `PENDING`, so the re-request genuinely re-fetches while nothing blanks. A failed refresh is non-destructive too — content and the day list survive, the error arrives as an inline banner, and `loadMore()` keeps working. Only a cold load or a scope switch clears the grid. **`previewStatus` placeholders**: `pending` renders a bare `surfaceVariant` scrim; `failed`/`not_supported` render a low-contrast `BrokenImage` glyph. A still-cooking or never-coming rendition never shows a broken-image state. **Viewer entry point** keeps working unchanged. `state.items` is a derived flat list in day order, so the pager's `indexOf`/`itemAt` resolve against exactly what the grid shows — a day still loading contributes nothing, keeping the start index honest. ## Reconciling with #1116 #1116 landed `TimelineViewModel.removeItem()` — trash removes an item from the list so the pager keeps its index and the next photo slides into place — written against the flat cursor list this PR replaces. Both features have to keep working, so `removeItem()` is re-implemented over day sections rather than dropped. Trashing still removes the item from the flat list; the owning day's `itemCount` drops with it so the header stays honest. Two things the flat list could not express needed deciding. A day left holding no media leaves the stored day list too, not just the rendered one — `loadMore()` rebuilds sections from that list, so a day removed only from the UI would reappear empty on the next scroll. And removing a day inside the exposed window shifts that window left by one, so the day sliding into its place is fetched next instead of being silently skipped. The three `removeItem` tests the rebase surfaced as failing are re-seated on the day model, and a fourth pins the resurrection case explicitly. ## i18n completion (T003) The three resource files now carry identical key sets apart from `app_name`, the brand name, which stays untranslated on purpose (plural resources match too). - **ViewModels return `@StringRes` ids, not `String`s.** `TimelineViewModel`, `AlbumsViewModel` and `BackupStatusViewModel` carried English fallbacks built from `failure.message ?: "Could not load the timeline"` / `"...read device albums"` / `"...read backup state"`. They now return a resource id resolved by the screen, matching the pattern `LoginViewModel` already used — a `ViewModel` has no `Context`, so it cannot localize. - **`AuthRepository` messages become resource ids.** The expired-login snackbar was hardcoded Danish (`"Login udløbet. Log ind igen."`), so a German or English device showed a Danish string on the most common recovery path. `onUnauthorized()` now emits `R.string.session_expired`; `MemoriesApp` resolves it during composition via `stringResource` rather than `context.getString`, which is not configuration-aware (and which lint flags). The pending id is `rememberSaveable` so an unacknowledged expiry notice survives a rotation. - **`LoginFailure.Unexpected` stops carrying a message.** Its three constructors built English literals (`"Login failed (HTTP 500)"`, `"Unexpected server response"`) which the login screen surfaced verbatim. It now carries a `@StringRes` template plus an optional status code; the HTTP code is still interpolated into the localized template, so a self-hosted operator keeps the one detail that is actionable and language-neutral. - **MediaStore bucket names.** `AndroidMediaStoreScanner` fell back to the English `"Unknown"` for a bucket with no display name, and that was rendered directly as an album row. The scanner now returns blank and `BackupScreen` substitutes the localized `backup_album_unknown`, keeping UI copy out of the sync layer. ## Scope toggle: why only Alle/Meine `scope=group` pins the query to a concrete `sharingGroupId` (`SHARED_MEDIA_JOIN_GROUP` matches `c.sharing_group_id = :sharingGroupId`, so a null id matches nothing). The app has no way to pick a group — the only source is `GET /api/sharing-groups`, which needs a picker surface. Shipping a third chip would render a control that silently returns nothing, so `Gruppe` is deferred and logged as **ISSUE-120** rather than shipped broken. ## Known issues **ISSUE-119** (pre-existing, `low`): `lintDebug` fails on the branch baseline with 16 errors — 8 × `UnsafeOptInUsageError` in `ui/timeline/ViewerPage.kt`, 7 × `LocalContextGetResourceValueCall` in `ui/timeline/MediaViewerScreen.kt` and 1 × `MissingTranslation` for `app_name`, all introduced by the viewer PRs #1112/#1116. Neither viewer file is touched here, and `lintDebug` is not a CI gate — the workflow runs only `:app:testDebugUnitTest` and `:app:assembleDebug`, both green. **This branch adds no new lint errors**: the two it initially introduced (`NonObservableLocale`, `LocalContextGetResourceValueCall` in `MemoriesApp`) are fixed. ## Verification ``` ./gradlew :app:testDebugUnitTest :app:assembleDebug # BUILD SUCCESSFUL, 166 tests, 0 failed ./gradlew :app:lintDebug # same 16 baseline errors, none new ``` Tests cover the day-section state machine (first-batch hydration, `loadMore` appending without duplication, undated trailing, scope switch dropping the old scope, refresh no-blanking, per-day failure + retry, 401 mid-hydration, the non-destructive failed refresh) and the days-page JSON shape. Both bugs the new tests caught during development — `loadMore` duplicating already-exposed days, and a refresh discarding the day list — are pinned by explicit assertions. Out of scope for this PR, unchanged: search, server albums, people, and the viewer screens/actions (#1116).
Switch the Fotos tab from the flat /api/timeline cursor list to the day-bucketed
endpoints the server already exposes (spec 055 S8, ADR 0048), so a family member
scrolls through labelled days instead of an undifferentiated wall of thumbnails.

API. Add GET /api/timeline/days and /api/timeline/days/{dayKey}/items as one
clearly separated additive block in MemoriesApi/HttpMemoriesApi — the concurrent
viewer lane edits the same file, so the additions are quarantined. dayKey
travels as a single path segment (captured:2026-10-10); OkHttp's path
canonicalisation leaves the colon intact, and dayKey is percent-encoded so a
future key with a slash cannot escape the route.

State machine. TimelineViewModel now holds a two-layer list: one cheap days
call returns every day's metadata, then each day's items hydrate on demand.
Only the first INITIAL_DAY_COUNT days are exposed up front and loadMore() appends
the next batch, so a large library never pays for the whole timeline up front.
A generation counter is bumped on every reset, so a slow response from a
previous scope or refresh is dropped rather than resurrecting stale state.

Undated. orderedForDisplay() partitions capture days from undated ones and
always emits the undated bucket last, so "Ohne Datum" is one trailing section
that is never interleaved — a property of the client, not just of the server's
capture_rank ordering.

Header copy. Day headers are formatted client-side from the date in the day key
via DateTimeFormatter.ofLocalizedDate(FULL) with the composition's Configuration
locale, not from the server's label/eyebrow, which are English-only hardcodes
("Friday, 10 October 2026" / "Without date"). A German-default app would
otherwise show English day headers under a Danish device locale.

Refresh without blanking. A refresh keeps every loaded day's thumbnails on
screen and drops them back to PENDING, so the re-request actually re-fetches
while the user still sees what they were looking at. A failed refresh is
non-destructive too: content and the day list survive, the error arrives as an
inline banner, and loadMore() keeps working. Only a cold load or a scope switch
clears the grid.

Scope. Alle/Meine ship now. `group` is deliberately deferred: the API pins it to
a concrete sharingGroupId, which the app cannot obtain without a group picker,
so a third chip would silently return nothing (logged as ISSUE-117).

Placeholders. previewStatus pending renders a bare surfaceVariant scrim;
failed/not_supported renders a low-contrast BrokenImage glyph. A still-cooking
or never-coming rendition never shows a broken-image state.

Viewer entry. state.items is a derived flat list in day order, so the pager's
indexOf/itemAt resolve against exactly what the grid shows — a day still
loading contributes nothing, keeping the start index honest.

Tests. TimelineViewModelTest covers the day-section machine (first-batch
hydration, loadMore appending without duplication, undated trailing, scope
switch dropping the old scope, refresh no-blanking, per-day failure + retry,
401 mid-hydration, and the non-destructive failed refresh). TimelineJsonTest
adds the days-page shape. Both bugs the new tests caught during development —
loadMore duplicating already-exposed days, and a refresh discarding the day
list — are pinned by explicit assertions.
Close out the Phase 0 i18n sweep (spec 055 T003). German stays the default in
values/, with values-da/ and values-en/ alongside; the three files now carry
identical key sets apart from app_name, which is the brand name and stays
untranslated on purpose.

ViewModels return @StringRes ids, not Strings. TimelineViewModel, AlbumsViewModel
and BackupStatusViewModel carried English fallbacks built from
failure.message ?: "Could not load the timeline" / "...read device albums" /
"...read backup state". They now return a resource id and the screen resolves it,
matching the pattern LoginViewModel already used — a ViewModel has no Context,
so it cannot localize, and only the composable can.

AuthRepository messages become resource ids. The expired-login snackbar was
hardcoded Danish ("Login udløbet. Log ind igen."), so a German or English device
showed a Danish string on the most common recovery path. onUnauthorized() now
emits R.string.session_expired and MemoriesApp resolves it during composition via
stringResource rather than context.getString: the latter is not
configuration-aware and would show a stale locale after a mid-session language
switch, and lint flags it (LocalContextGetResourceValueCall). The pending id is
rememberSaveable so an unacknowledged expiry notice survives a rotation instead
of being dropped.

LoginFailure.Unexpected stops carrying a message. Its three constructors built
English literals ("Login failed (HTTP 500)", "Unexpected server response"), which
messageFor then surfaced verbatim on the login screen. It now carries a
@StringRes template plus an optional status code; the HTTP code is still
interpolated into the localized template so a self-hosted operator keeps the one
detail that is actually actionable and language-neutral.

MediaStore bucket names. AndroidMediaStoreScanner fell back to the English word
"Unknown" for a bucket with no display name; that string was rendered directly as
an album row. The scanner now returns blank and BackupScreen substitutes the
localized backup_album_unknown, so the placeholder translates like everything
else while the sync layer stays free of UI copy.

Also drop a non-observable Locale.getDefault() read in the new day-header
formatting (NonObservableLocale) in favour of the composition's Configuration.
chore(android): log timeline follow-ups, bump to 0.1.5
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 14s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m17s
bb19be1e36
Record two defects this lane confirmed but did not fix.

ISSUE-116 is pre-existing: lintDebug fails on the branch baseline with 8 x
UnsafeOptInUsageError in ui/timeline/ViewerPage.kt (media3 UnstableApi usage
introduced by PR#1112 without an opt-in marker) plus 1 x MissingTranslation for
the app_name brand string. Neither is user-visible and lintDebug is not a CI
gate — the workflow runs only :app:testDebugUnitTest and :app:assembleDebug,
both green. ViewerPage.kt belongs to the concurrent viewer lane, so it is out of
scope here. This branch adds no new lint errors: the two it did introduce
(NonObservableLocale in the new day-header formatting, LocalContextGetResourceValueCall
in the snackbar) are fixed in the preceding commit.

ISSUE-117 is the scope-toggle follow-up: the chip row ships Alle/Meine only,
because scope=group pins the query to a concrete sharingGroupId and the app has
no picker to obtain one. Shipping the third chip would render a control that
silently returns nothing.

versionCode 6 / 0.1.5 marks the day-sectioned timeline and the completed i18n
sweep.
chris force-pushed ux-android-timeline from bb19be1e36
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 14s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m17s
to 46259e24b3
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 2m48s
2026-10-11 17:55:55 +02:00
Compare
chris merged commit b5cea95a60 into main 2026-10-11 18:09:48 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1118
No description provided.