@finsemble/finsemble-ui 6.6.1 → 7.0.0-beta-X

package/react/components/toolbar/workspaceManagementMenu/stores/workspaceManagementMenuStore.js

@@ -1,28 +1,44 @@
+/*!
+ * Copyright 2017 by ChartIQ, Inc.
+ * All rights reserved.
+ * The workspace management menu may be the most complicated component that we have (other than the toolbar). It isn't because workspace management is particularly difficult, it's because there is a lot of user question and answer going on. We don't want to overwrite data without explicit consent, and so the calls get involved. To simplify the code, we are using the `async` library. If you are unfamiliar with this library, see this link: https://caolan.github.io/async/docs.html
+ */
 import async from "async";
 import { Util } from "@finsemble/finsemble-api";
+// When a user cancels the save workspace dialog, we throw an error, which short-circuits the async call.
 const SAVE_DIALOG_CANCEL_ERROR = "Cancel";
 const NEGATIVE = "Negative";
-let PROMPT_ON_DIRTY_WORKSPACE = false;
-let DISCARD_UNSAVED_CHANGES = false;
+let PROMPT_ON_DIRTY_WORKSPACE;
+let DISCARD_UNSAVED_CHANGES;
 const WORKSPACE_CONFIGS = {
     PROMPT_USER_ON_DIRTY_WORKSPACE: "finsemble.servicesConfig.workspace.promptUserOnDirtyWorkspace",
     DISCARD_UNSAVED_CHANGES: "finsemble.servicesConfig.workspace.discardUnsavedChanges",
-    DEPRECATED_PROMPT_ON_DIRTY: "finsemble.preferences.workspaceService.promptUserOnDirtyWorkspace",
+    DEPRECATED_PROMPT_ON_DIRTY: "finsemble.preferences.workspaceService.promptUserOnDirtyWorkspace", // DEPRECATED - retrieving it for backwards compatibility
 };
 let WorkspaceManagementStore;
 let StoreClient;
 let Logger;
 let WorkspaceManagementGlobalStore;
+// Initial data for the store.
 const defaultData = {
     activeWorkspace: {},
     menuWidth: 285,
     WorkspaceList: [],
     newWorkspaceDialogIsActive: false,
+    /**
+     * State around whether the workspace is currently in the process of switching.
+     *
+     * For simplicity, we're storing this in the local store for now, but this precludes
+     * other components from signaling that the workspace is changing. A consequence,
+     * for example, is that if you switch workspaces uses a pin on the toolbar instead
+     * of the workspace management menu, the spinner doesn't show up.
+     */
     isSwitchingWorkspaces: false,
     isPromptingUser: false,
 };
 function addListeners(done) {
     FSBL.Clients.RouterClient.addListener("Application.restart", (err, response) => {
+        // when the user calls a "Reset" function, Finsemble shouldn't show a save workspace dialog.
         if (response.data && response.data.forceRestart === true)
             PROMPT_ON_DIRTY_WORKSPACE = false;
     });
@@ -44,21 +60,7 @@ const Actions = {
             callback(null);
         }
     },
-    initialize: () => {
-        FSBL.Clients.ConfigClient.getPreferences((err, preferences) => {
-            var _a, _b;
-            Logger.system.log("WorkspaceManagementStore init getPreferences", preferences);
-            if (preferences) {
-                PROMPT_ON_DIRTY_WORKSPACE = (_a = preferences[WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE]) !== null && _a !== void 0 ? _a : false;
-                DISCARD_UNSAVED_CHANGES = (_b = preferences[WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES]) !== null && _b !== void 0 ? _b : false;
-            }
-            else {
-                FSBL.Clients.ConfigClient.getValue({ field: WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE }, (err, data) => {
-                    Logger.system.log("WorkspaceManagementStore init getValue promptUserOnDirtyWorkspace", data);
-                    PROMPT_ON_DIRTY_WORKSPACE = data !== null && data !== void 0 ? data : true;
-                });
-            }
-        });
+    completeInitialize: () => {
         FSBL.Clients.ConfigClient.addListener({ field: WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE }, (err, config) => {
             Logger.system.log("WorkspaceManagementStore new promptUserOnDirtyWorkspace config", config);
             PROMPT_ON_DIRTY_WORKSPACE = !!config.value;
@@ -67,6 +69,7 @@ const Actions = {
             Logger.system.log("WorkspaceManagementStore new discardUnsavedChanges config", config);
             DISCARD_UNSAVED_CHANGES = !!config.value;
         });
+        // Gets the workspace list and sets the value in the store.
         FSBL.Clients.WorkspaceClient.getWorkspaces((err, workspaces) => {
             Logger.system.debug("WorkspaceManagementStore init getWorkspaces", workspaces);
             WorkspaceManagementStore.setValue({
@@ -74,6 +77,7 @@ const Actions = {
                 value: workspaces,
             });
         });
+        // Get the activeWorkspace and set the value. I could have iterated through the workspaces above and found the active one, but this seems simpler.
         FSBL.Clients.WorkspaceClient.getActiveWorkspace((err, activeWorkspace) => {
             Logger.system.debug("WorkspaceManagementStore init getActiveWorkspace", activeWorkspace);
             WorkspaceManagementStore.setValue({
@@ -81,6 +85,12 @@ const Actions = {
                 value: activeWorkspace,
             });
         });
+        /**
+         * We listen here for any workspace updates, and pass them to the store.
+         * **NOTE**: You may notice that the signature of this callback is different from the previous ones. In this case,
+         * we receive a `response`, instead of `workspaces` or `activeWorkspace`. This is because this callback is for
+         * a `RouterClient` message. The functions above are callbacks to `WorkspaceClient` API calls.
+         */
         FSBL.Clients.RouterClient.subscribe("Finsemble.WorkspaceService.update", (err, response) => {
             if (response.data && response.data.activeWorkspace) {
                 Logger.system.debug("WorkspaceManagementStore init update", response.data);
@@ -116,12 +126,19 @@ const Actions = {
                         Actions.renameWorkspace(action.data);
                         break;
                     default:
+                        // Nothing to do here
                         break;
                 }
             });
         });
     },
+    /*********************************************************************************************
+     *
+     *								GETTERS/SETTERS
+     *
+     *********************************************************************************************/
     getActiveWorkspace: () => WorkspaceManagementStore.getValue("activeWorkspace"),
+    // Get the name of the workspace that is currently being edited
     getWorkspaceBeingEdited: () => WorkspaceManagementStore.getValue("workspaceBeingEdited"),
     getWorkspaceList: () => WorkspaceManagementStore.getValue("WorkspaceList"),
     getIsSwitchingWorkspaces: () => WorkspaceManagementStore.getValue("isSwitchingWorkspaces"),
@@ -134,14 +151,24 @@ const Actions = {
         field: "isPromptingUser",
         value: val,
     }),
+    /*********************************************************************************************
+     *
+     *								Main Workspace Actions
+     *
+     *********************************************************************************************/
+    /**
+     * Handles the complete workflow for creating a new workspace.
+     * We make sure the user doesn't lose any unsaved work, ask them to name it, make sure that workspace doesn't already exist, then actually save the new workspace. After that, we fire off a notification to let them know that everything was a great success.
+     */
     newWorkspace: function () {
         let newWorkspaceName;
         Logger.system.log("New workspace - start.");
         const newWorkspaceDialogIsActive = WorkspaceManagementStore.getValue("newWorkspaceDialogIsActive");
+        // Creates the new workspace.
         const createIt = (params, cb) => {
             Logger.system.log("createIt", params);
             const { workspaceName } = params;
-            FSBL.Clients.WorkspaceClient.createNewWorkspace(workspaceName, {}, (err, response) => {
+            FSBL.Clients.WorkspaceClient.createWorkspace(workspaceName, {}, (err, response) => {
                 Logger.system.log("createIt createNewWorkspace response", workspaceName, response);
                 newWorkspaceName = response.workspaceName;
                 if (cb) {
@@ -169,6 +196,12 @@ const Actions = {
         }
         async.waterfall(tasks, Actions.onAsyncComplete);
     },
+    /**
+     * Handles the workflow for removing a workspace.
+     * As long as you are not deleting the workspace that is active, it will pop up a confirm dialog,
+     * and if the user says "yes", it will delete the workspace.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     removeWorkspace: (data, cb = (val) => { }) => {
         const workspaceName = data.name;
         const dialogParams = {
@@ -178,6 +211,9 @@ const Actions = {
             affirmativeResponseLabel: "Delete",
             hideModalOnClose: data.hideModalOnClose,
         };
+        /**
+         * Invoked when the user interacts with the dialog.
+         */
         function onUserInput(err, response) {
             if (response.choice === "affirmative") {
                 cb(true);
@@ -191,6 +227,9 @@ const Actions = {
         }
         Actions.spawnDialog("yesNo", dialogParams, onUserInput);
     },
+    /**
+     * The `activeWorkspace` is simply a copy of something we brought out of storage. This function copies the `activeWorkspace` to back to storage.
+     */
     saveWorkspace: (cb) => {
         const activeWorkspace = WorkspaceManagementStore.getValue("activeWorkspace");
         FSBL.Clients.WorkspaceClient.saveAs({
@@ -221,6 +260,8 @@ const Actions = {
         });
     },
     renameWorkspace: ({ oldName, newName }) => {
+        // Note: This does no checking of the workspace before renaming. If you call this function, and `newName` is an existing
+        // workspace name, the existing workspace will get stomped. Currently, the UI prevents renaming to existing names.
         FSBL.Clients.WorkspaceClient.rename({
             oldName: oldName,
             newName: newName,
@@ -237,6 +278,9 @@ const Actions = {
             top: "center",
         });
     },
+    /**
+     * Ask the user for a name, make sure it doesn't already exist, then save.
+     */
     saveWorkspaceAs: () => {
         function saveIt(workspaceName, callback) {
             FSBL.Clients.WorkspaceClient.saveAs({
@@ -256,8 +300,13 @@ const Actions = {
             saveIt,
         ], Actions.onAsyncComplete);
     },
+    /**
+     * Asks the user if they'd like to save their data, then loads the requested workspace.
+     */
     switchToWorkspace: async function ({ name }) {
         var _a;
+        // if a workspace prompt is outstanding for a previous switch, immediately return to lock out user from doing another switch (until responding to prompt);
+        // note this prompting flag is cleared in Actions.onAsyncComplete when the previous switch completes (after user responds to the prompt)
         const prompting = Actions.getIsPromptingUser();
         Logger.system.log("workspaceManagementMenuStore: switchToWorkspace", prompting ? "prompting" : "not-prompting");
         if (prompting)
@@ -265,6 +314,10 @@ const Actions = {
         Actions.setIsSwitchingWorkspaces(true);
         Actions.blurWindow();
         const activeWorkspace = WorkspaceManagementStore.getValue("activeWorkspace");
+        /**
+         * Actually perform the switch. Happens after we ask the user what they want.
+         *
+         */
         const switchWorkspace = (callback = () => { }) => {
             FSBL.Clients.WorkspaceClient.switchTo({
                 name: name,
@@ -273,6 +326,9 @@ const Actions = {
                 callback();
             });
         };
+        /**
+         * Make sure the user is sure
+         */
         const askAboutReload = (callback) => {
             Actions.spawnDialog("yesNo", {
                 monitor: "primary",
@@ -282,15 +338,21 @@ const Actions = {
                 negativeResponseLabel: "Don't Save",
             }, callback);
         };
+        /**
+         * If the workspace is dirty, we need to do more than if it's clean.
+         */
         if (await FSBL.Clients.WorkspaceClient.isWorkspaceDirty()) {
             let tasks = [];
             Actions.setIsPromptingUser(true);
             let firstMethod = Actions.autoSave, secondMethod = null;
             if (PROMPT_ON_DIRTY_WORKSPACE === true) {
+                // We want to ask the user to save. But if they're trying to reload the workspace,
+                // the message needs to be different. The first if block just switches that method.
                 firstMethod = Actions.askIfUserWantsToSave;
                 if (name === ((_a = FSBL.Clients.WorkspaceClient.activeWorkspace) === null || _a === void 0 ? void 0 : _a.name)) {
                     firstMethod = askAboutReload;
                 }
+                // If we are not autosaving, we need to process the dialog input.
                 secondMethod = Actions.handleSaveDialogResponse;
             }
             if (!DISCARD_UNSAVED_CHANGES) {
@@ -299,6 +361,7 @@ const Actions = {
             if (secondMethod) {
                 tasks.push(secondMethod);
             }
+            // Switch is the last thing we do.
             tasks.push(switchWorkspace);
             async.waterfall(tasks, Actions.onAsyncComplete);
         }
@@ -306,6 +369,14 @@ const Actions = {
             switchWorkspace();
         }
     },
+    /*********************************************************************************************
+     *
+     *								Workspace Management Helpers
+     *
+     *********************************************************************************************/
+    /**
+     * General handler for `async.series` and `async.waterfall`
+     */
     onAsyncComplete(err) {
         Logger.system.debug("workspaceManagementMenuStore: onAsyncComplete");
         WorkspaceManagementStore.setValue({
@@ -314,11 +385,20 @@ const Actions = {
         });
         const errMessage = err === null || err === void 0 ? void 0 : err.message;
         if (errMessage && errMessage !== NEGATIVE && errMessage !== SAVE_DIALOG_CANCEL_ERROR) {
+            // handle error.
             Logger.system.error(err);
         }
+        // Unlock the UI.
         Actions.setIsSwitchingWorkspaces(false);
         Actions.setIsPromptingUser(false);
     },
+    /**
+     * Helper for spawning dialogs. Keeps the internals of other functions squeaky clean.
+     *
+     * @param {string} type "yesNo" or "singleInput"
+     * @param {object} data Optional params for the dialog call.
+     * @param {function} responseCallback invoked when the user interacts with the dialog.
+     */
     spawnDialog(type, data, responseCallback) {
         Logger.system.debug("spawnDialog", type, data);
         if (type === "singleInput") {
@@ -331,6 +411,7 @@ const Actions = {
             Logger.system.log("SpawnSaveAsDialog onUserInput", response);
             let callbackError = null;
             if (typeof err === "string") {
+                // Error objects cause async to invoke the final callback in async.waterfall.
                 callbackError = new Error(err);
             }
             if (cb) {
@@ -346,12 +427,17 @@ const Actions = {
         };
         Actions.spawnDialog("singleInput", dialogParams, onUserInput);
     },
+    /**
+     * Spawns an input field asking what the user would like to name their new workspace.
+     */
     spawnWorkspaceInputField: (cb) => {
+        // Spawns the dialog with the input field and accepts a callback to be invoked after the user acts.
         Logger.system.log("SpawnWorkspaceInput - start");
         const onUserInput = (err, response) => {
             Logger.system.log("SpawnWorkspaceInput onUserInput", response);
             let callbackError = null;
             if (typeof err === "string") {
+                // Error objects cause async to invoke the final callback in async.waterfall.
                 callbackError = new Error(err);
             }
             if (cb) {
@@ -367,6 +453,9 @@ const Actions = {
         };
         Actions.spawnDialog("singleInput", dialogParams, onUserInput);
     },
+    /**
+     * Asks the user if they'd like to save their workspace if it's different from what's in storage. If the workspace is clean, we just invoke the callback.
+     */
     askIfUserWantsToSave: async function (callback) {
         const activeWorkspace = WorkspaceManagementStore.getValue("activeWorkspace");
         if (await FSBL.Clients.WorkspaceClient.isWorkspaceDirty()) {
@@ -390,24 +479,38 @@ const Actions = {
             return await waitForUserInput();
         }
         else {
+            // In this case the workspace is not dirty, so we don't need to save.
             if (callback)
                 callback(null, { choice: "negative" });
             return { choice: "negative" };
         }
     },
+    /**
+     * Handles the response from the dialog asking if the user wants to save their workspace.
+     *
+     * @param {any} response
+     * @param {any} callback
+     */
     handleSaveDialogResponse(response, callback) {
         if (response.choice === "affirmative") {
+            // User wants to save, so call the client API.
             Actions.saveWorkspace(callback);
         }
         else if (response.choice === "negative") {
+            // Doesn't want to save.
             callback(null);
         }
         else {
+            // choice === cancel
             callback(new Error(SAVE_DIALOG_CANCEL_ERROR));
         }
     },
+    /**
+     * Makes sure the user has input a valid workspace name.
+     */
     validateWorkspaceInput(response, callback) {
         Logger.system.log("spawnWorkspaceInput", response);
+        // If user wants to proceed but gave an invalid name, tell them that they messed up, then die.
         if (response.choice !== "cancel" && (!response.value || response.value === "")) {
             let dialogParams = {
                 title: "Invalid Workspace Name",
@@ -470,9 +573,13 @@ const Actions = {
             callback(null, { workspaceName, template });
         }
     },
+    /**
+     * Checks if the workspace exists. If it does, it asks the user if they're comfortable overwriting that data.
+     */
     checkIfWorkspaceAlreadyExists(response, callback) {
         const workspaceName = response.value;
         const camelCaseWorkspaceName = Util.camelCase(workspaceName);
+        // Do any of the workspaces have the same name that the user is trying to input.
         const workspaceExists = FSBL.Clients.WorkspaceClient.workspaces.some((workspace) => Util.camelCase(workspace) === camelCaseWorkspaceName);
         callback(null, {
             workspaceExists,
@@ -480,6 +587,14 @@ const Actions = {
             template: response.template,
         });
     },
+    /*********************************************************************************************
+     *
+     *								Misc functionality
+     *
+     *********************************************************************************************/
+    /**
+     * Un-focuses from the menu.
+     */
     blurWindow: function () {
         finsembleWindow.blur();
     },
@@ -502,44 +617,80 @@ function createGlobalStore(done) {
 }
 function getPreferences(done) {
     (async () => {
-        var _a, _b;
-        const { err: errPreferences, data: preferences } = await FSBL.Clients.ConfigClient.getPreferences();
-        if (errPreferences) {
-            Logger.system.error("workspaceManagementMenuStore.getPreferences - getPreferences", errPreferences);
+        var _a, _b, _c;
+        const { err: preferencesErr, data: preferencesValues } = await FSBL.Clients.ConfigClient.getPreferences();
+        if (preferencesErr) {
+            Logger.system.error("workspaceManagementMenuStore.getPreferences - getPreferences", preferencesErr);
         }
-        if (preferences && Object.keys(preferences).includes(WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE)) {
-            PROMPT_ON_DIRTY_WORKSPACE = preferences[WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE];
-            Object.keys(preferences).includes(WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES)
-                ? (DISCARD_UNSAVED_CHANGES = (_a = preferences[WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES]) !== null && _a !== void 0 ? _a : false)
-                : false;
+        let promptUserOnDirtyWorkspaceFromPreferences;
+        let discardUnsavedChangesFromPreferences;
+        if (preferencesValues) {
+            promptUserOnDirtyWorkspaceFromPreferences = preferencesValues[WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE];
+            discardUnsavedChangesFromPreferences = preferencesValues[WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES];
         }
-        else {
-            const { err: errValues, data: configValues } = await FSBL.Clients.ConfigClient.getValues([
+        // if we don't have a preference as a boolean value (i.e. null or undefined)
+        // fetch the config to apply
+        if (typeof promptUserOnDirtyWorkspaceFromPreferences !== "boolean") {
+            const { err: configErr, data: configValues } = await FSBL.Clients.ConfigClient.getValues([
                 WORKSPACE_CONFIGS.DEPRECATED_PROMPT_ON_DIRTY,
+                WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE,
             ]);
-            if (errValues) {
-                Logger.system.error("workspaceManagementMenuStore.getPreferences - getValues", errValues);
+            if (configErr) {
+                Logger.system.error("workspaceManagementMenuStore.getPreferences - getValues - promptUserOnDirtyWorkspace", configErr);
             }
-            PROMPT_ON_DIRTY_WORKSPACE = configValues
-                ? (_b = configValues[WORKSPACE_CONFIGS.DEPRECATED_PROMPT_ON_DIRTY]) !== null && _b !== void 0 ? _b : true
-                : true;
-            FSBL.Clients.ConfigClient.setPreference({
-                field: WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE,
-                value: PROMPT_ON_DIRTY_WORKSPACE,
-            });
+            if (configValues) {
+                // deprecated (if present) > config (fallback) > default
+                PROMPT_ON_DIRTY_WORKSPACE =
+                    (_b = (_a = configValues[WORKSPACE_CONFIGS.DEPRECATED_PROMPT_ON_DIRTY]) !== null && _a !== void 0 ? _a : configValues[WORKSPACE_CONFIGS.PROMPT_USER_ON_DIRTY_WORKSPACE]) !== null && _b !== void 0 ? _b : true;
+            }
+            else {
+                // we shouldn't get to this - but in case we do we apply the default.
+                PROMPT_ON_DIRTY_WORKSPACE = true;
+            }
+        }
+        else {
+            PROMPT_ON_DIRTY_WORKSPACE = promptUserOnDirtyWorkspaceFromPreferences;
+        }
+        // if we don't have a preference as a boolean value (i.e. null or undefined)
+        // fetch the config to apply
+        if (typeof discardUnsavedChangesFromPreferences !== "boolean") {
+            const { err: configErr, data: configValue } = await FSBL.Clients.ConfigClient.getValue(WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES);
+            if (configErr) {
+                Logger.system.error("workspaceManagementMenuStore.getPreferences - getValues - discardUnsavedworkspaceChanges", configErr);
+            }
+            if (configValue) {
+                // config (fallback) > default
+                DISCARD_UNSAVED_CHANGES = (_c = configValue[WORKSPACE_CONFIGS.DISCARD_UNSAVED_CHANGES]) !== null && _c !== void 0 ? _c : false;
+            }
+            else {
+                // we shouldn't get to this - but in case we do we assume user does not want to discard unsaved changes
+                // by default.
+                DISCARD_UNSAVED_CHANGES = false;
+            }
+        }
+        else {
+            DISCARD_UNSAVED_CHANGES = discardUnsavedChangesFromPreferences;
         }
         done();
     })();
 }
+/**
+ * Initializes the store for the Workspace Management Menu.
+ */
 function initialize(cb) {
     StoreClient = FSBL.Clients.DistributedStoreClient;
+    // eslint-disable-next-line prefer-destructuring
     Logger = FSBL.Clients.Logger;
     async.parallel([createGlobalStore, createLocalStore, getPreferences, addListeners], () => {
-        Actions.initialize();
+        Actions.completeInitialize();
         cb(WorkspaceManagementStore);
     });
 }
 let getStore = () => WorkspaceManagementStore;
+/**
+ * This is a quick little initialization manager that Terry hacked up.
+ * Ultimately everything in this file should be rewritten in hooks/redux pattern.
+ */
 class StoreManager {
     constructor() {
         this.initialized = false;