feat: public read API on ClipboardBinding (#24480)

Clipboard.onClick(button).read(onPayload, onError) — and the
single-field convenience variants readText / readHtml — make the
read side reachable from the same binding entry point as the write
side, instead of forcing callers to instantiate the internal
ReadFromClipboardAction themselves.

ClipboardPayload moves out of trigger.internal into the public
clipboard package so it can sit in the read methods' signatures
without leaking an internal type, mirroring how ClipboardContent
already lives there for the write side. The private bind() helper
on ClipboardBinding is generalised to accept any Action so it can
route both write and read actions.

The read IT view is restructured into headed sections and gains
two new buttons (read-text, read-html); the IT picks up matching
scenarios that use the existing resolving-clipboard shim.

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/component/clipboard/ClipboardBinding.java

@@ -23,10 +23,12 @@
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.HasValue;
 import com.vaadin.flow.component.Tag;
+import com.vaadin.flow.component.trigger.internal.Action;
 import com.vaadin.flow.component.trigger.internal.ImageBlobInput;
 import com.vaadin.flow.component.trigger.internal.LiteralInput;
 import com.vaadin.flow.component.trigger.internal.PromiseAction.Error;
 import com.vaadin.flow.component.trigger.internal.PropertyInput;
+import com.vaadin.flow.component.trigger.internal.ReadFromClipboardAction;
 import com.vaadin.flow.component.trigger.internal.Trigger;
 import com.vaadin.flow.component.trigger.internal.WriteToClipboardAction;
 import com.vaadin.flow.dom.Element;
@@ -37,13 +39,19 @@
 /**
  * Fluent surface returned from {@link Clipboard#onClick}. Each {@code write*}
  * action attaches one {@link WriteToClipboardAction} to the underlying
- * {@link Trigger}.
+ * {@link Trigger}; each {@code read*} action attaches one
+ * {@link ReadFromClipboardAction}.
  * <p>
- * Actions come in two flavours: fire-and-forget (one argument) and observed
- * (with {@code onCopied}/{@code onError} callbacks). {@code onCopied} receives
- * the string that was copied; {@code onError} receives the browser's error.
- * Both consumers are required in the observed form — pass {@code s -> {}} or
- * {@code err -> {}} to opt out of one.
+ * Write actions come in two flavours: fire-and-forget (one argument) and
+ * observed (with {@code onCopied}/{@code onError} callbacks). {@code onCopied}
+ * receives the string that was copied; {@code onError} receives the browser's
+ * error. Both consumers are required in the observed form — pass
+ * {@code s -> {}} or {@code err -> {}} to opt out of one.
+ * <p>
+ * Read actions always take both an {@code onPayload} consumer (receiving the
+ * clipboard contents or {@code null} if empty) and an {@code onError} consumer
+ * (receiving the browser's error, typically {@code "NotAllowedError"} when the
+ * user denied the {@code clipboard-read} permission).
  *
  * <pre>{@code
  * Button copy = new Button("Copy");
@@ -52,6 +60,11 @@
  * Clipboard.onClick(copy).writeText(textField,
  *         copied -> Notification.show("Copied " + copied),
  *         err -> Notification.show("Failed: " + err.message()));
+ *
+ * Button paste = new Button("Paste");
+ * Clipboard.onClick(paste).readText(
+ *         text -> Notification.show("Pasted " + text),
+ *         err -> Notification.show("Failed: " + err.message()));
  * }</pre>
  */
 public final class ClipboardBinding implements Serializable {
@@ -312,7 +325,72 @@ public void write(ClipboardContent content,
                 onError));
     }
 
-    private void bind(WriteToClipboardAction action) {
+    /**
+     * Reads the user's clipboard via {@code navigator.clipboard.read()} when
+     * the underlying trigger fires and delivers the contents to
+     * {@code onPayload}, or routes any failure to {@code onError}.
+     * <p>
+     * The Clipboard API requires the call to happen inside a short-lived user
+     * gesture AND the user to grant the {@code clipboard-read} permission;
+     * binding to a click trigger satisfies the gesture, but the browser may
+     * still reject the read with {@code "NotAllowedError"} when the permission
+     * is denied.
+     *
+     * @param onPayload
+     *            UI-thread callback receiving the clipboard contents, or
+     *            {@code null} if the clipboard was empty; not {@code null}
+     * @param onError
+     *            UI-thread callback receiving the browser's error, not
+     *            {@code null}
+     */
+    public void read(SerializableConsumer<@Nullable ClipboardPayload> onPayload,
+            SerializableConsumer<Error> onError) {
+        Objects.requireNonNull(onPayload, "onPayload must not be null");
+        Objects.requireNonNull(onError, "onError must not be null");
+        bind(new ReadFromClipboardAction(onPayload, onError));
+    }
+
+    /**
+     * Like {@link #read} but delivers only the {@code text/plain} field of the
+     * clipboard payload to {@code onText}. {@code onText} receives {@code null}
+     * if the clipboard was empty or had no {@code text/plain} representation.
+     *
+     * @param onText
+     *            UI-thread callback receiving the {@code text/plain} value, or
+     *            {@code null}; not {@code null}
+     * @param onError
+     *            UI-thread callback receiving the browser's error, not
+     *            {@code null}
+     */
+    public void readText(SerializableConsumer<@Nullable String> onText,
+            SerializableConsumer<Error> onError) {
+        Objects.requireNonNull(onText, "onText must not be null");
+        Objects.requireNonNull(onError, "onError must not be null");
+        bind(new ReadFromClipboardAction(
+                p -> onText.accept(p == null ? null : p.text()), onError));
+    }
+
+    /**
+     * Like {@link #read} but delivers only the {@code text/html} field of the
+     * clipboard payload to {@code onHtml}. {@code onHtml} receives {@code null}
+     * if the clipboard was empty or had no {@code text/html} representation.
+     *
+     * @param onHtml
+     *            UI-thread callback receiving the {@code text/html} value, or
+     *            {@code null}; not {@code null}
+     * @param onError
+     *            UI-thread callback receiving the browser's error, not
+     *            {@code null}
+     */
+    public void readHtml(SerializableConsumer<@Nullable String> onHtml,
+            SerializableConsumer<Error> onError) {
+        Objects.requireNonNull(onHtml, "onHtml must not be null");
+        Objects.requireNonNull(onError, "onError must not be null");
+        bind(new ReadFromClipboardAction(
+                p -> onHtml.accept(p == null ? null : p.html()), onError));
+    }
+
+    private void bind(Action action) {
         trigger.triggers(action);
     }
 }

…t/trigger/internal/ClipboardPayload.java …omponent/clipboard/ClipboardPayload.javaflow-server/src/main/java/com/vaadin/flow/component/trigger/internal/ClipboardPayload.java renamed to flow-server/src/main/java/com/vaadin/flow/component/clipboard/ClipboardPayload.java flow-server/src/main/java/com/vaadin/flow/component/trigger/internal/ClipboardPayload.java renamed to flow-server/src/main/java/com/vaadin/flow/component/clipboard/ClipboardPayload.java

@@ -13,18 +13,16 @@
  * License for the specific language governing permissions and limitations under
  * the License.
  */
-package com.vaadin.flow.component.trigger.internal;
+package com.vaadin.flow.component.clipboard;
 
 import java.io.Serializable;
 
 import org.jspecify.annotations.Nullable;
 
 /**
- * Textual clipboard contents delivered to {@link ReadFromClipboardAction}'s
- * handler. Either field may be {@code null} if the corresponding MIME type was
- * not present on the clipboard item.
- * <p>
- * For internal use only. May be renamed or removed in a future release.
+ * Textual clipboard contents delivered to {@link ClipboardBinding#read}'s
+ * payload handler. Either field may be {@code null} if the corresponding MIME
+ * type was not present on the clipboard item.
  *
  * @param text
  *            {@code text/plain} contents, or {@code null} if not present

flow-server/src/main/java/com/vaadin/flow/component/trigger/internal/ReadFromClipboardAction.java

@@ -17,6 +17,7 @@
 
 import org.jspecify.annotations.Nullable;
 
+import com.vaadin.flow.component.clipboard.ClipboardPayload;
 import com.vaadin.flow.dom.JsFunction;
 import com.vaadin.flow.function.SerializableConsumer;
 

flow-server/src/test/java/com/vaadin/flow/component/clipboard/ClipboardTest.java

@@ -15,9 +15,13 @@
  */
 package com.vaadin.flow.component.clipboard;
 
+import java.util.ArrayList;
 import java.util.List;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.Test;
+import tools.jackson.databind.node.ArrayNode;
+import tools.jackson.databind.node.ObjectNode;
 
 import com.vaadin.flow.component.AbstractField;
 import com.vaadin.flow.component.ClickNotifier;
@@ -27,9 +31,12 @@
 import com.vaadin.flow.component.internal.PendingJavaScriptInvocation;
 import com.vaadin.flow.component.internal.UIInternals.JavaScriptInvocation;
 import com.vaadin.flow.dom.JsFunction;
+import com.vaadin.flow.internal.JacksonUtils;
+import com.vaadin.flow.internal.nodefeature.ReturnChannelRegistration;
 import com.vaadin.tests.util.MockUI;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -196,6 +203,105 @@ void writeImage_nonImgComponent_throws() {
                 () -> Clipboard.onClick(button).writeImage(button));
     }
 
+    @Test
+    void read_emitsReadFromClipboardAction() {
+        UI ui = new MockUI();
+        TestButton button = new TestButton();
+        ui.getElement().appendChild(button.getElement());
+
+        Clipboard.onClick(button).read(p -> {
+        }, err -> {
+        });
+
+        // Observed PromiseAction wraps the inner call; the inner JsFunction
+        // delegates to the TS readPayload helper.
+        JsFunction action = actionFn(ui);
+        JsFunction inner = (JsFunction) action.getCaptures().get(1);
+        assertEquals("return window.Vaadin.Flow.clipboard.readPayload()",
+                inner.getBody());
+    }
+
+    @Test
+    void readText_adaptsPayloadConsumerToTextField() {
+        UI ui = new MockUI();
+        TestButton button = new TestButton();
+        ui.getElement().appendChild(button.getElement());
+
+        List<@Nullable String> received = new ArrayList<>();
+        Clipboard.onClick(button).readText(received::add, err -> {
+        });
+
+        // Capture the channel once before the install JS gets drained, then
+        // exercise both the payload-present and the null-payload paths.
+        ReturnChannelRegistration channel = returnChannel(ui);
+
+        invokeSuccess(channel, "hello", "<b>hello</b>");
+        assertEquals(List.of("hello"), received);
+
+        received.clear();
+        invokeSuccessNull(channel);
+        assertEquals(1, received.size());
+        assertNull(received.get(0));
+    }
+
+    @Test
+    void readHtml_adaptsPayloadConsumerToHtmlField() {
+        UI ui = new MockUI();
+        TestButton button = new TestButton();
+        ui.getElement().appendChild(button.getElement());
+
+        List<@Nullable String> received = new ArrayList<>();
+        Clipboard.onClick(button).readHtml(received::add, err -> {
+        });
+
+        ReturnChannelRegistration channel = returnChannel(ui);
+
+        invokeSuccess(channel, "hello", "<b>hello</b>");
+        assertEquals(List.of("<b>hello</b>"), received);
+
+        received.clear();
+        invokeSuccessNull(channel);
+        assertEquals(1, received.size());
+        assertNull(received.get(0));
+    }
+
+    private static void invokeSuccess(ReturnChannelRegistration channel,
+            String text, String html) {
+        ObjectNode payload = JacksonUtils.createObjectNode();
+        payload.put("text", text);
+        payload.put("html", html);
+        ObjectNode outcome = JacksonUtils.createObjectNode();
+        outcome.put("ok", true);
+        outcome.set("value", payload);
+        ArrayNode args = JacksonUtils.createArrayNode();
+        args.add(outcome);
+        channel.invoke(args);
+    }
+
+    private static void invokeSuccessNull(ReturnChannelRegistration channel) {
+        ObjectNode outcome = JacksonUtils.createObjectNode();
+        outcome.put("ok", true);
+        outcome.set("value", JacksonUtils.nullNode());
+        ArrayNode args = JacksonUtils.createArrayNode();
+        args.add(outcome);
+        channel.invoke(args);
+    }
+
+    /**
+     * The action's captures include the single return-channel registration (the
+     * third arg of the observed wrapper). Pull it out so the test can
+     * synthesise an outcome and verify the user-supplied consumer. Drains the
+     * pending JS invocations as a side effect — call once per test.
+     */
+    private static ReturnChannelRegistration returnChannel(UI ui) {
+        List<ReturnChannelRegistration> channels = actionFn(ui).getCaptures()
+                .stream().filter(o -> o instanceof ReturnChannelRegistration)
+                .map(o -> (ReturnChannelRegistration) o).toList();
+        assertEquals(1, channels.size(),
+                "Expected exactly one captured return channel");
+        return channels.get(0);
+    }
+
     /**
      * Returns the action JsFunction for a fire-and-forget binding: the install
      * JsFunction's $0 capture, which in fire-and-forget mode is the JsFunction

flow-server/src/test/java/com/vaadin/flow/component/trigger/internal/ReadFromClipboardActionTest.java

@@ -24,6 +24,7 @@
 import tools.jackson.databind.node.ObjectNode;
 
 import com.vaadin.flow.component.UI;
+import com.vaadin.flow.component.clipboard.ClipboardPayload;
 import com.vaadin.flow.dom.JsFunction;
 import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.tests.util.MockUI;

flow-tests/test-root-context/src/main/java/com/vaadin/flow/uitest/ui/TriggerReadFromClipboardView.java

@@ -15,38 +15,89 @@
  */
 package com.vaadin.flow.uitest.ui;
 
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.clipboard.Clipboard;
+import com.vaadin.flow.component.clipboard.ClipboardBinding;
 import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.component.html.H2;
+import com.vaadin.flow.component.html.Hr;
 import com.vaadin.flow.component.html.NativeButton;
-import com.vaadin.flow.component.trigger.internal.ClickTrigger;
-import com.vaadin.flow.component.trigger.internal.ReadFromClipboardAction;
+import com.vaadin.flow.component.html.Paragraph;
 import com.vaadin.flow.router.Route;
 import com.vaadin.flow.uitest.servlet.ViewTestLayout;
 
 /**
- * Wires a {@link ClickTrigger} on a button to a {@link ReadFromClipboardAction}
- * that writes the received {@code ClipboardPayload} (or {@code "null"}) into a
- * status div, so the IT can assert both paths. The IT replaces
+ * Buttons exercising {@link ClipboardBinding}'s read methods, grouped into
+ * sections so the view doubles as a manual smoke-test page: a multi-format read
+ * returning both {@code text/plain} and {@code text/html}, a text-only read,
+ * and an html-only read. Each action's payload/error consumer writes the
+ * outcome into the status {@link Div}. The IT replaces
  * {@code navigator.clipboard.read} with a recording shim so the assertions
- * don't depend on browser clipboard permissions.
+ * don't depend on browser clipboard permissions; manual users copy something
+ * into their system clipboard first, then click a button and read the result in
+ * the status div.
  */
 @Route(value = "com.vaadin.flow.uitest.ui.TriggerReadFromClipboardView", layout = ViewTestLayout.class)
 public class TriggerReadFromClipboardView extends AbstractDivView {
 
     @Override
     protected void onShow() {
-        NativeButton readButton = new NativeButton("Read");
-        readButton.setId("read");
         Div status = new Div();
         status.setId("status");
 
-        add(readButton, status);
+        NativeButton readButton = new NativeButton("Read clipboard");
+        readButton.setId("read");
+        addSection("Read both text/plain and text/html",
+                "Pastes the current clipboard's text and html into the status"
+                        + " line as \"text=...;html=...\" (or \"null\" if the"
+                        + " clipboard is empty).",
+                readButton);
+
+        NativeButton readTextButton = new NativeButton("Read text only");
+        readTextButton.setId("read-text");
+        addSection("Read only text/plain",
+                "Pastes just the clipboard's text/plain field into the status"
+                        + " line as \"text=...\" (or \"text=null\" if absent).",
+                readTextButton);
+
+        NativeButton readHtmlButton = new NativeButton("Read html only");
+        readHtmlButton.setId("read-html");
+        addSection("Read only text/html",
+                "Pastes just the clipboard's text/html field into the status"
+                        + " line as \"html=...\" (or \"html=null\" if absent).",
+                readHtmlButton);
+
+        add(new Hr(), new H2("Last action outcome"),
+                new Paragraph("Each button's onPayload/onError callback writes"
+                        + " here. \"error=<name>\" appears when the browser"
+                        + " rejected the read (e.g. permission denied)."),
+                status);
 
-        new ClickTrigger(readButton).triggers(new ReadFromClipboardAction(p -> {
+        Clipboard.onClick(readButton).read(p -> {
             if (p == null) {
                 status.setText("null");
             } else {
                 status.setText("text=" + p.text() + ";html=" + p.html());
             }
-        }, err -> status.setText("error=" + err.name())));
+        }, err -> status.setText("error=" + err.name()));
+
+        Clipboard.onClick(readTextButton).readText(
+                text -> status.setText("text=" + text),
+                err -> status.setText("error=" + err.name()));
+
+        Clipboard.onClick(readHtmlButton).readHtml(
+                html -> status.setText("html=" + html),
+                err -> status.setText("error=" + err.name()));
+    }
+
+    private void addSection(String heading, String description,
+            Component... contents) {
+        Div section = new Div();
+        section.getStyle().set("margin", "1em 0").set("padding", "0.5em 0")
+                .set("border-top", "1px solid #ccc");
+        section.add(new H2(heading));
+        section.add(new Paragraph(description));
+        section.add(contents);
+        add(section);
     }
 }