Tesserae

DetailsList

Description

DetailsList is a robust component for displaying an information-rich collection of items. It extends the basic List capabilities by supporting features such as sorting, grouping, multiple selection, and pagination. This component is ideal for scenarios where a dense presentation of metadata is required, such as file explorers or order listings. It is part of the Collections group in Tesserae.

Usage

Instantiate a DetailsList using the static helper method from Tesserae.UI. You must provide one or more column definitions (using helpers like IconColumn and DetailsListColumn) and supply list items that implement the IDetailsListItem interface.

Below is a minimal example of how to create a DetailsList displaying file items:

details-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 fileItems = GetDetailsListItems(); // your method for obtaining the list items

            var detailsList = DetailsList<DetailsListSampleFileItem>(
                IconColumn(Icon(UIcons.File), width: 32.px(), enableColumnSorting: true, sortingKey: "FileIcon"),
                DetailsListColumn(title: "File Name",     width: 350.px(), enableColumnSorting: true, sortingKey: "FileName", isRowHeader: true),
                DetailsListColumn(title: "Date Modified", width: 170.px(), enableColumnSorting: true, sortingKey: "DateModified"),
                DetailsListColumn(title: "Modified By",   width: 150.px(), enableColumnSorting: true, sortingKey: "ModifiedBy"),
                DetailsListColumn(title: "File Size",     width: 120.px(), enableColumnSorting: true, sortingKey: "FileSize")
            )
            .Height(500.px())
            .WithListItems(fileItems.ToArray())
            .SortedBy("FileName");

            // Render the DetailsList component
            document.body.appendChild(detailsList.Render());
            document.body.style.overflow = "hidden";
            MountCenteredToBody(detailsList);
        }

        private static DetailsListSampleFileItem[] GetDetailsListItems(int start = 1, int count = 100)
        {
            return Enumerable.Range(start, count).Select(n => new DetailsListSampleFileItem(UIcons.FileWord, $"Document_{n}.docx", DateTime.Today.AddDays(-n), "System", n * 1.5)).ToArray();
        }
    }

    public class DetailsListSampleFileItem : IDetailsListItem<DetailsListSampleFileItem>
    {
        public DetailsListSampleFileItem(UIcons icon, string name, DateTime modified, string by, double size) { FileIcon = icon; FileName = name; DateModified = modified; ModifiedBy = by; FileSize = size; }
        public UIcons FileIcon { get; }
        public string FileName { get; }
        public DateTime DateModified { get; }
        public string ModifiedBy { get; }
        public double FileSize { get; }
        public bool EnableOnListItemClickEvent => true;
        public void OnListItemClick(int index) => Toast().Information($"Clicked: {FileName}");
        public int CompareTo(DetailsListSampleFileItem other, string key)
        {
            switch (key)
            {
                case "FileName":     return string.Compare(FileName, other.FileName, StringComparison.OrdinalIgnoreCase);
                case "DateModified": return DateModified.CompareTo(other.DateModified);
                case "ModifiedBy":   return string.Compare(ModifiedBy, other.ModifiedBy, StringComparison.OrdinalIgnoreCase);
                case "FileSize":     return FileSize.CompareTo(other.FileSize);
                default:             return 0;
            }
        }
        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns, Func<IDetailsListColumn, Func<IComponent>, IComponent> cell)
        {
            yield return cell(columns[0], () => Icon(FileIcon));
            yield return cell(columns[1], () => TextBlock(FileName));
            yield return cell(columns[2], () => TextBlock(DateModified.ToShortDateString()));
            yield return cell(columns[3], () => TextBlock(ModifiedBy));
            yield return cell(columns[4], () => TextBlock(FileSize.ToString("N1") + " KB"));
        }
    }
}

Methods

Compact(): DetailsList
Sets the list to a compact mode (typically rendering items at a smaller height).
WithEmptyMessage(Func emptyListMessageGenerator): DetailsList
Specifies a function that generates a component to display when the list has no items.
• Parameter: emptyListMessageGenerator – a function returning an IComponent to be rendered as an empty message.
WithPaginatedItems(Func<Task<TDetailsListItem[]>> getNextItemPage): DetailsList
Enables pagination by allowing asynchronous loading of additional list items as the user scrolls.
• Parameter: getNextItemPage – an asynchronous function that returns an array of new list items.
WithListItems(params TDetailsListItem[] listItems): DetailsList
Adds list items to the component. If the list has already been rendered, it refreshes the displayed content.
• Parameter: listItems – an array of items implementing IDetailsListItem.
SortedBy(string columnSortingKey): DetailsList
Pre-sorts the list based on a provided column sorting key.
• Parameter: columnSortingKey – the key representing the column used for sorting.

Properties

IsCompact (bool)
Gets or sets whether the list is displayed in a compact style. Internally, setting this affects CSS classes to adjust row heights.
StylingContainer (HTMLElement)
Returns the container element that holds the entire DetailsList, useful for applying additional styling.
PropagateToStackItemParent (bool)
Indicates whether style propagations should be applied to the parent stack items; this is set to false by default.

Samples

Sortable DetailsList with 50 Items

This sample populates the list with 50 generated rows so sorting and scrolling are meaningful. Click any column header to re-sort, or click a row to fire its OnListItemClick event (shown via a toast).

details-list-2-sample.js

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

namespace Tesserae.Tests
{
    public class FileRow : IDetailsListItem<FileRow>
    {
        public FileRow(string name, DateTime modified, string by, double sizeKb)
        {
            FileName = name; DateModified = modified; ModifiedBy = by; FileSize = sizeKb;
        }
        public string   FileName     { get; }
        public DateTime DateModified { get; }
        public string   ModifiedBy   { get; }
        public double   FileSize     { get; }

        public bool EnableOnListItemClickEvent => true;
        public void OnListItemClick(int index) => Toast().Information($"Clicked: {FileName}");

        public int CompareTo(FileRow other, string key)
        {
            switch (key)
            {
                case "FileName":     return string.Compare(FileName, other.FileName, StringComparison.OrdinalIgnoreCase);
                case "DateModified": return DateModified.CompareTo(other.DateModified);
                case "ModifiedBy":   return string.Compare(ModifiedBy, other.ModifiedBy, StringComparison.OrdinalIgnoreCase);
                case "FileSize":     return FileSize.CompareTo(other.FileSize);
                default:             return 0;
            }
        }

        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns,
            Func<IDetailsListColumn, Func<IComponent>, IComponent> cell)
        {
            yield return cell(columns[0], () => Icon(UIcons.FileWord));
            yield return cell(columns[1], () => TextBlock(FileName));
            yield return cell(columns[2], () => TextBlock(DateModified.ToShortDateString()));
            yield return cell(columns[3], () => TextBlock(ModifiedBy));
            yield return cell(columns[4], () => TextBlock(FileSize.ToString("N1") + " KB"));
        }
    }

    internal static class App
    {
        private static FileRow[] Build(int count)
        {
            var owners = new[] { "Alice", "Bob", "Carol", "Dan", "Eve" };
            return Enumerable.Range(1, count).Select(n =>
                new FileRow($"Document_{n:D2}.docx",
                            DateTime.Today.AddDays(-n),
                            owners[n % owners.Length],
                            n * 13.7)).ToArray();
        }

        private static void Main()
        {
            var list = DetailsList<FileRow>(
                    IconColumn(Icon(UIcons.File), width: 32.px()),
                    DetailsListColumn(title: "File Name",     width: 280.px(), enableColumnSorting: true, sortingKey: "FileName", isRowHeader: true),
                    DetailsListColumn(title: "Date Modified", width: 160.px(), enableColumnSorting: true, sortingKey: "DateModified"),
                    DetailsListColumn(title: "Modified By",   width: 140.px(), enableColumnSorting: true, sortingKey: "ModifiedBy"),
                    DetailsListColumn(title: "File Size",     width: 120.px(), enableColumnSorting: true, sortingKey: "FileSize"))
                .Height(400.px())
                .WithListItems(Build(50))
                .SortedBy("FileName");

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }
    }
}

DetailsList with Live Pagination

Combine WithPaginatedItems with a real async producer. Each scroll to the bottom appends another 10 rows, simulating remote loading with Task.Delay. A Toast reports each batch so the loading behavior is visible.

details-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
{
    public class FileItem : IDetailsListItem<FileItem>
    {
        public FileItem(string name, double sizeKb) { FileName = name; FileSize = sizeKb; }
        public string FileName { get; }
        public double FileSize { get; }

        public bool EnableOnListItemClickEvent => false;
        public void OnListItemClick(int listItemIndex) { }

        public int CompareTo(FileItem other, string key)
            => key == "FileSize"
                ? FileSize.CompareTo(other.FileSize)
                : string.Compare(FileName, other.FileName, StringComparison.OrdinalIgnoreCase);

        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns,
            Func<IDetailsListColumn, Func<IComponent>, IComponent> cell)
        {
            yield return cell(columns[0], () => Icon(UIcons.File));
            yield return cell(columns[1], () => TextBlock(FileName));
            yield return cell(columns[2], () => TextBlock(FileSize.ToString("N1") + " KB"));
        }
    }

    internal static class App
    {
        private static int _page = 1;

        private static void Main()
        {
            var list = DetailsList<FileItem>(
                    IconColumn(Icon(UIcons.File), width: 32.px()),
                    DetailsListColumn(title: "File Name", width: 320.px(), enableColumnSorting: true, sortingKey: "FileName", isRowHeader: true),
                    DetailsListColumn(title: "File Size", width: 140.px(), enableColumnSorting: true, sortingKey: "FileSize"))
                .Height(360.px())
                .WithListItems(BuildPage())
                .WithPaginatedItems(async () =>
                {
                    await Task.Delay(700);
                    Toast().Information($"Loaded page {_page + 1}");
                    return BuildPage();
                })
                .SortedBy("FileName");

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }

        private static FileItem[] BuildPage()
        {
            var p = _page++;
            return Enumerable.Range(1, 10).Select(n =>
                new FileItem($"page{p:D2}-item{n:D2}.txt", n * 4.5 + p)).ToArray();
        }
    }
}

DetailsList with Empty Message

Use WithEmptyMessage to render a placeholder when no items are available. The delegate is only invoked when the list is empty, so it can be as elaborate as needed.

details-list-4-sample.js

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

namespace Tesserae.Tests
{
    public class EmptyRow : IDetailsListItem<EmptyRow>
    {
        public bool EnableOnListItemClickEvent => false;
        public void OnListItemClick(int index) { }
        public int CompareTo(EmptyRow other, string key) => 0;
        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns,
            Func<IDetailsListColumn, Func<IComponent>, IComponent> cell)
        {
            yield break;
        }
    }

    internal static class App
    {
        private static void Main()
        {
            var list = DetailsList<EmptyRow>(
                    IconColumn(Icon(UIcons.File), width: 32.px()),
                    DetailsListColumn(title: "File Name", width: 320.px(), isRowHeader: true),
                    DetailsListColumn(title: "File Size", width: 140.px()))
                .WithEmptyMessage(() =>
                    BackgroundArea(VStack().AlignItemsCenter().JustifyContentCenter().Children(
                        Icon(UIcons.InboxEmpty).XXLarge(),
                        TextBlock("No files in this folder").SemiBold().Padding(8.px()),
                        Button("Upload a file").Primary().SetIcon(UIcons.Upload)
                            .OnClick((s, e) => Toast().Information("Upload triggered"))
                    ).Padding(24.px())).WS().HS())
                .Height(280.px())
                .WithListItems(new EmptyRow[0]);

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }
    }
}