viconic-react-icons 1.0.8 → 1.1.1

package/README.md

@@ -3,16 +3,17 @@
 ![NPM Version](https://img.shields.io/npm/v/viconic-react-icons)
 ![NPM License](https://img.shields.io/npm/l/viconic-react-icons)
 
-The official React component wrapper for [Viconic](https://viconic.io.vn), a modern, hyper-fast, CDN-powered icon system.
+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.
 
 ## 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.
-- ?? **SSR Ready**: Fully supports Next.js, Vite, and other Server-Side Rendering frameworks.
-- ?? **TypeScript Support**: Includes built-in types for easy autocompletion.
+- 🪶 **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
 
@@ -24,9 +25,9 @@ yarn add viconic-react-icons
 pnpm add viconic-react-icons
 ```
 
-## Quick Start
+## Quick Start — System Icons
 
-Import the `ViconicIcon` component and pass the unique `name` identifier corresponding to your icon of choice from [viconic.io.vn](https://viconic.io.vn).
+Import the `ViconicIcon` component and pass the unique `name` identifier corresponding to your icon of choice from [viconic.dev](https://viconic.dev).
 
 ```jsx
 import { ViconicIcon } from "viconic-react-icons";
@@ -45,26 +46,74 @@ function App() {
     </div>
   );
 }
+```
+
+## Quick Start — Custom Kit
+
+Use icons from your own kit 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)
+initViconic({ kitId: "your-kit-uuid-here" });
+
+// You can load multiple kits!
+initViconic({ kitId: "another-kit-uuid" });
 
-export default App;
+function App() {
+  return (
+    <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" />
+      
+      {/* Mix kit icons with system icons */}
+      <ViconicIcon name="lucide:star" />
+    </div>
+  );
+}
 ```
 
 ## Props
 
 | Prop | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| `name` | `string` | `undefined` | **Required.** The unique icon ID (e.g. `lucide:activity`, `h2:0`). |
+| `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"`). |
 | `className` | `string` | `""` | Standard CSS class names (great for Tailwind). |
 | `style` | `React.CSSProperties` | `{}` | Inline CSS styling. |
 | `...props` | `HTMLAttributes` | | Spread standard HTML attributes (e.g. `onClick`, `title`). |
 
+## API
+
+### `initViconic(options)`
+
+Inject a kit's 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. |
+
+```jsx
+// In your main.jsx or App.jsx
+import { initViconic } from "viconic-react-icons";
+
+initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd" });
+```
+
 ## Architecture
 
 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.js from CDN, which fetches your kit's icon map and SVGs in parallel.
+
 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
 
 This project is licensed under the MIT License. Icon licenses depend on the specific icon families you request.
-

package/dist/index.js

@@ -30,7 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ViconicIcon: () => ViconicIcon,
-  default: () => index_default
+  default: () => index_default,
+  initViconic: () => initViconic
 });
 module.exports = __toCommonJS(index_exports);
 var import_react = __toESM(require("react"));
@@ -170,6 +171,17 @@ var import_react = __toESM(require("react"));
   }
   function parseViconicIcon(attrValue) {
     if (!attrValue) return null;
+    if (attrValue.startsWith("@")) {
+      const slashIdx = attrValue.indexOf("/");
+      if (slashIdx > 1) {
+        const prefix2 = attrValue.slice(1, slashIdx).trim();
+        const name = attrValue.slice(slashIdx + 1).trim();
+        if (prefix2 && name) {
+          return { prefix: prefix2, iconName: camelToKebab(name), isKit: true };
+        }
+      }
+      return null;
+    }
     const colonIdx = attrValue.indexOf(":");
     if (colonIdx < 1) return null;
     const prefix = attrValue.slice(0, colonIdx).trim();
@@ -219,10 +231,10 @@ var import_react = __toESM(require("react"));
   }
   const currentScript = document.currentScript;
   const config = {
-    apiBase: (((_a = window.CONFIG) == null ? void 0 : _a.API_BASE) || ((_b = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _b.apiBase) || "https://api.viconic.io.vn").replace(/\/$/, ""),
+    apiBase: (((_a = window.CONFIG) == null ? void 0 : _a.API_BASE) || ((_b = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _b.apiBase) || "https://api.viconic.dev").replace(/\/$/, ""),
     // Batch API for Iconify-style loading (by-prefix endpoint)
-    batchApiBase: (((_c = window.CONFIG) == null ? void 0 : _c.BATCH_API_BASE) || ((_d = window.CONFIG) == null ? void 0 : _d.API_BASE) || ((_e = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _e.batchApiBase) || "https://api.viconic.io.vn").replace(/\/$/, ""),
-    cdnDomain: ((_f = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _f.cdnDomain) || ((_g = window.CONFIG) == null ? void 0 : _g.CDN_DOMAIN) || "cdn.viconic.io.vn",
+    batchApiBase: (((_c = window.CONFIG) == null ? void 0 : _c.BATCH_API_BASE) || ((_d = window.CONFIG) == null ? void 0 : _d.API_BASE) || ((_e = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _e.batchApiBase) || "https://api.viconic.dev").replace(/\/$/, ""),
+    cdnDomain: ((_f = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _f.cdnDomain) || ((_g = window.CONFIG) == null ? void 0 : _g.CDN_DOMAIN) || "cdn.viconic.dev",
     // Custom domain for R2 CDN via Cloudflare edge (HTTP/2, edge cache)
     cdnCustomDomain: ((_h = window.CONFIG) == null ? void 0 : _h.CDN_CUSTOM_DOMAIN) || ((_i = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _i.cdnCustomDomain) || "",
     observe: (currentScript == null ? void 0 : currentScript.hasAttribute("data-observe")) ?? false,
@@ -814,8 +826,9 @@ var import_react = __toESM(require("react"));
   function registerViconicIcon(el) {
     if (!el || el.nodeType !== 1) return;
     if (processedElements.has(el)) return;
-    processedElements.add(el);
     const iconAttr = el.getAttribute("icon");
+    if (iconAttr && iconAttr.startsWith("@")) return;
+    processedElements.add(el);
     const parsed = parseViconicIcon(iconAttr);
     if (!parsed) {
       if (iconAttr) console.warn(`[CopyIcons] \u26A0\uFE0F Cannot parse viconic-icon icon="${iconAttr}"`);
@@ -1944,12 +1957,50 @@ var import_react = __toESM(require("react"));
 })();
 
 // src/index.jsx
+var _initializedKits = /* @__PURE__ */ new Set();
+function initViconic(options = {}) {
+  const { kitId, cdnBase = "cdn.viconic.dev" } = options;
+  if (typeof window === "undefined") return;
+  if (!kitId) {
+    console.warn("[Viconic] initViconic requires a kitId");
+    return;
+  }
+  if (_initializedKits.has(kitId)) return;
+  _initializedKits.add(kitId);
+  const scriptId = `viconic-kit-${kitId}`;
+  if (document.getElementById(scriptId)) return;
+  const script = document.createElement("script");
+  script.id = scriptId;
+  script.src = `https://${cdnBase}/kits/${kitId}/loader.js`;
+  script.async = true;
+  document.head.appendChild(script);
+}
 var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
   const iconRef = (0, import_react.useRef)(null);
   (0, import_react.useEffect)(() => {
-    if (window.CopyIcons && iconRef.current) {
-      window.CopyIcons.forceProcess(iconRef.current);
-    }
+    const el = iconRef.current;
+    if (!el) return;
+    const isKitIcon = name && name.startsWith("@");
+    if (window.CopyIcons && window.CopyIcons.forceProcess && !isKitIcon) {
+      window.CopyIcons.forceProcess(el);
+    }
+    const isLoaded = el.classList.contains("vi-ok") || el.classList.contains("svg-loaded");
+    if (isLoaded) return;
+    let retries = 0;
+    const maxRetries = 50;
+    const timer = setInterval(() => {
+      retries++;
+      if (el.classList.contains("vi-ok") || el.classList.contains("svg-loaded")) {
+        clearInterval(timer);
+        return;
+      }
+      if (el._u) el._u();
+      if (window.CopyIcons && window.CopyIcons.forceProcess && !isKitIcon) {
+        window.CopyIcons.forceProcess(el);
+      }
+      if (retries >= maxRetries) clearInterval(timer);
+    }, 100);
+    return () => clearInterval(timer);
   }, [name, className, size, color, style]);
   const combinedStyle = {
     ...size ? { fontSize: size } : {},
@@ -1970,7 +2021,8 @@ var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
 var index_default = ViconicIcon;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ViconicIcon
+  ViconicIcon,
+  initViconic
 });
 /**
  * CopyIcons Smart Loader v8.3 (CDN Smart Fallback + Early Abort)

package/dist/index.mjs

@@ -136,6 +136,17 @@ import React, { useEffect, useRef } from "react";
   }
   function parseViconicIcon(attrValue) {
     if (!attrValue) return null;
+    if (attrValue.startsWith("@")) {
+      const slashIdx = attrValue.indexOf("/");
+      if (slashIdx > 1) {
+        const prefix2 = attrValue.slice(1, slashIdx).trim();
+        const name = attrValue.slice(slashIdx + 1).trim();
+        if (prefix2 && name) {
+          return { prefix: prefix2, iconName: camelToKebab(name), isKit: true };
+        }
+      }
+      return null;
+    }
     const colonIdx = attrValue.indexOf(":");
     if (colonIdx < 1) return null;
     const prefix = attrValue.slice(0, colonIdx).trim();
@@ -185,10 +196,10 @@ import React, { useEffect, useRef } from "react";
   }
   const currentScript = document.currentScript;
   const config = {
-    apiBase: (((_a = window.CONFIG) == null ? void 0 : _a.API_BASE) || ((_b = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _b.apiBase) || "https://api.viconic.io.vn").replace(/\/$/, ""),
+    apiBase: (((_a = window.CONFIG) == null ? void 0 : _a.API_BASE) || ((_b = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _b.apiBase) || "https://api.viconic.dev").replace(/\/$/, ""),
     // Batch API for Iconify-style loading (by-prefix endpoint)
-    batchApiBase: (((_c = window.CONFIG) == null ? void 0 : _c.BATCH_API_BASE) || ((_d = window.CONFIG) == null ? void 0 : _d.API_BASE) || ((_e = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _e.batchApiBase) || "https://api.viconic.io.vn").replace(/\/$/, ""),
-    cdnDomain: ((_f = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _f.cdnDomain) || ((_g = window.CONFIG) == null ? void 0 : _g.CDN_DOMAIN) || "cdn.viconic.io.vn",
+    batchApiBase: (((_c = window.CONFIG) == null ? void 0 : _c.BATCH_API_BASE) || ((_d = window.CONFIG) == null ? void 0 : _d.API_BASE) || ((_e = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _e.batchApiBase) || "https://api.viconic.dev").replace(/\/$/, ""),
+    cdnDomain: ((_f = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _f.cdnDomain) || ((_g = window.CONFIG) == null ? void 0 : _g.CDN_DOMAIN) || "cdn.viconic.dev",
     // Custom domain for R2 CDN via Cloudflare edge (HTTP/2, edge cache)
     cdnCustomDomain: ((_h = window.CONFIG) == null ? void 0 : _h.CDN_CUSTOM_DOMAIN) || ((_i = currentScript == null ? void 0 : currentScript.dataset) == null ? void 0 : _i.cdnCustomDomain) || "",
     observe: (currentScript == null ? void 0 : currentScript.hasAttribute("data-observe")) ?? false,
@@ -780,8 +791,9 @@ import React, { useEffect, useRef } from "react";
   function registerViconicIcon(el) {
     if (!el || el.nodeType !== 1) return;
     if (processedElements.has(el)) return;
-    processedElements.add(el);
     const iconAttr = el.getAttribute("icon");
+    if (iconAttr && iconAttr.startsWith("@")) return;
+    processedElements.add(el);
     const parsed = parseViconicIcon(iconAttr);
     if (!parsed) {
       if (iconAttr) console.warn(`[CopyIcons] \u26A0\uFE0F Cannot parse viconic-icon icon="${iconAttr}"`);
@@ -1910,12 +1922,50 @@ import React, { useEffect, useRef } from "react";
 })();
 
 // src/index.jsx
+var _initializedKits = /* @__PURE__ */ new Set();
+function initViconic(options = {}) {
+  const { kitId, cdnBase = "cdn.viconic.dev" } = options;
+  if (typeof window === "undefined") return;
+  if (!kitId) {
+    console.warn("[Viconic] initViconic requires a kitId");
+    return;
+  }
+  if (_initializedKits.has(kitId)) return;
+  _initializedKits.add(kitId);
+  const scriptId = `viconic-kit-${kitId}`;
+  if (document.getElementById(scriptId)) return;
+  const script = document.createElement("script");
+  script.id = scriptId;
+  script.src = `https://${cdnBase}/kits/${kitId}/loader.js`;
+  script.async = true;
+  document.head.appendChild(script);
+}
 var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
   const iconRef = useRef(null);
   useEffect(() => {
-    if (window.CopyIcons && iconRef.current) {
-      window.CopyIcons.forceProcess(iconRef.current);
-    }
+    const el = iconRef.current;
+    if (!el) return;
+    const isKitIcon = name && name.startsWith("@");
+    if (window.CopyIcons && window.CopyIcons.forceProcess && !isKitIcon) {
+      window.CopyIcons.forceProcess(el);
+    }
+    const isLoaded = el.classList.contains("vi-ok") || el.classList.contains("svg-loaded");
+    if (isLoaded) return;
+    let retries = 0;
+    const maxRetries = 50;
+    const timer = setInterval(() => {
+      retries++;
+      if (el.classList.contains("vi-ok") || el.classList.contains("svg-loaded")) {
+        clearInterval(timer);
+        return;
+      }
+      if (el._u) el._u();
+      if (window.CopyIcons && window.CopyIcons.forceProcess && !isKitIcon) {
+        window.CopyIcons.forceProcess(el);
+      }
+      if (retries >= maxRetries) clearInterval(timer);
+    }, 100);
+    return () => clearInterval(timer);
   }, [name, className, size, color, style]);
   const combinedStyle = {
     ...size ? { fontSize: size } : {},
@@ -1936,7 +1986,8 @@ var ViconicIcon = ({ name, className, style, size, color, ...props }) => {
 var index_default = ViconicIcon;
 export {
   ViconicIcon,
-  index_default as default
+  index_default as default,
+  initViconic
 };
 /**
  * CopyIcons Smart Loader v8.3 (CDN Smart Fallback + Early Abort)

package/index.d.ts

@@ -1,13 +1,30 @@
 import * as React from 'react';
 
+export interface InitViconicOptions {
+    /** UUID of the Kit to load */
+    kitId: string;
+    /** Custom CDN domain (default: 'cdn.viconic.dev') */
+    cdnBase?: string;
+}
+
+/**
+ * Initialize a Viconic Kit. Injects the kit's loader script into <head>.
+ * Supports multiple kits — call once per kitId.
+ * Safe to call on server (no-op during SSR).
+ */
+export function initViconic(options: InitViconicOptions): void;
+
 export interface ViconicIconProps extends React.HTMLAttributes<HTMLElement> {
-    /** The unique icon ID (e.g., 'lucide:activity', 'h2:0'). Required. */
+    /** The unique icon ID. Required.
+     * - System icons: 'lucide:activity', 'h2:0'
+     * - Kit icons: '@prefix/iconName' (after calling initViconic)
+     */
     name: string;
 
-    /** Optional icon size, CSS format (e.g., '24px', '1.5rem'). Translates to style.fontSize */
+    /** Optional icon size, CSS format (e.g., '24px', '1.5rem'). */
     size?: string | number;
 
-    /** Optional icon color, CSS color value. Translates to style.color */
+    /** Optional icon color, CSS color value. */
     color?: string;
 
     style?: React.CSSProperties;
@@ -15,4 +32,3 @@ export interface ViconicIconProps extends React.HTMLAttributes<HTMLElement> {
 
 export const ViconicIcon: React.FC<ViconicIconProps>;
 export default ViconicIcon;
-

package/package.json

@@ -1,30 +1,33 @@
-{
-  "name": "viconic-react-icons",
-  "version": "1.0.8",
-  "description": "Viconic Smart Icons loader for React",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "files": [
-    "dist",
-    "src",
-    "index.d.ts"
-  ],
-  "scripts": {
-    "build": "tsup src/index.jsx --format cjs,esm --external react"
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0"
-  },
-  "keywords": [
-    "icons",
-    "viconic",
-    "react"
-  ],
-  "author": "Viconic Team",
-  "license": "MIT",
-  "types": "index.d.ts",
-  "devDependencies": {
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "viconic-react-icons",
+  "version": "1.1.1",
+  "description": "Viconic Smart Icons loader for React — supports Kit and 200k+ system icons",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "files": [
+    "dist",
+    "src",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.jsx --format cjs,esm --external react"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "keywords": [
+    "icons",
+    "viconic",
+    "react",
+    "kit",
+    "svg",
+    "icon-kit"
+  ],
+  "author": "Viconic Team",
+  "license": "MIT",
+  "types": "index.d.ts",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}