bertui-vicons 1.0.0

package/README.md

@@ -0,0 +1,308 @@
+# 🚀 BERTUI VIcons
+
+**Universal icon library that works EVERYWHERE.** Part of the BERTUI framework family.
+
+✅ Vercel | ✅ Cloudflare Pages | ✅ Netlify | ✅ Any platform
+
+## Why BERTUI VIcons?
+
+- ⚡ **Zero Build Failures**: Works on any platform (Vercel, Cloudflare, etc.)
+- 🎨 **Text Overlays**: Add dynamic text/numbers inside icons
+- 📦 **Zero Bundle Bloat**: Pre-optimized SVG templates
+- 🔄 **Lucide Compatible**: Drop-in replacement for lucide-react
+- 🎯 **Type-Safe**: Full TypeScript support
+- 🔥 **Blazing Fast**: String-based rendering, no DOM manipulation
+- 🏷️ **Smart Search**: Search by name, tags, categories (from Lucide metadata)
+- 📊 **1667 Icons**: Complete Lucide icon set
+
+## Installation
+
+```bash
+bun add bertui-vicons
+# or
+npm install bertui-vicons
+```
+
+## Quick Start
+
+### Basic Usage (Lucide-Compatible)
+
+```jsx
+import { ArrowRight, Heart, Star } from 'bertui-vicons';
+
+function App() {
+  return (
+    <div>
+      <ArrowRight />
+      <Heart size={32} color="red" />
+      <Star color="gold" />
+    </div>
+  );
+}
+```
+
+### Text Overlays (Revolutionary!)
+
+```jsx
+import { Bell, ArrowRight, Mail } from 'bertui-vicons';
+
+function App() {
+  return (
+    <div>
+      {/* Number badge */}
+      <Bell>5</Bell>
+      
+      {/* Text label */}
+      <ArrowRight>Next</ArrowRight>
+      
+      {/* Custom positioning */}
+      <Mail fontSize={14} fontWeight={700}>Inbox</Mail>
+    </div>
+  );
+}
+```
+
+### Wildcard Imports (Safe!)
+
+```jsx
+// Import everything - works perfectly on Vercel!
+import * as Icons from 'bertui-vicons';
+
+function IconGallery() {
+  return (
+    <div>
+      <Icons.Heart />
+      <Icons.Star />
+      <Icons.Zap />
+    </div>
+  );
+}
+```
+
+### Dynamic Icons
+
+```jsx
+import { Icon } from 'bertui-vicons';
+
+function DynamicIcon({ iconName, label }) {
+  return <Icon name={iconName}>{label}</Icon>;
+}
+
+// Usage
+<DynamicIcon iconName="ArrowRight" label="Next" />
+```
+
+### Search & Filter
+
+```jsx
+import { 
+  searchIcons, 
+  getIconsByCategory, 
+  getIconsByTag,
+  getAllIcons,
+  getAllCategories,
+  getAllTags
+} from 'bertui-vicons';
+
+// Search icons by name/tags/categories
+const results = searchIcons('arrow'); // Returns: ['ArrowRight', 'ArrowLeft', ...]
+
+// Get by category (from Lucide metadata)
+const devIcons = getIconsByCategory('development');
+// Returns icons in: accessibility, account, animals, arrows, brands, buildings, 
+// charts, communication, connectivity, cursors, design, devices, development, 
+// editing, files, food-beverage, gaming, home, maps, media, multimedia, nature, 
+// notifications, photography, security, shapes, shopping, social, sports, 
+// text, time, tools, transportation, travel, weather, and more!
+
+// Get by tag
+const textIcons = getIconsByTag('formatting');
+
+// Get all available options
+const allIcons = getAllIcons(); // 1667 icons
+const categories = getAllCategories(); // 43 categories
+const tags = getAllTags(); // Hundreds of searchable tags
+```
+
+## API Reference
+
+### Icon Props
+
+```typescript
+interface IconProps {
+  size?: number;              // Default: 24
+  color?: string;             // Default: 'currentColor'
+  strokeWidth?: number;       // Default: 2
+  className?: string;         // CSS class
+  style?: CSSProperties;      // Inline styles
+  children?: string | number; // Text overlay
+  x?: number;                 // Text X position (default: beside icon)
+  y?: number;                 // Text Y position (default: centered)
+  fontSize?: number;          // Text size (default: 12)
+  fontWeight?: number;        // Text weight (default: 600)
+  textColor?: string;         // Text color (default: same as icon)
+}
+```
+
+### Utility Functions
+
+```typescript
+// Search icons by name/tags/categories
+searchIcons(query: string): string[]
+
+// Get icons in a specific category
+getIconsByCategory(category: string): string[]
+
+// Get icons with a specific tag
+getIconsByTag(tag: string): string[]
+
+// Get metadata for an icon
+getIconMetadata(iconName: string): {
+  keywords: string[];
+  categories: string[];
+  tags: string[];
+} | null
+
+// Get all available categories
+getAllCategories(): string[]
+
+// Get all available tags
+getAllTags(): string[]
+
+// Get all icon names
+getAllIcons(): string[]
+```
+
+## Integration with BERTUI Framework
+
+BERTUI VIcons is built specifically for the [BERTUI Framework](https://github.com/BunElysiaReact/BERTUI) and works seamlessly with:
+
+- **Server Islands** - Icons render instantly in SSG mode
+- **Client Components** - Zero hydration overhead
+- **Build System** - No special configuration needed
+
+```jsx
+// In any BERTUI page/component
+import { Zap, Code, Rocket } from 'bertui-vicons';
+
+export default function Home() {
+  return (
+    <div>
+      <h1><Rocket /> Built with BERTUI</h1>
+      <Zap>Fast</Zap>
+      <Code>Simple</Code>
+    </div>
+  );
+}
+```
+
+## How It Works
+
+1. **Build Time**: Lucide SVGs + JSON metadata → Pre-rendered templates
+2. **Distribution**: Optimized SVG strings (no parsing needed)
+3. **Runtime**: Fast string replacement + React rendering
+4. **Result**: Works everywhere, zero platform issues
+
+## Platform Support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Vercel | ✅ | Works perfectly |
+| Cloudflare Pages | ✅ | Works perfectly |
+| Netlify | ✅ | Works perfectly |
+| Local Dev | ✅ | Works perfectly |
+| Any Node.js | ✅ | Works perfectly |
+
+## Statistics
+
+- **Total Icons**: 1667
+- **Categories**: 43 (from Lucide metadata)
+- **Tags**: Hundreds of searchable tags
+- **Bundle Size**: ~2.6MB (pre-optimized, tree-shakeable)
+- **Load Time**: Instant (pre-compiled)
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/BunElysiaReact/bertui-vicons.git
+
+# Install dependencies
+bun install
+
+# Build icons from /icons folder
+bun run build
+
+# Test all import patterns
+bun run test-usage.jsx
+```
+
+## Project Structure
+
+```
+bertui-vicons/
+├── icons/              # Source Lucide SVGs + JSON metadata
+├── build-icons.js      # Bun-powered build script
+├── generated/          # Auto-generated (gitignored)
+│   ├── index.js        # Main export with all components
+│   ├── index.d.ts      # TypeScript definitions
+│   ├── svg-templates.json    # Icon templates + metadata
+│   └── search-index.json     # Search/category/tag index
+├── test-usage.jsx      # Test file
+└── package.json
+```
+
+## Comparison
+
+| Feature | bertui-vicons | lucide-react | react-icons |
+|---------|---------------|--------------|-------------|
+| Bundle Size | Minimal | Large | Very Large |
+| Performance | ⚡⚡⚡ | ⚡ | ⚡ |
+| Text Overlays | ✅ | ❌ | ❌ |
+| Wildcard Imports | ✅ Safe | ⚠️ Bloat | ⚠️ Bloat |
+| Metadata Search | ✅ Tags + Categories | ❌ | ❌ |
+| Vercel Deploy | ✅ | ✅ | ✅ |
+| Platform Issues | ❌ None | ✅ | ✅ |
+| Icon Count | 1667 | 1667 | 40,000+ |
+
+## Migration from Lucide
+
+```jsx
+// Before (lucide-react)
+import { ArrowRight, Heart } from 'lucide-react';
+
+// After (bertui-vicons) - SAME API!
+import { ArrowRight, Heart } from 'bertui-vicons';
+
+// Bonus: Now you can add text overlays!
+<ArrowRight>Next</ArrowRight>
+
+// Bonus: Smart search with metadata!
+searchIcons('formatting') // finds all text formatting icons
+getIconsByCategory('development') // all dev-related icons
+```
+
+## Available Categories
+
+```
+accessibility, account, animals, arrows, brands, buildings, charts,
+communication, connectivity, cursors, design, devices, development,
+editing, files, food-beverage, gaming, home, maps, media, multimedia,
+nature, notifications, photography, security, shapes, shopping, social,
+sports, text, time, tools, transportation, travel, weather, and more!
+```
+
+## License
+
+MIT
+
+## Credits
+
+- Icons from [Lucide](https://lucide.dev/)
+- Metadata from Lucide JSON files
+- Built for [BERTUI Framework](https://github.com/BunElysiaReact/BERTUI)
+- Made with ⚡ by the BERTUI team
+
+---
+
+**Need help?** Check out the [BERTUI Docs](https://bertui-docswebsite.vercel.app/) or join our [Discord](https://discord.gg/kvbXfkJG)