@qwickapps/react-framework 1.3.0

package/src/__tests__/contexts/ThemeContext.test.js

@@ -0,0 +1,123 @@
+/**
+ * ThemeContext Tests
+ * Tests for theme management functionality
+ */
+
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { ThemeProvider, useTheme } from '../../contexts/ThemeContext';
+
+// Test component that uses the theme context
+const TestComponent = () => {
+  const { currentTheme, actualThemeMode, setPreferredTheme } = useTheme();
+  
+  return (
+    <div>
+      <span data-testid="theme-mode">{currentTheme}</span>
+      <span data-testid="actual-theme-mode">{actualThemeMode}</span>
+      <button onClick={() => setPreferredTheme('dark')}>Switch to Dark</button>
+      <button onClick={() => setPreferredTheme('light')}>Switch to Light</button>
+      <button onClick={() => setPreferredTheme('system')}>Switch to System</button>
+    </div>
+  );
+};
+
+const renderWithThemeProvider = (component) => {
+  return render(<ThemeProvider>{component}</ThemeProvider>);
+};
+
+describe('ThemeContext', () => {
+  beforeEach(() => {
+    // Reset document.documentElement mock
+    document.documentElement.setAttribute.mockClear();
+    document.documentElement.getAttribute.mockReturnValue(null);
+    
+    // Reset localStorage mocks 
+    localStorage.getItem.mockClear();
+    localStorage.setItem.mockClear();
+    
+    // Restore window.matchMedia mock
+    window.matchMedia = jest.fn().mockImplementation(query => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+  });
+
+  test('provides default theme mode as light', () => {
+    renderWithThemeProvider(<TestComponent />);
+    
+    expect(screen.getByTestId('theme-mode')).toHaveTextContent('light');
+  });
+
+  test('switches theme mode correctly', async () => {
+    renderWithThemeProvider(<TestComponent />);
+    
+    const darkButton = screen.getByText('Switch to Dark');
+    fireEvent.click(darkButton);
+    
+    await waitFor(() => {
+      expect(screen.getByTestId('theme-mode')).toHaveTextContent('dark');
+    });
+  });
+
+  test('persists theme preference to localStorage', () => {
+    renderWithThemeProvider(<TestComponent />);
+    
+    const lightButton = screen.getByText('Switch to Light');
+    fireEvent.click(lightButton);
+    
+    expect(localStorage.setItem).toHaveBeenCalledWith('qwickapps-react-framework-theme', 'light');
+  });
+
+  test('loads theme from localStorage on initialization', () => {
+    localStorage.getItem.mockImplementation(() => 'dark');
+    
+    renderWithThemeProvider(<TestComponent />);
+    
+    expect(screen.getByTestId('theme-mode')).toHaveTextContent('dark');
+  });
+
+  test('resolves system theme mode correctly', () => {
+    // Mock system preference as dark
+    window.matchMedia.mockImplementation(query => ({
+      matches: query === '(prefers-color-scheme: dark)',
+      media: query,
+      onchange: null,
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+
+    renderWithThemeProvider(<TestComponent />);
+    
+    expect(screen.getByTestId('actual-theme-mode')).toHaveTextContent('dark');
+  });
+
+  test('updates theme mode when theme changes', () => {
+    renderWithThemeProvider(<TestComponent />);
+    
+    const darkButton = screen.getByText('Switch to Dark');
+    fireEvent.click(darkButton);
+    
+    expect(screen.getByTestId('theme-mode')).toHaveTextContent('dark');
+  });
+
+  test('throws error when useTheme is used outside ThemeProvider', () => {
+    // Suppress console.error for this test
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    
+    expect(() => {
+      render(<TestComponent />);
+    }).toThrow('useTheme must be used within a ThemeProvider');
+    
+    consoleSpy.mockRestore();
+  });
+});

package/src/__tests__/utils/paletteUtils.test.js

@@ -0,0 +1,142 @@
+/**
+ * Palette Utilities Tests
+ * Tests for palette utility functions
+ */
+
+import {
+  AVAILABLE_PALETTES,
+  getCurrentPalette,
+  setPalette,
+  getPaletteName,
+  initializePalette,
+  savePalettePreference,
+  getCSSVariable,
+  setCSSVariable
+} from '../../utils/paletteUtils';
+
+describe('Palette Utilities', () => {
+  beforeEach(() => {
+    // Reset document mock
+    document.documentElement.getAttribute.mockReturnValue(null);
+    document.documentElement.setAttribute.mockClear();
+    
+    // Clear all mocks
+    jest.clearAllMocks();
+    document.documentElement.setAttribute.mockClear();
+  });
+
+  describe('AVAILABLE_PALETTES', () => {
+    test('contains all expected palettes', () => {
+      expect(AVAILABLE_PALETTES).toHaveLength(5);
+      
+      const paletteIds = AVAILABLE_PALETTES.map(p => p.id);
+      expect(paletteIds).toContain('default');
+      expect(paletteIds).toContain('winter');
+      expect(paletteIds).toContain('autumn');
+      expect(paletteIds).toContain('spring');
+      expect(paletteIds).toContain('ocean');
+    });
+
+    test('has proper structure for each palette', () => {
+      AVAILABLE_PALETTES.forEach(palette => {
+        expect(palette).toHaveProperty('id');
+        expect(palette).toHaveProperty('name');
+        expect(typeof palette.id).toBe('string');
+        expect(typeof palette.name).toBe('string');
+      });
+    });
+  });
+
+  describe('getCurrentPalette', () => {
+    test('returns default when no palette is set', () => {
+      expect(getCurrentPalette()).toBe('default');
+    });
+
+    test('returns palette from document attribute', () => {
+      document.documentElement.getAttribute.mockReturnValue('winter');
+      expect(getCurrentPalette()).toBe('winter');
+    });
+  });
+
+  describe('setPalette', () => {
+    test('sets palette attribute on document element', () => {
+      setPalette('ocean');
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-palette', 'ocean');
+    });
+
+    test('dispatches palette change event', () => {
+      const dispatchEventSpy = jest.spyOn(window, 'dispatchEvent');
+      setPalette('spring');
+      
+      expect(dispatchEventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'paletteChange',
+          detail: { palette: 'spring' }
+        })
+      );
+    });
+  });
+
+  describe('getPaletteName', () => {
+    test('returns correct name for valid palette ID', () => {
+      expect(getPaletteName('default')).toBe('Default');
+      expect(getPaletteName('winter')).toBe('Winter');
+      expect(getPaletteName('autumn')).toBe('Autumn');
+      expect(getPaletteName('spring')).toBe('Spring');
+      expect(getPaletteName('ocean')).toBe('Ocean');
+    });
+
+    test('returns palette ID when name not found', () => {
+      expect(getPaletteName('unknown')).toBe('unknown');
+    });
+  });
+
+  describe('initializePalette', () => {
+    test('loads palette from localStorage', () => {
+      localStorage.getItem.mockImplementation(() => 'winter');
+      initializePalette();
+      
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-palette', 'winter');
+    });
+
+    test('uses default when no saved palette', () => {
+      localStorage.getItem.mockImplementation(() => null);
+      initializePalette();
+      
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-palette', 'default');
+    });
+  });
+
+  describe('savePalettePreference', () => {
+    test('saves palette to localStorage and sets palette', () => {
+      savePalettePreference('autumn');
+      
+      expect(localStorage.setItem).toHaveBeenCalledWith('palette', 'autumn');
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-palette', 'autumn');
+    });
+  });
+
+  describe('getCSSVariable', () => {
+    test('gets CSS custom property value', () => {
+      global.getComputedStyle.mockReturnValue({
+        getPropertyValue: jest.fn().mockReturnValue('  #ff0000  '),
+      });
+      
+      const result = getCSSVariable('--primary-color');
+      
+      expect(getComputedStyle).toHaveBeenCalledWith(document.documentElement);
+      expect(result).toBe('#ff0000'); // Should be trimmed
+    });
+  });
+
+  describe('setCSSVariable', () => {
+    test('sets CSS custom property value', () => {
+      setCSSVariable('--primary-color', '#00ff00');
+      
+      expect(document.documentElement.style.setProperty).toHaveBeenCalledWith(
+        '--primary-color',
+        '#00ff00'
+      );
+    });
+  });
+});

package/src/__tests__/utils/themeUtils.test.js

@@ -0,0 +1,142 @@
+/**
+ * Theme Utilities Tests
+ * Tests for theme utility functions
+ */
+
+import {
+  getCurrentTheme,
+  setTheme,
+  getSystemTheme,
+  getComputedTheme,
+  initializeTheme,
+  saveThemePreference
+} from '../../utils/themeUtils';
+
+describe('Theme Utilities', () => {
+  beforeEach(() => {
+    // Reset document mock
+    document.documentElement.getAttribute.mockReturnValue(null);
+    document.documentElement.setAttribute.mockClear();
+    
+    // Reset localStorage mocks
+    localStorage.getItem.mockClear();
+    localStorage.setItem.mockClear();
+    
+    // Restore original matchMedia mock
+    window.matchMedia = jest.fn().mockImplementation(query => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+  });
+
+  describe('getCurrentTheme', () => {
+    test('returns default system when no theme is set', () => {
+      expect(getCurrentTheme()).toBe('system');
+    });
+
+    test('returns theme from document attribute', () => {
+      document.documentElement.getAttribute.mockReturnValue('dark');
+      expect(getCurrentTheme()).toBe('dark');
+    });
+  });
+
+  describe('setTheme', () => {
+    test('sets theme attribute on document element', () => {
+      setTheme('dark');
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-theme', 'dark');
+    });
+
+    test('dispatches theme change event', () => {
+      const dispatchEventSpy = jest.spyOn(window, 'dispatchEvent');
+      setTheme('light');
+      
+      expect(dispatchEventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'themeChange',
+          detail: { theme: 'light' }
+        })
+      );
+    });
+  });
+
+  describe('getSystemTheme', () => {
+    test('returns dark when system prefers dark', () => {
+      window.matchMedia.mockImplementation(query => ({
+        matches: query === '(prefers-color-scheme: dark)',
+      }));
+      
+      expect(getSystemTheme()).toBe('dark');
+    });
+
+    test('returns light when system prefers light', () => {
+      window.matchMedia.mockImplementation(query => ({
+        matches: query === '(prefers-color-scheme: light)',
+      }));
+      
+      expect(getSystemTheme()).toBe('light');
+    });
+  });
+
+  describe('getComputedTheme', () => {
+    test('resolves system to actual theme', () => {
+      window.matchMedia.mockImplementation(query => ({
+        matches: query === '(prefers-color-scheme: dark)',
+      }));
+      
+      expect(getComputedTheme('system')).toBe('dark');
+    });
+
+    test('returns explicit theme as-is', () => {
+      expect(getComputedTheme('light')).toBe('light');
+      expect(getComputedTheme('dark')).toBe('dark');
+    });
+
+    test('uses current theme when no theme provided', () => {
+      document.documentElement.getAttribute.mockReturnValue('light');
+      expect(getComputedTheme()).toBe('light');
+    });
+  });
+
+  describe('initializeTheme', () => {
+    test('loads theme from localStorage', () => {
+      localStorage.getItem.mockImplementation(() => 'dark');
+      initializeTheme();
+      
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-theme', 'dark');
+    });
+
+    test('uses system default when no saved theme', () => {
+      localStorage.getItem.mockImplementation(() => null);
+      initializeTheme();
+      
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-theme', 'system');
+    });
+
+    test('sets up system theme change listener', () => {
+      const addEventListenerSpy = jest.fn();
+      const mockMatchMedia = jest.fn().mockReturnValue({
+        addEventListener: addEventListenerSpy,
+      });
+      window.matchMedia = mockMatchMedia;
+      
+      initializeTheme();
+      
+      expect(addEventListenerSpy).toHaveBeenCalledWith('change', expect.any(Function));
+    });
+  });
+
+  describe('saveThemePreference', () => {
+    test('saves theme to localStorage and sets theme', () => {
+      saveThemePreference('dark');
+      
+      expect(localStorage.setItem).toHaveBeenCalledWith('theme', 'dark');
+      expect(document.documentElement.setAttribute).toHaveBeenCalledWith('data-theme', 'dark');
+    });
+  });
+});

package/src/components/AccessibilityChecker.tsx

@@ -0,0 +1,264 @@
+/**
+ * AccessibilityChecker Component - Development tool for checking theme accessibility
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ * 
+ * This component is only rendered in development mode and provides
+ * accessibility insights for the current theme/palette combination.
+ */
+
+import React, { useState, useEffect } from 'react';
+import {
+  Fab,
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  Typography,
+  List,
+  ListItem,
+  ListItemIcon,
+  ListItemText,
+  Chip,
+  Box,
+  IconButton,
+  Divider,
+} from '@mui/material';
+import {
+  Accessibility as AccessibilityIcon,
+  CheckCircle as CheckIcon,
+  Warning as WarningIcon,
+  Error as ErrorIcon,
+  Close as CloseIcon,
+} from '@mui/icons-material';
+import { getContrastRatio } from '@mui/material';
+import { getCurrentPalette } from '../utils/paletteUtils';
+import { getCurrentTheme } from '../utils/themeUtils';
+
+interface AccessibilityCheck {
+  id?: string;
+  name: string;
+  status: 'pass' | 'warning' | 'fail';
+  message?: string;
+  details?: string;
+  description?: string;
+  colors?: {
+    foreground: string;
+    background: string;
+  };
+}
+
+const AccessibilityChecker: React.FC = () => {
+  const [open, setOpen] = useState<boolean>(false);
+  const [checks, setChecks] = useState<AccessibilityCheck[]>([]);
+
+  useEffect(() => {
+    if (open && process.env.NODE_ENV === 'development') {
+      performAccessibilityChecks();
+    }
+  }, [open]);
+
+  if (process.env.NODE_ENV !== 'development') {
+    return null;
+  }
+
+  const performAccessibilityChecks = (): void => {
+    const checks: AccessibilityCheck[] = [];
+    const root = document.documentElement;
+    const computedStyle = getComputedStyle(root);
+    
+    // Get current colors
+    const bgColor = computedStyle.getPropertyValue('--palette-background-main').trim();
+    const textColor = computedStyle.getPropertyValue('--palette-text-primary').trim();
+    const primaryColor = computedStyle.getPropertyValue('--palette-primary-main').trim();
+    
+    // Convert CSS colors to hex for contrast calculation
+    const getHexFromCSS = (cssColor: string): string => {
+      if (!cssColor) return '#000000';
+      const temp = document.createElement('div');
+      temp.style.color = cssColor;
+      document.body.appendChild(temp);
+      const computed = getComputedStyle(temp).color;
+      document.body.removeChild(temp);
+      if (computed.startsWith('rgb')) {
+        const matches = computed.match(/\d+/g);
+        if (matches && matches.length >= 3) {
+          const r = parseInt(matches[0]).toString(16).padStart(2, '0');
+          const g = parseInt(matches[1]).toString(16).padStart(2, '0');
+          const b = parseInt(matches[2]).toString(16).padStart(2, '0');
+          return `#${r}${g}${b}`;
+        }
+      }
+      return cssColor;
+    };
+    const bgHex = getHexFromCSS(bgColor);
+    const textHex = getHexFromCSS(textColor);
+    const primaryHex = getHexFromCSS(primaryColor);
+    const textBgContrast = getContrastRatio(textHex, bgHex);
+    const primaryBgContrast = getContrastRatio(primaryHex, bgHex);
+    checks.push({
+      name: 'Text Contrast',
+      description: 'Text should have sufficient contrast against background',
+      status: textBgContrast >= 4.5 ? 'pass' : textBgContrast >= 3 ? 'warning' : 'fail',
+      details: `Contrast ratio: ${textBgContrast.toFixed(2)} (WCAG AA requires 4.5+)`,
+      colors: { foreground: textHex, background: bgHex }
+    });
+    checks.push({
+      name: 'Primary Color Contrast',
+      description: 'Primary color should be distinguishable from background',
+      status: primaryBgContrast >= 3 ? 'pass' : 'warning',
+      details: `Contrast ratio: ${primaryBgContrast.toFixed(2)}`,
+      colors: { foreground: primaryHex, background: bgHex }
+    });
+    checks.push({
+      name: 'Color Independence',
+      description: 'Information should not rely solely on color',
+      status: 'pass',
+      details: 'Icons and text labels are used alongside colors'
+    });
+    const focusIndicators = document.querySelectorAll(':focus-visible');
+    checks.push({
+      name: 'Focus Indicators',
+      description: 'Interactive elements should have visible focus indicators',
+      status: 'pass',
+      details: `${focusIndicators.length} elements currently focused`
+    });
+    const fontSize = parseFloat(computedStyle.fontSize);
+    checks.push({
+      name: 'Font Size',
+      description: 'Base font size should be readable',
+      status: fontSize >= 14 ? 'pass' : 'warning',
+      details: `Base font size: ${fontSize}px (recommended: 14px+)`
+    });
+    setChecks(checks);
+  };
+
+  const getStatusIcon = (status: 'pass' | 'warning' | 'fail') => {
+    switch (status) {
+      case 'pass':
+        return <CheckIcon color="success" />;
+      case 'warning':
+        return <WarningIcon color="warning" />;
+      case 'fail':
+        return <ErrorIcon color="error" />;
+      default:
+        return null;
+    }
+  };
+
+  const getStatusColor = (status: 'pass' | 'warning' | 'fail') => {
+    switch (status) {
+      case 'pass':
+        return 'success';
+      case 'warning':
+        return 'warning';
+      case 'fail':
+        return 'error';
+      default:
+        return 'default';
+    }
+  };
+
+  return (
+    <>
+      <Fab
+        color="secondary"
+        aria-label="accessibility checker"
+        onClick={() => setOpen(true)}
+        sx={{
+          position: 'fixed',
+          bottom: 16,
+          left: 16,
+          zIndex: 1000,
+        }}
+      >
+        <AccessibilityIcon />
+      </Fab>
+
+      <Dialog
+        open={open}
+        onClose={() => setOpen(false)}
+        maxWidth="md"
+        fullWidth
+      >
+        <DialogTitle sx={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+            <AccessibilityIcon />
+            Accessibility Report
+          </Box>
+          <IconButton onClick={() => setOpen(false)}>
+            <CloseIcon />
+          </IconButton>
+        </DialogTitle>
+        
+        <DialogContent>
+          <Box sx={{ mb: 2 }}>
+            <Typography variant="body2" color="text.secondary">
+              Current theme: {getCurrentTheme()} | Current palette: {getCurrentPalette()}
+            </Typography>
+          </Box>
+          
+          <Divider sx={{ mb: 2 }} />
+          
+          <List>
+            {checks.map((check, index) => (
+              <ListItem key={index} alignItems="flex-start">
+                <ListItemIcon>
+                  {getStatusIcon(check.status)}
+                </ListItemIcon>
+                <ListItemText
+                  primary={
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                      {check.name}
+                      <Chip
+                        label={check.status.toUpperCase()}
+                        size="small"
+                        color={getStatusColor(check.status)}
+                        variant="outlined"
+                      />
+                    </Box>
+                  }
+                  secondary={
+                    <>
+                      <Typography variant="body2" sx={{ mt: 0.5 }}>
+                        {check.description}
+                      </Typography>
+                      <Typography variant="caption" color="text.secondary" sx={{ mt: 0.5, display: 'block' }}>
+                        {check.details}
+                      </Typography>
+                      {check.colors && (
+                        <Box sx={{ display: 'flex', gap: 1, mt: 1 }}>
+                          <Box
+                            sx={{
+                              width: 20,
+                              height: 20,
+                              backgroundColor: check.colors.foreground,
+                              border: '1px solid #ccc',
+                              borderRadius: 1,
+                            }}
+                            title={`Foreground: ${check.colors.foreground}`}
+                          />
+                          <Box
+                            sx={{
+                              width: 20,
+                              height: 20,
+                              backgroundColor: check.colors.background,
+                              border: '1px solid #ccc',
+                              borderRadius: 1,
+                            }}
+                            title={`Background: ${check.colors.background}`}
+                          />
+                        </Box>
+                      )}
+                    </>
+                  }
+                />
+              </ListItem>
+            ))}
+          </List>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+};
+
+export default AccessibilityChecker;