fix: prevent infinite focus loop and stale selection in custom editors (CP: 25.1) (#9120)

This PR cherry-picks changes from the original PR #9113 to branch 25.1.

---

> ## Summary
> - Fix infinite `cellSelected` feedback loop triggered by programmatic
focus changes (e.g. `inputElement.select()`) in
`onCustomEditorDisplayed` callbacks
> - Prevent delayed server responses from hijacking the cell selection
when the user has already navigated away, including via keyboard
navigation through cells with custom editors
> - Add server-side reentrancy guard to prevent recursive
`onCustomEditorDisplayed` calls when callback code calls
`refreshCells()`
> 
> ## Root cause
> `CustomEditorEventListener.ONFOCUS` unconditionally sent
`cellSelected` to the server and updated the client-side selection on
every focus event — including programmatic focus from
`inputElement.select()` called in `onCustomEditorDisplayed`. When the
callback had non-trivial processing time, the delayed response would
steal focus and selection from whatever cell the user had since
navigated to, and could trigger an infinite client→server→client loop.
> 
> ## Approach
> **Client-side** (`CustomEditorEventListener`): track
`mousedown`/`touchstart` events to distinguish user-initiated focus from
programmatic focus. Only update the selection and send `cellSelected`
for user-initiated focus. For programmatic focus on a cell the user has
already left, return focus to the sheet. Keyboard navigation is
unaffected because `SelectionHandler` already handles selection updates
and `cellSelected` independently.
> 
> **Server-side** (`Spreadsheet`): reentrancy guard
(`insideCustomEditorCallback`) on `loadCustomEditorOnSelectedCell()` to
prevent recursive `onCustomEditorDisplayed` calls when user code in the
callback calls `refreshCells()`.
> 
> Fixes #9036
> 
> ## Test plan
> - [ ]
`CustomEditorIT#comboBoxEditorWithSelect_clickCell_callbackFiredOnce` —
verifies single click triggers exactly 1 callback (no loop)
> - [ ]
`CustomEditorIT#comboBoxEditorWithSelect_switchBetweenCells_noInfiniteLoop`
— rapidly clicks through editor cells to a non-editor cell, verifies
selection stays on the final cell and callback count is bounded
> - [ ] All 26 existing `CustomEditorIT` tests pass (keyboard
navigation, Tab, Shift+Tab, F2, Enter, ESC, shared editors, frozen
panes, always-visible mode)
> 
> 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: DiegoCardoso

vaadin-spreadsheet-flow-parent/vaadin-spreadsheet-flow-client/src/main/java/com/vaadin/addon/spreadsheet/client/CustomEditorEventListener.java

@@ -30,13 +30,14 @@ public class CustomEditorEventListener implements EventListener {
     private Slot slot;
     private String cellAddress;
     private SpreadsheetWidget widget;
+    private boolean userInitiatedFocus;
 
     public void init(Slot slot, String cellAddress) {
         this.slot = slot;
         this.cellAddress = cellAddress;
         Event.setEventListener(slot.getAssignedElement(), this);
-        DOM.sinkEvents(slot.getAssignedElement(),
-                Event.ONKEYDOWN | Event.FOCUSEVENTS);
+        DOM.sinkEvents(slot.getAssignedElement(), Event.ONKEYDOWN
+                | Event.FOCUSEVENTS | Event.ONMOUSEDOWN | Event.ONTOUCHSTART);
     }
 
     public void setCellAddress(String cellAddress) {
@@ -63,20 +64,45 @@ public void onBrowserEvent(Event event) {
                 break;
             }
             break;
+        case Event.ONMOUSEDOWN:
+        case Event.ONTOUCHSTART:
+            userInitiatedFocus = true;
+            break;
         case Event.ONFOCUS:
-            var jsniUtil = getSheetWidget().getSheetJsniUtil();
-            jsniUtil.parseColRow(cellAddress);
-            var col = jsniUtil.getParsedCol();
-            var row = jsniUtil.getParsedRow();
-            getSheetWidget().setSelectedCell(col, row);
-            getSheetWidget().updateSelectionOutline(col, col, row, row);
-            getSheetWidget().updateSelectedCellStyles(col, col, row, row, true);
-            getSpreadsheetWidget().getSpreadsheetHandler().cellSelected(row,
-                    col, true);
             slot.setElementFocused(true);
+            // Only update selection and notify the server if this focus was
+            // triggered by a user interaction (mouse/touch). Programmatic
+            // focus changes (e.g. inputElement.select() from
+            // onCustomEditorDisplayed) must not update the selection or send
+            // cellSelected — doing so would move the selection to a stale
+            // cell when the delayed server response arrives, and could
+            // create an infinite feedback loop between client and server.
+            // Keyboard navigation already handles selection updates and
+            // cellSelected through SelectionHandler independently.
+            if (userInitiatedFocus) {
+                userInitiatedFocus = false;
+                var jsniUtil = getSheetWidget().getSheetJsniUtil();
+                jsniUtil.parseColRow(cellAddress);
+                var col = jsniUtil.getParsedCol();
+                var row = jsniUtil.getParsedRow();
+                getSheetWidget().setSelectedCell(col, row);
+                getSheetWidget().updateSelectionOutline(col, col, row, row);
+                getSheetWidget().updateSelectedCellStyles(col, col, row, row,
+                        true);
+                getSpreadsheetWidget().getSpreadsheetHandler().cellSelected(row,
+                        col, true);
+            } else if (!cellAddress
+                    .equals(getSheetWidget().getSelectedCellKey())) {
+                // Programmatic focus (e.g. inputElement.select() from a
+                // delayed server response) on a cell the user has already
+                // left. Return focus to the sheet so keyboard input isn't
+                // captured by a stale editor.
+                getSheetWidget().focusSheet();
+            }
             break;
         case Event.ONBLUR:
             slot.setElementFocused(false);
+            userInitiatedFocus = false;
             break;
         }
     }

vaadin-spreadsheet-flow-parent/vaadin-spreadsheet-flow-integration-tests/src/main/java/com/vaadin/flow/component/spreadsheet/tests/fixtures/CustomEditorSelectFixture.java

@@ -0,0 +1,102 @@
+/**
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ * See {@literal <https://vaadin.com/commercial-license-and-service-terms>} for the full
+ * license.
+ */
+package com.vaadin.flow.component.spreadsheet.tests.fixtures;
+
+import org.apache.poi.ss.usermodel.Cell;
+import org.apache.poi.ss.usermodel.Sheet;
+
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.combobox.ComboBox;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.spreadsheet.Spreadsheet;
+import com.vaadin.flow.component.spreadsheet.SpreadsheetComponentFactory;
+
+/**
+ * Test fixture for verifying that custom editors calling
+ * {@code inputElement.select()} in {@code onCustomEditorDisplayed} do not cause
+ * an infinite focus loop between client and server.
+ * <p>
+ * Exposes a callback counter as a custom component in cell A1 (id
+ * "callbackCount") so tests can verify the number of
+ * {@code onCustomEditorDisplayed} invocations.
+ */
+public class CustomEditorSelectFixture implements SpreadsheetFixture {
+
+    @Override
+    public void loadFixture(Spreadsheet spreadsheet) {
+        spreadsheet.setColumnWidth(1, 150);
+        spreadsheet.setColumnWidth(2, 150);
+        spreadsheet.setColumnWidth(3, 150);
+        spreadsheet.setColumnWidth(4, 150);
+
+        spreadsheet.setSpreadsheetComponentFactory(new SelectEditorFactory());
+    }
+
+    private static class SelectEditorFactory
+            implements SpreadsheetComponentFactory {
+
+        private static final String[] FRUITS = { "Apple", "Banana", "Cherry" };
+
+        private int callbackCount;
+        private Span counterLabel;
+
+        @Override
+        public Component getCustomComponentForCell(Cell cell, int rowIndex,
+                int columnIndex, Spreadsheet spreadsheet, Sheet sheet) {
+            if (rowIndex == 0 && columnIndex == 0) {
+                if (counterLabel == null) {
+                    counterLabel = new Span("0");
+                    counterLabel.setId("callbackCount");
+                }
+                return counterLabel;
+            }
+            return null;
+        }
+
+        @Override
+        public Component getCustomEditorForCell(Cell cell, final int rowIndex,
+                final int columnIndex, final Spreadsheet spreadsheet,
+                Sheet sheet) {
+            if (rowIndex == 1 && columnIndex >= 1 && columnIndex <= 4) {
+                ComboBox<String> comboBox = new ComboBox<>();
+                comboBox.setItems(FRUITS);
+                comboBox.setWidthFull();
+                return comboBox;
+            }
+            return null;
+        }
+
+        @Override
+        public void onCustomEditorDisplayed(Cell cell, int rowIndex,
+                int columnIndex, Spreadsheet spreadsheet, Sheet sheet,
+                Component customEditor) {
+            callbackCount++;
+            if (counterLabel != null) {
+                counterLabel.setText(String.valueOf(callbackCount));
+            }
+
+            if (customEditor instanceof ComboBox<?>) {
+                try {
+                    // Simulate server-side processing time (DB lookups,
+                    // business logic). This delay causes the client to queue
+                    // subsequent cellSelected RPCs, reproducing the scenario
+                    // where the user navigates away before the response
+                    // arrives.
+                    Thread.sleep(200);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                }
+                @SuppressWarnings("unchecked")
+                ComboBox<String> comboBox = (ComboBox<String>) customEditor;
+                comboBox.setValue(FRUITS[columnIndex % FRUITS.length]);
+                comboBox.getElement().executeJs("this.inputElement.select();");
+            }
+        }
+    }
+}

vaadin-spreadsheet-flow-parent/vaadin-spreadsheet-flow-integration-tests/src/main/java/com/vaadin/flow/component/spreadsheet/tests/fixtures/TestFixtures.java

@@ -12,6 +12,7 @@
  * Test fixtures for server-side Spreadsheet manipulation
  *
  */
+@SuppressWarnings("java:S115") // Enum constants use PascalCase by convention
 public enum TestFixtures {
     FirstColumnWidth(FirstColumnWidthFixture.class),
     PopupButton(PopupButtonFixture.class),
@@ -39,6 +40,7 @@ public enum TestFixtures {
     AdjacentCustomEditors(AdjacentCustomEditorsFixture.class),
     CustomEditorShared(CustomEditorSharedFixture.class),
     CustomEditorRow(CustomEditorRowFixture.class),
+    CustomEditorSelect(CustomEditorSelectFixture.class),
     Styles(StylesFixture.class),
     LockCell(LockCellFixture.class),
     LockSheet(LockSheetFixture.class),

vaadin-spreadsheet-flow-parent/vaadin-spreadsheet-flow-integration-tests/src/test/java/com/vaadin/flow/component/spreadsheet/test/CustomEditorIT.java

@@ -572,6 +572,45 @@ private WebElement getActiveElement() {
         return getDriver().switchTo().activeElement();
     }
 
+    @Test
+    public void comboBoxEditorWithSelect_clickCell_callbackFiredOnce() {
+        createNewSpreadsheet();
+        loadTestFixture(TestFixtures.CustomEditorSelect);
+
+        clickCell("B2");
+        getCommandExecutor().waitForVaadin();
+
+        Assert.assertEquals("1", getCallbackCount());
+    }
+
+    @Test
+    public void comboBoxEditorWithSelect_switchBetweenCells_noInfiniteLoop() {
+        createNewSpreadsheet();
+        loadTestFixture(TestFixtures.CustomEditorSelect);
+
+        // Click rapidly through editor cells and stop at a non-editor cell.
+        // The server-side callback has a 200ms delay, so responses arrive
+        // after the user has already moved past those cells.
+        clickCell("B2");
+        clickCell("C2");
+        clickCell("F2");
+        getCommandExecutor().waitForVaadin();
+
+        // Selection must stay on the cell where the user stopped, not jump
+        // back to a stale editor cell when delayed responses arrive.
+        assertAddressFieldValue("F2");
+
+        // Each editor cell visited should trigger exactly one callback.
+        // Without the fix, this would cause an infinite loop.
+        int count = Integer.parseInt(getCallbackCount());
+        Assert.assertTrue("Expected at most 2 callbacks but got " + count
+                + " — possible infinite loop", count <= 2);
+    }
+
+    private String getCallbackCount() {
+        return $(TestBenchElement.class).id("callbackCount").getText();
+    }
+
     private void clickToggleCellVisibleButton() {
         waitUntil(driver -> {
             try {

vaadin-spreadsheet-flow-parent/vaadin-spreadsheet-flow/src/main/java/com/vaadin/flow/component/spreadsheet/Spreadsheet.java

@@ -253,6 +253,8 @@ public void setId(String id) {
 
     private Registration spreadsheetHandlerRegistration;
 
+    private boolean insideCustomEditorCallback;
+
     int getCols() {
         return cols;
     }
@@ -3748,6 +3750,13 @@ private void markAsDirty() {
      * cell.
      */
     protected void loadCustomEditorOnSelectedCell() {
+        // Guard against reentrancy: if user code in onCustomEditorDisplayed
+        // calls refreshCells() -> updateMarkedCells() ->
+        // reloadVisibleCellContents() -> loadCells() ->
+        // loadCustomEditorOnSelectedCell(), skip the recursive call.
+        if (insideCustomEditorCallback) {
+            return;
+        }
         CellReference selectedCellReference = selectionManager
                 .getSelectedCellReference();
         if (selectedCellReference != null && customComponentFactory != null) {
@@ -3761,9 +3770,18 @@ protected void loadCustomEditorOnSelectedCell() {
                 String componentId = currentCellKeysToEditorIdMap.get(key);
                 for (Component c : customComponents) {
                     if (getComponentNodeId(c).equals(componentId)) {
-                        customComponentFactory.onCustomEditorDisplayed(
-                                getCell(row, col), row, col, this,
-                                getActiveSheet(), c);
+                        insideCustomEditorCallback = true;
+                        try {
+                            customComponentFactory.onCustomEditorDisplayed(
+                                    getCell(row, col), row, col, this,
+                                    getActiveSheet(), c);
+                        } catch (Exception e) {
+                            LOGGER.warn(
+                                    "Error in onCustomEditorDisplayed for cell ({}, {})",
+                                    col + 1, row + 1, e);
+                        } finally {
+                            insideCustomEditorCallback = false;
+                        }
                         return;
                     }
                 }