[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/AutocompleteDebug.razor

@@ -0,0 +1,110 @@
+@page "/Lists/Autocomplete/Debug"
+
+@using static FluentUI.Demo.SampleData.Olympics2024
+
+<div style="margin: 24px;">
+
+    <div>Selected items: <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"
+                        Items="@Countries"
+                        OptionText="@(item => item.Name)"
+                        MaxSelectedWidth="@(MaxSelectedWidth ? "40px" : null)"
+                        ShowDismiss="@ShowDismiss"
+                        Multiple="@Multiple"
+                        MaximumSelectedOptions="@(SetMaximumSelectedOptions ? 4 : (int?)null)"
+                        @bind-Value="@SearchText"
+                        @bind-SelectedItems="@SelectedCountries">
+
+        @* Drop-down item template *@
+        <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>
+
+        @* Content displayed at the top of the drop-down list *@
+        <HeaderContent>
+            <FluentText Size="TextSize.Size200" Color="Color.Primary" Align="TextAlign.Center">
+                Suggested contacts
+            </FluentText>
+            <FluentProgressBar Thickness="ProgressThickness.Large" Visible="@context.InProgress" />
+        </HeaderContent>
+
+        @* Content displayed at the bottom of the drop-down list *@
+        <FooterContent>
+            @if (!context.Items.Any())
+            {
+                <FluentText Size="TextSize.Size200" Align="TextAlign.Center" Color="Color.Error" Style="width: 100%;">
+                    No results found
+                </FluentText>
+            }
+        </FooterContent>
+
+    </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" />
+        <FluentSwitch @bind-Value="@Multiple" Label="Multiple selection" />
+        <FluentSwitch @bind-Value="@SetMaximumSelectedOptions" Label="Set MaximumSelectedOptions to 4" />
+        <FluentButton OnClick="@SetSelectedCountriesAsync">
+            Set SelectedCountries to [be, fr]
+        </FluentButton>
+    </FluentStack>
+
+
+    <FluentAutocomplete TOption="Country"
+                        TValue="string"
+                        Width="100%"
+                        MaximumOptionsSearch="int.MaxValue"
+                        Label="Select countries from Items"
+                        Items="@Countries"
+                        OptionText="@(item => item.Name)"
+                        @bind-SelectedItems="@SelectedCountries" />
+
+</div>
+
+@code
+{
+    bool ShowProgressIndicator { get; set; }
+    bool MaxAutoHeight { get; set; }
+    bool MaxSelectedWidth { get; set; }
+    bool ShowDismiss { get; set; } = true;
+    bool Multiple { get; set; } = true;
+    bool SetMaximumSelectedOptions { get; set; }
+    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);
+    }
+
+    async Task SetSelectedCountriesAsync()
+    {
+        SelectedCountries = Countries.Where(i => i.Code == "be" || i.Code == "fr");
+        await Task.CompletedTask;
+    }
+}

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

@@ -0,0 +1,41 @@
+<div>Selected: <b>@string.Join("; ", Selected.Select(x => x.Name))</b></div>
+
+<FluentAutocomplete TOption="MyUser" 
+                    TValue="int" 
+                    Width="100%" 
+                    Label="Name" 
+                    Placeholder="Select a user"
+                    OptionText="(option) => option.Name" 
+                    OptionValue="(option) => option.UserId" 
+                    OptionSelectedComparer="MyComparer.Instance"
+                    OnOptionsSearch="@OnSearchAsync" 
+                    @bind-SelectedItems="@Selected" />
+
+@code
+{
+    IEnumerable<MyUser> Selected { get; set; } = [];
+
+    /// Search method called when the user types in the input or opens the options list.
+    /// A new list of MyUser is assigned with new object instances.
+    /// The component will use the OptionSelectedComparer to check if any of the new items are already selected.
+    Task OnSearchAsync(OptionsSearchEventArgs<MyUser> e)
+    {
+        e.Items = [
+            new MyUser(1, "Marvin Klein"),
+            new MyUser(2, "Denis Voituron"),
+        ];
+
+        return Task.CompletedTask;
+    }
+
+    record MyUser(int UserId, string Name);
+
+    class MyComparer : IEqualityComparer<MyUser>
+    {
+        public static readonly MyComparer Instance = new();
+
+        public bool Equals(MyUser? x, MyUser? y) => 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,82 @@
+@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">
+
+    @* Template used with each Option items *@
+    <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>
+
+
+    @* Content display at the top of the Popup area *@
+    <HeaderContent>
+        <FluentText Size="TextSize.Size200" Color="Color.Primary" Align="TextAlign.Center">
+            Suggested contacts
+        </FluentText>
+        <FluentProgressBar Thickness="ProgressThickness.Large" Visible="@context.InProgress" />
+    </HeaderContent>
+
+    @* Content display at the bottom of the Popup area *@
+    <FooterContent>
+        @if (!context.InProgress && !context.Items.Any())
+        {
+            <FluentText Size="TextSize.Size200" 
+                        Align="TextAlign.Center" 
+                        Color="Color.Error" 
+                        Style="width: 100%;">
+                No results found
+            </FluentText>
+        }
+    </FooterContent>
+
+</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,31 @@
+@using static FluentUI.Demo.SampleData.Olympics2024
+
+<div>Selected: <b>@SelectedCountry?.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; } = [];
+
+    Country? SelectedCountry
+    {
+        get => SelectedCountries.FirstOrDefault() ?? default;
+        set => SelectedCountries = value is not null ? [value] : [];
+    }
+
+    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,67 @@
+---
+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.
+
+This is particularly useful when the list of options is large, as the user can narrow down the list op options without needing to scroll through all available items.
+
+By default, the `FluentAutocomplete` component compares search results by instance with its internal selected items.
+You can control this behavior by providing the `OptionSelectedComparer` parameter.
+
+> **Note:** Accessibility requirements are not yet implemented for this component.
+
+## 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 }}
+
+## Different object instances from search result
+
+When the `OnOptionsSearch` method returns **new object instances** on each call (e.g. from an API or database query),
+the component cannot match them to already-selected items by **reference**.
+
+Use the `OptionSelectedComparer` parameter to provide a custom `IEqualityComparer<TOption>` that compares items by a unique key (such as an ID)
+instead of by reference. Without this, previously selected items may not appear as checked in the refreshed list.
+
+{{ AutocompleteComparer }}
+
+## API FluentAutocomplete
+
+{{ API Type=FluentAutocomplete<string,string> }}
+
+## Migrating to v5
+
+{{ INCLUDE File=MigrationFluentAutocomplete }}

examples/Demo/FluentUI.Demo.Client/Documentation/Components/List/Listbox/DebugPages/DebugList.razor

@@ -12,7 +12,7 @@
                TOption="string"
                TValue="string"
                @bind-SelectedItems="@SelectedItems"
-               Multiple="true" />
+               Multiple="false" />
 
 <FluentButton OnClick="@(e => Colors = new[] { "Yellow", "Purple", "Cyan" })">
     Yellow, Purple, Cyan