Add named motion tokens and animate list item changes

Introduce ui/components/Motion.kt beside the pane dimension tokens: two
named duration+easing tokens, MotionQuick (120ms) for small in-place state
changes and MotionStandard (220ms) for content that moves or swaps, under a
300ms MAX_MOTION_MILLIS cap. Every animation call site now asks a token for
its spec instead of writing a duration: the pane slide and section
Crossfade use MotionStandard, the section chevron uses MotionQuick, and the
pane-pop stagger moves in as MOTION_STAGGER_MILLIS (the old
PANE_SLIDE_* / SECTION_SWAP_MILLIS constants are gone).

Add a single LazyItemScope.animateListItem() helper (ListRow.kt) wrapping
the supported Modifier.animateItem with the tokens: items fade in/out
(MotionQuick) and slide to new positions on refresh, filter or re-sort
(MotionStandard). Pipelines rows, run rows, version rows and evidence rows
use it. Specs are built at composition time (no per-frame allocation) and
the chevron reads its angle inside graphicsLayer so it turns without
recomposing the header; resting layout is unchanged and the standard
animator duration scale still applies, so disabled animations are instant.

Add MotionTest covering token ordering, per-token bands, the cap, monotonic
easings, self-reversal and spec timing; SlidingPaneStackTest now reads the
pane timing from the token. Document the change and its verification in
android/README.md.
This commit is contained in:
2026-10-16 09:55:41 +01:00
parent 0b74903a00
commit 934994d7f7
12 changed files with 296 additions and 37 deletions
+75
View File
@@ -2011,3 +2011,78 @@ Not verified in this pass: the link fallback on-device (the reachable server ran
the file path); a narrow-window layout of the selection bar; receiving the bulk
share in a third-party app (the chooser was observed, not an import).
### Named motion tokens and animated list changes (16 Oct 2026, run 104/1)
Every animation duration and easing now lives in one file, and the pipelines and
runs lists animate per item instead of cutting.
- **One motion token file.** `ui/components/Motion.kt` (beside the pane's
dimension tokens in `SlidingPaneStack.kt`) defines two named tokens, each a
duration + easing pair: `MotionQuick` (120ms) for small in-place state changes
(the section chevron, a list row appearing/leaving) and `MotionStandard`
(220ms) for content moving or swapping (a pane sliding, a section
cross-fading, an item taking a new place in a re-sorted list). Nothing exceeds
the `MAX_MOTION_MILLIS` (300ms) cap and both easings are monotonic
ease-in-out curves; `MotionStandard` is symmetric, which is what keeps a pane
close the exact reverse of its open. A call site asks a token for its concrete
spec via `spec()`; it never writes a duration. The pane slide, the section
`Crossfade` and the chevron now use the tokens (`PANE_SLIDE_*` /
`SECTION_SWAP_MILLIS` are gone), and the pane pop stagger moved in as
`MOTION_STAGGER_MILLIS`.
- **Per-item list animation.** A single shared `LazyItemScope.animateListItem()`
(`ListRow.kt`) wraps Compose's supported `Modifier.animateItem(fadeInSpec,
placementSpec, fadeOutSpec)` with the tokens: an item fades in as it appears
and out as it leaves (`MotionQuick`), and the items still on screen slide to
their new positions when the list is refreshed, filtered or re-sorted
(`MotionStandard`) rather than jumping. Pipelines rows, run rows, pipeline
version rows and run evidence rows all use it. Because it is the supported
lazy-list item animation the list keeps its own scroll/measure state; the
modifier only drives the transition, so a resting list is unchanged.
- **System animation setting.** The tokens map onto Compose's standard
animations, so the platform animator duration scale applies unchanged: with
animations disabled each spec runs for zero time and an item is at its final
state at once, no special case.
- **No per-frame allocation.** Specs are built at composition time, not per
frame, and the chevron reads its animating angle inside the layer
(`graphicsLayer { rotationZ = … }`) so it turns without recomposing the header
each frame.
Verified on `emulator-5554` only (fold layout, 2076x2152 / 390dpi ≈ 852dp,
against the live server; never the attached Pixel):
- `gradle :app:assembleDebug :app:testDebugUnitTest --offline --console=plain`
(Gradle 9.7.1, JDK 17, `ANDROID_HOME` set) → `BUILD SUCCESSFUL`.
`gradle :app:testDebugUnitTest --rerun-tasks --offline` re-ran every result XML
to **174 tests across 22 classes, 0 failures, 0 errors, 0 skipped**; the new
`MotionTest` (6 cases) checks the token ordering (quick shorter than standard),
the per-token bands (quick 100-150ms, standard 200-250ms), the ≤300ms cap, that
every easing is monotonic `0→1`, that `MotionStandard` reverses itself, and
that a spec carries its token's timing. `SlidingPaneStackTest` now reads the
pane's timing from the token.
- **Filter change** (`filter.mp4`, frames `sheet1.png`/`sheet2.png`): at
`animator_duration_scale 5`, typing `docker` into the pipelines search fades
the non-matching rows out and moves the survivors up; deleting it brings the
rows back in.
- **A new run arriving** (`newrun.mp4`, frames `newrun_arrival.png` /
`newrun_sheet1.png`): run 105 was admitted out-of-band with
`pipelines run --json --pipeline 8 … --yes` (**not** from the app); tapping
Refresh in the Runs list shows run 105 fade in at the top while every existing
row slides down to make room. Run 105 then failed (its stage returned
`blocked`), so nothing had to be reclaimed.
- **Reduced motion** (`red_sheet.png`): at `animator_duration_scale 0`, typing
`d`/`do`/`doc`/`dock` leaves each captured frame fully settled — no ghosted or
half-placed rows — i.e. the change is instant with no partial state.
- `adb -s emulator-5554 logcat -d` held 0 `FATAL EXCEPTION` / 0
`E AndroidRuntime` lines; `animator_duration_scale` was left at 1.
- **APK publish.** `app-debug.apk` (17,913,089 bytes, sha256 `4bc1b781…`) copied
to `~/.local/share/pipelines/data/artifacts/104/1/pipelines-debug-wip-0b74903.apk`
(`0b74903` = `git rev-parse --short HEAD`); `curl -I
http://10.0.0.249:8080/artifacts/104/1/pipelines-debug-wip-0b74903.apk` returned
`HTTP/1.1 200 OK`, `Content-Type: application/vnd.android.package-archive`,
`Content-Length: 17913089`, and a streamed `curl | shasum -a 256` returned the
same `4bc1b781…`.
Not verified in this pass: a narrow-window frame of the item animation; an item
leaving a list (a run being deleted is not a client action), only the
appear/move halves driven above.
@@ -1,7 +1,6 @@
package net.awan.pipelines.ui.components
import androidx.compose.animation.Crossfade
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
@@ -115,7 +114,7 @@ fun DetailTabs(
val swap: @Composable (Modifier) -> Unit = { contentModifier ->
Crossfade(
targetState = selected,
animationSpec = tween(durationMillis = SECTION_SWAP_MILLIS),
animationSpec = MotionStandard.spec(),
modifier = contentModifier,
label = "section-swap",
) { index ->
@@ -277,8 +276,5 @@ fun rememberSectionExpansion(
/** The always-visible wide section rail's width (icons with labels). */
private const val WIDE_RAIL_WIDTH_DP = 200
/** The in-place section swap's cross-fade duration in milliseconds (short). */
private const val SECTION_SWAP_MILLIS = 180
/** Comfortable max text width for a tab body on a wide window. */
const val DETAIL_MAX_WIDTH_DP = 840
@@ -6,6 +6,7 @@ import androidx.compose.foundation.layout.ColumnScope
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyItemScope
import androidx.compose.foundation.selection.selectable
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.LocalContentColor
@@ -70,3 +71,26 @@ fun ListRow(
}
}
}
/**
* The one per-item animation for the app's lazy lists (pipelines, runs, version
* and evidence rows). It is Compose's supported lazy-list item animation
* (`Modifier.animateItem`, not the deprecated placement-only one), so the list
* keeps its own scroll/measure state and is never re-measured or janked:
*
* - an item fades in as it appears and out as it leaves ([MotionQuick], a small
* in-place state change);
* - while it is on screen and the list is refreshed, filtered or re-sorted, it
* slides to its new position ([MotionStandard]) instead of jumping;
* - the item's resting appearance is untouched — the modifier only drives the
* transition, so the settled list is exactly the list without it.
*
* The specs are built here at composition time, not per frame, and every token
* maps the system animator duration scale, so with animations disabled Compose
* runs each spec for zero time and the item is at its final state at once.
*/
internal fun LazyItemScope.animateListItem(modifier: Modifier = Modifier): Modifier = modifier.animateItem(
fadeInSpec = MotionQuick.spec(),
placementSpec = MotionStandard.spec(),
fadeOutSpec = MotionQuick.spec(),
)
@@ -0,0 +1,61 @@
package net.awan.pipelines.ui.components
import androidx.compose.animation.core.CubicBezierEasing
import androidx.compose.animation.core.Easing
import androidx.compose.animation.core.TweenSpec
import androidx.compose.animation.core.tween
/**
* The named motion tokens: the one place every animation duration and easing in
* the app is defined, alongside the pane's dimension tokens in
* [SlidingPaneStack]. No call site writes a duration of its own.
*
* There are two, matching the size of the change:
* - [MotionQuick] — a small state change that stays where it is: a chevron
* turning, a list row appearing or leaving. Deliberately short (100-150ms).
* - [MotionStandard] — content that moves or swaps: a pane sliding, a section
* cross-fading, a row taking its new place in a refreshed, filtered or
* re-sorted list (200-250ms).
*
* Nothing animates for longer than [MAX_MOTION_MILLIS] (~300ms). Both easings
* are monotonic ease-in-out curves and [MotionStandard] is symmetric, so an
* animation run backwards is the same curve travelled backwards (see
* [paneSlideSpec], whose exact reversal is a unit-tested property).
*
* A token carries only timing; a call site asks it for the concrete spec it
* needs through [spec]. The spec is built during composition (or when the state
* changes), never per frame: the frame loop only advances an animator Compose
* already owns, so an animation allocates nothing as it runs.
*/
internal data class MotionToken(val durationMillis: Int, val easing: Easing) {
init {
require(durationMillis in 1..MAX_MOTION_MILLIS) {
"motion duration out of range: $durationMillis (1..$MAX_MOTION_MILLIS)"
}
}
}
/** The longest any single animation may run, in milliseconds. */
internal const val MAX_MOTION_MILLIS = 300
/** The stagger between the levels of a multi-level pane pop, in milliseconds. */
internal const val MOTION_STAGGER_MILLIS = 60
/** Small, in-place state changes (~100-150ms). */
internal val MotionQuick = MotionToken(
durationMillis = 120,
easing = CubicBezierEasing(0.4f, 0f, 0.6f, 1f),
)
/** Content moving or swapping (~200-250ms); symmetric, so it reverses exactly. */
internal val MotionStandard = MotionToken(
durationMillis = 220,
easing = CubicBezierEasing(0.42f, 0f, 0.58f, 1f),
)
/** The one tween for this token, optionally staggered by [delayMillis]. */
internal fun <T> MotionToken.spec(delayMillis: Int = 0): TweenSpec<T> = tween(
durationMillis = durationMillis,
delayMillis = delayMillis,
easing = easing,
)
@@ -17,11 +17,10 @@ import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.rotate
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.graphicsLayer
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.semantics.clearAndSetSemantics
import androidx.compose.ui.semantics.contentDescription
@@ -55,8 +54,9 @@ fun SectionHeader(
modifier: Modifier = Modifier,
containerColor: Color = MaterialTheme.colorScheme.background,
) {
val rotation by animateFloatAsState(
val rotation = animateFloatAsState(
targetValue = if (expanded) 0f else -90f,
animationSpec = MotionQuick.spec(),
label = "section-chevron",
)
Column(
@@ -91,7 +91,9 @@ fun SectionHeader(
Icon(
imageVector = Icons.Default.KeyboardArrowDown,
contentDescription = null,
modifier = Modifier.rotate(rotation),
// Read the animating angle inside the layer so the chevron turns
// without recomposing the header on every frame.
modifier = Modifier.graphicsLayer { rotationZ = rotation.value },
)
}
HorizontalDivider(color = MaterialTheme.colorScheme.outlineVariant)
@@ -1,10 +1,7 @@
package net.awan.pipelines.ui.components
import androidx.compose.animation.core.CubicBezierEasing
import androidx.compose.animation.core.Easing
import androidx.compose.animation.core.TweenSpec
import androidx.compose.animation.core.animateDpAsState
import androidx.compose.animation.core.tween
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.BoxWithConstraints
@@ -57,41 +54,37 @@ internal val MIN_ACTIVE_PANE_WIDTH_DP = 320.dp
internal val MIN_COVERED_PANE_WIDTH_DP = 112.dp
/**
* The one slide timing every pane shares. [PANE_SLIDE_EASING] is a symmetric
* ease (its control points mirror about the centre), so the same curve run from
* the open offset back to the closed one is exactly the open curve travelled
* backwards: closing a pane is the time-reverse of opening it, at the same
* [PANE_SLIDE_MILLIS] duration. When several levels close in one tap the levels
* below the topmost wait [PANE_POP_STEP_MILLIS] each, so they reverse in order.
* The one slide timing every pane shares: the [MotionStandard] token, whose
* easing is symmetric (its control points mirror about the centre). The same
* curve run from the open offset back to the closed one is therefore exactly the
* open curve travelled backwards — closing a pane is the time-reverse of opening
* it, at the same [MotionStandard.durationMillis]. When several levels close in
* one tap the levels below the topmost wait [MOTION_STAGGER_MILLIS] each, so they
* reverse in order.
*/
internal const val PANE_SLIDE_MILLIS = 300
internal const val PANE_POP_STEP_MILLIS = 60
internal val PANE_SLIDE_EASING: Easing = CubicBezierEasing(0.42f, 0f, 0.58f, 1f)
/**
* The extra delay, in milliseconds, before the pane at [level] starts reversing
* for a stack whose visible depth just moved from [previousDepth] to [depth]. A
* single closing level is the exact reverse of opening it and starts at once;
* when more than one level was open and several are leaving, the topmost leaves
* first and each lower level waits one more [PANE_POP_STEP_MILLIS] so the
* first and each lower level waits one more [MOTION_STAGGER_MILLIS] so the
* cascade reads in order. A level that is open or opening never waits. Pure, so
* the mirror/stagger rule needs no device.
*/
internal fun paneSlideDelayMillis(level: Int, depth: Int, previousDepth: Int): Int {
if (level <= depth) return 0
val closing = previousDepth - depth
return if (closing > 1) (previousDepth - level) * PANE_POP_STEP_MILLIS else 0
return if (closing > 1) (previousDepth - level) * MOTION_STAGGER_MILLIS else 0
}
/**
* The slide spec for the pane at [level]: one shared duration and easing in both
* directions, plus [paneSlideDelayMillis] when several levels pop together.
* The slide spec for the pane at [level]: the shared [MotionStandard] duration
* and easing in both directions, plus [paneSlideDelayMillis] when several levels
* pop together.
*/
internal fun paneSlideSpec(level: Int, depth: Int, previousDepth: Int): TweenSpec<Dp> = tween(
durationMillis = PANE_SLIDE_MILLIS,
delayMillis = paneSlideDelayMillis(level, depth, previousDepth),
easing = PANE_SLIDE_EASING,
)
internal fun paneSlideSpec(level: Int, depth: Int, previousDepth: Int): TweenSpec<Dp> =
MotionStandard.spec(delayMillis = paneSlideDelayMillis(level, depth, previousDepth))
/**
* The peek budget actually spent on a wide window: the fixed [PEEK_BUDGET_DP]
@@ -55,6 +55,7 @@ import net.awan.pipelines.ui.components.ErrorState
import net.awan.pipelines.ui.components.KeyValueRow
import net.awan.pipelines.ui.components.LoadingState
import net.awan.pipelines.ui.components.PaneIdentity
import net.awan.pipelines.ui.components.animateListItem
import net.awan.pipelines.ui.components.paneSafeArea
import net.awan.pipelines.ui.components.collapsibleSection
import net.awan.pipelines.ui.components.copyText
@@ -214,7 +215,7 @@ private fun PipelineSummaryTab(detail: PipelineDetail, wide: Boolean, modifier:
}
} else {
items(detail.versions, key = { "version-${it.version}" }) { v ->
VersionRow(v, Modifier.padding(horizontal = 16.dp, vertical = 4.dp).animateItem())
VersionRow(v, animateListItem(Modifier.padding(horizontal = 16.dp, vertical = 4.dp)))
}
}
}
@@ -38,6 +38,7 @@ import net.awan.pipelines.ui.components.ErrorState
import net.awan.pipelines.ui.components.ListRow
import net.awan.pipelines.ui.components.LoadingState
import net.awan.pipelines.ui.components.PaneIdentity
import net.awan.pipelines.ui.components.animateListItem
import net.awan.pipelines.ui.components.paneSafeArea
import net.awan.pipelines.ui.theme.pipelinesText
@@ -112,6 +113,7 @@ fun PipelineListScreen(
pipeline = pipeline,
selected = pipeline.id == selectedId,
onClick = { onOpen(pipeline.id, pipeline.version) },
modifier = animateListItem(),
)
}
}
@@ -135,11 +137,17 @@ fun PipelineListScreen(
* row is selected when its pipeline is the one open in the detail pane.
*/
@Composable
private fun PipelineRow(pipeline: PipelineSummary, selected: Boolean, onClick: () -> Unit) {
private fun PipelineRow(
pipeline: PipelineSummary,
selected: Boolean,
onClick: () -> Unit,
modifier: Modifier = Modifier,
) {
val text = pipelinesText()
ListRow(
selected = selected,
onClick = onClick,
modifier = modifier,
leading = {
Icon(
imageVector = Icons.Default.AccountTree,
@@ -59,6 +59,7 @@ import net.awan.pipelines.ui.components.ErrorState
import net.awan.pipelines.ui.components.KeyValueRow
import net.awan.pipelines.ui.components.LoadingState
import net.awan.pipelines.ui.components.PaneIdentity
import net.awan.pipelines.ui.components.animateListItem
import net.awan.pipelines.ui.components.paneSafeArea
import net.awan.pipelines.ui.components.RunStatusIcon
import net.awan.pipelines.ui.components.StatusChip
@@ -555,7 +556,7 @@ private fun RunEvidenceTab(
item(key = "$sectionKey-body") {
EvidenceDetails(
record,
Modifier.padding(horizontal = 16.dp, vertical = 4.dp).animateItem(),
animateListItem(Modifier.padding(horizontal = 16.dp, vertical = 4.dp)),
)
}
}
@@ -53,6 +53,7 @@ import net.awan.pipelines.ui.components.ErrorState
import net.awan.pipelines.ui.components.ListRow
import net.awan.pipelines.ui.components.LoadingState
import net.awan.pipelines.ui.components.PaneIdentity
import net.awan.pipelines.ui.components.animateListItem
import net.awan.pipelines.ui.components.paneSafeArea
import net.awan.pipelines.ui.components.runStateColor
import net.awan.pipelines.ui.components.runStateOf
@@ -170,6 +171,7 @@ private fun RunHistoryContent(
run = run,
selected = run.id == selectedRunId,
onClick = { onOpenRun(run.id) },
modifier = animateListItem(),
)
}
}
@@ -249,12 +251,18 @@ private fun Metric(label: String, value: String, color: Color, text: PipelinesTe
* one open in the detail pane.
*/
@Composable
private fun RunRow(run: RunSummary, selected: Boolean, onClick: () -> Unit) {
private fun RunRow(
run: RunSummary,
selected: Boolean,
onClick: () -> Unit,
modifier: Modifier = Modifier,
) {
val text = pipelinesText()
val state = runStateOf(run.status)
ListRow(
selected = selected,
onClick = onClick,
modifier = modifier,
leading = {
RunStatusIcon(
state = state,
@@ -0,0 +1,90 @@
package net.awan.pipelines.ui.components
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test
/**
* The motion tokens are pure data, so the rules the app relies on are checked
* here without a device: the tokens are ordered (quick is shorter than
* standard), each stays inside its intended band, nothing exceeds the cap, and
* every easing is a monotonic curve that starts at 0 and ends at 1 — so a token
* is always a real, reversible animation and never a no-op or an overshoot.
*/
class MotionTest {
private val tokens = listOf(MotionQuick, MotionStandard)
@Test
fun quickIsShorterThanStandard() {
assertTrue(
"quick (${MotionQuick.durationMillis}) must be shorter than standard (${MotionStandard.durationMillis})",
MotionQuick.durationMillis < MotionStandard.durationMillis,
)
}
@Test
fun eachTokenStaysInItsBand() {
// Small state changes (quick) and content changes (standard).
assertTrue(
"quick out of its 100-150ms band: ${MotionQuick.durationMillis}",
MotionQuick.durationMillis in 100..150,
)
assertTrue(
"standard out of its 200-250ms band: ${MotionStandard.durationMillis}",
MotionStandard.durationMillis in 200..250,
)
}
@Test
fun nothingRunsLongerThanTheCap() {
for (token in tokens) {
assertTrue(
"duration ${token.durationMillis} exceeds $MAX_MOTION_MILLIS",
token.durationMillis in 1..MAX_MOTION_MILLIS,
)
}
}
@Test
fun everyEasingIsMonotonicFromZeroToOne() {
for (token in tokens) {
assertEquals("easing does not start at 0", 0f, token.easing.transform(0f), 1e-4f)
assertEquals("easing does not end at 1", 1f, token.easing.transform(1f), 1e-4f)
var previous = 0f
for (i in 0..100) {
val value = token.easing.transform(i / 100f)
assertTrue("easing not monotonic at $i", value >= previous - 1e-4f)
assertTrue("easing out of [0,1] at $i: $value", value >= -1e-4f && value <= 1f + 1e-4f)
previous = value
}
}
}
@Test
fun theStandardEasingReversesItself() {
// A symmetric curve is what lets the pane slide reverse exactly (see
// SlidingPaneStackTest); it is a property of the token, so it is checked
// here too.
for (i in 0..100) {
val t = i / 100f
assertEquals(
"standard easing not symmetric at $t",
1f,
MotionStandard.easing.transform(t) + MotionStandard.easing.transform(1f - t),
1e-4f,
)
}
}
@Test
fun aSpecCarriesItsTokensTiming() {
val quick = MotionQuick.spec<Float>()
assertEquals(MotionQuick.durationMillis, quick.durationMillis)
assertEquals(MotionQuick.easing, quick.easing)
assertEquals(0, quick.delay)
val staggered = MotionStandard.spec<Float>(delayMillis = MOTION_STAGGER_MILLIS)
assertEquals(MotionStandard.durationMillis, staggered.durationMillis)
assertEquals(MOTION_STAGGER_MILLIS, staggered.delay)
}
}
@@ -142,7 +142,7 @@ class SlidingPaneStackTest {
assertEquals(
"easing is not symmetric at $t",
1f,
PANE_SLIDE_EASING.transform(t) + PANE_SLIDE_EASING.transform(1f - t),
MotionStandard.easing.transform(t) + MotionStandard.easing.transform(1f - t),
1e-4f,
)
}
@@ -165,9 +165,9 @@ class SlidingPaneStackTest {
// level beneath waits one step, so the cascade reads in order.
assertEquals(0, paneSlideDelayMillis(level = 2, depth = 0, previousDepth = 2))
assertEquals(
PANE_POP_STEP_MILLIS,
MOTION_STAGGER_MILLIS,
paneSlideDelayMillis(level = 1, depth = 0, previousDepth = 2),
)
assertTrue(PANE_SLIDE_MILLIS > 0)
assertTrue(MotionStandard.durationMillis > 0)
}
}