compute static method

LiquidMorphState compute({
  1. required double rawValue,
  2. required double finalDx,
  3. required double finalDy,
  4. double horizontalOffset = 0.0,
  5. double verticalOffset = 0.0,
  6. double scaleDelta = 1.0,
  7. bool? adaptiveDamping,
  8. bool isClosing = false,
})

Computes the full LiquidMorphState for a single animation frame.

Parameters

  • rawValue — the raw, unclamped value from AnimationController.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 to 1.0 for backward compatibility — all existing callers without geometry information are unaffected.
  • adaptiveDamping — explicit opt-in/opt-out override for adaptive mode. When null (default), adaptive mode is inferred from scaleDelta.
  • isClosing — whether the morph animation is closing back to origin. Defaults to false. When true, 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,
  );
}