@backbay/glia-desktop 0.2.0-alpha.1

package/src/index.ts

@@ -0,0 +1,146 @@
+/**
+ * @backbay/glia Desktop OS
+ *
+ * Reusable desktop OS components for React applications.
+ * Includes window management, taskbar, context menus, and more.
+ *
+ * @example Basic usage with provider
+ * ```tsx
+ * import { DesktopOSProvider, Window, Taskbar, Desktop } from '@backbay/glia/desktop';
+ *
+ * function App() {
+ *   return (
+ *     <DesktopOSProvider
+ *       processes={myApps}
+ *       theme={{ colors: { accent: '#00ff88' } }}
+ *     >
+ *       <Desktop />
+ *       <Taskbar />
+ *     </DesktopOSProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Power user path with headless hooks
+ * ```tsx
+ * import { useWindowManager, useTaskbar } from '@backbay/glia/desktop/core';
+ *
+ * function MyWindowManager() {
+ *   const { windows, open, close, focus } = useWindowManager();
+ *   // Build your own UI
+ * }
+ * ```
+ */
+
+// Core (headless hooks and types)
+// Note: DesktopIcon type is exported as DesktopIconDef to avoid conflict with DesktopIcon component
+export {
+  // Window types
+  type WindowId,
+  type TilePosition,
+  type WindowState,
+  type WindowGroup,
+  type WindowOpenConfig,
+  type UseWindowManagerReturn,
+  // Window hooks
+  useWindowManager,
+  useWindowManagerStore,
+  createWindowManagerStore,
+  WindowManagerStoreProvider,
+  type WindowManagerStoreApi,
+  useWindowIds,
+  useWindow,
+  useIsWindowFocused,
+  useIsWindowFullscreen,
+  useIsFullscreenActive,
+  useWindowActions,
+  useWindowGroup,
+  // Shell types
+  type TaskbarButtonPosition,
+  type TaskbarItem,
+  type TaskbarPreviewState,
+  type UseTaskbarReturn,
+  type ContextMenuTargetType,
+  type ContextMenuTarget,
+  type ContextMenuItem,
+  type UseContextMenuReturn,
+  type StartMenuCategory,
+  type StartMenuApp,
+  type UseStartMenuReturn,
+  // Shell hooks
+  useTaskbar,
+  useTaskbarStore,
+  createTaskbarStore,
+  TaskbarStoreProvider,
+  type TaskbarStoreApi,
+  useStartMenu,
+  useStartMenuStore,
+  createStartMenuStore,
+  StartMenuStoreProvider,
+  type StartMenuStoreApi,
+  useSystemTray,
+  useSystemTrayStore,
+  createSystemTrayStore,
+  SystemTrayStoreProvider,
+  type SystemTrayStoreApi,
+  type SystemTrayItem as SystemTrayItemDef,
+  type UseSystemTrayReturn,
+  // Notification types
+  type NotificationType,
+  type NotificationPriority,
+  type NotificationAction,
+  type Notification,
+  type NotificationGroup,
+  type NotificationInput,
+  type UseNotificationsReturn,
+  // Notification hooks
+  useNotifications,
+  useNotificationStore,
+  createNotificationStore,
+  NotificationStoreProvider,
+  type NotificationStoreApi,
+  // Desktop types
+  type ProcessDefinition,
+  type ProcessInstance,
+  type DesktopIcon as DesktopIconDef,
+  type UseDesktopReturn,
+  type UseProcessRegistryReturn,
+  type SnapZone,
+  type UseSnapZonesReturn,
+  type DesktopOSConfig,
+  // Desktop hooks
+  useSnapZones,
+  useSnapZoneStore,
+  createSnapZoneStore,
+  SnapZoneStoreProvider,
+  type SnapZoneStoreApi,
+  getSnapZoneDimensions,
+  EDGE_THRESHOLD,
+  CORNER_SIZE,
+  // FileBrowser types
+  type FileItem,
+  type FileType,
+  type FileBrowserViewMode,
+  type FileBrowserSortField,
+  type FileBrowserSortOrder,
+  type FileBrowserSort,
+  type FileBrowserProps,
+  type UseFileBrowserReturn,
+  // FileBrowser hooks
+  useFileBrowser,
+  useFileBrowserStore,
+  createFileBrowserStore,
+  FileBrowserStoreProvider,
+  type FileBrowserStoreApi,
+} from './core';
+
+// Themes
+export * from './themes';
+
+// Providers
+export * from './providers';
+
+// Components (styled)
+export * from './components/desktop';
+export * from './components/window';
+export * from './components/shell';

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/providers/DesktopOSProvider.tsx

@@ -0,0 +1,391 @@
+/**
+ * @backbay/glia Desktop OS - DesktopOSProvider
+ *
+ * Main provider that wires together all desktop OS functionality.
+ * Manages windows, processes, taskbar, and context menus.
+ */
+
+'use client';
+
+import React, {
+  createContext,
+  useContext,
+  useMemo,
+  useCallback,
+  useEffect,
+  useRef,
+} from 'react';
+import type { PartialDesktopOSTheme } from '../themes/types';
+import { ThemeProvider } from './ThemeProvider';
+import {
+  useWindowManager,
+  useWindowManagerStore,
+} from '../core/window/useWindowManager';
+import type { WindowId, WindowState, UseWindowManagerReturn } from '../core/window/types';
+import { useSnapZones } from '../core/desktop/useSnapZones';
+import type { UseSnapZonesReturn } from '../core/desktop/types';
+import { useTaskbar, useTaskbarStore } from '../core/shell/useTaskbar';
+import type { UseTaskbarReturn } from '../core/shell/types';
+import type { ProcessDefinition, ProcessInstance, DesktopOSConfig } from '../core/desktop/types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Process Registry Store
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface ProcessRegistryState {
+  definitions: Map<string, ProcessDefinition>;
+  instances: Map<string, ProcessInstance>;
+}
+
+let processIdCounter = 0;
+function generateProcessInstanceId(): string {
+  return `process-${Date.now()}-${++processIdCounter}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Context
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface DesktopOSContextValue {
+  // Window management
+  windows: UseWindowManagerReturn;
+
+  // Snap zones
+  snapZones: UseSnapZonesReturn;
+
+  // Taskbar
+  taskbar: UseTaskbarReturn;
+
+  // Process management
+  processes: {
+    definitions: ProcessDefinition[];
+    instances: ProcessInstance[];
+    launch: (processId: string, args?: Record<string, unknown>) => string | null;
+    terminate: (instanceId: string) => void;
+    getDefinition: (id: string) => ProcessDefinition | undefined;
+    getInstanceByWindow: (windowId: WindowId) => ProcessInstance | undefined;
+  };
+
+  // Configuration
+  config: {
+    enableSnapZones: boolean;
+    enableWindowGroups: boolean;
+    enableAnimations: boolean;
+  };
+}
+
+const DesktopOSContext = createContext<DesktopOSContextValue | null>(null);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Hook
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Access the desktop OS context.
+ *
+ * @throws Error if used outside DesktopOSProvider
+ *
+ * @example
+ * ```tsx
+ * const { windows, processes, taskbar } = useDesktopOS();
+ *
+ * const handleLaunch = () => {
+ *   processes.launch('my-app');
+ * };
+ * ```
+ */
+export function useDesktopOS(): DesktopOSContextValue {
+  const context = useContext(DesktopOSContext);
+  if (!context) {
+    throw new Error('useDesktopOS must be used within a DesktopOSProvider');
+  }
+  return context;
+}
+
+/**
+ * Check if we're inside a DesktopOSProvider.
+ * Useful for components that work in both standalone and managed modes.
+ */
+export function useIsInDesktopOS(): boolean {
+  return useContext(DesktopOSContext) !== null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Provider
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface DesktopOSProviderProps extends DesktopOSConfig {
+  children: React.ReactNode;
+  /** Theme customization */
+  theme?: PartialDesktopOSTheme;
+}
+
+/**
+ * Main provider for desktop OS functionality.
+ *
+ * Wires together window management, process registry, taskbar, and theming.
+ *
+ * @example
+ * ```tsx
+ * const myApps: ProcessDefinition[] = [
+ *   {
+ *     id: 'notepad',
+ *     name: 'Notepad',
+ *     icon: <NotepadIcon />,
+ *     component: NotepadApp,
+ *     defaultSize: { width: 600, height: 400 },
+ *   },
+ * ];
+ *
+ * function App() {
+ *   return (
+ *     <DesktopOSProvider
+ *       processes={myApps}
+ *       theme={{ colors: { accent: '#00ff88' } }}
+ *       enableSnapZones
+ *       enableWindowGroups
+ *     >
+ *       <Desktop>
+ *         <WindowManager />
+ *       </Desktop>
+ *       <Taskbar />
+ *       <ContextMenu />
+ *     </DesktopOSProvider>
+ *   );
+ * }
+ * ```
+ */
+export function DesktopOSProvider({
+  children,
+  processes: processDefinitions,
+  initialWindows,
+  initialPinnedApps,
+  theme,
+  onWindowsChange,
+  onPinnedAppsChange,
+  enableSnapZones = true,
+  enableWindowGroups = true,
+  enableAnimations = true,
+}: DesktopOSProviderProps) {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Process Registry State
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const [processState, setProcessState] = React.useState<ProcessRegistryState>(
+    () => ({
+      definitions: new Map(processDefinitions.map((d) => [d.id, d])),
+      instances: new Map(),
+    })
+  );
+
+  // Update definitions when prop changes
+  useEffect(() => {
+    setProcessState((prev) => ({
+      ...prev,
+      definitions: new Map(processDefinitions.map((d) => [d.id, d])),
+    }));
+  }, [processDefinitions]);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Core Hooks
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const windowManager = useWindowManager();
+  const snapZones = useSnapZones();
+
+  // Build window info for taskbar
+  const windowsForTaskbar = useMemo(
+    () =>
+      windowManager.windows.map((w) => {
+        // Find the process instance for this window
+        const instance = Array.from(processState.instances.values()).find(
+          (i) => i.windowId === w.id
+        );
+        return {
+          id: w.id,
+          appId: instance?.processId ?? 'unknown',
+          title: w.title,
+          icon: w.icon,
+        };
+      }),
+    [windowManager.windows, processState.instances]
+  );
+
+  const taskbar = useTaskbar(windowsForTaskbar, windowManager.focusedId);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Process Management
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const launch = useCallback(
+    (processId: string, args?: Record<string, unknown>): string | null => {
+      const definition = processState.definitions.get(processId);
+      if (!definition) {
+        console.warn(`Process not found: ${processId}`);
+        return null;
+      }
+
+      // Check singleton constraint
+      if (definition.singleton) {
+        const existing = Array.from(processState.instances.values()).find(
+          (i) => i.processId === processId
+        );
+        if (existing) {
+          // Focus existing window instead
+          windowManager.focus(existing.windowId);
+          return existing.id;
+        }
+      }
+
+      // Open window
+      const windowId = windowManager.open({
+        title: definition.name,
+        icon: typeof definition.icon === 'string' ? definition.icon : undefined,
+        size: definition.defaultSize,
+        minSize: definition.minSize,
+        maxSize: definition.maxSize,
+      });
+
+      // Create process instance
+      const instanceId = generateProcessInstanceId();
+      const instance: ProcessInstance = {
+        id: instanceId,
+        processId,
+        windowId,
+        args,
+        startedAt: Date.now(),
+      };
+
+      setProcessState((prev) => {
+        const newInstances = new Map(prev.instances);
+        newInstances.set(instanceId, instance);
+        return { ...prev, instances: newInstances };
+      });
+
+      return instanceId;
+    },
+    [processState.definitions, processState.instances, windowManager]
+  );
+
+  const terminate = useCallback(
+    (instanceId: string) => {
+      const instance = processState.instances.get(instanceId);
+      if (!instance) return;
+
+      // Close the window
+      windowManager.close(instance.windowId);
+
+      // Remove process instance
+      setProcessState((prev) => {
+        const newInstances = new Map(prev.instances);
+        newInstances.delete(instanceId);
+        return { ...prev, instances: newInstances };
+      });
+    },
+    [processState.instances, windowManager]
+  );
+
+  const getDefinition = useCallback(
+    (id: string) => processState.definitions.get(id),
+    [processState.definitions]
+  );
+
+  const getInstanceByWindow = useCallback(
+    (windowId: WindowId) =>
+      Array.from(processState.instances.values()).find(
+        (i) => i.windowId === windowId
+      ),
+    [processState.instances]
+  );
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Callbacks
+  // ─────────────────────────────────────────────────────────────────────────
+
+  // Notify on windows change
+  useEffect(() => {
+    onWindowsChange?.(windowManager.windows);
+  }, [windowManager.windows, onWindowsChange]);
+
+  // Clean up process instances when windows close
+  useEffect(() => {
+    const windowIds = new Set(windowManager.windows.map((w) => w.id));
+
+    setProcessState((prev) => {
+      let changed = false;
+      const newInstances = new Map(prev.instances);
+
+      for (const [instanceId, instance] of prev.instances) {
+        if (!windowIds.has(instance.windowId)) {
+          newInstances.delete(instanceId);
+          changed = true;
+        }
+      }
+
+      return changed ? { ...prev, instances: newInstances } : prev;
+    });
+  }, [windowManager.windows]);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Initialize pinned apps
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const pinnedAppsInitialized = useRef(false);
+  useEffect(() => {
+    // Only initialize once, even if initialPinnedApps changes
+    if (pinnedAppsInitialized.current) return;
+    if (initialPinnedApps && initialPinnedApps.length > 0) {
+      pinnedAppsInitialized.current = true;
+      const taskbarStore = useTaskbarStore.getState();
+      for (const appId of initialPinnedApps) {
+        taskbarStore.pinApp(appId);
+      }
+    }
+  }, [initialPinnedApps]);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Context Value
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const contextValue = useMemo<DesktopOSContextValue>(
+    () => ({
+      windows: windowManager,
+      snapZones,
+      taskbar,
+      processes: {
+        definitions: Array.from(processState.definitions.values()),
+        instances: Array.from(processState.instances.values()),
+        launch,
+        terminate,
+        getDefinition,
+        getInstanceByWindow,
+      },
+      config: {
+        enableSnapZones,
+        enableWindowGroups,
+        enableAnimations,
+      },
+    }),
+    [
+      windowManager,
+      snapZones,
+      taskbar,
+      processState,
+      launch,
+      terminate,
+      getDefinition,
+      getInstanceByWindow,
+      enableSnapZones,
+      enableWindowGroups,
+      enableAnimations,
+    ]
+  );
+
+  return (
+    <ThemeProvider theme={theme}>
+      <DesktopOSContext.Provider value={contextValue}>
+        {children}
+      </DesktopOSContext.Provider>
+    </ThemeProvider>
+  );
+}

package/src/providers/ThemeProvider.tsx

@@ -0,0 +1,162 @@
+/**
+ * @backbay/glia Desktop OS - ThemeProvider
+ *
+ * Injects theme CSS variables into the DOM.
+ * Can be used standalone or wrapped by DesktopOSProvider.
+ */
+
+'use client';
+
+import React, { createContext, useContext, useRef, useMemo, useLayoutEffect, useEffect } from 'react';
+
+// SSR-safe useLayoutEffect - avoids React warnings during server rendering
+const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+import {
+  type DesktopOSTheme,
+  type PartialDesktopOSTheme,
+  themeToCssVariables,
+  mergeTheme,
+} from '../themes/types';
+import { defaultTheme } from '../themes/default';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Context
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface ThemeContextValue {
+  theme: DesktopOSTheme;
+  cssVariables: Record<string, string>;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Hook
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Access the current theme.
+ *
+ * @example
+ * ```tsx
+ * const { theme } = useDesktopTheme();
+ * console.log(theme.colors.accent);
+ * ```
+ */
+export function useDesktopTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    // Return default theme if not in provider (standalone mode)
+    return {
+      theme: defaultTheme,
+      cssVariables: themeToCssVariables(defaultTheme),
+    };
+  }
+  return context;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Provider
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ThemeProviderProps {
+  children: React.ReactNode;
+  /** Custom theme or partial theme to merge with default */
+  theme?: PartialDesktopOSTheme;
+  /** Target element to inject CSS variables (defaults to :root) */
+  target?: 'root' | 'local';
+  /** Class name for the wrapper div (only used when target='local') */
+  className?: string;
+}
+
+/**
+ * Provides theme context and injects CSS variables.
+ *
+ * @example Global injection (recommended)
+ * ```tsx
+ * <ThemeProvider theme={{ colors: { accent: '#00ff88' } }}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ *
+ * @example Local injection (for isolated instances)
+ * ```tsx
+ * <ThemeProvider target="local" className="my-desktop">
+ *   <Desktop />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+  children,
+  theme: partialTheme,
+  target = 'root',
+  className,
+}: ThemeProviderProps) {
+  const deprecationWarned = useRef(false);
+  if (!deprecationWarned.current) {
+    deprecationWarned.current = true;
+    console.warn("[Glia] DesktopOS ThemeProvider is deprecated. Use GliaThemeProvider instead.");
+  }
+
+  // Merge custom theme with default
+  const theme = useMemo(
+    () => (partialTheme ? mergeTheme(defaultTheme, partialTheme) : defaultTheme),
+    [partialTheme]
+  );
+
+  // Convert to CSS variables
+  const cssVariables = useMemo(() => themeToCssVariables(theme), [theme]);
+
+  // Inject CSS variables into :root
+  useIsomorphicLayoutEffect(() => {
+    if (target !== 'root') return;
+
+    const root = document.documentElement;
+    const previousValues: Record<string, string> = {};
+
+    // Store previous values and set new ones
+    for (const [key, value] of Object.entries(cssVariables)) {
+      previousValues[key] = root.style.getPropertyValue(key);
+      root.style.setProperty(key, value);
+    }
+
+    // Cleanup: restore previous values
+    return () => {
+      for (const [key, value] of Object.entries(previousValues)) {
+        if (value) {
+          root.style.setProperty(key, value);
+        } else {
+          root.style.removeProperty(key);
+        }
+      }
+    };
+  }, [cssVariables, target]);
+
+  const contextValue = useMemo(
+    () => ({ theme, cssVariables }),
+    [theme, cssVariables]
+  );
+
+  // Local injection wraps children in a div with inline CSS variables
+  if (target === 'local') {
+    const style: React.CSSProperties = {};
+    for (const [key, value] of Object.entries(cssVariables)) {
+      (style as Record<string, string>)[key] = value;
+    }
+
+    return (
+      <ThemeContext.Provider value={contextValue}>
+        <div className={className} style={style}>
+          {children}
+        </div>
+      </ThemeContext.Provider>
+    );
+  }
+
+  return (
+    <ThemeContext.Provider value={contextValue}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}