AnimationTimeline.fan constructor

AnimationTimeline.fan({ required List<AnimationController> controllers, Duration gap = Duration.zero, Duration hold = Duration.zero, Duration rest = Duration.zero, bool repeat = false, Object? id, String labelBuilder(int index, String phase)?, void onStepStart(int index, AnimationTimelineStep step, TimelineDirection direction)?, void onStepComplete(int index, AnimationTimelineStep step, TimelineDirection direction)?, })

Builds a fan choreography with staggered entrance and synchronized exit.

The generated sequence is:

1. animate each controller forward in index order with optional gap
2. optional hold
3. animate all controllers reverse together
4. optional rest

This is useful for menu reveals, panel blooms, and stepped entrances that should collapse back out in one coordinated beat.

Implementation

factory AnimationTimeline.fan({
  required List<AnimationController> controllers,
  Duration gap = Duration.zero,
  Duration hold = Duration.zero,
  Duration rest = Duration.zero,
  bool repeat = false,
  Object? id,
  String Function(int index, String phase)? labelBuilder,
  void Function(
    int index,
    AnimationTimelineStep step,
    TimelineDirection direction,
  )?
  onStepStart,
  void Function(
    int index,
    AnimationTimelineStep step,
    TimelineDirection direction,
  )?
  onStepComplete,
}) {
  if (controllers.isEmpty) {
    throw ArgumentError.value(
      controllers,
      'controllers',
      'must not be empty',
    );
  }

  final steps = <AnimationTimelineStep>[];
  for (var index = 0; index < controllers.length; index++) {
    if (index > 0 && gap > Duration.zero) {
      steps.add(
        AnimationTimelineStep.delay(
          gap,
          label: labelBuilder?.call(index, 'gap') ?? 'fan-gap-$index',
        ),
      );
    }
    steps.add(
      AnimationTimelineStep.forward(
        controllers[index],
        label: labelBuilder?.call(index, 'in') ?? 'fan-in-$index',
      ),
    );
  }
  if (hold > Duration.zero) {
    steps.add(
      AnimationTimelineStep.delay(
        hold,
        label:
            labelBuilder?.call(controllers.length - 1, 'hold') ?? 'fan-hold',
      ),
    );
  }
  steps.add(
    AnimationTimelineStep.parallel(
      [
        for (var index = 0; index < controllers.length; index++)
          AnimationTimelineStep.reverse(
            controllers[index],
            label: labelBuilder?.call(index, 'out') ?? 'fan-out-$index',
          ),
      ],
      label:
          labelBuilder?.call(controllers.length - 1, 'collapse') ??
          'fan-collapse',
    ),
  );
  if (rest > Duration.zero) {
    steps.add(
      AnimationTimelineStep.delay(
        rest,
        label:
            labelBuilder?.call(controllers.length - 1, 'rest') ?? 'fan-rest',
      ),
    );
  }

  return AnimationTimeline(
    steps: steps,
    repeat: repeat,
    id: id,
    onStepStart: onStepStart,
    onStepComplete: onStepComplete,
  );
}