docs(ListState): Add Tutorials about Binding ListState to ListView and Updating specific Items

Author: DevTKSS

README.md

@@ -49,7 +49,7 @@ The [Mvux Gallery](https://github.com/DevTKSS/DevTKSS.Uno.SampleApps/tree/master
 
 #### Featured Controls
 
-- **FeedView** combined with GridView and ListView
+- **FeedView** combined with **GridView** and **ListView**
 - **DataTemplate** centralized resource definitions
 - **Card**, **Grid**, **NavigationView**
 - **ItemOverlayTemplate** (replicated from WinUI 3 Gallery)
@@ -99,8 +99,15 @@ A complete tutorial application demonstrating navigation patterns with MVUX and
 
 A basic application demonstrating selection and display of member names in a `ListView` bound to a `ListState<string>` in the Model using MVUX.
 
+**Tutorial Documentation available:**
+
+- **MVUX State Management Tutorials** - Learn how to use `ListState` and `ListFeed` alongside with `ListView` and `Button.Command`-Binding (🇩🇪 [German](https://devtkss.github.io/DevTKSS.Uno.SampleApps/articles/de/Mvux-StateManagement/Overview-de.html) | 🇬🇧 [English](https://devtkss.github.io/DevTKSS.Uno.SampleApps/articles/en/Mvux-StateManagement/HowTo-Binding-ListState-and-ListFeed-de.md))
+
+**Video Tutorials available:**
+
 - **[Video Tutorial - How To: Binden von ListState und ImmutableList zu FeedView & ListView im UI | Uno Community Tutorial](https://youtu.be/wOsSlv1YFic)** - Step-by-step guide (🇩🇪 German)
-- **[Source Code](https://github.com/DevTKSS/DevTKSS.Uno.SampleApps/tree/master/src/DevTKSS.Uno.SimpleMemberSelectionApp/)**
+- **[Video Tutorial Series](https://youtube.com/playlist?list=PLEL6kb4Bivm_g81iKBl-f0eYPNr5h2dFX)** - Complete walkthrough (🇩🇪 German with English subtitles)
+- **[Source Code](https://github.com/DevTKSS/DevTKSS.Uno.SampleApps/tree/master/src/DevTKSS.Uno.XamlNavigationApp-1/)** - Browse the implementation
 
 ---
 

docs/articles/.attachments/Binding-ListState-FeedView.png

@@ -0,0 +1,143 @@
+---
+uid: DevTKSS.Uno.MvuxStateManagement.ListState.Selection.de
+---
+# Anleitung: Binding von ListState mit Selection
+
+## Überblick
+
+In diesem Beispiel zeigen wir dir, wie du ein `ListState` aus deinem Model an eine `ListView` bindest und wie du die Auswahl eines Elements verfolgst. Wir erstellen eine einfache Mitgliederlisten-Anzeige, bei der du:
+
+- Eine Liste von Mitgliedern in einer `ListView` anzeigen kannst
+- Ein Mitglied aus der `ListView` auswählen kannst
+- Das ausgewählte Mitglied oben auf der Seite angezeigt bekommst
+
+Dieses Beispiel zeigt die Grundlagen des `.Selection(...)`-Operators, der sowohl mit `IListState<T>` als auch mit `IListFeed<T>` funktioniert.
+
+## Voraussetzungen
+
+Bevor du mit diesem Tutorial beginnst, stelle sicher, dass du:
+
+- [Anleitung: Erstellen einer Uno Platform App](xref:DevTKSS.Uno.Setup.HowTo-CreateNewUnoApp.de) abgeschlossen hast
+- [Anleitung: Hinzufügen neuer Pages](xref:DevTKSS.Uno.Setup.HowTo-AddingNewPages.de) abgeschlossen hast
+- [Anleitung: Hinzufügen neuer MVUX Model-Klassen](xref:DevTKSS.Uno.Setup.HowTo-AddingNew-VM-Class-Record.de) abgeschlossen hast
+- Grundlegendes Verständnis von Dependency Injection aus [Anleitung: Verwendung von DI im Constructor](xref:DevTKSS.Uno.Setup.Using-DI-in-ctor.de) hast
+
+## Visuelle Referenz
+
+![Mitgliederlisten UI mit Selection](../../.attachments/Binding-ListState-FeedView.png)
+
+## Das Model Setup
+
+Zunächst definieren wir die States, die für die Anzeige und Auswahl benötigt werden.
+
+### Initialisierung von ListState
+
+Es gibt zwei gängige Möglichkeiten, den `ListState<T>` zu initialisieren:
+
+#### [Verwendung von `ListState.Async(...)`](#tab/Async)
+
+Mit der `ListState<string>.Async(...)`-Methode kannst du eine asynchrone Methode bereitstellen, die einmal aufgerufen wird, um die anfängliche Liste der Mitglieder zu erhalten. Dies ist nützlich, wenn du Daten asynchron aus einer API oder Datenbank laden musst.
+
+```csharp
+private readonly IImmutableList<string> _listMembers = ImmutableList.Create(
+    [
+        "Hans",
+        "Lisa",
+        "Anke",
+        "Tom"
+    ]);
+
+private async ValueTask<IImmutableList<string>> GetMembersAsync(CancellationToken ct)
+    => _listMembers;
+
+public IListState<string> Members => ListState<string>.Async(this, GetMembersAsync)
+                                                      .Selection(SelectedMember);
+
+public IState<string> SelectedMember => State<string>.Value(this, () => string.Empty);
+```
+
+Die Schlüsselelemente in diesem Code:
+
+- `_listMembers` - Eine statische unveränderliche Liste, die unsere Mitgliedernamen enthält
+- `GetMembersAsync(...)` - Asynchrone Methode, die die Liste zurückgibt (obwohl es sich um statische Daten handelt)
+- `Members` - `IListState<string>` initialisiert über `Async(...)` mit `.Selection(...)`-Operator
+- `SelectedMember` - `IState<string>`, das das aktuell ausgewählte Mitglied verfolgt
+
+**Hinweis:** Obwohl dieser Ansatz funktioniert, erfordert er erheblichen Boilerplate-Code (Feld + asynchrone Methode + ListState-Property), selbst für statische Daten, die eigentlich kein asynchrones Laden benötigen.
+
+#### [Verwendung von `ListState.Value(...)`](#tab/Value)
+
+Mit der `ListState<string>.Value(...)`-Methode kannst du eine statische Liste von Mitgliedern direkt in einer einzigen Zeile bereitstellen. Dieser Ansatz reduziert den Boilerplate drastisch und eignet sich perfekt für Demonstrationszwecke oder beim Umgang mit statischen Daten.
+
+```csharp
+public IListState<string> Members => ListState<string>.Value(this,
+     () => ImmutableList.Create(
+        [
+            "Hans",
+            "Lisa",
+            "Anke",
+            "Tom"
+        ])
+    ).Selection(SelectedMember);
+
+public IState<string> SelectedMember => State<string>.Value(this, () => string.Empty);
+```
+
+**Vorteile gegenüber dem Async-Ansatz:**
+
+- **90% weniger Code** - Kein separates Feld oder asynchrone Methode erforderlich
+- **Mehrzeilige Definition** - Klarer, lesbarer Property-Ausdruck mit ordnungsgemäßer Formatierung
+- **Sofortige Klarheit** - Du kannst die Daten direkt dort sehen, wo sie definiert sind
+- **Gleiche Funktionalität** - Erhält trotzdem den `.Selection(...)`-Operator und alle ListState-Features
+- **Ideal für statische Daten** - Kein unnötiger asynchroner Overhead für bereits verfügbare Daten
+
+> [!TIP]
+> **Wann Value vs Async verwenden:**
+>
+> - **Verwende `.Value(...)`**, wenn deine Daten statisch sind, aus Konstanten stammen oder synchron berechnet werden
+> - **Verwende `.Async(...)`**, wenn du tatsächlich Daten aus einer API, Datenbank abrufen oder asynchrone Operationen durchführen musst
+
+***
+
+## Die View (XAML)
+
+Nachdem wir nun unser Model mit den erforderlichen States eingerichtet haben, erstellen wir die UI. Unsere UI besteht aus einem `TextBlock`, der das ausgewählte Mitglied anzeigt, und einer `ListView` zur Anzeige aller Mitglieder:
+
+```xaml
+<StackPanel Spacing="16">
+    <!-- Display selected member -->
+    <TextBlock
+        Text="{Binding Path=SelectedMember, Mode=OneWay}"
+        FontSize="24"
+        FontWeight="Bold"/>
+
+    <!-- List of all members -->
+    <ListView
+        ItemsSource="{Binding Path=Members}"
+        SelectionMode="Single"
+        Height="300"/>
+</StackPanel>
+```
+
+> [!WARNING]
+> Wenn du das `ListView`-Control verwendest, stelle sicher, dass du die `ItemClickCommand`-Eigenschaft der `ListView` **nicht** gleichzeitig mit dem `.Selection(...)`-Operator des `ListState` setzt, da dies das Auswahlverhalten beeinträchtigt und den State, den du zur Widerspiegelung der aktuellen Auswahl verwendest, nicht wie erwartet aktualisiert. Du musst dich für eine der beiden Optionen entscheiden.
+
+Beachte die wichtigsten Bindings:
+
+- `ItemsSource="{Binding Path=Members}"` - bindet an unser `IListState<string>`
+- `Text="{Binding Path=SelectedMember, Mode=OneWay}"` - zeigt das ausgewählte Mitglied an
+
+## Zusammenfassung
+
+Dieses Beispiel demonstriert:
+
+1. Binding von `IListState<T>` an eine `ListView` mit `.Selection(...)`-Operator (funktioniert auch mit `IListFeed<T>`)
+2. Verwendung eines separaten `IState<string>` zur Verfolgung der Auswahl
+3. Anzeige des ausgewählten Elements in der UI
+4. Zwei Initialisierungsmethoden: `.Async(...)` für echte asynchrone Daten vs `.Value(...)` für statische Daten
+
+- [Link zum Source Code](../../../../src/DevTKSS.Uno.XamlNavigationApp-1/Presentation/DashboardModel.cs)
+
+Im nächsten Tutorial lernst du, wie du die ausgewählten Elemente bearbeiten und aktualisieren kannst.
+
+- [Nächstes Tutorial: Aktualisierung von ListState Items](xref:DevTKSS.Uno.MvuxStateManagement.ListState.UpdateItems.de)]

docs/articles/.attachments/DevTKSS.Uno.XamlNavigationApp.png

@@ -0,0 +1,55 @@
+---
+uid: DevTKSS.Uno.Mvux-StateManagement.Overview.de
+---
+# Übersicht: Mvux State Management
+
+## Einführung
+
+In dieser Tutorial-Serie lernst du, wie du `ListState` und `ListFeed` in deinen Uno Platform MVUX-Apps verwendest. Diese Komponenten ermöglichen dir die reaktive Verwaltung von Listen-Daten mit automatischer UI-Aktualisierung.
+
+## Was ist der Unterschied zwischen ListFeed und ListState?
+
+- **`IListFeed<T>`** - Schreibgeschützte read-only Daten-Sammlungen (z.B. Server-Antworten)
+  - Unterstützt `RequestRefreshAsync` oder `RefreshAsync` und den `.Selection(...)` Operator
+  - Kein Support für `ForEach`-Callbacks oder direkte Item-Updates via bspw. `UpdateAllAsync(...)`
+
+- **`IListState<T>`** - read-write Daten-Sammlungen
+  - Ermöglicht direkte Aktualisierung und Key-matching Updates von Elementen mit `UpdateAllAsync(...)` oder `UpdateItemAsync(...)`
+  - Unterstützt `ForEach`-Callbacks für die Verarbeitung von Elementen
+  - Unterstützt `AddAsync`/`RemoveAsync`-Operationen
+  - Ebenfalls kompatibel mit dem `.Selection(...)` Operator
+
+## Tutorial-Serie
+
+Diese Serie besteht aus zwei aufeinander aufbauenden Tutorials:
+
+### 1. [Binding von ListState mit Selection](xref:DevTKSS.Uno.MvuxStateManagement.ListState-Selection.de)
+
+In diesem ersten Tutorial lernst du die Grundlagen:
+
+- Wie du ein `ListState` an eine `ListView` bindest
+- Wie du den `.Selection(...)` Operator verwendest
+- Wie du das ausgewählte Element in der UI anzeigst
+- Unterschiede zwischen `.Async(...)` und `.Value(...)` Initialisierung
+
+### 2. [Aktualisierung von ListState Items](xref:DevTKSS.Uno.MvuxStateManagement.Update-ListStateItems.de)
+
+Im zweiten Tutorial erweitern wir die Funktionalität:
+
+- Wie du Elemente in einem `ListState` bearbeitest
+- Verwendung von `UpdateAllAsync(...)` mit Filterkriterien
+- Einsatz von `[FeedParameter]` für saubereres State-Handling
+- Warum `IListState<T>` für Aktualisierungen erforderlich ist
+
+## Voraussetzungen
+
+Bevor du mit diesen Tutorials beginnst, stelle sicher, dass du:
+
+- [Anleitung: Erstellen einer Uno Platform App](xref:DevTKSS.Uno.Setup.HowTo-CreateNewUnoApp.de) abgeschlossen hast
+- [Anleitung: Hinzufügen neuer Pages](xref:DevTKSS.Uno.Setup.HowTo-AddingNewPages.de) abgeschlossen hast
+- [Anleitung: Hinzufügen neuer MVUX Model-Klassen](xref:DevTKSS.Uno.Setup.HowTo-AddingNew-VM-Class-Record.de) abgeschlossen hast
+- Grundlegendes Verständnis von Dependency Injection aus [Anleitung: Verwendung von DI im Constructor](xref:DevTKSS.Uno.Setup.Using-DI-in-ctor.de) hast
+
+## Los geht's
+
+Beginne mit dem ersten Tutorial: [Binding von ListState mit Selection](xref:DevTKSS.Uno.MvuxStateManagement.ListState-Selection.de)

docs/articles/.attachments/MvuxListApp-ListState-UpdateAllAsync.gif

@@ -0,0 +1,161 @@
+---
+uid: DevTKSS.Uno.MvuxStateManagement.ListState.UpdateItems.de
+---
+# Anleitung: Aktualisierung von ListState Items
+
+## Überblick
+
+In diesem Tutorial erweitern wir das vorherige Beispiel und fügen die Möglichkeit hinzu, Elemente in einem `ListState` zu bearbeiten. Du wirst lernen:
+
+- Wie du einen zusätzlichen State für Benutzereingaben erstellst
+- Wie du `UpdateAllAsync(...)` verwendest, um Elemente zu aktualisieren
+- Wie du `[FeedParameter]` für saubereres State-Handling nutzt
+- Warum wir `IListState<T>` anstelle von `IListFeed<T>` für Aktualisierungen benötigen
+
+Dieses Szenario zeigt, warum wir `ListState` anstelle von `ListFeed` benötigen: Während `ListFeed` nur `RequestRefresh` oder `Refresh` Aktionen unterstützt (die einen neuen API-/Service-Aufruf erfordern), ermöglicht `ListState` die direkte Aktualisierung von Elementen in der Liste mithilfe von Filterkriterien.
+
+## Voraussetzungen
+
+Bevor du mit diesem Tutorial beginnst, stelle sicher, dass du:
+
+- [Anleitung: Binding von ListState mit Selection](xref:DevTKSS.Uno.MvuxStateManagement.ListState-Selection.de) abgeschlossen hast
+- Das vorherige Tutorial mit der grundlegenden ListState-Bindung verstanden hast
+
+## Visuelle Referenz
+
+![Mitgliederlisten-Editor mit Update-Funktion](../../.attachments/MvuxListApp-ListState-UpdateAllAsync.gif)
+
+## Erweiterung des Models
+
+Wir erweitern unser bestehendes Model um einen zusätzlichen State für die Bearbeitung und eine Methode zum Aktualisieren:
+
+### Zusätzlicher State für die Bearbeitung
+
+Wir benötigen einen State, um den geänderten Mitgliedernamen zu halten, den du eingibst:
+
+```csharp
+public IState<string> ModifiedMemberName => State<string>.Empty(this);
+```
+
+Dieser State ist bidirektional an die `TextBox` gebunden und erfasst deine Eingabe.
+
+### Vollständiges Model
+
+So sieht dein vollständiges Model aus:
+
+```csharp
+public partial record MainModel
+{
+    public IListState<string> Members => ListState<string>.Value(this,
+         () => ImmutableList.Create(
+            [
+                "Hans",
+                "Lisa",
+                "Anke",
+                "Tom"
+            ])
+        ).Selection(SelectedMember);
+
+    public IState<string> SelectedMember => State<string>.Value(this, () => string.Empty);
+    
+    public IState<string> ModifiedMemberName => State<string>.Empty(this);
+}
+```
+
+## Erweiterte View (XAML)
+
+Jetzt fügen wir die Bearbeitungselemente zur UI hinzu:
+
+[!code-xaml[](../../../../src/DevTKSS.Uno.MvuxListApp/Presentation/MainPage.xaml#MembersView?highlight=18,23,27,30)]
+
+Die neuen Bindings:
+
+- `Text="{Binding Path=ModifiedMemberName, Mode=TwoWay}"` - bidirektionales Binding für die Bearbeitung
+- `Command="{Binding Path=RenameMemberAsync}"` - löst die Umbenennungsoperation aus
+
+## Implementierung des Rename-Befehls
+
+> [!NOTE]
+> Wir verwenden einen schaltflächengesteuerten Befehl anstelle eines `.ForEach(...)`-Callbacks, um dir die explizite Kontrolle darüber zu geben, wann die Umbenennung erfolgt. Dies verhindert unbeabsichtigte Änderungen, wenn du:
+>
+> - Das falsche Mitglied ausgewählt hast
+> - Noch die korrekte Schreibweise nachschlägst
+> - Deine Meinung über die Umbenennung änderst
+
+Hier ist die Befehlsimplementierung:
+
+```csharp
+public async ValueTask RenameMemberAsync(
+    [FeedParameter(nameof(ModifiedMemberName))] string? modName,
+    [FeedParameter(nameof(SelectedMember))] string? replaceMember,
+    CancellationToken ct)
+{
+    if (string.IsNullOrWhiteSpace(modName))
+        return;
+
+    await Members.UpdateAllAsync(
+        match: item => item == replaceMember,
+        updater: _ => modName,
+        ct: ct
+    );
+
+    await Members.TrySelectAsync(modName, ct);
+}
+```
+
+Wichtige Punkte:
+
+- **`UpdateAllAsync(...)`** - Aktualisiert Elemente im `ListState`, die den Filterkriterien entsprechen
+- **`match: item => item == replaceMember`** - Findet das aktuell ausgewählte Mitglied
+- **`updater: _ => modName`** - Ersetzt es durch den neuen Namen
+- **`TrySelectAsync(...)`** - Wählt das Mitglied erneut anhand seines neuen Namens aus
+
+## Verwendung des FeedParameter-Attributs
+
+Beachte die `[FeedParameter]`-Attribute auf den Methodenparametern. Diese leistungsstarke Funktion wartet automatisch auf State-Werte und bindet sie an deine Methodenparameter, wodurch manuelle `await`-Aufrufe eliminiert werden:
+
+```csharp
+[FeedParameter(nameof(ModifiedMemberName))] string? modName,
+[FeedParameter(nameof(SelectedMember))] string? replaceMember
+```
+
+> [!TIP]
+> **Vorteile:**
+>
+> - Kein manuelles `await` der States innerhalb der Methode erforderlich
+> - Parameter können andere Namen als die ursprünglichen States haben (verbessert die Lesbarkeit)
+> - Sauberere, fokussiertere Methodenimplementierung
+
+**Alternative:** Verwende `[ImplicitFeedParameter]` auf Klassenebene, um alle Parameter automatisch zu binden, indem Namen exakt mit deinen States übereinstimmen:
+
+```csharp
+[ImplicitFeedParameter]
+public partial record MainModel
+{
+    ...
+
+    public async ValueTask RenameMemberAsync(
+        string? ModifiedMemberName,
+        string? SelectedMember,
+        CancellationToken ct)
+    { ... }
+}
+```
+
+Mit `[ImplicitFeedParameter]` auf der Klasse werden alle Methodenparameter automatisch gebunden, indem ihre Namen exakt mit deinen State-Property-Namen übereinstimmen. Das bedeutet:
+
+- Der Parameter `ModifiedMemberName` bindet automatisch an den `ModifiedMemberName`-State
+- Der Parameter `SelectedMember` bindet automatisch an den `SelectedMember`-State
+- Keine individuellen `[FeedParameter]`-Attribute für jeden Parameter erforderlich
+- Parameternamen müssen exakt mit State-Namen übereinstimmen (Groß-/Kleinschreibung beachten)
+
+## Zusammenfassung
+
+Dieses Beispiel demonstriert:
+
+1. Verwendung von bidirektionalem Binding für Benutzereingaben über `IState<string>`
+2. Aktualisierung von Listenelementen mit `UpdateAllAsync(...)` - nur verfügbar bei `IListState<T>` (nicht `IListFeed<T>`)
+3. Befehlsbasierte Aktualisierungen für explizite Benutzerkontrolle
+4. Nutzung von `[FeedParameter]` für saubereres asynchrones State-Handling
+
+Dieses Muster gewährleistet Datenkonsistenz und gibt dir die volle Kontrolle darüber, wann Änderungen in den Daten erfolgen und wann auch nicht.

docs/articles/de/Mvux-StateManagement/HowTo-Binding-ListState-Selection-de.md

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/dotnet/docfx/main/schemas/toc.schema.json
+- name: Übersicht: ListState und ListFeed
+  uid: DevTKSS.Uno.Mvux-StateManagement.Overview.de
+  href: HowTo-Binding-ListState-and-ListFeed-de.md
+- name: Binding von ListState mit Selection
+  uid: DevTKSS.Uno.MvuxStateManagement.ListState.Selection.de
+  href: HowTo-Binding-ListState-Selection-de.md
+- name: Aktualisierung von ListState Items
+  uid: DevTKSS.Uno.MvuxStateManagement.ListState.UpdateItems.de
+  href: HowTo-Update-ListState-Items-de.md