DRAFT [dev-v5] Add FluentAutocomplete

.editorconfig

@@ -109,6 +109,8 @@ indent_size = 4
 end_of_line = lf
 
 [*.{razor,cshtml}]
+indent_size = 4
+indent_style = space
 charset = utf-8-bom
 
 [*.{cs,vb}]

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Autocomplete/DebugPages/AutocompleteComparer.razor

@@ -0,0 +1,66 @@
+@page "/Lists/Autocomplete/Debug/Comparer"
+
+<div>Selected: <b>@string.Join("; ", Selected.Select(x => x.Name))</b></div>
+
+<FluentAutocomplete TOption="MyUser" 
+                    TValue="int" 
+                    Width="100%" 
+                    Label="Name" 
+                    Placeholder="Name"
+                    OptionText="(option) => option.Name" 
+                    OptionValue="(option) => option.UserId" 
+                    OptionSelectedComparer="MyComparer.Instance"
+                    OnOptionsSearch="@OnSearchAsync" 
+                    @bind-SelectedItems="@Selected" />
+
+@code
+{
+    IEnumerable<MyUser> Selected { get; set; } = [];
+
+    Task OnSearchAsync(OptionsSearchEventArgs<MyUser> e)
+    {
+        e.Items =
+        [
+            new MyUser
+            {
+                UserId = 1,
+                Name = "Marvin Klein"
+            },
+            new MyUser
+            {
+                UserId = 2,
+                Name = "Denis Voituron"
+            },
+    ];
+
+        return Task.CompletedTask;
+    }
+
+    class MyUser
+    {
+        public int UserId { get; set; }
+        public string Name { get; set; } = string.Empty;
+    }
+
+    class MyComparer : IEqualityComparer<MyUser>
+    {
+        public static readonly MyComparer Instance = new MyComparer();
+
+        public bool Equals(MyUser? x, MyUser? y)
+        {
+            if (ReferenceEquals(x, y))
+            {
+                return true;
+            }
+
+            if (x is null || y is null)
+            {
+                return false;
+            }
+
+            return x.UserId == y.UserId;
+        }
+
+        public int GetHashCode(MyUser obj) => obj.UserId.GetHashCode();
+    }
+}

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Autocomplete/Examples/AutocompleteCustomized.razor

@@ -0,0 +1,57 @@
+@using static FluentUI.Demo.SampleData.Olympics2024
+
+<div>Selected: <b>@string.Join("; ", SelectedCountries.Select(c => c.Name))</b></div>
+<div>Search Text: <b>@SearchText</b></div>
+
+<FluentAutocomplete TOption="Country"
+                    TValue="string"
+                    Width="100%"
+                    Label="Select countries"
+                    Placeholder="Type to search..."
+                    ShowProgressIndicator="@ShowProgressIndicator"                    
+                    MaxAutoHeight="@((MaxAutoHeight) ? "unset" : null)"
+                    OnOptionsSearch="@OnSearchAsync"
+                    OptionText="@(item => item.Name)"
+                    MaxSelectedWidth="@(MaxSelectedWidth ? "40px" : null)"
+                    ShowDismiss="@ShowDismiss"
+                    @bind-Value="@SearchText"
+                    @bind-SelectedItems="@SelectedCountries">
+    <OptionTemplate>
+        <FluentStack Style="pointer-events: none;" VerticalAlignment="VerticalAlignment.Center">
+            <FluentAvatar Image="@context.Flag()"
+                          Name="@context.Name" 
+                          Size="AvatarSize.Size20" />
+            <FluentText Margin="@Margin.Left4">
+                @context.Name
+            </FluentText>
+        </FluentStack>
+    </OptionTemplate>
+</FluentAutocomplete>
+
+<FluentStack Orientation="Orientation.Vertical">
+    <FluentSwitch @bind-Value="@ShowProgressIndicator" Label="Show progress indicator" />
+    <FluentSwitch @bind-Value="@MaxAutoHeight" Label="Auto height" />
+    <FluentSwitch @bind-Value="@MaxSelectedWidth" Label="Set a max selected width (40px)" />
+    <FluentSwitch @bind-Value="@ShowDismiss" Label="Show search or dismiss button" />
+</FluentStack>
+
+@code
+{
+    bool ShowProgressIndicator { get; set; }
+    bool MaxAutoHeight { get; set; }
+    bool MaxSelectedWidth { get; set; }
+    bool ShowDismiss { get; set; } = true;
+    string? SearchText { get; set; }
+    IEnumerable<Country> SelectedCountries { get; set; } = [];
+
+    async Task OnSearchAsync(OptionsSearchEventArgs<Country> e)
+    {
+        if (ShowProgressIndicator)
+        {
+            await Task.Delay(500); // Simulate async search
+        }
+
+        e.Items = Countries.Where(i => i.Name.StartsWith(e.Text, StringComparison.OrdinalIgnoreCase))
+                           .OrderBy(i => i.Name);
+    }
+}

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Autocomplete/Examples/AutocompleteDefault.razor

@@ -0,0 +1,25 @@
+@using static FluentUI.Demo.SampleData.Olympics2024
+
+<div>Selected: <b>@string.Join("; ", SelectedCountries.Select(c => c.Name))</b></div>
+
+<FluentAutocomplete TOption="Country"
+                    TValue="string"
+                    Width="100%"
+                    Label="Select countries"
+                    Placeholder="Type to search..."
+                    OnOptionsSearch="@OnSearchAsync"
+                    OptionText="@(item => item.Name)"
+                    OptionDisabled="@(e => e.Code == "au")"
+                    @bind-SelectedItems="@SelectedCountries" />
+@code
+{
+    IEnumerable<Country> SelectedCountries { get; set; } = [];
+
+    Task OnSearchAsync(OptionsSearchEventArgs<Country> e)
+    {
+        e.Items = Countries.Where(i => i.Name.StartsWith(e.Text, StringComparison.OrdinalIgnoreCase))
+                           .OrderBy(i => i.Name);
+
+        return Task.CompletedTask;
+    }
+}

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Autocomplete/Examples/AutocompleteMultipleFalse.razor

@@ -0,0 +1,25 @@
+@using static FluentUI.Demo.SampleData.Olympics2024
+
+<div>Selected: <b>@string.Join("; ", SelectedCountries.Select(c => c.Name))</b></div>
+
+<FluentAutocomplete TOption="Country"
+                    TValue="string"
+                    Label="Select a country"
+                    Multiple="false"
+                    Placeholder="Type to search..."
+                    OnOptionsSearch="@OnSearchAsync"
+                    OptionText="@(item => item.Name)"
+                    OptionDisabled="@(e => e.Code == "au")"
+                    @bind-SelectedItems="@SelectedCountries" />
+@code
+{
+    IEnumerable<Country> SelectedCountries { get; set; } = [];
+
+    Task OnSearchAsync(OptionsSearchEventArgs<Country> e)
+    {
+        e.Items = Countries.Where(i => i.Name.StartsWith(e.Text, StringComparison.OrdinalIgnoreCase))
+                           .OrderBy(i => i.Name);
+
+        return Task.CompletedTask;
+    }
+}

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Autocomplete/FluentAutocomplete.md

@@ -0,0 +1,53 @@
+---
+title: Autocomplete
+route: /Lists/Autocomplete
+---
+
+# Autocomplete
+
+An **Autocomplete** component is a text input that provides real-time suggestions as the user types.
+It combines a free-text input with a filtered list of options, allowing users to either select from the suggestions or type their own value.
+
+It is particularly useful when the list of options is large, as the user can narrow down choices without scrolling through all available items.
+
+## Keyboard interaction
+
+| Key | Behavior |
+|---|---|
+| **Type text** | Filters the list of options and triggers the `OnSearchAsync` method to fetch matching results. |
+| **Arrow Down / Arrow Up** | Opens the suggestion list and navigates through the items in the suggestion list. |
+| **Enter** | Selects the currently highlighted item. |
+| **Backspace** | Deletes the most recently selected item (in multi-select mode). |
+| **Escape** | Closes the suggestion list without selecting an item. |
+
+<br /><br />
+
+## Default
+
+A basic autocomplete that filters a list of countries as the user types.
+Multiple items can be selected, and one option is disabled (`OptionDisabled`).
+
+{{ AutocompleteDefault }}
+
+## Single item (Multiple=false)
+
+Set the `Multiple` parameter to `false` to restrict the selection to a single item.
+In this mode, the selected value replaces the input text and no tags are displayed.
+
+{{ AutocompleteMultipleFalse }}
+
+## Customized options
+
+Demonstrates advanced features: a custom `OptionTemplate` to render each option with a flag, a progress indicator during async search, 
+a configurable max dropdown height, and a max width for selected items.
+
+{{ AutocompleteCustomized }}
+
+## API FluentAutocomplete
+
+{{ API Type=FluentAutocomplete<string,string> }}
+
+## Migrating to v5
+
+TODO
+