reactdesk-core/README.md

A powerful React-based desktop environment library for creating Windows 11-like desktop interfaces with window management, taskbar, themes, and more

# ReactDesk

<div align="center">
  
  <img src="https://img.shields.io/badge/React-17%20%7C%2018-blue?style=for-the-badge&logo=react" alt="React Version" />
  <img src="https://img.shields.io/badge/TypeScript-5.4+-blue?style=for-the-badge&logo=typescript" alt="TypeScript" />
  <img src="https://img.shields.io/npm/v/@reactdesk/core?style=for-the-badge&color=red" alt="npm version" />
  <img src="https://img.shields.io/npm/l/@reactdesk/core?style=for-the-badge" alt="License" />
  <img src="https://img.shields.io/bundlephobia/minzip/@reactdesk/core?style=for-the-badge&color=green" alt="Bundle Size" />
  
  <h3>🖥️ A powerful React-based desktop environment library</h3>
  <p>Create stunning Windows 11 and macOS-like desktop interfaces with ease</p>
  
  [Demo](https://reactdesk.dev) • [Documentation](https://docs.reactdesk.dev) • [Examples](./example) • [Contributing](#contributing)
  
</div>

---

## ✨ Features

<table>
  <tr>
    <td>🪟 <b>Window Management</b></td>
    <td>Draggable, resizable, minimizable, maximizable windows with smooth animations</td>
  </tr>
  <tr>
    <td>🎨 <b>Theme Support</b></td>
    <td>Built-in Windows 11 and macOS themes with dark/light mode</td>
  </tr>
  <tr>
    <td>📱 <b>Responsive Design</b></td>
    <td>Adapts seamlessly to different screen sizes and orientations</td>
  </tr>
  <tr>
    <td>🎯 <b>Window Snapping</b></td>
    <td>7 different snap layouts for efficient window organization</td>
  </tr>
  <tr>
    <td>🖼️ <b>Taskbar & Dock</b></td>
    <td>Fully functional taskbar with window previews and app pinning</td>
  </tr>
  <tr>
    <td>⚡ <b>Performance</b></td>
    <td>Optimized rendering with React 18 features and code splitting</td>
  </tr>
  <tr>
    <td>🔧 <b>Customizable</b></td>
    <td>Extensive configuration options for appearance and behavior</td>
  </tr>
  <tr>
    <td>📦 <b>TypeScript</b></td>
    <td>Full TypeScript support with comprehensive type definitions</td>
  </tr>
</table>

## 🚀 Quick Start

### Installation

```bash
npm install @reactdesk/core
# or
yarn add @reactdesk/core
# or
pnpm add @reactdesk/core
```

### Basic Usage

```tsx
import React from 'react';
import { ReactDesk } from '@reactdesk/core';
import type { ReactDeskConfig } from '@reactdesk/core';

const config: ReactDeskConfig = {
  themeName: 'win11',
  applications: [
    {
      name: 'My App',
      icon: '📁',
      windowContent: () => <div>Hello World!</div>,
      windowConfig: {
        title: 'My Application',
        defaultSize: { width: 600, height: 400 }
      }
    }
  ]
};

function App() {
  return <ReactDesk {...config} />;
}

export default App;
```

## 📖 Documentation

### Configuration Options

#### Theme Configuration

```typescript
interface ThemeConfig {
  themeName?: 'win11' | 'macos';        // Desktop theme
  themeLayout?: 'win11' | 'macos';      // Layout style
  colorScheme?: 'light' | 'dark';       // Color scheme
  wallpaper?: string | React.ReactNode; // Background
}
```

#### Window Configuration

```typescript
interface WindowConfig {
  title?: string;                        // Window title
  icon?: string | React.ReactNode;       // Window icon
  defaultSize?: { width: number; height: number };
  initialRelativePosition?: { top?: number; left?: number; };
  allowResizing?: boolean;               // Enable resizing
  hideTitlebar?: boolean;               // Hide titlebar
  backgroundColor?: string;              // Window background
  maximized?: boolean;                  // Start maximized
  minimized?: boolean;                  // Start minimized
}
```

#### Application Definition

```typescript
interface Application {
  name: string;                          // App name
  icon?: string | React.ReactNode;       // App icon
  windowContent: React.FC;               // Window content
  windowConfig?: WindowConfig;           // Window settings
  taskbarPin?: boolean;                  // Pin to taskbar
  runOnStart?: boolean;                  // Auto-start
  singleton?: boolean;                   // Single instance
}
```

### Advanced Examples

#### Custom Wallpaper

```tsx
<ReactDesk 
  wallpaper="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
  // or use an image
  wallpaper="https://example.com/wallpaper.jpg"
  // or a React component
  wallpaper={<AnimatedBackground />}
/>
```

#### Multiple Windows

```tsx
const config: ReactDeskConfig = {
  initialState: {
    windows: [
      {
        Component: FileExplorer,
        title: 'File Explorer',
        defaultSize: { width: 800, height: 600 },
        initialRelativePosition: { top: 50, left: 50 }
      },
      {
        Component: Terminal,
        title: 'Terminal',
        defaultSize: { width: 600, height: 400 },
        initialRelativePosition: { top: 100, left: 100 }
      }
    ]
  }
};
```

#### Using Hooks

```tsx
import { useWindows, useProcesses, useSession } from '@reactdesk/core';

function MyComponent() {
  const { createWindow, closeWindow, maximize } = useWindows();
  const { createProcess } = useProcesses();
  const { foregroundId } = useSession();
  
  const openNewWindow = () => {
    const windowId = createWindow({
      Component: MyWindowContent,
      title: 'New Window',
      defaultSize: { width: 600, height: 400 }
    });
  };
  
  return <button onClick={openNewWindow}>Open Window</button>;
}
```

## 🎨 Themes

### Windows 11 Theme
- Fluent Design System
- Acrylic blur effects
- Smooth animations
- Snap layouts
- Start menu integration

### macOS Theme
- Apple Design Language
- Dock with magnification
- Mission Control view
- Native macOS controls
- Spotlight search

## 🏗️ Architecture

ReactDesk uses a modular architecture with context providers for state management:

```
ReactDesk
├── SignalProvider       # Event system
├── ViewportProvider     # Screen management
├── SessionProvider      # Session state
├── ProcessProvider      # Process management
├── WindowsProvider      # Window management
├── SyscallProvider      # System operations
├── ConfigProvider       # Configuration
├── ElementsProvider     # DOM references
└── MenuProvider         # Menu state
```

## 📊 Performance

- **Bundle Size**: ~200KB gzipped
- **Code Splitting**: Automatic chunking for optimal loading
- **Lazy Loading**: Components loaded on demand
- **Animations**: GPU-accelerated with Framer Motion
- **React 18**: Concurrent features for smooth interactions

## 🛠️ Development

### Prerequisites

- Node.js >= 16.0.0
- npm >= 7.0.0 or yarn >= 1.22.0

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/reactdesk.git
cd reactdesk

# Install dependencies
yarn install

# Start development server
yarn dev

# Build for production
yarn build

# Run tests
yarn test
```

### Project Structure

```
reactdesk/
├── lib/                  # Library source code
│   ├── components/       # React components
│   ├── contexts/         # Context providers
│   ├── hooks/           # Custom hooks
│   ├── styles/          # Themes and styles
│   ├── types/           # TypeScript types
│   └── utils/           # Utility functions
├── src/                  # Demo application
├── example/              # Example implementations
├── dist/                 # Build output
└── scripts/              # Build and utility scripts
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### How to Contribute

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by Windows 11 and macOS design systems
- Built with [React](https://reactjs.org/)
- Styled with [styled-components](https://styled-components.com/)
- Animations by [Framer Motion](https://www.framer.com/motion/)
- Window management with [react-rnd](https://github.com/bokuweb/react-rnd)

## 📊 Stats

![GitHub stars](https://img.shields.io/github/stars/yourusername/reactdesk?style=social)
![GitHub forks](https://img.shields.io/github/forks/yourusername/reactdesk?style=social)
![GitHub watchers](https://img.shields.io/github/watchers/yourusername/reactdesk?style=social)
![GitHub followers](https://img.shields.io/github/followers/yourusername?style=social)

## 🗺️ Roadmap

- [ ] Touch and mobile support
- [ ] Virtual desktop spaces
- [ ] File system integration
- [ ] Terminal emulator
- [ ] Notification system
- [ ] Context menus
- [ ] Keyboard shortcuts
- [ ] Accessibility improvements
- [ ] More themes (Ubuntu, KDE, etc.)
- [ ] Plugin system

## 💬 Community

- [Discord Server](https://discord.gg/reactdesk)
- [GitHub Discussions](https://github.com/yourusername/reactdesk/discussions)
- [Twitter](https://twitter.com/reactdesk)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/reactdesk)

## 📮 Support

- 🐛 [Report Bugs](https://github.com/yourusername/reactdesk/issues)
- 💡 [Request Features](https://github.com/yourusername/reactdesk/issues/new?template=feature_request.md)
- 📧 [Email Support](mailto:support@reactdesk.dev)
- 💰 [Sponsor on GitHub](https://github.com/sponsors/yourusername)

---

<div align="center">
  Made with ❤️ by the ReactDesk Team
  <br />
  <a href="https://reactdesk.dev">reactdesk.dev</a>
</div>