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

docs/_quartodoc-core.yml

@@ -166,7 +166,7 @@ quartodoc:
         - ui.update_text
         - name: ui.update_text_area
           dynamic: "shiny.ui.update_text"
-        - ui.update_navs
+        - ui.update_navset
         - ui.update_action_button
         - ui.update_action_link
         - ui.update_task_button

docs/_quartodoc-express.yml

@@ -126,7 +126,7 @@ quartodoc:
         - express.ui.update_numeric
         - express.ui.update_text
         - express.ui.update_text_area
-        - express.ui.update_navs
+        - express.ui.update_navset
         - express.ui.update_action_button
         - express.ui.update_action_link
         - express.ui.update_task_button

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_navs/app-core.py → shiny/api-examples/update_navset/app-core.py

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

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

@@ -15,4 +15,4 @@
 
 @reactive.effect
 def _():
-    ui.update_navs("inTabset", selected="panel" + str(input.controller()))
+    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,22 +144,22 @@ 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
     @reactive.event(input.show_tab)
     def _():
         ui.update_nav_panel("tabset_id", target="Foo", method="show")
-        ui.update_navs("tabset_id", selected="Foo")
+        ui.update_navset("tabset_id", selected="Foo")
     ```
 
     See Also
     --------
     ~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/ai_generated_apps/bookmark/navsets/app-hidden.py

@@ -42,7 +42,7 @@ def _():
             next_letter = letters[current_idx % len(letters)]
             next_id = f"{navset_fn_id}_{next_letter}"
 
-            ui.update_navs(navset_fn_id, selected=next_id)
+            ui.update_navset(navset_fn_id, selected=next_id)
 
     for navset_variant, params in navset_configs[navset_name].items():
         make_navset(navset_variant, **params.copy())

tests/playwright/examples/example_apps.py

@@ -47,6 +47,7 @@ def get_apps(path: str) -> typing.List[str]:
     "ShinyDeprecationWarning:",
     "shiny.render.transformer.output_transformer()",
 ]
+
 express_warnings = ["Detected Shiny Express app. "]
 app_allow_shiny_errors: typing.Dict[
     str, typing.Union[Literal[True], typing.List[str]]
@@ -235,8 +236,8 @@ def on_console_msg(msg: ConsoleMessage) -> None:
                 print("\nshort_app_path: " + short_app_path)
                 print("\napp_allowable_errors :")
                 print("\n".join(app_allowable_errors))
-                print("\nError lines remaining:")
-                print("\n".join(error_lines))
+                # The below can be used to get the exact lines needed to update the `app_allow_*_errors()` objects above
+                print("Unignored remaining lines in raw format: ", 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)