From 8ecd0db82ee547ca099d2a3721546679d61416a0 Mon Sep 17 00:00:00 2001
From: Jack Davison <davison.jack.jd@gmail.com>
Date: Thu, 18 Jul 2024 10:24:52 +0100
Subject: [PATCH] feat: add FA Legend function

fixes #1
---
 NAMESPACE          |  1 +
 R/faIcons.R        | 83 ++++++++++++++++++++++++++++++++++++++++++++++
 man/addFaLegend.Rd | 61 ++++++++++++++++++++++++++++++++++
 3 files changed, 145 insertions(+)
 create mode 100644 man/addFaLegend.Rd

diff --git a/NAMESPACE b/NAMESPACE
index a58c701..3cda807 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export("%>%")
+export(addFaLegend)
 export(faIcons)
 importFrom(magrittr,"%>%")
 importFrom(rsvg,rsvg_png)
diff --git a/R/faIcons.R b/R/faIcons.R
index ba172a3..35531e1 100644
--- a/R/faIcons.R
+++ b/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
+  )
+}
diff --git a/man/addFaLegend.Rd b/man/addFaLegend.Rd
new file mode 100644
index 0000000..8a0b76b
--- /dev/null
+++ b/man/addFaLegend.Rd
@@ -0,0 +1,61 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/faIcons.R
+\name{addFaLegend}
+\alias{addFaLegend}
+\title{Add a Font Awesome legend to a map}
+\usage{
+addFaLegend(
+  map,
+  icons,
+  labels,
+  colors = "black",
+  title = NULL,
+  position = c("topright", "bottomright", "bottomleft", "topleft"),
+  layerId = NULL,
+  className = "info legend",
+  data = leaflet::getMapData(map)
+)
+}
+\arguments{
+\item{map}{a map widget object created from \code{\link[leaflet]{leaflet}()}}
+
+\item{icons}{Name of the Font Awesome icons, passed to \code{\link[fontawesome:fa]{fontawesome::fa()}}. A
+full list of available icons can be found using
+\code{\link[fontawesome:fa_metadata]{fontawesome::fa_metadata()}}.}
+
+\item{labels}{Labels for each \code{icon}; should be the same length as \code{icons}.}
+
+\item{colors}{Colours to use for each \code{icon}. If \code{length(colors) == 1L} it is
+recycled for all icons. Otherwise should be the same length as \code{icons}.}
+
+\item{title}{the legend title; optional.}
+
+\item{position}{position of control: "topleft", "topright", "bottomleft", or
+"bottomright"}
+
+\item{layerId}{the layer id}
+
+\item{className}{extra CSS classes to append to the control, space separated}
+
+\item{data}{the data object from which the argument values are derived; by
+default, it is the \code{data} object provided to \code{leaflet()}
+initially, but can be overridden}
+}
+\value{
+a \link[leaflet:leaflet-package]{leaflet} widget
+}
+\description{
+Manually specify icons, labels, and colours to add a Font Awesome legend to a
+map. Useful in conjunction with \code{\link[=faIcons]{faIcons()}} to communicate the meaning of
+icons/colours.
+}
+\examples{
+library(leaflet)
+addFaLegend(
+  map = leaflet(),
+  icons = c("beer", "school"),
+  labels = c("Pub", "University"),
+  colors = c("red", "blue"),
+  title = "Student Hangout"
+)
+}