laantungir/amethyst
1
0
Fork 0
mirror of https://github.com/vitorpamplona/amethyst.git synced 2026-08-09 08:04:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3327 from vitorpamplona/claude/disappearing-scaffold-animation-zk9lql

Browse Source 
Fix disappearing bar settle logic to prevent blank bands on partial reveals
This commit is contained in:
Vitor Pamplona
2026-06-21 16:48:28 -04:00
committed by GitHub
parent abd540e3c2 d96d0220fb
commit 2187158c53
4 changed files with 132 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
amethyst/src/main/java/com/vitorpamplona/amethyst/ui/layouts/DisappearingBarNestedScroll.kt
+23 -14
View File
@@ -24,6 +24,7 @@ import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.input.nestedscroll.NestedScrollConnection
import androidx.compose.ui.input.nestedscroll.NestedScrollSource
import androidx.compose.ui.unit.Velocity
import kotlin.math.abs
/**
* Scroll-linked connection that hides/reveals the top and bottom bars together.
@@ -43,10 +44,16 @@ import androidx.compose.ui.unit.Velocity
* - onPostFling snaps a mid-way bar to the nearest edge, using the fling's remaining
* velocity as the spring's initial velocity so the settle feels continuous. No velocity
* is returned upward to avoid phantom scrolls on parent containers.
* - Hiding tracks the finger 1:1, but revealing is damped by [REVEAL_SENSITIVITY]. Once the
* bars are hidden, the small reverse drag a finger naturally makes when it catches/stops a
* fast scroll would otherwise be enough to snap the chrome (and the OS status bar) back.
* Damping the reveal direction makes bringing the bars back a more deliberate gesture.
* - Both hiding and revealing track the finger 1:1. The bar offset must equal the content's
* scroll offset so the bar's bottom edge stays glued to the first item's top edge; any
* asymmetry (e.g. a damped reveal) leaves the bar lagging behind the content and opens a
* blank band between the bar and the first item when the list returns to the top.
*
* Making the reveal a *deliberate* gesture — so the tiny reverse drag a finger makes when it
* catches/stops a fast scroll doesn't pop the chrome back — is handled without breaking that
* 1:1 invariant: a partial reveal that doesn't cross the halfway point is snapped back to the
* hidden edge by [DisappearingBarState.settleToNearestEdge] on fling/lift, and the binary OS
* status bar is debounced by the show/hide hysteresis in the scaffold.
*/
class DisappearingBarNestedScroll(
private val state: DisappearingBarState,
@@ -60,7 +67,10 @@ class DisappearingBarNestedScroll(
): Offset {
if (!canScroll()) return Offset.Zero
val totalY = consumed.y + available.y
if (totalY == 0f) return Offset.Zero
// Dead-zone: ignore sub-pixel jitter so the bars (and the binary status-bar toggle that
// tracks their collapse fraction) don't twitch on scroll noise. Kept symmetric and tiny so
// it never makes the reveal lag the content enough to open a visible gap.
if (abs(totalY) < MIN_SCROLL_DELTA) return Offset.Zero
// If the list did not consume any scroll and the bars are fully visible, treat
// this as a non-scrollable list and keep the bars in place. Without this, a tiny
@@ -90,19 +100,18 @@ class DisappearingBarNestedScroll(
private fun applyDelta(deltaY: Float) {
val topLimit = state.topHeightLimit
val bottomLimit = state.bottomHeightLimit
// Positive delta reveals the bars; negative delta hides them. Hiding stays 1:1 with the
// finger, while revealing is damped so a stray reverse drag doesn't bring the chrome back.
val effectiveDelta = if (deltaY > 0f) deltaY * REVEAL_SENSITIVITY else deltaY
state.topHeightOffset = (state.topHeightOffset + effectiveDelta).coerceIn(-topLimit, 0f)
state.bottomHeightOffset = (state.bottomHeightOffset + effectiveDelta).coerceIn(-bottomLimit, 0f)
// 1:1 in both directions: the bar offset mirrors the content scroll so the bar stays glued
// to the first item. Deliberate reveal is enforced on settle, not by damping the delta here.
state.topHeightOffset = (state.topHeightOffset + deltaY).coerceIn(-topLimit, 0f)
state.bottomHeightOffset = (state.bottomHeightOffset + deltaY).coerceIn(-bottomLimit, 0f)
}
companion object {
/**
* Fraction of scroll distance applied when revealing the bars (1.0 = same rate as hiding).
* Lower values require a more deliberate downward scroll to bring the chrome back, so the
* tiny reverse movement of a finger stopping a fast scroll no longer pops the bars open.
* Sub-pixel dead-zone: scroll attempts smaller than this are ignored so jitter doesn't nudge
* the bars. Tiny on purpose — large enough to swallow fractional noise, small enough that the
* bar offset never measurably lags the content scroll.
*/
const val REVEAL_SENSITIVITY = 0.5f
const val MIN_SCROLL_DELTA = 0.5f
}
}
amethyst/src/main/java/com/vitorpamplona/amethyst/ui/layouts/DisappearingBarState.kt
+53 -5
View File
@@ -46,8 +46,46 @@ class DisappearingBarState(
initialTopHeightOffset: Float = 0f,
initialBottomHeightOffset: Float = 0f,
) {
var topHeightOffset by mutableFloatStateOf(initialTopHeightOffset)
var bottomHeightOffset by mutableFloatStateOf(initialBottomHeightOffset)
private var _topHeightOffset by mutableFloatStateOf(initialTopHeightOffset)
private var _bottomHeightOffset by mutableFloatStateOf(initialBottomHeightOffset)
/**
* Latches that record whether each bar has been driven all the way to its hidden edge by real
* scrolling since it was last fully in view. The settle reads them to tell a deliberate hide —
* where the content has scrolled at least a full bar height, so snapping the bar fully hidden
* leaves content (not a blank band) in the slot it vacates — apart from a small near-top
* collapse, where snapping hidden would expose the background because the content hasn't
* scrolled far enough to fill the bar's slot.
*/
private var topReachedHiddenEdge = false
private var bottomReachedHiddenEdge = false
var topHeightOffset: Float
get() = _topHeightOffset
set(value) {
_topHeightOffset = value
updateLatch(value, topHeightLimit) { topReachedHiddenEdge = it }
}
var bottomHeightOffset: Float
get() = _bottomHeightOffset
set(value) {
_bottomHeightOffset = value
updateLatch(value, bottomHeightLimit) { bottomReachedHiddenEdge = it }
}
private inline fun updateLatch(
offset: Float,
limit: Float,
set: (Boolean) -> Unit,
) {
if (limit <= 0f) return
if (offset >= 0f) {
set(false)
} else if (offset <= -limit) {
set(true)
}
}
var topHeightLimit: Float = 0f
set(value) {
@@ -76,8 +114,8 @@ class DisappearingBarState(
*/
suspend fun settleToNearestEdge(initialVelocityY: Float = 0f) {
coroutineScope {
launch { settleOne({ topHeightOffset }, topHeightLimit, initialVelocityY) { topHeightOffset = it } }
launch { settleOne({ bottomHeightOffset }, bottomHeightLimit, initialVelocityY) { bottomHeightOffset = it } }
launch { settleOne({ topHeightOffset }, topHeightLimit, topReachedHiddenEdge, initialVelocityY) { topHeightOffset = it } }
launch { settleOne({ bottomHeightOffset }, bottomHeightLimit, bottomReachedHiddenEdge, initialVelocityY) { bottomHeightOffset = it } }
}
}
@@ -94,6 +132,7 @@ class DisappearingBarState(
private suspend fun settleOne(
get: () -> Float,
limit: Float,
canFullyHide: Boolean,
initialVelocityY: Float,
set: (Float) -> Unit,
) {
@@ -105,6 +144,11 @@ class DisappearingBarState(
val positionBiasToHide = -current > limit / 2f
val target =
when {
// Snapping to the hidden edge is only safe once the bar has actually been scrolled
// there (canFullyHide): the content has then moved at least a full bar height and
// fills the slot the bar vacates. From a small near-top collapse it hasn't, so
// snapping hidden would open a blank band — settle back into view instead.
!canFullyHide -> 0f
initialVelocityY < -VELOCITY_BIAS_THRESHOLD -> -limit
initialVelocityY > VELOCITY_BIAS_THRESHOLD -> 0f
positionBiasToHide -> -limit
@@ -142,10 +186,14 @@ class DisappearingBarState(
companion object {
private const val VELOCITY_BIAS_THRESHOLD = 200f
// Bounce-free so the chrome never wobbles past its edge, but stiff enough to feel like a
// quick native snap rather than a slow float once the finger lifts. Overshoot from a strong
// initial velocity is still caught by the bounds in animateOne, so a higher stiffness here
// only affects how briskly the bar resolves to its edge.
private val SETTLE_SPRING =
spring<Float>(
dampingRatio = Spring.DampingRatioNoBouncy,
stiffness = Spring.StiffnessMediumLow,
stiffness = Spring.StiffnessMedium,
)
val Saver: Saver<DisappearingBarState, *> =
amethyst/src/test/java/com/vitorpamplona/amethyst/ui/layouts/DisappearingBarNestedScrollTest.kt
+11 -10
View File
@@ -79,17 +79,17 @@ class DisappearingBarNestedScrollTest {
}
@Test
fun `scrolling content down reveals both bars from a hidden state, damped`() {
fun `scrolling content down reveals both bars from a hidden state`() {
val state = state(topLimit = 100f, bottomLimit = 50f)
state.topHeightOffset = -100f
state.bottomHeightOffset = -50f
val connection = nsc(state)
// Reveal is damped by REVEAL_SENSITIVITY (0.5), so a 30px drag only reveals 15px.
// Reveal tracks the finger 1:1, so a 30px drag reveals 30px.
connection.onPostScroll(Offset(0f, 30f), Offset(0f, 0f), NestedScrollSource.UserInput)
assertEquals(-85f, state.topHeightOffset)
assertEquals(-35f, state.bottomHeightOffset)
assertEquals(-70f, state.topHeightOffset)
assertEquals(-20f, state.bottomHeightOffset)
}
@Test
@@ -100,26 +100,27 @@ class DisappearingBarNestedScrollTest {
val connection = nsc(state)
// The list consumed 20px of a 40px reveal drag; 20 more was left as overscroll.
// The bars should move by the total 40 (damped to 20 on reveal), not just one half.
// The bars should move by the total 40, not just one of the halves.
connection.onPostScroll(Offset(0f, 20f), Offset(0f, 20f), NestedScrollSource.UserInput)
assertEquals(-30f, state.topHeightOffset)
assertEquals(-30f, state.bottomHeightOffset)
assertEquals(-10f, state.topHeightOffset)
assertEquals(-10f, state.bottomHeightOffset)
}
@Test
fun `revealing is less sensitive than hiding for the same drag distance`() {
fun `revealing tracks the finger 1 to 1, matching the hide rate so the bar stays glued to content`() {
// Hiding a 40px drag moves the bars the full 40px...
val hiding = state(topLimit = 100f, bottomLimit = 100f)
nsc(hiding).onPostScroll(Offset(0f, -40f), Offset(0f, 0f), NestedScrollSource.UserInput)
assertEquals(-40f, hiding.topHeightOffset)
// ...while revealing the same 40px from fully hidden only brings back 20px.
// ...and revealing the same 40px from fully hidden brings back the full 40px, so when the
// list returns to the top the bar is fully revealed with no blank band beneath it.
val revealing = state(topLimit = 100f, bottomLimit = 100f)
revealing.topHeightOffset = -100f
revealing.bottomHeightOffset = -100f
nsc(revealing).onPostScroll(Offset(0f, 40f), Offset(0f, 0f), NestedScrollSource.UserInput)
assertEquals(-80f, revealing.topHeightOffset)
assertEquals(-60f, revealing.topHeightOffset)
}
@Test
amethyst/src/test/java/com/vitorpamplona/amethyst/ui/layouts/DisappearingBarStateTest.kt
+45
View File
@@ -93,4 +93,49 @@ class DisappearingBarStateTest {
assertTrue("top bar overshot to $peakTop", peakTop <= 0.5f)
assertTrue("bottom bar overshot to $peakBottom", peakBottom <= 0.5f)
}
@Test
fun `a partial collapse that never reached the hidden edge settles back into view`() =
runTest {
// The bar is past the halfway point but was only ever scrolled here from the top — it
// never reached -limit, so the content hasn't moved a full bar height. Snapping it fully
// hidden would expose a blank band, so it must settle back to visible instead.
val state = state(topLimit = 100f, bottomLimit = 50f)
state.topHeightOffset = -80f
peakOffsetsDuring(state) { state.settleToNearestEdge() }
assertEquals(0f, state.topHeightOffset, 0.01f)
}
@Test
fun `a small reveal after fully hiding settles back to hidden, not into view`() =
runTest {
// Drive the bar to its hidden edge first (content has now scrolled a full bar height),
// then nudge it back a little — the small reverse drag a finger makes catching a scroll.
// Because it genuinely reached the hidden edge, snapping back hidden leaves no gap, so a
// sub-halfway reveal must not pop the chrome back open.
val state = state(topLimit = 100f, bottomLimit = 50f)
state.topHeightOffset = -100f
state.topHeightOffset = -90f
peakOffsetsDuring(state) { state.settleToNearestEdge() }
assertEquals(-100f, state.topHeightOffset, 0.01f)
}
@Test
fun `returning fully into view re-arms the gap guard so the next near-top collapse settles open`() =
runTest {
// Hide fully (arms the latch), come all the way back to visible (disarms it), then do a
// small near-top collapse again. It must settle open, proving the latch resets at 0.
val state = state(topLimit = 100f, bottomLimit = 50f)
state.topHeightOffset = -100f
state.topHeightOffset = 0f
state.topHeightOffset = -80f
peakOffsetsDuring(state) { state.settleToNearestEdge() }
assertEquals(0f, state.topHeightOffset, 0.01f)
}
}