feat: add getUI() to ComponentEvent (#24205)

`ComponentEvent` exposes the source component but offers no direct way
to reach its UI. Listeners that need the UI must dereference an
`Optional` via `event.getSource().getUI().ifPresent(...)`, which is
verbose and silently swallows the case where the source is detached.

Add `ComponentEvent.getUI()` returning `UI` directly. When the source is
itself a `UI`, it is returned as-is; otherwise the method returns the
resolved UI or throws `IllegalStateException` with a message pointing to
`getSource().getUI()` for code that must handle a detached source. This
matches the convention already used by `AbstractAttachDetachEvent`,
`UIInitEvent`, `BeforeEvent` and similar event types.

Fixes #18818

Author: mcollovati

flow-server/src/main/java/com/vaadin/flow/component/ComponentEvent.java

@@ -56,6 +56,38 @@ public T getSource() {
         return (T) super.getSource();
     }
 
+    /**
+     * Gets the UI the source component is attached to.
+     * <p>
+     * This is a convenience for {@code getSource().getUI().get()} when the
+     * event is fired while the source is attached to a UI, which is the common
+     * case.
+     * <p>
+     * If the source component is not currently attached to a UI, this method
+     * throws an {@link IllegalStateException}. This can happen, for example,
+     * when an initial value is set on a field before it is added to the UI and
+     * a value-change listener is invoked. If your listener can run while the
+     * source is detached, use {@code getSource().getUI()} instead, which
+     * returns an {@link java.util.Optional} and lets you handle the detached
+     * case explicitly.
+     *
+     * @return the UI the source component is attached to, never {@code null}
+     * @throws IllegalStateException
+     *             if the source component is not currently attached to a UI
+     */
+    public UI getUI() {
+        T source = getSource();
+        if (source instanceof UI ui) {
+            return ui;
+        }
+        return source.getUI()
+                .orElseThrow(() -> new IllegalStateException(
+                        "Cannot resolve UI for event source " + source
+                                + ": the component is not currently attached "
+                                + "to a UI. Use getSource().getUI() to handle "
+                                + "the detached case explicitly."));
+    }
+
     /**
      * Checks if this event originated from the client side.
      *

flow-server/src/test/java/com/vaadin/flow/component/ComponentEventTest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2000-2026 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;
+
+import org.junit.jupiter.api.Test;
+
+import com.vaadin.flow.component.ComponentTest.TestComponent;
+import com.vaadin.tests.util.MockUI;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ComponentEventTest {
+
+    @Test
+    void getUI_sourceAttached_returnsUI() {
+        MockUI ui = new MockUI();
+        TestComponent source = new TestComponent();
+        ui.add(source);
+
+        ComponentEvent<TestComponent> event = new ComponentEvent<>(source,
+                false);
+
+        assertSame(ui, event.getUI());
+    }
+
+    @Test
+    void getUI_sourceIsUI_returnsSource() {
+        MockUI ui = new MockUI();
+
+        ComponentEvent<UI> event = new ComponentEvent<>(ui, false);
+
+        assertSame(ui, event.getUI());
+    }
+
+    @Test
+    void getUI_sourceDetached_throwsIllegalStateException() {
+        TestComponent source = new TestComponent();
+
+        ComponentEvent<TestComponent> event = new ComponentEvent<>(source,
+                false);
+
+        IllegalStateException exception = assertThrows(
+                IllegalStateException.class, event::getUI);
+        assertNotNull(exception.getMessage());
+        assertEquals(true, exception.getMessage().contains("not")
+                && exception.getMessage().contains("attached"));
+    }
+}