rn-iconify 2.1.0 → 2.2.0

package/src/cache/CacheManager.ts

@@ -45,6 +45,11 @@ class CacheManagerImpl {
    */
   private bundledIconsInitialized = false;
 
+  /**
+   * Guard to prevent reporting icons during bundle load
+   */
+  private isLoadingBundle = false;
+
   /**
    * Initialize bundled icons from the Babel plugin cache
    * This should be called automatically on first access
@@ -73,13 +78,31 @@ class CacheManagerImpl {
       return 0;
     }
 
+    this.isLoadingBundle = true;
     this.bundledIcons = new Map();
+    let skippedCount = 0;
 
     for (const [iconName, data] of Object.entries(bundle.icons)) {
-      this.bundledIcons.set(iconName, data.svg);
+      if (data && typeof data.svg === 'string' && data.svg.length > 0) {
+        this.bundledIcons.set(iconName, data.svg);
+      } else {
+        skippedCount++;
+        if (__DEV__) {
+          console.warn(`[rn-iconify] Skipping invalid icon in bundle: ${iconName}`);
+        }
+      }
+    }
+
+    if (__DEV__ && skippedCount > 0) {
+      console.warn(`[rn-iconify] Skipped ${skippedCount} invalid icons in bundle`);
     }
 
     this.bundledIconsInitialized = true;
+
+    // Warmup memory cache from disk cache
+    this.warmup();
+
+    this.isLoadingBundle = false;
     return this.bundledIcons.size;
   }
 
@@ -142,6 +165,11 @@ class CacheManagerImpl {
   set(iconName: string, svg: string): void {
     MemoryCache.set(iconName, svg);
     DiskCache.set(iconName, svg);
+
+    // Report to Metro dev server for dynamic icon learning
+    if (!this.isLoadingBundle) {
+      this.reportIconUsage(iconName);
+    }
   }
 
   /**
@@ -334,6 +362,60 @@ class CacheManagerImpl {
       }
     }
   }
+
+  /**
+   * Warmup memory cache by loading recent disk cache entries
+   * Called automatically at the end of loadBundle()
+   *
+   * @param maxIcons Maximum number of icons to load into memory
+   */
+  warmup(maxIcons: number = 100): void {
+    try {
+      const keys = DiskCache.keys();
+      const toLoad = keys.slice(0, maxIcons);
+
+      let loaded = 0;
+      for (const key of toLoad) {
+        if (!MemoryCache.has(key)) {
+          const svg = DiskCache.get(key);
+          if (svg) {
+            MemoryCache.set(key, svg);
+            loaded++;
+          }
+        }
+      }
+
+      if (__DEV__ && loaded > 0) {
+        console.log(`[rn-iconify] Warmed up ${loaded} icons from disk cache`);
+      }
+    } catch {
+      // Warmup is best-effort, don't fail
+    }
+  }
+
+  /**
+   * Report icon usage to Metro dev server (DEV only)
+   * Fire-and-forget POST to the Metro middleware
+   */
+  reportIconUsage(iconName: string): void {
+    if (typeof __DEV__ === 'undefined' || !__DEV__) return;
+    if (this.isLoadingBundle) return;
+
+    try {
+      // Use global fetch if available (React Native)
+      if (typeof fetch === 'function') {
+        fetch('http://localhost:8081/__rn_iconify_log', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ icon: iconName }),
+        }).catch(() => {
+          // Silently ignore - Metro server might not have the plugin
+        });
+      }
+    } catch {
+      // Silently ignore
+    }
+  }
 }
 
 // Singleton instance

package/src/cache/DiskCache.ts

@@ -1,14 +1,53 @@
 /**
  * Disk cache using MMKV for persistent icon storage
  * Provides fast synchronous access via JSI
+ *
+ * Supports both react-native-mmkv v3.x and v4.x
  */
 
-import { MMKV } from 'react-native-mmkv';
+import * as MMKVModule from 'react-native-mmkv';
+
+/**
+ * MMKV storage interface (compatible with both v3 and v4)
+ */
+interface MMKVStorage {
+  getString(key: string): string | undefined;
+  set(key: string, value: string | number | boolean): void;
+  getNumber(key: string): number | undefined;
+  contains(key: string): boolean;
+  delete(key: string): void;
+  clearAll(): void;
+  getAllKeys(): string[];
+}
+
+/**
+ * Create MMKV instance compatible with both v3.x and v4.x
+ *
+ * v3.x: import { MMKV } from 'react-native-mmkv' → new MMKV({ id: '...' })
+ * v4.x: import { createMMKV } from 'react-native-mmkv' → createMMKV({ id: '...' })
+ */
+function createStorage(id: string): MMKVStorage {
+  const config = { id };
+
+  // v4.x: createMMKV function exists
+  if ('createMMKV' in MMKVModule && typeof MMKVModule.createMMKV === 'function') {
+    return MMKVModule.createMMKV(config) as MMKVStorage;
+  }
+
+  // v3.x: MMKV is a constructor
+  if ('MMKV' in MMKVModule && typeof MMKVModule.MMKV === 'function') {
+    const MMKVClass = MMKVModule.MMKV as new (config: { id: string }) => MMKVStorage;
+    return new MMKVClass(config);
+  }
+
+  throw new Error(
+    '[rn-iconify] Could not initialize MMKV storage. ' +
+      'Please ensure react-native-mmkv (v3.x or v4.x) is properly installed.'
+  );
+}
 
 // MMKV instance for icon cache
-const storage = new MMKV({
-  id: 'rn-iconify-cache',
-});
+const storage = createStorage('rn-iconify-cache');
 
 // Cache metadata storage
 const META_KEY_PREFIX = '__meta:';

package/src/cli/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+_No recent activity_
+</claude-mem-context>

package/src/cli/commands/bundle.ts

@@ -19,6 +19,52 @@ const ICONIFY_API = 'https://api.iconify.design';
  */
 const FETCH_TIMEOUT = 30000;
 
+/**
+ * Icon data from Iconify API
+ */
+interface IconData {
+  body: string;
+  width?: number;
+  height?: number;
+  left?: number;
+  top?: number;
+  rotate?: number;
+  hFlip?: boolean;
+  vFlip?: boolean;
+}
+
+/**
+ * Build SVG string from Iconify icon data with transformation support
+ */
+function buildSvgFromIconData(data: IconData, width: number, height: number): string {
+  const left = data.left ?? 0;
+  const top = data.top ?? 0;
+  const viewBox = `${left} ${top} ${width} ${height}`;
+
+  // Apply transformations (rotate, hFlip, vFlip)
+  let body = data.body;
+  const transforms: string[] = [];
+
+  if (data.rotate) {
+    const rotation = data.rotate * 90;
+    transforms.push(`rotate(${rotation} ${width / 2} ${height / 2})`);
+  }
+
+  if (data.hFlip || data.vFlip) {
+    const scaleX = data.hFlip ? -1 : 1;
+    const scaleY = data.vFlip ? -1 : 1;
+    const translateX = data.hFlip ? width : 0;
+    const translateY = data.vFlip ? height : 0;
+    transforms.push(`translate(${translateX} ${translateY}) scale(${scaleX} ${scaleY})`);
+  }
+
+  if (transforms.length > 0) {
+    body = `<g transform="${transforms.join(' ')}">${body}</g>`;
+  }
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}">${body}</svg>`;
+}
+
 /**
  * Fetch multiple icons with batching
  */
@@ -45,10 +91,10 @@ async function fetchIcons(
 
   // Fetch each prefix batch
   for (const [prefix, names] of byPrefix) {
-    try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
 
+    try {
       // Sort names alphabetically (Iconify best practice)
       const sortedNames = [...names].sort();
       const url = `${ICONIFY_API}/${prefix}.json?icons=${sortedNames.join(',')}`;
@@ -58,7 +104,6 @@ async function fetchIcons(
       }
 
       const response = await fetch(url, { signal: controller.signal });
-      clearTimeout(timeout);
 
       if (!response.ok) {
         console.error(`  Failed to fetch ${prefix}: ${response.status}`);
@@ -76,8 +121,7 @@ async function fetchIcons(
         if (iconData) {
           const width = iconData.width ?? defaultWidth;
           const height = iconData.height ?? defaultHeight;
-          const body = iconData.body;
-          const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${body}</svg>`;
+          const svg = buildSvgFromIconData(iconData, width, height);
 
           results[`${prefix}:${name}`] = { svg, width, height };
         } else if (verbose) {
@@ -92,6 +136,8 @@ async function fetchIcons(
         console.error(`  Error fetching ${prefix}:`, error);
       }
       processed += names.length;
+    } finally {
+      clearTimeout(timeout);
     }
   }
 

package/src/config/ConfigManager.ts

@@ -8,6 +8,7 @@ import type {
   IconifyAPIConfig,
   CacheConfig,
   PerformanceConfig,
+  DefaultsConfig,
   ResolvedConfig,
 } from './types';
 import { DEFAULT_CONFIG } from './types';
@@ -83,6 +84,13 @@ export const ConfigManager = {
     return currentConfig.performance;
   },
 
+  /**
+   * Get defaults configuration
+   */
+  getDefaultsConfig(): Required<DefaultsConfig> {
+    return currentConfig.defaults;
+  },
+
   /**
    * Update configuration
    * Merges with existing configuration
@@ -92,6 +100,7 @@ export const ConfigManager = {
       api: deepMerge(currentConfig.api, config.api ?? {}),
       cache: deepMerge(currentConfig.cache, config.cache ?? {}),
       performance: deepMerge(currentConfig.performance, config.performance ?? {}),
+      defaults: deepMerge(currentConfig.defaults, config.defaults ?? {}),
     };
 
     // Notify listeners

package/src/config/index.ts

@@ -22,6 +22,7 @@ export type {
   IconifyAPIConfig,
   CacheConfig,
   PerformanceConfig,
+  DefaultsConfig,
   ResolvedConfig,
 } from './types';
 

package/src/config/types.ts

@@ -65,6 +65,30 @@ export interface CacheConfig {
   diskCachePrefix?: string;
 }
 
+/**
+ * Default icon rendering configuration
+ */
+export interface DefaultsConfig {
+  /**
+   * Default placeholder to show while loading icons
+   * Set to false to explicitly disable
+   * @default undefined (no placeholder - non-breaking)
+   */
+  placeholder?: 'skeleton' | 'pulse' | 'shimmer' | false;
+
+  /**
+   * Enable fade-in transition for non-cached icons
+   * @default true
+   */
+  fadeIn?: boolean;
+
+  /**
+   * Fade-in animation duration in milliseconds
+   * @default 150
+   */
+  fadeInDuration?: number;
+}
+
 /**
  * Performance monitoring configuration
  */
@@ -112,6 +136,11 @@ export interface IconifyConfig {
    * Performance monitoring configuration
    */
   performance?: PerformanceConfig;
+
+  /**
+   * Default icon rendering configuration
+   */
+  defaults?: DefaultsConfig;
 }
 
 /**
@@ -121,6 +150,7 @@ export interface ResolvedConfig {
   api: Required<IconifyAPIConfig>;
   cache: Required<CacheConfig>;
   performance: Required<PerformanceConfig>;
+  defaults: Required<DefaultsConfig>;
 }
 
 /**
@@ -146,4 +176,9 @@ export const DEFAULT_CONFIG: ResolvedConfig = {
     trackCacheStats: true,
     maxHistorySize: 1000,
   },
+  defaults: {
+    placeholder: false,
+    fadeIn: true,
+    fadeInDuration: 150,
+  },
 };

package/src/index.ts

@@ -150,6 +150,7 @@ export type {
   IconifyAPIConfig,
   CacheConfig,
   PerformanceConfig,
+  DefaultsConfig,
   ResolvedConfig,
 } from './config';
 

package/src/metro/devServerMiddleware.ts

@@ -0,0 +1,137 @@
+/**
+ * Metro Dev Server Middleware
+ * Handles runtime icon usage reporting from the app
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { UsageFile, RnIconifyMetroOptions } from './types';
+
+const USAGE_ENDPOINT = '/__rn_iconify_log';
+const STATUS_ENDPOINT = '/__rn_iconify_status';
+
+/**
+ * Read the current usage file
+ */
+function readUsageFile(usagePath: string): UsageFile {
+  try {
+    if (fs.existsSync(usagePath)) {
+      const content = fs.readFileSync(usagePath, 'utf-8');
+      const data = JSON.parse(content) as UsageFile;
+      if (data.version === '1.0.0' && Array.isArray(data.icons)) {
+        return data;
+      }
+    }
+  } catch {
+    // File corrupted or doesn't exist
+  }
+
+  return { version: '1.0.0', icons: [], updatedAt: new Date().toISOString() };
+}
+
+/**
+ * Write usage file atomically (temp file + rename)
+ */
+function writeUsageFile(usagePath: string, data: UsageFile): void {
+  const dir = path.dirname(usagePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = usagePath + '.tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+  fs.renameSync(tmpPath, usagePath);
+}
+
+/**
+ * Parse JSON body from request
+ */
+function parseBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk: Buffer) => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(body) as Record<string, unknown>);
+      } catch {
+        reject(new Error('Invalid JSON'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Create the dev server middleware handler
+ */
+export function createDevServerMiddleware(options: RnIconifyMetroOptions = {}) {
+  const { outputDir = '.rn-iconify', verbose = false } = options;
+  const projectRoot = process.cwd();
+  const usagePath = path.isAbsolute(outputDir)
+    ? path.join(outputDir, 'usage.json')
+    : path.join(projectRoot, outputDir, 'usage.json');
+
+  return async function handleRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: () => void
+  ): Promise<void> {
+    const url = req.url;
+
+    // POST /__rn_iconify_log — report icon usage
+    if (req.method === 'POST' && url === USAGE_ENDPOINT) {
+      try {
+        const body = await parseBody(req);
+        const icon = body.icon;
+
+        if (typeof icon !== 'string' || !icon.includes(':')) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid icon name' }));
+          return;
+        }
+
+        // Read existing usage
+        const usage = readUsageFile(usagePath);
+
+        // Deduplicate
+        if (!usage.icons.includes(icon)) {
+          usage.icons.push(icon);
+          usage.updatedAt = new Date().toISOString();
+          writeUsageFile(usagePath, usage);
+
+          if (verbose) {
+            console.log(`[rn-iconify:metro] Learned icon: ${icon} (total: ${usage.icons.length})`);
+          }
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+      } catch (error) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Internal error' }));
+      }
+      return;
+    }
+
+    // GET /__rn_iconify_status — debug stats
+    if (req.method === 'GET' && url === STATUS_ENDPOINT) {
+      const usage = readUsageFile(usagePath);
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          iconCount: usage.icons.length,
+          icons: usage.icons,
+          updatedAt: usage.updatedAt,
+        })
+      );
+      return;
+    }
+
+    // Pass through to next middleware
+    next();
+  };
+}

package/src/metro/index.ts

@@ -0,0 +1,19 @@
+/**
+ * rn-iconify Metro Plugin
+ *
+ * Adds dev server middleware for runtime icon usage learning.
+ * When used with the Babel plugin, enables zero-config 0ms rendering.
+ *
+ * @example
+ * ```js
+ * // metro.config.js
+ * const { withRnIconify } = require('rn-iconify/metro');
+ *
+ * const config = getDefaultConfig(__dirname);
+ * module.exports = withRnIconify(config);
+ * ```
+ */
+
+export { withRnIconify } from './withRnIconify';
+export { createDevServerMiddleware } from './devServerMiddleware';
+export type { MetroConfig, RnIconifyMetroOptions, UsageFile } from './types';

package/src/metro/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Metro configuration types
+ * Minimal type definitions for Metro config integration
+ */
+
+import type { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Metro middleware function
+ */
+export type MetroMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+
+/**
+ * Metro server configuration
+ */
+export interface MetroServerConfig {
+  enhanceMiddleware?: (middleware: MetroMiddleware, server: unknown) => MetroMiddleware;
+}
+
+/**
+ * Metro configuration object (partial, only what we need)
+ */
+export interface MetroConfig {
+  server?: MetroServerConfig;
+  [key: string]: unknown;
+}
+
+/**
+ * rn-iconify Metro plugin options
+ */
+export interface RnIconifyMetroOptions {
+  /**
+   * Directory to store usage data
+   * @default '.rn-iconify'
+   */
+  outputDir?: string;
+
+  /**
+   * Enable verbose logging
+   * @default false
+   */
+  verbose?: boolean;
+}
+
+/**
+ * Usage file structure
+ */
+export interface UsageFile {
+  version: string;
+  icons: string[];
+  updatedAt: string;
+}

package/src/metro/withRnIconify.ts

@@ -0,0 +1,52 @@
+/**
+ * Metro Config Wrapper
+ * Adds rn-iconify middleware to the Metro dev server
+ *
+ * @example
+ * ```js
+ * // metro.config.js
+ * const { withRnIconify } = require('rn-iconify/metro');
+ *
+ * const config = getDefaultConfig(__dirname);
+ * module.exports = withRnIconify(config);
+ * ```
+ */
+
+import type { MetroConfig, MetroMiddleware, RnIconifyMetroOptions } from './types';
+import { createDevServerMiddleware } from './devServerMiddleware';
+
+/**
+ * Wrap a Metro config to add rn-iconify dev server middleware
+ * This enables runtime icon usage learning during development
+ */
+export function withRnIconify(config: MetroConfig, options?: RnIconifyMetroOptions): MetroConfig {
+  const middleware = createDevServerMiddleware(options);
+
+  const existingEnhance = config.server?.enhanceMiddleware;
+
+  return {
+    ...config,
+    server: {
+      ...config.server,
+      enhanceMiddleware: (metroMiddleware: MetroMiddleware, server: unknown): MetroMiddleware => {
+        // Apply existing enhanceMiddleware if present
+        const enhanced = existingEnhance
+          ? existingEnhance(metroMiddleware, server)
+          : metroMiddleware;
+
+        // Wrap with our middleware
+        return (req, res, next) => {
+          // Check if this is our endpoint
+          const url = req.url;
+          if (url === '/__rn_iconify_log' || url === '/__rn_iconify_status') {
+            middleware(req, res, next);
+            return;
+          }
+
+          // Otherwise pass through
+          enhanced(req, res, next);
+        };
+      },
+    },
+  };
+}

package/src/network/IconifyAPI.ts

@@ -62,19 +62,41 @@ async function fetchWithTimeout(
 
 /**
  * Combine multiple AbortSignals into one
+ * Properly cleans up event listeners to prevent memory leaks
  */
 function anySignal(signals: AbortSignal[]): AbortSignal {
   const controller = new AbortController();
 
+  // Check if any signal is already aborted
   for (const signal of signals) {
     if (signal.aborted) {
       controller.abort();
       return controller.signal;
     }
+  }
+
+  // Create abort handlers that we can clean up
+  const abortHandlers: Array<{ signal: AbortSignal; handler: () => void }> = [];
+
+  const cleanup = () => {
+    for (const { signal, handler } of abortHandlers) {
+      signal.removeEventListener('abort', handler);
+    }
+    abortHandlers.length = 0;
+  };
 
-    signal.addEventListener('abort', () => controller.abort(), { once: true });
+  for (const signal of signals) {
+    const handler = () => {
+      cleanup();
+      controller.abort();
+    };
+    abortHandlers.push({ signal, handler });
+    signal.addEventListener('abort', handler);
   }
 
+  // Also cleanup when our controller aborts (from timeout)
+  controller.signal.addEventListener('abort', cleanup, { once: true });
+
   return controller.signal;
 }