@jupyterlab/filebrowser 4.0.0-beta.1 → 4.0.0-rc.0

package/lib/listing.js

@@ -180,6 +180,8 @@ export class DirListing extends Widget {
         this._inRename = false;
         this._isDirty = false;
         this._hiddenColumns = new Set();
+        // _focusIndex should never be set outside the range [0, this._items.length - 1]
+        this._focusIndex = 0;
         this.addClass(DIR_LISTING_CLASS);
         this.translator = options.translator || nullTranslator;
         this._trans = this.translator.load('jupyterlab');
@@ -365,6 +367,15 @@ export class DirListing extends Widget {
         if (!this.isDisposed && result.button.accept) {
             await this._delete(items.map(item => item.path));
         }
+        // Re-focus
+        let focusIndex = this._focusIndex;
+        const lastIndexAfterDelete = this._sortedItems.length - items.length - 1;
+        if (focusIndex > lastIndexAfterDelete) {
+            // If the focus index after deleting items is out of bounds, set it to the
+            // last item.
+            focusIndex = Math.max(0, lastIndexAfterDelete);
+        }
+        this._focusItem(focusIndex);
     }
     /**
      * Duplicate the currently selected item(s).
@@ -532,7 +543,7 @@ export class DirListing extends Widget {
      * Select an item by name.
      *
      * @param name - The name of the item to select.
-     * @param focus - Whether to move focus the selected item.
+     * @param focus - Whether to move focus to the selected item.
      *
      * @returns A promise that resolves when the name is selected.
      */
@@ -693,16 +704,23 @@ export class DirListing extends Widget {
             nodes.push(node);
             content.appendChild(node);
         }
-        // Remove extra classes from the nodes.
-        nodes.forEach(node => {
+        nodes.forEach((node, i) => {
+            // Remove extra classes from the nodes.
             node.classList.remove(SELECTED_CLASS);
             node.classList.remove(RUNNING_CLASS);
             node.classList.remove(CUT_CLASS);
+            // Uncheck each file checkbox
             const checkbox = renderer.getCheckboxNode(node);
             if (checkbox) {
-                // Uncheck each file checkbox
                 checkbox.checked = false;
             }
+            // Handle `tabIndex`
+            const nameNode = renderer.getNameNode(node);
+            if (nameNode) {
+                // Must check if the name node is there because it gets replaced by the
+                // edit node when editing the name of the file or directory.
+                nameNode.tabIndex = i === this._focusIndex ? 0 : -1;
+            }
         });
         // Put the check-all checkbox in the header into the correct state
         const checkAllCheckbox = renderer.getCheckboxNode(this.headerNode);
@@ -723,7 +741,7 @@ export class DirListing extends Widget {
                 ? trans.__('Deselect all files and directories')
                 : trans.__('Select all files and directories'));
         }
-        // Add extra classes to item nodes based on widget state.
+        // Update item nodes based on widget state.
         items.forEach((item, i) => {
             const node = nodes[i];
             const ft = this._manager.registry.getFileTypeForModel(item);
@@ -824,6 +842,13 @@ export class DirListing extends Widget {
             }
             return;
         }
+        else {
+            // Focus the selected file on click to ensure a couple of things:
+            // 1. If a user clicks on the item node, its name node will receive focus.
+            // 2. If a user clicks on blank space in the directory listing, the
+            //    previously focussed item will be focussed.
+            this._focusItem(this._focusIndex);
+        }
     }
     /**
      * Handle the `'scroll'` event for the widget.
@@ -889,11 +914,11 @@ export class DirListing extends Widget {
             }
             this._softSelection = '';
         }
-        // Re-focus the selected file. This is needed because nodes corresponding
-        // to files selected in mousedown handler will not retain the focus
-        // as mousedown event is always followed by a blur/focus event.
+        // Re-focus. This is needed because nodes corresponding to files selected in
+        // mousedown handler will not retain the focus as mousedown event is always
+        // followed by a blur/focus event.
         if (event.button === 0) {
-            this._focusSelectedFile();
+            this._focusItem(this._focusIndex);
         }
         // Remove the drag listeners if necessary.
         if (event.button !== 0 || !this._drag) {
@@ -939,10 +964,102 @@ export class DirListing extends Widget {
             this._manager.openOrReveal(path);
         }
     }
+    /**
+     * Calculate the next focus index, given the current focus index and a
+     * direction, keeping within the bounds of the directory listing.
+     *
+     * @param index Current focus index
+     * @param direction -1 (up) or 1 (down)
+     * @returns The next focus index, which could be the same as the current focus
+     * index if at the boundary.
+     */
+    _getNextFocusIndex(index, direction) {
+        const nextIndex = index + direction;
+        if (nextIndex === -1 || nextIndex === this._items.length) {
+            // keep focus index within bounds
+            return index;
+        }
+        else {
+            return nextIndex;
+        }
+    }
+    /**
+     * Handle the up or down arrow key.
+     *
+     * @param event The keyboard event
+     * @param direction -1 (up) or 1 (down)
+     */
+    _handleArrowY(event, direction) {
+        // We only handle the `ctrl` and `shift` modifiers. If other modifiers are
+        // present, then do nothing.
+        if (event.altKey || event.metaKey) {
+            return;
+        }
+        // If folder is empty, there's nothing to do with the up/down key.
+        if (!this._items.length) {
+            return;
+        }
+        // Don't handle the arrow key press if it's not on directory item. This
+        // avoids a confusing user experience that can result from when the user
+        // moves the selection and focus index apart (via ctrl + up/down). The last
+        // selected item remains highlighted but the last focussed item loses its
+        // focus ring if it's not actively focussed.  This forces the user to
+        // visibly reveal the last focussed item before moving the focus.
+        if (!event.target.classList.contains(ITEM_TEXT_CLASS)) {
+            return;
+        }
+        event.stopPropagation();
+        event.preventDefault();
+        const focusIndex = this._focusIndex;
+        let nextFocusIndex = this._getNextFocusIndex(focusIndex, direction);
+        // The following if-block allows the first press of the down arrow to select
+        // the first (rather than the second) file/directory in the list. This is
+        // the situation when the page first loads or when a user changes directory.
+        if (direction > 0 &&
+            focusIndex === 0 &&
+            !event.ctrlKey &&
+            Object.keys(this.selection).length === 0) {
+            nextFocusIndex = 0;
+        }
+        // Shift key indicates multi-selection. Either the user is trying to grow
+        // the selection, or shrink it.
+        if (event.shiftKey) {
+            this._handleMultiSelect(nextFocusIndex);
+        }
+        else if (!event.ctrlKey) {
+            // If neither the shift nor ctrl keys were used with the up/down arrow,
+            // then we treat it as a normal, unmodified key press and select the
+            // next item.
+            this._selectItem(nextFocusIndex, event.shiftKey, false /* focus = false because we call focus method directly following this */);
+        }
+        this._focusItem(nextFocusIndex);
+        this.update();
+    }
+    /**
+     * cd ..
+     *
+     * Go up one level in the directory tree.
+     */
+    async goUp() {
+        const model = this.model;
+        if (model.path === model.rootPath) {
+            return;
+        }
+        try {
+            await model.cd('..');
+        }
+        catch (reason) {
+            console.warn(`Failed to go to parent directory of ${model.path}`, reason);
+        }
+    }
     /**
      * Handle the `'keydown'` event for the widget.
      */
     evtKeydown(event) {
+        // Do not handle any keydown events here if in the middle of a file rename.
+        if (this._inRename) {
+            return;
+        }
         switch (event.keyCode) {
             case 13: {
                 // Enter
@@ -952,34 +1069,64 @@ export class DirListing extends Widget {
                 }
                 event.preventDefault();
                 event.stopPropagation();
-                const selected = Object.keys(this.selection);
-                const path = selected[0];
-                const items = this._sortedItems;
-                const i = ArrayExt.findFirstIndex(items, value => value.path === path);
-                if (i === -1) {
+                for (const item of this.selectedItems()) {
+                    this.handleOpen(item);
+                }
+                return;
+            }
+            case 38:
+                // Up arrow
+                this._handleArrowY(event, -1);
+                return;
+            case 40:
+                // Down arrow
+                this._handleArrowY(event, 1);
+                return;
+            case 32: {
+                // Space
+                if (event.ctrlKey) {
+                    // Follow the Windows and Ubuntu convention: you must press `ctrl` +
+                    // `space` in order to toggle whether an item is selected.
+                    // However, do not handle if any other modifiers were pressed.
+                    if (event.metaKey || event.shiftKey || event.altKey) {
+                        return;
+                    }
+                    // Make sure the ctrl+space key stroke was on a valid, focussed target.
+                    const node = this._items[this._focusIndex];
+                    if (!(
+                    // Event must have occurred within a node whose item can be toggled.
+                    (node.contains(event.target) &&
+                        // That node must also contain the currently focussed element.
+                        node.contains(document.activeElement)))) {
+                        return;
+                    }
+                    event.stopPropagation();
+                    // Prevent default, otherwise the container will scroll.
+                    event.preventDefault();
+                    // Toggle item selected
+                    const { path } = this._sortedItems[this._focusIndex];
+                    if (this.selection[path]) {
+                        delete this.selection[path];
+                    }
+                    else {
+                        this.selection[path] = true;
+                    }
+                    this.update();
+                    // Key was handled, so return.
                     return;
                 }
-                const item = this._sortedItems[i];
-                this.handleOpen(item);
                 break;
             }
-            case 38: // Up arrow
-                this.selectPrevious(event.shiftKey);
-                event.stopPropagation();
-                event.preventDefault();
-                break;
-            case 40: // Down arrow
-                this.selectNext(event.shiftKey);
-                event.stopPropagation();
-                event.preventDefault();
-                break;
-            default:
-                break;
         }
         // Detects printable characters typed by the user.
         // Not all browsers support .key, but it discharges us from reconstructing
         // characters from key codes.
-        if (!this._inRename && event.key !== undefined && event.key.length === 1) {
+        if (event.key !== undefined &&
+            event.key.length === 1 &&
+            // Don't gobble up the space key on the check-all checkbox (which the
+            // browser treats as a click event).
+            !((event.key === ' ' || event.keyCode === 32) &&
+                event.target.type === 'checkbox')) {
             if (event.ctrlKey || event.shiftKey || event.altKey || event.metaKey) {
                 return;
             }
@@ -1270,10 +1417,12 @@ export class DirListing extends Widget {
             else {
                 this.selection[path] = true;
             }
+            this._focusItem(index);
             // Handle multiple select.
         }
         else if (event.shiftKey) {
-            this._handleMultiSelect(selected, index);
+            this._handleMultiSelect(index);
+            this._focusItem(index);
             // Handle a 'soft' selection
         }
         else if (path in this.selection && selected.length > 1) {
@@ -1282,68 +1431,121 @@ export class DirListing extends Widget {
         }
         else {
             // Select only the given item.
-            return this._selectItem(index, false);
+            return this._selectItem(index, false, true);
         }
         this.update();
     }
     /**
-     * (Re-)focus on the selected file.
+     * (Re-)focus an item in the directory listing.
      *
-     * If index is not given, it will be inferred from the current selection;
-     * providing index saves on the iteration time.
-     */
-    _focusSelectedFile(index) {
-        if (typeof index === 'undefined') {
-            const selected = Object.keys(this.selection);
-            if (selected.length > 1) {
-                // Multiselect - do not focus on any single file
-                return;
-            }
-            index = ArrayExt.findFirstIndex(this._sortedItems, value => value.path === selected[0]);
-        }
-        if (index === -1) {
+     * @param index The index of the item node to focus
+     */
+    _focusItem(index) {
+        const items = this._items;
+        if (items.length === 0) {
+            // Focus the top node if the folder is empty and therefore there are no
+            // items inside the folder to focus.
+            this._focusIndex = 0;
+            this.node.focus();
             return;
         }
-        // Focus on text to make shortcuts works
-        const node = this._items[index];
-        const text = DOMUtils.findElement(node, ITEM_TEXT_CLASS);
-        if (text) {
-            text.focus();
+        this._focusIndex = index;
+        const node = items[index];
+        const nameNode = this.renderer.getNameNode(node);
+        if (nameNode) {
+            // Make the filename text node focusable so that it receives keyboard
+            // events; text node was specifically chosen to receive shortcuts because
+            // it gets substituted with input element during file name edits which
+            // conveniently deactivates irrelevant shortcuts.
+            nameNode.tabIndex = 0;
+            nameNode.focus();
+        }
+    }
+    /**
+     * Are all of the items between two provided indices selected?
+     *
+     * The items at the indices are not considered.
+     *
+     * @param j Index of one item.
+     * @param k Index of another item. Note: may be less or greater than first
+     *          index.
+     * @returns True if and only if all items between the j and k are selected.
+     *          Returns undefined if j and k are the same.
+     */
+    _allSelectedBetween(j, k) {
+        if (j === k) {
+            return;
         }
+        const [start, end] = j < k ? [j + 1, k] : [k + 1, j];
+        return this._sortedItems
+            .slice(start, end)
+            .reduce((result, item) => result && this.selection[item.path], true);
     }
     /**
      * Handle a multiple select on a file item node.
      */
-    _handleMultiSelect(selected, index) {
-        // Find the "nearest selected".
+    _handleMultiSelect(index) {
         const items = this._sortedItems;
-        let nearestIndex = -1;
-        for (let i = 0; i < this._items.length; i++) {
-            if (i === index) {
-                continue;
-            }
-            const path = items[i].path;
-            if (selected.indexOf(path) !== -1) {
-                if (nearestIndex === -1) {
-                    nearestIndex = i;
-                }
-                else {
-                    if (Math.abs(index - i) < Math.abs(nearestIndex - i)) {
-                        nearestIndex = i;
-                    }
+        const fromIndex = this._focusIndex;
+        const target = items[index];
+        let shouldAdd = true;
+        if (index === fromIndex) {
+            // This follows the convention in Ubuntu and Windows, which is to allow
+            // the focussed item to gain but not lose selected status on shift-click.
+            // (MacOS is irrelevant here because MacOS Finder has no notion of a
+            // focused-but-not-selected state.)
+            this.selection[target.path] = true;
+            return;
+        }
+        // If the target and all items in-between are selected, then we assume that
+        // the user is trying to shrink rather than grow the group of selected
+        // items.
+        if (this.selection[target.path]) {
+            // However, there is a special case when the distance between the from-
+            // and to- index is just one (for example, when the user is pressing the
+            // shift key plus arrow-up/down). If and only if the situation looks like
+            // the following when going down (or reverse when going up) ...
+            //
+            // - [ante-anchor / previous item] unselected (or boundary)
+            // - [anchor / currently focussed item / item at from-index] selected
+            // - [target / next item / item at to-index] selected
+            //
+            // ... then we shrink the selection / unselect the currently focussed
+            // item.
+            if (Math.abs(index - fromIndex) === 1) {
+                const anchor = items[fromIndex];
+                const anteAnchor = items[fromIndex + (index < fromIndex ? 1 : -1)];
+                if (
+                // Currently focussed item is selected
+                this.selection[anchor.path] &&
+                    // Item on other side of focussed item (away from target) is either a
+                    // boundary or unselected
+                    (!anteAnchor || !this.selection[anteAnchor.path])) {
+                    delete this.selection[anchor.path];
                 }
             }
+            else if (this._allSelectedBetween(fromIndex, index)) {
+                shouldAdd = false;
+            }
         }
-        // Default to the first element (and fill down).
-        if (nearestIndex === -1) {
-            nearestIndex = 0;
-        }
-        // Select the rows between the current and the nearest selected.
-        for (let i = 0; i < this._items.length; i++) {
-            if ((nearestIndex >= i && index <= i) ||
-                (nearestIndex <= i && index >= i)) {
+        // Select (or unselect) the rows between chosen index (target) and the last
+        // focussed.
+        const step = fromIndex < index ? 1 : -1;
+        for (let i = fromIndex; i !== index + step; i += step) {
+            if (shouldAdd) {
+                if (i === fromIndex) {
+                    // Do not change the selection state of the starting (fromIndex) item.
+                    continue;
+                }
                 this.selection[items[i].path] = true;
             }
+            else {
+                if (i === index) {
+                    // Do not unselect the target item.
+                    continue;
+                }
+                delete this.selection[items[i].path];
+            }
         }
     }
     /**
@@ -1366,57 +1568,85 @@ export class DirListing extends Widget {
     /**
      * Allow the user to rename item on a given row.
      */
-    _doRename() {
+    async _doRename() {
         this._inRename = true;
+        const selectedPaths = Object.keys(this.selection);
+        // Bail out if nothing has been selected.
+        if (selectedPaths.length === 0) {
+            this._inRename = false;
+            return Promise.resolve('');
+        }
+        // Figure out which selected path to use for the rename.
         const items = this._sortedItems;
-        const path = Object.keys(this.selection)[0];
+        let { path } = items[this._focusIndex];
+        if (!this.selection[path]) {
+            // If the currently focused item is not selected, then choose the last
+            // selected item.
+            path = selectedPaths.slice(-1)[0];
+        }
+        // Get the corresponding model, nodes, and file name.
         const index = ArrayExt.findFirstIndex(items, value => value.path === path);
         const row = this._items[index];
         const item = items[index];
         const nameNode = this.renderer.getNameNode(row);
         const original = item.name;
+        // Seed the text input with current file name, and select and focus it.
         this._editNode.value = original;
-        this._selectItem(index, false);
-        return Private.doRename(nameNode, this._editNode, original).then(newName => {
-            this.node.focus();
-            if (!newName || newName === original) {
-                this._inRename = false;
-                return original;
-            }
-            if (!isValidFileName(newName)) {
-                void showErrorMessage(this._trans.__('Rename Error'), Error(this._trans._p('showErrorMessage', '"%1" is not a valid name for a file. Names must have nonzero length, and cannot include "/", "\\", or ":"', newName)));
-                this._inRename = false;
-                return original;
-            }
-            if (this.isDisposed) {
-                this._inRename = false;
-                throw new Error('File browser is disposed.');
-            }
+        this._selectItem(index, false, true);
+        // Wait for user input
+        const newName = await Private.userInputForRename(nameNode, this._editNode, original);
+        // Check if the widget was disposed during the `await`.
+        if (this.isDisposed) {
+            this._inRename = false;
+            throw new Error('File browser is disposed.');
+        }
+        let finalFilename = newName;
+        if (!newName || newName === original) {
+            finalFilename = original;
+        }
+        else if (!isValidFileName(newName)) {
+            void showErrorMessage(this._trans.__('Rename Error'), Error(this._trans._p('showErrorMessage', '"%1" is not a valid name for a file. Names must have nonzero length, and cannot include "/", "\\", or ":"', newName)));
+            finalFilename = original;
+        }
+        else {
+            // Attempt rename at the file system level.
             const manager = this._manager;
             const oldPath = PathExt.join(this._model.path, original);
             const newPath = PathExt.join(this._model.path, newName);
-            const promise = renameFile(manager, oldPath, newPath);
-            return promise
-                .catch(error => {
+            try {
+                await renameFile(manager, oldPath, newPath);
+            }
+            catch (error) {
                 if (error !== 'File not renamed') {
                     void showErrorMessage(this._trans._p('showErrorMessage', 'Rename Error'), error);
                 }
+                finalFilename = original;
+            }
+            // Check if the widget was disposed during the `await`.
+            if (this.isDisposed) {
                 this._inRename = false;
-                return original;
-            })
-                .then(() => {
-                if (this.isDisposed) {
-                    this._inRename = false;
-                    throw new Error('File browser is disposed.');
-                }
-                if (this._inRename) {
-                    // No need to catch because `newName` will always exit.
-                    void this.selectItemByName(newName);
-                }
-                this._inRename = false;
-                return newName;
-            });
-        });
+                throw new Error('File browser is disposed.');
+            }
+        }
+        // If nothing else has been selected, then select the renamed file. In
+        // other words, don't select the renamed file if the user has clicked
+        // away to some other file.
+        if (!this.isDisposed &&
+            Object.keys(this.selection).length === 1 &&
+            // We haven't updated the instance yet to reflect the rename, so unless
+            // the user or something else has updated the selection, the original file
+            // path and not the new file path will be in `this.selection`.
+            this.selection[item.path]) {
+            try {
+                await this.selectItemByName(finalFilename, true);
+            }
+            catch (_a) {
+                // do nothing
+                console.warn('After rename, failed to select file', finalFilename);
+            }
+        }
+        this._inRename = false;
+        return finalFilename;
     }
     /**
      * Select a given item.
@@ -1429,8 +1659,8 @@ export class DirListing extends Widget {
         }
         const path = items[index].path;
         this.selection[path] = true;
-        if (!keepExisting && focus) {
-            this._focusSelectedFile(index);
+        if (focus) {
+            this._focusItem(index);
         }
         this.update();
     }
@@ -1463,6 +1693,11 @@ export class DirListing extends Widget {
         this.clearSelectedItems();
         // Update the sorted items.
         this.sort(this.sortState);
+        // Reset focus. But wait until the DOM has been updated (hence
+        // `requestAnimationFrame`).
+        requestAnimationFrame(() => {
+            this._focusItem(0);
+        });
     }
     /**
      * Handle a `fileChanged` signal from the model.
@@ -1513,7 +1748,8 @@ export class DirListing extends Widget {
             header.className = HEADER_CLASS;
             node.appendChild(header);
             node.appendChild(content);
-            node.tabIndex = 0;
+            // Set to -1 to allow calling this.node.focus().
+            node.tabIndex = -1;
             return node;
         }
         /**
@@ -1679,11 +1915,6 @@ export class DirListing extends Widget {
             node.appendChild(text);
             node.appendChild(modified);
             node.appendChild(fileSize);
-            // Make the text note focusable so that it receives keyboard events;
-            // text node was specifically chosen to receive shortcuts because
-            // text element gets substituted with input area during file name edits
-            // which conveniently deactivate irrelevant shortcuts.
-            text.tabIndex = 0;
             if (hiddenColumns === null || hiddenColumns === void 0 ? void 0 : hiddenColumns.has('last_modified')) {
                 modified.classList.add(MODIFIED_COLUMN_HIDDEN);
             }
@@ -1716,11 +1947,6 @@ export class DirListing extends Widget {
             // Wrap the checkbox in a label element in order to increase its hit area.
             const labelWrapper = document.createElement('label');
             labelWrapper.classList.add(CHECKBOX_WRAPPER_CLASS);
-            // The individual file checkboxes are visible on hover, but the header
-            // check-all checkbox is always visible.
-            if (options === null || options === void 0 ? void 0 : options.alwaysVisible) {
-                labelWrapper.classList.add('jp-mod-visible');
-            }
             const checkbox = document.createElement('input');
             checkbox.type = 'checkbox';
             // Prevent the user from clicking (via mouse, keyboard, or touch) the
@@ -1729,6 +1955,15 @@ export class DirListing extends Widget {
             checkbox.addEventListener('click', event => {
                 event.preventDefault();
             });
+            // The individual file checkboxes are visible on hover, but the header
+            // check-all checkbox is always visible.
+            if (options === null || options === void 0 ? void 0 : options.alwaysVisible) {
+                labelWrapper.classList.add('jp-mod-visible');
+            }
+            else {
+                // Disable tabbing to all other checkboxes.
+                checkbox.tabIndex = -1;
+            }
             labelWrapper.appendChild(checkbox);
             return labelWrapper;
         }
@@ -1934,7 +2169,7 @@ var Private;
      *
      * @returns Boolean indicating whether the name changed.
      */
-    function doRename(text, edit, original) {
+    function userInputForRename(text, edit, original) {
         const parent = text.parentElement;
         parent.replaceChild(edit, text);
         edit.focus();
@@ -1945,7 +2180,7 @@ var Private;
         else {
             edit.setSelectionRange(0, index);
         }
-        return new Promise((resolve, reject) => {
+        return new Promise(resolve => {
             edit.onblur = () => {
                 parent.replaceChild(text, edit);
                 resolve(edit.value);
@@ -1962,20 +2197,10 @@ var Private;
                         event.preventDefault();
                         edit.value = original;
                         edit.blur();
-                        break;
-                    case 38: // Up arrow
-                        event.stopPropagation();
-                        event.preventDefault();
-                        if (edit.selectionStart !== edit.selectionEnd) {
-                            edit.selectionStart = edit.selectionEnd = 0;
-                        }
-                        break;
-                    case 40: // Down arrow
-                        event.stopPropagation();
-                        event.preventDefault();
-                        if (edit.selectionStart !== edit.selectionEnd) {
-                            edit.selectionStart = edit.selectionEnd = edit.value.length;
-                        }
+                        // Put focus back on the text node. That way the user can, for
+                        // example, press the keyboard shortcut to go back into edit mode,
+                        // and it will work.
+                        text.focus();
                         break;
                     default:
                         break;
@@ -1983,7 +2208,7 @@ var Private;
             };
         });
     }
-    Private.doRename = doRename;
+    Private.userInputForRename = userInputForRename;
     /**
      * Sort a list of items by sort state as a new array.
      */