Added color utilities

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.28.8",
+	"version": "0.28.14",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",

src/color.ts

@@ -1,12 +1,73 @@
+import {dec2Hex} from './math.ts';
+
 /**
  * Determine if either black or white provides more contrast to the provided color
- * @param {string} background Color to compare against
+ * @param {string} color Color to compare against
  * @return {"white" | "black"} Color with the most contrast
  */
-export function contrast(background: string): 'white' | 'black' {
-	const exploded = background?.match(background.length >= 6 ? /[0-9a-fA-F]{2}/g : /[0-9a-fA-F]/g);
+export function contrast(color: string): 'white' | 'black' {
+	const exploded = color?.match(color.length >= 6 ? /[0-9a-fA-F]{2}/g : /[0-9a-fA-F]/g);
 	if(!exploded || exploded?.length < 3) return 'black';
 	const [r, g, b] = exploded.map(hex => parseInt(hex.length == 1 ? `${hex}${hex}` : hex, 16));
 	const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
 	return luminance > 0.5 ? 'black' : 'white';
 }
+
+export function hex2Int(hex: string): {r: number, g: number, b: number} {
+	let r = 0, g = 0, b = 0;
+	if (hex.length === 4) {
+		r = parseInt(hex[1] + hex[1], 16);
+		g = parseInt(hex[2] + hex[2], 16);
+		b = parseInt(hex[3] + hex[3], 16);
+	} else {
+		r = parseInt(hex.slice(1, 3), 16);
+		g = parseInt(hex.slice(3, 5), 16);
+		b = parseInt(hex.slice(5, 7), 16);
+	}
+	return {r, g, b};
+}
+
+export function hue2rgb(p: number, q: number, t: number): number {
+	if(t < 0) t += 1;
+	if(t > 1) t -= 1;
+	if(t < 1 / 6) return p + (q - p) * 6 * t;
+	if(t < 1 / 2) return q;
+	if(t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+	return p;
+}
+
+export function int2Hex(r: number, g: number, b: number) {
+	return '#' + dec2Hex(r) + dec2Hex(g) + dec2Hex(b);
+}
+
+/**
+ * Adjusts the darkness of a hex color.
+ * @param {string} hex - The hex color (e.g., '#ff0000').
+ * @param {number} amount - A value between -1 (black) and 1 (white)
+ */
+export function shadeColor(hex: string, amount: number) {
+	let {r, g, b} = hex2Int(hex);
+	r /= 255; g /= 255; b /= 255;
+	const max = Math.max(r, g, b), min = Math.min(r, g, b);
+	let h, s, l = (max + min) / 2;
+
+	if (max === min) {
+		h = s = 0;
+	} else {
+		const d = max - min;
+		s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+		switch (max) {
+			case r: h = (g - b) / d + (g < b ? 6 : 0); break;
+			case g: h = (b - r) / d + 2; break;
+			case b: h = (r - g) / d + 4; break;
+			default: h = 0; break;
+		}
+		h /= 6;
+	}
+
+	// Adjust Lightness
+	l = Math.max(0, Math.min(1, l + amount));
+	const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+	const p = 2 * l - q;
+	return int2Hex(hue2rgb(p, q, h + 1/3), hue2rgb(p, q, h), hue2rgb(p, q, h - 1/3));
+};

src/index.ts

@@ -21,5 +21,6 @@ export * from './search';
 export * from './string';
 export * from './template';
 export * from './time';
+export * from './tts';
 export * from './types';
 export * from 'var-persist';

src/math.ts

@@ -30,6 +30,10 @@ export function dec2Frac(num: number, maxDen=1000): string {
 		(numerator ? numerator + '/' + closest.d : '');
 }
 
+export function dec2Hex(num: number): string {
+	const hex = Math.round(num * 255).toString(16);
+	return hex.length === 1 ? '0' + hex : hex;
+}
 
 /**
  * Convert fraction to decimal number
@@ -42,7 +46,7 @@ export function dec2Frac(num: number, maxDen=1000): string {
  * @param {string} frac Fraction to convert
  * @return {number} Faction as a decimal
  */
-export function fracToDec(frac: string) {
+export function frac2Dec(frac: string) {
 	let split = frac.split(' ');
 	const whole = split.length == 2 ? Number(split[0]) : 0;
 	split = (<string>split.pop()).split('/');

src/string.ts

@@ -140,7 +140,7 @@ export function pascalCase(str?: string): string {
  * @param {string} str Input string with emojis
  * @returns {string} Sanitized string without emojis
  */
-function removeEmojis(str: string): string {
+export function removeEmojis(str: string): string {
 	const emojiRegex = /(?:[\u2700-\u27bf]|(?:\ud83c[\udde6-\uddff]){2}|[\ud83c[\udde6-\uddff]|[\ud83d[\ude00-\ude4f]|[\ud83d[\ude80-\udeff]|[\ud83c[\udd00-\uddff]|[\ud83d[\ude50-\ude7f]|[\u2600-\u26ff]|[\u2700-\u27bf]|[\ud83e[\udd00-\uddff]|[\ud83c[\udf00-\uffff]|[\ud83d[\ude00-\udeff]|[\ud83c[\udde6-\uddff])/g;
 	return str.replace(emojiRegex, '');
 }

src/template.ts

@@ -8,7 +8,16 @@ export class TemplateError extends BadRequestError { }
 export function findTemplateVars(html: string): Record<string, any> {
 	const variables = new Set<string>();
 	const arrays = new Set<string>();
-	const excluded = new Set<string>(['true', 'false', 'null', 'undefined']);
+	const excluded = new Set([
+		'let', 'const', 'var', 'function', 'if', 'while', 'do', 'this', 'typeof',
+		'new', 'instanceof', 'in', 'for', 'else', 'case', 'break', 'continue',
+		'switch', 'default', 'with', 'eval', 'arguments', 'void', 'delete', 'null',
+		'undefined', 'true', 'false', 'async', 'await', 'try', 'catch', 'finally',
+		'throw', 'return', 'yield', 'debugger', 'extends', 'import', 'export',
+		'class', 'super', 'static', 'get', 'set', 'constructor', 'enum', 'implements',
+		'interface', 'package', 'private', 'protected', 'public', 'abstract', 'final',
+		'native', 'synchronized', 'throws', 'transient', 'volatile'
+	]);
 
 	// Extract & exclude loop variables, mark arrays
 	for (const loop of matchAll(html, /\{\{\s*?\*\s*?(.+?)\s+in\s+(.+?)\s*?}}/g)) {
@@ -70,6 +79,7 @@ export function findTemplateVars(html: string): Record<string, any> {
 	}
 	return result;
 }
+
 export async function renderTemplate(template: string, data: any, fetch?: (file: string) => Promise<string>) {
 	if(!fetch) fetch = (file) => { throw new TemplateError(`Unable to fetch template: ${file}`); }
 

src/tts.ts

@@ -0,0 +1,148 @@
+import {removeEmojis} from './string.ts';
+
+export class TTS {
+	private static readonly QUALITY_PATTERNS = ['Google', 'Microsoft', 'Samantha', 'Premium', 'Natural', 'Neural'];
+	private static _errorHandlerInstalled = false;
+
+	private _currentUtterance: SpeechSynthesisUtterance | null = null;
+	private _voicesLoaded: Promise<void>;
+	private _stoppedUtterances = new WeakSet<SpeechSynthesisUtterance>();
+
+	private _rate: number = 1.0;
+	get rate(): number { return this._rate; }
+	set rate(value: number) {
+		this._rate = value;
+		if(this._currentUtterance) this._currentUtterance.rate = value;
+	}
+
+	private _pitch: number = 1.0;
+	get pitch(): number { return this._pitch; }
+	set pitch(value: number) {
+		this._pitch = value;
+		if(this._currentUtterance) this._currentUtterance.pitch = value;
+	}
+
+	private _volume: number = 1.0;
+	get volume(): number { return this._volume; }
+	set volume(value: number) {
+		this._volume = value;
+		if(this._currentUtterance) this._currentUtterance.volume = value;
+	}
+
+	private _voice: SpeechSynthesisVoice | undefined;
+	get voice(): SpeechSynthesisVoice | undefined { return this._voice; }
+	set voice(value: SpeechSynthesisVoice | undefined) {
+		this._voice = value;
+		if(this._currentUtterance && value) this._currentUtterance.voice = value;
+	}
+
+	constructor(config?: {rate?: number; pitch?: number; volume?: number; voice?: SpeechSynthesisVoice | null}) {
+		TTS.installErrorHandler();
+		this._voicesLoaded = this.initializeVoices();
+		if(config) {
+			if(config.rate !== undefined) this._rate = config.rate;
+			if(config.pitch !== undefined) this._pitch = config.pitch;
+			if(config.volume !== undefined) this._volume = config.volume;
+			this._voice = config.voice === null ? undefined : (config.voice || undefined);
+		}
+	}
+
+	private static installErrorHandler(): void {
+		if(this._errorHandlerInstalled) return;
+		window.addEventListener('unhandledrejection', (event) => {
+			if(event.reason?.error === 'interrupted' && event.reason instanceof SpeechSynthesisErrorEvent) event.preventDefault();
+		});
+		this._errorHandlerInstalled = true;
+	}
+
+	private initializeVoices(): Promise<void> {
+		return new Promise((resolve) => {
+			const voices = window.speechSynthesis.getVoices();
+			if(voices.length > 0) {
+				if(!this._voice) this._voice = TTS.bestVoice();
+				resolve();
+			} else {
+				const handler = () => {
+					window.speechSynthesis.removeEventListener('voiceschanged', handler);
+					if(!this._voice) this._voice = TTS.bestVoice();
+					resolve();
+				};
+				window.speechSynthesis.addEventListener('voiceschanged', handler);
+			}
+		});
+	}
+
+	private static bestVoice(lang = 'en'): SpeechSynthesisVoice | undefined {
+		const voices = window.speechSynthesis.getVoices();
+		for (const pattern of this.QUALITY_PATTERNS) {
+			const voice = voices.find(v => v.name.includes(pattern) && v.lang.startsWith(lang));
+			if(voice) return voice;
+		}
+		return voices.find(v => v.lang.startsWith(lang));
+	}
+
+	private static cleanText(text: string): string {
+		return removeEmojis(text)
+			.replace(/```[\s\S]*?```/g, ' code block ')
+			.replace(/[#*_~`]/g, '');
+	}
+
+	private createUtterance(text: string): SpeechSynthesisUtterance {
+		const cleanedText = TTS.cleanText(text);
+		const utterance = new SpeechSynthesisUtterance(cleanedText);
+		const voice = this._voice || TTS.bestVoice();
+		if(voice) utterance.voice = voice;
+		utterance.rate = this._rate;
+		utterance.pitch = this._pitch;
+		utterance.volume = this._volume;
+		return utterance;
+	}
+
+	async speak(text: string): Promise<void> {
+		if(!text.trim()) return Promise.resolve();
+		await this._voicesLoaded;
+		return new Promise((resolve, reject) => {
+			this._currentUtterance = this.createUtterance(text);
+			const utterance = this._currentUtterance;
+			utterance.onend = () => {
+				this._currentUtterance = null;
+				resolve();
+			};
+			utterance.onerror = (error) => {
+				this._currentUtterance = null;
+				if(this._stoppedUtterances.has(utterance) && error.error === 'interrupted') resolve();
+				else reject(error);
+			};
+			window.speechSynthesis.speak(utterance);
+		});
+	}
+
+	stop(): void {
+		if(this._currentUtterance) this._stoppedUtterances.add(this._currentUtterance);
+		window.speechSynthesis.cancel();
+		this._currentUtterance = null;
+	}
+
+	speakStream(): {next: (text: string) => void, done: () => Promise<void>} {
+		let buffer = '';
+		let streamPromise: Promise<void> = Promise.resolve();
+		const sentenceRegex = /[^.!?\n]+[.!?\n]+/g;
+		return {
+			next: (text: string): void => {
+				buffer += text;
+				const sentences = buffer.match(sentenceRegex);
+				if(sentences) {
+					sentences.forEach(sentence => streamPromise = this.speak(sentence.trim()));
+					buffer = buffer.replace(sentenceRegex, '');
+				}
+			},
+			done: async (): Promise<void> => {
+				if(buffer.trim()) {
+					streamPromise = this.speak(buffer.trim());
+					buffer = '';
+				}
+				await streamPromise;
+			}
+		};
+	}
+}

tests/math.spec.ts

@@ -1,4 +1,4 @@
-import { dec2Frac, fracToDec } from '../src';
+import { dec2Frac, frac2Dec } from '../src';
 
 describe('Math Utilities', () => {
 	describe('dec2Frac', () => {
@@ -27,25 +27,25 @@ describe('Math Utilities', () => {
 
 	describe('fracToDec', () => {
 		it('should convert mixed fraction to decimal', () => {
-			expect(fracToDec('1 1/4')).toBeCloseTo(1.25);
-			expect(fracToDec('2 1/2')).toBeCloseTo(2.5);
-			expect(fracToDec('3 3/4')).toBeCloseTo(3.75);
+			expect(frac2Dec('1 1/4')).toBeCloseTo(1.25);
+			expect(frac2Dec('2 1/2')).toBeCloseTo(2.5);
+			expect(frac2Dec('3 3/4')).toBeCloseTo(3.75);
 		});
 
 		it('should convert fraction without whole part to decimal', () => {
-			expect(fracToDec('3/4')).toBeCloseTo(0.75);
-			expect(fracToDec('1/2')).toBeCloseTo(0.5);
-			expect(fracToDec('1/10')).toBeCloseTo(0.1);
+			expect(frac2Dec('3/4')).toBeCloseTo(0.75);
+			expect(frac2Dec('1/2')).toBeCloseTo(0.5);
+			expect(frac2Dec('1/10')).toBeCloseTo(0.1);
 		});
 
 		it('should convert whole number fraction', () => {
-			expect(fracToDec('4 0/1')).toBeCloseTo(4);
-			expect(fracToDec('0/1')).toBeCloseTo(0);
+			expect(frac2Dec('4 0/1')).toBeCloseTo(4);
+			expect(frac2Dec('0/1')).toBeCloseTo(0);
 		});
 
 		it('should handle zero correctly', () => {
-			expect(fracToDec('0/1')).toBeCloseTo(0);
-			expect(fracToDec('0 0/1')).toBeCloseTo(0);
+			expect(frac2Dec('0/1')).toBeCloseTo(0);
+			expect(frac2Dec('0 0/1')).toBeCloseTo(0);
 		});
 	});
 });