Refactor of layout rest API

[heswell]

This is a place to brainstorm ideas round the refactor of application layout loading - switching from a monolithic layout structure that describes the entire set of layouts that comprise the loaded application to a more modular structure that saves and loads layouts individually

1. client logs in for first time
   /api/vui/{username}

1A) existing service responds with 404, so we display defaultLayout, with placeholder

defaultLayout JSON is hardcoded in the app

{

type: "Stack",
props: {
    style: {
        width: "100%",
        height: "100%",
    },
    enableAddTab: true,
    enableRemoveTab: true,
    preserve: true,
    active: 0,
    TabstripProps: {
        allowAddTab: true,
        allowCloseTab: true,
        allowRenameTab: true,
    },
},
children: [
    {
        type: "Placeholder",
        title: "Page 1",
    },
]
}

1B) new service returns defaultLayout, with placeholder and version "vuu.layout.version": 2
note layout service returns the defaultLayout, its no longer hardcoded in the app
Note: we wrap the layout structure with an enclosing envelope that carries the version. We might
eventually want to record additional metadata here or user settings etc. Maybe application id

Note also: the 'placeholder' is defined inline. I think the new system should equally support
inline layouts and dynamically loaded layouts. The former should be considered readonly

Note also: the placeholder is simply an empty component, it accounts for the whitespace we see on empty application load. This will be replaced by a Welcome page of some kind with richer content.

{
"vuu.layout.version": 2
layout:
    {

    type: "Stack",
    props: {
        style: {
            width: "100%",
            height: "100%",
        },
        enableAddTab: true,
        enableRemoveTab: true,
        preserve: true,
        active: 0,
        TabstripProps: {
            allowAddTab: true,
            allowCloseTab: true,
            allowRenameTab: true,
        },
    },
    children: [
        {
            type: "Placeholder",
            title: "Page 1",
        },
    ]
    }
}

2. UI renders defaultLayout, with placeholder. In either of the scenarios above we reach this point.

3. User drags content onto layout to replace or displace placeholder

3A) existing service POSTS to /api/vui/{username} the full persisted JSON structure, as above but with new content in open tab

{

type: "Stack",
props: {
    style: {
        width: "100%",
        height: "100%",
    },
    enableAddTab: true,
    enableRemoveTab: true,
    preserve: true,
    active: 0,
    TabstripProps: {
        allowAddTab: true,
        allowCloseTab: true,
        allowRenameTab: true,
    },
},
children: [
    {
        type: "View",
        id: 'xzy',
        title: "Page 1",
        props: {
            closeable: true,
            header: true,
            label: "SIMUL Instruments",
            resize: "defer"
        },
        state: {
            "table-config": {
                columns: [
                    {name: "ric", label: "RIC", pin: "left" },
                    ...
                ]
            }
        },
        children: [
            {
                type: "Feature",
                props: {
                    url: "./feature-vuu-table/index.js"
                    css: "./feature-vuu-table/index.css"
                }

            }
        ]
    },
]
}

3B) new service makes 2 POST requests

Save the application-level JSON ...

• /api/vui/{username}

{
"vuu.layout.version": 2
layout:
    {

    type: "Stack",
    props: {
        style: {
            width: "100%",
            height: "100%",
        },
        enableAddTab: true,
        enableRemoveTab: true,
        preserve: true,
        active: 0,
        TabstripProps: {
            allowAddTab: true,
            allowCloseTab: true,
            allowRenameTab: true,
        },
    },
    children: [
        {
            type: "layout",
            title: "Page 1",
            url: "/api/vui/{username}/xyz" // OR to avoid hardcoding the url in json, maybe just the id, url can be built from that
        },
    ]
    }
}

save the new layout ...

Note: we need a way at runtime to identify that we are creating a new layout here not saving an existing layout. We can easily include an attribute in the defaultLayout that makes this easy

• /api/vui/layouts/xyz

{
    id: "xyz"
    createdBy: "",
    createdTime: "",
    lastUpdatedTime: "",
    layout: {
        type: "View",
        id: 'xzy',
        title: "Page 1",
        props: {
            closeable: true,
            header: true,
            label: "SIMUL Instruments",
            resize: "defer"
        },
        state: {
            "table-config": {
                columns: [
                    {name: "ric", label: "RIC", pin: "left" },
                    ...
                ]
            }
        },
        children: [
            {
                type: "Feature",
                props: {
                    url: "./feature-vuu-table/index.js"
                    css: "./feature-vuu-table/index.css"
                }

            }
        ]
    }
}

2. Client logs back in after creating this new layout

calls layout service endpoint ...

/api/vui/{username}

2A) existing service returns full JSON structure saved in 3A above

2B) new service returns application layout described in 3A above. This carries the "vuu.layout.version" at top level, so UI parses JSON, discovers 'active' attribute od Stack which denotes open layout, reads the metadata for this layout (the id), then loads

/api/vui/layouts/id

once received, this is merged into the application layout structure and everything proceeds as before.

Changes required:

• The application uses a config.json that allows startup params to be injected into the app, currently includes
  available features and websocket url. We can extend this to include layout rest endpoint root url

• change to deserialisation logic to recognise the version attribute and take the layout from the nested layout structure, rather than using top-level structure as layout.

• the serialisation logic must be changed so that when application is serialized, individual layouts are replaced by layout entries, with url and title etc.

• when LayoputProvider is passed the applciation json, it should store teh version as a context attribute, I think it will be useful

• the persistence code that currently saves any user manipulation of layout structure or Feature props will trigger a save layout operation, not a save application operation. Switching top level tabs will still trigger a save application.

• function in layout-utils to merge a dynamically loaded layout into the existing structure. This will involve deserializing the json to a JSX structure then injecting that structure into the application layout model. It will be a replace operation replacing the layout stub. There are existing layout model actions that do this kind of thing.

• Will need to represent the loading state in the ui, when a layout is opened dynamically. It will be very fast, but we should make sure we can display a loading state just in case.

• there are opportunities to reduce the size of the json we save. Some of the props we are saving (most of the props for View, for example) are the default props anyway. If we were smarter about saving only the props user has actually changed, might be useful optimisation.

[ddimtirov]

Note: we need a way at runtime to identify that we are creating a new layout here not saving an existing layout.

This can be expressed with the HTTP verb - PUT if you are sending the full layout, PATCH if you are sending delta.

I assume that the layout storage is associated with a user. It would be nice if the application provider can customize the default (set of) layouts that a user would get if no custom layouts are found. It would also be nice if there is a first-class API for the server to add a layout to a user's store.

Also, I'd like to have the option of tweaking layouts locally (i.e. by editing data in LocalStorage or InexedDB). In such case, the layout loading would amount to syncing the local data with the server, and then applying the active layout. It will also work even if the server does not offer persistence.

We haven't talked what will happen when the layout schema no longer matches the UI (i.e. forward compatibility for UI evolution)

[heswell]

"It would also be nice if there is a first-class API for the server to add a layout to a user's store."

agree. This would be really nice for publishing things like "whats new" type announcements, exactly the way VSCode does it

[heswell]

"I assume that the layout storage is associated with a user."

Good question. I think generally, yes, but we might also want to consider some kind of 'system' layouts that are readonly and shares across users