Stop semantic scroll actions at the scroll extents instead of overscrolling - #188788

// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/rendering.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_test/flutter_test.dart';

import 'widgets/semantics_tester.dart';

void main() {
  group('PR 188788 Review & Regression Verification Tests', () {
    testWidgets(
      'REGRESSION 1: NestedScrollView SemanticsAction.scrollUp is clamped to outerPosition.maxScrollExtent instead of scrolling inner ListView',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final outerKey = GlobalKey<NestedScrollViewState>();

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: MediaQuery(
              data: const MediaQueryData(accessibleNavigation: true),
              child: NestedScrollView(
                key: outerKey,
                headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
                  return const <Widget>[
                    SliverToBoxAdapter(
                      child: SizedBox(height: 200.0, child: Text('Collapsible Header')),
                    ),
                  ];
                },
                body: ListView.builder(
                  itemCount: 50,
                  itemExtent: 50.0,
                  itemBuilder: (BuildContext context, int index) => Text('Item $index'),
                ),
              ),
            ),
          ),
        );

        final ScrollController outerController = outerKey.currentState!.outerController;
        final ScrollController innerController = outerKey.currentState!.innerController;

        expect(outerController.offset, 0.0);
        expect(innerController.offset, 0.0);

        // In NestedScrollView, only the outer _NestedScrollPosition calls context.setCanDrag(true),
        // so all semantic scroll actions on NestedScrollView are handled by the outer Scrollable's
        // _ScrollableSemanticsGestureDelegate.
        final int nestedScrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[SemanticsAction.scrollUp, SemanticsAction.scrollToOffset],
            )
            .single
            .id;

        // Dispatch SemanticsAction.scrollUp (480px) on NestedScrollView:
        // On master (before PR 188788), _NestedScrollCoordinator distributes the 480px drag across
        // outerPosition (0.0 -> 200.0, collapsing the header sliver) AND innerPosition (0.0 -> 280.0).
        // With PR 188788, the outer _ScrollableSemanticsGestureDelegate clamps the 480px drag to
        // outerPosition.maxScrollExtent (200.0), so innerController receives 0.0 and cannot scroll!
        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          nestedScrollableId,
          SemanticsAction.scrollUp,
        );
        await tester.pumpAndSettle();

        expect(outerController.offset, 200.0);
        expect(
          innerController.offset,
          280.0,
          reason:
              'Regression in PR 188788: _ScrollableSemanticsGestureDelegate clamped the 480px scrollUp '
              'to outerPosition.maxScrollExtent (200.0), preventing innerController from scrolling the remaining 280px.',
        );

        semantics.dispose();
      },
    );

    testWidgets(
      'REGRESSION 2: NestedScrollView SemanticsAction.scrollDown is clamped to outerPosition.pixels instead of scrolling inner ListView and expanding floating header',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final outerKey = GlobalKey<NestedScrollViewState>();

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: MediaQuery(
              data: const MediaQueryData(accessibleNavigation: true),
              child: NestedScrollView(
                key: outerKey,
                floatHeaderSlivers: true,
                headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
                  return <Widget>[
                    SliverPersistentHeader(
                      floating: true,
                      delegate: _TestFloatingHeaderDelegate(extent: 200.0),
                    ),
                  ];
                },
                body: ListView.builder(
                  itemCount: 50,
                  itemExtent: 50.0,
                  itemBuilder: (BuildContext context, int index) => Text('Item $index'),
                ),
              ),
            ),
          ),
        );

        final ScrollController outerController = outerKey.currentState!.outerController;
        final ScrollController innerController = outerKey.currentState!.innerController;

        // Scroll up 500px by drag: 200px collapses the outer floating header, 300px scrolls the inner ListView.
        await tester.drag(find.byType(NestedScrollView), const Offset(0.0, -500.0));
        await tester.pumpAndSettle();

        expect(outerController.offset, 200.0);
        expect(innerController.offset, 300.0);

        // Drag down 190px so the floating header is almost fully revealed (outerController.offset == 10.0),
        // while innerController.offset is still at 300.0.
        await tester.drag(find.byType(NestedScrollView), const Offset(0.0, 190.0));
        await tester.pumpAndSettle();

        expect(outerController.offset, 10.0);
        expect(innerController.offset, 300.0);

        final int nestedScrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[
                SemanticsAction.scrollUp,
                SemanticsAction.scrollDown,
                SemanticsAction.scrollToOffset,
              ],
            )
            .single
            .id;

        // Perform SemanticsAction.scrollDown (which should scroll 480px down: 10px finishing the floating header
        // and 300px scrolling the inner ListView back to 0.0).
        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          nestedScrollableId,
          SemanticsAction.scrollDown,
        );
        await tester.pumpAndSettle();

        expect(outerController.offset, 0.0);
        expect(
          innerController.offset,
          0.0,
          reason:
              'Regression in PR 188788: _ScrollableSemanticsGestureDelegate clamped the 480px downward scroll '
              'to outerPosition.pixels (10.0), leaving innerController permanently stuck at 300.0 instead of 0.0.',
        );

        semantics.dispose();
      },
    );

    testWidgets(
      'REGRESSION 3: ClampingScrollPhysics no longer dispatches OverscrollNotification on semantic scroll at boundary',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final controller = ScrollController(initialScrollOffset: 190.0);
        addTearDown(controller.dispose);
        final overscrolls = <OverscrollNotification>[];

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: NotificationListener<OverscrollNotification>(
              onNotification: (OverscrollNotification notification) {
                overscrolls.add(notification);
                return false;
              },
              child: ListView(
                controller: controller,
                physics: const ClampingScrollPhysics(),
                children: List<Widget>.generate(
                  20,
                  (int i) => SizedBox(height: 40.0, child: Text('$i')),
                ),
              ),
            ),
          ),
        );

        final int scrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[
                SemanticsAction.scrollUp,
                SemanticsAction.scrollDown,
                SemanticsAction.scrollToOffset,
              ],
            )
            .single
            .id;

        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          scrollableId,
          SemanticsAction.scrollUp,
        );
        await tester.pumpAndSettle();

        expect(controller.offset, 200.0);
        expect(
          overscrolls,
          isNotEmpty,
          reason:
              'Regression in PR 188788: OverscrollNotification was suppressed on ClampingScrollPhysics '
              'because the drag delta was pre-clamped before ScrollPosition.setPixels.',
        );

        semantics.dispose();
      },
    );

    testWidgets(
      'ISSUE 4: TwoDimensionalScrollable with DiagonalDragBehavior.free fails to clamp horizontal semantic scrolls',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final horizontalController = ScrollController(initialScrollOffset: 190.0);
        final verticalController = ScrollController();
        addTearDown(horizontalController.dispose);
        addTearDown(verticalController.dispose);

        var maxHorizontalObserved = 190.0;
        horizontalController.addListener(() {
          if (horizontalController.offset > maxHorizontalObserved) {
            maxHorizontalObserved = horizontalController.offset;
          }
        });

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: MediaQuery(
              data: const MediaQueryData(accessibleNavigation: true),
              child: TwoDimensionalScrollable(
                diagonalDragBehavior: DiagonalDragBehavior.free,
                horizontalDetails: ScrollableDetails.horizontal(
                  controller: horizontalController,
                  physics: const BouncingScrollPhysics(),
                ),
                verticalDetails: ScrollableDetails.vertical(
                  controller: verticalController,
                  physics: const BouncingScrollPhysics(),
                ),
                viewportBuilder:
                    (BuildContext context, ViewportOffset vertical, ViewportOffset horizontal) {
                      return _SimpleTwoDimensionalViewport(
                        verticalOffset: vertical,
                        verticalAxisDirection: AxisDirection.down,
                        horizontalOffset: horizontal,
                        horizontalAxisDirection: AxisDirection.right,
                        delegate: TwoDimensionalChildBuilderDelegate(
                          maxXIndex: 0,
                          maxYIndex: 0,
                          builder: (BuildContext context, ChildVicinity vicinity) {
                            return const SizedBox(width: 1000.0, height: 1000.0);
                          },
                        ),
                        mainAxis: Axis.vertical,
                      );
                    },
              ),
            ),
          ),
        );

        expect(horizontalController.position.maxScrollExtent, 200.0);
        expect(horizontalController.offset, 190.0);

        final RawGestureDetectorState outerGestureDetector = tester.state<RawGestureDetectorState>(
          find.byType(RawGestureDetector).first,
        );
        outerGestureDetector.replaceSemanticsActions(<SemanticsAction>{
          SemanticsAction.scrollUp,
          SemanticsAction.scrollDown,
          SemanticsAction.scrollLeft,
          SemanticsAction.scrollRight,
        });
        await tester.pump();

        final int panScrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[
                SemanticsAction.scrollUp,
                SemanticsAction.scrollDown,
                SemanticsAction.scrollLeft,
                SemanticsAction.scrollRight,
                SemanticsAction.scrollToOffset,
              ],
            )
            .single
            .id;

        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          panScrollableId,
          SemanticsAction.scrollLeft,
        );
        await tester.pump();

        expect(
          maxHorizontalObserved,
          lessThanOrEqualTo(200.0),
          reason:
              'Bug in PR 188788: Horizontal semantic scroll on TwoDimensionalScrollable with DiagonalDragBehavior.free '
              'overscrolled past 200.0 because dragAxis (Axis.horizontal) != state.widget.axis (Axis.vertical).',
        );

        await tester.pumpAndSettle();
        semantics.dispose();
      },
    );

    testWidgets(
      'ISSUE 5: Variable-extent ListView.builder with BouncingScrollPhysics still overscrolls or truncates semantic scroll',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final controller = ScrollController();
        addTearDown(controller.dispose);

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: MediaQuery(
              data: const MediaQueryData(accessibleNavigation: true),
              child: ListView.builder(
                controller: controller,
                cacheExtent: 0.0,
                physics: const BouncingScrollPhysics(),
                itemCount: 9,
                itemBuilder: (BuildContext context, int index) {
                  return SizedBox(height: index < 8 ? 80.0 : 800.0, child: Text('Item $index'));
                },
              ),
            ),
          ),
        );

        expect(controller.position.maxScrollExtent, 120.0);

        final int scrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[SemanticsAction.scrollUp, SemanticsAction.scrollToOffset],
            )
            .single
            .id;

        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          scrollableId,
          SemanticsAction.scrollUp,
        );
        await tester.pumpAndSettle();

        expect(
          controller.offset,
          480.0,
          reason:
              'Bug in PR 188788: Semantic scroll of 480px was prematurely truncated to 120px because '
              '_ScrollableSemanticsGestureDelegate clamped against the pre-layout estimated maxScrollExtent.',
        );

        semantics.dispose();
      },
    );

    testWidgets(
      'ISSUE 6: Out-of-range ScrollPosition reverses semantic drag direction when clamped',
      (WidgetTester tester) async {
        final semantics = SemanticsTester(tester);
        final controller = ScrollController();
        addTearDown(controller.dispose);

        await tester.pumpWidget(
          Directionality(
            textDirection: TextDirection.ltr,
            child: MediaQuery(
              data: const MediaQueryData(accessibleNavigation: true),
              child: ListView(
                controller: controller,
                physics: const BouncingScrollPhysics(),
                children: List<Widget>.generate(
                  20,
                  (int i) => SizedBox(height: 40.0, child: Text('$i')),
                ),
              ),
            ),
          ),
        );

        controller.jumpTo(100.0);
        await tester.pump();

        final int scrollableId = semantics
            .nodesWith(
              actions: <SemanticsAction>[
                SemanticsAction.scrollUp,
                SemanticsAction.scrollDown,
                SemanticsAction.scrollToOffset,
              ],
            )
            .single
            .id;

        final TestGesture gesture = await tester.startGesture(const Offset(400.0, 300.0));
        await gesture.moveBy(const Offset(0.0, 160.0));
        await gesture.up();
        final double overscrolledOffset = controller.offset;
        expect(overscrolledOffset, lessThan(0.0));

        var updatedDelta = 0.0;
        controller.addListener(() {
          updatedDelta = controller.offset - overscrolledOffset;
        });

        tester.binding.pipelineOwner.semanticsOwner!.performAction(
          scrollableId,
          SemanticsAction.scrollDown,
        );

        expect(
          updatedDelta,
          lessThanOrEqualTo(0.0),
          reason:
              'Bug in PR 188788: When position.pixels is < minScrollExtent, SemanticsAction.scrollDown '
              'computed a positive clampedPixelDelta (+15.6px), scrolling UP instead of clamping/ignoring the downward scroll.',
        );

        await tester.pumpAndSettle();
        semantics.dispose();
      },
    );
  });
}

class _SimpleTwoDimensionalViewport extends TwoDimensionalViewport {
  const _SimpleTwoDimensionalViewport({
    required super.verticalOffset,
    required super.verticalAxisDirection,
    required super.horizontalOffset,
    required super.horizontalAxisDirection,
    required super.delegate,
    required super.mainAxis,
  });

  @override
  RenderTwoDimensionalViewport createRenderObject(BuildContext context) {
    return _RenderSimpleTwoDimensionalViewport(
      horizontalOffset: horizontalOffset,
      horizontalAxisDirection: horizontalAxisDirection,
      verticalOffset: verticalOffset,
      verticalAxisDirection: verticalAxisDirection,
      mainAxis: mainAxis,
      delegate: delegate as TwoDimensionalChildBuilderDelegate,
      childManager: context as TwoDimensionalChildManager,
    );
  }
}

class _RenderSimpleTwoDimensionalViewport extends RenderTwoDimensionalViewport {
  _RenderSimpleTwoDimensionalViewport({
    required super.horizontalOffset,
    required super.horizontalAxisDirection,
    required super.verticalOffset,
    required super.verticalAxisDirection,
    required super.mainAxis,
    required TwoDimensionalChildBuilderDelegate super.delegate,
    required super.childManager,
  });

  @override
  void layoutChildSequence() {
    final RenderBox child = buildOrObtainChildFor(const ChildVicinity(xIndex: 0, yIndex: 0))!;
    child.layout(const BoxConstraints(), parentUsesSize: true);
    parentDataOf(child).layoutOffset = Offset(-horizontalOffset.pixels, -verticalOffset.pixels);
    verticalOffset.applyContentDimensions(
      0.0,
      (child.size.height - viewportDimension.height).clamp(0.0, double.infinity),
    );
    horizontalOffset.applyContentDimensions(
      0.0,
      (child.size.width - viewportDimension.width).clamp(0.0, double.infinity),
    );
  }
}

class _TestFloatingHeaderDelegate extends SliverPersistentHeaderDelegate {
  _TestFloatingHeaderDelegate({required this.extent});

  final double extent;

  @override
  double get minExtent => extent;

  @override
  double get maxExtent => extent;

  @override
  Widget build(BuildContext context, double shrinkOffset, bool overlapsContent) {
    return SizedBox(height: extent, child: const Text('Floating Header'));
  }

  @override
  bool shouldRebuild(covariant _TestFloatingHeaderDelegate oldDelegate) {
    return oldDelegate.extent != extent;
  }
}