{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime as dt\n",
    "\n",
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `TimePicker` widget allows entering a time value as text or `datetime.time`. \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",
    "* **`end`** (str | datetime.time): Inclusive upper bound of the allowed time selection\n",
    "* **`start`** (str | datetime.time): Inclusive lower bound of the allowed time selection\n",
    "* **`value`** (str | datetime.time): The current value\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`clock`** (str): Whether to use 12 hour or 24 hour clock. Default is `'12h'`.\n",
    "* **`format`** (str): Formatting specification for the display of the picked date.\n",
    "    ```\n",
    "    +----+------------------------------------+------------+\n",
    "    | H  | Hours                              | 0 to 23    |\n",
    "    | HH | Hours, 2-digits                    | 00 to 23   |\n",
    "    | h  | Hours, 12-hour clock               | 1 to 12    |\n",
    "    | hh | Hours, 12-hour clock, 2-digits     | 1 to 12    |\n",
    "    | m  | Minutes                            | 0 to 59    |\n",
    "    | mm | Minutes                            | 00 to 59   |\n",
    "    | s  | Seconds                            | 0, 1 to 59 |\n",
    "    | ss | Seconds                            | 00 to 59   |\n",
    "    | a  | am/pm, lower-case                  | am or pm   |\n",
    "    | A  | AM/PM, upper-cas                   | AM or PM   |\n",
    "    +----+------------------------------------+------------+\n",
    "    ```\n",
    "    See also https://day.js.org/docs/en/parse/string-format.\n",
    "* **`hour_increment`** (int): The time steps between two hour options. Default is 1.\n",
    "* **`minute_increment`** (int): The time steps between two minure options. Default is 1.\n",
    "* **`mode`** (`Literal[\"digital\", \"analog\", \"auto\"]`): Whether to render a digital or analog clock. By default automatically switches between digital clock on desktop to analog clock on mobile.\n",
    "* **`label`** (str): The title of the widget\n",
    "* **`second_increment`** (int): The time steps between two second options. Default is 1.\n",
    "* **`seconds`** (bool): Allows to select seconds. By default, only hours and minutes are selectable, and AM/PM depending on the `clock` option. Default is False.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`color`** (str): A color variant `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "- **`sx`** (dict): Component level styling API.\n",
    "- **`theme_config`** (dict): Theming API.\n",
    "* **`variant`** (`Literal[\"filled\", \"outlined\", \"standard\"]`): The variant of the input field.\n",
    "\n",
    "##### Aliases\n",
    "\n",
    "For compatibility with Panel certain parameters are allowed as aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "##### Unsupported\n",
    "\n",
    "Options implemented by the `panel.widgets.TimePicker` widget but not `panel_material_ui.TimePicker`:\n",
    "\n",
    "- **`hour_step`** (int): Defines the granularity of hour value increments in the UI.\n",
    "- **`minute_step`** (int): Defines the granularity of minute value increments in the UI.\n",
    "- **`seconds_step`** (int): Defines the granularity of second value increments in the UI.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "The `TimePicker` widget allows selecting a time of day."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "time_picker = pmui.TimePicker(label='Time Picker', value=dt.datetime.now().time())\n",
    "\n",
    "pmui.Column(time_picker, height=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Either `datetime.time` or `str` can be used as input and `TimePicker` can be bounded by a start and end time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "time_picker = pmui.TimePicker(label='Time Picker', value=\"08:25\", start='00:00', end='12:00')\n",
    "\n",
    "pmui.Column(time_picker, height=380)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 24-hour Clock\n",
    "\n",
    "By default the `TimePicker` uses a 12-hour clock picker, but this may be changed to a '24h' clock."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "time_picker_12 = pmui.TimePicker(\n",
    "    label='Time Picker (12h)', value=\"08:28\", start='00:00', end='12:00', clock='12h'\n",
    ")\n",
    "time_picker_24 = pmui.TimePicker(\n",
    "    label='Time Picker (24h)', value=\"08:28\", start='00:00', end='12:00', clock='24h'\n",
    ")\n",
    "\n",
    "pmui.Row(time_picker_12, time_picker_24, height=380)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Format\n",
    "\n",
    "The formatting of the text field can be set independently from the clock. It follows the [day.js](https://day.js.org/docs/en/parse/string-format) string formatting options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "time_picker_leading_zero = pmui.TimePicker(\n",
    "    label='Time Picker', value=\"08:28\", start='00:00', end='12:00', format=\"HH:MM:ss\", seconds=True\n",
    ")\n",
    "time_picker_no_zeros = pmui.TimePicker(\n",
    "    label='Time Picker', value=\"08:28\", start='00:00', end='12:00', format=\"H:M:s\", seconds=True\n",
    ")\n",
    "\n",
    "pmui.Row(time_picker_leading_zero, time_picker_no_zeros, height=380)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mode\n",
    "\n",
    "By default the `TimePicker` will render as a digital clock on desktop environments and switch to a clock popup in mobile environments.\n",
    "\n",
    "To switch explicitly switch between the two set the `mode`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.TimePicker(label='Analog', mode=\"analog\"),\n",
    "    pmui.TimePicker(label='Digital', mode=\"digital\"),\n",
    "    height=360\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "You can set the `color` parameter to visually distinguish the `TimePicker` 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.TimePicker(label=color, color=color) for color in pmui.TimePicker.param.color.objects]\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.TimePicker(label='Filled', variant=\"filled\"),\n",
    "    pmui.TimePicker(label='Outlined', variant=\"outlined\"),\n",
    "    pmui.TimePicker(label='Standard', variant=\"standard\"),\n",
    "    height=360\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "The `TimePicker` 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.TimePicker(label='TimePicker').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 TimePicker:**\n",
    "\n",
    "- [Material UI TimePicker Reference](https://mui.com/x/api/date-pickers/date-time-picker/) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI TimePicker API](https://mui.com/x/api/date-pickers/date-time-picker/) - 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
}