nav_bar.dart 83 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:math' as math;
6 7 8
import 'dart:ui' show ImageFilter;

import 'package:flutter/foundation.dart';
9
import 'package:flutter/rendering.dart';
10
import 'package:flutter/services.dart';
11 12
import 'package:flutter/widgets.dart';

13
import 'button.dart';
14
import 'colors.dart';
15
import 'constants.dart';
16
import 'icons.dart';
17
import 'page_scaffold.dart';
18
import 'route.dart';
xster's avatar
xster committed
19
import 'theme.dart';
20

21
/// Standard iOS navigation bar height without the status bar.
22 23
///
/// This height is constant and independent of accessibility as it is in iOS.
24
const double _kNavBarPersistentHeight = kMinInteractiveDimensionCupertino;
25

26
/// Size increase from expanding the navigation bar into an iOS-11-style large title
27
/// form in a [CustomScrollView].
28
const double _kNavBarLargeTitleHeightExtension = 52.0;
29 30

/// Number of logical pixels scrolled down before the title text is transferred
31
/// from the normal navigation bar to a big title below the navigation bar.
32 33 34 35
const double _kNavBarShowLargeTitleThreshold = 10.0;

const double _kNavBarEdgePadding = 16.0;

36 37
const double _kNavBarBackButtonTapWidth = 50.0;

38
/// Title text transfer fade.
39
const Duration _kNavBarTitleFadeDuration = Duration(milliseconds: 150);
40

41
const Color _kDefaultNavBarBorderColor = Color(0x4D000000);
42

43 44
const Border _kDefaultNavBarBorder = Border(
  bottom: BorderSide(
45
    color: _kDefaultNavBarBorderColor,
46
    width: 0.0, // 0.0 means one physical pixel
47 48 49
  ),
);

50 51
// There's a single tag for all instances of navigation bars because they can
// all transition between each other (per Navigator) via Hero transitions.
52
const _HeroTag _defaultHeroTag = _HeroTag(null);
53

54
@immutable
55
class _HeroTag {
56 57
  const _HeroTag(this.navigator);

58
  final NavigatorState? navigator;
59

60 61
  // Let the Hero tag be described in tree dumps.
  @override
62 63 64 65 66 67 68 69 70 71
  String toString() => 'Default Hero tag for Cupertino navigation bars with navigator $navigator';

  @override
  bool operator ==(Object other) {
    if (identical(this, other)) {
      return true;
    }
    if (other.runtimeType != runtimeType) {
      return false;
    }
72 73
    return other is _HeroTag
        && other.navigator == navigator;
74 75 76
  }

  @override
77
  int get hashCode => identityHashCode(navigator);
78 79
}

80 81 82 83 84 85 86 87 88
// An `AnimatedWidget` that imposes a fixed size on its child widget, and
// shifts the child widget in the parent stack, driven by its `offsetAnimation`
// property.
class _FixedSizeSlidingTransition extends AnimatedWidget {
  const _FixedSizeSlidingTransition({
    required this.isLTR,
    required this.offsetAnimation,
    required this.size,
    required this.child,
89
  }) : super(listenable: offsetAnimation);
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124

  // Whether the writing direction used in the navigation bar transition is
  // left-to-right.
  final bool isLTR;

  // The fixed size to impose on `child`.
  final Size size;

  // The animated offset from the top-leading corner of the stack.
  //
  // When `isLTR` is true, the `Offset` is the position of the child widget in
  // the stack render box's regular coordinate space.
  //
  // When `isLTR` is false, the coordinate system is flipped around the
  // horizontal axis and the origin is set to the top right corner of the render
  // boxes. In other words, this parameter describes the offset from the top
  // right corner of the stack, to the top right corner of the child widget, and
  // the x-axis runs right to left.
  final Animation<Offset> offsetAnimation;

  final Widget child;

  @override
  Widget build(BuildContext context) {
    return Positioned(
      top: offsetAnimation.value.dy,
      left: isLTR ? offsetAnimation.value.dx : null,
      right: isLTR ? null : offsetAnimation.value.dx,
      width: size.width,
      height: size.height,
      child: child,
    );
  }
}

125 126 127 128 129 130
/// Returns `child` wrapped with background and a bottom border if background color
/// is opaque. Otherwise, also blur with [BackdropFilter].
///
/// When `updateSystemUiOverlay` is true, the nav bar will update the OS
/// status bar's color theme based on the background color of the nav bar.
Widget _wrapWithBackground({
131 132 133 134
  Border? border,
  required Color backgroundColor,
  Brightness? brightness,
  required Widget child,
135 136 137 138
  bool updateSystemUiOverlay = true,
}) {
  Widget result = child;
  if (updateSystemUiOverlay) {
139 140
    final bool isDark = backgroundColor.computeLuminance() < 0.179;
    final Brightness newBrightness = brightness ?? (isDark ? Brightness.dark : Brightness.light);
141
    final SystemUiOverlayStyle overlayStyle;
142 143 144 145 146 147 148 149
    switch (newBrightness) {
      case Brightness.dark:
        overlayStyle = SystemUiOverlayStyle.light;
        break;
      case Brightness.light:
        overlayStyle = SystemUiOverlayStyle.dark;
        break;
    }
150
    result = AnnotatedRegion<SystemUiOverlayStyle>(
151 152 153 154
      value: overlayStyle,
      child: result,
    );
  }
155 156
  final DecoratedBox childWithBackground = DecoratedBox(
    decoration: BoxDecoration(
157 158 159 160 161 162 163 164 165
      border: border,
      color: backgroundColor,
    ),
    child: result,
  );

  if (backgroundColor.alpha == 0xFF)
    return childWithBackground;

166 167 168
  return ClipRect(
    child: BackdropFilter(
      filter: ImageFilter.blur(sigmaX: 10.0, sigmaY: 10.0),
169 170 171 172 173 174 175
      child: childWithBackground,
    ),
  );
}

// Whether the current route supports nav bar hero transitions from or to.
bool _isTransitionable(BuildContext context) {
176
  final ModalRoute<dynamic>? route = ModalRoute.of(context);
177 178 179 180 181 182 183

  // Fullscreen dialogs never transitions their nav bar with other push-style
  // pages' nav bars or with other fullscreen dialog pages on the way in or on
  // the way out.
  return route is PageRoute && !route.fullscreenDialog;
}

184
/// An iOS-styled navigation bar.
185 186 187 188 189 190 191
///
/// The navigation bar is a toolbar that minimally consists of a widget, normally
/// a page title, in the [middle] of the toolbar.
///
/// It also supports a [leading] and [trailing] widget before and after the
/// [middle] widget while keeping the [middle] widget centered.
///
192 193 194 195
/// The [leading] widget will automatically be a back chevron icon button (or a
/// close button in case of a fullscreen dialog) to pop the current route if none
/// is provided and [automaticallyImplyLeading] is true (true by default).
///
196
/// The [middle] widget will automatically be a title text from the current
197 198
/// [CupertinoPageRoute] if none is provided and [automaticallyImplyMiddle] is
/// true (true by default).
199
///
200 201 202 203 204
/// It should be placed at top of the screen and automatically accounts for
/// the OS's status bar.
///
/// If the given [backgroundColor]'s opacity is not 1.0 (which is the case by
/// default), it will produce a blurring effect to the content behind it.
205
///
206
/// When [transitionBetweenRoutes] is true, this navigation bar will transition
207
/// on top of the routes instead of inside them if the route being transitioned
208 209 210 211 212
/// to also has a [CupertinoNavigationBar] or a [CupertinoSliverNavigationBar]
/// with [transitionBetweenRoutes] set to true. If [transitionBetweenRoutes] is
/// true, none of the [Widget] parameters can contain a key in its subtree since
/// that widget will exist in multiple places in the tree simultaneously.
///
213 214 215 216 217
/// By default, only one [CupertinoNavigationBar] or [CupertinoSliverNavigationBar]
/// should be present in each [PageRoute] to support the default transitions.
/// Use [transitionBetweenRoutes] or [heroTag] to customize the transition
/// behavior for multiple navigation bars per route.
///
218 219 220 221 222 223 224 225
/// When used in a [CupertinoPageScaffold], [CupertinoPageScaffold.navigationBar]
/// has its text scale factor set to 1.0 and does not respond to text scale factor
/// changes from the operating system, to match the native iOS behavior. To override
/// this behavior, wrap each of the `navigationBar`'s components inside a [MediaQuery]
/// with the desired [MediaQueryData.textScaleFactor] value. The text scale factor
/// value from the operating system can be retrieved in many ways, such as querying
/// [MediaQuery.textScaleFactorOf] against [CupertinoApp]'s [BuildContext].
///
226
/// {@tool dartpad}
227 228 229 230
/// This example shows a [CupertinoNavigationBar] placed in a [CupertinoPageScaffold].
/// Since [backgroundColor]'s opacity is not 1.0, there is a blur effect and
/// content slides underneath.
///
231
/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_navigation_bar.0.dart **
232 233
/// {@end-tool}
///
234 235
/// See also:
///
236 237 238 239
///  * [CupertinoPageScaffold], a page layout helper typically hosting the
///    [CupertinoNavigationBar].
///  * [CupertinoSliverNavigationBar] for a navigation bar to be placed in a
///    scrolling list and that supports iOS-11-style large titles.
240
///  * <https://developer.apple.com/design/human-interface-guidelines/ios/bars/navigation-bars/>
241
class CupertinoNavigationBar extends StatefulWidget implements ObstructingPreferredSizeWidget {
242
  /// Creates a navigation bar in the iOS style.
243
  const CupertinoNavigationBar({
244
    super.key,
245
    this.leading,
246
    this.automaticallyImplyLeading = true,
247 248
    this.automaticallyImplyMiddle = true,
    this.previousPageTitle,
249
    this.middle,
250
    this.trailing,
251
    this.border = _kDefaultNavBarBorder,
xster's avatar
xster committed
252
    this.backgroundColor,
253
    this.brightness,
254
    this.padding,
255 256
    this.transitionBetweenRoutes = true,
    this.heroTag = _defaultHeroTag,
257
  }) : assert(automaticallyImplyLeading != null),
258
       assert(automaticallyImplyMiddle != null),
259 260 261 262
       assert(transitionBetweenRoutes != null),
       assert(
         heroTag != null,
         'heroTag cannot be null. Use transitionBetweenRoutes = false to '
263
         'disable Hero transition on this navigation bar.',
264 265 266 267
       ),
       assert(
         !transitionBetweenRoutes || identical(heroTag, _defaultHeroTag),
         'Cannot specify a heroTag override if this navigation bar does not '
268
         'transition due to transitionBetweenRoutes = false.',
269
       );
270

271
  /// {@template flutter.cupertino.CupertinoNavigationBar.leading}
272
  /// Widget to place at the start of the navigation bar. Normally a back button
273
  /// for a normal page or a cancel button for full page dialogs.
274 275 276 277
  ///
  /// If null and [automaticallyImplyLeading] is true, an appropriate button
  /// will be automatically created.
  /// {@endtemplate}
278
  final Widget? leading;
279

280
  /// {@template flutter.cupertino.CupertinoNavigationBar.automaticallyImplyLeading}
281 282 283 284 285
  /// Controls whether we should try to imply the leading widget if null.
  ///
  /// If true and [leading] is null, automatically try to deduce what the [leading]
  /// widget should be. If [leading] widget is not null, this parameter has no effect.
  ///
286 287 288 289 290 291 292 293 294
  /// Specifically this navigation bar will:
  ///
  /// 1. Show a 'Close' button if the current route is a `fullscreenDialog`.
  /// 2. Show a back chevron with [previousPageTitle] if [previousPageTitle] is
  ///    not null.
  /// 3. Show a back chevron with the previous route's `title` if the current
  ///    route is a [CupertinoPageRoute] and the previous route is also a
  ///    [CupertinoPageRoute].
  ///
295
  /// This value cannot be null.
296
  /// {@endtemplate}
297 298
  final bool automaticallyImplyLeading;

299 300 301 302 303 304 305 306 307
  /// Controls whether we should try to imply the middle widget if null.
  ///
  /// If true and [middle] is null, automatically fill in a [Text] widget with
  /// the current route's `title` if the route is a [CupertinoPageRoute].
  /// If [middle] widget is not null, this parameter has no effect.
  ///
  /// This value cannot be null.
  final bool automaticallyImplyMiddle;

308
  /// {@template flutter.cupertino.CupertinoNavigationBar.previousPageTitle}
309 310 311 312 313 314 315 316 317 318
  /// Manually specify the previous route's title when automatically implying
  /// the leading back button.
  ///
  /// Overrides the text shown with the back chevron instead of automatically
  /// showing the previous [CupertinoPageRoute]'s `title` when
  /// [automaticallyImplyLeading] is true.
  ///
  /// Has no effect when [leading] is not null or if [automaticallyImplyLeading]
  /// is false.
  /// {@endtemplate}
319
  final String? previousPageTitle;
320

321
  /// Widget to place in the middle of the navigation bar. Normally a title or
322
  /// a segmented control.
323 324 325 326
  ///
  /// If null and [automaticallyImplyMiddle] is true, an appropriate [Text]
  /// title will be created if the current route is a [CupertinoPageRoute] and
  /// has a `title`.
327
  final Widget? middle;
328

329
  /// {@template flutter.cupertino.CupertinoNavigationBar.trailing}
330
  /// Widget to place at the end of the navigation bar. Normally additional actions
331
  /// taken on the page such as a search or edit function.
332
  /// {@endtemplate}
333
  final Widget? trailing;
334

335 336
  // TODO(xster): https://github.com/flutter/flutter/issues/10469 implement
  // support for double row navigation bars.
337

338
  /// {@template flutter.cupertino.CupertinoNavigationBar.backgroundColor}
339
  /// The background color of the navigation bar. If it contains transparency, the
340 341
  /// tab bar will automatically produce a blurring effect to the content
  /// behind it.
xster's avatar
xster committed
342 343
  ///
  /// Defaults to [CupertinoTheme]'s `barBackgroundColor` if null.
344
  /// {@endtemplate}
345
  final Color? backgroundColor;
346

347
  /// {@template flutter.cupertino.CupertinoNavigationBar.brightness}
348 349 350 351 352 353 354 355 356
  /// The brightness of the specified [backgroundColor].
  ///
  /// Setting this value changes the style of the system status bar. Typically
  /// used to increase the contrast ratio of the system status bar over
  /// [backgroundColor].
  ///
  /// If set to null, the value of the property will be inferred from the relative
  /// luminance of [backgroundColor].
  /// {@endtemplate}
357
  final Brightness? brightness;
358

359
  /// {@template flutter.cupertino.CupertinoNavigationBar.padding}
360 361 362 363 364 365 366 367 368 369 370
  /// Padding for the contents of the navigation bar.
  ///
  /// If null, the navigation bar will adopt the following defaults:
  ///
  ///  * Vertically, contents will be sized to the same height as the navigation
  ///    bar itself minus the status bar.
  ///  * Horizontally, padding will be 16 pixels according to iOS specifications
  ///    unless the leading widget is an automatically inserted back button, in
  ///    which case the padding will be 0.
  ///
  /// Vertical padding won't change the height of the nav bar.
371
  /// {@endtemplate}
372
  final EdgeInsetsDirectional? padding;
373

374
  /// {@template flutter.cupertino.CupertinoNavigationBar.border}
375 376 377
  /// The border of the navigation bar. By default renders a single pixel bottom border side.
  ///
  /// If a border is null, the navigation bar will not display a border.
378
  /// {@endtemplate}
379
  final Border? border;
380

381
  /// {@template flutter.cupertino.CupertinoNavigationBar.transitionBetweenRoutes}
382 383 384 385 386 387 388
  /// Whether to transition between navigation bars.
  ///
  /// When [transitionBetweenRoutes] is true, this navigation bar will transition
  /// on top of the routes instead of inside it if the route being transitioned
  /// to also has a [CupertinoNavigationBar] or a [CupertinoSliverNavigationBar]
  /// with [transitionBetweenRoutes] set to true.
  ///
xster's avatar
xster committed
389 390 391 392
  /// This transition will also occur on edge back swipe gestures like on iOS
  /// but only if the previous page below has `maintainState` set to true on the
  /// [PageRoute].
  ///
393 394 395 396 397 398 399
  /// When set to true, only one navigation bar can be present per route unless
  /// [heroTag] is also set.
  ///
  /// This value defaults to true and cannot be null.
  /// {@endtemplate}
  final bool transitionBetweenRoutes;

400
  /// {@template flutter.cupertino.CupertinoNavigationBar.heroTag}
401 402 403
  /// Tag for the navigation bar's Hero widget if [transitionBetweenRoutes] is true.
  ///
  /// Defaults to a common tag between all [CupertinoNavigationBar] and
404 405 406 407 408 409 410
  /// [CupertinoSliverNavigationBar] instances of the same [Navigator]. With the
  /// default tag, all navigation bars of the same navigator can transition
  /// between each other as long as there's only one navigation bar per route.
  ///
  /// This [heroTag] can be overridden to manually handle having multiple
  /// navigation bars per route or to transition between multiple
  /// [Navigator]s.
411 412 413 414 415 416
  ///
  /// Cannot be null. To disable Hero transitions for this navigation bar,
  /// set [transitionBetweenRoutes] to false.
  /// {@endtemplate}
  final Object heroTag;

417
  /// True if the navigation bar's background color has no transparency.
418
  @override
419
  bool shouldFullyObstruct(BuildContext context) {
420
    final Color backgroundColor = CupertinoDynamicColor.maybeResolve(this.backgroundColor, context)
421 422 423
                               ?? CupertinoTheme.of(context).barBackgroundColor;
    return backgroundColor.alpha == 0xFF;
  }
424

425
  @override
426
  Size get preferredSize {
427
    return const Size.fromHeight(_kNavBarPersistentHeight);
428
  }
429

430
  @override
431
  State<CupertinoNavigationBar> createState() => _CupertinoNavigationBarState();
432 433 434 435 436 437
}

// A state class exists for the nav bar so that the keys of its sub-components
// don't change when rebuilding the nav bar, causing the sub-components to
// lose their own states.
class _CupertinoNavigationBarState extends State<CupertinoNavigationBar> {
438
  late _NavigationBarStaticComponentsKeys keys;
439 440 441 442

  @override
  void initState() {
    super.initState();
443
    keys = _NavigationBarStaticComponentsKeys();
444 445
  }

446 447
  @override
  Widget build(BuildContext context) {
xster's avatar
xster committed
448
    final Color backgroundColor =
449
      CupertinoDynamicColor.maybeResolve(widget.backgroundColor, context) ?? CupertinoTheme.of(context).barBackgroundColor;
xster's avatar
xster committed
450

451
    final _NavigationBarStaticComponents components = _NavigationBarStaticComponents(
452 453 454 455 456 457 458 459 460 461 462
      keys: keys,
      route: ModalRoute.of(context),
      userLeading: widget.leading,
      automaticallyImplyLeading: widget.automaticallyImplyLeading,
      automaticallyImplyTitle: widget.automaticallyImplyMiddle,
      previousPageTitle: widget.previousPageTitle,
      userMiddle: widget.middle,
      userTrailing: widget.trailing,
      padding: widget.padding,
      userLargeTitle: null,
      large: false,
463 464
    );

465 466
    final Widget navBar = _wrapWithBackground(
      border: widget.border,
xster's avatar
xster committed
467
      backgroundColor: backgroundColor,
468
      brightness: widget.brightness,
xster's avatar
xster committed
469 470 471 472 473 474
      child: DefaultTextStyle(
        style: CupertinoTheme.of(context).textTheme.textStyle,
        child: _PersistentNavigationBar(
          components: components,
          padding: widget.padding,
        ),
475 476 477 478
      ),
    );

    if (!widget.transitionBetweenRoutes || !_isTransitionable(context)) {
xster's avatar
xster committed
479
      // Lint ignore to maintain backward compatibility.
480
      return navBar;
481 482
    }

483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506
    return Builder(
      // Get the context that might have a possibly changed CupertinoTheme.
      builder: (BuildContext context) {
        return Hero(
          tag: widget.heroTag == _defaultHeroTag
              ? _HeroTag(Navigator.of(context))
              : widget.heroTag,
          createRectTween: _linearTranslateWithLargestRectSizeTween,
          placeholderBuilder: _navBarHeroLaunchPadBuilder,
          flightShuttleBuilder: _navBarHeroFlightShuttleBuilder,
          transitionOnUserGestures: true,
          child: _TransitionableNavigationBar(
            componentsKeys: keys,
            backgroundColor: backgroundColor,
            backButtonTextStyle: CupertinoTheme.of(context).textTheme.navActionTextStyle,
            titleTextStyle: CupertinoTheme.of(context).textTheme.navTitleTextStyle,
            largeTitleTextStyle: null,
            border: widget.border,
            hasUserMiddle: widget.middle != null,
            largeExpanded: false,
            child: navBar,
          ),
        );
      },
507
    );
508 509
  }
}
510

511
/// An iOS-styled navigation bar with iOS-11-style large titles using slivers.
512 513 514 515
///
/// The [CupertinoSliverNavigationBar] must be placed in a sliver group such
/// as the [CustomScrollView].
///
516 517
/// This navigation bar consists of two sections, a pinned static section on top
/// and a sliding section containing iOS-11-style large title below it.
518 519
///
/// It should be placed at top of the screen and automatically accounts for
520
/// the iOS status bar.
521
///
522 523
/// Minimally, a [largeTitle] widget will appear in the middle of the app bar
/// when the sliver is collapsed and transfer to the area below in larger font
524 525
/// when the sliver is expanded.
///
526 527
/// For advanced uses, an optional [middle] widget can be supplied to show a
/// different widget in the middle of the navigation bar when the sliver is collapsed.
528
///
529 530 531 532 533 534 535
/// Like [CupertinoNavigationBar], it also supports a [leading] and [trailing]
/// widget on the static section on top that remains while scrolling.
///
/// The [leading] widget will automatically be a back chevron icon button (or a
/// close button in case of a fullscreen dialog) to pop the current route if none
/// is provided and [automaticallyImplyLeading] is true (true by default).
///
536
/// The [largeTitle] widget will automatically be a title text from the current
537 538
/// [CupertinoPageRoute] if none is provided and [automaticallyImplyTitle] is
/// true (true by default).
539
///
540
/// When [transitionBetweenRoutes] is true, this navigation bar will transition
541
/// on top of the routes instead of inside them if the route being transitioned
542 543 544 545 546 547
/// to also has a [CupertinoNavigationBar] or a [CupertinoSliverNavigationBar]
/// with [transitionBetweenRoutes] set to true. If [transitionBetweenRoutes] is
/// true, none of the [Widget] parameters can contain any [GlobalKey]s in their
/// subtrees since those widgets will exist in multiple places in the tree
/// simultaneously.
///
548 549 550 551 552
/// By default, only one [CupertinoNavigationBar] or [CupertinoSliverNavigationBar]
/// should be present in each [PageRoute] to support the default transitions.
/// Use [transitionBetweenRoutes] or [heroTag] to customize the transition
/// behavior for multiple navigation bars per route.
///
553 554 555 556 557 558 559 560
/// `CupertinoSliverNavigationBar` has its text scale factor set to 1.0 by default
/// and does not respond to text scale factor changes from the operating system,
/// to match the native iOS behavior. To override this behavior, wrap each of the
/// `CupertinoSliverNavigationBar`'s components inside a [MediaQuery] with the
/// desired [MediaQueryData.textScaleFactor] value. The text scale factor value
/// from the operating system can be retrieved in many ways, such as querying
/// [MediaQuery.textScaleFactorOf] against [CupertinoApp]'s [BuildContext].
///
561 562 563
/// The [stretch] parameter determines whether the nav bar should stretch to
/// fill the over-scroll area. The nav bar can still expand and contract as the
/// user scrolls, but it will also stretch when the user over-scrolls if the
564
/// [stretch] value is `true`. Defaults to `false`.
565
///
566 567 568 569 570 571
/// {@tool dartpad}
/// This example shows [CupertinoSliverNavigationBar] in action inside a [CustomScrollView].
///
/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_sliver_nav_bar.0.dart **
/// {@end-tool}
///
572 573
/// See also:
///
574 575
///  * [CupertinoNavigationBar], an iOS navigation bar for use on non-scrolling
///    pages.
576
///  * [CustomScrollView], a ScrollView that creates custom scroll effects using slivers.
577
///  * <https://developer.apple.com/design/human-interface-guidelines/ios/bars/navigation-bars/>
578
class CupertinoSliverNavigationBar extends StatefulWidget {
579 580 581
  /// Creates a navigation bar for scrolling lists.
  ///
  /// The [largeTitle] argument is required and must not be null.
582
  const CupertinoSliverNavigationBar({
583
    super.key,
584
    this.largeTitle,
585
    this.leading,
586
    this.automaticallyImplyLeading = true,
587 588
    this.automaticallyImplyTitle = true,
    this.previousPageTitle,
589 590
    this.middle,
    this.trailing,
591
    this.border = _kDefaultNavBarBorder,
xster's avatar
xster committed
592
    this.backgroundColor,
593
    this.brightness,
594
    this.padding,
595 596
    this.transitionBetweenRoutes = true,
    this.heroTag = _defaultHeroTag,
597
    this.stretch = false,
598 599
  }) : assert(automaticallyImplyLeading != null),
       assert(automaticallyImplyTitle != null),
600 601 602 603
       assert(
         automaticallyImplyTitle == true || largeTitle != null,
         'No largeTitle has been provided but automaticallyImplyTitle is also '
         'false. Either provide a largeTitle or set automaticallyImplyTitle to '
604
         'true.',
605
       );
606 607 608 609

  /// The navigation bar's title.
  ///
  /// This text will appear in the top static navigation bar when collapsed and
610 611 612 613 614 615 616 617 618 619 620
  /// below the navigation bar, in a larger font, when expanded.
  ///
  /// A suitable [DefaultTextStyle] is provided around this widget as it is
  /// moved around, to change its font size.
  ///
  /// If [middle] is null, then the [largeTitle] widget will be inserted into
  /// the tree in two places when transitioning from the collapsed state to the
  /// expanded state. It is therefore imperative that this subtree not contain
  /// any [GlobalKey]s, and that it not rely on maintaining state (for example,
  /// animations will not survive the transition from one location to the other,
  /// and may in fact be visible in two places at once during the transition).
621 622 623 624
  ///
  /// If null and [automaticallyImplyTitle] is true, an appropriate [Text]
  /// title will be created if the current route is a [CupertinoPageRoute] and
  /// has a `title`.
625 626 627
  ///
  /// This parameter must either be non-null or the route must have a title
  /// ([CupertinoPageRoute.title]) and [automaticallyImplyTitle] must be true.
628
  final Widget? largeTitle;
629

630
  /// {@macro flutter.cupertino.CupertinoNavigationBar.leading}
631 632
  ///
  /// This widget is visible in both collapsed and expanded states.
633
  final Widget? leading;
634

635
  /// {@macro flutter.cupertino.CupertinoNavigationBar.automaticallyImplyLeading}
636 637 638
  final bool automaticallyImplyLeading;

  /// Controls whether we should try to imply the [largeTitle] widget if null.
639
  ///
640 641 642
  /// If true and [largeTitle] is null, automatically fill in a [Text] widget
  /// with the current route's `title` if the route is a [CupertinoPageRoute].
  /// If [largeTitle] widget is not null, this parameter has no effect.
643 644
  ///
  /// This value cannot be null.
645 646
  final bool automaticallyImplyTitle;

647
  /// {@macro flutter.cupertino.CupertinoNavigationBar.previousPageTitle}
648
  final String? previousPageTitle;
649

650 651
  /// A widget to place in the middle of the static navigation bar instead of
  /// the [largeTitle].
652 653
  ///
  /// This widget is visible in both collapsed and expanded states. The text
654 655
  /// supplied in [largeTitle] will no longer appear in collapsed state if a
  /// [middle] widget is provided.
656
  final Widget? middle;
657

658
  /// {@macro flutter.cupertino.CupertinoNavigationBar.trailing}
659 660
  ///
  /// This widget is visible in both collapsed and expanded states.
661
  final Widget? trailing;
662

663
  /// {@macro flutter.cupertino.CupertinoNavigationBar.backgroundColor}
664
  final Color? backgroundColor;
665

666
  /// {@macro flutter.cupertino.CupertinoNavigationBar.brightness}
667
  final Brightness? brightness;
668

669
  /// {@macro flutter.cupertino.CupertinoNavigationBar.padding}
670
  final EdgeInsetsDirectional? padding;
671

672
  /// {@macro flutter.cupertino.CupertinoNavigationBar.border}
673
  final Border? border;
674

675
  /// {@macro flutter.cupertino.CupertinoNavigationBar.transitionBetweenRoutes}
676 677
  final bool transitionBetweenRoutes;

678
  /// {@macro flutter.cupertino.CupertinoNavigationBar.heroTag}
679 680
  final Object heroTag;

681
  /// True if the navigation bar's background color has no transparency.
682
  bool get opaque => backgroundColor?.alpha == 0xFF;
683

684 685 686 687
  /// Whether the nav bar should stretch to fill the over-scroll area.
  ///
  /// The nav bar can still expand and contract as the user scrolls, but it will
  /// also stretch when the user over-scrolls if the [stretch] value is `true`.
688 689 690 691 692 693
  ///
  /// When set to `true`, the nav bar will prevent subsequent slivers from
  /// accessing overscrolls. This may be undesirable for using overscroll-based
  /// widgets like the [CupertinoSliverRefreshControl].
  ///
  /// Defaults to `false`.
694 695
  final bool stretch;

696
  @override
697
  State<CupertinoSliverNavigationBar> createState() => _CupertinoSliverNavigationBarState();
698 699 700 701 702 703
}

// A state class exists for the nav bar so that the keys of its sub-components
// don't change when rebuilding the nav bar, causing the sub-components to
// lose their own states.
class _CupertinoSliverNavigationBarState extends State<CupertinoSliverNavigationBar> {
704
  late _NavigationBarStaticComponentsKeys keys;
705 706 707 708

  @override
  void initState() {
    super.initState();
709
    keys = _NavigationBarStaticComponentsKeys();
710 711
  }

712 713
  @override
  Widget build(BuildContext context) {
714
    final _NavigationBarStaticComponents components = _NavigationBarStaticComponents(
715 716 717 718 719 720 721 722 723 724 725
      keys: keys,
      route: ModalRoute.of(context),
      userLeading: widget.leading,
      automaticallyImplyLeading: widget.automaticallyImplyLeading,
      automaticallyImplyTitle: widget.automaticallyImplyTitle,
      previousPageTitle: widget.previousPageTitle,
      userMiddle: widget.middle,
      userTrailing: widget.trailing,
      userLargeTitle: widget.largeTitle,
      padding: widget.padding,
      large: true,
726 727
    );

728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745
    return MediaQuery(
      data: MediaQuery.of(context).copyWith(textScaleFactor: 1),
      child: SliverPersistentHeader(
        pinned: true, // iOS navigation bars are always pinned.
        delegate: _LargeTitleNavigationBarSliverDelegate(
          keys: keys,
          components: components,
          userMiddle: widget.middle,
          backgroundColor: CupertinoDynamicColor.maybeResolve(widget.backgroundColor, context) ?? CupertinoTheme.of(context).barBackgroundColor,
          brightness: widget.brightness,
          border: widget.border,
          padding: widget.padding,
          actionsForegroundColor: CupertinoTheme.of(context).primaryColor,
          transitionBetweenRoutes: widget.transitionBetweenRoutes,
          heroTag: widget.heroTag,
          persistentHeight: _kNavBarPersistentHeight + MediaQuery.of(context).padding.top,
          alwaysShowMiddle: widget.middle != null,
          stretchConfiguration: widget.stretch ? OverScrollHeaderStretchConfiguration() : null,
xster's avatar
xster committed
746
        ),
747 748
      ),
    );
749 750 751
  }
}

752
class _LargeTitleNavigationBarSliverDelegate
753
    extends SliverPersistentHeaderDelegate with DiagnosticableTreeMixin {
754
  _LargeTitleNavigationBarSliverDelegate({
755 756 757 758 759 760 761 762 763 764 765 766
    required this.keys,
    required this.components,
    required this.userMiddle,
    required this.backgroundColor,
    required this.brightness,
    required this.border,
    required this.padding,
    required this.actionsForegroundColor,
    required this.transitionBetweenRoutes,
    required this.heroTag,
    required this.persistentHeight,
    required this.alwaysShowMiddle,
767
    required this.stretchConfiguration,
768 769 770 771 772 773
  }) : assert(persistentHeight != null),
       assert(alwaysShowMiddle != null),
       assert(transitionBetweenRoutes != null);

  final _NavigationBarStaticComponentsKeys keys;
  final _NavigationBarStaticComponents components;
774
  final Widget? userMiddle;
775
  final Color backgroundColor;
776 777 778
  final Brightness? brightness;
  final Border? border;
  final EdgeInsetsDirectional? padding;
779
  final Color actionsForegroundColor;
780 781 782 783
  final bool transitionBetweenRoutes;
  final Object heroTag;
  final double persistentHeight;
  final bool alwaysShowMiddle;
784 785 786 787 788 789 790

  @override
  double get minExtent => persistentHeight;

  @override
  double get maxExtent => persistentHeight + _kNavBarLargeTitleHeightExtension;

791 792 793
  @override
  OverScrollHeaderStretchConfiguration? stretchConfiguration;

794 795 796 797
  @override
  Widget build(BuildContext context, double shrinkOffset, bool overlapsContent) {
    final bool showLargeTitle = shrinkOffset < maxExtent - minExtent - _kNavBarShowLargeTitleThreshold;

798
    final _PersistentNavigationBar persistentNavigationBar =
799
        _PersistentNavigationBar(
800
      components: components,
801
      padding: padding,
802 803 804
      // If a user specified middle exists, always show it. Otherwise, show
      // title when sliver is collapsed.
      middleVisible: alwaysShowMiddle ? null : !showLargeTitle,
805 806
    );

807
    final Widget navBar = _wrapWithBackground(
808
      border: border,
809
      backgroundColor: CupertinoDynamicColor.resolve(backgroundColor, context),
810
      brightness: brightness,
xster's avatar
xster committed
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845
      child: DefaultTextStyle(
        style: CupertinoTheme.of(context).textTheme.textStyle,
        child: Stack(
          fit: StackFit.expand,
          children: <Widget>[
            Positioned(
              top: persistentHeight,
              left: 0.0,
              right: 0.0,
              bottom: 0.0,
              child: ClipRect(
                // The large title starts at the persistent bar.
                // It's aligned with the bottom of the sliver and expands clipped
                // and behind the persistent bar.
                child: OverflowBox(
                  minHeight: 0.0,
                  maxHeight: double.infinity,
                  alignment: AlignmentDirectional.bottomStart,
                  child: Padding(
                    padding: const EdgeInsetsDirectional.only(
                      start: _kNavBarEdgePadding,
                      bottom: 8.0, // Bottom has a different padding.
                    ),
                    child: SafeArea(
                      top: false,
                      bottom: false,
                      child: AnimatedOpacity(
                        opacity: showLargeTitle ? 1.0 : 0.0,
                        duration: _kNavBarTitleFadeDuration,
                        child: Semantics(
                          header: true,
                          child: DefaultTextStyle(
                            style: CupertinoTheme.of(context).textTheme.navLargeTitleTextStyle,
                            maxLines: 1,
                            overflow: TextOverflow.ellipsis,
846
                            child: components.largeTitle!,
xster's avatar
xster committed
847
                          ),
848 849 850 851 852 853 854
                        ),
                      ),
                    ),
                  ),
                ),
              ),
            ),
xster's avatar
xster committed
855 856 857 858 859 860 861 862
            Positioned(
              left: 0.0,
              right: 0.0,
              top: 0.0,
              child: persistentNavigationBar,
            ),
          ],
        ),
863 864
      ),
    );
865 866 867 868 869

    if (!transitionBetweenRoutes || !_isTransitionable(context)) {
      return navBar;
    }

870
    return Hero(
871 872 873
      tag: heroTag == _defaultHeroTag
          ? _HeroTag(Navigator.of(context))
          : heroTag,
874 875 876
      createRectTween: _linearTranslateWithLargestRectSizeTween,
      flightShuttleBuilder: _navBarHeroFlightShuttleBuilder,
      placeholderBuilder: _navBarHeroLaunchPadBuilder,
xster's avatar
xster committed
877
      transitionOnUserGestures: true,
878 879 880
      // This is all the way down here instead of being at the top level of
      // CupertinoSliverNavigationBar like CupertinoNavigationBar because it
      // needs to wrap the top level RenderBox rather than a RenderSliver.
881
      child: _TransitionableNavigationBar(
882
        componentsKeys: keys,
883
        backgroundColor: CupertinoDynamicColor.resolve(backgroundColor, context),
xster's avatar
xster committed
884 885 886
        backButtonTextStyle: CupertinoTheme.of(context).textTheme.navActionTextStyle,
        titleTextStyle: CupertinoTheme.of(context).textTheme.navTitleTextStyle,
        largeTitleTextStyle: CupertinoTheme.of(context).textTheme.navLargeTitleTextStyle,
887 888 889 890 891 892
        border: border,
        hasUserMiddle: userMiddle != null,
        largeExpanded: showLargeTitle,
        child: navBar,
      ),
    );
893 894 895
  }

  @override
896
  bool shouldRebuild(_LargeTitleNavigationBarSliverDelegate oldDelegate) {
897
    return components != oldDelegate.components
898
        || userMiddle != oldDelegate.userMiddle
899
        || backgroundColor != oldDelegate.backgroundColor
900 901 902 903 904 905 906
        || border != oldDelegate.border
        || padding != oldDelegate.padding
        || actionsForegroundColor != oldDelegate.actionsForegroundColor
        || transitionBetweenRoutes != oldDelegate.transitionBetweenRoutes
        || persistentHeight != oldDelegate.persistentHeight
        || alwaysShowMiddle != oldDelegate.alwaysShowMiddle
        || heroTag != oldDelegate.heroTag;
907 908 909
  }
}

910
/// The top part of the navigation bar that's never scrolled away.
911
///
912
/// Consists of the entire navigation bar without background and border when used
913 914
/// without large titles. With large titles, it's the top static half that
/// doesn't scroll.
915 916
class _PersistentNavigationBar extends StatelessWidget {
  const _PersistentNavigationBar({
917
    required this.components,
918
    this.padding,
919
    this.middleVisible,
920
  });
921

922
  final _NavigationBarStaticComponents components;
923

924
  final EdgeInsetsDirectional? padding;
925 926
  /// Whether the middle widget has a visible animated opacity. A null value
  /// means the middle opacity will not be animated.
927
  final bool? middleVisible;
928

929 930
  @override
  Widget build(BuildContext context) {
931
    Widget? middle = components.middle;
932

933
    if (middle != null) {
934
      middle = DefaultTextStyle(
xster's avatar
xster committed
935
        style: CupertinoTheme.of(context).textTheme.navTitleTextStyle,
936
        child: Semantics(header: true, child: middle),
937 938 939 940 941
      );
      // When the middle's visibility can change on the fly like with large title
      // slivers, wrap with animated opacity.
      middle = middleVisible == null
        ? middle
942
        : AnimatedOpacity(
943
          opacity: middleVisible! ? 1.0 : 0.0,
944 945
          duration: _kNavBarTitleFadeDuration,
          child: middle,
946
        );
947
    }
948

949 950 951
    Widget? leading = components.leading;
    final Widget? backChevron = components.backChevron;
    final Widget? backLabel = components.backLabel;
952

953
    if (leading == null && backChevron != null && backLabel != null) {
954
      leading = CupertinoNavigationBarBackButton._assemble(
955 956
        backChevron,
        backLabel,
957
      );
958
    }
959

960
    Widget paddedToolbar = NavigationToolbar(
961 962 963
      leading: leading,
      middle: middle,
      trailing: components.trailing,
964
      middleSpacing: 6.0,
965 966 967
    );

    if (padding != null) {
968
      paddedToolbar = Padding(
969
        padding: EdgeInsets.only(
970 971
          top: padding!.top,
          bottom: padding!.bottom,
972 973 974 975 976
        ),
        child: paddedToolbar,
      );
    }

977
    return SizedBox(
978
      height: _kNavBarPersistentHeight + MediaQuery.of(context).padding.top,
979
      child: SafeArea(
980 981
        bottom: false,
        child: paddedToolbar,
982 983
      ),
    );
984 985
  }
}
986

987 988 989 990 991 992 993 994 995
// A collection of keys always used when building static routes' nav bars's
// components with _NavigationBarStaticComponents and read in
// _NavigationBarTransition in Hero flights in order to reference the components'
// RenderBoxes for their positions.
//
// These keys should never re-appear inside the Hero flights.
@immutable
class _NavigationBarStaticComponentsKeys {
  _NavigationBarStaticComponentsKeys()
996 997 998 999 1000 1001 1002
    : navBarBoxKey = GlobalKey(debugLabel: 'Navigation bar render box'),
      leadingKey = GlobalKey(debugLabel: 'Leading'),
      backChevronKey = GlobalKey(debugLabel: 'Back chevron'),
      backLabelKey = GlobalKey(debugLabel: 'Back label'),
      middleKey = GlobalKey(debugLabel: 'Middle'),
      trailingKey = GlobalKey(debugLabel: 'Trailing'),
      largeTitleKey = GlobalKey(debugLabel: 'Large title');
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019

  final GlobalKey navBarBoxKey;
  final GlobalKey leadingKey;
  final GlobalKey backChevronKey;
  final GlobalKey backLabelKey;
  final GlobalKey middleKey;
  final GlobalKey trailingKey;
  final GlobalKey largeTitleKey;
}

// Based on various user Widgets and other parameters, construct KeyedSubtree
// components that are used in common by the CupertinoNavigationBar and
// CupertinoSliverNavigationBar. The KeyedSubtrees are inserted into static
// routes and the KeyedSubtrees' child are reused in the Hero flights.
@immutable
class _NavigationBarStaticComponents {
  _NavigationBarStaticComponents({
1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030
    required _NavigationBarStaticComponentsKeys keys,
    required ModalRoute<dynamic>? route,
    required Widget? userLeading,
    required bool automaticallyImplyLeading,
    required bool automaticallyImplyTitle,
    required String? previousPageTitle,
    required Widget? userMiddle,
    required Widget? userTrailing,
    required Widget? userLargeTitle,
    required EdgeInsetsDirectional? padding,
    required bool large,
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071
  }) : leading = createLeading(
         leadingKey: keys.leadingKey,
         userLeading: userLeading,
         route: route,
         automaticallyImplyLeading: automaticallyImplyLeading,
         padding: padding,
       ),
       backChevron = createBackChevron(
         backChevronKey: keys.backChevronKey,
         userLeading: userLeading,
         route: route,
         automaticallyImplyLeading: automaticallyImplyLeading,
       ),
       backLabel = createBackLabel(
         backLabelKey: keys.backLabelKey,
         userLeading: userLeading,
         route: route,
         previousPageTitle: previousPageTitle,
         automaticallyImplyLeading: automaticallyImplyLeading,
       ),
       middle = createMiddle(
         middleKey: keys.middleKey,
         userMiddle: userMiddle,
         userLargeTitle: userLargeTitle,
         route: route,
         automaticallyImplyTitle: automaticallyImplyTitle,
         large: large,
       ),
       trailing = createTrailing(
         trailingKey: keys.trailingKey,
         userTrailing: userTrailing,
         padding: padding,
       ),
       largeTitle = createLargeTitle(
         largeTitleKey: keys.largeTitleKey,
         userLargeTitle: userLargeTitle,
         route: route,
         automaticImplyTitle: automaticallyImplyTitle,
         large: large,
       );

1072 1073 1074
  static Widget? _derivedTitle({
    required bool automaticallyImplyTitle,
    ModalRoute<dynamic>? currentRoute,
1075 1076 1077
  }) {
    // Auto use the CupertinoPageRoute's title if middle not provided.
    if (automaticallyImplyTitle &&
1078
        currentRoute is CupertinoRouteTransitionMixin &&
1079
        currentRoute.title != null) {
1080
      return Text(currentRoute.title!);
1081 1082 1083 1084 1085
    }

    return null;
  }

1086 1087 1088 1089 1090 1091 1092
  final KeyedSubtree? leading;
  static KeyedSubtree? createLeading({
    required GlobalKey leadingKey,
    required Widget? userLeading,
    required ModalRoute<dynamic>? route,
    required bool automaticallyImplyLeading,
    required EdgeInsetsDirectional? padding,
1093
  }) {
1094
    Widget? leadingContent;
1095 1096 1097 1098 1099 1100 1101 1102 1103

    if (userLeading != null) {
      leadingContent = userLeading;
    } else if (
      automaticallyImplyLeading &&
      route is PageRoute &&
      route.canPop &&
      route.fullscreenDialog
    ) {
1104
      leadingContent = CupertinoButton(
1105
        padding: EdgeInsets.zero,
1106
        onPressed: () { route.navigator!.maybePop(); },
1107
        child: const Text('Close'),
1108 1109 1110 1111 1112 1113 1114
      );
    }

    if (leadingContent == null) {
      return null;
    }

1115
    return KeyedSubtree(
1116
      key: leadingKey,
1117 1118
      child: Padding(
        padding: EdgeInsetsDirectional.only(
1119 1120
          start: padding?.start ?? _kNavBarEdgePadding,
        ),
xster's avatar
xster committed
1121 1122 1123
        child: IconTheme.merge(
          data: const IconThemeData(
            size: 32.0,
1124
          ),
xster's avatar
xster committed
1125
          child: leadingContent,
1126 1127 1128 1129 1130
        ),
      ),
    );
  }

1131 1132 1133 1134 1135 1136
  final KeyedSubtree? backChevron;
  static KeyedSubtree? createBackChevron({
    required GlobalKey backChevronKey,
    required Widget? userLeading,
    required ModalRoute<dynamic>? route,
    required bool automaticallyImplyLeading,
1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147
  }) {
    if (
      userLeading != null ||
      !automaticallyImplyLeading ||
      route == null ||
      !route.canPop ||
      (route is PageRoute && route.fullscreenDialog)
    ) {
      return null;
    }

1148
    return KeyedSubtree(key: backChevronKey, child: const _BackChevron());
1149 1150 1151 1152
  }

  /// This widget is not decorated with a font since the font style could
  /// animate during transitions.
1153 1154 1155 1156 1157 1158 1159
  final KeyedSubtree? backLabel;
  static KeyedSubtree? createBackLabel({
    required GlobalKey backLabelKey,
    required Widget? userLeading,
    required ModalRoute<dynamic>? route,
    required bool automaticallyImplyLeading,
    required String? previousPageTitle,
1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170
  }) {
    if (
      userLeading != null ||
      !automaticallyImplyLeading ||
      route == null ||
      !route.canPop ||
      (route is PageRoute && route.fullscreenDialog)
    ) {
      return null;
    }

1171
    return KeyedSubtree(
1172
      key: backLabelKey,
1173
      child: _BackLabel(
1174 1175 1176 1177 1178 1179 1180 1181
        specifiedPreviousTitle: previousPageTitle,
        route: route,
      ),
    );
  }

  /// This widget is not decorated with a font since the font style could
  /// animate during transitions.
1182 1183 1184 1185 1186 1187 1188 1189
  final KeyedSubtree? middle;
  static KeyedSubtree? createMiddle({
    required GlobalKey middleKey,
    required Widget? userMiddle,
    required Widget? userLargeTitle,
    required bool large,
    required bool automaticallyImplyTitle,
    required ModalRoute<dynamic>? route,
1190
  }) {
1191
    Widget? middleContent = userMiddle;
1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205

    if (large) {
      middleContent ??= userLargeTitle;
    }

    middleContent ??= _derivedTitle(
      automaticallyImplyTitle: automaticallyImplyTitle,
      currentRoute: route,
    );

    if (middleContent == null) {
      return null;
    }

1206
    return KeyedSubtree(
1207 1208 1209 1210 1211
      key: middleKey,
      child: middleContent,
    );
  }

1212 1213 1214 1215 1216
  final KeyedSubtree? trailing;
  static KeyedSubtree? createTrailing({
    required GlobalKey trailingKey,
    required Widget? userTrailing,
    required EdgeInsetsDirectional? padding,
1217 1218 1219 1220 1221
  }) {
    if (userTrailing == null) {
      return null;
    }

1222
    return KeyedSubtree(
1223
      key: trailingKey,
1224 1225
      child: Padding(
        padding: EdgeInsetsDirectional.only(
1226 1227
          end: padding?.end ?? _kNavBarEdgePadding,
        ),
xster's avatar
xster committed
1228 1229 1230
        child: IconTheme.merge(
          data: const IconThemeData(
            size: 32.0,
1231
          ),
xster's avatar
xster committed
1232
          child: userTrailing,
1233 1234 1235 1236 1237 1238 1239
        ),
      ),
    );
  }

  /// This widget is not decorated with a font since the font style could
  /// animate during transitions.
1240 1241 1242 1243 1244 1245 1246
  final KeyedSubtree? largeTitle;
  static KeyedSubtree? createLargeTitle({
    required GlobalKey largeTitleKey,
    required Widget? userLargeTitle,
    required bool large,
    required bool automaticImplyTitle,
    required ModalRoute<dynamic>? route,
1247 1248 1249 1250 1251
  }) {
    if (!large) {
      return null;
    }

1252
    final Widget? largeTitleContent = userLargeTitle ?? _derivedTitle(
1253 1254 1255 1256 1257 1258 1259 1260 1261
      automaticallyImplyTitle: automaticImplyTitle,
      currentRoute: route,
    );

    assert(
      largeTitleContent != null,
      'largeTitle was not provided and there was no title from the route.',
    );

1262
    return KeyedSubtree(
1263
      key: largeTitleKey,
1264
      child: largeTitleContent!,
1265 1266 1267 1268
    );
  }
}

1269 1270 1271 1272 1273 1274
/// A nav bar back button typically used in [CupertinoNavigationBar].
///
/// This is automatically inserted into [CupertinoNavigationBar] and
/// [CupertinoSliverNavigationBar]'s `leading` slot when
/// `automaticallyImplyLeading` is true.
///
1275 1276 1277 1278
/// When manually inserted, the [CupertinoNavigationBarBackButton] should only
/// be used in routes that can be popped unless a custom [onPressed] is
/// provided.
///
1279 1280 1281 1282 1283 1284 1285 1286 1287
/// Shows a back chevron and the previous route's title when available from
/// the previous [CupertinoPageRoute.title]. If [previousPageTitle] is specified,
/// it will be shown instead.
class CupertinoNavigationBarBackButton extends StatelessWidget {
  /// Construct a [CupertinoNavigationBarBackButton] that can be used to pop
  /// the current route.
  ///
  /// The [color] parameter must not be null.
  const CupertinoNavigationBarBackButton({
1288
    super.key,
xster's avatar
xster committed
1289
    this.color,
1290
    this.previousPageTitle,
1291
    this.onPressed,
1292
  }) : _backChevron = null,
1293
       _backLabel = null;
1294 1295 1296 1297 1298 1299 1300

  // Allow the back chevron and label to be separately created (and keyed)
  // because they animate separately during page transitions.
  const CupertinoNavigationBarBackButton._assemble(
    this._backChevron,
    this._backLabel,
  ) : previousPageTitle = null,
1301 1302
      color = null,
      onPressed = null;
1303 1304

  /// The [Color] of the back button.
1305
  ///
xster's avatar
xster committed
1306 1307 1308
  /// Can be used to override the color of the back button chevron and label.
  ///
  /// Defaults to [CupertinoTheme]'s `primaryColor` if null.
1309
  final Color? color;
1310

1311 1312 1313
  /// An override for showing the previous route's title. If null, it will be
  /// automatically derived from [CupertinoPageRoute.title] if the current and
  /// previous routes are both [CupertinoPageRoute]s.
1314
  final String? previousPageTitle;
1315

1316 1317 1318 1319
  /// An override callback to perform instead of the default behavior which is
  /// to pop the [Navigator].
  ///
  /// It can, for instance, be used to pop the platform's navigation stack
1320 1321
  /// via [SystemNavigator] instead of Flutter's [Navigator] in add-to-app
  /// situations.
1322 1323
  ///
  /// Defaults to null.
1324
  final VoidCallback? onPressed;
1325

1326
  final Widget? _backChevron;
1327

1328
  final Widget? _backLabel;
1329

1330 1331
  @override
  Widget build(BuildContext context) {
1332
    final ModalRoute<dynamic>? currentRoute = ModalRoute.of(context);
1333 1334
    if (onPressed == null) {
      assert(
1335
        currentRoute?.canPop ?? false,
1336 1337 1338
        'CupertinoNavigationBarBackButton should only be used in routes that can be popped',
      );
    }
1339

xster's avatar
xster committed
1340 1341
    TextStyle actionTextStyle = CupertinoTheme.of(context).textTheme.navActionTextStyle;
    if (color != null) {
1342
      actionTextStyle = actionTextStyle.copyWith(color: CupertinoDynamicColor.maybeResolve(color, context));
xster's avatar
xster committed
1343 1344
    }

1345
    return CupertinoButton(
1346
      padding: EdgeInsets.zero,
1347
      child: Semantics(
1348 1349 1350 1351
        container: true,
        excludeSemantics: true,
        label: 'Back',
        button: true,
xster's avatar
xster committed
1352 1353 1354 1355
        child: DefaultTextStyle(
          style: actionTextStyle,
          child: ConstrainedBox(
            constraints: const BoxConstraints(minWidth: _kNavBarBackButtonTapWidth),
1356
            child: Row(
1357 1358 1359 1360 1361
              mainAxisSize: MainAxisSize.min,
              children: <Widget>[
                const Padding(padding: EdgeInsetsDirectional.only(start: 8.0)),
                _backChevron ?? const _BackChevron(),
                const Padding(padding: EdgeInsetsDirectional.only(start: 6.0)),
1362 1363
                Flexible(
                  child: _backLabel ?? _BackLabel(
1364 1365 1366
                    specifiedPreviousTitle: previousPageTitle,
                    route: currentRoute,
                  ),
1367
                ),
1368 1369
              ],
            ),
1370 1371 1372
          ),
        ),
      ),
1373 1374
      onPressed: () {
        if (onPressed != null) {
1375
          onPressed!();
1376 1377 1378 1379
        } else {
          Navigator.maybePop(context);
        }
      },
1380 1381 1382
    );
  }
}
1383

1384

1385
class _BackChevron extends StatelessWidget {
1386
  const _BackChevron();
1387 1388

  @override
1389
  Widget build(BuildContext context) {
1390
    final TextDirection textDirection = Directionality.of(context);
1391
    final TextStyle textStyle = DefaultTextStyle.of(context).style;
1392 1393 1394

    // Replicate the Icon logic here to get a tightly sized icon and add
    // custom non-square padding.
1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406
    Widget iconWidget = Padding(
      padding: const EdgeInsetsDirectional.only(start: 6, end: 2),
      child: Text.rich(
        TextSpan(
          text: String.fromCharCode(CupertinoIcons.back.codePoint),
          style: TextStyle(
            inherit: false,
            color: textStyle.color,
            fontSize: 30.0,
            fontFamily: CupertinoIcons.back.fontFamily,
            package: CupertinoIcons.back.fontPackage,
          ),
1407 1408 1409 1410 1411
        ),
      ),
    );
    switch (textDirection) {
      case TextDirection.rtl:
1412 1413
        iconWidget = Transform(
          transform: Matrix4.identity()..scale(-1.0, 1.0, 1.0),
1414 1415 1416 1417 1418 1419 1420 1421
          alignment: Alignment.center,
          transformHitTests: false,
          child: iconWidget,
        );
        break;
      case TextDirection.ltr:
        break;
    }
1422

1423 1424 1425
    return iconWidget;
  }
}
1426

1427 1428 1429 1430
/// A widget that shows next to the back chevron when `automaticallyImplyLeading`
/// is true.
class _BackLabel extends StatelessWidget {
  const _BackLabel({
1431 1432
    required this.specifiedPreviousTitle,
    required this.route,
1433
  });
1434

1435 1436
  final String? specifiedPreviousTitle;
  final ModalRoute<dynamic>? route;
1437 1438 1439

  // `child` is never passed in into ValueListenableBuilder so it's always
  // null here and unused.
1440
  Widget _buildPreviousTitleWidget(BuildContext context, String? previousTitle, Widget? child) {
1441 1442 1443
    if (previousTitle == null) {
      return const SizedBox(height: 0.0, width: 0.0);
    }
1444

1445
    Text textWidget = Text(
1446 1447 1448 1449 1450 1451 1452
      previousTitle,
      maxLines: 1,
      overflow: TextOverflow.ellipsis,
    );

    if (previousTitle.length > 12) {
      textWidget = const Text('Back');
1453
    }
1454

1455
    return Align(
1456 1457 1458 1459
      alignment: AlignmentDirectional.centerStart,
      widthFactor: 1.0,
      child: textWidget,
    );
1460 1461 1462
  }

  @override
1463 1464 1465
  Widget build(BuildContext context) {
    if (specifiedPreviousTitle != null) {
      return _buildPreviousTitleWidget(context, specifiedPreviousTitle, null);
1466
    } else if (route is CupertinoRouteTransitionMixin<dynamic> && !route!.isFirst) {
1467
      final CupertinoRouteTransitionMixin<dynamic> cupertinoRoute = route! as CupertinoRouteTransitionMixin<dynamic>;
1468 1469 1470
      // There is no timing issue because the previousTitle Listenable changes
      // happen during route modifications before the ValueListenableBuilder
      // is built.
1471
      return ValueListenableBuilder<String?>(
1472 1473 1474 1475 1476 1477
        valueListenable: cupertinoRoute.previousTitle,
        builder: _buildPreviousTitleWidget,
      );
    } else {
      return const SizedBox(height: 0.0, width: 0.0);
    }
1478 1479
  }
}
1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490

/// This should always be the first child of Hero widgets.
///
/// This class helps each Hero transition obtain the start or end navigation
/// bar's box size and the inner components of the navigation bar that will
/// move around.
///
/// It should be wrapped around the biggest [RenderBox] of the static
/// navigation bar in each route.
class _TransitionableNavigationBar extends StatelessWidget {
  _TransitionableNavigationBar({
1491 1492 1493 1494 1495 1496 1497 1498 1499
    required this.componentsKeys,
    required this.backgroundColor,
    required this.backButtonTextStyle,
    required this.titleTextStyle,
    required this.largeTitleTextStyle,
    required this.border,
    required this.hasUserMiddle,
    required this.largeExpanded,
    required this.child,
1500 1501
  }) : assert(componentsKeys != null),
       assert(largeExpanded != null),
xster's avatar
xster committed
1502
       assert(!largeExpanded || largeTitleTextStyle != null),
1503 1504 1505
       super(key: componentsKeys.navBarBoxKey);

  final _NavigationBarStaticComponentsKeys componentsKeys;
1506
  final Color? backgroundColor;
xster's avatar
xster committed
1507 1508
  final TextStyle backButtonTextStyle;
  final TextStyle titleTextStyle;
1509 1510
  final TextStyle? largeTitleTextStyle;
  final Border? border;
1511 1512 1513 1514 1515
  final bool hasUserMiddle;
  final bool largeExpanded;
  final Widget child;

  RenderBox get renderBox {
1516
    final RenderBox box = componentsKeys.navBarBoxKey.currentContext!.findRenderObject()! as RenderBox;
1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528
    assert(
      box.attached,
      '_TransitionableNavigationBar.renderBox should be called when building '
      'hero flight shuttles when the from and the to nav bar boxes are already '
      'laid out and painted.',
    );
    return box;
  }

  @override
  Widget build(BuildContext context) {
    assert(() {
1529
      bool inHero = false;
1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545
      context.visitAncestorElements((Element ancestor) {
        if (ancestor is ComponentElement) {
          assert(
            ancestor.widget.runtimeType != _NavigationBarTransition,
            '_TransitionableNavigationBar should never re-appear inside '
            '_NavigationBarTransition. Keyed _TransitionableNavigationBar should '
            'only serve as anchor points in routes rather than appearing inside '
            'Hero flights themselves.',
          );
          if (ancestor.widget.runtimeType == Hero) {
            inHero = true;
          }
        }
        return true;
      });
      assert(
1546
        inHero,
1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572
        '_TransitionableNavigationBar should only be added as the immediate '
        'child of Hero widgets.',
      );
      return true;
    }());
    return child;
  }
}

/// This class represents the widget that will be in the Hero flight instead of
/// the 2 static navigation bars by taking inner components from both.
///
/// The `topNavBar` parameter is the nav bar that was on top regardless of
/// push/pop direction.
///
/// Similarly, the `bottomNavBar` parameter is the nav bar that was at the
/// bottom regardless of the push/pop direction.
///
/// If [MediaQuery.padding] is still present in this widget's [BuildContext],
/// that padding will become part of the transitional navigation bar as well.
///
/// [MediaQuery.padding] should be consistent between the from/to routes and
/// the Hero overlay. Inconsistent [MediaQuery.padding] will produce undetermined
/// results.
class _NavigationBarTransition extends StatelessWidget {
  _NavigationBarTransition({
1573 1574 1575
    required this.animation,
    required this.topNavBar,
    required this.bottomNavBar,
1576
  }) : heightTween = Tween<double>(
1577 1578 1579
         begin: bottomNavBar.renderBox.size.height,
         end: topNavBar.renderBox.size.height,
       ),
1580
       backgroundTween = ColorTween(
1581 1582 1583
         begin: bottomNavBar.backgroundColor,
         end: topNavBar.backgroundColor,
       ),
1584
       borderTween = BorderTween(
1585 1586 1587 1588 1589
         begin: bottomNavBar.border,
         end: topNavBar.border,
       );

  final Animation<double> animation;
1590 1591
  final _TransitionableNavigationBar topNavBar;
  final _TransitionableNavigationBar bottomNavBar;
1592 1593 1594 1595 1596 1597 1598

  final Tween<double> heightTween;
  final ColorTween backgroundTween;
  final BorderTween borderTween;

  @override
  Widget build(BuildContext context) {
1599 1600 1601 1602
    final _NavigationBarComponentsTransition componentsTransition = _NavigationBarComponentsTransition(
      animation: animation,
      bottomNavBar: bottomNavBar,
      topNavBar: topNavBar,
1603
      directionality: Directionality.of(context),
1604 1605
    );

1606 1607 1608 1609 1610
    final List<Widget> children = <Widget>[
      // Draw an empty navigation bar box with changing shape behind all the
      // moving components without any components inside it itself.
      AnimatedBuilder(
        animation: animation,
1611
        builder: (BuildContext context, Widget? child) {
1612 1613 1614
          return _wrapWithBackground(
            // Don't update the system status bar color mid-flight.
            updateSystemUiOverlay: false,
1615
            backgroundColor: backgroundTween.evaluate(animation)!,
1616
            border: borderTween.evaluate(animation),
1617
            child: SizedBox(
1618 1619 1620 1621 1622 1623 1624
              height: heightTween.evaluate(animation),
              width: double.infinity,
            ),
          );
        },
      ),
      // Draw all the components on top of the empty bar box.
1625 1626 1627 1628 1629 1630
      if (componentsTransition.bottomBackChevron != null) componentsTransition.bottomBackChevron!,
      if (componentsTransition.bottomBackLabel != null) componentsTransition.bottomBackLabel!,
      if (componentsTransition.bottomLeading != null) componentsTransition.bottomLeading!,
      if (componentsTransition.bottomMiddle != null) componentsTransition.bottomMiddle!,
      if (componentsTransition.bottomLargeTitle != null) componentsTransition.bottomLargeTitle!,
      if (componentsTransition.bottomTrailing != null) componentsTransition.bottomTrailing!,
1631
      // Draw top components on top of the bottom components.
1632 1633 1634 1635 1636 1637
      if (componentsTransition.topLeading != null) componentsTransition.topLeading!,
      if (componentsTransition.topBackChevron != null) componentsTransition.topBackChevron!,
      if (componentsTransition.topBackLabel != null) componentsTransition.topBackLabel!,
      if (componentsTransition.topMiddle != null) componentsTransition.topMiddle!,
      if (componentsTransition.topLargeTitle != null) componentsTransition.topLargeTitle!,
      if (componentsTransition.topTrailing != null) componentsTransition.topTrailing!,
1638 1639 1640 1641 1642 1643 1644
    ];


    // The actual outer box is big enough to contain both the bottom and top
    // navigation bars. It's not a direct Rect lerp because some components
    // can actually be outside the linearly lerp'ed Rect in the middle of
    // the animation, such as the topLargeTitle.
1645
    return SizedBox(
1646
      height: math.max(heightTween.begin!, heightTween.end!) + MediaQuery.of(context).padding.top,
1647
      width: double.infinity,
1648
      child: Stack(
1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678
        children: children,
      ),
    );
  }
}

/// This class helps create widgets that are in transition based on static
/// components from the bottom and top navigation bars.
///
/// It animates these transitional components both in terms of position and
/// their appearance.
///
/// Instead of running the transitional components through their normal static
/// navigation bar layout logic, this creates transitional widgets that are based
/// on these widgets' existing render objects' layout and position.
///
/// This is possible because this widget is only used during Hero transitions
/// where both the from and to routes are already built and laid out.
///
/// The components' existing layout constraints and positions are then
/// replicated using [Positioned] or [PositionedTransition] wrappers.
///
/// This class should never return [KeyedSubtree]s created by
/// _NavigationBarStaticComponents directly. Since widgets from
/// _NavigationBarStaticComponents are still present in the widget tree during the
/// hero transitions, it would cause global key duplications. Instead, return
/// only the [KeyedSubtree]s' child.
@immutable
class _NavigationBarComponentsTransition {
  _NavigationBarComponentsTransition({
1679 1680 1681 1682
    required this.animation,
    required _TransitionableNavigationBar bottomNavBar,
    required _TransitionableNavigationBar topNavBar,
    required TextDirection directionality,
1683 1684 1685 1686
  }) : bottomComponents = bottomNavBar.componentsKeys,
       topComponents = topNavBar.componentsKeys,
       bottomNavBarBox = bottomNavBar.renderBox,
       topNavBarBox = topNavBar.renderBox,
xster's avatar
xster committed
1687 1688 1689 1690 1691 1692
       bottomBackButtonTextStyle = bottomNavBar.backButtonTextStyle,
       topBackButtonTextStyle = topNavBar.backButtonTextStyle,
       bottomTitleTextStyle = bottomNavBar.titleTextStyle,
       topTitleTextStyle = topNavBar.titleTextStyle,
       bottomLargeTitleTextStyle = bottomNavBar.largeTitleTextStyle,
       topLargeTitleTextStyle = topNavBar.largeTitleTextStyle,
1693 1694 1695 1696 1697 1698
       bottomHasUserMiddle = bottomNavBar.hasUserMiddle,
       topHasUserMiddle = topNavBar.hasUserMiddle,
       bottomLargeExpanded = bottomNavBar.largeExpanded,
       topLargeExpanded = topNavBar.largeExpanded,
       transitionBox =
           // paintBounds are based on offset zero so it's ok to expand the Rects.
1699 1700
           bottomNavBar.renderBox.paintBounds.expandToInclude(topNavBar.renderBox.paintBounds),
       forwardDirection = directionality == TextDirection.ltr ? 1.0 : -1.0;
1701

1702
  static final Animatable<double> fadeOut = Tween<double>(
1703 1704 1705
    begin: 1.0,
    end: 0.0,
  );
1706
  static final Animatable<double> fadeIn = Tween<double>(
1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720
    begin: 0.0,
    end: 1.0,
  );

  final Animation<double> animation;
  final _NavigationBarStaticComponentsKeys bottomComponents;
  final _NavigationBarStaticComponentsKeys topComponents;

  // These render boxes that are the ancestors of all the bottom and top
  // components are used to determine the components' relative positions inside
  // their respective navigation bars.
  final RenderBox bottomNavBarBox;
  final RenderBox topNavBarBox;

xster's avatar
xster committed
1721 1722 1723 1724
  final TextStyle bottomBackButtonTextStyle;
  final TextStyle topBackButtonTextStyle;
  final TextStyle bottomTitleTextStyle;
  final TextStyle topTitleTextStyle;
1725 1726
  final TextStyle? bottomLargeTitleTextStyle;
  final TextStyle? topLargeTitleTextStyle;
xster's avatar
xster committed
1727

1728 1729 1730 1731 1732 1733 1734 1735 1736
  final bool bottomHasUserMiddle;
  final bool topHasUserMiddle;
  final bool bottomLargeExpanded;
  final bool topLargeExpanded;

  // This is the outer box in which all the components will be fitted. The
  // sizing component of RelativeRects will be based on this rect's size.
  final Rect transitionBox;

1737 1738 1739
  // x-axis unity number representing the direction of growth for text.
  final double forwardDirection;

1740 1741 1742 1743
  // Take a widget it its original ancestor navigation bar render box and
  // translate it into a RelativeBox in the transition navigation bar box.
  RelativeRect positionInTransitionBox(
    GlobalKey key, {
1744
    required RenderBox from,
1745
  }) {
1746
    final RenderBox componentBox = key.currentContext!.findRenderObject()! as RenderBox;
1747 1748
    assert(componentBox.attached);

1749
    return RelativeRect.fromRect(
1750 1751 1752 1753 1754
      componentBox.localToGlobal(Offset.zero, ancestor: from) & componentBox.size,
      transitionBox,
    );
  }

1755 1756 1757
  // Create an animated widget that moves the given child widget between its
  // original position in its ancestor navigation bar to another widget's
  // position in that widget's navigation bar.
1758
  //
1759 1760
  // Anchor their positions based on the vertical middle of their respective
  // render boxes' leading edge.
1761
  //
1762 1763 1764 1765 1766 1767 1768
  // This method assumes there's no other transforms other than translations
  // when converting a rect from the original navigation bar's coordinate space
  // to the other navigation bar's coordinate space, to avoid performing
  // floating point operations on the size of the child widget, so that the
  // incoming constraints used for sizing the child widget will be exactly the
  // same.
  _FixedSizeSlidingTransition slideFromLeadingEdge({
1769 1770 1771 1772
    required GlobalKey fromKey,
    required RenderBox fromNavBarBox,
    required GlobalKey toKey,
    required RenderBox toNavBarBox,
1773
    required Widget child,
1774
  }) {
1775 1776
    final RenderBox fromBox = fromKey.currentContext!.findRenderObject()! as RenderBox;
    final RenderBox toBox = toKey.currentContext!.findRenderObject()! as RenderBox;
1777

1778
    final bool isLTR = forwardDirection > 0;
1779

1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810
    // The animation moves the fromBox so its anchor (left-center or right-center
    // depending on the writing direction) aligns with toBox's anchor.
    final Offset fromAnchorLocal = Offset(
      isLTR ? 0 : fromBox.size.width,
      fromBox.size.height / 2,
    );
    final Offset toAnchorLocal = Offset(
      isLTR ? 0 : toBox.size.width,
      toBox.size.height / 2,
    );
    final Offset fromAnchorInFromBox = fromBox.localToGlobal(fromAnchorLocal, ancestor: fromNavBarBox);
    final Offset toAnchorInToBox = toBox.localToGlobal(toAnchorLocal, ancestor: toNavBarBox);

    // We can't get ahold of the render box of the stack (i.e., `transitionBox`)
    // we place components on yet, but we know the stack needs to be top-leading
    // aligned with both fromNavBarBox and toNavBarBox to make the transition
    // look smooth. Also use the top-leading point as the origin for ease of
    // calculation.

    // The offset to move fromAnchor to toAnchor, in transitionBox's top-leading
    // coordinates.
    final Offset translation = isLTR
      ? toAnchorInToBox - fromAnchorInFromBox
      : Offset(toNavBarBox.size.width - toAnchorInToBox.dx, toAnchorInToBox.dy)
      - Offset(fromNavBarBox.size.width - fromAnchorInFromBox.dx, fromAnchorInFromBox.dy);

    final RelativeRect fromBoxMargin = positionInTransitionBox(fromKey, from: fromNavBarBox);
    final Offset fromOriginInTransitionBox = Offset(
      isLTR ? fromBoxMargin.left : fromBoxMargin.right,
      fromBoxMargin.top,
    );
1811

1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822
    final Tween<Offset> anchorMovementInTransitionBox = Tween<Offset>(
      begin: fromOriginInTransitionBox,
      end: fromOriginInTransitionBox + translation,
    );

    return _FixedSizeSlidingTransition(
      isLTR: isLTR,
      offsetAnimation: animation.drive(anchorMovementInTransitionBox),
      size: fromBox.size,
      child: child,
    );
1823 1824 1825
  }

  Animation<double> fadeInFrom(double t, { Curve curve = Curves.easeIn }) {
1826 1827 1828
    return animation.drive(fadeIn.chain(
      CurveTween(curve: Interval(t, 1.0, curve: curve)),
    ));
1829 1830 1831
  }

  Animation<double> fadeOutBy(double t, { Curve curve = Curves.easeOut }) {
1832 1833 1834
    return animation.drive(fadeOut.chain(
      CurveTween(curve: Interval(0.0, t, curve: curve)),
    ));
1835 1836
  }

1837 1838
  Widget? get bottomLeading {
    final KeyedSubtree? bottomLeading = bottomComponents.leadingKey.currentWidget as KeyedSubtree?;
1839 1840 1841 1842 1843

    if (bottomLeading == null) {
      return null;
    }

1844
    return Positioned.fromRelativeRect(
1845
      rect: positionInTransitionBox(bottomComponents.leadingKey, from: bottomNavBarBox),
1846
      child: FadeTransition(
1847 1848 1849 1850 1851 1852
        opacity: fadeOutBy(0.4),
        child: bottomLeading.child,
      ),
    );
  }

1853 1854
  Widget? get bottomBackChevron {
    final KeyedSubtree? bottomBackChevron = bottomComponents.backChevronKey.currentWidget as KeyedSubtree?;
1855 1856 1857 1858 1859

    if (bottomBackChevron == null) {
      return null;
    }

1860
    return Positioned.fromRelativeRect(
1861
      rect: positionInTransitionBox(bottomComponents.backChevronKey, from: bottomNavBarBox),
1862
      child: FadeTransition(
1863
        opacity: fadeOutBy(0.6),
1864
        child: DefaultTextStyle(
xster's avatar
xster committed
1865
          style: bottomBackButtonTextStyle,
1866 1867 1868 1869 1870 1871
          child: bottomBackChevron.child,
        ),
      ),
    );
  }

1872 1873
  Widget? get bottomBackLabel {
    final KeyedSubtree? bottomBackLabel = bottomComponents.backLabelKey.currentWidget as KeyedSubtree?;
1874 1875 1876 1877 1878 1879 1880

    if (bottomBackLabel == null) {
      return null;
    }

    final RelativeRect from = positionInTransitionBox(bottomComponents.backLabelKey, from: bottomNavBarBox);

1881
    // Transition away by sliding horizontally to the leading edge off of the screen.
1882
    final RelativeRectTween positionTween = RelativeRectTween(
1883
      begin: from,
1884 1885 1886 1887 1888 1889
      end: from.shift(
        Offset(
          forwardDirection * (-bottomNavBarBox.size.width / 2.0),
          0.0,
        ),
      ),
1890 1891
    );

1892
    return PositionedTransition(
1893
      rect: animation.drive(positionTween),
1894
      child: FadeTransition(
1895
        opacity: fadeOutBy(0.2),
1896
        child: DefaultTextStyle(
xster's avatar
xster committed
1897
          style: bottomBackButtonTextStyle,
1898 1899 1900 1901 1902 1903
          child: bottomBackLabel.child,
        ),
      ),
    );
  }

1904 1905 1906 1907
  Widget? get bottomMiddle {
    final KeyedSubtree? bottomMiddle = bottomComponents.middleKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? topBackLabel = topComponents.backLabelKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? topLeading = topComponents.leadingKey.currentWidget as KeyedSubtree?;
1908 1909 1910 1911 1912 1913 1914 1915

    // The middle component is non-null when the nav bar is a large title
    // nav bar but would be invisible when expanded, therefore don't show it here.
    if (!bottomHasUserMiddle && bottomLargeExpanded) {
      return null;
    }

    if (bottomMiddle != null && topBackLabel != null) {
1916
      // Move from current position to the top page's back label position.
1917 1918 1919 1920 1921
      return slideFromLeadingEdge(
        fromKey: bottomComponents.middleKey,
        fromNavBarBox: bottomNavBarBox,
        toKey: topComponents.backLabelKey,
        toNavBarBox: topNavBarBox,
1922
        child: FadeTransition(
1923 1924
          // A custom middle widget like a segmented control fades away faster.
          opacity: fadeOutBy(bottomHasUserMiddle ? 0.4 : 0.7),
1925
          child: Align(
1926 1927 1928
            // As the text shrinks, make sure it's still anchored to the leading
            // edge of a constantly sized outer box.
            alignment: AlignmentDirectional.centerStart,
1929
            child: DefaultTextStyleTransition(
1930
              style: animation.drive(TextStyleTween(
xster's avatar
xster committed
1931 1932
                begin: bottomTitleTextStyle,
                end: topBackButtonTextStyle,
1933
              )),
1934 1935 1936 1937 1938 1939 1940
              child: bottomMiddle.child,
            ),
          ),
        ),
      );
    }

1941 1942 1943
    // When the top page has a leading widget override (one of the few ways to
    // not have a top back label), don't move the bottom middle widget and just
    // fade.
1944
    if (bottomMiddle != null && topLeading != null) {
1945
      return Positioned.fromRelativeRect(
1946
        rect: positionInTransitionBox(bottomComponents.middleKey, from: bottomNavBarBox),
1947
        child: FadeTransition(
1948 1949
          opacity: fadeOutBy(bottomHasUserMiddle ? 0.4 : 0.7),
          // Keep the font when transitioning into a non-back label leading.
1950
          child: DefaultTextStyle(
xster's avatar
xster committed
1951
            style: bottomTitleTextStyle,
1952 1953 1954 1955 1956 1957 1958 1959 1960
            child: bottomMiddle.child,
          ),
        ),
      );
    }

    return null;
  }

1961 1962 1963 1964
  Widget? get bottomLargeTitle {
    final KeyedSubtree? bottomLargeTitle = bottomComponents.largeTitleKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? topBackLabel = topComponents.backLabelKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? topLeading = topComponents.leadingKey.currentWidget as KeyedSubtree?;
1965 1966 1967 1968 1969 1970

    if (bottomLargeTitle == null || !bottomLargeExpanded) {
      return null;
    }

    if (bottomLargeTitle != null && topBackLabel != null) {
1971
      // Move from current position to the top page's back label position.
1972 1973 1974 1975 1976
      return slideFromLeadingEdge(
        fromKey: bottomComponents.largeTitleKey,
        fromNavBarBox: bottomNavBarBox,
        toKey: topComponents.backLabelKey,
        toNavBarBox: topNavBarBox,
1977
        child: FadeTransition(
1978
          opacity: fadeOutBy(0.6),
1979
          child: Align(
1980 1981 1982
            // As the text shrinks, make sure it's still anchored to the leading
            // edge of a constantly sized outer box.
            alignment: AlignmentDirectional.centerStart,
1983
            child: DefaultTextStyleTransition(
1984
              style: animation.drive(TextStyleTween(
xster's avatar
xster committed
1985 1986
                begin: bottomLargeTitleTextStyle,
                end: topBackButtonTextStyle,
1987
              )),
1988 1989 1990 1991 1992 1993 1994 1995 1996 1997
              maxLines: 1,
              overflow: TextOverflow.ellipsis,
              child: bottomLargeTitle.child,
            ),
          ),
        ),
      );
    }

    if (bottomLargeTitle != null && topLeading != null) {
1998 1999
      // Unlike bottom middle, the bottom large title moves when it can't
      // transition to the top back label position.
2000 2001
      final RelativeRect from = positionInTransitionBox(bottomComponents.largeTitleKey, from: bottomNavBarBox);

2002
      final RelativeRectTween positionTween = RelativeRectTween(
2003
        begin: from,
2004 2005 2006 2007 2008 2009
        end: from.shift(
          Offset(
            forwardDirection * bottomNavBarBox.size.width / 4.0,
            0.0,
          ),
        ),
2010 2011
      );

2012 2013
      // Just shift slightly towards the trailing edge instead of moving to the
      // back label position.
2014
      return PositionedTransition(
2015
        rect: animation.drive(positionTween),
2016
        child: FadeTransition(
2017 2018
          opacity: fadeOutBy(0.4),
          // Keep the font when transitioning into a non-back-label leading.
2019
          child: DefaultTextStyle(
2020
            style: bottomLargeTitleTextStyle!,
2021 2022 2023 2024 2025 2026 2027 2028 2029
            child: bottomLargeTitle.child,
          ),
        ),
      );
    }

    return null;
  }

2030 2031
  Widget? get bottomTrailing {
    final KeyedSubtree? bottomTrailing = bottomComponents.trailingKey.currentWidget as KeyedSubtree?;
2032 2033 2034 2035 2036

    if (bottomTrailing == null) {
      return null;
    }

2037
    return Positioned.fromRelativeRect(
2038
      rect: positionInTransitionBox(bottomComponents.trailingKey, from: bottomNavBarBox),
2039
      child: FadeTransition(
2040 2041 2042 2043 2044 2045
        opacity: fadeOutBy(0.6),
        child: bottomTrailing.child,
      ),
    );
  }

2046 2047
  Widget? get topLeading {
    final KeyedSubtree? topLeading = topComponents.leadingKey.currentWidget as KeyedSubtree?;
2048 2049 2050 2051 2052

    if (topLeading == null) {
      return null;
    }

2053
    return Positioned.fromRelativeRect(
2054
      rect: positionInTransitionBox(topComponents.leadingKey, from: topNavBarBox),
2055
      child: FadeTransition(
2056 2057 2058 2059 2060 2061
        opacity: fadeInFrom(0.6),
        child: topLeading.child,
      ),
    );
  }

2062 2063 2064
  Widget? get topBackChevron {
    final KeyedSubtree? topBackChevron = topComponents.backChevronKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? bottomBackChevron = bottomComponents.backChevronKey.currentWidget as KeyedSubtree?;
2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075

    if (topBackChevron == null) {
      return null;
    }

    final RelativeRect to = positionInTransitionBox(topComponents.backChevronKey, from: topNavBarBox);
    RelativeRect from = to;

    // If it's the first page with a back chevron, shift in slightly from the
    // right.
    if (bottomBackChevron == null) {
2076
      final RenderBox topBackChevronBox = topComponents.backChevronKey.currentContext!.findRenderObject()! as RenderBox;
2077 2078 2079 2080 2081 2082
      from = to.shift(
        Offset(
          forwardDirection * topBackChevronBox.size.width * 2.0,
          0.0,
        ),
      );
2083 2084
    }

2085
    final RelativeRectTween positionTween = RelativeRectTween(
2086 2087 2088 2089
      begin: from,
      end: to,
    );

2090
    return PositionedTransition(
2091
      rect: animation.drive(positionTween),
2092
      child: FadeTransition(
2093
        opacity: fadeInFrom(bottomBackChevron == null ? 0.7 : 0.4),
2094
        child: DefaultTextStyle(
xster's avatar
xster committed
2095
          style: topBackButtonTextStyle,
2096 2097 2098 2099 2100 2101
          child: topBackChevron.child,
        ),
      ),
    );
  }

2102 2103 2104 2105
  Widget? get topBackLabel {
    final KeyedSubtree? bottomMiddle = bottomComponents.middleKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? bottomLargeTitle = bottomComponents.largeTitleKey.currentWidget as KeyedSubtree?;
    final KeyedSubtree? topBackLabel = topComponents.backLabelKey.currentWidget as KeyedSubtree?;
2106 2107 2108 2109 2110

    if (topBackLabel == null) {
      return null;
    }

2111
    final RenderAnimatedOpacity? topBackLabelOpacity =
2112
        topComponents.backLabelKey.currentContext?.findAncestorRenderObjectOfType<RenderAnimatedOpacity>();
2113

2114
    Animation<double>? midClickOpacity;
2115
    if (topBackLabelOpacity != null && topBackLabelOpacity.opacity.value < 1.0) {
2116
      midClickOpacity = animation.drive(Tween<double>(
2117 2118
        begin: 0.0,
        end: topBackLabelOpacity.opacity.value,
2119
      ));
2120 2121 2122 2123 2124 2125 2126 2127 2128
    }

    // Pick up from an incoming transition from the large title. This is
    // duplicated here from the bottomLargeTitle transition widget because the
    // content text might be different. For instance, if the bottomLargeTitle
    // text is too long, the topBackLabel will say 'Back' instead of the original
    // text.
    if (bottomLargeTitle != null &&
        topBackLabel != null &&
2129
        bottomLargeExpanded) {
2130 2131 2132 2133 2134
      return slideFromLeadingEdge(
        fromKey: bottomComponents.largeTitleKey,
        fromNavBarBox: bottomNavBarBox,
        toKey: topComponents.backLabelKey,
        toNavBarBox: topNavBarBox,
2135
        child: FadeTransition(
2136
          opacity: midClickOpacity ?? fadeInFrom(0.4),
2137
          child: DefaultTextStyleTransition(
2138
            style: animation.drive(TextStyleTween(
xster's avatar
xster committed
2139 2140
              begin: bottomLargeTitleTextStyle,
              end: topBackButtonTextStyle,
2141
            )),
2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152
            maxLines: 1,
            overflow: TextOverflow.ellipsis,
            child: topBackLabel.child,
          ),
        ),
      );
    }

    // The topBackLabel always comes from the large title first if available
    // and expanded instead of middle.
    if (bottomMiddle != null && topBackLabel != null) {
2153 2154 2155 2156 2157
      return slideFromLeadingEdge(
        fromKey: bottomComponents.middleKey,
        fromNavBarBox: bottomNavBarBox,
        toKey: topComponents.backLabelKey,
        toNavBarBox: topNavBarBox,
2158
        child: FadeTransition(
2159
          opacity: midClickOpacity ?? fadeInFrom(0.3),
2160
          child: DefaultTextStyleTransition(
2161
            style: animation.drive(TextStyleTween(
xster's avatar
xster committed
2162 2163
              begin: bottomTitleTextStyle,
              end: topBackButtonTextStyle,
2164
            )),
2165 2166 2167 2168 2169 2170 2171 2172 2173
            child: topBackLabel.child,
          ),
        ),
      );
    }

    return null;
  }

2174 2175
  Widget? get topMiddle {
    final KeyedSubtree? topMiddle = topComponents.middleKey.currentWidget as KeyedSubtree?;
2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187

    if (topMiddle == null) {
      return null;
    }

    // The middle component is non-null when the nav bar is a large title
    // nav bar but would be invisible when expanded, therefore don't show it here.
    if (!topHasUserMiddle && topLargeExpanded) {
      return null;
    }

    final RelativeRect to = positionInTransitionBox(topComponents.middleKey, from: topNavBarBox);
2188 2189 2190 2191 2192 2193 2194 2195 2196 2197
    final RenderBox toBox = topComponents.middleKey.currentContext!.findRenderObject()! as RenderBox;

    final bool isLTR = forwardDirection > 0;

    // Anchor is the top-leading point of toBox, in transition box's top-leading
    // coordinate space.
    final Offset toAnchorInTransitionBox = Offset(
      isLTR ? to.left : to.right,
      to.top,
    );
2198 2199

    // Shift in from the trailing edge of the screen.
2200 2201 2202 2203 2204 2205
    final Tween<Offset> anchorMovementInTransitionBox = Tween<Offset>(
      begin: Offset(
        // the "width / 2" here makes the middle widget's horizontal center on
        // the trailing edge of the top nav bar.
        topNavBarBox.size.width - toBox.size.width / 2,
        to.top,
2206
      ),
2207
      end: toAnchorInTransitionBox,
2208 2209
    );

2210 2211 2212 2213
    return _FixedSizeSlidingTransition(
      isLTR: isLTR,
      offsetAnimation: animation.drive(anchorMovementInTransitionBox),
      size: toBox.size,
2214
      child: FadeTransition(
2215
        opacity: fadeInFrom(0.25),
2216
        child: DefaultTextStyle(
xster's avatar
xster committed
2217
          style: topTitleTextStyle,
2218 2219 2220 2221 2222 2223
          child: topMiddle.child,
        ),
      ),
    );
  }

2224 2225
  Widget? get topTrailing {
    final KeyedSubtree? topTrailing = topComponents.trailingKey.currentWidget as KeyedSubtree?;
2226 2227 2228 2229 2230

    if (topTrailing == null) {
      return null;
    }

2231
    return Positioned.fromRelativeRect(
2232
      rect: positionInTransitionBox(topComponents.trailingKey, from: topNavBarBox),
2233
      child: FadeTransition(
2234 2235 2236 2237 2238 2239
        opacity: fadeInFrom(0.4),
        child: topTrailing.child,
      ),
    );
  }

2240 2241
  Widget? get topLargeTitle {
    final KeyedSubtree? topLargeTitle = topComponents.largeTitleKey.currentWidget as KeyedSubtree?;
2242 2243 2244 2245 2246 2247 2248 2249

    if (topLargeTitle == null || !topLargeExpanded) {
      return null;
    }

    final RelativeRect to = positionInTransitionBox(topComponents.largeTitleKey, from: topNavBarBox);

    // Shift in from the trailing edge of the screen.
2250
    final RelativeRectTween positionTween = RelativeRectTween(
2251 2252 2253 2254 2255 2256
      begin: to.shift(
        Offset(
          forwardDirection * topNavBarBox.size.width,
          0.0,
        ),
      ),
2257 2258 2259
      end: to,
    );

2260
    return PositionedTransition(
2261
      rect: animation.drive(positionTween),
2262
      child: FadeTransition(
2263
        opacity: fadeInFrom(0.3),
2264
        child: DefaultTextStyle(
2265
          style: topLargeTitleTextStyle!,
2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276
          maxLines: 1,
          overflow: TextOverflow.ellipsis,
          child: topLargeTitle.child,
        ),
      ),
    );
  }
}

/// Navigation bars' hero rect tween that will move between the static bars
/// but keep a constant size that's the bigger of both navigation bars.
2277
RectTween _linearTranslateWithLargestRectSizeTween(Rect? begin, Rect? end) {
2278
  final Size largestSize = Size(
2279
    math.max(begin!.size.width, end!.size.width),
2280 2281
    math.max(begin.size.height, end.size.height),
  );
2282
  return RectTween(
2283 2284 2285
    begin: begin.topLeft & largestSize,
    end: end.topLeft & largestSize,
  );
2286
}
2287

2288
Widget _navBarHeroLaunchPadBuilder(
2289
  BuildContext context,
2290
  Size heroSize,
2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304
  Widget child,
) {
  assert(child is _TransitionableNavigationBar);
  // Tree reshaping is fine here because the Heroes' child is always a
  // _TransitionableNavigationBar which has a GlobalKey.

  // Keeping the Hero subtree here is needed (instead of just swapping out the
  // anchor nav bars for fixed size boxes during flights) because the nav bar
  // and their specific component children may serve as anchor points again if
  // another mid-transition flight diversion is triggered.

  // This is ok performance-wise because static nav bars are generally cheap to
  // build and layout but expensive to GPU render (due to clips and blurs) which
  // we're skipping here.
2305
  return Visibility(
2306 2307 2308 2309 2310 2311
    maintainSize: true,
    maintainAnimation: true,
    maintainState: true,
    visible: false,
    child: child,
  );
2312
}
2313 2314

/// Navigation bars' hero flight shuttle builder.
2315
Widget _navBarHeroFlightShuttleBuilder(
2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328
  BuildContext flightContext,
  Animation<double> animation,
  HeroFlightDirection flightDirection,
  BuildContext fromHeroContext,
  BuildContext toHeroContext,
) {
  assert(animation != null);
  assert(flightDirection != null);
  assert(fromHeroContext != null);
  assert(toHeroContext != null);
  assert(fromHeroContext.widget is Hero);
  assert(toHeroContext.widget is Hero);

2329 2330
  final Hero fromHeroWidget = fromHeroContext.widget as Hero;
  final Hero toHeroWidget = toHeroContext.widget as Hero;
2331 2332 2333 2334

  assert(fromHeroWidget.child is _TransitionableNavigationBar);
  assert(toHeroWidget.child is _TransitionableNavigationBar);

2335 2336
  final _TransitionableNavigationBar fromNavBar = fromHeroWidget.child as _TransitionableNavigationBar;
  final _TransitionableNavigationBar toNavBar = toHeroWidget.child as _TransitionableNavigationBar;
2337 2338 2339 2340 2341

  assert(fromNavBar.componentsKeys != null);
  assert(toNavBar.componentsKeys != null);

  assert(
2342
    fromNavBar.componentsKeys.navBarBoxKey.currentContext!.owner != null,
2343 2344 2345
    'The from nav bar to Hero must have been mounted in the previous frame',
  );
  assert(
2346
    toNavBar.componentsKeys.navBarBoxKey.currentContext!.owner != null,
2347 2348 2349 2350 2351
    'The to nav bar to Hero must have been mounted in the previous frame',
  );

  switch (flightDirection) {
    case HeroFlightDirection.push:
2352
      return _NavigationBarTransition(
2353 2354 2355 2356 2357
        animation: animation,
        bottomNavBar: fromNavBar,
        topNavBar: toNavBar,
      );
    case HeroFlightDirection.pop:
2358
      return _NavigationBarTransition(
2359 2360 2361 2362 2363
        animation: animation,
        bottomNavBar: toNavBar,
        topNavBar: fromNavBar,
      );
  }
2364
}