Update select.md

docs/ui-components/dialogs/select.md

@@ -14,59 +14,116 @@ Once you have the `select` component, you can create an instance with the follow
 
 ```javascript
 const mySelect = await select(
-  'My Title',          // Title of the select menu
-  options,             // Array of options or strings representing the options
-  opt                  // Additional options or boolean for rejectOnCancel
+  'My Title',    // Title of the select menu
+  items,         // Array of select items
+  options        // Additional options
 );
 ```
 
 ## Parameters
 
-### `title (string):`
-A string that will be displayed as the title of the select menu.
-
-### `options (Array\<Array or string>):`
-An array representing the options in the select menu. Each array should have a `value`, `text`, `icon`, and `disable` property.
-
-### `opt (SelectOptions | boolean):`
-An object or boolean that allows additional functionality to be added to the select menu.
-
-### SelectOptions
-
-- **hideOnSelect (boolean):**
-  - A boolean that specifies whether the select menu will hide when an option is selected.
+### `title` (string)
+The header text shown at the top of the selection dialog.
+
+### `items` (Array | String[])
+Options to display in three supported formats:
+
+1. **Simple strings**:
+   ```javascript
+   const items = ['Option 1', 'Option 2', 'Option 3'];
+   ```
+
+2. **Array format** `[value, text, icon, disabled, letters, checkbox]`:
+   ```javascript
+   const items = [
+     ['value1', 'Display Text', 'icon-class', false, 'AB', null],
+     ['value2', 'Another Option', null, true, null, true]
+   ];
+   ```
+
+3. **Object format**:
+   ```javascript
+   const items = [
+     {value: 'option1', text: 'First Option', icon: 'icon-class'},
+     {value: 'option2', text: 'Second Option', disabled: true}
+   ];
+   ```
+
+#### Item Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | String | Unique identifier returned when selected |
+| `text` | String | Display text shown to the user |
+| `icon` | String | CSS class for icon or 'letters' to use the letters parameter |
+| `disabled` | Boolean | Whether the option can be selected |
+| `letters` | String | Shows letter initials as an icon (when icon='letters') |
+| `checkbox` | Boolean | Adds a checkbox to the option when set |
+
+### `options` (Object | Boolean)
+Configure dialog behavior:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hideOnSelect` | Boolean | `true` | Close dialog after selection |
+| `textTransform` | Boolean | `false` | Apply text transformation to options |
+| `default` | String | `null` | Pre-selected option value |
+| `onCancel` | Function | `null` | Called when dialog is cancelled |
+| `onHide` | Function | `null` | Called when dialog is hidden |
+
+Pass `true` to reject the promise on cancel instead of using an object.
+
+## Examples
+
+### Basic Selection
+```javascript
+const select = acode.require('select');
+const result = await select('Pick a color', ['Red', 'Green', 'Blue']);
+```
 
-- **textTransform (boolean):**
-  - A boolean that specifies whether the text of the options should be transformed (e.g., to uppercase).
+### Rich Selection
+```javascript
+const items = [
+  ['edit', 'Edit File', 'edit', false],
+  ['delete', 'Delete File', 'delete', false],
+  ['share', 'Share File', 'share', true]
+];
 
-- **default (string):**
-  - A string that represents the default selected option.
+const options = {
+  hideOnSelect: true,
+  default: 'edit',
+  onCancel: () => console.log('Selection cancelled')
+};
 
-- **onCancel (Function):**
-  - A function that will be called when the user cancels the select menu.
+const action = await select('File Actions', items, options);
+```
 
-- **onHide (Function):**
-  - A function that will be called when the select menu is hidden.
+### With Checkboxes
+```javascript
+const features = [
+  {value: 'sync', text: 'Cloud Sync', checkbox: true},
+  {value: 'backup', text: 'Auto Backup', checkbox: false},
+  {value: 'formatting', text: 'Code Formatting', checkbox: true}
+];
 
-## Example
+const selected = await select('Enable Features', features, {hideOnSelect: false});
+```
 
-```javascript:line-numbers
-const select = acode.require('select');
-const options = [
-  ['option1', 'Option 1', 'icon1', true],
-  ['option2', 'Option 2', 'icon2', false],
+### Using Letter Icons
+```javascript
+const users = [
+  {value: 'john', text: 'John Smith', icon: 'letters', letters: 'JS'},
+  {value: 'jane', text: 'Jane Doe', icon: 'letters', letters: 'JD'}
 ];
-// Or 
-// simple one 
-// const options = ['Option 1', 'Option 2']
-const opt = {
-  onCancel: () => window.toast('Cancel Clicked', 3000),
-  hideOnSelect: true,
-  textTransform: true,
-  default: 'option2',
-};
 
-const mySelect = await select('My Title', options, opt);
+const selectedUser = await select('Choose User', users);
 ```
 
-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'.
+## Return Value
+The `value` of the selected item as a string, or rejects if cancelled with `rejectOnCancel: true`.
+
+## Notes
+
+- When using checkboxes, consider setting `hideOnSelect: false` to allow multiple selections
+- The dialog automatically scrolls to the default selected option when opened
+- Use the `letters` parameter with `icon: 'letters'` to display initials as avatars