ResilientAnimationController class base

A state-resilient, lifecycle-managed AnimationController wrapper powered by Coral.

ResilientAnimationController provides the full feature set of Flutter's AnimationController while offering complete state resilience across resource lifecycle drops. It defers actual engine creation until the underlying Coral resource is activated, preserves parameters locally during dormant states, and restores state seamlessly when reactivated or reset.

Design Philosophy: This class adopts a resilient state-delegate pattern (_DormantAnimationControlDelegate and _ActiveAnimationControlDelegate) to ensure state continuity and fault tolerance. When dormant, parameter updates and state mutations are safely staged locally without instantiating an active AnimationController engine or throwing state errors. When the coral resource activates, delegates swap seamlessly into an active engine without breaking existing listeners or property values. Furthermore, when the resource is deactivated, the controller gracefully reverts back to a dormant state, demonstrating complete resilience against lifecycle teardowns. It also implements CoralProvider<double>, optionally broadcasting value changes when broadcast is true.

AI & Developer Note:

  • Do not manually call engine.dispose() directly on the underlying AnimationController. Resource disposal must be handled via the coral lifecycle manager or dispose.
  • Parameter updates performed while dormant will be synchronized into the active engine once instantiated.
  • If broadcast is set to true, multiple subscribers can listen to the coral resource without triggering duplicate resource initializations.

Example:

base class ExpandablePanel extends ComplexComputation<Widget>
    with
        CorallineLifecycleAware,
        CorallineTerminalIntentAware,
        CorallineBuildContextAware,
        TickerProviderCorallineLifecycleAwareMixin {
  ExpandablePanel({required this.child});

  final Widget child;

  static final Animatable<double> _expansionTween = CurveTween(
    curve: Curves.easeInToLinear,
  );

  // 1. Initialize ResilientAnimationController using `this` as vsync TickerProvider.
  late final controller = ResilientAnimationController(
    duration: const Duration(milliseconds: 300),
    vsync: this,
  );

  // 2. Pass controller through Animatable to create a transformed Animation.
  late final animation = controller.drive(_expansionTween);

  @override
  Iterable<CoralNode> manifest() sync* {
    // 3. Register controller.coral in the reactive node topology.
    yield controller.coral;
  }

  @override
  Widget build() {
    // 4. Render animated transition with the transformed animation.
    return SizeTransition(
      sizeFactor: animation,
      child: child,
    );
  }
}
Inheritance
Implemented types
Mixed-in types

Constructors

ResilientAnimationController({bool broadcast = false, double? value, Duration? duration, Duration? reverseDuration, String? debugLabel, double lowerBound = 0.0, double upperBound = 1.0, AnimationBehavior animationBehavior = AnimationBehavior.normal, required TickerProvider vsync})
Creates a resilient animation controller with bounded limits.
ResilientAnimationController.unbounded({bool broadcast = false, double value = 0.0, Duration? duration, Duration? reverseDuration, String? debugLabel, required TickerProvider vsync, AnimationBehavior animationBehavior = AnimationBehavior.preserve})
Creates a resilient animation controller with unbounded limits.

Properties

animationBehavior → AnimationBehavior
The behavior of the controller when system settings disable animations.
final
broadcast → bool
Whether changes to the underlying coral resource are broadcasted to multiple subscribers.
final
coral → Coral<double>
The Coral<double> instance exposing the animated double value lifecycle.
no setteroverride
debugLabel → String?
A label used to identify this animation in debug output.
final
duration ↔ Duration?
The length of time this animation should last.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
isActivated → bool
Whether the underlying animation coral resource node has been activated.
no setteroverride
isAnimating → bool
Whether this animation is currently animating.
no setteroverride
isCompleted → bool
Whether this animation is stopped at the end (status is AnimationStatus.completed).
no setteroverride
isDeactivated → bool
Whether the underlying animation coral resource node has been permanently deactivated.
no setteroverride
isDismissed → bool
Whether this animation is stopped at the beginning (status is AnimationStatus.dismissed).
no setteroverride
isForwardOrCompleted → bool
Whether the current aim of the animation is toward completion.
no setteroverride
isPaused → bool
Whether the underlying animation coral resource node is temporarily paused.
no setteroverride
isRunning → bool
Whether the underlying animation coral resource node is currently running.
no setteroverride
lastElapsedDuration → Duration?
The amount of time that has elapsed since the animation started.
no setter
lowerBound → double
The value at which this animation is deemed to be dismissed.
final
reverseDuration ↔ Duration?
The length of time this animation should last when going in reverse.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → AnimationStatus
The current status of this animation.
no setteroverride
upperBound → double
The value at which this animation is deemed to be completed.
final
value ↔ double
The current value of the animation.
getter/setter pairoverride-getter
velocity → double
The rate of change of value per second.
no setter
view → Animation<double>?
Returns an Animation<double> view for this animation controller.
no setter
vsync ↔ TickerProvider
The TickerProvider used to create the underlying Ticker.
getter/setter pair

Methods

addListener(VoidCallback listener) → void
Calls the listener every time the value of the animation changes.
inherited
addStatusListener(AnimationStatusListener listener) → void
Calls listener every time the status of the animation changes.
inherited
animateBack(double target, {Duration? duration, Curve curve = Curves.linear}) → TickerFuture
Drives the animation from its current value to the given target, "backward".
animateBackWith(Simulation simulation) → TickerFuture
Drives the animation according to the given simulation with a status of reverse.
animateTo(double target, {Duration? duration, Curve curve = Curves.linear}) → TickerFuture
Drives the animation from its current value to the given target, "forward".
animateWith(Simulation simulation) → TickerFuture
Drives the animation according to the given simulation.
clearListeners() → void
Removes all listeners added with addListener.
inherited
clearStatusListeners() → void
Removes all listeners added with addStatusListener.
inherited
didRegisterListener() → void
Called immediately before a status listener is added via addStatusListener.
inherited
didUnregisterListener() → void
Called immediately after a status listener is removed via removeStatusListener.
inherited
dispose() → void
Releases the resources used by this object.
override
drive<U>(Animatable<U> child) → Animation<U>
Passes this animation through an Animatable to create a transformed Animation.
override
fling({double velocity = 1.0, SpringDescription? springDescription, AnimationBehavior? animationBehavior}) → TickerFuture
Drives the animation with a spring and initial velocity.
forward({double? from}) → TickerFuture
Starts running this animation forwards (towards the end).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Calls all the listeners.
inherited
notifyStatusListeners(AnimationStatus status) → void
Calls all the status listeners.
inherited
removeListener(VoidCallback listener) → void
Stop calling the listener every time the value of the animation changes.
inherited
removeStatusListener(AnimationStatusListener listener) → void
Stops calling the listener every time the status of the animation changes.
inherited
repeat({double? min, double? max, bool reverse = false, Duration? period, int? count}) → TickerFuture
Starts running this animation in the forward direction, and restarts when complete.
reset() → void
Sets the controller's value to lowerBound, stopping the animation.
resync(TickerProvider vsync) → void
Recreates the underlying ticker with a new TickerProvider.
reverse({double? from}) → TickerFuture
Starts running this animation in reverse (towards the beginning).
stop({bool canceled = true}) → void
Stops running this animation.
toggle({double? from}) → TickerFuture
Toggles the direction of this animation.
toString() → String
A string representation of this object.
inherited
toStringDetails() → String
Returns detailed diagnostic string representation for debug output.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited