feat: add bulk insert methods to ListSignal and SharedListSignal (#24026)

Add insertAllLast, insertAllFirst, and insertAllAt to ListSignal that
perform the entire batch with a single notification. Add insertAllLast,
insertAllFirst and insertAllAt to SharedListSignal using transactions
for atomicity.

---------

Co-authored-by: Tomi Virtanen <tltv@vaadin.com>

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/signals/local/ListSignal.java

@@ -16,6 +16,7 @@
 package com.vaadin.flow.signals.local;
 
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
@@ -201,6 +202,107 @@ private ValueSignal<T> insertAtInternal(int index, T value) {
         return entry;
     }
 
+    private List<ValueSignal<T>> createSignals(Collection<? extends T> values) {
+        List<ValueSignal<T>> signals = new ArrayList<>(values.size());
+        for (T value : values) {
+            signals.add(new ValueSignal<>(value, equalityChecker));
+        }
+        return signals;
+    }
+
+    /**
+     * Inserts all values as the last entries in this list. All entries are
+     * added with a single change notification.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     *
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @return an unmodifiable list of signals for the inserted entries
+     */
+    public List<ValueSignal<T>> insertAllLast(Collection<? extends T> values) {
+        Objects.requireNonNull(values, "Values must not be null");
+        if (values.isEmpty()) {
+            return List.of();
+        }
+        lock();
+        try {
+            checkPreconditions();
+            return insertAllAtInternal(
+                    Objects.requireNonNull(getSignalValue()).size(), values);
+        } finally {
+            unlock();
+        }
+    }
+
+    /**
+     * Inserts all values as the first entries in this list, preserving the
+     * order of the provided collection. All entries are added with a single
+     * change notification.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     *
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @return an unmodifiable list of signals for the inserted entries
+     */
+    public List<ValueSignal<T>> insertAllFirst(Collection<? extends T> values) {
+        return insertAllAt(0, values);
+    }
+
+    /**
+     * Inserts all values at the given index in this list, preserving the order
+     * of the provided collection. All entries are added with a single change
+     * notification.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     * <p>
+     * <b>Note:</b> This method should only be used in non-concurrent cases
+     * where the list structure is not being modified by other threads. The
+     * index is sensitive to concurrent modifications and may lead to unexpected
+     * results if the list is modified between determining the index and calling
+     * this method.
+     *
+     * @param index
+     *            the index at which to insert (0 for first, size() for last)
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @return an unmodifiable list of signals for the inserted entries
+     * @throws IndexOutOfBoundsException
+     *             if index is negative or greater than size()
+     */
+    public List<ValueSignal<T>> insertAllAt(int index,
+            Collection<? extends T> values) {
+        Objects.requireNonNull(values, "Values must not be null");
+        if (values.isEmpty()) {
+            return List.of();
+        }
+        lock();
+        try {
+            checkPreconditions();
+            List<ValueSignal<T>> currentEntries = Objects
+                    .requireNonNull(getSignalValue());
+            if (index < 0 || index > currentEntries.size()) {
+                throw new IndexOutOfBoundsException(
+                        "Index: " + index + ", Size: " + currentEntries.size());
+            }
+            return insertAllAtInternal(index, values);
+        } finally {
+            unlock();
+        }
+    }
+
+    private List<ValueSignal<T>> insertAllAtInternal(int index,
+            Collection<? extends T> values) {
+        assertLockHeld();
+        List<ValueSignal<T>> created = createSignals(values);
+        List<ValueSignal<T>> newEntries = new ArrayList<>(
+                Objects.requireNonNull(getSignalValue()));
+        newEntries.addAll(index, created);
+        setSignalValue(Collections.unmodifiableList(newEntries));
+        return Collections.unmodifiableList(created);
+    }
+
     /**
      * Removes the given entry from this list. Does nothing if the entry is not
      * in the list.

flow-server/src/main/java/com/vaadin/flow/signals/operations/BulkInsertOperation.java

@@ -0,0 +1,59 @@
+/*
+ * 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.signals.operations;
+
+import java.util.List;
+import java.util.Objects;
+
+import com.vaadin.flow.signals.Signal;
+
+/**
+ * An operation that inserts multiple child signals into a list as a single
+ * atomic batch. Unlike using individual {@link InsertOperation} instances, this
+ * operation tracks the entire batch with a single {@link #result()} future.
+ *
+ * @param <T>
+ *            the type of the newly inserted signals
+ */
+public class BulkInsertOperation<T extends Signal<?>>
+        extends SignalOperation<Void> {
+
+    private final List<T> signals;
+
+    /**
+     * Creates a new bulk insert operation with the given list of inserted
+     * signal instances.
+     *
+     * @param signals
+     *            an unmodifiable list of the newly inserted signal instances,
+     *            not <code>null</code>
+     */
+    public BulkInsertOperation(List<T> signals) {
+        this.signals = Objects.requireNonNull(signals);
+    }
+
+    /**
+     * Gets the list of newly inserted signal instances. The instances can be
+     * used immediately even in cases where the result of the operation is not
+     * immediately confirmed.
+     *
+     * @return an unmodifiable list of the newly inserted signal instances, not
+     *         <code>null</code>
+     */
+    public List<T> signals() {
+        return signals;
+    }
+}

flow-server/src/main/java/com/vaadin/flow/signals/shared/SharedListSignal.java

@@ -15,6 +15,9 @@
  */
 package com.vaadin.flow.signals.shared;
 
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.stream.Collectors;
@@ -30,8 +33,11 @@
 import com.vaadin.flow.signals.SignalCommand;
 import com.vaadin.flow.signals.function.CommandValidator;
 import com.vaadin.flow.signals.function.TransactionTask;
+import com.vaadin.flow.signals.operations.BulkInsertOperation;
 import com.vaadin.flow.signals.operations.InsertOperation;
 import com.vaadin.flow.signals.operations.SignalOperation;
+import com.vaadin.flow.signals.operations.SignalOperation.Result;
+import com.vaadin.flow.signals.operations.TransactionOperation;
 import com.vaadin.flow.signals.shared.impl.LocalAsynchronousSignalTree;
 import com.vaadin.flow.signals.shared.impl.SignalTree;
 
@@ -299,6 +305,88 @@ public InsertOperation<SharedValueSignal<T>> insertAt(T value,
                 this::child);
     }
 
+    /**
+     * Inserts all values as the last entries in this list. All inserts are
+     * performed within a single transaction for atomicity.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     *
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @return a bulk insert operation containing the inserted signals and a
+     *         single result future for the entire batch
+     */
+    public BulkInsertOperation<SharedValueSignal<T>> insertAllLast(
+            Collection<? extends T> values) {
+        return insertAllAt(values, ListPosition.last());
+    }
+
+    /**
+     * Inserts all values as the first entries in this list, preserving the
+     * order of the provided collection. All inserts are performed within a
+     * single transaction for atomicity.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     *
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @return a bulk insert operation containing the inserted signals and a
+     *         single result future for the entire batch
+     */
+    public BulkInsertOperation<SharedValueSignal<T>> insertAllFirst(
+            Collection<? extends T> values) {
+        return insertAllAt(values, ListPosition.first());
+    }
+
+    /**
+     * Inserts all values at the given position in this list, preserving the
+     * order of the provided collection. All inserts are performed within a
+     * single transaction for atomicity.
+     * <p>
+     * Each element is inserted immediately after the previously inserted
+     * element, so the final order matches the iteration order of the provided
+     * collection.
+     * <p>
+     * Individual null values are permitted if the element type allows null.
+     *
+     * @param values
+     *            the values to insert, not <code>null</code>
+     * @param at
+     *            the position at which to insert the first value, not
+     *            <code>null</code>
+     * @return a bulk insert operation containing the inserted signals and a
+     *         single result future for the entire batch
+     */
+    public BulkInsertOperation<SharedValueSignal<T>> insertAllAt(
+            Collection<? extends T> values, ListPosition at) {
+        Objects.requireNonNull(values, "Values must not be null");
+        Objects.requireNonNull(at, "Position must not be null");
+        if (values.isEmpty()) {
+            BulkInsertOperation<SharedValueSignal<T>> op = new BulkInsertOperation<>(
+                    List.of());
+            op.result().complete(new Result<>(null));
+            return op;
+        }
+        TransactionOperation<List<SharedValueSignal<T>>> txOp = Signal
+                .runInTransaction(() -> {
+                    List<SharedValueSignal<T>> signals = new ArrayList<>(
+                            values.size());
+                    ListPosition currentPos = at;
+                    for (T value : values) {
+                        InsertOperation<SharedValueSignal<T>> insertOp = insertAt(
+                                value, currentPos);
+                        signals.add(insertOp.signal());
+                        currentPos = ListPosition.after(insertOp.signal());
+                    }
+                    return Collections.unmodifiableList(signals);
+                });
+        BulkInsertOperation<SharedValueSignal<T>> bulkOp = new BulkInsertOperation<>(
+                Objects.requireNonNull(txOp.returnValue()));
+        txOp.result().thenAccept(
+                resultOrError -> bulkOp.result().complete(resultOrError));
+        return bulkOp;
+    }
+
     /**
      * Moves the given child signal to the given position in this list. The
      * operation fails if the child is not a child or if this list of if

flow-server/src/test/java/com/vaadin/flow/signals/local/ListSignalTest.java

@@ -702,6 +702,100 @@ void getValues_iterateWithoutTracking_throws() {
         assertThrows(IllegalStateException.class, () -> stream.toList());
     }
 
+    @Test
+    void insertAllLast_multipleValues_valuesAppended() {
+        ListSignal<String> signal = new ListSignal<>();
+        signal.insertLast("existing");
+
+        List<ValueSignal<String>> created = signal
+                .insertAllLast(List.of("a", "b", "c"));
+
+        assertEquals(3, created.size());
+        assertValues(signal, "existing", "a", "b", "c");
+    }
+
+    @Test
+    void insertAllLast_emptyCollection_noChange() {
+        ListSignal<String> signal = new ListSignal<>();
+        signal.insertLast("existing");
+
+        AtomicBoolean changed = new AtomicBoolean(false);
+        Usage usage = UsageTracker.track(signal::get);
+        usage.onNextChange(initial -> {
+            changed.set(true);
+            return false;
+        });
+
+        List<ValueSignal<String>> created = signal.insertAllLast(List.of());
+
+        assertTrue(created.isEmpty());
+        assertFalse(changed.get());
+        assertValues(signal, "existing");
+    }
+
+    @Test
+    void insertAllLast_singleNotification() {
+        ListSignal<String> signal = new ListSignal<>();
+
+        AtomicInteger changeCount = new AtomicInteger();
+        Usage usage = UsageTracker.track(signal::get);
+        usage.onNextChange(initial -> {
+            changeCount.incrementAndGet();
+            return true;
+        });
+
+        signal.insertAllLast(List.of("a", "b", "c"));
+
+        assertEquals(1, changeCount.get());
+    }
+
+    @Test
+    void insertAllFirst_multipleValues_valuesAtStart() {
+        ListSignal<String> signal = new ListSignal<>();
+        signal.insertLast("existing");
+
+        List<ValueSignal<String>> created = signal
+                .insertAllFirst(List.of("a", "b", "c"));
+
+        assertEquals(3, created.size());
+        assertValues(signal, "a", "b", "c", "existing");
+    }
+
+    @Test
+    void insertAllAt_validIndex_valuesInserted() {
+        ListSignal<String> signal = new ListSignal<>();
+        signal.insertLast("first");
+        signal.insertLast("last");
+
+        List<ValueSignal<String>> created = signal.insertAllAt(1,
+                List.of("a", "b"));
+
+        assertEquals(2, created.size());
+        assertValues(signal, "first", "a", "b", "last");
+    }
+
+    @Test
+    void insertAllAt_invalidIndex_throwsException() {
+        ListSignal<String> signal = new ListSignal<>();
+        signal.insertLast("existing");
+
+        assertThrows(IndexOutOfBoundsException.class,
+                () -> signal.insertAllAt(5, List.of("a")));
+        assertThrows(IndexOutOfBoundsException.class,
+                () -> signal.insertAllAt(-1, List.of("a")));
+    }
+
+    @Test
+    void insertAllLast_insideExplicitTransaction_throwsException() {
+        ListSignal<String> signal = new ListSignal<>();
+
+        assertThrows(IllegalStateException.class, () -> {
+            Transaction.runInTransaction(() -> {
+                signal.insertAllLast(List.of("a", "b"));
+            });
+        });
+    }
+
     private static void assertValues(ListSignal<String> signal,
             String... expectedValues) {
         List<String> values = signal.peek().stream().map(ValueSignal::peek)