# Details List

# 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:

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

var fileItems = GetDetailsListItems(); // your method for obtaining the list items

var detailsList = DetailsList---
label: "Details List"
layout: default
icon: table-rows
order: 980
---
## 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:

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

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)
.SortedBy("FileName");

// Render the DetailsList component
document.body.appendChild(detailsList.Render());

# 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.

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

var fileItems = GetDetailsListItems(); // Replace with your implementation to obtain 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)
.SortedBy("FileName");

// Render and attach to the document
document.body.appendChild(detailsList.Render());

# 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.

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

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(new DetailsListSampleFileItem[0])
.WithPaginatedItems(async () =>
{
    // Simulate asynchronous loading of the next page
    await Task.Delay(1000);
    return GetDetailsListItems();
})
.WithEmptyMessage(() => BackgroundArea(Card(TextBlock("Empty list").Padding(16.px()))))
.SortedBy("FileName");

document.body.appendChild(detailsList.Render());