leaf/examples/widget_example/README.md

# FileBrowser Widget

A WebAssembly-based file browser widget that can be embedded in any web application.

## Features

- File and directory browsing
- File upload with progress tracking (using TUS protocol)
- File download
- Directory creation and deletion
- File editing (markdown with live preview, text files)

## Running the Example

1. **Start a local server** (required for WASM):
   ```bash
   python3 -m http.server 8081
   # or
   npx serve .
   ```

2. **Start the mock backend** (in another terminal):
   ```bash
   cd ../file_browser_demo
   cargo run --bin mock_server
   ```

3. **Open the example**:
   - Navigate to `http://localhost:8081`
   - The widget will load with a configuration panel
   - Try different settings and see them applied in real-time

## Key Features Demonstrated

### Runtime Configuration
The example shows how to configure the widget at runtime without rebuilding:

```javascript
// Create base configuration
const config = create_default_config('http://localhost:3001/files');

// Apply runtime settings using corrected method names
config.setTheme('light');                    // Theme selection
config.setMaxFileSize(100 * 1024 * 1024);   // 100MB limit
config.setShowUpload(true);                  // Enable upload
config.setShowDownload(true);                // Enable download
config.setShowDelete(false);                 // Disable delete
config.setInitialPath('documents/');         // Start in documents folder

// Create widget with configuration
const widget = create_file_browser_widget('container-id', config);
```

### Dynamic Reconfiguration
The widget can be recreated with new settings:

```javascript
function updateWidget() {
    // Destroy existing widget
    if (currentWidget) {
        currentWidget.destroy();
    }
    
    // Create new widget with updated config
    const newConfig = create_default_config(newEndpoint);
    newConfig.setTheme(selectedTheme);
    currentWidget = create_file_browser_widget('container', newConfig);
}
```

### Error Handling
The example includes comprehensive error handling:

- WASM initialization errors
- Browser compatibility checks
- Widget creation failures
- Network connectivity issues

## Widget API Reference

### Core Functions

```javascript
// Initialize WASM module (call once)
await init();

// Create default configuration
const config = create_default_config(baseEndpoint);

// Create widget instance
const widget = create_file_browser_widget(containerId, config);

// Utility functions
const version = get_version();
const isCompatible = check_browser_compatibility();
```

### Configuration Methods

```javascript
config.setTheme(theme);              // 'light' | 'dark'
config.setMaxFileSize(bytes);        // Number in bytes
config.setShowUpload(enabled);       // Boolean
config.setShowDownload(enabled);     // Boolean
config.setShowDelete(enabled);       // Boolean
config.setCssClasses(classes);       // String of CSS classes
config.setInitialPath(path);         // String path
```

### Widget Handle Methods

```javascript
widget.destroy();                    // Clean up widget
// Note: Currently no update method - recreate widget for config changes
```

## Advanced Usage

### Custom Styling
```javascript
config.setCssClasses('my-custom-theme dark-mode');
```

### Multiple Widgets
```javascript
const widget1 = create_file_browser_widget('container1', config1);
const widget2 = create_file_browser_widget('container2', config2);
```

### Integration with Frameworks

**React:**
```jsx
function FileBrowserComponent({ endpoint }) {
    const containerRef = useRef();
    const widgetRef = useRef();
    
    useEffect(() => {
        async function initWidget() {
            await init();
            const config = create_default_config(endpoint);
            widgetRef.current = create_file_browser_widget(
                containerRef.current, 
                config
            );
        }
        initWidget();
        
        return () => widgetRef.current?.destroy();
    }, [endpoint]);
    
    return <div ref={containerRef} />;
}
```

**Vue:**
```vue
<template>
  <div ref="container"></div>
</template>

<script>
export default {
  async mounted() {
    await init();
    const config = create_default_config(this.endpoint);
    this.widget = create_file_browser_widget(this.$refs.container, config);
  },
  beforeUnmount() {
    this.widget?.destroy();
  }
}
</script>
```

## Troubleshooting

### Common Issues

1. **"config.setTheme is not a function"**
   - Ensure you're using the latest widget build
   - Check that WASM module is properly initialized

2. **Widget not appearing**
   - Verify container element exists
   - Check browser console for errors
   - Ensure WASM files are served correctly

3. **Backend connection errors**
   - Verify backend is running on specified endpoint
   - Check CORS configuration
   - Ensure all required API endpoints are implemented

### Debug Mode
```javascript
// Enable debug logging
console.log('Widget version:', get_version());
console.log('Browser compatible:', check_browser_compatibility());
```

## Performance Notes

- **Initial Load**: ~368KB total (WASM + JS)
- **Runtime Memory**: ~2-5MB depending on file list size
- **Startup Time**: ~100-300ms on modern browsers
- **File Operations**: Near-native performance via WASM

The widget is optimized for production use with minimal overhead.