From 36563647e2e503de53c4b4e477a814a771945bb9 Mon Sep 17 00:00:00 2001
From: Garrick Aden-Buie <garrick@adenbuie.com>
Date: Wed, 12 Jun 2024 15:29:36 -0400
Subject: [PATCH] feat(card_image): Add `alt` parameter

---
 R/card.R                      | 10 ++++++++++
 man/card_body.Rd              | 10 ++++++++++
 tests/testthat/_snaps/card.md |  6 +++---
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/R/card.R b/R/card.R
index fecf8cca2..3f25ded2a 100644
--- a/R/card.R
+++ b/R/card.R
@@ -256,6 +256,14 @@ card_footer <- function(..., class = NULL) {
 #'   starting with `https://` or similar) will be base64 encoded and provided to
 #'   the `src` attribute of the `<img>`. Alternatively, you may directly set
 #'   the image `src`, in which case `file` is ignored.
+#' @param alt Alternate text for the image, used by screen readers and assistive
+#'   devices. Provide alt text with a description of the image for any images
+#'   with important content. If alt text is not provided, the image will be
+#'   considered to be decorative and will not be read or announced by screen
+#'   readers.
+#'
+#'   For more information, the Web Accessibility Initiative (WAI) has a
+#'   [helpful tutorial on alt text](https://www.w3.org/WAI/tutorials/images/).
 #' @param href An optional URL to link to when a user clicks on the image.
 #' @param border_radius Which side of the image should have rounded corners,
 #'   useful when `card_image()` is used as an image cap at the top or bottom of
@@ -279,6 +287,7 @@ card_footer <- function(..., class = NULL) {
 #' @export
 card_image <- function(
   file,
+  alt = "",
   ...,
   src = NULL,
   href = NULL,
@@ -305,6 +314,7 @@ card_image <- function(
 
   image <- tags$img(
     src = src,
+    alt = alt,
     class = "img-fluid",
     class = switch(
       border_radius,
diff --git a/man/card_body.Rd b/man/card_body.Rd
index 4e01544aa..ff542dcfc 100644
--- a/man/card_body.Rd
+++ b/man/card_body.Rd
@@ -31,6 +31,7 @@ card_footer(..., class = NULL)
 
 card_image(
   file,
+  alt = "",
   ...,
   src = NULL,
   href = NULL,
@@ -86,6 +87,15 @@ starting with \verb{https://} or similar) will be base64 encoded and provided to
 the \code{src} attribute of the \verb{<img>}. Alternatively, you may directly set
 the image \code{src}, in which case \code{file} is ignored.}
 
+\item{alt}{Alternate text for the image, used by screen readers and assistive
+devices. Provide alt text with a description of the image for any images
+with important content. If alt text is not provided, the image will be
+considered to be decorative and will not be read or announced by screen
+readers.
+
+For more information, the Web Accessibility Initiative (WAI) has a
+\href{https://www.w3.org/WAI/tutorials/images/}{helpful tutorial on alt text}.}
+
 \item{href}{An optional URL to link to when a user clicks on the image.}
 
 \item{border_radius}{Which side of the image should have rounded corners,
diff --git a/tests/testthat/_snaps/card.md b/tests/testthat/_snaps/card.md
index a5f9510f5..31126f0b5 100644
--- a/tests/testthat/_snaps/card.md
+++ b/tests/testthat/_snaps/card.md
@@ -5,7 +5,7 @@
         "image cap on top of card")))
     Output
       <div class="card bslib-card bslib-mb-spacing html-fill-item html-fill-container" data-bslib-card-init data-require-bs-caller="card()" data-require-bs-version="5">
-        <img class="img-fluid card-img-top" src="https://example.com/image.jpg"/>
+        <img alt="" class="img-fluid card-img-top" src="https://example.com/image.jpg"/>
         <div class="card-body bslib-gap-spacing html-fill-item html-fill-container" style="margin-top:auto;margin-bottom:auto;flex:1 1 auto;">image cap on top of card</div>
         <script data-bslib-card-init>bslib.Card.initializeAllCards();</script>
       </div>
@@ -18,7 +18,7 @@
     Output
       <div class="card bslib-card bslib-mb-spacing html-fill-item html-fill-container" data-bslib-card-init data-require-bs-caller="card()" data-require-bs-version="5">
         <div class="card-body bslib-gap-spacing html-fill-item html-fill-container" style="margin-top:auto;margin-bottom:auto;flex:1 1 auto;">image cap on bottom of card</div>
-        <img class="img-fluid card-img-bottom" src="https://example.com/image.jpg"/>
+        <img alt="" class="img-fluid card-img-bottom" src="https://example.com/image.jpg"/>
         <script data-bslib-card-init>bslib.Card.initializeAllCards();</script>
       </div>
 
@@ -30,7 +30,7 @@
     Output
       <div class="card bslib-card bslib-mb-spacing html-fill-item html-fill-container" data-bslib-card-init data-require-bs-caller="card()" data-require-bs-version="5">
         <div class="card-header">header</div>
-        <img src="https://example.com/image.jpg" class="img-fluid"/>
+        <img src="https://example.com/image.jpg" alt="" class="img-fluid"/>
         <div class="card-body bslib-gap-spacing html-fill-item html-fill-container" style="margin-top:auto;margin-bottom:auto;flex:1 1 auto;">image not a cap</div>
         <script data-bslib-card-init>bslib.Card.initializeAllCards();</script>
       </div>