npm package: @oreqo/theme-lib
Description: Complete theme management system for React applications with dark mode, multiple theme variants, and extensive customization options
Author: Oreqo
Latest version: 1.0.3

# @oreqo/theme-lib

Complete theme management system for React applications with dark mode, multiple theme variants, and extensive customization options.

## Features

- 🌓 **Light/Dark Mode** - Seamless switching between light and dark themes
- 🎨 **Multiple Themes** - 3 dark theme variants and 1 light theme variant
- 🎯 **Color Schemes** - Purple, Green, Blue, and Dark Blue accent colors
- 📝 **Typography** - Customizable font family and text size
- 💾 **Auto Persistence** - Theme preferences automatically saved to localStorage
- ⚡ **Zero Configuration** - Works out of the box with sensible defaults
- 🔧 **Fully Customizable** - Fine-grained control over all theme aspects
- 📦 **Small Bundle Size** - Optimized for production use

## Installation

```bash
npm install @oreqo/theme-lib
```

or

```bash
yarn add @oreqo/theme-lib
```

## Quick Start

### 1. Wrap Your Application

Wrap your root component with `OreqoThemeProvider`:

```jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { OreqoThemeProvider } from '@oreqo/theme-lib';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')).render(
  <OreqoThemeProvider>
    <App />
  </OreqoThemeProvider>
);
```

### 2. Use Theme in Components

Access theme state and toggle functions:

```jsx
import { useOreqoTheme, toggleMode, setMatchedColor } from '@oreqo/theme-lib';

function MyComponent() {
  const { theme, mode } = useOreqoTheme();

  return (
    <div style={{
      backgroundColor: theme.background_color.content_area_background,
      color: theme.text_color.primary_text_color
    }}>
      <h1>Current Mode: {mode}</h1>
      <button onClick={toggleMode}>
        Switch to {mode === 'light' ? 'Dark' : 'Light'} Mode
      </button>
      <button onClick={() => setMatchedColor('blueColor')}>
        Change to Blue Theme
      </button>
    </div>
  );
}
```

## API Reference

### Components

#### `<OreqoThemeProvider>`

Main provider component that wraps your application.

**Props:**
- `children` (ReactNode) - Your application components
- `loading` (ReactNode, optional) - Loading component during rehydration

**Example:**
```jsx
<OreqoThemeProvider loading={<div>Loading theme...</div>}>
  <App />
</OreqoThemeProvider>
```

### Hooks

#### `useOreqoTheme()`

React hook to access theme state.

**Returns:**
- `theme` (Object) - Complete theme object with colors, shadows, fonts, etc.
- `colors` (Object) - Current color scheme
- `font` (string) - Current font family class
- `textSize` (string) - Current text size
- `mode` (string) - Current mode ('light' or 'dark')
- `selectedTheme` (string) - Current theme variant
- `layoutColor` (string) - Layout color (light mode only)
- `menuUIColor` (string) - Menu UI style
- `matchedColor` (string) - Accent color scheme
- `sidebarOrientation` (string) - Sidebar orientation

**Example:**
```jsx
const { theme, mode, colors } = useOreqoTheme();
```

### Action Functions

All action functions can be called directly without dispatch:

#### `toggleMode()`
Toggle between light and dark mode.

```jsx
import { toggleMode } from '@oreqo/theme-lib';

<button onClick={toggleMode}>Toggle Theme</button>
```

#### `setSelectedTheme(theme)`
Set theme variant (dark mode only: 'theme1', 'theme2', 'theme3').

```jsx
import { setSelectedTheme } from '@oreqo/theme-lib';

<button onClick={() => setSelectedTheme('theme2')}>Theme 2</button>
```

#### `setLayoutColor(color)`
Set layout color (light mode only: 'classic' or 'white').

```jsx
import { setLayoutColor } from '@oreqo/theme-lib';

<button onClick={() => setLayoutColor('white')}>White Layout</button>
```

#### `setMenuUIColor(style)`
Set menu UI style ('classic' or 'matched').

```jsx
import { setMenuUIColor } from '@oreqo/theme-lib';

<button onClick={() => setMenuUIColor('matched')}>Matched Menu</button>
```

#### `setMatchedColor(color)`
Set accent color ('purpleColor', 'greenColor', 'blueColor', 'darkBlueColor').

```jsx
import { setMatchedColor } from '@oreqo/theme-lib';

<button onClick={() => setMatchedColor('greenColor')}>Green Theme</button>
```

#### `setFont(font)`
Set font family ('font-inter' or 'font-public').

```jsx
import { setFont } from '@oreqo/theme-lib';

<button onClick={() => setFont('font-public')}>Public Sans</button>
```

#### `setTextSize(size)`
Set text size ('12px', '13px', '14px').

```jsx
import { setTextSize } from '@oreqo/theme-lib';

<button onClick={() => setTextSize('14px')}>Large Text</button>
```

#### `setSidebarOrientation(orientation)`
Set sidebar orientation ('vertical', 'horizontal', 'both').

```jsx
import { setSidebarOrientation } from '@oreqo/theme-lib';

<button onClick={() => setSidebarOrientation('horizontal')}>Horizontal</button>
```

#### `resetTheme()`
Reset all theme settings to defaults.

```jsx
import { resetTheme } from '@oreqo/theme-lib';

<button onClick={resetTheme}>Reset Theme</button>
```

## Complete Examples

### Dark Mode Toggle

```jsx
import { useOreqoTheme, toggleMode } from '@oreqo/theme-lib';

function DarkModeToggle() {
  const { mode } = useOreqoTheme();

  return (
    <button onClick={toggleMode}>
      {mode === 'light' ? '🌙 Dark Mode' : '☀️ Light Mode'}
    </button>
  );
}
```

### Color Scheme Selector

```jsx
import { useOreqoTheme, setMatchedColor } from '@oreqo/theme-lib';

function ColorPicker() {
  const { matchedColor, theme } = useOreqoTheme();

  const colors = [
    { name: 'Purple', value: 'purpleColor' },
    { name: 'Green', value: 'greenColor' },
    { name: 'Blue', value: 'blueColor' },
    { name: 'Dark Blue', value: 'darkBlueColor' }
  ];

  return (
    <div>
      {colors.map(color => (
        <button
          key={color.value}
          onClick={() => setMatchedColor(color.value)}
          style={{
            backgroundColor: matchedColor === color.value
              ? theme.primary_color
              : 'transparent',
            padding: '8px 16px',
            margin: '4px'
          }}
        >
          {color.name}
        </button>
      ))}
    </div>
  );
}
```

### Complete Settings Panel

```jsx
import {
  useOreqoTheme,
  toggleMode,
  setLayoutColor,
  setMenuUIColor,
  setMatchedColor,
  setFont,
  setTextSize
} from '@oreqo/theme-lib';

function ThemeSettings() {
  const {
    theme,
    mode,
    layoutColor,
    menuUIColor,
    matchedColor,
    font,
    textSize
  } = useOreqoTheme();

  return (
    <div style={{
      backgroundColor: theme.background_color.content_area_background,
      color: theme.text_color.primary_text_color,
      padding: '20px'
    }}>
      <h2>Theme Settings</h2>

      {/* Mode Toggle */}
      <div>
        <label>Theme Mode:</label>
        <button onClick={toggleMode}>
          {mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}
        </button>
      </div>

      {/* Layout (Light mode only) */}
      {mode === 'light' && (
        <div>
          <label>Layout:</label>
          <select
            value={layoutColor}
            onChange={(e) => setLayoutColor(e.target.value)}
          >
            <option value="classic">Classic</option>
            <option value="white">White</option>
          </select>
        </div>
      )}

      {/* Menu Style */}
      <div>
        <label>Menu Style:</label>
        <select
          value={menuUIColor}
          onChange={(e) => setMenuUIColor(e.target.value)}
        >
          <option value="classic">Classic</option>
          <option value="matched">Matched</option>
        </select>
      </div>

      {/* Accent Color */}
      <div>
        <label>Accent Color:</label>
        <select
          value={matchedColor}
          onChange={(e) => setMatchedColor(e.target.value)}
        >
          <option value="purpleColor">Purple</option>
          <option value="greenColor">Green</option>
          <option value="blueColor">Blue</option>
          <option value="darkBlueColor">Dark Blue</option>
        </select>
      </div>

      {/* Font */}
      <div>
        <label>Font:</label>
        <select
          value={font}
          onChange={(e) => setFont(e.target.value)}
        >
          <option value="font-inter">Inter</option>
          <option value="font-public">Public Sans</option>
        </select>
      </div>

      {/* Text Size */}
      <div>
        <label>Text Size:</label>
        <select
          value={textSize}
          onChange={(e) => setTextSize(e.target.value)}
        >
          <option value="12px">Small (12px)</option>
          <option value="13px">Medium (13px)</option>
          <option value="14px">Large (14px)</option>
        </select>
      </div>
    </div>
  );
}
```

## Theme Object Structure

The `theme` object contains comprehensive styling properties:

```javascript
{
  // Background Colors
  background_color: {
    content_area_background: string,
    sidebar_background: string,
    // ... more backgrounds
  },

  // Text Colors
  text_color: {
    primary_text_color: string,
    secondary_text_color: string,
    heading_text: string,
    // ... more text colors
  },

  // Border Colors
  border_color: {
    border_primary: string,
    border_secondary: string,
    // ... more borders
  },

  // Box Shadows
  boxShadow: {
    dropDown_shadow: string,
    modal_shadow: string,
    // ... more shadows
  },

  // Typography
  font: {
    fontSize: string,
    fontFamily: string
  },

  // Color Palette
  colors: {
    main_color: string,
    medium_color: string,
    background_color: string,
    // ... more colors
  }
}
```

## Advanced Usage

### Accessing Configuration Options

```jsx
import {
  matchedColorOptions,
  fontStyleOptions,
  THEME_MODES,
  COLOR_SCHEMES
} from '@oreqo/theme-lib';

// Available color options
console.log(matchedColorOptions);
// [{ label: 'Purple', id: 1, value: 'purpleColor' }, ...]

// Theme mode constants
console.log(THEME_MODES.LIGHT); // 'light'
console.log(THEME_MODES.DARK); // 'dark'
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Dependencies

- React 18+
- Redux Toolkit 2.0+
- React Redux 9.0+
- Redux Persist 6.0+

## License

MIT

## Contributing

Issues and pull requests are welcome! Please check out the [contribution guidelines](CONTRIBUTING.md).

## Support

For issues, questions, or suggestions, please [open an issue](https://github.com/your-org/oreqo-theme-system/issues).