Valstorm VFS (Virtual File System) UI User Guide

Welcome to the Valstorm Desktop VFS Navigation Guide. This document covers all user interactions, multi-selection workflows, drag-and-drop operations, and keyboard navigation available in the modern file tree interface.

1. Visual Overview & Layout

The Valstorm file tree brings a Linear / VS Code / Obsidian-inspired aesthetic designed for high density, visual clarity, and instant feedback.

┌────────────────────────────────────────────────────────────┐
│ 📁 CLOUD VAULTS                [🔍]  [📄+]  [📁+]  [⊟]      │  ← Interactive Header
├────────────────────────────────────────────────────────────┤
│ ▾ 📁 Projects                                              │
│ │   │                                                      │  ← Tree Guide Line
│ │   ├── 📄 roadmap.md                          [📄+] [📁+] │  ← Quick Action Hover
│ │   └── ▾ 📁 src                                           │
│ │       │   ├── 📄 index.ts                                │
│ │       │   └── 📄 App.tsx                                 │  ← Floating Selection Pill
│ ▾ 📁 Notes                                                 │
│     └── 📄 meeting-notes.docx                              │
└────────────────────────────────────────────────────────────┘

Key Visual Features:

• Dynamic SVG Iconography: Extension-specific colored glyphs (.ts, .json, .md, images, spreadsheets) and distinct open/closed folder states (Folder vs FolderOpen) with rotating chevrons.
• Floating Selection Pills: Clean 28px row density with rounded floating selection highlights (rounded-md mx-1.5) that provide clear visual focus without clipping window borders.
• Indentation Guide Lines: 1px vertical nesting lines (border-l) connecting parent folders to children with active-branch hover illumination.
• Quick Action Hover Toolbars: Instant action buttons (+ File, + Folder, Delete) appear seamlessly when hovering over any directory row.

2. Selection & Multi-Selection Workflows

Valstorm VFS supports comprehensive single and multi-item selection techniques:

3. Drag & Drop Interactions

The VFS features precise visual indicators for organizing and reordering items:

3.1. Moving into Folders

• Action: Drag a file, folder, or multi-selection over a folder row.
• Visual Cue: The folder highlights with a glowing blue inner bounding ring (ring-2 ring-blue-500 bg-blue-500/10).
• Result: Releasing the mouse drops the items inside that folder.

3.2. Inserting Between Items

• Action: Drag an item slightly above or below another file/folder row.
• Visual Cue: A sharp 2px horizontal blue insertion line appears with a depth indicator dot showing the exact target position.
• Result: Releasing the mouse reorders the item at that position.

3.3. Multi-Item Dragging

• Action: Multi-select multiple files (via Cmd+Click, Shift+Click, or Marquee Drag), then click and drag any selected item.
• Visual Cue: Custom drag ghost overlay displaying the batch drag operation with subtle tilt and elevation shadow.
• Result: All selected files and folders are moved together to the drop target.

3.4. External File Upload

• Action: Drag files directly from your operating system's desktop/file manager into the tree.
• Visual Cue: Tree container highlights with a dashed upload dropzone.
• Result: Files are automatically uploaded into the targeted vault.

4. Context Menu & Actions

Right-clicking on any file or folder opens a glassmorphism floating context menu (backdrop-blur-xl bg-white/90 dark:bg-zinc-900/90 shadow-2xl rounded-xl):

• New File... — Prompts inline filename creation inside the folder.
• New Folder... — Prompts inline directory creation.
• Rename (F2 / Enter) — Converts the row into an inline input field with the filename pre-selected.
• Copy Path (Cmd + C) — Copies the full VFS / cloud path to your clipboard.
• Delete (Cmd + Backspace / Del) — Prompts confirmation to delete single items or the entire active multi-selection.

5. Search & Filtering

• Instant Search Toggle: Click the Search (🔍) icon in the tree header to transform the header title into a borderless, focused filter input.
• Live Filtering: Type any query to instantly filter the tree view in real-time.
• Clear Filter: Press Escape or click ✕ to restore the full tree hierarchy.

6. Keyboard Shortcuts Cheat Sheet