Add busy indicators (aka spinners)

docs/_quartodoc-core.yml

@@ -108,6 +108,8 @@ quartodoc:
         - ui.include_js
         - ui.insert_ui
         - ui.remove_ui
+        - ui.busy_indicators.use
+        - ui.busy_indicators.spinner_options
         - ui.fill.as_fillable_container
         - ui.fill.as_fill_item
         - ui.fill.remove_all_fill

docs/_quartodoc-express.yml

@@ -160,6 +160,8 @@ quartodoc:
         - name: express.ui.tags       # uses tags.rst template
           children: embedded
         - express.ui.TagList    # uses class.rst template
+        - express.ui.busy_indicators.use
+        - express.ui.busy_indicators.spinner_options
         # TODO: should these be included?
         # - express.ui.fill.as_fillable_container
         # - express.ui.fill.as_fill_item

examples/busy_indicators/app.py

@@ -0,0 +1,111 @@
+# pyright:basic
+import asyncio
+import concurrent.futures
+import time
+
+import matplotlib.pyplot as mpl
+import numpy as np
+import seaborn as sns
+from faicons import icon_svg
+
+from shiny import App, module, reactive, render, ui
+
+# Execute each extended task on a different thread.
+pool = concurrent.futures.ThreadPoolExecutor()
+
+# Use Agg backend for matplotlib so that it doesn't try to open a window.
+mpl.switch_backend("Agg")
+
+
+# -- Reusable card module --
+@module.ui
+def card_ui(title="Tadpole", spinner_type="tadpole"):
+    return ui.card(
+        ui.card_header(
+            title,
+            ui.input_task_button("simulate", "Simulate", icon=icon_svg("shuffle")),
+            class_="d-flex justify-content-between align-items-center",
+        ),
+        ui.busy_indicators.spinner_options(
+            spinner_type, css_selector="." + spinner_type
+        ),
+        ui.output_plot("plot"),
+        class_=spinner_type,
+    )
+
+
+@module.server
+def card_server(input, output, session, length, simulate_all):
+
+    def do_plot(wait_time=0.5):
+        time.sleep(wait_time)
+
+        # Without ax, seaborn works through side effects, so supply the ax to avoid
+        # one figure from affecting another.
+        fig, ax = mpl.subplots(1, 1)
+        sns.lineplot(x=np.arange(100), y=np.random.randn(100), ax=ax)
+        return fig
+
+    @ui.bind_task_button(button_id="simulate")
+    @reactive.extended_task
+    async def plot_task(wait_time=1):
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(pool, do_plot, wait_time)
+
+    @reactive.effect
+    @reactive.event(input.simulate, ignore_none=False)
+    def _():
+        plot_task(1 if input.simulate() == 0 else length())
+
+    @reactive.effect
+    @reactive.event(simulate_all)
+    def _():
+        plot_task(length())
+
+    @render.plot
+    def plot():
+        return plot_task.result()
+
+
+# -- Main app --
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_task_button("simulate_all", "Simulate all", icon=icon_svg("shuffle")),
+        ui.input_selectize(
+            "indicator_types",
+            "Busy indicator types",
+            ["spinners", "pulse", "cursor"],
+            multiple=True,
+            selected=["spinners", "pulse"],
+        ),
+        ui.input_slider("length", "Simulation length", 0, 500, 5),
+    ),
+    ui.layout_columns(
+        card_ui("a", "Tadpole", "tadpole"),
+        card_ui("b", "Disc", "disc"),
+        card_ui("c", "Dots", "dots"),
+        card_ui("d", "Dot track", "dot-track"),
+        col_widths=[6, 6],
+    ),
+    card_ui("e", "Ball", "bounce"),
+    ui.output_ui("indicator_types_ui"),
+    fillable=True,
+    title="Busy indicators + extended tasks = ❤️",
+)
+
+
+def server(input, output, session):
+
+    @render.ui
+    def indicator_types_ui():
+        return ui.busy_indicators.use(input.indicator_types())
+
+    card_server("a", length=input.length, simulate_all=input.simulate_all)
+    card_server("b", length=input.length, simulate_all=input.simulate_all)
+    card_server("c", length=input.length, simulate_all=input.simulate_all)
+    card_server("d", length=input.length, simulate_all=input.simulate_all)
+    card_server("e", length=input.length, simulate_all=input.simulate_all)
+
+
+app = App(app_ui, server)
+app.on_shutdown(pool.shutdown)

js/build.ts

@@ -74,6 +74,14 @@ const opts: Array<BuildOptions> = [
     plugins: [sassPlugin({ type: "css", sourceMap: false })],
     metafile: true,
   },
+  {
+    entryPoints: {
+      "busy-indicators/busy-indicators": "busy-indicators/busy-indicators.scss",
+    },
+    loader: { ".svg": "dataurl" },
+    plugins: [sassPlugin({ type: "css", sourceMap: false })],
+    metafile: true,
+  },
 ];
 
 // Run function to avoid top level await

js/busy-indicators/busy-indicators.scss

@@ -0,0 +1,181 @@
+/*
+  CSS for shiny.ui.busy_indicators module.
+
+  The general idea is to leverage the `recalculating` class that shiny.js adds to each
+  output when it's recalculating and add a spinner to the `::after` pseudo-element.
+*/
+
+/* "Built-in" spinner types */
+/* Part of the reason why they're all here is so we can embed the SVGs in the CSS */
+:root {
+  --_shiny-spinner-type-tadpole: url(tadpole-spinner.svg);
+  --_shiny-spinner-type-disc: url(disc-spinner.svg);
+  --_shiny-spinner-type-dots: url(dots-spinner.svg);
+  --_shiny-spinner-type-dot-track: url(dot-track-spinner.svg);
+  --_shiny-spinner-type-bounce: url(ball.svg);
+}
+
+/* Mixin for pulsing banner since we need to include in several different contexts */
+@mixin shiny-page-busy {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 3px;
+  content: ""; /* Used in a ::after context */
+  animation-name: busy-page-pulse;
+  animation-duration: 20s;
+  animation-iteration-count: infinite;
+  background: linear-gradient(45deg, #fff, #505050, #007bc2, #74149c, #007bc2, #505050, #fff);
+  background-size: 800%;
+}
+
+[data-shiny-busy-indicator-types*="spinners"] {
+  .recalculating {
+    position: relative;
+
+    &::after {
+      position: absolute;
+
+      /* Spinner options */
+      --_shiny-spinner-mask-img: var(--shiny-spinner-mask-img, var(--_shiny-spinner-type-tadpole));
+      --_shiny-spinner-color: var(--shiny-spinner-color, var(--bs-primary, #007bc2));
+      --_shiny-spinner-size: var(--shiny-spinner-size, 40px);
+      --_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.5s);
+      --_shiny-spinner-animation: var(--shiny-spinner-animation, shiny-busy-spinner-spin);
+
+      /* Apply the spinner type as a mask */
+      mask-image: var(--_shiny-spinner-mask-img);
+      mask-position: center;
+      mask-size: contain;
+      mask-repeat: no-repeat;
+      -webkit-mask-image: var(--_shiny-spinner-mask-img);
+      -webkit-mask-position: center;
+      -webkit-mask-size: contain;
+      -webkit-mask-repeat: no-repeat;
+
+      /* Color, sizing, & positioning */
+      background: var(--_shiny-spinner-color);
+      width: var(--_shiny-spinner-size);
+      height: var(--_shiny-spinner-size);
+      inset: calc(50% - var(--_shiny-spinner-size) / 2);
+
+      /* Animation */
+      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);
+
+      content: "";
+      scale: 0;
+    }
+
+    /*
+      shiny.css puts `opacity: 0.3` on .recalculating, which unfortunately applies to
+      the spinner. Undo that, but still apply (smaller) opacity to immediate children
+      that aren't recalculating.
+    */
+    opacity: 1;
+    > *:not(.recalculating) {
+      opacity: 0.2;
+    }
+
+    /*
+      Disable spinner on uiOutput() mainly because (for other reasons) it has
+      `display:contents`, which breaks the ::after positioning.
+      Note that, even if we could position it, we'd probably want to disable it
+      if it has recalculating children.
+    */
+    &.shiny-html-output::after {
+      display: none;
+    }
+  }
+}
+
+/* Pulsing page-level banner */
+[data-shiny-busy-indicator-types*="pulse"] {
+  &.shiny-busy,
+  &.shiny-not-yet-idle,
+  &:has(.recalculating) {
+    &::after {
+      @include shiny-page-busy;
+    }
+  }
+}
+
+/****************************************
+In cursor mode, if the page has anything recalculating, show progress cursor
+*****************************************/
+[data-shiny-busy-indicator-types*="cursor"] {
+  &.shiny-busy,
+  &.shiny-not-yet-idle,
+  &:has(.recalculating) {
+    cursor: progress;
+  }
+
+  /* Show a page-level spinner if on mobile */
+  @media (max-width: 767px) {
+    &.shiny-busy,
+    &.shiny-not-yet-idle,
+    &:has(.recalculating) {
+      &::after {
+        @include shiny-page-busy;
+      }
+    }
+  }
+}
+
+/* Keyframes behind most spinner types */
+@keyframes shiny-busy-spinner-spin {
+  0% {
+    scale: 1;
+    rotate: 0deg;
+  }
+  100% {
+    scale: 1;
+    rotate: 360deg;
+  }
+}
+
+/* For busy_indicators.spinner_options(type="bounce") */
+@keyframes shiny-busy-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;
+  }
+}
+
+/* Keyframes for the pulsing banner */
+@keyframes busy-page-pulse {
+  0% {
+    background-position: 0px 50%;
+  }
+
+  50% {
+    background-position: 100% 50%;
+  }
+
+  100% {
+    background-position: 0px 50%;
+  }
+}