feat: Add row numbering to the row header area

docs/docs/row-headers.md

@@ -40,7 +40,7 @@ Provide a `DataTemplate` via [`RowHeaderTemplate`](xref:WinUI.TableView.TableVie
 
 ![Custom row header with icon](../images/row-headers-custom.png)
 
-> **Note:** The `Tag` of the `TableViewRowHeader` is set to the row's 1-based index. Bind to it with `{Binding Tag, RelativeSource={RelativeSource Mode=TemplatedParent}}` for row numbers.
+> **Note:** The `Tag` of the `TableViewRowHeader` is always set to the row's number (see [Row numbering](#row-numbering) below), whether or not a custom `RowHeaderTemplate` is set. Bind to it with `{Binding Tag, RelativeSource={RelativeSource Mode=TemplatedParent}}` to incorporate the number into a custom template.
 
 ### Selecting a template per row
 
@@ -71,6 +71,25 @@ public class StatusHeaderSelector : DataTemplateSelector
 </tv:TableView>
 ```
 
+## Row numbering
+
+Set [`ShowRowNumbers`](xref:WinUI.TableView.TableView.ShowRowNumbers) to `true` to display each row's number at the very start of the row, in its own column ahead of the row header content and the row details expander toggle:
+
+```xml
+<tv:TableView ItemsSource="{x:Bind Products}" ShowRowNumbers="True" />
+```
+
+The row number is a real, stable position among all rows - it does not renumber when a [group](grouping.md) is collapsed and hides other rows, unlike a naively counted display position. It coexists with `RowHeaderTemplate`, `RowHeaderTemplateSelector`, and the row details expander toggle without taking space from any of them.
+
+Customize its appearance with these theme resources:
+
+| Resource | Type | Description |
+|---|---|---|
+| `TableViewRowNumberFontSize` | `double` | Font size of the row number text |
+| `TableViewRowNumberForeground` | `Brush` | Foreground brush of the row number text |
+| `TableViewRowNumberMargin` | `Thickness` | Margin around the row number text |
+| `TableViewRowNumberMinWidth` | `double` | Minimum width of the row number column |
+
 ## Sizing the row header
 
 | Property | Default | Description |

samples/WinUI.TableView.SampleApp/Pages/GroupingPage.xaml

@@ -12,7 +12,7 @@
 
     <Grid>
         <controls:SamplePresenter Header="Grouping"
-                                  Description="Group a column via its options button (try Department or Gender), then use the buttons to add, insert, move, and delete items - a way to check those operations keep group headers, counts, and order correct. Groups sort by key by default; toggle 'Sort Groups by Count' below (or the same option in a grouped column's own flyout) to show the biggest group first instead.">
+                                  Description="Group a column via its options button (try Department or Gender), then use the buttons to add, insert, move, and delete items - a way to check those operations keep group headers, counts, and order correct. Groups sort by key by default; toggle 'Sort Groups by Count' below (or the same option in a grouped column's own flyout) to show the biggest group first instead. Turn on ShowRowNumbers and collapse a group to see row numbers stay real instead of renumbering the rows still visible.">
             <controls:SamplePresenter.Example>
                 <tv:TableView x:Name="tableView"
                               ItemsSource="{Binding Items}"
@@ -93,6 +93,10 @@
                                   OnContent="True"
                                   OffContent="False"
                                   IsOn="{Binding ShowGroupExpandCollapseButton, Mode=TwoWay, ElementName=tableView}" />
+                    <ToggleSwitch Header="ShowRowNumbers"
+                                  OnContent="True"
+                                  OffContent="False"
+                                  IsOn="{Binding ShowRowNumbers, Mode=TwoWay, ElementName=tableView}" />
                     <ToggleSwitch Header="AreStickyGroupHeadersEnabled"
                                   OnContent="True"
                                   OffContent="False"

samples/WinUI.TableView.SampleApp/Pages/OverviewPage.xaml

@@ -13,7 +13,7 @@
         <controls:SamplePresenter Header="Overview"
                                   Description="Here's a preview of how the default implementation of the WinUI TableView will look, showcasing its standard layout, structure, and features.">
             <controls:SamplePresenter.Example>
-                <tv:TableView ItemsSource="{Binding Items}" />
+                <tv:TableView ItemsSource="{Binding Items}" ShowRowNumbers="True" />
             </controls:SamplePresenter.Example>
             <controls:SamplePresenter.Xaml>
                 <x:String xml:space="preserve">

src/AutomationPeers/TableViewCellAutomationPeer.cs

@@ -70,8 +70,8 @@ protected override string GetNameCore()
             ? TableViewRowAutomationPeer.GetColumnHeaderText(col)
             : string.Empty;
 
-        var rowIndex = _owner.Row?.Index ?? -1;
-        var rowDisplay = rowIndex >= 0 ? $"Row {rowIndex + 1}" : string.Empty;
+        var rowNumber = _owner.Row?.RowNumber ?? 0;
+        var rowDisplay = rowNumber > 0 ? $"Row {rowNumber}" : string.Empty;
 
         var cellValue = _owner.Column is TableViewTemplateColumn
             ? string.Empty

src/AutomationPeers/TableViewRowAutomationPeer.cs

@@ -43,8 +43,8 @@ protected override string GetNameCore()
             return name;
         }
 
-        var index = _owner.Index;
-        return index >= 0 ? $"Row {index + 1}" : "Row";
+        var rowNumber = _owner.RowNumber;
+        return rowNumber > 0 ? $"Row {rowNumber}" : "Row";
     }
 
     /// <inheritdoc/>

src/AutomationPeers/TableViewRowHeaderAutomationPeer.cs

@@ -75,8 +75,8 @@ protected override string GetNameCore()
             }
         }
 
-        // Fall back to the row index
-        var rowIndex = _owner.TableViewRow?.Index ?? -1;
-        return rowIndex >= 0 ? $"Row {rowIndex + 1}" : base.GetNameCore();
+        // Fall back to the row number
+        var rowNumber = _owner.TableViewRow?.RowNumber ?? 0;
+        return rowNumber > 0 ? $"Row {rowNumber}" : base.GetNameCore();
     }
 }

src/ItemsSource/CollectionView.cs

@@ -811,6 +811,15 @@ public int IndexOf(object? item)
         return _view.IndexOf(item);
     }
 
+    /// <summary>
+    /// Returns the item's position among <see cref="_groupingSourceItems"/> - the full filtered+sorted set,
+    /// in source order - unlike <see cref="IndexOf"/>, unaffected by items being hidden by a collapsed group.
+    /// </summary>
+    internal int IndexOfSourceItem(object? item)
+    {
+        return item is null ? -1 : _groupingSourceItems.IndexOf(item);
+    }
+
     /// <summary>
     /// Inserts an item to the collection at the specified index.
     /// </summary>

src/TableView.Properties.cs

@@ -238,6 +238,11 @@ public partial class TableView
     /// </summary>
     public static readonly DependencyProperty HeadersVisibilityProperty = DependencyProperty.Register(nameof(HeadersVisibility), typeof(TableViewHeadersVisibility), typeof(TableView), new PropertyMetadata(TableViewHeadersVisibility.All, OnRowHeadersVisibilityChanged));
 
+    /// <summary>
+    /// Identifies the ShowRowNumbers dependency property.
+    /// </summary>
+    public static readonly DependencyProperty ShowRowNumbersProperty = DependencyProperty.Register(nameof(ShowRowNumbers), typeof(bool), typeof(TableView), new PropertyMetadata(false, OnShowRowNumbersChanged));
+
     /// <summary>
     /// Identifies the RowHeaderContent dependency property.
     /// </summary>
@@ -877,6 +882,15 @@ public TableViewHeadersVisibility HeadersVisibility
         set => SetValue(HeadersVisibilityProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether each row shows its number in the row header area.
+    /// </summary>
+    public bool ShowRowNumbers
+    {
+        get => (bool)GetValue(ShowRowNumbersProperty);
+        set => SetValue(ShowRowNumbersProperty, value);
+    }
+
     /// <summary>
     /// Gets or sets the data template for the row header.
     /// </summary>
@@ -1303,6 +1317,21 @@ private static void OnRowHeadersVisibilityChanged(DependencyObject d, Dependency
         }
     }
 
+    /// <summary>
+    /// Handles changes to the ShowRowNumbers property.
+    /// </summary>
+    private static void OnShowRowNumbersChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is TableView tableView)
+        {
+            foreach (var row in tableView._rows)
+            {
+                row.RowPresenter?.SetRowNumberVisibility();
+                row.RowPresenter?.SetRowNumber();
+            }
+        }
+    }
+
     /// <summary>
     /// Handles changes to the RowHeaderTemplate and RowHeaderTemplateSelector properties.
     /// </summary>

src/TableView.cs

@@ -143,6 +143,7 @@
         foreach (var row in _rows)
         {
             row.RowPresenter?.SetGroupIndent();
+            row.RowPresenter?.SetRowNumber();
         }
     }
 
@@ -1119,7 +1120,7 @@
 #if WINDOWS
     /// <summary>
     /// Applies <see cref="AreStickyGroupHeadersEnabled"/> to the underlying <see cref="ItemsStackPanel"/>, if the
     /// current <see cref="ItemsPanelRoot"/> is one.
     /// </summary>
     private void ApplyStickyGroupHeadersSetting()
     {
@@ -2811,6 +2812,33 @@
         });
     }
 
+    /// <summary>
+    /// Gets <paramref name="row"/>'s real, stable position among all rows - unlike <see cref="TableViewRow.Index"/>,
+    /// unaffected by other rows being hidden by a collapsed ancestor group. Only worth the lookup cost while
+    /// grouping is actually active; otherwise the display index already is the real index.
+    /// </summary>
+    internal int GetRealRowIndex(TableViewRow row)
+    {
+#if WINDOWS
+        if (_collectionView.GroupDescriptions.Count > 0)
+        {
+            return _collectionView.IndexOfSourceItem(row.Content);
+        }
+#endif
+        return row.Index;
+    }
+
+    /// <summary>
+    /// Refreshes the displayed row number (and <see cref="TableViewRowHeader.Tag"/>) for every realized row.
+    /// </summary>
+    internal void RefreshRowNumbers()
+    {
+        foreach (var row in _rows)
+        {
+            row.RowPresenter?.SetRowNumber();
+        }
+    }
+
     /// <summary>
     /// Resets the auto-calculated widths of the specified columns and recalculates them.
     /// </summary>
@@ -2980,6 +3008,7 @@
         foreach (var row in _rows)
         {
             row.RowPresenter?.SetRowHeaderVisibility();
+            row.RowPresenter?.SetRowNumberVisibility();
         }
     }
 

src/TableViewRow.cs

@@ -162,6 +162,7 @@ protected override void OnContentChanged(object oldContent, object newContent)
 
         RowPresenter?.InvalidateMeasure(); // The cells presenter does not measure every time.
         TableView?.EnsureAlternateRowColors();
+        TableView?.RefreshRowNumbers();
     }
 
     /// <inheritdoc/>
@@ -644,6 +645,13 @@ private double GetHorizontalGridlineHeight()
     /// </summary>
     public int Index => TableView?.IndexFromContainer(this) ?? -1;
 
+    /// <summary>
+    /// Gets the row's 1-based number as shown in the UI. When <see cref="TableView.ShowRowNumbers"/> is
+    /// enabled, this is the row's real, stable position among all rows - unaffected by other rows being
+    /// hidden by a collapsed group - rather than <see cref="Index"/>, which excludes them.
+    /// </summary>
+    public int RowNumber => TableView is { ShowRowNumbers: true } tableView ? tableView.GetRealRowIndex(this) + 1 : Index + 1;
+
     /// <summary>
     /// Gets or sets the TableView associated with the row.
     /// </summary>

src/TableViewRowPresenter.cs

@@ -24,6 +24,7 @@
 public partial class TableViewRowPresenter : Control
 {
     private TableViewRowHeader? _rowHeader;
+    private TextBlock? _rowNumberText;
     private Panel? _rootPanel;
     private StackPanel? _scrollableCellsPanel;
     private StackPanel? _frozenCellsPanel;
@@ -60,6 +61,7 @@
         }
 
         _rowHeader = GetTemplateChild("RowHeader") as TableViewRowHeader;
+        _rowNumberText = GetTemplateChild("RowNumberText") as TextBlock;
         _rootPanel = GetTemplateChild("RootPanel") as Panel;
         _scrollableCellsPanel = GetTemplateChild("ScrollableCellsPanel") as StackPanel;
         _frozenCellsPanel = GetTemplateChild("FrozenCellsPanel") as StackPanel;
@@ -94,6 +96,8 @@
         SetRowDetailsVisibility();
         SetRowDetailsTemplate();
         SetGroupIndent();
+        SetRowNumberVisibility();
+        SetRowNumber();
     }
 
     /// <summary>
@@ -203,7 +207,7 @@
     /// <summary>
     /// The extra <see cref="TableView.CellsHorizontalOffset"/> added for the active grouping depth, so cells (and,
     /// via that shared offset, the column headers) shift right under nested group headers. A single grouping
     /// level isn't indented - only levels after the first add <see cref="TableViewGroupHeaderRow.GroupIndentSize"/>.
     /// </summary>
     private double GetGroupIndent()
     {
@@ -359,6 +363,43 @@
         }
     }
 
+    /// <summary>
+    /// Sets the visibility of the row number based on the <see cref="TableView.ShowRowNumbers"/> setting.
+    /// Deliberately independent of multi-selection, the details toggle button, and <see cref="TableView.RowHeaderTemplate"/> -
+    /// the row number lives in its own column and must never be suppressed by any of those.
+    /// </summary>
+    internal void SetRowNumberVisibility()
+    {
+        if (_rowNumberText is not null && TableView is not null)
+        {
+            var areHeadersVisible = TableView.HeadersVisibility is TableViewHeadersVisibility.All or TableViewHeadersVisibility.Rows;
+
+            _rowNumberText.Visibility = TableView.ShowRowNumbers && areHeadersVisible ? Visibility.Visible : Visibility.Collapsed;
+        }
+    }
+
+    /// <summary>
+    /// Sets the displayed row number and <see cref="TableViewRowHeader.Tag"/> - the latter kept up to date
+    /// regardless of <see cref="TableView.ShowRowNumbers"/> so a custom <see cref="TableView.RowHeaderTemplate"/>
+    /// can bind to it via <c>{RelativeSource Mode=TemplatedParent}</c>.
+    /// </summary>
+    internal void SetRowNumber()
+    {
+        if (TableView is null || TableViewRow is null) return;
+
+        var rowNumber = TableViewRow.RowNumber;
+
+        if (_rowHeader is not null)
+        {
+            _rowHeader.Tag = rowNumber;
+        }
+
+        if (_rowNumberText is not null)
+        {
+            _rowNumberText.Text = rowNumber > 0 ? rowNumber.ToString() : string.Empty;
+        }
+    }
+
     internal void SetRowHeaderBindings()
     {
         _rowHeader?.SetBinding(HeightProperty, new Binding

src/Themes/Resources.xaml

@@ -83,8 +83,12 @@
             <Thickness x:Key="TableViewGroupHeaderRowExpanderMargin">4,0,4,0</Thickness>
             <Thickness x:Key="TableViewGroupHeaderRowContentMargin">8,0,16,0</Thickness>
             <x:Double x:Key="TableViewGroupHeaderRowFontSize">18</x:Double>
+            <StaticResource x:Key="TableViewRowNumberForeground" ResourceKey="TextFillColorSecondaryBrush" />
+            <x:Double x:Key="TableViewRowNumberFontSize">12</x:Double>
+            <Thickness x:Key="TableViewRowNumberMargin">8,0,4,0</Thickness>
+            <x:Double x:Key="TableViewRowNumberMinWidth">24</x:Double>
         </ResourceDictionary>
-        
+
         <ResourceDictionary x:Key="Dark">
             <x:String x:Key="SortIconAscending">&#xf0ad;</x:String>
             <x:String x:Key="SortIconDescending">&#xf0ae;</x:String>
@@ -161,6 +165,10 @@
             <Thickness x:Key="TableViewGroupHeaderRowExpanderMargin">4,0,0,0</Thickness>
             <Thickness x:Key="TableViewGroupHeaderRowContentMargin">8,0,16,0</Thickness>
             <x:Double x:Key="TableViewGroupHeaderRowFontSize">18</x:Double>
+            <StaticResource x:Key="TableViewRowNumberForeground" ResourceKey="TextFillColorSecondaryBrush" />
+            <x:Double x:Key="TableViewRowNumberFontSize">12</x:Double>
+            <Thickness x:Key="TableViewRowNumberMargin">8,0,4,0</Thickness>
+            <x:Double x:Key="TableViewRowNumberMinWidth">24</x:Double>
         </ResourceDictionary>
 
         <ResourceDictionary x:Key="HighContrast">
@@ -239,6 +247,10 @@
             <Thickness x:Key="TableViewGroupHeaderRowExpanderMargin">4,0,0,0</Thickness>
             <Thickness x:Key="TableViewGroupHeaderRowContentMargin">8,0,16,0</Thickness>
             <x:Double x:Key="TableViewGroupHeaderRowFontSize">18</x:Double>
+            <SolidColorBrush x:Key="TableViewRowNumberForeground" Color="{ThemeResource SystemColorButtonTextColor}" />
+            <x:Double x:Key="TableViewRowNumberFontSize">12</x:Double>
+            <Thickness x:Key="TableViewRowNumberMargin">8,0,4,0</Thickness>
+            <x:Double x:Key="TableViewRowNumberMinWidth">24</x:Double>
         </ResourceDictionary>
     </ResourceDictionary.ThemeDictionaries>
 

src/Themes/TableViewRowPresenter.xaml

@@ -78,14 +78,27 @@
 
                             <Grid>
                                 <Grid.ColumnDefinitions>
+                                    <ColumnDefinition x:Name="RowNumberColumn" Width="Auto" />
                                     <ColumnDefinition x:Name="RowHeaderColumn" Width="Auto" />
                                     <ColumnDefinition x:Name="DetailsExpandChevronColumn" Width="Auto" />
                                 </Grid.ColumnDefinitions>
 
-                                <local:TableViewRowHeader x:Name="RowHeader" />
-
+                                <TextBlock x:Name="RowNumberText"
+                                           Grid.Column="0"
+                                           Visibility="Collapsed"
+                                           TextAlignment="Right"
+                                           HorizontalAlignment="Stretch"
+                                           VerticalAlignment="Center"
+                                           MinWidth="{ThemeResource TableViewRowNumberMinWidth}"
+                                           Margin="{ThemeResource TableViewRowNumberMargin}"
+                                           FontSize="{ThemeResource TableViewRowNumberFontSize}"
+                                           Foreground="{ThemeResource TableViewRowNumberForeground}" />
+
+                                <local:TableViewRowHeader x:Name="RowHeader"
+                                                           Grid.Column="1" />
+
                                 <ToggleButton x:Name="DetailsToggleButton"
-                                              Grid.Column="1"
+                                              Grid.Column="2"
                                               VerticalAlignment="Stretch"
                                               Visibility="Collapsed"
                                               Margin="{ThemeResource TableViewDetailsToggleButtonMargin}"