Deprecate nav() in favor of nav_panel() (#876)

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Other changes
 
+* Closed #492: `shiny.ui.nav()` is now deprecated in favor of the more aptly named `shiny.ui.nav_panel()` (#876).
 * Update penguins example to credit Allison Horst and drop usage of `shiny.experimental` (#798).
 
 * `as_fillable_container()` and `as_fill_item()` no longer mutate the `Tag` object that was passed in. Instead, it returns a new `Tag` object. Also closed #856: these functions now put the `html-fill-container` and `html-fill-item` CSS classes last, instead of first. (#862)

docs/_quartodoc.yml

@@ -26,7 +26,7 @@ quartodoc:
         - express.layout.accordion_panel
         - express.layout.navset
         - express.layout.navset_card
-        - express.layout.nav
+        - express.layout.nav_panel
         - express.layout.page_fluid
         - express.layout.page_fixed
         - express.layout.page_fillable
@@ -87,10 +87,10 @@ quartodoc:
     - title: Navigation (tab) panels
       desc: Create segments of UI content.
       contents:
-        - ui.nav
-        - ui.nav_control
+        - ui.nav_panel
         - ui.nav_spacer
         - ui.nav_menu
+        - ui.nav_control
         - ui.navset_bar
         - ui.navset_tab
         - ui.navset_pill
@@ -306,6 +306,7 @@ quartodoc:
       contents:
         - ui.panel_main
         - ui.panel_sidebar
+        - ui.nav
     - title: Experimental
       desc: "These methods are under consideration and are considered unstable. However, if there is a method you are excited about, please let us know!"
       contents:

examples/event/app.py

@@ -12,12 +12,12 @@
       """
     ),
     ui.navset_card_tab(
-        ui.nav(
+        ui.nav_panel(
             "Sync",
             ui.input_action_button("btn", "Click me"),
             ui.output_ui("btn_value"),
         ),
-        ui.nav(
+        ui.nav_panel(
             "Async",
             ui.input_action_button("btn_async", "Click me"),
             ui.output_ui("btn_async_value"),

examples/express/nav_app.py

@@ -6,10 +6,10 @@
 
 with layout.layout_column_wrap(width=1 / 2):
     with layout.navset():
-        with layout.nav(title="One"):
+        with layout.nav_panel(title="One"):
             ui.input_slider("n", "N", 1, 100, 50)
 
-        with layout.nav(title="Two"):
+        with layout.nav_panel(title="Two"):
 
             @render.plot
             def histogram():
@@ -18,10 +18,10 @@ def histogram():
                 plt.hist(x, input.n(), density=True)
 
     with layout.navset_card():
-        with layout.nav(title="One"):
+        with layout.nav_panel(title="One"):
             ui.input_slider("n2", "N", 1, 100, 50)
 
-        with layout.nav(title="Two"):
+        with layout.nav_panel(title="Two"):
 
             @render.plot
             def histogram2():

examples/inputs-update/app.py

@@ -78,8 +78,8 @@
                 ),
             ),
             ui.navset_tab(
-                ui.nav("panel1", ui.h2("This is the first panel.")),
-                ui.nav("panel2", ui.h2("This is the second panel.")),
+                ui.nav_panel("panel1", ui.h2("This is the first panel.")),
+                ui.nav_panel("panel2", ui.h2("This is the second panel.")),
                 id="inTabset",
             ),
         ),

examples/static_plots/app.py

@@ -8,7 +8,7 @@
 
 nav = ui.navset_pill_list(
     ui.nav_control(ui.p("Choose a package", class_="lead text-center")),
-    ui.nav(
+    ui.nav_panel(
         "Plotnine",
         ui.output_plot("plotnine"),
         ui.div(
@@ -27,7 +27,7 @@
             ),
         ),
     ),
-    ui.nav(
+    ui.nav_panel(
         "Seaborn",
         ui.output_plot("seaborn"),
         ui.div(
@@ -36,11 +36,11 @@
             ui.input_slider("cov", "Co-variance", min=0, max=1, value=0.4),
         ),
     ),
-    ui.nav("Pandas", ui.output_plot("pandas")),
-    ui.nav("Holoviews", ui.output_plot("holoviews", height="600px")),
-    ui.nav("xarray", ui.output_plot("xarray")),
-    ui.nav("geopandas", ui.output_plot("geopandas")),
-    ui.nav("missingno", ui.output_plot("missingno")),
+    ui.nav_panel("Pandas", ui.output_plot("pandas")),
+    ui.nav_panel("Holoviews", ui.output_plot("holoviews", height="600px")),
+    ui.nav_panel("xarray", ui.output_plot("xarray")),
+    ui.nav_panel("geopandas", ui.output_plot("geopandas")),
+    ui.nav_panel("missingno", ui.output_plot("missingno")),
     widths=(2, 10),
     well=False,
 )

shiny/api-examples/nav/app.py

@@ -6,9 +6,9 @@
 
 def nav_controls(prefix: str) -> List[NavSetArg]:
     return [
-        ui.nav("a", prefix + ": tab a content"),
-        ui.nav("b", prefix + ": tab b content"),
-        ui.nav("c", prefix + ": tab c content"),
+        ui.nav_panel("a", prefix + ": tab a content"),
+        ui.nav_panel("b", prefix + ": tab b content"),
+        ui.nav_panel("c", prefix + ": tab c content"),
         ui.nav_spacer(),
         ui.nav_menu(
             "Links",

shiny/api-examples/navset_hidden/app.py

@@ -9,9 +9,9 @@
         ),
         ui.panel_main(
             ui.navset_hidden(
-                ui.nav(None, "Panel 1 content", value="panel1"),
-                ui.nav(None, "Panel 2 content", value="panel2"),
-                ui.nav(None, "Panel 3 content", value="panel3"),
+                ui.nav_panel(None, "Panel 1 content", value="panel1"),
+                ui.nav_panel(None, "Panel 2 content", value="panel2"),
+                ui.nav_panel(None, "Panel 3 content", value="panel3"),
                 id="hidden_tabs",
             ),
         ),

shiny/api-examples/update_navs/app.py

@@ -7,9 +7,9 @@
         ),
         ui.panel_main(
             ui.navset_card_tab(
-                ui.nav("Panel 1", "Panel 1 content", value="panel1"),
-                ui.nav("Panel 2", "Panel 2 content", value="panel2"),
-                ui.nav("Panel 3", "Panel 3 content", value="panel3"),
+                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",
             ),
         ),

shiny/express/layout.py

@@ -28,7 +28,7 @@
     "accordion_panel",
     "navset",
     "navset_card",
-    "nav",
+    "nav_panel",
     "page_fluid",
     "page_fixed",
     "page_fillable",
@@ -670,7 +670,7 @@ def navset_card(
     )
 
 
-def nav(
+def nav_panel(
     title: TagChild,
     *,
     value: Optional[str] = None,
@@ -695,7 +695,7 @@ def nav(
         An icon to appear inline with the button/link.
     """
     return RecallContextManager(
-        ui.nav,
+        ui.nav_panel,
         args=(title,),
         kwargs=dict(
             value=value,

shiny/templates/app-templates/multi-page/modules.py

@@ -8,7 +8,7 @@
 
 @module.ui
 def training_ui():
-    return ui.nav(
+    return ui.nav_panel(
         "Training Dashboard",
         ui.layout_columns(
             ui.card(
@@ -49,7 +49,7 @@ def metric():
 
 @module.ui
 def data_view_ui():
-    return ui.nav(
+    return ui.nav_panel(
         "View Data",
         ui.layout_columns(
             ui.value_box(

shiny/ui/__init__.py

@@ -87,7 +87,7 @@
 from ._markdown import markdown
 from ._modal import modal_button, modal, modal_show, modal_remove
 from ._navs import (
-    nav,
+    nav_panel,
     nav_menu,
     nav_control,
     nav_spacer,
@@ -103,6 +103,7 @@
     # Deprecated
     navset_pill_card,
     navset_tab_card,
+    nav,
 )
 from ._notification import notification_show, notification_remove
 from ._output import (
@@ -269,7 +270,7 @@
     "modal_show",
     "modal_remove",
     # _navs
-    "nav",
+    "nav_panel",
     "nav_menu",
     "nav_control",
     "nav_spacer",
@@ -285,6 +286,7 @@
     # # Deprecated
     "navset_pill_card",
     "navset_tab_card",
+    "nav",
     # _notification
     "notification_show",
     "notification_remove",