@ruc-lib/multi-select 2.0.4 → 2.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +133 -77
  2. package/package.json +6 -7
package/README.md CHANGED
@@ -1,97 +1,153 @@
1
1
  # ruclib-multi-select
2
2
 
3
- Multi Select box gives user flexibility to select multiple or single select options. It also used as parent child selection. Options are dynamic. Below points are configurable.
3
+ A flexible and customizable multi-select dropdown component for Angular applications. It supports single or multiple selections, parent-child relationships, search, sorting, and custom theming.
4
4
 
5
- # Features
6
- - Can be a single or multi select.
7
- - Set a limit on selections
8
- - Disable the whole select box at once.
9
- - Can change appearance
10
- - Maximum height of dropdown box.
11
- - Maximum height of options box.
12
- - Sort element by enabling sortBy.
13
- - Can customize the theme.
5
+ ## Installation Guide
14
6
 
15
- # Installation guide
7
+ To use the Multi-Select component, you can install the entire RUC library or just this specific component.
16
8
 
17
- # Install complete library
18
-
19
- `npm install @uxpractice/ruc-lib`
20
-
21
- # Install individual component
22
-
23
- If users only need the multi select component, they can install it separately
24
- `npm install @ruc-lib/multi-select`
25
-
26
- # Usage
27
-
28
- # import required modules
29
-
30
- for library
31
- `import { RuclibMultiSelectModule } from '@uxpractice/ruc-lib/multi-select'`
32
-
33
- for seperate package
34
- `import { RuclibMultiSelectModule } from '@ruc-lib/multi-select'`
35
-
36
- # use component selector
37
-
38
- ```
39
- <uxp-ruclib-multi-select [dataSource]="dataSourceForMultiSelectData" [rucInputData]="inputObjectDataMulti" [customTheme]="customTheme" (rucEvent)="passEvent($event)"></uxp-ruclib-multi-select>
9
+ ### Install the Entire Library
10
+ ```bash
11
+ npm install @uxpractice/ruc-lib
40
12
  ```
41
13
 
42
- # Input and Output
43
-
44
- # Inputs
45
- dataSource -> It is data to be passed in the multi-select component.
46
-
47
- rucInputData -> It is the configuration to be passed in the multi-select component.
48
-
49
- customTheme -> It is the name of the theme.
50
-
51
- # Output
52
-
53
- rucEvent -> is the event which will be fired when selection changes happens in multi-select.
14
+ ### Install Individual Component
15
+ If you only need the Multi-Select component:
16
+ ```bash
17
+ npm install @ruc-lib/multi-select
18
+ ```
54
19
 
55
- # rucInputData (sample object)
20
+ ## Usage
21
+
22
+ ### 1. Import the Module
23
+ In your Angular module file (e.g., `app.module.ts`), import the `RuclibMultiSelectModule`:
24
+
25
+ ```typescript
26
+ import { RuclibMultiSelectModule } from '@ruc-lib/multi-select';
27
+ import { AppComponent } from './app.component';
28
+ import { NgModule } from '@angular/core';
29
+ import { BrowserModule } from '@angular/platform-browser';
30
+ import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
31
+
32
+ @NgModule({
33
+ declarations: [AppComponent],
34
+ imports: [
35
+ BrowserModule,
36
+ BrowserAnimationsModule,
37
+ RuclibMultiSelectModule
38
+ ],
39
+ providers: [],
40
+ bootstrap: [AppComponent]
41
+ })
42
+ export class AppModule {}
43
+ ```
56
44
 
57
- # Detail definition of the each property can be found in type definition file.
45
+ ### 2. Use the Component
46
+ In your component's template, use the `<uxp-ruclib-multi-select>` selector and pass the configuration and data to the respective inputs.
58
47
 
48
+ ```html
49
+ <uxp-ruclib-multi-select
50
+ [dataSource]="dataSourceForMultiSelect"
51
+ [rucInputData]="inputObjectDataMulti"
52
+ [customTheme]="'custom-theme'"
53
+ (rucEvent)="handleEvent($event)">
54
+ </uxp-ruclib-multi-select>
59
55
  ```
60
- dataSourceForMultiSelectData = {
61
- singleSelection: false,
62
- label: 'Cities',
63
- showSelectAll: true,
64
- showSelected: true,
65
- appearance: 'outline',
66
- scroll: true,
67
- placeholder: 'Search or select from dropdown',
68
- //limit : 5,
69
- maxDropdownHeight: 200 /** height in px */,
70
- // inputbox properties
71
- // width: 100,
72
- /** width in % */
73
- maxHeight: 150 /** width in px */,
74
- disabled: false,
75
- //sort object
76
- sortBy: 'id',
77
- sortOrder: 'desc',
56
+
57
+ ## API Reference
58
+
59
+ ### Component Inputs
60
+
61
+ | Input | Type | Description |
62
+ |----------------|--------------------|--------------------------------------------------|
63
+ | `rucInputData` | `DefaultConfig` | The main configuration object for the component. |
64
+ | `dataSource` | `ListItem[]` | An array of items to be displayed in the dropdown. |
65
+ | `customTheme` | `string` | An optional CSS class for custom theming. |
66
+
67
+ ### Component Outputs
68
+
69
+ | Output | Type | Description |
70
+ |------------|--------------------|-----------------------------------------------------------------------------|
71
+ | `rucEvent` | `EventEmitter<any>` | Emits an event whenever a selection changes, an item is deselected, or the input is clicked. |
72
+
73
+ ### `DefaultConfig`
74
+ This is the main configuration object for the multi-select component.
75
+
76
+ | Property | Type | Description |
77
+ |---------------------|------------------------|---------------------------------------------------------------------------------------------------------|
78
+ | `singleSelection` | `boolean` | If `true`, allows only a single item to be selected. Defaults to `false`. |
79
+ | `label` | `string` | The label for the multi-select input field. |
80
+ | `showSelectAll` | `boolean` | If `true`, displays a "Select All" checkbox. Defaults to `true`. |
81
+ | `showSelected` | `boolean` | If `true`, displays a "Show Selected" filter. Defaults to `true`. |
82
+ | `appearance` | `'fill' \| 'outline'` | The appearance of the form field. Defaults to `'outline'`. |
83
+ | `scroll` | `boolean` | Enables or disables scrolling within the dropdown. Defaults to `true`. |
84
+ | `placeholder` | `string` | The placeholder text for the search input. |
85
+ | `limit` | `number` | The maximum number of items that can be selected. |
86
+ | `maxDropdownHeight` | `string` | The maximum height of the dropdown container (e.g., `'200px'`). |
87
+ | `maxHeight` | `number` | The maximum height of the options box in pixels. Defaults to `150`. |
88
+ | `disabled` | `boolean` | If `true`, disables the entire component. Defaults to `false`. |
89
+ | `sortBy` | `string` | The property of the `ListItem` to sort by (e.g., `'id'`, `'text'`). |
90
+ | `sortOrder` | `'asc' \| 'desc'` | The order of sorting. |
91
+
92
+ ### `ListItem`
93
+ This object defines the configuration for each item in the `dataSource`.
94
+
95
+ | Property | Type | Description |
96
+ |--------------|--------------------|--------------------------------------------------------------------------|
97
+ | `id` | `string \| number` | A unique identifier for the item. |
98
+ | `text` | `string` | The display text for the item. |
99
+ | `isDisabled` | `boolean` | If `true`, this item will be disabled and cannot be selected. |
100
+ | `icon` | `string` | An optional icon to display next to the item. |
101
+ | `childItem` | `any` | Used for creating parent-child relationships. |
102
+ | `grouped` | `boolean` | If `true`, indicates that the item is a group header. |
103
+
104
+ ## Example Configuration
105
+
106
+ Here's an example of how to configure the Multi-Select component in your component's TypeScript file.
107
+
108
+ ```typescript
109
+ import { Component } from '@angular/core';
110
+ import { DefaultConfig, ListItem } from '@ruc-lib/multi-select';
111
+
112
+ @Component({
113
+ selector: 'app-root',
114
+ templateUrl: './app.component.html',
115
+ })
116
+ export class AppComponent {
117
+
118
+ inputObjectDataMulti: DefaultConfig = {
119
+ singleSelection: false,
120
+ label: 'Cities',
121
+ showSelectAll: true,
122
+ showSelected: true,
123
+ appearance: 'outline',
124
+ scroll: true,
125
+ placeholder: 'Search or select from dropdown',
126
+ limit: 5,
127
+ maxDropdownHeight: '200px',
128
+ maxHeight: 150,
129
+ disabled: false,
130
+ sortBy: 'id',
131
+ sortOrder: 'desc',
78
132
  };
79
- ```
80
133
 
81
- # rucInputData (sample object)
134
+ dataSourceForMultiSelect: ListItem[] = [
135
+ { text: 'Afghanistan', id: 'AF', isDisabled: true },
136
+ { text: 'Åland Islands', id: 'AX', isDisabled: false },
137
+ { text: 'Albania', id: 'AL', isDisabled: false },
138
+ { text: 'Algeria', id: 'DZ', isDisabled: false },
139
+ ];
82
140
 
83
- ```
84
- inputObjectDataMulti = {
85
- { text: 'Afghanistan', id: 'AF', isDisable: true },
86
- { text: 'Åland Islands', id: 'AX', isDisable: false },
87
- { text: 'Albania', id: 'AL', isDisable: false },
88
- { text: 'Algeria', id: 'DZ', isDisable: false },
141
+ handleEvent(event: any) {
142
+ console.log(event.eventName, event.eventOutput);
143
+ }
89
144
  }
90
145
  ```
91
146
 
147
+ ## Contribution
92
148
 
93
- # Contribution
94
149
  Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.
95
150
 
96
- # Acknowledgements
97
- Thank you for choosing the Multi Select Component Library. If you have any feedback or suggestions, please let us know!
151
+ ## Acknowledgements
152
+
153
+ Thank you for choosing the Multi Select Component. If you have any feedback or suggestions, please let us know!
package/package.json CHANGED
@@ -1,16 +1,15 @@
1
1
  {
2
2
  "name": "@ruc-lib/multi-select",
3
- "version": "2.0.4",
3
+ "version": "2.0.6",
4
4
  "license": "MIT",
5
5
  "peerDependencies": {
6
6
  "@angular/common": "^17.0.0 || ^16.0.0 || ^15.0.0",
7
7
  "@angular/core": "^17.0.0 || ^16.0.0 || ^15.0.0",
8
- "@angular/form": "^17.0.0 || ^16.0.0 || ^15.0.0",
9
- "@angular/material": "^15.2.9 || ^14.0.0 || ^13.0.0",
10
- "@angular/animations": "15.2.10",
11
- "@angular/forms": "15.2.10",
12
- "@angular/platform-browser": "15.2.10",
13
- "@angular/cdk": "15.2.9"
8
+ "@angular/material": "^15.2.9 || ^14.0.0 || ^13.0.0 || ^16.0.0 || ^17.0.0",
9
+ "@angular/animations": "^15.2.10 || ^16.0.0 || ^17.0.0",
10
+ "@angular/forms": "^15.2.9",
11
+ "@angular/platform-browser": "^15.2.9",
12
+ "@angular/cdk": "^15.2.9"
14
13
  },
15
14
  "dependencies": {
16
15
  "tslib": "^2.3.0"