Pika GUI File Explorer 🚀

Добре дошли в официалната, изчерпателна документация на Pika GUI File Explorer. Този документ служи като пълно ръководство, технически наръчник и архитектурна спецификация за проекта. Тук ще намерите всичко необходимо, за да разберете как работи приложението под капака, защо са взети определени архитектурни решения и как да допринесете за неговото развитие.

---

📑 Съдържание

1. Въведение и Визия
2. Архитектурен Обзор
3. Технологичен Стек (Frontend) - Защо и Как?
   • React 19
   • TypeScript
   • Vite
   • Tailwind CSS
   • Zustand
   • React Virtuoso
   • Lucide React
4. Технологичен Стек (Backend) - Защо и Как?
   • Rust
   • Tauri 2.0
   • Ключови Rust Библиотеки (Crates)
5. Пълна Файлова Структура и Организация
6. Основни Функционалности и Имплементация
7. Инструкции за Инсталация и Стартиране
8. Оптимизация на Производителността
9. Сигурност и Права за Достъп
10. Бъдещо Развитие (Roadmap)

---

1. Въведение и Визия

В ерата на уеб технологиите, десктоп приложенията често биват пренебрегвани или изграждани с тежки фреймворци като Electron, които консумират огромно количество системни ресурси (RAM и CPU). Pika GUI File Explorer е създаден с една основна цел: да предложи модерен, красив и светкавично бърз файлов мениджър, който да съчетава най-доброто от двата свята - богатият потребителски интерфейс на уеб технологиите и безкомпромисната производителност на системните езици за програмиране.

Основни цели на проекта:

• Минимален отпечатък върху паметта: Благодарение на Tauri и Rust, приложението използва част от паметта, която би изисквало едно Electron приложение.
• Светкавична скорост: Операциите по файловата система се изпълняват директно на ниво операционна система чрез Rust, без излишно забавяне.
• Интуитивен UI/UX: Дизайнът е вдъхновен от най-добрите практики в съвременните операционни системи (macOS Finder, Windows 11 File Explorer), добавяйки модерни елементи като Command Palette.
• Безопасност: Rust гарантира липсата на проблеми с паметта (memory leaks, data races), което е критично важно при работа с потребителски файлове.

---

2. Архитектурен Обзор

Приложението следва стриктна клиент-сървър архитектура, но изпълнена локално в рамките на един десктоп процес чрез Tauri.

Графично представяне на архитектурата

+---------------------------------------------------------------+
|                      ОПЕРАЦИОННА СИСТЕМА                      |
|  (Windows, macOS, Linux - File System, OS API, System Tray)   |
+---------------------------------------------------------------+
                               ^
                               | (Системни извиквания)
                               v
+---------------------------------------------------------------+
|                     BACKEND (Rust Core)                       |
|                                                               |
|  +----------------+  +-----------------+  +----------------+  |
|  | File Watcher   |  | Command Handler |  | System Info    |  |
|  | (notify crate) |  | (tauri::command)|  | (sysinfo)      |  |
|  +----------------+  +-----------------+  +----------------+  |
|                                                               |
+---------------------------------------------------------------+
                               ^
                               | (Tauri IPC - Inter-Process Communication)
                               | JSON Messages
                               v
+---------------------------------------------------------------+
|                  FRONTEND (Webview / WebView2)                |
|                                                               |
|  +----------------+  +-----------------+  +----------------+  |
|  | React App      |  | Zustand Store   |  | Tailwind CSS   |  |
|  | (UI Components)|  | (State Mgmt)    |  | (Styling)      |  |
|  +----------------+  +-----------------+  +----------------+  |
|                                                               |
+---------------------------------------------------------------+

Как работи комуникацията (IPC)?

Когато потребителят кликне върху папка във frontend-а (React), се случва следното:

1. React компонентът извиква асинхронна функция от Zustand store-а.
2. Zustand store-ът използва @tauri-apps/api/core за да изпрати IPC съобщение (invoke) към Rust.
3. Съобщението съдържа името на командата (напр. read_directory) и аргументи (пътя до папката).
4. Rust backend-ът приема съобщението, изпълнява бързо четене на файловата система чрез стандартната библиотека на Rust (std::fs).
5. Rust сериализира резултата (списък с файлове и техните метаданни) в JSON чрез serde_json и го връща към frontend-а.
6. Zustand обновява състоянието си.
7. React пререндерира интерфейса, показвайки новите файлове чрез React Virtuoso.

Тази изолация гарантира, че frontend-ът никога няма директен достъп до файловата система, освен чрез стриктно дефинираните и защитени Rust команди.

---

3. Технологичен Стек (Frontend) - Защо и Как?

В тази секция ще разгледаме подробно всяка технология, използвана за изграждане на потребителския интерфейс.

React 19

Защо го избрахме? React е индустриален стандарт за изграждане на сложни потребителски интерфейси. Версия 19 въвежда подобрения в производителността, по-добра поддръжка за конкурентно рендериране и оптимизирани хукове (hooks). За файлов мениджър, който трябва да управлява сложни състояния (селекция, навигация, драг енд дроп), компонентният модел на React е незаменим.

Как го прилагаме? Използваме функционални компоненти и модерни хукове. Цялата структура е разделена на малки, преизползваеми части (напр. FileItem, ContextMenu, Breadcrumbs).

Пример за приложение (FileItem компонент):

import React from 'react';
import { useSelectionStore } from '../store/useSelectionStore';
import { FileIcon } from 'lucide-react';

interface FileItemProps {
  file: FileNode;
  onDoubleClick: (file: FileNode) => void;
}

export const FileItem: React.FC<FileItemProps> = React.memo(({ file, onDoubleClick }) => {
  const { selectedIds, toggleSelection } = useSelectionStore();
  const isSelected = selectedIds.includes(file.path);

  return (
    <div 
      className={`flex items-center p-2 cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-800 ${isSelected ? 'bg-blue-100 dark:bg-blue-900' : ''}`}
      onClick={(e) => toggleSelection(file.path, e.ctrlKey || e.metaKey)}
      onDoubleClick={() => onDoubleClick(file)}
    >
      <FileIcon className="w-5 h-5 mr-3 text-gray-500" />
      <span className="truncate">{file.name}</span>
    </div>
  );
});

TypeScript

Защо го избрахме? JavaScript е твърде гъвкав и податлив на грешки за приложение от такъв мащаб. TypeScript добавя строга типизация, която улавя грешките по време на компилация (compile-time), а не по време на изпълнение (runtime). Това е критично при комуникацията с Rust, където очакваме точно определени структури от данни (JSON).

Как го прилагаме? Имаме специална директория src/types, където са дефинирани всички интерфейси. Когато Rust върне данни за файл, ние сме сигурни, че те отговарят на нашия TypeScript интерфейс.

Пример за дефиниция (types/filesystem.ts):

export interface FileNode {
  name: string;
  path: string;
  isDir: boolean;
  size: number;
  lastModified: string;
  extension?: string;
  isHidden: boolean;
}

export interface SystemInfo {
  totalMemory: number;
  freeMemory: number;
  osName: string;
  osVersion: string;
  cpuModel: string;
}

Vite

Защо го избрахме? Vite (произнася се "виит") е модерен build tool, който замени Webpack в екосистемата на React. Избрахме го заради невероятната му скорост. Vite използва нативни ES модули в браузъра по време на разработка, което прави Hot Module Replacement (HMR) почти мигновен, независимо колко голям става проектът.

Как го прилагаме? Vite е конфигуриран чрез vite.config.ts. Той обработва нашия TypeScript и Tailwind CSS код и го пакетира ефективно за продукционна среда, интегрирайки се безпроблемно с Tauri CLI.

Tailwind CSS

Защо го избрахме? Традиционният CSS или дори препроцесори като SASS често водят до огромни, трудни за поддръжка стилови файлове (CSS bloat). Tailwind CSS е "utility-first" фреймворк. Вместо да пишем класове като .file-card, ние използваме класове като flex items-center p-4 bg-white rounded-lg shadow. Това ускорява разработката десетократно и гарантира, че нямаме неизползван CSS в крайната компилация.

Как го прилагаме? Цялото стилизиране на приложението е направено с Tailwind. Използваме го и за лесна поддръжка на Тъмна тема (Dark Mode).

Пример за приложение (Тъмна тема и hover ефекти):

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 transition-colors duration-200">
  <button className="px-4 py-2 bg-blue-500 hover:bg-blue-600 dark:bg-blue-600 dark:hover:bg-blue-700 rounded-md text-white">
    Действие
  </button>
</div>

Zustand

Защо го избрахме? Redux е твърде тежък и изисква много "boilerplate" код. Context API-то на React може да доведе до излишни пререндерирания (re-renders), ако не се използва внимателно. Zustand е изключително лек, бърз и гъвкав state manager. Той работи отлично с TypeScript и ни позволява да отделим логиката от компонентите.

Как го прилагаме? Имаме няколко отделни "магазина" (stores). Например useFileSystemStore управлява текущата директория и списъка с файлове, докато useSelectionStore управлява кои файлове са маркирани от потребителя.

Пример за приложение (src/store/useSelectionStore.ts):

import { create } from 'zustand';

interface SelectionState {
  selectedPaths: Set<string>;
  toggleSelection: (path: string, multi: boolean) => void;
  clearSelection: () => void;
  selectAll: (paths: string[]) => void;
}

export const useSelectionStore = create<SelectionState>((set) => ({
  selectedPaths: new Set(),
  toggleSelection: (path, multi) => set((state) => {
    const newSelection = multi ? new Set(state.selectedPaths) : new Set<string>();
    if (newSelection.has(path)) {
      newSelection.delete(path);
    } else {
      newSelection.add(path);
    }
    return { selectedPaths: newSelection };
  }),
  clearSelection: () => set({ selectedPaths: new Set() }),
  selectAll: (paths) => set({ selectedPaths: new Set(paths) })
}));

React Virtuoso

Защо го избрахме? Един от най-големите проблеми на уеб-базираните файлови мениджъри е производителността при отваряне на папки с хиляди файлове (напр. node_modules или System32). Рендерирането на 10,000 DOM елемента едновременно ще блокира браузъра. React Virtuoso е библиотека за виртуализация на списъци. Тя рендерира само тези елементи, които са видими на екрана (плюс малък буфер), поддържайки DOM дървото малко и производителността висока при 60 FPS.

Как го прилагаме? Използваме го в компонента FileList. Независимо дали в папката има 10 или 100,000 файла, приложението консумира едно и също количество памет за интерфейса.

Lucide React

Защо го избрахме? Изключително красива, модерна и лека библиотека за икони (fork на Feather Icons). Тя предлага консистентен дизайн и SVG иконите могат да бъдат стилизирани директно чрез Tailwind CSS класове.

Как го прилагаме? Всяка икона е React компонент. Имаме помощна функция iconHelper.ts, която връща правилната Lucide икона въз основа на файловото разширение (напр. икона за код за .js, икона за изображение за .png).

---

4. Технологичен Стек (Backend) - Защо и Как?

Backend-ът на нашето приложение е това, което го прави истински десктоп софтуер, а не просто уебсайт в прозорец.

Rust

Защо го избрахме? Rust е системен език за програмиране, който предлага производителността на C/C++, но с вградени гаранции за безопасност на паметта (memory safety) чрез своята система за собственост (ownership). При работа с файлови операции, нишката за сигурност е критична. Rust ни предпазва от често срещани грешки като null pointer dereferencing и buffer overflows. Освен това, Rust е изключително бърз и компилира до компактен машинен код.

Как го прилагаме? Цялата бизнес логика, свързана със системни операции, е написана на Rust в директорията src-tauri. От четене на директории до преместване на файлове в кошчето.

Tauri 2.0

Защо го избрахме? Алтернативата на Tauri е Electron. Electron пакетира цял Chromium браузър и Node.js среда във всяко приложение. Това води до инсталационни файлове над 100MB и консумация на RAM памет от стотици мегабайти дори при празно приложение. Tauri работи различно: той използва вече наличния уеб енджин в операционната система (WebView2 на Windows, WebKit на macOS, WebKitGTK на Linux). Резултатът? Инсталационният файл е под 10MB, а консумацията на RAM е драстично по-малка.

Как го прилагаме? Tauri служи като мост. Той създава прозореца на приложението, зарежда нашия React код в него и осигурява сигурен комуникационен канал (IPC) между React и Rust.

Ключови Rust Библиотеки (Crates)

За да не откриваме топлата вода, използваме утвърдени Rust библиотеки за специфични задачи:

1. trash (v5.1)

   • Защо: Когато потребителят изтрие файл, не искаме да го унищожим перманентно веднага. Искаме да отиде в системното кошче (Recycle Bin/Trash).
   • Как: Използваме trash::delete(path), което крос-платформено (работи и на Windows, и на Mac) премества файла в кошчето на операционната система.

2. sysinfo (v0.30)

   • Защо: Искаме да показваме полезна информация на потребителя в StatusBar-а, като например колко свободно място има на текущия диск.
   • Как: Чрез този crate извличаме данни за хардуера и дисковете директно от ядрото на ОС.

3. notify (v6.1.1)

   • Защо: Ако потребителят създаде нов файл през Terminal или през стандартния файлов мениджър, нашият Explorer трябва веднага да се актуализира, без потребителят да натиска "Refresh".
   • Как: Този crate слуша за събития (създаване, изтриване, промяна) на ниво операционна система за текущата директория и изпраща сигнал към нашия frontend чрез Tauri емитери.

4. walkdir (v2.4)

   • Защо: При търсене на файлове или изчисляване на размера на голяма папка, ни трябва рекурсивно обхождане на дървото от директории.
   • Как: walkdir предоставя бърз и ефикасен итератор за обхождане, който се справя отлично със символни връзки и скрити файлове.

5. zip (v4.2.0)

   • Защо: Архивирането и разархивирането са базови нужди за всеки файлов мениджър.
   • Как: Позволява ни да пакетираме избрани файлове в .zip архив директно чрез контекстното меню.

6. tokio (v1.49)

   • Защо: Много файлови операции са бавни (напр. копиране на 10GB файл). Не искаме те да блокират главната нишка на Rust (която управлява комуникацията с UI-я).
   • Как: Tokio е асинхронен runtime за Rust. Той ни позволява да изпълняваме тежки I/O операции във фонов режим (background threads) ефективно.

---

5. Пълна Файлова Структура и Организация

Организацията на кода е от критично значение за поддръжката на проекта. Ето подробна разбивка на всяка папка и важен файл:

C:\Users\sneic\Documents\Github\GUI-File-Explorer\
│
├── .github/workflows/              # Конфигурации за GitHub Actions (CI/CD)
│   └── build.yml                   # Автоматизирано тестване и компилиране при пушване
│
├── dist/                           # Генерирани файлове след билдване на React частта (Vite Output)
├── node_modules/                   # Инсталирани JavaScript/TypeScript пакети (NPM)
│
├── public/                         # Статични ресурси, които се сервират директно
│   ├── pika.svg                    # Основно лого на приложението
│   └── vite.svg                    # Лого на Vite
│
├── releases/                       # Директория, съдържаща готови инсталационни пакети
│   └── pika-explorer-v0.1.0.deb    # Пример: инсталатор за Debian/Ubuntu базирани системи
│
├── src/                            # FRONTEND: Главна директория за React кода
│   │
│   ├── assets/                     # Асети, които минават през Webpack/Vite (картинки, шрифтове)
│   │   └── react.svg               
│   │
│   ├── components/                 # Всички React компоненти, разделени логически
│   │   │
│   │   ├── features/               # Компоненти, които изпълняват специфична бизнес логика
│   │   │   ├── Breadcrumbs.tsx     # Навигационна лента (напр. C: > Users > Name > Docs)
│   │   │   ├── CommandPalette.tsx  # Търсачка/Команден панел (активира се с Ctrl+K)
│   │   │   ├── ConflictModal.tsx   # Модален прозорец при конфликт на имена (Смяна/Заместване)
│   │   │   ├── ContextMenu.tsx     # Custom меню при десен клик върху файл
│   │   │   ├── FileGrid.tsx        # Компонент за показване на файлове под формата на икони
│   │   │   ├── FileItem.tsx        # Индивидуален компонент за един файл/папка
│   │   │   ├── FileList.tsx        # Компонент за показване на файлове под формата на таблица/списък (ползва Virtuoso)
│   │   │   ├── FileView.tsx        # Контейнер, който превключва между Grid и List
│   │   │   ├── HomePage.tsx        # Начален екран (Бърз достъп, Последни файлове)
│   │   │   ├── InfoPanel.tsx       # Страничен панел с детайли за избрания файл (размер, дата, права)
│   │   │   ├── Modal.tsx           # Универсален компонент за изскачащи прозорци
│   │   │   ├── Notification.tsx    # Тоустове (Toast notifications) за успех/грешка
│   │   │   ├── QuickLook.tsx       # Бърз преглед на файл (активира се с Spacebar)
│   │   │   └── StatusBar.tsx       # Лента най-долу (брой файлове, селекция, размер)
│   │   │
│   │   └── layout/                 # Структурни компоненти на скелета на приложението
│   │       ├── MainLayout.tsx      # Главна обвивка (wrapper) за страниците
│   │       ├── MenuBar.tsx         # Класическо меню (File, Edit, View, Help)
│   │       ├── Sidebar.tsx         # Лява навигационна лента (Дискове, Любими папки)
│   │       ├── TitleBar.tsx        # Custom заглавна лента (заменя системната на ОС)
│   │       └── TopBar.tsx          # Горна лента с бутони Назад/Напред, Търсачка и Breadcrumbs
│   │
│   ├── hooks/                      # Custom React Hooks за преизползване на логика
│   │   └── useKeyboardNavigation.ts# Логика за навигация със стрелките, Enter, Backspace, Ctrl+A
│   │
│   ├── store/                      # Zustand конфигурации за глобалния стейт
│   │   ├── useFileSystemStore.ts   # Пази текущия път, списъка с файлове, история на навигацията
│   │   └── useSelectionStore.ts    # Пази кои файлове са маркирани в момента
│   │
│   ├── types/                      # TypeScript интерфейси и типове
│   │   └── filesystem.ts           # Дефиниции за FileNode, SystemInfo и др.
│   │
│   ├── utils/                      # Помощни функции, които не са React компоненти
│   │   ├── iconHelper.ts           # Логика за връщане на правилна икона според разширението
│   │   └── mockFileSystem.ts       # Данни за тестване (когато Rust backend-ът не е пуснат)
│   │
│   ├── App.css                     # Глобални стилове (предимно Tailwind директиви)
│   ├── App.tsx                     # Главен компонент, който сглобява Layout-а и Store-овете
│   ├── index.css                   # Входна точка за стиловете
│   └── main.tsx                    # Входна точка на React. Закача App към DOM-а (root div)
│
├── src-tauri/                      # BACKEND: Главна директория за Rust/Tauri кода
│   │
│   ├── capabilities/               # Настройки за права на достъп (Security)
│   │   └── default.json            # Дефинира кои Tauri API-та са разрешени (напр. fs:read)
│   │
│   ├── icons/                      # Икони за инсталатора и изпълнимия файл за различни ОС
│   │   ├── 32x32.png, icon.icns, icon.ico ...
│   │   ├── android/                # Икони за Android порт (в бъдеще)
│   │   └── ios/                    # Икони за iOS порт (в бъдеще)
│   │
│   ├── src/                        # Изходен код на Rust
│   │   ├── commands.rs             # Тук се намират функциите, които се викат от React (напр. fn read_dir())
│   │   ├── lib.rs                  # Библиотечен файл, експортира модулите
│   │   ├── main.rs                 # Входна точка на Rust приложението. Стартира Tauri Builder-а.
│   │   ├── models.rs               # Rust Structs (еквивалент на TS интерфейсите), които се сериализират до JSON
│   │   └── tests.rs                # Unit тестове за Rust логиката
│   │
│   ├── build.rs                    # Скрипт, който се изпълнява преди компилацията на Rust кода
│   ├── Cargo.lock                  # Точни версии на Rust зависимостите (еквивалент на package-lock.json)
│   ├── Cargo.toml                  # Дефиниция на Rust зависимостите (crates) и метаданни
│   ├── tauri.conf.json             # Главна конфигурация на Tauri (име, версия, прозорец, билд скриптове)
│   └── .gitignore                  # Игнорира /target/ директорията на Rust
│
├── zadanie i titulna stranica/     # Проектна документация и академични материали
│   ├── Логическа архитектура...docx# Описание на архитектурата
│   ├── Описание на UML...docx      # Документация към диаграмите
│   ├── Технологичен стек...docx    # Анализ на използваните технологии
│   ├── ТИТУЛНА 12б.docx            # Титулна страница за проект/курсова работа
│   ├── IMG_2026...jpg              # Снимки/Скечове на дизайна
│   └── Диаграми/                   # UML Диаграми (PNG формати)
│       ├── File Explorer CRUD Class Diagram.png
│       ├── File Explorer CRUD Sequence Diagram.png
│       └── File Explorer CRUD Use Case Diagram.png
│
├── .gitignore                      # Глобален gitignore за Node.js
├── eslint.config.js                # Конфигурация за ESLint (правила за писане на чист код)
├── index.html                      # Единственият HTML файл (Single Page Application основа)
├── package-lock.json               # Точни версии на NPM пакетите
├── package.json                    # NPM зависимости и скриптове (npm run dev, npm run build)
├── postcss.config.js               # Конфигурация за PostCSS (нужна на Tailwind)
├── README.md                       # ТОЗИ ДОКУМЕНТ
├── tsconfig.app.json               # TS конфигурация специфична за React кода
├── tsconfig.json                   # Главна TS конфигурация
├── tsconfig.node.json              # TS конфигурация специфична за Vite/Node скриптовете
└── vite.config.ts                  # Конфигурация на Vite (плъгини, портове, интеграция с Tauri)

---

6. Основни Функционалности и Имплементация

В тази секция ще разгледаме в детайли какво прави приложението и как сме реализирали ключовите функции.

6.1. Гъвкав Изглед (Grid & List) с Виртуализация

Една от най-сложните задачи пред файлов мениджър е изобразяването на огромни директории без забиване на потребителския интерфейс.

Как е реализирано:

• Потребителят може да превключва между Grid (големи икони) и List (детайлен списък).
• Когато е в режим List, използваме React Virtuoso. Компонентът FileList.tsx не създава HTML елементи за всички 10,000 файла. Той създава HTML само за около 20 файла, които се виждат на екрана. Докато потребителят скролира, Virtuoso преизползва тези DOM елементи, подменяйки само данните (име, размер, икона) в тях. Това гарантира константна консумация на памет и 60 кадъра в секунда (FPS).

6.2. Комуникация с Файловата Система (Rust Commands)

Всички реални операции се случват в Rust.

Как е реализирано: В src-tauri/src/commands.rs имаме функции, маркирани с макроса #[tauri::command]. Пример:

#[tauri::command]
pub async fn get_files(path: String) -> Result<Vec<FileNode>, String> {
    let mut files = Vec::new();
    let entries = std::fs::read_dir(&path).map_err(|e| e.to_string())?;

    for entry in entries {
        if let Ok(entry) = entry {
            let metadata = entry.metadata().map_err(|e| e.to_string())?;
            // Извличане на име, размер, дата на промяна...
            // Създаване на FileNode структура и добавяне в масива
        }
    }
    Ok(files) // Tauri автоматично го конвертира в JSON и го праща на React
}

А в React (useFileSystemStore.ts):

import { invoke } from '@tauri-apps/api/core';

// Вътре в Zustand действието:
const files: FileNode[] = await invoke('get_files', { path: currentPath });
set({ files, currentPath });

6.3. Интелигентна Клавиатурна Навигация

Професионалните потребители (Power users) използват клавиатурата повече от мишката. Нашата цел е приложението да може да се управлява изцяло без мишка.

Как е реализирано: Създадохме custom hook useKeyboardNavigation.ts. Той слуша за събития (keydown) глобално или върху специфичен контейнер.

• Стрелки (Up/Down/Left/Right): Преместват фокуса/селекцията към съответния файл.
• Enter: Отваря избраната папка или изпълнява файла чрез системната програма по подразбиране (чрез Tauri open API).
• Backspace: Връща една директория нагоре (еквивалент на бутона "Назад").
• Ctrl+A / Cmd+A: Селектира всички файлове в текущия изглед.
• Spacebar: Отваря Quick Look (Бърз преглед).

6.4. Command Palette (Командна Палитра)

Вдъхновено от инструменти като VS Code и Spotlight (macOS). Натискането на Ctrl+K (или Cmd+K) отваря изскачащ прозорец.

Как е реализирано: CommandPalette.tsx е компонент, който стои скрит в Layout-а. При активиране той фокусира текстово поле. Потребителят може да търси сред предефинирани команди ("Create New Folder", "Open Terminal Here", "Settings") или да търси файлове. Търсенето е оптимизирано и филтрира резултатите в реално време, докато потребителят пише.

6.5. Real-time File System Watcher

Ако промените файл извън Pika Explorer, той трябва да се актуализира автоматично.

Как е реализирано: Използваме Rust crate-а notify. В Rust създаваме фонова нишка (background thread), която слуша за събития в текущо отворената директория. Когато засече промяна (напр. създаден е нов файл), Rust изпраща събитие към frontend-а:

app.emit_all("fs-change", payload).unwrap();

В React (useFileSystemStore.ts) слушаме за това събитие чрез @tauri-apps/api/event и автоматично презареждаме списъка с файлове, извиквайки отново get_files.

6.6. Quick Look (Бърз Преглед)

Позволява бърз преглед на съдържанието на файл, без да се отваря външна програма (напр. преглед на снимка или прочитане на текстов файл).

Как е реализирано: При натискане на Spacebar върху маркиран файл, QuickLook.tsx компонентът се рендерира като модален прозорец (overlay).

• За снимки (png, jpg, webp), използваме Tauri протокола за зареждане на локални асети (asset://), заобикаляйки ограниченията на браузъра за достъп до локалната файлова система.
• За текстови файлове (txt, md, json, ts), изпращаме команда към Rust да прочете първите 50-100KB от файла и ги визуализираме в компонент с оцветена синтактична логика.

6.7. Контекстно Меню (Context Menu)

Собствено контекстно меню, което заменя стандартното на браузъра.

Как е реализирано: В FileGrid.tsx и FileList.tsx прихващаме събитието onContextMenu (десен клик).

1. Извикваме e.preventDefault(), за да спрем появата на менюто на браузъра.
2. Вземаме координатите на мишката (e.clientX, e.clientY).
3. Подаваме ги на компонента ContextMenu.tsx, който се рендерира на точната позиция чрез CSS position: fixed; left: Xpx; top: Ypx;.
4. Менюто съдържа опции като Copy, Cut, Paste, Rename, Delete, Properties, които комуникират съответно с Rust командите.

---

7. Инструкции за Инсталация и Стартиране

Тази секция е предназначена за разработчици, които искат да компилират, тестват или допринасят за проекта.

7.1. Предварителни изисквания (Prerequisites)

За да работите по проекта, компютърът ви трябва да бъде конфигуриран с необходимите инструменти за уеб и системно програмиране.

1. Node.js и NPM (или pnpm/yarn)

   • Инсталирайте последната LTS (Long Term Support) версия от nodejs.org.
   • Проверете инсталацията: node -v и npm -v.

2. Rust Environment

   • Инсталирайте Rust чрез rustup. Това е официалният мениджър за версиите на Rust.
   • За Linux/macOS изпълнете в терминала: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   • За Windows изтеглете и стартирайте rustup-init.exe.
   • Проверете инсталацията: rustc -V и cargo -V.

3. Системни зависимости според операционната система:

   • Windows:
     • Инсталирайте C++ Build Tools. Най-лесно става чрез сваляне на Visual Studio Build Tools и избиране на пакета "Desktop development with C++".
     • Инсталирайте WebView2 Runtime (на Windows 11 обикновено е инсталиран по подразбиране).
   • macOS:
     • Инсталирайте Xcode Command Line Tools, като изпълните в терминала: xcode-select --install.
   • Linux (Ubuntu/Debian):
     • Ще ви трябват системни библиотеки за създаване на графични интерфейси. Изпълнете:

       sudo apt update
       sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
       

7.2. Стъпки за първоначално стартиране (Development Mode)

След като сте подготвили средата си, следвайте тези стъпки:

1. Клонирайте хранилището локално: Отворете терминал и изпълнете:

   git clone https://github.com/vashiyat-potrebitel/GUI-File-Explorer.git
   cd GUI-File-Explorer
   

2. Инсталирайте JavaScript зависимостите: Това ще изтегли React, Vite, Tailwind, Zustand и всички други пакети, дефинирани в package.json.

   npm install
   

3. Стартирайте приложението в режим на разработка: Тази команда прави две неща: стартира Vite dev сървър за frontend-а (с Hot Module Replacement) и компилира Rust кода (което първия път отнема малко време, тъй като тегли и компилира всички Rust crates).

   npm run tauri dev
   

   Забележка: При първо стартиране компилацията на Rust може да отнеме от 2 до 10 минути в зависимост от мощността на компютъра ви. Следващите стартирания ще бъдат много по-бързи, благодарение на кеширането на Cargo.

7.3. Процес на Разработка (Workflow)

• Когато променяте файл в src/ (React/TS/CSS), Vite автоматично и мигновено ще актуализира интерфейса в отворения Tauri прозорец.
• Когато променяте файл в src-tauri/src/ (Rust), Tauri автоматично ще рекомпилира променения Rust код и ще рестартира приложението.

7.4. Компилиране за Продукция (Building for Production)

Когато сте готови да споделите приложението с крайни потребители, трябва да генерирате оптимизиран инсталатор.

1. Уверете се, че в src-tauri/tauri.conf.json сте задали правилен identifier (напр. com.pika.explorer) и сте актуализирали версията.
2. Изпълнете командата за билд:

   npm run tauri build
   

3. Този процес ще отнеме известно време, тъй като Rust ще компилира кода с максимални оптимизации (Release profile).
4. Резултатът:
   • На Windows ще намерите .msi и .exe инсталатори в src-tauri/target/release/bundle/msi/.
   • На macOS ще намерите .dmg и .app файлове в src-tauri/target/release/bundle/dmg/.
   • На Linux ще намерите .deb или .AppImage файлове.

Можете да копирате тези файлове в директорията releases/ (както е показано в дървото на проекта) за по-лесно разпространение.

---

8. Оптимизация на Производителността

Тъй като целта на Pika GUI File Explorer е да бъде по-бърз от традиционните файлов мениджъри, ние сме приложили множество техники за оптимизация на различни нива.

8.1. Оптимизации в Rust (Backend)

• Zero-cost abstractions: Използваме итератори и функционален стил в Rust, които се компилират до максимално ефективен машинен код.
• Мултитрединг с Tokio: Когато потребителят стартира тежка операция (напр. търсене на файл в целия диск C:\), ние не блокираме основната нишка. Търсенето се изпълнява в отделен thread (worker thread), а резултатите се изпращат асинхронно (streaming) към frontend-а на порции. Така интерфейсът остава отзивчив по всяко време.
• Минимизиране на сериализацията: Изпращането на огромни JSON обекти през IPC моста е бавно. Затова, когато четем директория с 50,000 файла, ние изпращаме само основните метаданни, нужни за списъка (име, размер, тип), а допълнителната информация (точни права, собственик, подробни дати) се зарежда on-demand само когато потребителят отвори InfoPanel за конкретния файл.

8.2. Оптимизации в React (Frontend)

• Избягване на Re-renders (Пререндерирания):
  • Използваме React.memo за компоненти като FileItem. Те се пререндерират САМО ако техните свойства (props) се променят (напр. файлът бъде избран или преименуван).
  • Състоянието е разделено в различни Zustand stores. Ако се промени селекцията (в useSelectionStore), това няма да предизвика пререндериране на Breadcrumbs, който слуша само useFileSystemStore.
• Виртуализация с React Virtuoso: Както беше споменато, това е ключът към справянето с огромни папки. Независимо колко елемента има в масива files, в DOM дървото съществуват максимум 30-40 div елемента.
• Мързеливо зареждане (Lazy Loading): Иконите за специфични типове файлове, както и модулите за QuickLook (напр. синтактичният хайлайтър за код), се зареждат само когато са реално необходими (чрез React.lazy и динамични импорти във Vite).

8.3. Оптимизация на Стилизирането (Tailwind)

Tailwind CSS премахва целия неизползван CSS по време на продукционния билд (чрез PurgeCSS логика вградена в него). Крайният CSS файл за цялото приложение често е под 15KB компресиран. Това гарантира мигновено зареждане на стиловете и нулево забавяне при рисуване на екрана (First Contentful Paint).

---

9. Сигурност и Права за Достъп

Файловият мениджър по дефиниция има достъп до най-чувствителните данни на компютъра на потребителя. Сигурността не е функция, тя е фундамент на този проект.

9.1. Сигурностният Модел на Tauri

Tauri е проектиран с мисъл за сигурност. За разлика от Node.js интеграцията в Electron (която дава пълен достъп до системата директно от JavaScript), Tauri изолира уеб изгледа.

• Frontend-ът (React) няма достъп до Node.js API-та (fs, child_process, os).
• Frontend-ът не може да чете или пише файлове директно.
• Всяко действие извън браузърната среда трябва да премине през стриктно дефиниран IPC канал към Rust.

9.2. Capabilities (Възможности)

Във файла src-tauri/capabilities/default.json ние изрично дефинираме (whitelist) кои модули от Tauri API са разрешени. Ако хакер успее да инжектира злонамерен JavaScript код (XSS атака) в приложението (което само по себе си е изключително трудно поради липсата на външни входове), този код няма да може да форматира диска, защото ние не сме разрешили изпълнението на произволни shell команди. Разрешени са само нашите custom Rust команди (напр. read_dir, delete_file_to_trash).

9.3. Безопасност на Паметта с Rust

Повечето уязвимости в системен софтуер (като класическия Windows Explorer) идват от проблеми с паметта (Buffer Overflow, Use-After-Free), написани на C/C++. Компилаторът на Rust гарантира на 100%, че такива грешки са невъзможни в нашия backend код (докато не използваме блокове маркирани като unsafe, каквито ние избягваме).

---

10. Бъдещо Развитие (Roadmap)

Това е само началото за Pika GUI File Explorer. Плановете ни за бъдещи версии включват:

• Версия 0.2.0 (Интеграции):
  • Интеграция с облачни услуги (Google Drive, Dropbox, OneDrive) директно в Sidebar-а.
  • Поддръжка на FTP / SFTP връзки за управление на отдалечени сървъри.
• Версия 0.3.0 (Продуктивност):
  • Разделяне на екрана на две (Dual Pane View) стил Total Commander.
  • Интегриран терминал в долната част на прозореца.
  • Разширен търсач (Search) с поддръжка на регулярни изрази (Regex) и търсене вътре в съдържанието на текстови файлове (чрез ripgrep логика).
• Версия 0.4.0 (Къстомизация):
  • Пълна поддръжка на теми (Themes) – потребителите да могат да създават свои собствени цветови палитри и да променят пакетите с икони.
  • Система за плъгини (Plugin System), позволяваща на общността да пише разширения за файла мениджъра (напр. плъгин за визуализация на 3D модели директно в Quick Look).
• Версия 1.0.0:
  • Напълно стабилен релиз.
  • Автоматични ъпдейти (Over-The-Air updates) интегрирани чрез вградения Tauri Updater.

---

Документацията е съставена с грижа за детайлите и страст към качествения софтуер. Благодарим ви, че избрахте и подкрепяте Pika GUI File Explorer!