CmdPal: Enhance font icon classification and visuals (#41573)

## Summary of the Pull Request - Introduces `FontIconGlyphClassifier` for classifying emojis and symbols. - Correctly recognizes multi-codepoint glyphs (e.g., 🧙🏼‍♀️ *woman mage with medium-light skin tone*). - Explicitly disallows multi-glyph icons (they would overflow anyway). - Distinguishes between emojis and regular text characters (letters, numbers, symbols), since emojis are slightly larger and require different padding. - Recognizes Unicode [Variation Selectors](https://en.wikipedia.org/wiki/Variation_Selectors_(Unicode_block)) to enforce specific styles: VS15 (U+FE0E) for text style (monochrome) and VS16 (U+FE0F) for emoji style (color). This lets developers choose which variant to display. By default, characters with both representations render as text/monochrome (e.g., ▶ `\u25B6`): <img width="428" height="39" alt="image" src="https://github.com/user-attachments/assets/c5e6865f-61de-4f45-9f3a-4e15e5e5ceb8" /> - Invalid icons are displayed as a dashed circle so extension developers can spot issues, without being overly distracting if they slip into production. - Updates `IconPathConverter` to use the new classifier for improved icon handling. - Adds `SampleIconPage` to demonstrate various icon usages and classifications. - Adjusts icon alignment in `IconBox` so icons are centered. - Scales negative padding for emojis in `IconBox` with control size, fixing misalignment and clipping (noticeable in tags and the details pane hero image). - Applies negative padding to all font icons. This removes the need for classification in these cases and ensures symbols rendered below the baseline remain visible. Based on [microsoft/terminal#19143](https://github.com/microsoft/terminal/pull/19143): Co-authored-by: Dustin L. Howett <duhowett@microsoft.com> Pictures? Pictures! <img width="1912" height="2394" alt="image" src="https://github.com/user-attachments/assets/05a16309-b658-4f21-8f9d-9a3f20db6ad8" /> Keyboard and flag/country emojis may look a bit off, but that’s how they’re actually rendered: <img width="482" height="95" alt="image" src="https://github.com/user-attachments/assets/dc7d4d0d-3dc8-4df5-9b9f-9e977e7e989f" />  ## PR Checklist - [x] Closes: - #41489 - #41496 - [ ] **Communication:** I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected - [ ] **Tests:** Added/updated and all pass - [ ] **Localization:** All end-user-facing strings can be localized - [ ] **Dev docs:** Added/updated - [ ] **New binaries:** Added on the required places - [ ] [JSON for signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json) for new binaries - [ ] [WXS for installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs) for new binaries and localization folder - [ ] [YML for CI pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml) for new test projects - [ ] [YML for signed pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml) - [ ] **Documentation updated:** If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys) and link it here: #xxx  ## Detailed Description of the Pull Request / Additional comments  ## Validation Steps Performed
2026-04-05 10:46:33 +02:00 · 2025-09-03 20:17:52 +02:00
parent b71bbf89ce
commit 347c3f1efa
9 changed files with 532 additions and 51 deletions
--- a/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.cpp
+++ b/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.cpp
@@ -0,0 +1,177 @@
+#include "pch.h"
+#include "FontIconGlyphClassifier.h"
+#include "FontIconGlyphClassifier.g.cpp"
+
+#include <icu.h>
+#include <utility>
+
+namespace winrt::Microsoft::Terminal::UI::implementation
+{
+    namespace
+    {
+        // Check if the code point is in the Private Use Area range used by Fluent UI icons.
+        [[nodiscard]] constexpr bool _isFluentIconPua(const UChar32 cp) noexcept
+        {
+            static constexpr UChar32 _fluentIconsPrivateUseAreaStart = 0xE700;
+            static constexpr UChar32 _fluentIconsPrivateUseAreaEnd = 0xF8FF;
+            return cp >= _fluentIconsPrivateUseAreaStart && cp <= _fluentIconsPrivateUseAreaEnd;
+        }
+
+        // Determine if the given text (as a sequence of UChar code units) is emoji
+        [[nodiscard]] bool _isEmoji(const UChar* p, const int32_t length) noexcept
+        {
+            if (!p || length < 1)
+            {
+                return false;
+            }
+
+            // https://www.unicode.org/reports/tr51/#Emoji_Variation_Selector_Notes
+            constexpr UChar32 vs15CodePoint = 0xFE0E; // Variation Selectors 15: text variation selector
+            constexpr UChar32 vs16CodePoint = 0xFE0F; // Variation Selectors: 16 emoji variation selector
+
+            // Decode the first code point correctly (surrogate-safe)
+            int32_t i0{ 0 };
+            UChar32 first{ 0 };
+            U16_NEXT(p, i0, length, first);
+
+            for (int32_t i = 0; i < length;)
+            {
+                UChar32 cp{ 0 };
+                U16_NEXT(p, i, length, cp);
+
+                if (cp == vs16CodePoint) { return true; }
+                if (cp == vs15CodePoint) { return false; }
+            }
+
+            return !U_IS_SURROGATE(first) && u_hasBinaryProperty(first, UCHAR_EMOJI_PRESENTATION);
+        }
+    }
+
+    bool FontIconGlyphClassifier::IsLikelyToBeEmojiOrSymbolIcon(const hstring& text)
+    {
+        if (text.empty())
+        {
+            return false;
+        }
+
+        if (text.size() == 1 && !IS_HIGH_SURROGATE(text[0]))
+        {
+            // If it's a single code unit, it's definitely either zero or one grapheme clusters.
+            // If it turns out to be illegal Unicode, we don't really care.
+            return true;
+        }
+
+        if (text.size() >= 2 && text[0] <= 0x7F && text[1] <= 0x7F)
+        {
+            // Two adjacent ASCII characters (as seen in most file paths) aren't a single
+            // grapheme cluster.
+            return false;
+        }
+
+        // Use ICU to determine whether text is composed of a single grapheme cluster.
+        int32_t off{ 0 };
+        UErrorCode status{ U_ZERO_ERROR };
+
+        UBreakIterator* const bi{ ubrk_open(UBRK_CHARACTER,
+                                            nullptr,
+                                            reinterpret_cast<const UChar*>(text.data()),
+                                            static_cast<int>(text.size()),
+                                            &status) };
+        if (bi)
+        {
+            if (U_SUCCESS(status))
+            {
+                off = ubrk_next(bi);
+            }
+            ubrk_close(bi);
+        }
+        return std::cmp_equal(off, text.size());
+    }
+
+    FontIconGlyphKind FontIconGlyphClassifier::Classify(hstring const& text) noexcept
+    {
+        if (text.empty())
+        {
+            return FontIconGlyphKind::None;
+        }
+
+        const size_t textSize{ text.size() };
+        const auto* buffer{ reinterpret_cast<const UChar*>(text.c_str()) };
+
+        // Fast path 1: Single UTF-16 code unit (most common case)
+        if (textSize == 1)
+        {
+            const UChar ch{ buffer[0] };
+
+            if (IS_HIGH_SURROGATE(ch))
+            {
+                return FontIconGlyphKind::Invalid;
+            }
+
+            if (_isFluentIconPua(ch))
+            {
+                return FontIconGlyphKind::FluentSymbol;
+            }
+
+            if (_isEmoji(&ch, 1))
+            {
+                return FontIconGlyphKind::Emoji;
+            }
+
+            return FontIconGlyphKind::Other;
+        }
+
+        // Fast path 2: Common file path pattern - two ASCII printable characters
+        if (textSize >= 2 && buffer[0] <= 0x7F && buffer[1] <= 0x7F)
+        {
+            // Definitely multiple graphemes
+            return FontIconGlyphKind::Invalid;
+        }
+
+        // Expensive path: Use ICU to determine grapheme boundaries
+        UErrorCode status{ U_ZERO_ERROR };
+
+        UBreakIterator* bi{ ubrk_open(UBRK_CHARACTER,
+                                      nullptr,
+                                      buffer,
+                                      static_cast<int32_t>(textSize),
+                                      &status) };
+
+        if (U_FAILURE(status) || !bi)
+        {
+            return FontIconGlyphKind::Invalid;
+        }
+
+        const int32_t start{ ubrk_first(bi) };
+        const int32_t end{ ubrk_next(bi) }; // end of first grapheme
+        ubrk_close(bi);
+
+        // No graphemes found
+        if (end == UBRK_DONE || end <= start)
+        {
+            return FontIconGlyphKind::None;
+        }
+
+        // If there's more than one grapheme, it's not a valid icon glyph
+        if (std::cmp_not_equal(end, textSize))
+        {
+            return FontIconGlyphKind::Invalid;
+        }
+
+        // Exactly one grapheme: classify
+        const UChar* grapheme = buffer + start;
+        const int32_t graphemeLength = end - start;
+
+        if (graphemeLength == 1 && _isFluentIconPua(grapheme[0]))
+        {
+            return FontIconGlyphKind::FluentSymbol;
+        }
+
+        if (_isEmoji(grapheme, graphemeLength))
+        {
+            return FontIconGlyphKind::Emoji;
+        }
+
+        return FontIconGlyphKind::Other;
+    }
+}
--- a/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.h
+++ b/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.h
@@ -0,0 +1,18 @@
+#pragma once
+
+#include "FontIconGlyphClassifier.g.h"
+
+namespace winrt::Microsoft::Terminal::UI::implementation
+{
+    struct FontIconGlyphClassifier
+    {
+        [[nodiscard]] static bool IsLikelyToBeEmojiOrSymbolIcon(const winrt::hstring& text);
+
+        [[nodiscard]] static FontIconGlyphKind Classify(winrt::hstring const& text) noexcept;
+    };
+}
+
+namespace winrt::Microsoft::Terminal::UI::factory_implementation
+{
+    BASIC_FACTORY(FontIconGlyphClassifier);
+}
--- a/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.idl
+++ b/src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.idl
@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+namespace Microsoft.Terminal.UI
+{
+    /// <summary>
+    /// Categorizes the type of a single grapheme cluster or input text.
+    /// Used to determine how the input should be handled or rendered (for example,
+    /// whether it should be treated as an emoji, an icon from a symbol font, plain text, etc.).
+    /// </summary>
+    enum FontIconGlyphKind
+    {
+        /// <summary>
+        /// Input is invalid or contains more than one grapheme cluster and therefore cannot be
+        /// treated as a single symbol. Typical for multi-character text like file paths
+        /// or composed strings that include separators.
+        /// </summary>
+        Invalid = -1,
+
+        /// <summary>
+        /// No grapheme present (empty string). Indicates absence of a symbol.
+        /// </summary>
+        None = 0,
+
+        /// <summary>
+        /// A single emoji grapheme cluster. This may consist of multiple Unicode code
+        /// points combined into one visible glyph (e.g., emoji with modifiers or ZWJ sequences).
+        /// </summary>
+        Emoji = 1,
+
+        /// <summary>
+        /// A single glyph from the Segoe Fluent Icons / MDL2 Assets Private Use Area (PUA),
+        /// typically in the Unicode range U+E700–U+F8FF. These are font-based icons (Fluent/MDL2).
+        /// </summary>
+        FluentSymbol = 2,
+
+        /// <summary>
+        /// A single non-emoji grapheme that is not a Fluent/MDL2 PUA symbol.
+        /// Covers ordinary characters, letters, numbers, or other single glyph symbols.
+        /// </summary>
+        Other = 3,
+    };
+
+    /// <summary>
+    /// Static utility class for text and icon analysis
+    /// </summary>
+    static runtimeclass FontIconGlyphClassifier
+    {
+        /// <summary>
+        /// Determines if text represents a single grapheme cluster (emoji/symbol icon).
+        /// Uses ICU for Unicode boundary detection to distinguish icons from file paths.
+        /// </summary>
+        /// <param name="text">Text to analyze</param>
+        /// <returns>True if single grapheme cluster, false for multi-character text or paths</returns>
+        static Boolean IsLikelyToBeEmojiOrSymbolIcon(String text);
+
+        /// <summary>
+        /// Classifies the input into a glyph kind suitable for icon or text rendering.
+        /// </summary>
+        static FontIconGlyphKind Classify(String text);
+    };
+}
--- a/src/modules/cmdpal/Microsoft.Terminal.UI/IconPathConverter.cpp
+++ b/src/modules/cmdpal/Microsoft.Terminal.UI/IconPathConverter.cpp
@@ -2,7 +2,7 @@
 #include "IconPathConverter.h"
 #include "IconPathConverter.g.cpp"

-// #include "Utils.h"
+ #include "FontIconGlyphClassifier.h"

 #include <Shlobj.h>
 #include <Shlobj_core.h>
@@ -110,7 +110,7 @@ namespace winrt::Microsoft::Terminal::UI::implementation
                if (til::equals_insensitive_ascii(iconUri.Extension(), L".svg"))
                {
                    typename ImageIconSource<TIconSource>::type iconSource;
-                    winrt::Microsoft::UI::Xaml::Media::Imaging::SvgImageSource source{ iconUri };	
+                    winrt::Microsoft::UI::Xaml::Media::Imaging::SvgImageSource source{ iconUri };
                    iconSource.ImageSource(source);
                    return iconSource;
                }
@@ -169,41 +169,46 @@ namespace winrt::Microsoft::Terminal::UI::implementation

            // If we fail to set the icon source using the "icon" as a path,
            // let's try it as a symbol/emoji.
-            //
-            // Anything longer than 2 wchar_t's _isn't_ an emoji or symbol, so
-            // don't do this if it's just an invalid path.
-            if (!iconSource && iconPath.size() <= 2)
+            if (!iconSource)
            {
                try
                {
-                    typename FontIconSource<TIconSource>::type icon;
-                    const auto ch = til::at(iconPath, 0);
+                    const auto glyph_kind = FontIconGlyphClassifier::Classify(iconPath);

-                    // The range of MDL2 Icons isn't explicitly defined, but
-                    // we're using this based off the table on:
-                    // https://docs.microsoft.com/en-us/windows/uwp/design/style/segoe-ui-symbol-font
-                    const auto isMDL2Icon = ch >= L'\uE700' && ch <= L'\uF8FF';
-                    if (isMDL2Icon)
+                    winrt::hstring family;
+                    if (glyph_kind == FontIconGlyphKind::Invalid)
                    {
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ L"Segoe Fluent Icons, Segoe MDL2 Assets" });
+                        family = L"Segoe UI";
                    }
                    else if (!fontFamily.empty())
                    {
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ fontFamily });
-
+                        family = fontFamily;
+                    }
+                    else if (glyph_kind == FontIconGlyphKind::FluentSymbol)
+                    {
+                        family = L"Segoe Fluent Icons, Segoe MDL2 Assets";
+                    }
+                    else if (glyph_kind == FontIconGlyphKind::Emoji)
+                    {
+                        // Emoji and other symbols go in the Segoe UI Emoji font.
+                        // Some emojis (e.g. 2️⃣) would be rendered as emoji glyphs otherwise.
+                        family = L"Segoe UI Emoji, Segoe UI";
                    }
                    else
                    {
-                        // Note: you _do_ need to manually set the font here.
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ L"Segoe UI" });
+                        family = L"Segoe UI";
                    }
+
+                    typename FontIconSource<TIconSource>::type icon;
+                    icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ family });
                    icon.FontSize(targetSize);
-                    icon.Glyph(iconPath);
+                    icon.Glyph(glyph_kind == FontIconGlyphKind::Invalid ? L"\u25CC" : iconPath);
                    iconSource = icon;
                }
                CATCH_LOG();
            }
        }
+
        if (!iconSource)
        {
            // Set the default IconSource to a BitmapIconSource with a null source
@@ -326,7 +331,7 @@ namespace winrt::Microsoft::Terminal::UI::implementation
    }

    static winrt::Microsoft::UI::Xaml::Media::Imaging::SoftwareBitmapSource _getImageIconSourceForBinary(std::wstring_view iconPathWithoutIndex,
-                                                                                                         int index, 
+                                                                                                         int index,
                                                                                                         int targetSize)
    {
        // Try:
--- a/src/modules/cmdpal/Microsoft.Terminal.UI/Microsoft.Terminal.UI.vcxproj
+++ b/src/modules/cmdpal/Microsoft.Terminal.UI/Microsoft.Terminal.UI.vcxproj
@@ -159,6 +159,9 @@
    <ClInclude Include="ResourceString.h">
      <DependentUpon>ResourceString.idl</DependentUpon>
    </ClInclude>
+    <ClInclude Include="FontIconGlyphClassifier.h">
+      <DependentUpon>FontIconGlyphClassifier.idl</DependentUpon>
+    </ClInclude>
  </ItemGroup>
  <ItemGroup>
    <ClCompile Include="init.cpp" />
@@ -178,6 +181,9 @@
      <DependentUpon>ResourceString.idl</DependentUpon>
    </ClCompile>
    <ClCompile Include="$(GeneratedFilesDir)module.g.cpp" />
+    <ClCompile Include="FontIconGlyphClassifier.cpp">
+      <DependentUpon>FontIconGlyphClassifier.idl</DependentUpon>
+    </ClCompile>
  </ItemGroup>
  <ItemGroup>
    <Midl Include="Converters.idl" />
@@ -185,6 +191,7 @@
    <Midl Include="RunHistory.idl" />
    <Midl Include="IDirectKeyListener.idl" />
    <Midl Include="ResourceString.idl" />
+    <Midl Include="FontIconGlyphClassifier.idl" />
  </ItemGroup>
  <ItemGroup>
    <None Include="packages.config" />