ngx-virtual-select-field-filterable 1.5.1 → 1.5.2

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 +96 -35
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- <span><a href="https://www.npmjs.com/package/ngx-virtual-select-field" title="View this project on NPM">![NPM Version](https://img.shields.io/npm/v/ngx-virtual-select-field?style=flat&logo=npm)
1
+ <span><a href="https://www.npmjs.com/package/ngx-virtual-select-field-filterable" title="View this project on NPM">![NPM Version](https://img.shields.io/npm/v/ngx-virtual-select-field-filterable?style=flat&logo=npm)
2
2
  </a></span>
3
- <span><a href="https://github.com/Vizer/ngx-virtual-select-field/actions/workflows/node.js.yml" title="View this project workflow">![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/vizer/ngx-virtual-select-field/node.js.yml?style=flat&logo=github&label=workflow)
3
+ <span><a href="https://github.com/kubiq/ngx-virtual-select-field/actions/workflows/test.yml" title="View this project workflow">![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/kubiq/ngx-virtual-select-field/test.yml?style=flat&logo=github&label=tests)
4
4
  </a></span>
5
5
 
6
6
  # Virtual Select component for Angular Material Form Field
@@ -10,6 +10,7 @@
10
10
  - [Description](#description)
11
11
  - [Getting started](#getting-started)
12
12
  - [Examples](#examples)
13
+ - [Keyboard Shortcuts](#keyboard-shortcuts)
13
14
  - [Customization](#customization)
14
15
  - [API](#api)
15
16
  - [NgxVirtualSelectFieldComponent<TValue>](#ngxvirtualselectfieldcomponenttvalue)
@@ -24,28 +25,31 @@
24
25
 
25
26
  ## Description
26
27
 
27
- This package replicates the Angular Material Select component with virtual scroll capabilities with help of cdk-virtual-scroll. It provides most major features of the original Angular Material Select component. The goal of this package is to provide similar api and features as the original Angular Material Select component but with virtual scroll capabilities. One major difference is that this package does not support option groups at the moment. Also, this requires own structural directive to be used for options in order to provide virtual scroll capabilities and custom template.
28
+ This package replicates the Angular Material Select component with virtual scroll capabilities using cdk-virtual-scroll. It provides most major features of the original Angular Material Select component. The goal of this package is to provide a similar API and features as the original Angular Material Select component but with virtual scroll capabilities for handling large datasets efficiently.
28
29
 
29
30
  Features:
30
31
 
31
- - Virtual scroll
32
- - Multi select
32
+ - Virtual scroll for large datasets (100,000+ items)
33
33
  - Single select
34
+ - Multi select with checkboxes
35
+ - Select all checkbox (for multi-select with filter)
34
36
  - Filterable options with search input
35
- - Clear buttons for filter and selection
37
+ - Clearable selection
36
38
  - Loading spinner for async data
37
39
  - Integrates with Angular Material Form Field
40
+ - Reactive Forms and Template-driven forms support
38
41
  - Custom trigger template
39
42
  - Custom option template
40
- - Keyboard navigation and shortcuts
41
- - Theming trough css variables
43
+ - Full keyboard navigation and shortcuts
44
+ - Type-ahead search
45
+ - Theming through CSS variables
42
46
 
43
47
  Not Supported Features for now:
44
48
 
45
49
  - Animations
46
- - Custom Error state mather
50
+ - Custom Error state matcher
47
51
  - Custom scroll strategy
48
- - Accessibility
52
+ - Full accessibility (in progress)
49
53
  - Option groups
50
54
 
51
55
  [Demo](https://stackblitz.com/edit/demo-ngx-virtual-select-field)
@@ -72,7 +76,7 @@ Not Supported Features for now:
72
76
  })
73
77
  ```
74
78
 
75
- 1. Create options collection in component. Options collection should be an array of objects with `value` and `label` properties. Optionally, you can add `disabled` property to disable specific options and `getLabel()` fot type ahead search.
79
+ 1. Create options collection in component. Options collection should be an array of objects with `value` and `label` properties. Optionally, you can add `disabled` property to disable specific options and `getLabel()` for type-ahead search.
76
80
 
77
81
  ```typescript
78
82
  ...
@@ -89,16 +93,16 @@ Not Supported Features for now:
89
93
  }
90
94
  ```
91
95
 
92
- 1. Setup template markup. `ngxVirtualSelectFieldOptionFor` directive should be user to pass options collection to the component and provide custom option template.
96
+ 1. Setup template markup. `ngxVirtualSelectFieldOptionFor` directive should be used to pass options collection to the component and provide custom option template.
93
97
 
94
98
  ```html
95
99
  <mat-form-field>
96
100
  <mat-label>Virtual Select Field Example</mat-label>
97
101
  <ngx-virtual-select-field [value]="value">
98
- <ngx-virtual-select-field-option
99
- *ngxVirtualSelectFieldOptionFor="let option of options"
102
+ <ngx-virtual-select-field-option
103
+ *ngxVirtualSelectFieldOptionFor="let option of options"
100
104
  [value]="option.value"
101
- [disabled]="option.disabled">
105
+ [disabled]="option.disabled">
102
106
  {{ option.label }}
103
107
  </ngx-virtual-select-field-option>
104
108
  </ngx-virtual-select-field>
@@ -120,9 +124,9 @@ Basic setup with value input and output binding
120
124
  <mat-form-field>
121
125
  <mat-label>Example</mat-label>
122
126
  <ngx-virtual-select-field [value]="value" (valueChange)="onValueChange($event)">
123
- <ngx-virtual-select-field-option
124
- *ngxVirtualSelectFieldOptionFor="let option of options" [value]="option.value">
125
- {{ option.label }}
127
+ <ngx-virtual-select-field-option
128
+ *ngxVirtualSelectFieldOptionFor="let option of options" [value]="option.value">
129
+ {{ option.label }}
126
130
  </ngx-virtual-select-field-option>
127
131
  </ngx-virtual-select-field>
128
132
  </mat-form-field>
@@ -134,7 +138,7 @@ Form control integration
134
138
  <mat-form-field>
135
139
  <mat-label>Form Control Example</mat-label>
136
140
  <ngx-virtual-select-field [formControl]="formControl">
137
- <ngx-virtual-select-field-option
141
+ <ngx-virtual-select-field-option
138
142
  *ngxVirtualSelectFieldOptionFor="let option of options" [value]="option.value">
139
143
  {{ option.label }}
140
144
  </ngx-virtual-select-field-option>
@@ -148,10 +152,10 @@ Multi select
148
152
  <mat-form-field>
149
153
  <mat-label>Multi Select Example</mat-label>
150
154
  <ngx-virtual-select-field [value]="value" multiple (valueChange)="onValueChange($event)">
151
- <ngx-virtual-select-field-option
152
- *ngxVirtualSelectFieldOptionFor="let option of options"
153
- [value]="option.value">
154
- {{ option.label }}
155
+ <ngx-virtual-select-field-option
156
+ *ngxVirtualSelectFieldOptionFor="let option of options"
157
+ [value]="option.value">
158
+ {{ option.label }}
155
159
  </ngx-virtual-select-field-option>
156
160
  </ngx-virtual-select-field>
157
161
  </mat-form-field>
@@ -213,6 +217,61 @@ Clearable select with clear button
213
217
  </mat-form-field>
214
218
  ```
215
219
 
220
+ Loading state for async data
221
+
222
+ ```html
223
+ <mat-form-field>
224
+ <mat-label>Async Example</mat-label>
225
+ <ngx-virtual-select-field
226
+ [value]="value"
227
+ [loading]="isLoading"
228
+ (valueChange)="onValueChange($event)">
229
+ <ngx-virtual-select-field-option
230
+ *ngxVirtualSelectFieldOptionFor="let option of options"
231
+ [value]="option.value">
232
+ {{ option.label }}
233
+ </ngx-virtual-select-field-option>
234
+ </ngx-virtual-select-field>
235
+ </mat-form-field>
236
+ ```
237
+
238
+ ## Keyboard Shortcuts
239
+
240
+ The component supports full keyboard navigation:
241
+
242
+ ### When Panel is Closed
243
+
244
+ | Shortcut | Single Select | Multi Select |
245
+ |----------|---------------|--------------|
246
+ | `Space` / `Enter` | Open panel | Open panel |
247
+ | `Alt + ArrowDown` | Open panel | Open panel |
248
+ | `ArrowDown` / `ArrowUp` | Navigate & select | Open panel |
249
+ | Type any character | Type-ahead search | Type-ahead search |
250
+
251
+ ### When Panel is Open
252
+
253
+ | Shortcut | Description |
254
+ |----------|-------------|
255
+ | `ArrowDown` / `ArrowUp` | Navigate through options |
256
+ | `Alt + ArrowDown` / `Alt + ArrowUp` | Close panel |
257
+ | `Enter` / `Space` | Toggle selection of active option |
258
+ | `Ctrl + A` | Select/deselect all options (multi-select only) |
259
+ | `Shift + ArrowDown` / `Shift + ArrowUp` | Extend selection (multi-select only) |
260
+ | `Home` / `End` | Jump to first/last option |
261
+ | `Page Up` / `Page Down` | Navigate by page |
262
+ | `Escape` | Close panel |
263
+ | `Tab` | Select active item and close panel |
264
+ | Type any character | Type-ahead search (300ms debounce) |
265
+
266
+ ### When Filter Input is Focused
267
+
268
+ | Shortcut | Description |
269
+ |----------|-------------|
270
+ | `ArrowDown` / `ArrowUp` | Move focus to options list |
271
+ | `ArrowLeft` / `ArrowRight` | Move cursor in filter input |
272
+ | `Escape` | Close panel |
273
+ | `Tab` | Close panel |
274
+
216
275
  ## Customization
217
276
 
218
277
  Components supports custom templates for trigger and option elements. You can use `ngx-virtual-select-field-trigger` and `ngx-virtual-select-field-option` components to define custom templates.
@@ -229,7 +288,7 @@ See more in API section below.
229
288
 
230
289
  ### NgxVirtualSelectFieldComponent<TValue>
231
290
 
232
- selector: `ngx-virtual-select-field`
291
+ selector: `ngx-virtual-select-field`
233
292
  Component to define select field
234
293
 
235
294
  | Input | Type | Default | Description |
@@ -246,20 +305,21 @@ Component to define select field
246
305
  | filterClearable | `boolean` | `true` | Show clear button in filter input |
247
306
  | clearable | `boolean` | `false` | Show clear button in select trigger to clear all selections |
248
307
  | loading | `boolean` | `false` | Show loading spinner while data is being loaded |
308
+ | showSelectAll | `boolean` | `true` | Show select all checkbox when multiple and filterable are enabled |
249
309
  | value | `TValue[] \| TValue \| null` | `null` | Value of the select field |
250
310
  | placeholder | `string` | none | Placeholder for the select field |
251
- | required | `boolean` | `false` | Define if fields is required |
252
- | disabled | `boolean` | `false` | Define if fields is disabled |
311
+ | required | `boolean` | `false` | Define if field is required |
312
+ | disabled | `boolean` | `false` | Define if field is disabled |
253
313
 
254
314
  | Output | Type | Description |
255
315
  | --------------- | ----------------------------- | -------------------------- |
256
316
  | valueChange | `TValue \| TValue[]` | Value change output |
257
- | selectionChange | `NgxVirtualSelectFieldChange` | Selecten change output |
317
+ | selectionChange | `NgxVirtualSelectFieldChange` | Selection change output |
258
318
 
259
319
 
260
320
  ### NgxVirtualSelectFieldOptionComponent<TValue>
261
321
 
262
- selector: `ngx-virtual-select-field-option`
322
+ selector: `ngx-virtual-select-field-option`
263
323
  Component to define option element
264
324
 
265
325
  | Input | Type | Default | Description |
@@ -273,7 +333,7 @@ Component to define option element
273
333
 
274
334
  ### NgxVirtualSelectFieldOptionSelectionChangeEvent<TValue>
275
335
 
276
- Interface to define option selection change event contract
336
+ Interface to define option selection change event contract
277
337
  Properties:
278
338
  | Name | Type | Description |
279
339
  |----------|-----------------------------------------------------------|----------------------------|
@@ -283,12 +343,12 @@ Properties:
283
343
 
284
344
  ### NgxVirtualSelectFieldTriggerComponent
285
345
 
286
- selector: `ngx-virtual-select-field-trigger`
346
+ selector: `ngx-virtual-select-field-trigger`
287
347
  Directive to define custom trigger template
288
348
 
289
349
  ### NgxVirtualSelectFieldOptionForDirective
290
350
 
291
- selector: `*ngxVirtualSelectFieldOptionFor`
351
+ selector: `*ngxVirtualSelectFieldOptionFor`
292
352
  Directive to define custom option template and iterate over options
293
353
  | Input | Type | Description |
294
354
  |----------------------------------|----------------------------------------------|---------------------|
@@ -296,14 +356,14 @@ Directive to define custom option template and iterate over options
296
356
 
297
357
  ### NgxVirtualSelectFieldOptionModel<TValue>
298
358
 
299
- Interface to define option model contract
359
+ Interface to define option model contract
300
360
  Properties:
301
361
  | Name | Type | Description |
302
362
  |-----------------------|----------------------------------------------------------------|----------------------------|
303
363
  | value | `TValue` | Value of the option |
304
364
  | label | `string` | Label of the option |
305
365
  | disabled? | `boolean` | Whether the option is disabled |
306
- | getLabel() optional | `(option: NgxVirtualSelectFieldOptionModel<TValue>) => string` | Function to get label of the option |
366
+ | getLabel() optional | `(option: NgxVirtualSelectFieldOptionModel<TValue>) => string` | Function to get label for type-ahead search |
307
367
 
308
368
  ### NGX_VIRTUAL_SELECT_FIELD_CONFIG
309
369
 
@@ -320,6 +380,7 @@ Properties:
320
380
  | overlayPanelClass | `string \| string[]` | CSS class to be added to the panel element|
321
381
  | optionHeight | `number` | Height for an option element |
322
382
  | panelViewportPageSize | `number` | Amount of visible items in list |
383
+ | showSelectAll | `boolean` | Show select all checkbox when multiple and filterable |
323
384
 
324
385
  ### NgxVirtualSelectFieldChange
325
386
 
@@ -327,8 +388,8 @@ Class to define event for `selectionChange` output
327
388
  Properties:
328
389
  | Name | Type | Description |
329
390
  |-----------------------|--------------------------------------------|----------------------------|
330
- | source | `NgxVirtualSelectFieldComponent` | isntance of the selector component |
331
- | value | `TValue` or `TValue[]` | new selection value|
391
+ | source | `NgxVirtualSelectFieldComponent` | Instance of the selector component |
392
+ | value | `TValue` or `TValue[]` | New selection value|
332
393
 
333
394
 
334
395
  ### CSS variables
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ngx-virtual-select-field-filterable",
3
- "version": "1.5.1",
3
+ "version": "1.5.2",
4
4
  "description": "Virtual Select Field for Angular Material",
5
5
  "keywords": [
6
6
  "angular",