npm package: @flexzap/symbols
Description: All the symbols components that makes part of the flexzap library
Author: flexzap
Latest version: 1.6.0

# @flexzap/symbols

Comprehensive SVG symbol management system for Angular applications, featuring an extensive icon library and flexible symbol rendering components. Part of the FlexZap Library ecosystem.

## Installation

```bash
npm install @flexzap/symbols
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install @angular/common@^21.1.0 @angular/core@^21.1.0
```

## Usage

### Basic Setup

```typescript
import { Component } from '@angular/core';
import { ZapSvg, ZapSvgConfig } from '@flexzap/symbols';

@Component({
  imports: [ZapSvg],
  template: `
    <zap-svg name="home" [config]="iconConfig" />
    <zap-svg name="settings" [config]="animatedConfig" />
  `
})
export class MyComponent {
  iconConfig = ZapSvgConfig.createIcon();
  animatedConfig = ZapSvgConfig.createIconAnimated();
}
```

### Advanced Usage with Custom Configuration

```typescript
import { Component } from '@angular/core';
import { ZapSvg, ZapSvgConfig, ZapSvgInterface } from '@flexzap/symbols';

@Component({
  imports: [ZapSvg],
  template: `
    <div class="toolbar">
      <zap-svg name="menu" [config]="menuConfig" />
      <zap-svg name="search" [config]="searchConfig" />
      <zap-svg name="refresh" [config]="loadingConfig" />
    </div>

    <div class="navigation">
      <zap-svg name="arrow-back" [config]="iconConfig" />
      <zap-svg name="home" [config]="iconConfig" />
      <zap-svg name="arrow-forward" [config]="iconConfig" />
    </div>
  `
})
export class SymbolComponent {
  iconConfig = ZapSvgConfig.createIcon();
  menuConfig = ZapSvgConfig.createIcon();
  searchConfig = ZapSvgConfig.createIcon();

  // Custom animated configuration
  loadingConfig: ZapSvgInterface = {
    type: 'icons',
    animate: {
      active: true,
      duration: 2 // 2 seconds rotation
    }
  };
}
```

## API Reference

### ZapSvg Component

Smart SVG symbol component that renders icons from the FlexZap symbol library with optional animation support.

#### Properties

| Property | Type              | Default               | Description                                                     |
| -------- | ----------------- | --------------------- | --------------------------------------------------------------- |
| `name`   | `string`          | `''`                  | The icon name to display (must match a symbol ID in the sprite) |
| `config` | `ZapSvgInterface` | `ZapSvgConfig.init()` | Configuration object for the symbol behavior                    |

#### Features

- **SVG Sprite Integration**: Automatically references symbols from the included sprite file
- **Animation Support**: Built-in CSS animation capabilities with configurable duration
- **OnPush Change Detection**: Optimized performance with reactive updates
- **Type Safety**: Full TypeScript support with interface validation

#### Template Integration

```typescript
@Component({
  template: `
    <zap-svg name="settings" [config]="config" />
  `
})
```

### ZapSvgConfig Service

Utility class for creating and managing SVG configuration objects with predefined patterns.

#### Static Methods

| Method                 | Parameters                | Returns           | Description                            |
| ---------------------- | ------------------------- | ----------------- | -------------------------------------- |
| `create()`             | `config: ZapSvgInterface` | `ZapSvgInterface` | Creates a custom configuration object  |
| `init()`               | -                         | `ZapSvgInterface` | Creates an empty/default configuration |
| `createIcon()`         | -                         | `ZapSvgInterface` | Creates a standard icon configuration  |
| `createIconAnimated()` | -                         | `ZapSvgInterface` | Creates an animated icon configuration |

#### Usage Examples

```typescript
// Basic icon
const basicIcon = ZapSvgConfig.createIcon();

// Animated icon with default settings
const animatedIcon = ZapSvgConfig.createIconAnimated();

// Custom configuration
const customIcon = ZapSvgConfig.create({
  type: 'icons',
  animate: {
    active: true,
    duration: 3
  }
});
```

### Type Definitions

#### ZapSvgInterface

```typescript
interface ZapSvgInterface {
  type: string; // Symbol type (typically 'icons')
  animate?: {
    active: boolean; // Whether animation is enabled
    duration?: number; // Animation duration in seconds
  };
}
```

## Available Icons

The library includes an extensive collection of icons in the following categories:

### Navigation & UI

- `home`, `menu`, `search`, `settings`
- `arrow-back`, `arrow-forward`, `arrow-upward`, `arrow-downward`
- `chevron-left`, `chevron-right`
- `expand-more`, `expand-less`, `compress-more`, `compress-less`, `unfold-more`, `unfold-less`
- `more-vertical`, `more-horizontal`
- `panel-left-close`, `panel-left-open`, `panel-right-close`, `panel-right-open`
- `panel-top-close`, `panel-top-open`
- `app`, `dashboard`, `dashboard-wide`, `view-kanban`
- `login`, `logout`

### Actions & Controls

- `add`, `edit`, `circle-edit`, `delete`, `delete-auto`, `delete-forever`, `delete-restore`, `done`, `remove`
- `close`, `circle-cancel`
- `refresh`, `sync`, `rotate-left`, `rotate-right`
- `content-copy`, `favorite`, `download`, `archive`, `unarchive`
- `cloud-done`, `cloud-download`, `cloud-lock`, `cloud-off`, `cloud-upload`
- `target`, `mop`, `license`
- `filter-list`, `filter-list-off`
- `visibility`, `visibility-lock`, `visibility-off`
- `zoom-in`, `zoom-out`
- `colorize`, `palette`

### Status & Feedback

- `circle-check`, `circle-add`, `circle-remove`, `circle-error`
- `circle-arrow-up`, `circle-arrow-down`, `circle-arrow-left`, `circle-arrow-right`
- `circle-account`, `circle-account-off`, `circle-block`
- `warning`, `been-here`
- `radio-checked`, `radio-unchecked`
- `checkbox-checked`, `checkbox-unchecked`

### Mood & Expression

- `mood-happy`, `mood-satisfied`, `mood-normal`, `mood-sad`, `mood-add`

### Business & Productivity

- `business-center`, `work`, `work-alert`, `work-history`, `work-update`
- `assignment`, `assignment-add`, `assignment-globe`, `task`, `receipt`, `docs`
- `card-add`, `card-credit`, `card-score`
- `inventory`, `inventory-box`, `package`
- `order-approve`, `order-inactive`, `order-play`

### Time & Date

- `alarm`, `alarm-add`, `alarm-off`, `alarm-on`, `alarm-pause`, `alarm-smart-wake`
- `timer-avg`, `timer-pause`, `timer-play`
- `calendar-check`, `calendar-clock`, `calendar-lock`, `calendar-month`, `calendar-today`

### Media & Notifications

- `circle-play`, `circle-pause`, `circle-stop`
- `notifications`, `notifications-active`, `notifications-off`, `notifications-paused`, `notifications-unread`
- `circle-notifications`

### Communication

- `mail`, `mail-asterisk`, `mail-attach`, `mail-draft`, `mail-lock`, `mail-off`, `mail-read`, `mail-shield`, `mail-unread`, `mail-unsubscribe`, `mail-forward`
- `send`, `send-and-archive`, `send-schedule`, `send-schedule-cancel`
- `mobile`

### Utility & System

- `mode-light`, `mode-dark`
- `balance-wallet`
- `rocket`, `bolt`
- `password`, `password-off`
- `counter-0` through `counter-9`

### Usage Example with Icon Names

```typescript
@Component({
  template: `
    <!-- Navigation icons -->
    <zap-svg name="home" [config]="iconConfig" />
    <zap-svg name="menu" [config]="iconConfig" />

    <!-- Action icons -->
    <zap-svg name="add" [config]="iconConfig" />
    <zap-svg name="edit" [config]="iconConfig" />

    <!-- Status icons -->
    <zap-svg name="circle-check" [config]="iconConfig" />
    <zap-svg name="done" [config]="iconConfig" />

    <!-- Animated loading -->
    <zap-svg name="refresh" [config]="animatedConfig" />
  `
})
```

## Styling

The components use SCSS for styling. Customize the appearance by overriding CSS custom properties:

```scss
zap-svg {
  // Custom symbol styles
  --zap-svg-size: 24px;
  --zap-svg-color: currentColor;

  svg {
    width: var(--zap-svg-size);
    height: var(--zap-svg-size);
    fill: var(--zap-svg-color);
  }
}
```

## Testing

This library uses Jest for unit testing with zoneless Angular configuration.

### Running Tests

```bash
# From the monorepo root
npm run symbols:test           # Run all unit tests with coverage
npm run symbols:test:watch     # Run tests in watch mode (no coverage)
```

### Test Configuration

- **Framework**: Jest with jest-preset-angular
- **Environment**: jsdom
- **Configuration**: Zoneless Angular (mandatory)
- **Coverage**: Reports generated at `coverage/flexzap/symbols/`

### Testing with ZapSvg

```typescript
import { TestBed } from '@angular/core/testing';
import { provideZonelessChangeDetection } from '@angular/core';
import { ZapSvg, ZapSvgConfig } from '@flexzap/symbols';

describe('ZapSvg Component', () => {
  let component: ZapSvg;
  let fixture: ComponentFixture<ZapSvg>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [ZapSvg],
      providers: [provideZonelessChangeDetection()]
    }).compileComponents();

    fixture = TestBed.createComponent(ZapSvg);
    component = fixture.componentInstance;
  });

  it('should render icon with correct href', () => {
    component.name = 'home';
    component.config = ZapSvgConfig.createIcon();
    component.ngOnChanges();

    expect(component.href).toContain('home');
    expect(component.href).toContain('icons.sprite.svg');
  });
});
```

## Asset Management

The library includes automated asset management through Node.js scripts:

### Configuration Scripts

- **`assets-config.js`**: Automatically configures Angular projects to include symbol assets with duplicate prevention

### Post-Install Process

When you install `@flexzap/symbols`, the post-install script automatically:

1. Updates your `angular.json` file to include symbol assets
2. Configures both build and test environments
3. Ensures proper asset paths for the SVG sprite files
4. Checks if assets already exist before adding them again

## Development

### Building the Library

```bash
# From the monorepo root
npm run symbols:build      # Build directly
ng build @flexzap/symbols  # Build using Angular CLI
```

### Code Scaffolding

To generate new components within this library:

```bash
ng generate component [component-name] --project @flexzap/symbols
```

## Publishing

### Build for Publication

```bash
# From the monorepo root
npm run symbols:build
```

### Publish to NPM

```bash
cd dist/flexzap/symbols
npm publish --access public
```

## Contributing

This library is part of the FlexZap Library monorepo. Please refer to the [main repository](../../../README.md) for contribution guidelines.

### Development Guidelines

- Use standalone components (default behavior)
- Follow the existing symbol naming conventions
- Use `input()` and `output()` functions instead of decorators
- Set `changeDetection: ChangeDetectionStrategy.OnPush`
- Write comprehensive tests with Jest (zoneless configuration)
- Follow semantic versioning for releases

### Adding New Icons

To add new icons to the library:

1. Add SVG symbols to `assets/icons.sprite.svg`
2. Follow the existing naming conventions (kebab-case)
3. Ensure all paths use consistent viewBox dimensions (40x40)
4. Update tests to include new icon names
5. Add documentation for new icon categories

## License

MIT License - see the [LICENSE](../../../LICENSE) file for details.

## Links

- **Homepage**: [https://www.flexzap.dev](https://www.flexzap.dev)
- **Repository**: [https://github.com/vitorazevedo/flexzap-library](https://github.com/vitorazevedo/flexzap-library)
- **Monorepo Documentation**: [Main README](../../../README.md)