Feature: FileBrowser (VFS)

Product Description (Copy/Paste Ready)

Polymech Virtual File System (VFS) Experience native-grade file management directly within your browser. The Polymech VFS FileBrowser is a blazing-fast, dual-pane explorer designed for modern CMS workflows. Drag, drop, and navigate through your assets with intuitive keyboard shortcuts and zero-latency loading. Unlike basic media libraries, it features a built-in rendering engine capable of instantly previewing everything from standard images and PDFs to raw markdown, spreadsheets, and complex engineering 3D models (STL/STEP/OBJ)—all without requiring intermediate downloads.

Comparison vs. Other Web Filebrowsers

Traditional CMS Media Libraries (WordPress, Drupal): Standard platforms heavily favor flat grids or tagged media blobs, restricting hierarchical folder organizations. The Polymech VFS acts like a true operating system file manager, enforcing strict tree hierarchies and directory paths, while still allowing grid-based thumbnail views.
Headless Asset Managers (Sanity, Strapi): Often architected purely as metadata stores linking out to CDN URLs. The Polymech VFS operates on physical nested directories giving developers full UNIX-like path predictability.
Out-of-the-Box Web Explorers (elFinder, FilePond): Most third-party integrations require aging backend dependencies (PHP) or use heavy, unoptimized DOM techniques. The Polymech FileBrowser is built natively in modern React. It utilizes zero-repaint layout effects to lock keyboard focus seamlessly and ensures instant UI reaction speeds.
Specialized Previews (3D & Code): Almost no native web filebrowsers offer immediate in-browser rendering for 3D engineering formats (.stl, .stp, .obj) or syntax-highlighted code files (.tsx, .py, etc.) without downloading them first. The Polymech VFS features a dynamic FileViewerRegistry that handles these specialized mesh and plaintext previews instantly.

The FileBrowser is a fully-featured, dual-pane virtual file system (VFS) client built into the Polymech platform. It provides native-like file exploration capabilities directly in the browser, featuring robust keyboard navigation, drag-and-resize panels, type-safe file discovery, and extensive previewing capabilities for a wide variety of file formats, including 3D models.

Core Architecture

The FileBrowser operates on a Virtual File System structure, connecting to a backend VFS API that mounts specific folders or resources. It extensively leverages standard modern React patterns (Hooks, Contexts, Layout Effects) to build a zero-latency feel for the user.

Main Component

./src/apps/filebrowser/FileBrowserPanel.tsx The entry point component. It orchestrates layout via ResizablePanelGroup and houses the toolbar, dialog popups, and the dual-pane system (the explorer on the left, the preview pane on the right). Core logic is delegated to modular hooks listed below.

State Hooks

The business logic of the browser is split into modular hooks located in ./src/modules/storage/hooks/:

Foundation Hooks (Data & Primitives)

useVfsAdapter.ts Handles data fetching from the backend API. Abstracts away directory fetching, cache management, fallback README indexing, and recursive size queries (includeSize).
useSelection.ts Governs state for selected files, handles batch selection arrays, and calculates item counts.
useKeyboardNavigation.ts Intercepts standard keyboard inputs within the module to provide accessible navigation. Converts array/grid positional awareness to focus updates natively.
useFilePreview.ts Manages states and refs for opening files in overlays/lightboxes.

Orchestration Hooks (Compose the primitives)

useDefaultSelectionHandler.ts Auto-select engine that runs on directory load: selects readme.md when present, restores the parent directory item on "go up" (return-target pattern), and auto-opens initialFile from URL params.
useDefaultKeyboardHandler.ts Global keyboard shortcut listener (Ctrl+F / F3 for search), typeahead search buffer management (with auto-clear on directory change), focus management on view mode switches, and wires the lower-level useKeyboardNavigation.
useDefaultActions.ts Centralizes all action callbacks: download (single/multi/dir-zip), lightbox navigation (prev/next), close-and-restore-focus patterns, double-click handling, and a unified relative link resolver (resolveRelativeVfsLink) that de-duplicates the previously separate readme-pane and file-viewer-pane link handlers.

File Views

The left pane of the file browser provides three rendering modes for the fetched directory contents.

./src/apps/filebrowser/FileTree.tsx The Tree view mode provides an expanding folder hierarchy approach. Note: Recursion and layout-level rendering effects explicitly override grid-snapping hooks to avoid redundant focus issues.
./src/modules/storage/FileListView.tsx A detailed, vertical list rendering standard OS-like columns (Icon, Name, Size, Date).
./src/modules/storage/FileGridView.tsx A resizable thumbnail rendering mode tailored for media directories.
./src/modules/storage/ThumbPreview.tsx Handles rendering fast thumbnail previews inline for media and models, mapping correctly scaled image requests to the backend.

Preview Architecture (FileViewerRegistry)

One of the stand-out features of the FileBrowser is the ability to preview files directly within the UI or via an isolated popup overlay, without downloading them individually. This routing is handled by:

./src/modules/storage/FileViewerRegistry.tsx

Depending on the mime category or file extension, the requested node is dynamically routed to the appropriate specialized viewer component under ./src/modules/storage/views/:

ImageLightbox (./src/components/ImageLightbox.tsx) Native integration for standard images via ResponsiveImage.
PdfLightbox.tsx Built over react-pdf, handles rendering standard .pdf outputs.
SpreadsheetLightbox.tsx Preview tables like .csv and .xlsx.
LightboxIframe.tsx Renders pure .html/.htm safely inside an iframe.
LightboxText.tsx Code and text preview utilizing Prism.js for on-the-fly markdown and syntax highlighting.
ThreeDViewer.tsx A robust 3D model engine implementation previewing .stl, .obj, .step and other engineering-centric mesh types up to specific memory thresholds.

If a folder is selected instead of a file, the right-pane preview defaults to:

A rendered README.md if one sits natively inside the directory.
An internal mounted FileBrowserPanel in thumbnail mode strictly locked as a directory sub-preview (autoFocus=false).

The keyboard and tab-index systems were optimized extensively to act natively:

Pressing Arrow Keys calculates grid-level math to jump up/down/left/right seamlessly.
Pressing Enter commits to entering directories.
Pressing Backspace triggers a "Return-to-Sender" effect (jumping out of folders automatically shifts focus onto the parent directory node precisely).
Ctrl + F / F3 triggers native file search scoped to the currently tracked tree context.
Typeahead search buffer auto-clears on directory navigation preventing stale matches from locking navigation.
Unmounting/mounting directories handles DOM manipulation strictly in useLayoutEffect, enforcing zero-repaint focus locking on tree and list container nodes.

Backend VFS Service

The backend drives the file structure by translating standardized REST commands to the file-system operations safely.

./server/src/products/storage/api/vfs-routes.ts Exposes the OpenAPI specifications and strict route mapping inputs for the File System.
./server/src/products/storage/api/vfs.ts Contains the MountManager, global route validations, rate-limited file-tree recursive walks (Search API), and ACL-governed path sandboxing logic.

Future Improvements (TODOs)

I18n (Internationalization): Abstract hardcoded strings into the globalization architecture via ../src/i18n.tsx to support multilingual FileBrowser deployments.
Keyboard Navigation: Expand keyboard shortcuts for batch selection manipulation and add comprehensive focus trapping within isolated preview lightboxes.
Security (User Content): Implement stricter Content Security Policies (CSP) within LightboxIframe and sanitization checks for user-uploaded HTML/SVG content to prevent stored XSS attacks.
Context API Abstraction: Formalize a generic ViewerControlContext to clean up the prop-drilling required for passing preview state (like LightboxNode) down deeper into specialized viewers.

9.6 KiB Raw Blame History