From 57f6ba5e3983b6e8c1ffb6b1225fb06313a78959 Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Thu, 17 Aug 2023 16:26:52 -0400
Subject: [PATCH] chore(api)!: Rename `ui.navset_pill_card` ->
 `ui.navset_card_pill` and `ui.navset_tab_card` -> `ui.navset_card_tab` (#681)

---
 CHANGELOG.md                          |   9 ++-
 docs/_quartodoc.yml                   |   8 +-
 examples/event/app.py                 |   2 +-
 shiny/api-examples/nav/app.py         |   8 +-
 shiny/api-examples/update_navs/app.py |   2 +-
 shiny/experimental/e2e/navbar/app.py  |  12 +--
 shiny/experimental/ui/__init__.py     |   6 +-
 shiny/experimental/ui/_navs.py        |  16 ++--
 shiny/experimental/ui/_sidebar.py     |   6 +-
 shiny/ui/__init__.py                  |   9 ++-
 shiny/ui/_navs.py                     | 103 ++++++++++++++++++++------
 tests/pytest/test_navs.py             |   2 +-
 12 files changed, 125 insertions(+), 58 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 98544f820..0116d3032 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,13 +8,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [UNRELEASED]
 
+### API changes
+
+* Renamed `shiny.ui.navset_pill_card` to `shiny.ui.navset_card_pill`. `shiny.ui.navset_pill_card` will throw a deprecated warning (#492).
+* Renamed `shiny.ui.navset_tab_card` to `shiny.ui.navset_card_tab`. `shiny.ui.navset_tab_card` will throw a deprecated warning (#492).
+* Renamed `shiny.experimental.ui.navset_pill_card` to `shiny.experimental.ui.navset_card_pill` (#492).
+* Renamed `shiny.experimental.ui.navset_tab_card` to `shiny.experimental.ui.navset_card_tab` (#492).
+
 ### New features
 
 * Added `shiny.render.renderer_components` decorator to help create new output renderers. (#621)
 
 ### Bug fixes
 
-Fixes #646: Wrap bare value box value in `<p />` tags. (#668)
+* Fixes #646: Wrap bare value box value in `<p />` tags. (#668)
 
 ### Other changes
 
diff --git a/docs/_quartodoc.yml b/docs/_quartodoc.yml
index aaa17d8e1..6d032d539 100644
--- a/docs/_quartodoc.yml
+++ b/docs/_quartodoc.yml
@@ -77,9 +77,9 @@ quartodoc:
         - ui.nav_spacer
         - ui.nav_menu
         - ui.navset_tab
-        - ui.navset_tab_card
+        - ui.navset_card_tab
         - ui.navset_pill
-        - ui.navset_pill_card
+        - ui.navset_card_pill
         - ui.navset_pill_list
         - ui.navset_hidden
     - title: UI panels
@@ -247,8 +247,8 @@ quartodoc:
             - experimental.ui.layout_sidebar
             - experimental.ui.page_navbar
             - experimental.ui.navset_bar
-            - experimental.ui.navset_tab_card
-            - experimental.ui.navset_pill_card
+            - experimental.ui.navset_card_tab
+            - experimental.ui.navset_card_pill
             - experimental.ui.sidebar_toggle
             - experimental.ui.panel_main
             - experimental.ui.panel_sidebar
diff --git a/examples/event/app.py b/examples/event/app.py
index c96f7ca85..20adf5d25 100644
--- a/examples/event/app.py
+++ b/examples/event/app.py
@@ -11,7 +11,7 @@
       print the number of clicks in the console twice.
       """
     ),
-    ui.navset_tab_card(
+    ui.navset_card_tab(
         ui.nav(
             "Sync",
             ui.input_action_button("btn", "Click me"),
diff --git a/shiny/api-examples/nav/app.py b/shiny/api-examples/nav/app.py
index 65c9bea3c..ed255589c 100644
--- a/shiny/api-examples/nav/app.py
+++ b/shiny/api-examples/nav/app.py
@@ -53,10 +53,10 @@ def nav_controls(prefix: str) -> List[NavSetArg]:
         ui.navset_tab(*nav_controls("navset_tab()")),
         ui.h4("navset_pill()"),
         ui.navset_pill(*nav_controls("navset_pill()")),
-        ui.h4("navset_tab_card()"),
-        ui.navset_tab_card(*nav_controls("navset_tab_card()")),
-        ui.h4("navset_pill_card()"),
-        ui.navset_pill_card(*nav_controls("navset_pill_card()")),
+        ui.h4("navset_card_tab()"),
+        ui.navset_card_tab(*nav_controls("navset_card_tab()")),
+        ui.h4("navset_card_pill()"),
+        ui.navset_card_pill(*nav_controls("navset_card_pill()")),
         ui.h4("navset_pill_list()"),
         ui.navset_pill_list(*nav_controls("navset_pill_list()")),
     )
diff --git a/shiny/api-examples/update_navs/app.py b/shiny/api-examples/update_navs/app.py
index de5961508..e319eba51 100644
--- a/shiny/api-examples/update_navs/app.py
+++ b/shiny/api-examples/update_navs/app.py
@@ -6,7 +6,7 @@
             ui.input_slider("controller", "Controller", min=1, max=3, value=1)
         ),
         ui.panel_main(
-            ui.navset_tab_card(
+            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"),
diff --git a/shiny/experimental/e2e/navbar/app.py b/shiny/experimental/e2e/navbar/app.py
index a9cf2d9e1..78761a44b 100644
--- a/shiny/experimental/e2e/navbar/app.py
+++ b/shiny/experimental/e2e/navbar/app.py
@@ -51,14 +51,14 @@ def nav_items(prefix: str) -> list[NavSetArg]:
         ),
         footer=ui.div(
             {"style": "width:80%; margin: 0 auto"},
-            ui.h4("navset_tab_card()"),
-            x.ui.navset_tab_card(
-                *nav_items("navset_tab_card()"),
+            ui.h4("navset_card_tab()"),
+            x.ui.navset_card_tab(
+                *nav_items("navset_card_tab()"),
                 sidebar=my_sidebar,
             ),
-            ui.h4("navset_pill_card()"),
-            x.ui.navset_pill_card(
-                *nav_items("navset_pill_card()"),
+            ui.h4("navset_card_pill()"),
+            x.ui.navset_card_pill(
+                *nav_items("navset_card_pill()"),
                 sidebar=my_sidebar,
             ),
             # Do not include `navset_bar()` in example. Ok for testing only
diff --git a/shiny/experimental/ui/__init__.py b/shiny/experimental/ui/__init__.py
index 54005f500..6f46660dc 100644
--- a/shiny/experimental/ui/__init__.py
+++ b/shiny/experimental/ui/__init__.py
@@ -34,7 +34,7 @@
 )
 from ._input_text import input_text_area
 from ._layout import layout_column_wrap
-from ._navs import navset_bar, navset_pill_card, navset_tab_card
+from ._navs import navset_bar, navset_card_pill, navset_card_tab
 from ._output import output_image, output_plot, output_ui
 from ._page import page_fillable, page_navbar, page_sidebar
 from ._sidebar import (
@@ -70,8 +70,8 @@
     "page_navbar",
     # Navs
     "navset_bar",
-    "navset_tab_card",
-    "navset_pill_card",
+    "navset_card_tab",
+    "navset_card_pill",
     # Card
     "CardItem",
     "ImgContainer",
diff --git a/shiny/experimental/ui/_navs.py b/shiny/experimental/ui/_navs.py
index 5f9f169cd..b3b9e78f0 100644
--- a/shiny/experimental/ui/_navs.py
+++ b/shiny/experimental/ui/_navs.py
@@ -2,8 +2,8 @@
 
 __all__ = (
     "navset_bar",
-    "navset_tab_card",
-    "navset_pill_card",
+    "navset_card_tab",
+    "navset_card_pill",
 )
 
 import copy
@@ -194,7 +194,7 @@ def navset_card_body(content: Tag, sidebar: Optional[Sidebar] = None) -> CardIte
         return CardItem(content)
 
 
-def navset_tab_card(
+def navset_card_tab(
     *args: NavSetArg,
     id: Optional[str] = None,
     selected: Optional[str] = None,
@@ -229,7 +229,7 @@ def navset_tab_card(
     * ~shiny.experimental.ui.navset_bar
     * ~shiny.ui.navset_tab
     * ~shiny.ui.navset_pill
-    * ~shiny.experimental.ui.navset_pill_card
+    * ~shiny.experimental.ui.navset_card_pill
     * ~shiny.ui.navset_hidden
 
     Example
@@ -249,7 +249,7 @@ def navset_tab_card(
     )
 
 
-def navset_pill_card(
+def navset_card_pill(
     *args: NavSetArg,
     id: Optional[str] = None,
     selected: Optional[str] = None,
@@ -287,7 +287,7 @@ def navset_pill_card(
     * ~shiny.experimental.ui.navset_bar
     * ~shiny.ui.navset_tab
     * ~shiny.ui.navset_pill
-    * ~shiny.experimental.ui.navset_tab_card
+    * ~shiny.experimental.ui.navset_card_tab
     * ~shiny.ui.navset_hidden
 
     Example
@@ -533,8 +533,8 @@ def navset_bar(
     * ~shiny.ui.nav_spacer
     * ~shiny.ui.navset_tab
     * ~shiny.ui.navset_pill
-    * ~shiny.experimental.ui.navset_tab_card
-    * ~shiny.experimental.ui.navset_pill_card
+    * ~shiny.experimental.ui.navset_card_tab
+    * ~shiny.experimental.ui.navset_card_pill
     * ~shiny.ui.navset_hidden
 
     Example
diff --git a/shiny/experimental/ui/_sidebar.py b/shiny/experimental/ui/_sidebar.py
index 3933154a9..233186680 100644
--- a/shiny/experimental/ui/_sidebar.py
+++ b/shiny/experimental/ui/_sidebar.py
@@ -133,7 +133,7 @@ def sidebar(
 
     * :func:`~shiny.experimental.ui.layout_sidebar`
       * Creates a sidebar layout component which can be dropped inside any Shiny UI page method (e.g. :func:`~shiny.experimental.ui.page_fillable`) or :func:`~shiny.experimental.ui.card` context.
-    * :func:`~shiny.experimental.ui.navset_bar`, :func:`~shiny.experimental.ui.navset_tab_card`, and :func:`~shiny.experimental.ui.navset_pill_card`
+    * :func:`~shiny.experimental.ui.navset_bar`, :func:`~shiny.experimental.ui.navset_card_tab`, and :func:`~shiny.experimental.ui.navset_card_pill`
       * Creates a multi page/tab UI with a singular `sidebar()` (which is
         shown on every page/tab).
 
@@ -185,8 +185,8 @@ def sidebar(
     --------
     * :func:`~shiny.experimental.ui.layout_sidebar`
     * :func:`~shiny.experimental.ui.navset_bar`
-    * :func:`~shiny.experimental.ui.navset_tab_card`
-    * :func:`~shiny.experimental.ui.navset_pill_card`
+    * :func:`~shiny.experimental.ui.navset_card_tab`
+    * :func:`~shiny.experimental.ui.navset_card_pill`
     """
     # TODO-future; validate `open`, bg, fg, class_, max_height_mobile
 
diff --git a/shiny/ui/__init__.py b/shiny/ui/__init__.py
index 5a579ac11..9554ee305 100644
--- a/shiny/ui/__init__.py
+++ b/shiny/ui/__init__.py
@@ -59,12 +59,15 @@
     nav_control,
     nav_spacer,
     navset_tab,
-    navset_tab_card,
     navset_pill,
-    navset_pill_card,
+    navset_card_pill,
+    navset_card_tab,
     navset_pill_list,
     navset_hidden,
     navset_bar,
+    # Deprecated
+    navset_pill_card,
+    navset_tab_card,
 )
 from ._notification import notification_show, notification_remove
 from ._output import (
@@ -176,6 +179,8 @@
     "nav_spacer",
     "navset_tab",
     "navset_tab_card",
+    "navset_card_tab",
+    "navset_card_pill",
     "navset_pill",
     "navset_pill_card",
     "navset_pill_list",
diff --git a/shiny/ui/_navs.py b/shiny/ui/_navs.py
index e368f8be4..e5b7c9aa2 100644
--- a/shiny/ui/_navs.py
+++ b/shiny/ui/_navs.py
@@ -6,12 +6,15 @@
     "nav_control",
     "nav_spacer",
     "navset_tab",
-    "navset_tab_card",
+    "navset_card_tab",
     "navset_pill",
-    "navset_pill_card",
+    "navset_card_pill",
     "navset_pill_list",
     "navset_hidden",
     "navset_bar",
+    # Deprecated - 2023-08-15
+    "navset_pill_card",
+    "navset_tab_card",
 )
 
 import copy
@@ -20,6 +23,7 @@
 
 from htmltools import MetadataNode, Tag, TagChild, TagList, div, tags
 
+from .._deprecated import warn_deprecated
 from .._docstring import add_example
 from .._namespaces import resolve_id
 from .._utils import private_random_int
@@ -119,8 +123,8 @@ def nav(
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
     """
     if value is None:
@@ -160,8 +164,8 @@ def nav_control(*args: TagChild) -> Nav:
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
     Example
     -------
@@ -182,8 +186,8 @@ def nav_spacer() -> Nav:
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
 
     Example
@@ -315,8 +319,8 @@ def nav_menu(
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
     Example
     -------
@@ -409,8 +413,8 @@ def navset_tab(
     ~shiny.ui.nav_spacer
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
 
     Example
@@ -461,8 +465,8 @@ def navset_pill(
     ~shiny.ui.nav_spacer
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
 
     Example
@@ -513,9 +517,9 @@ def navset_hidden(
     ~shiny.ui.nav_control
     ~shiny.ui.nav_spacer
     ~shiny.ui.navset_tab
-    ~shiny.ui.navset_tab_card
+    ~shiny.ui.navset_card_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_pill_list
     ~shiny.ui.navset_bar
     """
@@ -560,7 +564,7 @@ def layout(self, nav: TagChild, content: TagChild) -> Tag:
             return card(self.header, content, self.footer, header=nav)
 
 
-def navset_tab_card(
+def navset_card_tab(
     *args: NavSetArg,
     id: Optional[str] = None,
     selected: Optional[str] = None,
@@ -594,7 +598,7 @@ def navset_tab_card(
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
 
     Example
@@ -613,7 +617,7 @@ def navset_tab_card(
     )
 
 
-def navset_pill_card(
+def navset_card_pill(
     *args: NavSetArg,
     id: Optional[str] = None,
     selected: Optional[str] = None,
@@ -650,7 +654,7 @@ def navset_pill_card(
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
+    ~shiny.ui.navset_card_tab
     ~shiny.ui.navset_hidden
 
     Example
@@ -741,9 +745,9 @@ def navset_pill_list(
     ~shiny.ui.nav_control
     ~shiny.ui.nav_spacer
     ~shiny.ui.navset_tab
-    ~shiny.ui.navset_tab_card
+    ~shiny.ui.navset_card_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
     ~shiny.ui.navset_bar
     ~shiny.ui.navset_hidden
@@ -910,8 +914,8 @@ def navset_bar(
     ~shiny.ui.nav_spacer
     ~shiny.ui.navset_tab
     ~shiny.ui.navset_pill
-    ~shiny.ui.navset_tab_card
-    ~shiny.ui.navset_pill_card
+    ~shiny.ui.navset_card_tab
+    ~shiny.ui.navset_card_pill
     ~shiny.ui.navset_hidden
 
     Example
@@ -997,3 +1001,54 @@ def card(*args: TagChild, header: TagChild = None, footer: TagChild = None) -> T
         bootstrap_deps(),
         class_="card",
     )
+
+
+##############################################
+# Deprecated
+##############################################
+# Deprecated 2023-08-15
+def navset_pill_card(
+    *args: NavSetArg,
+    id: Optional[str] = None,
+    selected: Optional[str] = None,
+    header: TagChild = None,
+    footer: TagChild = None,
+    placement: Literal["above", "below"] = "above",
+) -> NavSetCard:
+    """Deprecated. Please use `navset_card_pill()` instead of `navset_pill_card()`."""
+    warn_deprecated(
+        "`navset_pill_card()` is deprecated. "
+        "This method will be removed in a future version, "
+        "please use :func:`~shiny.ui.navset_card_pill` instead."
+    )
+    return navset_card_pill(
+        *args,
+        id=id,
+        selected=selected,
+        header=header,
+        footer=footer,
+        placement=placement,
+    )
+
+
+# Deprecated 2023-08-15
+def navset_tab_card(
+    *args: NavSetArg,
+    id: Optional[str] = None,
+    selected: Optional[str] = None,
+    header: TagChild = None,
+    footer: TagChild = None,
+) -> NavSetCard:
+    """Deprecated. Please use `navset_card_tab()` instead of `navset_tab_card()`."""
+    warn_deprecated(
+        "`navset_tab_card()` is deprecated. "
+        "This method will be removed in a future version, "
+        "please use :func:`~shiny.ui.navset_card_tab` instead."
+    )
+    return navset_card_tab(
+        *args,
+        id=id,
+        selected=selected,
+        header=header,
+        footer=footer,
+    )
diff --git a/tests/pytest/test_navs.py b/tests/pytest/test_navs.py
index 083eda6dd..8abf50d94 100644
--- a/tests/pytest/test_navs.py
+++ b/tests/pytest/test_navs.py
@@ -97,7 +97,7 @@ def test_nav_markup():
     )
 
     x = with_private_seed(
-        ui.navset_pill_card,
+        ui.navset_card_pill,
         a,
         ui.nav_menu("Menu", c),
         b,