pyglove 0.4.5.dev20240319__py3-none-any.whl → 0.4.5.dev202501132210__py3-none-any.whl

pyglove/core/views/html/controls/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2024 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Common HTML controls."""
+
+# pylint: disable=g-importing-member
+# pylint: disable=g-bad-import-order
+
+from pyglove.core.views.html.controls.base import HtmlControl
+
+
+from pyglove.core.views.html.controls.label import Label
+from pyglove.core.views.html.controls.label import LabelGroup
+from pyglove.core.views.html.controls.label import Badge
+
+from pyglove.core.views.html.controls.tooltip import Tooltip
+
+from pyglove.core.views.html.controls.tab import Tab
+from pyglove.core.views.html.controls.tab import TabControl
+
+from pyglove.core.views.html.controls.progress_bar import ProgressBar
+from pyglove.core.views.html.controls.progress_bar import SubProgress
+
+# pylint: enable=g-bad-import-order
+# pylint: enable=g-importing-member

pyglove/core/views/html/controls/base.py

@@ -0,0 +1,275 @@
+# Copyright 2024 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Base for HTML controls."""
+
+import abc
+import contextlib
+import inspect
+import sys
+from typing import Annotated, Any, Dict, Iterator, List, Optional, Union
+
+from pyglove.core import utils
+from pyglove.core.symbolic import object as pg_object
+from pyglove.core.views.html import base
+
+Html = base.Html
+
+
+try:
+  _notebook = sys.modules['IPython'].display
+except Exception:  # pylint: disable=broad-except
+  _notebook = None
+
+
+class HtmlControl(pg_object.Object):
+  """Base class for HTML controls."""
+
+  id: Annotated[
+      Optional[str],
+      'Optional ID of the root element.'
+  ] = None
+
+  css_classes: Annotated[
+      List[str],
+      'Optional CSS classes of the root element.'
+  ] = []
+
+  styles: Annotated[
+      Dict[str, Any],
+      'Ad-hoc styles (vs. class-based) of the root element.'
+  ] = {}
+
+  interactive: Annotated[
+      bool,
+      (
+          'Whether the control is interactive. If False, optimizations will be '
+          'applied to reduce the size of the HTML.'
+      )
+  ] = False
+
+  def _on_bound(self):
+    super()._on_bound()
+    self._rendered = False
+    self._css_styles = []
+    self._dynamic_injected_css = set()
+    self._scripts = []
+
+  def add_style(self, *css: str) -> 'HtmlControl':
+    """Adds CSS styles to the HTML."""
+    self._css_styles.extend(css)
+    return self
+
+  def add_script(self, *scripts: str) -> 'HtmlControl':
+    self._scripts.extend(scripts)
+    return self
+
+  def to_html(self, **kwargs) -> Html:
+    """Returns the HTML representation of the control."""
+    self._rendered = True
+    self._dynamic_injected_css = set()
+    html = self._to_html(**kwargs)
+    return html.add_style(*self._css_styles).add_script(*self._scripts)
+
+  @abc.abstractmethod
+  def _to_html(self, **kwargs) -> Html:
+    """Returns the HTML representation of the control."""
+
+  @classmethod
+  @contextlib.contextmanager
+  def track_scripts(cls) -> Iterator[List[str]]:
+    del cls
+    all_tracked = utils.thread_local_get(_TLS_TRACKED_SCRIPTS, [])
+    current = []
+    all_tracked.append(current)
+    utils.thread_local_set(_TLS_TRACKED_SCRIPTS, all_tracked)
+    try:
+      yield current
+    finally:
+      all_tracked.pop(-1)
+      if not all_tracked:
+        utils.thread_local_del(_TLS_TRACKED_SCRIPTS)
+
+  def _sync_members(self, **fields) -> None:
+    """Synchronizes displayed values to members."""
+    self.rebind(fields, skip_notification=True, raise_on_no_change=False)
+
+  def _run_javascript(self, code: str, debug: bool = False) -> None:
+    """Runs the given JavaScript code."""
+    if not self.interactive:
+      raise ValueError(
+          f'Non-interactive control {self} cannot be updated. '
+          'Please set `interactive=True` in the constructor.'
+      )
+    if not self._rendered:
+      return
+
+    code = inspect.cleandoc(code)
+    if debug:
+      print('RUN JAVSCRIPT:\n', code)
+    if _notebook is not None:
+      _notebook.display(_notebook.Javascript(code))
+
+    # Track script execution.
+    all_tracked = utils.thread_local_get(_TLS_TRACKED_SCRIPTS, [])
+    for tracked in all_tracked:
+      tracked.append(code)
+
+  def _add_css_rules(self, css: str) -> None:
+    if not self._rendered or not css or css in self._dynamic_injected_css:
+      return
+    self._run_javascript(
+        f"""
+        const style = document.createElement('style');
+        style.type = 'text/css';
+        style.textContent = "{Html.escape(css, javascript_str=True)}";
+        document.head.appendChild(style);
+        """
+    )
+    self._dynamic_injected_css.add(css)
+
+  def _apply_css_rules(self, html: Html) -> None:
+    self._add_css_rules(html.styles.content)
+
+  def _insert_adjacent_html(
+      self,
+      element_selector_js: str,
+      html: Html,
+      var_name: str = 'elem',
+      position: str = 'beforeend'
+  ):
+    self._run_javascript(
+        f"""
+        {element_selector_js}
+        {var_name}.insertAdjacentHTML(
+            "{position}",
+            "{Html.escape(html, javascript_str=True).to_str(content_only=True)}"
+        );
+        """,
+    )
+    self._apply_css_rules(html)
+
+  def element_id(self, child: Optional[str] = None) -> Optional[str]:
+    """Returns the element id of this control or a child."""
+    if self.id is not None:
+      return self.id
+    elif not self.interactive:
+      return None
+    elif child is None:
+      return f'control-{id(self)}'
+    else:
+      return f'control-{id(self)}-{child}'
+
+  def _update_content(
+      self,
+      content: Union[str, Html],
+      child: Optional[str] = None,
+  ) -> None:
+    """Updates the content of the control."""
+    if isinstance(content, str):
+      return self._update_text(content, child)
+    else:
+      return self._update_inner_html(content, child)
+
+  def _update_text(
+      self,
+      content: str,
+      child: Optional[str] = None
+  ) -> str:
+    """Updates the content of the control."""
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.textContent = "{Html.escape(content, javascript_str=True)}";
+        """
+    )
+    return content
+
+  def _update_inner_html(
+      self,
+      html: base.Html,
+      child: Optional[str] = None,
+  ) -> base.Html:
+    """Updates the inner HTML of the control."""
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.innerHTML = "{Html.escape(html, javascript_str=True).to_str(content_only=True)}";
+        """
+    )
+    self._add_css_rules(html.styles.content)
+    return html
+
+  def _update_style(
+      self,
+      styles: Dict[str, Any],
+      *,
+      child: Optional[str] = None,
+      updates_only: bool = False,
+  ) -> Dict[str, Any]:
+    """Updates the style of the control."""
+    updated_styles = {} if updates_only else dict(self.styles or {})
+    updated_styles.update(styles)
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.style = "{Html.style_str(updated_styles)}";
+        """
+    )
+    return updated_styles
+
+  def _update_property(
+      self,
+      name: str,
+      value: str,
+      child: Optional[str] = None,
+  ) -> str:
+    """Updates a property of the control."""
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.{name} = "{value}";
+        """
+    )
+    return value
+
+  def _add_css_class(
+      self,
+      css_class: str,
+      child: Optional[str] = None,
+  ) -> str:
+    """Adds a CSS class to the control."""
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.classList.add("{css_class}");
+        """
+    )
+    return css_class
+
+  def _remove_css_class(
+      self,
+      css_class: str,
+      child: Optional[str] = None,
+  ) -> str:
+    """Removes a CSS class from the control."""
+    self._run_javascript(
+        f"""
+        elem = document.getElementById("{self.element_id(child)}");
+        elem.classList.remove("{css_class}");
+        """
+    )
+    return css_class
+
+
+_TLS_TRACKED_SCRIPTS = '__tracked_scripts__'

pyglove/core/views/html/controls/label.py

@@ -0,0 +1,207 @@
+# Copyright 2024 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Html label control."""
+
+from typing import Annotated, Any, Dict, List, Optional, Union
+
+from pyglove.core import typing as pg_typing
+from pyglove.core.symbolic import flags as pg_flags
+from pyglove.core.symbolic import object as pg_object
+# pylint: disable=g-importing-member
+from pyglove.core.views.html.base import Html
+from pyglove.core.views.html.controls.base import HtmlControl
+from pyglove.core.views.html.controls.tooltip import Tooltip
+# pylint: enable=g-importing-member
+
+
+@pg_object.use_init_args(
+    ['text', 'tooltip', 'link', 'id', 'css_classes', 'styles']
+)
+class Label(HtmlControl):
+  """Html label."""
+
+  text: Annotated[
+      Union[str, Html],
+      'The text or HTML content of the label.'
+  ]
+
+  tooltip: Annotated[
+      Optional[Tooltip],
+      '(Optional) The tooltip for the label.'
+  ] = None
+
+  link: Annotated[
+      Optional[str],
+      '(Optional) The URL for the link of the label.'
+  ] = None
+
+  target: Annotated[
+      Optional[str],
+      '(Optional) The target for the link of the label.'
+  ] = None
+
+  def _on_bound(self):
+    super()._on_bound()
+    if self.tooltip is not None:
+      self.tooltip.rebind(
+          for_element='.label',
+          interactive=self.tooltip.interactive or self.interactive,
+          notify_parents=False
+      )
+    self.add_style(
+        """
+        .label {
+          display: inline-block;
+          color: inherit;
+          padding: 5px;
+        }
+        .label-container {
+            display: inline-block;
+        }
+        """
+    )
+
+  def _to_html(self, **kwargs) -> Html:
+    text_elem = Html.element(
+        'a' if self.link is not None else 'span',
+        [self.text],
+        id=self.element_id(),
+        href=self.link,
+        css_classes=['label'] + self.css_classes,
+        styles=self.styles,
+        target=self.target,
+    )
+    if self.tooltip is None:
+      return text_elem
+    return Html.element(
+        'div',
+        [text_elem, self.tooltip],
+        css_classes=['label-container'],
+    )
+
+  def update(
+      self,
+      text: Union[str, Html, None] = None,
+      tooltip: Union[str, Html, None] = None,
+      link: Optional[str] = None,
+      styles: Optional[Dict[str, Any]] = None,
+      add_class: Optional[List[str]] = None,
+      remove_class: Optional[List[str]] = None,
+  ) -> None:
+    if text is not None:
+      self._sync_members(text=self._update_content(text))
+    if styles:
+      self._sync_members(styles=self._update_style(styles))
+    if link is not None:
+      self._sync_members(link=self._update_property('href', link))
+    if tooltip is not None:
+      self.tooltip.update(content=tooltip)
+    if add_class or remove_class:
+      css_classes = list(self.css_classes)
+      for x in add_class or []:
+        self._add_css_class(x)
+        css_classes.append(x)
+      for x in remove_class or []:
+        self._remove_css_class(x)
+        if x in css_classes:
+          css_classes.remove(x)
+      self._sync_members(css_classes=css_classes)
+
+# Register converter for automatic conversion.
+pg_typing.register_converter(str, Label, Label)
+pg_typing.register_converter(Html, Label, Label)
+
+
+class Badge(Label):
+  """A badge."""
+
+  def _on_bound(self):
+    super()._on_bound()
+    with pg_flags.notify_on_change(False):
+      self.css_classes.append('badge')
+    self.add_style(
+        """
+        .badge {
+          background-color: #EEE;
+          border-radius: 5px;
+          color: #777;
+        }
+        """
+    )
+
+
+@pg_object.use_init_args(
+    ['labels', 'name', 'id', 'css_classes', 'styles']
+)
+class LabelGroup(HtmlControl):
+  """Label group."""
+
+  labels: Annotated[
+      List[Label],
+      'The labels in the group.'
+  ]
+
+  name: Annotated[
+      Optional[Label],
+      'The label for the name of the group.'
+  ] = None
+
+  def _on_bound(self):
+    super()._on_bound()
+    with pg_flags.notify_on_change(False):
+      if self.name is not None:
+        self.name.rebind(
+            interactive=self.interactive or self.name.interactive,
+            raise_on_no_change=False
+        )
+        self.name.css_classes.append('group-name')
+      for label in self.labels:
+        label.css_classes.append('group-value')
+        label.rebind(
+            interactive=self.interactive or label.interactive,
+            raise_on_no_change=False,
+        )
+
+  def _to_html(self, **kwargs) -> Html:
+    return Html.element(
+        'div',
+        [self.name] + self.labels,
+        id=self.id or None,
+        css_classes=['label-group'] + self.css_classes,
+        styles=self.styles,
+    ).add_style(
+        """
+        .label-group {
+          display: inline-flex;
+          overflow: hidden;
+          border-radius: 5px;
+          border: 1px solid #DDD;
+          padding: 0px;
+          margin: 5px
+        }
+        .label-group .group-name {
+          padding: 5px;
+          color: white;
+          background-color: dodgerblue;
+        }
+        .label-group .group-name > .text {
+          color: white;
+        }
+        .label-group .group-value {
+        }
+        .label-group .badge {
+          border-radius: 0px;
+        }
+        """
+    )

pyglove/core/views/html/controls/label_test.py

@@ -0,0 +1,157 @@
+# Copyright 2024 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import inspect
+import unittest
+
+from pyglove.core import symbolic   # pylint: disable=unused-import
+from pyglove.core.views.html.controls import label as label_lib
+
+
+class TestCase(unittest.TestCase):
+
+  def assert_html_content(self, control, expected):
+    expected = inspect.cleandoc(expected).strip()
+    actual = control.to_html().content.strip()
+    if actual != expected:
+      print(actual)
+    self.assertEqual(actual, expected)
+
+
+class LabelTest(TestCase):
+
+  def test_text_only(self):
+    label = label_lib.Label('foo')
+    self.assertIsNone(label.tooltip)
+    self.assertIsNone(label.link)
+    self.assert_html_content(label, '<span class="label">foo</span>')
+    with self.assertRaisesRegex(ValueError, 'Non-interactive .*'):
+      label.update('bar')
+
+  def test_with_link(self):
+    label = label_lib.Label('foo', link='http://google.com', id='my-foo')
+    self.assertEqual(label.element_id(), 'my-foo')
+    self.assertIsNone(label.tooltip)
+    self.assertEqual(label.link, 'http://google.com')
+    self.assert_html_content(
+        label, '<a class="label" id="my-foo" href="http://google.com">foo</a>'
+    )
+
+  def test_with_tooltip(self):
+    label = label_lib.Label('foo', tooltip='bar')
+    self.assertEqual(label.tooltip.for_element, '.label')
+    self.assertIsNone(label.link)
+    self.assert_html_content(
+        label,
+        (
+            '<div class="label-container"><span class="label">foo</span>'
+            '<span class="tooltip">bar</span></div>'
+        )
+    )
+
+  def test_update(self):
+    label = label_lib.Label(
+        'foo', 'bar', 'http://google.com',
+        interactive=True,
+        css_classes=['foo', 'bar'],
+    )
+    self.assertIn('id="control-', label.to_html_str(content_only=True))
+    with label.track_scripts() as scripts:
+      label.update(
+          'bar',
+          tooltip='baz',
+          link='http://www.yahoo.com',
+          styles=dict(color='red'),
+          add_class=['baz'],
+          remove_class=['bar'],
+      )
+    self.assertEqual(label.text, 'bar')
+    self.assertEqual(label.tooltip.content, 'baz')
+    self.assertEqual(label.link, 'http://www.yahoo.com')
+    self.assertEqual(label.styles, dict(color='red'))
+    self.assertEqual(label.css_classes, ['foo', 'baz'])
+    self.assertEqual(
+        scripts,
+        [
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.element_id()}");
+                elem.textContent = "bar";
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.element_id()}");
+                elem.style = "color:red;";
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.element_id()}");
+                elem.href = "http://www.yahoo.com";
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.tooltip.element_id()}");
+                elem.textContent = "baz";
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.tooltip.element_id()}");
+                elem.classList.remove("html-content");
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.element_id()}");
+                elem.classList.add("baz");
+                """
+            ),
+            inspect.cleandoc(
+                f"""
+                elem = document.getElementById("{label.element_id()}");
+                elem.classList.remove("bar");
+                """
+            ),
+        ]
+    )
+
+  def test_badge(self):
+    badge = label_lib.Badge('foo')
+    self.assert_html_content(badge, '<span class="label badge">foo</span>')
+
+
+class LabelGroupTest(TestCase):
+
+  def test_basic(self):
+    group = label_lib.LabelGroup(['foo', 'bar'], name='baz')
+    self.assert_html_content(
+        group,
+        (
+            '<div class="label-group"><span class="label group-name">baz</span>'
+            '<span class="label group-value">foo</span>'
+            '<span class="label group-value">bar</span></div>'
+        )
+    )
+
+  def test_interactive(self):
+    group = label_lib.LabelGroup(['foo', 'bar'], name='baz', interactive=True)
+    self.assertTrue(group.name.interactive)
+    self.assertTrue(group.labels[0].interactive)
+    self.assertTrue(group.labels[1].interactive)
+
+
+if __name__ == '__main__':
+  unittest.main()