editor-ui-infrastructure

name	editor-ui-infrastructure
description	Guide proper usage of Editor UI infrastructure including Drawers (ButtonDrawer, ModalDrawer, TableDrawer, etc.), Elements (drag-drop targets, ComponentSelector), FieldEditors, and EditorUIConstants. Use when implementing editor panels, component editors, or any ImGui UI code to ensure consistency and code reuse.

Editor UI Infrastructure

Table of Contents

1. Overview
2. When to Use
3. Conceptual Model
   • Drawers
   • Elements
   • FieldEditors
   • EditorUIConstants
4. Best Practices
5. Common Anti-Patterns
6. Integration Checklist
7. Reference Documentation

---

Overview

The Editor UI infrastructure provides four layers of reusable UI components ensuring consistent styling and behavior across all editor panels and component editors.

Golden Rule: Never reimplement existing UI patterns. Always check if a Drawer, Element, or FieldEditor exists before writing custom ImGui code.

Benefits:

• Visual consistency across all editor panels
• Reduced code duplication
• Easier maintenance and global style changes
• Better user experience through familiar patterns

---

When to Use

Invoke this skill when:

• ✅ Implementing editor panels or component editors
• ✅ Adding UI elements to existing panels
• ✅ Questions about which UI utility to use
• ✅ Implementing drag-and-drop functionality
• ✅ Creating modal dialogs or confirmation prompts
• ✅ Rendering tables, trees, or structured data
• ✅ Adding buttons with consistent styling
• ✅ Working with field editors for primitive types

---

Conceptual Model

Drawers

What: Static utility classes for common UI patterns with consistent styling.

When: Use for standard UI operations (buttons, modals, tables, spacing, text).

Available: ButtonDrawer, ModalDrawer, TableDrawer, TreeDrawer, LayoutDrawer, TextDrawer, DragDropDrawer

Key Example:

// ❌ WRONG - Raw ImGui
if (ImGui.Button("Save", new Vector2(120, 30)))
    Save();

// ✅ CORRECT - Use ButtonDrawer
if (ButtonDrawer.DrawButton("Save", onClick: Save))
{
    // Additional logic if needed
}

Features:

• Automatic sizing via EditorUIConstants
• Semantic color coding (Error/Warning/Success/Info)
• Tooltip support
• Callback-based API reduces boilerplate

Common Methods:

• ButtonDrawer.DrawButton() - Standard button
• ButtonDrawer.DrawColoredButton() - Semantic colored button (red/green/yellow/blue)
• ModalDrawer.RenderConfirmationModal() - OK/Cancel dialog
• TableDrawer.BeginTable() - Consistent table rendering
• TreeDrawer.BeginTreeNode() - Expandable tree nodes
• LayoutDrawer.DrawSpacing() - Consistent vertical spacing
• TextDrawer.DrawText() - Colored text (Error/Warning/Success/Info)

See references/drawers-api.md for complete API reference (15+ button variants, modal types, etc.).

---

Elements

What: Complex, stateful UI components for specific interactions.

When: Use for specialized interactions (drag-drop, component selection, context menus).

Available: TextureDropTarget, AudioDropTarget, MeshDropTarget, ComponentSelector, EntityContextMenu, PrefabManager

Key Example:

// ❌ WRONG - Custom drag-drop implementation
ImGui.Button("Texture");
if (ImGui.BeginDragDropTarget())
{
    // Complex validation, error handling, visual feedback...
}

// ✅ CORRECT - Use specialized drop target
TextureDropTarget.Draw("Texture",
    currentPath: component.TexturePath,
    onTextureChanged: path => component.TexturePath = path,
    assetsManager: _assetsManager
);

Features:

• Built-in validation (file extensions, asset existence)
• Visual feedback (hover highlights, error messages)
• Consistent error handling
• Asset manager integration

Common Elements:

• TextureDropTarget - Texture files (.png, .jpg)
• AudioDropTarget - Audio files (.wav, .ogg)
• MeshDropTarget - Mesh files (.mesh)
• ComponentSelector - Searchable component list for "Add Component"
• EntityContextMenu - Right-click menu (duplicate, delete, rename)
• PrefabManager - Prefab creation/instantiation

See references/elements-api.md for complete API reference and usage patterns.

---

FieldEditors

What: Non-generic, boxing-based editors for types discovered via reflection at runtime. Used exclusively by the script inspector (ScriptComponentEditor) to render public fields of NativeScript subclasses.

When: Use when implementing custom rendering for a new type in the script inspector. Do not use in component editors — component editors use UIPropertyRenderer and VectorPanel instead (see below).

Available: Built-in editors for int, float, double, bool, string, Vector2, Vector3, Vector4. Add new types via FieldEditorRegistry.

Interface (Editor/UI/FieldEditors/IFieldEditor.cs):

public interface IFieldEditor
{
    bool Draw(string label, object value, out object newValue);
}

How it works: FieldEditorRegistry.GetEditor(type) returns the matching IFieldEditor?. The script inspector calls editor.Draw(label, boxedValue, out newBoxedValue) and uses reflection to write the result back.

For component editors, use UIPropertyRenderer and VectorPanel instead — they avoid boxing and are the correct pattern:

// ✅ CORRECT - Component editor (known types, no boxing)
UIPropertyRenderer.DrawPropertyField("Speed", component.Speed,
    newValue => component.Speed = (float)newValue);

var pos = component.Position;
VectorPanel.DrawVec3Control("Position", ref pos);
if (pos != component.Position) component.Position = pos;

See editor-field-creation skill for full details on implementing custom IFieldEditor types.

---

EditorUIConstants

What: Centralized constants for consistent styling across all UI.

When: Use for ALL sizing, spacing, colors (never hardcode values).

Key Categories:

• Button Sizes: StandardButtonWidth (120), StandardButtonHeight (30)
• Layout Ratios: PropertyLabelRatio (0.33f), PropertyInputRatio (0.67f)
• Spacing: StandardPadding (8), LargePadding (16), SmallPadding (4)
• Colors: ErrorColor (red), WarningColor (yellow), SuccessColor (green), InfoColor (blue)
• Axis Colors: AxisXColor (red), AxisYColor (green), AxisZColor (blue)
• Input Buffers: MaxNameLength (128), MaxPathLength (512)

Key Example:

// ❌ WRONG - Magic numbers
ImGui.Button("Export", new Vector2(150, 35));
ImGui.Dummy(new Vector2(0, 10));
ImGui.PushStyleColor(ImGuiCol.Text, new Vector4(1, 0, 0, 1));

// ✅ CORRECT - Use constants
ButtonDrawer.DrawButton("Export",
    width: EditorUIConstants.WideButtonWidth,
    height: EditorUIConstants.StandardButtonHeight);
LayoutDrawer.DrawSpacing();
ImGui.PushStyleColor(ImGuiCol.Text, EditorUIConstants.ErrorColor);

Golden Rule: EditorUIConstants is the ONLY static class allowed in the codebase (all other code uses DI).

See references/constants-catalog.md for complete catalog and design rationale.

---

Best Practices

1. Always Use Drawers Over Raw ImGui

Why: Ensures consistency, automatic sizing, proper callbacks.

// Use ButtonDrawer for all buttons
ButtonDrawer.DrawButton("Save");
ButtonDrawer.DrawColoredButton("Delete", MessageType.Error);

// Use ModalDrawer for confirmations
ModalDrawer.RenderConfirmationModal("Delete?", ref _show, "Sure?", () => Delete());

// Use LayoutDrawer for spacing
LayoutDrawer.DrawSpacing(); // Not ImGui.Dummy()

2. Use Specialized Drop Targets for Asset References

Why: Built-in validation, error handling, visual feedback.

// Use TextureDropTarget for textures
TextureDropTarget.Draw("Texture", onTextureChanged, assetsManager);

// Use AudioDropTarget for audio
AudioDropTarget.Draw("Audio Clip", onAudioChanged, assetsManager);

// Use MeshDropTarget for meshes
MeshDropTarget.Draw("Mesh", onMeshChanged, assetsManager);

3. Use UIPropertyRenderer and VectorPanel in Component Editors

Why: Component types are known at compile time — no boxing needed. IFieldEditor is for the script inspector only (reflection-based, runtime types).

// ✅ CORRECT - primitives via UIPropertyRenderer
UIPropertyRenderer.DrawPropertyField("Speed", component.Speed,
    newValue => component.Speed = (float)newValue);

UIPropertyRenderer.DrawPropertyField("Enabled", component.IsEnabled,
    newValue => component.IsEnabled = (bool)newValue);

// ✅ CORRECT - vectors via VectorPanel (axis colors, reset buttons)
var pos = component.Position;
VectorPanel.DrawVec3Control("Position", ref pos);
if (pos != component.Position) component.Position = pos;

// ❌ WRONG - IFieldEditor<T> doesn't exist; don't use IFieldEditor in component editors
_floatEditor.DrawField("Speed", ref component.Speed);

4. Use EditorUIConstants for All Sizing/Spacing

Why: Global style changes, visual consistency, no magic numbers.

// Always use constants
ButtonDrawer.DrawButton("Export",
    width: EditorUIConstants.WideButtonWidth);
LayoutDrawer.DrawSpacing(EditorUIConstants.LargePadding);
ImGui.PushStyleColor(ImGuiCol.Text, EditorUIConstants.ErrorColor);

// NEVER hardcode
ImGui.Button("Export", new Vector2(150, 35)); // ❌ WRONG
ImGui.Dummy(new Vector2(0, 10)); // ❌ WRONG

5. Use Semantic Colors for Actions

Why: Visual consistency, user expectations (red=danger, green=success).

// Destructive actions = Error (red)
ButtonDrawer.DrawColoredButton("Delete", MessageType.Error);
TextDrawer.DrawText("Validation failed", MessageType.Error);

// Confirmations = Success (green)
ButtonDrawer.DrawColoredButton("Save", MessageType.Success);
TextDrawer.DrawText("Saved successfully!", MessageType.Success);

// Cautions = Warning (yellow)
TextDrawer.DrawText("Overwriting existing file", MessageType.Warning);

6. Prefer ComponentSelector/EntityContextMenu Over Custom Menus

Why: Consistent UX, keyboard navigation, automatic component discovery.

// Use ComponentSelector for "Add Component"
private readonly ComponentSelector _selector = new();

if (ButtonDrawer.DrawButton("Add Component"))
    _selector.Show(entity);
_selector.Draw(); // Call every frame

// Use EntityContextMenu for right-click
private readonly EntityContextMenu _contextMenu = new();

if (ImGui.IsItemClicked(ImGuiMouseButton.Right))
    _contextMenu.Show(entity, scene);
_contextMenu.Draw(); // Call every frame

---

Common Anti-Patterns

1. Bypassing UI Infrastructure

Problem: Inconsistent sizing, breaks global style changes, harder to maintain.

// ❌ WRONG - Raw ImGui
if (ImGui.Button("Save", new Vector2(120, 30)))
    Save();
ImGui.SetNextItemWidth(200);

// ✅ CORRECT - Use infrastructure
if (ButtonDrawer.DrawButton("Save"))
    Save();
ImGui.SetNextItemWidth(EditorUIConstants.DefaultColumnWidth);

Why It's Bad: Hardcoded values prevent global style updates, break visual consistency.

2. Custom Drag-Drop Logic

Problem: Complex validation, error handling, visual feedback must be reimplemented.

// ❌ WRONG - Manual implementation
if (ImGui.BeginDragDropTarget())
{
    var payload = ImGui.AcceptDragDropPayload("CONTENT_BROWSER_ITEM");
    if (payload.NativePtr != null)
    {
        // File extension validation
        // Path validation
        // Error messages
        // Visual feedback
    }
}

// ✅ CORRECT - Use specialized target
TextureDropTarget.Draw("Texture", onChange, assetsManager);

Why It's Bad: Drop targets handle validation, errors, and visual feedback automatically.

3. Inline Field Editors

Problem: Breaks DI pattern, inconsistent layout ratios, no axis coloring.

// ❌ WRONG - Direct ImGui
ImGui.DragFloat("Speed", ref speed);
ImGui.DragFloat3("Position", ref position);

// ✅ CORRECT - Inject and use field editors
_floatEditor.DrawField("Speed", ref speed);
_vectorEditor.DrawField("Position", ref position); // Automatic X/Y/Z colors

Why It's Bad: Loses PropertyLabelRatio (33/67 split), axis color coding, reset buttons.

---

Integration Checklist

When implementing editor UI, ensure:

• All buttons use ButtonDrawer (not raw ImGui.Button)
• All asset references use drag-drop targets (TextureDropTarget, AudioDropTarget, etc.)
• All component editors inject field editors for primitive types
• All sizes/spacing use EditorUIConstants (no magic numbers)
• All colors use EditorUIConstants (ErrorColor, SuccessColor, AxisXColor, etc.)
• All modals use ModalDrawer.RenderConfirmationModal()
• All tables use TableDrawer.BeginTable()
• All trees use TreeDrawer
• All tooltips use LayoutDrawer.DrawTooltip()
• All spacing uses LayoutDrawer.DrawSpacing()

---

Reference Documentation

API References

Detailed API documentation for each infrastructure layer:

• references/drawers-api.md: Complete Drawer APIs

  • ButtonDrawer (15+ button variants)
  • ModalDrawer (confirmation dialogs, custom modals)
  • TableDrawer, TreeDrawer, LayoutDrawer, TextDrawer, DragDropDrawer
  • Common patterns and usage examples

• references/elements-api.md: Complete Element APIs

  • Drag-drop targets (Texture, Audio, Mesh, Prefab)
  • ComponentSelector (searchable component list)
  • EntityContextMenu (right-click operations)
  • PrefabManager (prefab creation/instantiation)

• references/constants-catalog.md: EditorUIConstants Catalog

  • Complete constant listing (button sizes, spacing, colors)
  • Design rationale (why PropertyLabelRatio = 0.33f, etc.)
  • Usage guidelines and quick reference

Related Files

• Editor/UI/Drawers/ - All drawer implementations
• Editor/UI/Elements/ - All element implementations
• Editor/UI/FieldEditors/ - All field editor implementations
• Editor/UI/Constants/EditorUIConstants.cs - Constant definitions

---

Summary

The Editor UI infrastructure provides four layers:

1. Drawers (7 classes): Static utilities for common patterns (buttons, modals, tables)
2. Elements (9 components): Stateful components for complex interactions (drop targets, selectors)
3. FieldEditors (8 generic types): Type-safe editors for component properties
4. EditorUIConstants (30+ constants): Centralized styling values

Key Principle: Never reimplement existing patterns. Check Drawers/Elements/FieldEditors first, then write custom ImGui code only if no match exists.