In-App Visual UI Editor

[MrScripty]

1. Introduction & Purpose

This proposal outlines the second phase of our UI development initiative: the creation of an in-app visual UI editor. This document assumes the successful completion of the "Final Development Plan: The whip_ui Framework," which provides the foundational Taffy-driven layout engine and TOML-based UI definition system.

The primary goal of this phase is to empower users and developers with the ability to interactively design, modify, and inspect the application's user interface layout and properties directly within the running application. This will create a powerful "live editing" workflow, leveraging the whip_ui framework we have built.

2. Goals & Scope

• Core Functionality (MVP Editor):
  • Implement a toggleable "UI Edit Mode" (e.g., via hotkey).
  • In Edit Mode:
    • Allow selection of UI elements by clicking on them.
    • Display a "Property Inspector" panel for the selected UI element. This inspector will itself be a UI built with whip_ui.
    • Allow modification of basic Taffy style properties (e.g., width, height, margin, padding, flex_grow, background_color) via the Inspector.
    • Provide real-time visual updates of the UI as properties are changed, triggering Taffy re-layouts.
    • Save the modified UI definition (structure and properties) back to its source TOML file.
    • Implement basic interactive manipulation, such as dragging a splitter to resize adjacent panels.
• Out of Scope (Initial Phases):
  • Advanced visual manipulation (e.g., direct drag-to-resize handles on elements, drag-and-drop reordering in the main view).
  • A full widget library beyond basic panels, buttons, and labels.
  • Undo/Redo functionality for UI edits.
  • Live editing of CSS-like class definitions (focus on inline/element-specific styles first).

3. Proposed Architecture & Design

The UI Editor will be a new mode within the existing Bevy application, built entirely on top of the event-driven whip_ui framework.

• UiEditorPlugin (Bevy Plugin):
  • Purpose: Manages the state and systems for the UI Edit Mode.
  • Resources:
    • UiEditorState { is_active: bool, selected_element: Option<Entity> }.
  • Events:
    • SelectUiElementRequest { target_entity: Entity }.
    • UpdateUiElementStyleRequest { target_entity: Entity, property: StylePropertyKey, new_value: StylePropertyValue }.
    • SaveUiLayoutRequest { path: String }.
  • Systems (run when UiEditorState.is_active):
    • toggle_ui_edit_mode_system: Listens for a hotkey to toggle UiEditorState.is_active.
    • ui_element_selection_system: Handles mouse clicks in edit mode. Performs hit-testing against layout bounding boxes and sends SelectUiElementRequest. This system will override normal interaction logic.
    • ui_element_drag_system: Handles specialized dragging in edit mode (like for splitters). It translates drag deltas into UpdateUiElementStyleRequest events for adjacent panels, rather than directly modifying a Transform.
    • property_inspector_system: If an element is selected, this system displays its properties (from its Styleable component) in the Inspector UI. It handles input in the Inspector and sends UpdateUiElementStyleRequest events.
    • apply_style_changes_system: Receives UpdateUiElementStyleRequest, modifies the Styleable component of the target entity, and updates the corresponding node in the TaffyTree, triggering a re-layout.
    • save_ui_layout_system: Receives SaveUiLayoutRequest, traverses the Bevy entity tree representing the UI, and serializes the current structure and Styleable properties back to the specified TOML file.

4. Implementation Plan & Actionable Steps

This plan begins after the whip_ui framework is complete and functional.

---

Milestone 0: Prerequisites

• Goal: Ensure the foundational framework is ready.
• Tasks:
  1. Verify that the whip_ui framework can successfully load and render a UI from a TOML file, as per the "Final Development Plan: The whip_ui Framework."
  2. Create the initial TOML layout for the editor itself (e.g., a main view with a sidebar for the future property inspector). This UI will be static for now.
• Success Criteria: The application launches with a basic, unchangeable layout that includes a placeholder area for the property inspector.

---

Milestone 1: Edit Mode & Element Selection

• Goal: Implement the ability to enter an "edit mode" and visually select UI elements.
• Tasks:
  1. Implement the UiEditorPlugin and the UiEditorState resource.
  2. Implement the toggle_ui_edit_mode_system to switch UiEditorState.is_active via a hotkey.
  3. Implement the ui_element_selection_system. When in edit mode, this system will:
     • Perform hit-testing on mouse clicks against the computed layout rectangles of UiNode entities.
     • On a successful hit, set the UiEditorState.selected_element.
  4. Add a simple visual feedback system (e.g., spawning a child entity with an outline ShapeData) that highlights the selected entity.
• Success Criteria: The user can press a hotkey to enter edit mode. Clicking on a UI panel highlights it with an outline. Clicking another panel moves the highlight.

---

Milestone 2: The Read-Only Property Inspector

• Goal: Display the properties of the selected element in the UI, breaking the "chicken-and-egg" problem.
• Tasks:
  1. Implement the property_inspector_system.
  2. This system checks if UiEditorState.selected_element is Some.
  3. If it is, it queries the Styleable component of the selected entity.
  4. It then finds the Text components of our inspector UI (e.g., the "width_value" label) and updates their content to display the properties from the selected entity's Styleable component.
• Success Criteria: When a panel is selected in edit mode, the sidebar UI populates with its current style properties (width, height, margin, etc.) as read-only text.

---

Milestone 3: Two-Way Binding & Live Editing

• Goal: Make the property inspector interactive, allowing for real-time modification of the UI.
• Tasks:
  1. Make the value fields in the inspector EditableText.
  2. Enhance property_inspector_system to handle text changes in its fields. When a value is edited, it will parse the new value and send an UpdateUiElementStyleRequest event.
  3. Implement the apply_style_changes_system to listen for this event, modify the appropriate Styleable component, and update the Taffy tree.
• Success Criteria: Selecting a UI element and changing a value (e.g., background_color or width) in the inspector causes the UI element to update visually in real-time.

---

Milestone 4: Saving Layout Changes

• Goal: Persist the changes made in the editor back to the source file.
• Tasks:
  1. Implement the save_ui_layout_system and the SaveUiLayoutRequest event.
  2. Trigger this event via a "Save" button in the editor's UI or a hotkey.
  3. The system will traverse the Bevy entity hierarchy of UiNodes, read their current Styleable properties and structure, and serialize the entire tree back to the appropriate TOML file.
• Success Criteria: The user can edit a UI, save the changes, restart the application, and see the modified layout load correctly.

---

Milestone 5: Advanced Interaction - Draggable Splitter

• Goal: Implement a more complex editor interaction to prove the architecture's flexibility.
• Tasks:
  1. Define a <splitter> widget type in a TOML blueprint.
  2. Implement the ui_element_drag_system.
  3. When a splitter is dragged in edit mode, this system will calculate the delta and send UpdateUiElementStyleRequest events to change the flex-basis or width of the panels adjacent to the splitter.
• Success Criteria: A splitter placed between two panels can be dragged interactively, causing the panels to resize smoothly in real-time.

5. Future Considerations (Post-MVP Editor)

Upon completion of this MVP editor, we will be positioned to tackle more advanced features. Each of these will be scoped in its own dedicated development proposal.

• Advanced Editor UX: (Hierarchy/Tree View, Radial Menus for element creation, Undo/Redo).
• Direct Visual Manipulation: (Drag-to-resize handles, drag-and-drop reordering).
• AI-Ready API (JSON-RPC Server): Exposing the editor's event bus for external control.