leaf/widgets/file_browser_widget/examples/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):

   python3 -m http.server 8081
   # or
   npx serve .
   

2. Start the mock backend (in another terminal):

   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:

// 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:

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

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

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

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

Advanced Usage

Custom Styling

config.setCssClasses('my-custom-theme dark-mode');

Multiple Widgets

const widget1 = create_file_browser_widget('container1', config1);
const widget2 = create_file_browser_widget('container2', config2);

Integration with Frameworks

React:

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:

<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

// 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.