Sync with latest bslib sidebar and card changes (#1129)

Co-authored-by: Barret Schloerke <[email protected]>
Co-authored-by: Winston Chang <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [UNRELEASED] - YYYY-MM-DD
 
+### Breaking Changes
+
+* Page-level sidebars used in `ui.page_sidebar()` and `ui.page_navbar()` will now default to being initially open but collapsible on desktop devices and always open on mobile devices. You can adjust this default choice by setting `ui.sidebar(open=)`. (#1129)
+
+* `ui.sidebar()` is now a thin wrapper for the internal `ui.Sidebar` class. The `ui.Sidebar` class has been updated to store the sidebar's contents and settings and to delay rendering until the sidebar HTML is actually used. Because most users call `ui.sidebar()` instead of using the class directly, this change is not expected to affect many apps. (#1129)
+
+### New features
+
+* `ui.sidebar(open=)` now accepts a dictionary with keys `desktop` and `mobile`, allowing you to independently control the initial state of the sidebar at desktop and mobile screen sizes. (#1129)
+
+### Other changes
+
+* We improved the accessibility of the full screen toggle button in cards created with `ui.card(full_screen=True)`. Full-screen cards are now also supported on mobile devices. (#1129)
+
+* When entering and exiting full-screen card mode, Shiny now emits a client-side custom `bslib.card` event that JavaScript-oriented users can use to react to the full screen state change. (#1129)
+
+* The sidebar's collapse toggle now has a high `z-index` value to ensure it always appears above elements in the main content area of `ui.layout_sidebar()`. The sidebar overlay also now receives the same high `z-index` on mobile layouts. (#1129)
+
 ### Bug fixes
 
 * Fixed `input_task_button` not working in a Shiny module. (#1108)

scripts/htmlDependencies.R

@@ -12,7 +12,7 @@ message("Installing GitHub packages: bslib, shiny, htmltools")
 withr::local_temp_libpaths()
 ignore <- capture.output({
   pak::pkg_install(c(
-    "rstudio/bslib@py-shiny-v0.7.0",
+    "rstudio/bslib@main",
     "rstudio/shiny@main",
     "cran::htmltools"
   ))

shiny/_namespaces.py

@@ -81,6 +81,10 @@ def resolve_id_or_none(id: Id | None) -> ResolvedId | None:
 
 
 def validate_id(id: str) -> None:
+    if not isinstance(id, str):
+        raise ValueError("`id` must be a single string")
+    if id == "":
+        raise ValueError("`id` must be a non-empty string")
     if not re_valid_id.match(id):
         raise ValueError(
             f"The string '{id}' is not a valid id; only letters, numbers, and "

shiny/_utils.py

@@ -199,6 +199,14 @@ def private_random_int(min: int, max: int) -> str:
         return str(random.randint(min, max))
 
 
+def private_random_id(prefix: str = "", bytes: int = 3) -> str:
+    if prefix != "" and not prefix.endswith("_"):
+        prefix += "_"
+
+    with private_seed():
+        return prefix + rand_hex(bytes)
+
+
 @contextlib.contextmanager
 def private_seed() -> Generator[None, None, None]:
     state = random.getstate()

shiny/api-examples/sidebar/app-core-dynamic.py

@@ -0,0 +1,90 @@
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+app_ui = ui.page_fluid(
+    ui.card(
+        ui.card_header("ui.sidebar() Settings"),
+        ui.layout_column_wrap(
+            ui.input_select(
+                "desktop",
+                label="Desktop",
+                choices=["open", "closed", "always"],
+                selected="open",
+            ),
+            ui.input_select(
+                "mobile",
+                label="Mobile",
+                choices=["open", "closed", "always"],
+                selected="closed",
+            ),
+            ui.input_select(
+                "position", label="Position", choices=["left", "right"], selected="left"
+            ),
+            width="100px",
+        ),
+    ),
+    ui.layout_column_wrap(
+        ui.card(
+            ui._card.card_body(
+                ui.output_ui("sidebar_dynamic", fill=True, fillable=True), class_="p-0"
+            ),
+        ),
+        ui.card(
+            ui.card_header("Sidebar Layout Code"),
+            ui.output_code("sidebar_code"),
+        ),
+        width="500px",
+    ),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @render.ui
+    def sidebar_dynamic():
+        return ui.layout_sidebar(
+            ui.sidebar(
+                ui.markdown(
+                    f"""
+                    **Desktop**: {input.desktop()}
+
+                    **Mobile**: {input.mobile()}
+
+                    **Position**: {input.position()}
+                    """
+                ),
+                title="Settings",
+                id="sidebar_dynamic",
+                open={"desktop": input.desktop(), "mobile": input.mobile()},
+                position=input.position(),
+            ),
+            ui.h2("Dynamic sidebar"),
+            ui.output_text_verbatim("state_dynamic"),
+        )
+
+    @render.text
+    def state_dynamic():
+        return f"input.sidebar_dynamic(): {input.sidebar_dynamic()}"
+
+    @render.code
+    def sidebar_code():
+        if input.desktop() == input.mobile():
+            open = f'"{input.desktop()}"'
+        elif input.desktop() == "open" and input.mobile() == "closed":
+            open = '{"desktop": "open", "mobile": "closed"}'
+        else:
+            open = f'{{"desktop": "{input.desktop()}", "mobile": "{input.mobile()}}}'
+
+        return f"""\
+ui.layout_sidebar(
+    ui.sidebar(
+        "Sidebar content...",
+        title="Sidebar title",
+        id="sidebar_id",
+        open={open},
+        position="{input.position()}"
+    ),
+    "Main content...",
+)
+"""
+
+
+app = App(app_ui, server)

shiny/api-examples/sidebar/app-express.py

@@ -7,7 +7,7 @@
         with ui.sidebar(id="sidebar_left", open="desktop"):
             "Left sidebar content"
 
-        @render.text
+        @render.code
         def state_left():
             return f"input.sidebar_left(): {input.sidebar_left()}"
 
@@ -17,7 +17,7 @@ def state_left():
         with ui.sidebar(id="sidebar_right", position="right", open="desktop"):
             "Right sidebar content"
 
-        @render.text
+        @render.code
         def state_right():
             return f"input.sidebar_right(): {input.sidebar_right()}"
 
@@ -27,7 +27,7 @@ def state_right():
         with ui.sidebar(id="sidebar_closed", open="closed"):
             "Closed sidebar content"
 
-        @render.text
+        @render.code
         def state_closed():
             return f"input.sidebar_closed(): {input.sidebar_closed()}"
 
@@ -37,6 +37,6 @@ def state_closed():
         with ui.sidebar(id="sidebar_always", open="always"):
             "Always sidebar content"
 
-        @render.text
+        @render.code
         def state_always():
             return f"input.sidebar_always(): {input.sidebar_always()}"

shiny/experimental/ui/_deprecated.py

@@ -52,6 +52,8 @@
 from ...ui._plot_output_opts import HoverOpts as MainHoverOpts
 from ...ui._sidebar import DeprecatedPanelMain, DeprecatedPanelSidebar
 from ...ui._sidebar import Sidebar as MainSidebar
+from ...ui._sidebar import SidebarOpenSpec as MainSidebarOpenSpec
+from ...ui._sidebar import SidebarOpenValue as MainSidebarOpenValue
 from ...ui._sidebar import layout_sidebar as main_layout_sidebar
 from ...ui._sidebar import panel_main as main_panel_main
 from ...ui._sidebar import panel_sidebar as main_panel_sidebar
@@ -398,29 +400,39 @@ class Sidebar(MainSidebar):
 
     def __init__(
         self,
-        tag: Tag,
-        collapse_tag: Optional[Tag],
-        position: Literal["left", "right"],
-        open: Literal["desktop", "open", "closed", "always"],
-        width: CssUnit,
-        max_height_mobile: Optional[str | float],
-        color_fg: Optional[str],
-        color_bg: Optional[str],
+        children: list[TagChild],
+        attrs: TagAttrs,
+        position: Literal["left", "right"] = "left",
+        open: Optional[MainSidebarOpenValue | MainSidebarOpenSpec] = None,
+        width: CssUnit = 250,
+        id: Optional[str] = None,
+        title: TagChild | str = None,
+        fg: Optional[str] = None,
+        bg: Optional[str] = None,
+        class_: Optional[str] = None,
+        max_height_mobile: Optional[str | float] = None,
+        gap: Optional[CssUnit] = None,
+        padding: Optional[CssUnit | list[CssUnit]] = None,
     ):
         warn_deprecated(
             "`shiny.experimental.ui.Sidebar` is deprecated. "
             "This class will be removed in a future version, "
             "please use :class:`shiny.ui.Sidebar` instead."
         )
         super().__init__(
-            tag,
-            collapse_tag,
-            position,
-            open,
-            width,
-            max_height_mobile,
-            color_fg,
-            color_bg,
+            children=children,
+            attrs=attrs,
+            position=position,
+            open=open,
+            width=width,
+            id=id,
+            title=title,
+            fg=fg,
+            bg=bg,
+            class_=class_,
+            max_height_mobile=max_height_mobile,
+            gap=gap,
+            padding=padding,
         )
 
 

shiny/express/ui/_cm_components.py

@@ -13,6 +13,7 @@
 from ...ui._card import CardItem
 from ...ui._layout_columns import BreakpointsUser
 from ...ui._navs import NavMenu, NavPanel, NavSet, NavSetBar, NavSetCard
+from ...ui._sidebar import SidebarOpenSpec, SidebarOpenValue
 from ...ui.css import CssUnit
 from .._recall_context import RecallContextManager
 
@@ -42,17 +43,18 @@
 @add_example()
 def sidebar(
     *,
-    width: CssUnit = 250,
     position: Literal["left", "right"] = "left",
-    open: Literal["desktop", "open", "closed", "always"] = "always",
+    open: Optional[SidebarOpenSpec | SidebarOpenValue | Literal["desktop"]] = None,
+    width: CssUnit = 250,
     id: Optional[str] = None,
     title: TagChild | str = None,
     bg: Optional[str] = None,
     fg: Optional[str] = None,
-    class_: Optional[str] = None,  # TODO-future; Consider using `**kwargs` instead
-    max_height_mobile: Optional[str | float] = "auto",
+    class_: Optional[str] = None,
+    max_height_mobile: Optional[str | float] = None,
     gap: Optional[CssUnit] = None,
     padding: Optional[CssUnit | list[CssUnit]] = None,
+    **kwargs: TagAttrValue,
 ) -> RecallContextManager[ui.Sidebar]:
     """
     Context manager for sidebar element
@@ -64,20 +66,21 @@ def sidebar(
     width
         A valid CSS unit used for the width of the sidebar.
     position
-        Where the sidebar should appear relative to the main content.
+        Where the sidebar should appear relative to the main content, one of `"left"` or
+        `"right"`.
     open
-        The initial state of the sidebar.
+        The initial state of the sidebar. If a string, the possible values are:
 
-        * `"desktop"`: the sidebar starts open on desktop screen, closed on mobile
-        * `"open"` or `True`: the sidebar starts open
-        * `"closed"` or `False`: the sidebar starts closed
-        * `"always"` or `None`: the sidebar is always open and cannot be closed
+        * `"open"`: the sidebar starts open
+        * `"closed"`: the sidebar starts closed
+        * `"always"`: the sidebar is always open and cannot be closed
 
-        In :func:`~shiny.ui.update_sidebar`, `open` indicates the desired state of the
-        sidebar. Note that :func:`~shiny.ui.update_sidebar` can only open or close the
-        sidebar, so it does not support the `"desktop"` and `"always"` options.
+        Alternatively, you can provide a dictionary with keys `"desktop"` and `"mobile"`
+        to set different initial states for desktop and mobile. For example, when
+        `{"desktop": "open", "mobile": "closed"}` the sidebar is initialized in the
+        open state on desktop screens or in the closed state on mobile screens.
     id
-        A character string. Required if wanting to re-actively read (or update) the
+        A character string. Required if wanting to reactively read (or update) the
         `collapsible` state in a Shiny app.
     title
         A character title to be used as the sidebar title, which will be wrapped in a
@@ -92,8 +95,8 @@ def sidebar(
     max_height_mobile
         A CSS length unit (passed through :func:`~shiny.ui.css.as_css_unit`) defining
         the maximum height of the horizontal sidebar when viewed on mobile devices. Only
-        applies to always-open sidebars that use `open = "always"`, where by default the
-        sidebar container is placed below the main content container on mobile devices.
+        applies to always-open sidebars on mobile, where by default the sidebar
+        container is placed below the main content container on mobile devices.
     gap
         A CSS length unit defining the vertical `gap` (i.e., spacing) between elements
         provided to `*args`.
@@ -109,6 +112,8 @@ def sidebar(
           and right, and the third will be bottom.
         * If four, then the values will be interpreted as top, right, bottom, and left
           respectively.
+    **kwargs
+        Named attributes are supplied to the sidebar content container.
     """
     return RecallContextManager(
         ui.sidebar,
@@ -124,6 +129,7 @@ def sidebar(
             max_height_mobile=max_height_mobile,
             gap=gap,
             padding=padding,
+            **kwargs,
         ),
     )
 

shiny/templates/package-templates/js-output/custom_component/custom_component.py

@@ -37,8 +37,8 @@ def __init__(self, _fn: Optional[ValueFn[int]] = None, *, height: str = "200px")
         self.height: str = height
 
     # Transforms non-`None` values into a `Jsonifiable` object.
-    # If you'd like more control on when and how the value is resolved,
-    # please use the `async def resolve(self)` method.
+    # If you'd like more control on when and how the value is rendered,
+    # please use the `async def render(self)` method.
     async def transform(self, value: int) -> Jsonifiable:
         # Send the results to the client. Make sure that this is a serializable
         # object and matches what is expected in the javascript code.

shiny/templates/package-templates/js-react/custom_component/custom_component.py

@@ -49,8 +49,8 @@ def auto_output_ui(self) -> Tag:
     #     self.extra_arg: str = extra_arg
 
     # Transforms non-`None` values into a `Jsonifiable` object.
-    # If you'd like more control on when and how the value is resolved,
-    # please use the `async def resolve(self)` method.
+    # If you'd like more control on when and how the value is rendered,
+    # please use the `async def render(self)` method.
     async def transform(self, value: str) -> Jsonifiable:
         # Send the results to the client. Make sure that this is a serializable
         # object and matches what is expected in the javascript code.