viconic-react-icons 1.4.1 → 1.5.0

package/README.md

@@ -1,21 +1,27 @@
-# Viconic React Icons
+# Viconic React Icons
 
-![NPM Version](https://img.shields.io/npm/v/viconic-react-icons)
-![NPM License](https://img.shields.io/npm/l/viconic-react-icons)
+[![NPM Version](https://img.shields.io/npm/v/viconic-react-icons?style=flat-square&color=blue)](https://www.npmjs.com/package/viconic-react-icons)
+[![NPM License](https://img.shields.io/npm/l/viconic-react-icons?style=flat-square)](https://github.com/noname21024/copyicons-backend)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/viconic-react-icons?style=flat-square&label=bundle%20size)](https://bundlephobia.com/package/viconic-react-icons)
 
 The official React component wrapper for [Viconic](https://viconic.dev), a modern, hyper-fast, CDN-powered icon system.
 
-`viconic-react-icons` gives you access to over 200,000+ open-source, pixel-perfect icons grouped in customizable collections. The icons are loaded dynamically from our Smart CDN at runtime, meaning your React bundle stays incredibly lightweight regardless of how many icons you use.
+`viconic-react-icons` gives you access to over **200,000+ open-source, pixel-perfect icons** grouped in customizable collections. The icons are loaded dynamically from our Smart CDN at runtime, meaning your React bundle stays incredibly lightweight regardless of how many icons you use.
 
-## Highlights
-- 🪶 **Zero-Bundle Bloat**: SVGs are fetched magically via our CDN and injected directly into the DOM.
-- 🎨 **Fully Customizable**: Compatible with Tailwind CSS and standard inline styles. Inherits color natively via `currentColor`.
-- ⚡ **Smart Caching**: LocalStorage and Memory caching so icons appear instantly on repeated renders.
-- 🔧 **Kit Support**: Use your custom icon kit with `initViconic()` — supports multiple kits.
-- 🖥️ **SSR Ready**: Fully supports Next.js, Vite, and other Server-Side Rendering frameworks.
-- 📘 **TypeScript Support**: Includes built-in types for easy autocompletion.
+---
 
-## Installation
+## 🌟 Highlights
+
+*   🪶 **Zero-Bundle Bloat**: SVGs are fetched magically via our CDN and injected directly into the DOM.
+*   ⚡ **Smart Caching**: LocalStorage and Memory caching so icons appear instantly on repeated renders. Event-driven icon injection for ultra-fast, progressive rendering.
+*   �� **Fully Customizable**: Compatible with Tailwind CSS and standard inline styles. Inherits color natively via `currentColor`.
+*   🔧 **Kit Support**: Use your custom icon kit with `initViconic()` — supports multiple kits and user-uploaded SVGs simultaneously.
+*   🖥️ **SSR Ready**: Fully supports Next.js, Vite, Remix, and other Server-Side Rendering frameworks.
+*   📘 **TypeScript Support**: Includes built-in types for easy autocompletion.
+
+---
+
+## 📦 Installation
 
 ```bash
 npm install viconic-react-icons
@@ -25,7 +31,11 @@ yarn add viconic-react-icons
 pnpm add viconic-react-icons
 ```
 
-## Quick Start — System Icons
+---
+
+## 🚀 Quick Start
+
+### 1. System Icons (200k+ Free Icons)
 
 Import the `ViconicIcon` component and pass the unique `name` identifier corresponding to your icon of choice from [viconic.dev](https://viconic.dev).
 
@@ -37,7 +47,7 @@ function App() {
     <div style={{ display: "flex", gap: "10px" }}>
       {/* Basic Usage */}
       <ViconicIcon name="h2:0" />
-      
+
       {/* With Tailwind CSS */}
       <ViconicIcon name="lucide:home" className="w-8 h-8 text-blue-500" />
       
@@ -48,17 +58,17 @@ function App() {
 }
 ```
 
-## Quick Start — Custom Kit
+### 2. Custom Kits & Uploaded Icons
 
-Use icons from your own kit created at [viconic.dev](https://viconic.dev):
+Use icons from your own customized kit (including your own SVG uploads) created at [viconic.dev](https://viconic.dev):
 
 ```jsx
 import { initViconic, ViconicIcon } from "viconic-react-icons";
 
-// Initialize your kit — call once at app startup (e.g., in main.jsx or App.jsx)
+// Initialize your kit — call once at app startup (e.g., in main.jsx or _app.tsx)
 initViconic({ kitId: "your-kit-uuid-here" });
 
-// You can load multiple kits!
+// You can load multiple kits at the same time!
 initViconic({ kitId: "another-kit-uuid" });
 
 function App() {
@@ -66,21 +76,23 @@ function App() {
     <div style={{ display: "flex", gap: "10px" }}>
       {/* Kit icon using @prefix/name format */}
       <ViconicIcon name="@myprefix/home" />
-      
-      {/* Kit icon using prefix:name format (also works) */}
-      <ViconicIcon name="myprefix:settings" />
-      
+
+      {/* User uploaded icon format */}
+      <ViconicIcon name="@myprefix/my-custom-logo" size="48px" />
+
       {/* Mix kit icons with system icons */}
-      <ViconicIcon name="lucide:star" />
+      <ViconicIcon name="lucide:star" color="#FFD700" />
     </div>
   );
 }
 ```
 
-## Props
+---
+
+## 🎛️ Props
 
 | Prop | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
+| :--- | :--- | :--- | :--- |
 | `name` | `string` | `undefined` | **Required.** The unique icon ID (e.g. `lucide:activity`, `@prefix/name`). |
 | `size` | `string \| number` | `undefined` | Icon size as CSS value (e.g. `"24px"`, `"2rem"`). |
 | `color` | `string` | `undefined` | Icon color as CSS value (e.g. `"red"`, `"#333"`). |
@@ -88,32 +100,46 @@ function App() {
 | `style` | `React.CSSProperties` | `{}` | Inline CSS styling. |
 | `...props` | `HTMLAttributes` | | Spread standard HTML attributes (e.g. `onClick`, `title`). |
 
-## API
+---
+
+## 🛠️ API Reference
 
 ### `initViconic(options)`
 
-Inject a kit's loader script into `<head>`. Call once per kit at app startup.
+Inject a kit's smart loader script into `<head>`. Call once per kit at app startup.
 
 | Option | Type | Default | Description |
-| ------ | ---- | ------- | ----------- |
+| :--- | :--- | :--- | :--- |
 | `kitId` | `string` | — | **Required.** UUID of your Viconic Kit. |
 | `cdnBase` | `string` | `"cdn.viconic.dev"` | Custom CDN domain. |
+| `version` | `string` | `undefined` | Cache-bust version. **Update this every time you add/remove icons in your kit.** |
 
 ```jsx
 // In your main.jsx or App.jsx
 import { initViconic } from "viconic-react-icons";
 
-initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd" });
+// Copy the exact snippet from the "Usage & Setup" tab in your Kit Editor
+// It already includes the correct version timestamp for your kit.
+initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd", version: "1774867419" });
 ```
 
-## Architecture
+> **⚠️ Important — Cache Busting:**  
+> Every time you update your kit on [viconic.dev](https://viconic.dev) (add/remove icons, click **"Update Kit"**), you must update the `version` value in `initViconic()` to the new timestamp shown in the **Usage & Setup** tab.  
+> This ensures your users always load the latest kit instead of a stale cached version.  
+> The **Usage & Setup** tab always shows the ready-to-copy snippet with the current version pre-filled.
+
+---
+
+## 🧠 Architecture
+
+This package is a high-performance React wrapper around `<viconic-icon>` Web Components. The included smart loader script dynamically monitors the DOM using a lightweight `MutationObserver` and rapidly replaces `<viconic-icon>` elements with actual raw `<svg>` code.
 
-This package is a React wrapper around `<viconic-icon>` Web Components. The included `copyicons-smart-loader.js` script dynamically monitors the DOM using a `MutationObserver` and rapidly replaces `<viconic-icon>` elements with actual raw `<svg>` code. 
+When using kits, `initViconic()` injects the kit's loader from CDN, which leverages **chunked batch fetching**, **event-driven rendering**, and **parallel processing**.
 
-When using kits, `initViconic()` injects the kit's loader.js from CDN, which fetches your kit's icon map and SVGs in parallel.
+Because we fetch SVGs in parallel and cache them heavily via LocalStorage across user sessions, your frontend performance score will skyrocket compared to packing large icon sets directly into your JS chunks.
 
-Because we fetch SVGs in parallel and cache them across user sessions, your frontend performance score will skyrocket compared to packing large icon sets directly into your JS chunks.
+---
 
-## License
+## 📄 License
 
-This project is licensed under the MIT License. Icon licenses depend on the specific icon families you request.
+This project is licensed under the MIT License. Icon licenses depend on the specific icon families you use.

package/dist/index.js

@@ -2003,6 +2003,54 @@ var import_react = __toESM(require("react"));
   }
 })();
 var _initializedKits = /* @__PURE__ */ new Set();
+var _kitMissQueues = {};
+var _kitMissTimers = {};
+function _queueKitMiss(prefix, iconBaseName) {
+  if (typeof window === "undefined") return;
+  const kits = window.CopyIconsKit || {};
+  let kitId = null;
+  for (const kId in kits) {
+    const kit = kits[kId];
+    if (kit.config && kit.config.prefix === prefix) {
+      kitId = kId;
+      break;
+    }
+  }
+  if (!kitId) return;
+  if (!_kitMissQueues[kitId]) _kitMissQueues[kitId] = /* @__PURE__ */ new Set();
+  _kitMissQueues[kitId].add(iconBaseName);
+  if (_kitMissTimers[kitId]) return;
+  _kitMissTimers[kitId] = setTimeout(() => {
+    delete _kitMissTimers[kitId];
+    const names = [..._kitMissQueues[kitId] || []];
+    delete _kitMissQueues[kitId];
+    if (!names.length) return;
+    const kit = (window.CopyIconsKit || {})[kitId];
+    if (!kit || !kit.config) return;
+    const api = kit.config.api || "https://api.viconic.dev";
+    fetch(`${api}/api/v1/kits/${kitId}/icons/?icons=${names.join(",")}`).then((r) => r.ok ? r.json() : null).then((bj) => {
+      if (!bj || !bj.icons) return;
+      const W = window.__viconic = window.__viconic || {};
+      W.icons = W.icons || {};
+      const pfx = kit.config.prefix;
+      for (const n in bj.icons) {
+        if (!Object.prototype.hasOwnProperty.call(bj.icons, n)) continue;
+        const d = bj.icons[n];
+        const svg = d.svg || "";
+        if (!svg || !svg.includes("<")) continue;
+        W.icons[`@${pfx}/${n}`] = svg;
+        W.icons[`${pfx}:${n}`] = svg;
+        W.icons[`${pfx}/${n}`] = svg;
+        W.icons[n] = W.icons[n] || svg;
+      }
+      try {
+        document.dispatchEvent(new CustomEvent("viconic:ready", { detail: { prefix: pfx, kitId } }));
+      } catch (e) {
+      }
+    }).catch(() => {
+    });
+  }, 0);
+}
 function initViconic(options = {}) {
   const { kitId, cdnBase = "cdn.viconic.dev", version } = options;
   if (typeof window === "undefined") return;
@@ -2084,17 +2132,10 @@ var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
       tryInjectFromEvent();
       if (!isInjected() && isKitIcon && prefixMatch) {
         const prefix = prefixMatch[1];
-        if (window.CopyIconsKit) {
-          for (const kId in window.CopyIconsKit) {
-            const kit = window.CopyIconsKit[kId];
-            if (kit.config && kit.config.prefix === prefix && typeof kit.reload === "function") {
-              kit.reload();
-              break;
-            }
-          }
-        }
+        const iconBaseName = prefixMatch[2];
+        _queueKitMiss(prefix, iconBaseName);
       }
-    }, 500);
+    }, 50);
     return () => {
       document.removeEventListener("viconic:ready", tryInjectFromEvent);
       clearTimeout(fallbackTimer);

package/dist/index.mjs

@@ -1968,6 +1968,54 @@ import React, { useEffect, useRef } from "react";
   }
 })();
 var _initializedKits = /* @__PURE__ */ new Set();
+var _kitMissQueues = {};
+var _kitMissTimers = {};
+function _queueKitMiss(prefix, iconBaseName) {
+  if (typeof window === "undefined") return;
+  const kits = window.CopyIconsKit || {};
+  let kitId = null;
+  for (const kId in kits) {
+    const kit = kits[kId];
+    if (kit.config && kit.config.prefix === prefix) {
+      kitId = kId;
+      break;
+    }
+  }
+  if (!kitId) return;
+  if (!_kitMissQueues[kitId]) _kitMissQueues[kitId] = /* @__PURE__ */ new Set();
+  _kitMissQueues[kitId].add(iconBaseName);
+  if (_kitMissTimers[kitId]) return;
+  _kitMissTimers[kitId] = setTimeout(() => {
+    delete _kitMissTimers[kitId];
+    const names = [..._kitMissQueues[kitId] || []];
+    delete _kitMissQueues[kitId];
+    if (!names.length) return;
+    const kit = (window.CopyIconsKit || {})[kitId];
+    if (!kit || !kit.config) return;
+    const api = kit.config.api || "https://api.viconic.dev";
+    fetch(`${api}/api/v1/kits/${kitId}/icons/?icons=${names.join(",")}`).then((r) => r.ok ? r.json() : null).then((bj) => {
+      if (!bj || !bj.icons) return;
+      const W = window.__viconic = window.__viconic || {};
+      W.icons = W.icons || {};
+      const pfx = kit.config.prefix;
+      for (const n in bj.icons) {
+        if (!Object.prototype.hasOwnProperty.call(bj.icons, n)) continue;
+        const d = bj.icons[n];
+        const svg = d.svg || "";
+        if (!svg || !svg.includes("<")) continue;
+        W.icons[`@${pfx}/${n}`] = svg;
+        W.icons[`${pfx}:${n}`] = svg;
+        W.icons[`${pfx}/${n}`] = svg;
+        W.icons[n] = W.icons[n] || svg;
+      }
+      try {
+        document.dispatchEvent(new CustomEvent("viconic:ready", { detail: { prefix: pfx, kitId } }));
+      } catch (e) {
+      }
+    }).catch(() => {
+    });
+  }, 0);
+}
 function initViconic(options = {}) {
   const { kitId, cdnBase = "cdn.viconic.dev", version } = options;
   if (typeof window === "undefined") return;
@@ -2049,17 +2097,10 @@ var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
       tryInjectFromEvent();
       if (!isInjected() && isKitIcon && prefixMatch) {
         const prefix = prefixMatch[1];
-        if (window.CopyIconsKit) {
-          for (const kId in window.CopyIconsKit) {
-            const kit = window.CopyIconsKit[kId];
-            if (kit.config && kit.config.prefix === prefix && typeof kit.reload === "function") {
-              kit.reload();
-              break;
-            }
-          }
-        }
+        const iconBaseName = prefixMatch[2];
+        _queueKitMiss(prefix, iconBaseName);
       }
-    }, 500);
+    }, 50);
     return () => {
       document.removeEventListener("viconic:ready", tryInjectFromEvent);
       clearTimeout(fallbackTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viconic-react-icons",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Viconic Smart Icons loader for React — supports Kit and 200k+ system icons",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.jsx

@@ -36,6 +36,60 @@ import './copyicons-smart-loader.js';
 // ============================================
 const _initializedKits = new Set();
 
+// ============================================
+// DEBOUNCED BATCH FETCH for missing kit icons
+// All ViconicIcon mounts queue their miss here;
+// a single setTimeout(0) fires ONE batch request
+// per kit instead of N individual kit.reload() calls.
+// ============================================
+const _kitMissQueues = {}; // kitId -> Set of icon names
+const _kitMissTimers = {}; // kitId -> timer handle
+
+function _queueKitMiss(prefix, iconBaseName) {
+    if (typeof window === 'undefined') return;
+    // Find kit by prefix
+    const kits = window.CopyIconsKit || {};
+    let kitId = null;
+    for (const kId in kits) {
+        const kit = kits[kId];
+        if (kit.config && kit.config.prefix === prefix) { kitId = kId; break; }
+    }
+    if (!kitId) return;
+    if (!_kitMissQueues[kitId]) _kitMissQueues[kitId] = new Set();
+    _kitMissQueues[kitId].add(iconBaseName);
+    if (_kitMissTimers[kitId]) return; // already scheduled
+    _kitMissTimers[kitId] = setTimeout(() => {
+        delete _kitMissTimers[kitId];
+        const names = [...(_kitMissQueues[kitId] || [])];
+        delete _kitMissQueues[kitId];
+        if (!names.length) return;
+        const kit = (window.CopyIconsKit || {})[kitId];
+        if (!kit || !kit.config) return;
+        const api = kit.config.api || 'https://api.viconic.dev';
+        fetch(`${api}/api/v1/kits/${kitId}/icons/?icons=${names.join(',')}`)
+            .then(r => r.ok ? r.json() : null)
+            .then(bj => {
+                if (!bj || !bj.icons) return;
+                const W = (window.__viconic = window.__viconic || {});
+                W.icons = W.icons || {};
+                const pfx = kit.config.prefix;
+                for (const n in bj.icons) {
+                    if (!Object.prototype.hasOwnProperty.call(bj.icons, n)) continue;
+                    const d = bj.icons[n];
+                    const svg = d.svg || '';
+                    if (!svg || !svg.includes('<')) continue;
+                    W.icons[`@${pfx}/${n}`] = svg;
+                    W.icons[`${pfx}:${n}`] = svg;
+                    W.icons[`${pfx}/${n}`] = svg;
+                    W.icons[n] = W.icons[n] || svg;
+                }
+                // Fire viconic:ready so all waiting ViconicIcon components inject
+                try { document.dispatchEvent(new CustomEvent('viconic:ready', { detail: { prefix: pfx, kitId } })); } catch(e) {}
+            })
+            .catch(() => {});
+    }, 0); // setTimeout(0): collect ALL icon misses from current render cycle
+}
+
 /**
  * Initialize a Viconic Kit in your React app.
  * Injects the kit's loader.js script into <head>.
@@ -169,24 +223,17 @@ export const ViconicIcon = ({ name, className, style, size, color, ...props }) =
 
         document.addEventListener('viconic:ready', tryInjectFromEvent);
 
-        // --- PATH 5: Short-deadline fallback (500ms) in case script already fired before we listened ---
+        // --- PATH 5: Short-deadline fallback (50ms) — queue a batch fetch for all missing kit icons ---
         const fallbackTimer = setTimeout(() => {
             if (isInjected()) return;
             tryInjectFromEvent();
-            // If still not loaded after 500ms, trigger kit reload once
             if (!isInjected() && isKitIcon && prefixMatch) {
                 const prefix = prefixMatch[1];
-                if (window.CopyIconsKit) {
-                    for (const kId in window.CopyIconsKit) {
-                        const kit = window.CopyIconsKit[kId];
-                        if (kit.config && kit.config.prefix === prefix && typeof kit.reload === 'function') {
-                            kit.reload();
-                            break;
-                        }
-                    }
-                }
+                const iconBaseName = prefixMatch[2];
+                // Use batch queue instead of kit.reload() to avoid N separate API calls
+                _queueKitMiss(prefix, iconBaseName);
             }
-        }, 500);
+        }, 50);
 
         return () => {
             document.removeEventListener('viconic:ready', tryInjectFromEvent);