feat(android): Phase 1 search screen with family-simple filters #1119

Merged
chris merged 2 commits from ux-android-search into main 2026-10-11 18:33:19 +02:00
Owner

Implements spec 055 task T006 — Phase 1: Search screen for the Android app.

What you get

  • Entry: a "Suche" card at the top of the MEHR hub, plus a search icon in the Photos screen header (its own final commit so the timeline lane's conflict on TimelineScreen.kt stays a single, obvious hunk).
  • Routes: search, plus searchMedia/{mediaItemId} so a result tap opens the existing MediaViewerScreen over the search result list without touching the timeline's viewer route.
  • Typing: debounced-as-you-type — 300 ms, minimum two characters. A family member spelling out "Oma am Strand" gets one request when they stop, not five on the way. A filter tap re-runs immediately, because a tap is already a finished gesture.
  • Filters: Favoriten (toggle), Jahr (year picker, newest → 1970), Person (picker fed by GET /api/person-assignments/people). Every active filter is its own removable chip; "Filter zurücksetzen" clears the row.
  • States: empty-query hint, no-results echoing the query, loading, error + retry, and a gentle "Kein Treffer für: …" hint for tokens the server could not resolve.

Raw token syntax gets no UI, but does not break: the box text goes to q untouched and the server parses person:"…", year:2023, from:/to:, album:"…", favorite:.

Filter findings (worth knowing before merge)

  1. filters.personFilters does not echo personId parameters. SearchService.filterSummary is built from the parsed tokens only, so it lists nothing unless the user actually typed person:"Name". The chips therefore keep filter state in the ViewModel instead of re-reading it back from the response.
  2. unmatchedTokens carries only unmatched person: tokens. Unmatched album: tokens arrive separately in unmatchedAlbumTokens, and either one makes the whole query return zero items (AND semantics). Both lists are merged into the hint.
  3. year: is the only token that needs a conflict guard. year: combined with the year parameter — and from:/to: combined with it — is a hard 400, so a typed period token suppresses the parameter. favorite: needs no guard (the token simply wins server-side), and personId is documented to AND together with person: tokens.

Risks / limits

  • One page only. GET /api/search accepts no cursor and caps limit at 100, so a broad query truncates silently. Recorded as ISSUE-122.
  • No filter-only search. The endpoint requires q ≥ 2 characters, so chips with an empty box show the "type at least two letters" hint instead of browsing by filter.
  • SearchViewModel is activity-scoped (hoisted at MemoriesApp, outside the NavHost) because navigation-compose gives every destination its own ViewModelStore. It resets on session change so one family member's search never lingers under another's login.
  • ISSUE-121 (high) — found while wiring this up: NavHost scopes each destination to its own NavBackStackEntry store (verified in the navigation-compose 2.10.2 bytecode, LocalOwnersProvider), so the PHOTOS and MEDIA_DETAIL destinations get different TimelineViewModel instances and the comment claiming otherwise is wrong. Deliberately not fixed here — the timeline lane owns those files — but the search lane avoids the same trap by hoisting its ViewModel.
  • The header search icon only appears once the timeline has items, because the Photos header lives inside the non-empty branch (same as the existing refresh button).

Verification

cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug — BUILD SUCCESSFUL, 189 tests, 0 failures, 0 skipped (35 new: SearchViewModelTest 18, SearchQueryTest 7, SearchJsonTest 5, HttpSearchApiTest 5).

Rebased onto origin/main (2362ef77) before pushing. Not merging — for review.

Implements spec 055 task **T006 — Phase 1: Search screen** for the Android app. ## What you get - **Entry**: a "Suche" card at the top of the MEHR hub, plus a search icon in the Photos screen header (its own final commit so the timeline lane's conflict on `TimelineScreen.kt` stays a single, obvious hunk). - **Routes**: `search`, plus `searchMedia/{mediaItemId}` so a result tap opens the existing `MediaViewerScreen` over the *search* result list without touching the timeline's viewer route. - **Typing**: debounced-as-you-type — 300 ms, minimum two characters. A family member spelling out "Oma am Strand" gets one request when they stop, not five on the way. A filter tap re-runs immediately, because a tap is already a finished gesture. - **Filters**: `Favoriten` (toggle), `Jahr` (year picker, newest → 1970), `Person` (picker fed by `GET /api/person-assignments/people`). Every active filter is its own removable chip; "Filter zurücksetzen" clears the row. - **States**: empty-query hint, no-results echoing the query, loading, error + retry, and a gentle "Kein Treffer für: …" hint for tokens the server could not resolve. Raw token syntax gets **no UI**, but does not break: the box text goes to `q` untouched and the server parses `person:"…"`, `year:2023`, `from:`/`to:`, `album:"…"`, `favorite:`. ## Filter findings (worth knowing before merge) 1. **`filters.personFilters` does not echo `personId` parameters.** `SearchService.filterSummary` is built from the *parsed tokens* only, so it lists nothing unless the user actually typed `person:"Name"`. The chips therefore keep filter state in the ViewModel instead of re-reading it back from the response. 2. **`unmatchedTokens` carries only unmatched `person:` tokens.** Unmatched `album:` tokens arrive separately in `unmatchedAlbumTokens`, and either one makes the whole query return zero items (AND semantics). Both lists are merged into the hint. 3. **`year:` is the only token that needs a conflict guard.** `year:` combined with the `year` parameter — and `from:`/`to:` combined with it — is a hard 400, so a typed period token suppresses the parameter. `favorite:` needs no guard (the token simply wins server-side), and `personId` is documented to AND together with `person:` tokens. ## Risks / limits - **One page only.** `GET /api/search` accepts no `cursor` and caps `limit` at 100, so a broad query truncates silently. Recorded as ISSUE-122. - **No filter-only search.** The endpoint requires `q` ≥ 2 characters, so chips with an empty box show the "type at least two letters" hint instead of browsing by filter. - **SearchViewModel is activity-scoped** (hoisted at `MemoriesApp`, outside the NavHost) because navigation-compose gives every destination its own `ViewModelStore`. It resets on session change so one family member's search never lingers under another's login. - **ISSUE-121 (`high`)** — found while wiring this up: `NavHost` scopes each destination to its own `NavBackStackEntry` store (verified in the navigation-compose 2.10.2 bytecode, `LocalOwnersProvider`), so the PHOTOS and MEDIA_DETAIL destinations get *different* `TimelineViewModel` instances and the comment claiming otherwise is wrong. Deliberately **not** fixed here — the timeline lane owns those files — but the search lane avoids the same trap by hoisting its ViewModel. - The header search icon only appears once the timeline has items, because the Photos header lives inside the non-empty branch (same as the existing refresh button). ## Verification `cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug` — **BUILD SUCCESSFUL, 189 tests, 0 failures, 0 skipped** (35 new: `SearchViewModelTest` 18, `SearchQueryTest` 7, `SearchJsonTest` 5, `HttpSearchApiTest` 5). Rebased onto `origin/main` (`2362ef77`) before pushing. **Not merging** — for review.
Add GET /api/search plus the person-picker endpoint to the API layer, an
activity-scoped SearchViewModel, and a search screen reachable from the MEHR
hub: search box, Favoriten/Jahr/Person chips, a results grid, and a viewer
route over the same result list.

- Search runs as you type: 300 ms debounce, minimum two characters. A filter
  tap re-runs immediately, because a tap is already a finished gesture.
- `q` goes out exactly as typed, so raw tokens (person:"…", year:2023,
  from:/to:, favorite:) keep working — the server parses them.
- Structured filters travel as parameters, never as tokens. A typed
  `year:`/`from:`/`to:` suppresses the `year` parameter (the server answers
  400 for that combination); `favorite:` and `personId` need no such guard.
- The person picker reads GET /api/person-assignments/people. `filters.personFilters`
  only echoes typed `person:` tokens and never the explicit `personId` params,
  so filter state lives in the ViewModel rather than being re-read back.
- SearchViewModel is hoisted at the MemoriesApp level, outside the NavHost,
  because navigation-compose scopes every destination to its own
  NavBackStackEntry ViewModelStore — results must survive the trip into the
  viewer and back. It resets whenever the session changes.

35 new unit tests: debounce and query gate, filter params, unmatched-token
hint, people picker, error/retry, session expiry, SearchPage JSON shape, and
the query-string contract. All 189 tests green; :app:assembleDebug passes.

Records ISSUE-121 (timeline viewer's second TimelineViewModel instance),
ISSUE-122 (search has no pagination behind the 100-item cap) and ISSUE-123
(spec omits the mediaType/approval params the controller accepts).
feat(android): add search entry point to the Photos screen header
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 2s
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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m53s
09744e71e1
One icon button next to the existing refresh action, wired to the same SEARCH
route the MEHR hub uses. Kept in its own commit so the timeline lane's merge
conflict on TimelineScreen.kt stays a single, obvious hunk.

Bump to 0.1.6 (versionCode 7) per the release pattern set by the viewer
actions release.
chris force-pushed ux-android-search from 09744e71e1
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 2s
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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m53s
to 7510a9ea8b
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 2s
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 2m41s
2026-10-11 18:26:35 +02:00
Compare
chris merged commit e69e410e11 into main 2026-10-11 18:33:19 +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!1119
No description provided.