I added more words since we added the showOverlay/hideOverlay callbacks, but modeled the docs after your suggestion. Let me know what you think.

I added more words since we added the showOverlay/hideOverlay callbacks, but modeled the docs after your suggestion. Let me know what you think.

I'd like to avoid the same method being called twice with different flags during a single opening/closing action, since this call stack will be confusing and even prone to infinite recursion if not managed correctly.

What if, instead of making onOpenRequested call menuController.open(transition: true), the onOpenRequested is given a callback to finalize the opening? Do you think this will be simpler?

Another approach is to add performOpen and performClose methods to MenuController. We can clearly document them to avoid being miscalled by applications.

I was debating between the callback or the transition property.. the recursion problem is a great point. What do you think would be a good name for the callback? For the decorator I used markMenuOpened, but that was a bit confusing. done()/complete()/finishedOpen/finish?

Any of them is an improvement, which we can start with.

Another option is to use a name with better meaning, such as showOverlay. Although this isn't the only thing that this callback does, my understanding is that this gives a close enough impression to the user (library developer) what it does.

Sweet -- I'll change the callbacks to showOverlay/hideOverlay.

Done! Unfortunately, function signatures don't seem to show positional argument names when using intellisense. Currently, I'm passing the position (1st argument in photo) and the showOverlay callback (2nd argument) into onOpenRequested, but I'm not sure if the ambiguity of the function signature warrants using named parameters. Otherwise, seems to work well.

Shall we rename it triggerRebuild (with negation) for more clarity what it does?

  /// If `triggerRebuild` is false, the menu will close without rebuilding its parent, which is useful when the
  /// menu is closed due to unmounting. Defaults to true.

That sounds good to me, although this was from the original MenuAnchor (not sure if it matters).

Did you meant to say RawMenuAnchor? That's fine, because these APIs are private.

Actually, the original MenuAnchor that RawMenuAnchor is based off of. But sounds good -- I'll make the change.

Edit: One caveat I just came across. inDispose only blocks rebuilds for the overlay menu, and it also blocks a post-frame callback if the menu was in the process of closing. It may actually be better if we just took out the "If inDispose is true, the menu will close without rebuilding its parent." comment. Let me know...

Sorry I don't quite understand. Can you point out the line that implements each usage of inDispose?

Instances are below.

  // in _RawMenuAnchorBaseMixin
  @protected
  void closeChildren({bool inDispose = false}) {
    assert(_debugMenuInfo('Closing children of $this${inDispose ? ' (dispose)' : ''}'));
    for (final _RawMenuAnchorBaseMixin child in List<_RawMenuAnchorBaseMixin>.from(
      _anchorChildren,
    )) {
     // ** Skipping the child's closing animation if we are disposing
      if (inDispose) {
        child.close(inDispose: inDispose);
      } else {
        child.handleCloseRequest();
      }
    }
  }

  // In _RawMenuAnchorGroupState
 @override
  void close({bool inDispose = false}) {
    if (!isOpen) {
      return;
    }

    closeChildren(inDispose: inDispose);

     // ** Notifying our parent and rebuilding this widget iff we are not disposing. 
    if (!inDispose) {
      if (SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks) {
        setState(() {
          // Mark dirty, but only if mounted and not in a build.
        });
      } else {
        SchedulerBinding.instance.addPostFrameCallback((Duration timestamp) {
          if (mounted) {
            setState(() {
              // Mark dirty.
            });
          }
        });
      }
    }
  }

// In _RawMenuAnchorState
  @override
  void close({bool inDispose = false}) {
    assert(_debugMenuInfo('Closing $this'));
    if (!isOpen) {
      return;
    }

    closeChildren(inDispose: inDispose);

    if (SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks) {
      _overlayController.hide();
    } else if (!inDispose) {
      // ** Adding a post-frame callback to close this overlay iff we are not disposing.
      SchedulerBinding.instance.addPostFrameCallback((_) {
        _overlayController.hide();
      }, debugLabel: 'MenuAnchor.hide');
    }

     // ** Notify our parent and rebuild this widget iff we are not disposing. 
    if (!inDispose) { 
      _parent?._childChangedOpenState();
      widget.onClose?.call();
      if (mounted &&
          SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks) {
        setState(() {
          // Mark dirty, but only if mounted and not in a build.
        });
      }
    }
  }

I suggest move the implementation of _RawMenuAnchorBaseMixin.requestOpen to _RawMenuAnchorState since this default implementation only affects this widget alone.

Also I suggest renaming this method to either handleControllerOpen or handleOpenRequested to clearly indicate when it is called. In general, I consider the two methods "handlers" because they're basically callbacks to be implemented in the perspective of the menu controller.

(Same suggestions for requestClose.)

Another way is to define a getter that returns onOpenRequested, i.e. both the anchor and the anchor group has onOpenRequested for the menu controller to use.

I renamed the callbacks to handleOpenRequested/handleCloseRequested. Moving handleOpenRequested on to only RawMenuAnchor is problematic, since MenuController only has access to _RawMenuAnchorBaseMixin. While we could do a typecheck (check if _anchor is _RawMenuAnchorState), that seems messier than just keeping them on the base class. Let me know what you think.

No, I mean keeping the handleOpenRequested as pure method and move the implementation to the two state classes. Is it possible?

Slight fix.

Slight fix, I wonder if this is the correct understanding.

Also did you remove

  /// It is not called when the menu is unmounted.
  /// By default it does nothing.

intentionally? I think the two sentences are worth adding. (The 2nd sentence also to onOpen).

So, this is another confusing aspect of the menu. If the focus moves onto the menu, the menu takes focus when it begins opening (when onOpen is called), and moves off the menu when it begins closing (when onCloseRequested is called). I observed this in several menus. Otherwise, it'd be bad a11y -- the user would have to wait for the menu to open or close before that user could move to another focus node.

For the removal question, I'm not sure why I took out the first part ("It is not called when the menu is unmounted") -- it may have been an accident. The "by default it does nothing" part was removed since the value defaults to null, so I thought it was evident that the callback did nothing, but I do know there are classes that have default behavior if a null value is provided. So, I'll add them both back in.

Do you mind if I rewrite it slightly to "By default, [onOpen] does nothing"? The rewording makes it a bit less ambigious since "menu" is also being referenced in the previous sentence.

Sorry I don't quite understand. Can you point out the line that implements each usage of inDispose?

No, I mean keeping the handleOpenRequested as pure method and move the implementation to the two state classes. Is it possible?

Is there a way to distinguish between repositioning and fresh open? Do you think a repositioning callback would help?

It is possible, but I would advise against it since the user has a few ways of figuring out if it's a reposition. If the menu is already open or opening, the user could check if their animation is already running forward or has finished. The user could also store the value of "position" and check for equality.

Also, the separate callback would still need a way of calling showOverlay with the new position, so users would have to write two callbacks that behave almost the same. Likewise, since "position" can be null, it could introduce some confusion as to whether moving from a null to a non-null "position" and vise versa counts as repositioning.

It seems to me that this if clause can be refactored so that widget.onOpenRequested is non null and has a default callback

  onOpenRequested = onOpenRequested ?? (position, open) => open(position)

Where would we be assigning onOpenRequested? We can't do the assignment in the RawMenuAnchor constructor since the widget is const.

While we could write something like widget.onOpenRequested?.call(position, open) ?? open(position), I tend to find null coalescing to be a bit unsightly compared to using a boring "if" statement. I may just be getting old.

should also typedef the parameter type Function({Offset? position})

the comment should also explain what each parameter are and how to use them in typical cases

Why do we need a postframe callback? would be good to have some comments on this

Somewhere in here or other place should document the invoking order of onOpenRequested, showOverlay and onOpen same for onCloseRequest and onClose

Can this have a default value to call the showOverlay directly?

Tong also was wondering this, and at the time I thought it would make RawMenuAnchor non const. I just checked, and it turns out I was wrong. So we can. Do these look good, or should I rename/make public?

static void _defaultOnOpenRequested(
    Offset? position,
    RawMenuAnchorShowOverlayCallback showOverlay,
) {
   showOverlay(position: position);
}

static void _defaultOnCloseRequested(RawMenuAnchorHideOverlayCallback close) {
    close();
}