@ruc-lib/knob 2.0.0 → 3.1.0

package/README.md

@@ -2,107 +2,181 @@
 
 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.
 
-# Features
-
-- User is allowed to add the knob of their choise from any of these: Arc, Vertical or Horizontal slider.
-- User is allowed to adjust the width (stroke) of the arc or slider line.
-- User is allowed to set size, color and width of the knob.
-- User is allowed to set the font-size, weight and color of value text.
-- User is allowed to set min and max value of range.
-- User is allowed to custom text before and after the value.
-- User is allowed to toggle the visibility of custom buttons to increment and decrement the value.
-- User is allowed to toggle the readonly and disabled mode.
-- User is allowed to toggle the visibility of tooltip.
-- User is allowed to adjust the value by using arrow keys of keyboard.
-- User is allowed to do some actions on these events onBlur, onFocus, onChange, onDragStart & onDragEnd.
-
-
 # Installation guide
 
-# Install complete library
-
-`npm install @uxpractice/ruc-lib`
+To use the Knob component, you can install the entire RUC library or just this specific component.
 
-# Install individual component
+### Install the Entire Library
+```bash
+npm install @uxpractice/ruc-lib
+```
 
-If users only need the knob component, they can install it separately
-`npm install @ruc-lib/knob`
+### Install Individual Component
 
-# Usage
+If you only need the Knob component
+```bash
+npm install @ruc-lib/knob
+```
 
-here path of the scss file is subject to change as per choice of the installation
 
-for library
-`@import "../node_modules/@ruc-lib/knob/lib/knob.scss";`
+# Version Compatibility
+
+Please ensure you install the correct version of `@ruc-lib/knob` based on your Angular version.
+ 
+| Angular Version    | Compatible `@ruc-lib/knob` Version     |
+|--------------------|------------------------------------------------------|
+| 15.x.x             | `npm install @ruc-lib/knob@^3.0.0`     |
+| 16.x.x             | `npm install @ruc-lib/knob@^3.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
+}
+```
 
-for seperate package
-`@import "../node_modules/@uxpractice/ruc-lib/knob/lib/knob.scss";`
+### 2. Use the Component
+In your component's template, use the `<uxp-ruclib-knob>` selector and pass the configuration object to the `rucInputData` input.
 
-# import required modules
+```html
+<uxp-ruclib-knob 
+  [rucInputData]="knobConfig" 
+  [customTheme]="customTheme"
+  (rucEvent)="passEvent($event)">
+</uxp-ruclib-knob>
+```
 
-for library
-`import { RuclibKnobModule } from '@uxpractice/ruc-lib/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,
+  };
 
-for seperate package
-`import { RuclibKnobModule } from '@ruc-lib/knob';`
+  passEvent(event: any) {
+    console.log('Knob Event:', event);
+  }
+}
+```
 
-# use component selector
+> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**
 
-```
-<uxp-ruclib-knob [rucInputData]="knobConfig" [customTheme]="customTheme"
-  (rucEvent)="passEvent($event)"></uxp-ruclib-knob>
-```
+When implementing **custom themes**, such as:
 
+```scss
+.custom-theme-1 {
+  @include angular-material-theme($custom-theme);
+}
 
-# Input and Output
-
-# Inputs
-rucInputData -> It is the configuration input to configure the knob
-
-customTheme -> It is the name of the theme.
-
-# Output
-
-rucEvent -> is the event which will be fired when any change is made in knob component
-
-# rucInputData (sample object)
-
-# Detail definition of the each property can be found in type definition file.
-
- ```
-knobConfig = {
-    min:<number> 0,
-    max:<number> 100,
-    step:<number> 1,
-    size:<number> 150,
-    valueColor:<string> '',
-    strokeBackground:<string> 'lightblue',
-    progressBackground: <string | string[]> 'blue', // 'green' |  ['green'] | ['red', 'blue', 'green', 'black', 'orange'],
-    strokeWidth:<number> 15,
-    valueSize:<number> 20,
-    valueWeight:<string> 'normal',
-    showHandle:<boolean> true,
-    handleBackground:<string> 'lightblue',
-    handleBorderColor:<string> 'blue',
-    handleBorderWidth:<number> 4,
-    roundedCorner:<boolean> true,
-    valuePrefix:<string> '',
-    valueSuffix:<string> '',
-    readOnly:<boolean> false,
-    disabled:<boolean> false,
-    enableTooltip:<boolean> false,
-    animateOnHover:<boolean> false,
-    isRangeMode:<boolean> false,
-    rangeStartValue:<number> 25,
-    rangeEndValue:<number> 75,
-    showButtons:<boolean> false,
-    knobType:<'horizontal' | 'vertical' | 'arc'> 'arc' // 'horizontal' | 'vertical' | 'arc'
-  };
+// 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
+## 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 Library. If you have any feedback or suggestions, please let us know!
+## Acknowledgements
+
+Thank you for choosing the Knob component. If you have any feedback or suggestions, please let us know!