feat(android): Phase 1 viewer actions — favorite, share, download, trash, info sheet #1116
Loading…
Reference in a new issue
No description provided.
Delete branch "ux-android-viewer-actions"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Spec 055 task T005 (Phase 1 viewer actions). Builds on Phase 0 PR #1112 and the Phase 0 IA shell PR #1114.
What you get
A second row in the viewer chrome, directly under the existing top bar and wearing the same 80% black scrim so the two rows read as one block:
favorite · share · save · details · trash
The actions are spread evenly rather than packed left — the row is an action bar, and its width changes with how many actions the current item actually has (the save button disappears when there is nothing to save). A bottom bar was considered and rejected: it would sit on top of the video controls row, which would have meant threading state between two unrelated composables to stop them colliding.
Favorite flips optimistically and reverts with a Retry action if the server disagrees. Tapping the heart before that item's detail has ever been loaded fetches the detail first rather than guessing — otherwise the first tap on an already-favorited photo would appear to do nothing, because the client would assume "not a favorite" and POST a value that was already true.
Share hands the Android share sheet the photo file (staged from the preview rendition and delivered through a FileProvider); videos, and any photo that cannot be staged, fall back to the web media page (
{serverUrl}/media/{id}). See "Decisions" below.Save downloads the preview rendition into
Pictures/Memoriesthrough MediaStore. minSdk 29 means scoped storage, so there is no runtime permission to request; the row is heldIS_PENDINGuntil the bytes are fully written, so a failed save never leaves a half-written entry visible in the gallery. Progress shows as a pill stacked under the snackbar, and both live outside the chrome so a save outlives a chrome hide. The save button is hidden whenpreviewUrlis absent — a button that can only fail is worse than no button.Trash asks for confirmation in plain language first ("Es landet zuerst im Papierkorb und kann wiederhergestellt werden."), then POSTs, then shows "Zum Papierkorb verschoben" with an Undo action that restores. The item is dropped from the pager so the next photo slides into its place. If that empties the list — one photo in the whole album — the screen holds on the empty state until Undo resolves instead of navigating away with the snackbar still up.
Info is a bottom sheet that renders only fields the payload actually carries: capture date, duration, title, description, things. No dashes for missing data, no placeholders, no raw JSON, no internal field names.
Findings that shaped the implementation
1. The OpenAPI document is wrong about trash and restore. It advertises
200 + MediaDetail. The controller is annotated@ResponseStatus(NO_CONTENT), so the running server answers 204 with an empty body — and the web client already types both asvoid. A client generated from the spec would try to decode a body that never arrives. The app is implemented against observed behaviour (executeEmpty(): any 2xx, body ignored), andHttpMediaActionsApiTestpins that. Filed as ISSUE-116; the fix belongs to the API spec, not the app.2.
MediaDetailcarriesthingsbut no persons/faces. The info sheet therefore cannot say who is in a photo, even though faces and person names exist server-side. Rather than invent a row, it simply does not offer one. Filed as ISSUE-117.3. No original file is downloadable. There is no user-facing
/api/media/{id}/originalcontroller (OpenAPI marks it "not currently exposed"; only the worker-scoped variant exists) andvideo_previewreportsvideo_preview_not_implemented. Saving the original is therefore impossible today — the same gap already recorded as ISSUE-115. The Save action saves the preview rendition only, and says so in the PR text rather than pretending otherwise. Once an original-stream endpoint lands, extending this is a one-method change inMediaDownloader.Decisions worth a second look
Share target. Revised after review. The product decision is that recipients may have no account and no route to the server, so sharing must hand them the actual picture — the standard family UX, like Google Photos. Photos are therefore fetched into
cacheDir/share/and passed toACTION_SENDas a content uri from aFileProvider(authority${applicationId}.share,FLAG_GRANT_READ_URI_PERMISSION); the bytes are written under a.partname and renamed into place, so a racing tap can never publish a truncated JPEG, and only that one subdirectory is exposed to foreign apps. The decision lives inShareTarget.kt#decideShareTarget— a pure function, unit-tested — rather than inside the ViewModel, so photo/video/failure can be exercised without Android types. Videos keep URL-text sharing because no video rendition exists yet (ISSUE-115), with a snackbar telling the sender recipients must be signed in; a photo that fails to stage, or aFileProviderpath that is refused, falls back to the same{serverUrl}/media/{id}link with a note, so a share tap is never a dead end.previewUrlwas never a viable link target: it sits behind bearer auth, so a recipient would hit a login wall.Chrome layout. Second actions row instead of a bottom bar, for the reason given above.
MediaViewerViewModelholds no Context. It emits typedViewerEvent/ViewerMessageKindvalues through a channel and the screen resolves them against resources. That keeps the whole optimistic-favorite / trash / retry / restore logic JVM-testable, and it is why the screen owns a localSnackbarHostState— the viewer is full-bleed black, so the app-level snackbar would have sat behind the bottom nav.Favorite state resolution.
favorites[id] ?: details[id]?.favorite ?: false, with the user's own in-flight choice always winning over a detail response that is racing it. A detail response never clobbers a key the user has already set.Scope discipline
ui/MemoriesApp.ktchanges by four lines (one import, oneviewModel(), two parameters), to stay clear of the concurrent nav-shell lane.TimelineViewModelgainedremoveItem(id), which only touches the loaded list — pagination reads the stored cursor, not the list, so removing the last loaded item cannot stall the timeline (pinned by a test).Verification
New coverage:
HttpMediaActionsApiTest— MockWebServer contract tests for the five endpoints: paths, bearer headers, themetadataClass/valuebody,204-empty for trash/restore,403 → ForbiddenApiException,401 → UnauthorizedApiException.MediaViewerViewModelTest— detail load (once, seeding favorite + absolute URLs, non-blocking), optimistic favorite while in flight, unfavorite-via-DELETE, the first-tap fetches-first regression guard, favorite failure → revert + working retry, forbidden → owner-only, trash/restore event flow, trash retry, download progress + bearer token + failure + no-preview, share link, filename, plus the share flow (photo staged →ShareReady, staging failure → link fallback, video → link without staging, no-preview → link, no-link + no-preview → nothing, missing session → re-login, in-flight debounce).ShareTargetTest— the pure share-target decision: photo → file, unknown type → photo, video → link with or without a rendition, blank preview → link, photo can still stage without a known link,Nothingwhen neither is available, and web-link normalisation.TimelineViewModelTest—removeItemshifts the following item into place, ignores unknown ids, does not stallload-more.ViewerDateTest— duration formatting and its null/zero/negative cases.All user-visible strings are in
values/(German),values-en/,values-da/; keys and format placeholders verified consistent across the three locales.Risks
decideShareTarget. Note the wording when a photo fails to stage says the link was shared while the photo could not be prepared — accurate, but the recipient then gets a link rather than the picture.ShareIntent.Nothingreusesviewer_no_preview_save. Reachable only when there is no session link and no rendition (effectively logged out), and its wording says "save" rather than "share". Cosmetic and near-unreachable; a dedicated string would fix it if anyone minds.Long, so that wait can be a few seconds.memories-{mediaItemId}.jpg, which is stable and collision-free but not human-readable. Deliberate: it avoids guessing at a title the server may not have.Follow-up commit: share the photo file
Second commit on this branch, addressing the share-target risk above.
media/MediaShareCache.kt+media/AndroidShareCache.kt— stages a rendition intocacheDir/share/via.part-then-rename, so no partially written file is ever handed out.media/RenditionHttp.kt— the HTTP rendition fetch factored out ofAndroidMediaDownloaderand shared by save and share, so the two paths cannot drift.ui/timeline/ShareTarget.kt—decideShareTarget()/shareWebLink()/shareFileName(), the testable decision.res/xml/file_paths.xml+ aFileProviderentry inAndroidManifest.xmlexposing onlycache-path "share".MediaViewerViewModel—sharing/preparingstate,ShareReadyandShareLinkevents;shareTextnow delegates toshareWebLink.MediaViewerScreen— the progress pill readsdownloads ?: preparingand labels itself accordingly (the save icon no longer shows busy while a share is preparing),shareFile()builds theACTION_SEND, andstartChooser()is shared with the text path.viewer_share_preparing/viewer_share_video_link/viewer_share_link_fallbackin de, en and da.Verification for this commit:
./gradlew :app:testDebugUnitTest :app:assembleDebug— BUILD SUCCESSFUL, 154 tests, 0 failures, APK assembled. CI on the PR: Android unit tests and debug APK success, Run scoped PR tests success, non-Android scopes correctly skipped.Not merged — left for orchestrator review.
Extend MemoriesApi/HttpMemoriesApi with the endpoints the Phase 1 viewer needs: GET /api/media/{id}, POST/DELETE /api/media/{id}/metadata-overrides for the favorite toggle, and POST /api/media/{id}/trash plus /restore. Implemented against observed server behaviour rather than the OpenAPI document: the controller is annotated @ResponseStatus(NO_CONTENT), so trash/restore answer 204 with an empty body while the spec claims 200 + MediaDetail. executeEmpty() accepts any 2xx and ignores the body, which matches what the web client already does. Adds ForbiddenApiException, mapped from 403, so the screen can say "only the owner can do this" instead of showing a generic failure.Adds a second row to the viewer chrome (favorite, share, save, details, trash) directly under the existing top bar with the same 80% black scrim, so both rows read as one block. A bottom bar was ruled out because it would overlap the video controls row. Favorite flips optimistically and reverts with a Retry snackbar action if the server disagrees; tapping the heart before the item's detail has ever loaded fetches it first rather than guessing, so the first tap on an already-favorited photo actually does something. Share hands the system share sheet the web media page ({serverUrl}/media/{id}) rather than previewUrl, which sits behind bearer auth and would open a login wall for the recipient. Download saves the preview rendition into Pictures/Memories through MediaStore (minSdk 29, so no runtime permission), with an IS_PENDING guard so a failed write never leaves a half-written row. Progress shows as a pill stacked under the snackbar; both live outside the chrome so a save outlives a chrome hide. The original file cannot be saved — there is no user-facing /original endpoint (see ISSUE-115) — so only the preview is ever offered and the control disappears when previewUrl is absent. Trash asks for confirmation in plain language first, then POSTs, shows "Zum Papierkorb verschoben" with an Undo action that restores, and drops the item from the pager so the next photo takes its place. If that empties the list, the screen holds on the empty state until Undo resolves instead of navigating away with the snackbar still up. The info bottom sheet renders only fields the payload actually carries — capture date, duration, title, description, things — never placeholders, never raw JSON, never internal field names. MediaDetail has no persons field, so people are simply not offered (ISSUE-117). MediaViewerViewModel holds no Context: it emits typed events and messages that the screen resolves against resources, which keeps it JVM-testable. MemoriesApp.kt changes are four lines (one import, one viewModel(), two parameters) to stay clear of the concurrent nav-shell lane.Recipients may have no account and no route to the server, so the share sheet now hands them the actual picture — standard family UX, like Google Photos. - Stage the preview rendition into cacheDir/share and pass it to ACTION_SEND through a FileProvider (${applicationId}.share) with FLAG_GRANT_READ_URI_PERMISSION. Bytes land under a .part name and are renamed into place, so a racing tap can never hand over a truncated JPEG, and only that one subdirectory is exposed to foreign apps. - Videos keep URL-text sharing: no video rendition exists yet (ISSUE-115), so the sender is told recipients must be signed in. - A photo that fails to stage, or a FileProvider path that is refused, falls back to the same web link with a note — a share tap is never a dead end. - Extract the photo/video/failure decision into decideShareTarget(), a pure function free of Android types, so it is unit-testable. - Factor the HTTP rendition fetch into one helper shared by the MediaStore save and the cache staging, so the two paths cannot drift apart. Strings added in de (default), en and da. Verification: ./gradlew :app:testDebugUnitTest :app:assembleDebug — 154 tests, 0 failures, APK assembled.