@lumeweb/portal-framework-ui 0.0.1 → 0.1.1

package/dist/esm/utils/index.js

@@ -0,0 +1,5 @@
+import { 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 } from "./theme.js";
+import { runWhenIdle } from "./asyncUtils.js";
+import { formatFileSize } from "./fileSize.js";
+
+export { adjustHue, applyThemeStyles, createDefaultSystemColors, createDefaultTheme, createZeroSystemColors, darkenColor, desaturateColor, ensureWcagContrast, formatFileSize, generateThemeCSS, getContrastRatio, getThemeById, hexToHsl, hslToRawString, hslToRgb, hslToString, isValidBackgroundImages, isValidColor, isValidSystemColors, lightenColor, meetsWcagContrast, meetsWcagNonTextContrast, meetsWcagTextContrast, mergeThemes, rgbToHsl, rgbToLuminance, runWhenIdle, saturateColor, validateTheme };

package/dist/esm/utils/theme.d.ts

@@ -0,0 +1,197 @@
+import { BackgroundImages, Color, SystemColors, Theme } from "../types/theme.js";
+
+//#region src/utils/theme.d.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.
+ */
+declare function adjustHue(color: Color, degrees: number): Color;
+/**
+ * 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.
+ */
+declare function applyThemeStyles(theme: Theme): void;
+/**
+ * Creates default system colors for a light theme.
+ */
+declare function createDefaultSystemColors(): SystemColors;
+/**
+ * Creates a default theme object.
+ * This can be used as a fallback or starting point.
+ */
+declare function createDefaultTheme(): Theme;
+/**
+ * Creates a system colors object with all values at zero.
+ * Useful for testing and reset operations.
+ */
+declare function createZeroSystemColors(): SystemColors;
+/**
+ * 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.
+ */
+declare function darkenColor(color: Color, amount: number): Color;
+/**
+ * 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.
+ */
+declare function desaturateColor(color: Color, amount: number): Color;
+/**
+ * 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.
+ */
+declare function ensureWcagContrast(theme: Theme, textLevel?: "AA" | "AAA", nonTextLevel?: "AA"): Theme;
+/**
+ * Generates CSS variable declarations for a given theme.
+ * @param theme The Theme object.
+ * @returns A CSS string with variable declarations.
+ */
+declare function generateThemeCSS(theme: Theme): string;
+/**
+ * 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).
+ */
+declare function getContrastRatio(color1: Color, color2: Color): number;
+/**
+ * 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.
+ */
+declare function getThemeById(themes: Theme[], themeId: string): Theme | undefined;
+/**
+ * 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.
+ */
+declare function hexToHsl(hex: string): Color | undefined;
+/**
+ * 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%".
+ */
+declare function hslToRawString(color: Color): string;
+/**
+ * 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].
+ */
+declare function hslToRgb(color: Color): [number, number, number];
+/**
+ * Converts a Color object to a CSS HSL string.
+ * @param color The Color object.
+ * @returns A string in the format "hsl(hue, saturation%, lightness%)".
+ */
+declare function hslToString(color: Color): string;
+/**
+ * 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.
+ */
+declare function isValidBackgroundImages(data: any): data is BackgroundImages;
+/**
+ * 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.
+ */
+declare function isValidColor(data: any): data is Color;
+/**
+ * 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.
+ */
+declare function isValidSystemColors(data: any): data is SystemColors;
+/**
+ * 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.
+ */
+declare function lightenColor(color: Color, amount: number): Color;
+/**
+ * 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.
+ */
+declare function meetsWcagContrast(color1: Color, color2: Color, level: "AA" | "AAA"): boolean;
+/**
+ * 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.
+ */
+declare function meetsWcagNonTextContrast(color1: Color, color2: Color): boolean;
+/**
+ * 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.
+ */
+declare function meetsWcagTextContrast(color1: Color, color2: Color, level: "AA" | "AAA", isLargeText: boolean): boolean;
+/**
+ * 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.
+ */
+declare function mergeThemes(base: Theme, overrides: Partial<Theme & {
+  system_colors?: Partial<SystemColors>;
+}>): Theme;
+/**
+ * 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.
+ */
+declare function rgbToHsl(r: number, g: number, b: number): Color;
+/**
+ * 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).
+ */
+declare function rgbToLuminance(r: number, g: number, b: number): number;
+/**
+ * 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.
+ */
+declare function saturateColor(color: Color, amount: number): Color;
+/**
+ * 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.
+ */
+declare function validateTheme(data: any): data 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.d.ts.map