Skip to content

Commit d1efcbc

Browse files
authored
Update select.md (#9)
- update to follow the last commit on main app
1 parent 995f95c commit d1efcbc

File tree

1 file changed

+98
-41
lines changed

1 file changed

+98
-41
lines changed

docs/ui-components/dialogs/select.md

Lines changed: 98 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -14,59 +14,116 @@ Once you have the `select` component, you can create an instance with the follow
1414

1515
```javascript
1616
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
2020
);
2121
```
2222

2323
## Parameters
2424

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+
```
3883

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+
];
4191

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+
};
4497

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+
```
47100

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+
];
50108

51-
## Example
109+
const selected = await select('Enable Features', features, {hideOnSelect: false});
110+
```
52111

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'}
58117
];
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-
};
68118

69-
const mySelect = await select('My Title', options, opt);
119+
const selectedUser = await select('Choose User', users);
70120
```
71121

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

Comments
 (0)