Various fixes for store modules

- Fix typing for createSelector() wrapped selectors. (use @type, not @return)
- Fix `FrameInfo` type and use it. Previously it was orphaned.

src/sidebar/services/frame-sync.js

@@ -6,15 +6,6 @@ import uiConstants from '../ui-constants';
 import * as metadata from '../util/annotation-metadata';
 import { watch } from '../util/watch';
 
-/**
- * @typedef FrameInfo
- * @property {string} uri - Current primary URI of the document being displayed
- * @property {string[]} searchUris - List of URIs that should be passed to the
- *           search API when searching for annotations on this document.
- * @property {string} documentFingerprint - Fingerprint of the document, used
- *                    for PDFs
- */
-
 /**
  * Return a minimal representation of an annotation that can be sent from the
  * sidebar app to a connected frame.

src/sidebar/store/modules/annotations.js

@@ -405,7 +405,7 @@ function updateFlagStatus(id, isFlagged) {
 /**
  * Count the number of annotations (as opposed to notes or orphans)
  *
- * @return {number}
+ * @type {(state: any) => number}
  */
 const annotationCount = createSelector(
   state => state.annotations,
@@ -451,7 +451,7 @@ function findIDsForTags(state, tags) {
 /**
  * Retrieve currently-focused annotation identifiers
  *
- * @return {string[]}
+ * @type {(state: any) => string[]}
  */
 const focusedAnnotations = createSelector(
   state => state.focused,
@@ -461,7 +461,7 @@ const focusedAnnotations = createSelector(
 /**
  * Retrieve currently-highlighted annotation identifiers
  *
- * @return {string[]}
+ * @type {(state: any) => string[]}
  */
 const highlightedAnnotations = createSelector(
   state => state.highlighted,
@@ -481,7 +481,7 @@ function isAnnotationFocused(state, $tag) {
 /**
  * Are there any annotations still waiting to anchor?
  *
- * @return {boolean}
+ * @type {(state: any) => boolean}
  */
 const isWaitingToAnchorAnnotations = createSelector(
   state => state.annotations,
@@ -492,7 +492,7 @@ const isWaitingToAnchorAnnotations = createSelector(
  * Return all loaded annotations that are not highlights and have not been saved
  * to the server
  *
- * @return {Annotation[]}
+ * @type {(state: any) => Annotation[]}
  */
 const newAnnotations = createSelector(
   state => state.annotations,
@@ -504,7 +504,7 @@ const newAnnotations = createSelector(
  * Return all loaded annotations that are highlights and have not been saved
  * to the server
  *
- * @return {Annotation[]}
+ * @type {(state: any) => Annotation[]}
  */
 const newHighlights = createSelector(
   state => state.annotations,
@@ -515,7 +515,7 @@ const newHighlights = createSelector(
 /**
  * Count the number of page notes currently in the collection
  *
- * @return {number}
+ @type {(state: any) => number}
  */
 const noteCount = createSelector(
   state => state.annotations,

src/sidebar/store/modules/drafts.js

@@ -180,7 +180,7 @@ function getDraftIfNotEmpty(state, annotation) {
 /**
  * Returns a list of draft annotations which have no id.
  *
- * @return {Draft[]}
+ * @type {(state: any) => Annotation[]}
  */
 const unsavedAnnotations = createSelector(
   state => state,
@@ -200,7 +200,7 @@ const unsavedAnnotations = createSelector(
  * @prop {() => number} countDrafts
  * @prop {(a: Annotation) => Draft|null} getDraft
  * @prop {(a: Annotation) => Draft|null} getDraftIfNotEmpty
- * @prop {() => Draft[]} unsavedAnnotations
+ * @prop {() => Annotation[]} unsavedAnnotations
  */
 
 export default {

src/sidebar/store/modules/frames.js

@@ -7,6 +7,18 @@ import shallowEqual from 'shallowequal';
 
 import * as util from '../util';
 
+/**
+ * @typedef {import('../../../types/annotator').DocumentMetadata} DocumentMetadata
+ */
+
+/**
+ * @typedef Frame
+ * @prop {string|null} id
+ *   - Sub-frames will all have a id (frame identifier) set. The main frame's id is always `null`
+ * @prop {DocumentMetadata} metadata - Metadata about the document currently loaded in this frame
+ * @prop {string} uri - Current primary URI of the document being displayed
+ */
+
 function init() {
   // The list of frames connected to the sidebar app
   return [];
@@ -40,6 +52,8 @@ const actions = util.actionTypes(update);
 
 /**
  * Add a frame to the list of frames currently connected to the sidebar app.
+ *
+ * @param {Frame} frame
  */
 function connectFrame(frame) {
   return { type: actions.CONNECT_FRAME, frame: frame };
@@ -47,6 +61,8 @@ function connectFrame(frame) {
 
 /**
  * Remove a frame from the list of frames currently connected to the sidebar app.
+ *
+ * @param {Frame} frame
  */
 function destroyFrame(frame) {
   return { type: actions.DESTROY_FRAME, frame: frame };
@@ -54,11 +70,14 @@ function destroyFrame(frame) {
 
 /**
  * Update the `isAnnotationFetchComplete` flag of the frame.
+ *
+ * @param {string} uri
+ * @param {boolean} isFetchComplete
  */
-function updateFrameAnnotationFetchStatus(uri, status) {
+function updateFrameAnnotationFetchStatus(uri, isFetchComplete) {
   return {
     type: actions.UPDATE_FRAME_ANNOTATION_FETCH_STATUS,
-    isAnnotationFetchComplete: status,
+    isAnnotationFetchComplete: isFetchComplete,
     uri: uri,
   };
 }
@@ -79,6 +98,8 @@ function frames(state) {
  * for that purpose.
  *
  * This may be `null` during startup.
+ *
+ * @type {(state: any) => Frame|null}
  */
 const mainFrame = createSelector(
   state => state,
@@ -88,6 +109,9 @@ const mainFrame = createSelector(
   frames => frames.find(f => !f.id) || null
 );
 
+/**
+ * @param {Frame} frame
+ */
 function searchUrisForFrame(frame) {
   let uris = [frame.uri];
 
@@ -114,8 +138,12 @@ const createShallowEqualSelector = createSelectorCreator(
   shallowEqual
 );
 
-// Memoized selector will return the same array (of URIs) reference unless the
-// values of the array change (are not shallow-equal).
+/**
+ * Memoized selector will return the same array (of URIs) reference unless the
+ * values of the array change (are not shallow-equal).
+ *
+ * @type {(state: any) => string[]}
+ */
 const searchUris = createShallowEqualSelector(
   frames => {
     return frames.reduce(

src/sidebar/store/modules/groups.js

@@ -141,7 +141,7 @@ function getGroup(state, id) {
 /**
  * Return groups the user isn't a member of that are scoped to the URI.
  *
- * @return {Group[]}
+ * @type {(state: any) => Group[]}
  */
 const getFeaturedGroups = createSelector(
   state => state.groups,
@@ -153,7 +153,7 @@ const getFeaturedGroups = createSelector(
  * that show up in the old groups menu. This should be removed once the new groups
  * menu is permanent.
  *
- * @return {Group[]}
+ * @type {(state: any) => Group[]}
  */
 const getInScopeGroups = createSelector(
   state => state.groups,
@@ -165,7 +165,7 @@ const getInScopeGroups = createSelector(
 /**
  * Return groups the logged in user is a member of.
  *
- * @return {Group[]}
+ * @type {(state: any) => Group[]}
  */
 const getMyGroups = createSelector(
   rootState => rootState.groups.groups,
@@ -183,7 +183,7 @@ const getMyGroups = createSelector(
 /**
  * Return groups that don't show up in Featured and My Groups.
  *
- * @return {Group[]}
+ * @type {(state: any) => Group[]}
  */
 const getCurrentlyViewingGroups = createSelector(
   rootState => allGroups(rootState.groups),

src/sidebar/store/modules/real-time-updates.js

@@ -158,6 +158,8 @@ function pendingDeletions(state) {
 
 /**
  * Return a total count of pending updates and deletions.
+ *
+ * @type {(state: any) => number}
  */
 const pendingUpdateCount = createSelector(
   state => [state.pendingUpdates, state.pendingDeletions],
@@ -168,6 +170,8 @@ const pendingUpdateCount = createSelector(
 /**
  * Return true if an annotation has been deleted on the server but the deletion
  * has not yet been applied.
+ *
+ * @param {string} id
  */
 function hasPendingDeletion(state, id) {
   return state.pendingDeletions.hasOwnProperty(id);

src/types/annotator.js

@@ -19,6 +19,7 @@
  * @prop {Object[]} link
  *   @prop {string} link.rel
  *   @prop {string} link.type
+ *   @prop {string} link.href
  * // html pages
  * @prop {Object.<string, string[]>} [dc]
  * @prop {Object.<string, string[]>} [eprints]