This change adds a way to provide explicit focus order for a part of the widget tree.

It adds FocusTraversalPolicyGroup, which in many ways is similar to DefaultFocusTraversal, except that it groups a widget subtree together so that those nodes are traversed as a group. DefaultFocusTraversal doesn't work as one would expect: If there is more than one DefaultFocusTraversal inside of a focus scope, the policy can change depending on which node was asked to move "next", which can cause unexpected behavior. The new grouping mechanism doesn't have that problem. I deprecate DefaultFocusTraversal in this PR.

It also adds OrderedFocusTraversalPolicy, which is a policy that can be supplied to FocusTraversalPolicyGroup to set the policy for a sub-tree. It looks for FocusTraversalOrder inherited widgets, which use a FocusOrder to do the sorting. FocusOrder has two subclasses: NumericalFocusOrder (which sorts based on a double), and LexicalFocusOrder, which sorts based on a String.

As part of doing this, I refactored the way FocusTraversalPolicy is implemented so that it has more default implementation methods, and exposes a new protected member: sortDescendants, which makes it easier for developers to make their own policy subclasses: they only need to implement sortDescendants to get a new ordering behavior, but can also still override any of the default implementation behaviors if they need different behavior.

I was able to do this without breaking the API (AFAICT).

This makes FocusManager a ChangeNotifier that notifies when the primaryFocus changes so that an app can track the current focus.

Fixes #50501

This PR modifies the existing API docs samples to use DartPad so that all of the samples are now interactive apps on the API docs site.

It also removes the restriction for the max width of the description area so that the dartpad region can expand horizontally.

I updated the first paragraph on the API docs to indicate that Flutter is more than just mobile now (same text as the README.md at the top level).

I modified a few of the examples so that they looked nicer, and fit better on the page.

I added the sample description text above each DartPad instance, since that often defines the context of the example.

I removed animations and images when they were redundant with the sample content. There were a few that made sense to keep, so I did.

provide Guidance for MultiChildRenderObjectWidget implementations

This change broke some internal tests that set the text editing value to
the same thing (the empty string) twice in a row. Note that in that
case, the developer had subclassed EditableTextState and overridden the
updateEditingValue method, which may or may not be relevant to the
failure.

This reverts commit 83d4d63a.

* Reland "Fix custom Elements that wants to decorate State.build (#49925)" (#50068)"

This reverts commit 62fdcb03.

Updates stack filtering for new frames in stateful element

This reverts commit a1143d17.

* Fix image provider missing early return

* test

* comments

* whitespace, another comment

* reland "Refactors global key duplication detection (#46183)"

This reverts commit d2b66dbf.

* fix test

This reverts commit 46ccd086.

This reverts commit 340b193f.

This PR fixes #49647 by changing DiagnosticableMixin.toDiagnosticsNode and other things to accept DiagnosticableMixin instead of requiring Diagnosticable.

Fixes the focus handling when popping pages so that when multiple pages are popped, the focus doesn't try to focus the interstitial pages.

Navigator 2.0: Refactor the imperative api to continue working in the new navigation system (#44930)