npm package: @ruc-lib/metered-progress-bar
Description: A customizable Angular progress bar component that displays progress with various styling options and categories. It supports different visual styles like solid, stripes, circles, and rectangles, and can be oriented horizontally or vertically.
Latest version: 4.0.0

# Metered Progress Bar

A customizable Angular progress bar component that displays progress with various styling options and categories. It supports different visual styles like solid, stripes, circles, and rectangles, and can be oriented horizontally or vertically.

## Installation Guide

To use the Metered Progress Bar component, you can install the entire RUC library or just this specific component.

### Install the Entire Library
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the MeteredProgressBar component:

**For Angular 15:**
```bash
npm install @ruc-lib/metered-progress-bar@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/metered-progress-bar@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/metered-progress-bar@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/metered-progress-bar@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/metered-progress-bar@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/metered-progress-bar@4.0.0
```

> **Note:** When installing in Angular 15-19 apps, you must specify the matching `@angular/material` and `@angular/cdk` versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

### 📦 Version Compatibility

| Angular Version    | Compatible `@ruc-lib/metered-progress-bar` Version     |
|--------------------|--------------------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/metered-progress-bar@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/metered-progress-bar@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/metered-progress-bar@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/metered-progress-bar@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/metered-progress-bar@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/metered-progress-bar@^4.0.0`     |

## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibMeteredProgressBarComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibMeteredProgressBarComponent } from '@uxpractice/ruc-lib/metered-progress-bar';

// For Individual Package
import { RuclibMeteredProgressBarComponent } from '@ruc-lib/metered-progress-bar';

@Component({
  selector: 'app-root',
  imports: [RuclibMeteredProgressBarComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-metered-progress-bar>` selector and pass the configuration object to the `rucInputData` input.

```html
<uxp-ruclib-metered-progress-bar [rucInputData]="meteredBarConfig"></uxp-ruclib-metered-progress-bar>
```

## API Reference

### Component Inputs

| Input          | Type               | Description                                  |
|----------------|--------------------|----------------------------------------------|
| `rucInputData` | `MeteredBarConfig` | The main configuration object for the component. |
| `customTheme`  | `string`           | An optional CSS class for custom theming.    |


### `MeteredBarConfig`
This is the main configuration object for the progress bar.

| Property                    | Type                                             | Description                                                                                             |
|-----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| `min`                       | `number`                                         | The minimum value of the progress bar (e.g., 0).                                                        |
| `max`                       | `number`                                         | The maximum value of the progress bar (e.g., 100).                                                      |
| `orientation`               | `'horizontal' \| 'vertical'`                     | The orientation of the progress bar.                                                                    |
| `barLabels`                 | `boolean`                                        | If `true`, displays percentage labels on the bar.                                                       |
| `barStyle`                  | `'solid' \| 'stripe' \| 'circle' \| 'rectangle'` | The visual style of the progress bar segments. Defaults to `solid`.                                     |
| `categoryLabelsOrientation` | `'top' \| 'bottom' \| 'left' \| 'right'`         | The orientation of category labels relative to the bar.                                                 |
| `categoryLabelStyle`        | `'basic' \| 'widget'`                            | The display style for category labels.                                                                  |
| `showCategoryLabels`        | `boolean`                                        | If `true`, displays the category labels.                                                                |
| `categories`                | `CategoryConfig[]`                               | An array of category configurations that make up the progress bar.                                      |
| `unitType`                  | `string`                                         | An optional unit to display next to the value (e.g., 'MB', 'GB', '%').                                  |

### `CategoryConfig`
This object defines the configuration for each segment within the progress bar.

| Property  | Type                               | Description                                                              |
|-----------|------------------------------------|--------------------------------------------------------------------------|
| `label`   | `string`                           | The label for the category, displayed in the legend and on hover.        |
| `color`   | `string`                           | The color of the category segment (e.g., `'#34d399'`, `'rgb(251,191,36)'`). |
| `value`   | `number`                           | The value of the category.                                               |
| `icon`    | `string` (optional)                | The name of a Material Icon to display for the category. If empty, a colored dot is shown. |
| `handler` | `(event?: any) => void` (optional) | A function to handle events for the category (e.g., click).              |

## Example Configuration

Here's an example of how to configure the Metered Progress Bar in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { MeteredBarConfig } from '@uxpractice/ruc-lib/metered-progress-bar';

// For Individual Package
import { MeteredBarConfig } from '@ruc-lib/metered-progress-bar';


@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  meteredBarConfig: MeteredBarConfig = {
    min: 0,
    max: 150,
    orientation: 'horizontal',
    barLabels: true,
    barStyle: 'stripe',
    categoryLabelsOrientation: 'bottom',
    categoryLabelStyle: 'widget',
    showCategoryLabels: true,
    categories: [
      { label: 'Applications', color: '#34d399', value: 95, icon: 'apps' },
      { label: 'Messages', color: '#fbbf24', value: 15, icon: 'message' },
      { label: 'Media', color: '#60a5fa', value: 21, icon: 'perm_media' },
      { label: 'Photos', color: '#6055ea', value: 12, icon: 'collections' }
    ],
    unitType: 'MB'
  };
}
```

> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**

When implementing **custom themes**, such as:

```scss
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}
```


## Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

## Acknowledgements

Thank you for choosing the Metered Progress Bar component. If you have any feedback or suggestions, please let us know!