fix(controls): Fix TextBlock style, typography and related issues

Author: apachezy

src/Wpf.Ui/Controls/FontTypographyPreset.cs

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the MIT License.
+// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
+// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
+// All Rights Reserved.
+
+using System.Windows.Markup;
+
+namespace Wpf.Ui.Controls;
+
+/// <summary>
+/// Represents a named typography preset containing font metrics used by controls
+/// (for example, font size and weight). Presets are intended to be stored as
+/// resources and referenced by the control's <c>FontTypography</c> mapping.
+/// </summary>
+/// <remarks>
+/// Example:
+/// <code lang="xml">
+/// &lt;ResourceDictionary
+///     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+///     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+///     xmlns:controls="clr-namespace:Wpf.Ui.Controls"&gt;
+///
+///   &lt;controls:FontTypographyPreset x:Key="BodyTextBlockStyle" FontSize="14" FontWeight="Regular" /&gt;
+///
+/// &lt;/ResourceDictionary&gt;
+///
+/// &lt;!-- TextBlock resolves the preset by resource key produced from the FontTypography enum --&gt;
+/// &lt;ui:TextBlock FontTypography="Body" /&gt;
+/// </code>
+/// </remarks>
+[MarkupExtensionReturnType(typeof(FontTypographyPreset))]
+public class FontTypographyPreset : MarkupExtension
+{
+    /// <summary>
+    /// Gets or sets the font size for this typography style, measured in device-independent units (1/96 inch).
+    /// If this property is <c>null</c>, no font size override will be applied from this style.
+    /// </summary>
+    public double? FontSize { get; set; }
+
+    /// <summary>
+    /// Gets or sets the font weight defined by this typography preset.
+    /// A <c>null</c> value indicates that no specific font weight should be applied.
+    /// </summary>
+    public FontWeight? FontWeight { get; set; }
+
+    /*
+       Note: Excluding LineHeight intentionally. WPF and WinUI have fundamentally
+       different text rendering engines - identical FontSize/LineHeight pairs would
+       break vertical text alignment and create maintenance nightmares.
+    */
+
+    /// <summary>
+    /// Returns this instance when used in XAML so the preset can be declared as a resource.
+    /// </summary>
+    public override object ProvideValue(IServiceProvider serviceProvider)
+    {
+        return this;
+    }
+}

src/Wpf.Ui/Controls/TextBlock/TextBlock.cs

@@ -3,73 +3,271 @@
 // Copyright (C) Leszek Pomianowski and WPF UI Contributors.
 // All Rights Reserved.
 
+using Wpf.Ui.Markup;
+using UiTextBlock = Wpf.Ui.Controls.TextBlock;
+using WinTextBlock = System.Windows.Controls.TextBlock;
+
 // ReSharper disable once CheckNamespace
 namespace Wpf.Ui.Controls;
 
 /// <summary>
-/// Extended <see cref="System.Windows.Controls.TextBlock"/> with additional parameters like <see cref="FontTypography"/>.
+/// Extended <see cref="System.Windows.Controls.TextBlock"/> that integrates with the library's
+/// typography and appearance resources.
 /// </summary>
-public class TextBlock : System.Windows.Controls.TextBlock
+/// <remarks>
+/// This control supports two mechanisms for applying design-system typography:
+/// <para>
+/// - The <see cref="FontTypography"/> enum which is mapped to a resource key and resolved
+///   at runtime to a <see cref="FontTypographyPreset"/>.
+/// </para>
+/// <para>
+/// - An internal resource-backed preset is resolved via a private puppet dependency property
+///   so the framework's resource system (DynamicResource) performs resolution and updates.
+/// </para>
+/// <para>
+/// The resolved preset is used to coerce <see cref="WinTextBlock.FontSizeProperty"/>
+/// and <see cref="WinTextBlock.FontWeight"/>.
+/// </para>
+/// <para>
+/// The <see cref="Appearance"/> property maps to brush resources and is applied via a resource reference.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code lang="xml">
+/// &lt;ui:TextBlock FontTypography="Body" Appearance="Primary" Text="Hello, world!" /&gt;
+/// </code>
+/// </example>
+public class TextBlock : WinTextBlock
 {
+    static TextBlock()
+    {
+        // Coerce FontSize based on FontTypography when set.
+        // Using AddOwner allows the opportunity to OverrideMetadata to be reserved for later.
+        FontSizeProperty.AddOwner(
+            typeof(UiTextBlock),
+            new FrameworkPropertyMetadata(
+                14d, // Fluent theme default font size - FontTypography Body font size
+                FrameworkPropertyMetadataOptions.AffectsMeasure
+              | FrameworkPropertyMetadataOptions.AffectsRender
+              | FrameworkPropertyMetadataOptions.Inherits,
+                null,
+                static (d, baseValue) => ((UiTextBlock)d).CoerceFontSize(baseValue)
+            )
+        );
+
+        // Coerce FontWeight based on FontTypography when set.
+        FontWeightProperty.AddOwner(
+            typeof(UiTextBlock),
+            new FrameworkPropertyMetadata(
+                FontWeights.Regular, // FontTypography Body font weight
+                FrameworkPropertyMetadataOptions.AffectsMeasure
+              | FrameworkPropertyMetadataOptions.AffectsRender
+              | FrameworkPropertyMetadataOptions.Inherits,
+                null,
+                static (d, baseValue) => ((UiTextBlock)d).CoerceFontWeight(baseValue)
+            )
+        );
+
+        // Coerce Foreground based on Appearance when set.
+        ForegroundProperty.AddOwner(
+            typeof(UiTextBlock),
+            new FrameworkPropertyMetadata(
+                UnsetMarkerBrush.Instance, // marker for an "unset" Foreground
+                FrameworkPropertyMetadataOptions.AffectsRender
+              | FrameworkPropertyMetadataOptions.SubPropertiesDoNotAffectRender
+              | FrameworkPropertyMetadataOptions.Inherits,
+                null,
+                static (d, baseValue) => ((UiTextBlock)d).CoerceForeground(baseValue)
+            )
+        );
+    }
+
     /// <summary>Identifies the <see cref="FontTypography"/> dependency property.</summary>
     public static readonly DependencyProperty FontTypographyProperty = DependencyProperty.Register(
         nameof(FontTypography),
-        typeof(FontTypography),
-        typeof(TextBlock),
+        typeof(FontTypography?),
+        typeof(UiTextBlock),
         new PropertyMetadata(
-            FontTypography.Body,
+            null,
             static (o, args) =>
             {
-                ((TextBlock)o).OnFontTypographyChanged((FontTypography)args.NewValue);
+                ((UiTextBlock)o).OnFontTypographyChanged((FontTypography?)args.NewValue);
             }
         )
     );
 
     /// <summary>Identifies the <see cref="Appearance"/> dependency property.</summary>
     public static readonly DependencyProperty AppearanceProperty = DependencyProperty.Register(
         nameof(Appearance),
-        typeof(TextColor),
-        typeof(TextBlock),
+        typeof(TextColor?),
+        typeof(UiTextBlock),
         new PropertyMetadata(
-            TextColor.Primary,
+            null,
             static (o, args) =>
             {
-                ((TextBlock)o).OnAppearanceChanged((TextColor)args.NewValue);
+                ((UiTextBlock)o).OnAppearanceChanged((TextColor?)args.NewValue);
+            }
+        )
+    );
+
+    /// <summary>
+    /// Private Puppet dependency property used to hold a ResourceReference to a FontTypographyPreset.
+    /// </summary>
+    private static readonly DependencyProperty FontTypographyPresetResourceRefProperty = DependencyProperty.Register(
+        "FontTypographyPresetResourceRef",
+        typeof(FontTypographyPreset),
+        typeof(UiTextBlock),
+        new PropertyMetadata(
+            null,
+            static (d, e) =>
+            {
+                d.CoerceValue(FontSizeProperty);
+                d.CoerceValue(FontWeightProperty);
+            }
+        )
+    );
+
+    /// <summary>
+    /// Private Puppet dependency property used to hold the Foreground resource resolved from the Appearance property.
+    /// </summary>
+    private static readonly DependencyProperty ForegroundResourceRefProperty = DependencyProperty.Register(
+        "ForegroundResourceRef",
+        typeof(Brush),
+        typeof(UiTextBlock),
+        new PropertyMetadata(
+            null,
+            static (d, e) =>
+            {
+                d.CoerceValue(ForegroundProperty);
+            }
+        )
+    );
+
+    /// <summary>
+    /// Private Puppet dependency property used to hold the default foreground resource.
+    /// This property can hold a DynamicResource reference so controls without an explicit Foreground
+    /// will use the library's themed foreground brush.
+    /// </summary>
+    private static readonly DependencyProperty DefaultForegroundResourceRefProperty = DependencyProperty.Register(
+        "DefaultForegroundResourceRef",
+        typeof(Brush),
+        typeof(UiTextBlock),
+        new PropertyMetadata(
+            null,
+            static (d, e) =>
+            {
+                d.CoerceValue(ForegroundProperty);
             }
         )
     );
 
     public TextBlock()
     {
-        var defaultFontTypography = (FontTypography)FontTypographyProperty.DefaultMetadata.DefaultValue;
-        SetResourceReference(StyleProperty, defaultFontTypography.ToResourceValue());
+        SetResourceReference(DefaultForegroundResourceRefProperty, TextColor.Primary.ToResourceKey());
     }
 
     /// <summary>
     /// Gets or sets the <see cref="FontTypography"/> of the text.
     /// </summary>
-    public FontTypography FontTypography
+    public FontTypography? FontTypography
     {
-        get => (FontTypography)GetValue(FontTypographyProperty);
+        get => (FontTypography?)GetValue(FontTypographyProperty);
         set => SetValue(FontTypographyProperty, value);
     }
 
     /// <summary>
     /// Gets or sets the color of the text.
     /// </summary>
-    public TextColor Appearance
+    public TextColor? Appearance
     {
-        get => (TextColor)GetValue(AppearanceProperty);
+        get => (TextColor?)GetValue(AppearanceProperty);
         set => SetValue(AppearanceProperty, value);
     }
 
-    private void OnFontTypographyChanged(FontTypography newTypography)
+    private void OnFontTypographyChanged(FontTypography? newTypography)
     {
-        SetResourceReference(StyleProperty, newTypography.ToResourceValue());
+        if (newTypography.HasValue)
+        {
+            var resourceKey = newTypography.Value.ToResourceKey();
+
+            // Use WPF resource reference mechanism to resolve and cache the preset.
+            // This avoids manual TryFindResource tree traversal.
+            SetResourceReference(FontTypographyPresetResourceRefProperty, resourceKey);
+        }
+        else
+        {
+            // Clear any puppet resource reference
+            ClearValue(FontTypographyPresetResourceRefProperty);
+        }
+
+        // Re-evaluate coerced values so when FontTypography is set, the
+        // CoerceValueCallbacks installed on FontSize/FontWeight will take effect
+        // and prevent local changes from overriding typography-defined values.
+        CoerceValue(FontSizeProperty);
+        CoerceValue(FontWeightProperty);
     }
 
-    private void OnAppearanceChanged(TextColor textColor)
+    private void OnAppearanceChanged(TextColor? textColor)
+    {
+        if (textColor.HasValue)
+        {
+            var resourceKey = textColor.Value.ToResourceKey();
+
+            // Similar to OnFontTypographyChanged, attach themed color resource reference to a proxy property,
+            // allowing the WPF resource system to handle updates automatically.
+            SetResourceReference(ForegroundResourceRefProperty, resourceKey);
+        }
+        else
+        {
+            ClearValue(ForegroundResourceRefProperty);
+        }
+
+        CoerceValue(ForegroundProperty);
+    }
+
+    /*
+     * The following CoerceValueCallback methods handle value precedence.
+     * When no explicit value is set (via style, local value, or inheritance),
+     * they apply WPFUI Fluent theme defaults.
+     */
+
+    private object CoerceFontSize(object baseValue)
     {
-        SetResourceReference(ForegroundProperty, textColor.ToResourceValue());
+        var preset = GetValue(FontTypographyPresetResourceRefProperty) as FontTypographyPreset;
+        if (preset?.FontSize is double size)
+        {
+            return size;
+        }
+
+        return baseValue;
+    }
+
+    private object CoerceFontWeight(object baseValue)
+    {
+        var preset = GetValue(FontTypographyPresetResourceRefProperty) as FontTypographyPreset;
+        if (preset?.FontWeight is FontWeight weight)
+        {
+            return weight;
+        }
+
+        return baseValue;
+    }
+
+    private object CoerceForeground(object baseValue)
+    {
+        if (GetValue(ForegroundResourceRefProperty) is Brush appearance)
+        {
+            return appearance;
+        }
+
+        if (ReferenceEquals(baseValue, UnsetMarkerBrush.Instance))
+        {
+            if (GetValue(DefaultForegroundResourceRefProperty) is Brush defaultForeground)
+            {
+                return defaultForeground;
+            }
+        }
+
+        return baseValue;
     }
-}
+}

src/Wpf.Ui/Controls/TextBlock/TextBlock.xaml

@@ -5,21 +5,28 @@
     All Rights Reserved.
 -->
 
-<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
+<ResourceDictionary
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:controls="clr-namespace:Wpf.Ui.Controls">
 
     <Style TargetType="{x:Type TextBlock}">
+        <!--
+            Attach default foreground resource ref so framework TextBlock can coerce to themed brush when unset.
 
-        <!--<Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}"/>-->
+            Explanation:
+            This Setter attaches a DynamicResource reference to the library's themed text brush
+            without changing dependency property or style precedence. If a TextBlock's Foreground
+            is explicitly set (local or via Style), that value remains authoritative. When Foreground
+            is not set, the framework will use the attached themed brush as a dynamic fallback,
+            and it will update automatically on theme/resource changes.
 
-        <!--  The Display option causes a large aliasing effect  -->
-        <!--<Setter Property="TextOptions.TextFormattingMode" Value="Ideal" />-->
-        <Setter Property="Background" Value="Transparent" />
-        <Setter Property="FontSize" Value="14" />
-        <Setter Property="Margin" Value="0" />
-        <Setter Property="Padding" Value="0" />
-        <Setter Property="Focusable" Value="False" />
-        <Setter Property="SnapsToDevicePixels" Value="True" />
-        <Setter Property="OverridesDefaultStyle" Value="True" />
+            Note:
+            If an app or control replaces the Style that sets the attached `controls:TextBlockHelper.DefaultForegroundResourceRef`
+            and the custom Style does not set this attached property, the library's themed foreground fallback will not apply.
+            In that case developers should reference the theme brush directly (for example via `{DynamicResource TextFillColorPrimaryBrush}`).
+        -->
+        <Setter Property="controls:TextBlockHelper.DefaultForegroundResourceRef" Value="{DynamicResource TextFillColorPrimaryBrush}" />
     </Style>
 
-</ResourceDictionary>
+</ResourceDictionary>