redhat-developer
diff --git a/‎docs/LSPApi.md
Copy file name to clipboard
+11-1Lines changed: 11 additions & 1 deletion b/‎docs/LSPApi.md
Copy file name to clipboard
+11-1Lines changed: 11 additions & 1 deletion
diff --git a/‎docs/LSPSupport.md
Copy file name to clipboard
+13-2Lines changed: 13 additions & 2 deletions b/‎docs/LSPSupport.md
Copy file name to clipboard
+13-2Lines changed: 13 additions & 2 deletions
diff --git a/‎docs/images/lsp-support/textDocument_documentSymbol_breadcrumbs.gif
Copy file name to clipboard
2.11 MB b/‎docs/images/lsp-support/textDocument_documentSymbol_breadcrumbs.gif
Copy file name to clipboard
2.11 MB
diff --git a/‎src/main/java/com/redhat/devtools/lsp4ij/client/features/LSPBreadcrumbsFeature.java
Copy file name to clipboard
+36Lines changed: 36 additions & 0 deletions b/‎src/main/java/com/redhat/devtools/lsp4ij/client/features/LSPBreadcrumbsFeature.java
Copy file name to clipboard
+36Lines changed: 36 additions & 0 deletions
diff --git a/‎src/main/java/com/redhat/devtools/lsp4ij/client/features/LSPClientFeatures.java
Copy file name to clipboard
+34Lines changed: 34 additions & 0 deletions b/‎src/main/java/com/redhat/devtools/lsp4ij/client/features/LSPClientFeatures.java
Copy file name to clipboard
+34Lines changed: 34 additions & 0 deletions
diff --git a/‎src/main/java/com/redhat/devtools/lsp4ij/features/documentSymbol/DocumentSymbolData.java
Copy file name to clipboard
+12-5Lines changed: 12 additions & 5 deletions b/‎src/main/java/com/redhat/devtools/lsp4ij/features/documentSymbol/DocumentSymbolData.java
Copy file name to clipboard
+12-5Lines changed: 12 additions & 5 deletions
diff --git a/‎src/main/java/com/redhat/devtools/lsp4ij/features/documentSymbol/LSPBreadcrumbsProvider.java
Copy file name to clipboard
+148Lines changed: 148 additions & 0 deletions b/‎src/main/java/com/redhat/devtools/lsp4ij/features/documentSymbol/LSPBreadcrumbsProvider.java
Copy file name to clipboard
+148Lines changed: 148 additions & 0 deletions
@@ -26,6 +26,7 @@ The [LSPClientFeatures](https://github.com/redhat-developer/lsp4ij/blob/main/src
 - [LSP typeDefinition feature](#lsp-typeDefinition-feature)
 - [LSP usage feature](#lsp-usage-feature)
 - [LSP workspace symbol feature](#lsp-workspace-symbol-feature)
+- [LSP breadcrumbs feature](#lsp-breadcrumbs-feature)
 - [LSP editor behavior feature](#lsp-editor-behavior-feature)
 - [Language server installer](#language-server-installer)
 
@@ -649,9 +650,18 @@ or, if appropriate, the the child/descendant element that represents the declara
 | boolean isSupported()       | Returns `true` if the LSP feature is supported and `false` otherwise. <br/>This supported state is called after starting the language server, which matches the LSP server capabilities. | Check the server capability            |
 | boolean supportsGotoClass() | Returns `true` if the LSP feature is efficient enough to support the IDE's Go To Class action which may be invoked frequently and `false` otherwise.                                     | `false`                                |
 
+## LSP Breadcrumbs Feature
+
+Unlike most features above, `LSPBreadcrumbsFeature` does **not** correspond directly to an LSP feature, but it does build upon `LSPDocumentSymbolFeature` to add breadcrumbs and sticky lines behavior to the IDE. It is _enabled by default_ for all language server definitions except for the HTML and XML language server definition templates. Those implementing custom language server integrations can opt out of these features if desired by overriding the respective methods listed below.
+
+| API                             | Description                                                                                                  | Default Behaviour |
+|---------------------------------|--------------------------------------------------------------------------------------------------------------|-------------------|
+| boolean isEnabled(PsiFile file) | Returns `true` if the the document symbols-based breadcrumbs info provider is enabled and `false` otherwise. | `true`            |
+=======
+
 ## LSP Editor Behavior Feature
 
-Unlike the features above, `LSPEditorFeature` does **not** correspond to an LSP feature. Instead it represents IDE editor behavior features, enhancements, and fixes that, alongside the language server-provided features, help provide an optimal editor experience for LSP4IJ-integrated file types. Note that these features are _disabled by default_ for `LanguageServerDefinition` and _enabled by default_ for `UserDefinedLanguageServerDefinition`. Those implementing custom language server integrations can opt into these features if desired by overriding the respective methods listed below.
+Unlike most features above, `LSPEditorFeature` does **not** correspond to an LSP feature. Instead it represents IDE editor behavior features, enhancements, and fixes that, alongside the language server-provided features, help provide an optimal editor experience for LSP4IJ-integrated file types. Note that these features are _disabled by default_ for `LanguageServerDefinition` and _enabled by default_ for `UserDefinedLanguageServerDefinition`. Those implementing custom language server integrations can opt into these features if desired by overriding the respective methods listed below.
 
 | API                                                            | Description                                                                                                                       | Default Behaviour                                                                                    |
 |----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
 
@@ -654,8 +654,9 @@ If you need other mapping:
 
 ### Document Symbol
 
-[textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_documentSymbol) is implemented with 
-the `lang.psiStructureViewFactory` extension point. By default, LSP4IJ registers the `lang.psiStructureViewFactory` with
+#### Structure View
+
+The IDE's `lang.psiStructureViewFactory` extension point is implemented using [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_documentSymbol). By default, LSP4IJ registers the `lang.psiStructureViewFactory` with
 [LSPDocumentSymbolStructureViewFactory](https://github.com/redhat-developer/lsp4ij/blob/main/src/main/java/com/redhat/devtools/lsp4ij/features/documentSymbol/LSPDocumentSymbolStructureViewFactory.java) class for `TEXT` and `textmate` languages:
 
 ```xml
@@ -690,6 +691,16 @@ You can also open the `Structure` view using the `View / Tool Windows / Structur
 
 ![textDocument/documentSymbol](./images/lsp-support/textDocument_documentSymbol.gif)
 
+#### Breadcrumbs and Sticky Lines
+
+The IDE's `breadcrumbsInfoProvider` extension point is also implemented using [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_documentSymbol). LSP4IJ registers the extension point for all file types and languages but filters at runtime for those associated with configured language server definitions.
+
+The feature is _enabled by default_ but can be disabled by overriding the respective feature flag either in code by overriding `LSPBreadcrumbsFeature#isEnabled()` (custom language server definitions) or client configuration (user-defined language server definitions). Note that sticky lines are only supported in JetBrains 2024.1+ IDE versions.
+
+Here is an example of breadcrumbs and sticky lines in TypeScript:
+
+![textDocument/documentSymbol breadcrumbs](./images/lsp-support/textDocument_documentSymbol_breadcrumbs.gif)
+
 ### Call Hierarchy
 
 [textDocument/prepareCallHierarchy](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_prepareCallHierarchy) is implemented with
 
@@ -0,0 +1,36 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Red Hat, Inc.
+ * Distributed under license by Red Hat, Inc. All rights reserved.
+ * This program is made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution,
+ * and is available at https://www.eclipse.org/legal/epl-v20.html
+ *
+ * Contributors:
+ * Red Hat, Inc. - initial API and implementation
+ ******************************************************************************/
+
+package com.redhat.devtools.lsp4ij.client.features;
+
+import com.intellij.psi.PsiFile;
+import org.eclipse.lsp4j.ServerCapabilities;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Breadcrumbs/sticky lines feature. This does not correspond directly to an LSP feature but is built upon
+ * {@link LSPDocumentSymbolFeature}.
+ */
+@ApiStatus.Experimental
+public class LSPBreadcrumbsFeature extends AbstractLSPDocumentFeature {
+
+    @Override
+    public void setServerCapabilities(@Nullable ServerCapabilities serverCapabilities) {
+    }
+
+    @Override
+    public boolean isSupported(@NotNull PsiFile file) {
+        // Requires the document symbol feature
+        return getClientFeatures().getDocumentSymbolFeature().isSupported(file);
+    }
+}
@@ -61,6 +61,8 @@ public class LSPClientFeatures implements Disposable, FileUriSupport {
 
     private LSPDocumentSymbolFeature documentSymbolFeature;
 
+    private LSPBreadcrumbsFeature breadcrumbsFeature;
+
     private LSPDiagnosticFeature diagnosticFeature;
 
     private LSPFoldingRangeFeature foldingRangeFeature;
@@ -643,6 +645,38 @@ public final LSPClientFeatures setDocumentSymbolFeature(@NotNull LSPDocumentSymb
         return this;
     }
 
+    /**
+     * Returns the LSP breadcrumbs feature.
+     *
+     * @return the LSP breadcrumbs feature.
+     */
+    @NotNull
+    public final LSPBreadcrumbsFeature getBreadcrumbsFeature() {
+        if (breadcrumbsFeature == null) {
+            initBreadcrumbsFeature();
+        }
+        return breadcrumbsFeature;
+    }
+
+    private synchronized void initBreadcrumbsFeature() {
+        if (breadcrumbsFeature != null) {
+            return;
+        }
+        setBreadcrumbsFeature(new LSPBreadcrumbsFeature());
+    }
+
+    /**
+     * Initialize the LSP breadcrumbs feature.
+     *
+     * @param breadcrumbsFeature the LSP breadcrumbs feature.
+     * @return the LSP client features.
+     */
+    public final LSPClientFeatures setBreadcrumbsFeature(@NotNull LSPBreadcrumbsFeature breadcrumbsFeature) {
+        breadcrumbsFeature.setClientFeatures(this);
+        this.breadcrumbsFeature = breadcrumbsFeature;
+        return this;
+    }
+
     /**
      * Returns the LSP diagnostic feature.
      *
 
@@ -10,8 +10,7 @@
  ******************************************************************************/
 package com.redhat.devtools.lsp4ij.features.documentSymbol;
 
-import javax.swing.Icon;
-
+import com.intellij.openapi.editor.Document;
 import com.intellij.openapi.project.Project;
 import com.intellij.openapi.util.TextRange;
 import com.intellij.psi.PsiElement;
@@ -20,11 +19,13 @@
 import com.redhat.devtools.lsp4ij.LSPIJUtils;
 import com.redhat.devtools.lsp4ij.LanguageServerItem;
 import com.redhat.devtools.lsp4ij.client.features.LSPClientFeatures;
-
 import org.eclipse.lsp4j.DocumentSymbol;
+import org.eclipse.lsp4j.Range;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import javax.swing.Icon;
+
 
 /**
  * LSP document symbol data.
@@ -37,7 +38,7 @@ public class DocumentSymbolData extends FakePsiElement {
     private final @NotNull PsiFile psiFile;
     private final DocumentSymbolData parent;
     private final @NotNull LanguageServerItem languageServer;
-    private TextRange textRange;
+    private volatile TextRange textRange = null;
     private DocumentSymbolData[] cachedChildren;
 
     public DocumentSymbolData(@NotNull DocumentSymbol documentSymbol,
@@ -83,7 +84,13 @@ public int getTextOffset() {
     @Override
     public TextRange getTextRange() {
         if (textRange == null) {
-            this.textRange = LSPIJUtils.toTextRange(documentSymbol.getRange(), LSPIJUtils.getDocument(psiFile.getVirtualFile()));
+            synchronized (this) {
+                if (textRange == null) {
+                    Range range = documentSymbol.getRange();
+                    Document document = LSPIJUtils.getDocument(psiFile);
+                    this.textRange = (range != null) && (document != null) ? LSPIJUtils.toTextRange(range, document) : psiFile.getTextRange();
+                }
+            }
         }
         return textRange;
     }
 
@@ -0,0 +1,148 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Red Hat Inc. and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ *
+ * Contributors:
+ *     Red Hat Inc. - initial API and implementation
+ *******************************************************************************/
+
+package com.redhat.devtools.lsp4ij.features.documentSymbol;
+
+import com.intellij.ide.structureView.StructureViewTreeElement;
+import com.intellij.lang.Language;
+import com.intellij.lang.LanguageUtil;
+import com.intellij.openapi.project.Project;
+import com.intellij.openapi.util.Conditions;
+import com.intellij.openapi.vfs.VirtualFile;
+import com.intellij.psi.PsiElement;
+import com.intellij.psi.PsiFile;
+import com.intellij.ui.breadcrumbs.BreadcrumbsProvider;
+import com.intellij.util.containers.ContainerUtil;
+import com.redhat.devtools.lsp4ij.LanguageServiceAccessor;
+import com.redhat.devtools.lsp4ij.features.documentSymbol.LSPDocumentSymbolStructureViewModel.LSPDocumentSymbolViewElement;
+import com.redhat.devtools.lsp4ij.features.documentSymbol.LSPDocumentSymbolStructureViewModel.LSPFileStructureViewElement;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import javax.swing.Icon;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * LSP document symbol-based breadcrumbs provider.
+ */
+public class LSPBreadcrumbsProvider implements BreadcrumbsProvider {
+
+    @Override
+    public Language[] getLanguages() {
+        // Register for all languages and filter in isSupported()
+        List<Language> languages = LanguageUtil.getLanguages(Conditions.alwaysTrue());
+        return languages.toArray(Language.EMPTY_ARRAY);
+    }
+
+    private boolean isSupported(@NotNull PsiElement element) {
+        Project project = element.getProject();
+        PsiFile file = element.getContainingFile();
+        VirtualFile virtualFile = file.getVirtualFile();
+        return LanguageServiceAccessor.getInstance(project).hasAny(
+                virtualFile,
+                // The breadcrumbs feature must be enabled and supported for the file's language server
+                ls -> ls.getClientFeatures().getBreadcrumbsFeature().isEnabled(file) &&
+                        ls.getClientFeatures().getBreadcrumbsFeature().isSupported(file)
+        );
+    }
+
+    @Override
+    public boolean acceptElement(@NotNull PsiElement element) {
+        // NOTE: This is only used to determine which already-vetted elements should be included in the breadcrumb trail
+        return element instanceof DocumentSymbolData;
+    }
+
+    @Override
+    @Nullable
+    public PsiElement getParent(@NotNull PsiElement element) {
+        if (isSupported(element)) {
+            if (element instanceof PsiFile file) {
+                return file.getParent();
+            } else if (element instanceof DocumentSymbolData documentSymbolData) {
+                return documentSymbolData.getParent();
+            } else {
+                return LSPDocumentSymbolUtils.getDocumentSymbolData(element);
+            }
+        }
+
+        return null;
+    }
+
+    @Override
+    @NotNull
+    public List<PsiElement> getChildren(@NotNull PsiElement element) {
+        if (isSupported(element)) {
+            if (element instanceof PsiFile file) {
+                LSPDocumentSymbolStructureViewModel structureViewModel = LSPDocumentSymbolUtils.getStructureViewModel(file);
+                StructureViewTreeElement root = structureViewModel != null ? structureViewModel.getRoot() : null;
+                if (root instanceof LSPFileStructureViewElement fileStructureViewElement) {
+                    StructureViewTreeElement[] children = fileStructureViewElement.getChildren();
+                    List<PsiElement> childElements = new ArrayList<>(children.length);
+                    for (StructureViewTreeElement child : children) {
+                        if (child instanceof LSPDocumentSymbolViewElement documentSymbolViewElement) {
+                            ContainerUtil.addIfNotNull(childElements, documentSymbolViewElement.getElement());
+                        }
+                    }
+                    return childElements;
+                }
+            } else {
+                DocumentSymbolData documentSymbolData = LSPDocumentSymbolUtils.getDocumentSymbolData(element);
+                if (documentSymbolData != null) {
+                    return Arrays.asList(documentSymbolData.getChildren());
+                }
+            }
+        }
+
+        return Collections.emptyList();
+    }
+
+    @Override
+    @NotNull
+    public String getElementInfo(@NotNull PsiElement element) {
+        if (isSupported(element)) {
+            if (element instanceof PsiFile file) {
+                return file.getName();
+            } else {
+                DocumentSymbolData documentSymbolData = LSPDocumentSymbolUtils.getDocumentSymbolData(element);
+                if (documentSymbolData != null) {
+                    String presentableText = documentSymbolData.getPresentableText();
+                    String name = documentSymbolData.getName();
+                    return presentableText != null ? presentableText : name != null ? name : "";
+                }
+            }
+        }
+
+        return "";
+    }
+
+    @Override
+    @Nullable
+    public String getElementTooltip(@NotNull PsiElement element) {
+        return !(element instanceof PsiFile) && isSupported(element) ? getElementInfo(element) : null;
+    }
+
+    @Override
+    @Nullable
+    public Icon getElementIcon(@NotNull PsiElement element) {
+        if (!(element instanceof PsiFile) && isSupported(element)) {
+            DocumentSymbolData documentSymbolData = LSPDocumentSymbolUtils.getDocumentSymbolData(element);
+            return documentSymbolData != null ? documentSymbolData.getIcon(false) : null;
+        }
+
+        return null;
+    }
+}