@ruc-lib/dual-list-selector 2.0.0 → 2.0.5

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 +166 -4
  2. package/package.json +8 -7
package/README.md CHANGED
@@ -1,8 +1,170 @@
1
- # ruclib-dual-list-selector
1
+ # Dual List Selector
2
2
 
3
- "A dual list selector allows users to select and move items from one list of available items to another list of selected items. Unlike a select list, a dual list selector separates the available options and the selected options into two separate lists, which allows users to easily scan the items they selected. Additionally we'll provide the support for expandable list items and custom theme, title and labels."
3
+ The Dual List Selector is a highly configurable Angular component that allows users to move items between two lists: an "available" list and a "selected" list. It's ideal for scenarios where users need to make multiple selections from a large set of options.
4
4
 
5
+ ## Features
5
6
 
6
- ## Running unit tests
7
+ - **Two-List Layout**: Clearly separates available and selected items.
8
+ - **Drag and Drop**: Intuitively move items between lists using Angular CDK Drag and Drop.
9
+ - **Button Controls**: Move selected items, or all items, with button clicks.
10
+ - **Search**: Filter items within both lists to quickly find what you're looking for.
11
+ - **Sorting**: Sort items alphabetically in ascending or descending order.
12
+ - **Item Disabling**: Prevent specific items from being moved.
13
+ - **State Persistence**: Optionally persist the selected and available items in `sessionStorage` across page refreshes.
14
+ - **Customizable**: Control dimensions and apply custom themes.
7
15
 
8
- Run `nx test ruclib-dual-list-selector` to execute the unit tests.
16
+
17
+
18
+ ## Dependencies
19
+
20
+ This library has peer dependencies on `@angular/core`, `@angular/common`, and `@angular/material`.
21
+
22
+ ```bash
23
+ npm install @angular/material @angular/cdk
24
+
25
+ ```
26
+
27
+ ## Installation Guide
28
+
29
+ To use the Dual List Selector component, you can install the entire RUC library or just this specific component.
30
+
31
+ ### Install the Entire Library
32
+ ```bash
33
+ npm install @uxpractice/ruc-lib
34
+ ```
35
+
36
+ ### Install Individual Component
37
+ If you only need the Dual List Selector component:
38
+ ```bash
39
+ npm install @ruc-lib/dual-list-selector
40
+ ```
41
+
42
+ ## Usage
43
+
44
+ 1. Import the Module In your Angular module file (e.g., `app.module.ts`), import the `RuclibDualListSelectorModule`:**
45
+
46
+ ```typescript
47
+ import { RuclibDualListSelectorModule } from '@ruc-lib/dual-list-selector';
48
+ import { FormsModule } from '@angular/forms';
49
+ import { MatListModule } from '@angular/material/list';
50
+ import { MatChipsModule } from '@angular/material/chips';
51
+ import { DragDropModule } from '@angular/cdk/drag-drop';
52
+ import { MatFormFieldModule } from '@angular/material/form-field';
53
+ import { MatInputModule } from '@angular/material/input';
54
+ import { MatIconModule } from '@angular/material/icon';
55
+ import { MatSortModule } from '@angular/material/sort';
56
+ import { MatTableModule } from '@angular/material/table';
57
+
58
+ @NgModule({
59
+ imports: [
60
+ // ... other modules
61
+ RuclibDualListSelectorModule,
62
+ FormsModule,
63
+ MatListModule,
64
+ DragDropModule,
65
+ MatChipsModule,
66
+ MatFormFieldModule,
67
+ MatInputModule,
68
+ MatIconModule,
69
+ MatSortModule,
70
+ MatTableModule
71
+ ]
72
+ })
73
+ export class YourModule { }
74
+ ```
75
+
76
+ 2. **In your component's template:**
77
+
78
+ ```html
79
+ <uxp-dual-list-selector
80
+ [dataSource]="items"
81
+ [rucInputData]="config"
82
+ (rucEvent)="onSubmit($event)">
83
+ </uxp-dual-list-selector>
84
+ ```
85
+
86
+ 3. **In your component's TypeScript file:**
87
+
88
+ ```typescript
89
+ import { Component } from '@angular/core';
90
+
91
+ @Component({
92
+ selector: 'app-your-component',
93
+ templateUrl: './your-component.html',
94
+ })
95
+ export class YourComponent {
96
+ // Configuration for the dual list
97
+ config = {
98
+ height: 450,
99
+ width: 300,
100
+ persistOnRefresh: true,
101
+ enableSearch: true,
102
+ sorting: true,
103
+ };
104
+
105
+ // Data for the dual list
106
+ items = [
107
+ { id: 1, name: 'Item 1', disable: true },
108
+ { id: 2, name: 'Item 2', disable: true },
109
+ { id: 3, name: 'Item 3', disable: false }, // This item cannot be moved
110
+ { id: 4, name: 'Item 4', disable: true },
111
+ ];
112
+
113
+ onSubmit(selectedItems: any[]) {
114
+ console.log('Submitted Items:', selectedItems);
115
+ // Handle the submitted data
116
+ }
117
+ }
118
+ ```
119
+
120
+ ## API Reference
121
+
122
+ ### Component Selector
123
+
124
+ `<uxp-dual-list-selector>`
125
+
126
+ ### Inputs
127
+
128
+ | Input | Type | Default | Description |
129
+ | :------------- | :--------------- | :------ | :--------------------------------------------------------------------------------------- |
130
+ | `dataSource` | `Item[]` | `[]` | An array of items to populate the lists. Each item should follow the `Item` interface. |
131
+ | `rucInputData` | `DualListConfig` | `{}` | A configuration object for the component's features. See `DualListConfig` interface below. |
132
+ | `customTheme` | `string` | `''` | A custom CSS class name to be applied to the root element for theming purposes. |
133
+
134
+ ### Outputs
135
+
136
+ | Output | Type | Description |
137
+ | :--------- | :-------------------- | :--------------------------------------------------------------------------------- |
138
+ | `rucEvent` | `EventEmitter<Item[]>` | Emits an array of the currently selected items when the "Submit" button is clicked. |
139
+
140
+ ### Interfaces
141
+
142
+ #### `DualListConfig`
143
+
144
+ ```typescript
145
+ interface DualListConfig {
146
+ height?: number;
147
+ width?: number;
148
+ persistOnRefresh?: boolean;
149
+ enableSearch?: boolean;
150
+ sorting?: boolean;
151
+ }
152
+ ```
153
+
154
+ #### `Item`
155
+
156
+ ```typescript
157
+ interface Item {
158
+ id: number | string;
159
+ name: string;
160
+ disable: boolean;
161
+ }
162
+ ```
163
+
164
+ ## Contribution
165
+
166
+ Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.
167
+
168
+ ## Acknowledgements
169
+
170
+ Thank you for choosing the Dual List Selector component. If you have any feedback or suggestions, please let us know!
package/package.json CHANGED
@@ -1,14 +1,15 @@
1
1
  {
2
2
  "name": "@ruc-lib/dual-list-selector",
3
- "version": "2.0.0",
3
+ "version": "2.0.5",
4
4
  "license": "MIT",
5
5
  "peerDependencies": {
6
- "@angular/common": "^17.0.0 || ^16.0.0 || ^15.0.0",
7
- "@angular/core": "^17.0.0 || ^16.0.0 || ^15.0.0",
8
- "@angular/material": "^15.2.9 || ^14.0.0 || ^13.0.0",
9
- "@angular/cdk": "15.2.9",
10
- "@angular/platform-browser": "15.2.10",
11
- "@angular/forms": "15.2.10"
6
+ "@angular/animations": ">=15.0.0",
7
+ "@angular/material": "^15.2.0",
8
+ "@angular/core": ">=15.0.0 <18.0.0",
9
+ "@angular/forms": ">=15.0.0 <18.0.0",
10
+ "@angular/common": ">=15.0.0 <18.0.0",
11
+ "@angular/platform-browser": ">=15.0.0 <18.0.0",
12
+ "@angular/cdk": "^15.2.9"
12
13
  },
13
14
  "dependencies": {
14
15
  "tslib": "^2.3.0"