npm - viconic-react-icons - Versions diffs - 1.4.0 → 1.4.2 - Mend

viconic-react-icons 1.4.0 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -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,16 +100,19 @@ 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` | Bypass cache version (e.g. pass `"dev"` or a timestamp). |
 ```jsx
 // In your main.jsx or App.jsx
@@ -106,14 +121,18 @@ import { initViconic } from "viconic-react-icons";
 initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd" });
 ```
-## Architecture
+---
+## 🧠 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/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "viconic-react-icons",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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 CHANGED Viewed

@@ -1,214 +1,214 @@
-import React, { useEffect, useRef } from 'react';
-import './copyicons-smart-loader.js';
-// ============================================
-// PRE-LOAD KIT CACHE SYNCHRONOUSLY AT MODULE LEVEL
-// Same architecture as kit loader: read localStorage before any render
-// so icons are available instantly when components mount.
-// ============================================
-(function _preloadKitCache() {
-    if (typeof window === 'undefined' || typeof localStorage === 'undefined') return;
-    try {
-        const W = (window.__viconic = window.__viconic || {});
-        W.icons = W.icons || {};
-        const TTL = 3 * 24 * 60 * 60 * 1000; // 3 days
-        for (let i = 0; i < localStorage.length; i++) {
-            const key = localStorage.key(i);
-            if (!key || !key.startsWith('viconic:')) continue;
-            try {
-                const c = JSON.parse(localStorage.getItem(key));
-                if (c && c.d && Date.now() - c.t < TTL) {
-                    // Register all icon name variants into W.icons
-                    for (const n in c.d) {
-                        if (!Object.prototype.hasOwnProperty.call(c.d, n)) continue;
-                        const svg = c.d[n];
-                        // Store by plain name so _u() can find it regardless of prefix
-                        if (!W.icons[n]) W.icons[n] = svg;
-                    }
-                }
-            } catch (e) { /* corrupted entry, skip */ }
-        }
-    } catch (e) { }
-})();
-// ============================================
-// Track initialized kits to avoid duplicate scripts
-// ============================================
-const _initializedKits = new Set();
-/**
- * Initialize a Viconic Kit in your React app.
- * Injects the kit's loader.js script into <head>.
- * Supports multiple kits — call once per kit.
- *
- * @param {Object} options
- * @param {string} options.kitId - UUID of the Kit (required)
- * @param {string} [options.cdnBase] - Custom CDN domain (default: cdn.viconic.dev)
- *
- * @example
- * import { initViconic } from 'viconic-react-icons';
- *
- * initViconic({ kitId: '387a6161-cb39-411f-8f13-29a5813e4efd' });
- * // Multiple kits:
- * initViconic({ kitId: 'another-kit-uuid', version: '1.0' });
- */
-export function initViconic(options = {}) {
-    const { kitId, cdnBase = 'cdn.viconic.dev', version } = options;
-    if (typeof window === 'undefined') return; // SSR guard
-    if (!kitId) {
-        console.warn('[Viconic] initViconic requires a kitId');
-        return;
-    }
-    if (_initializedKits.has(kitId)) return; // Already initialized
-    _initializedKits.add(kitId);
-    const scriptId = `viconic-kit-${kitId}`;
-    if (document.getElementById(scriptId)) return; // Script already in DOM
-    const script = document.createElement('script');
-    script.id = scriptId;
-    // Add cache busting for development or specific version updates
-    let url = `https://${cdnBase}/kits/${kitId}/loader.js`;
-    if (version) {
-        const vQuery = version === 'dev' ? Date.now() : version;
-        url += `?v=${vQuery}`;
-    }
-    script.src = url;
-    script.async = true;
-    document.head.appendChild(script);
-}
-/**
- * ViconicIcon — React component for rendering Viconic icons.
- *
- * Works with both:
- * - System icons: <ViconicIcon name="lucide:home" />
- * - Kit icons: <ViconicIcon name="@myprefix/home" /> (after initViconic)
- *
- * @param {string} name - Icon identifier (e.g., "lucide:home", "@prefix/name")
- * @param {string} [className] - CSS class names
- * @param {object} [style] - Inline styles
- * @param {string|number} [size] - Icon size (CSS value)
- * @param {string} [color] - Icon color (CSS value)
- */
-export const ViconicIcon = ({ name, className, style, size, color, ...props }) => {
-    const iconRef = useRef(null);
-    const prevNameRef = useRef(name);
-    useEffect(() => {
-        const el = iconRef.current;
-        if (!el) return;
-        // --- FIX DOM REUSE (Reconciliation) ---
-        if (prevNameRef.current !== name) {
-            el.innerHTML = '';
-            el.classList.remove('vi-ok', 'svg-loaded', 'vi-mono', 'ci-multicolor');
-            prevNameRef.current = name;
-        }
-        const isKitIcon = name && name.startsWith('@');
-        const prefixMatch = isKitIcon ? name.match(/^@([^/]+)\/(.+)$/) : null;
-        function isInjected() {
-            return el.classList.contains('vi-ok') || el.classList.contains('svg-loaded');
-        }
-        // --- PATH 1: Synchronous inject from W.icons (pre-loaded from localStorage at module init) ---
-        if (!isInjected()) {
-            const W = window.__viconic;
-            if (W && W.icons) {
-                // Try all key variants: iconBaseName, @prefix/name, prefix:name, prefix/name
-                const iconBaseName = prefixMatch ? prefixMatch[2] : null;
-                const svg = (iconBaseName && W.icons[iconBaseName])
-                    || (name && W.icons[name])
-                    || null;
-                if (svg) {
-                    el.innerHTML = svg;
-                    el.classList.add('vi-ok', 'svg-loaded');
-                }
-            }
-        }
-        // --- PATH 2: Smart loader for system icons (prefix:name) ---
-        if (!isInjected() && !isKitIcon) {
-            if (window.CopyIcons && window.CopyIcons.forceProcess) {
-                window.CopyIcons.forceProcess(el);
-            }
-        }
-        // --- PATH 3: Custom element _u() call (kit loader registered element) ---
-        if (!isInjected() && el._u) {
-            el._u();
-        }
-        if (isInjected()) return;
-        // --- PATH 4: Event-driven — listen for viconic:ready fired by kit loader after register() ---
-        // Much faster than polling: icons appear the instant the loader finishes fetching them.
-        function tryInjectFromEvent() {
-            if (isInjected()) return;
-            const W = window.__viconic;
-            if (W && W.icons) {
-                const iconBaseName = prefixMatch ? prefixMatch[2] : null;
-                const svg = (iconBaseName && W.icons[iconBaseName])
-                    || (name && W.icons[name])
-                    || null;
-                if (svg) {
-                    el.innerHTML = svg;
-                    el.classList.add('vi-ok', 'svg-loaded');
-                    return;
-                }
-            }
-            if (el._u) el._u();
-            if (!isKitIcon && window.CopyIcons && window.CopyIcons.forceProcess) {
-                window.CopyIcons.forceProcess(el);
-            }
-        }
-        document.addEventListener('viconic:ready', tryInjectFromEvent);
-        // --- PATH 5: Short-deadline fallback (500ms) in case script already fired before we listened ---
-        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;
-                        }
-                    }
-                }
-            }
-        }, 500);
-        return () => {
-            document.removeEventListener('viconic:ready', tryInjectFromEvent);
-            clearTimeout(fallbackTimer);
-        };
-    }, [name, className, size, color, style]);
-    const combinedStyle = {
-        ...(size ? { fontSize: size } : {}),
-        ...(color ? { color: color } : {}),
-        ...style
-    };
-    return (
-        <viconic-icon
-            ref={iconRef}
-            icon={name}
-            class={className}
-            style={combinedStyle}
-            {...props}
-        ></viconic-icon>
-    );
-};
-export default ViconicIcon;
+import React, { useEffect, useRef } from 'react';
+import './copyicons-smart-loader.js';
+// ============================================
+// PRE-LOAD KIT CACHE SYNCHRONOUSLY AT MODULE LEVEL
+// Same architecture as kit loader: read localStorage before any render
+// so icons are available instantly when components mount.
+// ============================================
+(function _preloadKitCache() {
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') return;
+    try {
+        const W = (window.__viconic = window.__viconic || {});
+        W.icons = W.icons || {};
+        const TTL = 3 * 24 * 60 * 60 * 1000; // 3 days
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (!key || !key.startsWith('viconic:')) continue;
+            try {
+                const c = JSON.parse(localStorage.getItem(key));
+                if (c && c.d && Date.now() - c.t < TTL) {
+                    // Register all icon name variants into W.icons
+                    for (const n in c.d) {
+                        if (!Object.prototype.hasOwnProperty.call(c.d, n)) continue;
+                        const svg = c.d[n];
+                        // Store by plain name so _u() can find it regardless of prefix
+                        if (!W.icons[n]) W.icons[n] = svg;
+                    }
+                }
+            } catch (e) { /* corrupted entry, skip */ }
+        }
+    } catch (e) { }
+})();
+// ============================================
+// Track initialized kits to avoid duplicate scripts
+// ============================================
+const _initializedKits = new Set();
+/**
+ * Initialize a Viconic Kit in your React app.
+ * Injects the kit's loader.js script into <head>.
+ * Supports multiple kits — call once per kit.
+ *
+ * @param {Object} options
+ * @param {string} options.kitId - UUID of the Kit (required)
+ * @param {string} [options.cdnBase] - Custom CDN domain (default: cdn.viconic.dev)
+ *
+ * @example
+ * import { initViconic } from 'viconic-react-icons';
+ *
+ * initViconic({ kitId: '387a6161-cb39-411f-8f13-29a5813e4efd' });
+ * // Multiple kits:
+ * initViconic({ kitId: 'another-kit-uuid', version: '1.0' });
+ */
+export function initViconic(options = {}) {
+    const { kitId, cdnBase = 'cdn.viconic.dev', version } = options;
+    if (typeof window === 'undefined') return; // SSR guard
+    if (!kitId) {
+        console.warn('[Viconic] initViconic requires a kitId');
+        return;
+    }
+    if (_initializedKits.has(kitId)) return; // Already initialized
+    _initializedKits.add(kitId);
+    const scriptId = `viconic-kit-${kitId}`;
+    if (document.getElementById(scriptId)) return; // Script already in DOM
+    const script = document.createElement('script');
+    script.id = scriptId;
+    // Add cache busting for development or specific version updates
+    let url = `https://${cdnBase}/kits/${kitId}/loader.js`;
+    if (version) {
+        const vQuery = version === 'dev' ? Date.now() : version;
+        url += `?v=${vQuery}`;
+    }
+    script.src = url;
+    script.async = true;
+    document.head.appendChild(script);
+}
+/**
+ * ViconicIcon — React component for rendering Viconic icons.
+ *
+ * Works with both:
+ * - System icons: <ViconicIcon name="lucide:home" />
+ * - Kit icons: <ViconicIcon name="@myprefix/home" /> (after initViconic)
+ *
+ * @param {string} name - Icon identifier (e.g., "lucide:home", "@prefix/name")
+ * @param {string} [className] - CSS class names
+ * @param {object} [style] - Inline styles
+ * @param {string|number} [size] - Icon size (CSS value)
+ * @param {string} [color] - Icon color (CSS value)
+ */
+export const ViconicIcon = ({ name, className, style, size, color, ...props }) => {
+    const iconRef = useRef(null);
+    const prevNameRef = useRef(name);
+    useEffect(() => {
+        const el = iconRef.current;
+        if (!el) return;
+        // --- FIX DOM REUSE (Reconciliation) ---
+        if (prevNameRef.current !== name) {
+            el.innerHTML = '';
+            el.classList.remove('vi-ok', 'svg-loaded', 'vi-mono', 'ci-multicolor');
+            prevNameRef.current = name;
+        }
+        const isKitIcon = name && name.startsWith('@');
+        const prefixMatch = isKitIcon ? name.match(/^@([^/]+)\/(.+)$/) : null;
+        function isInjected() {
+            return el.classList.contains('vi-ok') || el.classList.contains('svg-loaded');
+        }
+        // --- PATH 1: Synchronous inject from W.icons (pre-loaded from localStorage at module init) ---
+        if (!isInjected()) {
+            const W = window.__viconic;
+            if (W && W.icons) {
+                // Try all key variants: iconBaseName, @prefix/name, prefix:name, prefix/name
+                const iconBaseName = prefixMatch ? prefixMatch[2] : null;
+                const svg = (iconBaseName && W.icons[iconBaseName])
+                    || (name && W.icons[name])
+                    || null;
+                if (svg) {
+                    el.innerHTML = svg;
+                    el.classList.add('vi-ok', 'svg-loaded');
+                }
+            }
+        }
+        // --- PATH 2: Smart loader for system icons (prefix:name) ---
+        if (!isInjected() && !isKitIcon) {
+            if (window.CopyIcons && window.CopyIcons.forceProcess) {
+                window.CopyIcons.forceProcess(el);
+            }
+        }
+        // --- PATH 3: Custom element _u() call (kit loader registered element) ---
+        if (!isInjected() && el._u) {
+            el._u();
+        }
+        if (isInjected()) return;
+        // --- PATH 4: Event-driven — listen for viconic:ready fired by kit loader after register() ---
+        // Much faster than polling: icons appear the instant the loader finishes fetching them.
+        function tryInjectFromEvent() {
+            if (isInjected()) return;
+            const W = window.__viconic;
+            if (W && W.icons) {
+                const iconBaseName = prefixMatch ? prefixMatch[2] : null;
+                const svg = (iconBaseName && W.icons[iconBaseName])
+                    || (name && W.icons[name])
+                    || null;
+                if (svg) {
+                    el.innerHTML = svg;
+                    el.classList.add('vi-ok', 'svg-loaded');
+                    return;
+                }
+            }
+            if (el._u) el._u();
+            if (!isKitIcon && window.CopyIcons && window.CopyIcons.forceProcess) {
+                window.CopyIcons.forceProcess(el);
+            }
+        }
+        document.addEventListener('viconic:ready', tryInjectFromEvent);
+        // --- PATH 5: Short-deadline fallback (500ms) in case script already fired before we listened ---
+        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;
+                        }
+                    }
+                }
+            }
+        }, 500);
+        return () => {
+            document.removeEventListener('viconic:ready', tryInjectFromEvent);
+            clearTimeout(fallbackTimer);
+        };
+    }, [name, className, size, color, style]);
+    const combinedStyle = {
+        ...(size ? { fontSize: size } : {}),
+        ...(color ? { color: color } : {}),
+        ...style
+    };
+    return (
+        <viconic-icon
+            ref={iconRef}
+            icon={name}
+            class={className}
+            style={combinedStyle}
+            {...props}
+        ></viconic-icon>
+    );
+};
+export default ViconicIcon;