Activity

1. lornakelly

   added

   enhancementNew feature or requestNew feature or request

   on Jul 7, 2026
2. lornakelly

   added a parent issue on Jul 7, 2026

   • Epic: Milestone 2 - Edit a node #214
3. lornakelly

   added this to Editor Project Trackeron Jul 7, 2026
4. github-project-automation

   moved this to Backlog in Editor Project Trackeron Jul 7, 2026
5. lornakelly

   self-assigned this

   on Jul 7, 2026
6. lornakelly

   assigned

   kumaradityaraj

   and unassigned

   lornakelly

   on Jul 16, 2026
7. kumaradityaraj commented on Jul 22, 2026

   

   kumaradityaraj

   on Jul 22, 2026

   Contributor

   More actions

   Investigation: Node Editing Surface

   Overview

   This document evaluates two possible approaches for enabling node editing in the side panel:

   • Approach A: Edit the node's SOURCE block (YAML editor)
   • Approach B: Edit the rendered Properties view

   The goal is to determine which approach best supports future node editing while preventing structural workflow modifications (Milestone 3).

   ---

   Current Implementation

   NodeDetailsView currently renders two independent representations of a task.

   Task
    │
    ├── Properties
    │     └── getTaskDetails(task)
    │             └── flattenFields()
    │                     └── PropertyField
    │
    └── Source
          └── yaml.dump(task)
                  └── YamlField (read-only)
   

   These two views are completely independent.

   ---

   Current Properties View

   The Properties section is generated using:

   const fields = task ? getTaskDetails(task) : [];

   Each field is represented by:

   type DetailField =
     | { path: string; kind: "text"; display: string }
     | { path: string; kind: "array"; count: number }
     | { path: string; kind: "object" };

   The task is recursively flattened into dot-notation paths.

   Example:

   Input:

   action:
     functionRef:
       refName: sendEmail

   becomes

   action.functionRef.refName = sendEmail
   

   Nested objects are flattened until MAX_DEPTH.

   Arrays are summarized only by their count.

   Objects deeper than MAX_DEPTH are replaced with:

   {...}
   

   Metadata is intentionally omitted.

   ---

   Current Source View

   The Source section is generated using

   dump(task, {
     indent: 2,
     lineWidth: -1,
   })

   and rendered inside

   <YamlField />

   The YAML is currently read-only.

   This view always represents the complete task.

   No information is lost.

   ---

   Approach A – Editable YAML

   Description

   Convert the existing YAML source block into an editable editor.

   Instead of

   +----------------------+
   | YAML (read only)     |
   +----------------------+
   

   the user would edit

   name: SendEmail
   action:
     functionRef:
       refName: sendEmail

   directly.

   ---

   Advantages

   1. Minimal implementation effort

   Most of the existing implementation already exists.

   Only the editor changes from read-only to editable.

   ---

   2. Full fidelity

   The YAML contains the complete task.

   Nothing is lost.

   Every property can be edited.

   ---

   3. Uniform across task types

   No task-specific UI is required.

   Every task already has YAML.

   ---

   4. Future-proof

   New DSL fields automatically become editable without updating the UI.

   ---

   Disadvantages

   1. Cannot naturally restrict edits

   The user can modify anything.

   Examples:

   then:
     - task1
     - task2

   can become

   then:
     - task2
     - task1
     - task3

   This violates Milestone 3.

   ---

   2. Structural workflow changes are difficult to prevent

   The ticket explicitly states that users must not be able to

   • add child tasks
   • remove child tasks
   • reorder child tasks

   With free-form YAML this is extremely difficult.

   Preventing this would require:

   • parsing edited YAML
   • validating syntax
   • comparing original and edited structures
   • detecting forbidden modifications
   • rejecting invalid edits

   Essentially a structural diff engine.

   ---

   3. Invalid YAML

   Users can create malformed YAML.

   Example

   action
    functionRef

   The editor must continuously detect and recover from syntax errors.

   ---

   4. Invalid workflow schema

   Even valid YAML may produce an invalid workflow.

   Example

   type: switch

   inside a task that should remain an action task.

   Additional schema validation would be required.

   ---

   5. Difficult user experience

   Errors become harder to explain.

   Example:

   "Structural edits are not allowed."

   The editor must explain exactly what changed.

   ---

   6. High implementation complexity

   Although enabling editing is simple, enforcing restrictions is not.

   Most complexity moves into validation and change detection.

   ---

   Approach B – Editable Properties

   Description

   Instead of editing YAML, allow editing of the rendered Properties section.

   Current

   Name
   SendEmail
   
   Timeout
   PT10S
   

   could become

   Name
   [ SendEmail ]
   
   Timeout
   [ PT10S ]
   

   Each property becomes an appropriate input component.

   ---

   Advantages

   1. Natural restriction of editable fields

   Only exposed properties are editable.

   Workflow structure is never shown.

   Users cannot accidentally modify

   • child tasks
   • execution order
   • task hierarchy

   ---

   2. Easier validation

   Each field can be validated individually.

   Examples

   Timeout
   

   expects

   PT10S
   

   rather than arbitrary text.

   ---

   3. Better user experience

   Most users edit individual properties rather than raw YAML.

   Forms also allow:

   • dropdowns
   • checkboxes
   • numeric inputs
   • autocomplete

   ---

   4. Safer editing

   Only supported fields are writable.

   Everything else remains internal.

   ---

   5. Aligns with Milestone 3

   Because structural fields are never exposed, users cannot perform forbidden edits.

   No structural diffing is required.

   ---

   Disadvantages

   1. Current implementation is display-only

   Today's implementation loses information.

   Arrays become

   3 items
   

   instead of

   functions:
   - a
   - b
   - c

   ---

   Objects become

   {...}
   

   instead of

   arguments:
     first: John
     last: Doe

   ---

   Metadata is omitted entirely.

   ---

   2. DetailField is insufficient for editing

   Current model

   type DetailField =
     | text
     | array
     | object

   contains only display information.

   It does not preserve

   • actual value
   • value type
   • editability
   • validation rules

   ---

   3. Round-trip editing is impossible today

   Current pipeline

   Task
    ↓
   flattenFields()
    ↓
   DetailField[]
   

   cannot reconstruct

   Task
   

   again.

   Information is discarded during flattening.

   ---

   4. Requires redesign

   Supporting editing likely requires a richer model.

   Example

   interface EditableField {
       path: string;
       value: unknown;
       display: string;
       editable: boolean;
       type: "string" | "number" | "boolean" | "enum";
   }

   This preserves enough information to update the original task safely.

   ---

   Current Limitations of getTaskDetails()

   Current flattening intentionally sacrifices fidelity for readability.

   Feature	Current Behaviour
   Arrays	Rendered as item count
   Objects past depth 4	Rendered as {...}
   Metadata	Removed
   Nested objects	Flattened
   Original values	Not always preserved
   Reconstruction	Not possible

   This makes the Properties panel excellent for inspection but insufficient for editing.

   ---

   Comparison

   Area	Approach A (YAML)	Approach B (Properties)
   Initial implementation	Easy	Medium
   Restrict editable fields	Difficult	Easy
   Prevent structural edits	Very difficult	Natural
   Validation	Complex	Simple
   Invalid syntax possible	Yes	No
   Invalid workflow possible	High	Low
   Full task fidelity	Yes	No (currently)
   Requires redesign	No	Yes
   Long-term maintainability	Lower	Higher
   User friendliness	Medium	High

   ---

   Recommendation

   Based on the current implementation and the milestone requirements, Approach B (Editable Properties) appears to be the stronger long-term solution.

   Although it requires redesigning getTaskDetails() and the DetailField model to preserve editable information, it naturally enforces the milestone requirement of preventing structural workflow changes by exposing only supported fields.

   Approach A offers a quick path to editable YAML and preserves the full task representation, but enforcing restrictions such as preventing users from adding, removing, or reordering child steps would require substantial parsing, validation, and structural diffing logic. This increases implementation complexity and introduces a greater risk of invalid workflow definitions.

   A future editable Properties model could evolve from a display-only representation into a richer structured model that retains value types, editability, and validation metadata, allowing safe round-trip editing while keeping workflow structure protected.

   ---
8. kumaradityaraj

   moved this from Backlog to In Progress in Editor Project Trackeron Jul 22, 2026
9. kumaradityaraj commented on Jul 22, 2026

   

   kumaradityaraj

   on Jul 22, 2026

   Contributor

   More actions

   @lornakelly @fantonangeli @handreyrc @cheryl7114
10. lornakelly commented on Jul 22, 2026

    

    lornakelly

    on Jul 22, 2026

    Last edited by lornakelly

    CollaboratorAuthor

    More actions

    Thanks for the detailed write-up @kumaradityaraj. I agree that Approach B is the way to go.

    I don't think the UX of editing YAML directly in the diagram editor sidepanel will be great, especially since people will also have the option of using the dual view and editing YAML from there - we'd most likely need intellisense in the YAML block too for it to be reasonably user-friendly. Without that, it basically results in a worse UX than just using the dual viewer and writing YAML there. Approach B lets us better control and improve UX for the user going forward

    And yes, Approach A basically means we'll have to introduce a structural diff engine later, which isn't great. I think some of the "disadvantages" of Approach B are really about the current implementation rather than the approach itself - currently read only, fidelity loss and round-trip complexity aren't necessarily disadvantages, just things we need to address in the implementation.

    Essentially, Approach B requires more implementation work right now to get editing working - so it's short-term loss versus long-term gain. Whereas I think Approach A will just get more and more complex very quickly as we move forward and isnt really viable from a UX perspective IMO

    ❤️React with ❤️1Reacted by Kumar Aditya Raj
11. kumaradityaraj

    closed this as completedon Jul 23, 2026
12. github-project-automation

    moved this from In Progress to Done in Editor Project Trackeron Jul 23, 2026
13. kumaradityaraj

    moved this from Done to In review in Editor Project Trackeron Jul 23, 2026
14. kumaradityaraj

    reopened this on Jul 23, 2026
15. dgutierr

    closed this as completedon Jul 24, 2026
16. github-project-automation

    moved this from In review to Done in Editor Project Trackeron Jul 24, 2026
17. lornakelly commented on Jul 24, 2026

    

    lornakelly

    on Jul 24, 2026

    CollaboratorAuthor

    More actions

    Reviewed with team and in agreement for Approach B