Merge master into current branch

packages/flutter/lib/src/material/carousel.dart

@@ -145,6 +145,7 @@ class CarouselView extends StatefulWidget {
     this.enableSplash = true,
     required double this.itemExtent,
     required this.children,
+    this.onIndexChanged,
   }) : consumeMaxWeight = true,
        flexWeights = null,
        itemBuilder = null,
@@ -209,6 +210,7 @@ class CarouselView extends StatefulWidget {
     this.enableSplash = true,
     required List<int> this.flexWeights,
     required this.children,
+    this.onIndexChanged,
   }) : itemExtent = null,
        itemBuilder = null,
        itemCount = null;
@@ -252,6 +254,7 @@ class CarouselView extends StatefulWidget {
     required double this.itemExtent,
     required this.itemBuilder,
     this.itemCount,
+    this.onIndexChanged,
   }) : consumeMaxWeight = true,
        flexWeights = null,
        children = const <Widget>[];
@@ -309,6 +312,7 @@ class CarouselView extends StatefulWidget {
     required List<int> this.flexWeights,
     required this.itemBuilder,
     this.itemCount,
+    this.onIndexChanged,
   }) : itemExtent = null,
        children = const <Widget>[];
 
@@ -448,6 +452,46 @@ class CarouselView extends StatefulWidget {
   /// The child widgets for the carousel.
   final List<Widget> children;
 
+  /// {@template flutter.material.CarouselView.onIndexChanged}
+  /// A callback invoked when the leading item changes.
+  ///
+  /// The “leading” item is the one that the carousel resolves as primary for
+  /// the current frame according to its layout algorithm. This item can be only
+  /// partially visible while scrolling.
+  ///
+  /// - In a standard [CarouselView], the leading item is the one positioned at
+  ///   the leading edge of the viewport based on the current scroll offset.
+  ///
+  /// - In a [CarouselView.weighted], the leading item is chosen by the weighted
+  ///   layout algorithm (typically the one with the greatest effective weight;
+  ///   ties are resolved using proximity to the leading edge).
+  ///
+  /// If `itemSnapping` is enabled, scrolling settles with the resolved leading
+  /// item fully visible when possible.
+  ///
+  /// The callback fires only when the resolved leading index actually changes,
+  /// whether due to user interaction or programmatic scrolling.
+  /// {@endtemplate}
+  ///
+  /// {@tool dartpad}
+  /// Example:
+  ///
+  /// ```dart
+  /// CarouselView(
+  ///   itemExtent: 200.0,
+  ///   onIndexChanged: (int index) {
+  ///     print('Leading item changed to: $index');
+  ///   },
+  ///   children: <Widget>[
+  ///     Container(color: Colors.red),
+  ///     Container(color: Colors.green),
+  ///     Container(color: Colors.blue),
+  ///   ],
+  /// )
+  /// ```
+  /// {@end-tool}
+  final ValueChanged<int>? onIndexChanged;
+
   /// Called to build carousel item on demand.
   ///
   /// Will be called only for indices greater than or equal to zero and less
@@ -472,6 +516,7 @@ class _CarouselViewState extends State<CarouselView> {
   bool get _consumeMaxWeight => widget.consumeMaxWeight;
   CarouselController? _internalController;
   CarouselController get _controller => widget.controller ?? _internalController!;
+  late int _lastReportedLeadingItem;
 
   @override
   void initState() {
@@ -480,6 +525,7 @@ class _CarouselViewState extends State<CarouselView> {
     if (widget.controller == null) {
       _internalController = CarouselController();
     }
+    _lastReportedLeadingItem = _getInitialLeadingItem();
     _controller._attach(this);
   }
 
@@ -518,6 +564,15 @@ class _CarouselViewState extends State<CarouselView> {
     super.dispose();
   }
 
+  int _getInitialLeadingItem() {
+    if (widget.flexWeights != null) {
+      final int maxWeight = widget.flexWeights!.max;
+      final int firstMaxWeightIndex = widget.flexWeights!.indexOf(maxWeight);
+      return _controller.initialItem - firstMaxWeightIndex;
+    }
+    return _controller.initialItem;
+  }
+
   AxisDirection _getDirection(BuildContext context) {
     switch (widget.scrollDirection) {
       case Axis.horizontal:
@@ -636,21 +691,35 @@ class _CarouselViewState extends State<CarouselView> {
         _itemExtent = widget.itemExtent == null
             ? null
             : clampDouble(widget.itemExtent!, 0, mainAxisExtent);
-
-        return Scrollable(
-          axisDirection: axisDirection,
-          controller: _controller,
-          physics: physics,
-          viewportBuilder: (BuildContext context, ViewportOffset position) {
-            return Viewport(
-              cacheExtent: 0.0,
-              cacheExtentStyle: CacheExtentStyle.viewport,
-              axisDirection: axisDirection,
-              offset: position,
-              clipBehavior: Clip.antiAlias,
-              slivers: <Widget>[_buildSliverCarousel(theme)],
-            );
+        return NotificationListener<ScrollNotification>(
+          onNotification: (ScrollNotification notification) {
+            if (notification.depth == 0 &&
+                widget.onIndexChanged != null &&
+                notification is ScrollUpdateNotification) {
+              final ScrollPosition position = _controller.position;
+              final int currentLeadingIndex = (position as _CarouselPosition).leadingItem;
+              if (currentLeadingIndex != _lastReportedLeadingItem) {
+                _lastReportedLeadingItem = currentLeadingIndex;
+                widget.onIndexChanged?.call(currentLeadingIndex);
+              }
+            }
+            return false;
           },
+          child: Scrollable(
+            axisDirection: axisDirection,
+            controller: _controller,
+            physics: physics,
+            viewportBuilder: (BuildContext context, ViewportOffset position) {
+              return Viewport(
+                cacheExtent: 0.0,
+                cacheExtentStyle: CacheExtentStyle.viewport,
+                axisDirection: axisDirection,
+                offset: position,
+                clipBehavior: Clip.antiAlias,
+                slivers: <Widget>[_buildSliverCarousel(theme)],
+              );
+            },
+          ),
         );
       },
     );
@@ -1567,6 +1636,12 @@ class _CarouselPosition extends ScrollPositionWithSingleContext implements _Caro
     _flexWeights = value;
   }
 
+  // The index of the leading item in the carousel.
+  // getItemFromPixels may return a fractional value (e.g., 0.6 when mid-scroll).
+  // We use toInt() to truncate the fractional part, ensuring the leading item
+  // only advances after fully crossing the next item's boundary.
+  int get leadingItem => getItemFromPixels(pixels, viewportDimension).toInt();
+
   double updateLeadingItem(List<int>? newFlexWeights, bool newConsumeMaxWeight) {
     final double maxItem;
     if (hasPixels && flexWeights != null) {
@@ -1704,6 +1779,22 @@ class CarouselController extends ScrollController {
   /// The item that expands to the maximum size when first creating the [CarouselView].
   final int initialItem;
 
+  /// The current leading item index in the [CarouselView].
+  ///
+  /// {@macro flutter.material.CarouselView.onIndexChanged}
+  int get leadingItem {
+    assert(
+      positions.isNotEmpty,
+      'CarouselController.leadingItem cannot be accessed before a CarouselView is built with it.',
+    );
+    assert(
+      positions.length == 1,
+      'CarouselController.leadingItem cannot be read when multiple CarouselViews '
+      'are attached to the same controller.',
+    );
+    return (position as _CarouselPosition).leadingItem;
+  }
+
   _CarouselViewState? _carouselState;
 
   // ignore: use_setters_to_change_properties