ContrastHelper

components/ColorAnalyzer/samples/AccentAnalyzer.md

@@ -17,3 +17,5 @@ icon: assets/icon.png
 The AccentAnalyzer provides a pure XAML way to use the colors extracted from an image as a binding source for any `Color` property.
 
 > [!Sample AccentAnalyzerSample]
+
+> [!Sample ContrastHelperSample]

components/ColorAnalyzer/samples/AccentAnalyzerSample.xaml

@@ -1,4 +1,4 @@
-<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
+<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
 <Page x:Class="ColorAnalyzerExperiment.Samples.AccentAnalyzerSample"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
@@ -62,7 +62,7 @@
                 <Border.Background>
                     <SolidColorBrush Color="{x:Bind AccentAnalyzer.DominantColor, Mode=OneWay}" />
                 </Border.Background>
-                <TextBlock Foreground="Black"
+                <TextBlock helpers:ContrastHelper.Opponent="{x:Bind AccentAnalyzer.DominantColor, Mode=OneWay}"
                            Text="Dominant" />
             </Border>
 
@@ -74,8 +74,13 @@
                 <Border.Background>
                     <SolidColorBrush Color="{x:Bind AccentAnalyzer.BaseColor, Mode=OneWay}" />
                 </Border.Background>
-                <TextBlock Foreground="Black"
-                           Text="Base" />
+                <TextBlock Text="Base">
+                    <TextBlock.Foreground>
+                        <SolidColorBrush helpers:ContrastHelper.MinRatio="5"
+                                         helpers:ContrastHelper.Opponent="{x:Bind AccentAnalyzer.BaseColor, Mode=OneWay}"
+                                         Color="{x:Bind AccentAnalyzer.PrimaryAccentColor, Mode=OneWay}" />
+                    </TextBlock.Foreground>
+                </TextBlock>
             </Border>
 
             <!--  Primary  -->
@@ -86,7 +91,7 @@
                 <Border.Background>
                     <SolidColorBrush Color="{x:Bind AccentAnalyzer.PrimaryAccentColor, Mode=OneWay}" />
                 </Border.Background>
-                <TextBlock Foreground="Black"
+                <TextBlock helpers:ContrastHelper.Opponent="{x:Bind AccentAnalyzer.PrimaryAccentColor, Mode=OneWay}"
                            Text="Primary" />
             </Border>
             <!--  Secondary  -->
@@ -97,7 +102,7 @@
                 <Border.Background>
                     <SolidColorBrush Color="{x:Bind AccentAnalyzer.SecondaryAccentColor, Mode=OneWay}" />
                 </Border.Background>
-                <TextBlock Foreground="Black"
+                <TextBlock helpers:ContrastHelper.Opponent="{x:Bind AccentAnalyzer.SecondaryAccentColor, Mode=OneWay}"
                            Text="Secondary" />
             </Border>
             <!--  Tertiary  -->
@@ -108,7 +113,7 @@
                 <Border.Background>
                     <SolidColorBrush Color="{x:Bind AccentAnalyzer.TertiaryAccentColor, Mode=OneWay}" />
                 </Border.Background>
-                <TextBlock Foreground="Black"
+                <TextBlock helpers:ContrastHelper.Opponent="{x:Bind AccentAnalyzer.TertiaryAccentColor, Mode=OneWay}"
                            Text="Tertiary" />
             </Border>
 

components/ColorAnalyzer/samples/ContrastHelperSample.xaml

@@ -0,0 +1,75 @@
+<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
+<Page x:Class="ColorAnalyzerExperiment.Samples.ContrastHelperSample"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:behaviors="using:CommunityToolkit.WinUI.Behaviors"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:helpers="using:CommunityToolkit.WinUI.Helpers"
+      xmlns:interactivity="using:Microsoft.Xaml.Interactivity"
+      xmlns:local="using:ColorAnalyzerExperiment.Samples"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      mc:Ignorable="d">
+
+    <Grid>
+        <Grid.RowDefinitions>
+            <RowDefinition />
+            <RowDefinition Height="auto" />
+        </Grid.RowDefinitions>
+
+        <Grid.ColumnDefinitions>
+            <ColumnDefinition />
+            <ColumnDefinition />
+        </Grid.ColumnDefinitions>
+
+        <Border Grid.ColumnSpan="2">
+            <Border.Background>
+                <SolidColorBrush Color="{x:Bind BackgroundPicker.Color, Mode=OneWay}" />
+            </Border.Background>
+            <StackPanel Spacing="2">
+                <TextBlock helpers:ContrastHelper.Opponent="{x:Bind BackgroundPicker.Color, Mode=OneWay}"
+                           FontSize="24"
+                           Text="Always legible text" />
+                <TextBlock helpers:ContrastHelper.MinRatio="5"
+                           helpers:ContrastHelper.Opponent="{x:Bind BackgroundPicker.Color, Mode=OneWay}"
+                           FontSize="24"
+                           Text="Legible text (MinRatio: 5)">
+                    <TextBlock.Foreground>
+                        <SolidColorBrush Color="{x:Bind ForegroundPicker.Color, Mode=OneWay}" />
+                    </TextBlock.Foreground>
+                </TextBlock>
+                <TextBlock helpers:ContrastHelper.MinRatio="3"
+                           helpers:ContrastHelper.Opponent="{x:Bind BackgroundPicker.Color, Mode=OneWay}"
+                           FontSize="16"
+                           Text="Legible text (MinRatio: 3)">
+                    <TextBlock.Foreground>
+                        <SolidColorBrush Color="{x:Bind ForegroundPicker.Color, Mode=OneWay}" />
+                    </TextBlock.Foreground>
+                </TextBlock>
+                <TextBlock FontSize="16"
+                           Text="Potentially illegible text">
+                    <TextBlock.Foreground>
+                        <SolidColorBrush Color="{x:Bind ForegroundPicker.Color, Mode=OneWay}" />
+                    </TextBlock.Foreground>
+                </TextBlock>
+            </StackPanel>
+        </Border>
+
+        <StackPanel Grid.Row="1"
+                    HorizontalAlignment="Center">
+            <TextBlock Text="Desired Foreground" />
+            <ColorPicker x:Name="ForegroundPicker"
+                         IsColorChannelTextInputVisible="False"
+                         IsHexInputVisible="False"
+                         Color="Black" />
+        </StackPanel>
+
+        <StackPanel Grid.Row="1"
+                    Grid.Column="1"
+                    HorizontalAlignment="Center">
+            <TextBlock Text="Backround" />
+            <ColorPicker x:Name="BackgroundPicker"
+                         IsColorChannelTextInputVisible="False"
+                         IsHexInputVisible="False" />
+        </StackPanel>
+    </Grid>
+</Page>

components/ColorAnalyzer/samples/ContrastHelperSample.xaml.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace ColorAnalyzerExperiment.Samples;
+
+/// <summary>
+/// An example sample page of a custom control inheriting from Panel.
+/// </summary>
+[ToolkitSample(id: nameof(ContrastHelperSample), "ContrastAnalyzer helper", description: $"A sample for showing how the contrast analyzer can be used.")]
+public sealed partial class ContrastHelperSample : Page
+{
+    public ContrastHelperSample()
+    {
+        this.InitializeComponent();
+    }
+}

components/ColorAnalyzer/src/AccentAnalyzer.cs

@@ -17,7 +17,7 @@
 namespace CommunityToolkit.WinUI.Helpers;
 
 /// <summary>
-/// A resource that can be used to extract color palettes out of any UIElement.
+/// A resource that can be used to extract color palettes out of any <see cref="UIElement"/>.
 /// </summary>
 public partial class AccentAnalyzer : DependencyObject
 {

components/ColorAnalyzer/src/Contrast/ContrastHelper.Properties.cs

@@ -0,0 +1,102 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Windows.UI;
+
+namespace CommunityToolkit.WinUI.Helpers;
+
+public partial class ContrastHelper
+{
+    // TODO: Handle gradient brushes?
+    /// <summary>
+    /// An attached property that defines the color to compare against.
+    /// </summary>
+    /// <remarks>
+    /// This property can be attached to any <see cref="TextBlock"/> or <see cref="Control"/>
+    /// to update their <see cref="TextBlock.Foreground"/> or <see cref="Control.Foreground"/>.
+    /// If the original Foreground is not a <see cref="SolidColorBrush"/>, it will always apply contrast.
+    /// It can also be attached to any <see cref="SolidColorBrush"/> to update the <see cref="SolidColorBrush.Color"/>.
+    /// </remarks>
+    public static readonly DependencyProperty OpponentProperty =
+        DependencyProperty.RegisterAttached(
+            "Opponent",
+            typeof(Color),
+            typeof(ContrastHelper),
+            new PropertyMetadata(Colors.Transparent, OnOpponentChanged));
+
+    /// <summary>
+    /// An attached property that defines the minimum acceptable contrast ratio against the opponent color.
+    /// </summary>
+    /// <remarks>
+    /// Range: 1 to 21 (inclusive). Default is 21 (maximum contrast).
+    /// </remarks>
+    public static readonly DependencyProperty MinRatioProperty =
+        DependencyProperty.RegisterAttached(
+            "MinRatio",
+            typeof(double),
+            typeof(ContrastHelper),
+            new PropertyMetadata(21d, OnMinRatioChanged));
+
+    /// <summary>
+    /// An attached property that records the original color before adjusting for contrast.
+    /// </summary>
+    public static readonly DependencyProperty OriginalColorProperty =
+        DependencyProperty.RegisterAttached(
+            "Original",
+            typeof(Color),
+            typeof(ContrastHelper),
+            new PropertyMetadata(Colors.Transparent));
+
+    // Tracks the SolidColorBrush we're monitoring for changes
+    private static readonly DependencyProperty CallbackObjectProperty =
+        DependencyProperty.RegisterAttached(
+            "CallbackObject",
+            typeof(DependencyObject),
+            typeof(ContrastHelper),
+            new PropertyMetadata(null));
+
+    // Tracks the callback token from the SolidColorBrush we are monitoring
+    private static readonly DependencyProperty CallbackProperty =
+        DependencyProperty.RegisterAttached(
+            "Callback",
+            typeof(long),
+            typeof(ContrastHelper),
+            new PropertyMetadata(0L));
+
+    /// <summary>
+    /// Get the opponent color to compare against.
+    /// </summary>
+    /// <returns>The opponent color.</returns>
+    public static Color GetOpponent(DependencyObject obj) => (Color)obj.GetValue(OpponentProperty);
+
+    /// <summary>
+    /// Set the opponent color to compare against.
+    /// </summary>
+    public static void SetOpponent(DependencyObject obj, Color value) => obj.SetValue(OpponentProperty, value);
+
+    /// <summary>
+    /// Get the minimum acceptable contrast ratio against the opponent color.
+    /// </summary>
+    public static double GetMinRatio(DependencyObject obj) => (double)obj.GetValue(MinRatioProperty);
+
+    /// <summary>
+    /// Set the minimum acceptable contrast ratio against the opponent color.
+    /// </summary>
+    public static void SetMinRatio(DependencyObject obj, double value) => obj.SetValue(MinRatioProperty, value);
+
+    /// <summary>
+    /// Gets the original color before adjustment for contrast.
+    /// </summary>
+    public static Color GetOriginal(DependencyObject obj) => (Color)obj.GetValue(OriginalColorProperty);
+
+    private static void SetOriginal(DependencyObject obj, Color color) => obj.SetValue(OriginalColorProperty, color);
+
+    private static DependencyObject GetCallbackObject(DependencyObject obj) => (DependencyObject)obj.GetValue(CallbackObjectProperty);
+
+    private static void SetCallbackObject(DependencyObject obj, DependencyObject dp) => obj.SetValue(CallbackObjectProperty, dp);
+
+    private static long GetCallback(DependencyObject obj) => (long)obj.GetValue(CallbackProperty);
+
+    private static void SetCallback(DependencyObject obj, long value) => obj.SetValue(CallbackProperty, value);
+}