{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `AutocompleteInput` widget enhances a standard text input by providing a panel of suggested options as you type. This widget is ideal in two main scenarios:\n",
    "\n",
    "- When the input must be selected from a predefined set of valid values, such as a location field requiring a recognized location name.\n",
    "- When any value is allowed, but offering suggestions—such as previous searches or similar terms—can help users save time and reduce errors.\n",
    "\n",
    "`AutocompleteInput` belongs to the family of single-value, option-selection widgets, which also includes [`RadioBoxGroup`](RadioBoxGroup.ipynb), [`Select`](Select.ipynb), and [`DiscreteSlider`](DiscreteSlider.ipynb). These widgets share a consistent API for ease of use.\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "For more details on customization, see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`disabled`** (bool): If True, the widget is not editable.\n",
    "* **`case_sensitive`** (bool, default=True): Controls whether matching is case sensitive.\n",
    "* **`lazy_search`** (bool, default=False): If True, search queries are sent to the backend for processing.\n",
    "* **`min_characters`** (int, default=2): Minimum number of characters required before suggestions appear.\n",
    "* **`options`** (list or dict): The set of selectable options, provided as a list or dictionary.\n",
    "* **`restrict`** (bool, default=True): If False, users can enter values not present in the options list.\n",
    "* **`search_strategy`** (str): Determines how suggestions are matched. \"starts_with\" (default) matches from the beginning; \"includes\" matches any substring.\n",
    "* **`value`** (str): The selected value, updated when the user presses <enter>. If `restrict=True`, must be one of the options.\n",
    "* **`value_input`** (str): The current input value, updated on every key press.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`label`** (str): The widget's title.\n",
    "* **`size`** (`Literal[\"small\", \"medium\"]`): Whether the input field is \"small\" or \"medium\" sized.\n",
    "* **`placeholder`** (str): Text shown when no value is selected.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`color` (str)**: Choose from \"default\" (default), \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", or \"danger\".\n",
    "- **`sx`** (dict): Component-level styling options.\n",
    "- **`theme_config`** (dict): Theming options.\n",
    "- **`variant`** (str): Choose from \"filled\", \"outlined\" (default), or \"standard\".\n",
    "\n",
    "##### Aliases\n",
    "\n",
    "For compatibility with Panel, some parameters have aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "In its simplest form, `AutocompleteInput` lets users select a value from a predefined list of options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "autocomplete = pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', options=['Biology', 'Chemistry', 'Physics'], color='warning'\n",
    ")\n",
    "\n",
    "pmui.Row(autocomplete, height=125)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The available options appear as you start typing parts of the options in the list like \"Bi\", \"Ch\" or \"Ph\".\n",
    "\n",
    "- The `value` parameter shows the currently selected option (updated when you press <enter> or select an option).\n",
    "- The `value_input` parameter reflects the text currently entered or highlighted in the input field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pmui.Row(autocomplete.param.value, autocomplete.param.value_input)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try typing \"Ph\" in the AutocompleteInput above, then select \"Physics\". Notice how the `value` parameter updates only when you make a selection, while `value_input` reflects your current input."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using a Dictionary for Options\n",
    "\n",
    "You can also provide the `options` parameter as a dictionary. The keys will be displayed as labels in the dropdown menu, while the values are the actual option values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "options_dict = pmui.AutocompleteInput(label='Autocomplete', options={'Biology': 1, 'Chemistry': 2, 'Physics': 3})\n",
    "\n",
    "pmui.Row(options_dict, height=125)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the label is shown when no value is selected.\n",
    "\n",
    "Let's observe how the `value` and `value_input` parameters change as you type and select a value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(options_dict.param.value, options_dict.param.value_input)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Placeholder\n",
    "\n",
    "You can set a `placeholder` to display helpful guidance in the input field when no value is selected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', placeholder=\"Enter a value\", options=['Biology', 'Chemistry', 'Physics'],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Case Sensitivity\n",
    "\n",
    "Control whether the filter is case sensitive using the `case_sensitive` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "case_insensitive = pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', case_sensitive=False, options=['Biology', 'Chemistry', 'Physics'],\n",
    ")\n",
    "\n",
    "pmui.Row(case_insensitive, height=125)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, the option \"Physics\" will appear regardless of whether you type \"ph\", \"pH\", \"Ph\", or \"PH\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Minimum Characters Required\n",
    "\n",
    "You can adjust the minimum number of characters a user must type before suggestions appear using the `min_characters` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "min_characters = pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', min_characters=0, options=['Biology', 'Chemistry', 'Physics'],\n",
    ")\n",
    "\n",
    "pmui.Row(min_characters, height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Search Strategy\n",
    "\n",
    "By default, `search_strategy` is set to \"starts_with\". You can change it to \"includes\" to match any part of the option string.\n",
    "\n",
    "Try entering \"aa\", \"bb\", \"cc\", or \"zz\" to see how the matching works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "search_strategy = pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', search_strategy=\"includes\", options=['aabbcc', 'bbaacc', 'zzaabb'],\n",
    ")\n",
    "\n",
    "pmui.Row(search_strategy, height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try entering \"aa\", \"bb\", \"cc\" or \"zz\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Lazy Search\n",
    "\n",
    "When working with a huge number of options it is sometimes not feasible to send all the options to the frontend. Instead we may want to perform the search on the server and only return the results. This behavior can be enabled by setting `lazy_search=True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "N = 5000\n",
    "options = [f\"Item {i:04d}\" for i in range(1, N + 1)]\n",
    "\n",
    "lazy_autocomplete = pmui.AutocompleteInput(\n",
    "    name=\"Search items\",\n",
    "    options=options,\n",
    "    placeholder=\"Start typing (e.g. 'Item 0123')\",\n",
    "    case_sensitive=False,\n",
    "    lazy_search=True\n",
    ")\n",
    "\n",
    "pmui.Row(lazy_autocomplete, height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Restrict Input\n",
    "\n",
    "Control whether users can enter values not present in the options list using the `restrict` parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If `restrict=False`, the `AutocompleteInput` will allow any input, not just the provided options. This is useful when you want to suggest completions but not limit user input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "not_restricted = autocomplete.clone(value='Mathematics', restrict=False, options=['Biology', 'Chemistry', 'Physics'])\n",
    "\n",
    "pmui.Row(not_restricted, height=125)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's observe how the `value` parameter updates as you enter custom values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pn.pane.Str(not_restricted.param.value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled and Loading\n",
    "\n",
    "Like other widgets, the `AutocompleteInput` can be disabled and/or show a loading indicator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', disabled=True, loading=True, options=['Biology', 'Chemistry', 'Physics'],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "You can set the `color` parameter to visually distinguish the `AutocompleteInput` when active. Available options include \"default\", \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", and \"danger\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    *[pmui.AutocompleteInput(label=color, color=color) for color in pmui.AutocompleteInput.param.color.objects]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Size\n",
    "\n",
    "The `size` parameter allows toggling between \"small\" and \"medium\" (default) sized input fields:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.AutocompleteInput(label='Small', size=\"small\"),\n",
    "    pmui.AutocompleteInput(label='Medium', size=\"medium\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variant\n",
    "\n",
    "The `variant` parameter controls the visual style of the input. Choose from \"filled\", \"outlined\" (default), or \"standard\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.AutocompleteInput(label='Filled', variant=\"filled\"),\n",
    "    pmui.AutocompleteInput(label='Outlined', variant=\"outlined\"),\n",
    "    pmui.AutocompleteInput(label='Standard', variant=\"standard\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Favorite Programming Language\n",
    "\n",
    "Lets create a self contained example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()\n",
    "\n",
    "programming_languages = [\n",
    "    \"Python\", \"JavaScript\", \"Java\", \"C++\", \"C#\", \"Go\", \"Rust\", \n",
    "    \"TypeScript\", \"Swift\", \"Kotlin\", \"Ruby\", \"PHP\", \"Scala\", \n",
    "    \"R\", \"MATLAB\", \"Julia\", \"Perl\", \"Haskell\", \"Clojure\"\n",
    "]\n",
    "\n",
    "language_input = pmui.AutocompleteInput(\n",
    "    label=\"Favorite Programming Language\",\n",
    "    options=programming_languages,\n",
    "    placeholder=\"Start typing a programming language...\",\n",
    "    width=300\n",
    ")\n",
    "\n",
    "def create_text(value):\n",
    "    if not value:\n",
    "        return \"No programming language selected\"\n",
    "    if value==\"Python\":\n",
    "        return \"🐍 **Python** is a great choice!\"\n",
    "    return f\"Your favorite programming language is **{value}**\"\n",
    "\n",
    "text = pn.bind(create_text, language_input)\n",
    "\n",
    "pn.Column(\"*Type in the field below to see autocomplete suggestions*\", language_input, text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.AutocompleteInput(\n",
    "    label='Autocomplete Input', options=['Biology', 'Chemistry', 'Physics'],\n",
    ").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 AutoComplete:**\n",
    "\n",
    "- [Material UI AutoComplete Reference](https://mui.com/material-ui/react-autocomplete) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI AutoComplete API](https://mui.com/material-ui/api/autocomplete/) - 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
}