@xivdyetools/core 1.3.7

package/dist/services/LocalizationService.js

@@ -0,0 +1,449 @@
+/**
+ * LocalizationService - Facade for localization functionality
+ *
+ * Per R-4: Facade pattern - delegates to focused service classes
+ * Provides multi-language support with lazy loading and fallback chains
+ *
+ * @module services
+ */
+import { LocaleLoader } from './localization/LocaleLoader.js';
+import { LocaleRegistry } from './localization/LocaleRegistry.js';
+import { TranslationProvider } from './localization/TranslationProvider.js';
+// ============================================================================
+// Pure Utility Functions (Extracted for testability)
+// ============================================================================
+/**
+ * List of supported locale codes
+ */
+export const SUPPORTED_LOCALES = [
+    'en',
+    'ja',
+    'de',
+    'fr',
+    'ko',
+    'zh',
+];
+/**
+ * Extract 2-letter locale code from longer locale strings
+ * Pure function - no side effects, easy to test
+ *
+ * @param locale - Locale string (e.g., 'en-US', 'ja', 'de-DE')
+ * @returns 2-letter locale code or null
+ *
+ * @example
+ * ```typescript
+ * extractLocaleCode('en-US') // 'en'
+ * extractLocaleCode('ja') // 'ja'
+ * extractLocaleCode('zh-CN') // null (not supported)
+ * ```
+ */
+export function extractLocaleCode(locale) {
+    const code = locale.split('-')[0].toLowerCase();
+    return SUPPORTED_LOCALES.includes(code) ? code : null;
+}
+/**
+ * Resolve locale from preference chain
+ * Pure function - determines locale based on priority without side effects
+ *
+ * Priority: explicit > guild > system > fallback
+ *
+ * @param preference - Locale preference with fallback chain
+ * @returns Resolved locale code
+ *
+ * @example
+ * ```typescript
+ * resolveLocaleFromPreference({
+ *     explicit: 'de',
+ *     guild: 'ja',
+ *     system: 'en-US',
+ *     fallback: 'en'
+ * }); // Returns 'de' (highest priority)
+ *
+ * resolveLocaleFromPreference({
+ *     explicit: null,
+ *     guild: 'ja-JP',
+ *     system: 'en',
+ *     fallback: 'en'
+ * }); // Returns 'ja' (extracted from guild)
+ * ```
+ */
+export function resolveLocaleFromPreference(preference) {
+    // 1. Try explicit user selection (highest priority)
+    if (preference.explicit && SUPPORTED_LOCALES.includes(preference.explicit)) {
+        return preference.explicit;
+    }
+    // 2. Try guild/server preference
+    if (preference.guild) {
+        const guildLocale = extractLocaleCode(preference.guild);
+        if (guildLocale && SUPPORTED_LOCALES.includes(guildLocale)) {
+            return guildLocale;
+        }
+    }
+    // 3. Try user's system language
+    if (preference.system) {
+        const systemLocale = extractLocaleCode(preference.system);
+        if (systemLocale && SUPPORTED_LOCALES.includes(systemLocale)) {
+            return systemLocale;
+        }
+    }
+    // 4. Fallback
+    return preference.fallback;
+}
+/**
+ * LocalizationService - Main entry point for localization features
+ *
+ * Refactored for testability: Supports dependency injection of loader, registry, and translator
+ *
+ * @example Basic usage (static API)
+ * ```typescript
+ * import { LocalizationService } from 'xivdyetools-core';
+ *
+ * // Set locale (lazy loads locale data)
+ * await LocalizationService.setLocale('ja');
+ *
+ * // Get localized label
+ * const label = LocalizationService.getLabel('dye'); // "カララント:"
+ *
+ * // Get localized dye name
+ * const dyeName = LocalizationService.getDyeName(5729); // "スノウホワイト"
+ * ```
+ *
+ * @example Instance-based usage for testing
+ * ```typescript
+ * const mockLoader = new MockLocaleLoader();
+ * const service = new LocalizationService({ loader: mockLoader });
+ * await service.setLocale('ja');
+ * ```
+ *
+ * @example Discord bot locale resolution
+ * ```typescript
+ * const preference: LocalePreference = {
+ *     explicit: interaction.options.getString('language'),
+ *     guild: interaction.guildLocale,
+ *     system: interaction.locale,
+ *     fallback: 'en'
+ * };
+ * await LocalizationService.setLocaleFromPreference(preference);
+ * ```
+ */
+export class LocalizationService {
+    /**
+     * Constructor with optional dependency injection
+     * @param config Configuration with optional loader, registry, and translator
+     */
+    constructor(config = {}) {
+        this.currentLocale = 'en';
+        this.isInitialized = false;
+        this.loader = config.loader || new LocaleLoader();
+        this.registry = config.registry || new LocaleRegistry();
+        this.translator = config.translator || new TranslationProvider(this.registry);
+    }
+    /**
+     * Get the default singleton instance
+     * Per Issue #6: Returns eagerly-initialized instance to avoid race conditions
+     */
+    static getDefault() {
+        return this.defaultInstance;
+    }
+    /**
+     * Set active locale (loads locale file if not cached)
+     *
+     * @param locale - Locale code ('en', 'ja', 'de', 'fr')
+     * @throws {AppError} If locale file fails to load
+     *
+     * @example
+     * ```typescript
+     * await service.setLocale('ja');
+     * console.log(service.getCurrentLocale()); // 'ja'
+     * ```
+     */
+    async setLocale(locale) {
+        // Check if already loaded
+        if (this.registry.hasLocale(locale)) {
+            this.currentLocale = locale;
+            this.isInitialized = true;
+            return;
+        }
+        // Load locale data (synchronous as of v1.1.3, async signature kept for API compatibility)
+        await Promise.resolve(); // Satisfy async requirement while maintaining sync behavior
+        const localeData = this.loader.loadLocale(locale);
+        this.registry.registerLocale(localeData);
+        this.currentLocale = locale;
+        this.isInitialized = true;
+    }
+    /**
+     * Static method: Set locale using default instance
+     */
+    static async setLocale(locale) {
+        return this.getDefault().setLocale(locale);
+    }
+    /**
+     * Set locale from preference object with priority chain
+     * Uses pure function resolveLocaleFromPreference for resolution logic
+     *
+     * Priority: explicit > guild > system > fallback
+     *
+     * @param preference - Locale preference with fallback chain
+     *
+     * @example
+     * ```typescript
+     * // Discord bot usage
+     * await service.setLocaleFromPreference({
+     *     explicit: 'de',     // User selected German
+     *     guild: 'ja',        // Server is Japanese
+     *     system: 'en-US',    // User's system is English
+     *     fallback: 'en'
+     * });
+     * // Sets locale to 'de' (highest priority)
+     * ```
+     */
+    async setLocaleFromPreference(preference) {
+        const locale = resolveLocaleFromPreference(preference);
+        await this.setLocale(locale);
+    }
+    /**
+     * Static method: Set locale from preference using default instance
+     */
+    static async setLocaleFromPreference(preference) {
+        return this.getDefault().setLocaleFromPreference(preference);
+    }
+    /**
+     * Get current active locale
+     *
+     * @returns Current locale code
+     *
+     * @example
+     * ```typescript
+     * console.log(service.getCurrentLocale()); // 'ja'
+     * ```
+     */
+    getCurrentLocale() {
+        return this.currentLocale;
+    }
+    /**
+     * Static method: Get current locale from default instance
+     */
+    static getCurrentLocale() {
+        return this.getDefault().getCurrentLocale();
+    }
+    /**
+     * Check if service is initialized with a locale
+     *
+     * @returns true if locale data is loaded
+     *
+     * @example
+     * ```typescript
+     * if (!service.isLocaleLoaded()) {
+     *     await service.setLocale('en');
+     * }
+     * ```
+     */
+    isLocaleLoaded() {
+        return this.isInitialized;
+    }
+    /**
+     * Static method: Check if locale is loaded in default instance
+     */
+    static isLocaleLoaded() {
+        return this.getDefault().isLocaleLoaded();
+    }
+    /**
+     * Get localized UI label (with fallback to English)
+     *
+     * @param key - Translation key
+     * @returns Localized label
+     */
+    getLabel(key) {
+        return this.translator.getLabel(key, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized label using default instance
+     */
+    static getLabel(key) {
+        return this.getDefault().getLabel(key);
+    }
+    /**
+     * Get localized dye name by itemID
+     *
+     * @param itemID - Dye item ID (5729-48227)
+     * @returns Localized name or null if not found
+     */
+    getDyeName(itemID) {
+        return this.translator.getDyeName(itemID, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized dye name using default instance
+     */
+    static getDyeName(itemID) {
+        return this.getDefault().getDyeName(itemID);
+    }
+    /**
+     * Get localized category name
+     *
+     * @param category - Category key (e.g., "Reds", "Blues")
+     * @returns Localized category name
+     */
+    getCategory(category) {
+        return this.translator.getCategory(category, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized category using default instance
+     */
+    static getCategory(category) {
+        return this.getDefault().getCategory(category);
+    }
+    /**
+     * Get localized acquisition method
+     *
+     * @param acquisition - Acquisition key (e.g., "Dye Vendor", "Crafting")
+     * @returns Localized acquisition method
+     */
+    getAcquisition(acquisition) {
+        return this.translator.getAcquisition(acquisition, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized acquisition using default instance
+     */
+    static getAcquisition(acquisition) {
+        return this.getDefault().getAcquisition(acquisition);
+    }
+    /**
+     * Get all metallic dye IDs (for exclusion filtering)
+     *
+     * @returns Array of metallic dye item IDs
+     */
+    getMetallicDyeIds() {
+        return this.translator.getMetallicDyeIds(this.currentLocale);
+    }
+    /**
+     * Static method: Get metallic dye IDs using default instance
+     */
+    static getMetallicDyeIds() {
+        return this.getDefault().getMetallicDyeIds();
+    }
+    /**
+     * Get localized harmony type name
+     *
+     * @param key - Harmony type key
+     * @returns Localized harmony type
+     */
+    getHarmonyType(key) {
+        return this.translator.getHarmonyType(key, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized harmony type using default instance
+     */
+    static getHarmonyType(key) {
+        return this.getDefault().getHarmonyType(key);
+    }
+    /**
+     * Get localized vision type name
+     *
+     * @param key - Vision type key
+     * @returns Localized vision type
+     */
+    getVisionType(key) {
+        return this.translator.getVisionType(key, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized vision type using default instance
+     */
+    static getVisionType(key) {
+        return this.getDefault().getVisionType(key);
+    }
+    /**
+     * Get localized job name
+     *
+     * @param key - Job key
+     * @returns Localized job name
+     */
+    getJobName(key) {
+        return this.translator.getJobName(key, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized job name using default instance
+     */
+    static getJobName(key) {
+        return this.getDefault().getJobName(key);
+    }
+    /**
+     * Get localized Grand Company name
+     *
+     * @param key - Grand Company key
+     * @returns Localized Grand Company name
+     */
+    getGrandCompanyName(key) {
+        return this.translator.getGrandCompanyName(key, this.currentLocale);
+    }
+    /**
+     * Static method: Get localized Grand Company name using default instance
+     */
+    static getGrandCompanyName(key) {
+        return this.getDefault().getGrandCompanyName(key);
+    }
+    /**
+     * Get all available locale codes
+     *
+     * @returns Array of supported locale codes
+     */
+    getAvailableLocales() {
+        return [...SUPPORTED_LOCALES];
+    }
+    /**
+     * Static method: Get available locales
+     */
+    static getAvailableLocales() {
+        return [...SUPPORTED_LOCALES];
+    }
+    /**
+     * Preload multiple locales for instant switching
+     * Useful for apps that need to switch locales without delay
+     *
+     * @param locales - Array of locale codes to preload
+     */
+    async preloadLocales(locales) {
+        await Promise.all(locales.map((locale) => this.setLocale(locale)));
+    }
+    /**
+     * Static method: Preload locales using default instance
+     */
+    static async preloadLocales(locales) {
+        return this.getDefault().preloadLocales(locales);
+    }
+    /**
+     * Clear all loaded locales from cache
+     * Useful for testing or memory management
+     */
+    clear() {
+        this.registry.clear();
+        this.currentLocale = 'en';
+        this.isInitialized = false;
+    }
+    /**
+     * Static method: Clear cache of default instance
+     */
+    static clear() {
+        this.getDefault().clear();
+    }
+    /**
+     * Reset the static singleton instance
+     * Useful for testing to prevent test pollution between test suites
+     * Per Issue #6: Creates a fresh instance since we use eager initialization
+     *
+     * @example
+     * ```typescript
+     * // In test cleanup
+     * afterEach(() => {
+     *     LocalizationService.resetInstance();
+     * });
+     * ```
+     */
+    static resetInstance() {
+        this.defaultInstance.clear();
+        this.defaultInstance = new LocalizationService();
+    }
+}
+// Default singleton instance for static API compatibility
+// Per Issue #6: Eager initialization to avoid race conditions in concurrent scenarios
+LocalizationService.defaultInstance = new LocalizationService();
+//# sourceMappingURL=LocalizationService.js.map

package/dist/services/LocalizationService.js.map

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

package/dist/services/PaletteService.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @xivdyetools/core - Palette Extraction Service
+ *
+ * Extracts dominant colors from pixel data using K-means clustering.
+ * Matches extracted colors to closest FFXIV dyes.
+ *
+ * @module services/PaletteService
+ * @example
+ * ```typescript
+ * import { PaletteService, DyeService, dyeDatabase } from '@xivdyetools/core';
+ *
+ * const paletteService = new PaletteService();
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Extract 4 dominant colors from pixel data
+ * const palette = paletteService.extractPalette(pixels, 4);
+ *
+ * // Extract and match to dyes in one step
+ * const matches = paletteService.extractAndMatchPalette(pixels, 4, dyeService);
+ * ```
+ */
+import type { RGB, Dye, Logger } from '../types/index.js';
+import type { DyeService } from './DyeService.js';
+/**
+ * Options for palette extraction
+ */
+export interface PaletteExtractionOptions {
+    /** Number of colors to extract (3-5, default: 4) */
+    colorCount?: number;
+    /** Maximum K-means iterations (default: 25) */
+    maxIterations?: number;
+    /** Convergence threshold in RGB distance (default: 1.0) */
+    convergenceThreshold?: number;
+    /** Maximum pixels to sample (default: 10000) */
+    maxSamples?: number;
+}
+/**
+ * An extracted color with its dominance (cluster size)
+ */
+export interface ExtractedColor {
+    /** The extracted RGB color (cluster centroid) */
+    color: RGB;
+    /** Percentage of pixels in this cluster (0-100) */
+    dominance: number;
+    /** Number of pixels in this cluster */
+    pixelCount: number;
+}
+/**
+ * A matched palette entry with extracted and matched dye
+ */
+export interface PaletteMatch {
+    /** The extracted RGB color */
+    extracted: RGB;
+    /** The closest matching FFXIV dye */
+    matchedDye: Dye;
+    /** Color distance between extracted and matched (lower is better) */
+    distance: number;
+    /** Percentage of pixels in this cluster (0-100) */
+    dominance: number;
+}
+/**
+ * Configuration options for PaletteService
+ */
+export interface PaletteServiceOptions {
+    /** Logger for service operations (defaults to NoOpLogger) */
+    logger?: Logger;
+}
+/**
+ * Service for extracting color palettes from images
+ *
+ * Uses K-means clustering to find dominant colors, then matches
+ * them to the closest FFXIV dyes.
+ */
+export declare class PaletteService {
+    private logger;
+    /** Default extraction options */
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Create a new PaletteService
+     * @param options - Optional configuration including logger
+     */
+    constructor(options?: PaletteServiceOptions);
+    /**
+     * Sample pixels from an array if it exceeds maxSamples
+     * Uses uniform sampling to maintain color distribution
+     * CORE-PERF-004: Fixed potential out-of-bounds access on last iteration
+     */
+    private samplePixels;
+    /**
+     * Extract dominant colors from pixel data
+     *
+     * @param pixels - Array of RGB pixel values
+     * @param options - Extraction options (colorCount, maxIterations, etc.)
+     * @returns Array of extracted colors sorted by dominance (most dominant first)
+     *
+     * @example
+     * ```typescript
+     * const pixels = [{ r: 255, g: 0, b: 0 }, { r: 254, g: 1, b: 1 }, ...];
+     * const palette = paletteService.extractPalette(pixels, { colorCount: 4 });
+     * // Returns: [{ color: { r: 255, g: 0, b: 0 }, dominance: 45, pixelCount: 4500 }, ...]
+     * ```
+     */
+    extractPalette(pixels: RGB[], options?: PaletteExtractionOptions): ExtractedColor[];
+    /**
+     * Extract colors from pixel data and match each to the closest FFXIV dye
+     *
+     * @param pixels - Array of RGB pixel values
+     * @param dyeService - DyeService instance for matching
+     * @param options - Extraction options
+     * @returns Array of palette matches sorted by dominance
+     *
+     * @example
+     * ```typescript
+     * const matches = paletteService.extractAndMatchPalette(pixels, dyeService, { colorCount: 4 });
+     * // Returns: [{ extracted: {...}, matchedDye: {...}, distance: 12.3, dominance: 45 }, ...]
+     * ```
+     */
+    extractAndMatchPalette(pixels: RGB[], dyeService: DyeService, options?: PaletteExtractionOptions): PaletteMatch[];
+    /**
+     * Convert flat pixel array (Uint8ClampedArray from canvas) to RGB array
+     * Skips alpha channel
+     *
+     * @param data - Flat array of RGBA values [r, g, b, a, r, g, b, a, ...]
+     * @returns Array of RGB objects
+     */
+    static pixelDataToRGB(data: Uint8ClampedArray | number[]): RGB[];
+    /**
+     * Filter out near-transparent pixels from RGBA data
+     * Useful for images with transparent backgrounds
+     *
+     * @param data - Flat array of RGBA values
+     * @param alphaThreshold - Minimum alpha to include (0-255, default: 128)
+     * @returns Array of RGB objects for non-transparent pixels
+     */
+    static pixelDataToRGBFiltered(data: Uint8ClampedArray | number[], alphaThreshold?: number): RGB[];
+}
+//# sourceMappingURL=PaletteService.d.ts.map

package/dist/services/PaletteService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaletteService.d.ts","sourceRoot":"","sources":["../../src/services/PaletteService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,KAAK,EAAE,GAAG,CAAC;IACX,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,SAAS,EAAE,GAAG,CAAC;IACf,qCAAqC;IACrC,UAAU,EAAE,GAAG,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmND;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IAEvB,iCAAiC;IACjC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAKrC;IAEF;;;OAGG;gBACS,OAAO,GAAE,qBAA0B;IAI/C;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,cAAc,EAAE;IA6CvF;;;;;;;;;;;;;OAaG;IACH,sBAAsB,CACpB,MAAM,EAAE,GAAG,EAAE,EACb,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,EAAE;IA4BjB;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAAE,GAAG,GAAG,EAAE;IAehE;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAC3B,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAAE,EAClC,cAAc,GAAE,MAAY,GAC3B,GAAG,EAAE;CAgBT"}