From 12c20772acbb130e8671a3c460368fb25b55e339 Mon Sep 17 00:00:00 2001
From: Tim van der Meij <timvandermeij@gmail.com>
Date: Tue, 18 Aug 2020 23:04:56 +0200
Subject: [PATCH] Improve the field value parsing for choice widgets to handle
 `null` values

The specification states that the field value is `null` if no item is
selected and we didn't handle this case properly. Even though this did
not break the rendering because we always convert the value to an array
and the `includes` check in the display layer would simply not match,
the field value would be `[null]` which is not expected and strange from
an API perspective.

This commit fixes that by ensuring that we return an empty array in
case the field value is `null`. The API therefore still always gives an
array for the field value, but now the code is more specific so that the
value is either an empty array or an array of strings.
---
 src/core/annotation.js       | 11 +++++++----
 test/unit/annotation_spec.js |  4 ++--
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/core/annotation.js b/src/core/annotation.js
index 1da946338..5133633c0 100644
--- a/src/core/annotation.js
+++ b/src/core/annotation.js
@@ -1610,11 +1610,14 @@ class ChoiceWidgetAnnotation extends WidgetAnnotation {
       }
     }
 
-    // Determine the field value. In this case, it may be a string or an
-    // array of strings. For convenience in the display layer, convert the
-    // string to an array of one string as well.
-    if (!Array.isArray(this.data.fieldValue)) {
+    // The field value can be `null` if no item is selected, a string if one
+    // item is selected or an array of strings if multiple items are selected.
+    // For consistency in the API and convenience in the display layer, we
+    // always make the field value an array with zero, one or multiple items.
+    if (isString(this.data.fieldValue)) {
       this.data.fieldValue = [this.data.fieldValue];
+    } else if (!this.data.fieldValue) {
+      this.data.fieldValue = [];
     }
 
     // Process field flags for the display layer.
diff --git a/test/unit/annotation_spec.js b/test/unit/annotation_spec.js
index aaba14975..9964cb676 100644
--- a/test/unit/annotation_spec.js
+++ b/test/unit/annotation_spec.js
@@ -2479,8 +2479,8 @@ describe("annotation", function () {
     });
 
     it("should convert the field value to an array", function (done) {
-      const inputs = ["Foo", ["Foo", "Bar"]];
-      const outputs = [["Foo"], ["Foo", "Bar"]];
+      const inputs = [null, "Foo", ["Foo", "Bar"]];
+      const outputs = [[], ["Foo"], ["Foo", "Bar"]];
 
       let promise = Promise.resolve();
       for (let i = 0, ii = inputs.length; i < ii; i++) {