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:

```rust
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:**
```bash
# 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:
  ```bash
  cargo install trunk
  ```
- `wasm32-unknown-unknown` target:
  ```bash
  rustup target add wasm32-unknown-unknown
  ```

### Easy Demo Launch

The quickest way to see the file browser in action:

```bash
./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**:
   ```bash
   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

```bash
# 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

```bash
# 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:**
```bash
# From the file_browser_demo directory
trunk serve
```

**Production Mode:**
```bash
# 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:

```rust
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:

```rust
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.