{
 "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 `TextInput` widget allows entering any string using a text input box.\n",
    "\n",
    "Discover more on using widgets to add interactivity to your applications in the [how-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html). Alternatively, learn [how to set up callbacks and (JS-)links between parameters](https://panel.holoviz.org/how_to/links/index.html) or [how to use them as part of declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html).\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",
    "* **`enter_pressed`** (event): An event that triggers when the `<enter>` key is pressed.\n",
    "* **`value`** (str): The current value updated when pressing the `<enter>` key or when the widget loses focus because the user clicks away or presses the tab key.\n",
    "* **`value_input`** (str): The current value updated on every key press.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (str): The color variant of the inputs, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "* **`error_state`** (boolean): Indicates an invalid text entry.\n",
    "* **`max_length`** (int): The maximum number of allowed characters.\n",
    "* **`label`** (str): The title of the widget\n",
    "* **`placeholder`** (str): A placeholder string displayed when no value is entered.\n",
    "* **`size`** (`Literal[\"small\", \"medium\"]`): The size variant of the widget.\n",
    "* **`variant`** (`Literal[\"filled\", \"outlined\", \"standard\"]`): The variant of the input field.\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 `TextInput` widget provides a simple text entry form:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "text_input = pmui.TextInput(label='Some label')\n",
    "text_input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``TextInput.value`` returns a string type that can be read out and set like other widgets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "text_input.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Placeholder\n",
    "\n",
    "The `TextInput` widget provides a simple text entry form and supports a `placeholder` which is displayed when the `value` is empty:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.TextInput(label=\"Some label\", placeholder=\"Some placeholder\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Value Input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `TextInput.value` is updated after an `enter_pressed` event or when switching focus, i.e. when clicking or tabbing away from the widget. To get the current value after every keystroke you can inspect the `value_input` instead:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "value_input = pmui.TextInput(label='Value', value='Hello W')\n",
    "\n",
    "pmui.Column(\n",
    "    value_input,\n",
    "    pmui.Row(pmui.Typography(value_input.param.value), pmui.Typography(value_input.param.value_input))\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enter Pressed\n",
    "\n",
    "The `enter_pressed` parameter is triggered when ENTER key is pressed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "text_input_enter = pmui.TextInput(label=\"Press ENTER\")\n",
    "\n",
    "enter_count = pn.rx(0)\n",
    "def update_enter_count(event):\n",
    "    enter_count.rx.value += 1\n",
    "pn.bind(update_enter_count, text_input_enter.param.enter_pressed, watch=True)\n",
    "\n",
    "pmui.Column(text_input_enter, enter_count)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Maximum Length\n",
    "\n",
    "The `max_length` controls the maximum number of characters that can be entered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.TextInput(label='Name (max_length=12)', max_length=12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Error State\n",
    "\n",
    "Often times you will want to validate the input to a `TextInput`. To indicate that there is some error in the entry you can set the `error_state` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.TextInput(label='TextInput (invalid entry)', error_state=True)"
   ]
  },
  {
   "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": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "pmui.TextInput(\n",
    "    label='Text Input', disabled=True, loading=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "You can set the `color` parameter to visually distinguish the `TextInput` 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.TextInput(label=color, color=color) for color in pmui.TextInput.param.color.objects]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Size\n",
    "\n",
    "The `size` parameter allows toggling between \"small\", \"medium\" (default) and \"large\" sized input fields:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.TextInput(label='Small', size=\"small\"),\n",
    "    pmui.TextInput(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.TextInput(label='Filled', variant=\"filled\"),\n",
    "    pmui.TextInput(label='Outlined', variant=\"outlined\"),\n",
    "    pmui.TextInput(label='Standard', variant=\"standard\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Description Tooltip"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.TextInput(label='Some label', description=\"Some tooltip\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Search\n",
    "\n",
    "This example will search a list based on `value_input`:"
   ]
  },
  {
   "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",
    "VALUES = [\n",
    "    \"Hello\", \"Hello World\", \"Hello Panel Material UI\",\n",
    "    \"Hallo\", \"Hallo World\", \"Hallo Panel Material UI\",\n",
    "]\n",
    "\n",
    "search_text = pmui.TextInput(label='Search', placeholder='Search here')\n",
    "\n",
    "def search(text):\n",
    "    if text:\n",
    "        return [v for v in VALUES if text.lower() in v.lower()]\n",
    "    return VALUES\n",
    "\n",
    "pmui.Column(search_text, pn.bind(search, search_text.param.value_input),)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Input Form with Validation\n",
    "\n",
    "The form below requires you to enter a name 3 characters long or longer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import param\n",
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()\n",
    "\n",
    "class FormState(param.Parameterized):\n",
    "    value = param.String(default='', label=\"Name\", doc=\"Input value for the text field.\")\n",
    "    error_message = param.String(default='', doc=\"Error message for validation.\")\n",
    "\n",
    "    @pn.depends(\"value\")\n",
    "    def label(self):\n",
    "        if not self.error_message:\n",
    "            return \"Name\"\n",
    "        return f\"Name ({self.error_message})\"\n",
    "\n",
    "    @pn.depends(\"value\")\n",
    "    def error_state(self):\n",
    "        return bool(self.error_message)\n",
    "    \n",
    "    @pn.depends(\"value\", \"error_message\")\n",
    "    def validated_value(self):\n",
    "        if not self.value or self.error_message:\n",
    "            return None\n",
    "        return f\"Valid value: **{self.value}**\"\n",
    "    \n",
    "    @param.depends('value', watch=True)\n",
    "    def validate_value(self):\n",
    "        if len(self.value) < 3:\n",
    "            self.error_message = \"Must be at least 3 characters\"\n",
    "        else:\n",
    "            self.error_message = \"\"\n",
    "    \n",
    "\n",
    "state = FormState()\n",
    "\n",
    "text_input = pmui.TextInput(value=state.value, label=state.label, placeholder='Enter your name...', error_state=state.error_state)\n",
    "\n",
    "def set_value(event):\n",
    "    state.value = text_input.value\n",
    "\n",
    "submit_button = pmui.Button(label='Submit', color='primary', on_click=set_value)\n",
    "\n",
    "pmui.Column(\n",
    "    \"## TextInput Form\",\n",
    "    text_input,\n",
    "    submit_button,\n",
    "    state.validated_value,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.TextInput(\n",
    "    label='TextInput'\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 TextField Reference](https://mui.com/material-ui/react-text-field) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI TextField API](https://mui.com/material-ui/api/text-field/) - 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.13.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}