customization: support custom lodash template to render result row

this is the second (after CSS), very powerful customization feature: it
allows a user of the element to define a <template row> tag inside the
custom element, and inside of that they can create HTML markup as well
as access the data of the row (the Feature) through the lodash template
language.

Example:

<ge-autocomplete …>
	<template row>
	  <div>${feature.properties.gid}: ${feature.properties.name}</div>
	</template>
</ge-autocomplete>

Author: mxlje

package-lock.json

@@ -12,6 +12,9 @@
     "@geocodeearth/core-js": "^0.0.7",
     "downshift": "6.1.3",
     "lodash.debounce": "^4.0.8",
+    "lodash.escape": "^4.0.1",
+    "lodash.template": "^4.5.0",
+    "lodash.unescape": "^4.0.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   },

package.json

@@ -5,6 +5,7 @@ import debounce from 'lodash.debounce'
 import css from './autocomplete.css'
 import strings from '../strings'
 import { LocationMarker, Loading } from '../icons'
+import escape from '../escape'
 
 const emptyResults = {
   text: '',
@@ -22,7 +23,8 @@ export default ({
   onSelect: userOnSelectItem,
   onChange: userOnChange,
   onError: userOnError,
-  environment = window
+  environment = window,
+  rowTemplate
 }) => {
   const [results, setResults] = useState(emptyResults)
   const [isLoading, setIsLoading] = useState(false)
@@ -150,20 +152,33 @@ export default ({
 
       <ol {...getMenuProps()} className={showResults ? 'results' : 'results-empty'}>
         {showResults &&
-          results.features.map((item, index) => (
-            <li
-              className={
-                highlightedIndex === index
-                  ? 'result-item result-item-active'
-                  : 'result-item'
-              }
-              key={item.properties.id}
-              {...getItemProps({ item, index })}
-            >
-              <LocationMarker className='result-item-icon' />
-              {itemToString(item)}
-            </li>
-          ))}
+          results.features.map((item, index) => {
+            // render row with custom template, if available
+            // the feature itself is recursively escaped as we can’t guarantee safe data from the API
+            if (typeof rowTemplate === 'function') {
+              return <li
+                key={item.properties.id}
+                {...getItemProps({ item, index })}
+                dangerouslySetInnerHTML={{ __html: rowTemplate(escape({
+                  ...item,
+                  active: highlightedIndex === index
+                })) }}
+              />
+            } else {
+              return <li
+                className={
+                  highlightedIndex === index
+                    ? 'result-item result-item-active'
+                    : 'result-item'
+                }
+                key={item.properties.id}
+                {...getItemProps({ item, index })}
+              >
+                <LocationMarker className='result-item-icon' />
+                {itemToString(item)}
+              </li>
+            }
+          })}
 
         <div className='attribution'>
           ©&nbsp;<a href="https://geocode.earth">Geocode Earth</a>,&nbsp;

src/autocomplete/autocomplete.js

@@ -0,0 +1,18 @@
+import _escape from 'lodash.escape'
+
+// escape takes any value (primarily objects) and recursively escapes the values
+const escape = (v) => {
+  if (typeof v === 'string') return _escape(v)
+  if (typeof v === 'number' || typeof v === 'boolean') return v
+  if (Array.isArray(v)) return v.map(l => escape(l))
+
+  return Object.keys(v).reduce(
+    (attrs, key) => ({
+      ...attrs,
+      [key]: escape(v[key]),
+    }),
+    {}
+  )
+}
+
+export default escape

src/escape.js

@@ -2,6 +2,8 @@ import React, { useMemo } from 'react'
 import ReactDOM from 'react-dom'
 import Autocomplete from './autocomplete'
 import compact from './compact'
+import _template from 'lodash.template'
+import _unescape from 'lodash.unescape'
 
 const customElementName = 'ge-autocomplete'
 
@@ -131,6 +133,7 @@ class GEAutocomplete extends HTMLElement {
 
   connectedCallback () {
     this.importStyles()
+    this.importRowTemplate()
     this.render()
   }
 
@@ -146,9 +149,29 @@ class GEAutocomplete extends HTMLElement {
     this.shadowRoot.appendChild(styles)
   }
 
+  // importRowTemplate looks for a <template row> tag inside the custom element
+  // and stores its contents as a lodash template, which is then passed on to
+  // the autocomplete component
+  importRowTemplate() {
+    const tmpl = this.querySelector('template[row]')
+    if (tmpl === null) return
+
+    this.rowTemplate = _template(
+      _unescape(tmpl.innerHTML.trim()), // unescape is important for `<%` etc. lodash tags
+      { variable: 'feature' } // namespace the passed in Feature as `feature` so missing keys don’t throw
+    )
+
+    // contrary to the way custom styles are handled above we remove the <template> when we’re done
+    // so it doesn’t hang around in the host document (not the Shadow DOM)
+    tmpl.remove()
+  }
+
   render () {
     ReactDOM.render(
-      <WebComponent {...this.props} host={this} />,
+      <WebComponent
+        {...this.props}
+        host={this}
+        rowTemplate={this.rowTemplate} />,
       this.shadowRoot
     )
   }