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

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Metered Progress Bar component:

npm install @ruc-lib/metered-progress-bar

Version Compatibility

Please ensure you install the correct version of @ruc-lib/metered-progress-bar based on your Angular version.

| Angular Version | Compatible @ruc-lib/metered-progress-bar Version | |--------------------|--------------------------------------------------------| | 15.x.x | npm install @ruc-lib/metered-progress-bar@^3.0.0 | | 16.x.x | npm install @ruc-lib/metered-progress-bar@^3.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibMeteredProgressBarComponent:

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.

<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.

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:

.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!