@nice2dev/icons 1.0.5 → 1.0.8

package/dist/types/iconAnalytics.d.ts

@@ -1,131 +1,238 @@
 /**
- * @file iconAnalytics.tsx
- * @description Optional icon usage analytics — tracks which icons are rendered,
- * provides a dashboard component, and recommendations for unused icons.
+ * @file iconAnalytics.ts
+ * @module @nice2dev/icons
+ * @description PRO-28.3 — Icon Usage Analytics Service
  *
- * @example
- * ```tsx
- * // 1. Wrap your app with the analytics provider
- * const { AnalyticsProvider, useIconAnalytics } = createIconAnalyticsProvider();
- *
- * function App() {
- *   return (
- *     <AnalyticsProvider>
- *       <MyApp />
- *       <IconAnalyticsDashboard />
- *     </AnalyticsProvider>
- *   );
- * }
- *
- * // 2. Use the hook inside icon wrappers or manually
- * function TrackedIcon(props) {
- *   const analytics = useIconAnalytics();
- *   useEffect(() => { analytics.track('NtdHome'); }, []);
- *   return <NtdHome {...props} />;
- * }
- * ```
+ * Tracks and analyzes icon usage patterns:
+ * - Most used icons
+ * - Icons per project
+ * - Missing icons suggestions
+ * - Unused icons cleanup
  */
-import React from 'react';
-/** A single usage tracking event. */
+/** Single icon usage event */
 export interface IconUsageEvent {
-    /** Icon component name (e.g. 'NtdHome') */
-    name: string;
-    /** Timestamp of last render */
-    lastSeen: number;
-    /** Total render count */
-    count: number;
-    /** Variant used (last) */
+    /** Icon name */
+    iconName: string;
+    /** Usage context/component */
+    context?: string;
+    /** Project/app identifier */
+    projectId?: string;
+    /** Variant used */
     variant?: string;
-    /** Size used (last) */
-    size?: string | number;
-    /** Component path where the icon was rendered */
-    location?: string;
+    /** Size used */
+    size?: number | string;
+    /** Timestamp */
+    timestamp: number;
 }
-/** Configuration for the analytics system. */
-export interface IconAnalyticsOptions {
-    /** Enable/disable tracking (default: true in dev, false in prod) */
-    enabled?: boolean;
-    /** Maximum events to retain in memory */
-    maxEvents?: number;
-    /** Callback when a new icon is tracked */
-    onTrack?: (event: IconUsageEvent) => void;
-    /** Persist to localStorage key (default: none) */
-    storageKey?: string;
+/** Usage statistics for a single icon */
+export interface IconUsageStats {
+    /** Icon name */
+    name: string;
+    /** Total usage count */
+    totalUsage: number;
+    /** First used timestamp */
+    firstUsed: number;
+    /** Last used timestamp */
+    lastUsed: number;
+    /** Contexts where used */
+    contexts: Map<string, number>;
+    /** Projects where used */
+    projects: Set<string>;
+    /** Variants used */
+    variants: Map<string, number>;
+    /** Average size */
+    avgSize: number;
 }
-/** Aggregated analytics report. */
+/** Project usage summary */
+export interface ProjectIconSummary {
+    /** Project identifier */
+    projectId: string;
+    /** Total unique icons */
+    uniqueIcons: number;
+    /** Total usage events */
+    totalUsage: number;
+    /** Most used icons in project */
+    topIcons: {
+        name: string;
+        count: number;
+    }[];
+    /** Categories used */
+    categories: Map<string, number>;
+}
+/** Analytics report */
 export interface IconAnalyticsReport {
-    /** Total unique icons tracked */
-    totalUniqueIcons: number;
-    /** Total render count across all icons */
-    totalRenderCount: number;
-    /** Icons sorted by usage (most used first) */
-    mostUsed: IconUsageEvent[];
-    /** Icons that were rendered only once */
-    rarelyUsed: IconUsageEvent[];
-    /** Timestamp of report generation */
-    generatedAt: number;
+    /** Report period start */
+    periodStart: number;
+    /** Report period end */
+    periodEnd: number;
+    /** Total events */
+    totalEvents: number;
+    /** Unique icons used */
+    uniqueIcons: number;
+    /** Top 20 most used icons */
+    mostUsed: {
+        name: string;
+        count: number;
+    }[];
+    /** Recently added icons that are trending */
+    trendingIcons: {
+        name: string;
+        growth: number;
+    }[];
+    /** Icons that may be underused */
+    underutilized: string[];
+    /** Potentially missing icons (common searches with no match) */
+    potentiallyMissing: string[];
+    /** Deprecated icons still in use */
+    deprecatedInUse: {
+        name: string;
+        count: number;
+    }[];
+    /** Per-project breakdown */
+    projectSummaries: ProjectIconSummary[];
+}
+/** Storage configuration */
+export interface AnalyticsStorageConfig {
+    /** Maximum events to keep in memory */
+    maxEventsInMemory: number;
+    /** Auto-persist interval (ms), 0 = disabled */
+    persistInterval: number;
+    /** Storage key for localStorage */
+    storageKey: string;
+    /** Enable console debug logging */
+    debug: boolean;
 }
-declare class IconAnalyticsEngine {
+/**
+ * Icon Analytics Service for tracking usage patterns.
+ */
+export declare class IconAnalyticsService {
     private events;
-    private options;
-    constructor(options?: IconAnalyticsOptions);
-    track(name: string, meta?: {
-        variant?: string;
-        size?: string | number;
-        location?: string;
-    }): void;
-    getReport(): IconAnalyticsReport;
-    getAll(): IconUsageEvent[];
+    private iconStats;
+    private config;
+    private persistTimer;
+    private knownIcons;
+    private deprecatedIcons;
+    private searchMisses;
+    constructor(config?: Partial<AnalyticsStorageConfig>);
+    /**
+     * Track an icon usage event.
+     */
+    track(event: Omit<IconUsageEvent, 'timestamp'>): void;
+    /**
+     * Track a search miss (icon not found).
+     */
+    trackSearchMiss(query: string): void;
+    /**
+     * Register an icon as known (for finding unused).
+     */
+    registerKnownIcon(name: string, deprecated?: boolean): void;
+    /**
+     * Bulk register icons.
+     */
+    registerKnownIcons(icons: {
+        name: string;
+        deprecated?: boolean;
+    }[]): void;
+    private updateStats;
+    /**
+     * Get usage stats for a specific icon.
+     */
+    getIconStats(iconName: string): IconUsageStats | undefined;
+    /**
+     * Get most used icons.
+     */
+    getMostUsedIcons(limit?: number): {
+        name: string;
+        count: number;
+    }[];
+    /**
+     * Get least used icons (icons used but rarely).
+     */
+    getLeastUsedIcons(limit?: number): {
+        name: string;
+        count: number;
+    }[];
+    /**
+     * Get icons that have never been used.
+     */
+    getUnusedIcons(): string[];
+    /**
+     * Get deprecated icons that are still being used.
+     */
+    getDeprecatedInUse(): {
+        name: string;
+        count: number;
+    }[];
+    /**
+     * Get potentially missing icons based on search misses.
+     */
+    getPotentiallyMissingIcons(minMisses?: number): {
+        query: string;
+        misses: number;
+    }[];
+    /**
+     * Get icons used in a specific project.
+     */
+    getIconsByProject(projectId: string): {
+        name: string;
+        count: number;
+    }[];
+    /**
+     * Get project summaries.
+     */
+    getProjectSummaries(): ProjectIconSummary[];
+    /**
+     * Generate full analytics report.
+     */
+    generateReport(periodDays?: number): IconAnalyticsReport;
+    private startPersistTimer;
+    private stopPersistTimer;
+    private saveToStorage;
+    private loadFromStorage;
+    /**
+     * Force save to storage.
+     */
+    persist(): void;
+    /**
+     * Clear all analytics data.
+     */
     clear(): void;
-    private persist;
-}
-interface IconAnalyticsContextValue {
-    track: (name: string, meta?: {
-        variant?: string;
-        size?: string | number;
-        location?: string;
-    }) => void;
-    getReport: () => IconAnalyticsReport;
-    getAll: () => IconUsageEvent[];
-    clear: () => void;
+    /**
+     * Destroy the service (cleanup timers).
+     */
+    destroy(): void;
 }
 /**
- * Hook to access the icon analytics tracker.
- *
- * @returns Analytics functions: `track`, `getReport`, `getAll`, `clear`.
- *
- * @example
- * ```tsx
- * const analytics = useIconAnalytics();
- * analytics.track('NtdHome', { variant: 'solid', size: 'lg' });
- * const report = analytics.getReport();
- * ```
+ * Get the default analytics service instance.
  */
-export declare function useIconAnalytics(): IconAnalyticsContextValue;
+export declare function getIconAnalytics(config?: Partial<AnalyticsStorageConfig>): IconAnalyticsService;
 /**
- * Creates an analytics provider and hook pair.
- *
- * @param options - Analytics configuration
- * @returns `{ AnalyticsProvider, useIconAnalytics }` to wrap your app.
+ * Track an icon usage (shorthand).
+ */
+export declare function trackIconUsage(iconName: string, options?: Partial<Omit<IconUsageEvent, 'iconName' | 'timestamp'>>): void;
+/**
+ * Track a search miss (shorthand).
  */
-export declare function createIconAnalyticsProvider(options?: IconAnalyticsOptions): {
-    AnalyticsProvider: React.FC<{
-        children: React.ReactNode;
-    }>;
-    useIconAnalytics: typeof useIconAnalytics;
-    engine: IconAnalyticsEngine;
-};
-export interface IconAnalyticsDashboardProps {
-    /** Max items to show in top list */
-    maxItems?: number;
-    /** Additional class */
-    className?: string;
-    /** Additional styles */
-    style?: React.CSSProperties;
+export declare function trackIconSearchMiss(query: string): void;
+export interface UseIconAnalyticsReturn {
+    /** Track icon usage */
+    track: (iconName: string, context?: string) => void;
+    /** Most used icons */
+    mostUsed: {
+        name: string;
+        count: number;
+    }[];
+    /** Unused icons */
+    unused: string[];
+    /** Refresh data */
+    refresh: () => void;
+    /** Full report */
+    report: IconAnalyticsReport | null;
+    /** Generate full report */
+    generateReport: (periodDays?: number) => void;
 }
 /**
- * Dashboard component showing icon usage analytics.
- * Displays most-used icons, render counts, and recommendations.
+ * React hook for icon analytics.
  */
-export declare const IconAnalyticsDashboard: React.FC<IconAnalyticsDashboardProps>;
-export {};
+export declare function useIconAnalytics(projectId?: string): UseIconAnalyticsReturn;
+export default IconAnalyticsService;

package/dist/types/index.d.ts

@@ -65,27 +65,39 @@ export type { AnimationStep, AnimationSequenceConfig, AnimationPlaybackState, An
 export { exportIconToFigmaNode, exportIconToSvgString, exportIconToDataUrl, generateFigmaPluginManifest, downloadIconAsSvg, downloadIconAsPng, copyIconToClipboard, batchExportIcons, } from './figmaExport';
 export type { FigmaVectorPath, FigmaVectorNode, FigmaIconFrame, FigmaComponentSet, FigmaExportOptions, FigmaPluginIconEntry, FigmaPluginManifest, } from './figmaExport';
 export * from './icons';
-export { NtdIconMorph, NtdPathMorph, NtdMorphPair, useMorphState, } from './NtdIconMorph';
+export { NtdIconMorph, NtdPathMorph, NtdMorphPair, useMorphState } from './NtdIconMorph';
 export type { NtdIconMorphProps, NtdPathMorphProps, NtdMorphPairProps, MorphPairName, MorphTrigger, } from './NtdIconMorph';
-export { NtdBadge, NtdStatusDot, NtdIconOverlay, NtdIconStack, } from './NtdIconBadge';
+export { NtdBadge, NtdStatusDot, NtdIconOverlay, NtdIconStack } from './NtdIconBadge';
 export type { NtdBadgeProps, NtdStatusDotProps, NtdIconOverlayProps, NtdIconStackProps, BadgePosition, StatusType, } from './NtdIconBadge';
 export { registerIcon, searchIcons, getIcon, getIconMetadata, getIconsByCategory, getAllIcons, getCategoryCounts, getSearchSuggestions, initializeIconMetadata, CATEGORY_INFO, UI_ICON_METADATA, ACTION_ICON_METADATA, } from './iconMetadata';
 export type { IconMetadata, IconSearchResult, IconCategory, SearchMatch, SearchOptions, } from './iconMetadata';
+export { NiceIconEditor, useIconEditor } from './NiceIconEditor';
+export type { NiceIconEditorProps, IconEditorState } from './NiceIconEditor';
+export { NiceIconSetCreator, useIconSetCreator } from './NiceIconSetCreator';
+export type { NiceIconSetCreatorProps, IconSetConfig, IconSetItem } from './NiceIconSetCreator';
+export { NiceIconPreview } from './NiceIconPreview';
+export type { NiceIconPreviewProps, PreviewMode, PreviewLayout, PreviewSize, } from './NiceIconPreview';
+export { NiceFaviconGenerator, useFaviconGenerator } from './NiceFaviconGenerator';
+export type { NiceFaviconGeneratorProps, FaviconSize, ManifestConfig, GeneratedAsset, UseFaviconGeneratorReturn, } from './NiceFaviconGenerator';
+export { NiceDesktopIconExporter, useDesktopIconExporter, DESKTOP_ICON_SIZES, RETINA_VARIANTS, LINUX_HICOLOR_DIRS, } from './NiceDesktopIconExporter';
+export type { NiceDesktopIconExporterProps, DesktopIconSize, RetinaVariant, ExportedIcon, IconExportConfig, UseDesktopIconExporterReturn, } from './NiceDesktopIconExporter';
+export { advancedSearch, levenshteinDistance, fuzzyMatchScore, tokenizeQuery, registerExtendedIcon, getExtendedMetadata, toggleFavorite, isFavorite, getFavorites, recordIconUsage, getRecentlyUsed, findSimilarIcons, getSearchSuggestions as getAdvancedSearchSuggestions, getSearchAnalytics, getIconUsageStats, clearSearchHistory, clearRecentlyUsed, useAdvancedIconSearch, } from './advancedIconSearch';
+export type { IconDomain, IconUseCase, IconStyle, LocalizedNames, ExtendedIconMetadata, AdvancedSearchFilters, AdvancedSearchResult, SearchAnalytics, UseAdvancedSearchReturn, } from './advancedIconSearch';
+export { IconAnalyticsService, getIconAnalytics, trackIconUsage, trackIconSearchMiss, useIconAnalytics, } from './iconAnalytics';
+export type { IconUsageEvent, IconUsageStats, ProjectIconSummary, IconAnalyticsReport, AnalyticsStorageConfig, UseIconAnalyticsReturn, } from './iconAnalytics';
 export { createNiceIconResolver, getResolverIconNames } from './resolver';
 export type { NiceIconResolverOptions } from './resolver';
 export { ntdIconPlugin, ntdIconPreset } from './tailwind-plugin';
 export type { NtdTailwindPluginOptions } from './tailwind-plugin';
 export { isSolidProps, isOutlineProps, isDuotoneProps, isFlatProps, isSharpProps, isRoundedProps, isMiniProps, isThreeDProps, toIconProps, } from './variantProps';
 export type { VariantIconProps, SolidIconProps, OutlineIconProps, DuotoneIconProps, FlatIconProps, SharpIconProps, RoundedIconProps, MiniIconProps, ThreeDIconProps, } from './variantProps';
-export { useIconAnalytics, IconAnalyticsDashboard, createIconAnalyticsProvider } from './iconAnalytics';
-export type { IconUsageEvent, IconAnalyticsOptions, IconAnalyticsReport, IconAnalyticsDashboardProps, } from './iconAnalytics';
 export { NtdStateMorph, useStateMorph } from './NtdStateMorph';
 export type { NtdStateMorphProps, MorphStateMap, StateMorphHandle } from './NtdStateMorph';
 export { NtdLottieIcon, lottieToIcon, exportToLottie } from './lottieIntegration';
-export type { NtdLottieIconProps, LottieAnimationData, LottieExportOptions } from './lottieIntegration';
+export type { NtdLottieIconProps, LottieAnimationData, LottieExportOptions, } from './lottieIntegration';
 export { NtdParticleIcon } from './particleEffects';
 export type { NtdParticleIconProps, ParticlePreset, ParticleConfig } from './particleEffects';
-export { FigmaSyncManager, createFigmaSyncManager, diffIconSets, } from './figmaSync';
+export { FigmaSyncManager, createFigmaSyncManager, diffIconSets } from './figmaSync';
 export type { FigmaSyncConfig, FigmaSyncResult, FigmaIconDiff, FigmaSyncDirection, } from './figmaSync';
 export { NtdIconFloral, NtdIconFestive, NtdIconNeon, NtdIconSketch, NtdIconWatercolor, NtdIconCosmic, NtdIconSteampunk, NtdIconFrost, NtdIconPixel, NtdIconOrganic, NtdIconGeometric, } from './iconStyles';
 export type { IconStyleIntensity, IconStyleBaseProps, NtdIconFloralProps, NtdIconFestiveProps, NtdIconNeonProps, NtdIconSketchProps, NtdIconWatercolorProps, NtdIconCosmicProps, NtdIconSteampunkProps, NtdIconFrostProps, NtdIconPixelProps, NtdIconOrganicProps, NtdIconGeometricProps, } from './iconStyles';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice2dev/icons",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Beautiful, lightweight, multi-color SVG icon library for React with animations",
   "author": "NiceToDev <contact@nicetodev.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -89,7 +89,7 @@
     "test:visual:ci": "npx chromatic --auto-accept-changes=main",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
     "changelog:first": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
-    "version": "npm run changelog && git add CHANGELOG.md"
+    "version": "1.0.8"
   },
   "keywords": [
     "icons",