Tesserae

SearchableList

Description

The SearchableList component is a generic list container designed to display and filter a collection of items that implement the ISearchableItem interface. It provides an integrated search box that allows users to search through the items by typing in a term. The component is highly customizable, supporting features such as custom "no results" messages, background search operations, and the addition of custom components before or after the search box. Use this component when you need a searchable list interface in your application.

Usage

Instantiate a SearchableList using the static helper methods from Tesserae.UI. It accepts an array or an ObservableList of items (each implementing ISearchableItem) and optional column widths for layout purposes. The search box filters items based on whether their IsMatch method returns true for each entered search term.

Below is a minimal sample demonstrating how to implement the ISearchableItem interface and create a SearchableList with a custom "no results" message:

searchable-list-sample.js

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

namespace Tesserae.Tests
{
    internal static class App
    { 
        private static void Main()
        {
            var sampleComponent = new SampleUsage();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class MySearchableItem : ISearchableItem
    {
        private readonly string _name;
        public MySearchableItem(string name)
        {
            _name = name;
        }

        public bool IsMatch(string searchTerm) => _name.IndexOf(searchTerm, StringComparison.OrdinalIgnoreCase) >= 0;

        public IComponent Render() => Card(TextBlock(_name));
    }

    public class SampleUsage : IComponent
    {
        public HTMLElement Render()
        {
            // Create an array of searchable items.
            var items = new MySearchableItem[]
            {
                new MySearchableItem("Apple"),
                new MySearchableItem("Banana"),
                new MySearchableItem("Cherry")
            };

            // Instantiate SearchableList with a custom no results message.
            var searchableList = SearchableList(items)
                .WithNoResultsMessage(() => Card(TextBlock("No Results").Padding(16.px())));

            return searchableList.Render();
        }
    }
}

Methods

• WithNoResultsMessage(Func emptyListMessageGenerator)
- Sets a custom no results message by specifying a delegate that returns an IComponent.
- Parameter: emptyListMessageGenerator – a function that generates an IComponent to display when no items match the search.

• SearchBox(Action sb)
- Allows customization of the inner SearchBox component.
- Parameter: sb – an action delegate to modify the SearchBox properties.

• CaptureSearchBox(out SearchBox sb)
- Captures and returns the underlying SearchBox instance for further customization or external manipulation.
- Parameter: sb – an output parameter that will hold the SearchBox instance.

• WithBackgroundSearch(Func<string, Task<T[]>> searcher)
- Configures a background search operation that is executed asynchronously based on the current search text.
- Parameter: searcher – a function that returns a Task with an array of items to include in the search result.

• HideSearchBoxIfLessThan(int items)
- Hides the search box when the number of items in the list is less than the specified threshold.
- Parameter: items – the minimum number of items required to show the search box.

• ShowNotMatching()
- Configures the list to optionally display items that do not match the current search criteria (styled differently).

• BeforeSearchBox(params IComponent[] beforeComponents)
- Inserts one or more custom components into the search box container before the default SearchBox.
- Parameter: beforeComponents – one or more IComponent instances to add before the SearchBox.

• AfterSearchBox(params IComponent[] afterComponents)
- Appends one or more custom components to the search box container after the SearchBox.
- Parameter: afterComponents – one or more IComponent instances to add after the SearchBox.

• Render()
- Renders the SearchableList component into its underlying HTMLElement.
- Returns: HTMLElement – the rendered DOM element.

Properties

• Items (ObservableList)
- Exposes the underlying collection of searchable items.

• ShowNotMatchingItems (bool)
- Determines whether items that do not match the search criteria should still be shown (with a distinct styling).

• StylingContainer (HTMLElement)
- (Read-only) Returns the container element used for styling purposes.

• PropagateToStackItemParent (bool)
- (Read-only) Indicates if the styling should propagate to the parent container of each list item.

Samples

Searchable List with No Results Message

This sample demonstrates how to configure a SearchableList with a custom message that is displayed when no items match the search criteria.

searchable-list-2-sample.js

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

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new NoResultsSample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class MySearchableItem : ISearchableItem
    {
        private readonly string _name;
        public MySearchableItem(string name)
        {
            _name = name;
        }

        public bool IsMatch(string searchTerm) => _name.IndexOf(searchTerm, StringComparison.OrdinalIgnoreCase) >= 0;

        public IComponent Render() => Card(TextBlock(_name));
    }

    public class NoResultsSample : IComponent
    {
        public HTMLElement Render()
        {
            var items = new MySearchableItem[]
            {
                new MySearchableItem("Red"),
                new MySearchableItem("Green"),
                new MySearchableItem("Blue")
            };

            var searchableList = SearchableList(items)
                .WithNoResultsMessage(() =>
                    Card(TextBlock("No Results Found").Padding(16.px()))
                        .WidthStretch()
                        .HeightStretch()
                        .MinHeight(100.px()));

            return searchableList.Render();
        }
    }
}

Searchable List with Additional Custom Components

This sample shows how to add custom buttons before and after the search box within a SearchableList.

searchable-list-3-sample.js

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

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new CustomComponentsSample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class CustomComponentsSample : IComponent
    {
        public HTMLElement Render()
        {
            var items = new[]
            {
                new MySearchableItem("Alpha"),
                new MySearchableItem("Beta"),
                new MySearchableItem("Gamma")
            };

            var searchableList = SearchableList(items)
                .BeforeSearchBox(Button("Before").Link())
                .AfterSearchBox(Button("After").Primary())
                .WithNoResultsMessage(() => Card(TextBlock("No Results").Padding(16.px())));

            return searchableList.Render();
        }
    }

    public class MySearchableItem : ISearchableItem
    {
        private readonly string _value;
        public MySearchableItem(string value)
        {
            _value = value;
        }

        public bool IsMatch(string searchTerm)
        {
            return _value.IndexOf(searchTerm, StringComparison.OrdinalIgnoreCase) >= 0;
        }

        public IComponent Render() => Card(TextBlock(_value));
    }
}