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

# @flexzap/feedback

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

## Installation

```bash
npm install @flexzap/feedback
```

### 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, 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

```typescript
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.addNotification(notification);
  }

  showError() {
    const notification: ZapNotificationInterface = {
      id: `error-${Date.now()}`,
      message: 'An error occurred. Please try again.',
      severity: 'error',
      delay: 5
    };
    this.feedbackService.addNotification(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.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

```typescript
@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

```typescript
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

```typescript
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

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

## Styling

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

```scss
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

```bash
# 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

```typescript
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

```bash
# 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:

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

## Publishing

### Build for Publication

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

### Publish to NPM

```bash
cd dist/flexzap/feedback
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)
- 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](../../../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)