npm package: @ruc-lib/knob
Description: A component for creating a custom knob with different shapes like arc, vertical slider & horizontal slider where user can adjust the value by sliding a handle on arc or by sliding a handle on vertical or horizonatl slider.
Latest version: 4.0.0

# ruclib-knob

A component for creating a custom knob with different shapes like arc, vertical slider & horizontal slider where user can adjust the value by sliding a handle on arc or by sliding a handle on vertical or horizonatl slider.

# Installation guide

To use the Knob 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 Knob component:

**For Angular 15:**
```bash
npm install @ruc-lib/knob@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/knob@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/knob@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/knob@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/knob@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/knob@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/knob` Version     |
|--------------------|----------------------------------------|
| 15.x.x             | `npm install @ruc-lib/knob@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/knob@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/knob@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/knob@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/knob@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/knob@^4.0.0`     |

## Usage
### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibKnobComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibKnobComponent } from '@uxpractice/ruc-lib/knob';

// For Individual Package
import { RuclibKnobComponent } from '@ruc-lib/knob';

@Component({
  selector: 'app-root',
  imports: [RuclibKnobComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-knob>` selector and pass the configuration object to the `rucInputData` input.

```html
<uxp-ruclib-knob 
  [rucInputData]="knobConfig" 
  [customTheme]="customTheme"
  (rucEvent)="passEvent($event)">
</uxp-ruclib-knob>
```

## API Reference

### Component Inputs
| Input          | Type               | Description                                       |
|----------------|--------------------|---------------------------------------------------|
| `rucInputData` | `knobConfig`       | The main configuration object for the knob.       |
| `customTheme`  | `string`           | An optional CSS class for custom theming.         |

### Component Outputs
| Output    | Type      | Description                                       |
|-----------|-----------|---------------------------------------------------|
| `rucEvent`| `any`     | Emits events related to knob actions.             |


### knobConfig

This is the main configuration object for the Knob component.
| Property              | Type                    | Description                                                                            |
|-----------------------|-------------------------|----------------------------------------------------------------------------------------|
| `min`                 | `number`                | Sets the minimum value of the knob.                                                    |
| `max`                 | `number`                | Sets the maximum value of the knob.                                                    |
| `step`                | `number`                | Sets the increment/decrement step for the knob's value.                                |
| `size`                | `number`                | Sets the overall size (width and height) of the knob in pixels.                        |
| `valueColor`          | `string`                | Sets the color of the displayed value text.                                            |
| `strokeBackground`    | `string`                | Sets the background color of the knob's track (the non-progress part).                 |
| `progressBackground`  | `string \| string[]`    | Sets the color of the progress indicator. Can be a single color or an array of colors. |
| `strokeWidth`         | `number`                | Sets the width of the knob's track and progress indicator.                             |
| `valueSize`           | `number`                | Sets the font size of the displayed value text.                                        |
| `valueWeight`         | `string`                | Sets the font weight of the displayed value text (e.g., 'normal', 'bold').             |
| `showHandle`          | `boolean`               | Toggles the visibility of the knob's handle.                                           |
| `handleBackground`    | `string`                | Sets the background color of the knob's handle.                                        |
| `handleBorderColor`   | `string`                | Sets the border color of the knob's handle.                                            |
| `handleBorderWidth`   | `number`                | Sets the border width of the knob's handle.                                            |
| `roundedCorner`       | `boolean`               | Applies rounded corners to the knob's track and progress.                              |
| `valuePrefix`         | `string`                | Text to display before the value.                                                      |
| `valueSuffix`         | `string`                | Text to display after the value.                                                       |
| `readOnly`            | `boolean`               | If true, the knob's value cannot be changed by user interaction.                       |
| `disabled`            | `boolean`               | If true, the knob is completely inactive and unchangeable.                             |
| `enableTooltip`       | `boolean`               | Toggles the visibility of a tooltip displaying the current value on hover/drag.        |
| `animateOnHover`      | `boolean`               | Enables a subtle animation effect when the user hovers over the knob.                  |
| `isRangeMode`         | `boolean`               | If true, the knob operates in a range selection mode with two handles.                 |
| `rangeStartValue`     | `number`                | Sets the starting value for the range when `isRangeMode` is true.                      |
| `rangeEndValue`       | `number`                | Sets the ending value for the range when `isRangeMode` is true.                        |
| `showButtons`         | `boolean`               | Toggles the visibility of increment and decrement buttons.                             |

## Example Configuration

Here's an example of how to configure the Knob component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { KnobConfig } from '@uxpractice/ruc-lib/knob';

// For Individual package
import { KnobConfig } from '@ruclib/knob';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  knobConfig: KnobConfig = {
    min: 0,
    max: 100,
    step: 1,
    size: 200,
    strokeWidth: 20,
    valueWeight: 'bold',
    showHandle: true,
    handleBackground: '#fff',
    handleBorderColor: '#007bff',
    handleBorderWidth: 2,
    roundedCorner: true,
    valuePrefix: '$',
    valueSuffix: '',
    readOnly: false,
    disabled: false,
    enableTooltip: true,
    animateOnHover: true,
    isRangeMode: false,
    rangeStartValue: 0,
    rangeEndValue:100,
    showButtons: true,
  };

  passEvent(event: any) {
    console.log('Knob Event:', event);
  }
}
```

> ⚠️ **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 Knob component. If you have any feedback or suggestions, please let us know!