121 lines
9.6 KiB
Markdown
121 lines
9.6 KiB
Markdown
# 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`](../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`](../src/modules/storage/hooks/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`](../src/modules/storage/hooks/useSelection.ts)**
|
|
Governs state for selected files, handles batch selection arrays, and calculates item counts.
|
|
- **[`useKeyboardNavigation.ts`](../src/modules/storage/hooks/useKeyboardNavigation.ts)**
|
|
Intercepts standard keyboard inputs within the module to provide accessible navigation. Converts array/grid positional awareness to focus updates natively.
|
|
- **[`useFilePreview.ts`](../src/modules/storage/hooks/useFilePreview.ts)**
|
|
Manages states and refs for opening files in overlays/lightboxes.
|
|
|
|
#### Orchestration Hooks (Compose the primitives)
|
|
- **[`useDefaultSelectionHandler.ts`](../src/modules/storage/hooks/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`](../src/modules/storage/hooks/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`](../src/modules/storage/hooks/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`](../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`](../src/modules/storage/FileListView.tsx)**
|
|
A detailed, vertical list rendering standard OS-like columns (Icon, Name, Size, Date).
|
|
- **[`./src/modules/storage/FileGridView.tsx`](../src/modules/storage/FileGridView.tsx)**
|
|
A resizable thumbnail rendering mode tailored for media directories.
|
|
- **[`./src/modules/storage/ThumbPreview.tsx`](../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`](../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/`:
|
|
|
|
1. **`ImageLightbox`** ([`./src/components/ImageLightbox.tsx`](../src/components/ImageLightbox.tsx))
|
|
Native integration for standard images via `ResponsiveImage`.
|
|
2. **`PdfLightbox.tsx`**
|
|
Built over `react-pdf`, handles rendering standard `.pdf` outputs.
|
|
3. **`SpreadsheetLightbox.tsx`**
|
|
Preview tables like `.csv` and `.xlsx`.
|
|
4. **`LightboxIframe.tsx`**
|
|
Renders pure `.html`/`.htm` safely inside an iframe.
|
|
5. **`LightboxText.tsx`**
|
|
Code and text preview utilizing `Prism.js` for on-the-fly markdown and syntax highlighting.
|
|
6. **`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`).
|
|
|
|
---
|
|
|
|
## Keyboard Navigation & Focus Flow
|
|
|
|
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`](../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`](../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`](../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.
|
|
|