@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.2.10 @angular/core@^21.2.10

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.addFeedback('notifications', {
      id: 'unique-id',
      message: 'Hello from FlexZap!',
      severity: 'info',
      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!',
      severity: 'success',
      delay: 3
    };
    this.feedbackService.addFeedback('notifications', notification);
  }

  showError() {
    const notification: ZapNotificationInterface = {
      id: `error-${Date.now()}`,
      message: 'An error occurred. Please try again.',
      severity: 'error',
      delay: 5
    };
    this.feedbackService.addFeedback('notifications', notification);
  }

  showPersistent() {
    const notification: ZapNotificationInterface = {
      id: `persistent-${Date.now()}`,
      message: 'This notification stays until manually dismissed.',
      severity: 'info',
      delay: 0 // No auto-dismiss
    };
    this.feedbackService.addFeedback('notifications', 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 | | --------------- | ---------------------------------------------------------------- | -------------------------------------------------------- | | addFeedback() | type: 'notifications' \| 'alerts', feedback: ZapFeedbackType | Adds a feedback item (notification or alert) to the pool |

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 {
  severity: string; // Severity of the notification (success, error, info, etc.)
  message: string; // Notification text
  id?: string; // Unique identifier
  delay: number; // Auto-dismiss delay in seconds (0 = no auto-dismiss)
}

ZapAlertInterface

interface ZapAlertInterface {
  severity: string; // Severity of the alert (warning, danger, etc.)
  message: string; // Alert text
  id?: string; // Unique identifier
  delay: number; // Auto-dismiss delay in seconds
}

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',
      severity: 'info',
      delay: 1
    };

    service.addFeedback('notifications', notification);
    expect(service.notifications().length).toBe(1);
  });
});

Development

Building the Library

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

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