@nezam.ai/web-tree

Reusable browser tree control for application sidebars, explorers, and catalog surfaces.

What It Provides

• compact tree rows with keyboard navigation
• searchable fuzzy filtering with highlighted matches
• collapse and expand all controls
• VS Code-style indentation guides and sticky-scroll ancestor rails
• optional favorite toggles
• optional copyable code badges
• accessible tree and treeitem roles

Public API

Import from @nezam.ai/web-tree:

import { createTreeControl, filterTreeNodes } from '@nezam.ai/web-tree';

createTreeControl(options) accepts:

• nodes
• selectedNodeId
• onSelect
• onActivate
• onToggle
• onFavoriteToggle
• onCodeClick
• searchable
• searchPlaceholder
• searchClearLabel
• searchQuery
• searchIncludeAncestorLabels
• searchNotFoundMessage
• defaultFindMode
• defaultFindMatchType
• showNotFoundMessage
• showSearchClearButton
• emptyMessage
• defaultExpandAll
• defaultExpandDepth
• indentSize
• expandOnRowClick
• expandOnDoubleClick
• keyboardSupport
• typeNavigationEnabled
• typeNavigationMode
• enableStickyScroll
• stickyScrollMaxItemCount
• multipleSelectionSupport
• showFavoriteToggle
• favoriteNodeIds
• ariaLabel

The returned control exposes:

• element
• findMode
• findMatchType
• showNotFoundMessage
• enableStickyScroll
• stickyScrollMaxItemCount
• focus()
• select()
• focusSearch()
• setPlaceHolder(text)
• openFind()
• closeFind()
• style(styles)
• getSelection()
• setSelection(nodeIds)
• getFocus()
• setFocus(nodeId)
• getNode(nodeId)
• getNodeLocation(node)
• getHistory()
• setSearchQuery(query)
• clearSearch()
• showMessage(message)
• clearMessage()
• expandAll()
• collapseAll()
• toggleAllExpanded()
• setCollapsed(nodeId, collapsed?, recursive?)
• expand(nodeId, recursive?)
• collapse(nodeId, recursive?)
• toggleCollapsed(nodeId, recursive?)
• isCollapsible(nodeId)
• expandTo(nodeId)
• isCollapsed(nodeId)
• update(options)
• destroy()
• triggerTypeNavigation()

filterTreeNodes(nodes, query, options) is exported for adapters that need to reuse the same filtering behavior outside the widget.

Filtering

The filter keeps matching branches visible and preserves ancestor context. By default, node search text includes the node label, description, searchable text, kind, code, and ancestor labels. The defaultFindMode option switches between filtering and highlight-only search, and defaultFindMatchType switches between fuzzy and contiguous matching.

Styling

The package ships a standalone CSS contract at @nezam.ai/web-tree/style.css. Adapters can layer their own classes on top of the shared tree classes:

• ui-lib-tree-control
• ui-lib-tree-control-toolbar
• ui-lib-tree-control-search
• ui-lib-tree-control-row
• ui-lib-tree-control-code
• ui-lib-tree-control-star

For runtime theme tweaks, style(styles) scopes the tree-specific colors and sticky-scroll treatment to a single instance.

Demos

Run the standalone demo gallery from the package root:

cd packages/web/tree
npm run demo

Open http://127.0.0.1:8080/tree/demos/ after the server starts.

The gallery renders several live tree instances that cover selection, searching, scoped filtering, ancestor-aware search toggles, search updates, search toolbar updates, search messages, code search, code search updates, transaction code search, payload alias search, kind search, selection search, count refresh, header and aria-label updates, empty-state copy updates, default expansion policy updates, runtime class hook updates, search toolbar visibility updates, favorite set updates, icon metadata updates, explicit icon precedence, interaction hub callbacks, composite refresh updates, class surface styling, expand/collapse methods, explorer mode search and row clicks, metadata updates, lifecycle teardown and remount cycles, row click expansion policy updates, double-click expansion, chrome updates, collapse/expand controls, favorites, copyable codes, descriptions, group icon states, icons, counts, empty states, header text, indent spacing, search without a clear button, no search bar, class hooks, row click toggles, selection activation, toggle callbacks, custom clear labels, favorite toggle visibility, favorite callbacks, selection updates, callback swapping, code callbacks, header suppression in non-searchable mode, VS Code-style guide rails, sticky-scroll keyboard behavior, guide rails showcase, guide ordering, guide stacking, and office-ribbon-inspired combined catalog coverage, and live updates.