docs: improve doc

docs/vitepress/.vitepress/config.mjs

@@ -56,6 +56,7 @@ export default defineConfig({
             { text: 'Cheatsheet', link: '/guide/intro/cheatsheet' },
             { text: 'Course', link: '/guide/intro/course' },
             // { text: 'Vue 2/3 client', link: '/guide/intro/vue23' },
+            { text: 'Widgets', link: '/guide/intro/widgets' },
           ]
         },
         {
@@ -96,20 +97,9 @@ export default defineConfig({
           text: 'Core functionalities',
           items: [
             { text: 'Basics', link: '/examples/core/basics' },
-            { text: 'File management', link: '/examples/core/files' },
+            { text: 'Files', link: '/examples/core/files' },
             { text: 'Jupyter', link: '/examples/core/jupyter' },
-
-            // { text: 'CLI', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/cli.py' },
-            // { text: 'File Upload', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/upload.py' },
-            // { text: 'Router', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/10_router.py' },
-            // { text: 'Favicon', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/12_reserved_state.py' },
-            // { text: 'MouseTrap', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/16_mousetrap.py'},
-            // { text: 'Download text', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/22_download_server_content.py' },
-            // { text: 'Download binary', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/24_vtk_download_image.py' },
-            // { text: 'CSS', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/28_css.py' },
-            // { text: 'Class decorator', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/decorators/default_class_decorator.py' },
-            // { text: 'Panel comparison', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/panel' },
-            // { text: 'Docker', link: 'https://github.com/Kitware/trame/blob/master/examples/deploy/docker/SingleFile' },
+            // router, docker            
           ]
         },
         {

docs/vitepress/examples/core/basics.md

@@ -5,10 +5,8 @@ The examples presented below are meant to be executed and explored so you can un
 ## State management
 
 ::: code-group
-
 <<< @/../../examples/core_features/state.py
 <<< @/../../examples/core_features/reserved_state.py
-
 :::
 
 ## Events management
@@ -18,10 +16,8 @@ The examples presented below are meant to be executed and explored so you can un
 ## User Interface
 
 ::: code-group
-
 <<< @/../../examples/core_features/dynamic_layout.py
 <<< @/../../examples/core_features/multi_layout.py
-
 :::
 
 ## Life Cycle 
@@ -41,3 +37,7 @@ Once hot-reload is enabled by either using the `TRAME_HOT_RELOAD` environment va
 But in the following example, you can use `watchdog` to execute the UI update on file change.
 
 <<< @/../../examples/core_features/hot_reload.py
+
+## Class for trame application
+
+<<< @/../../examples/core_features/app.py

docs/vitepress/examples/core/files.md

@@ -1,9 +1,28 @@
 ## Download
 
+::: code-group
+<<< @/../../examples/core_features/download_txt.py
+<<< @/../../examples/core_features/download_binary.py
+:::
 
 ## Upload
 
+<<< @/../../examples/core_features/upload.py
 
 ## Browse
 
-<<< @/../../examples/core_features/sys_filebrowser.py
+<<< @/../../examples/core_features/sys_filebrowser.py
+
+## Local CSS file
+
+::: code-group
+<<< @/../../examples/core_features/custom_css.py
+<<< @/../../examples/core_features/custom.css
+:::
+
+## Local images as URL
+
+::: code-group
+<<< @/../../examples/core_features/images_inline.py
+<<< @/../../examples/core_features/images_http.py
+:::

docs/vitepress/examples/core/jupyter.md

@@ -1,3 +1,29 @@
-## Exposing a trame application into Jupyter
+# Exposing a trame application into Jupyter
+
+## Disable warning
+
+```python
+import os
+os.environ["TRAME_DISABLE_V3_WARNING"] = "1"
+```
+
+## Define application
 
 <<< @/../../examples/core_features/jupyter.py
+
+## Use application within Jupyter
+
+```python
+cone = Cone()
+await cone.ui.ready
+cone.ui
+```
+
+![Trame in Jupyer](/assets/images/deployment/jupyter.png)
+
+## Edit state in another cell
+
+```python
+cone.resolution = 4
+```
+

docs/vitepress/guide/intro/widgets.md

@@ -0,0 +1,27 @@
+## Widgets compatibility and package name
+
+| Widget name (trame.widget.{name}) | Package name | Supported version | Number of components |
+| --- | --- | --- | --- |
+| html | (built-in) | 2 & 3 | 80 |
+| client | (built-in) | 2 & 3 | 5 |
+| vuetify, vuetify2, vuetify3 | trame-vuetify | 2 & 3 | 146/156 |
+| router | trame-router | 2 & 3 | 2 |
+| vtk, paraview | trame-vtk | 2 & 3 | 15 |
+| plotly | trame-plotly | 2 & 3 | 1 |
+| xterm | trame-xterm | 2 & 3 | 1 |
+| code | trame-code | 2 & 3 | 1 |
+| iframe | trame-iframe | 2 & 3 | 2 |
+| trame | trame-components | 2 & 3 | 11 |
+| keycloak | trame-keycloak | 2 & 3 (wip) | 1 |
+| quasar | trame-quasar | 3 | 123 |
+| formkit | trame-formkit | 3 | 2 |
+| leaflet | trame-leaflet | 2 | 22 |
+| pvui | trame-pvui | 2 | . |
+| grid | trame-grid-layout | 2 | 2 |
+| tauri | trame-tauri | 2 | - |
+| vega | trame-vega | 2 | 1 |
+| simput | trame-simput | 2 | 2 |
+| rca | trame-rca | 2 (wip for 3) | 7 |
+| matplotlib | trame-matplotlib | 2 | 1 |
+| markdown | trame-markdown | 2 | 1 |
+| deckgl | trame-deckgl | 2 | 1 |

docs/vitepress/guide/versions/trame_v2-3.md

@@ -79,30 +79,4 @@ os.environ["TRAME_DISABLE_V3_WARNING"] = "1"
 
 Trame in itself won't have API change but it is possible that vue3 widget will have a different API like you can see between vuetify2 and vuetify3, but in general we'll try to maintain full API compatibility.
 
-## Widgets compatibility and package name
-
-| Widget name (trame.widget.{name}) | Package name | Supported version |
-| --- | --- | --- |
-| html | (built-in) | 2 & 3 |
-| client | (built-in) | 2 & 3 |
-| vuetify, vuetify2, vuetify3 | trame-vuetify | 2 & 3 |
-| router | trame-router | 2 & 3 |
-| vtk, paraview | trame-vtk | 2 & 3 |
-| plotly | trame-plotly | 2 & 3 |
-| xterm | trame-xterm | 2 & 3 |
-| code | trame-code | 2 & 3 |
-| iframe | trame-iframe | 2 & 3 |
-| trame | trame-components | 2 & 3 |
-| keycloak | trame-keycloak | 2 & 3 (wip) |
-| formkit | trame-formkit | 3 |
-| leaflet | trame-leaflet | 2 |
-| video | trame-video | 2 |
-| pvui | trame-pvui | 2 |
-| grid | trame-grid-layout | 2 |
-| tauri | trame-tauri | 2 |
-| vega | trame-vega | 2 |
-| simput | trame-simput | 2 |
-| rca | trame-rca | 2 (wip for 3) |
-| matplotlib | trame-matplotlib | 2 |
-| markdown | trame-markdown | 2 |
-| deckgl | trame-deckgl | 2 |
+<!--@include: ../intro/widgets.md-->

examples/core_features/app.py

@@ -0,0 +1,53 @@
+from trame.app import get_server
+from trame.decorators import TrameApp, change, controller, trigger, life_cycle
+from trame.ui.html import DivLayout
+from trame.widgets import html
+
+
+@TrameApp()
+class App:
+    def __init__(self, name=None):
+        self.server = get_server(name)
+        self.ui()
+
+    @property
+    def state(self):
+        return self.server.state
+
+    @property
+    def ctrl(self):
+        return self.server.controller
+
+    @trigger("exec")
+    def method_call(self, msg):
+        print("method_called", msg)
+
+    @controller.set("hello")
+    def method_on_ctrl(self, *args):
+        print("method_on_ctrl", args)
+
+    @change("resolution")
+    def one_slider(self, resolution, **kwargs):
+        print("Slider value 1", resolution)
+
+    @life_cycle.server_ready
+    def on_ready(self, *args, **kwargs):
+        print("on_ready")
+
+    def ui(self):
+        with DivLayout(self.server) as layout:
+            html.Input(
+                type="range",
+                min=3,
+                max=60,
+                step=1,
+                v_model_number=("resolution", 6),
+            )
+            html.Button("trigger", click="trigger('exec', ['trigger'])")
+            html.Button("method", click=(self.method_call, "['method']"))
+            html.Button("ctrl", click=self.ctrl.hello)
+
+
+if __name__ == "__main__":
+    app = App()
+    app.server.start()

examples/core_features/custom.css

@@ -0,0 +1,3 @@
+body {
+    background-color: red;
+}

examples/core_features/custom_css.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from trame.app import get_server
+from trame.widgets import client
+from trame.ui.html import DivLayout
+
+CSS_FILE = Path(__file__).with_name("custom.css")
+
+server = get_server()
+with DivLayout(server):
+    client.Style(CSS_FILE.read_text())
+
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/download_binary.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+from trame.app import get_server
+from trame.ui.html import DivLayout
+from trame.widgets import html
+
+BINARY_FILE = Path(__file__).parent.parent / "data/can.ex2"
+
+server = get_server()
+state, ctrl = server.state, server.controller
+
+
+@ctrl.trigger("download_binary")
+def download():
+    return server.protocol.addAttachment(BINARY_FILE.read_bytes())
+
+
+with DivLayout(server):
+    html.Button(
+        "Download ",
+        click="utils.download('can.ex2', trigger('download_binary'), 'application/octet-stream')",
+    )
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/download_txt.py

@@ -0,0 +1,28 @@
+import time
+from trame.app import get_server
+from trame.ui.html import DivLayout
+from trame.widgets import html
+
+server = get_server()
+state, ctrl = server.state, server.controller
+
+state.other_txt_content = "Some content to download..."
+
+
+@ctrl.trigger("download_content")
+def generate_content():
+    return f"Hello on the server is {time.time()}"
+
+
+with DivLayout(server):
+    html.Button(
+        "Download from method",
+        click="utils.download('method.txt', trigger('download_content'), 'text/plain')",
+    )
+    html.Button(
+        "Download from state",
+        click="utils.download('state.txt', other_txt_content, 'text/plain')",
+    )
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/events.py

@@ -47,8 +47,6 @@ def method_4(*args, **kwargs):
 # UI setup
 # -----------------------------------------------------------------------------
 
-layout = DivLayout(server)
-
 with DivLayout(server):
     html.Div(
         "State a={{ a }}", style="padding: 20px; margin: 20px; border: solid 1px #333;"

examples/core_features/images_http.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from trame.app import get_server
+from trame.widgets import html
+from trame.ui.html import DivLayout
+
+
+DIRECTORY = Path(__file__).parent.parent.parent / "docs/vitepress/assets/images/apps"
+
+server = get_server()
+server.enable_module({"serve": {"data": str(DIRECTORY.absolute())}})
+
+with DivLayout(server):
+    for file in DIRECTORY.iterdir():
+        html.Img(src=f"/data/{file.name}", style="width: 200px;")
+
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/images_inline.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from trame.app import get_server
+from trame.assets.local import LocalFileManager
+from trame.widgets import html
+from trame.ui.html import DivLayout
+
+
+KEYS = []
+DIRECTORY = Path(__file__).parent.parent.parent / "docs/vitepress/assets/images/apps"
+ASSETS = LocalFileManager(DIRECTORY)
+
+for image in DIRECTORY.iterdir():
+    key = image.stem.replace("-", "_")
+    ASSETS.url(key, image.name)
+    KEYS.append(key)
+
+
+server = get_server()
+with DivLayout(server):
+    for key in KEYS:
+        html.Img(src=ASSETS[key], style="width: 200px;")
+
+
+if __name__ == "__main__":
+    server.start()