api!: Move most methods from shiny.experimental.ui into shiny.ui;…

… Deprecate most of `shiny.experimental.ui` (#753)

CHANGELOG.md

@@ -14,24 +14,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added support for integration with Quarto (#746).
 * Added `shiny.render.renderer_components` decorator to help create new output renderers (#621).
 * Added `shiny.experimental.ui.popover()`, `update_popover()`, and `toggle_popover()` for easy creation (and server-side updating) of [Bootstrap popovers](https://getbootstrap.com/docs/5.2/components/popovers/). Popovers are similar to tooltips, but are more persistent, and should primarily be used with button-like UI elements (e.g. `input_action_button()` or icons) (#680).
-* Added `shiny.experimental.ui.toggle_switch()` (#680).
 * Added CSS classes to UI input methods (#680) .
 * `Session` objects can now accept an asynchronous (or synchronous) function for `.on_flush(fn=)`, `.on_flushed(fn=)`, and `.on_ended(fn=)` (#686).
 * `App()` now allows `static_assets` to represent multiple paths. To do this, pass in a dictionary instead of a string (#763).
 
 ### 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).
-
-#### Experimental API changes
-
-* 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).
-* Renamed `shiny.experimental.ui.sidebar_toggle()` to `shiny.experimental.ui.toggle_sidebar()` (#680).
-* Renamed `shiny.experimental.ui.tooltip_toggle()` to `shiny.experimental.ui.toggle_tooltip()` (#680).
-* Renamed `shiny.experimental.ui.tooltip_update()` to `shiny.experimental.ui.update_tooltip()` (#680).
-
+* 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)
+
+#### API relocations
+
+* `shiny.ui`'s `navset_pill_card()` and `navset_tab_card()` have been renamed to `.navset_card_pill()` and `navset_tab_card()` respectively (#492).
+
+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
+  * `page_sidebar()`, `toggle_sidebar()`, `layout_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()`
+  * `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.as_width_unit()`, `css.CssUnit`
+* Tooltip - Hover-based context UI element
+  * `tooltip()`, `toggle_tooltip()`, `update_tooltip()`
+* Popover - Click-based context UI element
+  * `popover()`, `toggle_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()`, `Accordion`
+* 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
+  * `valuebox()`
+* Navs - Navigation within a page
+  * `navset_bar()`, `navset_tab_card()`, `navset_pill_card()`
+  * `page_navbar(sidebar=, fillable=, fillable_mobile=, gap=, padding=, inverse=True)`, `navset_card_tab(sidebar=)`, `navset_card_pill(sidebar=)`, `navset_bar(sidebar=, fillable=, gap=, padding=)`
+* 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.
+
+Methods still under consideration in `shiny.experimental.ui`:
+* `value_box(showcase=)`
+* `card(wrapper=)`, `card_body()`, `card_image()`, `card_header()`
+
+
+#### API removals
+
+* `shiny.experimental.ui.FillingLayout` has been removed. (#481)
+* 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.eperimental.ui.as_fill_carrier()` and `shiny.eperimental.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)
 
 ### Bug fixes
 

docs/_quartodoc.yml

@@ -12,16 +12,27 @@ quartodoc:
     - title: Page containers
       desc: Create a user interface page container.
       contents:
+        - ui.page_sidebar
         - ui.page_navbar
+        - ui.page_sidebar
+        - ui.page_fillable
         - ui.page_fluid
         - ui.page_fixed
         - ui.page_bootstrap
     - title: UI Layout
       desc: Control the layout of multiple UI components.
       contents:
+        - ui.sidebar
         - ui.layout_sidebar
-        - ui.panel_sidebar
-        - ui.panel_main
+        - ui.layout_column_wrap
+        - ui.card
+        - ui.card_header
+        - ui.card_footer
+        - ui.value_box
+        - ui.popover
+        - ui.tooltip
+        - ui.accordion
+        - ui.accordion_panel
         - ui.column
         - ui.row
     - title: UI Inputs
@@ -42,33 +53,6 @@ quartodoc:
         - ui.input_password
         - ui.input_action_button
         - ui.input_action_link
-    - title: Update inputs
-      desc: Programmatically update input values.
-      contents:
-        - name: ui.update_select
-          dynamic: true
-        - name: ui.update_selectize
-          dynamic: true
-        - name: ui.update_slider
-          dynamic: true
-        - ui.update_date
-        - name: ui.update_date_range
-          dynamic: true
-        - name: ui.update_checkbox
-          dynamic: true
-        - name: ui.update_checkbox_group
-          dynamic: true
-        - name: ui.update_switch
-          dynamic: true
-        - name: ui.update_radio_buttons
-          dynamic: true
-        - name: ui.update_numeric
-          dynamic: true
-        - ui.update_text
-        - name: ui.update_text_area
-          dynamic: "shiny.ui.update_text"
-        - name: ui.update_navs
-          dynamic: true
     - title: Navigation (tab) panels
       desc: Create segments of UI content.
       contents:
@@ -77,6 +61,7 @@ quartodoc:
         - ui.nav_spacer
         - ui.nav_menu
         - ui.navset_tab
+        - ui.navset_bar
         - ui.navset_card_tab
         - ui.navset_pill
         - ui.navset_card_pill
@@ -107,6 +92,50 @@ quartodoc:
         - ui.include_js
         - ui.insert_ui
         - ui.remove_ui
+        - 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.css.as_css_unit
+        - ui.css.as_css_padding
+    - title: Update inputs
+      desc: Programmatically update input values.
+      contents:
+        - name: ui.update_select
+          dynamic: true
+        - name: ui.update_selectize
+          dynamic: true
+        - name: ui.update_slider
+          dynamic: true
+        - ui.update_date
+        - name: ui.update_date_range
+          dynamic: true
+        - name: ui.update_checkbox
+          dynamic: true
+        - name: ui.update_checkbox_group
+          dynamic: true
+        - name: ui.update_switch
+          dynamic: true
+        - name: ui.update_radio_buttons
+          dynamic: true
+        - name: ui.update_numeric
+          dynamic: true
+        - ui.update_text
+        - name: ui.update_text_area
+          dynamic: "shiny.ui.update_text"
+        - name: ui.update_navs
+          dynamic: true
+    - title: Update UI Layouts
+      desc: ""
+      contents:
+        - ui.toggle_sidebar
+        - ui.toggle_switch
+        - ui.toggle_tooltip
+        - ui.toggle_popover
+        - ui.update_tooltip
+        - ui.update_popover
+        - ui.update_accordion_panel
     - title: Rendering outputs
       desc: "UI (output_*()) and server (render)ing functions for generating content server-side."
       contents:
@@ -207,6 +236,10 @@ quartodoc:
             - types.FileInfo
             - types.ImgData
             - types.NavSetArg
+            - ui.Sidebar
+            - ui.CardItem
+            - ui.AccordionPanel
+            - ui.css.CssUnit
             - ui._input_slider.SliderValueArg
             - ui._input_slider.SliderStepArg
         - kind: page
@@ -232,61 +265,26 @@ quartodoc:
             - types.SilentException
             - types.SilentCancelOutputException
             - types.SafeException
+    - title: Deprecated
+      desc: ""
+      contents:
+        - ui.panel_main
+        - ui.panel_sidebar
     - 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:
-        - kind: page
-          path: ExSidebar
-          summary:
-            name: "Sidebar"
-            desc: "Sidebar layouts allow users to easily access filters, settings, and other inputs alongside interactive features they control."
-          flatten: true
-          contents:
-            - experimental.ui.page_sidebar
-            - experimental.ui.sidebar
-            - experimental.ui.layout_sidebar
-            - experimental.ui.page_navbar
-            - experimental.ui.navset_bar
-            - experimental.ui.navset_card_tab
-            - experimental.ui.navset_card_pill
-            - experimental.ui.toggle_sidebar
-            - experimental.ui.toggle_switch
-            - experimental.ui.panel_main
-            - experimental.ui.panel_sidebar
-            - experimental.ui.Sidebar
         - kind: page
           path: ExCard
           summary:
             name: "Card"
             desc: "Cards are a common organizing unit for modern user interfaces (UI). At their core, they’re just rectangular containers with borders and padding. However, when utilized properly to group related information, they help users better digest, engage, and navigate through content."
           flatten: true
           contents:
-            - experimental.ui.card
-            - experimental.ui.card_header
-            - experimental.ui.card_title
             - experimental.ui.card_body
+            - experimental.ui.card_title
             - experimental.ui.card_image
-            - experimental.ui.card_footer
-            - experimental.ui.CardItem
             - experimental.ui.ImgContainer
-            - experimental.ui.TagCallable
             - experimental.ui.WrapperCallable
-        - kind: page
-          path: ExAccordionPanels
-          summary:
-            name: "Accordion panels"
-            desc: "Methods related to creating and updating vertically collapsing accordion panels."
-          flatten: true
-          contents:
-            - experimental.ui.accordion
-            - experimental.ui.accordion_panel
-            - experimental.ui.accordion_panel_set
-            - experimental.ui.accordion_panel_open
-            - experimental.ui.accordion_panel_close
-            - experimental.ui.accordion_panel_insert
-            - experimental.ui.accordion_panel_remove
-            - experimental.ui.update_accordion_panel
-            - experimental.ui.AccordionPanel
         - kind: page
           path: ExValueBoxes
           summary:
@@ -297,61 +295,3 @@ quartodoc:
             - experimental.ui.value_box
             - experimental.ui.showcase_left_center
             - experimental.ui.showcase_top_right
-        - kind: page
-          path: ExTooltip
-          summary:
-            name: "Tooltips"
-            desc: "Display additional information when focusing (or hovering over) a UI element."
-          flatten: true
-          contents:
-            - experimental.ui.tooltip
-            - experimental.ui.toggle_tooltip
-            - experimental.ui.update_tooltip
-        - kind: page
-          path: ExPopover
-          summary:
-            name: "Popovers"
-            desc: "Display additional information when clicking on a UI element (typically a button)."
-          flatten: true
-          contents:
-            - experimental.ui.popover
-            - experimental.ui.toggle_popover
-            - experimental.ui.update_popover
-        - kind: page
-          path: ExFillingLayout
-          summary:
-            name: "Filling layouts"
-            desc: "Methods to create containers that are allowed to shrink or expand available space."
-          flatten: true
-          contents:
-            - experimental.ui.page_fillable
-            - experimental.ui.layout_column_wrap
-            - experimental.ui.as_fill_carrier
-            - experimental.ui.as_fillable_container
-            - experimental.ui.as_fill_item
-            - experimental.ui.remove_all_fill
-            - experimental.ui.is_fill_carrier
-            - experimental.ui.is_fillable_container
-            - experimental.ui.is_fill_item
-            - experimental.ui.FillingLayout
-            - experimental.ui.output_image
-            - experimental.ui.output_plot
-            - experimental.ui.output_ui
-        - kind: page
-          path: ExUiInputs
-          summary:
-            name: "UI Inputs"
-            desc: "Additional or upgraded UI inputs."
-          flatten: true
-          contents:
-            - experimental.ui.input_text_area
-        - kind: page
-          path: ExCss
-          summary:
-            name: "Css"
-            desc: "Helper methods related to CSS."
-          flatten: true
-          contents:
-            - experimental.ui.as_css_unit
-            - experimental.ui.as_css_padding
-            - experimental.ui.CssUnit

examples/model-score/app.py

@@ -9,7 +9,6 @@
 from plotly_streaming import render_plotly_streaming
 from shinywidgets import output_widget
 
-import shiny.experimental as x
 from shiny import App, Inputs, Outputs, Session, reactive, render, ui
 
 THRESHOLD_MID = 0.85
@@ -82,8 +81,8 @@ def app_ui(req):
     end_time = datetime.now(timezone.utc)
     start_time = end_time - timedelta(minutes=1)
 
-    return x.ui.page_sidebar(
-        x.ui.sidebar(
+    return ui.page_sidebar(
+        ui.sidebar(
             ui.input_checkbox_group(
                 "models", "Models", model_names, selected=model_names
             ),
@@ -124,10 +123,10 @@ def app_ui(req):
         ui.div(
             ui.h1("Model monitoring dashboard"),
             ui.p(
-                x.ui.output_ui("value_boxes"),
+                ui.output_ui("value_boxes"),
             ),
-            x.ui.card(output_widget("plot_timeseries")),
-            x.ui.card(output_widget("plot_dist")),
+            ui.card(output_widget("plot_timeseries")),
+            ui.card(output_widget("plot_dist")),
             style="max-width: 800px;",
         ),
         fillable=False,
@@ -190,12 +189,12 @@ def value_boxes():
         # Round scores to 2 decimal places
         scores_by_model = {x: round(y, 2) for x, y in scores_by_model.items()}
 
-        return x.ui.layout_column_wrap(
+        return ui.layout_column_wrap(
             "135px",
             *[
                 # For each model, return a value_box with the score, colored based on
                 # how high the score is.
-                x.ui.value_box(
+                ui.value_box(
                     model,
                     ui.h2(score),
                     theme_color="success"