# Icon Library

A comprehensive icon library with support for multiple categories and sizes.

## Features

- Multiple icon categories (archive, arrow, basic, flags, etc.)
- Two size variants: 16px and 24px
- Optimized CSS output with minimal duplication
- Special handling for flag icons (displayed with original colors)
- Mask-based icons for color inheritance
- Responsive and accessible

## Installation

```bash
npm install
```

## NPM Installation

```bash
# Using npm
npm install @denarius/icons-ui

# Using yarn
yarn add @denarius/icons-ui
```

## Usage

### HTML

```html
<!-- Basic icon -->
<div class="icon-basic-home"></div>

<!-- Icon with size modifier -->
<div class="icon-basic-home icon--sm"></div>

<!-- Flag icon (displays with original colors) -->
<div class="icon-flags-us"></div>
```

### CSS

```css
/* Custom styling for icons */
.icon-basic-home {
  color: blue; /* This will change the color of the icon */
}

/* Flag icons maintain their original colors */
.icon-flags-us {
  /* No color property needed for flags */
}
```

## Icon Categories

The library includes the following icon categories:

- archive
- arrow
- basic
- flags (special handling with original colors)
- and many more...

## Advanced Usage

### Theme Integration

```scss
// Dark mode support
.icon-theme {
  @include icon-mask("../assets/icons/theme.svg", #333);

  @media (prefers-color-scheme: dark) {
    background-color: #fff;
  }
}

// Custom theme colors
.custom-theme {
  --icon-primary: #007bff;
  --icon-secondary: #6c757d;

  .icon-custom {
    @include icon-mask("../assets/icons/custom.svg", var(--icon-primary));

    &:hover {
      background-color: var(--icon-secondary);
    }
  }
}
```

### Responsive Patterns

```scss
// Mobile-first approach
.icon-responsive {
  @include icon-complete(
    "../assets/icons/responsive.svg",
    (
      size: 16px,
      color: #007bff,
      responsive: true,
    )
  );
}

// Custom breakpoints
.icon-custom-responsive {
  @include icon-size(16px);

  @media (min-width: 576px) {
    @include icon-size(20px);
  }
  @media (min-width: 768px) {
    @include icon-size(24px);
  }
  @media (min-width: 992px) {
    @include icon-size(32px);
  }
}
```

### Animation Integration

```scss
// Rotating icon
.icon-spinner {
  @include icon-complete(
    "../assets/icons/spinner.svg",
    (
      size: 24px,
      color: #007bff,
      transition: 0.3s,
    )
  );
  animation: spin 1s linear infinite;
}

// Pulse effect
.icon-notification {
  @include icon-complete(
    "../assets/icons/notification.svg",
    (
      size: 24px,
      color: #dc3545,
      transition: 0.3s,
    )
  );
  animation: pulse 2s ease infinite;
}

@keyframes spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

@keyframes pulse {
  0% {
    transform: scale(1);
  }
  50% {
    transform: scale(1.2);
  }
  100% {
    transform: scale(1);
  }
}
```

### Best Practices

1. **Icon Sizing**

   - Use standard sizes (16px, 24px, 32px) for consistency
   - Implement responsive sizes based on viewport
   - Consider touch target sizes for interactive icons (minimum 44x44px)

2. **Color Management**

   - Use CSS variables for theme colors
   - Implement consistent hover states
   - Consider color contrast for accessibility
   - Use `currentColor` for icons that should inherit text color

3. **Performance**

   - Optimize SVG files before usage
   - Use appropriate caching strategies
   - Implement lazy loading for large icon sets
   - Consider using sprite sheets for multiple icons

4. **Accessibility**
   - Add appropriate `aria-label` attributes
   - Ensure sufficient color contrast
   - Provide text alternatives where needed
   - Consider reduced motion preferences

```html
<!-- Accessible icon button -->
<button class="icon-button" aria-label="Close dialog">
  <span class="icon-close" aria-hidden="true"></span>
</button>

<!-- Icon with text -->
<div class="icon-with-text">
  <span class="icon-info" aria-hidden="true"></span>
  <span>Information</span>
</div>
```

### Troubleshooting

Common issues and solutions:

1. **Icons not displaying**

   - Check if paths to SVG files are correct
   - Verify SVG files are properly optimized
   - Ensure mask properties are supported in target browsers

2. **Colors not applying**

   - Verify the icon is using `icon-mask` mixin
   - Check if color values are valid
   - Ensure no conflicting styles are present

3. **Responsive issues**

   - Verify media query breakpoints
   - Check if responsive option is enabled
   - Ensure parent container isn't restricting size

4. **Performance concerns**
   - Optimize SVG files
   - Use appropriate caching
   - Consider lazy loading
   - Implement sprite sheets for multiple icons

### Browser Support

The library supports all modern browsers with the following features:

- CSS Masks
- CSS Custom Properties (variables)
- CSS Grid
- Flexbox
- CSS Animations

| Feature       | Chrome | Firefox | Safari | Edge |
| ------------- | ------ | ------- | ------ | ---- |
| CSS Masks     | 51+    | 53+     | 9.1+   | 79+  |
| CSS Variables | 49+    | 31+     | 9.1+   | 79+  |
| CSS Grid      | 57+    | 52+     | 10.1+  | 79+  |
| Flexbox       | 21+    | 28+     | 6.1+   | 12+  |

### Contributing

1. **Adding new icons**

   ```bash
   # Add SVG file to assets/icons directory
   npm run build  # Regenerates icon map
   ```

2. **Creating new mixins**

   ```scss
   // Add to styles/mixins/_icon-helpers.scss
   @mixin icon-new-feature($param) {
     // Implementation
   }
   ```

## Development

### Project Structure

```
IconLibrary/
├── dist/                        # Distribution files
│ ├── assets/                    # Copied assets
│ │   └── icons/                 # SVG icons
│ └── css/                       # Compiled CSS
│ └── Scss/                      # Helper Mixins
│
├── assets/                      # Asset files
│ ├── icons/                     # SVG icons
│ └── animations/                # Animation files
│
├── styles/                      # SASS styles
│ └── mixins/                    # SASS mixins
│   ├── icon-library.scss        # Icon library mixins
│   ├── icon-helpers.scss        # Icon helper mixins
│   └── icon-map.scss            # Auto-generated icon map
│
├── scripts/                     # Build scripts
│ ├── generate-icon-map.js       # Generates the icon map
│ ├── generate-demo.js           # Generates demo HTML
│ └── copy-files.js              # Copies files to dist
│
├── demo/                        # Auto-generated Demo files and documentation
└── azure-pipelines.yml          # CI/CD pipeline configuration
```

### Build Process

The project provides two main scripts:

1. **Build the library**:

   ```bash
   npm run build
   ```

   This script generates the icon map, builds the SASS files, and copies all necessary files to the distribution folder.

2. **Generate demo**:
   ```bash
   npm run demo
   ```
   This script generates a demo HTML page showcasing all available icons.

## How It Works

### Icon Implementation

The library uses two different approaches for displaying icons:

1. **Mask-based Icons** (most categories):

   - Uses CSS mask properties to display icons
   - Icons inherit the text color via `currentColor`
   - Allows for easy color customization

2. **Flag Icons** (flags category):
   - Uses regular background images
   - Icons display with their original colors
   - No color inheritance (flags maintain their design colors)

### CSS Optimization

The generated CSS is optimized to minimize file size:

- Common properties are shared via SASS extends
- Separate base classes for different icon types
- Efficient selector structure

## License

MIT

## Usage with NPM

### CSS Usage

```html
<!-- In your HTML file -->
<link
  rel="stylesheet"
  href="node_modules/@denarius/icons-ui/dist/css/icon-library.min.css"
/>
```

```javascript
// In your JavaScript file
import "@denarius/icons-ui/dist/css/icon-library.css";
```