aura-glass
Version:
A comprehensive glassmorphism design system for React applications with 142+ production-ready components
124 lines • 3.98 kB
TypeScript
/**
* Liquid Glass Contrast Guard System
*
* Ensures WCAG compliance for all glass surfaces with dynamic tinting.
* Automatically adjusts opacity, tint, and backdrop-filter to maintain
* readable text contrast ratios even with environmental changes.
*
* Features:
* - Real-time backdrop luminance sampling
* - Automatic contrast ratio enforcement (AA/AAA)
* - Content-aware tint adjustment
* - Performance optimized with throttling
* - Fallback modes for edge cases
*/
import React from 'react';
import { type LiquidGlassMaterial, type MaterialVariant, type GlassIntent } from '../tokens/glass';
export type ContrastLevel = 'A' | 'AA' | 'AAA';
export declare const CONTRAST_RATIOS: Record<ContrastLevel, number>;
export interface RGBColor {
r: number;
g: number;
b: number;
a?: number;
}
export interface HSLColor {
h: number;
s: number;
l: number;
a?: number;
}
export interface BackdropSample {
averageLuminance: number;
dominantHue: number;
contrast: number;
timestamp: number;
confidence: number;
}
export interface ContrastAdjustment {
originalContrast: number;
adjustedContrast: number;
modifications: {
opacity?: number;
tint?: string;
backdropBlur?: number;
fallbackMode?: boolean;
};
meetsRequirement: boolean;
level: ContrastLevel;
}
/**
* Core Contrast Guard System
*/
export declare class ContrastGuard {
private cache;
private observers;
private throttleTimers;
private readonly CACHE_TTL;
private readonly THROTTLE_DELAY;
private readonly SAMPLING_SIZE;
/**
* Sample backdrop luminance behind a glass element
*/
sampleBackdrop(element: HTMLElement): Promise<BackdropSample>;
/**
* Calculate contrast ratio between foreground and background colors
*/
calculateContrastRatio(foreground: string, background: string): number;
/**
* Adjust glass surface properties to meet contrast requirements
*/
enforceContrast(element: HTMLElement, textColor: string, targetLevel?: ContrastLevel, material?: LiquidGlassMaterial, variant?: MaterialVariant): Promise<ContrastAdjustment>;
/**
* Start monitoring an element for backdrop changes
*/
startMonitoring(element: HTMLElement, callback: (adjustment: ContrastAdjustment) => void, options?: {
targetLevel?: ContrastLevel;
material?: LiquidGlassMaterial;
variant?: MaterialVariant;
textColor?: string;
}): void;
/**
* Stop monitoring an element
*/
stopMonitoring(element: HTMLElement): void;
/**
* Generate adaptive tint based on backdrop analysis
*/
generateAdaptiveTint(backdrop: BackdropSample, intent?: GlassIntent): string;
private performBackdropSample;
private captureBackdrop;
private analyzeImageData;
private estimateBackdropFromStyles;
private calculateAdjustments;
private calculateContrastWithOpacity;
private getRelativeLuminance;
private getRelativeLuminanceFromRGB;
private parseColor;
private rgbToHsl;
private luminanceToColor;
private getContrastLevel;
private getCacheKey;
private cleanCache;
private getDefaultBackdropSample;
private getFallbackAdjustment;
}
/**
* Singleton instance for global use
*/
export declare const contrastGuard: ContrastGuard;
/**
* Hook for React components to use contrast guard
*/
export declare function useContrastGuard(elementRef: React.RefObject<HTMLElement | null>, options?: {
targetLevel?: ContrastLevel;
material?: LiquidGlassMaterial;
variant?: MaterialVariant;
textColor?: string;
onAdjustment?: (adjustment: ContrastAdjustment) => void;
}): ContrastAdjustment | null;
/**
* Utility function to apply contrast adjustments to an element
*/
export declare function applyContrastAdjustment(element: HTMLElement, adjustment: ContrastAdjustment): void;
//# sourceMappingURL=contrastGuard.d.ts.map