add full stop error, whitespace trimming, short text warning and extr…

…a examples

R/data-bad_link_text.R

@@ -9,7 +9,7 @@
 #' https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context).
 #'
 #' @format ## `bad_link_text`
-#' A data frame with 48 rows and 1 columns:
+#' A data frame with 52 rows and 1 columns:
 #' \describe{
 #'   \item{bad_link_text}{Lower cased examples of non-descriptive link text}
 #' }

R/external_link.R

@@ -19,6 +19,10 @@
 #' This also adds "This link opens in a new tab" as a visually hidden span
 #' element within the html outputted to warn non-visual users of the behaviour.
 #'
+#' The function will error if you end with a full stop, give a warning for
+#' particularly short link text and will automatically trim any leading or
+#' trailing white space inputted into link_text.
+#'
 #' Related links and guidance:
 #'
 #' * [Government digital services guidelines on the use of links](
@@ -36,7 +40,10 @@
 #' @param href URL that you want the link to point to
 #' @param link_text Text that will appear describing your link, must be
 #' descriptive of the page you are linking to. Vague text like 'click here' or
-#' 'here' will cause an error.
+#' 'here' will cause an error, as will ending in a full stop. Leading and
+#' trailing white space will be automatically trimmed. If the string is shorter
+#' than 7 characters a console warning will be thrown. There is no way to hush
+#' this other than providing more detail.
 #' @param add_warning Boolean for adding "(opens in new tab)" at the end of the
 #' link text to warn users of the behaviour. Be careful and consider
 #' accessibility before removing the visual warning.
@@ -56,17 +63,21 @@ external_link <- function(href, link_text, add_warning = TRUE) {
     stop("add_warning must be a TRUE or FALSE value")
   }
 
+  # Trim whitespace as I don't trust humans not to accidentally include
+  link_text <- stringr::str_trim(link_text)
+
   # Create a basic check for raw URLs
   is_url <- function(text) {
     url_pattern <- "^(https://|http://|www\\.)"
     grepl(url_pattern, text)
   }
 
+  # Check for vague link text on our list
   if (is_url(link_text)) {
     stop(paste0(
       link_text,
-      " has been recognise as a raw URL, please change the link_text value to",
-      " a description of the page being linked to instead"
+      " has been recognised as a raw URL, please change the link_text value",
+      "to a description of the page being linked to instead"
     ))
   }
 
@@ -82,6 +93,22 @@ external_link <- function(href, link_text, add_warning = TRUE) {
     )
   }
 
+  # Check if link text ends in a full stop
+  if (grepl("\\.$", link_text)) {
+    stop("link_text should not end with a full stop")
+  }
+
+  # Give a console warning if link text is under 7 characters
+  # Arbritary number that allows for R Shiny to be link text without a warning
+  if (nchar(link_text) < 7) {
+    warning(paste0(
+      "the link_text: ", link_text, ", is shorter than 7 characters, this is",
+      " unlikely to be descriptive for users, consider having more detailed",
+      " link text"
+    ))
+  }
+
+  # Assuming all else has passed, make the link text a nice accessible link
   if (add_warning) {
     link_text <- paste(link_text, "(opens in new tab)")
     hidden_span <- NULL # don't have extra hidden text if clear in main text

data-raw/bad_link_text.R

@@ -1,16 +1,16 @@
 bad_link_text <- data.frame(
   bad_link_text = c(
     # one word examples
-    "click", "csv", "dashboard", "document", "download", "file", "form",
-    "guidance", "here", "information", "jpeg", "jpg", "learn", "link", "more",
-    "next", "page", "pdf", "previous", "read", "site", "svg", "this", "web",
-    "webpage", "website", "word", "xslx",
+    "click", "csv", "continue", "dashboard", "document", "download", "file",
+    "form", "guidance", "here", "info", "information", "jpeg", "jpg", "learn",
+    "link", "more", "next", "page", "pdf", "previous", "read", "site", "svg",
+    "this", "web", "webpage", "website", "word", "xslx",
     # two word examples
     "click here", "click this link", "download csv", "download document",
     "download file", "download here", "download jpg", "download jpeg",
     "download pdf", "download png", "download svg", "download word",
     "download xslx", "further information", "go here", "learn more",
-    "read more", "this page", "web page", "web site"
+    "link to", "read more", "this page", "visit this", "web page", "web site"
   )
 )
 

tests/testthat/test-data-bad_link_text.R

@@ -4,7 +4,7 @@ test_that("Returns data frame", {
 
 test_that("Matches description", {
   # If this test fails, update the notes in R/data-bad_link_text.R
-  expect_equal(nrow(dfeshiny::bad_link_text), 48)
+  expect_equal(nrow(dfeshiny::bad_link_text), 52)
   expect_equal(names(dfeshiny::bad_link_text), "bad_link_text")
 })
 

tests/testthat/test-external_link.R

@@ -29,6 +29,7 @@ test_that("Rejects dodgy link text", {
   expect_error(external_link("https://shiny.posit.co/", "Click here"))
   expect_error(external_link("https://shiny.posit.co/", "here"))
   expect_error(external_link("https://shiny.posit.co/", "PDF"))
+  expect_error(external_link("https://shiny.posit.co/", "Full stop."))
   expect_error(external_link("https://shiny.posit.co/", "https://shiny.posit.co/"))
   expect_error(external_link("https://shiny.posit.co/", "http://shiny.posit.co/"))
   expect_error(external_link("https://shiny.posit.co/", "www.google.com"))
@@ -53,3 +54,33 @@ test_that("New tab warning always stays for non-visual users", {
     grepl("This link opens in a new tab", test_link_hidden$children[[1]])
   )
 })
+
+test_that("Surrounding whitespace shrubbery is trimmed", {
+  expect_equal(
+    external_link("https://shiny.posit.co/", "   R Shiny")$children[[2]],
+    "R Shiny (opens in new tab)"
+  )
+
+  expect_equal(
+    external_link("https://shiny.posit.co/", "R Shiny    ")$children[[2]],
+    "R Shiny (opens in new tab)"
+  )
+
+  expect_equal(
+    external_link("https://shiny.posit.co/", "   R Shiny   ")$children[[2]],
+    "R Shiny (opens in new tab)"
+  )
+})
+
+test_that("Warning appears for short link text and not for long text", {
+  expect_warning(
+    external_link("https://shiny.posit.co/", "R"),
+    paste0(
+      "the link_text: R, is shorter than 7 characters, this is",
+      " unlikely to be descriptive for users, consider having more detailed",
+      " link text"
+    )
+  )
+
+  expect_no_warning(external_link("https://shiny.posit.co/", "R Shiny"))
+})