@flexzap/utilities

Essential utility services and helpers for Angular applications. Part of the FlexZap Library ecosystem.

Installation

npm install @flexzap/utilities

Peer Dependencies

This library requires the following peer dependencies:

npm install @angular/common@^21.1.0 @angular/core@^21.1.0 @angular/platform-browser@^21.1.0

Usage

ZapNavigation

The ZapNavigation service provides safe, platform-agnostic navigation methods.

import { Component, inject } from '@angular/core';
import { ZapNavigation } from '@flexzap/utilities';

@Component({
  template: `
    <button (click)="goToExternal()">Go to Google</button>
    <button (click)="sendEmail()">Contact Us</button>
    <button (click)="callSupport()">Call Support</button>
  `
})
export class MyComponent {
  private navigation = inject(ZapNavigation);

  goToExternal() {
    // Safely navigates to URL (sanitized and browser-check included)
    this.navigation.goToUrl('https://google.com', '_blank');
  }

  sendEmail() {
    this.navigation.mailTo('[email protected]', 'Help', 'I need assistance');
  }

  callSupport() {
    this.navigation.callTo('+1234567890');
  }
}

API Reference

ZapNavigation Service

Service for handling navigation and URL opening in a safe, platform-agnostic way.

Methods

| Method | Parameters | Description | | -------------- | -------------------------------------------------------------------- | -------------------------------------------------------------- | | goToUrl | url: string, target?: '_self' \| '_blank' \| '_parent' \| '_top' | Navigates to the specified URL. Default target is _self. | | mailTo | email: string, subject?: string, body?: string | Opens the default email client with optional subject and body. | | callTo | tel: string | Initiates a phone call to the specified number. | | smsTo | tel: string | Initiates an SMS to the specified number. | | linkTo | id: string | Smoothly scrolls to the element with the specified ID. | | downloadFile | url: string, filename?: string | Downloads a file from the specified URL. |

Features

• Platform Agnostic: Safe to call in SSR environments (checks PLATFORM_ID).
• Security: Automatically sanitizes URLs to prevent XSS.
• SSR Safe: Prevents window access on the server.

Testing

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

Running Tests

# From the monorepo root
npm run utilities:test            # Run all unit tests with coverage
npm run utilities: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/utilities/

Development

Building the Library

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

Publishing

Build for Publication

# From the monorepo root
npm run utilities:build

Publish to NPM

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

Contributing

This library is part of the FlexZap Library monorepo. Please refer to the main repository for contribution guidelines.

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