[Proposal] OnVisualState markup extension

[matt-goldman]

OnVisualState markup extension: collocated visual state declarations

Visual State Manager is incredibly powerful but also convoluted, requiring substantial boilerplate for something that could be expressed much more simply. I'd like to propose an OnVisualState markup extension that follows the same pattern established by AppThemeBinding: replacing a verbose, structurally separated approach with a collocated, declarative one.

The problem

Take the following example. This is a control used in a list of search results; each item can be selected to add to a collection. The visual requirements are to remove the default selection background and show a check icon when selected.

<?xml version="1.0" encoding="utf-8"?>
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:vm="clr-namespace:Squads.UI.ViewModels"
             xmlns:mct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="Squads.UI.Controls.UserCard"
             ControlTemplate="{StaticResource Card}">
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroupList>
            <VisualStateGroup x:Name="CommOnVisualStates">
                <VisualState x:Name="Selected">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="Transparent" />
                        <Setter TargetName="CheckLabel"
                                Property="Label.IsVisible" Value="True" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Normal">
                    <VisualState.Setters>
                        <Setter TargetName="CheckLabel"
                                Property="Label.IsVisible" Value="False" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </VisualStateManager.VisualStateGroups>
    <Grid ColumnDefinitions="*, 5*"
          Padding="10"
          x:Name="UserProfile"
          x:DataType="vm:UserProfileViewModel">
        <mct:AvatarView StrokeThickness="1"
                        BorderColor="{AppThemeBinding Light={StaticResource Gray900},
                                                  Dark={StaticResource White}}"
                        ImageSource="{Binding ProfilePictureUrl}"
                        Text="{Binding Initials}"
                        CornerRadius="25"
                        WidthRequest="50"
                        HeightRequest="50"
                        VerticalOptions="Center"
                        HorizontalOptions="Center"/>

        <VerticalStackLayout Grid.Column="1"
                             VerticalOptions="Center"
                             Margin="10,0"
                             Spacing="2">
            <Label FontAttributes="Bold"
                   Text="{Binding FullName}"/>
            <Label Text="{Binding Email}" />
        </VerticalStackLayout>

        <Label Grid.Column="1"
               Text="&#xf29a;"
               FontFamily="FluentIcons"
               FontSize="Header"
               VerticalOptions="Center"
               HorizontalOptions="End"
               TextColor="{StaticResource SelectedGreen}"
               x:Name="CheckLabel"/>
    </Grid>
</ContentView>

There are two problems with this:

1. Excessive boilerplate. The VSM block is 17 lines (conservatively; I adjusted for formatting some properties across multiple lines, which seemed more honest) to express what amounts to two property/value pairs per state.
2. Visual customisation is divorced from the controls being targeted. To understand what CheckLabel.IsVisible does, you have to read the property on the label, then jump to the VSM block at the top of the file (or worse, in a separate style/resource dictionary), then mentally merge them. This structural separation makes maintenance harder and makes the XAML harder to reason about at a glance.

Proposed solution

An OnVisualState markup extension that collocates state-dependent values with the properties they apply to, the same thing AppThemeBinding did for theme-dependent values.

<?xml version="1.0" encoding="utf-8"?>
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:vm="clr-namespace:Squads.UI.ViewModels"
             xmlns:mct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="Squads.UI.Controls.UserCard"
             ControlTemplate="{StaticResource Card}">
    <Grid ColumnDefinitions="*, 5*"
          BackgroundColor="{OnVisualState Selected=Transparent}"
          Padding="10"
          x:Name="UserProfile"
          x:DataType="vm:UserProfileViewModel">
        <mct:AvatarView StrokeThickness="1"
                        BorderColor="{AppThemeBinding Light={StaticResource Gray900},
                                                  Dark={StaticResource White}}"
                        ImageSource="{Binding ProfilePictureUrl}"
                        Text="{Binding Initials}"
                        CornerRadius="25"
                        WidthRequest="50"
                        HeightRequest="50"
                        VerticalOptions="Center"
                        HorizontalOptions="Center"/>

        <VerticalStackLayout Grid.Column="1"
                             VerticalOptions="Center"
                             Margin="10,0"
                             Spacing="2">
            <Label FontAttributes="Bold"
                   Text="{Binding FullName}"/>
            <Label Text="{Binding Email}" />
        </VerticalStackLayout>

        <Label Grid.Column="1"
               IsVisible="{OnVisualState Normal=False, Selected=True}"
               Text="&#xf29a;"
               FontFamily="FluentIcons"
               FontSize="Header"
               VerticalOptions="Center"
               HorizontalOptions="End"
               TextColor="{StaticResource SelectedGreen}"
               x:Name="CheckLabel"/>
    </Grid>
</ContentView>

This solves both problems:

1. 17 lines of boilerplate removed. The entire VSM block is gone, replaced by inline declarations on the properties that actually change.
2. Customisations live with the controls they target. You can see at a glance that CheckLabel.IsVisible is False in Normal and True in Selected, right where the property is declared.

Behaviour

• Omitted states preserve the default value. BackgroundColor="{OnVisualState Selected=Transparent}" means: in the Selected state, set BackgroundColor to Transparent; in all other states, leave it at whatever value it would otherwise have (inherited, default, or explicitly set). This is consistent with how Trigger and DataTrigger already behave, when the condition is no longer met, the property reverts, and eliminates an entire class of VSM bug where forgetting to define a Normal setter leaves a property stuck on the value from another state.

• Targets CommOnVisualStates by default, with an optional Group parameter for custom state groups.
• Composable with existing markup extensions. {OnVisualState Normal={StaticResource Gray500}, Focused={StaticResource Primary}} should work the same way nested extensions work with AppThemeBinding.

Precedent

This follows the pattern established by AppThemeBinding, which replaced manual RequestedThemeChanged handling with a collocated, declarative markup extension. The motivations are the same: less boilerplate, better collocation, easier maintenance, applied to visual states instead of themes.

Relationship to C# XAML expressions

XAML C# expressions (slated for .NET 11) will make many things easier, and it's worth considering whether they'd make this unnecessary. My current thinking is that even if an expression could inspect visual state and return a value, OnVisualState would still be a valid addition for two reasons:

1. Declarative vs imperative. OnVisualState is vocabulary that extends the declarative surface; an expression is a workaround through imperative code. AppThemeBinding exists despite the fact that you can handle theming in code-behind, because the declarative form is more idiomatic and easier to maintain.
2. Subscription semantics. A purpose-built markup extension can optimise for the visual-state access pattern (one subscription per element fanning out to all OnVisualState instances, lifecycle tied to element attach/detach, no reflection at evaluation time). A general-purpose expression mechanism can't make those assumptions.

Status

I've started dabbling with a prototype, nothing I particularly want to share yet. This is something I'll use for sure but wanted to gauge community appetite for something like this in the toolkit.