leaf/examples/file_browser_demo/README.md

File Browser Demo

A comprehensive file browser component built with Yew (Rust) and compiled to WebAssembly, featuring Uppy.js integration for resumable file uploads via the TUS protocol.

Features

• 📁 File System Browser: Navigate directories, view files with metadata
• ⬆️ Resumable Uploads: TUS protocol support via Uppy.js for reliable file uploads
• ⬇️ File Downloads: Direct download with progress tracking
• 🗂️ Directory Management: Create and delete directories
• 🗑️ File Management: Delete files with confirmation
• 📊 Progress Tracking: Real-time upload progress with visual indicators
• 🎨 Modern UI: Bootstrap-styled responsive interface
• 🚀 WebAssembly: High-performance Rust code compiled to WASM

Architecture

Component Structure

FileBrowser
├── FileBrowserConfig (Properties)
├── FileBrowserMsg (Messages)
├── API Functions (HTTP calls to backend)
└── Uppy.js Integration (JavaScript interop)

Key Components

1. FileBrowser: Main Yew component with file listing, navigation, and upload UI
2. FileBrowserConfig: Configuration struct for customizing the widget
3. API Layer: Async functions for backend communication using web_sys::fetch
4. Uppy Integration: JavaScript interop for TUS resumable uploads

Configuration Options

The FileBrowserConfig struct allows extensive customization:

FileBrowserConfig {
    base_endpoint: "/files".to_string(),        // Backend API endpoint
    max_file_size: 100 * 1024 * 1024,          // Max file size (100MB)
    chunk_size: 1024 * 1024,                   // Download chunk size (1MB)
    initial_path: "".to_string(),              // Starting directory
    show_upload: true,                         // Enable upload functionality
    show_download: true,                       // Enable download functionality
    show_delete: true,                         // Enable delete functionality
    show_create_dir: true,                     // Enable directory creation
    css_classes: "container-fluid".to_string(), // Custom CSS classes
    theme: "light".to_string(),                // Uppy theme (light/dark)
}

Backend Compatibility

The file browser component is designed to work with the Python Flask backend from src/files.py. It expects the following API endpoints:

• GET /files/list/{path} - List directory contents
• POST /files/upload - TUS resumable upload endpoint
• GET /files/download/{path} - Download files
• POST /files/dirs/{path} - Create directories
• DELETE /files/delete/{path} - Delete files/directories

Mock Server

For testing and development, this demo includes a Rust-based mock server that implements the same API as the Python backend:

Location: mock-server/

Features:

• Full API compatibility with src/files.py
• Sample files and directories for testing
• CORS enabled for frontend development
• Lightweight and fast
• No external dependencies beyond Rust

Manual Usage:

# Start just the mock server
./run-mock-server.sh

# Or run manually
cd mock-server
cargo run --release

Quick Start

Prerequisites

• Rust (latest stable version)
• trunk for building and serving WASM applications:

  cargo install trunk
  

• wasm32-unknown-unknown target:

  rustup target add wasm32-unknown-unknown
  

Easy Demo Launch

The quickest way to see the file browser in action:

./run-demo.sh

This script will:

1. Build and start the Rust mock server on http://localhost:3001
2. Build and serve the WASM demo on http://localhost:8080
3. Automatically open your browser to the demo
4. Handle cleanup when you press Ctrl+C

Prerequisites

1. Rust and Trunk:

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

2. Backend Server: The Python Flask backend from the knowledgecenter project

Building and Running

1. Build the WASM Application

# From the file_browser_demo directory
./build.sh

This will:

• Build the Rust code to WebAssembly using Trunk
• Generate optimized WASM and JavaScript files
• Output files to the dist/ directory

2. Start the Backend Server

# From the knowledgecenter directory
cd /path/to/knowledgecenter
python -m flask run

Make sure CORS is configured to allow requests from your frontend origin.

3. Serve the Frontend

Development Mode:

# From the file_browser_demo directory
trunk serve

Production Mode:

# From the file_browser_demo directory
./serve.sh

4. Open in Browser

Trunk will automatically open http://127.0.0.1:8080 in your web browser.

Usage as a Widget

The file browser can be used as a reusable widget in other Yew applications:

use framework::components::{FileBrowser, FileBrowserConfig};

#[function_component(MyApp)]
fn my_app() -> Html {
    let config = FileBrowserConfig {
        base_endpoint: "/api/files".to_string(),
        initial_path: "documents".to_string(),
        theme: "dark".to_string(),
        ..Default::default()
    };

    html! {
        <div class="my-app">
            <FileBrowser ..config />
        </div>
    }
}

Customization

Styling

The component uses Bootstrap classes and can be customized via:

1. CSS Classes: Pass custom classes via css_classes in config
2. Theme: Set Uppy theme to "light" or "dark"
3. Custom CSS: Override the default styles in your application

Functionality

Enable/disable features via configuration:

FileBrowserConfig {
    show_upload: false,     // Hide upload functionality
    show_delete: false,     // Hide delete buttons
    show_create_dir: false, // Hide directory creation
    // ... other options
}

Development

Project Structure

file_browser_demo/
├── Cargo.toml          # Rust dependencies
├── build.sh            # Build script
├── index.html          # HTML template with Uppy.js
├── src/
│   └── main.rs         # Main Yew application
└── README.md           # This file

Key Dependencies

• yew: Rust web framework
• wasm-bindgen: Rust/JavaScript interop
• web-sys: Web API bindings
• serde: Serialization for API communication
• js-sys: JavaScript value manipulation

JavaScript Dependencies

• Uppy.js: File upload library with TUS support
• Bootstrap: UI framework
• Bootstrap Icons: Icon set

Troubleshooting

WASM Module Loading Issues

1. Ensure files are served over HTTP (not file://)
2. Check browser console for detailed error messages
3. Verify WASM files are generated in pkg/ directory

Upload Issues

1. Check backend server is running and accessible
2. Verify CORS configuration allows your frontend origin
3. Ensure TUS endpoints are properly implemented in backend

Build Issues

1. Update Rust toolchain: rustup update
2. Clear cargo cache: cargo clean
3. Reinstall wasm-pack if needed

Browser Support

• Chrome/Chromium 80+
• Firefox 72+
• Safari 13.1+
• Edge 80+

WebAssembly and modern JavaScript features are required.

License

This demo is part of the Hero Framework project. See the main project for licensing information.