@denariusfinancees/icons-ui/dist/README.md

Library containing Denarius brand UI icons

# Denarius Icons UI Library - Distribution Files

This directory contains the distributed files of the Denarius Icons UI Library. These files are ready to use in your projects.

## Directory Structure

```
dist/
├── assets/
│   └── icons/                          # SVG icon files organized by category
│       ├── basic/                      # Basic UI elements
│       │   ├── basic-16-home.svg       # 16px home icon
│       │   ├── basic-24-home.svg       # 24px home icon
│       │   ├── basic-16-search.svg     # 16px search icon
│       │   └── basic-24-search.svg     # 24px search icon
│       │
│       ├── arrows/                     # Directional arrows
│       │   ├── arrows-16-left.svg      # 16px left arrow
│       │   ├── arrows-24-left.svg      # 24px left arrow
│       │   ├── arrows-16-right.svg     # 16px right arrow
│       │   └── arrows-24-right.svg     # 24px right arrow
│       │
│       ├── weather/                    # Weather-related icons
│       │   ├── weather-16-sun.svg      # 16px sun icon
│       │   ├── weather-24-sun.svg      # 24px sun icon
│       │   ├── weather-16-cloud.svg    # 16px cloud icon
│       │   └── weather-24-cloud.svg    # 24px cloud icon
│       │
│       └── more categories...
│
├── css/                                # Pre-compiled CSS files
│   ├── denarius-ui-icons.css           # Unminified CSS for development
│   └── denarius-ui-icons.min.css       # Minified CSS for production
│
└── scss/                               # SCSS source files for customization
    └── _denarius-ui-icon-helpers.scss  # Helper mixins for icon implementation
```

## Asset Management

### Copying Icon Assets

When building your application, you need to copy the icon assets to your project's distribution folder. Here are the recommended approaches:

1. **Using glob pattern in your build configuration:**

```javascript
// Example using webpack
module.exports = {
  // ... other config
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        {
          from: 'node_modules/@denariusfinancees/icons-ui/dist/assets/icons/**/*',
          to: 'assets/icons/[path][name][ext]'
        }
      ]
    })
  ]
};

// Example using Angular CLI (angular.json)
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "node_modules/@denariusfinancees/icons-ui/dist/assets/icons",
                "output": "assets/icons"
              }
            ]
          }
        }
      }
    }
  }
}
```

2. **Using npm scripts:**

```json
{
  "scripts": {
    "copy-icons": "copyfiles -u 4 \"node_modules/@denariusfinancees/icons-ui/dist/assets/icons/**/*\" dist/assets/icons"
  }
}
```

### Important Notes

- The icon assets must be copied to maintain the same directory structure as in the library
- Ensure the paths in your CSS/SCSS files match the final location of the assets
- Consider using a build tool that can handle this automatically
- The assets should be copied before the CSS is processed to ensure proper path resolution

## Quick Start

### 1. CSS Installation

```html
<link rel="stylesheet" href="css/denarius-ui-icons.min.css" />
```

### 2. Basic Usage

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

<!-- Icon with size variant -->
<span class="icon-basic-home icon--sm"></span>

<!-- Icon with custom color -->
<span class="icon-basic-home" style="color: #007bff;"></span>
```

## Advanced Usage

### SCSS Integration

1. **Import the Mixins**

```scss
@import "scss/mixins/denarius-ui-icon-helpers";
```

2. **Basic Icon Implementation**

```scss
.custom-icon {
  @include icon-mask("../assets/icons/basic/basic-24-home.svg", #333);
  @include icon-size(24px);
}
```

3. **Complete Icon Setup**

```scss
.advanced-icon {
  @include icon-complete(
    "../assets/icons/basic/basic-24-home.svg",
    (
      size: 24px,
      color: #007bff,
      hover-color: #0056b3,
      transition: 0.3s,
      responsive: true,
    )
  );
}
```

### Theme Integration

```scss
// Light/Dark theme support
.themed-icon {
  @include icon-mask("../assets/icons/basic/basic-24-home.svg");

  :root[data-theme="light"] & {
    background-color: #333;
  }

  :root[data-theme="dark"] & {
    background-color: #fff;
  }
}

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

  .theme-icon {
    @include icon-mask(
      "../assets/icons/basic/basic-24-home.svg",
      var(--icon-primary)
    );

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

### Responsive Implementation

```scss
// Mobile-first approach
.responsive-icon {
  @include icon-responsive(16px, 24px, 32px, #007bff);
}

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

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

## Available Mixins

### Core Mixins

| Mixin       | Description           | Parameters             |
| ----------- | --------------------- | ---------------------- |
| `icon-base` | Base icon properties  | None                   |
| `icon-size` | Set icon dimensions   | `$size`                |
| `icon-mask` | Color-inheriting icon | `$icon-path`, `$color` |
| `icon-bg`   | Fixed-color icon      | `$icon-path`           |

### Enhancement Mixins

| Mixin             | Description        | Parameters                    |
| ----------------- | ------------------ | ----------------------------- |
| `icon-hover`      | Hover state        | `$color`                      |
| `icon-transition` | Smooth transitions | `$duration`                   |
| `icon-rotate`     | Icon rotation      | `$degrees`                    |
| `icon-responsive` | Responsive sizing  | `$sm`, `$md`, `$lg`, `$color` |

### All-in-One Mixin

```scss
@include icon-complete(
  $icon-path,
  (
    size: 24px,
    // Icon size
    color: #000,
    // Base color
    hover-color: #333,
    // Hover color (optional)
    transition: 0.3s,
    // Transition duration (optional)
    rotate: 0deg,
    // Rotation angle (optional)
    responsive: false
      // Enable responsive sizing (optional),,,,,,,,,,,,,,,,,,,,,,,,
  )
);
```

## Icon Categories and Naming

### File Naming Convention

1. **SVG Icons**

   - Format: `{category}-{size}-{name}.svg`
   - Example: `basic-16-home.svg`, `basic-24-search.svg`
   - Sizes available: 16px and 24px

2. **CSS Files**

   - Development: `denarius-ui-icons.css`
   - Production: `denarius-ui-icons.min.css`

3. **SCSS Files**
   - Mixins: `_denarius-ui-icon-helpers.scss`

### Category Organization

Each category folder contains icons related to a specific theme:

- `basic/`: Common UI elements (home, search, menu, etc.)
- `arrows/`: Directional indicators (left, right, up, down)
- `weather/`: Weather symbols (sun, cloud, rain, etc.)
- `status/`: Status indicators (success, error, warning, etc.)
- etc...

## Best Practices

### Accessibility

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

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

### Performance

1. **CSS Import Optimization**

```html
<!-- Production -->
<link rel="stylesheet" href="css/denarius-ui-icons.min.css" />

<!-- Development -->
<link rel="stylesheet" href="css/denarius-ui-icons.css" />
```

2. **Lazy Loading**

```html
<link
  rel="stylesheet"
  href="css/denarius-ui-icons.min.css"
  media="print"
  onload="this.media='all'"
/>
```

## Browser Support

| Feature       | Chrome | Firefox | Safari | Edge |
| ------------- | ------ | ------- | ------ | ---- |
| Basic Support | 51+    | 53+     | 9.1+   | 79+  |
| CSS Masks     | 51+    | 53+     | 9.1+   | 79+  |
| CSS Variables | 49+    | 31+     | 9.1+   | 79+  |

## Troubleshooting

### Common Issues

1. **Icons not displaying**

   - Check if paths to SVG files are correct
   - Verify CSS is properly loaded
   - Ensure class names match exactly

2. **Colors not applying**

   - Verify the icon uses mask-based implementation
   - Check if color values are valid
   - Inspect for CSS specificity issues

3. **Size issues**
   - Confirm parent container constraints
   - Check responsive breakpoints
   - Verify size modifier classes

## Support

For issues and feature requests:

- GitHub Issues: [Your Repository URL]
- Documentation: [Your Docs URL]
- Support Email: [Your Support Email]

## License

[Your License Type] - See LICENSE file for details

## Angular Integration

### Installation

1. **Install the package**

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

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

2. **Import styles in angular.json**

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/@denarius/icons-ui/dist/css/denarius-ui-icons.min.css"
            ]
          }
        }
      }
    }
  }
}
```

### Basic Usage

1. **Component Implementation**

```typescript
// icon.component.ts
import { Component, Input } from "@angular/core";

@Component({
  selector: "app-icon",
  template: `
    <div
      [class]="iconClass"
      [style.color]="color"
      [attr.aria-label]="ariaLabel"
      [attr.aria-hidden]="!ariaLabel"
    ></div>
  `,
})
export class IconComponent {
  @Input() name: string = "";
  @Input() size: "sm" | "md" = "md";
  @Input() color?: string;
  @Input() ariaLabel?: string;

  get iconClass(): string {
    const classes = [`icon-${this.name}`];
    if (this.size === "sm") {
      classes.push("icon--sm");
    }
    return classes.join(" ");
  }
}
```

2. **Usage in Components**

```html
<!-- Using the icon component -->
<app-icon name="basic-home" size="sm" color="#007bff" ariaLabel="Home">
</app-icon>
```