@fde-desktop/fde-core 0.3.8 → 0.4.2

package/README.md

@@ -1,15 +1,23 @@
-# @frannunpal/fde-core
+# @fde-desktop/fde-core
 
-Core library for building FDE Desktop environments. This package provides the essential components, hooks, stores, types, and utilities to create desktop-like applications in React.
+Core library for building FDE Desktop environments. This package provides everything needed to create desktop-like applications in React:
+
+- **UI Components**: Desktop, Window, Taskbar, Launcher, ContextMenu, etc.
+- **Core Apps**: Files, Settings, Notepad, Image Viewer, PDF Viewer, etc.
+- **Stores**: Zustand stores for desktop, settings, custom apps
+- **Hooks**: 30+ hooks for app management, notifications, icons, file system, etc.
+- **Domain Entities**: createWindow, createDesktopIcon, createLauncherFolder
+- **Infrastructure**: IndexedDBFileSystem, DockerFileSystemAdapter, FdeApiAdapter
+- **Types & Utilities**: Full TypeScript types and helper functions
 
 ## Installation
 
 ```bash
-npm install @frannunpal/fde-core react react-dom
+npm install @fde-desktop/fde-core
 # or
-yarn add @frannunpal/fde-core react react-dom
+yarn add @fde-desktop/fde-core
 # or
-bun add @frannunpal/fde-core react react-dom
+bun add @fde-desktop/fde-core
 ```
 
 ## Peer Dependencies
@@ -17,89 +25,448 @@ bun add @frannunpal/fde-core react react-dom
 - `react` ^19.0.0
 - `react-dom` ^19.0.0
 
+## Quick Start
+
+The simplest way is to use the `FdeDesktop` component:
+
+```tsx
+import { FdeDesktop, type AppRegistryEntry } from '@fde-desktop/fde-core';
+
+// Define your custom apps (optional)
+const myApps: Record<string, AppRegistryEntry> = {
+  'my-app': {
+    loader: () => import('./MyApp'),
+    appName: 'My App',
+  },
+};
+
+function App() {
+  return <FdeDesktop customApps={myApps}>{/* Optional: custom desktop content */}</FdeDesktop>;
+}
+```
+
+Core apps (Files, Settings, Notepad, etc.) are loaded automatically. Your custom apps are merged with the core registry.
+
 ## Exports
 
+### UI Components
+
+```tsx
+import {
+  // Main wrapper
+  FdeDesktop,
+
+  // Desktop components
+  Desktop,
+  DesktopIcon,
+  Window,
+  AppMenuBar,
+  DynamicMenuBarRenderer,
+
+  // System UI
+  Taskbar,
+  Launcher,
+  TaskbarContextMenu,
+  LanguageSelector,
+
+  // Menus
+  ContextMenu,
+  CreateItemContextMenu,
+
+  // Theme
+  ThemeProvider,
+  useTheme,
+  DEFAULT_FDE_THEME,
+
+  // Context
+  FdeProvider,
+  useFdeContext,
+  AppReadyProvider,
+  useAppReady,
+
+  // Registry helpers
+  initRegistry,
+  getAppComponent,
+  getMenuBarComponent,
+  getMenuBarBuilder,
+  isLazyApp,
+  getAppName,
+  registerComponents,
+} from '@fde-desktop/fde-core';
+```
+
 ### Apps (Core Apps)
 
-```typescript
+```tsx
 import {
   FilesApp,
   SettingsApp,
-  NotepadApp,
+  NotesApp,
   ImageViewerApp,
   PdfApp,
   UploaderApp,
   MenuEditApp,
   DeviceInfoApp,
   CalendarApp,
+  TerminalApp,
+  CodeServerApp,
   CORE_APPS,
   CORE_APP_IDS,
-} from '@frannunpal/fde-core';
+  DEFAULT_WINDOW_DIMENSIONS,
+} from '@fde-desktop/fde-core';
+
+// Menu bar components for apps
+import {
+  NotesMenuBar,
+  SettingsMenuBar,
+  PdfMenuBar,
+  ImageViewerMenuBar,
+  MenuEditMenuBar,
+  TerminalMenuBar,
+} from '@fde-desktop/fde-core';
+```
+
+### Lazy-Loaded App Components
+
+```tsx
+import {
+  FilesAppLazy,
+  NotesAppLazy,
+  ImageViewerAppLazy,
+  PdfAppLazy,
+  MenuEditAppLazy,
+  UploaderAppLazy,
+  SettingsAppLazy,
+  DeviceInfoAppLazy,
+  CalendarAppLazy,
+  CreateItemAppLazy,
+} from '@fde-desktop/fde-core';
+```
+
+### Shared Components
+
+```tsx
+import {
+  AppIcon,
+  VscIcon,
+  AppLoading,
+  AppEmptyState,
+  LanguageFlag,
+  CollapsibleSection,
+  FileIcon,
+  DirtyIndicator,
+  ColorPicker,
+  CreateItemApp,
+  DownloadProgress,
+  FilePickerApp,
+  FilePickerModal,
+  FolderPicker,
+  IconColorPicker,
+  SettingsSection,
+  ExternalLinkApp,
+  CustomAppLoader,
+  CustomAppLoadingScreen,
+  CustomAppNotSupported,
+  CustomAppOffline,
+  PortraitWarning,
+} from '@fde-desktop/fde-core';
 ```
 
 ### Stores
 
-```typescript
+```tsx
 import {
   useDesktopStore,
   useSettingsStore,
   useCustomAppStore,
   useAppTempMemoryStore,
-} from '@frannunpal/fde-core';
+  useCloseModalStore,
+  fileSystem,
+  resetFileSystem,
+  resetWindowManager,
+} from '@fde-desktop/fde-core';
+
+// Desktop state
+const { windows, openWindow, closeWindow } = useDesktopStore();
+
+// Settings
+const { wallpaper, theme, language, setThemeMode } = useSettingsStore();
+
+// Custom apps (Docker)
+const { customApps, loadCustomApps } = useCustomAppStore();
 ```
 
 ### Hooks
 
-```typescript
+```tsx
 import {
+  // App management
   useOpenApp,
+  useAppName,
   useFdeApi,
-  useNotifications,
-  useSystemTheme,
+
+  // UI
   useClock,
+  useSystemTheme,
+  useAnimationDuration,
+  useAdaptiveDimensions,
+  useTaskbarHeight,
+  useTaskbarContextMenu,
+  useContextMenu,
+  useCollapsible,
+  useSearchFilter,
+
+  // Notifications
+  useNotifications,
+
+  // File system
+  useDownload,
+  useResolvedUrl,
+
+  // Icons
+  useFcIcon,
+  useFcIconElement,
+  useFiIcon,
+  useFiIconElement,
+  useVscIcon,
+  useVscIconElement,
+
+  // Drag & Drop
+  DragDropProvider,
+  useDroppableArea,
+  useDraggableItem,
+  useDragDropState,
+
+  // Window
+  useWindowButtonRegistry,
+
+  // Theme & Language
+  useApplyFont,
+  useFontDownload,
+  useLanguageSync,
+
+  // State
+  useIsDirty,
+  useCloseInterceptor,
+
+  // Device
+  useDeviceDetection,
+
+  // Updates
+  useAppUpdate,
+
+  // Custom apps
   useCustomAppHMR,
-  // ... more hooks
-} from '@frannunpal/fde-core';
+  useCustomAppLifecycle,
+
+  // Lifecycle
+  useFolderName,
+} from '@fde-desktop/fde-core';
+```
+
+### Domain Entities
+
+```tsx
+import {
+  createWindow,
+  createDesktopIcon,
+  createLauncherFolder,
+  createPredefinedLauncherFolder,
+  updateLauncherFolder,
+  createFolder,
+  createFile,
+} from '@fde-desktop/fde-core';
+
+const win = createWindow({
+  title: 'My Window',
+  appId: 'my-app',
+  x: 100,
+  y: 100,
+  width: 800,
+  height: 600,
+});
+
+const icon = createDesktopIcon({
+  appId: 'files',
+  x: 20,
+  y: 20,
+  name: 'Files',
+  fcIcon: 'FcFolder',
+});
+```
+
+### Infrastructure
+
+```tsx
+import {
+  IndexedDBFileSystem,
+  DockerFileSystemAdapter,
+  FdeApiAdapter,
+  initializeFdeApi,
+  getFdeApi,
+  WindowManagerAdapter,
+  DefaultThemeProvider,
+  toMantineTheme,
+  JsDosAdapter,
+  prefetchApps,
+  migrateStorage,
+  SUPPORTED_LANGUAGES,
+  DEFAULT_LANGUAGE,
+} from '@fde-desktop/fde-core';
 ```
 
 ### Types & Interfaces
 
-```typescript
+```tsx
 import type {
+  // App types
   AppEntry,
+  AppRegistryEntry,
+  AppComponent,
+  WindowContentProps,
+  MenuBarBuilder,
+  MenuBarComponent,
+  MenuBarComponentProps,
+
+  // Window types
   WindowEntity,
-  FSNode,
-  DesktopIconInput,
+  WindowInput,
+  WindowProps,
+
+  // File system types
+  FileSystemNode,
+  FileNode,
+  FolderNode,
   IFileSystem,
-  // ... more types
-} from '@frannunpal/fde-core';
+
+  // Desktop types
+  DesktopIconEntity,
+  DesktopIconInput,
+  DesktopState,
+  NotificationItem,
+  ClipboardState,
+
+  // Theme types
+  Theme,
+  ThemeMode,
+  FdeTheme,
+  CustomThemeColors,
+  IThemeProvider,
+
+  // Other
+  AppMenuElement,
+  MenuItem,
+  CreateFolderOptions,
+  FdeApi,
+  LauncherFolder,
+  LauncherFolderInput,
+  SupportedLanguage,
+} from '@fde-desktop/fde-core';
 ```
 
 ### Utilities
 
-```typescript
+```tsx
 import {
+  // UUID
+  generateUUID,
+  uuidv4,
+
+  // Runtime detection
   getRuntime,
   isDocker,
   isBrowser,
-  uuid,
+  isElectron,
+  isDev,
+
+  // Formatting
   formatBytes,
-  // ... more utilities
-} from '@frannunpal/fde-core';
+  getFileExtension,
+  getMimeTypeFromExtension,
+  getAppIdForMime,
+
+  // File system
+  sortNodes,
+  sortDesktopIcons,
+  buildBreadcrumbs,
+
+  // Version
+  isNewerVersion,
+
+  // Browser
+  clearBrowserData,
+
+  // DOM
+  waitForContainer,
+
+  // URL
+  getBaseUrl,
+  resolveUrl,
+
+  // Hash
+  hashBlob,
+
+  // Colors
+  getFourRandomColors,
+} from '@fde-desktop/fde-core';
 ```
 
 ### Constants
 
-```typescript
+```tsx
 import {
-  CORE_APPS,
-  EXTRA_APPS,
+  // Layout
   DEFAULT_WINDOW_DIMENSIONS,
-  DEFAULT_THEME_COLORS,
   ICON_COLUMN_WIDTH,
+  ICON_ROW_HEIGHT,
+  ICON_MARGIN,
   TASKBAR_HEIGHT,
-  // ... more constants
-} from '@frannunpal/fde-core';
+  DEFAULT_VIEWPORT_WIDTH,
+  DEFAULT_VIEWPORT_HEIGHT,
+
+  // Breakpoints
+  BREAKPOINTS,
+
+  // Animation
+  ANIMATION_DURATION,
+
+  // Fonts
+  AVAILABLE_FONTS,
+  FONT_STACKS,
+  GOOGLE_FONTS_HREF,
+
+  // Colors
+  PRESET_COLORS,
+
+  // Icons
+  PRESET_ICONS,
+
+  // Launcher
+  DEFAULT_LAUNCHER_FOLDERS,
+  CUSTOM_APPS_FOLDER_ID,
+
+  // App IDs
+  APP_IDS,
+
+  // Themes
+  DEFAULT_FDE_THEME,
+} from '@fde-desktop/fde-core';
+```
+
+### i18n
+
+```tsx
+import { i18n } from '@fde-desktop/fde-core';
+import { I18nextProvider } from 'react-i18next';
+
+// Use in your app
+function App() {
+  return (
+    <I18nextProvider i18n={i18n}>
+      <FdeDesktop />
+    </I18nextProvider>
+  );
+}
 ```
 
 ## Core Apps
@@ -108,7 +475,7 @@ The following apps are included in `CORE_APPS`:
 
 | App ID         | Name         | Description            |
 | -------------- | ------------ | ---------------------- |
-| `files`        | FilesApp     | File browser           |
+| `files`        | Files        | File browser           |
 | `settings`     | Settings     | System settings        |
 | `notepad`      | Notepad      | Text editor (Tiptap)   |
 | `image-viewer` | Image Viewer | Image viewer           |
@@ -117,56 +484,40 @@ The following apps are included in `CORE_APPS`:
 | `device-info`  | Device Info  | System information     |
 | `calendar`     | Calendar     | Calendar widget        |
 | `menuedit`     | MenuEdit     | Launcher folder editor |
+| `terminal`     | Terminal     | Terminal emulator      |
+| `code-server`  | VS Code      | VS Code in browser     |
+
+## Example App
+
+The main repository's `src/` directory contains a complete example application that demonstrates how to use this package. It includes:
+
+- **WelcomeApp**: Personal portfolio/profile app
+- **LinkedinApp** / **GithubApp**: External link apps
+- **DosEmulatorApp**: DOS game emulator using js-dos
+- **Custom App Registry**: Shows how to register custom apps
+
+See the [main repository](https://github.com/frannunpal/fde-desktop) for the complete example.
 
 ## Runtime Detection
 
-```typescript
-import { getRuntime, isDocker, isBrowser, isElectron, isDev } from '@frannunpal/fde-core';
+```tsx
+import { getRuntime, isDocker, isBrowser, isElectron, isDev } from '@fde-desktop/fde-core';
 
-const runtime = getRuntime(); // 'docker' | 'browser' | 'electron'
+const runtime = getRuntime(); // 'browser' | 'docker' | 'electron'
 
 if (isDocker()) {
-  // Docker-specific code
+  // Docker-specific code (API-based file system)
 }
 
 if (isBrowser()) {
-  // Browser-specific code
+  // Browser-only code (IndexedDB file system)
 }
-```
-
-## Usage Example
-
-```tsx
-import { useDesktopStore, useOpenApp, FilesApp, CORE_APPS } from '@frannunpal/fde-core';
-
-function MyDesktop() {
-  const { windows, openWindow } = useDesktopStore();
-  const openApp = useOpenApp();
 
-  return (
-    <div>
-      <h1>My Desktop</h1>
-      {CORE_APPS.map(app => (
-        <button key={app.id} onClick={() => openApp(app)}>
-          {app.icon} {app.name}
-        </button>
-      ))}
-    </div>
-  );
+if (isElectron()) {
+  // Electron desktop app code
 }
 ```
 
-## Note on UI Components
-
-This package exports core logic, hooks, stores, and types, but **does not include UI components**. The UI components in the main repo depend on static assets (images, wallpapers) specific to the host application.
-
-For UI components, refer to the source code at:
-
-- `src/Presentation/Components/DesktopArea/`
-- `src/Presentation/Components/Window/`
-- `src/Presentation/Components/Taskbar/`
-- `src/Presentation/Components/Launcher/`
-
 ## License
 
-APACHE Version 2.0
+MIT