Add a dock tree data model to bevy_ui_widgets

[jbuehler23]

Objective

Part of #25958.

Dockable panel layouts need a model of which panels sit in which tab groups and how the space is split, separate from the UI that shows them, so layouts can be edited, saved and restored.

Solution

A dock module in bevy_ui_widgets with the dock tree as plain data. Leaves are tab groups and splits hold weighted children, with weights that match the split pane so the next PR can turn the tree straight into split panes and tab lists.

• DockTree component, so an app can have more than one dock
• tabs point at content through a DockPanelKey the app maps to what it builds
• add, split at an edge, move, move to an edge, remove, set active and set sizes, all returning an error for invalid ids
• simplify removes empty groups and collapses single child splits
• serialization behind the serialize feature

There's no UI here yet, building it from the tree comes next.

AI disclosure

This is ported from the dock tree in Jackdaw. I had AI move it into bevy_ui_widgets, strip the editor specific parts and change splits to weighted children so they line up with the split pane, then port and extend the tests. I reviewed the model and the changes from the original.

[alice-i-cecile]

Why a distinct crate rather than a module in bevy_ui_widgets? Are we expecting that much complexity? It's not technically a widget, maybe, but it really operates at a similar level. My preference here is to stick it in the existing crate unless there's a really strong reason to spin it off.

We can always feature flag this too to reduce compile times etc if it ever matters.

[jbuehler23]

Fair, moved it into bevy_ui_widgets as a dock module, no feature flag since it's plain data.

[viridia]

Very interesting. Just some preliminary questions at this point.

[viridia]

Is this meant to be a representational source of truth, or a wire format derived from the scene?

Reading further down, I see that it is a component. What entity owns it?

I'm a little fuzzy on the lifecycle - if this is derived from the scene, it makes sense, since extracting this would make it easier to serialize. If OTOH the scene is derived from this, I'm not as clear why the scene isn't the source of truth (I'm sure there's a reason, I just don't know it yet.)

[jbuehler23]

Good question! The DockTree is the source of truth, and the UI is derived from it. It's a component on the dock's root entity, and the follow-up PR adds a reconciler that builds the split panes, tab lists and panel content as children of that entity, and keeps them in sync whenever the tree changes. Tabs and splitters only propose changes (same controlled pattern as the other widgets), and those get applied to the tree.

The reason it isn't the scene itself is that the layout operations are tree operations on plain data. Splitting a group at an edge, moving a tab between groups and collapsing empty groups are much simpler and easier to test there than as entity hierarchy surgery. It also makes layouts easy to save and restore, and lets the UI entities be rebuilt or reused freely without losing the layout. Happy to talk through it more!

[viridia]

Can we get a comment that explains this?

[jbuehler23]

Added it to the module docs and the DockTree docs, explaining that the tree is the source of truth and the UI is derived from it.