ms-components 0.2.0__tar.gz → 0.3.0__tar.gz

{ms_components-0.2.0 → ms_components-0.3.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: ms_components
-Version: 0.2.0
+Version: 0.3.0
 Summary: PySide6 UI components for MolSuite: smart table, project browser, job monitor, PyMOL dock, steppers.
 Author: Mario S. Valdés-Tresanco, Mario E. Valdés-Tresanco
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/MolSuite/ms_components
+Project-URL: Documentation, https://molsuite.github.io/ms_components/
 Project-URL: Issues, https://github.com/MolSuite/ms_components/issues
 Keywords: pyside6,qt,widgets,molsuite,table,monitor
 Classifier: Development Status :: 4 - Beta
@@ -30,6 +31,10 @@ Dynamic: license-file
 PySide6 UI components for MolSuite: smart table, project browser, job monitor,
 PyMOL dock, steppers and the shared theming (`themes/` + `base.qss`).
 
+[`ms_tutorial`](docs/ms_tutorial.md) provides informative and interactive tours:
+Python binds existing widgets/signals, while content can be defined in Python or
+TOML. Try `PYTHONPATH=src python examples/tutorial_demo.py` from a source checkout.
+
 Part of the [MolSuite](https://molsuite.github.io/) stack. Built on top of
 [`ms_flow`](https://github.com/MolSuite/ms_flow).
 
@@ -42,6 +47,11 @@ PyPI (`>=3.2.0a0`):
 pip install ms_components
 ```
 
+## Documentation
+
+<https://molsuite.github.io/ms_components/>: a guide to each component, examples,
+and the API reference.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Third-party icon/asset licenses live in `licenses/`.

{ms_components-0.2.0 → ms_components-0.3.0}/README.md

@@ -3,6 +3,10 @@
 PySide6 UI components for MolSuite: smart table, project browser, job monitor,
 PyMOL dock, steppers and the shared theming (`themes/` + `base.qss`).
 
+[`ms_tutorial`](docs/ms_tutorial.md) provides informative and interactive tours:
+Python binds existing widgets/signals, while content can be defined in Python or
+TOML. Try `PYTHONPATH=src python examples/tutorial_demo.py` from a source checkout.
+
 Part of the [MolSuite](https://molsuite.github.io/) stack. Built on top of
 [`ms_flow`](https://github.com/MolSuite/ms_flow).
 
@@ -15,6 +19,11 @@ PyPI (`>=3.2.0a0`):
 pip install ms_components
 ```
 
+## Documentation
+
+<https://molsuite.github.io/ms_components/>: a guide to each component, examples,
+and the API reference.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Third-party icon/asset licenses live in `licenses/`.

{ms_components-0.2.0 → ms_components-0.3.0}/docs/api_reference.md

@@ -11,6 +11,10 @@ Names beginning with an underscore are implementation details.
 
 ::: ms_components.ms_monitor
 
+## Hosts and executors
+
+::: ms_components.ms_executors
+
 ## Projects
 
 ::: ms_components.ms_projects
@@ -27,6 +31,10 @@ Names beginning with an underscore are implementation details.
 
 ::: ms_components.ms_stepper
 
+## Guided tutorials
+
+::: ms_components.ms_tutorial
+
 ## Tool panel
 
 ::: ms_components.tool_panel

{ms_components-0.2.0 → ms_components-0.3.0}/docs/examples.md

@@ -88,18 +88,25 @@ app.exec()
 
 ## Job monitor for a running job
 
-Attach the monitor to a `MolSuite` runtime and watch a job advance. The worker
-must live in an importable module:
+Attach the monitor to a `Workspace` and watch a job advance. The task and the
+job must live in an importable module:
 
 ```python
 # workers.py
 import time
 
+from ms_flow import file_sink, job, task
 
-def slow_square(payload: dict) -> dict:
+
+@task()
+def slow_square(value: int) -> dict:
     time.sleep(0.1)
-    value = int(payload["value"])
     return {"value": value, "square": value * value}
+
+
+@job(task=slow_square, output=file_sink("squares.json"))
+def slow_squares(params, project):
+    yield from range(100)
 ```
 
 ```python
@@ -107,26 +114,21 @@ from PySide6.QtWidgets import QApplication
 
 from ms_components.ms_monitor import MolSuiteMonitorBridge, MolSuiteMonitorWidget
 from ms_components.theme import apply_theme
-from ms_flow.api import MolSuite
-from workers import slow_square
+from ms_flow import Workspace
+from workers import slow_squares
 
 app = QApplication([])
 apply_theme("auto", app)
 
-ms = MolSuite(app_id="monitor-demo")
+ms = Workspace(app_id="monitor-demo")
 ms.create_or_open_project(name="monitor-demo", folder="./monitor-demo", activate=True)
 
-bridge = MolSuiteMonitorBridge(molsuite=ms, poll_ms=500)
+bridge = MolSuiteMonitorBridge(workspace=ms, poll_ms=500)
 monitor = MolSuiteMonitorWidget(bridge=bridge)
 bridge.start()
-app.aboutToQuit.connect(bridge.stop)   # stop polling before the runtime shuts down
-
-ms.run(
-    name="slow-squares",
-    input=[{"value": value} for value in range(100)],
-    process=slow_square,
-    executor="thread",
-)
+app.aboutToQuit.connect(bridge.stop)   # stop polling before the workspace shuts down
+
+ms.submit(slow_squares, executor="thread")
 
 monitor.resize(1100, 650)
 monitor.show()

{ms_components-0.2.0 → ms_components-0.3.0}/docs/index.md

@@ -19,11 +19,13 @@ pip install ms_components
 | Module | Responsibility |
 | --- | --- |
 | `ms_components.ms_table` | Declarative, paginated table over SQLModel |
-| `ms_components.ms_monitor` | Job, executor, and event monitor for a MolSuite runtime |
+| `ms_components.ms_monitor` | Job monitor for an `ms_flow` workspace: cancel, resume, move |
+| `ms_components.ms_executors` | Hosts and executors: Settings pages and the panel that starts them |
 | `ms_components.ms_projects` | Project browser and project menu |
 | `ms_components.ms_settings` | Typed editor for application settings |
 | `ms_components.ms_pymol` | PyMOL dock and control bar |
 | `ms_components.ms_stepper` | Step-by-step wizard widget |
+| [`ms_components.ms_tutorial`](ms_tutorial.md) | Informative and interactive tours, with Python bindings and optional TOML content |
 | `ms_components.tool_panel` | Configure-then-run frame shared by tools |
 | `ms_components.step_dialog` | Dialog that runs provisioning steps off the GUI thread |
 | `ms_components.theme` | Themes, palette roles, and fonts |

ms_components-0.3.0/docs/ms_tutorial.md

@@ -0,0 +1,160 @@
+# Guided tutorials
+
+`ms_components.ms_tutorial` supplies informative and interactive tours for any
+Qt Widgets application. It imports no application, project catalog, or orchestrator.
+No existing application slot needs a tutorial call.
+
+## Python bindings, optional TOML content
+
+Use **Python for widget/signal bindings**. They are live Qt objects and may need
+application logic to reveal a panel or verify a result. Use either **Python or
+TOML for tutorial content**. Both produce the same `Tutorial` model.
+
+TOML is useful when editing explanations or translating a tour without touching
+bindings. It uses Python 3.12's standard-library `tomllib`, so no YAML dependency
+is needed. Files contain symbolic IDs, never Python expressions, imports, widget
+attribute paths, or executable callbacks. Unknown keys and invalid definitions
+raise `ValueError`; TOML syntax and filesystem errors propagate to the caller.
+
+```toml
+id = "first-import"
+title = "Import your data"
+
+[[steps]]
+id = "overview"
+target = "input.panel"
+title = "Input panel"
+text = "Configure your input here, then review the resulting records."
+
+[[steps]]
+id = "import"
+target = "input.run"
+title = "Import the example"
+text = "Run the import. This step advances only after the expected job succeeds."
+advance_on = "input.imported"
+```
+
+```python
+from ms_components.ms_tutorial import (
+    TutorialController, TutorialEvent, TutorialTarget, load_tutorial,
+)
+
+window.tutorials = TutorialController(
+    targets={
+        "input.panel": TutorialTarget(lambda: window.input_panel,
+                                      prepare=window.show_input_panel),
+        "input.run": TutorialTarget(lambda: window.input_panel.run_button),
+    },
+    events={
+        "input.imported": TutorialEvent(
+            window.monitor_bridge.job_finished,
+            accept=lambda job_id, status: job_id == expected_job_id() and status == "completed",
+        ),
+    },
+    parent=window,
+)
+window.tutorials.start(load_tutorial("first_import.toml"))
+```
+
+Names such as `input.panel` are plain dictionary keys. The application supplies
+their meaning; `ms_tutorial` knows nothing about AMDockVS or Molsuite's job statuses.
+The example's `expected_job_id()` and `show_input_panel` are application-provided
+functions, not methods required by this component. Real operations still go
+through the application's existing APIs.
+
+For a small tour, define the content in Python instead:
+
+```python
+from ms_components.ms_tutorial import Tutorial, TutorialStep
+
+overview = Tutorial("overview", "Interface overview", (
+    TutorialStep("input", "input.panel", "Input", "Configure your data here."),
+    TutorialStep("run", "input.run", "Run", "This submits the configured operation."),
+))
+window.tutorials.start(overview)
+```
+
+## Informative and interactive steps
+
+- Without `advance_on`, a step is **informative**: Next/Back control the tour.
+  The spotlight remains visible but blocks clicks and keyboard actions on the host
+  window. The component never clicks controls or executes application actions.
+- With `advance_on`, a step is **interactive**: the spotlight admits real input to
+  its target, and Next stays disabled until the named event is accepted. Completion
+  advances automatically. Other application slots retain their existing connections.
+- `TutorialEvent.accept` receives the signal's arguments. Use it to match the job,
+  project, selection, or success state that the step actually expects. A request or
+  button click does not in general prove that an asynchronous operation succeeded.
+- Events are observed only while their step is active. Already completed steps may
+  be revisited with Back and left with Next. A new run resets tutorial completion,
+  without resetting application data. Multiple queued copies of an old event do
+  not complete a later step, even if both steps use the same signal.
+
+`TutorialEvent.signal` also accepts a zero-argument resolver for signals belonging
+to dialogs or controls that are recreated. It is resolved when entering the step.
+
+The controller queues event validation to the UI thread, including signals emitted
+by background workers. Validators must be fast and must not mutate the UI or start
+another tutorial. Signal argument types must be supported by Qt's queued connections
+(Python objects and the ordinary Qt types are suitable).
+
+## Dynamic panels and multiple windows
+
+`TutorialTarget.widget` is a `QWidget` or a zero-argument resolver returning one.
+Optional `TutorialTarget.rect` resolves a rectangle in that widget's coordinates,
+for example `rect=lambda: menu_bar.actionGeometry(help_action)` to highlight just
+the Help menu item. It is recomputed as the layout changes; the widget is unchanged.
+The controller resolves it again as the UI changes. `prepare`, when provided,
+runs once on entering the step and should only reveal the needed UI, through its
+existing public navigation API. Do not submit jobs or change scientific data there.
+Navigation callbacks must also account for Back, for example hiding a modal dialog
+when returning to its parent window; the controller does not close application dialogs.
+
+An overlay belongs to the target's top-level window. On the next step the controller
+can move to another window, a floating dock, or a modal dialog, without application
+slots knowing about it. It follows resizing, moving, and ancestor viewport clipping.
+Use `prepare` to scroll offscreen controls into view; the component does not scroll
+the application automatically. Hidden targets temporarily hide the overlay; an
+initial hidden target without an existing overlay fails with a diagnostic. Missing
+or deleted targets and callback failures stop the tour and emit `failed`.
+
+Lifecycle signals:
+
+| Signal | Arguments |
+| --- | --- |
+| `started` | tutorial ID |
+| `step_changed` | step ID, zero-based index |
+| `finished` | tutorial ID |
+| `cancelled` | tutorial ID |
+| `failed` | tutorial ID, diagnostic message |
+
+Call `start(tutorial)`, `next()`, `back()`, or `stop()` on the UI thread. Keep the
+controller alive, normally as an attribute of the main window, and give it a Qt
+parent. Escape/Exit cancel; closing the current host also cancels. Stopping a tour
+removes its signal connection and event filter and restores the earlier focus
+when that widget is still visible. Switching tutorials cancels the previous one.
+Invalid target/event registry keys are rejected before cancelling an active tour.
+The component never creates `QApplication` or changes the application's theme.
+
+## Demo and checks
+
+From the source checkout, in `MSDD_312`:
+
+```bash
+PYTHONPATH=src python examples/tutorial_demo.py
+QT_QPA_PLATFORM=offscreen PYTHONPATH=src python -m pytest -q tests/test_tutorial.py
+```
+
+The demo has two buttons: an informative tour defined in Python, and a mixed
+interactive/informative tour loaded from `examples/tutorial_demo.toml`. Its
+application slot has no tutorial calls. Add the sibling `ms_flow/src` and
+`ms_env/src` to `PYTHONPATH` if those packages are not installed in the environment.
+
+## Scope
+
+This component guides an existing UI within one process. Continuing in a new process,
+saving progress, translation catalogs, and the application's Help menu remain the
+application's responsibility. A spotlight over native platform dialogs or embedded
+OpenGL renderers is platform-dependent; use a Qt Widgets practice view if needed.
+On a host almost entirely occupied by the target, the callout may overlap part of
+the spotlight. Expose a smaller target in the binding to leave room for the callout.

{ms_components-0.2.0 → ms_components-0.3.0}/docs/usage.md

@@ -135,28 +135,46 @@ action bar state.
 
 ## Job monitor
 
-The bridge polls a `MolSuite` runtime and translates its snapshots into Qt
+The bridge polls an `ms_flow` `Workspace` and translates its snapshots into Qt
 signals and models; the widget only presents them. You can embed the whole
 monitor or consume only the bridge signals.
 
 ```python
-from ms_flow.api import MolSuite
+from ms_flow import Workspace
 from ms_components.ms_monitor import MolSuiteMonitorBridge, MolSuiteMonitorWidget
 
-ms = MolSuite(app_id="demo")
+ms = Workspace(app_id="demo")
 ms.create_or_open_project(name="demo", folder="./demo-project", activate=True)
 
-bridge = MolSuiteMonitorBridge(molsuite=ms, poll_ms=500)
+bridge = MolSuiteMonitorBridge(workspace=ms, poll_ms=500)
 monitor = MolSuiteMonitorWidget(bridge=bridge)
 bridge.bridge_error.connect(print)
-bridge.job_finished.connect(lambda *args: print("job finished", args))
+bridge.job_finished.connect(lambda job_id, status: print("job finished", job_id, status))
 bridge.start()
 monitor.show()
 ```
 
 When closing, call `bridge.stop()` first and `ms.shutdown()` afterwards. The
-supported operator actions are refresh, cancel, and — when the job keeps a
-re-buildable source — resubmit.
+operator can cancel jobs, **Resume** a job that was interrupted or canceled,
+and **Move** a job to another active executor. An application with its own
+rules of where a job may go passes `resume(job_id, executor)` and
+`destinations(job_id)` to the bridge.
+
+## Where jobs run
+
+`ms_components.ms_executors` edits the hosts and executors kept by `ms_flow`.
+Both widgets go through the `Workspace`, which refuses what cannot be done now
+(changing an executor while it is active, for example) and says why.
+
+```python
+from ms_components.ms_executors import ExecutorsPanel, KeptPage
+
+hosts = KeptPage(ms, "hosts")            # a Settings page: the machines
+executors = KeptPage(ms, "executors")    # a Settings page: who runs jobs on them
+panel = ExecutorsPanel(ms)               # the quick window that starts and stops executors
+panel.settings_requested.connect(lambda: print("open the Settings page"))
+panel.show()
+```
 
 ## Projects, settings, and PyMOL
 
@@ -164,7 +182,7 @@ re-buildable source — resubmit.
   and create projects through the public `ms_flow` project catalog. Connect
   `project_requested` to open the chosen project; do not read the MolSuite
   databases from the UI.
-- `AppSettingsDialog(runtime=...)` edits the layered configuration of a
-  MolSuite runtime.
+- `AppSettingsDialog(runtime=...)` edits the layered configuration of an
+  application.
 - `PymolDockWidget(title, manager)` needs the PyMOL `cmd`/manager object of the
   application's PyMOL integration.

ms_components-0.3.0/examples/tutorial_demo.py

@@ -0,0 +1,74 @@
+"""Run in MSDD_312: PYTHONPATH=src python examples/tutorial_demo.py."""
+from pathlib import Path
+import sys
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QApplication, QDialog, QLabel, QPushButton, QVBoxLayout, QWidget
+
+from ms_components.ms_tutorial import (
+    Tutorial, TutorialController, TutorialEvent, TutorialStep, TutorialTarget, load_tutorial,
+)
+from ms_components.theme import apply_theme
+
+
+class DemoWindow(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.setWindowTitle("ms_tutorial · Python + TOML")
+        self.resize(900, 640)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(28, 28, 28, 28)
+        layout.setSpacing(18)
+        layout.addWidget(QLabel("Tutoriales independientes de la aplicación"))
+        self.load_button = QPushButton("Cargar ejemplo")
+        self.status = QLabel("Sin datos de muestra")
+        layout.addWidget(self.load_button, alignment=Qt.AlignmentFlag.AlignLeft)
+        layout.addWidget(self.status)
+        layout.addStretch()
+        self.info_button = QPushButton("Recorrido informativo · Python")
+        self.interactive_button = QPushButton("Recorrido interactivo · TOML")
+        layout.addWidget(self.info_button)
+        layout.addWidget(self.interactive_button)
+        self.details = QDialog(self)
+        self.details.setWindowTitle("Detalles")
+        self.details.resize(600, 420)
+        details_layout = QVBoxLayout(self.details)
+        self.details_text = QLabel("Este panel pertenece a otro diálogo.")
+        details_layout.addWidget(self.details_text, alignment=Qt.AlignmentFlag.AlignTop)
+        details_layout.addStretch()
+
+        # Existing application behavior: no tutorial calls in this slot.
+        self.load_button.clicked.connect(self.load_sample)
+        self.tutorials = TutorialController(
+            targets={
+                "input.load": TutorialTarget(self.load_button, prepare=self.details.hide),
+                "input.status": TutorialTarget(self.status, prepare=self.details.hide),
+                "details.text": TutorialTarget(lambda: self.details_text, prepare=self.details.show),
+            },
+            events={"input.loaded": TutorialEvent(self.load_button.clicked)},
+            parent=self,
+        )
+        self.informative = Tutorial("overview", "Conoce la interfaz", (
+            TutorialStep("input", "input.load", "Entrada", "Este botón carga los datos de muestra. "
+                         "En este recorrido solo lo explicamos: no se puede activar."),
+            TutorialStep("status", "input.status", "Estado", "Aquí aparece el estado de los datos. "
+                         "No ha hecho falta ejecutar ninguna acción para terminar el recorrido."),
+        ))
+        self.interactive = load_tutorial(Path(__file__).with_suffix(".toml"))
+        self.info_button.clicked.connect(lambda: self.tutorials.start(self.informative))
+        self.interactive_button.clicked.connect(lambda: self.tutorials.start(self.interactive))
+
+    def load_sample(self):
+        self.status.setText("Ejemplo cargado")
+
+
+def main():
+    app = QApplication(sys.argv)
+    apply_theme("auto", app)
+    window = DemoWindow()
+    window.show()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ms_components-0.3.0/examples/tutorial_demo.toml

@@ -0,0 +1,21 @@
+id = "interactive-demo"
+title = "Tutorial interactivo"
+
+[[steps]]
+id = "load"
+target = "input.load"
+title = "Carga el ejemplo"
+text = "Pulsa Cargar ejemplo. La guía escucha la señal existente desde fuera del componente."
+advance_on = "input.loaded"
+
+[[steps]]
+id = "details"
+target = "details.text"
+title = "Otra ventana"
+text = "El controlador ha abierto un diálogo mediante una función de navegación. Este paso es informativo y avanza con Next."
+
+[[steps]]
+id = "summary"
+target = "input.status"
+title = "Terminado"
+text = "La aplicación conserva sus propios slots. El tutorial solo añade sus conexiones mientras están activas."

{ms_components-0.2.0 → ms_components-0.3.0}/pyproject.toml

@@ -39,6 +39,7 @@ dev = ["pytest>=7.0"]
 
 [project.urls]
 Homepage = "https://github.com/MolSuite/ms_components"
+Documentation = "https://molsuite.github.io/ms_components/"
 Issues = "https://github.com/MolSuite/ms_components/issues"
 
 # The release tag is the only version there is: nothing to bump by hand, and

{ms_components-0.2.0 → ms_components-0.3.0}/src/ms_components/base.qss

@@ -4,6 +4,17 @@ QMainWindow::separator {
     height: 1px;
 }
 
+QFrame#TutorialCallout {
+    background: palette(window);
+    border: 1px solid palette(mid);
+    border-radius: 8px;
+}
+
+QTextBrowser#TutorialText {
+    background: transparent;
+    border: none;
+}
+
 QToolBar {
     border: none;
     padding: 3px;
@@ -130,6 +141,19 @@ QPushButton:default {
     border-color: palette(highlight);
 }
 
+/* A split button (QToolButton with a menu arrow) is an action button, not a toolbar icon:
+   framed like QPushButton, the arrow in its own segment. */
+QToolButton[popupMode="MenuButtonPopup"] {
+    border: 1px solid palette(mid);
+    padding: 5px 14px;
+    padding-right: 24px;
+}
+
+QToolButton[popupMode="MenuButtonPopup"]::menu-button {
+    border-left: 1px solid palette(mid);
+    width: 18px;
+}
+
 /* Card = content surface. Nav trees/lists stay flat unless opted in. */
 QTableView,
 QTreeView[card="true"],