@backbay/glia-desktop 0.2.0-alpha.1

package/src/core/shell/useTaskbar.tsx

@@ -0,0 +1,320 @@
+/**
+ * @backbay/glia Desktop OS - useTaskbar Hook
+ *
+ * Taskbar state management for button positions and hover previews.
+ * Used for minimize/restore animations and window preview tooltips.
+ */
+
+import { useMemo, createContext, useContext, useState, type ReactNode } from 'react';
+import { create, createStore, useStore } from 'zustand';
+import { useShallow } from 'zustand/react/shallow';
+import type { WindowId } from '../window/types';
+import type {
+  TaskbarButtonPosition,
+  TaskbarPreviewState,
+  TaskbarItem,
+  UseTaskbarReturn,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Delay before showing preview (ms) */
+const PREVIEW_SHOW_DELAY = 200;
+
+/** Delay before hiding preview - allows moving to preview (ms) */
+const PREVIEW_HIDE_DELAY = 100;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface TaskbarStore {
+  buttonPositions: Map<string, TaskbarButtonPosition>;
+  previewState: TaskbarPreviewState | null;
+  pinnedApps: string[];
+  _showPreviewTimeout: ReturnType<typeof setTimeout> | null;
+  _hidePreviewTimeout: ReturnType<typeof setTimeout> | null;
+
+  registerButtonPosition: (id: string, position: TaskbarButtonPosition) => void;
+  unregisterButtonPosition: (id: string) => void;
+  getButtonPosition: (id: string) => TaskbarButtonPosition | undefined;
+  getButtonCenter: (id: string) => { x: number; y: number } | undefined;
+
+  startPreviewHover: (windowId: WindowId, icon?: string) => void;
+  endPreviewHover: () => void;
+  cancelHidePreview: () => void;
+  hidePreview: () => void;
+
+  pinApp: (appId: string) => void;
+  unpinApp: (appId: string) => void;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Factory
+// ═══════════════════════════════════════════════════════════════════════════
+
+function createTaskbarStoreImpl(set: any, get: any): TaskbarStore {
+  return {
+    buttonPositions: new Map(),
+    previewState: null,
+    pinnedApps: [],
+    _showPreviewTimeout: null,
+    _hidePreviewTimeout: null,
+
+    registerButtonPosition: (id, position) => {
+      set((state: TaskbarStore) => {
+        const newPositions = new Map(state.buttonPositions);
+        newPositions.set(id, position);
+        return { buttonPositions: newPositions };
+      });
+    },
+
+    unregisterButtonPosition: (id) => {
+      set((state: TaskbarStore) => {
+        const newPositions = new Map(state.buttonPositions);
+        newPositions.delete(id);
+        return { buttonPositions: newPositions };
+      });
+    },
+
+    getButtonPosition: (id) => {
+      return get().buttonPositions.get(id);
+    },
+
+    getButtonCenter: (id) => {
+      const pos = get().buttonPositions.get(id);
+      if (!pos) return undefined;
+      return {
+        x: pos.x + pos.width / 2,
+        y: pos.y + pos.height / 2,
+      };
+    },
+
+    startPreviewHover: (windowId, icon) => {
+      const state = get();
+
+      if (state._hidePreviewTimeout) {
+        clearTimeout(state._hidePreviewTimeout);
+        set({ _hidePreviewTimeout: null });
+      }
+
+      if (state._showPreviewTimeout) {
+        clearTimeout(state._showPreviewTimeout);
+      }
+
+      const timeout = setTimeout(() => {
+        const currentState = get();
+        const anchorRect = currentState.buttonPositions.get(windowId);
+        if (anchorRect) {
+          set({
+            previewState: { windowId, anchorRect, icon },
+            _showPreviewTimeout: null,
+          });
+        }
+      }, PREVIEW_SHOW_DELAY);
+
+      set({ _showPreviewTimeout: timeout });
+    },
+
+    endPreviewHover: () => {
+      const state = get();
+
+      if (state._showPreviewTimeout) {
+        clearTimeout(state._showPreviewTimeout);
+        set({ _showPreviewTimeout: null });
+      }
+
+      if (state._hidePreviewTimeout) {
+        clearTimeout(state._hidePreviewTimeout);
+      }
+
+      const timeout = setTimeout(() => {
+        set({ previewState: null, _hidePreviewTimeout: null });
+      }, PREVIEW_HIDE_DELAY);
+
+      set({ _hidePreviewTimeout: timeout });
+    },
+
+    cancelHidePreview: () => {
+      const state = get();
+
+      if (state._hidePreviewTimeout) {
+        clearTimeout(state._hidePreviewTimeout);
+        set({ _hidePreviewTimeout: null });
+      }
+    },
+
+    hidePreview: () => {
+      const state = get();
+
+      if (state._showPreviewTimeout) {
+        clearTimeout(state._showPreviewTimeout);
+      }
+      if (state._hidePreviewTimeout) {
+        clearTimeout(state._hidePreviewTimeout);
+      }
+
+      set({
+        previewState: null,
+        _showPreviewTimeout: null,
+        _hidePreviewTimeout: null,
+      });
+    },
+
+    pinApp: (appId) => {
+      set((state: TaskbarStore) => ({
+        pinnedApps: state.pinnedApps.includes(appId)
+          ? state.pinnedApps
+          : [...state.pinnedApps, appId],
+      }));
+    },
+
+    unpinApp: (appId) => {
+      set((state: TaskbarStore) => ({
+        pinnedApps: state.pinnedApps.filter((id: string) => id !== appId),
+      }));
+    },
+  };
+}
+
+/** Factory: creates an isolated Taskbar store instance. */
+export function createTaskbarStore() {
+  return createStore<TaskbarStore>((set, get) => createTaskbarStoreImpl(set, get));
+}
+
+export type TaskbarStoreApi = ReturnType<typeof createTaskbarStore>;
+
+const TaskbarStoreContext = createContext<TaskbarStoreApi | null>(null);
+
+/** Provider that creates an isolated Taskbar store for its subtree. */
+export function TaskbarStoreProvider({ children }: { children: ReactNode }) {
+  const [store] = useState(() => createTaskbarStore());
+  return (
+    <TaskbarStoreContext.Provider value={store}>
+      {children}
+    </TaskbarStoreContext.Provider>
+  );
+}
+
+// Legacy singleton
+export const useTaskbarStore = create<TaskbarStore>((set, get) => createTaskbarStoreImpl(set, get));
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Context-aware store resolver
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Returns the context-provided store if available, otherwise the singleton. */
+function useResolvedTaskbarStore(): import('zustand').StoreApi<TaskbarStore> {
+  const contextStore = useContext(TaskbarStoreContext);
+  return contextStore ?? useTaskbarStore;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Public Hook
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Hook for taskbar state management.
+ *
+ * Handles button position tracking for animations and hover preview state.
+ *
+ * @example
+ * ```tsx
+ * const { registerButtonPosition, startPreviewHover, endPreviewHover } = useTaskbar();
+ *
+ * // Register button position on mount
+ * useEffect(() => {
+ *   const rect = buttonRef.current?.getBoundingClientRect();
+ *   if (rect) {
+ *     registerButtonPosition(windowId, {
+ *       x: rect.x, y: rect.y, width: rect.width, height: rect.height
+ *     });
+ *   }
+ * }, []);
+ *
+ * // Handle hover
+ * <button
+ *   onMouseEnter={() => startPreviewHover(windowId)}
+ *   onMouseLeave={endPreviewHover}
+ * >
+ *   {title}
+ * </button>
+ * ```
+ */
+export function useTaskbar(
+  windows: Array<{ id: string; appId: string; title: string; icon?: string }> = [],
+  activeWindowId: WindowId | null = null
+): UseTaskbarReturn {
+  const resolvedStore = useResolvedTaskbarStore();
+  const store = useStore(
+    resolvedStore,
+    useShallow((state) => ({
+      buttonPositions: state.buttonPositions,
+      previewState: state.previewState,
+      pinnedApps: state.pinnedApps,
+      registerButtonPosition: state.registerButtonPosition,
+      unregisterButtonPosition: state.unregisterButtonPosition,
+      getButtonCenter: state.getButtonCenter,
+      startPreviewHover: state.startPreviewHover,
+      endPreviewHover: state.endPreviewHover,
+      cancelHidePreview: state.cancelHidePreview,
+      hidePreview: state.hidePreview,
+      pinApp: state.pinApp,
+      unpinApp: state.unpinApp,
+    })),
+  );
+
+  // Build taskbar items from windows and pinned apps (memoized to prevent unnecessary re-renders)
+  const items = useMemo(() => {
+    const result: TaskbarItem[] = [];
+
+    // Add pinned apps (even if not running)
+    for (const appId of store.pinnedApps) {
+      const runningWindow = windows.find((w) => w.appId === appId);
+      result.push({
+        id: runningWindow?.id ?? `pinned-${appId}`,
+        windowId: runningWindow?.id,
+        appId,
+        title: runningWindow?.title ?? appId,
+        icon: runningWindow?.icon,
+        isPinned: true,
+        isActive: runningWindow?.id === activeWindowId,
+      });
+    }
+
+    // Add running windows that aren't pinned
+    for (const window of windows) {
+      if (!store.pinnedApps.includes(window.appId)) {
+        result.push({
+          id: window.id,
+          windowId: window.id,
+          appId: window.appId,
+          title: window.title,
+          icon: window.icon,
+          isPinned: false,
+          isActive: window.id === activeWindowId,
+        });
+      }
+    }
+
+    return result;
+  }, [windows, store.pinnedApps, activeWindowId]);
+
+  return {
+    items,
+    activeWindowId,
+    previewState: store.previewState,
+    buttonPositions: store.buttonPositions,
+    registerButtonPosition: store.registerButtonPosition,
+    unregisterButtonPosition: store.unregisterButtonPosition,
+    getButtonCenter: store.getButtonCenter,
+    pin: store.pinApp,
+    unpin: store.unpinApp,
+    startPreviewHover: store.startPreviewHover,
+    endPreviewHover: store.endPreviewHover,
+    cancelHidePreview: store.cancelHidePreview,
+    hidePreview: store.hidePreview,
+  };
+}

package/src/core/useKeyboardNavigation.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect } from "react";
+import { useWindowManagerStore, type WindowManagerStoreApi } from "./window/useWindowManager";
+
+/**
+ * Global keyboard navigation hook for the desktop shell.
+ *
+ * Listens for:
+ * - Ctrl+Tab: Cycle focus to the next open window
+ * - Escape: Close the current overlay / exit fullscreen
+ *
+ * Call this once from the desktop shell root component.
+ *
+ * @param storeApi - Optional store API; defaults to the legacy singleton.
+ */
+export function useKeyboardNavigation(storeApi?: WindowManagerStoreApi) {
+  useEffect(() => {
+    const api = storeApi ?? useWindowManagerStore;
+
+    function handleKeyDown(e: KeyboardEvent) {
+      const store = api.getState();
+
+      // Ctrl+Tab — cycle to next window
+      if (e.key === "Tab" && e.ctrlKey && !e.altKey && !e.metaKey) {
+        e.preventDefault();
+        store._cycleFocusNext();
+        return;
+      }
+
+      // Escape — exit fullscreen if active
+      if (e.key === "Escape" && store.fullscreenId) {
+        store._exitFullscreen();
+        return;
+      }
+    }
+
+    globalThis.addEventListener("keydown", handleKeyDown);
+    return () => globalThis.removeEventListener("keydown", handleKeyDown);
+  }, [storeApi]);
+}

package/src/core/window/__tests__/useWindowManager.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { useWindowManagerStore } from '../useWindowManager';
+
+function resetStore() {
+  useWindowManagerStore.setState({
+    windows: new Map(),
+    groups: new Map(),
+    focusedId: null,
+    fullscreenId: null,
+    nextZIndex: 1,
+  });
+}
+
+describe('WindowManager store', () => {
+  beforeEach(() => {
+    resetStore();
+  });
+
+  describe('open', () => {
+    it('creates a window entry', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test Window' });
+
+      const state = useWindowManagerStore.getState();
+      expect(state.windows.size).toBe(1);
+      expect(state.windows.get(id)).toBeDefined();
+      expect(state.windows.get(id)!.title).toBe('Test Window');
+    });
+
+    it('sets the new window as focused', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      const state = useWindowManagerStore.getState();
+      expect(state.focusedId).toBe(id);
+      expect(state.windows.get(id)!.isFocused).toBe(true);
+    });
+
+    it('uses default size when none provided', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.size).toEqual({ width: 640, height: 480 });
+    });
+
+    it('uses provided size', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test', size: { width: 800, height: 600 } });
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.size).toEqual({ width: 800, height: 600 });
+    });
+
+    it('increments z-index for each new window', () => {
+      const store = useWindowManagerStore.getState();
+      const id1 = store._open({ title: 'W1' });
+      const id2 = useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      const state = useWindowManagerStore.getState();
+      const w1 = state.windows.get(id1)!;
+      const w2 = state.windows.get(id2)!;
+      expect(w2.zIndex).toBeGreaterThan(w1.zIndex);
+    });
+  });
+
+  describe('close', () => {
+    it('removes the window', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+      expect(useWindowManagerStore.getState().windows.size).toBe(1);
+
+      useWindowManagerStore.getState()._close(id);
+      expect(useWindowManagerStore.getState().windows.size).toBe(0);
+    });
+
+    it('focuses next topmost window after closing focused window', () => {
+      const store = useWindowManagerStore.getState();
+      const id1 = store._open({ title: 'W1' });
+      const id2 = useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      expect(useWindowManagerStore.getState().focusedId).toBe(id2);
+
+      useWindowManagerStore.getState()._close(id2);
+      expect(useWindowManagerStore.getState().focusedId).toBe(id1);
+    });
+
+    it('sets focusedId to null when last window is closed', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._close(id);
+      expect(useWindowManagerStore.getState().focusedId).toBeNull();
+    });
+
+    it('does nothing for non-existent window', () => {
+      const store = useWindowManagerStore.getState();
+      store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._close('non-existent');
+      expect(useWindowManagerStore.getState().windows.size).toBe(1);
+    });
+  });
+
+  describe('focus', () => {
+    it('updates z-index and focused state', () => {
+      const store = useWindowManagerStore.getState();
+      const id1 = store._open({ title: 'W1' });
+      const id2 = useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      // id2 is focused, focus id1
+      useWindowManagerStore.getState()._focus(id1);
+
+      const state = useWindowManagerStore.getState();
+      expect(state.focusedId).toBe(id1);
+      expect(state.windows.get(id1)!.isFocused).toBe(true);
+      expect(state.windows.get(id2)!.isFocused).toBe(false);
+    });
+
+    it('does nothing if window is already focused', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      const zBefore = useWindowManagerStore.getState().nextZIndex;
+      useWindowManagerStore.getState()._focus(id);
+      const zAfter = useWindowManagerStore.getState().nextZIndex;
+
+      // nextZIndex should not change since it was already focused
+      expect(zAfter).toBe(zBefore);
+    });
+  });
+
+  describe('minimize', () => {
+    it('sets isMinimized to true', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._minimize(id);
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.isMinimized).toBe(true);
+    });
+
+    it('focuses next topmost non-minimized window', () => {
+      const store = useWindowManagerStore.getState();
+      const id1 = store._open({ title: 'W1' });
+      const id2 = useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      useWindowManagerStore.getState()._minimize(id2);
+
+      expect(useWindowManagerStore.getState().focusedId).toBe(id1);
+    });
+
+    it('sets focusedId to null when all windows are minimized', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._minimize(id);
+
+      expect(useWindowManagerStore.getState().focusedId).toBeNull();
+    });
+  });
+
+  describe('maximize', () => {
+    it('sets isMaximized to true and saves pre-maximize state', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test', position: { x: 100, y: 100 }, size: { width: 400, height: 300 } });
+
+      useWindowManagerStore.getState()._maximize(id);
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.isMaximized).toBe(true);
+      expect(w.preMaximize).toEqual({ x: 100, y: 100, width: 400, height: 300 });
+      expect(w.position).toEqual({ x: 0, y: 0 });
+    });
+
+    it('does nothing if already maximized', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._maximize(id);
+      const firstSize = useWindowManagerStore.getState().windows.get(id)!.size;
+
+      useWindowManagerStore.getState()._maximize(id);
+      const secondSize = useWindowManagerStore.getState().windows.get(id)!.size;
+
+      expect(firstSize).toEqual(secondSize);
+    });
+  });
+
+  describe('restore', () => {
+    it('restores from minimized', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test' });
+
+      useWindowManagerStore.getState()._minimize(id);
+      expect(useWindowManagerStore.getState().windows.get(id)!.isMinimized).toBe(true);
+
+      useWindowManagerStore.getState()._restore(id);
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.isMinimized).toBe(false);
+    });
+
+    it('restores from maximized to pre-maximize position', () => {
+      const store = useWindowManagerStore.getState();
+      const id = store._open({ title: 'Test', position: { x: 100, y: 200 }, size: { width: 400, height: 300 } });
+
+      useWindowManagerStore.getState()._maximize(id);
+      useWindowManagerStore.getState()._restore(id);
+
+      const w = useWindowManagerStore.getState().windows.get(id)!;
+      expect(w.isMaximized).toBe(false);
+      expect(w.position).toEqual({ x: 100, y: 200 });
+      expect(w.size).toEqual({ width: 400, height: 300 });
+    });
+  });
+
+  describe('stacking order', () => {
+    it('maintains correct z-index order with multiple windows', () => {
+      const store = useWindowManagerStore.getState();
+      const id1 = store._open({ title: 'W1' });
+      const id2 = useWindowManagerStore.getState()._open({ title: 'W2' });
+      const id3 = useWindowManagerStore.getState()._open({ title: 'W3' });
+
+      // Focus id1, bringing it to top
+      useWindowManagerStore.getState()._focus(id1);
+
+      const state = useWindowManagerStore.getState();
+      const z1 = state.windows.get(id1)!.zIndex;
+      const z2 = state.windows.get(id2)!.zIndex;
+      const z3 = state.windows.get(id3)!.zIndex;
+
+      // id1 should be on top (highest z-index)
+      expect(z1).toBeGreaterThan(z2);
+      expect(z1).toBeGreaterThan(z3);
+    });
+  });
+
+  describe('minimizeAll', () => {
+    it('minimizes all windows and clears focus', () => {
+      const store = useWindowManagerStore.getState();
+      store._open({ title: 'W1' });
+      useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      useWindowManagerStore.getState()._minimizeAll();
+
+      const state = useWindowManagerStore.getState();
+      for (const [, w] of state.windows) {
+        expect(w.isMinimized).toBe(true);
+      }
+      expect(state.focusedId).toBeNull();
+    });
+  });
+
+  describe('closeAll', () => {
+    it('removes all windows', () => {
+      const store = useWindowManagerStore.getState();
+      store._open({ title: 'W1' });
+      useWindowManagerStore.getState()._open({ title: 'W2' });
+
+      useWindowManagerStore.getState()._closeAll();
+
+      const state = useWindowManagerStore.getState();
+      expect(state.windows.size).toBe(0);
+      expect(state.focusedId).toBeNull();
+    });
+  });
+});

package/src/core/window/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @backbay/glia Desktop OS - Window Core
+ */
+
+export * from './types';
+export * from './useWindowManager';