feat: setup file pinning architecture

Author: devvaannsh

src/document/DocumentCommandHandlers.js

@@ -2002,12 +2002,33 @@ define(function (require, exports, module) {
             });
     }
 
-    function handleFilePin() {
-        // @devansh: implement the pin functionality here...
+    /**
+     * we call this function when the user selects the 'Pin' option from the context menu
+     * so we pin the file. the pinned file is displayed before the normal files in the working set and tab bar
+     * we also prevent the pinned files from being closed during bulk close operations
+     * @param {{file: File, paneId: string}} commandData - the file to pin and paneId,
+     *                         if unavailable we use the current file and active pane
+     */
+    function handleFilePin(commandData = {}) {
+        const file = commandData.file || MainViewManager.getCurrentlyViewedFile();
+        const paneId = commandData.paneId || MainViewManager.ACTIVE_PANE;
+
+        if (file) {
+            MainViewManager.pinFile(paneId, file);
+        }
     }
 
-    function handleFileUnpin() {
-        // @devansh: implement the unpin functionality here...
+    /**
+     * this unpins the file so it goes back to normal behavior in the working set and tab bar
+     * @param {{file: File, paneId: string}} commandData - read the JSDoc for handleFilePin
+     */
+    function handleFileUnpin(commandData = {}) {
+        const file = commandData.file || MainViewManager.getCurrentlyViewedFile();
+        const paneId = commandData.paneId || MainViewManager.ACTIVE_PANE;
+
+        if (file) {
+            MainViewManager.unpinFile(paneId, file);
+        }
     }
 
     /** Show the selected sidebar (tree or workingset) item in Finder/Explorer */

src/view/MainViewManager.js

@@ -1001,6 +1001,68 @@ define(function (require, exports, module) {
         exports.trigger("_workingSetDisableAutoSort", pane.id);
     }
 
+    /**
+     * This function is called from DocumentCommandHandlers.js handleFilePin function
+     * it is to pin the file. the pinned file is displayed before the normal files in the working set and tab bar
+     * we also prevent the pinned files from being closed during bulk close operations
+     *
+     * @param {!string} paneId - the id of the pane in which to pin the file or ACTIVE_PANE
+     * @param {!File} file - the File to pin
+     * @return {boolean} true if the file was pinned, false if it was already pinned or not in the working set
+     */
+    function pinFile(paneId, file) {
+        const pane = _getPane(paneId);
+        if (!pane) {
+            return false;
+        }
+
+        const result = pane.pinPath(file.fullPath);
+        if (result) {
+            exports.trigger("workingSetPinned", file, pane.id);
+            exports.trigger("workingSetSort", pane.id);
+        }
+
+        return result;
+    }
+
+    /**
+     * called from DocumentCommandHandlers.js handleFileUnpin function,
+     * to unpin the file
+     *
+     * @param {!string} paneId - the id of the pane in which to unpin the file or ACTIVE_PANE
+     * @param {!File} file - the File to unpin
+     * @return {boolean} true if the file was unpinned, false if it wasn't pinned
+     */
+    function unpinFile(paneId, file) {
+        const pane = _getPane(paneId);
+        if (!pane) {
+            return false;
+        }
+
+        const result = pane.unpinPath(file.fullPath);
+        if (result) {
+            exports.trigger("workingSetUnpinned", file, pane.id);
+        }
+
+        return result;
+    }
+
+    /**
+     * checks if a file path is pinned in the working set.
+     *
+     * @param {!string} paneId - the id of the pane in which to check or ACTIVE_PANE
+     * @param {!string} path - the full path to check
+     * @return {boolean} true if the file is pinned
+     */
+    function isPathPinned(paneId, path) {
+        const pane = _getPane(paneId);
+        if (!pane) {
+            return false;
+        }
+
+        return pane.isPathPinned(path);
+    }
+
     /**
      * Get the next or previous file in the MRU list.
      * @param {!number} direction - Must be 1 or -1 to traverse forward or backward
@@ -1808,6 +1870,11 @@ define(function (require, exports, module) {
     exports.getWorkingSetSize = getWorkingSetSize;
     exports.getWorkingSet = getWorkingSet;
 
+    // Pin Management
+    exports.pinFile = pinFile;
+    exports.unpinFile = unpinFile;
+    exports.isPathPinned = isPathPinned;
+
     // Pane state
     exports.cacheScrollState = cacheScrollState;
     exports.restoreAdjustedScrollState = restoreAdjustedScrollState;

src/view/Pane.js

@@ -515,9 +515,82 @@ define(function (require, exports, module) {
         this._viewListAddedOrder = [];
         this._views = {};
         this._currentView = null;
+        this._pinnedPaths = new Set();
         this.showInterstitial(true);
     };
 
+    /**
+     * this pins a file path
+     * @param {string} path - the full path of the file to pin
+     * @return {boolean} true if the file was pinned, false if it was already pinned or not in the view list
+     */
+    Pane.prototype.pinPath = function (path) {
+        // check if already pinned, if it is then ignore
+        if (this.isPathPinned(path)) {
+            return false;
+        }
+
+        // check if the file is present in the open view list, if not then also ignore
+        const index = this.findInViewList(path);
+        if (index === -1) {
+            return false;
+        }
+
+        // add the file path to the pinned paths set
+        // we also reorder the view list as pinned files should appear before regular files
+        this._pinnedPaths.add(path);
+        this._reorderViewListForPinning();
+        return true;
+    };
+
+    /**
+     * this unpins a file path.
+     * @param {string} path - the full path of the file to unpin
+     * @return {boolean} true if the file was unpinned, false if it wasn't pinned
+     */
+    Pane.prototype.unpinPath = function (path) {
+        // if the file is already unpinned, we just ignore
+        if (!this.isPathPinned(path)) {
+            return false;
+        }
+
+        // we just remove the file path from the pinned paths set
+        // here we don't need to reorder the view list, the file can stay in its current position
+        this._pinnedPaths.delete(path);
+        return true;
+    };
+
+    /**
+     * checks if a file path is pinned
+     * @param {string} path - the full path of the file
+     * @return {boolean} true if the file is pinned false otherwise
+     */
+    Pane.prototype.isPathPinned = function (path) {
+        return this._pinnedPaths.has(path);
+    };
+
+    /**
+     * this function is responsible to reorder the view list such that pinned files appear first
+     * the pinned files and regular files both maintain their relative order
+     * @private
+     */
+    Pane.prototype._reorderViewListForPinning = function () {
+        const self = this;
+
+        this._viewList.sort(function (a, b) {
+            // just the regular comparison sorting logic based on whether the files are pinned or not
+            const aPinned = self._pinnedPaths.has(a.fullPath);
+            const bPinned = self._pinnedPaths.has(b.fullPath);
+            if (aPinned && !bPinned) {
+                return -1;
+            }
+            if (!aPinned && bPinned) {
+                return 1;
+            }
+            return 0;
+        });
+    };
+
     /**
       * Creates a pane event namespaced to this pane
       * (pass an empty string to generate just the namespace key to pass to jQuery to turn off all events handled by this pane)
@@ -948,6 +1021,8 @@ define(function (require, exports, module) {
             this._viewList.splice(index, 1);
             this._viewListMRUOrder.splice(this.findInViewListMRUOrder(file.fullPath), 1);
             this._viewListAddedOrder.splice(this.findInViewListAddedOrder(file.fullPath), 1);
+            // also remove from pinned paths if it was pinned
+            this._pinnedPaths.delete(file.fullPath);
         }
 
         // Destroy the view
@@ -1514,6 +1589,7 @@ define(function (require, exports, module) {
     Pane.prototype.loadState = function (state) {
         var filesToAdd = [],
             viewStates = {},
+            pinnedPaths = [],
             activeFile,
             data,
             self = this;
@@ -1530,10 +1606,22 @@ define(function (require, exports, module) {
             if (entry.viewState) {
                 viewStates[entry.file] = entry.viewState;
             }
+            if (entry.pinned) {
+                pinnedPaths.push(entry.file);
+            }
         });
 
         this.addListToViewList(filesToAdd);
 
+        // restore pinned state
+        pinnedPaths.forEach(function (path) {
+            self._pinnedPaths.add(path);
+        });
+        // reorder to put pinned files first
+        if (pinnedPaths.length > 0) {
+            this._reorderViewListForPinning();
+        }
+
         ViewStateManager.addViewStates(viewStates);
 
         activeFile = activeFile || getInitialViewFilePath();
@@ -1551,6 +1639,7 @@ define(function (require, exports, module) {
      */
     Pane.prototype.saveState = function () {
         var result = [],
+            self = this,
             currentlyViewedPath = this.getCurrentlyViewedPath();
 
         // Save the current view state first
@@ -1570,7 +1659,8 @@ define(function (require, exports, module) {
                 result.push({
                     file: file.fullPath,
                     active: (file.fullPath === currentlyViewedPath),
-                    viewState: ViewStateManager.getViewState(file)
+                    viewState: ViewStateManager.getViewState(file),
+                    pinned: self._pinnedPaths.has(file.fullPath)
                 });
             }
         });