npm package: @paneton/tree
Description: A modern, powerful hierarchical tree component with virtual rendering for massive datasets
Author: @lewopxd
Latest version: 1.0.0

# @paneton/tree

> A modern, powerful, and efficient hierarchical tree component with high-performance virtual rendering engine for massive datasets.

[![npm version](https://img.shields.io/npm/v/@paneton/tree.svg)](https://www.npmjs.com/package/@paneton/tree)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🚀 **Virtual Rendering** - Handle thousands of nodes without performance degradation
- 🎨 **Fully Themable** - CSS variables for complete customization
- 📦 **Zero Dependencies** - Self-contained, no external dependencies
- 🔧 **Rich API** - Programmatic control with intuitive methods
- 🎯 **Compact Folders** - Smart folder compaction for cleaner hierarchies
- 🔍 **Node Search** - Built-in findNode() and revealNode() methods
- ⚡ **Event Callbacks** - onClick, onExpand handlers for all nodes
- 🎮 **Custom Actions** - Add buttons with custom icons and callbacks
- ♿ **Accessible** - Keyboard navigation ready
- 📱 **Responsive** - Works on all screen sizes

## 📦 Installation
```bash
npm install @paneton/tree
```

Or using yarn:
```bash
yarn add @paneton/tree
```

Or via CDN:
```html
<script src="https://unpkg.com/@paneton/tree/dist/paneton.tree.min.js"></script>
```

## 🚀 Quick Start
```html
<!DOCTYPE html>
<html>
<head>
    <style>
        #tree-container { 
            height: 400px; 
            width: 300px;
        }
    </style>
</head>
<body>
    <div id="tree-container"></div>
    
    <script src="node_modules/@paneton/tree/dist/paneton.tree.min.js"></script>
    <script>
        const tree = new Paneton.Tree('#tree-container', {
            data: [
                {
                    name: 'Documents',
                    icon: '📁',
                    children: [
                        { name: 'Resume.pdf', icon: '📄' },
                        { name: 'Cover Letter.docx', icon: '📝' }
                    ]
                },
                {
                    name: 'Images',
                    icon: '📁',
                    children: [
                        { name: 'vacation.jpg', icon: '🖼️' },
                        { name: 'screenshot.png', icon: '🖼️' }
                    ]
                }
            ]
        });
    </script>
</body>
</html>
```

## 📚 Basic Usage

### Creating a Tree
```javascript
const tree = new Paneton.Tree('#container', {
    data: [], // Your hierarchical data
    theme: {}, // Theme customization
    compactFolders: false, // Enable folder compaction
    sortNodes: true, // Auto-sort nodes
    autoHideButtons: false, // Auto-hide action buttons
    expandOnClick: false, // Expand folders on label click
    showSegments: true // Show indent guide lines
});
```

### Data Structure
```javascript
const data = [
    {
        name: 'Folder Name',
        icon: '📁', // Optional icon
        expanded: true, // Optional: default expanded state
        children: [
            {
                name: 'File Name',
                icon: '📄',
                buttons: [ // Optional action buttons
                    {
                        icon: '<svg>...</svg>',
                        tooltip: 'Delete',
                        onClick: (nodeAPI) => {
                            console.log('Delete clicked', nodeAPI);
                        }
                    }
                ],
                onClick: (nodeAPI) => {
                    console.log('Node clicked', nodeAPI);
                }
            }
        ],
        onExpand: (isExpanded, nodeAPI) => {
            console.log('Folder expanded:', isExpanded);
        }
    }
];
```

## 🎨 Theming

Customize the tree appearance using the theme object:
```javascript
const tree = new Paneton.Tree('#container', {
    data: myData,
    theme: {
        backgroundColor: '#1e1e1e',
        nodeTextColor: '#ffffff',
        nodeBackgroundHover: '#2a2a2a',
        nodeBackgroundSelected: '#3a3a3a',
        fontFamily: 'Arial, sans-serif',
        fontSize: '14px'
    }
});
```

## 🔧 API Methods

### findNode(path)
Find a node by its full path:
```javascript
const node = tree.findNode('Documents/Images/photo.jpg');
if (node) {
    console.log(node.data);
    node.select();
    node.expand();
}
```

### revealNode(path)
Scroll to and select a node:
```javascript
tree.revealNode('Documents/Deep/Nested/File.txt').then(element => {
    console.log('Node revealed:', element);
});
```

### add(nodes, options)
Add nodes dynamically:
```javascript
tree.add([
    { name: 'New File.txt', icon: '📄' }
], {
    parentPath: 'Documents'
});
```

### destroy()
Clean up the tree instance:
```javascript
tree.destroy();
```

## 🎯 Advanced Features

### Compact Folders

Automatically compact single-child folder chains:
```javascript
const tree = new Paneton.Tree('#container', {
    data: myData,
    compactFolders: true // src/components/ui → src/components/ui
});
```

### Auto-hide Buttons

Hide action buttons until hover:
```javascript
const tree = new Paneton.Tree('#container', {
    data: myData,
    autoHideButtons: 'activeNode' // or 'all'
});
```

### Custom Buttons

Add custom action buttons to any node:
```javascript
{
    name: 'MyFile.txt',
    buttons: [
        {
            icon: '<svg>...</svg>',
            tooltip: 'Download',
            onClick: (nodeAPI) => downloadFile(nodeAPI.path)
        },
        {
            icon: '<svg>...</svg>',
            tooltip: 'Share',
            onClick: (nodeAPI) => shareFile(nodeAPI.path)
        }
    ]
}
```

## 📖 Full Documentation

For complete API reference and advanced examples, visit:
- [API Reference](../../docs/api-reference.md)
- [Getting Started Guide](../../docs/getting-started.md)
- [Examples](../../docs/examples/)

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

## 📄 License

MIT © [@lewopxd](https://github.com/lewopxd)

## 🔗 Links

- [GitHub Repository](https://github.com/0zdev/paneton)
- [Issue Tracker](https://github.com/0zdev/paneton/issues)
- [NPM Package](https://www.npmjs.com/package/@paneton/tree)

---

**Part of the [Paneton Framework](https://github.com/0zdev/paneton)** 🥖