igniteui-theming 25.1.0 → 25.2.0

package/dist/mcp/utils/color.js

@@ -1,24 +1,63 @@
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
+import { themingImporter } from "./theming-resolve.js";
 import * as sass from "sass-embedded";
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-const PACKAGE_ROOT = path.resolve(__dirname$1, "..", "..", "..");
-const LUMINANCE_THRESHOLD = 0.5;
-const DEFAULT_MINIMUM_CONTRAST_RATIO = 3;
-const SUGGESTED_COLORS = {
-  light: {
-    surface: ["white", "#ffffff", "#f8f9fa", "#fafafa", "#f5f5f5"],
-    gray: ["black", "#000000", "#333333", "#212121", "#424242"]
-  },
-  dark: {
-    surface: ["#222222", "#1a1a1a", "#121212", "#181818", "#2d2d2d"],
-    gray: ["white", "#ffffff", "#e5e5e5", "#f5f5f5", "#eeeeee"]
-  }
+//#region src/utils/color.ts
+/**
+* Color analysis utilities using Sass-embedded.
+* Calls the actual Sass luminance() and contrast() functions for accurate validation.
+*/
+/**
+* Luminance threshold for determining light vs dark colors.
+* Colors with luminance > 0.5 are considered "light".
+* Colors with luminance <= 0.5 are considered "dark".
+*/
+var LUMINANCE_THRESHOLD = .5;
+/**
+* Suggested colors for different variants.
+*/
+var SUGGESTED_COLORS = {
+	light: {
+		surface: [
+			"white",
+			"#ffffff",
+			"#f8f9fa",
+			"#fafafa",
+			"#f5f5f5"
+		],
+		gray: [
+			"black",
+			"#000000",
+			"#333333",
+			"#212121",
+			"#424242"
+		]
+	},
+	dark: {
+		surface: [
+			"#222222",
+			"#1a1a1a",
+			"#121212",
+			"#181818",
+			"#2d2d2d"
+		],
+		gray: [
+			"white",
+			"#ffffff",
+			"#e5e5e5",
+			"#f5f5f5",
+			"#eeeeee"
+		]
+	}
 };
+/**
+* Analyze a single color using Sass luminance() function.
+*
+* @param color - CSS color value (hex, rgb, hsl, or named color)
+* @returns Color analysis with luminance and isLight flag
+* @throws Error if Sass compilation fails or color is invalid
+*/
 async function analyzeColor(color) {
-  const sassCode = `
-@use 'sass/color' as color;
+	const sassCode = `
+@use 'igniteui-theming/sass/color' as color;
 
 $lum: color.luminance(${color});
 
@@ -26,237 +65,236 @@ $lum: color.luminance(${color});
   --luminance: #{$lum};
 }
 `;
-  try {
-    const result = await sass.compileStringAsync(sassCode, {
-      loadPaths: [PACKAGE_ROOT]
-    });
-    const luminanceMatch = result.css.match(/--luminance:\s*([\d.]+)/);
-    if (!luminanceMatch) {
-      throw new Error(
-        `Could not parse luminance from Sass output for color: ${color}`
-      );
-    }
-    const luminance = Number.parseFloat(luminanceMatch[1]);
-    return {
-      color,
-      luminance,
-      isLight: luminance > LUMINANCE_THRESHOLD
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to analyze color "${color}": ${message}`);
-  }
+	try {
+		const luminanceMatch = (await sass.compileStringAsync(sassCode, { importers: [themingImporter] })).css.match(/--luminance:\s*([\d.]+)/);
+		if (!luminanceMatch) throw new Error(`Could not parse luminance from Sass output for color: ${color}`);
+		const luminance = Number.parseFloat(luminanceMatch[1]);
+		return {
+			color,
+			luminance,
+			isLight: luminance > LUMINANCE_THRESHOLD
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to analyze color "${color}": ${message}`);
+	}
 }
+/**
+* Analyze surface and gray colors together in a single Sass compilation.
+* This is more efficient than calling analyzeColor twice.
+*
+* @param params - Object containing surface and/or gray colors
+* @returns Combined analysis results
+*/
 async function analyzeSurfaceGrayColors(params) {
-  const { surface, gray } = params;
-  if (!surface && !gray) {
-    return {};
-  }
-  const sassLines = [`@use 'sass/color' as color;`, ""];
-  if (surface) {
-    sassLines.push(`$surface-lum: color.luminance(${surface});`);
-  }
-  if (gray) {
-    sassLines.push(`$gray-lum: color.luminance(${gray});`);
-  }
-  if (surface && gray) {
-    sassLines.push(`$contrast: color.contrast(${surface}, ${gray});`);
-  }
-  sassLines.push("", ":root {");
-  if (surface) {
-    sassLines.push("  --surface-luminance: #{$surface-lum};");
-  }
-  if (gray) {
-    sassLines.push("  --gray-luminance: #{$gray-lum};");
-  }
-  if (surface && gray) {
-    sassLines.push("  --contrast-ratio: #{$contrast};");
-  }
-  sassLines.push("}");
-  const sassCode = sassLines.join("\n");
-  try {
-    const result = await sass.compileStringAsync(sassCode, {
-      loadPaths: [PACKAGE_ROOT]
-    });
-    const analysis = {};
-    if (surface) {
-      const surfaceMatch = result.css.match(/--surface-luminance:\s*([\d.]+)/);
-      if (surfaceMatch) {
-        const luminance = Number.parseFloat(surfaceMatch[1]);
-        analysis.surface = {
-          color: surface,
-          luminance,
-          isLight: luminance > LUMINANCE_THRESHOLD
-        };
-      }
-    }
-    if (gray) {
-      const grayMatch = result.css.match(/--gray-luminance:\s*([\d.]+)/);
-      if (grayMatch) {
-        const luminance = Number.parseFloat(grayMatch[1]);
-        analysis.gray = {
-          color: gray,
-          luminance,
-          isLight: luminance > LUMINANCE_THRESHOLD
-        };
-      }
-    }
-    if (surface && gray) {
-      const contrastMatch = result.css.match(/--contrast-ratio:\s*([\d.]+)/);
-      if (contrastMatch) {
-        analysis.contrastRatio = Number.parseFloat(contrastMatch[1]);
-      }
-    }
-    return analysis;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to analyze surface/gray colors: ${message}`);
-  }
+	const { surface, gray } = params;
+	if (!surface && !gray) return {};
+	const sassLines = [`@use 'igniteui-theming/sass/color' as color;`, ""];
+	if (surface) sassLines.push(`$surface-lum: color.luminance(${surface});`);
+	if (gray) sassLines.push(`$gray-lum: color.luminance(${gray});`);
+	if (surface && gray) sassLines.push(`$contrast: color.contrast(${surface}, ${gray});`);
+	sassLines.push("", ":root {");
+	if (surface) sassLines.push("  --surface-luminance: #{$surface-lum};");
+	if (gray) sassLines.push("  --gray-luminance: #{$gray-lum};");
+	if (surface && gray) sassLines.push("  --contrast-ratio: #{$contrast};");
+	sassLines.push("}");
+	const sassCode = sassLines.join("\n");
+	try {
+		const result = await sass.compileStringAsync(sassCode, { importers: [themingImporter] });
+		const analysis = {};
+		if (surface) {
+			const surfaceMatch = result.css.match(/--surface-luminance:\s*([\d.]+)/);
+			if (surfaceMatch) {
+				const luminance = Number.parseFloat(surfaceMatch[1]);
+				analysis.surface = {
+					color: surface,
+					luminance,
+					isLight: luminance > LUMINANCE_THRESHOLD
+				};
+			}
+		}
+		if (gray) {
+			const grayMatch = result.css.match(/--gray-luminance:\s*([\d.]+)/);
+			if (grayMatch) {
+				const luminance = Number.parseFloat(grayMatch[1]);
+				analysis.gray = {
+					color: gray,
+					luminance,
+					isLight: luminance > LUMINANCE_THRESHOLD
+				};
+			}
+		}
+		if (surface && gray) {
+			const contrastMatch = result.css.match(/--contrast-ratio:\s*([\d.]+)/);
+			if (contrastMatch) analysis.contrastRatio = Number.parseFloat(contrastMatch[1]);
+		}
+		return analysis;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to analyze surface/gray colors: ${message}`);
+	}
 }
+/**
+* Check if a color is valid by attempting to analyze it.
+*
+* @param color - CSS color value to validate
+* @returns true if the color is valid, false otherwise
+*/
 async function isValidColor(color) {
-  try {
-    await analyzeColor(color);
-    return true;
-  } catch {
-    return false;
-  }
+	try {
+		await analyzeColor(color);
+		return true;
+	} catch {
+		return false;
+	}
 }
+/**
+* Validate multiple colors in a single Sass compilation for efficiency.
+* This is much faster than calling isValidColor() for each color individually.
+*
+* @param colors - Map of key names to color values
+* @returns Map of key names to validation results (true = valid, false = invalid)
+*/
 async function validateColorsInBatch(colors) {
-  const entries = Object.entries(colors);
-  if (entries.length === 0) {
-    return {};
-  }
-  const sassLines = [`@use 'sass:color';`, `@use 'sass:meta';`, ""];
-  for (const [key, colorValue] of entries) {
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-    sassLines.push(
-      `$${safeKey}-valid: meta.type-of(${colorValue}) == 'color';`
-    );
-  }
-  sassLines.push("", ":root {");
-  for (const [key] of entries) {
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-    sassLines.push(`  --${safeKey}-valid: #{$${safeKey}-valid};`);
-  }
-  sassLines.push("}");
-  const sassCode = sassLines.join("\n");
-  try {
-    const result = await sass.compileStringAsync(sassCode, {
-      loadPaths: [PACKAGE_ROOT]
-    });
-    const validationResults = {};
-    for (const [key] of entries) {
-      const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-      const validMatch = result.css.match(
-        new RegExp(`--${safeKey}-valid:\\s*(true|false)`)
-      );
-      validationResults[key] = validMatch ? validMatch[1] === "true" : false;
-    }
-    return validationResults;
-  } catch {
-    const validationResults = {};
-    for (const [key, colorValue] of entries) {
-      validationResults[key] = await isValidColor(colorValue);
-    }
-    return validationResults;
-  }
+	const entries = Object.entries(colors);
+	if (entries.length === 0) return {};
+	const sassLines = [
+		`@use 'sass:color';`,
+		`@use 'sass:meta';`,
+		""
+	];
+	for (const [key, colorValue] of entries) {
+		const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+		sassLines.push(`$${safeKey}-valid: meta.type-of(${colorValue}) == 'color';`);
+	}
+	sassLines.push("", ":root {");
+	for (const [key] of entries) {
+		const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+		sassLines.push(`  --${safeKey}-valid: #{$${safeKey}-valid};`);
+	}
+	sassLines.push("}");
+	const sassCode = sassLines.join("\n");
+	try {
+		const result = await sass.compileStringAsync(sassCode, { importers: [themingImporter] });
+		const validationResults = {};
+		for (const [key] of entries) {
+			const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+			const validMatch = result.css.match(new RegExp(`--${safeKey}-valid:\\s*(true|false)`));
+			validationResults[key] = validMatch ? validMatch[1] === "true" : false;
+		}
+		return validationResults;
+	} catch {
+		const validationResults = {};
+		for (const [key, colorValue] of entries) validationResults[key] = await isValidColor(colorValue);
+		return validationResults;
+	}
 }
-const DEFAULT_HUE_TOLERANCE = 30;
-function huesAreClose(hue1, hue2, tolerance = DEFAULT_HUE_TOLERANCE) {
-  const diff = Math.abs(hue1 - hue2);
-  const circularDiff = Math.min(diff, 360 - diff);
-  return circularDiff <= tolerance;
+/**
+* Check if two hue values are within tolerance of each other,
+* accounting for the circular nature of hue (0° = 360°).
+*
+* @param hue1 - First hue value (0-360)
+* @param hue2 - Second hue value (0-360)
+* @param tolerance - Maximum allowed difference in degrees (default: 30)
+* @returns true if hues are within tolerance
+*/
+function huesAreClose(hue1, hue2, tolerance = 30) {
+	const diff = Math.abs(hue1 - hue2);
+	return Math.min(diff, 360 - diff) <= tolerance;
 }
+/**
+* Analyze multiple colors in a single Sass compilation for efficiency.
+* Returns luminance and hue for each color.
+*
+* @param colors - Map of key names to color values
+* @returns Map of key names to analysis results
+*/
 async function analyzeColorsWithHue(colors) {
-  const entries = Object.entries(colors);
-  if (entries.length === 0) {
-    return {};
-  }
-  const sassLines = [`@use 'sass/color' as igColor;`, `@use 'sass:color';`, ""];
-  for (const [key, color] of entries) {
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-    sassLines.push(`$${safeKey}-lum: igColor.luminance(${color});`);
-    sassLines.push(
-      `$${safeKey}-hue: color.channel(${color}, "hue", $space: hsl);`
-    );
-  }
-  sassLines.push("", ":root {");
-  for (const [key] of entries) {
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-    sassLines.push(`  --${safeKey}-luminance: #{$${safeKey}-lum};`);
-    sassLines.push(`  --${safeKey}-hue: #{$${safeKey}-hue};`);
-  }
-  sassLines.push("}");
-  const sassCode = sassLines.join("\n");
-  try {
-    const result = await sass.compileStringAsync(sassCode, {
-      loadPaths: [PACKAGE_ROOT]
-    });
-    const analysis = {};
-    for (const [key] of entries) {
-      const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
-      const lumMatch = result.css.match(
-        new RegExp(`--${safeKey}-luminance:\\s*([\\d.]+)`)
-      );
-      const hueMatch = result.css.match(
-        new RegExp(`--${safeKey}-hue:\\s*([\\d.]+)`)
-      );
-      if (lumMatch && hueMatch) {
-        analysis[key] = {
-          luminance: Number.parseFloat(lumMatch[1]),
-          hue: Number.parseFloat(hueMatch[1])
-        };
-      }
-    }
-    return analysis;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to analyze colors: ${message}`);
-  }
+	const entries = Object.entries(colors);
+	if (entries.length === 0) return {};
+	const sassLines = [
+		`@use 'igniteui-theming/sass/color' as igColor;`,
+		`@use 'sass:color';`,
+		""
+	];
+	for (const [key, color] of entries) {
+		const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+		sassLines.push(`$${safeKey}-lum: igColor.luminance(${color});`);
+		sassLines.push(`$${safeKey}-hue: color.channel(${color}, "hue", $space: hsl);`);
+	}
+	sassLines.push("", ":root {");
+	for (const [key] of entries) {
+		const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+		sassLines.push(`  --${safeKey}-luminance: #{$${safeKey}-lum};`);
+		sassLines.push(`  --${safeKey}-hue: #{$${safeKey}-hue};`);
+	}
+	sassLines.push("}");
+	const sassCode = sassLines.join("\n");
+	try {
+		const result = await sass.compileStringAsync(sassCode, { importers: [themingImporter] });
+		const analysis = {};
+		for (const [key] of entries) {
+			const safeKey = key.replace(/[^a-zA-Z0-9]/g, "-");
+			const lumMatch = result.css.match(new RegExp(`--${safeKey}-luminance:\\s*([\\d.]+)`));
+			const hueMatch = result.css.match(new RegExp(`--${safeKey}-hue:\\s*([\\d.]+)`));
+			if (lumMatch && hueMatch) analysis[key] = {
+				luminance: Number.parseFloat(lumMatch[1]),
+				hue: Number.parseFloat(hueMatch[1])
+			};
+		}
+		return analysis;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to analyze colors: ${message}`);
+	}
 }
-const PALETTE_LUMINANCE_THRESHOLDS = {
-  /** Below this luminance, lighter shades (50-200) will lack contrast range */
-  TOO_DARK: 0.05,
-  /** Above this luminance, darker shades (600-900) will appear washed out */
-  TOO_LIGHT: 0.45
+/**
+* Luminance thresholds for palette shade generation suitability.
+* Colors outside this range may produce poor automatic shade generation results.
+*
+* Note: This is different from LUMINANCE_THRESHOLD (0.5) which determines
+* if a color is "light" or "dark" for variant matching. These thresholds
+* determine if a color can produce a good range of shades when used with
+* the palette() function.
+*
+* Based on color theory research:
+* - Optimal base color tone: 35-65 L* (CIELAB)
+* - Too light (L* > 70-75): darker shades compress together
+* - Too dark (L* < 25-30): lighter shades compress together
+*/
+var PALETTE_LUMINANCE_THRESHOLDS = {
+	TOO_DARK: .05,
+	TOO_LIGHT: .45
 };
+/**
+* Analyze whether a color is suitable for automatic shade generation.
+* Colors with extreme luminance (very light or very dark) may produce
+* poor results when using the palette() function's automatic shade generation.
+*
+* @param color - CSS color value (hex, rgb, hsl, or named color)
+* @returns Analysis result indicating suitability and any issues
+*/
 async function analyzeColorForPalette(color) {
-  const analysis = await analyzeColor(color);
-  if (analysis.luminance > PALETTE_LUMINANCE_THRESHOLDS.TOO_LIGHT) {
-    return {
-      color,
-      luminance: analysis.luminance,
-      suitable: false,
-      issue: "too-light",
-      description: `Luminance ${analysis.luminance.toFixed(2)} exceeds ${PALETTE_LUMINANCE_THRESHOLDS.TOO_LIGHT} - darker shades (600-900) will appear washed out`
-    };
-  }
-  if (analysis.luminance < PALETTE_LUMINANCE_THRESHOLDS.TOO_DARK) {
-    return {
-      color,
-      luminance: analysis.luminance,
-      suitable: false,
-      issue: "too-dark",
-      description: `Luminance ${analysis.luminance.toFixed(2)} is below ${PALETTE_LUMINANCE_THRESHOLDS.TOO_DARK} - lighter shades (50-200) will lack contrast range`
-    };
-  }
-  return {
-    color,
-    luminance: analysis.luminance,
-    suitable: true
-  };
+	const analysis = await analyzeColor(color);
+	if (analysis.luminance > PALETTE_LUMINANCE_THRESHOLDS.TOO_LIGHT) return {
+		color,
+		luminance: analysis.luminance,
+		suitable: false,
+		issue: "too-light",
+		description: `Luminance ${analysis.luminance.toFixed(2)} exceeds ${PALETTE_LUMINANCE_THRESHOLDS.TOO_LIGHT} - darker shades (600-900) will appear washed out`
+	};
+	if (analysis.luminance < PALETTE_LUMINANCE_THRESHOLDS.TOO_DARK) return {
+		color,
+		luminance: analysis.luminance,
+		suitable: false,
+		issue: "too-dark",
+		description: `Luminance ${analysis.luminance.toFixed(2)} is below ${PALETTE_LUMINANCE_THRESHOLDS.TOO_DARK} - lighter shades (50-200) will lack contrast range`
+	};
+	return {
+		color,
+		luminance: analysis.luminance,
+		suitable: true
+	};
 }
-export {
-  DEFAULT_HUE_TOLERANCE,
-  DEFAULT_MINIMUM_CONTRAST_RATIO,
-  LUMINANCE_THRESHOLD,
-  PALETTE_LUMINANCE_THRESHOLDS,
-  SUGGESTED_COLORS,
-  analyzeColor,
-  analyzeColorForPalette,
-  analyzeColorsWithHue,
-  analyzeSurfaceGrayColors,
-  huesAreClose,
-  isValidColor,
-  validateColorsInBatch
-};
+//#endregion
+export { LUMINANCE_THRESHOLD, SUGGESTED_COLORS, analyzeColorForPalette, analyzeColorsWithHue, analyzeSurfaceGrayColors, huesAreClose, validateColorsInBatch };

package/dist/mcp/utils/preprocessing.js

@@ -1,34 +1,61 @@
+//#region src/utils/preprocessing.ts
+/**
+* Recursively parse JSON strings in a value.
+*
+* This function handles cases where nested objects are passed as JSON strings
+* (e.g., from MCP Inspector text fields or MCP clients that send nested objects as strings).
+* It only attempts to parse strings that look like JSON objects or arrays (starting with `{` or `[`).
+*
+* @param value - The value to process
+* @returns The value with any JSON strings parsed into objects/arrays
+*
+* @example
+* // String that looks like JSON is parsed
+* deepParseJsonStrings('{"mode": "shades"}') // => { mode: 'shades' }
+*
+* // Regular strings are left as-is
+* deepParseJsonStrings('hello') // => 'hello'
+*
+* // Nested objects are processed recursively
+* deepParseJsonStrings({ primary: '{"mode": "shades"}' })
+* // => { primary: { mode: 'shades' } }
+*/
 function deepParseJsonStrings(value) {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
-      try {
-        const parsed = JSON.parse(trimmed);
-        return deepParseJsonStrings(parsed);
-      } catch {
-        return value;
-      }
-    }
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map(deepParseJsonStrings);
-  }
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([k, v]) => [k, deepParseJsonStrings(v)])
-    );
-  }
-  return value;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed.startsWith("{") || trimmed.startsWith("[")) try {
+			return deepParseJsonStrings(JSON.parse(trimmed));
+		} catch {
+			return value;
+		}
+		return value;
+	}
+	if (Array.isArray(value)) return value.map(deepParseJsonStrings);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, deepParseJsonStrings(v)]));
+	return value;
 }
+/**
+* Create a tool handler with automatic JSON string preprocessing.
+*
+* This wrapper ensures that nested objects passed as JSON strings (common when
+* using MCP Inspector) are properly parsed before schema validation.
+*
+* @param schema - The Zod schema for validating the tool's parameters
+* @param handler - The tool handler function
+* @returns A wrapped handler that preprocesses inputs before validation
+*
+* @example
+* server.registerTool(
+*   'create_custom_palette',
+*   { ... },
+*   withPreprocessing(createCustomPaletteSchema, handleCreateCustomPalette)
+* );
+*/
 function withPreprocessing(schema, handler) {
-  return async (rawParams) => {
-    const preprocessed = deepParseJsonStrings(rawParams);
-    const validated = schema.parse(preprocessed);
-    return handler(validated);
-  };
+	return async (rawParams) => {
+		const preprocessed = deepParseJsonStrings(rawParams);
+		return handler(schema.parse(preprocessed));
+	};
 }
-export {
-  deepParseJsonStrings,
-  withPreprocessing
-};
+//#endregion
+export { withPreprocessing };