feat(suggestion): expose suburb field from API in suggestion (#469)

* feat(suggestion): add suburb field in suggestion

the places API sometimes returns a suburb field but this field was not
exposed in suggestion. it is now exposed.

fixes #337

* doc(suggestion): document suburb field

add documentation about the newly exposed suburb field in the
suggestion object

Author: JonathanMontane

docs/source/documentation.html.md.erb

@@ -605,6 +605,21 @@ Examples:
     </tr>
     <tr>
 <td markdown="1">
+<div class="api-entry" id="api-suggestion-suburb"><code>suburb</code></div>
+
+Type: **string**
+</td>
+<td markdown="1">
+Suburb name.
+
+Examples:
+
+ - Angelino heights
+ - Harbor City
+</td>
+    </tr>
+    <tr>
+<td markdown="1">
 <div class="api-entry" id="api-suggestion-latlng"><code>latlng</code></div>
 
 Type: **Object**

src/formatHit.js

@@ -46,6 +46,9 @@ export default function formatHit({
       ? hit.administrative[0]
       : undefined;
     const city = hit.city && hit.city[0] !== name ? hit.city[0] : undefined;
+    const suburb = hit.suburb && hit.suburb[0] !== name
+      ? hit.suburb[0]
+      : undefined;
 
     const highlight = {
       name: getBestHighlightedForm(hit._highlightResult.locale_names),
@@ -56,12 +59,16 @@ export default function formatHit({
         ? getBestHighlightedForm(hit._highlightResult.administrative)
         : undefined,
       country: country ? hit._highlightResult.country.value : undefined,
+      suburb: suburb
+        ? getBestHighlightedForm(hit._highlightResult.suburb)
+        : undefined,
     };
 
     const suggestion = {
       name,
       administrative,
       city,
+      suburb,
       country,
       countryCode: findCountryCode(hit._tags),
       type: findType(hit._tags),

src/formatHit.test.js

@@ -37,6 +37,46 @@ describe('formatHit', () => {
         highlight: { administrative: undefined, name: 'Île-de-France' },
       },
     }),
+    getTestCase({
+      name: 'no suburb',
+      hit: { suburb: undefined },
+      expected: {
+        suburb: undefined,
+        highlight: { suburb: undefined },
+      },
+    }),
+    getTestCase({
+      name: 'suburb[0] === locale_names[0]',
+      hit: {
+        suburb: ['Harbor City'],
+        locale_names: ['Harbor City'],
+        _highlightResult: {
+          locale_names: [{ value: 'Harbor City' }],
+          suburb: [{ value: 'Harbor City' }],
+        },
+      },
+      expected: {
+        suburb: undefined,
+        name: 'Harbor City',
+        highlight: { suburb: undefined, name: 'Harbor City' },
+      },
+    }),
+    getTestCase({
+      name: 'suburb[0] !== locale_names[0]',
+      hit: {
+        suburb: ['Harbor City'],
+        locale_names: ['237th Street'],
+        _highlightResult: {
+          locale_names: [{ value: '237th Street' }],
+          suburb: [{ value: 'Harbor City' }],
+        },
+      },
+      expected: {
+        suburb: 'Harbor City',
+        name: '237th Street',
+        highlight: { suburb: 'Harbor City', name: '237th Street' },
+      },
+    }),
     getTestCase({
       name: 'locale_names[1] is matching',
       hit: {
@@ -156,6 +196,7 @@ describe('formatHit', () => {
         name: output.name,
         administrative: output.administrative,
         city: output.city,
+        suburb: output.suburb,
         country: output.country,
         countryCode: output.countryCode,
         type: output.type,