npm package: @ng-vui/icon
Description: Angular SVG Component for NG-VUI Library
Author: Varun Singh
Latest version: 1.0.1

# NgVuiIcon Component

A comprehensive SVG icon library component for consistent and scalable icons across the application.

## Features

- 🎨 **SVG-based**: Crisp, scalable vector icons
- 📚 **Icon Registry**: Centralized icon management system
- 🎯 **File Type Detection**: Smart icon selection based on file types
- 🎨 **Customizable**: Multiple sizes and color variants
- 🔧 **Extensible**: Easy to add custom icons
- ♿ **Accessible**: Proper ARIA support
- 📱 **Responsive**: Scales perfectly at any size

## Installation

The component is part of the ng-vui component library:

```typescript
import { NgVuiIconComponent } from 'path/to/ng-vui-icon';
```

## Basic Usage

### Simple Icon

```html
<ng-vui-icon name="file" size="24px"></ng-vui-icon>
<ng-vui-icon name="upload" color="primary"></ng-vui-icon>
<ng-vui-icon name="check-circle" color="success"></ng-vui-icon>
```

### File Type Icons

```html
<!-- Automatic file type detection -->
<ng-vui-icon [name]="getFileTypeIcon('document.pdf')"></ng-vui-icon>
<ng-vui-icon [name]="getFileTypeIcon('photo.jpg')"></ng-vui-icon>
<ng-vui-icon [name]="getFileTypeIcon('data.xlsx')"></ng-vui-icon>
```

### Status Icons

```html
<!-- Upload status indicators -->
<ng-vui-icon [name]="getStatusIcon('pending')"></ng-vui-icon>
<ng-vui-icon [name]="getStatusIcon('uploading')"></ng-vui-icon>
<ng-vui-icon [name]="getStatusIcon('success')"></ng-vui-icon>
<ng-vui-icon [name]="getStatusIcon('error')"></ng-vui-icon>
```

## Available Icons

### File Type Icons
- `file` - Generic file
- `file-image` - Image files
- `file-pdf` - PDF documents
- `file-doc` - Word documents
- `file-excel` - Excel spreadsheets
- `file-zip` - Archive files

### Upload & Folder Icons
- `folder` - Folder/directory
- `upload` - Upload arrow
- `paperclip` - Attachment
- `upload-cloud` - Cloud upload

### Status Icons
- `clock` - Pending status
- `upload-cloud` - Uploading status
- `check-circle` - Success status
- `x-circle` - Error status

### Action Icons
- `x` - Close/remove
- `plus` - Add/create

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `name` | `string` | - | Icon name from registry |
| `size` | `string` | `'20px'` | Icon size (CSS value) |
| `color` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info' \| 'muted'` | - | Color variant |
| `className` | `string` | - | Additional CSS classes |

## Size Variants

```html
<!-- Predefined sizes -->
<ng-vui-icon name="file" size="12px"></ng-vui-icon> <!-- xs -->
<ng-vui-icon name="file" size="16px"></ng-vui-icon> <!-- sm -->
<ng-vui-icon name="file" size="20px"></ng-vui-icon> <!-- md (default) -->
<ng-vui-icon name="file" size="24px"></ng-vui-icon> <!-- lg -->
<ng-vui-icon name="file" size="32px"></ng-vui-icon> <!-- xl -->

<!-- Custom sizes -->
<ng-vui-icon name="file" size="48px"></ng-vui-icon>
<ng-vui-icon name="file" size="2rem"></ng-vui-icon>
```

## Color Variants

```html
<ng-vui-icon name="file" color="primary"></ng-vui-icon>   <!-- Blue -->
<ng-vui-icon name="file" color="secondary"></ng-vui-icon> <!-- Gray -->
<ng-vui-icon name="file" color="success"></ng-vui-icon>   <!-- Green -->
<ng-vui-icon name="file" color="warning"></ng-vui-icon>   <!-- Yellow -->
<ng-vui-icon name="file" color="error"></ng-vui-icon>     <!-- Red -->
<ng-vui-icon name="file" color="info"></ng-vui-icon>      <!-- Cyan -->
<ng-vui-icon name="file" color="muted"></ng-vui-icon>     <!-- Light gray -->
```

## Custom Icons

### Register Single Icon

```typescript
import { registerIcon } from 'path/to/ng-vui-icon';

registerIcon('custom-icon', `
  <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="..." stroke="currentColor" stroke-width="2"/>
  </svg>
`);
```

### Register Multiple Icons

```typescript
import { registerIcons } from 'path/to/ng-vui-icon';

registerIcons({
  'custom-icon-1': '<svg>...</svg>',
  'custom-icon-2': '<svg>...</svg>',
  'brand-logo': '<svg>...</svg>'
});
```

## Utility Functions

### File Type Detection

```typescript
import { getFileTypeIcon } from 'path/to/ng-vui-icon';

// By filename
const iconName = getFileTypeIcon('document.pdf'); // Returns 'file-pdf'
const iconName = getFileTypeIcon('photo.jpg');    // Returns 'file-image'

// By filename and MIME type
const iconName = getFileTypeIcon('file.bin', 'image/png'); // Returns 'file-image'
```

### Status Icon Selection

```typescript
import { getStatusIcon } from 'path/to/ng-vui-icon';

const iconName = getStatusIcon('pending');   // Returns 'clock'
const iconName = getStatusIcon('uploading'); // Returns 'upload-cloud'
const iconName = getStatusIcon('success');   // Returns 'check-circle'
const iconName = getStatusIcon('error');     // Returns 'x-circle'
```

## Integration with File Uploader

Replace emoji icons in the file uploader component:

```html
<!-- Before (emoji) -->
<span class="file-icon">📁</span>

<!-- After (SVG) -->
<ng-vui-icon
  [name]="getFileTypeIcon(file.name, file.type)"
  size="16px"
  color="secondary">
</ng-vui-icon>
```

## Usage in File Uploader Mini Component

Here's how to integrate with the existing file uploader:

```typescript
// In component
import { getFileTypeIcon, getStatusIcon } from 'path/to/ng-vui-icon';

export class NgVuiFileUploaderMiniComponent {
  getFileIconName(file: MiniFileMetadata): string {
    return getFileTypeIcon(file.name, file.type);
  }

  getStatusIconName(status: string): string {
    return getStatusIcon(status);
  }
}
```

```html
<!-- In template -->
<ng-vui-icon
  [name]="getFileIconName(file)"
  size="16px"
  color="secondary">
</ng-vui-icon>

<ng-vui-icon
  [name]="getStatusIconName(file.status)"
  size="14px">
</ng-vui-icon>
```

## Styling

The component uses CSS custom properties for easy theming:

```css
ng-vui-icon {
  --icon-color-primary: #3b82f6;
  --icon-color-secondary: #6b7280;
  --icon-color-success: #10b981;
  --icon-color-warning: #f59e0b;
  --icon-color-error: #ef4444;
  --icon-color-info: #06b6d4;
  --icon-color-muted: #9ca3af;
}
```

## Accessibility

The component includes proper accessibility features:
- Uses `currentColor` for SVG stroke/fill for proper contrast
- Supports high contrast mode
- Proper semantic markup
- Screen reader compatible

## Performance

- **Lightweight**: SVG icons are embedded, no external requests
- **Tree Shakable**: Only registered icons are included in bundle
- **Cached**: Icon registry prevents duplicate SVG parsing
- **Optimized**: Minimal DOM structure and CSS

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- IE 11+ (with polyfills)

## Migration from Emoji Icons

1. Replace emoji strings with icon names:
   ```typescript
   // Before
   getFileIcon(file): string {
     if (file.type.startsWith('image/')) return '🖼️';
     return '📄';
   }

   // After
   getFileIconName(file): string {
     return getFileTypeIcon(file.name, file.type);
   }
   ```

2. Update templates:
   ```html
   <!-- Before -->
   <span>{{ getFileIcon(file) }}</span>

   <!-- After -->
   <ng-vui-icon [name]="getFileIconName(file)" size="16px"></ng-vui-icon>
   ```

## Contributing

When adding new icons:
1. Use consistent viewBox (0 0 24 24)
2. Use `currentColor` for stroke/fill
3. Follow naming convention: `category-name`
4. Include both outline and filled variants if needed
5. Test with different sizes and colors
6. Update documentation

## 📄 License

MIT © [VUI](https://github.com/ultimatevarun/ng-vui-examples)

---

**Need help?** Check our [documentation](https://ultimatevarun.github.io/ng-vui-examples/ng-vui-icon.html) or open an issue on GitHub.