api(ui): Drop toggle_ methods. Consolidate update accordion methods. Stronger typing for layout_sidebar(sidebar) and page_sidebar(sidebar)

CHANGELOG.md

@@ -35,9 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added `shiny.ui.navset_underline()` and `shiny.ui.navset_card_underline()` whose navigation container is similar to `shiny.ui.navset_tab()` and `shiny.ui.navset_card_tab()` respectively, but its active/focused navigation links are styled with an underline. (#772)
 * `shiny.ui.layout_column_wrap(width, *args)` was rearranged to `shiny.ui.layout_column_wrap(*args, width)`. Now, `width` will default to `200px` is no value is provided. (#772)
 * `shiny.ui.showcase_left_center()` and `shiny.ui.showcase_top_right()` no longer take two values for the `width` argument. Instead, they now take a single value (e.g., `width = "30%"`) representing the width of the showcase are in the value box. Furthermore, they've both gained `width_full_screen` arguments that determine the width of the showcase area when the value box is expanded to fill the screen. (#772)
-
-
-* TODO-barret-API; `shiny.ui.panel_main()` and `shiny.ui.panel_sidebar()` are deprecated in favor of new API for `shiny.ui.layout_sidebar()`. Please use `shiny.ui.sidebar()` to construct a sidebar and supply it (along with the main content) to `shiny.ui.layout_sidebar(*args, **kwargs)`. (#680)
+* `shiny.ui.panel_main()` and `shiny.ui.panel_sidebar()` are deprecated in favor of new API for `shiny.ui.layout_sidebar()`. Please use `shiny.ui.sidebar()` to construct a `sidebar=` and supply it to `shiny.ui.layout_sidebar(sidebar, *args, **kwargs)`. (#788)
+* `shiny.experimental.ui.toggle_sidebar()` has been renamed to `shiny.ui.update_sidebar()`. It's `open` value now only supports `bool` values. (#788)
 
 #### API relocations
 
@@ -46,18 +45,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The following methods have been moved from `shiny.experimental.ui` and integrated into `shiny.ui` (final locations under `shiny.ui` are displayed) (#680):
 
 * Sidebar - Sidebar layout or manipulation
-  * `sidebar()`, `page_sidebar()`, `toggle_sidebar()`, `layout_sidebar()`, `Sidebar`
+  * `sidebar()`, `page_sidebar()`, `update_sidebar()`, `layout_sidebar()`, `Sidebar`
 * Filling layout - Allow UI components to expand into the parent container and/or allow its content to expand
-  * `page_fillable()`, `fill.as_fillable_container()`, `fill.as_fill_item()`, `fill.is_fillable_container()`, `fill.is_fill_item()`, `fill.remove_all_fill()`
+  * `page_fillable()`, `fill.as_fillable_container()`, `fill.as_fill_item()`, `fill.remove_all_fill()`
   * `output_plot(fill=)`, `output_image(fill=)`, `output_ui(fill=, fillable=)`
 * CSS units - CSS units and padding
   * `css.as_css_unit()`, `css.as_css_padding()`, `css.CssUnit`
 * Tooltip - Hover-based context UI element
-  * `tooltip()`, `toggle_tooltip()`, `update_tooltip()`
+  * `tooltip()`, `update_tooltip()`
 * Popover - Click-based context UI element
-  * `popover()`, `toggle_popover()`, `update_popover()`
+  * `popover()`, `update_popover()`
 * Accordion - Vertically collapsible UI element
-  * `accordion()`, `accordion_panel()`, `accordion_panel_close()`, `accordion_panel_insert()`, `accordion_panel_open()`, `accordion_panel_remove()`, `accordion_panel_set()`, `update_accordion_panel()`, `Accordion`, `AccordionPanel`
+  * `accordion()`, `accordion_panel()`, `insert_accordion_panel()`, `remove_accordion_panel()`, `update_accordion()`, `update_accordion_panel()`, `Accordion`, `AccordionPanel`
 * Card - A general purpose container for grouping related UI elements together
   * `card()`, `card_header()`, `card_footer()`, `CardItem`
 * Valuebox - Opinionated container for displaying a value and title
@@ -70,7 +69,6 @@ The following methods have been moved from `shiny.experimental.ui` and integrate
 * Layout - Layout of UI elements
   * `layout_column_wrap()`
 * Inputs - UI elements for user input
-  * `toggle_switch()`
   * `input_text_area(autoresize=)`
 
 If a ported method is called from `shiny.experimental.ui`, a deprecation warning will be displayed.
@@ -84,10 +82,11 @@ Methods still under consideration in `shiny.experimental.ui`:
 #### API removals
 
 * `shiny.experimental.ui.FillingLayout` has been removed. (#481)
+* `shiny.experimental.ui.toggle_switch()` has been made defunct. Please remove it from your code and use `shiny.ui.update_switch()` instead. (#772)
 * `shiny.experimental.ui.as_width_unit()` has been made defunct. Please remove it from your code. (#772)
+* `shiny.experimental.ui`' `as_fill_carrier()`, `is_fill_carrier()`, `is_fillable_container()`, and `is_fill_item()` have been made defunct. Remove them from your code. (#680, #788)
 * Support for `min_height=`, `max_height=`, and `gap=` in `shiny.experimental.ui.as_fillable_container()` and `as_fill_item()` has been removed. (#481)
-* `shiny.experimental.ui.TagCallable` has been deprecated. Its type is equivalent to `htmltools.TagFunction`. (#680)
-* `shiny.experimental.ui.as_fill_carrier()` and `shiny.experimental.ui.is_fill_carrier()` have been deprecated. Please use `shiny.ui.fill.as_fill_item()` and `shiny.ui.fill.as_fillable_container()` or `shiny.ui.fill.is_fill_item()` and `shiny.ui.fill.is_fillable_container()` respectively in combination to achieve similar behavior. (#680)
+* `shiny.experimental.ui.TagCallable` has been made defunct. Please use its type is equivalent to `htmltools.TagFunction`. (#680)
 
 ### Bug fixes
 

docs/_quartodoc.yml

@@ -106,8 +106,8 @@ quartodoc:
         - ui.fill.as_fillable_container
         - ui.fill.as_fill_item
         - ui.fill.remove_all_fill
-        - ui.fill.is_fillable_container
-        - ui.fill.is_fill_item
+        # - ui.fill.is_fillable_container
+        # - ui.fill.is_fill_item
         - ui.css.as_css_unit
         - ui.css.as_css_padding
     - title: Update inputs
@@ -140,13 +140,13 @@ quartodoc:
     - title: Update UI Layouts
       desc: ""
       contents:
-        - ui.toggle_sidebar
-        - ui.toggle_switch
-        - ui.toggle_tooltip
-        - ui.toggle_popover
+        - ui.update_sidebar
         - ui.update_tooltip
         - ui.update_popover
+        - ui.update_accordion
         - ui.update_accordion_panel
+        - ui.insert_accordion_panel
+        - ui.remove_accordion_panel
     - title: Rendering outputs
       desc: "UI (output_*()) and server (render)ing functions for generating content server-side."
       contents:

shiny/api-examples/accordion_panel_insert/app.py → shiny/api-examples/insert_accordion_panel/app.py

@@ -21,7 +21,7 @@ def server(input: Inputs, output: Outputs, session: Session):
     @reactive.Effect
     @reactive.event(input.add_panel)
     def _():
-        ui.accordion_panel_insert("acc", make_panel(str(random.randint(0, 10000))))
+        ui.insert_accordion_panel("acc", make_panel(str(random.randint(0, 10000))))
 
 
 app = App(app_ui, server)

shiny/api-examples/accordion_panel_remove/app.py → shiny/api-examples/remove_accordion_panel/app.py

@@ -37,7 +37,7 @@ def _():
             return
 
         # Remove panel
-        ui.accordion_panel_remove("acc", f"Section { user_choices.pop() }")
+        ui.remove_accordion_panel("acc", f"Section { user_choices.pop() }")
 
         label = "No more panels to remove!"
         if len(user_choices) > 0:

shiny/api-examples/accordion_panel_set/app.py → shiny/api-examples/update_accordion/app.py

@@ -16,7 +16,7 @@ def server(input: Inputs, output: Outputs, session: Session):
     @reactive.Effect
     @reactive.event(input.set_acc)
     def _():
-        ui.accordion_panel_set("acc", ["Section A", "Section C", "Section E"])
+        ui.update_accordion("acc", show=["Section A", "Section C", "Section E"])
 
 
 app = App(app_ui, server)

shiny/api-examples/accordion_panel_update/app.py → shiny/api-examples/update_accordion_panel/app.py

@@ -12,7 +12,7 @@ def make_panel(letter: str) -> ui.AccordionPanel:
 items = [make_panel(letter) for letter in "ABCDE"]
 
 app_ui = ui.page_fluid(
-    ui.input_switch("update_panel", "Update Sections"),
+    ui.input_switch("update_panel", "Update (and open) Sections"),
     ui.accordion(*items, id="acc", multiple=True),
 )
 
@@ -22,13 +22,19 @@ def server(input: Inputs, output: Outputs, session: Session):
     @reactive.event(input.update_panel)
     def _():
         txt = " (updated)" if input.update_panel() else ""
+        show = bool(input.update_panel() % 2 == 1)
         for letter in "ABCDE":
             ui.update_accordion_panel(
                 "acc",
                 f"sec_{letter}",
                 f"Some{txt} narrative for section {letter}",
                 title=f"Section {letter}{txt}",
+                # Open Accordion Panel to see updated contents
+                show=show,
             )
+        next_show_txt = "close" if show else "open"
+
+        ui.update_switch("update_panel", label=f"Update (and {next_show_txt}) Sections")
 
 
 app = App(app_ui, server)

shiny/api-examples/toggle_popover/app.py → shiny/api-examples/update_popover/app.py

@@ -4,8 +4,6 @@
     ui.input_action_button("btn_show", "Show popover", class_="mt-3 me-3"),
     ui.input_action_button("btn_close", "Close popover", class_="mt-3 me-3"),
     ui.br(),
-    ui.input_action_button("btn_toggle", "Toggle popover", class_="mt-3 me-3"),
-    ui.br(),
     ui.br(),
     ui.popover(
         ui.input_action_button("btn_w_popover", "A button w/ a popover", class_="mt-3"),
@@ -20,19 +18,13 @@ def server(input: Inputs, output: Outputs, session: Session):
     def _():
         req(input.btn_show())
 
-        ui.toggle_popover("popover_id", show=True)
+        ui.update_popover("popover_id", show=True)
 
     @reactive.Effect
     def _():
         req(input.btn_close())
 
-        ui.toggle_popover("popover_id", show=False)
-
-    @reactive.Effect
-    def _():
-        req(input.btn_toggle())
-
-        ui.toggle_popover("popover_id")
+        ui.update_popover("popover_id", show=False)
 
     @reactive.Effect
     def _():

shiny/api-examples/update_sidebar/app.py

@@ -0,0 +1,31 @@
+from shiny import App, Inputs, Outputs, Session, reactive, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar("Sidebar content", id="sidebar"),
+    ui.input_action_button("open_sidebar", label="Open sidebar", class_="me-3"),
+    ui.input_action_button("close_sidebar", label="Close sidebar", class_="me-3"),
+    ui.br(),
+    ui.br(),
+    ui.output_text_verbatim("state"),
+    fillable=False,
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @reactive.Effect
+    @reactive.event(input.open_sidebar)
+    def _():
+        ui.update_sidebar("sidebar", show=True)
+
+    @reactive.Effect
+    @reactive.event(input.close_sidebar)
+    def _():
+        ui.update_sidebar("sidebar", show=False)
+
+    @output
+    @render.text
+    def state():
+        return f"input.sidebar(): {input.sidebar()}"
+
+
+app = App(app_ui, server=server)

shiny/api-examples/update_tooltip/app.py

@@ -1,7 +1,12 @@
-from shiny import App, Inputs, Outputs, Session, reactive, ui
+from shiny import App, Inputs, Outputs, Session, reactive, req, ui
 
 app_ui = ui.page_fluid(
-    ui.input_action_button("btn_update", "Update tooltip phrase", class_="mt-3 me-3"),
+    ui.input_action_button("btn_show", "Show tooltip", class_="mt-3 me-3"),
+    ui.input_action_button("btn_close", "Close tooltip", class_="mt-3 me-3"),
+    ui.br(),
+    ui.input_action_button(
+        "btn_update", "Update tooltip phrase (and show tooltip)", class_="mt-3 me-3"
+    ),
     ui.br(),
     ui.br(),
     ui.tooltip(
@@ -15,8 +20,15 @@
 def server(input: Inputs, output: Outputs, session: Session):
     @reactive.Effect
     def _():
-        # Immediately display tooltip
-        ui.toggle_tooltip("tooltip_id", show=True)
+        req(input.btn_show())
+
+        ui.update_tooltip("tooltip_id", show=True)
+
+    @reactive.Effect
+    def _():
+        req(input.btn_close())
+
+        ui.update_tooltip("tooltip_id", show=False)
 
     @reactive.Effect
     @reactive.event(input.btn_update)
@@ -25,12 +37,11 @@ def _():
             "A " + " ".join(["NEW" for _ in range(input.btn_update())]) + " message"
         )
 
-        ui.update_tooltip("tooltip_id", content)
-        ui.toggle_tooltip("tooltip_id", show=True)
+        ui.update_tooltip("tooltip_id", content, show=True)
 
     @reactive.Effect
-    @reactive.event(input.btn_w_tooltip)
     def _():
+        req(input.btn_w_tooltip())
         ui.notification_show("Button clicked!", duration=3, type="message")