{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Select` widget is used for collecting user provided information from a list or dictionary of `options` via a dropdown menu or selection area. Its built upon the [Material UI Select](https://mui.com/material-ui/react-select/) component.\n",
    "\n",
    "The `Select` widget falls into the broad category of single-value, option-selection widgets that provide a compatible API and include the [`RadioBoxGroup`](RadioBoxGroup.ipynb), [`AutocompleteInput`](AutocompleteInput.ipynb) and [`DiscreteSlider`](DiscreteSlider.ipynb) widgets.\n",
    "\n",
    "Explore more about using widgets to add interactivity to your applications in the [Make your component interactive](https://panel.holoviz.org/how_to/interactivity/index.html), [Link Parameters](https://panel.holoviz.org/how_to/links/index.html) or \n",
    "[Declarative API](https://panel.holoviz.org/how_to/param/index.html) guides.\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "For details on other options for customizing the component, see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`disabled`** (boolean): Whether the widget is editable.\n",
    "* **`disabled_options`** (list): Optional list of `options` that are disabled, i.e., unusable and un-clickable. If `options` is a dictionary, the list items must be dictionary values.\n",
    "* **`filter_on_search`** (boolean): Whether to filter or highlight the matching options on search.\n",
    "* **`filter_str`** (str): Filter string for the dropdown.\n",
    "* **`groups`** (dict): A dictionary whose keys are used to visually group the options and whose values are either a list or a dictionary of options to select from. Mutually exclusive with `options` and valid only if `size` is 1.\n",
    "* **`options`** (list or dict): A list or dictionary of options to select from.\n",
    "* **`searchable`** (boolean): Whether to render a search box.\n",
    "* **`value`** (object): The current value; must be one of the option values.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`bookmarks`** (list): List of bookmarked options that are rendered first.\n",
    "* **`color`** (str): The color variant of the input, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "* **`dropdown_open`** (bool): Whether the dropdown is open.\n",
    "* **`dropdown_height`** (int): Height of the dropdown menu.\n",
    "* **`label`** (str): The title of the widget.\n",
    "* **`variant`** (str): One of filled, outlined (default), or standard.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (dict): Component-level styling API.\n",
    "- **`theme_config`** (dict): Theming API.\n",
    "\n",
    "##### Aliases\n",
    "\n",
    "For compatibility with Panel, certain parameters are allowed as aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "The `Select` widget allows selecting from a list of `options`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "select = pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], height=200)\n",
    "\n",
    "select"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like most other widgets, ``Select`` has a value parameter that can be accessed or set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "select.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `options` parameter also accepts a dictionary whose keys are going to be the labels of the dropdown menu. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "select = pmui.Select(label='Age', options={'Ten': 10, 'Twenty': 20, 'Thirty': 30}, height=200)\n",
    "\n",
    "select"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "select.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Updating the value will display the right label."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "select.value = 30"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filled and Standard Variants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], variant=\"standard\"),\n",
    "    pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], variant=\"filled\"),\n",
    "    height=200\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Colors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.FlexBox(*[pmui.Select(label=color, options=['Ten', 'Twenty', 'Thirty'], color=color) for color in pmui.Select.param.color.objects])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The color will show when you select a select widget."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Other Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], disabled=True, loading=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Searchable\n",
    "\n",
    "You can make the `Select` widget `searchable`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True, height=250)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can configure whether options are filtered or merely highlighted on search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True, filter_on_search=True),\n",
    "    pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True, filter_on_search=False),\n",
    "    height=250\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may provide a default string to filter on:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty'], searchable=True, filter_str=\"F\", height=250)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dropdown Height and Open State\n",
    "\n",
    "You may control the `dropdown_height` and the `drowdown_open` state programmatically:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty'], dropdown_height=200, dropdown_open=False, height=250)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled Options\n",
    "\n",
    "A subset of the displayed items can be disabled with `disabled_options`. The widget `value` cannot be set to one of the `disabled_options`, either programmatrically or with the user interface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty'], disabled_options=['Twenty'], height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grouping\n",
    "\n",
    "The items displayed in the dropdown menu can be grouped visually (also known as *optgroup*) by setting the `groups` parameter **instead of** `options`. `groups` accepts a dictionary whose keys are used to group the options and whose values are defined similarly to how `options` are defined."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "grouped = pmui.Select(label='Select', groups={'Europe': ['Greece', 'France'], 'Africa': ['Algeria', 'Congo']}, height=300)\n",
    "\n",
    "grouped"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bookmarks\n",
    "\n",
    "Options can also be set as `bookmarks` which moves them to the top of the list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty'], bookmarks=['Ten', 'Fourty'], height=250)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `Select` widget exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Select(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty']).api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References\n",
    "\n",
    "**Panel Documentation:**\n",
    "\n",
    "- [How-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html) - Learn how to add interactivity to your applications using widgets\n",
    "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html) - Connect parameters between components and create reactive interfaces\n",
    "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html) - Build parameter-driven applications\n",
    "\n",
    "**Material UI Select:**\n",
    "\n",
    "- [Material UI Select Reference](https://mui.com/material-ui/react-select/) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Select API](https://mui.com/material-ui/api/select/) - Detailed API reference and configuration options"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}