Documentation
Concepts

Features

A minimal core and opt-in features - selection, checkboxes, rename, async children, type-ahead, virtualization, drags - so a tree ships only what it installs.

The tree is a minimal core and opt-in features. With no feature, a tree renders, expands and collapses, and moves one roving tab stop with the WAI-ARIA keys: it is a complete, accessible tree. A feature adds one capability, its state, commands, keys and ARIA, and comes from its own entry: an app that never imports it does not ship it.

featureentryadds
selection(options?)@fragiola/tree-react/selectionthe selected items, the selection mode (single by default, multiple, none), item.select and the other selection commands, the keys and clicks that select, aria-selected, data-selected, aria-multiselectable, and the selectedItemIds prop
checkboxes(options?)@fragiola/tree-react/checkboxestri-state checks (checkedItemIds, cascade by default or independent), item.check, item.toggle-check, aria-checked, data-checked, data-indeterminate, Space to toggle the check (space), and the checkedItemIds prop; the check control is yours (Checkboxes)
rename(options?)@fragiola/tree-react/renamethe renaming item, the renamable flag and default, item.start-rename (F2), item.rename, item.cancel-rename, the engine's commit-rename and cancel-rename, data-renaming, and useTreeItemRename for your own input (Rename)
asyncChildren()@fragiola/tree-react/async-childrenparents whose children come from your loadChildren (childrenStatus), their commands, the engine's load-children, aria-busy, data-loading, data-load-error, and the loadChildren prop (Async loading)
typeAhead(options?)@fragiola/tree-react/type-aheadtyped characters focus the next item whose label starts with them (timeout), and model.get("type-ahead-match") (Keyboard and type-ahead)
virtualization(options?)@fragiola/tree-react/virtualizationa window of the visible items in view, rendered by VirtualItems, for trees of hundreds of thousands of rows (Virtualization)
dragAndDrop(options?)@fragiola/tree-react/drag-and-dropthe Pointer Events drag and the keyboard drag of the tree's items (one item.move per drop), auto-expand and auto-scroll, DropIndicator, data-dragging, data-drop-target, data-drop-position, and the drag keys (drop-target, start-keyboard-drag, …) (Drag and drop)
dragGroup({ name, transfer? })@fragiola/tree-react/drag-groupdrags between the trees of a group, a transfer between two models, data-dragging-from-other-tree; needs dragAndDrop() (Between trees)
foreignDrop({ accept?, onDrop })@fragiola/tree-react/foreign-dropfiles, links and text dropped from outside, with the same target and DropIndicator, with or without dragAndDrop() (Foreign content)
dropOutside({ onDrop })@fragiola/tree-react/drop-outsiderows dropped on your own targets outside every tree, drop-outside-element; needs dragAndDrop() (Dropping outside)

item.move and the movable and droppable flags stay in the core: a tree without drag and drop still moves items by command. Each framework's package has the same entries (@fragiola/tree-vue/selection, @fragiola/tree-angular/virtualization, …), and the core's are @fragiola/tree/<feature>.

Installing

The model takes its features once, when it is created, and keeps them: a later change of a root's features prop is ignored, with a warning.

import { createTreeModel, Tree } from "@fragiola/tree-react";
import { selection } from "@fragiola/tree-react/selection";

const features = [selection({ mode: "multiple" })] as const;

export function Files() {
    const [model] = useState(() => createTreeModel<Types, typeof features>(json, { features }));
    const count = useTreeState((state) => state.selectedItemIds.length, { model });
    return (
        <Tree.Root model={model} aria-label="Files">
            <Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
        </Tree.Root>
    );
}

// or a root that creates its own model
<Tree.Root<Types, typeof features> defaultTree={json} features={features} aria-label="Files">

Typed by the features

The features type the model, the engine and everything around them. model.run("item.select", …) compiles only with selection(); model.state.selectedItemIds and engine.get("virtual-window") exist only with their feature; a root's selectedItemIds prop compiles only when its model has the selection. At runtime, a command of a feature that is not installed returns not_found, its get key reads undefined and its is key answers false: nothing throws.

TypeScript infers the features from createTreeModel(json, { features }) when it infers the registry too. When you give the registry (createTreeModel<Types>(…)), give the features as well (createTreeModel<Types, typeof features>(…), with const features = [...] as const), and in the same way to Tree.Root, useTree, useTreeRef, useTreeState and typedTree. Given a model, useTreeState infers them.

Documents

A document is the same JSON with or without features (The JSON model), and a field belongs to its feature: selectedItemIds, selectionAnchorItemId and settings.selectionMode load only into a model with selection(); checkedItemIds and settings.checkMode with checkboxes(); renamingItemId, settings.renamable and an item's renamable with rename(); an item's childrenStatus with asyncChildren(). Elsewhere they are a validation issue (requires the selection feature), never dropped silently, and model.get("tree-json") writes only the installed features' fields. Check a saved document against the model's features with validateTree(json, { features }).

What stays outside

As everywhere in the tree: no styles, no rendered menus, no text. A feature gives behaviour, state, ARIA and data-*; what its state looks like is your CSS ([data-selected]). The bundle of each package is checked by pnpm build: no main entry contains a feature's code.