chore: deprecate update_navs

CHANGELOG.md

@@ -27,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changes
 
+* `ui.update_navs()` has been deprecated in favor of `ui.update_navset()`. (#2047)
+
 * `express.ui.insert_accordion_panel()`'s function signature has changed to be more ergonomic. Now you can pass the `panel_title` and `panel_contents` directly instead of `ui.hold()`ing the `ui.accordion_panel()` context manager. (#2042)
 
 ### Improvements

examples/inputs-update/app.py

@@ -185,7 +185,7 @@ def _():
         # Tabset input =============================================
         # Change the selected tab.
         # The tabsetPanel must have been created with an 'id' argument
-        ui.update_navs("inTabset", selected="panel2" if c_num % 2 else "panel1")
+        ui.update_navset("inTabset", selected="panel2" if c_num % 2 else "panel1")
 
 
 app = App(app_ui, server, debug=True)

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

@@ -19,7 +19,7 @@ def server(input: Inputs, output: Outputs, session: Session):
     @reactive.effect
     @reactive.event(input.controller)
     def _():
-        ui.update_navs("hidden_tabs", selected="panel" + str(input.controller()))
+        ui.update_navset("hidden_tabs", selected="panel" + str(input.controller()))
 
 
 app = App(app_ui, server)

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

@@ -16,4 +16,4 @@
 @reactive.effect
 @reactive.event(input.controller)
 def _():
-    ui.update_navs("hidden_tabs", selected="panel" + str(input.controller()))
+    ui.update_navset("hidden_tabs", selected="panel" + str(input.controller()))

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

@@ -0,0 +1,20 @@
+from shiny import App, Inputs, Outputs, Session, reactive, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(ui.input_slider("controller", "Controller", min=1, max=3, value=1)),
+    ui.navset_card_tab(
+        ui.nav_panel("Panel 1", "Panel 1 content", value="panel1"),
+        ui.nav_panel("Panel 2", "Panel 2 content", value="panel2"),
+        ui.nav_panel("Panel 3", "Panel 3 content", value="panel3"),
+        id="inTabset",
+    ),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @reactive.effect
+    def _():
+        ui.update_navset("inTabset", selected="panel" + str(input.controller()))
+
+
+app = App(app_ui, server)

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

@@ -0,0 +1,18 @@
+from shiny import reactive
+from shiny.express import input, ui
+
+with ui.sidebar():
+    ui.input_slider("controller", "Controller", min=1, max=3, value=1)
+
+with ui.navset_card_tab(id="inTabset"):
+    with ui.nav_panel("Panel 1", value="panel1"):
+        "Panel 1 content"
+    with ui.nav_panel("Panel 2", value="panel2"):
+        "Panel 2 content"
+    with ui.nav_panel("Panel 3", value="panel3"):
+        "Panel 3 content"
+
+
+@reactive.effect
+def _():
+    ui.update_navset("inTabset", selected="panel" + str(input.controller()))

shiny/express/ui/__init__.py

@@ -94,6 +94,7 @@
     update_date_range,
     update_nav_panel,
     update_navs,
+    update_navset,
     update_numeric,
     update_popover,
     update_radio_buttons,
@@ -246,6 +247,7 @@
     "update_text",
     "update_text_area",
     "update_navs",
+    "update_navset",
     "update_tooltip",
     "update_popover",
     "insert_ui",

shiny/express/ui/_cm_components.py

@@ -1203,7 +1203,7 @@ def nav_panel(
     value
         The value of the item. This is used to determine whether the item is active
         (when an ``id`` is provided to the nav container), programmatically select the
-        item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the
+        item (e.g., :func:`~shiny.ui.update_navset`), and/or be provided to the
         ``selected`` argument of the navigation container (e.g.,
         :func:`~shiny.ui.navset_tab`).
     icon
@@ -1249,7 +1249,7 @@ def nav_menu(
     value
         The value of the item. This is used to determine whether the item is active
         (when an ``id`` is provided to the nav container), programmatically select the
-        item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the
+        item (e.g., :func:`~shiny.ui.update_navset`), and/or be provided to the
         ``selected`` argument of the navigation container (e.g.,
         :func:`~shiny.ui.navset_tab`).
     icon

shiny/express/ui/_insert.py

@@ -111,7 +111,7 @@ def insert_nav_panel(
     value
         The value of the panel. Use this value to determine whether the panel is active
         (when an `id` is provided to the nav container) or to programmatically
-        select the item (e.g., :func:`~shiny.ui.update_navs`). You can also
+        select the item (e.g., :func:`~shiny.ui.update_navset`). You can also
         provide the value to the `selected` argument of the navigation container
         (e.g., :func:`~shiny.ui.navset_tab`).
     icon

shiny/ui/__init__.py

@@ -94,6 +94,7 @@
     update_date,
     update_date_range,
     update_navs,
+    update_navset,
     update_numeric,
     update_popover,
     update_radio_buttons,
@@ -273,6 +274,7 @@
     "update_text",
     "update_text_area",
     "update_navs",
+    "update_navset",
     "update_tooltip",
     "update_popover",
     # _insert

shiny/ui/_input_update.py

@@ -16,6 +16,7 @@
     "update_text",
     "update_text_area",
     "update_navs",
+    "update_navset",
 )
 
 import json
@@ -27,6 +28,7 @@
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 
+from .._deprecated import warn_deprecated
 from .._docstring import add_example, doc_format, no_example
 from .._typing_extensions import NotRequired, TypedDict
 from .._utils import drop_none
@@ -1054,6 +1056,45 @@ def update_navs(
     ----
     {note}
 
+    See Also
+    --------
+    * :func:`~shiny.ui.navset_tab`
+    * :func:`~shiny.ui.navset_pill`
+    * :func:`~shiny.ui.page_navbar`
+    """
+    warn_deprecated(
+        "`shiny.ui.update_navs()` has been superseded by `shiny.ui.update_navset()` and will be removed in the near future."
+    )
+
+    update_navset(
+        id=id,
+        selected=selected,
+        session=session,
+    )
+
+
+@add_example()
+@doc_format(note=_note)
+def update_navset(
+    id: str, selected: Optional[str] = None, session: Optional[Session] = None
+) -> None:
+    """
+    Change the value of a navs container on the client.
+
+    Parameters
+    ----------
+    id
+        An input id.
+    selected
+        The values that should be initially selected, if any.
+    session
+        A :class:`~shiny.Session` instance. If not provided, it is inferred via
+        :func:`~shiny.session.get_current_session`.
+
+    Note
+    ----
+    {note}
+
     See Also
     --------
     * :func:`~shiny.ui.navset_tab`

shiny/ui/_navs.py

@@ -131,7 +131,7 @@ def nav_panel(
     value
         The value of the item. Use this value to determine whether the item is active
         (when an ``id`` is provided to the nav container) or to programmatically
-        select the item (e.g., :func:`~shiny.ui.update_navs`). You can also
+        select the item (e.g., :func:`~shiny.ui.update_navset`). You can also
         provide the value to the ``selected`` argument of the navigation container
         (e.g., :func:`~shiny.ui.navset_tab`).
     icon
@@ -334,7 +334,7 @@ def nav_menu(
     value
         The value of the item. Use this value to determine whether the item is active
         (when an ``id`` is provided to the nav container) or to programmatically
-        select the item (e.g., :func:`~shiny.ui.update_navs`). You can also
+        select the item (e.g., :func:`~shiny.ui.update_navset`). You can also
         provide the value to the ``selected`` argument of the navigation container
         (e.g., :func:`~shiny.ui.navset_tab`).
     icon

shiny/ui/_navs_dynamic.py

@@ -144,7 +144,7 @@ def update_nav_panel(
 
     Note
     ----
-    On reveal, the `nav_panel` will not be the active tab. To change the active tab, use :func:`~shiny.ui.update_navs()`
+    On reveal, the `nav_panel` will not be the active tab. To change the active tab, use :func:`~shiny.ui.update_navset()`
     For example:
     ```python
     @reactive.effect
@@ -159,7 +159,7 @@ def _():
     ~shiny.ui.insert_nav_panel
     ~shiny.ui.remove_nav_panel
     ~shiny.ui.nav_panel
-    ~shiny.ui.update_navs
+    ~shiny.ui.update_navset
     """
 
     session = require_active_session(session)

tests/playwright/examples/example_apps.py

@@ -47,6 +47,13 @@ def get_apps(path: str) -> typing.List[str]:
     "ShinyDeprecationWarning:",
     "shiny.render.transformer.output_transformer()",
 ]
+
+nav_panel_errors = [
+    "ShinyDeprecationWarning:",
+    "ShinyDeprecationWarning: `ShinyDeprecationWarning: `shiny.ui.update_navs()` has been superseded by `shiny.ui.update_navset()` and will be removed in the near future.",
+    '  ui.update_navs("inTabset", selected="panel2" if c_num % 2 else "panel1")',
+    '  ui.update_navs("inTabset", selected="panel" + str(input.controller()))',
+]
 express_warnings = ["Detected Shiny Express app. "]
 app_allow_shiny_errors: typing.Dict[
     str, typing.Union[Literal[True], typing.List[str]]
@@ -68,6 +75,7 @@ def get_apps(path: str) -> typing.List[str]:
     "examples/brownian": [*output_transformer_errors],
     "examples/model-score": [*output_transformer_errors],
     "deploys/plotly": [*output_transformer_errors],
+    "api-examples/update_navs": [*nav_panel_errors],
 }
 app_allow_external_errors: typing.List[str] = [
     # TODO-garrick-future: Remove after fixing sidebar max_height_mobile warning
@@ -237,6 +245,7 @@ def on_console_msg(msg: ConsoleMessage) -> None:
                 print("\n".join(app_allowable_errors))
                 print("\nError lines remaining:")
                 print("\n".join(error_lines))
+                print("Error lines: ", error_lines)
             assert len(error_lines) == 0
 
         # Check for JavaScript errors

tests/playwright/shiny/bugs/0696-resolve-id/app.py

@@ -458,12 +458,12 @@ def update_session(
                 if session.input.tooltip() != on_off:
                     ui.update_tooltip("tooltip", show=on_off)
 
-            ui.update_navs("navset_bar", selected=letter)
-            ui.update_navs("navset_card_pill", selected=letter)
-            ui.update_navs("navset_card_tab", selected=letter)
-            ui.update_navs("navset_hidden", selected=letter)
-            ui.update_navs("navset_pill", selected=letter)
-            ui.update_navs("navset_tab", selected=letter)
+            ui.update_navset("navset_bar", selected=letter)
+            ui.update_navset("navset_card_pill", selected=letter)
+            ui.update_navset("navset_card_tab", selected=letter)
+            ui.update_navset("navset_hidden", selected=letter)
+            ui.update_navset("navset_pill", selected=letter)
+            ui.update_navset("navset_tab", selected=letter)
 
     module_keys = (
         ("update_global", ""),

tests/playwright/shiny/components/nav/navset_hidden_kitchensink/app.py

@@ -31,10 +31,10 @@
 @reactive.effect
 @reactive.event(input.controller1)
 def _():
-    ui.update_navs("hidden_tabs1", selected="panel" + str(input.controller1()))
+    ui.update_navset("hidden_tabs1", selected="panel" + str(input.controller1()))
 
 
 @reactive.effect
 @reactive.event(input.controller2)
 def _():
-    ui.update_navs("hidden_tabs2", selected="panel" + str(input.controller2()))
+    ui.update_navset("hidden_tabs2", selected="panel" + str(input.controller2()))

tests/playwright/shiny/components/navset_hidden/app.py

@@ -21,7 +21,7 @@ def server(input: Inputs, output: Outputs, session: Session):
     @reactive.effect
     @reactive.event(input.controller)
     def _():
-        ui.update_navs("hidden_tabs", selected="panel" + str(input.controller()))
+        ui.update_navset("hidden_tabs", selected="panel" + str(input.controller()))
 
 
 app = App(app_ui, server)