refactor: throw when using scrollToIndex(int...) with flat data provider (#8090)

Co-authored-by: Sascha Ißbrücker <[email protected]>

Author: vursen

vaadin-grid-flow-parent/vaadin-grid-flow/src/main/java/com/vaadin/flow/component/treegrid/TreeGrid.java

@@ -1020,14 +1020,29 @@ public void scrollToIndex(int index) {
      * component will first try to scroll to the item at index 2 in the root
      * level. If that item is expanded, it will then try to scroll to the item
      * at index 1 among its children, and so forth.
+     * <p>
+     * This method is only supported for data providers that use
+     * {@link HierarchyFormat#NESTED}. For {@link HierarchyFormat#FLATTENED},
+     * use {@link #scrollToIndex(int)} with a flat index instead.
      *
      * @param path
      *            an array of indexes representing the path to the target item
      * @throws IllegalArgumentException
      *             if the path is empty
-     * @see TreeGrid#scrollToIndex(int)
+     * @throws UnsupportedOperationException
+     *             if the data provider uses a hierarchy format other than
+     *             {@link HierarchyFormat#NESTED}
      */
     public void scrollToIndex(int... path) {
+        if (!getDataProvider().getHierarchyFormat()
+                .equals(HierarchyFormat.NESTED)) {
+            throw new UnsupportedOperationException(
+                    """
+                            scrollToIndex(int...) is supported only for data providers that use HierarchyFormat.NESTED. \
+                            For HierarchyFormat.FLATTENED, use scrollToIndex(int) with a flat index instead.
+                            """);
+        }
+
         if (path.length == 0) {
             throw new IllegalArgumentException(
                     "At least one index should be provided.");

vaadin-grid-flow-parent/vaadin-grid-flow/src/test/java/com/vaadin/flow/component/treegrid/ScrollToIndexTest.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.treegrid;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.vaadin.flow.data.provider.hierarchy.HierarchicalDataProvider.HierarchyFormat;
+import com.vaadin.flow.data.provider.hierarchy.TreeData;
+import com.vaadin.flow.data.provider.hierarchy.TreeDataProvider;
+
+public class ScrollToIndexTest {
+    private TreeGrid<String> treeGrid = new TreeGrid<>();
+    private TreeData<String> treeData = new TreeData<>();
+
+    @Test
+    public void nestedHierarchyFormat_scrollToIndexPath_doesNotThrow() {
+        treeGrid.setDataProvider(
+                new TreeDataProvider<>(treeData, HierarchyFormat.NESTED));
+        treeGrid.scrollToIndex(0, 0);
+    }
+
+    @Test
+    public void flattenedHierarchyFormat_scrollToIndexPath_throws() {
+        treeGrid.setDataProvider(
+                new TreeDataProvider<>(treeData, HierarchyFormat.FLATTENED));
+        Assert.assertThrows(UnsupportedOperationException.class,
+                () -> treeGrid.scrollToIndex(0, 0));
+    }
+}