@asafarim/react-themes 1.6.1 → 1.8.0-canary.2f6ab36.2

package/README.md

@@ -1,685 +1,685 @@
-# @asafarim/react-themes
-
-A comprehensive theme management system for React applications with automatic dark/light mode detection, custom theme creation, and smooth transitions.
-
-![npm version](https://img.shields.io/npm/v/@asafarim/react-themes)
-![license](https://img.shields.io/npm/l/@asafarim/react-themes)
-![typescript](https://img.shields.io/badge/TypeScript-Ready-blue)
-
-## 📸 Preview
-
-Experience the theme system in action with our **[Live Interactive Demo](https://alisafari-it.github.io/react-themes/)**
-
-### 🎯 Demo Showcases
-
-The live demo demonstrates all package capabilities:
-
-- **🎨 Theme Switching**: Real-time theme transitions between light, dark, and auto modes
-- **🔧 Component Gallery**: All built-in components (ThemeToggle, ThemeSelector) in action
-- **📱 Responsive Design**: How themes adapt across different screen sizes
-- **🎪 CSS Variables**: Live CSS variable updates and their effects
-- **⚡ Performance**: Smooth animations and transitions
-- **♿ Accessibility**: Keyboard navigation and screen reader support
-
-<table>
-  <tr>
-    <td align="center">
-      <img src="./src/react-themes-light.png" alt="Light Theme Preview" width="400"/>
-      <br/>
-      <em>Light Theme - Clean and Modern</em>
-    </td>
-    <td align="center">
-      <img src="./src/react-themes-dark.png" alt="Dark Theme Preview" width="400"/>
-      <br/>
-      <em>Dark Theme - Elegant and Eye-friendly</em>
-    </td>
-  </tr>
-</table>
-
-### 🚀 Try It Live
-
-Visit **[alisafari-it.github.io/react-themes](https://alisafari-it.github.io/react-themes)** to:
-
-1. **Interactive Testing**: Toggle between themes and see instant changes
-2. **Code Examples**: View implementation examples for each feature
-3. **Performance Metrics**: See how fast theme switching works
-4. **Integration Examples**: Real-world usage with other components
-5. **Customization Demo**: Examples of custom theme creation
-6. **Browser Compatibility**: Test across different browsers and devices
-
-## ✨ Features
-
-### 🌓 **Smart Theme Management**
-
-- **Auto Detection**: Automatically detects and follows system dark/light mode preferences
-- **Manual Override**: Users can manually select their preferred theme mode
-- **Persistence**: Remembers user choice across browser sessions using localStorage
-- **Real-time Updates**: Instantly responds to system theme changes
-
-### 🎨 **Advanced Theming System**
-
-- **Built-in Themes**: Professionally designed light and dark themes out of the box
-- **Custom Themes**: Create unlimited custom themes with full control over colors, spacing, and typography
-- **Theme Merging**: Easily extend existing themes with custom properties
-- **CSS Variables**: Automatic injection of CSS custom properties for seamless styling
-
-### ⚡ **Performance & User Experience**
-
-- **Smooth Transitions**: Beautiful, configurable transitions between theme changes
-- **Zero Flicker**: Prevents flash of unstyled content during theme initialization
-- **Lightweight**: Minimal bundle size impact (~8KB gzipped)
-- **Tree Shakeable**: Import only what you need
-
-### 🔧 **Developer Experience**
-
-- **TypeScript First**: Full TypeScript support with comprehensive type definitions
-- **React 18+ Ready**: Optimized for latest React features including concurrent rendering
-- **Hooks API**: Intuitive React hooks for theme management
-- **Component Library**: Pre-built, accessible components for common use cases
-
-### 🎯 **Integration & Compatibility**
-
-- **Framework Agnostic**: Works with any React-based framework (Next.js, Gatsby, CRA, Vite)
-- **CSS-in-JS Compatible**: Works with styled-components, emotion, and other CSS-in-JS libraries
-- **Tailwind Ready**: Seamlessly integrates with Tailwind CSS through CSS variables
-- **Server-Side Rendering**: Full SSR support with proper hydration handling
-
-### ♿ **Accessibility & Standards**
-
-- **WCAG Compliant**: Meets Web Content Accessibility Guidelines
-- **Keyboard Navigation**: Full keyboard support for all interactive elements
-- **Screen Reader Support**: Proper ARIA labels and announcements
-- **High Contrast**: Ensures sufficient color contrast ratios in all themes
-- **Reduced Motion**: Respects user's motion preferences
-
-## 📦 Installation
-
-```bash
-npm install @asafarim/react-themes
-# or
-yarn add @asafarim/react-themes
-# or
-pnpm add @asafarim/react-themes
-```
-
-## 🚀 Quick Start
-
-### 1. Wrap your app with ThemeProvider
-
-```tsx
-import React from 'react';
-import { ThemeProvider } from '@asafarim/react-themes';
-import '@asafarim/react-themes/styles.css'; // Optional base styles
-
-function App() {
-  return (
-    <ThemeProvider defaultMode="auto" persistMode={true}>
-      <YourAppContent />
-    </ThemeProvider>
-  );
-}
-```
-
-### 2. Use the theme in your components
-
-```tsx
-import React from 'react';
-import { useTheme, ThemeToggle } from '@asafarim/react-themes';
-
-function MyComponent() {
-  const { mode, currentTheme, toggleMode } = useTheme();
-
-  return (
-    <div>
-      <h1>Current mode: {mode}</h1>
-      <ThemeToggle />
-      {/* Your component content */}
-    </div>
-  );
-}
-```
-
-## 🎯 Use Cases & Examples
-
-### 📚 **Real-World Applications**
-
-Our **[Live Demo](https://bibliography.asafarim.com/react-themes/demo)** showcases these practical implementations:
-
-#### 🌐 **Web Applications**
-
-```tsx
-// E-commerce dashboard with theme switching
-import { ThemeProvider, ThemeToggle } from '@asafarim/react-themes';
-
-function EcommerceDashboard() {
-  return (
-    <ThemeProvider defaultMode="auto" persistMode={true}>
-      <header className="dashboard-header">
-        <h1>Sales Dashboard</h1>
-        <ThemeToggle size="sm" showLabels={true} />
-      </header>
-      <main className="dashboard-content">
-        {/* Dashboard content adapts automatically */}
-      </main>
-    </ThemeProvider>
-  );
-}
-```
-
-#### 📱 **Mobile-First Design**
-
-```css
-/* Responsive design that adapts to theme */
-.mobile-card {
-  background: var(--theme-color-background-secondary);
-  border: 1px solid var(--theme-color-border);
-  padding: var(--theme-spacing-md);
-  border-radius: var(--theme-radius-lg);
-  
-  /* Automatic dark mode styling */
-  box-shadow: var(--theme-shadow-sm);
-  transition: var(--theme-transition-normal);
-}
-```
-
-#### 🎨 **Design Systems**
-
-```tsx
-// Integration with component libraries
-import { Button, Card } from 'your-ui-library';
-import { useTheme } from '@asafarim/react-themes';
-
-function ThemedComponents() {
-  const { currentTheme } = useTheme();
-  
-  return (
-    <Card 
-      style={{ 
-        backgroundColor: currentTheme.colors.background,
-        color: currentTheme.colors.text 
-      }}
-    >
-      <Button variant={currentTheme.mode === 'dark' ? 'outlined' : 'filled'}>
-        Themed Button
-      </Button>
-    </Card>
-  );
-}
-```
-
-### 🔄 **Advanced Patterns**
-
-#### 🎪 **Dynamic Theme Loading**
-
-```tsx
-// Load themes dynamically based on user preferences
-import { createTheme, useTheme } from '@asafarim/react-themes';
-
-function DynamicThemeLoader() {
-  const { setTheme } = useTheme();
-  
-  const loadUserTheme = async (userId: string) => {
-    const userPrefs = await fetch(`/api/users/${userId}/theme`);
-    const themeData = await userPrefs.json();
-    
-    const customTheme = createTheme(themeData);
-    setTheme(customTheme);
-  };
-  
-  return <div>Loading personalized theme...</div>;
-}
-```
-
-#### 🏢 **Multi-Brand Applications**
-
-```tsx
-// Switch between different brand themes
-const brandThemes = {
-  corporate: createTheme(lightTheme, {
-    name: 'corporate',
-    colors: { primary: '#0066cc', secondary: '#004499' }
-  }),
-  creative: createTheme(darkTheme, {
-    name: 'creative', 
-    colors: { primary: '#ff6b6b', secondary: '#4ecdc4' }
-  })
-};
-
-<ThemeProvider customThemes={brandThemes}>
-  <BrandSwitcher />
-</ThemeProvider>
-```
-
-## 📖 API Reference
-
-### 🏗️ ThemeProvider
-
-The foundational component that manages theme state and applies CSS variables throughout your application.
-
-```tsx
-interface ThemeProviderProps {
-  children: ReactNode;
-  defaultMode?: 'light' | 'dark' | 'auto';
-  defaultTheme?: string;
-  persistMode?: boolean;
-  storageKey?: string;
-  customThemes?: Record<string, Theme>;
-  config?: ThemeConfig;
-}
-```
-
-**Essential Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | **required** | Child components to provide theme context to |
-| `defaultMode` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Initial theme mode on first load |
-| `defaultTheme` | `string` | `'default'` | Name of the default theme to use |
-| `persistMode` | `boolean` | `true` | Whether to save user's theme choice to localStorage |
-| `storageKey` | `string` | `'asafarim-theme-mode'` | localStorage key for persistence |
-| `customThemes` | `Record<string, Theme>` | `{}` | Additional themes to make available |
-
-**Advanced Configuration:**
-
-```tsx
-// Extended configuration options
-interface ThemeConfig {
-  transitionDuration?: string;
-  breakpoints?: Record<string, string>;
-  enableSystemTheme?: boolean;
-  cssVariablePrefix?: string;
-}
-
-<ThemeProvider 
-  config={{
-    transitionDuration: '200ms',
-    enableSystemTheme: true,
-    cssVariablePrefix: 'app-theme'
-  }}
->
-  <App />
-</ThemeProvider>
-```
-
-### 🪝 useTheme Hook
-
-The primary hook for accessing and controlling theme state.
-
-```tsx
-interface UseThemeReturn {
-  currentTheme: Theme;           // Currently active theme object
-  mode: ThemeMode;              // Current mode: 'light' | 'dark' | 'auto'
-  setMode: (mode: ThemeMode) => void;    // Change theme mode
-  setTheme: (theme: Theme) => void;      // Change active theme
-  themes: Record<string, Theme>; // All available themes
-  toggleMode: () => void;        // Cycle through light → dark → auto
-}
-```
-
-**Real-world Example:**
-
-```tsx
-function ThemeAwareComponent() {
-  const { currentTheme, mode, setMode, toggleMode } = useTheme();
-  
-  // Conditional styling based on theme
-  const isDarkMode = mode === 'dark' || 
-    (mode === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches);
-  
-  return (
-    <div style={{ 
-      backgroundColor: currentTheme.colors.background,
-      color: currentTheme.colors.text 
-    }}>
-      <h2>Current Theme: {currentTheme.name}</h2>
-      <p>Mode: {mode} {isDarkMode ? '🌙' : '☀️'}</p>
-      <button onClick={toggleMode}>Toggle Theme</button>
-    </div>
-  );
-}
-```
-
-### ⚡ useThemeToggle Hook
-
-Simplified hook specifically for theme mode toggling with additional utilities.
-
-```tsx
-interface UseThemeToggleReturn {
-  mode: ThemeMode;              // Current theme mode
-  setMode: (mode: ThemeMode) => void;    // Set specific mode
-  toggleMode: () => void;        // Cycle through modes
-  isDark: boolean;              // true if dark mode is active
-  isLight: boolean;             // true if light mode is active  
-  isAuto: boolean;              // true if auto mode is active
-  effectiveMode: 'light' | 'dark';  // Resolved mode (auto becomes light/dark)
-}
-```
-
-**Practical Usage:**
-
-```tsx
-function SmartThemeButton() {
-  const { mode, toggleMode, isDark, effectiveMode } = useThemeToggle();
-  
-  const getIcon = () => {
-    if (mode === 'auto') return '🌓';
-    return isDark ? '🌙' : '☀️';
-  };
-  
-  const getLabel = () => {
-    if (mode === 'auto') return `Auto (${effectiveMode})`;
-    return mode === 'dark' ? 'Dark Mode' : 'Light Mode';
-  };
-  
-  return (
-    <button onClick={toggleMode} title={getLabel()}>
-      {getIcon()} {getLabel()}
-    </button>
-  );
-}
-```
-
-### Components
-
-#### ThemeToggle
-
-A pre-built theme toggle button.
-
-```tsx
-<ThemeToggle 
-  size="md"           // 'sm' | 'md' | 'lg'
-  showLabels={false}  // Show text labels
-  className="custom-class"
-  style={{ margin: '10px' }}
-/>
-```
-
-#### ThemeSelector
-
-A dropdown selector for theme modes.
-
-```tsx
-<ThemeSelector 
-  showLabels={true}
-  className="custom-class"
-  options={[
-    { mode: 'light', label: 'Light', icon: '☀️' },
-    { mode: 'dark', label: 'Dark', icon: '🌙' },
-    { mode: 'auto', label: 'Auto', icon: '🌓' }
-  ]}
-/>
-```
-
-## 🎨 Custom Themes
-
-### Creating Custom Themes
-
-```tsx
-import { createTheme, lightTheme } from '@asafarim/react-themes';
-
-const myCustomTheme = createTheme(lightTheme, {
-  name: 'my-theme',
-  colors: {
-    primary: '#ff6b6b',
-    primaryHover: '#ff5252',
-    background: '#f8f9fa',
-    text: '#212529'
-  }
-});
-
-// Use with provider
-<ThemeProvider customThemes={{ 'my-theme': myCustomTheme }}>
-  <App />
-</ThemeProvider>
-```
-
-### Using CSS Variables
-
-The package automatically injects CSS variables that you can use in your styles:
-
-```css
-.my-component {
-  background-color: var(--theme-color-background);
-  color: var(--theme-color-text);
-  border: 1px solid var(--theme-color-border);
-  border-radius: var(--theme-radius-md);
-  padding: var(--theme-spacing-md);
-  transition: all var(--theme-transition-normal);
-}
-
-.my-button {
-  background-color: var(--theme-color-primary);
-  color: white;
-  font-size: var(--theme-font-size-sm);
-}
-
-.my-button:hover {
-  background-color: var(--theme-color-primary-hover);
-}
-```
-
-## 🎯 Integration with @asafarim/dd-menu
-
-This package works seamlessly with `@asafarim/dd-menu`:
-
-```tsx
-import { DDMenu } from '@asafarim/dd-menu';
-import { useTheme } from '@asafarim/react-themes';
-
-function NavMenu() {
-  const { mode } = useTheme();
-  
-  return (
-    <DDMenu 
-      items={menuItems}
-      theme={mode}  // Pass current theme mode
-      variant="navbar"
-    />
-  );
-}
-```
-
-## 🚀 Live Demo & Showcase
-
-### 🎭 **Interactive Demo**
-
-Experience all features at **[bibliography.asafarim.com/react-themes/demo](https://bibliography.asafarim.com/react-themes/demo)**
-
-The demo is a comprehensive showcase featuring:
-
-#### 🎨 **Theme Gallery**
-
-- **Light Theme**: Clean, modern interface with excellent readability
-- **Dark Theme**: Elegant dark mode optimized for low-light environments  
-- **Auto Mode**: Intelligent system preference detection with seamless switching
-- **Custom Themes**: Examples of brand-specific and specialized themes
-
-#### 🛠️ **Component Showcase**
-
-- **ThemeToggle Variants**: Different sizes, styles, and label configurations
-- **ThemeSelector**: Dropdown with icons, labels, and custom options
-- **Integration Examples**: Real components using theme variables
-- **Performance Metrics**: Live transition timing and smoothness demos
-
-#### 📊 **Technical Demonstrations**
-
-- **CSS Variables Live**: Watch variables update in real-time as themes change
-- **Browser Compatibility**: Cross-browser testing interface
-- **Accessibility Features**: Screen reader announcements and keyboard navigation
-- **Mobile Responsiveness**: Touch-optimized controls and layouts
-
-#### 🔧 **Developer Tools**
-
-- **Code Examples**: Copy-paste ready implementations
-- **Theme Inspector**: Live theme object visualization
-- **CSS Variable Explorer**: All available variables with current values
-- **Performance Monitor**: Bundle size and render time metrics
-
-### 📱 **Mobile-Optimized Experience**
-
-The demo is fully responsive and showcases:
-
-- Touch-friendly theme controls
-- Swipe gestures for theme switching  
-- Adaptive layouts for different screen sizes
-- Battery-conscious animations
-
-### 🎯 **Use Cases Demonstrated**
-
-1. **E-commerce Interface**: Product cards, navigation, and checkout flows
-2. **Dashboard Layout**: Charts, tables, and control panels
-3. **Content Management**: Text editors, media galleries, and forms
-4. **Social Platform**: Posts, comments, and user profiles
-5. **Documentation Site**: Code blocks, navigation, and search interfaces
-
-## 🔧 Advanced Usage
-
-### Custom Theme Structure
-
-```tsx
-interface Theme {
-  name: string;
-  mode: 'light' | 'dark' | 'auto';
-  colors: {
-    background: string;
-    backgroundSecondary: string;
-    text: string;
-    textSecondary: string;
-    primary: string;
-    primaryHover: string;
-    border: string;
-    // ... more colors
-  };
-  spacing: {
-    xs: string;
-    sm: string;
-    md: string;
-    lg: string;
-    // ... more spacing
-  };
-  // ... typography, radius, transitions, zIndex
-}
-```
-
-### Programmatic Theme Application
-
-```tsx
-import { applyTheme } from '@asafarim/react-themes';
-
-// Apply theme manually
-applyTheme(customTheme, 'dark');
-```
-
-## 🌍 Browser Support
-
-- Modern browsers with CSS custom properties support
-- Chrome 49+
-- Firefox 31+
-- Safari 9.1+
-- Edge 16+
-
-## 🤝 Contributing
-
-We welcome contributions! The project is open source and actively maintained.
-
-### 🛠️ **Development Setup**
-
-```bash
-git clone https://github.com/AliSafari-IT/asafarim
-cd ASafariM.Clients/packages/react-themes
-pnpm install
-pnpm build
-pnpm test
-```
-
-### 🧪 **Testing the Demo**
-
-```bash
-# Run the demo locally
-cd ../../asafarim-bibliography
-pnpm install
-pnpm start
-# Visit http://localhost:3004/react-themes/demo
-```
-
-### 📋 **Contribution Guidelines**
-
-- Follow TypeScript best practices
-- Add tests for new features
-- Update documentation and examples
-- Ensure accessibility compliance
-- Test across different browsers
-
-## 📄 License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🌟 **Why Choose @asafarim/react-themes?**
-
-### ✅ **Production Ready**
-
-- Used in production at [ASafariM Bibliography](https://bibliography.asafarim.com)
-- Thoroughly tested across browsers and devices
-- Optimized for performance and accessibility
-- Regular updates and maintenance
-
-### 🎯 **Developer Focused**
-
-- Extensive TypeScript support
-- Comprehensive documentation with live examples
-- Active community support
-- Regular feature updates based on user feedback
-
-### 🚀 **Modern Standards**
-
-- React 18+ optimized
-- CSS3 custom properties
-- ES2020+ JavaScript features
-- Modern bundling and tree-shaking support
-
-## 🔗 Related Packages & Ecosystem
-
-- **[`@asafarim/dd-menu`](https://www.npmjs.com/package/@asafarim/dd-menu)** - Elegant dropdown menu component with theme integration
-- **[ASafariM Bibliography](https://bibliography.asafarim.com)** - Live application showcasing the theme system
-- **[Interactive Demo](https://bibliography.asafarim.com/react-themes/demo)** - Comprehensive feature demonstration
-
-## � Project Stats
-
-- 🏗️ **Built with**: TypeScript, React 18, CSS3 Custom Properties
-- 📦 **Bundle Size**: ~8KB gzipped
-- 🌍 **Browser Support**: Modern browsers (Chrome 49+, Firefox 31+, Safari 9.1+, Edge 16+)
-- ⚡ **Performance**: Zero-flicker theme switching, optimized re-renders
-- ♿ **Accessibility**: WCAG 2.1 AA compliant
-
-## �📝 Changelog
-
-### 🎉 **v1.1.0** - Latest
-
-- Enhanced TypeScript definitions
-- Improved performance and bundle size
-- Added comprehensive demo showcase
-- Extended browser compatibility
-- New theme customization options
-
-### 🚀 **v1.0.0** - Initial Release  
-
-- Core theme provider functionality
-- Auto mode detection with system preference sync
-- CSS variable injection system
-- Built-in components (ThemeToggle, ThemeSelector)
-- TypeScript support with full type safety
-- localStorage persistence with customizable keys
-
----
-
-<div align="center">
-
-### 🌟 **Experience the Future of React Theming**
-
-**[Try the Live Demo](https://alisafari-it.github.io/react-themes)** | **[View Documentation](https://www.npmjs.com/package/@asafarim/react-themes)** | **[See Source Code](https://github.com/AliSafari-IT/react-themes)**
-
-Made with ❤️ and ☕ by **[ASafariM](https://asafarim.com)**
-
-*Empowering developers to create beautiful, accessible, and user-friendly themed applications*
-
-</div>
+# @asafarim/react-themes
+
+A comprehensive theme management system for React applications with automatic dark/light mode detection, custom theme creation, and smooth transitions.
+
+![npm version](https://img.shields.io/npm/v/@asafarim/react-themes)
+![license](https://img.shields.io/npm/l/@asafarim/react-themes)
+![typescript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+## 📸 Preview
+
+Experience the theme system in action with our **[Live Interactive Demo](https://alisafari-it.github.io/react-themes/)**
+
+### 🎯 Demo Showcases
+
+The live demo demonstrates all package capabilities:
+
+- **🎨 Theme Switching**: Real-time theme transitions between light, dark, and auto modes
+- **🔧 Component Gallery**: All built-in components (ThemeToggle, ThemeSelector) in action
+- **📱 Responsive Design**: How themes adapt across different screen sizes
+- **🎪 CSS Variables**: Live CSS variable updates and their effects
+- **⚡ Performance**: Smooth animations and transitions
+- **♿ Accessibility**: Keyboard navigation and screen reader support
+
+<table>
+  <tr>
+    <td align="center">
+      <img src="./src/react-themes-light.png" alt="Light Theme Preview" width="400"/>
+      <br/>
+      <em>Light Theme - Clean and Modern</em>
+    </td>
+    <td align="center">
+      <img src="./src/react-themes-dark.png" alt="Dark Theme Preview" width="400"/>
+      <br/>
+      <em>Dark Theme - Elegant and Eye-friendly</em>
+    </td>
+  </tr>
+</table>
+
+### 🚀 Try It Live
+
+Visit **[alisafari-it.github.io/react-themes](https://alisafari-it.github.io/react-themes)** to:
+
+1. **Interactive Testing**: Toggle between themes and see instant changes
+2. **Code Examples**: View implementation examples for each feature
+3. **Performance Metrics**: See how fast theme switching works
+4. **Integration Examples**: Real-world usage with other components
+5. **Customization Demo**: Examples of custom theme creation
+6. **Browser Compatibility**: Test across different browsers and devices
+
+## ✨ Features
+
+### 🌓 **Smart Theme Management**
+
+- **Auto Detection**: Automatically detects and follows system dark/light mode preferences
+- **Manual Override**: Users can manually select their preferred theme mode
+- **Persistence**: Remembers user choice across browser sessions using localStorage
+- **Real-time Updates**: Instantly responds to system theme changes
+
+### 🎨 **Advanced Theming System**
+
+- **Built-in Themes**: Professionally designed light and dark themes out of the box
+- **Custom Themes**: Create unlimited custom themes with full control over colors, spacing, and typography
+- **Theme Merging**: Easily extend existing themes with custom properties
+- **CSS Variables**: Automatic injection of CSS custom properties for seamless styling
+
+### ⚡ **Performance & User Experience**
+
+- **Smooth Transitions**: Beautiful, configurable transitions between theme changes
+- **Zero Flicker**: Prevents flash of unstyled content during theme initialization
+- **Lightweight**: Minimal bundle size impact (~8KB gzipped)
+- **Tree Shakeable**: Import only what you need
+
+### 🔧 **Developer Experience**
+
+- **TypeScript First**: Full TypeScript support with comprehensive type definitions
+- **React 18+ Ready**: Optimized for latest React features including concurrent rendering
+- **Hooks API**: Intuitive React hooks for theme management
+- **Component Library**: Pre-built, accessible components for common use cases
+
+### 🎯 **Integration & Compatibility**
+
+- **Framework Agnostic**: Works with any React-based framework (Next.js, Gatsby, CRA, Vite)
+- **CSS-in-JS Compatible**: Works with styled-components, emotion, and other CSS-in-JS libraries
+- **Tailwind Ready**: Seamlessly integrates with Tailwind CSS through CSS variables
+- **Server-Side Rendering**: Full SSR support with proper hydration handling
+
+### ♿ **Accessibility & Standards**
+
+- **WCAG Compliant**: Meets Web Content Accessibility Guidelines
+- **Keyboard Navigation**: Full keyboard support for all interactive elements
+- **Screen Reader Support**: Proper ARIA labels and announcements
+- **High Contrast**: Ensures sufficient color contrast ratios in all themes
+- **Reduced Motion**: Respects user's motion preferences
+
+## 📦 Installation
+
+```bash
+npm install @asafarim/react-themes
+# or
+yarn add @asafarim/react-themes
+# or
+pnpm add @asafarim/react-themes
+```
+
+## 🚀 Quick Start
+
+### 1. Wrap your app with ThemeProvider
+
+```tsx
+import React from 'react';
+import { ThemeProvider } from '@asafarim/react-themes';
+import '@asafarim/react-themes/styles.css'; // Optional base styles
+
+function App() {
+  return (
+    <ThemeProvider defaultMode="auto" persistMode={true}>
+      <YourAppContent />
+    </ThemeProvider>
+  );
+}
+```
+
+### 2. Use the theme in your components
+
+```tsx
+import React from 'react';
+import { useTheme, ThemeToggle } from '@asafarim/react-themes';
+
+function MyComponent() {
+  const { mode, currentTheme, toggleMode } = useTheme();
+
+  return (
+    <div>
+      <h1>Current mode: {mode}</h1>
+      <ThemeToggle />
+      {/* Your component content */}
+    </div>
+  );
+}
+```
+
+## 🎯 Use Cases & Examples
+
+### 📚 **Real-World Applications**
+
+Our **[Live Demo](https://bibliography.asafarim.com/react-themes/demo)** showcases these practical implementations:
+
+#### 🌐 **Web Applications**
+
+```tsx
+// E-commerce dashboard with theme switching
+import { ThemeProvider, ThemeToggle } from '@asafarim/react-themes';
+
+function EcommerceDashboard() {
+  return (
+    <ThemeProvider defaultMode="auto" persistMode={true}>
+      <header className="dashboard-header">
+        <h1>Sales Dashboard</h1>
+        <ThemeToggle size="sm" showLabels={true} />
+      </header>
+      <main className="dashboard-content">
+        {/* Dashboard content adapts automatically */}
+      </main>
+    </ThemeProvider>
+  );
+}
+```
+
+#### 📱 **Mobile-First Design**
+
+```css
+/* Responsive design that adapts to theme */
+.mobile-card {
+  background: var(--theme-color-background-secondary);
+  border: 1px solid var(--theme-color-border);
+  padding: var(--theme-spacing-md);
+  border-radius: var(--theme-radius-lg);
+  
+  /* Automatic dark mode styling */
+  box-shadow: var(--theme-shadow-sm);
+  transition: var(--theme-transition-normal);
+}
+```
+
+#### 🎨 **Design Systems**
+
+```tsx
+// Integration with component libraries
+import { Button, Card } from 'your-ui-library';
+import { useTheme } from '@asafarim/react-themes';
+
+function ThemedComponents() {
+  const { currentTheme } = useTheme();
+  
+  return (
+    <Card 
+      style={{ 
+        backgroundColor: currentTheme.colors.background,
+        color: currentTheme.colors.text 
+      }}
+    >
+      <Button variant={currentTheme.mode === 'dark' ? 'outlined' : 'filled'}>
+        Themed Button
+      </Button>
+    </Card>
+  );
+}
+```
+
+### 🔄 **Advanced Patterns**
+
+#### 🎪 **Dynamic Theme Loading**
+
+```tsx
+// Load themes dynamically based on user preferences
+import { createTheme, useTheme } from '@asafarim/react-themes';
+
+function DynamicThemeLoader() {
+  const { setTheme } = useTheme();
+  
+  const loadUserTheme = async (userId: string) => {
+    const userPrefs = await fetch(`/api/users/${userId}/theme`);
+    const themeData = await userPrefs.json();
+    
+    const customTheme = createTheme(themeData);
+    setTheme(customTheme);
+  };
+  
+  return <div>Loading personalized theme...</div>;
+}
+```
+
+#### 🏢 **Multi-Brand Applications**
+
+```tsx
+// Switch between different brand themes
+const brandThemes = {
+  corporate: createTheme(lightTheme, {
+    name: 'corporate',
+    colors: { primary: '#0066cc', secondary: '#004499' }
+  }),
+  creative: createTheme(darkTheme, {
+    name: 'creative', 
+    colors: { primary: '#ff6b6b', secondary: '#4ecdc4' }
+  })
+};
+
+<ThemeProvider customThemes={brandThemes}>
+  <BrandSwitcher />
+</ThemeProvider>
+```
+
+## 📖 API Reference
+
+### 🏗️ ThemeProvider
+
+The foundational component that manages theme state and applies CSS variables throughout your application.
+
+```tsx
+interface ThemeProviderProps {
+  children: ReactNode;
+  defaultMode?: 'light' | 'dark' | 'auto';
+  defaultTheme?: string;
+  persistMode?: boolean;
+  storageKey?: string;
+  customThemes?: Record<string, Theme>;
+  config?: ThemeConfig;
+}
+```
+
+**Essential Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | **required** | Child components to provide theme context to |
+| `defaultMode` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Initial theme mode on first load |
+| `defaultTheme` | `string` | `'default'` | Name of the default theme to use |
+| `persistMode` | `boolean` | `true` | Whether to save user's theme choice to localStorage |
+| `storageKey` | `string` | `'asafarim-theme-mode'` | localStorage key for persistence |
+| `customThemes` | `Record<string, Theme>` | `{}` | Additional themes to make available |
+
+**Advanced Configuration:**
+
+```tsx
+// Extended configuration options
+interface ThemeConfig {
+  transitionDuration?: string;
+  breakpoints?: Record<string, string>;
+  enableSystemTheme?: boolean;
+  cssVariablePrefix?: string;
+}
+
+<ThemeProvider 
+  config={{
+    transitionDuration: '200ms',
+    enableSystemTheme: true,
+    cssVariablePrefix: 'app-theme'
+  }}
+>
+  <App />
+</ThemeProvider>
+```
+
+### 🪝 useTheme Hook
+
+The primary hook for accessing and controlling theme state.
+
+```tsx
+interface UseThemeReturn {
+  currentTheme: Theme;           // Currently active theme object
+  mode: ThemeMode;              // Current mode: 'light' | 'dark' | 'auto'
+  setMode: (mode: ThemeMode) => void;    // Change theme mode
+  setTheme: (theme: Theme) => void;      // Change active theme
+  themes: Record<string, Theme>; // All available themes
+  toggleMode: () => void;        // Cycle through light → dark → auto
+}
+```
+
+**Real-world Example:**
+
+```tsx
+function ThemeAwareComponent() {
+  const { currentTheme, mode, setMode, toggleMode } = useTheme();
+  
+  // Conditional styling based on theme
+  const isDarkMode = mode === 'dark' || 
+    (mode === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+  
+  return (
+    <div style={{ 
+      backgroundColor: currentTheme.colors.background,
+      color: currentTheme.colors.text 
+    }}>
+      <h2>Current Theme: {currentTheme.name}</h2>
+      <p>Mode: {mode} {isDarkMode ? '🌙' : '☀️'}</p>
+      <button onClick={toggleMode}>Toggle Theme</button>
+    </div>
+  );
+}
+```
+
+### ⚡ useThemeToggle Hook
+
+Simplified hook specifically for theme mode toggling with additional utilities.
+
+```tsx
+interface UseThemeToggleReturn {
+  mode: ThemeMode;              // Current theme mode
+  setMode: (mode: ThemeMode) => void;    // Set specific mode
+  toggleMode: () => void;        // Cycle through modes
+  isDark: boolean;              // true if dark mode is active
+  isLight: boolean;             // true if light mode is active  
+  isAuto: boolean;              // true if auto mode is active
+  effectiveMode: 'light' | 'dark';  // Resolved mode (auto becomes light/dark)
+}
+```
+
+**Practical Usage:**
+
+```tsx
+function SmartThemeButton() {
+  const { mode, toggleMode, isDark, effectiveMode } = useThemeToggle();
+  
+  const getIcon = () => {
+    if (mode === 'auto') return '🌓';
+    return isDark ? '🌙' : '☀️';
+  };
+  
+  const getLabel = () => {
+    if (mode === 'auto') return `Auto (${effectiveMode})`;
+    return mode === 'dark' ? 'Dark Mode' : 'Light Mode';
+  };
+  
+  return (
+    <button onClick={toggleMode} title={getLabel()}>
+      {getIcon()} {getLabel()}
+    </button>
+  );
+}
+```
+
+### Components
+
+#### ThemeToggle
+
+A pre-built theme toggle button.
+
+```tsx
+<ThemeToggle 
+  size="md"           // 'sm' | 'md' | 'lg'
+  showLabels={false}  // Show text labels
+  className="custom-class"
+  style={{ margin: '10px' }}
+/>
+```
+
+#### ThemeSelector
+
+A dropdown selector for theme modes.
+
+```tsx
+<ThemeSelector 
+  showLabels={true}
+  className="custom-class"
+  options={[
+    { mode: 'light', label: 'Light', icon: '☀️' },
+    { mode: 'dark', label: 'Dark', icon: '🌙' },
+    { mode: 'auto', label: 'Auto', icon: '🌓' }
+  ]}
+/>
+```
+
+## 🎨 Custom Themes
+
+### Creating Custom Themes
+
+```tsx
+import { createTheme, lightTheme } from '@asafarim/react-themes';
+
+const myCustomTheme = createTheme(lightTheme, {
+  name: 'my-theme',
+  colors: {
+    primary: '#ff6b6b',
+    primaryHover: '#ff5252',
+    background: '#f8f9fa',
+    text: '#212529'
+  }
+});
+
+// Use with provider
+<ThemeProvider customThemes={{ 'my-theme': myCustomTheme }}>
+  <App />
+</ThemeProvider>
+```
+
+### Using CSS Variables
+
+The package automatically injects CSS variables that you can use in your styles:
+
+```css
+.my-component {
+  background-color: var(--theme-color-background);
+  color: var(--theme-color-text);
+  border: 1px solid var(--theme-color-border);
+  border-radius: var(--theme-radius-md);
+  padding: var(--theme-spacing-md);
+  transition: all var(--theme-transition-normal);
+}
+
+.my-button {
+  background-color: var(--theme-color-primary);
+  color: white;
+  font-size: var(--theme-font-size-sm);
+}
+
+.my-button:hover {
+  background-color: var(--theme-color-primary-hover);
+}
+```
+
+## 🎯 Integration with @asafarim/dd-menu
+
+This package works seamlessly with `@asafarim/dd-menu`:
+
+```tsx
+import { DDMenu } from '@asafarim/dd-menu';
+import { useTheme } from '@asafarim/react-themes';
+
+function NavMenu() {
+  const { mode } = useTheme();
+  
+  return (
+    <DDMenu 
+      items={menuItems}
+      theme={mode}  // Pass current theme mode
+      variant="navbar"
+    />
+  );
+}
+```
+
+## 🚀 Live Demo & Showcase
+
+### 🎭 **Interactive Demo**
+
+Experience all features at **[bibliography.asafarim.com/react-themes/demo](https://bibliography.asafarim.com/react-themes/demo)**
+
+The demo is a comprehensive showcase featuring:
+
+#### 🎨 **Theme Gallery**
+
+- **Light Theme**: Clean, modern interface with excellent readability
+- **Dark Theme**: Elegant dark mode optimized for low-light environments  
+- **Auto Mode**: Intelligent system preference detection with seamless switching
+- **Custom Themes**: Examples of brand-specific and specialized themes
+
+#### 🛠️ **Component Showcase**
+
+- **ThemeToggle Variants**: Different sizes, styles, and label configurations
+- **ThemeSelector**: Dropdown with icons, labels, and custom options
+- **Integration Examples**: Real components using theme variables
+- **Performance Metrics**: Live transition timing and smoothness demos
+
+#### 📊 **Technical Demonstrations**
+
+- **CSS Variables Live**: Watch variables update in real-time as themes change
+- **Browser Compatibility**: Cross-browser testing interface
+- **Accessibility Features**: Screen reader announcements and keyboard navigation
+- **Mobile Responsiveness**: Touch-optimized controls and layouts
+
+#### 🔧 **Developer Tools**
+
+- **Code Examples**: Copy-paste ready implementations
+- **Theme Inspector**: Live theme object visualization
+- **CSS Variable Explorer**: All available variables with current values
+- **Performance Monitor**: Bundle size and render time metrics
+
+### 📱 **Mobile-Optimized Experience**
+
+The demo is fully responsive and showcases:
+
+- Touch-friendly theme controls
+- Swipe gestures for theme switching  
+- Adaptive layouts for different screen sizes
+- Battery-conscious animations
+
+### 🎯 **Use Cases Demonstrated**
+
+1. **E-commerce Interface**: Product cards, navigation, and checkout flows
+2. **Dashboard Layout**: Charts, tables, and control panels
+3. **Content Management**: Text editors, media galleries, and forms
+4. **Social Platform**: Posts, comments, and user profiles
+5. **Documentation Site**: Code blocks, navigation, and search interfaces
+
+## 🔧 Advanced Usage
+
+### Custom Theme Structure
+
+```tsx
+interface Theme {
+  name: string;
+  mode: 'light' | 'dark' | 'auto';
+  colors: {
+    background: string;
+    backgroundSecondary: string;
+    text: string;
+    textSecondary: string;
+    primary: string;
+    primaryHover: string;
+    border: string;
+    // ... more colors
+  };
+  spacing: {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    // ... more spacing
+  };
+  // ... typography, radius, transitions, zIndex
+}
+```
+
+### Programmatic Theme Application
+
+```tsx
+import { applyTheme } from '@asafarim/react-themes';
+
+// Apply theme manually
+applyTheme(customTheme, 'dark');
+```
+
+## 🌍 Browser Support
+
+- Modern browsers with CSS custom properties support
+- Chrome 49+
+- Firefox 31+
+- Safari 9.1+
+- Edge 16+
+
+## 🤝 Contributing
+
+We welcome contributions! The project is open source and actively maintained.
+
+### 🛠️ **Development Setup**
+
+```bash
+git clone https://github.com/AliSafari-IT/asafarim
+cd ASafariM.Clients/packages/react-themes
+pnpm install
+pnpm build
+pnpm test
+```
+
+### 🧪 **Testing the Demo**
+
+```bash
+# Run the demo locally
+cd ../../asafarim-bibliography
+pnpm install
+pnpm start
+# Visit http://localhost:3004/react-themes/demo
+```
+
+### 📋 **Contribution Guidelines**
+
+- Follow TypeScript best practices
+- Add tests for new features
+- Update documentation and examples
+- Ensure accessibility compliance
+- Test across different browsers
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🌟 **Why Choose @asafarim/react-themes?**
+
+### ✅ **Production Ready**
+
+- Used in production at [ASafariM Bibliography](https://bibliography.asafarim.com)
+- Thoroughly tested across browsers and devices
+- Optimized for performance and accessibility
+- Regular updates and maintenance
+
+### 🎯 **Developer Focused**
+
+- Extensive TypeScript support
+- Comprehensive documentation with live examples
+- Active community support
+- Regular feature updates based on user feedback
+
+### 🚀 **Modern Standards**
+
+- React 18+ optimized
+- CSS3 custom properties
+- ES2020+ JavaScript features
+- Modern bundling and tree-shaking support
+
+## 🔗 Related Packages & Ecosystem
+
+- **[`@asafarim/dd-menu`](https://www.npmjs.com/package/@asafarim/dd-menu)** - Elegant dropdown menu component with theme integration
+- **[ASafariM Bibliography](https://bibliography.asafarim.com)** - Live application showcasing the theme system
+- **[Interactive Demo](https://bibliography.asafarim.com/react-themes/demo)** - Comprehensive feature demonstration
+
+## � Project Stats
+
+- 🏗️ **Built with**: TypeScript, React 18, CSS3 Custom Properties
+- 📦 **Bundle Size**: ~8KB gzipped
+- 🌍 **Browser Support**: Modern browsers (Chrome 49+, Firefox 31+, Safari 9.1+, Edge 16+)
+- ⚡ **Performance**: Zero-flicker theme switching, optimized re-renders
+- ♿ **Accessibility**: WCAG 2.1 AA compliant
+
+## �📝 Changelog
+
+### 🎉 **v1.1.0** - Latest
+
+- Enhanced TypeScript definitions
+- Improved performance and bundle size
+- Added comprehensive demo showcase
+- Extended browser compatibility
+- New theme customization options
+
+### 🚀 **v1.0.0** - Initial Release  
+
+- Core theme provider functionality
+- Auto mode detection with system preference sync
+- CSS variable injection system
+- Built-in components (ThemeToggle, ThemeSelector)
+- TypeScript support with full type safety
+- localStorage persistence with customizable keys
+
+---
+
+<div align="center">
+
+### 🌟 **Experience the Future of React Theming**
+
+**[Try the Live Demo](https://alisafari-it.github.io/react-themes)** | **[View Documentation](https://www.npmjs.com/package/@asafarim/react-themes)** | **[See Source Code](https://github.com/AliSafari-IT/react-themes)**
+
+Made with ❤️ and ☕ by **[ASafariM](https://asafarim.com)**
+
+*Empowering developers to create beautiful, accessible, and user-friendly themed applications*
+
+</div>