Created Design: dynamic palette (markdown)

Design:-dynamic-palette.md

@@ -0,0 +1,70 @@
+Design notes for #322 
+
+Currently, the palette of nodes is loaded when the runtime starts and does not change.
+
+The runtime needs to allow nodes to be added/removed dynamically.
+
+Some points that need to be considered:
+
+- nodes can be added by dropping files into the node path, or by npm. Both of these mechanisms should be supported by this feature
+    - adding by file will expect the file to have already been copied into node path
+    - adding by npm will trigger an npm install of the module
+    - future support for importing a zip or files themselves?
+- removing a node cannot 'unload' the module - care must be taken if the node creates any 'static' resources
+- removing a node in the editor must allow it to remove any artefacts added to the page (eg, debug node's tab)
+- a node file or module can contain multiple nodes. Making a request to remove a single node type may trigger the removal of multiple node types.
+- what to do if the node is being used in the current flow? Safest option is to reject the removal.
+- removing a node, without also removing the files, will mean it returns to the palette on the next restart. That would be unexpected.
+
+
+## On the packaging of nodes
+
+### node ###
+A **node** is defined in an html file and a js file. The js file will include a call to the runtime's version of `RED.nodes.registerType`. The html file will contain the template and help script blocks, along with a call to the editor's version of `RED.nodes.registerType`.
+
+### node set ###
+A js/html file pair may contain multiple **nodes**. This is called a **node set**. Any error loading the js/html files will cause all **nodes** in a **node set** to be unavailable.
+
+### node module ###
+An npm **node module** may contain multiple js/html file pairs - each identified in the `package.json` file. Hence, an npm module may contain multiple **node sets**, each containing 1 or more **nodes**.
+
+### node pack ###
+A `node pack` is a collection of similarly-themed nodes that a user might want to install together. It is structurally the same as a node module, but acts as a meta-package that pulls in multiple specific **node modules** using the standard package dependency mechanism.
+
+### Add/Remove vs Enable/Disable
+The Add/Remove api is for getting new nodes installed into the runtime as well as removing them. It operates at either the js/html level, or the node module level.
+
+The Enable/Disable api is used with **node sets**. This is how a user can install a **node module** using the Add/Remove API, then elect to disable one or more of the **node sets** it contains so they don't appear in the palette.
+
+### Adding a node set/module
+To add a new node to the palette:
+
+1. a request is POSTed to `{admin root}/nodes` to trigger the add.
+   The post body is a JSON structure that identifies where the node information comes from, either a local file (`file`) or an npm module (`module`).
+
+        {
+            file: "path to local node .js file or package.json",
+            module: "npm module name"
+        }
+
+2. The response to this request is a json object containing the node set id, a list of the specific types in the set and a boolean flag to show if it is enabled or not. If not enabled, it may also list an error message describing why it is not enabled - unless if has been disabled by the user.
+
+3. An event is fired over the comms link telling any connected editors that nodes have been added. This triggers a HTTP Get back to `{admin root}/nodes/{node-set-id}` to load the node definition/help/edit template.
+
+### Remove node set/module
+To remove a node from the palette:
+
+1. a DELETE http request is sent to `{admin root}/nodes/{node-set-id}` to trigger the removal.
+2. If the any of the corresponding nodes are in use, the request is rejected
+3. The runtime registry removes the corresponding nodes.
+4. An event is fired over the comms link telling any connected editors that the nodes have been removed.
+
+### Enable a node set
+TBD
+
+ - need a persistence mechanism to remember the enabled/disabled state of nodes over restarts.
+
+### Disable a node set
+TBD
+
+ - as with remove, cannot disable a node set that contains an in-use type