Implement static CSS loader utility (#624)

`ipywidgets` provides its own mechanism for styling widgets. However, it is often insufficient and clunky, only exposing a limited set of style properties. This PR implements a CSS stylesheet loader utility and a dedicated static folder for CSS stylesheets (loaded on import by the utility) to extend widget styling to the full breadth of standard features allowed by CSS. The utility can be imported by apps wishing to leverage this approach to widget styling.

aiidalab_widgets_base/__init__.py

@@ -1,7 +1,5 @@
 """Reusable widgets for AiiDAlab applications."""
 
-from aiida.manage import get_profile
-
 _WARNING_TEMPLATE = """
 <div style="background-color: #f7f7f7; border: 2px solid #e0e0e0; padding: 20px; border-radius: 5px;">
     <p style="font-size: 16px; font-weight: bold; color: #ff5733;">Warning:</p>
@@ -13,6 +11,20 @@
 """
 
 
+def load_default_profile():
+    """Loads the default profile if none loaded and warn of deprecation."""
+    from aiida import load_profile
+
+    load_profile()
+
+    profile = get_profile()
+    assert profile is not None, "Failed to load the default profile"
+
+    # raise a deprecation warning
+    warning = HTML(_WARNING_TEMPLATE.format(profile=profile.name, version="v3.0.0"))
+    display(warning)
+
+
 # We only detect profile and throw a warning if it is on the notebook
 # It is not necessary to do this in the unit tests
 def is_running_in_jupyter():
@@ -27,22 +39,22 @@ def is_running_in_jupyter():
         return False
 
 
-# load the default profile if no profile is loaded, and raise a deprecation warning
-# this is a temporary solution to avoid breaking existing notebooks
-# this will be removed in the next major release
-if is_running_in_jupyter() and get_profile() is None:
-    # if no profile is loaded, load the default profile and raise a deprecation warning
-    from aiida import load_profile
+if is_running_in_jupyter():
+    from pathlib import Path
+
+    from aiida.manage import get_profile
     from IPython.display import HTML, display
 
-    load_profile()
+    # load the default profile if no profile is loaded, and raise a deprecation warning
+    # this is a temporary solution to avoid breaking existing notebooks
+    # this will be removed in the next major release
+    if get_profile() is None:
+        load_default_profile()
 
-    profile = get_profile()
-    assert profile is not None, "Failed to load the default profile"
+    from .utils.loaders import load_css
+
+    load_css(css_path=Path(__file__).parent / "static/styles")
 
-    # raise a deprecation warning
-    warning = HTML(_WARNING_TEMPLATE.format(profile=profile.name, version="v3.0.0"))
-    display(warning)
 
 from .computational_resources import (
     ComputationalResourcesWidget,

aiidalab_widgets_base/static/styles/README.md

@@ -0,0 +1,3 @@
+# Stylesheets for AiiDAlab Widgets Base
+
+This folder contains `.css` stylesheets, which are loaded on any import from the AiiDAlab widgets base package.

aiidalab_widgets_base/utils/loaders.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from IPython.display import Javascript, display
+
+
+def load_css(css_path: Path | str) -> None:
+    """Load and inject CSS stylesheets into the DOM.
+
+    Parameters
+    ----------
+    `css_path` : `Path` | `str`
+        The path to the CSS stylesheet. If the path is a directory,
+        all CSS files in the directory will be loaded.
+    """
+    path = Path(css_path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"CSS file or directory not found: {path}")
+
+    filenames = [*path.glob("*.css")] if path.is_dir() else [path]
+
+    for fn in filenames:
+        stylesheet = fn.read_text()
+        display(
+            Javascript(f"""
+                var style = document.createElement('style');
+                style.type = 'text/css';
+                style.innerHTML = `{stylesheet}`;
+                document.head.appendChild(style);
+            """)
+        )

docs/source/contribute/index.rst

@@ -8,3 +8,20 @@ Contributions to the AiiDAlab widgets are highly welcome and can take different
 * `Report bugs <https://github.com/aiidalab/aiidalab-widgets-base/issues>`_.
 * `Feature requests <https://github.com/aiidalab/aiidalab-widgets-base/issues>`_.
 * Help us improve the documentation of widgets.
+
+**************
+Widget styling
+**************
+
+Though ``ipywidgets`` does provide some basic styling options via the ``layout`` and ``style`` attributes, it is often not enough to create a visually appealing widget.
+As such, we recommend the use of `CSS <https://www.w3schools.com/css/>`_ stylesheets to style your widgets.
+These may be packaged under ``aiidalab_widgets_base/static/styles``, which are automatically loaded on import via the ``load_css`` utility.
+
+A ``global.css`` stylesheet is made available for global html-tag styling and ``ipywidgets`` or ``Jupyter`` style overrides.
+For more specific widgets and components, please add a dedicated stylesheet.
+Note that all stylesheets in the ``styles`` directory will be loaded on import.
+
+We recommend using classes to avoid style leaking outside of the target widget.
+We also advise causion when using the `!important <https://www.w3schools.com/css/css_important.asp>`_ flag on CSS properties, as it may interfere with other stylesheets.
+
+If you are unsure about the styling of your widget, feel free to ask for help on the `AiiDAlab Discourse channel <https://aiida.discourse.group/tag/aiidalab>`_.

setup.cfg

@@ -64,6 +64,10 @@ docs =
     pydata-sphinx-theme~=0.15
     myst-nb~=1.1
 
+
+[options.package_data]
+aiidalab_widgets_base.static.styles = *.css
+
 [bumpver]
 current_version = "v2.3.0a1"
 version_pattern = "vMAJOR.MINOR.PATCH[PYTAGNUM]"

tests/test_loaders.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+from aiidalab_widgets_base.utils.loaders import load_css
+
+
+def test_load_css():
+    """Test `load_css` utility."""
+    css_dir = Path("aiidalab_widgets_base/static/styles")
+    load_css(css_path=css_dir)
+    load_css(css_path=css_dir / "global.css")

tests_notebooks/static/styles/test.css

@@ -0,0 +1,3 @@
+.red-text {
+  color: rgb(255, 0, 0);
+}

tests_notebooks/test_notebook.ipynb

@@ -0,0 +1,67 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ipywidgets as ipw"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from aiida import load_profile\n",
+    "\n",
+    "load_profile();"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from aiidalab_widgets_base.utils.loaders import load_css\n",
+    "\n",
+    "load_css(css_path=\"static/styles/test.css\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "label = ipw.Label(\"Testing\")\n",
+    "label.add_class(\"red-text\")\n",
+    "display(label)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

tests_notebooks/test_notebooks.py

@@ -5,6 +5,15 @@
 from selenium.webdriver.common.keys import Keys
 
 
+def test_loaded_css(selenium_driver):
+    driver = selenium_driver("tests_notebooks/test_notebook.ipynb")
+    element = driver.find_element(By.CLASS_NAME, "red-text")
+    assert element.value_of_css_property("color") in (
+        "rgba(255, 0, 0, 1)",  # Chrome
+        "rgb(255, 0, 0)",  # Firefox
+    )
+
+
 def test_notebook_service_available(notebook_service):
     url, token = notebook_service
     response = requests.get(f"{url}/?token={token}")