Files
pipelines/docs/notes/bottom-selector-strip.md
T
alan 49f40bfe45 android: move the detail and visit selectors to a bottom strip on narrow windows
The two selectors that were a horizontally scrolling Material 3 tab row at
the top of a surface become one deliberate treatment. On a narrow window the
shared detail selector (`DetailTabs`) and the visit selector are now the shared
bottom strip (`ui/components/SelectorStrip.kt`), pinned in the thumb zone above
the system gesture inset with the content filling the area above; a wide window
keeps the left rail for the detail selector and the pinned top row for visits.

- SelectorStrip: the one bottom strip plus its pure model (`SelectorEntry`,
  `SelectorPlacement`, `detailSelectorPlacement`, `visitSelectorPlacement`,
  `selectorStripShown`, `detailSelectorEntries`, `visitSelectorKey/Label`,
  `visitMarker`, `visitSelectorEntries`). Each entry keeps at least the platform
  minimum touch target, shows its whole label, and a visit shows its recorded
  status/outcome as a small `RunStatusIcon` marker rather than an invented one.
  Selection is carried by tab semantics and container colour, not colour alone.
  A single entry (or none) draws no strip.
- `DetailTabs` narrow branch replaced by `SelectorStrip` after the panel in a
  Column; the wide rail is unchanged.
- `StageDetailPane`: `StageVisitStrip` is the narrow visit selector; the bodies
  put a `weight(1f)` scroll above it and keep the top row only on a wide window.
  The stage definition section still shows no strip.
- `SessionExport`: `SessionExportSection` gains `visitTabs` so the narrow pane
  does not render the visit selector twice.
- `PipelinesApp`: the strip publishes its measured height through the new
  `LocalBottomStripInset`/`BottomStripInset`, and the floating pill's overlay
  lifts by `pillBottomOffset(stripHeight) = SPACING_L + stripHeight` (pure, zero
  when no strip is up), so the pill never overlaps the strip.
- Tests: new `SelectorStripTest` (placements, single-entry no strip, detail
  entries keep tab keys/titles/icons, visit labels and markers, stable visit
  keys) and a new `PipelinesNavTest` case pinning the pill lift.

Pill/strip clearance is the brief's "pill moves clear of the strip" option,
implemented once in `pillBottomOffset`. All geometry and motion come from the
existing named tokens and the layout; no new dependency.

Documentation checked: no packaged OpenCode skill reference (`internal/author/
skill/references/`) or packaged template (`examples/*.md`) documents the app's
detail/visit selector presentation, so neither is stale and `internal/author/
install.go`'s managed inventory needs no change. The shared `android/README.md`
is made stale by this change (the narrow tab-row wording at lines ~182-184,
~233-235 and ~487-488) and is recorded for the single `docs-fold` writer in the
new `docs/notes/bottom-selector-strip.md` rather than edited here.
2026-10-18 00:50:15 +01:00

124 lines
8.8 KiB
Markdown

# The detail and visit selectors: a bottom strip narrow, the rail wide
## What this item changed
`android/` only, the two selectors that used to be a horizontally scrolling Material 3
tab row at the top of a surface.
- `ui/components/SelectorStrip.kt` (new) — the one bottom selector strip, plus its pure
model. `SelectorEntry(key, label, icon, marker)`, `SelectorPlacement` (`Rail` / `TopRow`
/ `BottomStrip`), `detailSelectorPlacement(wide)`, `visitSelectorPlacement(wide)`,
`selectorStripShown(entryCount)`, `detailSelectorEntries(tabs)`,
`visitSelectorKey/Label(index)`, `visitMarker(step)`, `visitSelectorEntries(runSteps)`;
the `BottomStripInset` cell and `LocalBottomStripInset` the strip publishes its measured
height through; and the `SelectorStrip` composable (a full-width `Surface`, a hairline
top divider, one horizontally scrolling row of entries, each entry at least the platform
minimum touch target, the selected one carried by `Role.Tab` + selected state and the
container colour, a visit's recorded state shown as a small `RunStatusIcon` marker, and
a single entry drawing no strip at all).
- `ui/components/DetailTabs.kt` — the narrow branch's `PrimaryScrollableTabRow` is replaced
by `SelectorStrip(detailSelectorEntries(tabs), …)` **after** the panel in a `Column`, so
the content fills the area above the strip and the selector sits in the thumb zone. The
wide branch is unchanged (the left `RailTab` rail). The `@OptIn(ExperimentalMaterial3Api)`
and the `PrimaryScrollableTabRow`/`Tab` imports are gone.
- `ui/graph/StageDetailPane.kt` — `StageVisitTabs` stays the pinned **wide** visit row (now
labelling each visit through `visitSelectorLabel`); new `StageVisitStrip` is the narrow
form, the shared `SelectorStrip` fed by `visitSelectorEntries(runSteps)` (labels `visit N`
plus each visit's recorded status/outcome marker). `StageDetailBody` and `StageSectionBody`
put the strip below a `weight(1f)` scroll on a narrow window and keep the top row on a wide
one; a section that does not change per visit (`Stage definition`) still shows no strip.
The session branch composes `DetailTabBody` with `weight(1f)` above the strip.
- `ui/graph/SessionExport.kt` — `SessionExportSection` gains `visitTabs: Boolean` (passed as
`wide`), and `SessionHeader` renders the pinned visit row only when it is true, so the
narrow pane does not show the visit selector twice.
- `ui/PipelinesApp.kt` — the bottom strip's measured height is published to the content
through `LocalBottomStripInset` (a `BottomStripInset` cell created in the shell), and the
floating pill's overlay `Column` lifts by it: `pillBottomOffset(stripHeight) = SPACING_L +
stripHeight` (pure, new). So the pill moves clear of the strip while it is shown — the
chosen of the brief's two options — implemented once, and zero when no strip is up.
- Tests — `ui/components/SelectorStripTest.kt` (new: the placements, one-entry shows no
strip, the detail entries keep every tab key/title/icon so per-entry saved state is keyed
the same, the visit labels with their recorded markers, no marker for a visit with no
recorded state, the stable per-visit key) and `PipelinesNavTest` (the pill lifts by
exactly the strip height and keeps its margin with none). The existing `DetailTabsTest`
clamping/state tests and `StageDetailSheetTest` visit tests are unchanged and still pass.
## Shared documents this change makes stale
`android/README.md` documents the app's selector presentation and is written here rather
than edited in place; the `docs-fold` writer should update it.
- `android/README.md:182-184` — the bullet ending "Narrow windows show a horizontally
scrolling `PrimaryScrollableTabRow`; wide windows show an always-visible selectable rail
(icon + label, no collapse control)." should read "Narrow windows show the shared
`SelectorStrip` pinned to the bottom of the surface, in the thumb zone, with the panel
filling the area above it; wide windows show an always-visible selectable rail on the
left (icon + label, no collapse control)." The rest of the bullet (the in-place
`Crossfade`, no lateral motion, the per-section `rememberSaveableStateHolder` keyed by
the tab key, `clampTabIndex`) is still true.
- `android/README.md:233-235` — "The section index presentation does follow the window
width: a narrow window shows the tab row across the top, a wide window the always-visible
side rail…" should read "…a narrow window shows the bottom selector strip, a wide window
the always-visible side rail…".
- `android/README.md:487-488` — the Timeline + visit tabs bullet's "shows a `visit 1..N`
tab row only when there is more than one visit" should read "shows a `visit 1..N` row
(the pinned top row on a wide window, the bottom strip on a narrow one, each visit's
recorded state as a small marker) only when there is more than one visit".
- Append the dated section below at the end of `android/README.md`, after the last record.
```markdown
## The detail and visit selectors: a bottom strip narrow, the rail wide (18 Oct 2026)
Both selectors that were a horizontally scrolling Material 3 tab row at the top of a
surface are now one deliberate treatment: the shared detail selector (`DetailTabs`, the
pipeline and the run detail) and the visit selector (`StageVisitTabs`). On a **narrow**
window the selector is the shared `SelectorStrip` pinned to the bottom of the surface, in
the thumb zone above the system gesture inset, with the content filling the area above it;
on a **wide** one the detail selector keeps its existing left rail and the visit selector
its pinned top row. `android/` only; no new dependency (still only the declared
`material-icons-extended`), no Pipelines server/Go/installer/Docker file touched and no run
started from the app; the build and unit tests only, no device command run.
- **One shared strip.** `ui/components/SelectorStrip.kt` holds the strip and its pure
model: `SelectorEntry(key, label, icon, marker)`, `SelectorPlacement` (`Rail` / `TopRow` /
`BottomStrip`), `detailSelectorPlacement(wide)` / `visitSelectorPlacement(wide)`,
`selectorStripShown(entryCount)`, `detailSelectorEntries(tabs)`, `visitSelectorKey/Label`,
`visitMarker(step)` and `visitSelectorEntries(runSteps)`. A single entry (or none) draws
no strip, so a single-visit stage and a one-section surface stay strip-free.
- **Legible, unmistakable, token-driven.** Each entry keeps at least the platform minimum
touch target and shows its whole label (an ellipsis only if the row is scrolled), carries
the rail's glyph where the model has one, and shows a visit's recorded status/outcome as a
small marker (`RunStatusIcon`) — never a stand-in for data the model does not carry. The
selected entry is conveyed by `Role.Tab` + selected state and the container colour, not
colour alone. Every dimension is an existing `Dimens` token or the layout; no new
hardcoded value.
- **The pill moves clear of the strip.** The strip publishes its measured height through the
new `LocalBottomStripInset` (`BottomStripInset`), and the floating pill's overlay lifts by
`pillBottomOffset(stripHeight) = SPACING_L + stripHeight` — the one of the brief's two
options, implemented once and zero when no strip is up (a unit test pins both). The pane
stack's Back gesture and the in-place `Crossfade` swap are untouched, and each section's
own saved state is still keyed by its tab key.
- **Evidence.** `<gradle> --offline --no-daemon :app:assembleDebug :app:testDebugUnitTest`
→ `BUILD SUCCESSFUL`; the 69 result XMLs aggregate to **654 tests, 0 failures, 0 errors,
0 skipped**. New `SelectorStripTest` (7 tests) and one new `PipelinesNavTest` case.
`app-debug.apk` 18,700,429 bytes, sha256
`5b5bb9e0d67586c0a964853097be89842fc99053f428d4d24905fda1aaa71af3`, published as
`pipelines-debug-wip-d9619ea.apk` (`HTTP/1.1 200 OK`, the published bytes
Content-Length-matching the local file). Built in a worktree at `d9619ea`, which is
`main`'s tip, so no feature of `main` is missing from it.
Not verified in this pass: how the strip and the lifted pill actually render, and the
screenshots the brief names (the pipeline and run detail on a narrow window, a stage detail
with more than one visit, the single-entry case, and the wide rail) — that needs the device,
which this build-and-unit-test pass did not use; visual review owns the operator's Pixel 9
Pro XL.
```
## Not stale
- No packaged OpenCode skill reference (`internal/author/skill/references/`) documents the
app's detail/visit selectors; they describe the server, the CLI and the pipeline authoring
model. No packaged template (`examples/*.md`) and no `internal/author/` managed file names
them, so `internal/author/install.go`'s inventory needs no change.
- `android/AGENTS.md` lists `ui/components/` and `ui/graph/` generically and needs no change.