cats-ui-lib 2.0.4 → 2.0.5

package/README.md

@@ -1,63 +1,799 @@
-# CatsUi
+# cats-ui-lib
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 19.2.0.
+A comprehensive Angular UI component library built with Angular 19, providing a rich set of reusable, customizable components for modern web applications.
 
-## Code scaffolding
+[![npm version](https://img.shields.io/npm/v/cats-ui-lib.svg)](https://www.npmjs.com/package/cats-ui-lib)
+[![Angular](https://img.shields.io/badge/Angular-19-red.svg)](https://angular.dev)
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+---
+
+## 📦 Installation
 
 ```bash
-ng generate component component-name
+npm install cats-ui-lib
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+---
 
-```bash
-ng generate --help
+## ⚙️ Setup
+
+### 1. Configure `angular.json`
+
+Add the following inside the `build > options` section of your `angular.json`:
+
+```json
+"assets": [
+  {
+    "glob": "**/*",
+    "input": "node_modules/cats-ui/assets"
+  }
+],
+"styles": [
+  "node_modules/cats-ui-lib/styles/_index.scss"
+]
 ```
 
-## Building
+### 2. Import the Module
 
-To build the library, run:
+```typescript
+import { CatsUiModule } from 'cats-ui-lib';
 
-```bash
-ng build cats-ui
+@NgModule({
+  imports: [CatsUiModule],
+})
+export class AppModule {}
+```
+
+---
+
+## 🧩 Components
+
+---
+
+### `InputComponent` — `<cats-ui-input>`
+
+Supports types: `text` · `number` · `email` · `password`
+
+**Template:**
+```html
+<cats-ui-input
+  [inputConfig]="inputConfig"
+  [(ngModel)]="name"
+  required>
+</cats-ui-input>
+
+<!-- Disabled state -->
+<cats-ui-input
+  [disabled]="true"
+  [inputConfig]="inputConfig"
+  [(ngModel)]="name">
+</cats-ui-input>
+```
+
+**TypeScript:**
+```typescript
+import { InputConfig } from 'cats-ui-lib';
+
+inputConfig: InputConfig = {
+  type: 'text',
+  placeholder: 'Enter value',
+};
+```
+
+**`InputConfig` options:**
+
+| Property      | Type     | Description                                      |
+|---------------|----------|--------------------------------------------------|
+| `type`        | `string` | Input type: `text`, `email`, `password`, `number`|
+| `placeholder` | `string` | Placeholder text                                 |
+
+---
+
+### `SingleSelectComponent` — `<cats-ui-single-select>`
+
+**Template:**
+```html
+<cats-ui-single-select
+  [optionList]="options"
+  [singleSelectConfig]="singleConfig"
+  [parentNativeElement]="'parent'"
+  (onSelection)="onSelection($event)">
+</cats-ui-single-select>
+```
+
+**TypeScript:**
+```typescript
+import { SingleSelectConfig } from 'cats-ui-lib';
+
+options = [
+  { id: 1, name: 'Option 1', disable: false },
+  { id: 2, name: 'Option 2', disable: false },
+];
+
+singleConfig: SingleSelectConfig = {
+  idField: 'id',
+  textField: 'name',
+  disabledField: 'disable',
+  placeholder: 'Select Option',
+};
+
+onSelection(dt: any) {
+  console.log('Selected:', dt);
+}
+```
+
+**`SingleSelectConfig` options:**
+
+| Property        | Type     | Description                        |
+|-----------------|----------|------------------------------------|
+| `idField`       | `string` | Key for option ID                  |
+| `textField`     | `string` | Key for display label              |
+| `disabledField` | `string` | Key to mark option as disabled     |
+| `placeholder`   | `string` | Placeholder text                   |
+
+---
+
+### `MultiSelectComponent` — `<cats-ui-multi-select>`
+
+**Template:**
+```html
+<cats-ui-multi-select
+  [optionList]="options"
+  [multiSelectConfig]="multiSelectConfig"
+  (onSelection)="onSelection($event)">
+</cats-ui-multi-select>
+```
+
+**TypeScript:**
+```typescript
+import { MultiSelectConfig } from 'cats-ui-lib';
+
+multiSelectConfig: MultiSelectConfig = {
+  idField: 'id',
+  textField: 'name',
+  disabledField: 'disable',
+  placeholder: 'Select Option',
+  prefixLabel: '',
+  enableSearch: true,
+  chipLimit: 2,
+  selectAll: true,
+  required: false,
+};
+```
+
+**`MultiSelectConfig` options:**
+
+| Property        | Type      | Description                                  |
+|-----------------|-----------|----------------------------------------------|
+| `idField`       | `string`  | Key for option ID                            |
+| `textField`     | `string`  | Key for display label                        |
+| `disabledField` | `string`  | Key to mark option as disabled               |
+| `placeholder`   | `string`  | Placeholder text                             |
+| `prefixLabel`   | `string`  | Label prefix shown before selected chips     |
+| `enableSearch`  | `boolean` | Show search input inside dropdown            |
+| `chipLimit`     | `number`  | Max chips to display before `+N more`        |
+| `selectAll`     | `boolean` | Show "Select All" option                     |
+| `required`      | `boolean` | Mark field as required                       |
+
+---
+
+### `AutoComplete SingleSelect` — `<cats-ui-input-single-select>`
+
+**Template:**
+```html
+<cats-ui-input-single-select
+  [optionsList]="options"
+  [autoSingleSelectConfig]="autoSingleSelectConfig"
+  (onItemSelection)="onSelection($event)">
+</cats-ui-input-single-select>
+```
+
+**TypeScript:**
+```typescript
+import { AutoCompleteSingleSelectConfig } from 'cats-ui-lib';
+
+autoSingleSelectConfig: AutoCompleteSingleSelectConfig = {
+  idField: 'id',
+  textField: 'name',
+  disabledField: '',
+  placeholder: 'Enter or select',
+  required: false,
+  customInput: true,
+};
+```
+
+**`AutoCompleteSingleSelectConfig` options:**
+
+| Property        | Type      | Description                              |
+|-----------------|-----------|------------------------------------------|
+| `idField`       | `string`  | Key for option ID                        |
+| `textField`     | `string`  | Key for display label                    |
+| `disabledField` | `string`  | Key to mark option as disabled           |
+| `placeholder`   | `string`  | Placeholder text                         |
+| `required`      | `boolean` | Mark field as required                   |
+| `customInput`   | `boolean` | Allow free-text input not in option list |
+
+---
+
+### `AutoComplete MultiSelect` — `<cats-ui-input-multi-select>`
+
+**Template:**
+```html
+<cats-ui-input-multi-select
+  [optionsList]="options"
+  [autoCompleteMultiSelectConfig]="autoMultiSelectConfig"
+  (onItemSelection)="onSelection($event)">
+</cats-ui-input-multi-select>
+```
+
+**TypeScript:**
+```typescript
+import { AutoCompleteMultiSelectConfig } from 'cats-ui-lib';
+
+autoMultiSelectConfig: AutoCompleteMultiSelectConfig = {
+  idField: 'id',
+  textField: 'name',
+  disabledField: 'disable',
+  placeholder: 'Type to Search',
+  selectAll: false,
+  chipLimit: 2,
+  customInput: false,
+  infoText: 'Select any 8 KPIs',
+  selectionLimit: 5,
+};
+```
+
+**`AutoCompleteMultiSelectConfig` options:**
+
+| Property         | Type      | Description                              |
+|------------------|-----------|------------------------------------------|
+| `idField`        | `string`  | Key for option ID                        |
+| `textField`      | `string`  | Key for display label                    |
+| `disabledField`  | `string`  | Key to mark option as disabled           |
+| `placeholder`    | `string`  | Placeholder text (supports HTML)         |
+| `selectAll`      | `boolean` | Show "Select All" option                 |
+| `chipLimit`      | `number`  | Max chips shown before `+N more`         |
+| `customInput`    | `boolean` | Allow free-text input                    |
+| `infoText`       | `string`  | Helper text shown below the input        |
+| `selectionLimit` | `number`  | Max number of items that can be selected |
+
+---
+
+### `SearchBoxComponent` — `<cats-ui-search-box>`
+
+**Template:**
+```html
+<cats-ui-search-box
+  [searchConfig]="searchConfig"
+  (searchParamValue)="searchParamValue($event)">
+</cats-ui-search-box>
+```
+
+**TypeScript:**
+```typescript
+import { SearchConfig } from 'cats-ui-lib';
+
+searchConfig: SearchConfig = {
+  serachValue: '',
+  placeholder: 'Search Here',
+};
+
+searchParamValue(data: any) {
+  console.log('searchParamValue', data);
+}
+```
+
+---
+
+### `AccordionComponent` — `<cats-ui-accordion>`
+
+**Template:**
+```html
+<cats-ui-accordion>
+  <cats-ui-accordion-item title="Panel 1" [index]="0">
+    <ng-template>
+      <p>Content for Panel 1.</p>
+    </ng-template>
+  </cats-ui-accordion-item>
+
+  <cats-ui-accordion-item title="Panel 2" [index]="1">
+    <ng-template>
+      <p>Content for Panel 2.</p>
+    </ng-template>
+  </cats-ui-accordion-item>
+</cats-ui-accordion>
+```
+
+---
+
+### `RadioButtonComponent` — `<cats-ui-radio-button>`
+
+**Template:**
+```html
+<cats-ui-radio-button
+  [config]="radioConfig"
+  [optionList]="options"
+  (selectionChange)="onRadio($event)">
+</cats-ui-radio-button>
+```
+
+**TypeScript:**
+```typescript
+import { RadioButtonConfig } from 'cats-ui-lib';
+
+radioConfig: RadioButtonConfig = {
+  valueField: 'id',
+  textField: 'name',
+  name: 'gender',
+  disabled: 'disable',
+};
+
+options = [
+  { id: 1, name: 'Option 1', disable: false },
+  { id: 2, name: 'Option 2', disable: false },
+];
+
+onRadio(data: any) {
+  console.log('radio', data);
+}
+```
+
+**`RadioButtonConfig` options:**
+
+| Property      | Type     | Description                        |
+|---------------|----------|------------------------------------|
+| `valueField`  | `string` | Key for option value               |
+| `textField`   | `string` | Key for display label              |
+| `name`        | `string` | HTML radio group name              |
+| `disabled`    | `string` | Key to mark an option as disabled  |
+
+---
+
+### `CheckboxComponent` — `<cats-ui-checkbox-button>`
+
+**Template:**
+```html
+<cats-ui-checkbox-button
+  [checkBoxConfig]="checkBoxConfig"
+  [optionList]="taskOptions"
+  (onCheckBoxSelection)="checkBox($event)">
+</cats-ui-checkbox-button>
+```
+
+**TypeScript:**
+```typescript
+import { CheckBoxConfig } from 'cats-ui-lib';
+
+checkBoxConfig: CheckBoxConfig = {
+  idField: 'id',
+  textField: 'name',
+  name: 'check23',
+  disabledField: 'disable',
+};
+
+taskOptions = [
+  { id: '101', name: 'Parent Task 1', disable: true },
+  { id: '102', name: 'Parent Task 2', disable: false },
+];
+
+checkBox(data: any) {
+  console.log('checkbox selection', data);
+}
+```
+
+**`CheckBoxConfig` options:**
+
+| Property        | Type     | Description                       |
+|-----------------|----------|-----------------------------------|
+| `idField`       | `string` | Key for option ID                 |
+| `textField`     | `string` | Key for display label             |
+| `name`          | `string` | HTML checkbox group name          |
+| `disabledField` | `string` | Key to mark an option as disabled |
+
+---
+
+### `ToggleComponent` — `<cats-ui-toogle-button>`
+
+**Template:**
+```html
+<cats-ui-toogle-button
+  [toggleConfig]="toggleConfig"
+  (onToggled)="onToggled($event)">
+</cats-ui-toogle-button>
+```
+
+**TypeScript:**
+```typescript
+import { ToggleConfig } from 'cats-ui-lib';
+
+toggleConfig: ToggleConfig = {
+  disabled: false,
+  checked: false,
+};
+
+onToggled(data: any) {
+  console.log('toggled', data);
+}
+```
+
+**`ToggleConfig` options:**
+
+| Property   | Type      | Description                      |
+|------------|-----------|----------------------------------|
+| `disabled` | `boolean` | Disable the toggle               |
+| `checked`  | `boolean` | Initial checked state            |
+
+---
+
+### `TabComponent` — `<cats-ui-tab>`
+
+Supports `horizontal` (default) and `vertical` orientations with optional disabled tabs.
+
+**Template:**
+```html
+<cats-ui-tab
+  [activeTab]="0"
+  orientation="vertical"
+  [disabledTabs]="[1]"
+  (selectTab)="onTabSelected($event)">
+
+  <cats-ui-tab-item>
+    <ng-template tabHeading>Home</ng-template>
+    <ng-template tabContent>Home content</ng-template>
+  </cats-ui-tab-item>
+
+  <cats-ui-tab-item>
+    <ng-template tabHeading>Profile</ng-template>
+    <ng-template tabContent>Profile content</ng-template>
+  </cats-ui-tab-item>
+
+</cats-ui-tab>
+```
+
+**Dynamic tabs with close button:**
+```html
+<cats-ui-tab
+  [activeTab]="activeTabIndex"
+  [disabledTabs]="disabledTabs"
+  (selectTab)="onTabSelected($event)">
+
+  @for (tab of tabs; track $index) {
+    <cats-ui-tab-item>
+      <ng-template tabHeading>
+        {{ tab.heading }}
+        <span class="btn-close ms-3" (click)="closeTab($index)">x</span>
+      </ng-template>
+      <ng-template tabContent>{{ tab.content }}</ng-template>
+    </cats-ui-tab-item>
+  }
+
+</cats-ui-tab>
+```
+
+**TypeScript:**
+```typescript
+tabs = [
+  { heading: 'Home',    content: 'Home content'    },
+  { heading: 'Profile', content: 'Profile content' },
+];
+activeTabIndex = 0;
+disabledTabs: number[] = [1];
+
+onTabSelected(index: number) {
+  this.activeTabIndex = index;
+}
+
+closeTab(index: number) {
+  if (this.tabs.length > 1) {
+    this.tabs.splice(index, 1);
+    if (this.activeTabIndex >= this.tabs.length) {
+      this.activeTabIndex = this.tabs.length - 1;
+    }
+  }
+}
+```
+
+---
+
+### `TabsetComponent` — `<cats-ui-tabset>`
+
+An advanced tabset with add/close tab support, icons, badge counts, and a home tab.
+
+**Template:**
+```html
+<cats-ui-tabset
+  [tabs]="tab1"
+  [(activeTab)]="activeTab"
+  [tabConfig]="tabConfig"
+  (tabAdded)="onTabAdded($event)"
+  (tabClosed)="onTabClosed($event)"
+  (activeTabChange)="activeTabChange($event)">
+
+  <!-- Tab ID 0 is the Home tab (requires homeTab: true in tabConfig) -->
+  <cats-ui-tab-content [tabId]="0">Home Content</cats-ui-tab-content>
+  <cats-ui-tab-content [tabId]="1">Tab 1 Content</cats-ui-tab-content>
+  <cats-ui-tab-content [tabId]="2">Tab 2 Content</cats-ui-tab-content>
+
+</cats-ui-tabset>
+```
+
+**TypeScript:**
+```typescript
+tabConfig = {
+  addTab:   true,   // Show "+" add tab button
+  closeTab: true,   // Show close button on tabs
+  homeTab:  true,   // Enable a fixed home tab at ID 0
+  type:     'Stroke', // Tab style variant
+};
+
+tab1 = [
+  { id: 1, title: 'Tab1' },
+  {
+    id: 2,
+    title: 'Tab2',
+    leadingIcon: 'images/command.svg',
+    tralingIocn: 'images/x-circle.svg',
+    count: 67,
+  },
+];
+
+activeTab: any;
+tab = 6; // counter for dynamic tab IDs
+
+onTabAdded(ev: any) {
+  const newTab = {
+    id: ++this.tab,
+    title: `Dynamic Tab ${this.tab}`,
+  };
+  this.tab1 = [...this.tab1, newTab];
+  this.activeTab = newTab.id;
+}
+
+onTabClosed(id: number) {
+  console.log('Tab closed:', id);
+}
+
+activeTabChange(dt: any) {
+  console.log('Active tab:', dt);
+}
+```
+
+**Tab item options:**
+
+| Property      | Type     | Description                          |
+|---------------|----------|--------------------------------------|
+| `id`          | `number` | Unique tab ID                        |
+| `title`       | `string` | Tab label                            |
+| `leadingIcon` | `string` | Icon path shown before the title     |
+| `tralingIocn` | `string` | Icon path shown after the title      |
+| `count`       | `number` | Badge count shown on the tab         |
+
+---
+
+### `CustomDatePickerComponent` — `<cats-ui-custom-date-picker>`
+
+Supports `single`, `range`, and `dual` modes with optional time selection.
+
+| Mode     | Description                         |
+|----------|-------------------------------------|
+| `single` | Single date picker (± time)         |
+| `range`  | Start and end date picker (± time)  |
+| `dual`   | Two-calendar view (± time)          |
+
+**Template:**
+```html
+<!-- Single date + time -->
+<cats-ui-custom-date-picker
+  [config]="{ mode: 'single', time: true, parentDateFormat: 'MM/dd/yyyy' }"
+  (applied)="displayData($event)">
+</cats-ui-custom-date-picker>
+
+<!-- Date range -->
+<cats-ui-custom-date-picker
+  [config]="{ mode: 'range', time: false, parentDateFormat: 'MM/dd/yyyy' }"
+  (applied)="displayData($event)">
+</cats-ui-custom-date-picker>
+
+<!-- Date range + time -->
+<cats-ui-custom-date-picker
+  [config]="{ mode: 'range', time: true, parentDateFormat: 'MM/dd/yyyy' }"
+  (applied)="displayData($event)">
+</cats-ui-custom-date-picker>
+
+<!-- Dual calendar -->
+<cats-ui-custom-date-picker
+  [config]="{ mode: 'dual', time: false, parentDateFormat: 'MM/dd/yyyy' }"
+  (applied)="displayData($event)">
+</cats-ui-custom-date-picker>
+
+<!-- Dual calendar + time -->
+<cats-ui-custom-date-picker
+  [config]="{ mode: 'dual', time: true, parentDateFormat: 'MM/dd/yyyy' }"
+  (applied)="displayData($event)">
+</cats-ui-custom-date-picker>
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+**Config options:**
+
+| Property           | Type      | Description                                         |
+|--------------------|-----------|-----------------------------------------------------|
+| `mode`             | `string`  | `'single'` \| `'range'` \| `'dual'`                |
+| `time`             | `boolean` | Show time picker alongside the date                 |
+| `parentDateFormat` | `string`  | Output date format, e.g. `'MM/dd/yyyy'`             |
+| `minDate`          | `Date`    | Minimum selectable date                             |
+| `maxDate`          | `Date`    | Maximum selectable date                             |
+| `placeholder`      | `string`  | Placeholder for single-date mode                    |
+| `fromPlaceholder`  | `string`  | Placeholder for start date in range/dual mode       |
+| `toPlaceholder`    | `string`  | Placeholder for end date in range/dual mode         |
+| `disabledDates`    | `Date[]`  | Array of dates to disable                           |
+| `disablePastDays`  | `number`  | Number of past days to disable                      |
+| `showDateLabel`    | `boolean` | Show label above date input                         |
+| `showTimeLabel`    | `boolean` | Show label above time input                         |
 
-### Publishing the Library
+---
 
-Once the project is built, you can publish your library by following these steps:
+### `TimestampFilterComponent` — `<cats-ui-timestamp-filter>`
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/cats-ui
-   ```
+A pre-built filter component with quick date presets, custom input, and date picker submenus.
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+**Template:**
+```html
+<cats-ui-timestamp-filter
+  [config]="timeFilterConfig"
+  (selectionChange)="onFilterChange($event)">
+</cats-ui-timestamp-filter>
+```
 
-## Running unit tests
+**TypeScript:**
+```typescript
+timeFilterConfig = {
+  title: 'Timestamp Filter',
+  showReset: true,
+  options: [
+    { label: 'Live',           value: 'live'  },
+    { label: 'Today',          value: 'today', default: true },
+    { label: 'This Week',      value: 'week'  },
+    { label: 'This Month',     value: 'month' },
+    { label: 'This Financial Year', value: 'fy' },
+    { label: 'Last 24 Hours',  value: '24h'   },
+    { label: 'Last 30 days',   value: '30d'   },
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+    // Custom number input (e.g. "Last N days")
+    { label: 'Last', value: 'last', type: 'input', custom: true },
+
+    // Date picker submenus
+    {
+      label: 'Custom Date',
+      value: 'date',
+      type: 'submenu',
+      custom: true,
+      pickerMode: 'single',
+      parentDateFormat: 'MM/dd/yyyy',
+    },
+    {
+      label: 'Custom Date and Time',
+      value: 'datetime',
+      type: 'submenu',
+      custom: true,
+      pickerMode: 'single',
+      parentDateFormat: 'MM/dd/yyyy',
+    },
+    {
+      label: 'Custom Date Range',
+      value: 'range',
+      type: 'submenu',
+      custom: true,
+      pickerMode: 'range',
+    },
+    {
+      label: 'Custom Date and Time Range',
+      value: 'datetimerange',
+      type: 'submenu',
+      custom: true,
+    },
+  ],
+};
+
+onFilterChange(dt: any) {
+  console.log('timestamp filter', dt);
+}
+```
+
+**Config options:**
+
+| Property    | Type      | Description                             |
+|-------------|-----------|-----------------------------------------|
+| `title`     | `string`  | Label shown above the filter            |
+| `showReset` | `boolean` | Show a reset button                     |
+| `options`   | `array`   | Array of filter option objects          |
+
+**Option object fields:**
+
+| Field              | Type      | Description                                                     |
+|--------------------|-----------|-----------------------------------------------------------------|
+| `label`            | `string`  | Display label for the option                                    |
+| `value`            | `string`  | Emitted value on selection                                      |
+| `default`          | `boolean` | Pre-select this option on load                                  |
+| `type`             | `string`  | `'input'` for numeric entry, `'submenu'` for date picker popup  |
+| `custom`           | `boolean` | Marks as a custom/user-defined option                           |
+| `pickerMode`       | `string`  | Date picker mode: `'single'` \| `'range'`                      |
+| `parentDateFormat` | `string`  | Output date format for picker submenus                          |
+
+---
+
+### `Tooltip Directive` — `catsUiTooltip`
+
+Apply as an attribute on any HTML element.
+
+```html
+<button catsUiTooltip="This is a tooltip">Hover me</button>
+```
+
+---
+
+## 📁 Project Structure
+
+```
+cats-ui-lib/
+├── accordion/
+├── auto-complete-multi-select/
+├── auto-complete-single-select/
+├── checkbox-button/
+├── custom-date-picker/
+├── date-time-picker/
+├── input/
+├── multi-select/
+├── radio-button/
+├── search-box/
+├── single-select/
+├── tabs/
+├── tabset/
+├── timestamp-filter/
+└── toogle-button/
+```
+
+---
+
+## 🔗 Links
+
+- **npm:** [https://www.npmjs.com/package/cats-ui-lib](https://www.npmjs.com/package/cats-ui-lib)
+- **Angular CLI Docs:** [https://angular.dev/tools/cli](https://angular.dev/tools/cli)
+
+---
+
+## 🛠️ Development
+
+### Build the library
 
 ```bash
-ng test
+ng build cats-ui
 ```
 
-## Running end-to-end tests
+### Run unit tests
 
-For end-to-end (e2e) testing, run:
+```bash
+ng test
+```
+
+### Publish to npm
 
 ```bash
-ng e2e
+ng build cats-ui
+cd dist/cats-ui
+npm publish
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+---
+
+## 📋 Requirements
+
+| Dependency | Version |
+|------------|---------|
+| Angular    | >= 19.x |
+| Node.js    | >= 18.x |
+
+---
 
-## Additional Resources
+## 📄 License
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+MIT © cats-ui-lib