feat(card_image): Improve card_image() API and usage

[gadenbuie]

This PR improves the card_image() API and fixes a few minor rough edges, including fixing #1071.

• Currently card_image() is by default wrapped in a card_body() container. This happens even if setting container = NULL because the card_image() result doesn't have a card_item class. This makes it impossible to use card_image() for the card image caps described in the Boostrap docs.

  With this PR, we now default to container = NULL and, when this is the case, call as.card_item() on the image so that the image is treated as a card item.

  I'm not sure how much value container adds -- it's easy enough to do card_body(card_image()) if that's really desired -- and I don't think there's any harm in unconditionally adding the card_item class to the image. I'd be in favor of deprecating the container argument (unless I've missed an important use case).

• border_radius gains "auto", the new default value. When border_radius = "auto", we add a card_image_auto class to the card_image() output that is detected by card(). We then automatically add the card-img-top, card-img-bottom, or card-img class if the card image is the first, last or only child. In all other cases, we don't modify the image tag.

• I changed the default value of card_image(fill = ) to FALSE. fill = TRUE might have worked better when card_image() was always wrapped in a card_body() but in most cases having fill = TRUE will cause the image to stretch, distorting the image. I don't think this is what most people want from card_image().

• I added a bit of logic such that a URI or non-local file path can be given to file. Instead of having to write

  card_image(file = NULL, src = "https://example.com/cat.png")

  users can just give the URL to file

  card_image("https://example.com/cat.png")

  This is backwards compatible in the sense that when a value is passed to src, that value is used directly. The advantage is that we won't even consulte file when src is provided, allowing card_image(src = "cat.png") to skip the base64 encoding.

• I added alt = "" as a default argument that appears before the dots. This has the side effect of marking most card_image() uses as decorative. That's probably better than the default of not having alt text at all, and it intends to bring increased attention to alt text without breaking existing apps by making alt required. Fixes card_image() should include explicit alt argument #1071

Example app

library(shiny)
# library(bslib)
pkgload::load_all()

card_img <- card_image(
  file = "https://picsum.photos/seed/posit/600/300"
)

ui <- page_fillable(
  layout_column_wrap(
    width = 300,
    # advanced usage with a card image overlay
    # see: https://getbootstrap.com/docs/5.3/components/card/#image-overlays
    card(
      class = "text-light",
      card_image(
        file = "https://picsum.photos/seed/posit/600/900",
        # fill = TRUE,
        border_radius = "all"
      ),
      card_body(
        class = "card-img-overlay",
        lorem::ipsum(2)
      )
    ),
    # Typical usage: card top cap
    card(
      card_img,
      lorem::ipsum(1),
    ),
    # Typical usage: card bottom cap
    card(
      lorem::ipsum(1),
      card_img,
    ),
    # Typical usage: images for top/bottom cap, plus one in middle
    card(
      fill = FALSE,
      card_img,
      lorem::ipsum(1, 2),
      card_img,
      lorem::ipsum(1, 2),
      card_img
    )
  )
)

server <- function(input, output, session) {

}

shinyApp(ui, server)

[cpsievert]

Let's investigate what this would mean for navset_card_*()

[gadenbuie]

Turns out this works perfectly with navset_card_*().

Kapture.2024-07-15.at.10.30.52.mp4