Fix three defects found reviewing the sample index exporter

Resolve option bindings whose path carries a cast. x:Bind spells a cast as a
parenthesised type ahead of the path, as in (x:Int32)Columns. Reading the cast as
part of the path made the option lookup miss while the whole-word scan still
matched, so a binding with a perfectly readable default was treated as having
none and its attribute was removed. UniformGrid lost its spans and first column,
which is what that sample exists to demonstrate. An attached property path such
as (Grid.Row) is a path rather than a cast and is left alone.

Stop reading commented-out markup as live. A comment ends at --> and a CDATA
section at ]]>, not at the first >. Three scans stopped at the first one and
resumed inside the comment, so an x:Name in a comment counted as a declared
element, an option binding in a comment was rewritten in the published text, and
a prefix used only in a comment was published as a required import. An
apostrophe in comment prose also opened a quote that never closed, abandoning
prefix stripping for the rest of the fragment. Three samples carry comments of
the shape that triggers this today, and are unaffected only because none of them
happens to contain a name or a binding.

Report a duplicate entry id instead of renaming one. The bare slug went to
whichever document was read first and the loser was qualified with its component
name, so adding a component that sorted earlier would silently change the id of
an entry that had already shipped. An id is published as stable, so a collision
is now an error a contributor settles by renaming, and every existing id stays
where it is.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Jaylyn-Barbee

catalog/toolkit-samples.json

@@ -3096,20 +3096,22 @@
         {
           "header": "UniformGrid",
           "details": "Each cell in the grid, by default, will be the same size. If no value for Rows and Columns are provided, the UniformGrid will create a square layout based on the total number of visible items. If a fixed size is provided for Rows and Columns then additional children that can\u0027t fit in the number of cells provided won\u0027t be displayed. In addition, UniformGrid is a Panel instead of an ItemsControl. As such, it could be used as a Panel in such ItemsControls. The UniformGrid inherits from Grid and provides many additional features compared to its predecessor, see more below.",
-          "xaml": "\u003CGrid\u003E\n    \u003Ccontrols:UniformGrid\u003E\n\n        \u003CBorder Grid.Row=\u00221\u0022\n                Grid.Column=\u00221\u0022\n                Background=\u0022AliceBlue\u0022\u003E\n            \u003CTextBlock Text=\u00221\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Cornsilk\u0022\u003E\n            \u003CTextBlock Text=\u00222\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022DarkSalmon\u0022\u003E\n            \u003CTextBlock Text=\u00223\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Gainsboro\u0022\u003E\n            \u003CTextBlock Text=\u00224\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022LightBlue\u0022\u003E\n            \u003CTextBlock Text=\u00225\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022MediumAquamarine\u0022\u003E\n            \u003CTextBlock Text=\u00226\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022MistyRose\u0022\u003E\n            \u003CTextBlock Text=\u00227\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022LightCyan\u0022\u003E\n            \u003CTextBlock Text=\u00228\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Salmon\u0022\u003E\n            \u003CTextBlock Text=\u00229\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Goldenrod\u0022\u003E\n            \u003CTextBlock Text=\u002210\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Pink\u0022\u003E\n            \u003CTextBlock Text=\u002211\u0022 /\u003E\n        \u003C/Border\u003E\n    \u003C/controls:UniformGrid\u003E\n\u003C/Grid\u003E",
+          "xaml": "\u003CGrid\u003E\n    \u003Ccontrols:UniformGrid Columns=\u00220\u0022\n                          FirstColumn=\u00221\u0022\n                          Rows=\u00220\u0022\u003E\n\n        \u003CBorder Grid.Row=\u00221\u0022\n                Grid.RowSpan=\u00222\u0022\n                Grid.Column=\u00221\u0022\n                Grid.ColumnSpan=\u00222\u0022\n                Background=\u0022AliceBlue\u0022\u003E\n            \u003CTextBlock Text=\u00221\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Cornsilk\u0022\u003E\n            \u003CTextBlock Text=\u00222\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022DarkSalmon\u0022\u003E\n            \u003CTextBlock Text=\u00223\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Gainsboro\u0022\u003E\n            \u003CTextBlock Text=\u00224\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022LightBlue\u0022\u003E\n            \u003CTextBlock Text=\u00225\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022MediumAquamarine\u0022\u003E\n            \u003CTextBlock Text=\u00226\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022MistyRose\u0022\u003E\n            \u003CTextBlock Text=\u00227\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022LightCyan\u0022\u003E\n            \u003CTextBlock Text=\u00228\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Salmon\u0022\u003E\n            \u003CTextBlock Text=\u00229\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Goldenrod\u0022\u003E\n            \u003CTextBlock Text=\u002210\u0022 /\u003E\n        \u003C/Border\u003E\n        \u003CBorder Background=\u0022Pink\u0022\u003E\n            \u003CTextBlock Text=\u002211\u0022 /\u003E\n        \u003C/Border\u003E\n    \u003C/controls:UniformGrid\u003E\n\u003C/Grid\u003E",
           "xmlnsImports": [
             "xmlns:controls=\u0022using:CommunityToolkit.WinUI.Controls\u0022"
           ],
           "toolkit": {
             "sampleId": "UniformGridSample",
             "sourcePath": "components/Primitives/samples/UniformGridSample.xaml",
+            "optionsResolved": [
+              "Columns=0",
+              "FirstColumn=1",
+              "Item1ColumnSpan=2",
+              "Item1RowSpan=2",
+              "Rows=0"
+            ],
             "optionBindingsDropped": [
-              "Columns",
-              "FirstColumn",
-              "Grid.ColumnSpan",
-              "Grid.RowSpan",
-              "Orientation",
-              "Rows"
+              "Orientation"
             ]
           }
         }
@@ -3239,7 +3241,7 @@
         {
           "header": "RadialGauge",
           "details": "This control will make data visualizations and dashboards more engaging with rich style and interactivity. The round gauges are powerful, easy to use, and highly configurable to present dashboards capable of displaying clocks, industrial panels, automotive dashboards, and even aircraft cockpits. The Radial Gauge supports animated transitions between configuration states. The control gradually animates as it redraws changes to the needle, needle position, scale range, color range, and more.",
-          "xaml": "\u003CStackPanel HorizontalAlignment=\u0022Center\u0022\n            VerticalAlignment=\u0022Center\u0022\n            Orientation=\u0022Horizontal\u0022\u003E\n    \u003Ccontrols:RadialGauge x:Name=\u0022RadialGauge\u0022\n                          Width=\u0022280\u0022\n                          IsEnabled=\u0022True\u0022\n                          IsInteractive=\u0022True\u0022\n                          Maximum=\u0022240\u0022\n                          Minimum=\u00220\u0022\n                          NeedleLength=\u002260\u0022\n                          NeedleWidth=\u00224\u0022\n                          ScalePadding=\u00220\u0022\n                          ScaleTickWidth=\u00220\u0022\n                          ScaleWidth=\u002212\u0022\n                          StepSize=\u002230\u0022\n                          TickLength=\u00226\u0022\n                          TickPadding=\u002224\u0022\n                          TickWidth=\u00222\u0022\n                          ValueStringFormat=\u0022N0\u0022\n                          Value=\u0022120\u0022 /\u003E\n\u003C/StackPanel\u003E",
+          "xaml": "\u003CStackPanel HorizontalAlignment=\u0022Center\u0022\n            VerticalAlignment=\u0022Center\u0022\n            Orientation=\u0022Horizontal\u0022\u003E\n    \u003Ccontrols:RadialGauge x:Name=\u0022RadialGauge\u0022\n                          Width=\u0022280\u0022\n                          IsEnabled=\u0022True\u0022\n                          IsInteractive=\u0022True\u0022\n                          MaxAngle=\u0022150\u0022\n                          Maximum=\u0022240\u0022\n                          MinAngle=\u0022-150\u0022\n                          Minimum=\u00220\u0022\n                          NeedleLength=\u002260\u0022\n                          NeedleWidth=\u00224\u0022\n                          ScalePadding=\u00220\u0022\n                          ScaleTickWidth=\u00220\u0022\n                          ScaleWidth=\u002212\u0022\n                          StepSize=\u002230\u0022\n                          TickLength=\u00226\u0022\n                          TickPadding=\u002224\u0022\n                          TickSpacing=\u002215\u0022\n                          TickWidth=\u00222\u0022\n                          ValueStringFormat=\u0022N0\u0022\n                          Value=\u0022120\u0022 /\u003E\n\u003C/StackPanel\u003E",
           "xmlnsImports": [
             "xmlns:controls=\u0022using:CommunityToolkit.WinUI.Controls\u0022"
           ],
@@ -3249,6 +3251,8 @@
             "optionsResolved": [
               "Enabled=True",
               "IsInteractive=True",
+              "MaxAngle=150",
+              "MinAngle=-150",
               "NeedleLength=60",
               "NeedleWidth=4",
               "ScalePadding=0",
@@ -3257,13 +3261,9 @@
               "StepSize=30",
               "TickLength=6",
               "TickPadding=24",
+              "TickSpacing=15",
               "TickWidth=2",
               "Value=120"
-            ],
-            "optionBindingsDropped": [
-              "MaxAngle",
-              "MinAngle",
-              "TickSpacing"
             ]
           }
         }

tools/SampleIndexExporter.Tests/ContractConformanceTests.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using System.Text.RegularExpressions;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 namespace CommunityToolkit.SampleIndex.Tests;
@@ -41,6 +42,29 @@ public void EntryIdsAreUniqueAndUrlSafe()
             "Entry ids must be lowercase letters, digits and hyphens:\n  " + string.Join("\n  ", unsafeIds));
     }
 
+    [TestMethod]
+    public void EntryIdDependsOnlyOnItsOwnDocumentFileName()
+    {
+        // An id is published as stable, so it has to be a function of the entry's own document
+        // and nothing else. Deriving it from the set of entries present — qualifying whichever
+        // of two colliding file names happened to be read second — would silently rename an
+        // entry that already shipped the day an unrelated component was added. A collision is
+        // reported as an error instead, so this invariant holds by construction.
+        var unexpected = RepositoryIndex.Index.Controls
+            .Where(c => c.Toolkit?.DocumentPath is { } path && c.Id != ExpectedId(path))
+            .Select(c => $"{c.Id} (expected '{ExpectedId(c.Toolkit!.DocumentPath!)}' from {c.Toolkit!.DocumentPath})")
+            .ToList();
+
+        Assert.AreEqual(
+            0,
+            unexpected.Count,
+            "Entry ids must be derived from their own documentation file name alone:\n  "
+                + string.Join("\n  ", unexpected));
+    }
+
+    private static string ExpectedId(string documentPath) =>
+        Regex.Replace(Path.GetFileNameWithoutExtension(documentPath).ToLowerInvariant(), "[^a-z0-9]+", "-").Trim('-');
+
     [TestMethod]
     public void EveryEntryHasANameAndSourceDocument()
     {

tools/SampleIndexExporter.Tests/XamlFragmentTests.cs

@@ -233,6 +233,109 @@ public void PageResourcesOpenUpASelfClosingHostElement()
         StringAssert.Contains(result.Xaml!, "</Border>");
     }
 
+    [TestMethod]
+    public void ACastInABindingPathDoesNotHideTheOption()
+    {
+        // x:Bind writes a cast as a parenthesised type ahead of the path. Reading the cast as
+        // part of the path made the lookup miss, so a binding with a readable default was
+        // treated as having none and UniformGrid published without its spans or first column.
+        var result = Extract(
+            "<Border Grid.RowSpan=\"{x:Bind (x:Int32)Item1RowSpan, Mode=OneWay}\" />",
+            new SampleOption("Item1RowSpan", "2"));
+
+        Assert.IsNull(result.Error);
+        StringAssert.Contains(result.Xaml!, "Grid.RowSpan=\"2\"");
+        CollectionAssert.Contains(result.OptionsResolved, "Item1RowSpan=2");
+        Assert.AreEqual(0, result.OptionBindingsDropped.Count);
+    }
+
+    [TestMethod]
+    public void AnAttachedPropertyPathIsNotMistakenForACast()
+    {
+        // {Binding (Grid.Row)} is a path, not a cast: the parentheses are the whole path and
+        // there is nothing after them. Stripping them would turn the path into the empty
+        // string and lose the binding.
+        var result = Extract("<Border Tag=\"{Binding (Grid.Row)}\" />");
+
+        Assert.IsNull(result.Error);
+        StringAssert.Contains(result.Xaml!, "{Binding (Grid.Row)}");
+    }
+
+    [TestMethod]
+    public void MarkupInsideACommentIsNotRewritten()
+    {
+        // A comment ends at '-->', not at the first '>'. Stopping at the first one resumed the
+        // scan inside the comment — here, straight after the <StackPanel> start tag — and
+        // edited the author's commented-out alternative as though it were live markup.
+        var result = Extract(
+            """
+            <!--<StackPanel>
+                <Button IsEnabled="{x:Bind IsCardEnabled}" />
+            </StackPanel>-->
+            <Border Background="Red" />
+            """,
+            new SampleOption("IsCardEnabled", "True"));
+
+        Assert.IsNull(result.Error);
+        StringAssert.Contains(result.Xaml!, "<Button IsEnabled=\"{x:Bind IsCardEnabled}\" />");
+        Assert.AreEqual(0, result.OptionsResolved.Count);
+        Assert.AreEqual(0, result.OptionBindingsDropped.Count);
+    }
+
+    [TestMethod]
+    public void AnElementNameInsideACommentDoesNotCountAsDeclared()
+    {
+        // The commented-out element does not exist, so the binding that names it is dangling
+        // and its attribute has to go. Reading the comment as markup would publish a binding
+        // pointing at nothing.
+        var result = Extract(
+            """
+            <!--<StackPanel>
+                <TextBox x:Name="Source" Text="Hi" />
+            </StackPanel>-->
+            <TextBlock Text="{Binding Text, ElementName=Source}" />
+            """);
+
+        Assert.IsNull(result.Error);
+        Assert.IsFalse(result.Xaml!.Contains("ElementName=Source", StringComparison.Ordinal));
+    }
+
+    [TestMethod]
+    public void APrefixUsedOnlyInsideACommentIsNotPublishedAsAnImport()
+    {
+        // An import tells the reader to reference a package. One needed only by markup the
+        // author commented out is a package the published fragment does not use.
+        var result = Extract(
+            """
+            <!--<Border Background="{controls:SomeExtension}" />-->
+            <Border Background="Red" />
+            """);
+
+        Assert.AreEqual(0, result.XmlnsImports.Count);
+    }
+
+    [TestMethod]
+    public void AnApostropheInACommentDoesNotSwallowTheRestOfTheFragment()
+    {
+        // The prefix stripper tracks quotes so it does not stop at a '>' inside an attribute
+        // value. Prose in a comment is not attribute values, and reading it as such opened a
+        // quote that never closed, abandoning the rest of the fragment.
+        var result = XamlFragment.Extract(
+            """
+            <Page x:Class="Sample.MySample"
+                  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+                  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+                  xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+            <!-- The win: prefix doesn't survive extraction. -->
+            <win:TextBox Text="Hi" />
+            </Page>
+            """,
+            []);
+
+        Assert.IsNull(result.Error);
+        StringAssert.Contains(result.Xaml!, "<TextBox Text=\"Hi\" />");
+    }
+
     [TestMethod]
     public void UnsettledBindingsAcceptsMarkupWithNoBindings()
     {

tools/SampleIndexExporter/IndexGenerator.cs

@@ -165,7 +165,7 @@ private static List<string> GeneratedKeywords(MarkdownDocument document)
         List<WithheldSample> withheld,
         Dictionary<string, string> usedIds)
     {
-        var id = UniqueId(document, component, issues, usedIds);
+        var id = UniqueId(document, issues, usedIds);
         if (id is null)
         {
             return null;
@@ -361,16 +361,21 @@ private static Dictionary<string, SampleDeclaration> ReadDeclarations(
     }
 
     /// <summary>
-    /// Derive the entry's identifier from the documentation file name, and keep it unique.
+    /// Derive the entry's identifier from the documentation file name.
     /// </summary>
     /// <remarks>
     /// The file name rather than the title, because consumers key sample ids off this and a
-    /// title is prose that gets reworded. When two components document the same name, the
-    /// component qualifies the second one rather than either silently winning.
+    /// title is prose that gets reworded.
+    ///
+    /// <para>Two components documenting the same file name is reported rather than resolved.
+    /// Qualifying one of them with its component name would have to pick which one, and any
+    /// rule for picking depends on the set of components present — so adding a component could
+    /// change the id of an entry that already shipped, which is the one thing an identifier
+    /// documented as stable must never do. A collision is a build failure a contributor settles
+    /// by renaming, and every existing id stays where it is.</para>
     /// </remarks>
     private static string? UniqueId(
         MarkdownDocument document,
-        string component,
         List<IndexIssue> issues,
         Dictionary<string, string> usedIds)
     {
@@ -382,17 +387,10 @@ private static Dictionary<string, SampleDeclaration> ReadDeclarations(
             return id;
         }
 
-        var qualified = $"{Slug(component)}-{id}";
-        if (!usedIds.TryGetValue(qualified, out owner))
-        {
-            usedIds[qualified] = document.RelativePath;
-            return qualified;
-        }
-
         issues.Add(new IndexIssue(
             IssueSeverity.Error,
             document.RelativePath,
-            $"entry id '{qualified}' is already used by {owner}. Rename one of the documentation files."));
+            $"entry id '{id}' is already used by {owner}. Rename one of the documentation files."));
 
         return null;
     }