Add static folder for static files and pre-loaded stylesheets (using new utility)

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}")