nova-trame 0.13.1__py3-none-any.whl

nova/trame/view/components/visualization/interactive_2d_plot.py

@@ -0,0 +1,85 @@
+"""View implementation for Interactive2DPlot."""
+
+from typing import Any, Optional
+
+from altair import Chart
+from trame.widgets import client, vega
+
+
+class Interactive2DPlot(vega.Figure):
+    """Creates an interactive 2D plot in Trame using Vega.
+
+    Trame provides two primary mechanisms for composing 2D plots: `Plotly <https://github.com/Kitware/trame-plotly>`_
+    and `Vega-Lite/Altair <https://github.com/Kitware/trame-vega>`_. If you only need static plots or basic browser
+    event handling, then please use these libraries directly.
+
+    If you need to capture complex front-end interactions, then you can
+    use our provided Interactive2DPlot widget that is based on Vega-Lite. This uses the same API as Trame's vega.Figure,
+    except that it will automatically sync Vega's signal states as the user interacts with the plot.
+
+    The following allows the user to select a region of the plot and tracks the selected region in Python:
+
+    .. literalinclude:: ../tests/test_interactive_2d_plot.py
+        :start-after: setup 2d plot
+        :end-before: setup 2d plot complete
+        :dedent:
+    """
+
+    def __init__(self, figure: Optional[Chart] = None, **kwargs: Any) -> None:
+        """Constructor for Interactive2DPlot.
+
+        Parameters
+        ----------
+        figure : `altair.Chart <https://altair-viz.github.io/user_guide/generated/toplevel/altair.Chart.html#altair.Chart>`_
+            Altair chart object
+        kwargs
+            Arguments to be passed to `AbstractElement <https://trame.readthedocs.io/en/latest/core.widget.html#trame_client.widgets.core.AbstractElement>`_
+
+        Returns
+        -------
+        None
+        """
+        self._initialized = False
+
+        super().__init__(figure=figure, **kwargs)
+        self.ref = f"nova__vega_{self._id}"
+        self.server.state[self.ref] = {}
+        self._start_update_handlers = client.JSEval(
+            exec=(
+                "async () => {"
+                f" let ref = window.trame.refs['{self.ref}'];"
+                "  await ref.mountVis();"  # wait for the new  visualization to be rendered in the front-end
+                "  if (ref.viz === undefined) { return; }"  # If the component is not mounted, do nothing
+                "  for (const [key, value] of Object.entries(ref.viz.view._signals)) {"
+                "    if (key === 'unit') { continue; }"  # this causes a JSError for some reason if not skipped
+                "    ref.viz.view.addSignalListener(key, (name, value) => {"
+                f"     window.trame.state.state['{self.ref}'][name] = value;"  # sync front-end state
+                f"     flushState('{self.ref}');"  # sync back-end state
+                "    })"
+                "  }"
+                "}"
+            )
+        ).exec
+
+        client.ClientTriggers(mounted=self.update)
+
+    def get_signal_state(self, name: str) -> Any:
+        """Retrieves a Vega signal's state by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the signal to retrieve.
+
+        Returns
+        -------
+        typing.Any
+            The current value of the Vega signal.
+        """
+        return self.server.state[self.ref].get(name, None)
+
+    def update(self, figure: Optional[Chart] = None, **kwargs: Any) -> None:
+        super().update(figure=figure, **kwargs)
+
+        if hasattr(self, "_start_update_handlers"):
+            self._start_update_handlers()

nova/trame/view/layouts/__init__.py

@@ -0,0 +1,5 @@
+from .grid import GridLayout
+from .hbox import HBoxLayout
+from .vbox import VBoxLayout
+
+__all__ = ["GridLayout", "HBoxLayout", "VBoxLayout"]

nova/trame/view/layouts/grid.py

@@ -0,0 +1,148 @@
+"""Trame implementation of the GridLayout class."""
+
+from typing import Any, Optional, Union
+
+from trame.widgets import html
+from trame_client.widgets.core import AbstractElement
+
+
+class GridLayout(html.Div):
+    """Creates a grid with a specified number of columns."""
+
+    def __init__(
+        self,
+        columns: int = 1,
+        height: Optional[Union[int, str]] = None,
+        width: Optional[Union[int, str]] = None,
+        halign: Optional[str] = None,
+        valign: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Constructor for GridLayout.
+
+        Parameters
+        ----------
+        columns : int
+            The number of columns in the grid.
+        height : optional[int | str]
+            The height of this grid. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        width : optional[int | str]
+            The width of this grid. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        halign : optional[str]
+            The horizontal alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>`__ for available options.
+        valign : optional[str]
+            The vertical alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>`__ for available options.
+        kwargs : Any
+            Additional keyword arguments to pass to html.Div.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        Basic usage:
+
+        .. literalinclude:: ../tests/gallery/app.py
+            :start-after: setup grid
+            :end-before: setup grid complete
+            :dedent:
+
+        Building a custom left-middle-right layout:
+
+        .. literalinclude:: ../tests/test_layouts.py
+            :start-after: setup complex layout example
+            :end-before: setup complex layout example complete
+            :dedent:
+        """
+        classes = kwargs.pop("classes", [])
+        if isinstance(classes, list):
+            classes = " ".join(classes)
+        classes += " d-grid"
+
+        style = self.get_root_styles(columns, height, width, halign, valign) | kwargs.pop("style", {})
+
+        super().__init__(classes=classes, style=style, **kwargs)
+
+    def get_root_styles(
+        self,
+        columns: int,
+        height: Optional[Union[int, str]],
+        width: Optional[Union[int, str]],
+        halign: Optional[str],
+        valign: Optional[str],
+    ) -> dict[str, str]:
+        height = f"{height}px" if isinstance(height, int) else height
+        width = f"{width}px" if isinstance(width, int) else width
+
+        styles = {
+            "grid-template-columns": f"repeat({columns}, 1fr)",
+        }
+
+        if height:
+            styles["height"] = height
+        if width:
+            styles["width"] = width
+        if halign:
+            styles["justify-items"] = halign
+        if valign:
+            styles["align-items"] = valign
+
+        return styles
+
+    def get_row_style(self, row_span: int) -> str:
+        return f"grid-row-end: span {row_span};"
+
+    def get_column_style(self, column_span: int) -> str:
+        return f"grid-column-end: span {column_span};"
+
+    def add_child(self, child: Union[AbstractElement, str]) -> AbstractElement:
+        """Add a child to the grid.
+
+        Do not call this directly. Instead, use Trame's `with` syntax, which will call this method internally. This
+        method is documented here as a reference for the span parameters.
+
+        Parameters
+        ----------
+        child : `AbstractElement \
+            <https://trame.readthedocs.io/en/latest/core.widget.html#trame_client.widgets.core.AbstractElement>`_ | str
+            The child to add to the grid.
+        row_span : int
+            The number of rows this child should span.
+        column_span : int
+            The number of columns this child should span.
+
+        Returns
+        -------
+        None
+
+        Example
+        -------
+        .. literalinclude:: ../tests/gallery/app.py
+            :start-after: grid row and column span example
+            :end-before: grid row and column span example end
+            :dedent:
+        """
+        if isinstance(child, str):
+            child = html.Div(child)
+
+        row_span = 1
+        column_span = 1
+        if "row_span" in child._py_attr:
+            row_span = child._py_attr["row_span"]
+        if "column_span" in child._py_attr:
+            column_span = child._py_attr["column_span"]
+
+        if "style" not in child._py_attr or child.style is None:
+            child.style = ""
+        child.style += f"; {self.get_row_style(row_span)} {self.get_column_style(column_span)}"
+
+        if "classes" not in child._py_attr or child.classes is None:
+            child.classes = ""
+        child.classes += " d-grid-item"
+
+        super().add_child(child)

nova/trame/view/layouts/hbox.py

@@ -0,0 +1,79 @@
+"""Trame implementation of the HBoxLayout class."""
+
+from typing import Any, Optional, Union
+
+from trame.widgets import html
+
+
+class HBoxLayout(html.Div):
+    """Creates an element that horizontally stacks its children."""
+
+    def __init__(
+        self,
+        height: Optional[Union[int, str]] = None,
+        width: Optional[Union[int, str]] = None,
+        halign: Optional[str] = None,
+        valign: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Constructor for HBoxLayout.
+
+        Parameters
+        ----------
+        height : optional[int | str]
+            The height of this box. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        width : optional[int | str]
+            The width of this box. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        halign : optional[str]
+            The horizontal alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>`__ for available options.
+        valign : optional[str]
+            The vertical alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>`__ for available options.
+        kwargs : Any
+            Additional keyword arguments to pass to html.Div.
+
+        Returns
+        -------
+        None
+
+        Example
+        -------
+        .. literalinclude:: ../tests/gallery/app.py
+            :start-after: setup hbox
+            :end-before: setup hbox complete
+            :dedent:
+        """
+        classes = kwargs.pop("classes", [])
+        if isinstance(classes, list):
+            classes = " ".join(classes)
+        classes += " d-flex flex-row"
+
+        style = self.get_root_styles(height, width, halign, valign) | kwargs.pop("style", {})
+
+        super().__init__(classes=classes, style=style, **kwargs)
+
+    def get_root_styles(
+        self,
+        height: Optional[Union[int, str]],
+        width: Optional[Union[int, str]],
+        halign: Optional[str],
+        valign: Optional[str],
+    ) -> dict:
+        height = f"{height}px" if isinstance(height, int) else height
+        width = f"{width}px" if isinstance(width, int) else width
+
+        styles = {}
+
+        if height:
+            styles["height"] = height
+        if width:
+            styles["width"] = width
+        if halign:
+            styles["justify-content"] = halign
+        if valign:
+            styles["align-items"] = valign
+
+        return styles

nova/trame/view/layouts/vbox.py

@@ -0,0 +1,79 @@
+"""Trame implementation of the VBoxLayout class."""
+
+from typing import Any, Optional, Union
+
+from trame.widgets import html
+
+
+class VBoxLayout(html.Div):
+    """Creates an element that vertically stacks its children."""
+
+    def __init__(
+        self,
+        height: Optional[Union[int, str]] = None,
+        width: Optional[Union[int, str]] = None,
+        halign: Optional[str] = None,
+        valign: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Constructor for VBoxLayout.
+
+        Parameters
+        ----------
+        height : optional[int | str]
+            The height of this box. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        width : optional[int | str]
+            The width of this box. If an integer is provided, it is interpreted as pixels. If a string is provided,
+            the string is treated as a CSS value.
+        halign : optional[str]
+            The horizontal alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>`__ for available options.
+        valign : optional[str]
+            The vertical alignment of items in the grid. See `MDN
+            <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>`__ for available options.
+        kwargs : Any
+            Additional keyword arguments to pass to html.Div.
+
+        Returns
+        -------
+        None
+
+        Example
+        -------
+        .. literalinclude:: ../tests/gallery/app.py
+            :start-after: setup vbox
+            :end-before: setup vbox complete
+            :dedent:
+        """
+        classes = kwargs.pop("classes", [])
+        if isinstance(classes, list):
+            classes = " ".join(classes)
+        classes += " d-flex flex-column"
+
+        style = self.get_root_styles(height, width, halign, valign) | kwargs.pop("style", {})
+
+        super().__init__(classes=classes, style=style, **kwargs)
+
+    def get_root_styles(
+        self,
+        height: Optional[Union[int, str]],
+        width: Optional[Union[int, str]],
+        halign: Optional[str],
+        valign: Optional[str],
+    ) -> dict:
+        height = f"{height}px" if isinstance(height, int) else height
+        width = f"{width}px" if isinstance(width, int) else width
+
+        styles = {}
+
+        if height:
+            styles["height"] = height
+        if width:
+            styles["width"] = width
+        if halign:
+            styles["align-items"] = halign
+        if valign:
+            styles["justify-content"] = valign
+
+        return styles

nova/trame/view/theme/__init__.py

@@ -0,0 +1,3 @@
+from .theme import ThemedApp
+
+__all__ = ["ThemedApp"]

nova/trame/view/theme/assets/core_style.scss

@@ -0,0 +1,30 @@
+html {
+    overflow-y: auto;
+}
+
+.d-grid {
+    display: grid;
+    gap: 0.25em;
+    grid-auto-rows: auto;
+}
+
+@media only screen and (max-width: 959px) {
+    .d-grid {
+        grid-template-columns: repeat(1, 1fr) !important;
+    }
+
+    .d-grid-item {
+        grid-column: 1 / 1 !important;
+    }
+}
+
+/* Global font sizes can't be set through the Vuetify configuration. */
+.v-theme--CompactTheme {
+    font-size: 0.85rem;
+
+    .v-card-title,
+    .v-list-item-title,
+    .v-toolbar-title {
+        font-size: 1rem;
+    }
+}

nova/trame/view/theme/assets/vuetify_config.json

@@ -0,0 +1,180 @@
+{
+    "defaults": {
+        "global": {
+            "hideDetails": "auto",
+            "hideSpinButtons": true,
+            "persistentPlaceholder": true
+        },
+        "VAlert": {
+            "color": "secondary"
+        },
+        "VAppBar": {
+            "color": "primary",
+            "VBtn": {
+                "color": false
+            }
+        },
+        "VBadge": {
+            "color": "secondary"
+        },
+        "VBtn": {
+            "color": "primary"
+        },
+        "VBtnToggle": {
+            "color": "primary",
+            "VBtn": {
+                "class": "border-primary border-sm"
+            }
+        },
+        "VCard": {
+            "VCardSubtitle": {
+                "style": {
+                    "white-space": "normal"
+                }
+            },
+            "VCardTitle": {
+                "style": {
+                    "line-height": 1.2,
+                    "white-space": "normal"
+                }
+            }
+        },
+        "VCardSubtitle": {
+            "opacity": 0.8
+        },
+        "VCheckbox": {
+            "color": "primary"
+        },
+        "VChip": {
+            "color": "primary"
+        },
+        "VDivider": {
+            "color": "primary"
+        },
+        "VExpansionPanels": {
+            "color": "primary"
+        },
+        "VFileInput": {
+            "color": "primary",
+            "prependIcon": false
+        },
+        "VLabel": {
+            "style": {
+                "opacity": 1.0
+            }
+        },
+        "VList": {
+            "VListItemAction": {
+                "VBtn": {
+                    "class": "ml-2"
+                },
+                "VProgressCircular": {
+                    "class": "ml-2"
+                }
+            }
+        },
+        "VListItem": {
+            "VBtn": {
+                "color": "secondary"
+            }
+        },
+        "VListItemSubtitle": {
+            "opacity": 0.8
+        },
+        "VProgressCircular": {
+            "color": "secondary"
+        },
+        "VProgressLinear": {
+            "color": "secondary"
+        },
+        "VRadioGroup": {
+            "color": "primary"
+        },
+        "VSelect": {
+            "color": "primary"
+        },
+        "VSlider": {
+            "color": "primary"
+        },
+        "VSnackbar": {
+            "color": "primary",
+            "VBtn": {
+                "color": false
+            }
+        },
+        "VSwitch": {
+            "color": "primary"
+        },
+        "VTextarea": {
+            "color": "primary"
+        },
+        "VTextField": {
+            "color": "primary"
+        },
+        "VWindowItem": {
+            "reverseTransition": "fade-transition",
+            "transition": "fade-transition"
+        }
+    },
+    "theme": {
+        "defaultTheme": "ModernTheme",
+        "themes": {
+            "ModernTheme": {
+                "colors": {
+                    "background": "#f0f0f0",
+                    "primary": "#007833",
+                    "secondary": "#f48e5c"
+                },
+                "defaults": {
+                    "VCard": {
+                        "class": "pa-4",
+                        "VCard": {
+                            "class": "border-primary border-sm pa-4",
+                            "style": {
+                                "background-color": "rgba(var(--v-theme-primary), 0.1)"
+                            }
+                        },
+                        "VListItem": {
+                            "class": "border-primary border-sm",
+                            "style": {
+                                "background-color": "rgba(var(--v-theme-primary), 0.1)"
+                            }
+                        }
+                    }
+                },
+                "title": "Modern",
+                "value": "ModernTheme"
+            },
+            "CompactTheme": {
+                "colors": {
+                    "background": "#f0f0f0",
+                    "primary": "#007833",
+                    "secondary": "#f48e5c"
+                },
+                "defaults": {
+                    "global": {
+                        "density": "compact"
+                    },
+                    "VBadge": {
+                        "dot": true
+                    },
+                    "VBtn": {
+                        "density": "default"
+                    },
+                    "VTextField": {
+                        "VBtn": {
+                            "size": "small"
+                        }
+                    }
+                },
+                "title": "Compact",
+                "value": "CompactTheme"
+            }
+        },
+        "variations": {
+            "colors": ["primary", "secondary", "accent"],
+            "darken": 5,
+            "lighten": 5
+        }
+    }
+}