sticky_header test: Use CustomPaintOrderScrollView in test, example, and doc

By letting us control the paint order between slivers, this
fixes all the skipped tests in this test file.

Author: gnprice

lib/example/sticky_header.dart

@@ -17,8 +17,10 @@
 /// so as to set the app ID differently.
 library;
 
-import 'package:flutter/material.dart';
+// ignore: undefined_hidden_name // anticipates https://github.com/flutter/flutter/pull/164818
+import 'package:flutter/material.dart' hide SliverPaintOrder;
 
+import '../widgets/scrolling.dart';
 import '../widgets/sticky_header.dart';
 
 /// Example page using [StickyHeaderListView] and [StickyHeaderItem] in a
@@ -151,9 +153,11 @@ class ExampleVerticalDouble extends StatelessWidget {
 
     return Scaffold(
       appBar: AppBar(title: Text(title)),
-      body: CustomScrollView(
+      body: CustomPaintOrderScrollView(
         semanticChildCount: numSections,
         center: centerKey,
+        paintOrder: headerAtBottom ?
+          SliverPaintOrder.lastIsTop : SliverPaintOrder.firstIsTop,
         slivers: [
           SliverStickyHeaderList(
             key: const ValueKey('top'),

lib/widgets/sticky_header.dart

@@ -318,6 +318,8 @@ enum _HeaderGrowthPlacement {
 /// When the list item that controls the sticky header has
 /// [StickyHeaderItem.allowOverflow] true, the header will be permitted
 /// to overflow not only the item but this whole sliver.
+/// (This provides seamless behavior if, for example, two back-to-back slivers
+/// are used for implementing a double-ended scrollable list.)
 ///
 /// The caller is responsible for arranging the paint order between slivers
 /// so that this works correctly: a sliver that might overflow must be painted
@@ -327,12 +329,11 @@ enum _HeaderGrowthPlacement {
 /// then this [SliverStickyHeaderList] must paint after any slivers that appear
 /// to the right of this sliver.
 ///
-/// At present there's no off-the-shelf way to fully control the paint order
-/// between slivers.
-/// See the implementation of [RenderViewport.childrenInPaintOrder] for the
-/// paint order provided by [CustomScrollView]; it meets the above needs
-/// for some arrangements of slivers and values of [headerPlacement],
-/// but not others.
+/// To control the viewport's paint order,
+/// consider using [CustomPaintOrderScrollView] instead of [CustomScrollView].
+/// Then [SliverPaintOrder.firstIsTop] for [HeaderPlacement.scrollingStart],
+/// or [SliverPaintOrder.lastIsTop] for [HeaderPlacement.scrollingEnd],
+/// suffices for meeting the needs above.
 class SliverStickyHeaderList extends RenderObjectWidget {
   SliverStickyHeaderList({
     super.key,

test/widgets/sticky_header_test.dart

@@ -4,9 +4,12 @@ import 'package:checks/checks.dart';
 import 'package:collection/collection.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
-import 'package:flutter/rendering.dart';
-import 'package:flutter/widgets.dart';
+// ignore: undefined_hidden_name // anticipates https://github.com/flutter/flutter/pull/164818
+import 'package:flutter/rendering.dart' hide SliverPaintOrder;
+// ignore: undefined_hidden_name // anticipates https://github.com/flutter/flutter/pull/164818
+import 'package:flutter/widgets.dart' hide SliverPaintOrder;
 import 'package:flutter_test/flutter_test.dart';
+import 'package:zulip/widgets/scrolling.dart';
 import 'package:zulip/widgets/sticky_header.dart';
 
 void main() {
@@ -230,19 +233,24 @@ void main() {
   });
 
   testWidgets('hit-testing for header overflowing sliver', (tester) async {
+    const centerKey = ValueKey('center');
     final controller = ScrollController();
     await tester.pumpWidget(Directionality(textDirection: TextDirection.ltr,
-      child: CustomScrollView(
+      child: CustomPaintOrderScrollView(
         controller: controller,
+        anchor: 0.0,
+        center: centerKey,
+        paintOrder: SliverPaintOrder.firstIsTop,
         slivers: [
           SliverStickyHeaderList(
             headerPlacement: HeaderPlacement.scrollingStart,
             delegate: SliverChildListDelegate(
               List.generate(100, (i) => StickyHeaderItem(
                 allowOverflow: true,
-                header: _Header(i, height: 20),
-                child: _Item(i, height: 100))))),
+                header: _Header(99 - i, height: 20),
+                child: _Item(99 - i, height: 100))))),
           SliverStickyHeaderList(
+            key: centerKey,
             headerPlacement: HeaderPlacement.scrollingStart,
             delegate: SliverChildListDelegate(
               List.generate(100, (i) => StickyHeaderItem(
@@ -251,9 +259,8 @@ void main() {
                 child: _Item(100 + i, height: 100))))),
         ])));
 
-    const topExtent = 100 * 100;
     for (double topHeight in [5, 10, 15, 20]) {
-      controller.jumpTo(topExtent - topHeight);
+      controller.jumpTo(-topHeight);
       await tester.pump();
       // The top sliver occupies height [topHeight].
       // Its header overhangs by `20 - topHeight`.
@@ -327,49 +334,34 @@ Future<void> _checkSequence(
   ];
 
   final double anchor;
-  bool paintOrderGood;
   if (reverseGrowth) {
     slivers.reverseRange(0, slivers.length);
     anchor = 1.0;
-    paintOrderGood = switch (sliverConfig) {
-      _SliverConfig.single => true,
-      // The last sliver will paint last.
-      _SliverConfig.backToBack => headerPlacement == HeaderPlacement.scrollingEnd,
-      // The last sliver will paint last.
-      _SliverConfig.followed => headerPlacement == HeaderPlacement.scrollingEnd,
-    };
   } else {
     anchor = 0.0;
-    paintOrderGood = switch (sliverConfig) {
-      _SliverConfig.single => true,
-      // The last sliver will paint last.
-      _SliverConfig.backToBack => headerPlacement == HeaderPlacement.scrollingEnd,
-      // The first sliver will paint last.
-      _SliverConfig.followed => headerPlacement == HeaderPlacement.scrollingStart,
-    };
   }
 
-  final skipBecausePaintOrder = allowOverflow && !paintOrderGood;
-  if (skipBecausePaintOrder) {
-    // TODO need to control paint order of slivers within viewport in order to
-    //   make some configurations behave properly when headers overflow slivers
-    markTestSkipped('sliver paint order');
-    // Don't return yet; we'll still check layout, and skip specific affected checks below.
+  SliverPaintOrder paintOrder = SliverPaintOrder.centerTopFirstBottom;
+  if (!allowOverflow || (sliverConfig == _SliverConfig.single)) {
+    // The paint order doesn't matter.
+  } else {
+    paintOrder = headerPlacement == HeaderPlacement.scrollingStart
+      ? SliverPaintOrder.firstIsTop : SliverPaintOrder.lastIsTop;
   }
 
-
   final controller = ScrollController();
   await tester.pumpWidget(Directionality(
     textDirection: textDirection ?? TextDirection.rtl,
-    child: CustomScrollView(
+    child: CustomPaintOrderScrollView(
       controller: controller,
       scrollDirection: axis,
       reverse: reverse,
       anchor: anchor,
       center: center,
+      paintOrder: paintOrder,
       slivers: slivers)));
 
-  final overallSize = tester.getSize(find.byType(CustomScrollView));
+  final overallSize = tester.getSize(find.bySubtype<CustomScrollView>());
   final extent = overallSize.onAxis(axis);
   assert(extent % 100 == 0);
   assert(sliverScrollExtent - extent > 100);
@@ -418,7 +410,6 @@ Future<void> _checkSequence(
     check(insetExtent(find.byType(_Header))).equals(expectedHeaderInsetExtent);
 
     // Check the header gets hit when it should, and not when it shouldn't.
-    if (skipBecausePaintOrder) return;
     await tester.tapAt(headerInset(1));
     await tester.tapAt(headerInset(expectedHeaderInsetExtent - 1));
     check(_TapLogged.takeTapLog())..length.equals(2)