compute static method
Computes the full LiquidMorphState for a single animation frame.
Parameters
rawValue— the raw, unclamped value fromAnimationController.unbounded. Legitimately exceeds[0, 1]during spring overshoot phases.finalDx— target horizontal displacement from the trigger center to the menu center, in logical pixels.finalDy— target vertical displacement from the trigger center to the menu center, in logical pixels.horizontalOffset— screen-edge clamping correction for horizontal overflow, accumulated by the menu positioning logic.verticalOffset— screen-edge clamping correction for vertical overflow.scaleDelta— geometric scale ratio of the morph (target area / source area, square-rooted). Use computeScaleDelta to derive this from sizes. Values > 1.5 engage adaptive damping. Defaults to1.0for backward compatibility — all existing callers without geometry information are unaffected.adaptiveDamping— explicit opt-in/opt-out override for adaptive mode. Whennull(default), adaptive mode is inferred fromscaleDelta.isClosing— whether the morph animation is closing back to origin. Defaults tofalse. Whentrue, avoids reverse-direction J-curve launch.
Implementation
static LiquidMorphState compute({
required double rawValue,
required double finalDx,
required double finalDy,
double horizontalOffset = 0.0,
double verticalOffset = 0.0,
double scaleDelta = 1.0,
bool? adaptiveDamping,
bool isClosing = false,
}) {
final clampedValue = rawValue.clamp(0.0, 1.0);
// Inject the close undershoot so Blob B bounces past the anchor on close.
// The open-side overshoot (rawValue > 1) is intentionally excluded because
// it causes an unwanted size wobble during the initial expansion.
final closeUndershoot = rawValue < 0.0 ? rawValue : 0.0;
// ── Adaptive mode detection ───────────────────────────────────────────────
// Engages when explicitly requested or when the scale ratio indicates a
// large-scale morph (button → sheet, button → tall menu).
final bool adaptive = adaptiveDamping ?? (scaleDelta > 1.5);
// ── Effective J-curve amplitude ───────────────────────────────────────────
// Small morphs (adaptive = false): full 2.5 amplitude for maximum teardrop.
// Large morphs (adaptive = true): damped inversely with vertical travel so
// physical overshoot stays within ~10–14 px.
final double amplitude = adaptive
? computeAdaptiveBackOutAmplitude(finalDy: finalDy)
: _backOutAmplitude;
// ── J-Curve Position ──────────────────────────────────────────────────────
// On open: The back-out curve overshoots past 1.0 before settling at 1.0,
// creating the "string pull" teardrop neck at maximum separation.
// On close: The surface returns home toward 0.0 following the spring's
// natural deceleration profile without any reverse-direction launch, plus
// the closing undershoot bounce past 0.0.
final double pathT;
if (isClosing) {
pathT = clampedValue + closeUndershoot;
} else {
pathT =
_BackOutCurve(amplitude).transform(clampedValue) + closeUndershoot;
}
// ── Size ─────────────────────────────────────────────────────────────────
// On close: ease-in via inverted linearToEaseOut so the surface visibly
// shrinks while returning toward the anchor, opening |pathT - sizeT| in
// mid-flight to drive the SDF metaball bridge.
// On open:
// Small morphs: linearToEaseOut — starts fast, decelerates to the target.
// Large morphs (scaleDelta > 3): smootherstep — keeps early peel controlled
// through detach/travel, then blossoms into destination bounds.
final double rawSizeT;
if (isClosing) {
rawSizeT = 1.0 - Curves.linearToEaseOut.transform(1.0 - clampedValue);
} else if (adaptive && scaleDelta > 3.0) {
rawSizeT = _smootherStep(clampedValue);
} else {
rawSizeT = Curves.linearToEaseOut.transform(clampedValue);
}
final sizeT = rawSizeT + closeUndershoot;
// ── Closing Momentum Push (Blob A displacement) ───────────────────────────
// When the spring overshoots past 0 (rawValue < 0), Blob A is displaced
// proportionally to mirror the closing momentum.
//
// For large-scale morphs the raw displacement would be proportional to the
// huge travel distance, producing a jarring multi-pixel jolt on the trigger.
// The pushFactor caps the effective travel to [_maxPushTravelPx] so the
// bounce remains a subtle iOS-native nudge.
final double pushFactor;
if (adaptive) {
final travelDx = (finalDx + horizontalOffset).abs();
final travelDy = (finalDy + verticalOffset).abs();
final travelMag = math.sqrt(travelDx * travelDx + travelDy * travelDy);
pushFactor = travelMag > 0.0
? (_maxPushTravelPx / travelMag).clamp(0.0, 1.0)
: 1.0;
} else {
pushFactor = 1.0;
}
final pushDx = rawValue < 0.0
? (finalDx + horizontalOffset) * rawValue * pushFactor
: 0.0;
final pushDy = rawValue < 0.0
? (finalDy + verticalOffset) * rawValue * pushFactor
: 0.0;
// ── Blob B Displacement ───────────────────────────────────────────────────
final currentDx = finalDx * pathT;
final currentDy = finalDy * pathT;
// ── Anchor Scale ─────────────────────────────────────────────────────────
// Shrinks the ghost trigger (Blob A) to 0 over the first 40% of the open
// animation so the droplet cleanly detaches, and grows it back from 0 to 1
// over the final 40% of the close animation as the droplet re-merges.
final anchorScale =
(1.0 - (clampedValue / _anchorEaseDuration)).clamp(0.0, 1.0);
// ── Metaball Blend ────────────────────────────────────────────────────────
// Separation between pathT (position) and sizeT (size) drives the SDF
// smooth-union radius on both open and close, peaking in mid-flight and
// converging to 0.0 at rest (0.0) and settled (1.0) so there is zero
// artificial SDF inflation at handoff.
final blendAttenuation = computeBlendAttenuation(scaleDelta);
final separation = (pathT - sizeT).abs();
final blend = (separation * _blendMultiplier * blendAttenuation)
.clamp(0.0, _maxBlend);
// ── Container Scale Pulse ─────────────────────────────────────────────────
// Subtle squeeze/swell during spring overshoot phases.
final containerScale = rawValue > 1.0
? 1.0 + (rawValue - 1.0) * 0.10 // open overshoot (negligible)
: rawValue < 0.0
? 1.0 + rawValue * 0.55 // close undershoot → visible squeeze
: 1.0;
// ── Phase ─────────────────────────────────────────────────────────────────
final phase = _derivePhase(rawValue, clampedValue);
return LiquidMorphState(
pathT: pathT,
sizeT: sizeT,
currentDx: currentDx,
currentDy: currentDy,
pushDx: pushDx,
pushDy: pushDy,
anchorScale: anchorScale,
blend: blend,
containerScale: containerScale,
phase: phase,
);
}