[widgets/raw_menu_anchor.dart] Always call onClose and onCloseRequested on descendants before parent. (flutter#182357)

This PR corrects the order in which onClose() and onCloseRequested() is
called by a RawMenuAnchor tree.

Per @dkwingsmt:

> A close is immediate and should close children immediately before
closing itself, while a closeRequest [can be] async and should
closeRequest children.

Before, calling close() on a parent would call handleCloseRequest() on
its children, leading to children (potentially) finishing their closure
after their parents.

Additionally, if a RawMenuAnchor is already closed, it will not trigger
onCloseRequested.

**Details:**
 
The handleCloseRequest portion of the
_RawMenuAnchorBaseMixin.closeChildren function has been moved into a
requestChildrenClose function to be more explicit.

Additionally, this PR makes handleCloseRequest call
requestChildrenClose() after calling widget.onCloseRequested on
_RawMenuAnchorState. This makes submenus begin closing after their
parent menu begins closing. I also modified the menu_anchor.dart and
raw_menu_anchor.3.dart code to remove a closeChildren call (now
redundant).

Last, this PR makes handleCloseRequest short-circuit if a menu isn't
open. This prevents unncessary widget.onCloseRequest calls when a
submenu is opened, since all sibling menus call handleCloseRequest
before the submenu begins opening.

This is a breaking change. I had to modify one of the DismissMenuAnchor
tests since onCloseRequested is now called on all descendants when a
dismissal occurs. I think it's best to introduce this change because it
can lead to hard-to-track behavior when creating menus (that's how I
discovered it).

Migration guide: flutter/website#13145

Additional tests were added to check the opening and closing behavior. 

Fixes flutter#182355

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

---------

Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>

Author: davidhicks980

examples/api/lib/widgets/raw_menu_anchor/raw_menu_anchor.3.dart

@@ -181,9 +181,6 @@ class MenuState extends State<Menu> with SingleTickerProviderStateMixin {
       return;
     }
 
-    // Animate the menu's children out of view.
-    menuController.closeChildren();
-
     // Animate the menu out of view.
     animationController.reverse().whenComplete(hideOverlay);
   }

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

@@ -656,7 +656,6 @@ class _MenuAnchorState extends State<MenuAnchor> with SingleTickerProviderStateM
       return;
     }
 
-    _menuController.closeChildren();
     _animationController.reverse().whenComplete(hideOverlay);
   }
 

packages/flutter/lib/src/widgets/raw_menu_anchor.dart

@@ -310,10 +310,23 @@ class RawMenuAnchor extends StatefulWidget {
 
   /// Called when a request is made to close the menu.
   ///
-  /// This callback is triggered every time [MenuController.close] is called,
-  /// regardless of whether the overlay is already hidden. As a result, this
-  /// callback can be used to add a delay or a closing animation before the menu
-  /// is hidden.
+  /// This callback can be used to add a delay or a closing animation before the
+  /// menu is hidden.
+  ///
+  /// This callback is triggered every time [MenuController.close] is called
+  /// while this menu is open.
+  ///
+  /// This callback is also triggered when a sibling [RawMenuAnchor] is opened
+  /// while this menu is open. In this case, the callback can be used to add a
+  /// delay or a closing animation while the sibling menu opens. When
+  /// implementing this behavior, consider disabling interactions so that the
+  /// closing menu does not interfere with the opening sibling menu. Also
+  /// consider disabling semantics, focus, and hit testing for the closing menu
+  /// for the duration of the closing animation.
+  ///
+  /// Pending timers or animations started in a previous call to
+  /// [onCloseRequested] should be canceled when this callback is triggered to
+  /// prevent them from closing the menu at an unintended time.
   ///
   /// If the menu is not closed, this callback will also be called when the root
   /// menu anchor is scrolled and when the screen is resized.
@@ -600,22 +613,40 @@ mixin _RawMenuAnchorBaseMixin<T extends StatefulWidget> on State<T> {
   @protected
   void handleCloseRequest();
 
-  /// Request that the submenus of this menu be closed.
+  /// Close the open submenus of this menu.
   ///
-  /// By default, this method will call [handleCloseRequest] on each child of this
-  /// menu, which will trigger the closing sequence of each child.
+  /// This method will call [close] on each child of this menu, which will
+  /// immediately close the child.
   ///
   /// If `inDispose` is true, this method was triggered by the widget being
   /// unmounted.
+  ///
+  /// See also:
+  /// * [requestChildrenClose], which triggers the closing sequence of each
+  ///   child by calling [handleCloseRequest] on each child.
   @protected
   void closeChildren({bool inDispose = false}) {
     assert(_debugMenuInfo('Closing children of $this${inDispose ? ' (dispose)' : ''}'));
-    for (final child in List<_RawMenuAnchorBaseMixin>.of(_anchorChildren)) {
-      if (inDispose) {
-        child.close(inDispose: inDispose);
-      } else {
-        child.handleCloseRequest();
-      }
+    final children = List<_RawMenuAnchorBaseMixin>.of(_anchorChildren);
+    for (final child in children) {
+      child.close(inDispose: inDispose);
+    }
+  }
+
+  /// Request that the open submenus of this menu be closed.
+  ///
+  /// This method will call [handleCloseRequest] on each child of this menu,
+  /// which will trigger the closing sequence of each child.
+  ///
+  /// See also:
+  /// * [closeChildren], which immediately closes each child without triggering
+  ///   the closing sequence.
+  @protected
+  void requestChildrenClose() {
+    assert(_debugMenuInfo('Calling handleCloseRequest for children of $this'));
+    final children = List<_RawMenuAnchorBaseMixin>.of(_anchorChildren);
+    for (final child in children) {
+      child.handleCloseRequest();
     }
   }
 
@@ -626,7 +657,7 @@ mixin _RawMenuAnchorBaseMixin<T extends StatefulWidget> on State<T> {
   void handleOutsideTap(PointerDownEvent pointerDownEvent) {
     assert(_debugMenuInfo('Tapped Outside $menuController'));
     if (isOpen) {
-      closeChildren();
+      requestChildrenClose();
     }
   }
 
@@ -708,7 +739,7 @@ class _RawMenuAnchorState extends State<RawMenuAnchor> with _RawMenuAnchorBaseMi
     assert(_debugMenuInfo('Opening $this at ${position ?? Offset.zero}'));
 
     // Close all siblings.
-    _parent?.closeChildren();
+    _parent?.requestChildrenClose();
     assert(!_overlayController.isShowing);
     _menuPosition = position;
     _parent?._childChangedOpenState();
@@ -731,7 +762,9 @@ class _RawMenuAnchorState extends State<RawMenuAnchor> with _RawMenuAnchorBaseMi
       return;
     }
 
+    // Parents will close after children do.
     closeChildren(inDispose: inDispose);
+
     // Don't hide if we're in the middle of a build.
     if (SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks) {
       _overlayController.hide();
@@ -764,6 +797,10 @@ class _RawMenuAnchorState extends State<RawMenuAnchor> with _RawMenuAnchorBaseMi
 
   @override
   void handleCloseRequest() {
+    if (!isOpen) {
+      return;
+    }
+
     // Changes in MediaQuery.sizeOf(context) cause RawMenuAnchor to close during
     // didChangeDependencies. When this happens, calling setState during the
     // closing sequence (handleCloseRequest -> onCloseRequested -> hideOverlay)
@@ -779,6 +816,9 @@ class _RawMenuAnchorState extends State<RawMenuAnchor> with _RawMenuAnchorBaseMi
         }
       }, debugLabel: 'RawMenuAnchor.handleCloseRequest');
     }
+
+    // Parents will request close before children do.
+    requestChildrenClose();
   }
 
   Widget _buildOverlay(BuildContext context, OverlayChildLayoutInfo layoutInfo) {
@@ -939,7 +979,7 @@ class _RawMenuAnchorGroupState extends State<RawMenuAnchorGroup>
   @override
   void handleCloseRequest() {
     assert(_debugMenuInfo('Requesting close $this'));
-    close();
+    requestChildrenClose();
   }
 
   @override
@@ -1018,7 +1058,7 @@ class MenuController {
   /// without closing the menu itself.
   void closeChildren() {
     assert(_anchor != null);
-    _anchor!.closeChildren();
+    _anchor!.requestChildrenClose();
   }
 
   // ignore: use_setters_to_change_properties