Add busy indicators (aka spinners)

examples/loading-spinners/app.py

@@ -0,0 +1,60 @@
+# pyright:basic
+import asyncio
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from shiny import App, reactive, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_slider("rows", "Rows", 0, 100, 20),
+    ),
+    ui.use_loading_spinners(color="red"),
+    ui.layout_column_wrap(
+        ui.card(
+            # Add a spinner directly to an output.
+            ui.with_spinner(ui.output_plot("plot")),
+        ),
+        ui.card(
+            ui.output_plot("plot2"),
+        ),
+        height="1500px",
+    ),
+    class_="dot-track-spinner",
+)
+
+
+def server(input, output, session):
+    first_render = reactive.value(True)
+
+    @render.plot
+    async def plot():
+        # Generate input.rows() random numbers
+        data = np.random.randn(input.rows())
+        plt.plot(data)
+        plt.ylabel("some numbers")
+
+        # Only sleep on subsequent renders so we can quickly start looking at the
+        # spinner
+        with reactive.isolate():
+            if not first_render.get():
+                # Sleep for a second to simulate a long running process
+                await asyncio.sleep(3)
+            else:
+                first_render.set(False)
+
+        return plt.gcf()
+
+    @render.plot
+    async def plot2():
+        # Generate input.rows() random numbers
+        data = np.random.randn(input.rows())
+        plt.plot(data)
+        plt.ylabel("some numbers")
+        # Sleep for a second to simulate a long running process
+
+        return plt.gcf()
+
+
+app = App(app_ui, server)

shiny/ui/__init__.py

@@ -139,6 +139,11 @@
 )
 from ._tooltip import tooltip
 
+from ._loading_spinners import (
+    use_loading_spinners,
+    with_spinner,
+)
+
 
 from htmltools import (
     TagList,
@@ -346,4 +351,7 @@
     "strong",
     "em",
     "hr",
+    # Items related to loading spinners
+    "use_loading_spinners",
+    "with_spinner",
 )

shiny/ui/_html_deps_external.py

@@ -5,6 +5,7 @@
 from .._versions import bootstrap as bootstrap_version
 from .._versions import shiny_html_deps
 from ..html_dependencies import jquery_deps
+from ._loading_spinners import page_level_spinners_deps
 
 """
 HTML dependencies for external dependencies Bootstrap, ionrangeslider, datepicker, selectize, and jQuery UI.
@@ -25,7 +26,13 @@ def bootstrap_deps() -> list[HTMLDependency]:
         stylesheet={"href": "bootstrap.min.css"},
         meta={"name": "viewport", "content": "width=device-width, initial-scale=1"},
     )
-    deps = [jquery_deps(), dep]
+    deps = [
+        jquery_deps(),
+        dep,
+        # Place spinners css in as a dependency. Eventually this should be in the main
+        # shiny css.
+        page_level_spinners_deps,
+    ]
     return deps
 
 

shiny/ui/_loading_spinners.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from htmltools import HTML, HTMLDependency, Tag, head_content, tags
+
+from .. import __version__
+
+
+def use_loading_spinners(
+    type: Literal["tadpole", "disc", "dots", "dot-track", "bounce"] = "tadpole",
+    color: Optional[str] = None,
+    size: Optional[str] = None,
+    speed: Optional[str] = None,
+    delay: Optional[str] = None,
+) -> HTMLDependency:
+    """
+    Function to tweak loading spinner options for app.
+
+    This function allows you to tweak the style of the loading spinners used in your app.
+
+    When supplied in your app's UI, elements that are loading (e.g. plots or tables)
+    will have a spinner displayed over them. This is useful for when you have a
+    long-running computation and want to indicate to the user that something is
+    happening beyond the default grayed-out element.
+
+    Parameters
+    ----------
+
+    type
+        The type of spinner to use. Options include "disc", "tadpole", "dots",
+        "dot-track", and "bounce". Defaults to "tadpole".
+    color
+        The color of the spinner. This can be any valid CSS color. Defaults to the
+        current app "primary" color (if using a theme) or light-blue if not.
+    size
+        The size of the spinner. This can be any valid CSS size. Defaults to "80px".
+    speed
+        The amount of time for the spinner to complete a single revolution. This can be
+        any valid CSS time. Defaults to "1s".
+    delay
+        The amount of time to wait before showing the spinner. This can be any valid CSS
+        time. Defaults to "0.5s". This is useful for not showing the spinner if the
+        computation finishes quickly.
+    page_level
+        Should the spinner be shown at the page level (i.e. one spinner per app) or at
+        the level of each output (default).
+
+    Returns
+    -------
+    :
+        An HTMLDependency
+
+    Notes
+    -----
+    This function is meant to be called a single time. If it is called multiple times
+    with different arguments then only the first call will be reflected.
+    """
+
+    animation = None
+    easing = None
+
+    # Some of the spinners work better with linear easing and some with ease-in-out so
+    # we modify them together.
+    if type == "disc":
+        svg = "disc-spinner.svg"
+        easing = "linear"
+    elif type == "dots":
+        svg = "dots-spinner.svg"
+        easing = "linear"
+    elif type == "dot-track":
+        svg = "dot-track-spinner.svg"
+        easing = "linear"
+    elif type == "bounce":
+        svg = "ball.svg"
+        animation = "shiny-loading-spinner-bounce"
+        # Set speed variable to 0.8s if it hasnt been set by the user
+        speed = speed or "0.8s"
+    else:
+        svg = "tadpole-spinner.svg"
+        easing = "linear"
+
+    # We set options using css variables. Here we create the rule that updates the
+    # appropriate variables before being included in the head of the document with our
+    # html dep.
+    rule_contents = (
+        f"--shiny-spinner-svg: url({svg});"
+        + (f"--shiny-spinner-easing: {easing};" if easing else "")
+        + (f"--shiny-spinner-animation: {animation};" if animation else "")
+        + (f"--shiny-spinner-color: {color};" if color else "")
+        + (f"--shiny-spinner-size: {size};" if size else "")
+        + (f"--shiny-spinner-speed: {speed};" if speed else "")
+        + (f"--shiny-spinner-delay: {delay};" if delay else "")
+    )
+
+    return head_content(tags.style(HTML("body{" + rule_contents + "}</style>")))
+
+
+page_level_spinners_deps = HTMLDependency(
+    "shiny-loading-spinners-css",
+    version=__version__,
+    source={
+        "package": "shiny",
+        "subdir": "www/shared/loading-spinners/",
+    },
+    stylesheet=[
+        {"href": "spinners-page-level.css"},
+        {"href": "spinners-common.css"},
+    ],
+    all_files=True,
+)
+
+
+def with_spinner(el: Tag) -> Tag:
+    """
+    Enable a loading spinner for a given output. These spinners will sit directly on the
+    output itself rather than in the upper corner.
+
+    Parameters
+    ----------
+
+    el
+        The element to add the spinner to. Typically an output element like a
+        plot or table.
+
+    Returns
+    -------
+    :
+        Element with the class "show-spinner" added to it.
+
+    Examples
+    --------
+
+    ```{python}
+    #|eval: false
+    ui.with_spinner(ui.output_plot("plot")),
+    ```
+    """
+    el.attrs["class"] = el.attrs.get("class", "") + " show-spinner"
+    return el

shiny/www/shared/loading-spinners/spinners-common.css

@@ -0,0 +1,75 @@
+/*
+  We replace the default loading/recalculating state of lowering the opacity with a
+  background blur effect. It's a bit more subtle and also doesn't affect spinners themselves
+  since they sit above the blur filter.
+*/
+.recalculating {
+  /* Used so that our psuedo-elements can be positioned with respect to the output */
+  position: relative;
+
+  /* Override the default .recalculating style */
+  opacity: 1;
+}
+
+.recalculating::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 1000;
+  animation-name: shiny-loading-spinner-fade-in;
+  animation-duration: var(--_shiny-spinner-blur-speed);
+  animation-timing-function: var(--_shiny-spinner-blur-easing);
+  animation-delay: var(--_shiny-spinner-delay);
+  /* This makes it so the blur stays after animating in */
+  animation-fill-mode: forwards;
+}
+
+/*
+  Various keyframe animations available to use for spinner animations.
+*/
+
+@keyframes shiny-loading-spinner-fade-in {
+  from {
+    -webkit-backdrop-filter: blur(0px);
+    backdrop-filter: blur(0px);
+  }
+  to {
+    -webkit-backdrop-filter: blur(3px);
+    backdrop-filter: blur(3px);
+  }
+}
+
+@keyframes shiny-loading-spinner-spin {
+  0% {
+    scale: 1;
+    rotate: 0deg;
+  }
+  100% {
+    scale: 1;
+    rotate: 360deg;
+  }
+}
+
+@keyframes shiny-loading-spinner-bounce {
+  0% {
+    animation-timing-function: cubic-bezier(0.33, 0, 0.66, 0.33);
+    translate: 0 calc(var(--_shiny-spinner-size) * (5 / 24));
+    scale: 1 1;
+  }
+  46.875% {
+    translate: 0 calc(var(--_shiny-spinner-size) * (20 / 24));
+    scale: 1 1;
+  }
+  50% {
+    animation-timing-function: cubic-bezier(0.33, 0.66, 0.66, 1);
+    translate: 0 calc(var(--_shiny-spinner-size) * (20.5 / 24));
+    scale: 1.2 0.85;
+  }
+  53.125% {
+    scale: 1 1;
+  }
+  100% {
+    translate: 0 calc(var(--_shiny-spinner-size) * (5 / 24));
+    scale: 1 1;
+  }
+}

shiny/www/shared/loading-spinners/spinners-element-level.css

@@ -0,0 +1,39 @@
+/* Override the default styles since they would make the spinner fade as well */
+.recalculating {
+  --_shiny-spinner-color: var(
+    --shiny-spinner-color,
+    var(--bs-primary, #007bc2)
+  );
+  --_shiny-spinner-svg: var(--shiny-spinner-svg, url(tadpole-spinner.svg));
+  --_shiny-spinner-size: var(--shiny-spinner-size, 80px);
+  --_shiny-spinner-easing: var(--shiny-spinner-easing, ease-in-out);
+  --_shiny-spinner-speed: var(--shiny-spinner-speed, 2s);
+  --_shiny-spinner-delay: var(--shiny-spinner-delay, 0.1s);
+  --_shiny-spinner-animation: var(
+    --shiny-spinner-animation,
+    shiny-loading-spinner-spin
+  );
+
+  --_shiny-spinner-blur-speed: var(--shiny-spinner-blur-speed, 0.2s);
+  --_shiny-spinner-blur-easing: var(--shiny-spinner-blur-easing, ease-in);
+}
+
+.recalculating::after {
+  content: "";
+  background: var(--_shiny-spinner-color, gray);
+  -webkit-mask: var(--_shiny-spinner-svg) center/contain no-repeat;
+  mask: var(--_shiny-spinner-svg) center/contain no-repeat;
+  width: var(--_shiny-spinner-size);
+  height: var(--_shiny-spinner-size);
+  position: absolute;
+  inset: calc(50% - var(--_shiny-spinner-size) / 2);
+
+  scale: 0;
+  animation-name: var(--_shiny-spinner-animation);
+  animation-duration: var(--_shiny-spinner-speed);
+  animation-iteration-count: infinite;
+  animation-timing-function: var(--_shiny-spinner-easing);
+  animation-delay: var(--_shiny-spinner-delay);
+
+  z-index: 1001;
+}