Project planning: UI hierarchies and the current Parent-Child implementation

[alice-i-cecile]

(Following up from #2569) As it stands, the existing Parent-Child implementation has several serious issues, particularly in a UI context:

1. Multiple root UI nodes are not supported, causing mysterious z-fighting. This is debatably the correct choice, but the failure is both silent and undocumented.
2. Orphaned nodes are not automatically cleaned up, leading to confusing correctness bugs in end-user code. Fixing this seems both expensive and very complex: see Test for orphan parent-child relations #1278 for some failing tests, where we could not come to a satisfying conclusion.
3. The ergonomics of working with complex UI hierarchies are not great due to the confusingly similar (and undocumented) APIs for child-building and the requirement to use closures. This tends to encourage unpleasant deeply nested code and monolithic build_ui systems. See User experience report: `bevy_ui` in Bevy 0.5 #2235 for my own experiences.
4. Children are not forced to be unique: see Enforce uniqueness in Children #1079.
5. Transform propagation happens once per frame; causing strange behavior.

There are also some less pressing issues:

1. Using the layout system is almost completely undocumented. This is particularly intimidating for those who have never used flexbox in CSS before.
2. The stretch layout library has poor performance (particularly for large and complex trees), several bugs, and was last updated two years ago.
3. Users cannot easily and correctly create parent-child-like components due to the complexity involved.
4. The Children component will be heap-allocated if more than 8 exist, creating sudden perf cliffs. See

   bevy/crates/bevy_transform/src/hierarchy/child_builder.rs

   Line 13 in ecb7804

   children: SmallVec<[Entity; 8]>,

5. There's no good way to enforce that parent-child hierarchies are valid, tending to result in very strange behavior if some combination of Node, Style, Transform or GlobalTransform are missing (depending on what exactly the user is doing). Kinded entities #1634's kinded entities are an attempt to tackle this problem.
6. Users cannot opt-out of some of the Transform propagation behavior: rotation, translation and scale are all locked. See [Merged by Bors] - Add missing bytemuck feature #2625 for an interesting variant on this limitation. This is also frustrating when attempting to work with sprites and 2D text.
7. We have no way to enforce that parent-child hierarchies actually form a tree, opening the door to subtle user bugs.
8. Transform components of entities within the UI hierarchy can be mutably accessed and set, but changing them just silently fails to work.
9. Parent-child hierarchies work very differently in a UI vs non-UI context, and cannot be mixed. I actually think these should just be different component types.
10. Users must use the Style component to manually position visual elements in UI coordinate space.

(Let me know if you have more complaints or disagree and I'll edit this post).

Paths forward

The current solution is not great, and should probably be prioritized for cleanup in some form due to the number and severity of user bugs it has created.

1. Fix up some docs and wait and see what relations bring. Many of these issues can be mitigated with better expectation setting and education for users.
2. Prioritize relations (Entity Relations #1627) work for 0.7 and immediately replace the existing parent-child impl with it. This has several unknowns WRT perf and is a lot of work.
3. Work on the alternate parent-child impl hinted at by @cart back in December in Enforce uniqueness in Children #1079. I'm not sure what this would entail, or how many of the issues it might fix.

For the most part, I think that this work should wait until 0.7 to avoid delaying release, but documentation improvements from non-Cart contributors are probably still a good use of time before then no matter what path we choose.