{
 "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 `DatetimePicker` widget allows selecting selecting a datetime value using a text box and the browser's datetime-picking utility.\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",
    "* **`clearable`** (`boolean`, `default=False`): If true, allows the date to be cleared.\n",
    "* **`disabled`** (`boolean`, `default=False`): Whether the widget is editable\n",
    "* **`disabled_dates`** (`list[datetime.date | datetime.datetime | str]`): dates to make unavailable for selection; others will be available. Specified as list of `datetime`, `date` or `str` objects in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`disable_future`** (`boolean`): If true, future dates are disabled.\n",
    "* **`disable_past`** (`boolean`): If true, past dates are disabled.\n",
    "* **`enabled_dates`** (`list[datetime.date | datetime.datetime | str]`): Dates to make available for selection; others will be unavailable. Specified as list of `datetime`, `date` or `str` objects in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`enable_time`** (`boolean`): Enable editing of the time in the widget, default is True\n",
    "* **`enable_seconds`** (`boolean`): Enable editing of seconds in the widget, default is True\n",
    "* **`end`** (`datetime.date | datetime.datetime | str`): Inclusive upper bound of the allowed date selection as a `datetime` or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`format`** (`str`):The format of the datetime displayed in the input (by default depends on `military_time`).\n",
    "* **`military_time`** (`boolean`): Enable 24 hours time in the widget, default is True\n",
    "* **`start`** (`datetime.datetime | datetime.date | str`): Inclusive lower bound of the allowed date selection as a datetime or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`value`** (`datetime.datetime | datetime.date | str`): The selected value as a `datetime` or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601). Always returns a `datetime` object.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`label`** (str): The title of the widget\n",
    "* **`visible`** (boolean): Whether the widget is visible\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 certain parameters are allowed as aliases:\n",
    "\n",
    "- **`button_style`**: Alias for `variant`\n",
    "- **`button_type`**: Alias for `color`\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "`DatetimePicker` allows selecting a date and time. The datetime can be provided as a datetime object or as an ISO string and supports optional `start` and `end` bounds:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_picker = pmui.DatetimePicker(\n",
    "    label='Datetime Picker', value=dt.datetime(2021, 3, 2, 12, 10), start='2021-03-01 00:00', end='2021-03-31 00:00'\n",
    ")\n",
    "\n",
    "pmui.Column(datetime_picker, height=450)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To ensure it is visible in a notebook we have placed it in a `Column` with a fixed height.\n",
    "\n",
    "`DatetimePicker.value` always returns a `datetime` type that can be read out or set like other widgets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_picker.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Time format\n",
    "\n",
    "The time format is controlled by the `format` and `military_time` options. The former controls how the time is displayed once selected while the latter controls whether the picker displays a 12 hour or 24 hour clock:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_12h = pmui.DatetimePicker(\n",
    "    label='Datetime Picker', military_time=False, value=dt.datetime(2021, 3, 2, 12, 10)\n",
    ")\n",
    "\n",
    "datetime_24h = pmui.DatetimePicker(\n",
    "    label='Datetime Picker', military_time=False, value=dt.datetime(2021, 3, 2, 12, 10), format='YY-MM-DD hh:mm a'\n",
    ")\n",
    "\n",
    "datetime_seconds = pmui.DatetimePicker(\n",
    "    label='Datetime Picker', enable_seconds=True, value=dt.datetime(2021, 3, 2, 12, 10, 32)\n",
    ")\n",
    "\n",
    "pmui.Row(datetime_picker, datetime_24h, datetime_seconds, height=450)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Limiting to a calendar range\n",
    "\n",
    "The range of selectable dates can be limited by setting `start` and/or `end`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt_picker = pmui.DatetimePicker(\n",
    "    label='Date Time Picker',\n",
    "    start=dt.datetime(2024, 4, 1, 0, 0),\n",
    "    end=dt.datetime(2024, 4, 7, 0, 0),\n",
    "    value=dt.datetime(2024, 4, 1, 11, 37)\n",
    ")\n",
    "\n",
    "pmui.Row(dt_picker, height=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disable Past or Future\n",
    "\n",
    "The `disable_past` and `disable_future` options make it easy to limit the selectable dates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "disable_past = pmui.DatetimePicker(\n",
    "    disable_past=True,\n",
    "    label='Date Time Picker (disable_past)',\n",
    ")\n",
    "\n",
    "disable_future = pmui.DatetimePicker(\n",
    "    disable_future=True,\n",
    "    label='Date Time Picker (disable_future)',\n",
    ")\n",
    "\n",
    "pmui.Row(disable_past, disable_future, height=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enabled Dates\n",
    "\n",
    "The `enabled_dates` option allows limiting the dates that can be selected to a specific subset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker = pmui.DatetimePicker(\n",
    "    label='Date Time Picker (enabled_dates)',\n",
    "    enabled_dates=[dt.datetime(2024, 4, i, 12, 37) for i in range(1, 7)],\n",
    "    value=dt.datetime(2024, 4, 1, 11, 37)\n",
    ")\n",
    "\n",
    "pmui.Column(date_picker, height=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled Dates\n",
    "\n",
    "The `disabled_dates` option allows excluding specific dates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker = pmui.DatetimePicker(\n",
    "    label='Date Time Picker (disabled_dates)',\n",
    "    disabled_dates=[dt.datetime(2024, 4, i, 12, 37) for i in range(2, 7)],\n",
    "    value=dt.datetime(2024, 4, 1, 11, 37)\n",
    ")\n",
    "\n",
    "pmui.Column(date_picker, height=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Controls\n",
    "\n",
    "The `DatetimePicker` 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.Row(datetime_picker.api(jslink=True), datetime_picker)"
   ]
  },
  {
   "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 DatetimePicker:**\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
}