Diagram description and example inputs

[aaronchongth]

New feature implementation

Implemented feature

Fixes #153.

• added fields description and example_inputs into Diagram
• propagate usage into diagram editor
• added those fields into example diagram json files we host
• will address adding description and example_inputs when exporting, in a separate PR

GenAI Use

We follow OSRA's policy on GenAI tools

• I used a GenAI tool in this PR.
• I did not use GenAI

Generated-by:

[mxgrey]

I think this is a good start, but I see some improvements that can be made before we merge it. I've left some inline comments about improving the data structures in the Diagram schema. Besides that, I have some recommendations on improving the UI:

Editing descriptions

I think we should address the ability to edit and export the descriptions and input examples within this PR, because I believe doing that in a follow-up PR will effectively become a rewrite of all the typescript introduced in this PR.

Reduce clutter

I don't think it's necessary for the diagram description or example inputs to always be visible. For example, the node builder descriptions are hidden behind an (i) icon, and show up in a tooltip:

I think we should do something similar for the workflow descriptions. Maybe we can have a (?) or (i) toggle button on the right-hand side of the Run Workflow row that would expand a panel to the right of the Run Workflow widget. That expanded panel would contain a read-only text box of the workflow description, as well as a 📝 button to switch the description text box into an edit mode.

Then for the input examples, we could put a (?) or (i) toggle button on the right-hand side of the Request: row that would expand a panel that lists out the input examples. This would also have a 📝 button to switch into edit mode. This panel would be mutually exclusive with the description panel, so toggling on one would automatically toggle off the other.

These are just rough ideas. I'm happy to further discuss the feasibility or effectiveness of this approach.

[mxgrey]

A few concerns here:

• For each example input, we should also allow a description, so users can have some context about the input.
• The data type of the input should not be String, it should be JsonMessage. The String type is too ambiguous, i.e. should the value be interpreted as a literal character string or as the text of a JSON message?
• There's no need to wrap Option around Vec. We can tag this field with #[serde(default, skip_serializing_if = "is_default")]. That way the field can just be skipped for empty vectors.

Overall we should see something like

pub struct ExampleInput {
    pub value: JsonMessage,
    pub description: String,
}

#[serde(default, skip_serializing_if = "is_default")]
example_inputs: Vec<ExampleInput>,

[mxgrey]

We should tag this field with

#[serde(default, skip_serializing_if = "is_default")]

so it can truly be an optional field.