npm - @jmruthers/pace-core - Versions diffs - 0.2.7 → 0.5.1 - Mend

@jmruthers/pace-core 0.2.7 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (541) hide show

package/src/theming/__tests__/runtime.accessibility.test.ts DELETED Viewed

@@ -1,474 +0,0 @@
-/**
- * @file Theming Runtime Accessibility Tests
- * @package @jmruthers/pace-core
- * @module Theming/Runtime
- * @since 2.0.0
- */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { JSDOM } from 'jsdom';
-import {
-  applyPalette,
-  clearPalette,
-  generateSSRThemeCSS,
-  type PaletteData,
-  type ColorShade
-} from '../runtime';
-describe('Theming Runtime Accessibility Tests', () => {
-  let dom: JSDOM;
-  let document: Document;
-  beforeEach(() => {
-    dom = new JSDOM('<!DOCTYPE html><html><head></head><body></body></html>');
-    document = dom.window.document;
-    Object.defineProperty(global, 'document', {
-      value: document,
-      writable: true
-    });
-  });
-  afterEach(() => {
-    dom.window.close();
-  });
-  /**
-   * Calculate relative luminance using WCAG formula
-   * Note: This is a simplified version for OKLCH colors
-   */
-  const calculateRelativeLuminance = (color: ColorShade): number => {
-    // Convert OKLCH L value to relative luminance approximation
-    // In OKLCH, L is already perceptually uniform lightness
-    return Math.max(0, Math.min(1, color.L));
-  };
-  /**
-   * Calculate contrast ratio between two colors
-   */
-  const calculateContrastRatio = (color1: ColorShade, color2: ColorShade): number => {
-    const lum1 = calculateRelativeLuminance(color1);
-    const lum2 = calculateRelativeLuminance(color2);
-    const lighter = Math.max(lum1, lum2);
-    const darker = Math.min(lum1, lum2);
-    return (lighter + 0.05) / (darker + 0.05);
-  };
-  /**
-   * Check if color meets WCAG contrast requirements
-   */
-  const meetsWCAGContrast = (foreground: ColorShade, background: ColorShade, level: 'AA' | 'AAA' = 'AA'): boolean => {
-    const ratio = calculateContrastRatio(foreground, background);
-    const requiredRatio = level === 'AAA' ? 7 : 4.5;
-    return ratio >= requiredRatio;
-  };
-  const createAccessiblePalette = (): PaletteData => ({
-    main: {
-      '50': { L: 0.98, C: 0.005, H: 220 },   // Very light
-      '100': { L: 0.92, C: 0.01, H: 220 },   // Light
-      '200': { L: 0.85, C: 0.02, H: 220 },   // Light
-      '300': { L: 0.75, C: 0.05, H: 220 },   // Medium light
-      '400': { L: 0.65, C: 0.1, H: 220 },    // Medium
-      '500': { L: 0.55, C: 0.15, H: 220 },   // Medium
-      '600': { L: 0.45, C: 0.2, H: 220 },    // Medium dark
-      '700': { L: 0.35, C: 0.18, H: 220 },   // Dark
-      '800': { L: 0.25, C: 0.15, H: 220 },   // Darker
-      '900': { L: 0.15, C: 0.12, H: 220 },   // Very dark
-      '950': { L: 0.05, C: 0.08, H: 220 },   // Darkest
-      'raw': { L: 0.45, C: 0.2, H: 220 }
-    },
-    sec: {
-      '50': { L: 0.98, C: 0.005, H: 120 },
-      '500': { L: 0.55, C: 0.15, H: 120 },
-      '900': { L: 0.15, C: 0.12, H: 120 },
-      'raw': { L: 0.45, C: 0.2, H: 120 }
-    },
-    acc: {
-      '50': { L: 0.98, C: 0.005, H: 30 },
-      '500': { L: 0.55, C: 0.15, H: 30 },
-      '900': { L: 0.15, C: 0.12, H: 30 },
-      'raw': { L: 0.45, C: 0.2, H: 30 }
-    }
-  });
-  const createPoorContrastPalette = (): PaletteData => ({
-    main: {
-      '50': { L: 0.6, C: 0.1, H: 220 },    // Too dark for light background
-      '500': { L: 0.5, C: 0.15, H: 220 },  // Medium - poor contrast
-      '900': { L: 0.4, C: 0.12, H: 220 },  // Too light for dark text
-      'raw': { L: 0.5, C: 0.15, H: 220 }
-    },
-    sec: {
-      '500': { L: 0.5, C: 0.15, H: 120 },
-      'raw': { L: 0.5, C: 0.15, H: 120 }
-    },
-    acc: {
-      '500': { L: 0.5, C: 0.15, H: 30 },
-      'raw': { L: 0.5, C: 0.15, H: 30 }
-    }
-  });
-  describe('Color Contrast Validation', () => {
-    it('should generate palettes with sufficient contrast ranges', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      // Test contrast between light and dark shades
-      const lightShade = palette.main['50'];
-      const darkShade = palette.main['900'];
-      const contrastRatio = calculateContrastRatio(lightShade, darkShade);
-      // Should have good contrast between light and dark shades
-      expect(contrastRatio).toBeGreaterThan(4.5); // AA level (adjusted for realistic OKLCH calculation)
-    });
-    it('should provide adequate contrast for text on background combinations', () => {
-      const palette = createAccessiblePalette();
-      // Test common text/background combinations
-      const textOnLight = meetsWCAGContrast(palette.main['900'], palette.main['50']);
-      const textOnDark = meetsWCAGContrast(palette.main['50'], palette.main['900']);
-      expect(textOnLight).toBe(true);
-      expect(textOnDark).toBe(true);
-      // Test that we can calculate contrast ratios for all combinations
-      const contrastRatio = calculateContrastRatio(palette.main['900'], palette.main['50']);
-      expect(contrastRatio).toBeGreaterThan(1); // Basic sanity check
-    });
-    it('should detect insufficient contrast in poor palettes', () => {
-      const poorPalette = createPoorContrastPalette();
-      // Test insufficient contrast
-      const poorContrast = meetsWCAGContrast(poorPalette.main['500'], poorPalette.main['50']);
-      expect(poorContrast).toBe(false);
-    });
-    it('should validate contrast across all three palette types', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      const paletteTypes = ['main', 'sec', 'acc'] as const;
-      paletteTypes.forEach(paletteType => {
-        const paletteData = palette[paletteType];
-        if (paletteData['50'] && paletteData['900']) {
-          const contrast = calculateContrastRatio(paletteData['50'], paletteData['900']);
-          expect(contrast).toBeGreaterThan(4.5); // AA level minimum
-        }
-      });
-    });
-  });
-  describe('Color Blindness Considerations', () => {
-    it('should generate palettes with sufficient lightness differences for color blind users', () => {
-      const palette = createAccessiblePalette();
-      // Color blind users rely heavily on lightness differences
-      const shades = Object.keys(palette.main).filter(key => key !== 'raw').sort((a, b) => parseInt(a) - parseInt(b));
-      for (let i = 0; i < shades.length - 1; i++) {
-        const currentShade = palette.main[shades[i]];
-        const nextShade = palette.main[shades[i + 1]];
-        const lightnessDiff = Math.abs(currentShade.L - nextShade.L);
-        // Should have meaningful lightness difference between adjacent shades
-        expect(lightnessDiff).toBeGreaterThan(0.05);
-      }
-    });
-    it('should maintain consistent chroma progression for color discrimination', () => {
-      const palette = createAccessiblePalette();
-      // Check that chroma (saturation) changes in a predictable way
-      const mainShades = ['100', '300', '500', '700', '900'];
-      for (let i = 0; i < mainShades.length - 1; i++) {
-        const current = palette.main[mainShades[i]];
-        const next = palette.main[mainShades[i + 1]];
-        if (current && next) {
-          // Chroma should generally increase or stay consistent towards middle shades
-          const chromaDiff = Math.abs(current.C - next.C);
-          expect(chromaDiff).toBeLessThan(0.1); // Reasonable chroma progression
-        }
-      }
-    });
-    it('should provide alternative identification beyond color alone', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      const styleElement = document.getElementById('pace-theme-dynamic') as HTMLStyleElement;
-      const cssContent = styleElement.textContent || '';
-      // Verify that the CSS includes semantic naming that doesn't rely on color alone
-      expect(cssContent).toContain('--color-main-');
-      expect(cssContent).toContain('--color-sec-');
-      expect(cssContent).toContain('--color-acc-');
-      // The semantic naming (main, sec, acc) provides meaning beyond color
-      expect(cssContent).not.toContain('--color-red-');
-      expect(cssContent).not.toContain('--color-blue-');
-      expect(cssContent).not.toContain('--color-green-');
-    });
-  });
-  describe('High Contrast Mode Support', () => {
-    it('should generate extreme contrast palettes for high contrast needs', () => {
-      const highContrastPalette: PaletteData = {
-        main: {
-          '50': { L: 0.99, C: 0, H: 0 },    // Near white
-          '500': { L: 0.5, C: 0.3, H: 220 }, // Saturated medium
-          '900': { L: 0.01, C: 0, H: 0 },    // Near black
-          'raw': { L: 0.5, C: 0.3, H: 220 }
-        },
-        sec: {
-          '50': { L: 0.99, C: 0, H: 0 },
-          '500': { L: 0.5, C: 0.3, H: 120 },
-          '900': { L: 0.01, C: 0, H: 0 },
-          'raw': { L: 0.5, C: 0.3, H: 120 }
-        },
-        acc: {
-          '50': { L: 0.99, C: 0, H: 0 },
-          '500': { L: 0.5, C: 0.3, H: 30 },
-          '900': { L: 0.01, C: 0, H: 0 },
-          'raw': { L: 0.5, C: 0.3, H: 30 }
-        }
-      };
-      applyPalette(highContrastPalette);
-      const extremeContrast = calculateContrastRatio(
-        highContrastPalette.main['50'],
-        highContrastPalette.main['900']
-      );
-      expect(extremeContrast).toBeGreaterThan(15); // Very high contrast
-    });
-    it('should handle achromatic (grayscale) palettes for maximum accessibility', () => {
-      const grayscalePalette: PaletteData = {
-        main: {
-          '50': { L: 0.95, C: 0, H: 0 },
-          '100': { L: 0.9, C: 0, H: 0 },
-          '500': { L: 0.5, C: 0, H: 0 },
-          '800': { L: 0.2, C: 0, H: 0 },
-          '900': { L: 0.1, C: 0, H: 0 },
-          'raw': { L: 0.5, C: 0, H: 0 }
-        },
-        sec: {
-          '500': { L: 0.5, C: 0, H: 0 },
-          'raw': { L: 0.5, C: 0, H: 0 }
-        },
-        acc: {
-          '500': { L: 0.5, C: 0, H: 0 },
-          'raw': { L: 0.5, C: 0, H: 0 }
-        }
-      };
-      expect(() => applyPalette(grayscalePalette)).not.toThrow();
-      const styleElement = document.getElementById('pace-theme-dynamic') as HTMLStyleElement;
-      const cssContent = styleElement.textContent || '';
-      // Should contain achromatic colors (C = 0)
-      expect(cssContent).toContain('oklch(0.95 0 0)');
-      expect(cssContent).toContain('oklch(0.5 0 0)');
-      expect(cssContent).toContain('oklch(0.1 0 0)');
-    });
-  });
-  describe('Reduced Motion and Animation Considerations', () => {
-    it('should apply themes instantly without animation dependencies', () => {
-      const palette = createAccessiblePalette();
-      const startTime = performance.now();
-      applyPalette(palette);
-      const endTime = performance.now();
-      // Should apply instantly (no animation delays)
-      expect(endTime - startTime).toBeLessThan(5);
-      // Should immediately be available in DOM
-      const styleElement = document.getElementById('pace-theme-dynamic');
-      expect(styleElement).toBeTruthy();
-    });
-    it('should support immediate theme clearing for reduced motion users', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      expect(document.getElementById('pace-theme-dynamic')).toBeTruthy();
-      const startTime = performance.now();
-      clearPalette();
-      const endTime = performance.now();
-      // Should clear instantly (allow for some timing variance)
-      expect(endTime - startTime).toBeLessThan(10);
-      expect(document.getElementById('pace-theme-dynamic')).toBeNull();
-    });
-  });
-  describe('Screen Reader and Assistive Technology Support', () => {
-    it('should generate CSS that does not interfere with screen readers', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      const styleElement = document.getElementById('pace-theme-dynamic') as HTMLStyleElement;
-      // Style element should have proper ID for programmatic access
-      expect(styleElement.id).toBe('pace-theme-dynamic');
-      // Should not contain content that would be read by screen readers
-      expect(styleElement.textContent).not.toContain('screen-reader');
-      expect(styleElement.textContent).not.toContain('aria-');
-      expect(styleElement.textContent).not.toContain('alt=');
-    });
-    it('should maintain semantic color naming for assistive technologies', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      const styleElement = document.getElementById('pace-theme-dynamic') as HTMLStyleElement;
-      const cssContent = styleElement.textContent || '';
-      // Should use semantic names that convey meaning
-      expect(cssContent).toContain('--color-main-'); // Primary/main color
-      expect(cssContent).toContain('--color-sec-');  // Secondary color
-      expect(cssContent).toContain('--color-acc-');  // Accent color
-      // Should not use ambiguous color names
-      expect(cssContent).not.toContain('--color-color1-');
-      expect(cssContent).not.toContain('--color-brand-');
-      expect(cssContent).not.toContain('--color-custom-');
-    });
-    it('should support programmatic theme detection for assistive tools', () => {
-      const palette = createAccessiblePalette();
-      applyPalette(palette);
-      // Assistive tools should be able to detect theme state
-      const isDynamic = document.getElementById('pace-theme-dynamic') !== null;
-      expect(isDynamic).toBe(true);
-      clearPalette();
-      const isCleared = document.getElementById('pace-theme-dynamic') === null;
-      expect(isCleared).toBe(true);
-    });
-  });
-  describe('WCAG Compliance Validation', () => {
-    it('should meet WCAG 2.1 Level AA contrast requirements', () => {
-      const palette = createAccessiblePalette();
-      // Test key contrast combinations for AA compliance
-      const testCombinations = [
-        { fg: palette.main['900'], bg: palette.main['50'], name: 'Dark text on light background' },
-        { fg: palette.main['50'], bg: palette.main['900'], name: 'Light text on dark background' },
-      ];
-      testCombinations.forEach(({ fg, bg, name }) => {
-        if (fg && bg) {
-          const contrast = calculateContrastRatio(fg, bg);
-          // Note: Our simplified OKLCH contrast calculation may not perfectly match WCAG
-          // but we test that it produces reasonable values
-          expect(contrast).toBeGreaterThan(3); // Reasonable contrast threshold
-        }
-      });
-    });
-    it('should support WCAG 2.1 Level AAA contrast where possible', () => {
-      const palette = createAccessiblePalette();
-      // Test highest contrast combinations for AAA compliance
-      const highContrastCombinations = [
-        { fg: palette.main['900'], bg: palette.main['50'] },
-        { fg: palette.main['50'], bg: palette.main['900'] },
-      ];
-      highContrastCombinations.forEach(({ fg, bg }) => {
-        if (fg && bg) {
-          const contrast = calculateContrastRatio(fg, bg);
-          // With our accessible palette, we should get decent contrast
-          expect(contrast).toBeGreaterThan(4.5); // Good contrast threshold
-        }
-      });
-    });
-    it('should maintain color contrast in SSR-generated CSS', () => {
-      const palette = createAccessiblePalette();
-      const ssrCSS = generateSSRThemeCSS(palette);
-      // SSR CSS should contain the same contrast-compliant colors
-      expect(ssrCSS).toContain('oklch(0.98 0.005 220)'); // Light shade
-      expect(ssrCSS).toContain('oklch(0.15 0.12 220)');  // Dark shade (900 value)
-      // Verify the CSS structure is valid for accessibility tools
-      expect(ssrCSS).toMatch(/@theme static \{[\s\S]*\}/);
-    });
-  });
-  describe('Accessibility Error Handling', () => {
-    it('should gracefully handle invalid color values without breaking accessibility', () => {
-      const invalidPalette: PaletteData = {
-        main: {
-          'invalid': { L: NaN, C: Infinity, H: -1 },
-          '500': { L: 0.5, C: 0.2, H: 220 }, // Valid fallback
-          'raw': { L: 0.5, C: 0.2, H: 220 }
-        },
-        sec: {
-          '500': { L: 0.5, C: 0.2, H: 120 },
-          'raw': { L: 0.5, C: 0.2, H: 120 }
-        },
-        acc: {
-          '500': { L: 0.5, C: 0.2, H: 30 },
-          'raw': { L: 0.5, C: 0.2, H: 30 }
-        }
-      };
-      expect(() => applyPalette(invalidPalette)).not.toThrow();
-      // Should still create valid CSS structure
-      const styleElement = document.getElementById('pace-theme-dynamic') as HTMLStyleElement;
-      expect(styleElement).toBeTruthy();
-      expect(styleElement.textContent).toContain('@theme static {');
-    });
-    it('should maintain accessibility when DOM manipulation fails', () => {
-      const originalAppendChild = document.head.appendChild;
-      // Mock DOM failure
-      document.head.appendChild = () => {
-        throw new Error('DOM manipulation failed');
-      };
-      const palette = createAccessiblePalette();
-      expect(() => applyPalette(palette)).toThrow();
-      // Restore original function
-      document.head.appendChild = originalAppendChild;
-      // Should still be able to apply palette after error
-      expect(() => applyPalette(palette)).not.toThrow();
-    });
-  });
-});