Add tutorial for creating a search box with an icon

data/docs/ui-wpf-modern/06. tutorials/# creating-a-search-box/index.en-US.mdx

@@ -0,0 +1,120 @@
+---
+description: "Learn how to build a search box, from a simple icon overlay to a fully working AutoSuggestBox with suggestions."
+---
+
+# Creating a Search Box with an Icon
+
+iNKORE.UI.WPF.Modern doesn't ship a dedicated `SearchBox` control, but you can get the classic search box look and behavior in two ways: layering an icon on top of a plain TextBox, or using the built-in [AutoSuggestBox](%BASE_NAME%/components/text/autosuggest-box) control together with its `QueryIcon` property. This tutorial walks through both, starting with the simple visual-only version and then upgrading it to a fully working search experience with suggestions.
+
+## Step 1: A simple TextBox with a search icon
+
+If you only need the visual style, with no suggestions or autocomplete, you can place a `FontIcon` on top of a `TextBox` using a Grid, and pad the TextBox so typed text doesn't sit underneath the icon.
+
+### Overlay the icon on the TextBox
+
+```xml
+<Grid Width="240">
+    <TextBox x:Name="SearchTextBox"
+             Padding="30,6,6,6"
+             ui:ControlHelper.PlaceholderText="Search" />
+    <ui:FontIcon Icon="{x:Static ui:SegoeFluentIcons.Search}"
+                 HorizontalAlignment="Left"
+                 Margin="8,0,0,0"
+                 Foreground="{DynamicResource TextFillColorSecondaryBrush}"
+                 IsHitTestVisible="False" />
+</Grid>
+```
+
+A few things make this work:
+
+- The TextBox and the FontIcon share the same cell of the Grid, so the icon is drawn on top of it.
+
+- `Padding="30,6,6,6"` leaves room on the left so the caret and typed text start after the icon instead of underneath it. Adjust the first number to match the size of the icon you use.
+
+- `IsHitTestVisible="False"` on the icon lets clicks pass through to the TextBox underneath, so the control still behaves like a single input instead of two separate hit areas.
+
+- `ui:ControlHelper.PlaceholderText` adds a "Search" hint that disappears once the user starts typing.
+
+This approach is purely visual. Pressing <kbd>Enter</kbd> or typing doesn't trigger a search on its own, you would still need to handle the TextBox's `TextChanged` or `KeyDown` event yourself. It's a good fit for lightweight cases like a header search field, but it ends up reinventing behavior that [AutoSuggestBox](%BASE_NAME%/components/text/autosuggest-box) already provides.
+
+## Step 2: Upgrade to AutoSuggestBox
+
+When you need suggestions while typing, plus a query that can be submitted with <kbd>Enter</kbd> or by clicking the icon, [AutoSuggestBox](%BASE_NAME%/components/text/autosuggest-box) is the better fit. It's built for exactly this scenario, and already comes with keyboard and accessibility support for the suggestion list.
+
+### Add an AutoSuggestBox with a search icon
+
+Setting **QueryIcon** turns the icon into a button. Clicking it, or pressing <kbd>Enter</kbd> while the AutoSuggestBox is focused, raises the **QuerySubmitted** event, the same way clicking the query button in a native search box would.
+
+```xml
+<ui:AutoSuggestBox x:Name="SearchBox"
+                    Width="240"
+                    PlaceholderText="Search"
+                    TextChanged="SearchBox_TextChanged"
+                    QuerySubmitted="SearchBox_QuerySubmitted">
+    <ui:AutoSuggestBox.QueryIcon>
+        <ui:FontIcon Icon="{x:Static ui:SegoeFluentIcons.Search}" />
+    </ui:AutoSuggestBox.QueryIcon>
+</ui:AutoSuggestBox>
+```
+
+### Populate suggestions while typing
+
+Handle **TextChanged**, and only react when the change was actually caused by the user typing, rather than a suggestion being chosen or you setting `Text` from code, by checking `args.Reason`:
+
+```csharp
+private void SearchBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
+{
+    if (args.Reason == AutoSuggestionBoxTextChangeReason.UserInput)
+    {
+        sender.ItemsSource = Items
+            .Where(item => item.IndexOf(sender.Text, StringComparison.CurrentCultureIgnoreCase) >= 0)
+            .ToList();
+    }
+}
+```
+
+### Handle the submitted query
+
+**QuerySubmitted** fires when the user presses <kbd>Enter</kbd>, clicks the query icon, or picks a suggestion from the list. `args.ChosenSuggestion` tells you whether a suggestion was picked; otherwise, treat `args.QueryText` as a plain search term:
+
+```csharp
+private void SearchBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
+{
+    if (args.ChosenSuggestion != null)
+    {
+        Navigate(args.ChosenSuggestion);
+    }
+    else if (!string.IsNullOrEmpty(args.QueryText))
+    {
+        Search(args.QueryText);
+    }
+}
+```
+
+## Remarks
+
+### Which approach should I use?
+
+- Use the plain TextBox with an icon overlay when you only need the look of a search box, and you're already handling the actual searching some other way, for example a separate search button, or filtering as-you-type without a suggestion dropdown.
+
+- Use AutoSuggestBox with **QueryIcon** when you want suggestions, keyboard navigation through the suggestion list, and a query button that behaves consistently with the rest of your app.
+
+### Icons
+
+`SegoeFluentIcons.Search` is only one of the icons bundled with iNKORE.UI.WPF.Modern. You can use `FontIcon` with any other glyph, or swap it for a `BitmapIcon` or `PathIcon` if you need a custom look.
+
+## See also
+
+### Related controls
+
+- [AutoSuggestBox](%BASE_NAME%/components/text/autosuggest-box)
+
+- [TextBox](%BASE_NAME%/components/text/text-box)
+
+- [FontIcon](%BASE_NAME%/components/media/font-icon)
+
+### Microsoft Learn
+
+- [AutoSuggestBox Class (WinRT)](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.autosuggestbox)
+
+- [Search - Windows apps](https://learn.microsoft.com/en-us/windows/apps/design/controls/search)