Merge branch 'main' into yogesh-dashi-vega

# Conflicts:
#	dashi/package-lock.json
#	dashi/package.json

Author: b-yogesh

README.md

@@ -1,2 +1,3 @@
 # dashi
-Dashboard experiments
+
+See [here](dashi/README.md).

dashi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 by Brockmann Consult GmbH and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dashi/README.md

@@ -1,10 +1,54 @@
 # dashi 
 
-Dashi is a demo for server-configured panels using Plotly + Tornado.
+Dashi is a JavaScript library that allows configuring server-side widgets
+and plugging them into existing web frontends.
 
-### Run UI
+_Note, this library is experimental and under development still._
+
+## How it is supposed to work
+
+Users write the widgets in, e.g. Python, and a REST server implements three 
+endpoints to publish the widgets:
+
+- `GET /contributions`: Called once after application UI starts up.
+  Returns an object whose keys are contribution points (e.g., "panels") 
+  and whose values are arrays of contribution objects.
+- `POST /layout/{contribPoint}/{contribIndex}`:
+  Called once for every contribution when it becomes visible in the UI.
+  Returns the contribution's initial component tree
+- `POST /callback`:
+  Called when users interact with the component tree or on application 
+  state changes. Returns an array of contribution changes where each 
+  contribution change contains an array of actions to be applied to the 
+  component tree.
+
+The following sequence diagram depicts how the library is supposed to 
+work. The top shows the JavaScript frontend that uses this library.
+The bottom shows the lifeline of the backend REST server.
+
+![docs/sequence.png](docs/sequence.png)
+
+## How to run the demo
 
 ```bash
+git clone https://github.com/bcdev/dashi.git
+```
+
+### Run the server
+
+```bash
+cd dashi/dashipy
+conda env create
+conda activate dashi
+pip install -ve . 
+python -m dashipy.demo.server
+```
+
+### Run the UI
+
+```bash
+cd ../dashi
 npm install
 npm run dev
 ```
+