Refactor `build-thread` (#2321)

- Add additional type-checking and clarify comments
- Use ES6 conventions
- Structure code for readability

src/sidebar/test/build-thread-test.js

@@ -141,6 +141,39 @@ describe('build-thread', function () {
       ]);
     });
 
+    it('handles annotations that have their own ID in their `references` list', () => {
+      const fixture = [
+        { id: '1', references: ['1'] },
+        { id: '2', references: ['1'] },
+        { id: '3', references: ['1', '3'] },
+      ];
+      const thread = createThread(fixture);
+      assert.deepEqual(thread, [
+        {
+          annotation: {
+            id: '1',
+            references: ['1'],
+          },
+          children: [
+            {
+              annotation: {
+                id: '2',
+                references: ['1'],
+              },
+              children: [],
+            },
+            {
+              annotation: {
+                id: '3',
+                references: ['1', '3'],
+              },
+              children: [],
+            },
+          ],
+        },
+      ]);
+    });
+
     it('handles missing parent annotations', function () {
       const fixture = [
         {

src/types/api.js

@@ -38,6 +38,8 @@
  *
  * @typedef Annotation
  * @prop {string} [id]
+ * @prop {string} [$tag] - A locally-generated unique identifier for annotations
+ *       that have not been saved to the service yet (and thus do not have an id)
  * @prop {string[]} [references]
  * @prop {string} created
  * @prop {string} group