leaf/widgets/file_browser_widget/pkg

FileBrowser Widget

A powerful WebAssembly-based file browser widget that can be embedded in any web application. Built with Rust and Yew, compiled to WASM for maximum performance.

Features

• 📁 File & Directory Management: Browse, create, delete files and directories
• 📤 Resumable Uploads: Upload files with progress tracking using TUS protocol
• 📥 File Downloads: Download files with proper MIME type handling
• ✏️ File Editing: Built-in editors for text files and markdown with live preview
• 🎨 Modern UI: Responsive Bootstrap-based interface with light/dark themes
• 🔧 Highly Configurable: Extensive JavaScript API for customization
• 🚀 High Performance: Compiled to WebAssembly for native-like performance
• 🌐 Cross-Browser: Works in all modern browsers

Quick Start

1. Installation

Via npm (recommended)

npm install @herocode/file-browser-widget

Manual Download

Download the latest release files:

• file_browser_widget.js
• file_browser_widget_bg.wasm

2. Include Dependencies

Add Bootstrap CSS and Icons to your HTML:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css" rel="stylesheet">

3. Create Container

Add a container element to your HTML:

<div id="file-browser-container"></div>

4. Initialize Widget

import init, { 
    create_file_browser_widget, 
    create_default_config 
} from '@herocode/file-browser-widget';

async function initFileBrowser() {
    // Initialize the WASM module
    await init();
    
    // Create configuration
    const config = create_default_config('http://localhost:3001/files');
    config.set_theme('light');
    config.set_show_upload(true);
    config.set_show_download(true);
    config.set_show_delete(true);
    config.set_max_file_size(100 * 1024 * 1024); // 100MB
    
    // Create and mount the widget
    const widget = create_file_browser_widget('file-browser-container', config);
    
    console.log('FileBrowser widget initialized successfully!');
}

// Initialize when page loads
initFileBrowser().catch(console.error);

Configuration API

WidgetConfig

The main configuration object for customizing the widget behavior:

const config = create_default_config('http://localhost:3001/files');

// File size limit (in bytes)
config.set_max_file_size(50 * 1024 * 1024); // 50MB

// Feature toggles
config.set_show_upload(true);
config.set_show_download(true);
config.set_show_delete(true);

// UI customization
config.set_theme('dark'); // 'light' or 'dark'
config.set_css_classes('my-custom-class');
config.set_initial_path('documents/');

Configuration Options

Option	Type	Default	Description
base_endpoint	string	required	Backend API endpoint for file operations
max_file_size	number	104857600	Maximum file size for uploads (bytes)
show_upload	boolean	true	Enable/disable upload functionality
show_download	boolean	true	Enable/disable download functionality
show_delete	boolean	true	Enable/disable delete functionality
theme	string	'light'	UI theme ('light' or 'dark')
css_classes	string	''	Additional CSS classes for root element
initial_path	string	''	Initial directory path to display

JavaScript API

Functions

init()

Initialize the WASM module. Must be called before using other functions.

await init();

create_default_config(base_endpoint)

Create a default configuration object.

const config = create_default_config('http://localhost:3001/files');

create_file_browser_widget(container_id, config)

Create and mount a widget to a DOM element by ID.

const widget = create_file_browser_widget('my-container', config);

create_file_browser_widget_on_element(element, config)

Create and mount a widget to a specific DOM element.

const element = document.getElementById('my-container');
const widget = create_file_browser_widget_on_element(element, config);

check_browser_compatibility()

Check if the current browser supports the widget.

if (!check_browser_compatibility()) {
    console.error('Browser not supported');
}

get_version()

Get the widget version.

console.log('Widget version:', get_version());

Widget Handle

The widget functions return a handle that can be used to manage the widget:

const widget = create_file_browser_widget('container', config);

// Destroy the widget
widget.destroy();

Backend Requirements

The widget expects a REST API compatible with the following endpoints:

File Listing

GET /files/list/<path>
Response: JSON array of file/directory objects

Directory Creation

POST /files/dirs/<path>
Creates a new directory at the specified path

File/Directory Deletion

DELETE /files/delete/<path>
Deletes the file or directory at the specified path

File Upload (TUS Protocol)

POST /files/upload
Handles resumable file uploads using TUS protocol

File Download

GET /files/download/<path>
Returns the file content with appropriate headers

Example Backend Response Format

File listing response:

[
  {
    "name": "document.pdf",
    "path": "documents/document.pdf",
    "size": 1024000,
    "is_directory": false,
    "modified": "2023-12-01T10:30:00Z"
  },
  {
    "name": "images",
    "path": "documents/images",
    "size": 0,
    "is_directory": true,
    "modified": "2023-12-01T09:15:00Z"
  }
]

Advanced Usage

Custom Styling

Add custom CSS to style the widget:

.file-browser-widget {
    border: 1px solid #ddd;
    border-radius: 8px;
    overflow: hidden;
}

.file-browser-widget .card {
    border: none;
}

Multiple Widgets

You can create multiple widget instances on the same page:

// Widget 1
const config1 = create_default_config('http://api1.example.com/files');
const widget1 = create_file_browser_widget('container1', config1);

// Widget 2  
const config2 = create_default_config('http://api2.example.com/files');
config2.set_theme('dark');
const widget2 = create_file_browser_widget('container2', config2);

Error Handling

try {
    const widget = create_file_browser_widget('container', config);
} catch (error) {
    console.error('Failed to create widget:', error);
    // Show fallback UI
}

Development

Building from Source

1. Install Rust and wasm-pack:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack

2. Build the widget:

./build.sh

3. Test locally:

npm run dev
# Open http://localhost:8000/example.html

Project Structure

widgets/file_browser_widget/
├── src/
│   └── lib.rs              # Main widget implementation
├── dist/                   # Built distribution files
├── pkg/                    # wasm-pack output
├── Cargo.toml             # Rust dependencies
├── package.json           # npm package config
├── build.sh               # Build script
└── README.md              # This file

Browser Support

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

The widget requires WebAssembly support and modern JavaScript features.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions