@@ -14,59 +14,116 @@ Once you have the `select` component, you can create an instance with the follow
14
14
15
15
``` javascript
16
16
const mySelect = await select (
17
- ' My Title' , // Title of the select menu
18
- options , // Array of options or strings representing the options
19
- opt // Additional options or boolean for rejectOnCancel
17
+ ' My Title' , // Title of the select menu
18
+ items , // Array of select items
19
+ options // Additional options
20
20
);
21
21
```
22
22
23
23
## Parameters
24
24
25
- ### ` title (string): `
26
- A string that will be displayed as the title of the select menu.
27
-
28
- ### ` options (Array\<Array or string>): `
29
- An array representing the options in the select menu. Each array should have a ` value ` , ` text ` , ` icon ` , and ` disable ` property.
30
-
31
- ### ` opt (SelectOptions | boolean): `
32
- An object or boolean that allows additional functionality to be added to the select menu.
33
-
34
- ### SelectOptions
35
-
36
- - ** hideOnSelect (boolean):**
37
- - A boolean that specifies whether the select menu will hide when an option is selected.
25
+ ### ` title ` (string)
26
+ The header text shown at the top of the selection dialog.
27
+
28
+ ### ` items ` (Array | String[ ] )
29
+ Options to display in three supported formats:
30
+
31
+ 1 . ** Simple strings** :
32
+ ``` javascript
33
+ const items = [' Option 1' , ' Option 2' , ' Option 3' ];
34
+ ```
35
+
36
+ 2 . ** Array format** ` [value, text, icon, disabled, letters, checkbox] ` :
37
+ ``` javascript
38
+ const items = [
39
+ [' value1' , ' Display Text' , ' icon-class' , false , ' AB' , null ],
40
+ [' value2' , ' Another Option' , null , true , null , true ]
41
+ ];
42
+ ```
43
+
44
+ 3 . ** Object format** :
45
+ ``` javascript
46
+ const items = [
47
+ {value: ' option1' , text: ' First Option' , icon: ' icon-class' },
48
+ {value: ' option2' , text: ' Second Option' , disabled: true }
49
+ ];
50
+ ```
51
+
52
+ #### Item Parameters
53
+
54
+ | Parameter | Type | Description |
55
+ | -----------| ------| -------------|
56
+ | ` value ` | String | Unique identifier returned when selected |
57
+ | ` text ` | String | Display text shown to the user |
58
+ | ` icon ` | String | CSS class for icon or 'letters' to use the letters parameter |
59
+ | ` disabled ` | Boolean | Whether the option can be selected |
60
+ | ` letters ` | String | Shows letter initials as an icon (when icon='letters') |
61
+ | ` checkbox ` | Boolean | Adds a checkbox to the option when set |
62
+
63
+ ### ` options ` (Object | Boolean)
64
+ Configure dialog behavior:
65
+
66
+ | Option | Type | Default | Description |
67
+ | --------| ------| ---------| -------------|
68
+ | ` hideOnSelect ` | Boolean | ` true ` | Close dialog after selection |
69
+ | ` textTransform ` | Boolean | ` false ` | Apply text transformation to options |
70
+ | ` default ` | String | ` null ` | Pre-selected option value |
71
+ | ` onCancel ` | Function | ` null ` | Called when dialog is cancelled |
72
+ | ` onHide ` | Function | ` null ` | Called when dialog is hidden |
73
+
74
+ Pass ` true ` to reject the promise on cancel instead of using an object.
75
+
76
+ ## Examples
77
+
78
+ ### Basic Selection
79
+ ``` javascript
80
+ const select = acode .require (' select' );
81
+ const result = await select (' Pick a color' , [' Red' , ' Green' , ' Blue' ]);
82
+ ```
38
83
39
- - ** textTransform (boolean):**
40
- - A boolean that specifies whether the text of the options should be transformed (e.g., to uppercase).
84
+ ### Rich Selection
85
+ ``` javascript
86
+ const items = [
87
+ [' edit' , ' Edit File' , ' edit' , false ],
88
+ [' delete' , ' Delete File' , ' delete' , false ],
89
+ [' share' , ' Share File' , ' share' , true ]
90
+ ];
41
91
42
- - ** default (string):**
43
- - A string that represents the default selected option.
92
+ const options = {
93
+ hideOnSelect: true ,
94
+ default: ' edit' ,
95
+ onCancel : () => console .log (' Selection cancelled' )
96
+ };
44
97
45
- - ** onCancel (Function): **
46
- - A function that will be called when the user cancels the select menu.
98
+ const action = await select ( ' File Actions ' , items, options);
99
+ ```
47
100
48
- - ** onHide (Function):**
49
- - A function that will be called when the select menu is hidden.
101
+ ### With Checkboxes
102
+ ``` javascript
103
+ const features = [
104
+ {value: ' sync' , text: ' Cloud Sync' , checkbox: true },
105
+ {value: ' backup' , text: ' Auto Backup' , checkbox: false },
106
+ {value: ' formatting' , text: ' Code Formatting' , checkbox: true }
107
+ ];
50
108
51
- ## Example
109
+ const selected = await select (' Enable Features' , features, {hideOnSelect: false });
110
+ ```
52
111
53
- ``` javascript:line-numbers
54
- const select = acode.require('select');
55
- const options = [
56
- ['option1 ', 'Option 1 ', 'icon1 ', true] ,
57
- ['option2 ', 'Option 2 ', 'icon2 ', false],
112
+ ### Using Letter Icons
113
+ ``` javascript
114
+ const users = [
115
+ {value : ' john ' , text : ' John Smith ' , icon : ' letters ' , letters : ' JS ' } ,
116
+ {value : ' jane ' , text : ' Jane Doe ' , icon : ' letters ' , letters : ' JD ' }
58
117
];
59
- // Or
60
- // simple one
61
- // const options = ['Option 1', 'Option 2']
62
- const opt = {
63
- onCancel: () => window.toast('Cancel Clicked', 3000),
64
- hideOnSelect: true,
65
- textTransform: true,
66
- default: 'option2',
67
- };
68
118
69
- const mySelect = await select('My Title ', options, opt );
119
+ const selectedUser = await select (' Choose User ' , users );
70
120
```
71
121
72
- In this example, the select menu will have two options: "Option 1" and "Option 2" with their respective values, icons, and disable property. The ` opt ` parameter allows the user to cancel the selection, the menu will hide on selection, the text will be transformed to uppercase, and the default option will be 'option2'.
122
+ ## Return Value
123
+ The ` value ` of the selected item as a string, or rejects if cancelled with ` rejectOnCancel: true ` .
124
+
125
+ ## Notes
126
+
127
+ - When using checkboxes, consider setting ` hideOnSelect: false ` to allow multiple selections
128
+ - The dialog automatically scrolls to the default selected option when opened
129
+ - Use the ` letters ` parameter with ` icon: 'letters' ` to display initials as avatars
0 commit comments