Handle NaN values and add JSDoc to compareArrays

Per review suggestion from camdecoster:
- Add JSDoc comment documenting ascending-order comparison,
  NaN-sorting behavior, and prefix handling.
- Handle values that do not order against each other (NaN,
  undefined) by sorting them after every orderable value.
- Add test verifying NaN color values sort after orderable
  values in bundled parallel-categories paths.

The 4 pre-existing drag/reorder test failures are unchanged
by this commit (27->28 passing, same 4 baseline failures).

Author: CAOShurong

src/traces/parcats/parcats.js

@@ -370,12 +370,27 @@ function compareRawColor(a, b) {
     }
 }
 
+/**
+ * Compare two sort arrays element by element in ascending order.
+ * Values that do not order against each other, for example NaN, sort last.
+ * The shorter array sorts first when one array is a prefix of the other.
+ *
+ * @param {Array} a
+ * @param {Array} b
+ */
 function compareArrays(a, b) {
     for(var i = 0; i < Math.min(a.length, b.length); i++) {
-        if(a[i] < b[i]) {
-            return -1;
-        } else if(a[i] > b[i]) {
-            return 1;
+        var valA = a[i];
+        var valB = b[i];
+
+        if(valA < valB) return -1;
+        if(valA > valB) return 1;
+        // Handle values that do not order against each other (NaN, undefined, etc.)
+        if(valA !== valB) {
+            // Sort these after every orderable value.
+            var badA = isNaN(valA);
+            var badB = isNaN(valB);
+            if(badA !== badB) return badA ? 1 : -1;
         }
     }
 

test/jasmine/tests/parcats_test.js

@@ -307,6 +307,32 @@ describe('Basic parcats trace', function() {
             .then(done, done.fail);
     });
 
+    it('should sort NaN color values after orderable values', function(done) {
+        var trace = {
+            type: 'parcats',
+            dimensions: [
+                {values: ['a', 'a', 'a', 'a']},
+                {values: ['b', 'b', 'b', 'b']}
+            ],
+            line: {color: [10, NaN, 2, NaN]},
+            bundlecolors: true
+        };
+
+        Plotly.newPlot(gd, [trace])
+            .then(function() {
+                var parcatsViewModel = d3Select('g.trace.parcats').datum();
+                var pathColors = parcatsViewModel.paths.map(function(path) {
+                    return path.model.rawColor;
+                });
+
+                // Orderable values sort first, NaN values sort last
+                expect(pathColors.slice(0, 2)).toEqual([2, 10]);
+                expect(isNaN(pathColors[2])).toBe(true);
+                expect(isNaN(pathColors[3])).toBe(true);
+            })
+            .then(done, done.fail);
+    });
+
     it('should compute initial model views properly', function(done) {
         Plotly.newPlot(gd, basicMock)
             .then(function() {