Does this mean that controller.toggle(true) is the same as calling controller.forward() and controller.toggle(false) is the same as controller.reverse()?

From an API perspective I find it difficult to wrap my head around this API. It is not super-clear what the boolean means. Why is true == forward?

Does this mean that controller.toggle(true) is the same as calling controller.forward() and controller.toggle(false) is the same as controller.reverse()?

Yes!

Technically, we could get rid of .forward() and .reverse() and have everything implemented in terms of .animateTo() and .animateFrom() with relatively minimal refactoring. But I like having "forward" and "reverse" since they're common use cases.

Likewise, I think it makes sense to have .toggle(), since the following AnimationController logic is very common:

if (condition) {
  _controller.forward();
} else {
  _controller.reverse();
}

From an API perspective I find it difficult to wrap my head around this API. It is not super-clear what the boolean means. Why is true == forward?

This is something I hadn't considered. After looking it over again, it does feel redundant to include the method in the parameter name, and I agree that it should have a better explanation.

I've made updates to the method accordingly; thank you!

My problem with the API is more that when I see controller.toggle(true) I don't actually immediately know what that means. Toggle doesn't naturally take a boolean, so it makes the code harder to understand compared to the if/else pattern, which is immediately obvious.

Ah okay, that makes sense: fewer lines of code isn't necessarily worth it if it becomes significantly more difficult to understand.

I 100% agree that toggle(true) and toggle(false) is extremely unintuitive—animated_cross_fade.dart is an egregious example of this:

_controller.toggle(switch (widget.crossFadeState) {
  CrossFadeState.showFirst => false,
  CrossFadeState.showSecond => true,
});


// much more readable as a switch statement
switch (widget.crossFadeState) {
  case CrossFadeState.showFirst:
    _controller.reverse();
  case CrossFadeState.showSecond:
    _controller.forward();
}

However, I believe that the vast majority of the toggle calls in this PR are very intuitive & easy to follow, for example:

@override
void didUpdateWidget(_RallyTab oldWidget) {
  super.didUpdateWidget(oldWidget);
  _controller.toggle(widget.isExpanded);
}

My immediate thought upon reading: "This looks like a stateful widget with an animation controller that toggles each time isExpanded changes."

If I were to give a letter grade to the current additions, it would probably be as follows:

A+ for the empty .toggle() calls (6 in this PR)

_controller.toggle(_showDrawerContents);

_controller.toggle(shouldOpenList);

_codeBackgroundColorController.toggle(
  _demoStateIndex.value == _DemoState.code.index,
);

_controller.toggle(widget.isExpanded);

_positionController.toggle(widget.value);

_controller.toggle(widget.mode == DatePickerMode.year);

enableController.toggle(widget.isEnabled);

selectController.toggle(widget.selected);

deleteDrawerController.toggle(hasDeleteButton);

_opacityController.toggle(widget.visible);

_orientationController.toggle(_orientationController.isDismissed);

_controller.toggle(widget.isExpanded);

_hoverColorController.toggle(widget.isHovering);

_controller.toggle(hasError);

_controller.toggle(widget.isSelected);

_extendedController.toggle(widget.extended);

enableController.toggle(isEnabled);

_state.enableController.toggle(isInteractive);

_controller.toggle(widget.isOpen);

_reactionFocusFadeController.toggle(focused);

_reactionHoverFadeController.toggle(hovering);

_controller.toggle(widget.visibility?.value ?? true);

_controller.toggle(widget.visibility?.value ?? true);

_positionController.toggle(value ?? tristate);

avatarDrawerController.toggle(hasAvatar || widget.selected);

_controller.toggle(!widget.checked);

menuAnimation.toggle(!menuAnimation.isCompleted);

_floatingLabelController.toggle(
  _floatingLabelEnabled && widget._labelShouldWithdraw,
);

_state.overlayController.toggle(hovered && (hoveringStartThumb || hoveringEndThumb));

_moveController!.toggle(
  _moveController!.value > (widget.dismissThresholds[_dismissDirection] ?? _kDismissThreshold),
);

_controller.toggle(switch (widget.crossFadeState) {
  CrossFadeState.showFirst => false,
  CrossFadeState.showSecond => true,
});

I'll go ahead and revert those 3 worst examples.

/// Toggles the direction of this animation.
///
/// The value of `forward` should toggle between `true` and `false`, and
/// `toggle()` should be called each time it changes. This function acts
/// like `forward()` or `reverse()` based on whether the value passed is
/// `true` or `false`, respectively.
///
/// If no argument is provided, the controller changes direction every time,
/// based on the current [status].
///
/// {@macro flutter.animation.AnimationController.ticker_canceled}
TickerFuture toggle({ bool? forward }) {
  return _toggle('toggle', forward ?? !isForwardOrCompleted, null);
}

Here's the current method documentation (edited based on @gnprice's comment, thanks!)