docs: Warn against using ui.modal(fade=True) when showing/hiding too quickly

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `ui.Chat()` now correctly handles new `ollama.chat()` return value introduced in `ollama` v0.4. (#1787)
 
+* Updated documentation of `ui.modal()` and `ui.modal_remove()` now warn against using `ui.modal(fade=True)` when there's a chance of showing and hiding the modal within 500ms or less. (#1808)
+
 ## [1.2.1] - 2024-11-14
 
 ### Bug fixes

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

@@ -1,5 +1,6 @@
 from shiny import App, Inputs, Outputs, Session, reactive, ui
 
+MODEL_DELAY = 4
 
 def run_model(delay=10.0):
     import time
@@ -17,6 +18,7 @@ def the_modal():
         title="Running model",
         easy_close=False,
         footer=None,
+        fade=MODEL_DELAY > 1
     )
 
 
@@ -34,7 +36,7 @@ def do_run_model():
         # Show the modal, blocking interaction with the UI
         ui.modal_show(the_modal())
 
-        result = run_model(delay=4)
+        result = run_model(delay=MODEL_DELAY)
 
         # Now that we have model results, remove the modal
         # and update the model result reactive value

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

@@ -1,6 +1,7 @@
 from shiny import reactive
 from shiny.express import input, ui
 
+MODEL_DELAY=4
 
 def run_model(delay=10.0):
     import time
@@ -23,6 +24,7 @@ def the_modal():
         title="Running model",
         easy_close=False,
         footer=None,
+        fade=MODEL_DELAY > 1
     )
 
 
@@ -32,7 +34,7 @@ def do_run_model():
     # Show the modal, blocking interaction with the UI
     ui.modal_show(the_modal())
 
-    result = run_model(delay=4)
+    result = run_model(delay=MODEL_DELAY)
 
     # Now that we have model results, remove the modal
     # and update the model result reactive value

shiny/ui/_modal.py

@@ -94,7 +94,9 @@ def modal(
         ``modal_button()``, or from a call to ``modal_remove()`` on the server.
     fade
         If ``False``, the modal dialog will have no fade-in animation (it will simply
-        appear rather than fade in to view).
+        appear rather than fade in to view). When `fade=True`, be careful to avoid
+        showing and hiding the modal too quickly. Only show and hide the modal when the
+        intervening code takes at least 300 to 500ms to execute.
     **kwargs
         Attributes to be applied to the modal's body tag.
 
@@ -193,6 +195,10 @@ def modal_remove(session: Optional[Session] = None) -> None:
     Modals can also be removed manually by the user if a :func:`~shiny.ui.modal_button`
     is provided, or if the modal is created with `easy_close=True`.
 
+    Be careful to avoid showing and hiding the modal too quickly when using
+    `ui.modal(fade=True)`. The intervening code should take at least 300 to 500ms to
+    execute (i.e. longer than it takes for the fade animation to reveal the modal).
+
     Parameters
     ----------
     session