@flexzap/feedback

Comprehensive feedback management system for Angular applications, including notifications, alerts, and user feedback components. Part of the FlexZap Library ecosystem.

Installation

npm install @flexzap/feedback

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, inject } from '@angular/core';
import { ZapNotification, ZapFeedbackManagement } from '@flexzap/feedback';

@Component({
  imports: [ZapNotification],
  template: `
    <button (click)="showNotification()">Show Notification</button>
    <zap-notification />
  `
})
export class MyComponent {
  private feedbackService = inject(ZapFeedbackManagement);
  
  showNotification() {
    this.feedbackService.addNotification({
      id: 'unique-id',
      message: 'Hello from FlexZap!',
      delay: 3
    });
  }
}

Advanced Usage with Custom Configuration

import { Component, inject } from '@angular/core';
import { ZapNotification, ZapFeedbackManagement } from '@flexzap/feedback';
import type { ZapNotificationInterface } from '@flexzap/feedback';

@Component({
  imports: [ZapNotification],
  template: `
    <div class="actions">
      <button (click)="showSuccess()">Success</button>
      <button (click)="showError()">Error</button>
      <button (click)="showPersistent()">Persistent</button>
    </div>
    <zap-notification />
  `
})
export class FeedbackComponent {
  private feedbackService = inject(ZapFeedbackManagement);
  
  showSuccess() {
    const notification: ZapNotificationInterface = {
      id: `success-${Date.now()}`,
      message: 'Operation completed successfully!',
      type: 'success',
      delay: 3
    };
    this.feedbackService.addNotification(notification);
  }
  
  showError() {
    const notification: ZapNotificationInterface = {
      id: `error-${Date.now()}`,
      message: 'An error occurred. Please try again.',
      type: 'error',
      delay: 5
    };
    this.feedbackService.addNotification(notification);
  }
  
  showPersistent() {
    const notification: ZapNotificationInterface = {
      id: `persistent-${Date.now()}`,
      message: 'This notification stays until manually dismissed.',
      type: 'info',
      delay: 0 // No auto-dismiss
    };
    this.feedbackService.addNotification(notification);
  }
}

API Reference

ZapNotification Component

Smart notification display component that automatically shows/hides based on the notification pool.

Features

• Automatic Visibility: Shows when notifications exist, hides when empty
• Reactive Integration: Automatically updates with ZapFeedbackManagement service
• Responsive Display: Handles multiple notifications efficiently
• OnPush Change Detection: Optimized performance

Template Integration

@Component({
  template: `<zap-notification />`
})

ZapFeedbackManagement Service

Injectable service for managing feedback with signal-based reactive state management.

Methods

| Method | Parameters | Description | |--------|------------|-------------| | addNotification() | notification: ZapNotificationInterface | Adds a notification to the pool | | addAlert() | alert: ZapAlertInterface | Adds an alert to the pool | | clearNotifications() | - | Clears all notifications | | clearAlerts() | - | Clears all alerts |

Computed Properties

| Property | Type | Description | |----------|------|-------------| | pool | ZapFeedbackInterface | Complete feedback pool (notifications + alerts) | | notifications | ZapNotificationInterface[] | Array of current notifications | | alerts | ZapAlertInterface[] | Array of current alerts |

Features

• Signal-based State: Uses Angular signals for reactive state management
• Automatic Cleanup: Configurable auto-removal with delay timers
• Separate Pools: Independent management of notifications and alerts
• Memory Safe: Proper cleanup of timers and resources

Type Definitions

ZapNotificationInterface

interface ZapNotificationInterface {
  id: string;           // Unique identifier
  message: string;      // Notification text
  type?: string;        // Optional type (success, error, info, etc.)
  delay?: number;       // Auto-dismiss delay in seconds (0 = no auto-dismiss)
  data?: any;           // Optional additional data
}

ZapAlertInterface

interface ZapAlertInterface {
  id: string;           // Unique identifier
  message: string;      // Alert text
  type?: string;        // Optional type (warning, danger, etc.)
  delay?: number;       // Auto-dismiss delay in seconds
  actions?: any[];      // Optional action buttons
}

ZapFeedbackInterface

interface ZapFeedbackInterface {
  notifications: ZapNotificationInterface[];
  alerts: ZapAlertInterface[];
}

Styling

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

zap-notification {
  // Custom notification styles
  --zap-notification-bg: #f8f9fa;
  --zap-notification-color: #212529;
  --zap-notification-success-bg: #d4edda;
  --zap-notification-error-bg: #f8d7da;
}

Testing

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

Running Tests

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

Testing with ZapFeedbackManagement

import { TestBed } from '@angular/core/testing';
import { provideZonelessChangeDetection } from '@angular/core';
import { ZapFeedbackManagement } from '@flexzap/feedback';

describe('ZapFeedbackManagement', () => {
  let service: ZapFeedbackManagement;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [provideZonelessChangeDetection()]
    });
    service = TestBed.inject(ZapFeedbackManagement);
  });

  it('should add notification to pool', () => {
    const notification = {
      id: 'test',
      message: 'Test notification',
      delay: 1
    };
    
    service.addNotification(notification);
    expect(service.notifications().length).toBe(1);
  });
});

Development

Building the Library

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

Code Scaffolding

To generate new components within this library:

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

Publishing

Build for Publication

# From the monorepo root
npm run feedback:build

Publish to NPM

cd dist/flexzap/feedback
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)
• Use input() and output() functions instead of decorators
• Set changeDetection: ChangeDetectionStrategy.OnPush
• Use signals for reactive state management
• Write comprehensive tests with Jest (zoneless configuration)
• Follow semantic versioning for releases

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