From da6e957a02904eaeb18419ba8ddff916c273a94c Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 17 Jul 2024 12:06:25 -0400 Subject: [PATCH] `shiny.experimental`: Deprecate `card()`, `card_body()` and `card_title()` (#1543) --- CHANGELOG.md | 2 + docs/_quartodoc-core.yml | 15 +- .../api-examples/card_title/app.py | 18 --- shiny/experimental/ui/__init__.py | 17 +-- shiny/experimental/ui/_card.py | 140 +----------------- shiny/experimental/ui/_deprecated.py | 126 ++++++++++++++++ 6 files changed, 141 insertions(+), 177 deletions(-) delete mode 100644 shiny/experimental/api-examples/card_title/app.py create mode 100644 shiny/experimental/ui/_deprecated.py diff --git a/CHANGELOG.md b/CHANGELOG.md index c746f2ee6..f038e972f 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/docs/_quartodoc-core.yml b/docs/_quartodoc-core.yml index 4bbd133d7..377c61f6c 100644 --- a/docs/_quartodoc-core.yml +++ b/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 diff --git a/shiny/experimental/api-examples/card_title/app.py b/shiny/experimental/api-examples/card_title/app.py deleted file mode 100644 index a38838021..000000000 --- a/shiny/experimental/api-examples/card_title/app.py +++ /dev/null @@ -1,18 +0,0 @@ -import shiny.experimental as x -from shiny import App, ui - -app_ui = ui.page_fluid( - x.ui.card( - ui.card_header("This is the header"), - x.ui.card_body( - x.ui.card_title("This is the title"), - ui.p("This is the body."), - ui.p("This is still the body."), - ), - ui.card_footer("This is the footer"), - full_screen=True, - ) -) - - -app = App(app_ui, server=None) diff --git a/shiny/experimental/ui/__init__.py b/shiny/experimental/ui/__init__.py index 72796b312..5e7cf070b 100644 --- a/shiny/experimental/ui/__init__.py +++ b/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", ) diff --git a/shiny/experimental/ui/_card.py b/shiny/experimental/ui/_card.py index 1d7ad9cc2..078fda92f 100644 --- a/shiny/experimental/ui/_card.py +++ b/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`. diff --git a/shiny/experimental/ui/_deprecated.py b/shiny/experimental/ui/_deprecated.py new file mode 100644 index 000000000..ba454b9ef --- /dev/null +++ b/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", +)