@nice2dev/icons 1.1.5 → 1.1.6

package/dist/cjs/utilities.js

@@ -0,0 +1,401 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+
+/**
+ * @file utilities.ts
+ * @description Utility hooks and functions for @nice2dev/icons
+ *
+ * Provides:
+ * - useIcon hook for dynamic icon loading
+ * - useReducedMotion hook for accessibility
+ * - preloadIcons for performance optimization
+ * - Icon type guards and helpers
+ *
+ * @example
+ * ```tsx
+ * import { useIcon, useReducedMotion, preloadIcons } from '@nice2dev/icons/utilities';
+ *
+ * // Dynamic icon loading
+ * const { Icon, isLoading } = useIcon('NtdHome');
+ *
+ * // Respect user preference for reduced motion
+ * const prefersReducedMotion = useReducedMotion();
+ *
+ * // Preload icons for better performance
+ * await preloadIcons(['NtdHome', 'NtdSearch', 'NtdUser']);
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+/* ────────────────────────────────────────────────────────────────────────────
+   ICON REGISTRY
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Global icon cache for dynamic loading
+ */
+const iconRegistry = new Map();
+/**
+ * Registers an icon in the global registry
+ */
+function registerIcon(name, component) {
+    iconRegistry.set(name, {
+        component,
+        loadedAt: Date.now(),
+    });
+}
+/**
+ * Gets an icon from the registry
+ */
+function getIconFromRegistry(name) {
+    var _a;
+    return (_a = iconRegistry.get(name)) === null || _a === void 0 ? void 0 : _a.component;
+}
+/**
+ * Clears the icon registry
+ */
+function clearIconRegistry() {
+    iconRegistry.clear();
+}
+/**
+ * Gets all registered icon names
+ */
+function getRegisteredIconNames() {
+    return Array.from(iconRegistry.keys());
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   USE ICON HOOK
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Hook for dynamically loading icons by name.
+ *
+ * @param iconName - Name of the icon to load (e.g., 'NtdHome')
+ * @param options - Loading options
+ * @returns Icon component, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function DynamicIcon({ name }: { name: string }) {
+ *   const { Icon, isLoading, error } = useIcon(name);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error || !Icon) return <FallbackIcon />;
+ *
+ *   return <Icon size="md" />;
+ * }
+ * ```
+ */
+function useIcon(iconName, options = {}) {
+    const { fallback, cache = true } = options;
+    const [state, setState] = React.useState({
+        Icon: iconName ? getIconFromRegistry(iconName) || null : null,
+        isLoading: false,
+        error: null,
+    });
+    React.useEffect(() => {
+        if (!iconName) {
+            setState({ Icon: null, isLoading: false, error: null });
+            return;
+        }
+        // Check cache first
+        const cached = getIconFromRegistry(iconName);
+        if (cached) {
+            setState({ Icon: cached, isLoading: false, error: null });
+            return;
+        }
+        // Start loading
+        setState((prev) => ({ ...prev, isLoading: true, error: null }));
+        // Dynamic import (assumes icons are exported individually)
+        const loadIcon = async () => {
+            try {
+                // Try to import from the icons module
+                const module = await Promise.resolve().then(function () { return require('./icons/index.js'); });
+                const IconComponent = module[iconName];
+                if (IconComponent) {
+                    if (cache) {
+                        registerIcon(iconName, IconComponent);
+                    }
+                    setState({ Icon: IconComponent, isLoading: false, error: null });
+                }
+                else {
+                    throw new Error(`Icon "${iconName}" not found`);
+                }
+            }
+            catch (err) {
+                setState({
+                    Icon: fallback || null,
+                    isLoading: false,
+                    error: err instanceof Error ? err : new Error('Failed to load icon'),
+                });
+            }
+        };
+        loadIcon();
+    }, [iconName, cache, fallback]);
+    return state;
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   USE REDUCED MOTION
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Subscribes to prefers-reduced-motion media query.
+ */
+function subscribeToReducedMotion(callback) {
+    if (typeof window === 'undefined') {
+        return () => { };
+    }
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handler = () => callback();
+    mediaQuery.addEventListener('change', handler);
+    return () => mediaQuery.removeEventListener('change', handler);
+}
+/**
+ * Gets current reduced motion preference.
+ */
+function getReducedMotionSnapshot() {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Server snapshot for SSR (assumes no reduced motion preference).
+ */
+function getReducedMotionServerSnapshot() {
+    return false;
+}
+/**
+ * Hook that returns true if user prefers reduced motion.
+ * Uses useSyncExternalStore for SSR compatibility.
+ *
+ * @returns Whether the user prefers reduced motion
+ *
+ * @example
+ * ```tsx
+ * function AnimatedIcon() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <NtdHeart
+ *       animation={prefersReducedMotion ? undefined : 'pulse'}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+function useReducedMotion() {
+    return React.useSyncExternalStore(subscribeToReducedMotion, getReducedMotionSnapshot, getReducedMotionServerSnapshot);
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   PRELOAD ICONS
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Preloads icons into the registry for instant access.
+ *
+ * @param iconNames - Array of icon names to preload
+ * @returns Promise that resolves when all icons are loaded
+ *
+ * @example
+ * ```tsx
+ * // Preload critical icons at app startup
+ * useEffect(() => {
+ *   preloadIcons(['NtdHome', 'NtdSearch', 'NtdUser', 'NtdMenu']);
+ * }, []);
+ * ```
+ */
+async function preloadIcons(iconNames) {
+    const results = new Map();
+    try {
+        const module = await Promise.resolve().then(function () { return require('./icons/index.js'); });
+        for (const name of iconNames) {
+            const IconComponent = module[name];
+            if (IconComponent) {
+                registerIcon(name, IconComponent);
+                results.set(name, IconComponent);
+            }
+        }
+    }
+    catch (error) {
+        console.warn('Failed to preload icons:', error);
+    }
+    return results;
+}
+/**
+ * Creates a preloader component that preloads icons on mount.
+ *
+ * @param iconNames - Icons to preload
+ * @returns React component that preloads icons
+ *
+ * @example
+ * ```tsx
+ * const IconPreloader = createIconPreloader(['NtdHome', 'NtdSearch']);
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <IconPreloader />
+ *       <MainContent />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+function createIconPreloader(iconNames) {
+    return function IconPreloader() {
+        React.useEffect(() => {
+            preloadIcons(iconNames);
+        }, []);
+        return null;
+    };
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   ICON PROPS HELPERS
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Creates props with animation disabled if user prefers reduced motion.
+ *
+ * @param props - Original icon props
+ * @param prefersReducedMotion - Whether user prefers reduced motion
+ * @returns Props with animation conditionally disabled
+ */
+function withReducedMotionProps(props, prefersReducedMotion) {
+    if (!prefersReducedMotion) {
+        return props;
+    }
+    return {
+        ...props,
+        animation: undefined,
+        animationDuration: undefined,
+        gradientAnimation: undefined,
+    };
+}
+/**
+ * Creates accessible icon props based on context.
+ *
+ * @param options - Accessibility options
+ * @returns Icon props for accessibility
+ */
+function createAccessibleIconProps(options) {
+    const { label, isDecorative = !label, role } = options;
+    if (isDecorative) {
+        return {
+            'aria-hidden': true,
+            role: 'presentation',
+        };
+    }
+    return {
+        'aria-label': label,
+        role: role || 'img',
+        title: label,
+    };
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   ICON TYPE GUARDS
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Checks if a value is a valid icon component.
+ * Handles both regular components and forwardRef components.
+ */
+function isIconComponent(value) {
+    if (value == null) {
+        return false;
+    }
+    // ForwardRef components are objects with $$typeof, regular components are functions
+    const isValidComponent = typeof value === 'function' || (typeof value === 'object' && '$$typeof' in value);
+    if (!isValidComponent) {
+        return false;
+    }
+    const displayName = value.displayName;
+    return typeof displayName === 'string' && displayName.startsWith('Ntd');
+}
+/**
+ * Checks if an icon name is valid.
+ */
+function isValidIconName(name) {
+    return /^Ntd[A-Z][a-zA-Z0-9]*$/.test(name);
+}
+/**
+ * Creates a function that renders multiple icons efficiently.
+ *
+ * @param configs - Array of icon configurations
+ * @returns Function that renders all configured icons
+ *
+ * @example
+ * ```tsx
+ * const renderNavIcons = createBatchIconRenderer([
+ *   { name: 'NtdHome', props: { size: 'md' } },
+ *   { name: 'NtdSearch', props: { size: 'md' } },
+ *   { name: 'NtdUser', props: { size: 'md' } },
+ * ]);
+ *
+ * // In component
+ * const icons = renderNavIcons();
+ * ```
+ */
+function useBatchIcons(configs) {
+    const [icons, setIcons] = React.useState(new Map());
+    const [isLoading, setIsLoading] = React.useState(true);
+    React.useEffect(() => {
+        const loadIcons = async () => {
+            setIsLoading(true);
+            const names = configs.map((c) => c.name);
+            const loadedIcons = await preloadIcons(names);
+            setIcons(loadedIcons);
+            setIsLoading(false);
+        };
+        loadIcons();
+    }, [configs.map((c) => c.name).join(',')]);
+    const renderIcon = React.useCallback((name, additionalProps) => {
+        const Icon = icons.get(name);
+        const config = configs.find((c) => c.name === name);
+        if (!Icon) {
+            return null;
+        }
+        const mergedProps = {
+            ...config === null || config === void 0 ? void 0 : config.props,
+            ...additionalProps,
+        };
+        return React.createElement(Icon, mergedProps);
+    }, [icons, configs]);
+    return {
+        renderIcon,
+        isLoading,
+        icons,
+    };
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   EXPORTS
+───────────────────────────────────────────────────────────────────────────── */
+var utilities = {
+    useIcon,
+    useReducedMotion,
+    preloadIcons,
+    createIconPreloader,
+    registerIcon,
+    getIconFromRegistry,
+    clearIconRegistry,
+    getRegisteredIconNames,
+    withReducedMotionProps,
+    createAccessibleIconProps,
+    isIconComponent,
+    isValidIconName,
+    useBatchIcons,
+};
+
+exports.clearIconRegistry = clearIconRegistry;
+exports.createAccessibleIconProps = createAccessibleIconProps;
+exports.createIconPreloader = createIconPreloader;
+exports.default = utilities;
+exports.getIconFromRegistry = getIconFromRegistry;
+exports.getRegisteredIconNames = getRegisteredIconNames;
+exports.isIconComponent = isIconComponent;
+exports.isValidIconName = isValidIconName;
+exports.preloadIcons = preloadIcons;
+exports.registerIcon = registerIcon;
+exports.useBatchIcons = useBatchIcons;
+exports.useIcon = useIcon;
+exports.useReducedMotion = useReducedMotion;
+exports.withReducedMotionProps = withReducedMotionProps;

package/dist/cjs/variantProps.js

@@ -85,4 +85,3 @@ exports.isSolidProps = isSolidProps;
 exports.isThreeDProps = isThreeDProps;
 exports.isVividProps = isVividProps;
 exports.toIconProps = toIconProps;
-//# sourceMappingURL=variantProps.js.map

package/dist/esm/NiceDesktopIconExporter.js

@@ -649,4 +649,3 @@ const NiceDesktopIconExporter = ({ icon, initialConfig, onExport, className = ''
 };
 
 export { DESKTOP_ICON_SIZES, LINUX_HICOLOR_DIRS, NiceDesktopIconExporter, RETINA_VARIANTS, useDesktopIconExporter };
-//# sourceMappingURL=NiceDesktopIconExporter.js.map

package/dist/esm/NiceFaviconGenerator.js

@@ -423,4 +423,3 @@ const styles = {
 };
 
 export { NiceFaviconGenerator, useFaviconGenerator };
-//# sourceMappingURL=NiceFaviconGenerator.js.map

package/dist/esm/NiceIconEditor.js

@@ -452,4 +452,3 @@ const styles = {
 };
 
 export { NiceIconEditor, useIconEditor };
-//# sourceMappingURL=NiceIconEditor.js.map

package/dist/esm/NiceIconPicker.js

@@ -407,4 +407,3 @@ const NiceIconPicker = forwardRef(function NiceIconPicker({ icons, value = null,
 });
 
 export { NiceIconPicker };
-//# sourceMappingURL=NiceIconPicker.js.map

package/dist/esm/NiceIconPreview.js

@@ -193,4 +193,3 @@ const styles = {
 };
 
 export { NiceIconPreview };
-//# sourceMappingURL=NiceIconPreview.js.map

package/dist/esm/NiceIconSetCreator.js

@@ -562,4 +562,3 @@ const styles = {
 };
 
 export { NiceIconSetCreator, useIconSetCreator };
-//# sourceMappingURL=NiceIconSetCreator.js.map

package/dist/esm/NtdIconBadge.js

@@ -375,4 +375,3 @@ const NtdIconStack = forwardRef(({ base: BaseIcon, overlay: OverlayIcon, basePro
 NtdIconStack.displayName = 'NtdIconStack';
 
 export { NtdBadge, NtdIconOverlay, NtdIconStack, NtdStatusDot };
-//# sourceMappingURL=NtdIconBadge.js.map

package/dist/esm/NtdIconMorph.js

@@ -388,4 +388,3 @@ function useMorphState(options = {}) {
 }
 
 export { NtdIconMorph, NtdMorphPair, NtdPathMorph, useMorphState };
-//# sourceMappingURL=NtdIconMorph.js.map

package/dist/esm/NtdStateMorph.js

@@ -172,4 +172,3 @@ function useStateMorph(states, initialState, options) {
 }
 
 export { NtdStateMorph, useStateMorph };
-//# sourceMappingURL=NtdStateMorph.js.map

package/dist/esm/advancedIconSearch.js

@@ -557,4 +557,3 @@ function useAdvancedIconSearch(debounceMs = 200, locale = 'en') {
 }
 
 export { advancedSearch, clearRecentlyUsed, clearSearchHistory, findSimilarIcons, fuzzyMatchScore, getExtendedMetadata, getFavorites, getIconUsageStats, getRecentlyUsed, getSearchAnalytics, getSearchSuggestions, isFavorite, levenshteinDistance, recordIconUsage, registerExtendedIcon, toggleFavorite, tokenizeQuery, useAdvancedIconSearch };
-//# sourceMappingURL=advancedIconSearch.js.map

package/dist/esm/animationControls.js

@@ -680,4 +680,3 @@ const PRESET_INTERACTIONS = {
 };
 
 export { AnimationController, InteractiveIcon, PRESET_INTERACTIONS, PRESET_SEQUENCES, createAnimationSequence, createClickAnimation, createHoverAnimation, createVisibilityAnimation, useAnimationSequence };
-//# sourceMappingURL=animationControls.js.map

package/dist/esm/client.js

@@ -0,0 +1,5 @@
+export { AnimationController, InteractiveIcon, PRESET_INTERACTIONS, PRESET_SEQUENCES, createAnimationSequence, createClickAnimation, createHoverAnimation, createVisibilityAnimation, useAnimationSequence } from './animationControls.js';
+export { NiceIconPicker } from './NiceIconPicker.js';
+export { NtdIconMorph, NtdMorphPair, NtdPathMorph, useMorphState } from './NtdIconMorph.js';
+export { NtdBadge, NtdIconOverlay, NtdIconStack, NtdStatusDot } from './NtdIconBadge.js';
+export { SMIL_ANIMATION_TYPES, SmilAnimationWrapper, createSmilAnimationDef, generateSmilAnimation, isSmilSupported } from './smilAnimations.js';

package/dist/esm/createIcon.js

@@ -234,4 +234,3 @@ function createIcon(options) {
 }
 
 export { createIcon };
-//# sourceMappingURL=createIcon.js.map