Better methods to organize the vertical position of layers

[JaffaKetchup]

Converted to #1564 to allow tracking in v6 Release Planning.

---

In flutter_map, all nonRotatedChildren always appear on top of all children. This can cause issues for some users, who need to be able to control exactly where each layer is positioned within the layer stack, and also need to control whether the layer rotates.

As such, it may be desirable in the long term to find a solution to this issue. Three proposals discussed somewhat in #1551 (#1551 (comment), #1551 (comment), #1551 (comment), #1551 (comment)) are listed below, but all FM users are welcome to add their ideas or opinions!

The builder proposal

An initial suggestion by @rorystephenson, started in #1551, was to introduce (or potentially replace the current children/nonRotatedChildren arguments with) a builder method. The user would create a Stack widget themselves, using a new widget FlutterMapTransform.rotate to enable rotation on specific layers.

I (@JaffaKetchup) think that having the user handle the stack and opt-in to rotation on layers:

• increases the time required to implement the map first time round: even though only by maybe half a minute, converting users from other libraries needs to be as quick and easy as possible
  • means the user requires knowledge about the difference between a rotated and non-rotated layer before they can implement their first layer
• is perhaps a little 'backwards' considering most layers are rotatable - surely the non-rotatable layers are the odd-ones out, and so should explicitly state that they don't support rotation
• causes friction when adding new/multiple rotatable layers, as another sub-Stack is required, or another FlutterMapTransform wrapper is required
• makes code less readable as it's hard to see what the map widget is doing immediately, and somewhat breaks the general convention of interactive maps being formed from layers: layers are now descendants of the user's custom widget tree, not FlutterMap or a related widget
• requires migration across all users (a later proposal made the builder optional via an alternative constructor)

The wrapper widget and mixin proposal

I (@JaffaKetchup) proposed an alternative that aimed to solve most of these. Create a widget NonRotatedLayer that did nothing more than direct it's builder to build the child argument, meaning it essentially acts like a tag. nonRotatedChildren still appear above all other children, and don't require an explicit NonRotatedLayer, however children can use a NonRotatedLayer just to force non-rotation to its direct descendant, as FM internals would recognise the tag.

To avoid redundant wrapping, this could (also) be implemented via a mixin (as proposed by @rorystephenson), and be allowed to be applied to all widgets. This would allow maximum flexibility.

However, as pointed out by @rorystephenson, this will not work if the layer is not directly below the children. If it is a descendant of, lets say a FutureBuilder, the effect will not apply.
I'm (@JaffaKetchup) not sure this is an issue, as either method does not restrict it's child type, so the order of the FutureBuilder and mixin/NonRotatedLayer could be swapped to restore functionality.

[ibrierley]

One thing worth bearing in mind, and I'm unsure of this, there could be a performance penalty with having multiple children each with their own rotation, vs one rotation with several children. It's worth trying to test that with any possible solutions (or at least have it somehow as an option still to group some together).

[JaffaKetchup]

I thought about this but assumed it wasn't an issue. We should do some benchmarking.
However, here's an implementation that groups as best as possible (the nonRotatedChildren just needs to be appended to the output, then the entire output is the children of the Stack). Note that it checks for the mixin, which is just an empty mixin 'handle'.

  Iterable<Widget> _prepareChildren(List<Widget> children) sync* {
    final stackChildren = <Widget>[];

    Widget prepareRotateStack() {
      final box = OverflowBox(
        minWidth: size.x,
        maxWidth: size.x,
        minHeight: size.y,
        maxHeight: size.y,
        child: Transform.rotate(
          angle: rotationRad,
          child: Stack(children: List.from(stackChildren)),
        ),
      );
      stackChildren.clear();
      return box;
    }

    for (final Widget child in children) {
      if (child is NonRotatedLayerMixin) {
        if (stackChildren.isNotEmpty) yield prepareRotateStack();
        yield child;
      } else {
        stackChildren.add(child);
      }
    }
    if (stackChildren.isNotEmpty) yield prepareRotateStack();
  }

[JaffaKetchup]

Converted to #1564 to allow tracking in v6 Release Planning.