@flexzap/misc/README.md

All the miscellaneous components that makes part of the flexzap library

# @flexzap/misc

Miscellaneous utility components for Angular applications, including spinners, progress bars, and other common UI elements. Part of the FlexZap Library ecosystem.

## Installation

```bash
npm install @flexzap/misc
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install @angular/common@^20.3.0 @angular/core@^20.3.0 @flexzap/pipes@^0.0.1
```

## Usage

### Basic Implementation

```typescript
import { Component } from '@angular/core';
import { ZapSpinner, ZapProgressBar } from '@flexzap/misc';

@Component({
  standalone: true,
  imports: [ZapSpinner, ZapProgressBar],
  template: `
    <!-- Simple spinner -->
    <zap-spinner />
    
    <!-- Progress bar with percentage -->
    <zap-progress-bar 
      [value]="currentValue" 
      [min]="0" 
      [max]="100"
      [format]="{ symbol: '%' }" />
      
    <!-- Custom range progress bar -->
    <zap-progress-bar 
      [value]="progress" 
      [min]="10" 
      [max]="50" />
  `
})
export class MyComponent {
  currentValue = 75;
  progress = 30;
}
```

## API Reference

### ZapSpinner Component

A simple loading spinner component with customizable styling.

#### Features

- **OnPush Change Detection**: Optimized performance with OnPush strategy
- **SCSS Styling**: Customizable styles with SCSS support
- **Lightweight**: No inputs or outputs, pure visual component
- **Standalone Component**: No module imports required

### ZapProgressBar Component

An animated progress bar component with customizable range and formatting.

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `value` | `number` | `0` | Current progress value |
| `min` | `number` | `0` | Minimum value for the progress range |
| `max` | `number` | `100` | Maximum value for the progress range |
| `format` | `Partial<ZapNumericInterface>` | `{}` | Formatting options for the displayed value (uses @flexzap/pipes) |

#### Features

- **OnPush Change Detection**: Optimized performance with OnPush strategy
- **Animated Transitions**: Smooth CSS transitions with 100ms delay
- **Flexible Range**: Supports custom min/max values
- **Number Formatting**: Integration with @flexzap/pipes for value display
- **Percentage Calculation**: Automatic percentage calculation based on range
- **Standalone Component**: No module imports required

### Styling

Both components use SCSS for styling. You can customize the appearance by overriding the default styles:

```scss
zap-spinner {
  // Custom spinner styles
  --zap-spinner-color: #007bff;
  --zap-spinner-size: 2rem;
}

zap-progress-bar {
  // Custom progress bar styles
  --zap-progress-bar-height: 8px;
  --zap-progress-bar-bg: #e9ecef;
  --zap-progress-bar-fill: #007bff;
  --zap-progress-bar-border-radius: 4px;
}
```

## Testing

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

### Running Tests

```bash
# From the monorepo root
npm run misc:test            # Run all unit tests once
npm run misc:test:watch      # Run tests in watch mode
npm run misc:test:coverage   # Generate a test coverage report
```

### Test Configuration

- **Framework**: Jest with jest-preset-angular
- **Environment**: jsdom
- **Configuration**: Zoneless Angular (mandatory)
- **Coverage**: Reports generated at `../../../coverage/flexzap/misc/`

## Development

### Building the Library

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

### Code Scaffolding

To generate new components within this library:

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

## Publishing

### Build for Publication

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

### Publish to NPM

```bash
cd dist/flexzap/misc
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`
- 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)