XCEngine/docs/used/NewEditor_InspectorLayout_RootRefactorPlan_2026-04-21.md

NewEditor Inspector Layout Root Refactor Plan

Date: 2026-04-21

Context

This plan targets the new_editor Inspector field layout path only.

Current symptom:

• Inspector field controls do not follow one explicit column policy.
• Different field types shift or compress at different thresholds.
• Transform and the fields below it stop aligning once the Inspector becomes narrow.

Current root cause:

• Shared row layout code in UIEditorFieldRowLayout is guessing when a caller is "Inspector-like" and silently replacing the caller's requested minimum control width.
• That guess is based on generic layout numbers such as controlColumnStart and labelControlGap, which is an invalid ownership boundary.
• Vector fields also still carry a dead prefix palette chain that no longer affects rendering after the visible background was moved to componentRects.

Files In Scope

• new_editor/include/XCEditor/Widgets/UIEditorFieldRowLayout.h
• new_editor/src/Widgets/UIEditorFieldRowLayout.cpp
• new_editor/include/XCEditor/Fields/UIEditorPropertyGrid.h
• new_editor/include/XCEditor/Fields/UIEditorFieldStyle.h
• new_editor/src/Fields/UIEditorFieldStyle.cpp
• Hosted Inspector field headers under new_editor/include/XCEditor/Fields/
• Hosted Inspector field sources under new_editor/src/Fields/

Refactor Goals

1. Remove all implicit Inspector detection from shared row layout.
2. Make shared control-column width an explicit metric owned by PropertyGrid and forwarded to hosted fields.
3. Keep hosted field layout behavior consistent by policy instead of per-field hidden overrides.
4. Remove dead vector prefix palette data that no longer drives rendering.
5. Rebuild XCUIEditor.exe after the refactor and keep the worktree changes scoped to new_editor.

Implementation Plan

Stage 1: Make The Contract Explicit

Add one explicit metric for hosted shared-column reservation:

• sharedControlColumnMinWidth

Propagation chain:

• UIEditorPropertyGridMetrics
• hosted field metrics (Bool, Number, Text, Enum, Color, Object, Asset, Vector2, Vector3, Vector4)
• UIEditorFieldRowLayoutMetrics

Rules:

• Default value outside Inspector stays 0.0f
• Inspector-owned PropertyGrid metrics set the shared width explicitly
• Shared row layout consumes this field directly and never infers Inspector mode from unrelated metrics

Stage 2: Remove Hidden Width Guessing

Replace the current behavior in UIEditorFieldRowLayout.cpp:

• delete the implicit ResolveHostedControlMinimumWidth(...) path
• delete the inspectorHostedControlMinWidth token
• make reserved control width depend only on explicit row-layout metrics and the caller-provided value

Expected result:

• the row-layout contract becomes deterministic
• hosted fields stop getting different fallback behavior because of hidden special-cases

Stage 3: Clean Vector Dead Code

Remove prefixColor and prefixBorderColor from:

• inspector field tokens
• vector field palette structs
• vector palette resolution code
• PropertyGrid palette builder forwarding

Reason:

• those fields no longer affect visible rendering after the component background moved to componentRects

Stage 4: Validation

Validation steps:

• compile XCUIEditorApp in Debug
• if the editor process is locking the output exe, kill XCUIEditor first
• verify the rebuilt output is build/new_editor/Debug/XCUIEditor.exe

Done Criteria

This refactor is complete when:

• shared row layout contains no Inspector guessing logic
• Inspector column width policy is explicit in metrics
• hosted field metric forwarding is consistent for all field types
• vector dead palette chain is removed
• XCUIEditor.exe rebuild succeeds