Make Android pane navigation adaptive with a fixed peek budget

Replace the per-level peek with a fixed total peek budget on wide windows
and drop the stack entirely on narrow ones, so a folded phone loses no
width to dead peek space and a deep stack never reserves more than the
budget.

- SlidingPaneStack gains a `wide` parameter (the callers pass the existing
  isWideLayout value). On a narrow window the budget is 0dp, so every
  pane's open offset is 0 and each opened pane is a full-window screen
  that springs in over the last; Back, the gesture and the pane's own back
  control pop one level and nothing is left on the left.
- On a wide window peekBudgetDp (PEEK_BUDGET_DP, 224dp) is the fixed total
  space shared between the covered panes, independent of depth, so the
  active pane's left edge is always exactly the budget and its width
  (hostWidth - budget) stays constant as levels are added. paneOpenOffsetsDp
  widens the leftmost strip first so it stays tappable after the start
  inset (min of PEEK_WIDTH_DP and the platform minimum interactive size),
  then splits the rest evenly. peekBudgetDp clamps so the active pane never
  collapses below MIN_ACTIVE_PANE_WIDTH_DP and paneWidthDp is never
  negative. All geometry is derived from the named tokens, the measured
  host width and the system insets - no new literals.
- The peek-strip hit targets now come from the shared offsets, and panes
  remain opaque, inset inside the safe area, hidden from accessibility when
  covered, and opening/closing stay exact mirrors through the same
  animators. PaneState documents the narrow (no peek) rule.
- SlidingPaneStackTest is rewritten around the pure budget geometry (narrow
  spends no peek, the wide active pane is constant width, four levels share
  one budget with every strip tappable, the budget clamps, tiny hosts never
  go negative), and android/README.md records the pass, its evidence and
  what was not verified.
This commit is contained in:
2026-10-15 23:49:10 +01:00
parent 5314542c13
commit 0b373d0c65
5 changed files with 309 additions and 72 deletions
@@ -5,8 +5,9 @@ import androidx.compose.runtime.saveable.Saver
/**
* Which pane of the sliding stack is showing: the list (level 0), the selected
* item's detail (level 1) and, when a stage/node is open, the stage pane
* (level 2). The panes stack left to right and each leaves a peek of the pane it
* covers.
* (level 2). On a wide window the panes stack left to right and share a fixed
* peek budget; on a narrow window only the topmost pane is visible and it fills
* the window.
*/
enum class MasterPane { List, Detail, Stage }
@@ -71,7 +72,8 @@ fun backStep(selection: PaneSelection): BackResult = when (selection.pane) {
* The selection after tapping the peek of the pane at [level]: every pane to its
* right is closed. Level 0 (the list) shows a bare list; level 1 shows the same
* item's detail with no stage; a [level] at or beyond the current depth is a
* no-op (there is nothing to its right).
* no-op (there is nothing to its right). Peeks exist only on a wide window;
* narrow windows use Back/gesture for the same one-level step.
*/
fun popTo(selection: PaneSelection, level: Int): PaneSelection = when {
level <= 0 -> PaneSelection()
@@ -208,6 +208,7 @@ private fun PipelineDestination(vm: AppViewModel, wide: Boolean, onOpenRun: (Lon
SlidingPaneStack(
depth = depth,
wide = wide,
onPopTo = { level -> selection = popTo(selection, level) },
backContentDescription = { level -> if (level == 0) "Back to pipelines" else "Back to pipeline" },
pane = { level, paneModifier ->
@@ -274,6 +275,7 @@ private fun RunsDestination(
SlidingPaneStack(
depth = depth,
wide = wide,
onPopTo = { level -> onSelectionChange(popTo(selection, level)) },
backContentDescription = { level -> if (level == 0) "Back to runs" else "Back to run" },
pane = { level, paneModifier ->
@@ -33,57 +33,103 @@ import androidx.compose.ui.unit.dp
import net.awan.pipelines.ui.MAX_PANE_DEPTH
/**
* The one named minimum width of the visible peek strip left of an open pane.
* The actual peek is derived from this and the platform's minimum interactive
* size, widened further by the left system-gesture inset so the *tappable* strip
* (after that inset) is still at least the minimum interactive size.
* The named dimension tokens behind the pane geometry. No screen hardcodes a
* peek width or a pane width; every offset and width is derived from these, the
* measured host width and the system insets.
*
* [PEEK_WIDTH_DP] is the minimum width of one covered pane's tappable peek.
* [PEEK_BUDGET_DP] is the fixed *total* peek budget a wide window may spend on
* all covered panes together, however deep the stack gets.
* [MIN_ACTIVE_PANE_WIDTH_DP] is the least width worth leaving to the active
* (topmost) pane before the budget has to be reduced.
*/
private val PEEK_WIDTH_DP = 56.dp
internal val PEEK_WIDTH_DP = 56.dp
internal val PEEK_BUDGET_DP = 224.dp
internal val MIN_ACTIVE_PANE_WIDTH_DP = 320.dp
/**
* The visible peek width: at least [PEEK_WIDTH_DP], and always wide enough that
* the tappable strip left after [startInset] is at least [minimumInteractive].
* Pure so the geometry is unit-testable without a device.
* The peek budget actually spent on a wide window: the fixed [PEEK_BUDGET_DP]
* token, reduced only when that would leave the active pane narrower than
* [MIN_ACTIVE_PANE_WIDTH_DP] on a small host. The budget never depends on the
* stack depth, so the active pane keeps a constant width as levels are added.
* Pure so the budget is unit-testable without a device.
*/
internal fun peekWidthDp(minimumInteractive: Dp, startInset: Dp = 0.dp): Dp =
maxOf(PEEK_WIDTH_DP, minimumInteractive + startInset)
internal fun peekBudgetDp(hostWidth: Dp, requested: Dp = PEEK_BUDGET_DP): Dp =
requested.coerceAtMost((hostWidth - MIN_ACTIVE_PANE_WIDTH_DP).coerceAtLeast(0.dp))
/**
* The x offset of pane [level] when it is open: one peek per level, so each
* covered pane keeps exactly one peek visible. Derived, never a magic offset.
* The open left offset of every pane `0..covered` on a wide window. `[0]` is the
* list at 0 and `[covered]` is the active pane at exactly [budget]; the covered
* panes therefore share that one fixed budget between them and the active pane
* keeps the constant width `hostWidth - budget` no matter how deep the stack is.
* The leftmost strip is widened first so that after [startInset] it still leaves
* [minPeek] tappable; the remaining budget is then split evenly between the other
* covered panes. A degenerate host clamps to whatever fits rather than
* overflowing. Pure, so the shared-budget geometry needs no device.
*/
internal fun paneOffsetDp(level: Int, peek: Dp): Dp = peek * level
internal fun paneOpenOffsetsDp(
covered: Int,
budget: Dp,
startInset: Dp,
minPeek: Dp,
): List<Dp> {
if (covered <= 0) return listOf(0.dp)
if (budget <= 0.dp) return List(covered + 1) { 0.dp }
if (covered == 1) return listOf(0.dp, budget)
val offsets = ArrayList<Dp>(covered + 1)
offsets += 0.dp
val first = minOf(budget, maxOf(budget / covered, startInset + minPeek))
offsets += first
val rest = budget - first
val steps = covered - 1
for (i in 2..covered) {
offsets += first + rest * (i - 1) / steps
}
return offsets
}
/**
* The width of pane [level]: the measured host width minus the peeks it leaves
* visible to its left. Derived from the measured width, never hardcoded.
* The width of the pane whose open left edge is [offset] on a wide window: from
* that offset to the host's right edge. The active pane therefore measures
* `hostWidth - budget`; a narrow host can never yield a negative width.
*/
internal fun paneWidthDp(hostWidth: Dp, level: Int, peek: Dp): Dp =
maxOf(0.dp, hostWidth - peek * level)
internal fun paneWidthDp(hostWidth: Dp, offset: Dp): Dp =
maxOf(0.dp, hostWidth - offset)
/**
* The one shared sliding pane stack: pane 0 (the list) fills the host and each
* deeper pane overlays the one below, sliding in from the right until a peek
* strip of the pane it covers stays visible on the left. Both the Pipelines and
* Runs destinations use this, so the motion and geometry live in exactly one
* place, and the stage pane is the same third level as the detail.
* The one shared sliding pane stack, adaptive to the window width. Both the
* Pipelines and Runs destinations use it, so the motion and geometry live in
* exactly one place and the stage pane is the same third level as the detail.
*
* On a **narrow** window ([wide] false) it is not a stack at all: there is no
* peek and no leftover strip, and each opened pane is a full-window screen that
* slides in over the last. On a **wide** window ([wide] true) the panes stack,
* but the space spent on the covered panes is a single fixed budget shared
* between them: the active pane's left edge is always exactly the budget, so it
* keeps a constant width and the stack never consumes more than the budget
* however deep it gets.
*
* [depth] is the number of visible panes minus one (0..[MAX_PANE_DEPTH]);
* [pane] composes the level's content and is expected to render nothing for a
* level whose selection is empty (so a closing pane simply slides back out).
* Tapping a covered pane's peek calls [onPopTo] with that pane's level, closing
* every pane to its right; [backContentDescription] names each strip.
* On a wide window, tapping a covered pane's peek calls [onPopTo] with that
* pane's level, closing every pane to its right; [backContentDescription] names
* each strip. On a narrow window there is no strip and Back/gesture/the pane's
* own back control pop the level.
*
* Every pane is always composed and each level has its own long-lived
* [animateDpAsState], so opening slides in and closing slides back out with no
* first-frame hack, and a rapid run of taps only retargets an existing animator
* (never half-slid). A covered pane is hidden from accessibility and made
* non-interactive so TalkBack focus follows the top pane and a tap can never leak
* through to a covered one; only its peek strip stays tappable.
* (never half-slid). Opening and closing are exact mirrors: the same offsets and
* [spring] retarget in reverse. A covered pane is hidden from accessibility and
* made non-interactive so TalkBack focus follows the top pane and a tap can never
* leak through to a covered one; on a wide window only its peek strip stays
* tappable.
*/
@Composable
fun SlidingPaneStack(
depth: Int,
wide: Boolean,
onPopTo: (Int) -> Unit,
modifier: Modifier = Modifier,
backContentDescription: (Int) -> String = { "Back" },
@@ -100,7 +146,18 @@ fun SlidingPaneStack(
val startInset = insetPadding.calculateLeftPadding(direction)
val topInset = insetPadding.calculateTopPadding()
val bottomInset = insetPadding.calculateBottomPadding()
val peek = peekWidthDp(LocalMinimumInteractiveComponentSize.current, startInset)
// Narrow: no peek at all (budget 0, every pane fills the host). Wide: one
// fixed budget shared between the covered panes. The platform's minimum
// interactive size is the floor for a tappable strip, never a literal.
val minPeek = maxOf(PEEK_WIDTH_DP, LocalMinimumInteractiveComponentSize.current)
val budget = if (wide) peekBudgetDp(hostWidth) else 0.dp
val offsets = paneOpenOffsetsDp(
covered = depth,
budget = budget,
startInset = startInset,
minPeek = minPeek,
)
// Pane 0 fills the host; it is blocked as soon as anything covers it.
pane(
@@ -114,13 +171,16 @@ fun SlidingPaneStack(
// beyond the depth sits off-screen and the caller renders nothing.
for (level in 1..MAX_PANE_DEPTH) {
val covered = level - 1
if (covered < depth) {
// The covered pane's tappable peek: clear of the status/nav bars,
// of the left gesture area (startInset) and, via the peek
// derivation, at least the minimum interactive size. Tapping it
// closes every pane to its right.
val stripOffset = if (covered == 0) startInset else peek * covered
val stripWidth = if (covered == 0) peek - startInset else peek
// The covered pane's tappable peek (wide windows only): the strip
// between this pane's offset and the next pane's, clear of the
// status/nav bars and of the left gesture area. Tapping it closes
// every pane to its right.
if (budget > 0.dp && covered < depth) {
val stripStart = offsets[covered]
val stripEnd = offsets[covered + 1]
val stripOffset = if (covered == 0) startInset else stripStart
val stripWidth = if (covered == 0) stripEnd - startInset else stripEnd - stripStart
Box(
Modifier
.align(Alignment.TopStart)
@@ -139,15 +199,20 @@ fun SlidingPaneStack(
)
}
// An open pane sits at its shared-budget offset; a closed one waits
// exactly off the right edge. Its width is already the width it will
// have when open, so it slides rather than grows.
val openOffset = if (level <= depth) offsets[level] else hostWidth
val openWidth = paneWidthDp(hostWidth, if (level <= depth) offsets[level] else budget)
val offset by animateDpAsState(
targetValue = if (level <= depth) paneOffsetDp(level, peek) else hostWidth,
targetValue = openOffset,
animationSpec = spring(),
label = "pane-slide-$level",
)
Box(
Modifier
.offset(x = offset)
.width(paneWidthDp(hostWidth, level, peek))
.width(openWidth)
.fillMaxHeight()
.then(if (level < depth) Modifier.blockPointerInput() else Modifier),
) {
@@ -1,48 +1,111 @@
package net.awan.pipelines.ui.components
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test
/**
* The pane geometry is pure, so the adaptive width rules are checked here without
* a device: a narrow window spends no peek at all, and a wide window spends one
* fixed budget shared between the covered panes however deep the stack gets.
*/
class SlidingPaneStackTest {
private fun assertDp(expected: Dp, actual: Dp, delta: Float = 0.01f) =
assertEquals(expected.value, actual.value, delta)
@Test
fun peekIsAtLeastTheNamedMinimum() {
// The named token (56dp) wins over a smaller platform minimum.
assertEquals(56.dp, peekWidthDp(minimumInteractive = 48.dp))
assertEquals(56.dp, peekWidthDp(minimumInteractive = 40.dp))
fun narrowWindowSpendsNoPeekAtAnyDepth() {
// Budget 0 is the narrow model: no stack and no leftover strip, so every
// pane's open offset is 0 (the host's left edge).
for (covered in 0..4) {
val offsets = paneOpenOffsetsDp(
covered = covered,
budget = 0.dp,
startInset = 30.dp,
minPeek = PEEK_WIDTH_DP,
)
assertEquals(covered + 1, offsets.size)
offsets.forEach { assertDp(0.dp, it) }
}
}
@Test
fun peekWidensSoTheStripIsStillTappableAfterTheGestureInset() {
// The left gesture inset eats 30dp; the visible peek grows so the
// tappable strip (peek - inset) is still the minimum interactive size.
val peek = peekWidthDp(minimumInteractive = 48.dp, startInset = 30.dp)
assertEquals(78.dp, peek)
assertTrue(peek - 30.dp >= 48.dp)
fun wideActivePaneKeepsAConstantWidthAtEveryDepth() {
val host = 800.dp
val budget = peekBudgetDp(host)
assertDp(PEEK_BUDGET_DP, budget)
// The active (topmost) pane's left edge is exactly the budget, so its
// width is host - budget no matter how many levels are open.
for (covered in 1..4) {
val offsets = paneOpenOffsetsDp(covered, budget, startInset = 0.dp, minPeek = PEEK_WIDTH_DP)
assertDp(budget, offsets.last())
assertDp(host - budget, paneWidthDp(host, offsets.last()))
}
}
@Test
fun peekWithoutInsetStaysTheNamedToken() {
assertEquals(56.dp, peekWidthDp(minimumInteractive = 48.dp, startInset = 0.dp))
fun fourLevelsShareTheOneFixedBudget() {
val offsets = paneOpenOffsetsDp(
covered = 3,
budget = PEEK_BUDGET_DP,
startInset = 0.dp,
minPeek = PEEK_WIDTH_DP,
)
// Four levels: the list plus three covered panes plus the active one.
assertEquals(4, offsets.size)
assertDp(PEEK_BUDGET_DP, offsets.last())
val strips = offsets.zipWithNext { a, b -> b - a }
assertEquals(3, strips.size)
// The three covered panes share the budget between them, not three peeks.
assertDp(PEEK_BUDGET_DP, strips.fold(0.dp) { acc, strip -> acc + strip })
strips.forEach { assertTrue("peek too thin to tap: $it", it >= PEEK_WIDTH_DP) }
}
@Test
fun paneOffsetIsOnePeekPerLevel() {
// Each open pane sits one more peek to the right, so the pane below keeps
// exactly its own peek visible.
assertEquals(0.dp, paneOffsetDp(level = 0, peek = 56.dp))
assertEquals(56.dp, paneOffsetDp(level = 1, peek = 56.dp))
assertEquals(112.dp, paneOffsetDp(level = 2, peek = 56.dp))
fun firstStripStaysTappableAfterTheGestureInset() {
val startInset = 30.dp
val offsets = paneOpenOffsetsDp(3, PEEK_BUDGET_DP, startInset, PEEK_WIDTH_DP)
// The leftmost strip is widened so the tappable part (after the inset)
// still measures at least the named minimum.
val firstStrip = offsets[1] - offsets[0]
assertTrue(firstStrip - startInset >= PEEK_WIDTH_DP)
}
@Test
fun paneWidthIsTheHostLessItsPeeks() {
assertEquals(411.dp, paneWidthDp(hostWidth = 411.dp, level = 0, peek = 56.dp))
assertEquals(355.dp, paneWidthDp(hostWidth = 411.dp, level = 1, peek = 56.dp))
assertEquals(299.dp, paneWidthDp(hostWidth = 411.dp, level = 2, peek = 56.dp))
// Never negative when the host is narrower than the stacked peeks.
assertEquals(0.dp, paneWidthDp(hostWidth = 100.dp, level = 2, peek = 56.dp))
fun budgetShrinksSoTheActivePaneNeverCollapses() {
// A host narrower than the ideal leaves room for: the budget is clamped
// so the active pane keeps at least the named minimum width.
val host = 400.dp
val budget = peekBudgetDp(host)
assertTrue(budget >= 0.dp)
assertTrue(paneWidthDp(host, budget) >= MIN_ACTIVE_PANE_WIDTH_DP)
}
@Test
fun tinyHostNeverProducesNegativeGeometry() {
assertDp(0.dp, peekBudgetDp(100.dp))
val offsets = paneOpenOffsetsDp(3, peekBudgetDp(100.dp), 0.dp, PEEK_WIDTH_DP)
offsets.zipWithNext { a, b -> assertTrue(b >= a) }
offsets.forEach { assertTrue(paneWidthDp(100.dp, it) >= 0.dp) }
}
@Test
fun offsetsAreMonotonicAndDeterministic() {
// Same inputs give the same offsets (opening and closing are mirrors),
// and the panes never overlap in the wrong order.
val a = paneOpenOffsetsDp(3, PEEK_BUDGET_DP, 30.dp, PEEK_WIDTH_DP)
val b = paneOpenOffsetsDp(3, PEEK_BUDGET_DP, 30.dp, PEEK_WIDTH_DP)
assertEquals(a, b)
a.zipWithNext { x, y -> assertTrue(y >= x) }
}
@Test
fun paneWidthIsHostLessOffsetAndNeverNegative() {
assertDp(411.dp, paneWidthDp(411.dp, 0.dp))
assertDp(355.dp, paneWidthDp(411.dp, 56.dp))
assertDp(0.dp, paneWidthDp(100.dp, 200.dp))
}
}