@lumeweb/portal-framework-ui 0.0.1 → 0.1.1

package/dist/esm/utils/theme.js

@@ -0,0 +1,689 @@
+//#region src/utils/theme.ts
+/**
+* Adjusts the hue of a color by a given number of degrees.
+* Hue wraps around at 360.
+* @param color The Color object.
+* @param degrees The number of degrees to adjust the hue by.
+* @returns A new Color object.
+*/
+function adjustHue(color, degrees) {
+	let newHue = color.hue + degrees;
+	newHue = newHue % 360;
+	if (newHue < 0) newHue += 360;
+	return {
+		...color,
+		hue: newHue
+	};
+}
+/**
+* Applies the styles from a Theme object to the DOM.
+* This function manipulates the document head and root element class.
+* @param theme The Theme object to apply.
+*/
+function applyThemeStyles(theme) {
+	const css = generateThemeCSS(theme);
+	const style = document.createElement("style");
+	style.textContent = css;
+	const existingStyle = document.head.querySelector("style[data-theme]");
+	if (existingStyle) document.head.removeChild(existingStyle);
+	style.setAttribute("data-theme", theme.id);
+	document.head.appendChild(style);
+	document.documentElement.className = `theme-${theme.id}`;
+}
+/**
+* Creates default system colors for a light theme.
+*/
+function createDefaultSystemColors() {
+	return {
+		active_ui_element: {
+			hue: 0,
+			lightness: 80,
+			saturation: 0
+		},
+		background: {
+			hue: 0,
+			lightness: 100,
+			saturation: 0
+		},
+		borders: {
+			hue: 0,
+			lightness: 70,
+			saturation: 0
+		},
+		high_contrast_text: {
+			hue: 0,
+			lightness: 10,
+			saturation: 0
+		},
+		hovered_element_border: {
+			hue: 0,
+			lightness: 50,
+			saturation: 0
+		},
+		hovered_solid_bg: {
+			hue: 0,
+			lightness: 35,
+			saturation: 0
+		},
+		hovered_ui_element: {
+			hue: 0,
+			lightness: 85,
+			saturation: 0
+		},
+		low_contrast_text: {
+			hue: 0,
+			lightness: 30,
+			saturation: 0
+		},
+		solid_background: {
+			hue: 0,
+			lightness: 40,
+			saturation: 0
+		},
+		subtle_background: {
+			hue: 0,
+			lightness: 95,
+			saturation: 0
+		},
+		ui_element_background: {
+			hue: 0,
+			lightness: 90,
+			saturation: 0
+		},
+		ui_element_border: {
+			hue: 0,
+			lightness: 60,
+			saturation: 0
+		}
+	};
+}
+/**
+* Creates a default theme object.
+* This can be used as a fallback or starting point.
+*/
+function createDefaultTheme() {
+	return {
+		background_images: {
+			login: "",
+			register: "",
+			reset_password: ""
+		},
+		id: "default",
+		name: "Default Theme",
+		system_colors: createDefaultSystemColors()
+	};
+}
+/**
+* Creates a system colors object with all values at zero.
+* Useful for testing and reset operations.
+*/
+function createZeroSystemColors() {
+	return {
+		active_ui_element: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		background: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		borders: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		high_contrast_text: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		hovered_element_border: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		hovered_solid_bg: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		hovered_ui_element: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		low_contrast_text: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		solid_background: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		subtle_background: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		ui_element_background: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		},
+		ui_element_border: {
+			hue: 0,
+			lightness: 0,
+			saturation: 0
+		}
+	};
+}
+/**
+* Darkens a color by a given percentage.
+* @param color The Color object.
+* @param amount The percentage amount to darken by (0-100).
+* @returns A new Color object.
+*/
+function darkenColor(color, amount) {
+	const newLightness = clamp(color.lightness - amount, 0, 100);
+	return {
+		...color,
+		lightness: newLightness
+	};
+}
+/**
+* Desaturates a color by a given percentage.
+* @param color The Color object.
+* @param amount The percentage amount to desaturate by (0-100).
+* @returns A new Color object.
+*/
+function desaturateColor(color, amount) {
+	const newSaturation = clamp(color.saturation - amount, 0, 100);
+	return {
+		...color,
+		saturation: newSaturation
+	};
+}
+/**
+* Attempts to adjust theme colors to meet WCAG contrast requirements.
+* It iterates through common color pairs and adjusts lightness if contrast is insufficient.
+* Returns a new Theme object if changes were made, otherwise returns the original theme.
+* @param theme The Theme object to check and potentially adjust.
+* @param textLevel The desired WCAG level for text contrast ('AA' or 'AAA'). Defaults to 'AA'.
+* @param nonTextLevel The desired WCAG level for non-text contrast ('AA'). Defaults to 'AA'.
+* @returns A new Theme object with adjusted colors if needed, or the original theme.
+*/
+function ensureWcagContrast(theme, textLevel = "AA", nonTextLevel = "AA") {
+	const modifiedTheme = {
+		...theme,
+		systemColors: { ...theme.system_colors }
+	};
+	let changesMade = false;
+	const colors = modifiedTheme.systemColors;
+	for (const { bgKey, fgKey, type } of [
+		{
+			bgKey: "background",
+			fgKey: "high_contrast_text",
+			type: "text"
+		},
+		{
+			bgKey: "background",
+			fgKey: "low_contrast_text",
+			type: "text"
+		},
+		{
+			bgKey: "ui_element_background",
+			fgKey: "high_contrast_text",
+			type: "text"
+		},
+		{
+			bgKey: "ui_element_background",
+			fgKey: "low_contrast_text",
+			type: "text"
+		},
+		{
+			bgKey: "ui_element_background",
+			fgKey: "ui_element_border",
+			type: "non-text"
+		},
+		{
+			bgKey: "hovered_ui_element",
+			fgKey: "hovered_element_border",
+			type: "non-text"
+		},
+		{
+			bgKey: "ui_element_background",
+			fgKey: "active_ui_element",
+			type: "non-text"
+		},
+		{
+			bgKey: "background",
+			fgKey: "hovered_ui_element",
+			type: "non-text"
+		},
+		{
+			bgKey: "background",
+			fgKey: "solid_background",
+			type: "non-text"
+		},
+		{
+			bgKey: "solid_background",
+			fgKey: "hovered_solid_bg",
+			type: "non-text"
+		}
+	]) {
+		const fgColor = colors[fgKey];
+		const bgColor = colors[bgKey];
+		let needsAdjustment = false;
+		let requiredRatio;
+		if (type === "text") {
+			requiredRatio = textLevel === "AAA" ? 7 : 4.5;
+			if (!meetsWcagTextContrast(fgColor, bgColor, textLevel, false)) needsAdjustment = true;
+		} else {
+			requiredRatio = 3;
+			if (!meetsWcagNonTextContrast(fgColor, bgColor)) needsAdjustment = true;
+		}
+		if (needsAdjustment) {
+			changesMade = true;
+			console.warn(`WCAG Contrast Warning: Pair ${fgKey} vs ${bgKey} (Current Ratio: ${getContrastRatio(fgColor, bgColor)}) does not meet required ratio ${requiredRatio} for ${type === "text" ? textLevel + " Text" : "Non-text"}. Attempting to adjust.`);
+			rgbToLuminance(...hslToRgb(fgColor));
+			rgbToLuminance(...hslToRgb(bgColor));
+			let adjustedFg = { ...fgColor };
+			let adjustedBg = { ...bgColor };
+			let currentRatio = getContrastRatio(adjustedFg, adjustedBg);
+			const step = 1;
+			const maxAttempts = 200;
+			let attempts = 0;
+			let adjustingFg = true;
+			while (currentRatio < requiredRatio && attempts < maxAttempts) {
+				attempts++;
+				const currentFgLuminance = rgbToLuminance(...hslToRgb(adjustedFg));
+				const currentBgLuminance = rgbToLuminance(...hslToRgb(adjustedBg));
+				let adjustedThisIteration = false;
+				if (adjustingFg) {
+					const fgAdjustmentDirection = currentFgLuminance < currentBgLuminance ? -1 : 1;
+					const nextFgLightness = clamp(adjustedFg.lightness + fgAdjustmentDirection * step, 0, 100);
+					if (adjustedFg.lightness === nextFgLightness) adjustingFg = false;
+					else {
+						adjustedFg = {
+							...adjustedFg,
+							lightness: nextFgLightness
+						};
+						currentRatio = getContrastRatio(adjustedFg, adjustedBg);
+						adjustedThisIteration = true;
+					}
+				}
+				if (!adjustedThisIteration && !adjustingFg) {
+					const bgAdjustmentDirection = currentBgLuminance < currentFgLuminance ? 1 : -1;
+					const nextBgLightness = clamp(adjustedBg.lightness + bgAdjustmentDirection * step, 0, 100);
+					if (adjustedBg.lightness === nextBgLightness) break;
+					else {
+						adjustedBg = {
+							...adjustedBg,
+							lightness: nextBgLightness
+						};
+						currentRatio = getContrastRatio(adjustedFg, adjustedBg);
+						adjustedThisIteration = true;
+					}
+				}
+				if (!adjustedThisIteration) {
+					console.warn(`  WCAG Contrast Warning: Neither FG nor BG could be adjusted further for ${fgKey} vs ${bgKey}. Current Ratio: ${currentRatio}. Required: ${requiredRatio}. Stopping.`);
+					break;
+				}
+			}
+			modifiedTheme.systemColors[fgKey] = adjustedFg;
+			modifiedTheme.systemColors[bgKey] = adjustedBg;
+			if (getContrastRatio(adjustedFg, adjustedBg) < requiredRatio) console.warn(`WCAG Contrast Warning: Pair ${fgKey} vs ${bgKey} could not meet required ratio ${requiredRatio} after ${attempts} attempts. Final Ratio: ${getContrastRatio(adjustedFg, adjustedBg)}.`);
+		}
+	}
+	return changesMade ? modifiedTheme : theme;
+}
+/**
+* Generates CSS variable declarations for a given theme.
+* @param theme The Theme object.
+* @returns A CSS string with variable declarations.
+*/
+function generateThemeCSS(theme) {
+	const systemColors = theme?.system_colors && typeof theme.system_colors === "object" && !Array.isArray(theme.system_colors) ? theme.system_colors : {};
+	const backgroundImages = theme?.background_images && typeof theme.background_images === "object" && !Array.isArray(theme.background_images) ? theme.background_images : {};
+	const colorVariables = Object.entries(systemColors).map(([key, value]) => {
+		if (!isValidColor(value)) {
+			console.warn(`Skipping invalid color for key "${key}" in theme "${theme?.id}"`);
+			return "";
+		}
+		return `--theme-${key.replace(/_/g, "-")}: ${hslToRawString(value)};`;
+	}).filter((line) => line !== "").join("\n  ");
+	const backgroundImageVariables = Object.entries(backgroundImages).map(([key, value]) => {
+		if (typeof value !== "string") {
+			console.warn(`Skipping invalid background image URL for key "${key}" in theme "${theme?.id}"`);
+			return "";
+		}
+		return `--lume-bg-${key.replace(/_/g, "-")}: url("${value}");`;
+	}).filter((line) => line !== "").join("\n  ");
+	return `
+:root.theme-${theme?.id || "unknown"} {
+  ${colorVariables}
+  ${backgroundImageVariables}
+}
+`;
+}
+/**
+* Calculates the contrast ratio between two colors.
+* Based on WCAG 2.x guidelines.
+* @param color1 The first Color object.
+* @param color2 The second Color object.
+* @returns The contrast ratio (1 to 21).
+*/
+function getContrastRatio(color1, color2) {
+	const [r1, g1, b1] = hslToRgb(color1);
+	const [r2, g2, b2] = hslToRgb(color2);
+	const luminance1 = rgbToLuminance(r1, g1, b1);
+	const luminance2 = rgbToLuminance(r2, g2, b2);
+	const lighter = Math.max(luminance1, luminance2);
+	const darker = Math.min(luminance1, luminance2);
+	const ratio = (lighter + .05) / (darker + .05);
+	return Math.round(ratio * 100) / 100;
+}
+/**
+* Finds a specific theme by its ID from a list of themes.
+* @param themes The array of available themes.
+* @param themeId The ID of the theme to find.
+* @returns The found Theme object or undefined if not found.
+*/
+function getThemeById(themes, themeId) {
+	return themes.find((t) => t.id === themeId);
+}
+/**
+* Converts a Hex color string (#RRGGBB or #RGB) to an HSL Color object.
+* @param hex The hex color string.
+* @returns An HSL Color object or undefined if the hex string is invalid.
+*/
+function hexToHsl(hex) {
+	const hexMatch = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(hex);
+	if (!hexMatch) {
+		console.error(`Invalid hex color format: ${hex}`);
+		return;
+	}
+	let cleanHex = hexMatch[1];
+	if (cleanHex.length === 3) cleanHex = cleanHex[0] + cleanHex[0] + cleanHex[1] + cleanHex[1] + cleanHex[2] + cleanHex[2];
+	return rgbToHsl(parseInt(cleanHex.substring(0, 2), 16), parseInt(cleanHex.substring(2, 4), 16), parseInt(cleanHex.substring(4, 6), 16));
+}
+/**
+* Converts a Color object to raw HSL values as a string.
+* @param color The Color object.
+* @returns A string in the format "hue, saturation%, lightness%".
+*/
+function hslToRawString(color) {
+	return `${color.hue}, ${color.saturation}%, ${color.lightness}%`;
+}
+/**
+* Converts an HSL Color object to RGB values (0-255).
+* Needed for calculating luminance for contrast ratio.
+* @param color The HSL Color object.
+* @returns An array [r, g, b] with values in the range [0, 255].
+*/
+function hslToRgb(color) {
+	const h = color.hue / 360;
+	const s = color.saturation / 100;
+	const l = color.lightness / 100;
+	let b, g, r;
+	if (s === 0) r = g = b = l;
+	else {
+		const hue2rgb = (p, q, t) => {
+			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;
+		};
+		const q = l < .5 ? l * (1 + s) : l + s - l * s;
+		const p = 2 * l - q;
+		r = hue2rgb(p, q, h + 1 / 3);
+		g = hue2rgb(p, q, h);
+		b = hue2rgb(p, q, h - 1 / 3);
+	}
+	return [
+		Math.round(r * 255),
+		Math.round(g * 255),
+		Math.round(b * 255)
+	];
+}
+/**
+* Converts a Color object to a CSS HSL string.
+* @param color The Color object.
+* @returns A string in the format "hsl(hue, saturation%, lightness%)".
+*/
+function hslToString(color) {
+	return `hsl(${hslToRawString(color)})`;
+}
+/**
+* Checks if an object conforms to the BackgroundImages interface structure.
+* @param data The object to validate.
+* @returns True if the object is valid BackgroundImages, false otherwise.
+*/
+function isValidBackgroundImages(data) {
+	if (typeof data !== "object" || data === null) return false;
+	for (const key of [
+		"login",
+		"register",
+		"reset_password"
+	]) if (!Object.prototype.hasOwnProperty.call(data, key) || typeof data[key] !== "string") return false;
+	return true;
+}
+/**
+* Checks if an object conforms to the Color interface structure.
+* @param data The object to validate.
+* @returns True if the object is a valid Color, false otherwise.
+*/
+function isValidColor(data) {
+	return typeof data === "object" && data !== null && typeof data.hue === "number" && typeof data.saturation === "number" && typeof data.lightness === "number";
+}
+/**
+* Checks if an object conforms to the SystemColors interface structure.
+* @param data The object to validate.
+* @returns True if the object is valid SystemColors, false otherwise.
+*/
+function isValidSystemColors(data) {
+	if (typeof data !== "object" || data === null) return false;
+	for (const key of [
+		"active_ui_element",
+		"background",
+		"borders",
+		"high_contrast_text",
+		"hovered_element_border",
+		"hovered_solid_bg",
+		"hovered_ui_element",
+		"low_contrast_text",
+		"solid_background",
+		"subtle_background",
+		"ui_element_background",
+		"ui_element_border"
+	]) if (!Object.prototype.hasOwnProperty.call(data, key) || !isValidColor(data[key])) return false;
+	return true;
+}
+/**
+* Lightens a color by a given percentage.
+* @param color The Color object.
+* @param amount The percentage amount to lighten by (0-100).
+* @returns A new Color object.
+*/
+function lightenColor(color, amount) {
+	const newLightness = clamp(color.lightness + amount, 0, 100);
+	return {
+		...color,
+		lightness: newLightness
+	};
+}
+/**
+* Checks if the contrast ratio between two colors meets a specified WCAG level.
+* Assumes normal text size (not large text).
+* WCAG AA requires 4.5:1. WCAG AAA requires 7:1.
+* @param color1 The first Color object.
+* @param color2 The second Color object.
+* @param level The WCAG level to check against ('AA' or 'AAA').
+* @returns True if the contrast ratio meets the level, false otherwise.
+*/
+function meetsWcagContrast(color1, color2, level) {
+	return meetsWcagTextContrast(color1, color2, level, false);
+}
+/**
+* Checks if the contrast ratio between two colors meets the WCAG 2.1 SC 1.4.11 Non-text Contrast (AA) requirement.
+* This applies to graphical objects and user interface components.
+* @param color1 The first Color object (e.g., icon color, border color).
+* @param color2 The second Color object (e.g., adjacent background color).
+* @returns True if the contrast ratio is 3:1 or higher, false otherwise.
+*/
+function meetsWcagNonTextContrast(color1, color2) {
+	return getContrastRatio(color1, color2) >= 3;
+}
+/**
+* Checks if the contrast ratio between two colors meets a specified WCAG level for text.
+* WCAG 2.x/2.1 SC 1.4.3 (Minimum) and SC 1.4.6 (Enhanced).
+* @param color1 The first Color object (e.g., text color).
+* @param color2 The second Color object (e.g., background color).
+* @param level The WCAG level to check against ('AA' or 'AAA').
+* @param isLargeText True if the text is considered "large text" by WCAG definition.
+* @returns True if the contrast ratio meets the level for the given text size, false otherwise.
+*/
+function meetsWcagTextContrast(color1, color2, level, isLargeText) {
+	const ratio = getContrastRatio(color1, color2);
+	let requiredRatio;
+	if (isLargeText) requiredRatio = level === "AAA" ? 4.5 : 3;
+	else requiredRatio = level === "AAA" ? 7 : 4.5;
+	return ratio >= requiredRatio;
+}
+/**
+* Merges properties from an overrides object into a base theme object.
+* Performs a deep merge for systemColors and backgroundImages.
+* @param base The base Theme object.
+* @param overrides The partial Theme object with overrides.
+* @returns A new Theme object with overrides applied.
+*/
+function mergeThemes(base, overrides) {
+	const mergedTheme = { ...base };
+	if (overrides.name !== void 0) mergedTheme.name = overrides.name;
+	if (overrides.default !== void 0) mergedTheme.default = overrides.default;
+	if (overrides.system_colors) mergedTheme.system_colors = {
+		...base.system_colors,
+		...overrides.system_colors
+	};
+	if (overrides.background_images) mergedTheme.background_images = {
+		...base.background_images,
+		...overrides.background_images
+	};
+	return mergedTheme;
+}
+/**
+* Converts RGB values (0-255) to an HSL Color object.
+* @param r Red value (0-255).
+* @param g Green value (0-255).
+* @param b Blue value (0-255).
+* @returns An HSL Color object.
+*/
+function rgbToHsl(r, g, b) {
+	r = clamp(r, 0, 255);
+	g = clamp(g, 0, 255);
+	b = clamp(b, 0, 255);
+	const rNorm = r / 255;
+	const gNorm = g / 255;
+	const bNorm = b / 255;
+	const max = Math.max(rNorm, gNorm, bNorm);
+	const min = Math.min(rNorm, gNorm, bNorm);
+	let h = 0;
+	let s = 0;
+	const l = (max + min) / 2;
+	if (max !== min) {
+		const d = max - min;
+		s = l > .5 ? d / (2 - max - min) : d / (max + min);
+		switch (max) {
+			case bNorm:
+				h = (rNorm - gNorm) / d + 4;
+				break;
+			case gNorm:
+				h = (bNorm - rNorm) / d + 2;
+				break;
+			case rNorm:
+				h = (gNorm - bNorm) / d + (gNorm < bNorm ? 6 : 0);
+				break;
+		}
+		h /= 6;
+	}
+	const hue = Math.round(h * 360);
+	const saturation = Math.round(s * 100);
+	return {
+		hue,
+		lightness: Math.round(l * 100),
+		saturation
+	};
+}
+/**
+* Calculates the relative luminance of an RGB color.
+* Based on WCAG 2.x guidelines.
+* @param r Red value (0-255).
+* @param g Green value (0-255).
+* @param b Blue value (0-255).
+* @returns The relative luminance (0-1).
+*/
+function rgbToLuminance(r, g, b) {
+	const channelLuminance = (channel) => {
+		const srgb = channel / 255;
+		return srgb <= .03928 ? srgb / 12.92 : Math.pow((srgb + .055) / 1.055, 2.4);
+	};
+	const lumR = channelLuminance(r);
+	const lumG = channelLuminance(g);
+	const lumB = channelLuminance(b);
+	return .2126 * lumR + .7152 * lumG + .0722 * lumB;
+}
+/**
+* Saturates a color by a given percentage.
+* @param color The Color object.
+* @param amount The percentage amount to saturate by (0-100).
+* @returns A new Color object.
+*/
+function saturateColor(color, amount) {
+	const newSaturation = clamp(color.saturation + amount, 0, 100);
+	return {
+		...color,
+		saturation: newSaturation
+	};
+}
+/**
+* Validates if an object conforms to the Theme interface structure.
+* @param data The object to validate.
+* @returns True if the object is a valid Theme, false otherwise.
+*/
+function validateTheme(data) {
+	if (typeof data !== "object" || data === null) return false;
+	if (typeof data.id !== "string" || typeof data.name !== "string") return false;
+	if (!isValidSystemColors(data.systemColors)) return false;
+	if (!isValidBackgroundImages(data.backgroundImages)) return false;
+	if (data.default !== void 0 && typeof data.default !== "boolean") return false;
+	return true;
+}
+/**
+* Clamps a value between a minimum and maximum.
+* @param value The value to clamp.
+* @param min The minimum allowed value.
+* @param max The maximum allowed value.
+* @returns The clamped value.
+*/
+function clamp(value, min, max) {
+	return Math.max(min, Math.min(value, max));
+}
+/**
+* Merges properties from an overrides object into a base theme object.
+* Useful for applying partial theme customizations.
+* export function mergeThemes(base: Theme, overrides: Partial<Theme>): Theme { ... }
+*/
+/**
+* Validates if an object conforms to the Theme interface structure.
+* export function function validateTheme(theme: any): theme is Theme { ... }
+*/
+
+//#endregion
+export { adjustHue, applyThemeStyles, createDefaultSystemColors, createDefaultTheme, createZeroSystemColors, darkenColor, desaturateColor, ensureWcagContrast, generateThemeCSS, getContrastRatio, getThemeById, hexToHsl, hslToRawString, hslToRgb, hslToString, isValidBackgroundImages, isValidColor, isValidSystemColors, lightenColor, meetsWcagContrast, meetsWcagNonTextContrast, meetsWcagTextContrast, mergeThemes, rgbToHsl, rgbToLuminance, saturateColor, validateTheme };
+//# sourceMappingURL=theme.js.map