@pikacss/plugin-icons 0.0.39 → 0.0.40

package/README.md

@@ -1,6 +1,7 @@
+<!-- eslint-disable -->
 # @pikacss/plugin-icons
 
-Use thousands of icons from popular icon sets in PikaCSS.
+Use thousands of icons from popular icon sets in PikaCSS with full TypeScript autocomplete.
 
 ## Installation
 
@@ -18,84 +19,149 @@ import { defineEngineConfig } from '@pikacss/core'
 import { icons } from '@pikacss/plugin-icons'
 
 export default defineEngineConfig({
-  plugins: [
-    icons()
-  ],
-  icons: {
-    // Configure icons plugin here
-    prefix: 'i-',
-    scale: 1,
-    mode: 'auto',
-  }
+	plugins: [
+		icons() // ⚠️ Must be a function call!
+	],
+	icons: {
+		prefix: 'i-',
+		scale: 1,
+		mode: 'auto',
+	}
 })
 ```
 
-**Your code**:
+**Module Augmentation** (TypeScript autocomplete support):
+```typescript
+declare module '@pikacss/core' {
+	interface EngineConfig {
+		icons?: {
+			prefix?: string | string[] // Default: 'i-'
+			scale?: number // Default: 1
+			mode?: 'auto' | 'mask' | 'bg' // Default: 'auto'
+			cdn?: string // CDN base URL
+			collections?: Record<string, any> // Custom icon collections
+			autoInstall?: boolean // Default: false
+			unit?: string // Size unit for icons
+			extraProperties?: Record<string, string> // Extra CSS props
+			processor?: (styleItem: StyleItem, meta: IconMeta) => void
+			autocomplete?: string[] // Icons for autocomplete
+		}
+	}
+}
+
+export default defineEngineConfig({
+	plugins: [icons()],
+	icons: { // ✅ Full autocomplete for all options
+		prefix: 'icon-',
+		scale: 1.2,
+		mode: 'mask'
+	}
+})
+```
+
+**Your code** (3 usage methods):
 ```typescript
 // Method 1: Direct shortcut string
 const iconClass = pika('i-mdi:home')
 
-// Method 2: With additional styles (shortcut as first argument)
+// Method 2: Shortcut with additional styles (recommended)
 const styledIcon = pika('i-mdi:home', {
-  fontSize: '24px',
-  color: 'blue'
+	fontSize: '24px',
+	color: 'blue'
 })
 
 // Method 3: Using __shortcut property in style object
 const iconWithStyles = pika({
-  __shortcut: 'i-mdi:home',
-  fontSize: '24px'
+	__shortcut: 'i-mdi:home',
+	fontSize: '24px'
 })
 ```
 
 ## Features
 
-- 🎨 Access to 100,000+ icons from popular icon sets
-- 🔍 Auto-installs icon collections on demand
-- 📦 Tree-shakeable - only icons you use are included
-- 🎯 Simple shortcut syntax with customizable prefix
-- 🔧 Customizable icon collections
-- ⚡ Built on top of Iconify
-- 🎭 Supports both mask mode (for currentColor) and background mode
+- 🎨 **100,000+ icons** from popular icon sets via Iconify
+- 🔍 **Auto-installs** icon collections on demand (optional)
+- 📦 **Tree-shakeable** - only icons you use are included
+- 🎯 **Simple shortcut syntax** with customizable prefix
+- 🔧 **Customizable** icon collections and CDN
+- ⚡ **Built on Iconify** - reliable and fast
+- 🎭 **3 rendering modes**: auto, mask (currentColor), bg (background)
+- 💡 **Full TypeScript autocomplete** via module augmentation
 
 ## Usage
 
-### Basic Icon Usage
+### Three Usage Methods
 
-Icons are provided as shortcuts (default prefix is `i-`):
+PikaCSS provides three ways to use icons:
 
+**Method 1: Direct shortcut string** (simplest)
 ```typescript
-// Direct shortcut string
 const iconClass = pika('i-mdi:home')
+```
 
-// Combine shortcut with styles (recommended)
+**Method 2: Shortcut with additional styles** (recommended)
+```typescript
 const styledIcon = pika('i-mdi:home', {
-  fontSize: '24px',
-  color: 'blue'
+	fontSize: '24px',
+	color: 'blue'
 })
+```
 
-// Or use __shortcut property
+**Method 3: Using `__shortcut` property** (for complex objects)
+```typescript
 const iconWithStyles = pika({
-  __shortcut: 'i-mdi:home',
-  display: 'inline-block'
+	__shortcut: 'i-mdi:home',
+	fontSize: '24px',
+	display: 'inline-block'
 })
 ```
 
+All three methods produce the same underlying shortcut registration - choose based on your coding style.
+
 ### Supported Icon Collections
 
-All Iconify icon collections are supported. Some popular ones:
+All Iconify icon collections are supported (100,000+ icons). Popular collections include:
 
-- **Material Design Icons**: `mdi:*`
-- **Heroicons**: `heroicons:*`
-- **Bootstrap Icons**: `bi:*`
-- **Font Awesome**: `fa:*`, `fa-solid:*`, `fa-brands:*`
-- **Tabler Icons**: `tabler:*`
-- **Carbon**: `carbon:*`
-- **Phosphor**: `ph:*`
-- **Lucide**: `lucide:*`
+- **Material Design Icons**: `i-mdi:*` (5,000+ icons)
+- **Heroicons**: `i-heroicons:*` (300+ icons)
+- **Bootstrap Icons**: `i-bi:*` (1,800+ icons)
+- **Font Awesome**: `i-fa:*`, `i-fa-solid:*`, `i-fa-brands:*` (2,000+ icons)
+- **Tabler Icons**: `i-tabler:*` (4,000+ icons)
+- **Carbon**: `i-carbon:*` (2,000+ icons)
+- **Phosphor**: `i-ph:*` (6,000+ icons)
+- **Lucide**: `i-lucide:*` (1,000+ icons)
 
 Browse all collections at: [Iconify Icon Sets](https://icon-sets.iconify.design/)
 
+### Icon Syntax
+
+Icons follow the pattern: **`{prefix}{collection}:{icon-name}`**
+
+Default prefix is `i-`, so the full syntax is: `i-{collection}:{name}`
+
+```typescript
+pika('i-mdi:home') // Material Design home icon
+pika('i-heroicons:user') // Heroicons user icon
+pika('i-carbon:cloud-upload') // Carbon cloud upload icon
+```
+
+### Icon Rendering Modes
+
+Append `?mask`, `?bg`, or `?auto` to specify the rendering mode:
+
+```typescript
+pika('i-mdi:home?mask') // Mask mode (uses currentColor)
+pika('i-mdi:home?bg') // Background mode
+pika('i-mdi:home?auto') // Auto-detect (default)
+```
+
+**Mode descriptions:**
+- **`auto`** (default): Automatically selects `mask` or `bg` based on whether the icon's SVG contains `currentColor`
+- **`mask`**: Icon uses CSS mask with `currentColor`, inheriting text color (best for monochrome icons)
+- **`bg`**: Icon uses `background-image` (best for multi-colored icons)
+
+**Implementation detail:** The mode detection happens at build time by checking if the icon's SVG source includes the string `"currentColor"`. If found, mode defaults to `mask`; otherwise, it defaults to `bg`.
+
 ### Usage Examples
 
 ```typescript
@@ -104,74 +170,52 @@ const homeIcon = pika('i-mdi:home')
 
 // Icon with size and color
 const largeIcon = pika('i-mdi:account', {
-  fontSize: '48px',
-  color: '#3b82f6'
+	fontSize: '48px',
+	color: '#3b82f6'
 })
 
 // Icon with hover effect
 const hoverIcon = pika('i-mdi:heart', {
-  fontSize: '24px',
-  color: 'red',
-  cursor: 'pointer',
-  '$:hover': {
-    transform: 'scale(1.2)'
-  }
+	'fontSize': '24px',
+	'color': 'red',
+	'cursor': 'pointer',
+	'$:hover': {
+		transform: 'scale(1.2)'
+	}
 })
 
 // Combining multiple shortcuts
 const buttonWithIcon = pika('btn', 'i-mdi:send', {
-  display: 'inline-flex',
-  alignItems: 'center',
-  gap: '0.5rem'
+	display: 'inline-flex',
+	alignItems: 'center',
+	gap: '0.5rem'
 })
 ```
 
-### Icon Syntax
-
-Icons follow the pattern: `{prefix}{collection}:{icon-name}` (default prefix is `i-`)
-
-```typescript
-pika('i-mdi:home')              // Material Design home icon
-pika('i-heroicons:user')        // Heroicons user icon
-pika('i-carbon:cloud-upload')   // Carbon cloud upload icon
-```
-
-### Icon Rendering Modes
-
-Append `?mask`, `?bg`, or `?auto` to specify the rendering mode:
-
-```typescript
-pika('i-mdi:home?mask')  // Mask mode (uses currentColor)
-pika('i-mdi:home?bg')    // Background mode
-pika('i-mdi:home?auto')  // Auto-detect (default)
-```
-
-- **auto**: Automatically selects mask or bg based on whether icon contains `currentColor`
-- **mask**: Icon inherits the current text color (good for monochrome icons)
-- **bg**: Uses background-image (good for multi-colored icons)
-
 ### Customizing Icon Size and Color
 
-Icons inherit text properties:
+Icons inherit text properties by default:
 
 ```typescript
-// Using shortcut with styles
+// Method 2: Shortcut with styles
 pika('i-mdi:home', {
-  fontSize: '32px',
-  color: '#3b82f6'  // Works with mask mode
+	fontSize: '32px', // Controls icon size
+	color: '#3b82f6' // Works with mask mode
 })
 
-// Using __shortcut property
+// Method 3: __shortcut property
 pika({
-  __shortcut: 'i-mdi:home',
-  fontSize: '32px',
-  color: '#3b82f6'
+	__shortcut: 'i-mdi:home',
+	fontSize: '32px',
+	color: '#3b82f6'
 })
 ```
 
+**Note:** Color inheritance only works in `mask` mode. In `bg` mode, the icon retains its original colors.
+
 ## Configuration
 
-Configure the icons plugin using the standard plugin pattern:
+The icons plugin is configured using the standard PikaCSS plugin pattern with full TypeScript autocomplete:
 
 ```typescript
 /// <reference path="./src/pika.gen.ts" />
@@ -180,124 +224,245 @@ import { defineEngineConfig } from '@pikacss/core'
 import { icons } from '@pikacss/plugin-icons'
 
 export default defineEngineConfig({
-  // 1. Register plugin in plugins array
-  plugins: [
-    icons()  // Note: Call the function!
-  ],
-  
-  // 2. Configure at root level
-  icons: {
-    prefix: 'i-',        // Shortcut prefix
-    scale: 1,            // Icon scale multiplier
-    mode: 'auto',        // 'auto' | 'mask' | 'bg'
-    cdn: 'https://esm.sh/', // CDN for icon collections
-    autoInstall: false,  // Auto-install icon packages
-    // ... other options
-  }
+	// 1. Register plugin in plugins array
+	plugins: [
+		icons() // ⚠️ Must be a function call: icons() not icons
+	],
+
+	// 2. Configure at root level with full autocomplete
+	icons: {
+		prefix: 'i-', // Shortcut prefix
+		scale: 1, // Icon scale multiplier
+		mode: 'auto', // 'auto' | 'mask' | 'bg'
+		cdn: 'https://esm.sh/', // CDN for icon collections
+		autoInstall: false, // Auto-install icon packages
+		// ... other options
+	}
 })
 ```
 
-::: tip Common Mistake
+::: warning Common Mistake
 Always call the plugin function: `plugins: [icons()]` not `plugins: [icons]`
 :::
 
-### Available Options
+### All Configuration Options
 
 ```typescript
 interface IconsConfig {
-  /**
-   * Icon shortcut prefix.
-   * @default 'i-'
-   */
-  prefix?: string | string[]
-
-  /**
-   * Scale factor for icons.
-   * @default 1
-   */
-  scale?: number
-
-  /**
-   * Icon rendering mode.
-   * - 'auto': Auto-detect based on currentColor
-   * - 'mask': Use mask with currentColor
-   * - 'bg': Use background image
-   * @default 'auto'
-   */
-  mode?: 'auto' | 'mask' | 'bg'
-
-  /**
-   * CDN base URL for loading icon collections.
-   */
-  cdn?: string
-
-  /**
-   * Custom icon collections.
-   */
-  collections?: Record<string, any>
-
-  /**
-   * Auto-install icon collections from npm.
-   * @default false
-   */
-  autoInstall?: boolean
-
-  /**
-   * Unit for icon size (when specified).
-   */
-  unit?: string
-
-  /**
-   * Extra CSS properties to apply to all icons.
-   */
-  extraProperties?: Record<string, string>
-
-  /**
-   * Custom processor for icon styles.
-   */
-  processor?: (styleItem: StyleItem, meta: IconMeta) => void
-
-  /**
-   * Icons for auto-completion.
-   */
-  autocomplete?: string[]
+	/**
+	 * Icon shortcut prefix.
+	 * Can be a single string or array of prefixes.
+	 * @default 'i-'
+	 */
+	prefix?: string | string[]
+
+	/**
+	 * Scale factor for icons.
+	 * Multiplies icon dimensions.
+	 * @default 1
+	 */
+	scale?: number
+
+	/**
+	 * Icon rendering mode.
+	 * - 'auto': Auto-detect based on currentColor in SVG
+	 * - 'mask': Use CSS mask with currentColor (inherits text color)
+	 * - 'bg': Use background-image (preserves original colors)
+	 * @default 'auto'
+	 */
+	mode?: 'auto' | 'mask' | 'bg'
+
+	/**
+	 * CDN base URL for loading icon collections.
+	 * Icons are fetched from this CDN when not found locally.
+	 * @example 'https://esm.sh/'
+	 */
+	cdn?: string
+
+	/**
+	 * Custom icon collections.
+	 * Define your own icons as SVG strings.
+	 * @example
+	 * {
+	 *   'my-icons': {
+	 *     'logo': '<svg>...</svg>',
+	 *     'custom': '<svg>...</svg>'
+	 *   }
+	 * }
+	 */
+	collections?: Record<string, any>
+
+	/**
+	 * Auto-install icon collections from npm.
+	 * When enabled, missing icon packages are automatically installed.
+	 * @default false
+	 */
+	autoInstall?: boolean
+
+	/**
+	 * Unit for icon size (when specified).
+	 * Applied to width and height when using scale with unit.
+	 * @example 'em', 'rem', 'px'
+	 */
+	unit?: string
+
+	/**
+	 * Extra CSS properties to apply to all icons.
+	 * Merged into every generated icon style.
+	 * @example { verticalAlign: 'middle' }
+	 */
+	extraProperties?: Record<string, string>
+
+	/**
+	 * Custom processor for icon styles before rendering.
+	 * Allows modifying the generated CSS object.
+	 */
+	processor?: (styleItem: StyleItem, meta: IconMeta) => void
+
+	/**
+	 * Icons for auto-completion in your editor.
+	 * List of icon shortcuts to provide autocomplete suggestions.
+	 * @example ['mdi:home', 'heroicons:user']
+	 */
+	autocomplete?: string[]
+
+	/**
+	 * Iconify collection names for validation.
+	 */
+	iconifyCollectionsNames?: string[]
+
+	/**
+	 * Path for resolving icon collection node modules.
+	 */
+	collectionsNodeResolvePath?: string
+
+	/**
+	 * Customizations for icon SVG processing.
+	 */
+	customizations?: IconifyLoaderCustomizations
 }
 ```
 
-### Custom Icon Prefix
+### Configuration Examples
 
-Change the shortcut prefix:
+#### Custom Icon Prefix
+
+Change the shortcut prefix to avoid conflicts:
 
 ```typescript
 export default defineEngineConfig({
-  plugins: [icons()],
-  icons: {
-    prefix: 'icon-'  // Now use icon-mdi:home
-  }
+	plugins: [icons()],
+	icons: {
+		prefix: 'icon-' // Now use: icon-mdi:home
+	}
 })
+
+// Usage with custom prefix
+const iconClass = pika('icon-mdi:home')
 ```
 
-### Custom Icon Scale
+#### Custom Icon Scale
 
 Adjust the default scale of all icons:
 
 ```typescript
 export default defineEngineConfig({
-  plugins: [icons()],
-  icons: {
-    scale: 1.2  // Make all icons 20% larger
-  }
+	plugins: [icons()],
+	icons: {
+		scale: 1.2 // Make all icons 20% larger
+	}
 })
 ```
 
+#### Force Specific Rendering Mode
+
+Override auto-detection to always use mask or bg mode:
+
+```typescript
+export default defineEngineConfig({
+	plugins: [icons()],
+	icons: {
+		mode: 'mask' // All icons inherit text color
+	}
+})
+```
+
+#### Multiple Prefixes
+
+Support multiple shortcut prefixes:
+
+```typescript
+export default defineEngineConfig({
+	plugins: [icons()],
+	icons: {
+		prefix: ['i-', 'icon-'] // Both work
+	}
+})
+
+// Both are valid
+const icon1 = pika('i-mdi:home')
+const icon2 = pika('icon-mdi:home')
+```
+
+#### Custom Icon Collections
+
+Define your own icon collections:
+
+```typescript
+export default defineEngineConfig({
+	plugins: [icons()],
+	icons: {
+		collections: {
+			'my-icons': {
+				logo: '<svg viewBox="0 0 24 24"><path d="..." /></svg>',
+				custom: '<svg>...</svg>'
+			}
+		}
+	}
+})
+
+// Usage
+const myIcon = pika('i-my-icons:logo')
+```
+
 ## How It Works
 
-The plugin automatically:
+The plugin registers icon shortcuts using the PikaCSS shortcut system:
+
+1. **Pattern Detection**: Icons matching `{prefix}{collection}:{name}` pattern (e.g., `i-mdi:home`) are detected in your `pika()` calls
+2. **SVG Loading**: Icon SVG is loaded from Iconify (via CDN or local node_modules)
+3. **CSS Variable Generation**: SVG is encoded and stored as a CSS custom property (e.g., `--pika-svg-icon-mdi-home`)
+4. **Mode Selection**: Based on mode setting and SVG content:
+   - **auto**: Checks if SVG contains `currentColor` → mask mode if yes, bg mode if no
+   - **mask**: Uses CSS mask properties with `background-color: currentColor` (icon inherits text color)
+   - **bg**: Uses `background-image` (icon retains original colors)
+5. **Style Application**: CSS properties are applied to create the final icon appearance
 
-1. Detects icon usage in your code
-2. Downloads the required icon collections from Iconify
-3. Generates optimized SVG background images
-4. Applies them using CSS custom properties
+**Example flow:**
+```typescript
+pika('i-mdi:home', { fontSize: '24px', color: 'blue' })
+```
+1. Plugin detects `i-mdi:home` shortcut
+2. Loads Material Design Icons "home" icon from Iconify
+3. Encodes SVG: `url("data:image/svg+xml;utf8,...")`
+4. Stores in CSS variable: `--pika-svg-icon-mdi-home`
+5. Applies mask mode (if icon uses currentColor):
+   ```css
+   .generated-class {
+     --svg-icon: var(--pika-svg-icon-mdi-home);
+     -webkit-mask: var(--svg-icon) no-repeat;
+     mask: var(--svg-icon) no-repeat;
+     mask-size: 100% 100%;
+     background-color: currentColor;
+     font-size: 24px;
+     color: blue;
+   }
+   ```
+
+This approach ensures:
+- **Efficient CSS**: Icons are stored once as CSS variables and reused
+- **Color Inheritance**: Mask mode allows icons to inherit text color dynamically
+- **Performance**: Only icons you use are included in the bundle
 
 ## Performance
 

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@pikacss/plugin-icons",
   "type": "module",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.git",
+    "url": "https://github.com/pikacss/pikacss.github.io.git",
     "directory": "packages/plugin-icons"
   },
   "bugs": {
-    "url": "https://github.com/pikacss/pikacss/issues"
+    "url": "https://github.com/pikacss/pikacss.github.io/issues"
   },
   "keywords": [
     "pikacss",
@@ -42,7 +42,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@pikacss/core": "0.0.39"
+    "@pikacss/core": "0.0.40"
   },
   "dependencies": {
     "@iconify/utils": "^3.1.0",
@@ -50,7 +50,7 @@
     "ofetch": "^1.5.1"
   },
   "devDependencies": {
-    "@pikacss/core": "0.0.39"
+    "@pikacss/core": "0.0.40"
   },
   "scripts": {
     "build": "tsdown && pnpm exec publint",