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

Basic DetailsList with Text Items

This sample demonstrates creating a simple DetailsList that displays file metadata with sorting functionality.

details-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
{
    public class DetailsListSampleFileItem : IDetailsListItem<DetailsListSampleFileItem>
    {
        public string FileName     { get; set; }
        public string DateModified { get; set; }
        public string ModifiedBy   { get; set; }
        public string FileSize     { get; set; }

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

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

        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns,
            Func<IDetailsListColumn, Func<IComponent>, IComponent> createGridCellExpression)
        {
            foreach (var column in columns)
            {
                yield return createGridCellExpression(column, () =>
                {
                    switch (column.SortingKey)
                    {
                        case "FileIcon":     return Icon(UIcons.File);
                        case "FileName":     return TextBlock(FileName);
                        case "DateModified": return TextBlock(DateModified);
                        case "ModifiedBy":   return TextBlock(ModifiedBy);
                        case "FileSize":     return TextBlock(FileSize);
                        default:             return TextBlock("");
                    }
                });
            }
        }
    }

    internal static class App
    {
        private static void Main()
        {
            var fileItems = new List<DetailsListSampleFileItem>
            {
                new DetailsListSampleFileItem { FileName = "report.pdf",   DateModified = "2024-05-01", ModifiedBy = "Alice", FileSize = "1.2 MB" },
                new DetailsListSampleFileItem { FileName = "design.png",   DateModified = "2024-04-22", ModifiedBy = "Bob",   FileSize = "850 KB" },
                new DetailsListSampleFileItem { FileName = "notes.txt",    DateModified = "2024-03-15", ModifiedBy = "Carol", FileSize = "12 KB"  }
            };

            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");

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

DetailsList with Paginated Items and Empty Message

This sample shows how to configure a DetailsList that loads additional pages of items and displays a custom empty message when no items are available.

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 string FileName { get; set; }
        public string FileSize { get; set; }

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

        public int CompareTo(FileItem other, string sortingKey) =>
            string.Compare(FileName, other.FileName, StringComparison.Ordinal);

        public IEnumerable<IComponent> Render(IList<IDetailsListColumn> columns,
            Func<IDetailsListColumn, Func<IComponent>, IComponent> createGridCellExpression)
        {
            foreach (var column in columns)
            {
                yield return createGridCellExpression(column, () =>
                    TextBlock(column.SortingKey == "FileName" ? FileName : FileSize));
            }
        }
    }

    internal static class App
    {
        private static void Main()
        {
            var detailsList = DetailsList<FileItem>(
                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: "File Size", width: 120.px(), enableColumnSorting: true, sortingKey: "FileSize")
            )
            .Height(500.px())
            .WithListItems(new FileItem[0])
            .WithPaginatedItems(async () =>
            {
                // Simulate asynchronous loading of the next page
                await Task.Delay(1000);
                return new[]
                {
                    new FileItem { FileName = "page2-item1.txt", FileSize = "12 KB" },
                    new FileItem { FileName = "page2-item2.txt", FileSize = "8 KB"  }
                };
            })
            .WithEmptyMessage(() => BackgroundArea(Card(TextBlock("Empty list").Padding(16.px()))))
            .SortedBy("FileName");

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