feat: add FA Legend function

fixes #1

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export("%>%")
+export(addFaLegend)
 export(faIcons)
 importFrom(magrittr,"%>%")
 importFrom(rsvg,rsvg_png)

R/faIcons.R

@@ -123,3 +123,86 @@ faIcons <- function(icon = "circle",
 }
 
 
+#' Add a Font Awesome legend to a map
+#'
+#' Manually specify icons, labels, and colours to add a Font Awesome legend to a
+#' map. Useful in conjunction with [faIcons()] to communicate the meaning of
+#' icons/colours.
+#'
+#' @param icons Name of the Font Awesome icons, passed to [fontawesome::fa()]. A
+#'   full list of available icons can be found using
+#'   [fontawesome::fa_metadata()].
+#' @param labels Labels for each `icon`; should be the same length as `icons`.
+#' @param colors Colours to use for each `icon`. If `length(colors) == 1L` it is
+#'   recycled for all icons. Otherwise should be the same length as `icons`.
+#' @param title the legend title; optional.
+#' @inheritParams leaflet::addControl
+#'
+#' @return a [leaflet][leaflet::leaflet-package] widget
+#' @export
+#'
+#' @examples
+#' library(leaflet)
+#' addFaLegend(
+#'   map = leaflet(),
+#'   icons = c("beer", "school"),
+#'   labels = c("Pub", "University"),
+#'   colors = c("red", "blue"),
+#'   title = "Student Hangout"
+#' )
+addFaLegend <- function(map,
+                        icons,
+                        labels,
+                        colors = "black",
+                        title = NULL,
+                        position = c("topright", "bottomright", "bottomleft", "topleft"),
+                        layerId = NULL,
+                        className = "info legend",
+                        data = leaflet::getMapData(map)) {
+  position <- match.arg(position)
+
+  # format title
+  html_title <- ""
+  if (!is.null(title)) {
+    html_title <- paste0("<div style='margin-bottom:3px'><strong>",
+                         title,
+                         "</strong></div>")
+  }
+
+  assemble_legend_item <-
+    function(icon, label, color) {
+      paste0(fontawesome::fa(
+        icon,
+        width = "1em",
+        height = "1em",
+        fill = color
+      ),
+      "   ",
+      label)
+    }
+
+  html <-
+    paste0(html_title,
+           paste0(
+             purrr::pmap_vec(
+               tibble::tibble(
+                 icon = icons,
+                 label = labels,
+                 color = colors
+               ),
+               assemble_legend_item
+             ),
+             collapse = "<br>"
+           ),
+
+           collapse = "<br>")
+
+  leaflet::addControl(
+    map = map,
+    html = html,
+    position = position,
+    layerId = layerId,
+    className = className,
+    data = data
+  )
+}