Tesserae - Tree

Tree

Description

A component that displays a hierarchical list

A tree displays hierarchical data. Nodes can be expanded or collapsed to reveal nested data.

Supports synchronous and asynchronous loading of child nodes.

Filter(predicate) is a view over the tree rather than a change to it: a row that matches keeps its subtree as it was, a folder on the way to a match stays visible and is opened so the match can be seen, and everything else is hidden. Filter("text") is the common case, a case-insensitive match on each row's Text, and an empty text clears the filter. Items added while a filter is in force are filtered as they arrive; ClearFilter() shows everything again and closes the folders the filter opened, so the user's own expansion is what comes back. Opening a folder for the filter raises no OnExpanded, so code that persists what the user expanded is not misled. IsFiltered says whether a filter is in force, and Tree.Item.IsFilteredOut reads it per row.

Tree.Item.IconColor(color) tints a row's icon and leaves the text alone — the danger tint a file that fails to compile gets in an editor's file tree — and survives the icon being swapped; null goes back to the theme's colour.

Row commands (TreeCommand) appear on hover unless CommandsAlwaysVisible() keeps them on show, and a row keeps the same height whether or not they are showing, so a tree does not twitch under the pointer. In a command menu every row is the width of the menu. Commands shrink with the rows in a Compact() tree.

Samples

Basic Synchronous Tree

tree-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var component = new Tree().Items(
                new Tree.Item("samples/ConsoleApp...", UIcons.Folder).Expanded().Items(
                    new Tree.Item("ConsoleApp1.csproj", UIcons.File).Selected(),
                    new Tree.Item("Program.cs", UIcons.File)
                ),
                new Tree.Item("src", UIcons.Folder).Expanded().Items(
                    new Tree.Item("MarkdownRende...", UIcons.Folder).Expanded().Items(
                        new Tree.Item("MarkdownConve...", UIcons.File),
                        new Tree.Item("Slides", UIcons.Folder).Expanded().Items(
                            new Tree.Item("Blocks", UIcons.Folder).Expanded().Items(
                                new Tree.Item("HeadingRe...", UIcons.File),
                                new Tree.Item("HeadingRe...", UIcons.File)
                            ),
                            new Tree.Item("SlideDocume...", UIcons.File)
                        )
                    ),
                    new Tree.Item("MarkdownRende...", UIcons.Folder).Expanded().Items(
                        new Tree.Item("MarkdownRende...", UIcons.File),
                        new Tree.Item("Program.cs", UIcons.File)
                    ),
                    new Tree.Item("MarkdownRenderer...", UIcons.File)
                )
            );

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

Filtering

tree-filter-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var tree = new Tree().Compact().Items(
                new Tree.Item("endpoints", UIcons.Folder).Expanded().Items(
                    new Tree.Item("search", UIcons.Folder).Items(
                        new Tree.Item("people.cs",    UIcons.File),
                        new Tree.Item("documents.cs", UIcons.File)
                    ),
                    new Tree.Item("upload.cs",  UIcons.File),
                    new Tree.Item("webhook.cs", UIcons.File).IconColor(Theme.Colors.Red600)
                ),
                new Tree.Item("tasks", UIcons.Folder).Items(
                    new Tree.Item("nightly-import.cs", UIcons.File),
                    new Tree.Item("cleanup.cs",        UIcons.File)
                ),
                new Tree.Item("indexes", UIcons.Folder).Items(
                    new Tree.Item("people.json",    UIcons.File),
                    new Tree.Item("documents.json", UIcons.File)
                )
            );

            var search = SearchBox("Filter the tree...").SearchAsYouType().OnSearch((s, term) => tree.Filter(term));

            var component = VStack().WS().Children(search.WS(), tree);

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component.Width(360.px()));
        }
    }
}

Asynchronous Tree

tree-2-sample.cs

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

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var component = new Tree().Items(
                new Tree.Item("Lazy Loaded Folder", UIcons.Folder).ItemsAsync(async () =>
                {
                    await Task.Delay(1000);
                    return new[]
                    {
                        new Tree.Item("Async Child 1", UIcons.File),
                        new Tree.Item("Async Child 2", UIcons.File)
                    };
                })
            );

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

Selectable Tree

tree-3-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var component = new Tree().SelectionEnabled().Items(
                new Tree.Item("Root 1", UIcons.Folder).Expanded().Items(
                    new Tree.Item("Child A", UIcons.File),
                    new Tree.Item("Child B", UIcons.File)
                ),
                new Tree.Item("Root 2", UIcons.Folder).Expanded().Items(
                    new Tree.Item("Child C", UIcons.File).Selected(),
                    new Tree.Item("Child D", UIcons.File)
                )
            );

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

File-System Tree with Selection Events

This sample models a realistic project layout. OnSelected on the Tree fires every time the user clicks an item, so we mirror the path of the selected node in a panel beside the tree.

tree-4-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var selected = TextBlock("(none)").SemiBold();

            var tree = new Tree().SelectionEnabled().Items(
                new Tree.Item("my-app", UIcons.Folder).Expanded().Items(
                    new Tree.Item("src", UIcons.Folder).Expanded().Items(
                        new Tree.Item("components", UIcons.Folder).Expanded().Items(
                            new Tree.Item("Button.tsx",  UIcons.File),
                            new Tree.Item("Avatar.tsx",  UIcons.File),
                            new Tree.Item("Sidebar.tsx", UIcons.File)
                        ),
                        new Tree.Item("hooks", UIcons.Folder).Items(
                            new Tree.Item("useTheme.ts", UIcons.File),
                            new Tree.Item("useAuth.ts",  UIcons.File)
                        ),
                        new Tree.Item("index.tsx", UIcons.File)
                    ),
                    new Tree.Item("public", UIcons.Folder).Items(
                        new Tree.Item("favicon.ico", UIcons.File),
                        new Tree.Item("logo.svg",    UIcons.File)
                    ),
                    new Tree.Item("package.json", UIcons.File),
                    new Tree.Item("README.md",    UIcons.File)
                )
            ).OnSelected((s, item) => selected.Text(item.Text));

            var component = HStack().WS().H(380).Children(
                tree.MinWidth(260.px()),
                VStack().Padding(16.px()).Grow().Children(
                    Label("Selected file: ").SetContent(selected),
                    TextBlock("Click a node in the tree to update this panel.").Small().Secondary().PT(8)
                )
            );

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

API reference

enum

TreeSelectionMode

public enum TreeSelectionMode

How many items of a Tree can be selected at once, and with which gestures.

Namespace: Tesserae

Values

Name	Description
None	Items cannot be selected.
Single	One item at a time: selecting an item unselects whatever was selected before.
Multiple	Any number of items, with the gestures of a search-results list: the checkbox toggles one item, ctrl (or cmd) clicking a row does the same, and shift-clicking a row selects everything between it and the last item the user picked.

Value

TreeSelectionMode.None

None

Items cannot be selected.

Value

TreeSelectionMode.Single

Single

One item at a time: selecting an item unselects whatever was selected before.

Value

TreeSelectionMode.Multiple

Multiple

Any number of items, with the gestures of a search-results list: the checkbox toggles one item, ctrl (or cmd) clicking a row does the same, and shift-clicking a row selects everything between it and the last item the user picked.

class

Tree

public sealed class Tree : ComponentBase<Tree, HTMLUListElement>, IContainer<Tree.Item, Tree.Item>, IObservableComponent<Tree.Item>

A vertically-stacked tree view with expand / collapse, keyboard navigation, selection and arbitrary item rendering.

Namespace: Tesserae
Inheritance: ComponentBase<Tree, HTMLUListElement> → Tree
Implements: IContainer<Tree.Item, Tree.Item>, IObservableComponent<Tree.Item>

Constructors

Name	Description
Tree	Initializes a new instance of this class.

Constructor

Tree

public Tree()

Initializes a new instance of this class.

Properties

Name	Description
SelectedItem	Gets the currently selected item - the last one the user picked when several are selected.
SelectedItems	Returns every selected item, in the order they appear in the tree.
SelectionMode	Returns how many items of the tree can be selected at once.
IsCascading	Returns a value indicating whether selecting an item also selects everything below it.
IsFiltered	Whether a filter set by `Filter` is in force.

Property

Tree.SelectedItem

public Item SelectedItem { get; private set; }

Gets the currently selected item - the last one the user picked when several are selected.

Property

Tree.SelectedItems

public Item[] SelectedItems

Returns every selected item, in the order they appear in the tree.

Property

Tree.SelectionMode

public TreeSelectionMode SelectionMode

Returns how many items of the tree can be selected at once.

Property

Tree.IsCascading

public bool IsCascading

Returns a value indicating whether selecting an item also selects everything below it.

Property

Tree.IsFiltered

public bool IsFiltered

Whether a filter set by Filter is in force.

Methods

Name	Description
Render	Renders the component's root HTML element.
OnSelected	Registers a callback invoked when the selected event fires.
OnSelectionChanged	Registers a callback invoked whenever the selection changes, with every selected item. A gesture that moves several items at once - a range, or a cascade into a folder's contents - runs it once.
Compact	Switches the tree to a compact density, matching the row height, font size and indentation of a code editor's file explorer.
SelectionEnabled	Enables or disables single-item selection on the tree. Shorthand for `Selectable` with `Single`.
Selectable	Makes the items of the tree selectable, as many at a time as the given mode allows. In `Multiple` every item shows a checkbox, ctrl (or cmd) clicking a row toggles it, and shift-clicking one selects everything between it and the last item picked.
NotSelectable	Takes selection away again, unselecting whatever was selected.
CascadeSelection	Makes an item's selection carry to everything below it: selecting a folder selects every item inside it, unselecting it unselects them, and a folder only some of whose contents are selected is drawn as partially selected.
ClearSelection	Unselects every item of the tree.
SelectAll	Selects every selectable item of the tree.
RefreshCascadeState	Re-reads every folder's state from its contents, deepest first.
Add	Adds the given item to the component.
Clear	Clears the component's current state.
Filter	Shows only the items `predicate` accepts, plus whatever leads to them: an item that matches keeps its subtree as it was, an ancestor of a match stays visible and is opened so the match can be seen, and everything else is hidden. The filter is a view over the tree, not a change to it - items added while it is active are filtered as they arrive, and `ClearFilter` puts every item back, including the expansion state the user had before the filter opened folders on their behalf. Opening a folder for the filter raises no `OnExpanded`, so code persisting what the user expanded is not misled by it.
ClearFilter	Removes the filter set by `Filter`: every item is shown again, and the folders the filter opened return to how the user had left them.
Replace	Replaces an existing item with a new one.
AsObservable	Returns an observable that tracks the currently-selected tree item.
Items	Adds the given items to the component.
ToggleSelection	Toggles the given item, and makes it the anchor the next shift-click ranges from.
SelectRangeTo	Selects everything between the anchor - the last item the user picked - and the given item, unselecting whatever falls outside it, the way a shift-click through a list of search results does. The range runs over the rows that are actually on screen, so a collapsed folder counts as one row (and, when the tree cascades, brings its contents with it).

Method

Tree.Render

public override HTMLElement Render()

Renders the component's root HTML element.

Method

Tree.OnSelected

public Tree OnSelected(ComponentEventHandler<Tree, Item> onSelected)

Registers a callback invoked when the selected event fires.

Method

Tree.OnSelectionChanged

public Tree OnSelectionChanged(ComponentEventHandler<Tree, Item[]> onSelectionChanged)

Registers a callback invoked whenever the selection changes, with every selected item. A gesture that moves several items at once - a range, or a cascade into a folder's contents - runs it once.

Method

Tree.Compact

public Tree Compact(bool compact = true)

Switches the tree to a compact density, matching the row height, font size and indentation of a code editor's file explorer.

Method

Tree.SelectionEnabled

public Tree SelectionEnabled(bool enabled = true)

Enables or disables single-item selection on the tree. Shorthand for Selectable with Single.

Method

Tree.Selectable

public Tree Selectable(TreeSelectionMode mode = TreeSelectionMode.Multiple)

Makes the items of the tree selectable, as many at a time as the given mode allows. In Multiple every item shows a checkbox, ctrl (or cmd) clicking a row toggles it, and shift-clicking one selects everything between it and the last item picked.

Method

Tree.NotSelectable

public Tree NotSelectable()

Takes selection away again, unselecting whatever was selected.

Method

Tree.CascadeSelection

public Tree CascadeSelection(bool cascade = true)

Makes an item's selection carry to everything below it: selecting a folder selects every item inside it, unselecting it unselects them, and a folder only some of whose contents are selected is drawn as partially selected.

Method

Tree.ClearSelection

public Tree ClearSelection()

Unselects every item of the tree.

Method

Tree.SelectAll

public Tree SelectAll()

Selects every selectable item of the tree.

Method

Tree.RefreshCascadeState

private void RefreshCascadeState()

Re-reads every folder's state from its contents, deepest first.

Method

Tree.Add

public void Add(Item component)

Adds the given item to the component.

Method

Tree.Clear

public void Clear()

Clears the component's current state.

Method

Tree.Filter

Overload

Filter(Func<Item, bool>) Shows only the items predicate accepts, plus whatever leads to them: an item that matches keeps its subtree as it was, an ancestor of a match stays visible and is opened so the match can be seen, and everything else is hidden. The filter is a view over the tree, not a change to it - items added while it is active are filtered as they arrive, and ClearFilter puts every item back, including the expansion state the user had before the filter opened folders on their behalf. Opening a folder for the filter raises no OnExpanded, so code persisting what the user expanded is not misled by it.

Filter(string) Shows only the items whose text contains text, ignoring case, and the folders leading to them. An empty text clears the filter.

Overload
Filter(Func<Item, bool>)	Shows only the items `predicate` accepts, plus whatever leads to them: an item that matches keeps its subtree as it was, an ancestor of a match stays visible and is opened so the match can be seen, and everything else is hidden. The filter is a view over the tree, not a change to it - items added while it is active are filtered as they arrive, and `ClearFilter` puts every item back, including the expansion state the user had before the filter opened folders on their behalf. Opening a folder for the filter raises no `OnExpanded`, so code persisting what the user expanded is not misled by it.
Filter(string)	Shows only the items whose text contains `text`, ignoring case, and the folders leading to them. An empty text clears the filter.

Filter(Func<Item, bool>)

public Tree Filter(Func<Item, bool> predicate)

Shows only the items predicate accepts, plus whatever leads to them: an item that matches keeps its subtree as it was, an ancestor of a match stays visible and is opened so the match can be seen, and everything else is hidden. The filter is a view over the tree, not a change to it - items added while it is active are filtered as they arrive, and ClearFilter puts every item back, including the expansion state the user had before the filter opened folders on their behalf. Opening a folder for the filter raises no OnExpanded, so code persisting what the user expanded is not misled by it.

Parameters

predicate Func<Item, bool>

Filter(string)

public Tree Filter(string text)

Shows only the items whose text contains text, ignoring case, and the folders leading to them. An empty text clears the filter.

Parameters

text string

Method

Tree.ClearFilter

public Tree ClearFilter()

Removes the filter set by Filter: every item is shown again, and the folders the filter opened return to how the user had left them.

Method

Tree.Replace

public void Replace(Item newComponent, Item oldComponent)

Replaces an existing item with a new one.

Method

Tree.AsObservable

public IObservable<Item> AsObservable()

Returns an observable that tracks the currently-selected tree item.

Method

Tree.Items

public Tree Items(params Item[] children)

Adds the given items to the component.

Method

Tree.ToggleSelection

internal void ToggleSelection(Item item)

Toggles the given item, and makes it the anchor the next shift-click ranges from.

Method

Tree.SelectRangeTo

internal void SelectRangeTo(Item item)

Selects everything between the anchor - the last item the user picked - and the given item, unselecting whatever falls outside it, the way a shift-click through a list of search results does. The range runs over the rows that are actually on screen, so a collapsed folder counts as one row (and, when the tree cascades, brings its contents with it).

Events

Name	Description
SelectedItemChanged	Raised when selected item changed occurs.
SelectionChanged	Raised when any item is selected or unselected, with everything that is selected afterwards.

Event

Tree.SelectedItemChanged

public event ComponentEventHandler<Tree, Item> SelectedItemChanged

Raised when selected item changed occurs.

Event

Tree.SelectionChanged

public event ComponentEventHandler<Tree, Item[]> SelectionChanged

Raised when any item is selected or unselected, with everything that is selected afterwards.

TreeCommand

A command inside a tree item, drawn as a small action button on the row.

class

TreeCommand

public class TreeCommand : IComponent

A Command component for use within a Tree item, typically appearing as a small action button.

Namespace: Tesserae
Implements: IComponent

Constructors

Name	Description
TreeCommand	Initializes a new instance of this class.

Constructor

TreeCommand

Overload
TreeCommand(UIcons, UIconsWeight)	Initializes a new instance of this class.
TreeCommand(string, UIcons, UIconsWeight)	Initializes a new instance of this class.
TreeCommand(Emoji)	Initializes a new instance of this class.
TreeCommand(string, Emoji)	Initializes a new instance of this class.
TreeCommand(ISidebarIcon)	Initializes a new instance of this class.
TreeCommand(string, ISidebarIcon)	Initializes a new instance of this class.

TreeCommand(UIcons, UIconsWeight)

public TreeCommand(UIcons icon, UIconsWeight weight = UIconsWeight.Regular) : this(null, Button().SetIcon(icon, weight: weight))

Initializes a new instance of this class.

Parameters

icon UIcons
weight UIconsWeight

TreeCommand(string, UIcons, UIconsWeight)

public TreeCommand(string href, UIcons icon, UIconsWeight weight = UIconsWeight.Regular) : this(href, Button().SetIcon(icon, weight: weight))

Initializes a new instance of this class.

Parameters

href string
icon UIcons
weight UIconsWeight

TreeCommand(Emoji)

public TreeCommand(Emoji icon) : this(null, Button().SetIcon(icon))

Initializes a new instance of this class.

Parameters

icon Emoji

TreeCommand(string, Emoji)

public TreeCommand(string href, Emoji icon) : this(href, Button().SetIcon(icon))

Initializes a new instance of this class.

Parameters

href string
icon Emoji

TreeCommand(ISidebarIcon)

public TreeCommand(ISidebarIcon image) : this(null, image)

Initializes a new instance of this class.

Parameters

image ISidebarIcon

TreeCommand(string, ISidebarIcon)

public TreeCommand(string href, ISidebarIcon image)

Initializes a new instance of this class.

Parameters

href string
image ISidebarIcon

Methods

Name	Description
Foreground	Sets the foreground color of the command button.
HookToParentContextMenu	Configures the command to hook into the parent tree item's context menu event.
Background	Sets the background color of the command button.
Default	Sets the command to use the default style.
Primary	Sets the command to use the primary style.
Success	Sets the command to use the success style.
Danger	Sets the command to use the danger style.
Tooltip	Sets a tooltip for the command.
OnClickMenu	Configures the command to show a menu when clicked.
ShowMenu	Shows the associated menu for the command.
RaiseOnClick	Programmatically raises the click event.
RaiseOnContextMenu	Programmatically raises the context menu event.
OnClick	Adds a click event handler.
OnContextMenu	Adds a context menu event handler.
SetIcon	Sets the icon for the command.
SetText	Sets the text label for the command.
Render	Renders the tree command.

Method

TreeCommand.Foreground

public TreeCommand Foreground(string color)

Sets the foreground color of the command button.

Method

TreeCommand.HookToParentContextMenu

public TreeCommand HookToParentContextMenu()

Configures the command to hook into the parent tree item's context menu event.

Method

TreeCommand.Background

public TreeCommand Background(string color)

Sets the background color of the command button.

Method

TreeCommand.Default

public TreeCommand Default()

Sets the command to use the default style.

Method

TreeCommand.Primary

public TreeCommand Primary()

Sets the command to use the primary style.

Method

TreeCommand.Success

public TreeCommand Success()

Sets the command to use the success style.

Method

TreeCommand.Danger

public TreeCommand Danger()

Sets the command to use the danger style.

Method

TreeCommand.Tooltip

Overload
Tooltip(string)	Sets a tooltip for the command.
Tooltip(IComponent)	Sets a tooltip component for the command.
Tooltip(Func<IComponent>)	Sets a tooltip generator function for the command.

Tooltip(string)

public TreeCommand Tooltip(string text)

Sets a tooltip for the command.

Parameters

text string

Tooltip(IComponent)

public TreeCommand Tooltip(IComponent tooltip)

Sets a tooltip component for the command.

Parameters

tooltip IComponent

Tooltip(Func<IComponent>)

public TreeCommand Tooltip(Func<IComponent> tooltip)

Sets a tooltip generator function for the command.

Parameters

tooltip Func<IComponent>

Method

TreeCommand.OnClickMenu

public TreeCommand OnClickMenu(Func<TreeCommand[]> generator)

Configures the command to show a menu when clicked.

Parameters

generator: A function that generates the tree commands for the menu.

Method

TreeCommand.ShowMenu

public void ShowMenu()

Shows the associated menu for the command.

Method

TreeCommand.RaiseOnClick

public TreeCommand RaiseOnClick(MouseEvent mouseEvent)

Programmatically raises the click event.

Method

TreeCommand.RaiseOnContextMenu

public TreeCommand RaiseOnContextMenu(MouseEvent mouseEvent)

Programmatically raises the context menu event.

Method

TreeCommand.OnClick

Overload
OnClick(Action)	Adds a click event handler.
OnClick(Action<Button, MouseEvent>)	Adds a click event handler with button and mouse event arguments.

OnClick(Action)

public TreeCommand OnClick(Action action)

Adds a click event handler.

Parameters

action Action

OnClick(Action<Button, MouseEvent>)

public TreeCommand OnClick(Action<Button, MouseEvent> action)

Adds a click event handler with button and mouse event arguments.

Parameters

action Action<Button, MouseEvent>

Method

TreeCommand.OnContextMenu

Overload
OnContextMenu(Action)	Adds a context menu event handler.
OnContextMenu(Action<Button, MouseEvent>)	Adds a context menu event handler with button and mouse event arguments.

OnContextMenu(Action)

public TreeCommand OnContextMenu(Action action)

Adds a context menu event handler.

Parameters

action Action

OnContextMenu(Action<Button, MouseEvent>)

public TreeCommand OnContextMenu(Action<Button, MouseEvent> action)

Adds a context menu event handler with button and mouse event arguments.

Parameters

action Action<Button, MouseEvent>

Method

TreeCommand.SetIcon

Overload
SetIcon(UIcons, string, UIconsWeight)	Sets the icon for the command.
SetIcon(Emoji)	Sets an emoji icon for the command.

SetIcon(UIcons, string, UIconsWeight)

public TreeCommand SetIcon(UIcons icon, string color = "", UIconsWeight weight = UIconsWeight.Regular)

Sets the icon for the command.

Parameters

icon UIcons
color string
weight UIconsWeight

SetIcon(Emoji)

public TreeCommand SetIcon(Emoji icon)

Sets an emoji icon for the command.

Parameters

icon Emoji

Method

TreeCommand.SetText

public TreeCommand SetText(string text)

Sets the text label for the command.

Method

TreeCommand.Render

public HTMLElement Render()

Renders the tree command.