Window Manager Context Provider
Relevant source files
The following files were used as context for generating this wiki page:
The Window Manager Context Provider is a core architectural component of the portfolio application that facilitates a multi-window desktop environment within a web browser. It acts as the central state authority, managing the lifecycle, positioning, and layering (z-index) of various application windows.
The system utilizes React's Context API and a useReducer pattern to provide a unified interface for interacting with windows from disparate components like the Dock or individual Window headers. By encapsulating window logic, it ensures that only a single instance of an application is open at a time and handles complex state transitions such as focusing, minimizing, and resizing.
Sources: context/WindowManagerContext.tsx:1-40, features/desktop/components/Desktop.tsx:21-36
State Management Architecture
The state is governed by a reducer-based workflow that processes discrete actions to update the global window state.
State Structure
The WindowManagerState maintains an array of active windows, the ID of the currently focused window, and a counter for the next available z-index to ensure correct visual stacking.
| Field | Type | Description |
|---|---|---|
windows | WindowState[] | Array of active window objects including geometry and metadata. |
focusedId | string | null | The ID of the window currently receiving user focus. |
nextZIndex | number | A counter used to bring windows to the foreground. |
Sources: workflows/windowManager.ts:12-16
Action Dispatch Flow
The provider exposes a memoized API to the rest of the application, abstracting the dispatch calls into high-level functions like open, close, and focus.
The diagram above illustrates how a UI interaction (e.g., clicking a Dock icon) triggers a state update that propagates back to the visual layers.
Sources: context/WindowManagerContext.tsx:32-48, features/desktop/components/WindowLayer.tsx:10-18
Core Reducer Logic
The windowReducer handles the complex logic of window manipulation. It ensures single-instance application behavior: if an app is already open, the open action simply brings it to the front and restores it if minimized.
Window Operations
- Open: Checks if the
appIdalready exists. If so, it increments the z-index and focuses the window. If not, it creates a new entry. - Focus: Updates the
focusedIdand incrementsnextZIndexto move the window to the top layer. - Minimize: Sets the
isMinimizedflag to true and clears thefocusedIdif the minimized window was active. - Geometry Updates: The
moveandresizeactions update thex,y,width, andheightproperties specifically for the target window ID.
Sources: workflows/windowManager.ts:47-104, workflows/windowManager.test.ts:14-87
Layering and Focus Sequence
The following sequence demonstrates how focus is transferred between windows to manage z-indices.
Component Interactions
Dock Integration
The Dock component uses the open function and the isOpen utility. It passes a defaultGeometry when opening an app for the first time.
Sources: features/desktop/components/Dock.tsx:11-30
Window Component Interaction
The Window component consumes the context to enable interactive features:
- Dragging: Calls
move(id, x, y)during pointer move events. - Resizing: Calls
resize(id, w, h)via a dedicated drag handle. - Header Controls: The "Close" and "Minimize" buttons trigger their respective context functions.
- Auto-Focus: Clicking anywhere on a window triggers
focus(id).
Sources: features/desktop/components/Window.tsx:31-55
Technical Implementation Details
The context is restricted to client-side usage via the "use client" directive and includes a safety hook to prevent usage outside of the provider.
// context/WindowManagerContext.tsx:55-63
export function useWindowManager(): WindowManagerValue {
const ctx = useContext(WindowManagerContext);
if (!ctx) {
throw new Error(
"useWindowManager must be used within WindowManagerProvider",
);
}
return ctx;
}
Constraints and Constraints
- Minimum Dimensions: Windows are constrained by
MIN_W(320px) andMIN_H(240px) during resize operations. - Boundary Detection: The drag logic in
Window.tsxprevents windows from being moved entirely off-screen, maintaining a minimum title bar visibility.
Sources: features/desktop/components/Window.tsx:11-45
Summary
The Window Manager Context Provider serves as the backbone of the desktop experience, synchronizing state between the Dock, the WindowLayer, and individual Window instances. By centralizing logic in a reducer, it provides a predictable and testable way to manage complex UI behaviors like window layering and single-instance application management.