Wunderbaum

wunderbaum is a modern, framework-agnostic tree and treegrid control for the web. It is the designated successor to Fancytree. It is designed to be performant with large data structures and provides an object-oriented API with zero dependencies.

Key features include:

• Drag and drop, editing, filtering, sorting, and multi-selection.
• Full keyboard support.
• Written in TypeScript and distributed as ES6 (ESM & UMD).
• Framework agnostic (can be used with any JS framework or vanilla JS).

Wunderbaum is a modern, framework-agnostic JavaScript tree/treegrid control designed for high performance with large data structures. It supports features like drag and drop, editing, filtering, sorting, multi-selection, and full keyboard support.

Note: Wunderbaum is currently in beta status. Its API, markup, and stylesheets are subject to change.

Wunderbaum implements drag and drop using the native HTML Drag and Drop API. This enables interaction between different tree instances, different browsers, and even native applications.

Key Concept: Manual Tree Modification Crucially, Wunderbaum does not automatically modify the tree structure during a drag-and-drop operation. Instead, the tree fires a drop event, and the application developer is responsible for manually updating the tree (e.g., using node.moveTo() or node.addNode()) based on the event data.

Wunderbaum is built around a tree data model consisting of a Wunderbaum class instance containing a hierarchical structure of WunderbaumNode objects.

Nodes can exist in several independent states simultaneously:

• Active
• Selected
• Focused
• Hovered

Because these states are independent, a single node can be active, selected, and focused all at once, or none of these. The data model can be initialized from a JavaScript object, an Ajax JSON response, or a generator function. You interact with the tree using an object-oriented API (e.g., tree.getNodeByKey(), node.setTitle(), or node.setExpanded()).

Wunderbaum uses a viewport concept: the rectangular, scrollable area on the page that contains the tree.

To maintain high performance with large datasets (100k+ nodes), Wunderbaum uses on-demand rendering. Only nodes currently visible within the viewport are materialized as HTML elements in the DOM. Additionally, children of collapsed parent nodes do not have HTML elements.

Important Developer Guidelines:

• Do not manipulate HTML directly. Instead, modify the data model and call tree.update() or node.update() to reflect changes.
• Event Binding: Because of lazy rendering, you cannot bind events directly to all node HTML elements. Instead, use Wunderbaum's built-in event handlers (like click, dblclick, and keypress) or use standard event delegation.

The most common format is a single object containing a children array. This format allows you to include metadata like types, columns, and _keyMap alongside the tree structure.

{
  "types": {...},
  "columns": [...],
  "_keyMap": {...},
  "children": [
    {
      "title": "Books",
      "expanded": true,
      "children": [
        {
          "title": "Art of War",
          "author": "Sun Tzu"
        },
      ]
    },
    ...
  ]
}

Wunderbaum supports two patterns of lazy loading to handle hierarchical structures of potentially infinite size:

1. Delayed Initialization: The entire tree initialization can be delayed until an asynchronous Ajax request completes. This shows a spinner icon until the data arrives, ensuring fast initial page loads.
2. Lazy Child Nodes: Individual nodes can be marked as 'lazy'. These nodes trigger Ajax requests to fetch their children only when they are expanded for the first time.

Caveats for Lazy Loading: Since the complete tree data model or all DOM elements might not be present in the browser, certain API functions like tree.getNodeByKey() or node.findAll() may not work as expected if the required nodes haven't been loaded yet.

When providing data via source, Wunderbaum maps JSON properties to a specific node model.

Reserved Attributes: These properties are part of the core model and are accessed directly (e.g., node.title). They include:

• checkbox, classes, expanded, icon, iconTooltip, key, lazy, radiogroup, refKey, selected, statusNodeType, title, tooltip, type, unselectable.

Custom Data: Any property not in the reserved list is stored under the data namespace. You access these via node.data.propertyName (e.g., node.data.author).

Important Notes:

• title is the only mandatory property.
• Node titles are automatically escaped to prevent XSS attacks.
• The structure can be nested using a children list.