feat: Add theme argument to page functions (#1334)

Author: gadenbuie

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added support for creating modules using Shiny Express syntax, and using modules in Shiny Express apps. (#1220)
 
+* `ui.page_*()` functions gain a `theme` argument that allows you to replace the Bootstrap CSS file with a new CSS file. `theme` can be a local CSS file, a URL, or a [shinyswatch](https://posit-dev.github.io/py-shinyswatch) theme. In Shiny Express apps, `theme` can be set via `express.ui.page_opts()`. (#1334)
+
 ### Bug fixes
 
 ### Other changes

shiny/api-examples/theme/_purgecss.py

@@ -0,0 +1,63 @@
+# This file is used to create a minimal Bootstrap CSS file based on the Minty
+# Bootstwatch theme for use in the example apps.
+
+# NOTE: This script requires the `purgecss` package to be installed.
+#       You can install it with `npm install -g purgecss`.
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import shinyswatch
+
+from shiny import ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_numeric("n", "N", min=0, max=100, value=20),
+        title="Parameters",
+    ),
+    ui.h2("Output"),
+    ui.output_text_verbatim("txt"),
+    ui.markdown(
+        """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+    ),
+    shinyswatch.theme.minty,
+    title="Theme Example",
+)
+
+# If __file__ is not defined, use the current working directory
+if not globals().get("__file__"):
+    __file__ = Path.cwd() / "_purgecss.py"
+
+save_dir = Path(__file__).parent / "output"
+if save_dir.exists():
+    shutil.rmtree(save_dir)
+save_dir.mkdir()
+app_ui.save_html(save_dir / "index.html", include_version=False)
+
+purged_dir = Path(__file__).parent / "css"
+if purged_dir.exists():
+    shutil.rmtree(purged_dir)
+purged_dir.mkdir(exist_ok=True)
+
+args = [
+    "purgecss",
+    "--css",
+    "output/lib/shinyswatch-css/bootswatch.min.css",
+    "--content",
+    "output/index.html",
+    "--output",
+    "css",
+]
+
+subprocess.run(args)
+
+(purged_dir / "bootswatch.min.css").rename(purged_dir / "bootswatch-minty.min.css")
+
+if True:
+    shutil.rmtree(save_dir)

shiny/api-examples/theme/app-core-remote.py

@@ -0,0 +1,28 @@
+from shiny import App, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_numeric("n", "N", min=0, max=100, value=20),
+        title="Parameters",
+    ),
+    ui.h2("Output"),
+    ui.output_text_verbatim("txt"),
+    ui.markdown(
+        """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+    ),
+    title="Theme Example",
+    theme="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sketchy/bootstrap.min.css",
+)
+
+
+def server(input, output, session):
+    @render.text
+    def txt():
+        return f"n*2 is {input.n() * 2}"
+
+
+app = App(app_ui, server)

shiny/api-examples/theme/app-core-shinyswatch.py

@@ -0,0 +1,30 @@
+import shinyswatch
+
+from shiny import App, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_numeric("n", "N", min=0, max=100, value=20),
+        title="Parameters",
+    ),
+    ui.h2("Output"),
+    ui.output_text_verbatim("txt"),
+    ui.markdown(
+        """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+    ),
+    title="Theme Example",
+    theme=shinyswatch.theme.slate(),
+)
+
+
+def server(input, output, session):
+    @render.text
+    def txt():
+        return f"n*2 is {input.n() * 2}"
+
+
+app = App(app_ui, server)

shiny/api-examples/theme/app-core.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+from shiny import App, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_numeric("n", "N", min=0, max=100, value=20),
+        title="Parameters",
+    ),
+    ui.h2("Output"),
+    ui.output_text_verbatim("txt"),
+    ui.markdown(
+        """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+    ),
+    title="Theme Example",
+    # theme=shinyswatch.theme.slate,
+    # theme="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css",
+    theme=Path(__file__).parent / "css" / "bootswatch-minty.min.css",
+)
+
+
+def server(input, output, session):
+    @render.text
+    def txt():
+        return f"n*2 is {input.n() * 2}"
+
+
+app = App(app_ui, server)

shiny/api-examples/theme/app-express-remote.py

@@ -0,0 +1,25 @@
+from shiny.express import input, render, ui
+
+ui.page_opts(
+    title="Theme Example",
+    theme="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sketchy/bootstrap.min.css",
+)
+
+with ui.sidebar(title="Parameters"):
+    ui.input_numeric("n", "N", min=0, max=100, value=20)
+
+ui.h2("Output")
+
+
+@render.code
+def txt():
+    return f"n*2 is {input.n() * 2}"
+
+
+ui.markdown(
+    """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+)

shiny/api-examples/theme/app-express-shinyswatch.py

@@ -0,0 +1,27 @@
+import shinyswatch
+
+from shiny.express import input, render, ui
+
+ui.page_opts(
+    title="Theme Example",
+    theme=shinyswatch.theme.slate,
+)
+
+with ui.sidebar(title="Parameters"):
+    ui.input_numeric("n", "N", min=0, max=100, value=20)
+
+ui.h2("Output")
+
+
+@render.code
+def txt():
+    return f"n*2 is {input.n() * 2}"
+
+
+ui.markdown(
+    """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+)

shiny/api-examples/theme/app-express.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+from shiny.express import input, render, ui
+
+ui.page_opts(
+    title="Theme Example",
+    theme=Path(__file__).parent / "css" / "bootswatch-minty.min.css",
+)
+
+with ui.sidebar(title="Parameters"):
+    ui.input_numeric("n", "N", min=0, max=100, value=20)
+
+ui.h2("Output")
+
+
+@render.code
+def txt():
+    return f"n*2 is {input.n() * 2}"
+
+
+ui.markdown(
+    """
+**AI-generated filler text.** In the world of exotic fruits, the durian stands out with its spiky exterior and strong odor. Despite its divisive smell, many people are drawn to its rich, creamy texture and unique flavor profile. This tropical fruit is often referred to as the "king of fruits" in various Southeast Asian countries.
+
+Durians are known for their large size and thorn-covered husk, which requires careful handling. The flesh inside can vary in color from pale yellow to deep orange, with a custard-like consistency that melts in your mouth. Some describe its taste as a mix of sweet, savory, and creamy, while others find it overpowering and pungent.
+"""
+)