web_editor_spec.md

Note

• There are probably things missing, use best judgement and/or msg/call me
• editor concept loosely ispired by scratch.mit.edu
• user can drag and drop blocks around

Rough UI Overview

• Shapes and Colors

  • Scratch represents datatypes w/ shapes and categories w/ colors
  • having everything with rounded edges is ok for now
  • Espescially considering how loosely typed our language is
  • I'm not sure about colors, I guess we could do by category

• Toolbox: displayed on left of editor

  • Big clickable area that says "generate from template" (does nothing for now)
  • Dropdown categories containing operator blocks
  • blocks: blocks, as they would look in sandbox
  • help button: question mark with a circle around it
    • this shows operator title+subtitle card as a

• Sandbox: right of editor

  • Scrollable
  • Move blocks around
  • Drag blocks into each other's argument fields
  • basically scratch
  • start with blocks that say "buy when" and "sell when"

Operators List

• there will be an endpoint to get metadata for all operators that user has access to
• there is significantly more metadata than needed for this MVP
• there are likely mispellings, typos, etc. that will cause problems
  • will pay for each one u find and fix
• there are probably ones that cause edge conditions
  • lmk, some we don't need
• if operator starts with a space it's synthetic and

Operator Metadata Breakdown

• this data will be provided by GET /strategy/operators/metadata

{

    // this is one example
    
    // the label shouldn't be seen by user
    //   unique name for operator
    //   useful for referencing operator data without duplicating it
    "av_rsi" : { 

        // used to generate help button (can ignore for now)
        title: 'RSI',
        subtitle: 'Relative Strength Index',

        // ignore
        hidden: false,
        in: 2, out: 1, dynamic: true, static: false,

        // data/input fields (these will be inserted into 'template')
        // we specify information needed to generate inputs
        // and attach the value to a name to be used to generate code
        params: {
            // name of the field
            // if possible, this should be the placeholder for input box
            Period: {
                // display on hover
                tooltip: 'number of days to lookback',

                type: 'number', // ignore
                input: { // use this data for generating input field/data
                    
                    // input type
                    // standard html input type names 
                    //    except for "dropdown" and "disabled"
                    type: "number", // input field type

                    // ignore
                    constraints: [
                        "positive",
                        "integer"
                    ],
                }
            },

            // name of field
            Symbol: {
                // show on hover
                tooltip: 'symbol for equity',
                
                // ignore
                type: 'string,text',

                input: {
                    // input type
                    type: "text",

                    // ignore
                    constraints: [ "equity symbol", "not empty", "no spaces" ]
                }
            }
        },

        // this is used to group items (can ignore for now)
        category: 'Technical Indicators', // grouping
        
        // template used to render block
        //    referenced fields enclosed in moustaches,
        //    when displayed they should get replaced with input boxes
        template: '{{Symbol}} RSI {{Period}} days', // how to display to user 

        // syntax for generating code
        //    insert values from input boxes into a string to generate expression
        //    I reccomend using a tree structure like in Functionality section
        syntax: '{{{Period}} {{Symbol}} av_rsi', // how to generate code from it

        // ignore
        returns: 'number', // return datatype (ignore for now)
        tests: [ 0.001, 99.99 ] // test cases
    },


    // this is another example
    "gnews_topic" : {
        hidden: true, in: 1, out: 1, dynamic: true, // ignore
    
        // used to generate help info (not required)
        title: "Google News",
        subtitle: "News feed from Google News Topic",
        
        // Fields
        params: {
            // name of field
            "Topic" : {
                type: "string", // ignore
                tooltip: "Topic from news.google.com", // show on hover

                // defineing input box
                input: {
                    // this is one of the non-standard input types
                    type: "dropdown",
                    // options user has to choose from
                    options: {
                        // key: text user sees and clicks on
                        // value: value that label corresponds to
                        "World" : "WORLD", 
                        "Tech" : "TECHNOLOGY", 
                        "Entertainment" : "ENTERTAINMENT", 
                        "Business" : "BUSINESS",
                        "Sports" : "SPORTS",
                        "Science" : "SCIENCE", 
                        "Health" : "HEALTH"
                    },
                },
            }
        },

        template: "GNews {{Topic}}", // used to generate block
        syntax: "{{Topic}} gnews_topic", // used to generate code
        category: "Feeds", // for grouping (can ignore for now)

        // ignore
        returns: "feed",
    }
}

Literals

• Anything that isn't an operator is assumed to be JSON
• when inserting into operator.syntax you can just do JSON.stringify

Categories

• Might add more/change, best to use response to generate dropdowns :/
• Literals: nothing
• Technical Indicators:
• Feeds:
• Rates:
• Math:
• Comparisons:
• Logic:
• Developer Tools:

Params

• The Key / Name of field should be watermarked

Constraints

• text:
  • not empty: str.length != 0
  • no spaces: !str.includes(' ')
  • regex: valid regular expression (new regex trycatch?)
  • json array : JSON.parse(s) instanceof Array
  • json: is valid json
  • url: valid url
• numbers:
  • positive
  • whole

Type

You can ignore these for now :)

• any: loosely typed
• string:
• list: ordered list of values
• object: named values
• feed: special type of array

Input types:

• valid html input type: use it
• "disabled": can only be used by dropping blocks in
• "dropdown": see object in input.options
  • key: what user sees and clicks
  • value: value that replaces it
• constraints: warn user when invalid

Functionality

• Need to be able to convert what's in the sandbox into a syntax tree
• ie:

{
    token : ">",
    args: {
        "A" : {
            token: "price",
            args: {
                "Symbol" : {
                    value: "aapl"
                },
                "Date" : {
                    token: "now",
                    args: {},
                }
            }
        },
        "B" : {
            value: 350
        }
    }
}

• need to use relevant operator's metadata to generate code
• ie:

const metadata = getOperatorMetaData();
function toCode(tree) {
    if (tree.value)
        return JSON.stringifiy(tree.value);
    
    let code = metadata[tree.token].syntax;
    for (const arg in tree.args)
        code = code.replace(`{{${arg}}}`, toCode(tree.args[arg]));
    return code;
}

Requirements

• draggable demo
• convert structure into a syntax tree (Functionality)
• generate operator blocks from metadata

Features we want to add eventually

We would like to add more advanced features eventually, so having room for growth and having flexible code is usually best. Don't worry about implementing these unless it's trivial.

• generate from template:
  • adding group of blocks based on a form
• opening from saved expression:
  • going from syntax tree to block diagram
• fancy literals:
  • ie - object literals which look like a table
• Operator Embedded form:
  • click a button next to the news operator
  • opens an form that guides through filling in the details
  • when ok is pressed, details will be put in argument fields
• Syntax Checking w/highlighting
  • Our api has a syntax check feature
  • for each branch of expression tree
    • convert to code and run syntax check
  • border for all parts that failed is red
• right click -> run
  • right click on a block/block-expresssion to run it and see output
• copy-paste: blocks + block expressions
• special operators
  • block that can take an arbitrary number of conditions and we have a function on frontend to handle converting them to code
    • examples: any of n conditions, json constructor
  • make some blocks have vertical and horizontal components
    • {{List}}<br/><center>append</center><br/>{{Element}}
• multiple-expression: more than one syntax tree
• Type Checking
  • Make border/Block turn green if types match
• Shapes and colors
  • probably will add more colors + shapes
  • will want to change some of them to icons (ie - twitter logo)
  • probably will do something like template: "<<TwitterLogo>> @{{User}}"
• Autocomplete reccomendations

Example of something in sandbox (example from scratch)