docs(tooltip,popover): Document trigger accessibility considerations (#825)

Author: gadenbuie

R/popover.R

@@ -26,12 +26,8 @@
 #'
 #' @section Theming/Styling:
 #'
-#'   Like other bslib components, popovers can be themed by supplying [relevant
-#'   theming
-#'   variables](https://rstudio.github.io/bslib/articles/bs5-variables/index.html#popover-bg)
-#'   to [bs_theme()], which effects styling of every popover on the page. To
-#'   style a _specific_ popover differently from other popovers, utilize the
-#'   `customClass` option:
+#'   ```{r child="man/fragments/tooltip-popover_theming.Rmd", el = "popover"}
+#'   ```
 #'
 #'   ```
 #'   popover(
@@ -46,6 +42,27 @@
 #'   bs_theme() |> bs_add_rules(".my-pop { max-width: none; }")
 #'   ```
 #'
+#' @section Accessibility of Popover Triggers:
+#'
+#'   ```{r child="man/fragments/tooltip-popover_a11y-trigger.Rmd", el = "popover"}
+#'   ```
+#'
+#'   ```r
+#'   popover(
+#'     bsicons::bs_icon("gear", title = "Settings"),
+#'     title = "Settings",
+#'     sliderInput("n", "Number of points", 1, 100, 50)
+#'   )
+#'   ```
+#'
+#'   ```r
+#'   popover(
+#'     fontawesome::fa("gear", a11y = "sem", title = "Settings"),
+#'     title = "Settings",
+#'     sliderInput("n", "Number of points", 1, 100, 50)
+#'   )
+#'   ```
+#'
 #' @describeIn popover Add a popover to a UI element
 #' @references <https://getbootstrap.com/docs/5.3/components/popovers/>
 #' @export

R/tooltip.R

@@ -17,12 +17,8 @@
 #'
 #' @section Theming/Styling:
 #'
-#'   Like other bslib components, tooltips can be themed by supplying [relevant
-#'   theming
-#'   variables](https://rstudio.github.io/bslib/articles/bs5-variables/index.html#tooltip-bg)
-#'   to [bs_theme()], which effects styling of every popover on the page. To
-#'   style a _specific_ popover differently from other popovers, utilize the
-#'   `customClass` option:
+#'   ```{r child="man/fragments/tooltip-popover_theming.Rmd", el="tooltip"}
+#'   ```
 #'
 #'   ```
 #'   tooltip(
@@ -37,6 +33,25 @@
 #'   bs_theme() |> bs_add_rules(".my-tip { max-width: none; }")
 #'   ```
 #'
+#' @section Accessibility of Tooltip Triggers:
+#'
+#'   ```{r child="man/fragments/tooltip-popover_a11y-trigger.Rmd", el = "tooltip"}
+#'   ```
+#'
+#'   ```r
+#'   tooltip(
+#'     bsicons::bs_icon("info-circle", title = "About tooltips"),
+#'     "Text shown in the tooltip."
+#'   )
+#'   ```
+#'
+#'   ```r
+#'   tooltip(
+#'     fontawesome::fa("info-circle", title = "About tooltips"),
+#'     "Text shown in the tooltip."
+#'   )
+#'   ```
+#'
 #' @describeIn tooltip Add a tooltip to a UI element
 #' @references <https://getbootstrap.com/docs/5.3/components/tooltips/>
 #' @export

man/fragments/tooltip-popover_a11y-trigger.Rmd

@@ -0,0 +1,19 @@
+```{r include = FALSE}
+el <- function() knitr::opts_current$get("el")
+```
+
+Because the user needs to interact with the `trigger` element to see the `r el()`, it's best practice to use an element that is typically accessible via keyboard interactions, like a button or a link.
+If you use a non-interactive element, like a `<span>` or text, bslib will automatically add the `tabindex="0"` attribute to the trigger element to make sure that users can reach the element with the keyboard.
+This means that in most cases you can use any element you want as the trigger.
+
+One place where it's important to consider the accessibility of the trigger is when using an icon without any accompanying text.
+In these cases, many R packages that provide icons will create an icon element with the assumption that the icon is decorative, which will make it inaccessible to users of assistive technologies.
+
+When using an icon as the primary trigger, ensure that the icon does not have `aria-hidden="true"` or `role="presentation"` attributes.
+Icon packages typically provide a way to specify a title for the icon, as well as a way to specify that the icon is not decorative.
+The title should be a short description of the purpose of the trigger, rather than a description of the icon itself.
+
+* If you're using [bsicons::bs_icon()], provide a `title`.
+* If you're using [fontawesome::fa()], set `a11y = "sem"` and provide a `title`.
+
+For example:

man/fragments/tooltip-popover_theming.Rmd

@@ -0,0 +1,9 @@
+```{r include = FALSE}
+el <- function() knitr::opts_current$get("el")
+```
+
+Like other bslib components, `r el()`s can be themed by supplying
+[relevant theming variables](https://rstudio.github.io/bslib/articles/bs5-variables/index.html#`r el()`-bg)
+to [bs_theme()],
+which effects styling of every `r el()` on the page.
+To style a _specific_ `r el()` differently from other `r el()`, utilize the `customClass` option: