@finsemble/finsemble-ui 7.0.0 → 7.1.0-beta.2

package/react/components/windowTitleBar/components/center/TabList.js

@@ -5,26 +5,32 @@ import { Store, Actions } from "../../stores/windowTitleBarStore";
 import { Title } from "../windowTitle";
 import _throttle from "lodash/throttle";
 let TAB_WIDTH = 300;
+// Next two items are for calculating how large the title should be within a tab.
 const ICON_AREA = 16;
 const CLOSE_BUTTON_MARGIN = 12;
 const MINIMUM_TAB_SIZE = 100;
 const stopTilingOrTabbing = (params, cb) => {
     const transmitAndQueryStop = () => {
+        // docking service has a responder for the query
         FSBL.Clients.RouterClient.query("DockingService.stopTilingOrTabbing", params, () => {
             cb === null || cb === void 0 ? void 0 : cb();
         });
+        // WindowTitleBarShell is listening for transmit events so that it knows when tiling/tabbing has stopped
         FSBL.Clients.RouterClient.transmit("DockingService.stopTilingOrTabbing", params);
     };
+    // Get the mouse position if not passed in.
     if (!params.mousePosition) {
         fin.desktop.System.getMousePosition((position) => {
             params.mousePosition = position;
             transmitAndQueryStop();
+            // If allowDropOnSelf is true, it came from a tab/window drop event. Run the callback.
             if (!params.allowDropOnSelf)
                 cb === null || cb === void 0 ? void 0 : cb();
         });
     }
     else {
         transmitAndQueryStop();
+        // If allowDropOnSelf is true, it came from a tab/window drop event. Run the callback.
         if (!params.allowDropOnSelf)
             cb === null || cb === void 0 ? void 0 : cb();
     }
@@ -68,6 +74,9 @@ export class TabList extends React.Component {
             y: 0,
         };
     }
+    /**
+     * Make sure that _this_ is correct inside of our event handlers.
+     */
     bindCorrectContext() {
         this.startDrag = this.startDrag.bind(this);
         this.stopDrag = this.stopDrag.bind(this);
@@ -91,6 +100,7 @@ export class TabList extends React.Component {
         this.getTabWidth = this.getTabWidth.bind(this);
         this.setTabListTranslateX = this.setTabListTranslateX.bind(this);
         this.onTabListTranslateChanged = this.onTabListTranslateChanged.bind(this);
+        this.changeTab = this.changeTab.bind(this);
     }
     getTabWidth(params = {}) {
         let { boundingBox, tabList } = params;
@@ -107,6 +117,9 @@ export class TabList extends React.Component {
         let newTabWidth = containerWidth / tabList.length;
         return newTabWidth < MINIMUM_TAB_SIZE ? MINIMUM_TAB_SIZE : newTabWidth;
     }
+    /**
+     * Resize handler. Calculates the space that the center-region is taking up. May be used to scale tabs proportionally.
+     */
     onWindowResize() {
         let bounds = this.refs.Me.getBoundingClientRect();
         this.setState({
@@ -117,6 +130,13 @@ export class TabList extends React.Component {
     findTabIndex(tab) {
         return this.state.tabs.findIndex((el) => tab.windowName === el.windowName);
     }
+    /**
+     *
+     * Function that's called when this component fires the onDragStart event, this will start the tiling or tabbing process
+     *
+     * @param e The SyntheticEvent created by React when the startdrag event is called
+     * @memberof windowTitleBar
+     */
     startDrag(e, windowIdentifier) {
         this.setState({
             iAmDragging: true,
@@ -126,7 +146,15 @@ export class TabList extends React.Component {
             windowIdentifier,
         });
     }
+    /**
+     * Called when the react component detects a drop (or stop drag, which is equivalent)
+     *
+     * @param e The SyntheticEvent created by React when the stopdrag event is called
+     * @memberof windowTitleBar
+     */
     stopDrag(e) {
+        // We don't want onDropHandler() in windowTitleBarComponent.jsx
+        // to handle this drop event, so we call event.stopPropagation().
         e.stopPropagation();
         FSBL.Clients.Logger.system.debug("Tab stopDrag.");
         this.mousePositionOnDragEnd = {
@@ -136,6 +164,7 @@ export class TabList extends React.Component {
         const { boundingBox } = this.state;
         finsembleWindow.getBounds((err, bounds) => {
             var _a, _b, _c, _d;
+            // We ONLY want to know if we're in the tab region!
             const tabRegion = {
                 top: boundingBox.top + ((_a = bounds === null || bounds === void 0 ? void 0 : bounds.top) !== null && _a !== void 0 ? _a : 0),
                 bottom: boundingBox.bottom + ((_b = bounds === null || bounds === void 0 ? void 0 : bounds.top) !== null && _b !== void 0 ? _b : 0),
@@ -145,28 +174,38 @@ export class TabList extends React.Component {
                 height: 0,
             };
             if (!isPointInBox(this.mousePositionOnDragEnd, tabRegion)) {
+                // allow for a 50ms delay so this message goes after a drop message from a target window if tabbing
                 setTimeout(() => {
                     stopTilingOrTabbing({
                         mousePosition: this.mousePositionOnDragEnd,
                     });
                 }, 50);
-                this.setState({
-                    iAmDragging: false,
-                });
                 this.onWindowResize();
             }
             else {
+                // sometimes a tab gets dropped in a bad spot where no action gets taken and we get stuck in tiling mode
+                // to make sure nothing bad happens, call cancel after a similar 50ms delay
+                // If some action was taken, this will be ignored by Finsemble
                 setTimeout(() => {
                     FSBL.Clients.RouterClient.transmit("DockingService.cancelTilingOrTabbing", {
                         windowIdentifier: this.state.activeTab,
                     });
                 }, 50);
             }
+            // set the default state after dragging
+            this.setState({
+                iAmDragging: false,
+            });
         });
     }
+    /**
+     * Helper function that will pull data from a drop event, parse it, and return it.
+     * @param {event} e
+     */
     extractWindowIdentifier(e) {
         try {
             let identifier = JSON.parse(e.dataTransfer.getData("application/fsbl-tab-data"));
+            // If the "identifier" is formed properly, it'll have this properly. Otherwise, it's something else (e.g., share data, image, etc).
             if (typeof identifier.windowName !== "undefined") {
                 return identifier;
             }
@@ -183,6 +222,10 @@ export class TabList extends React.Component {
             return null;
         }
     }
+    /**
+     * Called when a drop event occurs on the tab region. We (hope) that this came from a tab. Could be a share icon, an image, something else - that's why we check to see if the identifier exists before doing anything.
+     * @param {event} e
+     */
     drop(e) {
         let identifier;
         if (e) {
@@ -192,11 +235,15 @@ export class TabList extends React.Component {
         }
         FSBL.Clients.Logger.system.debug("Tab drag drop.");
         if (!identifier)
-            return;
+            return; // the dropped item is not a tab
         if (this.state.tabs.length === 1 && identifier.windowName === finsembleWindow.name) {
+            // The source and destination tabs are the same
+            //
+            // Cancel the tabbing event
             FSBL.Clients.RouterClient.transmit("DockingService.cancelTilingOrTabbing", {
                 windowIdentifier: this.state.activeTab,
             });
+            // But also set "iAmDragging" to false in order to allow other tabs to be dragged in here
             this.setState({
                 iAmDragging: false,
             });
@@ -205,6 +252,7 @@ export class TabList extends React.Component {
         stopTilingOrTabbing({ allowDropOnSelf: true, action: "tabbing" }, () => {
             FSBL.Clients.RouterClient.transmit("tabbingDragEnd", { success: true });
             if (identifier && identifier.windowName) {
+                // Calls a method defined inside of windowTitleBar.jsx.
                 this.onTabAdded(identifier, this.state.hoveredTabIndex);
             }
             else if (identifier && identifier.waitForIdentifier) {
@@ -228,13 +276,20 @@ export class TabList extends React.Component {
         };
         return lastTab.right + this.state.translateX > this.state.boundingBox.right - this.state.boundingBox.left;
     }
+    /**
+     * Event handler for when a user wheels inside of the tab region. We translate the deltaY that the event provides into horizontal movement. The translateX value that we return will be used in the render method below.
+     * @param {event} e
+     * This should probably be refactored into separate handlers for scroll and mousewheel to account for the differences in event properties.
+     */
     onMouseWheel(e) {
         e.preventDefault();
         let numTabs = this.state.tabs.length;
         let translateX = 0;
+        // If there's more than one tab, do some calculations, otherwise we aren't going to scroll this region, no matter how much the user wants us to.
         if (numTabs > 1) {
             let currentX = this.refs.Me.scrollLeft;
             let { boundingBox } = this.state;
+            // Figure out position of first tab and last tab.
             let firstTab = {
                 left: 0 + boundingBox.left,
             };
@@ -245,6 +300,7 @@ export class TabList extends React.Component {
             if (e.nativeEvent.deltaY < 0) {
                 deltaX = 0 - deltaX;
             }
+            // Mouses with high sensitivity will cause massive scroll amounts. We don't want to scroll more than one tab's width in a single mouse wheel, otherwise you risk missing a tab.
             if (Math.abs(deltaX) > this.state.tabWidth) {
                 let isNegative = false;
                 if (deltaX < 0) {
@@ -252,6 +308,7 @@ export class TabList extends React.Component {
                 }
                 deltaX = isNegative ? 0 - this.state.tabWidth : this.state.tabWidth;
             }
+            // when we set scrollLeft on the element, this event fires. But there's no actual event. so stop.
             if (!e.nativeEvent.deltaY) {
                 return;
             }
@@ -266,39 +323,60 @@ export class TabList extends React.Component {
             translateX = deltaY + currentX;
             let newRightForLastTab = lastTab.right + translateX;
             let newLeftForFirstTab = firstTab.left + translateX;
+            // Do not let the left of the first tab move to the right of the left edge of the bounding box.
             if (newLeftForFirstTab < 0) {
                 return this.scrollToFirstTab();
             }
             else if (e.nativeEvent.deltaY < 0 && newRightForLastTab <= boundingBox.right) {
+                // ONLY IF the user is scrolling from right-to-left (deltaY will be negative). IF they try to do that, do not allow the right edge of the last tab to detach.
                 return this.scrollToLastTab();
             }
+            // Else, the translation is okay. We're in the middle of our list and the first and last tabs aren't being rendered improperly.
             translateX < 0 ? (translateX = 0) : translateX;
             this.setState({ translateX });
         }
     }
+    /**
+     * Scrolls to our active tab.
+     */
     scrollToActiveTab() {
         this.scrollToTab(this.state.activeTab);
     }
+    /**
+     * Scrolls to the first tab in our list of tabs.
+     */
     scrollToFirstTab() {
         let firstTab = this.state.tabs[0];
         this.scrollToTab(firstTab);
     }
+    /**
+     * Scrolls to the last tab in our list of tabs
+     */
     scrollToLastTab() {
         let lastTab = this.state.tabs[this.state.tabs.length - 1];
         this.scrollToTab(lastTab);
     }
+    /**
+     * Function that will horizontally scroll the tab region so that the right edge of the tab lines up with the right edge of the tab region.
+     * @param {} tab
+     */
     scrollToTab(tab) {
+        // 'BoundingBox' is just the boundingClientRect of the tab region. It is, in essence, the center part of the windowTitleBar.
         let { boundingBox } = this.state;
         let tabIndex = this.state.tabs.findIndex((el) => el.windowName === tab.windowName);
         if (tabIndex > -1) {
             let leftEdgeOfTab = tabIndex * this.state.tabWidth;
             let rightEdgeOfTab = leftEdgeOfTab + this.state.tabWidth;
             let translateX = rightEdgeOfTab;
+            // Our translation is  this: Take the  right edge of the bounding box, and subtract the left edge. This gives us the 0 point for the box. Then, we subtract the right edge of the tab. The result is a number that we use to shift the entire element and align the right edge of the tab with the right edge of the bounding box. We also account for the 30 px region on the right.
+            // If there's no overflow, we don't scroll.
             if (rightEdgeOfTab < boundingBox.right) {
                 translateX = 0;
             }
             else {
+                // Our translation is  this: Take the  right edge of the bounding box, and subtract the left edge. This gives us the 0 point for the box. Then, we subtract the right edge of the tab. The result is a number that we use to shift the entire element and align the right edge of the tab with the right edge of the bounding box.
                 translateX = boundingBox.right - boundingBox.left - rightEdgeOfTab;
+                // If there's no overflow, we don't scroll.
                 if (rightEdgeOfTab < boundingBox.right) {
                     translateX = 0;
                 }
@@ -309,9 +387,17 @@ export class TabList extends React.Component {
     setTabListTranslateX(translateX) {
         Actions.setTabListScrollPosition(translateX);
     }
+    /**
+     * Someone is dragging _something_ over the tab region. We respond by rendering the ghost tab.
+     * @param {event} e
+     */
     dragOver(e) {
         e.preventDefault();
     }
+    /**
+     * Triggered when the user moves their mouse out of the tabRegion after a dragOver event happens. When they leave, we hide our placeholder tab.
+     * @param {event} e
+     */
     dragLeave(e) {
         let boundingRect = this.state.boundingBox;
         if (!isPointInBox({ x: e.screenX, y: e.screenY }, boundingRect)) {
@@ -320,10 +406,20 @@ export class TabList extends React.Component {
             });
         }
     }
+    /**
+     * Set to a timeout. An event is sent to the RouterClient which will be handled by the drop handler on the window.
+     * In the event that a drop handler never fires to stop tiling or tabbing, this will take care of it.
+     *
+     * @memberof windowTitleBar
+     */
     cancelTabbing() {
         stopTilingOrTabbing({ allowDropOnSelf: true });
         this.onWindowResize();
     }
+    /**
+     * Basically exists just to keep the render method clean. Gives conditional classes to the active tab.
+     * @param {tab} tab
+     */
     getTabClasses(tab) {
         let classes = "fsbl-tab";
         let tabIndex = this.findTabIndex(tab);
@@ -336,14 +432,24 @@ export class TabList extends React.Component {
     }
     onTabDraggedOver(e, tabDraggedOver) {
         e.preventDefault();
+        // Find index of tab.
         let tabIndex = this.findTabIndex(tabDraggedOver);
         this.setState({
             hoveredTabIndex: tabIndex,
         });
     }
+    /**
+     * OnClick handler for the close button on individual tabs.
+     * @PLACEHOLDER will interact with tabbing API
+     * @param {*} tab
+     */
     onTabClosed(identifier) {
         Actions.closeTab(identifier);
     }
+    /**
+     * drop handler for the tab region.
+     * @param {*} tab
+     */
     onTabAdded(identifier, newIndex) {
         if (newIndex === -1) {
             newIndex = undefined;
@@ -362,6 +468,11 @@ export class TabList extends React.Component {
             hoveredTabIndex: undefined,
         });
     }
+    /**
+     * OnClick handler for individual tabs.
+     * @PLACEHOLDER will interact with tabbing API
+     * @param {*} tab
+     */
     setActiveTab(tab) {
         Actions.setActiveTab(tab);
     }
@@ -378,12 +489,57 @@ export class TabList extends React.Component {
             translateX: value,
         });
     }
+    /**
+     * Change active tab to the next one on either its left or right
+     *
+     * @param direction the direction the tab should change to (1 = right, -1 = left)
+     */
+    changeTab(direction) {
+        const { currentIndex } = Actions.findTab(this.state.activeTab);
+        let newIndex = currentIndex + direction;
+        if (newIndex < 0) {
+            newIndex = this.state.tabs.length - 1;
+        }
+        else if (newIndex >= this.state.tabs.length) {
+            newIndex = 0;
+        }
+        Actions.setActiveTab(this.state.tabs[newIndex]);
+    }
     UNSAFE_componentWillMount() {
+        // Store.addListener({ field: "activeTab" }, this.onActiveTabChanged);
         Store.addListener({ field: "tabs" }, this.onTabsChanged);
         Store.addListener({ field: "tabListTranslateX" }, this.onTabListTranslateChanged);
     }
     componentDidMount() {
         window.addEventListener("resize", this.onWindowResizeThrottled);
+        window.addEventListener("keydown", (e) => {
+            if (e.ctrlKey) {
+                // On Mac or Windows, Ctrl+Tab changes tabs to the right
+                // On Windows, Ctrl+PageDown changes tabs to the right
+                if ((e.key === "Tab" && !e.shiftKey) || e.key === "PageDown") {
+                    this.changeTab(1);
+                    e.preventDefault();
+                    // On Mac or Windows, Ctrl+Shift+Tab changes tabs to the left
+                    // On Windows, Ctrl+PageUp changes tabs to the left
+                }
+                else if (e.key === "PageUp" || (e.key === "Tab" && e.shiftKey)) {
+                    this.changeTab(-1);
+                    e.preventDefault();
+                }
+            }
+            else if (e.metaKey && e.altKey) {
+                // On Mac, Cmd+Opt+Right changes tabs to the right
+                if (e.key === "ArrowRight") {
+                    this.changeTab(1);
+                    e.preventDefault();
+                    // On Mac, Cmd+Opt+Left changes tabs to the left
+                }
+                else if (e.key === "ArrowLeft") {
+                    this.changeTab(-1);
+                    e.preventDefault();
+                }
+            }
+        });
         let boundingBox = this.refs.Me.getBoundingClientRect();
         this.setState({
             boundingBox: boundingBox,
@@ -391,6 +547,7 @@ export class TabList extends React.Component {
         });
     }
     componentWillUnmount() {
+        // Store.removeListener({ field: "activeTab" }, this.onActiveTabChanged);
         Store.removeListener({ field: "tabs" }, this.onTabsChanged);
         Store.removeListener({ field: "tabListTranslateX" }, this.onTabListTranslateChanged);
         window.removeEventListener("resize", this.onWindowResizeThrottled);
@@ -401,6 +558,7 @@ export class TabList extends React.Component {
     render() {
         let { translateX } = this.state;
         translateX = Math.abs(translateX);
+        // If we have just 1 tab, we render the title. Unless someone is dragging a tab around - in that case, we will render the tab view, even though we only have 1.
         let componentToRender = "title";
         if (this.state.tabs.length === 1 && this.props.listenForDragOver && !this.state.iAmDragging) {
             componentToRender = "tabs";
@@ -408,6 +566,7 @@ export class TabList extends React.Component {
         if (this.state.tabs.length > 1) {
             componentToRender = "tabs";
         }
+        // Cleanup in case we were translated before closing the second to last tab. This left-aligns the title.
         if (componentToRender === "title") {
             translateX = 0;
         }
@@ -421,6 +580,9 @@ export class TabList extends React.Component {
                 componentToRender === "title" && this.renderTitle(),
                 componentToRender === "tabs" && this.renderTabs())));
     }
+    /**
+     * Function to render the title. Helps keep the render code clean.
+     */
     renderTitle() {
         const windowIdentifier = {
             windowName: finsembleWindow.name,
@@ -435,6 +597,10 @@ export class TabList extends React.Component {
             React.createElement(FinsembleHoverDetector, { edge: "top", hoverAction: this.hoverAction.bind(this) }),
             React.createElement(Title, { onUpdate: this.props.onTitleUpdated, windowIdentifier: windowIdentifier })));
     }
+    /**
+     * Renders the array of tabs.
+     * @param {*} props
+     */
     renderTabs() {
         let titleWidth = this.state.tabWidth - ICON_AREA - CLOSE_BUTTON_MARGIN;
         return this.state.tabs.map((tab) => (React.createElement(Tab, { draggable: "true", key: tab.windowName, className: this.getTabClasses(tab), onClick: () => {