The current logic for wrapping the index, (index + widget.children.length) % widget.children.length, is incorrect for negative indices in Dart. The % operator can return a negative value if the dividend is negative. For example, if index is -4 and widget.children.length is 3, the expression evaluates to (-4 + 3) % 3, which is -1 % 3, resulting in -1. This will lead to a RangeError when trying to access widget.children[-1].

A more robust approach that correctly handles both positive and negative indices is to use the (a % n + n) % n pattern, which ensures the result is always a valid non-negative index.

      index = (index % widget.children.length + widget.children.length) % widget.children.length;

The current test for animateToItem only covers positive indices. To ensure the infinite scrolling is robust, especially when scrolling backwards, it's important to also test with negative indices. The bug in the index-wrapping logic would have been caught by a test case that animates to a negative index like -4 (when there are 3 children). I suggest adding assertions for negative indices to make the test suite more comprehensive.

      // Verify animating to indices outside the actual children range.
      controller.animateToItem(5);
      await tester.pumpAndSettle();
      expect(find.textContaining('Item 2'), findsAtLeastNWidgets(2));

      // Verify animating to a negative index.
      controller.animateToItem(-4);
      await tester.pumpAndSettle();
      expect(find.textContaining('Item 2'), findsAtLeastNWidgets(2));

Can we try to expect all item 0, 1 and 2 are on the screen?

Is this possible at all? If not we can remove this check.

Have removed this, was adding this for bidirectional infinite carousel(droped that idea).

In the API doc, we can also mention itemBuilder and itemCount will be ignored when infinite is not true:)

Update API doc

This calculation seems the same as the non-infinite version.

Merged both condition.

I think we can just use scrollOffset here instead of constraints.scrollOffset.

This seems not accurate as well. My understanding is the max index should just be scrollOffset / maxExtent - 1. scrollOffset / maxExtent is how many items we can include and - 1 is to indicate the item index.

Again, this was for bidirectional carousel. Have removed it.

Putting a hard-code number might be not safe here. We can get the upper bound by using the firstVisibleItemIndex and weights.

Updated this

When infinite, we can just go here, instead of create another if statement.

(constraints.viewportMainAxisExtent / safeMinExtent).ceil() is how many items with minimum extent in the viewport, but why do we need to multiply it by weights length? Feels the result doesn't make sense.

seems (constraints.viewportMainAxisExtent / safeMinExtent).ceil() is safe enough?

Logically, it should be good, I just gave extra buffer, but i will change.

The original if else is to prevent the index to be out of range. Don't we need to constrain the index when infinite is true?

for infinite, its already coming in constrain, it will be unnecessary operation, but I can remove the condition.

We should make the tests more accurate, like checking the layout rects for each item are correct. If scrolling forward by 500, each item extent is 200, then the visible item should be "item 2", "item 0", "item 1", and "item 2", right?

Here and everywhere else.

I have pushed the change.

Remove this line if we don't use the multiplier.

I think no need to use clampDouble. _firstVisibleItemIndex + constraints.viewportMainAxisExtent / safeMinExtent).ceil() is safe enough.