@xivdyetools/core 1.3.7

package/dist/services/PresetService.js

@@ -0,0 +1,261 @@
+/**
+ * @xivdyetools/core - Preset Service
+ *
+ * Manages preset color palettes for FFXIV glamours.
+ * Provides themed color combinations for jobs, seasons, events, and aesthetics.
+ *
+ * @module services/PresetService
+ * @example
+ * ```typescript
+ * import { PresetService, presetData, DyeService, dyeDatabase } from '@xivdyetools/core';
+ *
+ * const presetService = new PresetService(presetData);
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Get all job presets
+ * const jobPresets = presetService.getPresetsByCategory('jobs');
+ *
+ * // Get a preset with resolved dye objects
+ * const rdmPreset = presetService.getPresetWithDyes('job-rdm', dyeService);
+ * ```
+ */
+/**
+ * Service for managing preset color palettes
+ *
+ * @example
+ * ```typescript
+ * const presetService = new PresetService(presetData);
+ *
+ * // List categories
+ * const categories = presetService.getCategories();
+ *
+ * // Get presets by category
+ * const jobPresets = presetService.getPresetsByCategory('jobs');
+ *
+ * // Search presets
+ * const results = presetService.searchPresets('red');
+ * ```
+ */
+export class PresetService {
+    /**
+     * Initialize the preset service with preset data
+     * @param presetData - Preset data object (import from presets.json)
+     */
+    constructor(presetData) {
+        this.data = presetData;
+        // Build lookup map for O(1) access by ID
+        this.presetById = new Map(this.data.palettes.map((p) => [p.id, p]));
+    }
+    // ============================================================================
+    // Category Operations
+    // ============================================================================
+    /**
+     * Get all preset categories with metadata
+     * @returns Array of category metadata with IDs
+     *
+     * @example
+     * ```typescript
+     * const categories = presetService.getCategories();
+     * // [{ id: 'jobs', name: 'FFXIV Jobs', description: '...', icon: '⚔️' }, ...]
+     * ```
+     */
+    getCategories() {
+        return Object.entries(this.data.categories).map(([id, meta]) => ({
+            id,
+            ...meta,
+        }));
+    }
+    /**
+     * Get metadata for a specific category
+     * @param category - Category identifier
+     * @returns Category metadata or undefined if not found
+     */
+    getCategoryMeta(category) {
+        return this.data.categories[category];
+    }
+    // ============================================================================
+    // Preset Retrieval
+    // ============================================================================
+    /**
+     * Get all presets
+     * @returns Array of all preset palettes
+     */
+    getAllPresets() {
+        return [...this.data.palettes];
+    }
+    /**
+     * Get all presets in a specific category
+     * @param category - Category to filter by
+     * @returns Array of presets in that category
+     *
+     * @example
+     * ```typescript
+     * const jobPresets = presetService.getPresetsByCategory('jobs');
+     * // Returns all job-themed presets (RDM, BLM, WHM, etc.)
+     * ```
+     */
+    getPresetsByCategory(category) {
+        return this.data.palettes.filter((p) => p.category === category);
+    }
+    /**
+     * Get a specific preset by ID
+     * @param id - Preset identifier (e.g., "job-rdm")
+     * @returns Preset or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const rdm = presetService.getPreset('job-rdm');
+     * if (rdm) {
+     *   console.log(rdm.name); // "Red Mage"
+     *   console.log(rdm.dyes); // [5738, 13115, 13117, 5729]
+     * }
+     * ```
+     */
+    getPreset(id) {
+        return this.presetById.get(id);
+    }
+    /**
+     * Get preset count by category
+     * @returns Map of category to preset count
+     */
+    getPresetCountByCategory() {
+        const counts = new Map();
+        for (const preset of this.data.palettes) {
+            counts.set(preset.category, (counts.get(preset.category) ?? 0) + 1);
+        }
+        return counts;
+    }
+    // ============================================================================
+    // Search Operations
+    // ============================================================================
+    /**
+     * Search presets by name or tags
+     * @param query - Search query (case-insensitive)
+     * @returns Array of matching presets
+     *
+     * @example
+     * ```typescript
+     * // Search by name
+     * const results = presetService.searchPresets('red');
+     * // Returns: Red Mage, Blood Red themed presets, etc.
+     *
+     * // Search by tag
+     * const tankResults = presetService.searchPresets('tank');
+     * // Returns: Paladin, Warrior, Dark Knight, Gunbreaker
+     * ```
+     */
+    searchPresets(query) {
+        const lowerQuery = query.toLowerCase().trim();
+        if (!lowerQuery) {
+            return [];
+        }
+        return this.data.palettes.filter((p) => p.name.toLowerCase().includes(lowerQuery) ||
+            p.description.toLowerCase().includes(lowerQuery) ||
+            p.tags.some((tag) => tag.toLowerCase().includes(lowerQuery)));
+    }
+    /**
+     * Search presets by tag (exact match)
+     * @param tag - Tag to search for (case-insensitive)
+     * @returns Array of presets with that tag
+     */
+    getPresetsByTag(tag) {
+        const lowerTag = tag.toLowerCase().trim();
+        return this.data.palettes.filter((p) => p.tags.some((t) => t.toLowerCase() === lowerTag));
+    }
+    // ============================================================================
+    // Random Selection
+    // ============================================================================
+    /**
+     * Get a random preset, optionally filtered by category
+     * @param category - Optional category to filter by
+     * @returns Random preset, or undefined if no presets exist
+     *
+     * @example
+     * ```typescript
+     * // Random from all presets
+     * const random = presetService.getRandomPreset();
+     *
+     * // Random job preset
+     * const randomJob = presetService.getRandomPreset('jobs');
+     * ```
+     */
+    getRandomPreset(category) {
+        const pool = category ? this.getPresetsByCategory(category) : this.data.palettes;
+        if (pool.length === 0) {
+            return undefined;
+        }
+        return pool[Math.floor(Math.random() * pool.length)];
+    }
+    // ============================================================================
+    // Dye Resolution (requires DyeService)
+    // ============================================================================
+    /**
+     * Get preset with resolved Dye objects
+     * Requires a DyeService instance to resolve dye IDs to full Dye objects
+     *
+     * @param id - Preset identifier
+     * @param dyeService - DyeService instance for resolving dye IDs
+     * @returns Resolved preset with full Dye objects, or undefined if preset not found
+     *
+     * @example
+     * ```typescript
+     * const dyeService = new DyeService(dyeDatabase);
+     * const resolved = presetService.getPresetWithDyes('job-rdm', dyeService);
+     *
+     * if (resolved) {
+     *   resolved.resolvedDyes.forEach(dye => {
+     *     if (dye) {
+     *       console.log(`${dye.name}: ${dye.hex}`);
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    getPresetWithDyes(id, dyeService) {
+        const preset = this.getPreset(id);
+        if (!preset) {
+            return undefined;
+        }
+        return {
+            ...preset,
+            resolvedDyes: preset.dyes.map((dyeId) => dyeService.getDyeById(dyeId)),
+        };
+    }
+    /**
+     * Resolve multiple presets with their Dye objects
+     * @param presets - Array of presets to resolve
+     * @param dyeService - DyeService instance for resolving dye IDs
+     * @returns Array of resolved presets
+     */
+    resolvePresets(presets, dyeService) {
+        return presets.map((preset) => ({
+            ...preset,
+            resolvedDyes: preset.dyes.map((dyeId) => dyeService.getDyeById(dyeId)),
+        }));
+    }
+    // ============================================================================
+    // Metadata
+    // ============================================================================
+    /**
+     * Get data version
+     * @returns Version string from preset data
+     */
+    getVersion() {
+        return this.data.version;
+    }
+    /**
+     * Get last update timestamp
+     * @returns ISO date string of last update
+     */
+    getLastUpdated() {
+        return this.data.lastUpdated;
+    }
+    /**
+     * Get total number of presets
+     * @returns Total preset count
+     */
+    getPresetCount() {
+        return this.data.palettes.length;
+    }
+}
+//# sourceMappingURL=PresetService.js.map

package/dist/services/PresetService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresetService.js","sourceRoot":"","sources":["../../src/services/PresetService.ts"],"names":[],"mappings":"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"}

package/dist/services/color/ColorAccessibility.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Color Accessibility
+ * Per R-4: Focused class for accessibility-related color operations
+ * Handles WCAG contrast, luminance, and text color optimization
+ */
+import type { HexColor } from '../../types/index.js';
+/**
+ * Color accessibility utilities
+ * Per R-4: Single Responsibility - accessibility operations only
+ */
+export declare class ColorAccessibility {
+    /**
+     * Calculate perceived luminance of a color (0-1)
+     * Uses relative luminance formula from WCAG
+     */
+    static getPerceivedLuminance(hex: string): number;
+    /**
+     * Calculate contrast ratio between two colors
+     * Returns 1 (no contrast) to 21 (maximum contrast)
+     */
+    static getContrastRatio(hex1: string, hex2: string): number;
+    /**
+     * Check if two colors meet WCAG AA contrast ratio (4.5:1 for small text, 3:1 for large)
+     */
+    static meetsWCAGAA(hex1: string, hex2: string, largeText?: boolean): boolean;
+    /**
+     * Check if two colors meet WCAG AAA contrast ratio (7:1 for small text, 4.5:1 for large)
+     */
+    static meetsWCAGAAA(hex1: string, hex2: string, largeText?: boolean): boolean;
+    /**
+     * Check if a color is light (for determining text color on background)
+     */
+    static isLightColor(hex: string): boolean;
+    /**
+     * Get optimal text color for a background color
+     */
+    static getOptimalTextColor(backgroundColor: string): HexColor;
+}
+//# sourceMappingURL=ColorAccessibility.d.ts.map

package/dist/services/color/ColorAccessibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorAccessibility.d.ts","sourceRoot":"","sources":["../../../src/services/color/ColorAccessibility.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIrD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAiBjD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAU3D;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO;IAKnF;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO;IAKpF;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzC;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,QAAQ;CAK9D"}

package/dist/services/color/ColorAccessibility.js

@@ -0,0 +1,71 @@
+/**
+ * Color Accessibility
+ * Per R-4: Focused class for accessibility-related color operations
+ * Handles WCAG contrast, luminance, and text color optimization
+ */
+import { createHexColor } from '../../types/index.js';
+import { ColorConverter } from './ColorConverter.js';
+/**
+ * Color accessibility utilities
+ * Per R-4: Single Responsibility - accessibility operations only
+ */
+export class ColorAccessibility {
+    /**
+     * Calculate perceived luminance of a color (0-1)
+     * Uses relative luminance formula from WCAG
+     */
+    static getPerceivedLuminance(hex) {
+        const rgb = ColorConverter.hexToRgb(hex);
+        // Convert to sRGB (linear RGB)
+        const toLinear = (c) => {
+            const cNorm = c / 255;
+            return cNorm <= 0.03928 ? cNorm / 12.92 : Math.pow((cNorm + 0.055) / 1.055, 2.4);
+        };
+        const r = toLinear(rgb.r);
+        const g = toLinear(rgb.g);
+        const b = toLinear(rgb.b);
+        // WCAG relative luminance formula
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    }
+    /**
+     * Calculate contrast ratio between two colors
+     * Returns 1 (no contrast) to 21 (maximum contrast)
+     */
+    static getContrastRatio(hex1, hex2) {
+        const lum1 = this.getPerceivedLuminance(hex1);
+        const lum2 = this.getPerceivedLuminance(hex2);
+        const lighter = Math.max(lum1, lum2);
+        const darker = Math.min(lum1, lum2);
+        return (lighter + 0.05) / (darker + 0.05);
+    }
+    /**
+     * Check if two colors meet WCAG AA contrast ratio (4.5:1 for small text, 3:1 for large)
+     */
+    static meetsWCAGAA(hex1, hex2, largeText = false) {
+        const ratio = this.getContrastRatio(hex1, hex2);
+        return ratio >= (largeText ? 3 : 4.5);
+    }
+    /**
+     * Check if two colors meet WCAG AAA contrast ratio (7:1 for small text, 4.5:1 for large)
+     */
+    static meetsWCAGAAA(hex1, hex2, largeText = false) {
+        const ratio = this.getContrastRatio(hex1, hex2);
+        return ratio >= (largeText ? 4.5 : 7);
+    }
+    /**
+     * Check if a color is light (for determining text color on background)
+     */
+    static isLightColor(hex) {
+        const luminance = this.getPerceivedLuminance(hex);
+        return luminance > 0.5;
+    }
+    /**
+     * Get optimal text color for a background color
+     */
+    static getOptimalTextColor(backgroundColor) {
+        return this.isLightColor(backgroundColor)
+            ? createHexColor('#000000')
+            : createHexColor('#FFFFFF');
+    }
+}
+//# sourceMappingURL=ColorAccessibility.js.map

package/dist/services/color/ColorAccessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorAccessibility.js","sourceRoot":"","sources":["../../../src/services/color/ColorAccessibility.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAW;QACtC,MAAM,GAAG,GAAG,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEzC,+BAA+B;QAC/B,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE;YACrC,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,CAAC;YACtB,OAAO,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC;QACnF,CAAC,CAAC;QAEF,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAE1B,kCAAkC;QAClC,OAAO,MAAM,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAY,EAAE,IAAY;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAE9C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEpC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,YAAqB,KAAK;QACvE,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAY,EAAE,IAAY,EAAE,YAAqB,KAAK;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,GAAW;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAClD,OAAO,SAAS,GAAG,GAAG,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,eAAuB;QAChD,OAAO,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC;YACvC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC;YAC3B,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/services/color/ColorConverter.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Color Converter
+ * Per R-4: Focused class for color format conversions
+ * Handles conversions between hex, RGB, and HSV color formats
+ */
+import type { RGB, HSV, HexColor } from '../../types/index.js';
+/**
+ * Configuration for ColorConverter caches
+ */
+export interface ColorConverterConfig {
+    cacheSize?: number;
+}
+/**
+ * Color format converter with LRU caching
+ * Per R-4: Single Responsibility - format conversions only
+ *
+ * Refactored for testability: Supports dependency injection of cache configuration
+ */
+export declare class ColorConverter {
+    private readonly hexToRgbCache;
+    private readonly rgbToHexCache;
+    private readonly rgbToHsvCache;
+    private readonly hsvToRgbCache;
+    private readonly hexToHsvCache;
+    private static defaultInstance;
+    /**
+     * Constructor with optional cache configuration
+     * @param config Configuration for cache sizes (default: 1000 entries per cache)
+     */
+    constructor(config?: ColorConverterConfig);
+    /**
+     * Get the default singleton instance
+     * Per Issue #6: Returns eagerly-initialized instance to avoid race conditions
+     */
+    private static getDefault;
+    /**
+     * Clear all caches (useful for testing or memory management)
+     */
+    clearCaches(): void;
+    /**
+     * Static method: Clear all caches of the default instance
+     */
+    static clearCaches(): void;
+    /**
+     * Get cache statistics (for monitoring)
+     */
+    getCacheStats(): {
+        hexToRgb: number;
+        rgbToHex: number;
+        rgbToHsv: number;
+        hsvToRgb: number;
+        hexToHsv: number;
+    };
+    /**
+     * Static method: Get cache statistics from default instance
+     */
+    static getCacheStats(): {
+        hexToRgb: number;
+        rgbToHex: number;
+        rgbToHsv: number;
+        hsvToRgb: number;
+        hexToHsv: number;
+    };
+    /**
+     * Convert hexadecimal color to RGB
+     * Per P-1: Cached for performance
+     * @example hexToRgb("#FF0000") -> { r: 255, g: 0, b: 0 }
+     */
+    hexToRgb(hex: string): RGB;
+    /**
+     * Static method: Convert hex to RGB using default instance
+     */
+    static hexToRgb(hex: string): RGB;
+    /**
+     * Convert RGB to hexadecimal color
+     * Per P-1: Cached for performance
+     * @example rgbToHex(255, 0, 0) -> "#FF0000"
+     */
+    rgbToHex(r: number, g: number, b: number): HexColor;
+    /**
+     * Static method: Convert RGB to hex using default instance
+     */
+    static rgbToHex(r: number, g: number, b: number): HexColor;
+    /**
+     * Convert RGB to HSV
+     * Per P-1: Cached for performance, optimized single-pass min/max
+     * @example rgbToHsv(255, 0, 0) -> { h: 0, s: 100, v: 100 }
+     */
+    rgbToHsv(r: number, g: number, b: number): HSV;
+    /**
+     * Static method: Convert RGB to HSV using default instance
+     */
+    static rgbToHsv(r: number, g: number, b: number): HSV;
+    /**
+     * Normalize hue to [0, 360) range.
+     * CORE-BUG-001: Ensures consistent cache keys for equivalent hue values
+     * (e.g., h=359.9999 and h=0.0001 both produce similar cache keys after rounding)
+     * Also handles negative values and values >= 360.
+     */
+    private normalizeHue;
+    /**
+     * Convert HSV to RGB
+     * Per P-1: Cached for performance
+     * @example hsvToRgb(0, 100, 100) -> { r: 255, g: 0, b: 0 }
+     */
+    hsvToRgb(h: number, s: number, v: number): RGB;
+    /**
+     * Static method: Convert HSV to RGB using default instance
+     */
+    static hsvToRgb(h: number, s: number, v: number): RGB;
+    /**
+     * Convert hex to HSV
+     * Per P-1: Cached for performance
+     */
+    hexToHsv(hex: string): HSV;
+    /**
+     * Static method: Convert hex to HSV using default instance
+     */
+    static hexToHsv(hex: string): HSV;
+    /**
+     * Convert HSV to hex
+     */
+    hsvToHex(h: number, s: number, v: number): HexColor;
+    /**
+     * Static method: Convert HSV to hex using default instance
+     */
+    static hsvToHex(h: number, s: number, v: number): HexColor;
+    /**
+     * Normalize a hex color to #RRGGBB format
+     */
+    normalizeHex(hex: string): HexColor;
+    /**
+     * Static method: Normalize hex using default instance
+     */
+    static normalizeHex(hex: string): HexColor;
+    /**
+     * Calculate Euclidean distance between two RGB colors
+     * Returns 0 for identical colors, ~441.67 for white vs black
+     */
+    getColorDistance(hex1: string, hex2: string): number;
+    /**
+     * Static method: Calculate color distance using default instance
+     */
+    static getColorDistance(hex1: string, hex2: string): number;
+}
+//# sourceMappingURL=ColorConverter.d.ts.map

package/dist/services/color/ColorConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorConverter.d.ts","sourceRoot":"","sources":["../../../src/services/color/ColorConverter.ts"],"names":[],"mappings":"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"}