@versini/ui-icon-renderer 1.0.4 → 2.1.0

package/README.md

@@ -1 +1,141 @@
 # @versini/ui-icon-renderer
+
+[![npm version](https://img.shields.io/npm/v/@versini/ui-icon-renderer?style=flat-square)](https://www.npmjs.com/package/@versini/ui-icon-renderer)
+![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40versini%2Fui-icon-renderer?style=flat-square&label=size%20(gzip)>)
+
+> A React hook for lazy-loading icons from `@versini/ui-icons` on demand.
+
+The Icon Renderer package provides `useIconRenderer`, a hook that dynamically imports icons by name at runtime. This avoids bundling all 100+ icons upfront, making it ideal for components like icon pickers where the full icon set is needed but shouldn't impact initial bundle size.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+
+## Features
+
+- **🚀 Lazy Loading**: Icons are loaded on demand via dynamic imports — no upfront bundle cost
+- **⚡ Optional Preloading**: Warm the cache ahead of time to prevent flash on render
+- **🧩 Simple Hook API**: Single `useIconRenderer` hook covers all use cases
+- **🌲 Tree-shakeable**: Only the hook is included in your bundle, icon data stays lazy
+- **🔧 TypeScript**: Fully typed with comprehensive prop definitions
+- **📦 Shared Cache**: Module-level cache ensures each icon is loaded only once across components
+
+## Installation
+
+```bash
+npm install @versini/ui-icon-renderer
+```
+
+> **Note**: This package requires `@versini/ui-icons` as a peer dependency.
+
+## Usage
+
+### Render Icons Without Preloading
+
+When you don't know which icon will be needed ahead of time, or preloading isn't necessary. The icon loads automatically when rendered (brief null while loading).
+
+```tsx
+import { useIconRenderer } from "@versini/ui-icon-renderer";
+
+function App() {
+  const [IconRenderer] = useIconRenderer();
+  const [selectedIcon, setSelectedIcon] = useState<string | null>(null);
+
+  return (
+    <div>
+      <button onClick={() => setSelectedIcon("IconAdd")}>Show Icon</button>
+      {selectedIcon && IconRenderer && <IconRenderer icon={selectedIcon} />}
+    </div>
+  );
+}
+```
+
+### Preload Icons to Prevent Flash
+
+When you know which icons will be needed, preload them before rendering to avoid a flash of empty content.
+
+```tsx
+import { useIconRenderer } from "@versini/ui-icon-renderer";
+
+function App() {
+  const [IconRenderer, preloadIcons] = useIconRenderer();
+  const [showIcons, setShowIcons] = useState(false);
+
+  return (
+    <div>
+      <button
+        onMouseEnter={() => preloadIcons(["IconAdd", "IconDelete", "IconEdit"])}
+        onClick={() => setShowIcons(true)}
+      >
+        Show Icons
+      </button>
+      {showIcons && IconRenderer && (
+        <div>
+          <IconRenderer icon="IconAdd" />
+          <IconRenderer icon="IconDelete" />
+          <IconRenderer icon="IconEdit" />
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Icon Picker
+
+Load all available icons lazily for an icon picker component.
+
+```tsx
+import { useIconRenderer } from "@versini/ui-icon-renderer";
+
+const ALL_ICON_NAMES = ["IconAdd", "IconDelete", "IconEdit", "IconSearch"];
+
+function IconPicker({ onSelect }: { onSelect: (name: string) => void }) {
+  const [IconRenderer, preloadIcons] = useIconRenderer();
+
+  useEffect(() => {
+    preloadIcons(ALL_ICON_NAMES);
+  }, [preloadIcons]);
+
+  if (!IconRenderer) {
+    return null;
+  }
+
+  return (
+    <div className="grid grid-cols-6 gap-2">
+      {ALL_ICON_NAMES.map((name) => (
+        <button key={name} onClick={() => onSelect(name)}>
+          <IconRenderer icon={name} />
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## API
+
+### useIconRenderer
+
+```tsx
+const [IconRenderer, preloadIcons] = useIconRenderer();
+```
+
+Returns a tuple:
+
+| Index | Name         | Type                                  | Description                                                                                    |
+| ----- | ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 0     | IconRenderer | `React.FC<IconRendererProps> \| null` | The icon component, or `null` while the module is loading. Available after first render cycle. |
+| 1     | preloadIcons | `(icons: string[]) => Promise<void>`  | Preloads icon data into the cache. Optional — icons auto-load when rendered if not preloaded.  |
+
+### IconRenderer Props
+
+| Prop      | Type     | Default | Description                                                            |
+| --------- | -------- | ------- | ---------------------------------------------------------------------- |
+| icon      | `string` | -       | The name of the icon to render (e.g. `"IconAdd"`, `"IconDeleteLight"`) |
+| className | `string` | -       | CSS class(es) to add to the SVG element                                |
+
+_Also accepts all standard SVG element props (`React.ComponentPropsWithoutRef<"svg">`)._

package/dist/184.js

@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+
+
+function useIconRenderer() {
+    const modRef = useRef(null);
+    const [mod, setMod] = useState(null);
+    useEffect(()=>{
+        /* v8 ignore start -- dynamic imports are not fully instrumented by V8 */ import("./475.js").then((mod) => ({ IconRenderer: mod.IconRenderer,preloadIcon: mod.preloadIcon,preloadIcons: mod.preloadIcons })).then((m)=>{
+            modRef.current = m;
+            setMod(m);
+        }).catch(()=>{});
+    /* v8 ignore stop */ }, []);
+    /* v8 ignore start -- dynamic imports are not fully instrumented by V8 */ const preload = useCallback((icons)=>{
+        const ensure = modRef.current ? Promise.resolve(modRef.current) : import("./475.js").then((mod) => ({ IconRenderer: mod.IconRenderer,preloadIcon: mod.preloadIcon,preloadIcons: mod.preloadIcons })).then((m)=>{
+            modRef.current = m;
+            setMod(m);
+            return m;
+        });
+        return ensure.then((m)=>m.preloadIcons(icons)).catch(()=>{});
+    }, []);
+    /* v8 ignore stop */ return [
+        mod?.IconRenderer ?? null,
+        preload
+    ];
+}
+
+export { useEffect, useIconRenderer, useState };

package/dist/475.js

@@ -0,0 +1,55 @@
+import { jsx } from "react/jsx-runtime";
+import { useState, useEffect } from "./184.js";
+
+
+
+
+const iconCache = new Map();
+const toKebabCase = (name)=>name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+const preloadIcon = async (icon)=>{
+    if (iconCache.has(icon)) {
+        return;
+    }
+    /* v8 ignore start -- dynamic template-literal imports are not instrumented by V8 */ try {
+        const kebabIcon = toKebabCase(icon);
+        const mod = await import(`./data/${kebabIcon}.js`);
+        if (mod?.default) {
+            iconCache.set(icon, mod.default);
+        }
+    } catch  {
+    // Icon not found — skip silently
+    }
+/* v8 ignore stop */ };
+const preloadIcons = (icons)=>Promise.all(icons.map(preloadIcon));
+const IconRenderer = ({ icon, ...rest })=>{
+    const [IconComponent, setIconComponent] = useState(()=>iconCache.get(icon) ?? null);
+    useEffect(()=>{
+        if (iconCache.has(icon)) {
+            setIconComponent(()=>iconCache.get(icon));
+            return;
+        }
+        setIconComponent(null);
+        /* v8 ignore start -- dynamic template-literal imports are not instrumented by V8 */ (async ()=>{
+            try {
+                await preloadIcon(icon);
+                const cached = iconCache.get(icon);
+                if (cached) {
+                    setIconComponent(()=>cached);
+                }
+            } catch  {
+            // Icon not found
+            }
+        })();
+    /* v8 ignore stop */ }, [
+        icon
+    ]);
+    if (!IconComponent) {
+        return null;
+    }
+    return /*#__PURE__*/ jsx(IconComponent, {
+        "data-slot": "icon",
+        ...rest
+    });
+};
+
+export { IconRenderer, preloadIcon, preloadIcons };

package/dist/data/icon-attachment-light.js

@@ -0,0 +1,8 @@
+/**
+ * This file was automatically generated.
+ * Please do not edit manually.
+ *
+ * To update this file, run `npm run build:list`.
+ *
+ */
+export { IconAttachmentLight as default } from "@versini/ui-icons/icon-attachment-light";

package/dist/data/icon-attachment.js

@@ -0,0 +1,8 @@
+/**
+ * This file was automatically generated.
+ * Please do not edit manually.
+ *
+ * To update this file, run `npm run build:list`.
+ *
+ */
+export { IconAttachment as default } from "@versini/ui-icons/icon-attachment";

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import { JSX } from 'react/jsx-runtime';
-import { default as React_2 } from 'react';
 
-export declare const IconRenderer: ({ icon, ...rest }: {
+export declare function useIconRenderer(): readonly [(({ icon, ...rest }: {
     icon: string;
-} & React_2.ComponentPropsWithoutRef<"svg">) => JSX.Element | null;
+} & React.ComponentPropsWithoutRef<"svg">) => JSX.Element | null) | null, (icons: string[]) => Promise<void | void[]>];
 
 export { }

package/dist/index.js

@@ -1,38 +1,2 @@
-import { jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
 
-
-
-
-
-const toKebabCase = (name)=>name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
-const IconRenderer = ({ icon, ...rest })=>{
-    const [IconComponent, setIconComponent] = useState(null);
-    useEffect(()=>{
-        setIconComponent(null);
-        /* v8 ignore start -- dynamic template-literal imports are not instrumented by V8 */ (async ()=>{
-            try {
-                const kebabIcon = toKebabCase(icon);
-                const mod = await import(`./data/${kebabIcon}.js`);
-                if (mod && mod.default) {
-                    setIconComponent(()=>mod.default);
-                }
-            } catch  {
-            // Icon not found
-            }
-        })();
-    /* v8 ignore stop */ }, [
-        icon
-    ]);
-    if (!IconComponent) {
-        return null;
-    }
-    return /*#__PURE__*/ jsx(IconComponent, {
-        "data-slot": "icon",
-        ...rest
-    });
-};
-
-/* v8 ignore next 1 */ 
-
-export { IconRenderer };
+export { useIconRenderer } from "./184.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-icon-renderer",
-	"version": "1.0.4",
+	"version": "2.1.0",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -14,6 +14,12 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
 	"files": [
 		"dist"
 	],
@@ -37,11 +43,11 @@
 		"test": "vitest run"
 	},
 	"peerDependencies": {
-		"@versini/ui-icons": "4.22.2",
+		"@versini/ui-icons": "4.23.0",
 		"clsx": ">=2"
 	},
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "85c2706ce9e267f57683ecb346a86b6f5b0cd6f3"
+	"gitHead": "0ccbca8586510e8619f039e193b68ef15ab795c5"
 }