tyrell-components 1.0.0-RC6

package/lib/utils/icon-registry.js

@@ -0,0 +1,304 @@
+/**
+ * Icon Registry System
+ * Simple icon storage and retrieval with Cache API persistence
+ * PORTED FROM: clj/ty/icons.cljs
+ */
+import { VERSION } from '../version.js';
+/** Icon registry - maps icon names to SVG strings */
+const iconRegistry = new Map();
+/** Watchers for registry changes - now receives Set of changed icon names */
+const watchers = new Map();
+/** Track which icons each watcher cares about (for selective notification) */
+const watcherIconNames = new Map();
+/** Pending notifications - batched for performance */
+let pendingNotifications = null;
+let notificationTimer = null;
+/** Cache API configuration */
+const CACHE_NAME = `ty-icons-v${VERSION}`;
+// Use a fake URL base for Cache API (requires valid URL format)
+const CACHE_URL_BASE = 'https://ty-icons.local/';
+/** Track in-flight cache reads to avoid duplicate work */
+const cacheReadPromises = new Map();
+/** Flag to track if old caches have been cleared */
+let oldCachesCleared = false;
+/**
+ * Clear old cache versions on first use
+ * This runs lazily the first time any icon is requested
+ */
+async function clearOldCaches() {
+    if (oldCachesCleared || !('caches' in window))
+        return;
+    oldCachesCleared = true;
+    try {
+        const cacheNames = await caches.keys();
+        const oldCaches = cacheNames.filter(name => name.startsWith('ty-icons-v') && name !== CACHE_NAME);
+        await Promise.all(oldCaches.map(name => caches.delete(name)));
+        if (oldCaches.length > 0) {
+            console.log(`🗑️  Cleared ${oldCaches.length} old icon cache(s)`);
+        }
+    }
+    catch (err) {
+        console.warn('[ty-icons] Failed to clear old caches:', err);
+    }
+}
+/**
+ * Cache an icon in Cache API (non-blocking background operation)
+ * @param name Icon name
+ * @param svg SVG string
+ */
+async function cacheIcon(name, svg) {
+    if (!('caches' in window))
+        return;
+    try {
+        const cache = await caches.open(CACHE_NAME);
+        const response = new Response(svg, {
+            headers: { 'Content-Type': 'image/svg+xml' }
+        });
+        // Cache API requires valid URLs
+        await cache.put(`${CACHE_URL_BASE}${name}`, response);
+    }
+    catch (err) {
+        // Silent fail - caching is an optimization, not critical
+        console.warn(`[ty-icons] Failed to cache icon "${name}":`, err);
+    }
+}
+/**
+ * Read icon directly from cache (for immediate rendering)
+ * This is the key function that prevents icon twitching!
+ * @param name Icon name
+ * @returns Promise<string | null> - SVG string from cache or null
+ */
+export async function getCachedIcon(name) {
+    // Check if we already have a read in progress for this icon
+    const existingPromise = cacheReadPromises.get(name);
+    if (existingPromise) {
+        return existingPromise;
+    }
+    // Create new read promise
+    const readPromise = (async () => {
+        try {
+            // Clear old caches on first cache access
+            await clearOldCaches();
+            const cache = await caches.open(CACHE_NAME);
+            const response = await cache.match(`${CACHE_URL_BASE}${name}`);
+            if (response) {
+                return await response.text();
+            }
+        }
+        catch (err) {
+            console.warn(`[ty-icons] Failed to read icon "${name}" from cache:`, err);
+        }
+        return null;
+    })();
+    // Store promise to avoid duplicate work
+    cacheReadPromises.set(name, readPromise);
+    // Clean up promise after completion
+    readPromise.finally(() => {
+        cacheReadPromises.delete(name);
+    });
+    return readPromise;
+}
+/**
+ * Register multiple icons at once
+ * Always updates memory and notifies watchers immediately
+ * Cache update happens in background (only if different from cached version)
+ * @param icons Object mapping icon names to SVG strings
+ */
+export function registerIcons(icons) {
+    const changedIcons = new Set();
+    Object.entries(icons).forEach(([name, svg]) => {
+        // Always set in memory registry (fast, synchronous)
+        iconRegistry.set(name, svg);
+        changedIcons.add(name);
+        // Compare with cache in background to avoid unnecessary cache writes
+        /*getCachedIcon(name).then(cachedSvg => {
+          // Only write to cache if content actually changed
+          if (cachedSvg !== svg) {
+            cacheIcon(name, svg).catch(() => {
+              // Error already logged in cacheIcon
+            })
+          }
+          // If cachedSvg === svg, skip cache write (already up to date)
+        }).catch(() => {
+          // No cached version or error reading cache - write new icon
+          cacheIcon(name, svg).catch(() => {
+            // Error already logged in cacheIcon
+          })
+        })
+        */
+    });
+    // Notify watchers immediately (synchronous)
+    if (changedIcons.size > 0) {
+        scheduleNotification(changedIcons);
+    }
+}
+/**
+ * Register a single icon
+ * Always updates memory and notifies watchers immediately
+ * Cache update happens in background (only if different from cached version)
+ * @param name Icon name
+ * @param svg SVG string
+ */
+export function registerIcon(name, svg) {
+    // Always set in memory registry (fast, synchronous)
+    iconRegistry.set(name, svg);
+    // Notify watchers immediately (synchronous)
+    scheduleNotification(new Set([name]));
+    // Compare with cache in background to avoid unnecessary cache writes
+    getCachedIcon(name).then(cachedSvg => {
+        // Only write to cache if content actually changed
+        if (cachedSvg !== svg) {
+            cacheIcon(name, svg).catch(() => {
+                // Error already logged in cacheIcon
+            });
+        }
+        // If cachedSvg === svg, skip cache write (already up to date)
+    }).catch(() => {
+        // No cached version or error reading cache - write new icon
+        cacheIcon(name, svg).catch(() => {
+            // Error already logged in cacheIcon
+        });
+    });
+}
+/**
+ * Lookup an icon by name from memory
+ * NOTE: This does NOT check cache - use getCachedIcon() for that
+ * @param name Icon name
+ * @returns SVG string or undefined
+ */
+export function getIcon(name) {
+    return iconRegistry.get(name);
+}
+/**
+ * Check if an icon exists in memory
+ * NOTE: This does NOT check cache
+ * @param name Icon name
+ * @returns true if icon is registered in memory
+ */
+export function hasIcon(name) {
+    return iconRegistry.has(name);
+}
+/**
+ * Clear all registered icons from memory and cache
+ */
+export async function clearIcons() {
+    const allIcons = new Set(iconRegistry.keys());
+    iconRegistry.clear();
+    // Clear cache
+    if ('caches' in window) {
+        try {
+            await caches.delete(CACHE_NAME);
+            oldCachesCleared = false; // Allow re-clearing next time
+        }
+        catch (err) {
+            console.warn('[ty-icons] Failed to clear icon cache:', err);
+        }
+    }
+    scheduleNotification(allIcons);
+}
+/**
+ * Add a watcher for registry changes
+ * @param id Unique watcher ID
+ * @param iconName Optional icon name to watch (for selective notification)
+ * @param callback Function to call when watched icons change
+ */
+export function addWatcher(id, iconName, callback) {
+    watchers.set(id, callback);
+    if (iconName) {
+        watcherIconNames.set(id, iconName);
+    }
+}
+/**
+ * Remove a watcher
+ * @param id Watcher ID to remove
+ */
+export function removeWatcher(id) {
+    watchers.delete(id);
+    watcherIconNames.delete(id);
+}
+/**
+ * Schedule notification for changed icons (batched and deferred)
+ */
+function scheduleNotification(changedIcons) {
+    // Accumulate changed icons
+    if (!pendingNotifications) {
+        pendingNotifications = new Set();
+    }
+    changedIcons.forEach(name => pendingNotifications.add(name));
+    // Cancel existing timer
+    if (notificationTimer !== null) {
+        clearTimeout(notificationTimer);
+    }
+    // Schedule notification using requestIdleCallback or setTimeout
+    const scheduleCallback = typeof requestIdleCallback !== 'undefined'
+        ? requestIdleCallback
+        : (cb) => setTimeout(cb, 0);
+    notificationTimer = scheduleCallback(() => {
+        const toNotify = pendingNotifications;
+        pendingNotifications = null;
+        notificationTimer = null;
+        // Only notify if we have icons to notify about
+        if (toNotify && toNotify.size > 0) {
+            notifyWatchers(toNotify);
+        }
+    });
+}
+/**
+ * Notify watchers of changed icons (selective notification)
+ */
+function notifyWatchers(changedIcons) {
+    watchers.forEach((callback, watcherId) => {
+        const watchedIcon = watcherIconNames.get(watcherId);
+        // If watcher is watching a specific icon, only notify if that icon changed
+        if (watchedIcon) {
+            if (changedIcons.has(watchedIcon)) {
+                callback(new Set([watchedIcon]));
+            }
+        }
+        else {
+            // Watcher wants all changes
+            callback(changedIcons);
+        }
+    });
+}
+/**
+ * Get all registered icon names (memory only, not cache)
+ * @returns Array of icon names
+ */
+export function getIconNames() {
+    return Array.from(iconRegistry.keys());
+}
+/**
+ * Get registry size (memory only)
+ * @returns Number of registered icons in memory
+ */
+export function getIconCount() {
+    return iconRegistry.size;
+}
+/**
+ * Get cache statistics
+ * @returns Promise with cache info
+ */
+export async function getCacheInfo() {
+    const info = {
+        version: VERSION,
+        cacheName: CACHE_NAME,
+        available: 'caches' in window
+    };
+    if (!info.available)
+        return info;
+    try {
+        const cache = await caches.open(CACHE_NAME);
+        const keys = await cache.keys();
+        const iconKeys = keys.filter(req => req.url.startsWith(CACHE_URL_BASE));
+        return {
+            ...info,
+            iconCount: iconKeys.length
+        };
+    }
+    catch (err) {
+        console.warn('[ty-icons] Failed to get cache info:', err);
+        return info;
+    }
+}
+//# sourceMappingURL=icon-registry.js.map

package/lib/utils/icon-registry.js.map

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

package/lib/utils/locale.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Locale Resolution Utilities
+ *
+ * Provides a cascade system for resolving locale/language preferences:
+ * 1. Component's explicit `locale` attribute (highest priority)
+ * 2. Closest ancestor's `lang` attribute
+ * 3. Document root's `lang` attribute
+ * 4. Browser's language preference
+ * 5. 'en-US' fallback (lowest priority)
+ *
+ * This allows developers to set locale at any level:
+ * - Per-component: <ty-input locale="fr-FR">
+ * - Per-section: <div lang="de-DE"><ty-input></ty-input></div>
+ * - Per-page: <html lang="es-ES">
+ * - Browser default: Uses navigator.language
+ *
+ * @example
+ * ```typescript
+ * // In a component
+ * class TyInput extends HTMLElement {
+ *   get locale(): string {
+ *     return getEffectiveLocale(this, this.getAttribute('locale'));
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Get the effective locale for an element using the resolution cascade.
+ *
+ * Resolution order:
+ * 1. Explicit locale attribute on the element
+ * 2. Closest ancestor element with a `lang` attribute
+ * 3. Document root element's `lang` attribute
+ * 4. Browser's navigator.language
+ * 5. Fallback to 'en-US'
+ *
+ * @param element - The element to get locale for
+ * @param explicitLocale - Optional explicit locale value (from component's locale attribute)
+ * @returns The resolved locale string (e.g., 'en-US', 'fr-FR')
+ *
+ * @example
+ * ```html
+ * <html lang="en-US">
+ *   <div lang="fr-FR">
+ *     <ty-input></ty-input>              <!-- Uses 'fr-FR' -->
+ *     <ty-input locale="de-DE"></ty-input>  <!-- Uses 'de-DE' -->
+ *   </div>
+ *   <ty-input></ty-input>                <!-- Uses 'en-US' -->
+ * </html>
+ * ```
+ */
+export declare function getEffectiveLocale(element: HTMLElement, explicitLocale?: string | null): string;
+/**
+ * Normalize a locale string to BCP 47 format.
+ * Handles common variations and ensures consistency.
+ *
+ * @param locale - The locale string to normalize
+ * @returns Normalized locale string
+ *
+ * @example
+ * ```typescript
+ * normalizeLocale('en')       // 'en'
+ * normalizeLocale('en_US')    // 'en-US'
+ * normalizeLocale('EN-us')    // 'en-US'
+ * ```
+ */
+export declare function normalizeLocale(locale: string): string;
+/**
+ * Check if a locale string is valid BCP 47 format.
+ *
+ * @param locale - The locale string to validate
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLocale('en-US')    // true
+ * isValidLocale('fr')       // true
+ * isValidLocale('invalid!') // false
+ * ```
+ */
+export declare function isValidLocale(locale: string): boolean;
+/**
+ * Get the language code from a locale (e.g., 'en' from 'en-US').
+ *
+ * @param locale - The locale string
+ * @returns The language code
+ *
+ * @example
+ * ```typescript
+ * getLanguageCode('en-US')  // 'en'
+ * getLanguageCode('fr-FR')  // 'fr'
+ * getLanguageCode('de')     // 'de'
+ * ```
+ */
+export declare function getLanguageCode(locale: string): string;
+/**
+ * Get the region/country code from a locale (e.g., 'US' from 'en-US').
+ *
+ * @param locale - The locale string
+ * @returns The region code, or undefined if not present
+ *
+ * @example
+ * ```typescript
+ * getRegionCode('en-US')  // 'US'
+ * getRegionCode('fr-FR')  // 'FR'
+ * getRegionCode('de')     // undefined
+ * ```
+ */
+export declare function getRegionCode(locale: string): string | undefined;
+/**
+ * Create a MutationObserver to watch for lang attribute changes.
+ * Useful for components that need to react to dynamic locale changes.
+ *
+ * @param element - The element to observe
+ * @param callback - Function to call when lang changes
+ * @returns Cleanup function to disconnect the observer
+ *
+ * @example
+ * ```typescript
+ * class TyInput extends HTMLElement {
+ *   private _localeObserver?: () => void;
+ *
+ *   connectedCallback() {
+ *     this._localeObserver = observeLocaleChanges(this, () => {
+ *       this.render(); // Re-render when locale changes
+ *     });
+ *   }
+ *
+ *   disconnectedCallback() {
+ *     this._localeObserver?.();
+ *   }
+ * }
+ * ```
+ */
+export declare function observeLocaleChanges(element: HTMLElement, callback: (newLocale: string) => void): () => void;
+//# sourceMappingURL=locale.d.ts.map

package/lib/utils/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/utils/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,CA0BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoBtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACpC,MAAM,IAAI,CAyBZ"}

package/lib/utils/locale.js

@@ -0,0 +1,213 @@
+/**
+ * Locale Resolution Utilities
+ *
+ * Provides a cascade system for resolving locale/language preferences:
+ * 1. Component's explicit `locale` attribute (highest priority)
+ * 2. Closest ancestor's `lang` attribute
+ * 3. Document root's `lang` attribute
+ * 4. Browser's language preference
+ * 5. 'en-US' fallback (lowest priority)
+ *
+ * This allows developers to set locale at any level:
+ * - Per-component: <ty-input locale="fr-FR">
+ * - Per-section: <div lang="de-DE"><ty-input></ty-input></div>
+ * - Per-page: <html lang="es-ES">
+ * - Browser default: Uses navigator.language
+ *
+ * @example
+ * ```typescript
+ * // In a component
+ * class TyInput extends HTMLElement {
+ *   get locale(): string {
+ *     return getEffectiveLocale(this, this.getAttribute('locale'));
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Get the effective locale for an element using the resolution cascade.
+ *
+ * Resolution order:
+ * 1. Explicit locale attribute on the element
+ * 2. Closest ancestor element with a `lang` attribute
+ * 3. Document root element's `lang` attribute
+ * 4. Browser's navigator.language
+ * 5. Fallback to 'en-US'
+ *
+ * @param element - The element to get locale for
+ * @param explicitLocale - Optional explicit locale value (from component's locale attribute)
+ * @returns The resolved locale string (e.g., 'en-US', 'fr-FR')
+ *
+ * @example
+ * ```html
+ * <html lang="en-US">
+ *   <div lang="fr-FR">
+ *     <ty-input></ty-input>              <!-- Uses 'fr-FR' -->
+ *     <ty-input locale="de-DE"></ty-input>  <!-- Uses 'de-DE' -->
+ *   </div>
+ *   <ty-input></ty-input>                <!-- Uses 'en-US' -->
+ * </html>
+ * ```
+ */
+export function getEffectiveLocale(element, explicitLocale) {
+    // 1. Explicit locale attribute takes highest priority
+    if (explicitLocale) {
+        return explicitLocale;
+    }
+    // 2. Check closest ancestor with lang attribute
+    // This allows per-section locale overrides
+    const langElement = element.closest('[lang]');
+    if (langElement) {
+        const lang = langElement.getAttribute('lang');
+        if (lang)
+            return lang;
+    }
+    // 3. Check document root (html element)
+    if (document.documentElement.lang) {
+        return document.documentElement.lang;
+    }
+    // 4. Use browser's language preference
+    if (navigator.language) {
+        return navigator.language;
+    }
+    // 5. Ultimate fallback
+    return 'en-US';
+}
+/**
+ * Normalize a locale string to BCP 47 format.
+ * Handles common variations and ensures consistency.
+ *
+ * @param locale - The locale string to normalize
+ * @returns Normalized locale string
+ *
+ * @example
+ * ```typescript
+ * normalizeLocale('en')       // 'en'
+ * normalizeLocale('en_US')    // 'en-US'
+ * normalizeLocale('EN-us')    // 'en-US'
+ * ```
+ */
+export function normalizeLocale(locale) {
+    if (!locale)
+        return 'en-US';
+    // Replace underscores with hyphens (en_US -> en-US)
+    let normalized = locale.replace(/_/g, '-');
+    // Split into parts
+    const parts = normalized.split('-');
+    if (parts.length === 0)
+        return 'en-US';
+    // Lowercase language code (EN -> en)
+    parts[0] = parts[0].toLowerCase();
+    // Uppercase country code if present (us -> US)
+    if (parts.length > 1) {
+        parts[1] = parts[1].toUpperCase();
+    }
+    return parts.join('-');
+}
+/**
+ * Check if a locale string is valid BCP 47 format.
+ *
+ * @param locale - The locale string to validate
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLocale('en-US')    // true
+ * isValidLocale('fr')       // true
+ * isValidLocale('invalid!') // false
+ * ```
+ */
+export function isValidLocale(locale) {
+    if (!locale)
+        return false;
+    // BCP 47 language tag pattern
+    // Simplified: allows language-region format
+    const pattern = /^[a-z]{2,3}(-[A-Z]{2})?$/;
+    return pattern.test(locale);
+}
+/**
+ * Get the language code from a locale (e.g., 'en' from 'en-US').
+ *
+ * @param locale - The locale string
+ * @returns The language code
+ *
+ * @example
+ * ```typescript
+ * getLanguageCode('en-US')  // 'en'
+ * getLanguageCode('fr-FR')  // 'fr'
+ * getLanguageCode('de')     // 'de'
+ * ```
+ */
+export function getLanguageCode(locale) {
+    if (!locale)
+        return 'en';
+    return locale.split('-')[0].toLowerCase();
+}
+/**
+ * Get the region/country code from a locale (e.g., 'US' from 'en-US').
+ *
+ * @param locale - The locale string
+ * @returns The region code, or undefined if not present
+ *
+ * @example
+ * ```typescript
+ * getRegionCode('en-US')  // 'US'
+ * getRegionCode('fr-FR')  // 'FR'
+ * getRegionCode('de')     // undefined
+ * ```
+ */
+export function getRegionCode(locale) {
+    if (!locale)
+        return undefined;
+    const parts = locale.split('-');
+    return parts.length > 1 ? parts[1].toUpperCase() : undefined;
+}
+/**
+ * Create a MutationObserver to watch for lang attribute changes.
+ * Useful for components that need to react to dynamic locale changes.
+ *
+ * @param element - The element to observe
+ * @param callback - Function to call when lang changes
+ * @returns Cleanup function to disconnect the observer
+ *
+ * @example
+ * ```typescript
+ * class TyInput extends HTMLElement {
+ *   private _localeObserver?: () => void;
+ *
+ *   connectedCallback() {
+ *     this._localeObserver = observeLocaleChanges(this, () => {
+ *       this.render(); // Re-render when locale changes
+ *     });
+ *   }
+ *
+ *   disconnectedCallback() {
+ *     this._localeObserver?.();
+ *   }
+ * }
+ * ```
+ */
+export function observeLocaleChanges(element, callback) {
+    let currentLocale = getEffectiveLocale(element);
+    // Create observer for lang attribute changes on ancestors
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.type === 'attributes' && mutation.attributeName === 'lang') {
+                const newLocale = getEffectiveLocale(element);
+                if (newLocale !== currentLocale) {
+                    currentLocale = newLocale;
+                    callback(newLocale);
+                }
+            }
+        }
+    });
+    // Observe document and all ancestors
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['lang'],
+        subtree: true
+    });
+    // Return cleanup function
+    return () => observer.disconnect();
+}
+//# sourceMappingURL=locale.js.map

package/lib/utils/locale.js.map

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

package/lib/utils/mobile.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mobile detection utility
+ *
+ * Uses CSS media query via matchMedia for reliable detection:
+ * - `pointer: coarse` identifies touch-primary devices (not laptops with touchscreens)
+ * - Breakpoint is evaluated by the browser, always in sync with CSS
+ * - Called on each use (not cached), so it responds to viewport changes and rotation
+ */
+/**
+ * Detect mobile touch devices.
+ * Returns true when the primary pointer is coarse (touch) AND viewport is narrow.
+ */
+export declare function isMobileTouch(breakpoint?: number): boolean;
+//# sourceMappingURL=mobile.d.ts.map