@theia/preferences 1.75.0 → 1.76.0-next.10

package/src/browser/preference-tree-model.ts

@@ -34,6 +34,9 @@ import { Preference } from './util/preference-types';
 import { Event } from '@theia/core/lib/common';
 import { COMMONLY_USED_SECTION_PREFIX } from './util/preference-layout';
 
+/** Node id of the 'Commonly Used' group, see `PreferenceTreeGenerator`. */
+const COMMONLY_USED_NODE_ID = `${COMMONLY_USED_SECTION_PREFIX}@${COMMONLY_USED_SECTION_PREFIX}`;
+
 export interface PreferenceTreeNodeProps extends NodeProps {
     visibleChildren: number;
     isExpansible?: boolean;
@@ -46,6 +49,7 @@ export enum PreferenceFilterChangeSource {
     Schema,
     Search,
     Scope,
+    Category,
 }
 export interface PreferenceFilterChangeEvent {
     source: PreferenceFilterChangeSource
@@ -71,6 +75,14 @@ export class PreferenceTreeModel extends TreeModelImpl {
     protected _currentRows: Map<string, PreferenceTreeNodeRow> = new Map();
     protected _totalVisibleLeaves = 0;
     private _suppressSelection = false;
+    private preservingCategoryFilter = false;
+    protected _categoryFilterId: string | undefined;
+    protected _initialSelectionApplied = false;
+    protected lastSelectionId: string | undefined;
+
+    get categoryFilterId(): string | undefined {
+        return this._categoryFilterId;
+    }
 
     get currentRows(): Readonly<Map<string, PreferenceTreeNodeRow>> {
         return this._currentRows;
@@ -104,23 +116,44 @@ export class PreferenceTreeModel extends TreeModelImpl {
     protected async doInit(): Promise<void> {
         super.init();
         this.toDispose.pushAll([
+            this.onSelectionChanged(selectionEvent => {
+                this.lastSelectionId = selectionEvent[0]?.id;
+                if (this.preservingCategoryFilter) {
+                    return;
+                }
+                const node = selectionEvent[0];
+                const newId = node ? this.categoryIdForSelection(node) : undefined;
+                if (newId !== this._categoryFilterId) {
+                    this._categoryFilterId = newId;
+                    this.updateFilteredRows(PreferenceFilterChangeSource.Category);
+                }
+            }),
             this.treeGenerator.onSchemaChanged(newTree => this.handleNewSchema(newTree)),
             this.scopeTracker.onScopeChanged(scopeDetails => {
                 this._currentScope = scopeDetails.scope;
                 this.updateFilteredRows(PreferenceFilterChangeSource.Scope);
+                this.ensureSelectedCategoryHasVisibleSettings();
             }),
             this.filterInput.onFilterChanged(newSearchTerm => {
                 this.lastSearchedTags = Array.from(newSearchTerm.matchAll(/@tag:([^\s]+)/g)).map(match => match[0].slice(5));
                 const newSearchTermWithoutTags = newSearchTerm.replace(/@tag:[^\s]+/g, '');
                 this.lastSearchedLiteral = newSearchTermWithoutTags;
                 this.lastSearchedFuzzy = newSearchTermWithoutTags.replace(/\s/g, '');
+                const wasFiltered = this._isFiltered;
                 this._isFiltered = newSearchTerm.length > 2;
-                if (this.isFiltered) {
+                if (this._isFiltered) {
+                    // Search results span all categories: drop the category filter and the
+                    // now-stale selection so the tree matches the shown results.
+                    this._categoryFilterId = undefined;
+                    this.clearSelection();
                     this.expandAll();
                 } else if (CompositeTreeNode.is(this.root)) {
                     const root = this.root;
                     // Avoid intermediate selection events while collapsing.
                     this.withSuppressedSelection(() => this.collapseAll(root));
+                    if (wasFiltered) {
+                        this.selectDefaultCategory();
+                    }
                 }
                 this.updateFilteredRows(PreferenceFilterChangeSource.Search);
             }),
@@ -135,10 +168,91 @@ export class PreferenceTreeModel extends TreeModelImpl {
 
     private handleNewSchema(newRoot: CompositeTreeNode): void {
         this.root = newRoot;
+        if (this._categoryFilterId && !this.getNode(this._categoryFilterId)) {
+            this._categoryFilterId = undefined;
+        }
         if (this.isFiltered) {
             this.expandAll();
         }
         this.updateFilteredRows(PreferenceFilterChangeSource.Schema);
+        this.restoreSelectionInNewTree();
+        this.ensureSelectedCategoryHasVisibleSettings();
+        this.applyInitialSelection();
+    }
+
+    /**
+     * Re-applies the selection after the tree has been rebuilt with new node instances,
+     * e.g. when plugins contribute preferences after startup. The selection state resolves
+     * nodes by id, but the rebuilt node lacks the `selected` flag that drives the tree
+     * highlight. If the selected node is gone from the new schema, falls back to the
+     * default category.
+     */
+    protected restoreSelectionInNewTree(): void {
+        if (!this.lastSelectionId) {
+            return;
+        }
+        const node = this.getNode(this.lastSelectionId);
+        if (node && SelectableTreeNode.is(node)) {
+            if (!node.selected) {
+                this.selectPreservingCategoryFilter(node);
+            }
+        } else {
+            this.clearSelection();
+            this._initialSelectionApplied = false;
+        }
+    }
+
+    protected applyInitialSelection(): void {
+        if (this._initialSelectionApplied) {
+            return;
+        }
+        if (this.selectedNodes.length > 0) {
+            // Something is already selected, e.g. by the user before the schema change.
+            this._initialSelectionApplied = true;
+            return;
+        }
+        if (this._isFiltered) {
+            // A search (e.g. restored on startup) is active; the default selection is
+            // applied when it is cleared instead.
+            return;
+        }
+        if (this.selectDefaultCategory()) {
+            this._initialSelectionApplied = true;
+        }
+    }
+
+    /**
+     * Selects the 'Commonly Used' category, the default detail page of the settings editor.
+     * @returns `true` if the category was found and selected.
+     */
+    protected selectDefaultCategory(): boolean {
+        const commonlyUsed = this.getNode(COMMONLY_USED_NODE_ID);
+        if (commonlyUsed && SelectableTreeNode.is(commonlyUsed)) {
+            this.selectNode(commonlyUsed);
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Falls back to the default category when the selected category has no settings left to
+     * show, e.g. after switching to a scope in which none of its settings are valid. Otherwise
+     * the editor would show an empty page for a category the tree no longer lists. Clears the
+     * selection instead if the default category has no settings to show either.
+     */
+    protected ensureSelectedCategoryHasVisibleSettings(): void {
+        if (!this._categoryFilterId || this.hasVisibleSettings(this._categoryFilterId)) {
+            return;
+        }
+        if (this.hasVisibleSettings(COMMONLY_USED_NODE_ID)) {
+            this.selectDefaultCategory();
+        } else {
+            this.clearSelection();
+        }
+    }
+
+    protected hasVisibleSettings(categoryId: string): boolean {
+        return !!this._currentRows.get(categoryId)?.visibleChildren;
     }
 
     protected updateRows(): void {
@@ -266,15 +380,42 @@ export class PreferenceTreeModel extends TreeModelImpl {
     }
 
     /**
+     * Returns the id of the nearest composite (category) ancestor of `node`,
+     * inclusive of `node` itself. Returns `undefined` if no category ancestor is found.
+     */
+    protected categoryIdForSelection(node: TreeNode): string | undefined {
+        let current: TreeNode | undefined = node;
+        while (current) {
+            if (Preference.TreeNode.is(current) && Preference.CompositeTreeNode.is(current)) {
+                return current.id;
+            }
+            current = current.parent;
+        }
+        return undefined;
+    }
+
+    /**
+     * Selects `node` to mirror the editor's scroll position in the tree. Unlike an explicit
+     * selection, this does not change the category filter: scrolling must never narrow the
+     * settings editor, only an explicit selection may.
      * @returns true if selection changed, false otherwise
      */
     selectIfNotSelected(node: SelectableTreeNode): boolean {
         const currentlySelected = this.selectedNodes[0];
         if (!node.selected || node !== currentlySelected) {
-            node.selected = true;
-            this.selectNode(node);
+            this.selectPreservingCategoryFilter(node);
             return true;
         }
         return false;
     }
+
+    protected selectPreservingCategoryFilter(node: SelectableTreeNode): void {
+        this.preservingCategoryFilter = true;
+        try {
+            node.selected = true;
+            this.selectNode(node);
+        } finally {
+            this.preservingCategoryFilter = false;
+        }
+    }
 }

package/src/browser/style/index.css

@@ -219,6 +219,12 @@
   font-size: var(--theia-ui-font-size2);
 }
 
+.theia-settings-container .theia-settings-pinned-category-header {
+  position: sticky;
+  z-index: 5;
+  background-color: var(--theia-editor-background);
+}
+
 .theia-settings-container .settings-section>li {
   list-style-type: none;
   margin: var(--theia-ui-padding) 0px;

package/src/browser/views/preference-editor-widget.ts

@@ -21,7 +21,6 @@ import * as deepEqual from 'fast-deep-equal';
 import {
     CompositeTreeNode,
     SelectableTreeNode,
-    StatefulWidget,
     TopDownTreeIterator,
     ExpandableTreeNode,
 } from '@theia/core/lib/browser';
@@ -37,12 +36,8 @@ import { PreferencesScopeTabBar } from './preference-scope-tabbar-widget';
 import { PreferenceNodeRendererCreatorRegistry } from './components/preference-node-renderer-creator';
 import { COMMONLY_USED_SECTION_PREFIX } from '../util/preference-layout';
 
-export interface PreferencesEditorState {
-    firstVisibleChildID: string,
-}
-
 @injectable()
-export class PreferencesEditorWidget extends BaseWidget implements StatefulWidget {
+export class PreferencesEditorWidget extends BaseWidget {
     static readonly ID = 'settings.editor';
     static readonly LABEL = nls.localizeByDefault('Settings Editor');
 
@@ -138,6 +133,8 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
 
         if (e.source === PreferenceFilterChangeSource.Search) {
             this.handleSearchChange(isFiltered, leavesAreVisible);
+        } else if (e.source === PreferenceFilterChangeSource.Category) {
+            this.handleCategoryChange(isFiltered, leavesAreVisible);
         } else if (e.source === PreferenceFilterChangeSource.Scope) {
             this.handleScopeChange(isFiltered);
         } else if (e.source === PreferenceFilterChangeSource.Schema) {
@@ -146,10 +143,14 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
             unreachable(e.source, 'Not all PreferenceFilterChangeSource enum variants handled.');
         }
 
-        if (scrollTarget) {
+        // Only sync the tree to a row that is still shown. A row hidden by the change, e.g. because
+        // it is not valid in the new scope or lies outside the selected category, must not pull the
+        // tree selection away from the page that is shown.
+        if (scrollTarget && this.isRendererVisible(scrollTarget)) {
             this.showInTree(scrollTarget);
         }
         this.resetScroll(scrollTarget);
+        this.pinCategoryHeaders();
 
         if (e.source === PreferenceFilterChangeSource.Search) {
             // Reset focus if search context changes.
@@ -158,6 +159,11 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
     }
 
     protected getScrollTarget(source: PreferenceFilterChangeSource): string | undefined {
+        if (source === PreferenceFilterChangeSource.Category) {
+            // A newly selected category always opens at its top. Scrolling back to the last focused
+            // control would re-select its (previous) category in the tree and desync tree and editor.
+            return undefined;
+        }
         if (source !== PreferenceFilterChangeSource.Search) {
             return this.firstVisibleChildID;
         }
@@ -167,6 +173,11 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
         return undefined;
     }
 
+    protected isRendererVisible(nodeId: string): boolean {
+        const { id, collection } = this.analyzeIDAndGetRendererGroup(nodeId);
+        return !!collection.get(id)?.visible;
+    }
+
     protected isRendererInViewport(nodeId: string): boolean {
         const { id, collection } = this.analyzeIDAndGetRendererGroup(nodeId);
         const renderer = collection.get(id);
@@ -243,6 +254,14 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
         }
     }
 
+    protected handleCategoryChange(isFiltered: boolean, leavesAreVisible: boolean): void {
+        if (leavesAreVisible) {
+            for (const [, renderer] of this.allRenderers()) {
+                this.hideIfFailsFilters(renderer, isFiltered);
+            }
+        }
+    }
+
     protected areLeavesVisible(): boolean {
         const leavesAreVisible = this.model.totalVisibleLeaves > 0;
         this.node.classList.toggle('no-results', !leavesAreVisible);
@@ -266,12 +285,30 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
         }
     }
 
+    /**
+     * Returns true if a category filter is active and `node` is outside the visible slice:
+     * not the selected category itself, not a descendant of it, and not one of its
+     * composite ancestors (whose headers we keep visible above the selected category).
+     * Keeps the left tree intact (filtering is applied here, not in the model).
+     */
+    protected isOutsideSelectedCategory(node: Preference.TreeNode): boolean {
+        const categoryId = this.model.categoryFilterId;
+        if (!categoryId || node.id === categoryId) {
+            return false;
+        }
+        const category = this.model.getNode(categoryId);
+        if (!CompositeTreeNode.is(category) || CompositeTreeNode.isAncestor(category, node)) {
+            return false;
+        }
+        return !(CompositeTreeNode.is(node) && CompositeTreeNode.isAncestor(node, category));
+    }
+
     /**
      * @returns true if the renderer is hidden, false otherwise.
      */
     protected hideIfFailsFilters(renderer: GeneralPreferenceNodeRenderer, isFiltered: boolean): boolean {
         const row = this.model.currentRows.get(renderer.nodeId);
-        if (!row || (CompositeTreeNode.is(row.node) && (isFiltered || row.visibleChildren === 0))) {
+        if (!row || (CompositeTreeNode.is(row.node) && (isFiltered || row.visibleChildren === 0)) || this.isOutsideSelectedCategory(row.node)) {
             renderer.hide();
             return true;
         } else {
@@ -280,6 +317,69 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
         }
     }
 
+    /**
+     * Pins category header rows to the top of the scroll container via `position: sticky`.
+     * The headers of the selected category and its ancestors are stacked on top of each
+     * other; the headers of its subsections all share the single slot below that stack, so
+     * the subsection currently scrolled into view replaces the previous one instead of the
+     * headers piling up. Clears the styles when no category filter is active.
+     */
+    protected pinCategoryHeaders(): void {
+        requestAnimationFrame(() => {
+            const categoryId = this.model.categoryFilterId;
+            const stackedHeaders = this.getStackedHeaderRenderers();
+            // Read all heights before writing any styles, so that the layout is computed only once.
+            const heights = stackedHeaders.map(renderer => renderer.node.offsetHeight);
+            const stackedTops = new Map<string, number>();
+            let stackHeight = 0;
+            stackedHeaders.forEach((renderer, index) => {
+                stackedTops.set(renderer.nodeId, stackHeight);
+                stackHeight += heights[index];
+            });
+            for (const [, renderer] of this.allRenderers()) {
+                if (!CompositeTreeNode.is(this.model.getNode(renderer.nodeId))) {
+                    continue;
+                }
+                const wrapper = renderer.node;
+                if (categoryId && renderer.visible) {
+                    wrapper.classList.add('theia-settings-pinned-category-header');
+                    wrapper.style.top = `${stackedTops.get(renderer.nodeId) ?? stackHeight}px`;
+                } else {
+                    wrapper.classList.remove('theia-settings-pinned-category-header');
+                    wrapper.style.top = '';
+                }
+            }
+        });
+    }
+
+    /**
+     * @returns the visible header renderers of the selected category and its ancestors,
+     * outermost first, i.e. in document order. Empty if no category filter is active.
+     */
+    protected getStackedHeaderRenderers(): GeneralPreferenceNodeRenderer[] {
+        const renderers: GeneralPreferenceNodeRenderer[] = [];
+        const categoryId = this.model.categoryFilterId;
+        if (!categoryId) {
+            return renderers;
+        }
+        for (let node = this.model.getNode(categoryId); node && Preference.TreeNode.is(node); node = node.parent) {
+            const { id, collection } = this.analyzeIDAndGetRendererGroup(node.id);
+            const renderer = collection.get(id);
+            if (renderer?.visible) {
+                renderers.unshift(renderer);
+            }
+        }
+        return renderers;
+    }
+
+    /**
+     * @returns the total height of the pinned header stack, i.e. the space at the top of the
+     * scroll container that is covered by the headers of the selected category and its ancestors.
+     */
+    protected getStackedHeaderHeight(stackedHeaders: GeneralPreferenceNodeRenderer[] = this.getStackedHeaderRenderers()): number {
+        return stackedHeaders.reduce((height, renderer) => height + renderer.node.offsetHeight, 0);
+    }
+
     protected resetScroll(nodeIDToScrollTo?: string): void {
         if (this.scrollBar) { // Absent on widget creation
             this.doResetScroll(nodeIDToScrollTo);
@@ -300,7 +400,8 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
                 const { id, collection } = this.analyzeIDAndGetRendererGroup(nodeIDToScrollTo);
                 const renderer = collection.get(id);
                 if (renderer?.visible) {
-                    this.scrollContainer.scrollTo(0, renderer.node.offsetTop);
+                    // Place the target right below the pinned category headers, not behind them.
+                    this.scrollContainer.scrollTo(0, renderer.node.offsetTop - this.getStackedHeaderHeight());
                     return;
                 }
             }
@@ -324,10 +425,21 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
     onScroll = throttle(this.doOnScroll.bind(this), 50);
 
     protected findFirstVisibleChildID(): string | undefined {
-        const { scrollTop } = this.scrollContainer;
+        // The pinned headers of the selected category and its ancestors always sit at the top of
+        // the scroll container. Skip them and look for the first row right below the stack,
+        // otherwise the outermost ancestor would always be reported and the tree selection would
+        // jump from the selected sub-category to its parent.
+        const stackedHeaders = this.getStackedHeaderRenderers();
+        const stackBottom = this.scrollContainer.scrollTop + this.getStackedHeaderHeight(stackedHeaders);
         for (const [, renderer] of this.allRenderers()) {
-            const { offsetTop, offsetHeight } = renderer.node;
-            if (Math.abs(offsetTop - scrollTop) <= offsetHeight / 2) {
+            const { offsetTop, offsetHeight, offsetParent } = renderer.node;
+            // Skip hidden renderers (display:none): they report offsetTop/offsetHeight 0
+            // and would otherwise match scrollTop===0, hijacking the selection back to
+            // the first hidden category.
+            if (!offsetParent || stackedHeaders.includes(renderer)) {
+                continue;
+            }
+            if (Math.abs(offsetTop - stackBottom) <= offsetHeight / 2) {
                 return renderer.nodeId;
             }
         }
@@ -408,15 +520,4 @@ export class PreferencesEditorWidget extends BaseWidget implements StatefulWidge
     protected override getScrollContainer(): HTMLElement {
         return this.scrollContainer;
     }
-
-    storeState(): PreferencesEditorState {
-        return {
-            firstVisibleChildID: this.firstVisibleChildID,
-        };
-    }
-
-    restoreState(oldState: PreferencesEditorState): void {
-        this.firstVisibleChildID = oldState.firstVisibleChildID;
-        this.resetScroll(this.firstVisibleChildID);
-    }
 }

package/src/browser/views/preference-widget.tsx

@@ -16,7 +16,7 @@
 
 import { postConstruct, injectable, inject } from '@theia/core/shared/inversify';
 import { Panel, Widget, Message, StatefulWidget, codicon } from '@theia/core/lib/browser';
-import { PreferencesEditorState, PreferencesEditorWidget } from './preference-editor-widget';
+import { PreferencesEditorWidget } from './preference-editor-widget';
 import { PreferencesTreeWidget } from './preference-tree-widget';
 import { PreferencesSearchbarState, PreferencesSearchbarWidget } from './preference-searchbar-widget';
 import { PreferencesScopeTabBar, PreferencesScopeTabBarState } from './preference-scope-tabbar-widget';
@@ -27,7 +27,6 @@ import { PreferenceScope } from '@theia/core';
 
 interface PreferencesWidgetState {
     scopeTabBarState: PreferencesScopeTabBarState,
-    editorState: PreferencesEditorState,
     searchbarWidgetState: PreferencesSearchbarState,
 }
 
@@ -106,14 +105,12 @@ export class PreferencesWidget extends Panel implements StatefulWidget {
     storeState(): PreferencesWidgetState {
         return {
             scopeTabBarState: this.tabBarWidget.storeState(),
-            editorState: this.editorWidget.storeState(),
             searchbarWidgetState: this.searchbarWidget.storeState(),
         };
     }
 
     restoreState(state: PreferencesWidgetState): void {
         this.tabBarWidget.restoreState(state.scopeTabBarState);
-        this.editorWidget.restoreState(state.editorState);
         this.searchbarWidget.restoreState(state.searchbarWidgetState);
     }
 }