docs(grid): Add Cell Selection documentation and revamp Selection articles

components/grid/columns/auto-generated.md

@@ -384,5 +384,5 @@ This example shows how to:
 ## See also
 * [Column Width]({%slug grid-columns-width%})
 * [Live Demo: Auto Generated Columns](https://demos.telerik.com/blazor-ui/grid/column-auto-generation)
-* [Selection]({%slug components/grid/selection/overview%})
+* [Selection]({%slug grid-selection-overview%})
 * [Paging]({%slug components/grid/features/paging%})

components/grid/columns/checkbox.md

@@ -12,7 +12,7 @@ position: 2
 
 This article describes the configuration parameters of the Blazor `GridCheckboxColumn`.
 
-The `GridCheckboxColumn` provides an additional way for users to [select Grid rows]({%slug components/grid/selection/overview%}). By default, users can select and unselect rows by clicking anywhere on them.
+The `GridCheckboxColumn` provides an additional way for users to [select Grid rows]({%slug grid-selection-overview%}). By default, users can select and unselect rows by clicking anywhere on them.
 
 If you need checkboxes to display or edit boolean values, then use a [Grid column template]({%slug grid-templates-column%}) instead.
 
@@ -25,7 +25,7 @@ The Grid checkbox column has the following exclusive parameters. For other avail
 | Parameter | Type and Default Value | Description |
 | --- | --- | --- |
 | `CheckBoxOnlySelection` | `bool` | Determines if row selection occurs only on checkbox clicks. By default, user can select rows by clicking anywhere, except on command buttons. |
-| `SelectAll` | `bool` <br /> (`true`) | Determines if the column header renders a checkbox to select all rows. Set this to `false` if the [Grid `SelectionMode` is `Single`]({%slug components/grid/selection/single%}). The `SelectAll` parameter has no effect when the checkbox column has a [`HeaderTemplate`](#headertemplate). |
+| `SelectAll` | `bool` <br /> (`true`) | Determines if the column header renders a checkbox to select all rows. Set this to `false` if the [Grid `SelectionMode` is `Single`]({%slug grid-selection-overview%}#use-single-or-multiple-selection). The `SelectAll` parameter has no effect when the checkbox column has a [`HeaderTemplate`](#headertemplate). |
 | `SelectAllMode` | `GridSelectAllMode` enum <br /> (`Current`) | Determines if the header cell checkbox selects all rows on the current page, or all rows in the Grid. `Current` selects the visible rows on the current page. `All` selects all the data items, including ones that may be currently filtered out. `All` requires the [Grid to be data-bound via its `Data` parameter, and not `OnRead`]({%slug common-features-data-binding-overview%}#how-to-provide-data). When using `OnRead`, the two `SelectAllMode`s behave identically, because the Grid controls only one page of items. |
 | `Title` | `string` | The text in the checkbox column's header. The title renders only when `SelectAll` is `false`. |
 
@@ -185,4 +185,4 @@ The example below doesn't take into account sorting, filtering and paging. If th
 ## See Also
 
 * [Live Demo: Grid Selection](https://demos.telerik.com/blazor-ui/grid/selection)
-* [Grid Selection Overview]({%slug components/grid/selection/overview%})
+* [Grid Selection Overview]({%slug grid-selection-overview%})

components/grid/editing/incell.md

@@ -209,7 +209,7 @@ Click a cell, edit it and click outside of the grid to see the change. You can a
 
 ## Incell Editing and Selection
 
-* To enable item selection with InCell Edit Mode, add a `<GridCheckboxColumn />` to the `<Columns>` collection. More information on that can be read in the [Selection]({%slug components/grid/selection/overview%}#notes) article.
+* To enable row selection with InCell Edit Mode, add a `<GridCheckboxColumn />` to the `<Columns>` collection. More information on that can be read in the [Row Selection]({%slug grid-selection-row%}#selection-and-editing-modes) article.
 
     * To see how to select the row that is being edited in InCell edit mode without using a `<GridCheckboxColumn />` check out the [Row Selection in Edit with InCell EditMode]({%slug grid-kb-row-select-incell-edit%}) Knowledge Base article.
 
@@ -238,4 +238,4 @@ The incell editor template requires a focusable element to maintain the tab orde
 ## See Also
 
 * [Live Demo: Grid InCell Editing](https://demos.telerik.com/blazor-ui/grid/editing-incell)
-* [Grid Selection Documentation]({%slug components/grid/selection/overview%})
+* [Grid Selection Documentation]({%slug grid-selection-overview%})

components/grid/events.md

@@ -29,6 +29,7 @@ This article explains the events available in the Telerik Grid for Blazor. They
 * [PageChanged](#pagechanged)
 * [PageSizeChanged](#pagesizechanged)
 * [SelectedItemsChanged](#selecteditemschanged)
+* [SelectedCellsChanged](#selectedcellschanged)
 
 ## CUD Events
 
@@ -1055,7 +1056,11 @@ Make sure to update the current page size when using the event.
 
 ## SelectedItemsChanged
 
-Fires when item selection is enabled and the user [selects or deselects one item]({%slug components/grid/selection/single%}#selecteditemschanged-event) or [multiple items]({%slug components/grid/selection/multiple%}#selecteditemschanged-event), depending on the [selection mode]({%slug components/grid/selection/overview%}).
+Fires when [row selection is enabled]({%slug grid-selection-overview%}#enable-row-or-cell-selection) and the user selects or deselects one row or multiple rows, depending on the [selection mode]({%slug grid-selection-overview%}#use-single-or-multiple-selection).
+
+## SelectedCellsChanged
+
+Fires when [cell selection is enabled]({%slug grid-selection-overview%}#enable-row-or-cell-selection) and the user selects or deselects one cell or multiple cells, depending on the [selection mode]({%slug grid-selection-overview%}#use-single-or-multiple-selection).
 
 ## See Also
 

components/grid/overview.md

@@ -144,13 +144,13 @@ The Grid supports custom content in various parts of the component such as data
 
 ## More Blazor Grid Features
 
-* [Selection]({%slug components/grid/selection/overview%}) - select one or multiple rows via clicks or checkboxes
-* [State]({%slug grid-state%}) - get or set the Grid configuration programmatically
-* [Toolbar]({%slug components/grid/features/toolbar%}) - define user actions in a toolbar above the header cells
-* [Hierarchy]({%slug components/grid/features/hierarchy%}) - nest Grids and visualize parent-child relations between data records
-* [Drag and drop rows]({%slug grid-drag-drop-overview%}) - move rows in a Grid or between different Grids
-* [Loading animation]({%slug grid-loading%}) - show a loading animation to improve user experience during long data operations
-* Scrolling - the Grid will show standard scrollbars automatically if the data does not fit the current component width and height.
+* [Selection]({%slug grid-selection-overview%})—select one or multiple rows through clicks or checkboxes or select one or multiple cells through clicks.
+* [State]({%slug grid-state%})—get or set the Grid configuration programmatically.
+* [Toolbar]({%slug components/grid/features/toolbar%})—define user actions in a toolbar above the header cells.
+* [Hierarchy]({%slug components/grid/features/hierarchy%})—nest Grids and visualize parent-child relations between data records.
+* [Drag and drop rows]({%slug grid-drag-drop-overview%})—move rows in a Grid or between different Grids.
+* [Loading animation]({%slug grid-loading%})—show a loading animation to improve user experience during long data operations.
+* Scrolling—the Grid will show standard scrollbars automatically if the data does not fit the current component width and height.
 
 
 ## Grid Parameters

components/grid/row-drag-drop.md

@@ -1691,7 +1691,7 @@ public class Resource
 
 ### Drag and Drop multiple Rows
 
-You can drag and drop multiple rows in one or between multiple instances of the Grid. To enable it, you should set the [`SelectionMode` parameter]({%slug components/grid/selection/overview%}) of the TelerikGrid to `GridSelectionMode.Multiple`. Then, if you drag a selected row, you will effectively drag all the selected rows.
+You can drag and drop multiple rows in one or between multiple instances of the Grid. To enable it, you should set the [`SelectionMode` parameter]({%slug grid-selection-overview%}) of the TelerikGrid to `GridSelectionMode.Multiple`. Then, if you drag a selected row, you will effectively drag all the selected rows.
 
 When you select multiple rows, the row drag clue will be `N items selected` where `N` is the number of selected rows.
 

components/grid/selection/cells.md

@@ -0,0 +1,240 @@
+---
+title: Cell Selection
+page_title: Grid - Cells Selection
+description: Learn how to select cell  in Blazor Grid component. Explore the selected cells. Discover cell selection bevahior when combined with other Grid features. Try the practical sample code for cell selection.
+slug: grid-selection-cell
+tags: telerik,blazor,grid,selection,cells
+position: 5
+---
+
+# Cell Selection
+
+The Grid component supports [single or multiple cell selection]({%slug grid-selection-overview%}#use-single-or-multiple-selection). You can select a cell with mouse click anywhere in the cell. You can access the collection of selected cells, use this collection and manipulate it. You can subscribe to selection events.
+
+## Basics
+
+To select a cell, click anywhere in it.
+
+To select a range of cells in one or more columns, hold the **Shift** key, while clicking on the first and last cell of the range. To select or deselect multiple cells that don't belong to a range, hold the **Ctrl** key.
+
+You can also select a cell range by holding and dragging the mouse cursor. The dragging motion defines the diagonal of a rectangle and the Grid will select the cells under this rectangle. To allow this kind of cell selection, set the `DragToSelect` parameter in [`GridSelectionSettings`]({%slug grid-selection-overview%}#enable-row-or-cell-selection). The **Shift** and **Ctrl** modifiers are not supported in drag-to-select mode.
+
+To enable cell selection:
+
+1. Set the Grid `SelectedCells` parameter to a collection of type `IEnumerable<GridSelectedCellDescriptor>`. The collection must be initialized in advance. See [`GridSelectedCellDescriptor`](#gridselectedcelldescriptor) for infomation about the object properties.
+1. Add a `<GridSelectionSettings>` tag to the `<GridSettings>` tag, and set the `SelectionType` parameter to the `GridSelectionType.Cell`.
+
+>caption Grid multiple cell selection
+
+````CSHTML
+<TelerikGrid Data="@GridData"
+             SelectionMode="@GridSelectionMode.Multiple"
+             @bind-SelectedCells="@SelectedCells"
+             Pageable="true">
+    <GridSettings>
+        <GridSelectionSettings SelectionType="@GridSelectionType.Cell" DragToSelect="true" />
+    </GridSettings>
+    <GridColumns>
+        <GridColumn Field="@nameof(Employee.Name)" />
+        <GridColumn Field="@nameof(Employee.Team)" />
+    </GridColumns>
+</TelerikGrid>
+
+<h3>Selected Cells:</h3>
+
+<ul>
+    @foreach (GridSelectedCellDescriptor cellDescriptor in SelectedCells)
+    {
+        <li>
+            Column <code>Field</code>: @cellDescriptor.ColumnField,
+            <code>EmployeeId</code>: @( ((Employee)cellDescriptor.DataItem).EmployeeId )
+        </li>
+    }
+</ul>
+
+@code {
+    private List<Employee> GridData { get; set; } = new();
+
+    private IEnumerable<GridSelectedCellDescriptor> SelectedCells { get; set; } = Enumerable.Empty<GridSelectedCellDescriptor>();
+
+    protected override void OnInitialized()
+    {
+        for (int i = 1; i <= 15; i++)
+        {
+            GridData.Add(new Employee()
+            {
+                EmployeeId = i,
+                Name = $"Employee {i}",
+                Team = $"Team {i % 3 + 1}"
+            });
+        }
+
+        SelectedCells = new List<GridSelectedCellDescriptor>() {
+            new GridSelectedCellDescriptor()
+            {
+                DataItem = GridData.ElementAt(2),
+                ColumnField = nameof(Employee.Name)
+            }
+        };
+    }
+
+    public class Employee
+    {
+        public int EmployeeId { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public string Team { get; set; } = string.Empty;
+    }
+}
+````
+
+## SelectedCellsChanged Event
+
+You can respond to user selection actions through the `SelectedCellsChanged` event. The event handler receives a collection of type `IEnumerable<GridSelectedCellDescriptor>`. The collection may have multiple, single, or no objects in it, depending on the `SelectionMode` and the last user selection.
+
+>caption Using the Grid SelectedCellsChanged event
+
+````CSHTML
+@* Select cells and handle the SelectedCellsChanged event *@
+
+<TelerikGrid Data="@GridData"
+             SelectionMode="@GridSelectionMode.Multiple"
+             SelectedCells="@SelectedCells"
+             SelectedCellsChanged="@( (IEnumerable<GridSelectedCellDescriptor> newSelected) => OnCellSelect(newSelected) )"
+             Pageable="true">
+    <GridSettings>
+        <GridSelectionSettings SelectionType="@GridSelectionType.Cell" DragToSelect="true" />
+    </GridSettings>
+    <GridColumns>
+        <GridColumn Field="@nameof(Employee.Name)" />
+        <GridColumn Field="@nameof(Employee.Team)" />
+    </GridColumns>
+</TelerikGrid>
+
+<p><code>SelectedItemsChanged</code> fired at: @SelectedCellsChangedLog</p>
+
+<h3>Selected Cells:</h3>
+
+<ul>
+    @foreach (GridSelectedCellDescriptor cellDescriptor in SelectedCells)
+    {
+        <li>
+            Column <code>Field</code>: @cellDescriptor.ColumnField,
+            <code>EmployeeId</code>: @( ((Employee)cellDescriptor.DataItem).EmployeeId )
+        </li>
+    }
+</ul>
+
+@code {
+    private List<Employee> GridData { get; set; } = new();
+
+    private IEnumerable<GridSelectedCellDescriptor> SelectedCells { get; set; } = Enumerable.Empty<GridSelectedCellDescriptor>();
+
+    private string SelectedCellsChangedLog { get; set; } = string.Empty;
+
+    protected void OnCellSelect(IEnumerable<GridSelectedCellDescriptor> cellDescriptors)
+    {
+        // Update the SelectedCells collection manually.
+        // When using two-way binding, this happens automatically.
+        SelectedCells = cellDescriptors;
+
+        SelectedCellsChangedLog = DateTime.Now.ToLongTimeString();
+    }
+
+    protected override void OnInitialized()
+    {
+        for (int i = 1; i <= 15; i++)
+        {
+            GridData.Add(new Employee()
+            {
+                EmployeeId = i,
+                Name = $"Employee {i}",
+                Team = $"Team {i % 3 + 1}"
+            });
+        }
+
+        SelectedCells = new List<GridSelectedCellDescriptor>() {
+            new GridSelectedCellDescriptor()
+            {
+                DataItem = GridData.ElementAt(2),
+                ColumnField = nameof(Employee.Name)
+            }
+        };
+    }
+
+    public class Employee
+    {
+        public int EmployeeId { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public string Team { get; set; } = string.Empty;
+    }
+}
+````
+
+### SelectedCellsChanged and Asynchronous Operations
+
+The `SelectedCellsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) event instead.
+
+## GridSelectedCellDescriptor
+
+The `GridSelectedCellDescriptor` type exposes the following properties:
+
+@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
+
+| Property Name | Type | Description |
+| --- | --- | --- |
+| `ColumnField` | `string` | The value of the [Grid column `Field`]({%slug components/grid/columns/bound%}#data-binding) parameter, if set. |
+| `ColumnId` | `string` | The value of the [Grid column `Id`]({%slug components/grid/columns/bound%}#identification) parameter, if set. |
+| `DataItem` | `object` | The Grid data item instance. Cast it to the actual Grid model type before use. |
+
+## Selection When Data Changes
+
+When the Grid `Data` collection changes, the `SelectedCells` collection has the following behavior:
+
+* When the user updates a selected cell and the item instance is replaced, you have to also replace the `SelectedCellDescriptor.DataItem` object in the `SelectedCells` collection. Do that in the [Grid `OnUpdate` event]({%slug components/grid/editing/overview%}#events).
+* When the user deletes a row with selected cells, update the `SelectedCells` collection in the the Grid `OnDelete` event handler.
+* To select cells from a new item in the Grid you can use the [`OnCreate` event]({%slug components/grid/editing/overview%}#events) to update the `SelectedCells` collection.
+
+### Equals Comparison
+
+The items in `SelectedCells` are compared against the items in the Grid data in order to determine which cells will be highlighted. The default framework behavior is to compare objects by reference. The data item references may not match when:
+
+* The Grid is databound through its `OnRead` event and each data request returns different data item instances.
+* The `SelectedCells` are obtained from a different data source than the all Grid items, for example, from a separate service.
+
+In such cases, the selected cells may not appear as expected. You have to [override the `Equals` method of the Grid model class]({%slug grid-state%}#equals-comparison) so that the items are compared by a unique identifier rather than by reference. When you override `Equals`, it is also recommended to override the [`GetHashCode`](https://docs.microsoft.com/en-us/dotnet/api/system.object.gethashcode) method.
+
+## Cell Selection and Other Grid Features
+
+The selection feature behavior may vary when the Grid configuration combines cell selection and other Grid features, such as editing, virtualization, paging, templates. In such cases you need to consider certain limitation or include some modications.
+
+### Selection and Editing Modes
+
+When you want to edit a Grid item, the cell selection has the following behavior:
+
+* Cell selection is not supported with [`Incell` edit mode]({%slug components/grid/editing/incell%}) due to the overlapping pointer events that trigger selection and editing. If both features are enabled, only the editing will work.
+* [`Inline` edit mode]({%slug components/grid/editing/inline%}) and [`Popup` edit mode]({%slug components/grid/editing/popup%}) integrate with cell selection without limitations.
+
+### Selection and Virtual Scrolling
+
+When the Grid has [virtual scrolling]({%slug components/grid/virtual-scrolling%}), the component is able to select a range of cells with **Shift** only if all rows in that range are currently rendered. Consider the following scenario:
+
+1. Select a cell.
+1. Scroll down, so that virtualization kicks in and the rendered rows are no longer the same.
+1. Select another cell with **Shift**.
+
+In this case, the range selection will start from the first row that is currently rendered. Compare with [Selection and paging](#selection-and-paging) below.
+
+### Selection and Paging
+
+The `SelectedCells` collection persists across paging.
+
+### Selection and Templates
+
+When using [Grid templates]({%slug components/grid/features/templates%}) with cell selection:
+
+* If you are using a [Grid column template]({%slug grid-templates-column%}) and you have a clickable element in the template, wrap this element in a container with a `@onclick:stopPropagation` directive. You can check the knowledge base article on [how to prevent row selection when the user clicks another component in the Grid column template]({%slug grid-kb-row-selection-in-column-template%}). It applies for both row and cell selection.
+* If you are using a [row template]({%slug components/grid/features/templates%}#row-template) the Grid does not support cell selection. The row template removes the built-in cell instances and the HTML markup may not even include the expected number of cells.
+
+## See Also
+
+* [Live Demo: Grid Cell Selection](https://demos.telerik.com/blazor-ui/grid/cell-selection)