🌲 TreeForge - Getting Started

A lightweight, dependency-free JavaScript package for rendering file trees with style.

📦 Installation

npm install treeforge

Don't forget the CSS!

Add the TreeForge UI stylesheet to your HTML:

<!-- Option 1: Direct link (CDN) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/styles/ui.css">

<!-- Option 2: From node_modules -->
<link rel="stylesheet" href="node_modules/treeforge/styles/ui.css">

<!-- Option 3: Import in JS (with bundler) -->
<script>
import 'treeforge/styles/ui.css';
</script>

🚀 Quick Start (3 Lines)

import TreeForge, { ConfigPresets } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: { name: 'root', type: 'folder', children: [] },
    ...ConfigPresets.GITHUB_CLONE  // That's it!
});

Output:

📁 root
└── (empty folder)

✨ What You Get

🎨 15 Beautiful Styles

import { TreeStyles } from 'treeforge';

settings: TreeStyles.GITHUB            // GitHub style
settings: TreeStyles.VSCODE_DARK       // VS Code dark
settings: TreeStyles.DRACULA           // Dracula theme
settings: TreeStyles.NORD              // Nord theme
// ... and 11 more!

⚙️ 15 Configuration Presets

import { ConfigPresets } from 'treeforge';

...ConfigPresets.GITHUB_CLONE         // GitHub browser
...ConfigPresets.VSCODE_CLONE         // VS Code editor
...ConfigPresets.FILE_MANAGER         // File manager
...ConfigPresets.DOCS_BROWSER         // Documentation
// ... and 11 more!

🪝 10 Lifecycle Hooks

hooks: {
    onCreateFile: (path) => {},
    onDeleteFile: (path) => {},
    onReadFile: (path) => {},
    onWriteFile: (path, content) => {},
    // ... and 6 more!
}

📖 Complete Examples

Example 1: Simple Tree

import TreeForge from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: {
        name: 'my-project',
        type: 'folder',
        children: [
            { name: 'src', type: 'folder', children: [] },
            { name: 'README.md', type: 'file' }
        ]
    }
});

Example 2: With Built-in Style

import TreeForge, { TreeStyles } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    settings: TreeStyles.VSCODE_DARK  // Beautiful VS Code style!
});

Example 3: Complete Configuration Preset

import TreeForge, { ConfigPresets } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    ...ConfigPresets.FILE_MANAGER  // Includes: style, features, shortcuts, menus!
});

Example 4: With API Backend

import TreeForge, { ConfigPresets, RestApiHooks } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    ...ConfigPresets.VSCODE_CLONE,
    onLoad: async () => {
        const res = await fetch('/api/tree');
        return await res.json();
    },
    hooks: RestApiHooks  // Pre-built REST API hooks!
});

Example 5: With LocalStorage

import TreeForge, { TreeStyles, LocalStorageHooks } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    settings: TreeStyles.GITHUB,
    hooks: LocalStorageHooks  // Auto-save to localStorage!
});

🎯 Import Guide

Main Imports

// TreeForge class (default export)
import TreeForge from 'treeforge';

// Everything else (named exports)
import { 
    TreeStyles,           // 15 visual styles
    ConfigPresets,        // 15 complete configs
    LocalStorageHooks,    // Pre-built hooks
    RestApiHooks,         // Pre-built hooks
    combineHooks,         // Utility functions
    getPreset,
    mergePresets
} from 'treeforge';

All Available Exports

import TreeForge, {
    // Styles & Presets
    TreeStyles,              // 15 visual themes
    ConfigPresets,           // 15 complete configurations
    
    // Hook Examples
    LocalStorageHooks,       // Save to localStorage
    RestApiHooks,            // Connect to REST API
    AnalyticsHooks,          // Track events
    ValidationHooks,         // Validate operations
    CacheHooks,              // Cache file content
    AutoSaveHooks,           // Auto-save with debounce
    combineHooks,            // Combine multiple hooks
    
    // Utilities
    getPreset,               // Get specific preset
    mergePresets,            // Merge presets
    listPresets,             // List all presets
    createConfig,            // Create custom config
    validateConfig,          // Validate config
    
    // References
    SettingsReference,
    EditorConfigReference,
    TreeDataStructure
} from 'treeforge';

📚 Documentation

• HOW_TO_USE.md - Import guide and patterns
• DOCUMENTATION.md - Complete documentation (1600+ lines)
• QUICK_REFERENCE.md - Cheat sheet
• CONFIG_README.md - Configuration guide
• COMPLETE_REFERENCE.md - API reference
• mds/README.md - Documentation index: an organized table-of-contents for the mds/ docs folder.

🎨 All 15 Styles

| Style | Theme | Usage | |-------|-------|-------| | MINIMAL | Basic | TreeStyles.MINIMAL | | GITHUB | GitHub | TreeStyles.GITHUB | | VSCODE_DARK | VS Code Dark | TreeStyles.VSCODE_DARK | | VSCODE_LIGHT | VS Code Light | TreeStyles.VSCODE_LIGHT | | COLORFUL | Vibrant | TreeStyles.COLORFUL | | MATERIAL_DARK | Material Dark | TreeStyles.MATERIAL_DARK | | MATERIAL_LIGHT | Material Light | TreeStyles.MATERIAL_LIGHT | | ASCII | Terminal | TreeStyles.ASCII | | ASCII_COMPACT | Compact | TreeStyles.ASCII_COMPACT | | MONOCHROME | B&W | TreeStyles.MONOCHROME | | SOLARIZED_DARK | Solarized | TreeStyles.SOLARIZED_DARK | | DRACULA | Dracula | TreeStyles.DRACULA | | NORD | Nord | TreeStyles.NORD | | ONE_DARK | One Dark | TreeStyles.ONE_DARK | | HIGH_CONTRAST | Accessible | TreeStyles.HIGH_CONTRAST |

⚙️ All 15 Configuration Presets

| Preset | Best For | Usage | |--------|----------|-------| | MINIMAL | Simple trees | ConfigPresets.MINIMAL | | GITHUB_CLONE | Repo browser | ConfigPresets.GITHUB_CLONE | | VSCODE_CLONE | Code editor | ConfigPresets.VSCODE_CLONE | | FILE_MANAGER | File operations | ConfigPresets.FILE_MANAGER | | DOCS_BROWSER | Documentation | ConfigPresets.DOCS_BROWSER | | MEDIA_BROWSER | Photos/videos | ConfigPresets.MEDIA_BROWSER | | CODE_EDITOR | Code playground | ConfigPresets.CODE_EDITOR | | TERMINAL_STYLE | CLI aesthetic | ConfigPresets.TERMINAL_STYLE | | COMPACT | Sidebar | ConfigPresets.COMPACT | | ACCESSIBLE | Screen readers | ConfigPresets.ACCESSIBLE | | MOBILE_OPTIMIZED | Touch devices | ConfigPresets.MOBILE_OPTIMIZED | | LARGE_DATASET | 10,000+ files | ConfigPresets.LARGE_DATASET | | COLLABORATIVE | Team workspace | ConfigPresets.COLLABORATIVE | | READ_ONLY | View-only | ConfigPresets.READ_ONLY | | DRACULA_THEME | Dracula colors | ConfigPresets.DRACULA_THEME | | NORD_THEME | Nord colors | ConfigPresets.NORD_THEME |

🪝 All 10 Hooks

hooks: {
    onCreateFile: (path, parentNode) => {},      // File created
    onCreateFolder: (path, parentNode) => {},    // Folder created
    onDeleteFile: (path, node) => {},            // File deleted
    onDeleteFolder: (path, node) => {},          // Folder deleted
    onDeleteNode: (path, node) => {},            // Any node deleted
    onRenameNode: (oldPath, newPath, node) => {},// Node renamed
    onReadFile: (path, node) => 'content',       // Read file
    onWriteFile: (path, content, node) => {},    // Write file
    onLoad: () => treeData,                      // Load data
    onFileOpen: (path, content, node) => {}      // File opened
}

💡 Common Patterns

Pattern: GitHub-style Browser

import TreeForge, { ConfigPresets } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    ...ConfigPresets.GITHUB_CLONE
});

Pattern: VS Code-style Editor

import TreeForge, { ConfigPresets } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    ...ConfigPresets.VSCODE_CLONE
});

Pattern: Custom Style + Hooks

import TreeForge, { TreeStyles, LocalStorageHooks } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    settings: TreeStyles.DRACULA,
    hooks: LocalStorageHooks
});

Pattern: Preset + Override

import TreeForge, { ConfigPresets, TreeStyles } from 'treeforge';

const tree = new TreeForge({
    containerId: 'tree',
    localData: myData,
    ...ConfigPresets.FILE_MANAGER,  // Full features
    settings: TreeStyles.NORD       // But use Nord theme
});

🎯 Key Features

✅ Zero Dependencies - Pure vanilla JavaScript
✅ 15 Styles - Beautiful pre-built themes
✅ 15 Presets - Complete configurations ready to use
✅ 10 Hooks - Full control over CRUD operations
✅ Lightweight - <15KB minified
✅ Type Safe - TypeScript interfaces included
✅ Framework Agnostic - Works with React, Vue, Angular, vanilla JS
✅ Fully Documented - 1600+ lines of documentation

🔗 Links

• GitHub: https://github.com/abmercy035/treeforge
• NPM: https://npmjs.com/package/treeforge
• Issues: https://github.com/abmercy035/treeforge/issues
• Documentation: DOCUMENTATION.md

📄 License

ISC © abmercy035

TreeForge - Render trees beautifully in 3 lines of code 🌲✨