# 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)
```bash
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:
```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:
```html
<div id="file-browser-container"></div>
```

### 4. Initialize Widget

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

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

```javascript
await init();
```

#### `create_default_config(base_endpoint)`
Create a default configuration object.

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

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

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

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

#### `get_version()`
Get the widget version.

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

### Widget Handle

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

```javascript
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:
```json
[
  {
    "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:

```css
.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:

```javascript
// 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

```javascript
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:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack
```

2. Build the widget:
```bash
./build.sh
```

3. Test locally:
```bash
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](https://github.com/herocode/framework)
- 🐛 [Issue Tracker](https://github.com/herocode/framework/issues)
- 💬 [Discussions](https://github.com/herocode/framework/discussions)