shiny.experimental: Deprecate card(), card_body() and `card_tit…

…le()` (#1543)

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Deprecated functions in `shiny.experimental` have been removed. By and large, these functions are now available in the main `shiny` namespace. (#1540)
 
+* We've deprecated several card-related `shiny.experimental.ui` functions that were moved to the main `shiny.ui` namespace in v0.6.0. Both `card()` and `card_body()` are no longer experimental and can be called via `shiny.ui.card()` and `shiny.ui.card_body()` directly. `shiny.experimental.ui.card_title()` is now deprecated, but can be replaced with `shiny.ui.tags.h5()` or `shiny.ui.card_header()`. (#1543)
+
 ### New features
 
 * Added a new `shiny.ui.Chat` class for building conversational interfaces with fully customizable and performant response generation. (#1453)

docs/_quartodoc-core.yml

@@ -346,22 +346,17 @@ quartodoc:
         - render.transformer.output_transformer
         - render.transformer.resolve_value_fn
     - 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!"
+      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: 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."
+            desc: >
+              Additional card components that compliment [ui.card](ui.card.qmd).
           flatten: true
           contents:
-            - name: experimental.ui.card_body
-              dynamic: false
-            - name: experimental.ui.card_title
-              dynamic: false
             - name: experimental.ui.card_image
               dynamic: false
-            - name: experimental.ui.ImgContainer
-              dynamic: false
-            - name: experimental.ui.WrapperCallable
-              dynamic: false

shiny/experimental/ui/__init__.py

@@ -1,20 +1,13 @@
 # Experimental
 
-from ._card import (
-    WrapperCallable,
-    ImgContainer,
-    card,
-    card_body,
-    card_image,
-    card_title,
-)
+from ._card import card_image
+from ._deprecated import card, card_body, card_title
 
 __all__ = (
-    # Card
-    "WrapperCallable",
-    "ImgContainer",
+    # Deprecated
     "card",
-    "card_title",
     "card_body",
+    "card_title",
+    # Still experimental
     "card_image",
 )

shiny/experimental/ui/_card.py

@@ -6,152 +6,18 @@
 from pathlib import Path, PurePath
 from typing import Literal, Optional, Protocol
 
-from htmltools import (
-    Tag,
-    TagAttrs,
-    TagAttrValue,
-    TagChild,
-    TagFunction,
-    Tagifiable,
-    css,
-    tags,
-)
+from htmltools import Tag, TagAttrs, TagAttrValue, Tagifiable, css, tags
 
 from ..._docstring import add_example
-from ...types import MISSING, MISSING_TYPE
-from ...ui._card import CardItem, WrapperCallable, _card_impl, card_body
+from ...ui._card import CardItem, card_body
 from ...ui.css import CssUnit, as_css_unit
 from ...ui.fill import as_fill_item, as_fillable_container
 
-__all__ = (
-    # Worried about `wrapper`
-    "card",
-    # Do not want to expose card_body yet
-    "card_body",
-    # Questioning:
-    "card_title",
-    "card_image",
-)
-
-
-def card(
-    *args: TagChild | TagAttrs | CardItem,
-    full_screen: bool = False,
-    height: Optional[CssUnit] = None,
-    max_height: Optional[CssUnit] = None,
-    min_height: Optional[CssUnit] = None,
-    fill: bool = True,
-    class_: Optional[str] = None,
-    wrapper: WrapperCallable | None | MISSING_TYPE = MISSING,
-    **kwargs: TagAttrValue,
-) -> Tag:
-    """
-    A Bootstrap card component
-
-    A card is a general purpose container that groups related UI elements together with a border
-    and optional padding. To learn more about `card()`s, see [the bslib card
-    article](https://rstudio.github.io/bslib/articles/cards.html).
-
-    Parameters
-    ----------
-    *args
-        Unnamed arguments can be any valid child of an :class:`~htmltools.Tag` (This
-        includes card items such as :func:`~shiny.experimental.ui.card_body`).
-    full_screen
-        If `True`, an icon will appear when the user's pointer hovers over the card body. Clicking the
-        icon expands the card to fit viewport size.
-    height, max_height, min_height
-        Any valid CSS unit (e.g., `height="200px"`). These will not apply when a card is made
-        `full_screen`. In this case, consider setting a `height` in
-        :func:`~shiny.experimental.ui.card_body`.
-    fill
-        Whether or not to allow the card to grow/shrink to fit a fillable container with
-        an opinionated height (e.g., :func:`~shiny.ui.page_fillable`).
-    class_
-        Additional CSS classes for the returned Tag.
-    wrapper
-        A function that returns a UI element to call on any unnamed arguments in `*args`
-        that are not already card item(s) (like
-        :func:`~shiny.ui.card_header`,
-        :func:`~shiny.experimental.ui.card_body`, etc.). Note that non-card items are
-        grouped together into one `wrapper` call (e.g. given `card("a", "b",
-        card_body("c"), "d")`, `wrapper` would be called twice, once with `"a"` and
-        `"b"` and once with `"d"`).
-    **kwargs
-        HTML attributes on the returned Tag.
-
-    Returns
-    -------
-    :
-        A :func:`~shiny.ui.tags.div` tag.
-
-    See Also
-    --------
-    * :func:`~shiny.ui.layout_column_wrap` for laying out multiple cards
-      or multiple columns inside a card.
-    * :func:`~shiny.ui.card_header` for creating a header within a card.
-    * :func:`~shiny.experimental.ui.card_title` for creating a title within a card body.
-    * :func:`~shiny.experimental.ui.card_body` for putting content inside a card.
-    * :func:`~shiny.ui.card_footer` for creating a footer within a card.
-    * :func:`~shiny.experimental.ui.card_image` for adding an image to a card.
-    """
-    return _card_impl(
-        *args,
-        full_screen=full_screen,
-        height=height,
-        max_height=max_height,
-        min_height=min_height,
-        fill=fill,
-        class_=class_,
-        wrapper=wrapper,
-        id=None,
-        **kwargs,
-    )
-
+__all__ = ("card_image",)
 
 ############################################################################
 
 
-@add_example()
-def card_title(
-    *args: TagChild | TagAttrs,
-    container: TagFunction = tags.h5,
-    **kwargs: TagAttrValue,
-) -> Tagifiable:
-    """
-    A card title container
-
-    :func:`~shiny.experimental.ui.card_title` creates a general container for the "title" of
-    a :func:`~shiny.ui.card`. This component is designed
-    to be provided as a direct child to :func:`~shiny.ui.card`.
-
-    Parameters
-    ----------
-    *args
-        Contents to appear in the card's title, or tag attributes to pass to the
-        resolved :class:`~htmltools.Tag` object.
-    container
-        Method for the returned :class:`~htmltools.Tag` object. Defaults to
-        :func:`~shiny.ui.tags.h5`.
-    **kwargs
-        Additional HTML attributes for the returned :class:`~htmltools.Tag` object.
-
-    Returns
-    -------
-    :
-        An :class:`~htmltools.Tag` object.
-
-    See Also
-    --------
-    * :func:`~shiny.ui.card` for creating a card component.
-    * :func:`~shiny.ui.card_header` for creating a header within a card.
-    * :func:`~shiny.experimental.ui.card_body` for putting content inside a card.
-    * :func:`~shiny.ui.card_footer` for creating a footer within a card.
-    * :func:`~shiny.experimental.ui.card_image` for adding an image to a card.
-    """
-    return container(*args, **kwargs)
-
-
 class ImgContainer(Protocol):
     """
     A callable that wraps the return value of `card_image()`. To isolate your object in a card, return a :class:`~shiny.ui.CardItem`.

shiny/experimental/ui/_deprecated.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from htmltools import TagAttrs, TagAttrValue, TagChild, TagFunction, Tagifiable, tags
+
+from ..._deprecated import warn_deprecated
+from ...types import MISSING, MISSING_TYPE
+from ...ui import CardItem
+from ...ui import card as main_card
+from ...ui._card import card_body as main_card_body  # FIXME after #1506
+from ...ui.css import CssUnit
+
+
+def card(
+    *args: TagChild | TagAttrs | CardItem,
+    full_screen: bool = False,
+    height: Optional[CssUnit] = None,
+    max_height: Optional[CssUnit] = None,
+    min_height: Optional[CssUnit] = None,
+    fill: bool = True,
+    class_: Optional[str] = None,
+    wrapper: MISSING_TYPE = MISSING,
+    **kwargs: TagAttrValue,
+):
+    """Deprecated. Please use :func:`~shiny.ui.card()` instead."""
+    warn_deprecated(
+        "`shiny.experimental.ui.card()` was deprecated in shiny 1.0.0. "
+        "Card components are now available in the main shiny namespace. "
+        "Please use `shiny.ui.card()` instead."
+    )
+    return main_card(
+        *args,
+        full_screen=full_screen,
+        height=height,
+        max_height=max_height,
+        min_height=min_height,
+        fill=fill,
+        class_=class_,
+        id=None,
+        **kwargs,
+    )
+
+
+def card_body(
+    *args: TagChild | TagAttrs,
+    fillable: bool = True,
+    min_height: Optional[CssUnit] = None,
+    max_height: Optional[CssUnit] = None,
+    max_height_full_screen: Optional[CssUnit] | MISSING_TYPE = MISSING,
+    height: Optional[CssUnit] = None,
+    padding: Optional[CssUnit | list[CssUnit]] = None,
+    gap: Optional[CssUnit] = None,
+    fill: bool = True,
+    class_: Optional[str] = None,
+    **kwargs: TagAttrValue,
+):
+    """Deprecated. Please use :func:`~shiny.ui.card_body()` instead."""
+    warn_deprecated(
+        "`shiny.experimental.ui.card_body()` was deprecated in shiny 1.0.0. "
+        "Card components are now available in the main shiny namespace. "
+        "Please use `shiny.ui.card_body()` instead."
+    )
+    return main_card_body(
+        *args,
+        fillable=fillable,
+        min_height=min_height,
+        max_height=max_height,
+        max_height_full_screen=max_height_full_screen,
+        height=height,
+        padding=padding,
+        gap=gap,
+        fill=fill,
+        class_=class_,
+        **kwargs,
+    )
+
+
+def card_title(
+    *args: TagChild | TagAttrs,
+    container: TagFunction = tags.h5,
+    **kwargs: TagAttrValue,
+) -> Tagifiable:
+    """
+    Deprecated. Please use :func:`~shiny.ui.tags.h5()` instead.
+
+    :func:`~shiny.experimental.ui.card_title` creates a general container for the "title" of
+    a :func:`~shiny.ui.card`. This component is designed
+    to be provided as a direct child to :func:`~shiny.ui.card`.
+
+    Parameters
+    ----------
+    *args
+        Contents to appear in the card's title, or tag attributes to pass to the
+        resolved :class:`~htmltools.Tag` object.
+    container
+        Method for the returned :class:`~htmltools.Tag` object. Defaults to
+        :func:`~shiny.ui.tags.h5`.
+    **kwargs
+        Additional HTML attributes for the returned :class:`~htmltools.Tag` object.
+
+    Returns
+    -------
+    :
+        An :class:`~htmltools.Tag` object.
+
+    See Also
+    --------
+    * :func:`~shiny.ui.card` for creating a card component.
+    * :func:`~shiny.ui.card_header` for creating a header within a card.
+    * :func:`~shiny.experimental.ui.card_body` for putting content inside a card.
+    * :func:`~shiny.ui.card_footer` for creating a footer within a card.
+    * :func:`~shiny.experimental.ui.card_image` for adding an image to a card.
+    """
+    warn_deprecated(
+        "`shiny.experimental.ui.card_title()` was deprecated in shiny 1.0.0 "
+        "and will be removed in a future version of shiny. "
+        "Please use `shiny.ui.tags.h5()` instead."
+    )
+    return container(*args, **kwargs)
+
+
+__all__ = (
+    "card",
+    "card_body",
+)