Add atomic NicePool display and preset initialization

Author: cudmore

integrations/nicepool-pyqt5/README.md

@@ -32,6 +32,19 @@ The adapter is storage-agnostic. To persist UI-created workspaces, connect
 list with `set_presets()` after the initial `data_reset`. See
 `examples/preset_persistence.py`.
 
+Apply display-only startup options in the constructor so the first browser
+render already has the intended appearance:
+
+```python
+pool = NicePoolWidget(
+    theme="dark",
+    controls_collapsed=True,
+    preset_editing_visible=True,
+)
+```
+
+The corresponding setters remain available for runtime changes.
+
 ## Run tests and the example
 
 ```bash

integrations/nicepool-pyqt5/examples/demo.py

@@ -30,10 +30,65 @@ def main() -> int:
     """Launch the demo window."""
     application = QApplication(sys.argv)
     window = QMainWindow()
-    pool = NicePoolWidget()
+    pool = NicePoolWidget(controls_collapsed=True)
     pool.error_occurred.connect(print)
     pool.selection_changed.connect(lambda selection: print("Selection:", selection))
-    pool.set_dataframe(sample_dataframe(), row_id_column="pool_row_id")
+    pool.set_dataframe(
+        sample_dataframe(),
+        row_id_column="pool_row_id",
+        schema=[
+            {"name": "pool_row_id", "type": "string", "axis_label": "Row"},
+            {
+                "name": "condition",
+                "type": "string",
+                "axis_label": "Condition",
+                "categorical": True,
+            },
+            {
+                "name": "accept",
+                "type": "string",
+                "axis_label": "Accepted",
+                "categorical": True,
+            },
+            {"name": "time", "type": "number", "axis_label": "Time"},
+            {
+                "name": "amplitude",
+                "type": "number",
+                "axis_label": "Amplitude",
+            },
+        ],
+        preset_definitions=[
+            {
+                "name": "Amplitude over time",
+                "state": {
+                    "layout": "1x1",
+                    "plots": [
+                        {
+                            "plotType": "scatter",
+                            "xColumn": "time",
+                            "yColumn": "amplitude",
+                            "colorColumn": "condition",
+                        }
+                    ],
+                },
+            },
+            {
+                "name": "Amplitude by condition",
+                "state": {
+                    "layout": "1x1",
+                    "plots": [
+                        {
+                            "plotType": "swarm",
+                            "xColumn": "time",
+                            "yColumn": "amplitude",
+                            "groupColumn": "condition",
+                        }
+                    ],
+                },
+            },
+        ],
+        default_preset="Amplitude over time",
+    )
     window.setCentralWidget(pool)
     window.resize(1200, 800)
     window.setWindowTitle("NicePool PyQt5")
@@ -43,4 +98,3 @@ def main() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
-

integrations/nicepool-pyqt5/frontend/main.ts

@@ -2,6 +2,7 @@ import {
   registerNicePoolElement,
   type DatasetInput,
   type NicePoolPreset,
+  type NicePoolPresetDefinition,
   type NicePoolSelection,
   type NicePoolState,
   type NicePoolTheme,
@@ -26,6 +27,7 @@ interface QtNamespace {
 
 interface NicePoolDomElement extends HTMLElement {
   setData(input: DatasetInput): void
+  initializeData(input: DatasetInput, definitions: readonly NicePoolPresetDefinition[], defaultPresetName?: string | null): void
   replaceData(input: DatasetInput): void
   setState(state: NicePoolState): void
   getState(): NicePoolState
@@ -51,6 +53,12 @@ interface CommandEnvelope {
   payload?: unknown
 }
 
+interface InitializeDataPayload {
+  dataset: DatasetInput
+  presetDefinitions: NicePoolPresetDefinition[]
+  defaultPresetName?: string | null
+}
+
 declare global {
   interface Window {
     qt: QtNamespace
@@ -68,8 +76,15 @@ if (typeof globalThis.structuredClone !== 'function') {
 
 registerNicePoolElement()
 
-const pool = document.querySelector<NicePoolDomElement>('nice-pool')
-if (!pool) throw new Error('The NicePool host page is missing its <nice-pool> element')
+const host = document.querySelector<HTMLElement>('#nicepool-host')
+if (!host) throw new Error('The NicePool host page is missing its mount element')
+const parameters = new URLSearchParams(window.location.search)
+const pool = document.createElement('nice-pool') as NicePoolDomElement
+const initialTheme = parameters.get('theme')
+if (initialTheme === 'dark' || initialTheme === 'light') pool.setTheme(initialTheme)
+pool.setControlsCollapsed(parameters.get('controlsCollapsed') === 'true')
+pool.setShowPresetEditing(parameters.get('presetEditingVisible') !== 'false')
+host.append(pool)
 
 function errorText(reason: unknown): string {
   return reason instanceof Error ? reason.message : String(reason)
@@ -108,6 +123,10 @@ new window.QWebChannel(window.qt.webChannelTransport, (channel) => {
   const execute = (command: CommandEnvelope): unknown => {
     switch (command.name) {
       case 'setData': return pool.setData(command.payload as DatasetInput)
+      case 'initializeData': {
+        const payload = command.payload as InitializeDataPayload
+        return pool.initializeData(payload.dataset, payload.presetDefinitions, payload.defaultPresetName)
+      }
       case 'replaceData': return pool.replaceData(command.payload as DatasetInput)
       case 'setState': return pool.setState(command.payload as NicePoolState)
       case 'getState': return pool.getState()

integrations/nicepool-pyqt5/src/nicepool_pyqt5/static/index.html

@@ -6,13 +6,13 @@
     <title>NicePool PyQt5</title>
     <link rel="stylesheet" href="./nicepool-pyqt5.css" />
     <style>
-      html, body, nice-pool { display: block; width: 100%; height: 100%; margin: 0; }
+      html, body, #nicepool-host, nice-pool { display: block; width: 100%; height: 100%; margin: 0; }
       body { overflow: hidden; }
     </style>
     <script src="qrc:///qtwebchannel/qwebchannel.js"></script>
   </head>
   <body>
-    <nice-pool></nice-pool>
+    <div id="nicepool-host"></div>
     <script src="./nicepool-pyqt5.js"></script>
   </body>
 </html>

integrations/nicepool-pyqt5/src/nicepool_pyqt5/widget.py

@@ -8,7 +8,7 @@
 from typing import Any
 
 import pandas as pd
-from PyQt5.QtCore import QUrl, pyqtSignal
+from PyQt5.QtCore import QUrl, QUrlQuery, pyqtSignal
 from PyQt5.QtWebChannel import QWebChannel
 from PyQt5.QtWebEngineWidgets import QWebEngineSettings, QWebEngineView
 from PyQt5.QtWidgets import QVBoxLayout, QWidget
@@ -32,8 +32,29 @@ class NicePoolWidget(QWidget):
     data_replaced = pyqtSignal()
     error_occurred = pyqtSignal(str)
 
-    def __init__(self, parent: QWidget | None = None) -> None:
+    def __init__(
+        self,
+        parent: QWidget | None = None,
+        *,
+        theme: str = "dark",
+        controls_collapsed: bool = False,
+        preset_editing_visible: bool = True,
+    ) -> None:
+        """Create a NicePool host with display options applied before first render.
+
+        Args:
+            parent: Optional parent widget.
+            theme: Initial ``dark`` or ``light`` theme.
+            controls_collapsed: Whether the controls panel starts collapsed.
+            preset_editing_visible: Whether preset editing starts visible.
+
+        Raises:
+            ValueError: If ``theme`` is not supported.
+            RuntimeError: If the packaged browser assets are unavailable.
+        """
         super().__init__(parent)
+        if theme not in {"dark", "light"}:
+            raise ValueError("theme must be 'dark' or 'light'")
         static_directory = Path(__file__).resolve().parent / "static"
         html_path = static_directory / "index.html"
         script_path = static_directory / "nicepool-pyqt5.js"
@@ -51,6 +72,7 @@ def __init__(self, parent: QWidget | None = None) -> None:
         self._pending: dict[int, tuple[str, ResultCallback | None, ErrorCallback | None]] = {}
 
         self.web_view = QWebEngineView(self)
+        self.web_view.hide()
         self.web_view.settings().setAttribute(
             QWebEngineSettings.JavascriptCanAccessClipboard,
             True,
@@ -67,7 +89,18 @@ def __init__(self, parent: QWidget | None = None) -> None:
         self._bridge.message_received.connect(self._receive_browser_message)
         self._bridge.invalid_message.connect(self.error_occurred)
         self.web_view.loadFinished.connect(self._load_finished)
-        self.web_view.load(QUrl.fromLocalFile(str(html_path)))
+        page_url = QUrl.fromLocalFile(str(html_path))
+        query = QUrlQuery()
+        query.addQueryItem("theme", theme)
+        query.addQueryItem(
+            "controlsCollapsed", "true" if controls_collapsed else "false"
+        )
+        query.addQueryItem(
+            "presetEditingVisible",
+            "true" if preset_editing_visible else "false",
+        )
+        page_url.setQuery(query)
+        self.web_view.load(page_url)
 
     @property
     def is_ready(self) -> bool:
@@ -108,6 +141,11 @@ def _receive_browser_message(self, message: dict[str, Any]) -> None:
                 return
             self._ready = True
             self.ready_changed.emit(True)
+            if not any(
+                message["name"] in {"setData", "initializeData"}
+                for message in self._queued_messages
+            ):
+                self.web_view.show()
             self._dispatch_next()
             return
         if kind == "response":
@@ -151,6 +189,7 @@ def _receive_event(self, message: dict[str, Any]) -> None:
         elif name == "themeChanged":
             self.theme_changed.emit(str(detail))
         elif name == "dataReset":
+            self.web_view.show()
             self.data_reset.emit()
         elif name == "dataReplaced":
             self.data_replaced.emit()
@@ -164,16 +203,28 @@ def set_dataframe(
         row_id_column: str,
         schema: Sequence[Mapping[str, Any]] | None = None,
         pre_filter_columns: Sequence[str] | None = None,
+        preset_definitions: Sequence[Mapping[str, Any]] | None = None,
+        default_preset: str | None = None,
     ) -> None:
         """Atomically replace NicePool data from a pandas DataFrame."""
+        dataset = dataframe_to_dataset(
+            dataframe,
+            row_id_column=row_id_column,
+            schema=schema,
+            pre_filter_columns=pre_filter_columns,
+        )
+        if preset_definitions is None:
+            if default_preset is not None:
+                raise ValueError("default_preset requires preset_definitions")
+            self._send("setData", dataset)
+            return
         self._send(
-            "setData",
-            dataframe_to_dataset(
-                dataframe,
-                row_id_column=row_id_column,
-                schema=schema,
-                pre_filter_columns=pre_filter_columns,
-            ),
+            "initializeData",
+            {
+                "dataset": dataset,
+                "presetDefinitions": [dict(item) for item in preset_definitions],
+                "defaultPresetName": default_preset,
+            },
         )
 
     def set_records(
@@ -183,16 +234,28 @@ def set_records(
         row_id_column: str,
         schema: Sequence[Mapping[str, Any]] | None = None,
         pre_filter_columns: Sequence[str] | None = None,
+        preset_definitions: Sequence[Mapping[str, Any]] | None = None,
+        default_preset: str | None = None,
     ) -> None:
         """Atomically replace NicePool data from rectangular records."""
+        dataset = records_to_dataset(
+            records,
+            row_id_column=row_id_column,
+            schema=schema,
+            pre_filter_columns=pre_filter_columns,
+        )
+        if preset_definitions is None:
+            if default_preset is not None:
+                raise ValueError("default_preset requires preset_definitions")
+            self._send("setData", dataset)
+            return
         self._send(
-            "setData",
-            records_to_dataset(
-                records,
-                row_id_column=row_id_column,
-                schema=schema,
-                pre_filter_columns=pre_filter_columns,
-            ),
+            "initializeData",
+            {
+                "dataset": dataset,
+                "presetDefinitions": [dict(item) for item in preset_definitions],
+                "defaultPresetName": default_preset,
+            },
         )
 
     def replace_dataframe(

integrations/nicepool-pyqt5/tests/test_widget.py

@@ -11,12 +11,28 @@
 from nicepool_pyqt5 import NicePoolWidget
 
 
+def test_default_preset_requires_definitions(qtbot) -> None:
+    """Reject a default preset when no definitions were supplied."""
+    widget = NicePoolWidget()
+    qtbot.addWidget(widget)
+    with pytest.raises(ValueError, match="requires preset_definitions"):
+        widget.set_records(
+            [{"id": "a", "x": 1.0}],
+            row_id_column="id",
+            default_preset="Missing",
+        )
+
+
 @pytest.mark.skipif(
     os.environ.get("NICEPOOL_RUN_WEBENGINE_TEST") != "1",
     reason="set NICEPOOL_RUN_WEBENGINE_TEST=1 on a host with a working display/OpenGL context",
 )
 def test_webengine_bridge_round_trip_and_no_selection_echo(qtbot) -> None:
-    widget = NicePoolWidget()
+    widget = NicePoolWidget(
+        theme="light",
+        controls_collapsed=True,
+        preset_editing_visible=False,
+    )
     qtbot.addWidget(widget)
     assert widget.web_view.settings().testAttribute(
         QWebEngineSettings.JavascriptCanAccessClipboard
@@ -39,6 +55,32 @@ def test_webengine_bridge_round_trip_and_no_selection_echo(qtbot) -> None:
             row_id_column="id",
         )
 
+    initial_display: list[object] = []
+    widget.web_view.page().runJavaScript(
+        """
+        (() => {
+          const pool = document.querySelector('nice-pool');
+          const root = pool?.shadowRoot;
+          return {
+            theme: pool?.getTheme(),
+            controlsCollapsed: pool?.getControlsCollapsed(),
+            presetEditingVisible: pool?.getShowPresetEditing(),
+            presetVisible: Boolean(root?.querySelector('.nicepool-preset-bar select')),
+          };
+        })();
+        """,
+        initial_display.append,
+    )
+    qtbot.waitUntil(lambda: len(initial_display) == 1, timeout=5_000)
+    assert initial_display == [
+        {
+            "theme": "light",
+            "controlsCollapsed": True,
+            "presetEditingVisible": False,
+            "presetVisible": True,
+        }
+    ]
+
     qtbot.wait(250)
     widget.set_primary_selection("a")
     state: list[object] = []

packages/nicepool/e2e/nicepool.spec.ts

@@ -63,6 +63,7 @@ test('collapses and restores controls through the public element API', async ({
     (element as HTMLElement & { setControlsCollapsed(collapsed: boolean): void }).setControlsCollapsed(true)
   })
   await expect.poll(() => controls.evaluate((element) => element.getBoundingClientRect().width)).toBe(0)
+  await expect(pool.getByLabel('Preset')).toBeVisible()
   await expect.poll(() => pool.evaluate((element) =>
     (element as HTMLElement & { getControlsCollapsed(): boolean }).getControlsCollapsed(),
   )).toBe(true)