@jupyterlab/notebook 4.1.0-alpha.3 → 4.1.0-beta.0

package/lib/actions.d.ts

@@ -649,10 +649,24 @@ export declare namespace NotebookActions {
      */
     function trust(notebook: Notebook, translator?: ITranslator): Promise<void>;
     /**
-     * Access last notebook history.
+     * If the notebook has an active cell, focus it.
      *
-     * @param notebook - The target notebook widget.
+     * @param notebook The target notebook widget
+     * @param options Optional options to change the behavior of this function
+     * @param options.waitUntilReady If true, do not call focus until activeCell.ready is resolved
+     * @param options.preventScroll If true, do not scroll the active cell into view
+     *
+     * @returns a promise that resolves when focus has been called on the active
+     * cell's node.
+     *
+     * #### Notes
+     * By default, waits until after the active cell has been attached unless
+     * called with { waitUntilReady: false }
      */
+    function focusActiveCell(notebook: Notebook, options?: {
+        waitUntilReady?: boolean;
+        preventScroll?: boolean;
+    }): Promise<void>;
     function accessPreviousHistory(notebook: Notebook): Promise<void>;
     /**
      * Access next notebook history.

package/lib/actions.js

@@ -165,7 +165,7 @@ export class NotebookActions {
             .catch(reason => {
             // no-op
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.splitCell = splitCell;
     /**
@@ -268,7 +268,7 @@ export class NotebookActions {
         if (primary instanceof MarkdownCell) {
             notebook.activeCell.rendered = false;
         }
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.mergeCells = mergeCells;
     /**
@@ -287,7 +287,7 @@ export class NotebookActions {
         }
         const state = Private.getState(notebook);
         Private.deleteCells(notebook);
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.deleteCells = deleteCells;
     /**
@@ -320,7 +320,7 @@ export class NotebookActions {
         // Make the newly inserted cell active.
         notebook.activeCellIndex = newIndex;
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.insertAbove = insertAbove;
     /**
@@ -353,7 +353,7 @@ export class NotebookActions {
         // Make the newly inserted cell active.
         notebook.activeCellIndex = newIndex;
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.insertBelow = insertBelow;
     function move(notebook, shift) {
@@ -377,7 +377,7 @@ export class NotebookActions {
         else {
             notebook.moveCell(firstIndex, firstIndex + shift, lastIndex - firstIndex);
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     /**
      * Move the selected cell(s) down.
@@ -416,7 +416,7 @@ export class NotebookActions {
         }
         const state = Private.getState(notebook);
         Private.changeCellType(notebook, value);
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.changeCellType = changeCellType;
     /**
@@ -439,7 +439,7 @@ export class NotebookActions {
         }
         const state = Private.getState(notebook);
         const promise = Private.runSelected(notebook, sessionContext, sessionDialogs, translator);
-        Private.handleRunState(notebook, state, false);
+        void Private.handleRunState(notebook, state, false);
         return promise;
     }
     NotebookActions.run = run;
@@ -464,7 +464,7 @@ export class NotebookActions {
         }
         const state = Private.getState(notebook);
         const promise = Private.runCells(notebook, cells, sessionContext, sessionDialogs, translator);
-        Private.handleRunState(notebook, state, false);
+        void Private.handleRunState(notebook, state, false);
         return promise;
     }
     NotebookActions.runCells = runCells;
@@ -515,7 +515,7 @@ export class NotebookActions {
         else {
             notebook.activeCellIndex++;
         }
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.runAndAdvance = runAndAdvance;
@@ -559,7 +559,7 @@ export class NotebookActions {
             });
         }
         notebook.mode = 'edit';
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.runAndInsert = runAndInsert;
@@ -586,7 +586,7 @@ export class NotebookActions {
         const promise = Private.runCells(notebook, notebook.widgets, sessionContext, sessionDialogs, translator);
         notebook.activeCellIndex = lastIndex;
         notebook.deselectAll();
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.runAll = runAll;
@@ -609,7 +609,7 @@ export class NotebookActions {
         }
         const promise = Private.runSelected(notebook);
         notebook.activeCellIndex = previousIndex;
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.renderAllMarkdown = renderAllMarkdown;
@@ -635,7 +635,7 @@ export class NotebookActions {
         const state = Private.getState(notebook);
         const promise = Private.runCells(notebook, notebook.widgets.slice(0, notebook.activeCellIndex), sessionContext, sessionDialogs, translator);
         notebook.deselectAll();
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.runAllAbove = runAllAbove;
@@ -662,7 +662,7 @@ export class NotebookActions {
         const promise = Private.runCells(notebook, notebook.widgets.slice(notebook.activeCellIndex), sessionContext, sessionDialogs, translator);
         notebook.activeCellIndex = lastIndex;
         notebook.deselectAll();
-        Private.handleRunState(notebook, state, true);
+        void Private.handleRunState(notebook, state, true);
         return promise;
     }
     NotebookActions.runAllBelow = runAllBelow;
@@ -716,7 +716,7 @@ export class NotebookActions {
         const state = Private.getState(notebook);
         notebook.activeCellIndex = possibleNextCellIndex;
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.selectAbove = selectAbove;
     /**
@@ -757,7 +757,7 @@ export class NotebookActions {
         const state = Private.getState(notebook);
         notebook.activeCellIndex = possibleNextCellIndex;
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.selectBelow = selectBelow;
     /** Insert new heading of same level above active cell.
@@ -821,7 +821,7 @@ export class NotebookActions {
         }
         // clear selection and handle state
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.selectHeadingAboveOrCollapseHeading = selectHeadingAboveOrCollapseHeading;
     /**
@@ -851,7 +851,7 @@ export class NotebookActions {
             }
         }
         notebook.deselectAll();
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.selectHeadingBelowOrExpandHeading = selectHeadingBelowOrExpandHeading;
     /**
@@ -881,7 +881,7 @@ export class NotebookActions {
         else {
             notebook.extendContiguousSelectionTo(notebook.activeCellIndex - 1);
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.extendSelectionAbove = extendSelectionAbove;
     /**
@@ -911,7 +911,7 @@ export class NotebookActions {
         else {
             notebook.extendContiguousSelectionTo(notebook.activeCellIndex + 1);
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.extendSelectionBelow = extendSelectionBelow;
     /**
@@ -985,6 +985,7 @@ export class NotebookActions {
         }
         const values = clipboard.getData(JUPYTER_CELL_MIME);
         addCells(notebook, mode, values, true);
+        void focusActiveCell(notebook);
     }
     NotebookActions.paste = paste;
     /**
@@ -1093,7 +1094,7 @@ export class NotebookActions {
         if (cellsFromClipboard) {
             notebook.lastClipboardInteraction = 'paste';
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     /**
      * Undo a cell action.
@@ -1111,7 +1112,7 @@ export class NotebookActions {
         notebook.mode = 'command';
         notebook.model.sharedModel.undo();
         notebook.deselectAll();
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.undo = undo;
     /**
@@ -1130,7 +1131,7 @@ export class NotebookActions {
         notebook.mode = 'command';
         notebook.model.sharedModel.redo();
         notebook.deselectAll();
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.redo = redo;
     /**
@@ -1157,7 +1158,7 @@ export class NotebookActions {
             raw: { ...config.raw, lineNumbers }
         };
         notebook.editorConfig = newConfig;
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.toggleAllLineNumbers = toggleAllLineNumbers;
     /**
@@ -1184,7 +1185,7 @@ export class NotebookActions {
                 Private.outputCleared.emit({ notebook, cell: child });
             }
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.clearOutputs = clearOutputs;
     /**
@@ -1211,7 +1212,7 @@ export class NotebookActions {
                 Private.outputCleared.emit({ notebook, cell: child });
             }
         }
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.clearAllOutputs = clearAllOutputs;
     /**
@@ -1229,7 +1230,7 @@ export class NotebookActions {
                 cell.inputHidden = true;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.hideCode = hideCode;
     /**
@@ -1247,7 +1248,7 @@ export class NotebookActions {
                 cell.inputHidden = false;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.showCode = showCode;
     /**
@@ -1265,7 +1266,7 @@ export class NotebookActions {
                 cell.inputHidden = true;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.hideAllCode = hideAllCode;
     /**
@@ -1283,7 +1284,7 @@ export class NotebookActions {
                 cell.inputHidden = false;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.showAllCode = showAllCode;
     /**
@@ -1301,7 +1302,7 @@ export class NotebookActions {
                 cell.outputHidden = true;
             }
         });
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.hideOutput = hideOutput;
     /**
@@ -1319,7 +1320,7 @@ export class NotebookActions {
                 cell.outputHidden = false;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.showOutput = showOutput;
     /**
@@ -1337,7 +1338,7 @@ export class NotebookActions {
                 cell.outputHidden = true;
             }
         });
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.hideAllOutputs = hideAllOutputs;
     /**
@@ -1373,7 +1374,7 @@ export class NotebookActions {
                 cell.outputHidden = false;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.showAllOutputs = showAllOutputs;
     /**
@@ -1391,7 +1392,7 @@ export class NotebookActions {
                 cell.outputsScrolled = true;
             }
         });
-        Private.handleState(notebook, state, true);
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.enableOutputScrolling = enableOutputScrolling;
     /**
@@ -1409,7 +1410,7 @@ export class NotebookActions {
                 cell.outputsScrolled = false;
             }
         });
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.disableOutputScrolling = disableOutputScrolling;
     /**
@@ -1474,7 +1475,7 @@ export class NotebookActions {
             }
         });
         Private.changeCellType(notebook, 'markdown');
-        Private.handleState(notebook, state);
+        void Private.handleState(notebook, state);
     }
     NotebookActions.setMarkdownHeader = setMarkdownHeader;
     /**
@@ -1483,12 +1484,15 @@ export class NotebookActions {
      * @param notebook - The target notebook widget.
      */
     function collapseAllHeadings(notebook) {
+        const state = Private.getState(notebook);
         for (const cell of notebook.widgets) {
             if (NotebookActions.getHeadingInfo(cell).isHeading) {
                 NotebookActions.setHeadingCollapse(cell, true, notebook);
                 NotebookActions.setCellCollapse(cell, true);
             }
         }
+        notebook.activeCellIndex = 0;
+        void Private.handleState(notebook, state, true);
     }
     NotebookActions.collapseAllHeadings = collapseAllHeadings;
     /**
@@ -1756,6 +1760,38 @@ export class NotebookActions {
     }
     NotebookActions.trust = trust;
     /**
+     * If the notebook has an active cell, focus it.
+     *
+     * @param notebook The target notebook widget
+     * @param options Optional options to change the behavior of this function
+     * @param options.waitUntilReady If true, do not call focus until activeCell.ready is resolved
+     * @param options.preventScroll If true, do not scroll the active cell into view
+     *
+     * @returns a promise that resolves when focus has been called on the active
+     * cell's node.
+     *
+     * #### Notes
+     * By default, waits until after the active cell has been attached unless
+     * called with { waitUntilReady: false }
+     */
+    async function focusActiveCell(notebook, options = { waitUntilReady: true, preventScroll: false }) {
+        const { activeCell } = notebook;
+        const { waitUntilReady, preventScroll } = options;
+        if (!activeCell) {
+            return;
+        }
+        if (waitUntilReady) {
+            await activeCell.ready;
+        }
+        if (notebook.isDisposed || activeCell.isDisposed) {
+            return;
+        }
+        activeCell.node.focus({
+            preventScroll
+        });
+    }
+    NotebookActions.focusActiveCell = focusActiveCell;
+    /*
      * Access last notebook history.
      *
      * @param notebook - The target notebook widget.
@@ -1827,31 +1863,31 @@ var Private;
     /**
      * Handle the state of a widget after running an action.
      */
-    function handleState(notebook, state, scrollIfNeeded = false) {
+    async function handleState(notebook, state, scrollIfNeeded = false) {
         const { activeCell, activeCellIndex } = notebook;
-        if (state.wasFocused || notebook.mode === 'edit') {
-            notebook.activate();
-        }
         if (scrollIfNeeded && activeCell) {
-            notebook.scrollToItem(activeCellIndex, 'auto', 0).catch(reason => {
+            await notebook.scrollToItem(activeCellIndex, 'auto', 0).catch(reason => {
                 // no-op
             });
         }
+        if (state.wasFocused || notebook.mode === 'edit') {
+            notebook.activate();
+        }
     }
     Private.handleState = handleState;
     /**
      * Handle the state of a widget after running a run action.
      */
-    function handleRunState(notebook, state, scroll = false) {
-        if (state.wasFocused || notebook.mode === 'edit') {
-            notebook.activate();
-        }
+    async function handleRunState(notebook, state, scroll = false) {
         const { activeCell, activeCellIndex } = notebook;
         if (scroll && activeCell) {
-            notebook.scrollToItem(activeCellIndex, 'smart', 0).catch(reason => {
+            await notebook.scrollToItem(activeCellIndex, 'smart', 0).catch(reason => {
                 // no-op
             });
         }
+        if (state.wasFocused || notebook.mode === 'edit') {
+            notebook.activate();
+        }
     }
     Private.handleRunState = handleRunState;
     /**
@@ -2120,7 +2156,7 @@ var Private;
         else {
             notebook.lastClipboardInteraction = 'copy';
         }
-        handleState(notebook, state);
+        void handleState(notebook, state);
     }
     Private.copyOrCut = copyOrCut;
     /**
@@ -2402,7 +2438,7 @@ var Private;
                 });
             }
             notebook.deselectAll();
-            Private.handleState(notebook, state, true);
+            void Private.handleState(notebook, state, true);
             notebook.mode = 'edit';
             notebook.widgets[cellIndex].setHidden(false);
         }