From 3d8ac863b5ea35ec99f24b32e73119ab16e60e37 Mon Sep 17 00:00:00 2001
From: Robert Haken <haken@havit.cz>
Date: Wed, 27 Nov 2024 10:08:07 +0100
Subject: [PATCH] [HxGrid] Doc - When using Multiselect & Pagination, the
 selection is removed when navigating to other page. (#576) - data identity
 explanation

---
 .../HxGridDoc/HxGrid_Documentation.razor      | 29 +++++++++++++++----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/Havit.Blazor.Documentation/Pages/Components/HxGridDoc/HxGrid_Documentation.razor b/Havit.Blazor.Documentation/Pages/Components/HxGridDoc/HxGrid_Documentation.razor
index 8ac28d5b..6a629dda 100644
--- a/Havit.Blazor.Documentation/Pages/Components/HxGridDoc/HxGrid_Documentation.razor
+++ b/Havit.Blazor.Documentation/Pages/Components/HxGridDoc/HxGrid_Documentation.razor
@@ -31,11 +31,11 @@
 
 		<DocHeading Title="Asynchronous data" Id="ApplyToAsync" Level="3" />
 		<p>
-            When loading data asynchronously, always ensure that the <code>DataProvider</code> waits for the data to be available;
-            otherwise, the skeleton UI (placeholders) will not display correctly.<br />
-            If you are preloading data and using the <code>request.ApplyTo(data)</code> extension method,
-            you can leverage <code>TaskCompletionSource</code> to handle waiting until the data is loaded.
-            </p>
+			When loading data asynchronously, always ensure that the <code>DataProvider</code> waits for the data to be available;
+			otherwise, the skeleton UI (placeholders) will not display correctly.<br />
+			If you are preloading data and using the <code>request.ApplyTo(data)</code> extension method,
+			you can leverage <code>TaskCompletionSource</code> to handle waiting until the data is loaded.
+		</p>
 		<Demo Type="typeof(HxGrid_Demo_ApplyTo_Async)" />
 
 		<DocHeading Title="Using IQueryable" Id="IQueryable" Level="3" />
@@ -133,6 +133,25 @@
 			The "select/deselect all" checkbox operates only on visible records and adds/removes them from the selection accordingly.
 			Non-visible items (e.g., from other pages) are not affected by this operation.
 		</p>
+		<DocAlert Type="DocAlertType.Warning">
+			If you encounter a situation where selected items are present in <code>@nameof(HxGrid<TItem>.SelectedDataItems)</code>,
+			but their corresponding checkboxes are not marked in the UI after paging or other navigation,
+			it is likely due to issues with data identity.
+		</DocAlert>
+		<p>
+			By default, equality in C# for <code>class</code> instances relies on reference equality,
+			meaning two instances with identical data are not considered equal unless they are the same reference.
+		</p>
+		To address this:
+		<ul>
+			<li>Override <code>Equals</code>: Implement a custom equality logic for your data items (e.g., compare by <code>Id</code> or other key properties).</li>
+			<li>Use a <code>record</code>: For data items defined as <code>record</code>, equality is automatically generated by the compiler based on all properties.</li>
+		</ul>
+		<p>
+			This issue typically arises when the grid's <code>DataProvider</code> returns new instances for the same rows during subsequent requests.
+			Since these new instances are not equal to the previously selected ones (based on reference equality),
+			their corresponding rows are not marked as selected in the UI.
+		</p>
 		<DocAlert>
 			When using <code>@nameof(GridContentNavigationMode.InfiniteScroll)</code>, <code>@nameof(HxGrid<TItem>.PreserveSelection)="true"</code> is required for multi-row selection to work.
 			Attempting to use <code>@nameof(HxGrid<TItem>.MultiSelectionEnabled)="true"</code> without enabling <code>PreserveSelection</code> will result in an exception. Additionally, the "select/deselect all" checkbox is intentionally hidden in this mode,