@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

npm install @flexzap/symbols

Peer Dependencies

This library requires the following peer dependencies:

npm install @angular/common@^21.0.0 @angular/core@^21.0.0

Usage

Basic Setup

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

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

@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

// 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

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

@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:

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

# 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

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

# From the monorepo root
npm run symbols:build      # Build with version bump
ng build @flexzap/symbols  # Build directly

Code Scaffolding

To generate new components within this library:

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

Publishing

Build for Publication

# From the monorepo root
npm run symbols:build

Publish to NPM

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

Contributing

This library is part of the FlexZap Library monorepo. Please refer to the main repository 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 file for details.

Links

• Homepage: https://www.flexzap.dev
• Repository: https://github.com/vitorazevedo/flexzap-library
• Monorepo Documentation: Main README