feat: Replace country-regex with country-iso-search

draftlogs/7856_add.md

@@ -0,0 +1 @@
+- Replace `country-regex` with `country-iso-search` to search for country names in choropleth, scattergeo traces [[#7856](https://github.com/plotly/plotly.js/pull/7856)]

package.json

@@ -83,7 +83,7 @@
     "color": "^5.0.0",
     "color-normalize": "1.5.0",
     "color-rgba": "3.0.0",
-    "country-regex": "^1.1.0",
+    "country-iso-search": "^0.1.1",
     "d3-force": "^1.2.1",
     "d3-format": "^1.4.5",
     "d3-geo": "^1.12.1",

src/lib/custom_country_codes.ts

@@ -0,0 +1,45 @@
+import type { CountryRecord } from 'country-iso-search';
+
+/**
+ * Plotly-specific country records for disputed and unrecognized territories
+ * that are not part of ISO 3166-1. Each entry uses an ISO3-like code in the
+ * `X` range (reserved by ISO 3166-1 for user-assigned codes) so these regions
+ * can be looked up alongside standard countries from `country-iso-search`.
+ */
+export const COUNTRIES_X: ReadonlyArray<CountryRecord> = [
+    {
+        iso3: 'XAC',
+        iso2: '',
+        m49: '',
+        name: 'Aksai Chin',
+        aliases: []
+    },
+    {
+        iso3: 'XAP',
+        iso2: '',
+        m49: '',
+        name: 'Arunachal Pradesh',
+        aliases: []
+    },
+    {
+        iso3: 'XBT',
+        iso2: '',
+        m49: '',
+        name: 'Bir Tawil',
+        aliases: []
+    },
+    {
+        iso3: 'XHT',
+        iso2: '',
+        m49: '',
+        name: 'Halaib Triangle',
+        aliases: []
+    },
+    {
+        iso3: 'XJK',
+        iso2: '',
+        m49: '',
+        name: 'Jammu and Kashmir',
+        aliases: []
+    }
+];

src/lib/geo_location_utils.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var d3 = require('@plotly/d3');
-var countryRegex = require('country-regex');
+const { COUNTRIES, createLookup } = require('country-iso-search');
 var { area: turfArea } = require('@turf/area');
 var { centroid: turfCentroid } = require('@turf/centroid');
 var { bbox: turfBbox } = require('@turf/bbox');
@@ -12,9 +12,9 @@ var isPlainObject = require('./is_plain_object');
 var nestedProperty = require('./nested_property');
 var polygon = require('./polygon');
 const { usaLocationAbbreviations, usaLocationList } = require('./usa_location_names');
+const { COUNTRIES_X } = require('./custom_country_codes');
 
-// make list of all country iso3 ids from at runtime
-var countryIds = Object.keys(countryRegex);
+const { lookupAlpha3 } = createLookup([...COUNTRIES, ...COUNTRIES_X]);
 
 var locationmodeToIdFinder = {
     'ISO-3': identity,
@@ -23,13 +23,8 @@ var locationmodeToIdFinder = {
 };
 
 function countryNameToISO3(countryName) {
-    for (var i = 0; i < countryIds.length; i++) {
-        var iso3 = countryIds[i];
-        var regex = new RegExp(countryRegex[iso3]);
-
-        if (regex.test(countryName.trim().toLowerCase())) return iso3;
-    }
-
+    const iso3 = lookupAlpha3(countryName);
+    if (iso3) return iso3;
     loggers.log('Unrecognized country name: ' + countryName + '.');
 
     return false;

src/traces/choropleth/defaults.js

@@ -4,12 +4,6 @@ var Lib = require('../../lib');
 var colorscaleDefaults = require('../../components/colorscale/defaults');
 var attributes = require('./attributes');
 
-const locationmodeBreakingChangeWarning = [
-    'The library used by the *country names* `locationmode` option is changing in the next major version.',
-    'Some country names in existing plots may not work in the new version.',
-    'To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.'
-].join(' ');
-
 module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     function coerce(attr, dflt) {
         return Lib.coerce(traceIn, traceOut, attributes, attr, dflt);
@@ -34,10 +28,6 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
 
     var locationMode = coerce('locationmode', locationmodeDflt);
 
-    if (locationMode === 'country names') {
-        Lib.warn(locationmodeBreakingChangeWarning);
-    }
-
     if (locationMode === 'geojson-id') {
         coerce('featureidkey');
     }

src/traces/scattergeo/attributes.js

@@ -14,11 +14,6 @@ var scatterMarkerAttrs = scatterAttrs.marker;
 var scatterLineAttrs = scatterAttrs.line;
 var scatterMarkerLineAttrs = scatterMarkerAttrs.line;
 
-const breakingChangeWarning = [
-    'The library used by the *country names* `locationmode` option is changing in an upcoming version.',
-    'Country names in existing plots may not work in the new version.'
-].join(' ');
-
 module.exports = overrideAll(
     {
         lon: {
@@ -43,7 +38,6 @@ module.exports = overrideAll(
             values: ['ISO-3', 'USA-states', 'country names', 'geojson-id'],
             dflt: 'ISO-3',
             description: [
-                breakingChangeWarning,
                 'Determines the set of locations used to match entries in `locations`',
                 'to regions on the map.',
                 'Values *ISO-3*, *USA-states*, *country names* correspond to features on',

src/traces/scattergeo/defaults.js

@@ -10,12 +10,6 @@ var handleFillColorDefaults = require('../scatter/fillcolor_defaults');
 
 var attributes = require('./attributes');
 
-const locationmodeBreakingChangeWarning = [
-    'The library used by the *country names* `locationmode` option is changing in the next major version.',
-    'Some country names in existing plots may not work in the new version.',
-    'To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.'
-].join(' ');
-
 module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     function coerce(attr, dflt) {
         return Lib.coerce(traceIn, traceOut, attributes, attr, dflt);
@@ -33,10 +27,6 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
 
         var locationMode = coerce('locationmode', locationmodeDflt);
 
-        if (locationMode === 'country names') {
-            Lib.warn(locationmodeBreakingChangeWarning);
-        }
-
         if (locationMode === 'geojson-id') {
             coerce('featureidkey');
         }

src/types/generated/schema.d.ts

@@ -2346,7 +2346,7 @@ export interface ChoroplethData {
      */
     legendwidth?: number;
     /**
-     * The library used by the *country names* `locationmode` option is changing in an upcoming version. Country names in existing plots may not work in the new version. Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).
+     * Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).
      * @default 'ISO-3'
      */
     locationmode?: 'ISO-3' | 'USA-states' | 'country names' | 'geojson-id';
@@ -8240,7 +8240,7 @@ export interface ScattergeoData {
         width?: number;
     };
     /**
-     * The library used by the *country names* `locationmode` option is changing in an upcoming version. Country names in existing plots may not work in the new version. Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).
+     * Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).
      * @default 'ISO-3'
      */
     locationmode?: 'ISO-3' | 'USA-states' | 'country names' | 'geojson-id';

test/jasmine/tests/geo_test.js

@@ -886,6 +886,18 @@ describe('geojson / topojson utils', function() {
 
             expect(out).toEqual(false);
         });
+
+        it('with *country names* locationmode and an ISO 3166-1 short-name suffix', () => {
+            const out = _locationToFeature(topojson, 'Korea, Republic of', 'country names');
+
+            expect(out.id).toEqual('KOR');
+        });
+
+        it('with *country names* locationmode and a custom country code', () => {
+            const out = _locationToFeature(topojson, 'Aksai Chin', 'country names');
+
+            expect(out.id).toEqual('XAC');
+        });
     });
 
     describe('should distinguish between US and US Virgin Island', function() {

test/plot-schema.json

@@ -24133,7 +24133,7 @@
           "valType": "number"
         },
         "locationmode": {
-          "description": "The library used by the *country names* `locationmode` option is changing in an upcoming version. Country names in existing plots may not work in the new version. Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).",
+          "description": "Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).",
           "dflt": "ISO-3",
           "editType": "calc",
           "valType": "enumerated",
@@ -61010,7 +61010,7 @@
           }
         },
         "locationmode": {
-          "description": "The library used by the *country names* `locationmode` option is changing in an upcoming version. Country names in existing plots may not work in the new version. Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).",
+          "description": "Determines the set of locations used to match entries in `locations` to regions on the map. Values *ISO-3*, *USA-states*, *country names* correspond to features on the base map and value *geojson-id* corresponds to features from a custom GeoJSON linked to the `geojson` attribute. *USA-states* accepts both two-letter abbreviations (e.g. *CA*) and full state names (e.g. *California*).",
           "dflt": "ISO-3",
           "editType": "calc",
           "valType": "enumerated",