[docs] Describe choicedropdown form field

docs/apis/subsystems/form/fields/_category_.yml

@@ -0,0 +1 @@
+label: Form fields

docs/apis/subsystems/form/fields/choicedropdown.md

@@ -0,0 +1,61 @@
+# Choice Dropdown Form Field (`choicedropdown`)
+
+The `choicedropdown` form field creates a dropdown list with multiple options. It is different from a
+standard select dropdown in that each option can have extra icons and descriptions. This field is often
+used in forms to facilitate the selection of a non-trivial option that demands additional information.
+
+## Using the `choicedropdown` Form Field
+
+While most form API fields use primitive data types, the `choicedropdown` form field uses a particular
+data definition called `choicelist`. This data definition is an abstraction that represents a user
+choice list and is used in other UI components like `core\output\local\dropdown\status`
+or `core\output\local\action_menu\subpanel`.
+
+The `choicelist` class provides a way to define a list of options with additional information such as icons,
+descriptions, the currently selected option, or the ability to disable specific options.
+
+## Example Usage
+
+To create a `choicedropdown` form field, you need to:
+
+1. Create a new instance of the `choicelist` class.
+1. Add options and any extra information to the `choicelist` instance.
+1. Add the `choicedropdown` form field to the form, passing the `choicelist` instance.
+
+```php
+// Define the options for the dropdown list.
+$options = new core\output\choicelist();
+$options->add_option(
+    'option1',
+    "Text option 1",
+    [
+        'description' => 'Option 1 description',
+        'icon' => new pix_icon('t/hide', 'Eye icon 1'),
+    ]
+);
+$options->add_option(
+    'option2',
+    "Text option 2",
+    [
+        'description' => 'Option 2 description',
+        'icon' => new pix_icon('t/stealth', 'Eye icon 2'),
+    ]
+);
+$options->add_option(
+    'option3',
+    "Text option 3",
+    [
+        'description' => 'Option 3 description',
+        'icon' => new pix_icon('t/show', 'Eye icon 3'),
+    ]
+);
+
+// Add the choicedropdown field to the form.
+$mform->addElement(
+    'choicedropdown',
+    'FIELDNAME',
+    get_string('FIELDNAME', 'PLUGINNAME'),
+    $options,
+);
+$mform->setDefault('FIELDNAME', $defaultvalue);
+```

docs/apis/subsystems/form/index.md

@@ -154,9 +154,11 @@ Moodle provides a number of basic, and advanced, form elements. These are descri
 <!-- cspell:ignore choosecoursefile -->
 <!-- cspell:ignore modgrade -->
 <!-- cspell:ignore questioncategory -->
+<!-- cspell:ignore choicedropdown -->
 
 1. [Autocomplete](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete) - A select box that allows you to start typing to narrow the list of options, or search for results.
 1. [advcheckbox](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox) - Advance checkbox
+1. [choicedropdown](./form/fields/choicedropdown) - A dropdown menu where custom information is displayed on each option.
 1. [float](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float)
 1. [passwordunmask](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask) - A password element with option to show the password in plaintext.
 1. [recaptcha](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha)