# Picker

# Description

Picker is a versatile UI component used for selecting items from a list of suggestions. It provides support for both multi-selection (with tag-like selections) and single selection modes, and it can render selected items either inline or as separate components. This component is useful when you need to allow users to search, filter, and pick recipients or tags with confirmation feedback via suggestions.

# Usage

You instantiate a Picker using the static helper method from Tesserae.UI. The component is generic (Picker) and expects a type that implements the IPickerItem interface. Items can be added using the Items methods, and you can register a callback for when an item is selected using OnItemSelected.

Below is a simple example demonstrating how to create a picker with text suggestions:

using System;
using System.Collections.Generic;
using System.Linq;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

public class SimplePickerItem : IPickerItem
{
    public SimplePickerItem(string name)
    {
        Name = name;
    }
    
    public string Name { get; }
    public bool IsSelected { get; set; }
    
    public IComponent Render()
    {
        return TextBlock(Name);
    }
}

public class PickerExample
{
    public static void Main()
    {
        var picker = Picker<SimplePickerItem>(maximumAllowedSelections: 3, duplicateSelectionsAllowed: false)
            .Items(new SimplePickerItem("Item 1"), new SimplePickerItem("Item 2"), new SimplePickerItem("Item 3"))
            .OnItemSelected((sender, e) =>
            {
                // Handle item selection
                Console.WriteLine("Selected: " + e.Item.Name);
            });
        
        // Render the component and attach it to the DOM
        document.body.appendChild(picker.Render());
    }
}

# Methods

Items(params TPickerItem[] items)
- Description: Sets the list of available picker items using a parameter array.
- Parameters: An array of TPickerItem.
- Returns: The current Picker instance for fluent chaining.
Items(IEnumerable items)
- Description: Sets the list of available picker items from an enumerable collection.
- Parameters: An IEnumerable of TPickerItem.
- Returns: The current Picker instance for fluent chaining.
OnItemSelected(ComponentEventHandler<Picker, ItemPickedEvent> eventHandler)
- Description: Registers an event handler that is invoked whenever an item is picked/selected.
- Parameters: A delegate with parameters (sender: Picker, e: ItemPickedEvent).
- Returns: The current Picker instance for fluent chaining.

# Properties

TabIndex (set)
- Description: Sets the tab index of the underlying text input control.
MaximumAllowedSelections
- Description: Gets the maximum number of items that can be selected.
DuplicateSelectionsAllowed
- Description: Indicates whether the same item can be selected more than once.
SuggestionsTolerance
- Description: Determines the minimum number of characters in the textbox before suggestions appear.
PickerItems (read-only)
- Description: Returns an enumerable list of all available picker items.
SelectedPickerItems (read-only)
- Description: Returns an enumerable list of currently selected items.
UnselectedPickerItems (read-only)
- Description: Returns an enumerable list of items that have not been selected.

# Samples

# Basic Picker with Text Suggestions

In this sample, we create a picker that supports multiple selections. We add a few sample items and register an event handler to log the selected item to the console.

using System;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

public class CustomPickerItem : IPickerItem
{
    public CustomPickerItem(string name)
    {
        Name = name;
    }
    
    public string Name { get; }
    public bool IsSelected { get; set; }
    
    public IComponent Render()
    {
        return TextBlock(Name);
    }
}

public class PickerUsageSample
{
    public static void Main()
    {
        var picker = Picker<CustomPickerItem>(maximumAllowedSelections: 5, duplicateSelectionsAllowed: false, suggestionsTolerance: 1, suggestionsTitleText: "Suggested Items")
            .Items(
                new CustomPickerItem("Alpha"),
                new CustomPickerItem("Beta"),
                new CustomPickerItem("Gamma"),
                new CustomPickerItem("Delta")
            )
            .OnItemSelected((sender, e) =>
            {
                // Handle selection - for instance, log to console
                Console.WriteLine("Selected Item: " + e.Item.Name);
            });
        
        // Attach the picker to the DOM
        document.body.appendChild(picker.Render());
    }
}

# Picker with Inline Selections and Component-based Rendering

This sample demonstrates a picker that renders selected items using an icon alongside text for a richer UI experience.

using System;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

public class IconPickerItem : IPickerItem
{
    private readonly UIcons _icon;
    
    public IconPickerItem(string name, UIcons icon)
    {
        Name = name;
        _icon = icon;
    }

    public string Name { get; }
    public bool IsSelected { get; set; }
    
    public IComponent Render()
    {
        return HStack().AlignContent(ItemAlign.Center)
                       .Children(Icon(_icon).MinWidth(16.px()), TextBlock(Name));
    }
}

public class ComponentPickerExample
{
    public static void Main()
    {
        var picker = Picker<IconPickerItem>(maximumAllowedSelections: 3, duplicateSelectionsAllowed: false, suggestionsTolerance: 1, renderSelectionsInline: false, suggestionsTitleText: "Select an Item")
            .Items(
                new IconPickerItem("Option A", UIcons.Bomb),
                new IconPickerItem("Option B", UIcons.BlenderPhone),
                new IconPickerItem("Option C", UIcons.Carrot)
            )
            .OnItemSelected((sender, e) =>
            {
                Console.WriteLine("User picked: " + e.Item.Name);
            });
        
        document.body.appendChild(picker.Render());
    }
}

# Picker

# Picker

# Description

# Usage

# Methods

# Properties

# Samples

# Basic Picker with Text Suggestions

# Picker with Inline Selections and Component-based Rendering

# See also