{
 "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 `DatetimeRangePicker` allows selecting a datetime range using a calendar-based picker with two months displayed side by side and time inputs for the start and end times. It extends the `DateRangePicker` with time selection capabilities.\n",
    "\n",
    "The `DatetimeRangePicker` is built on [react-day-picker](https://daypicker.dev/) and styled to integrate with Material UI's theming system.\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "For comprehensive customization options, see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`disabled`** (`boolean`, `default=False`): Whether the widget is interactive or read-only.\n",
    "* **`disabled_dates`** (`list[datetime.date | str]`): Dates to make unavailable for selection.\n",
    "* **`enable_seconds`** (`boolean`, `default=True`): Enable editing of seconds in the time inputs.\n",
    "* **`enabled_dates`** (`list[datetime.date | str]`): Dates to make available for selection; others will be unavailable.\n",
    "* **`end`** (`datetime.datetime | str`): The latest selectable datetime.\n",
    "* **`format`** (`str`): The display format of the datetimes shown in the input field. Auto-set based on `military_time`.\n",
    "* **`military_time`** (`boolean`, `default=True`): Whether to display time in 24-hour format.\n",
    "* **`start`** (`datetime.datetime | str`): The earliest selectable datetime.\n",
    "* **`value`** (`tuple[datetime.datetime, datetime.datetime]`): The selected datetime range as a tuple.\n",
    "* **`value_start`** (`datetime.date`, readonly): The lower value of the selected range.\n",
    "* **`value_end`** (`datetime.date`, readonly): The upper value of the selected range.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`label`** (str): The descriptive text displayed above the input field.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`color`** (str): Visual theme color. Choose from \"default\" (default), \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", or \"danger\".\n",
    "- **`sx`** (dict): Component-level styling API for fine-grained customization.\n",
    "- **`theme_config`** (dict): Theming API for consistent design system integration.\n",
    "- **`variant`** (str): Input field style variant. Choose from \"filled\", \"outlined\" (default), or \"standard\".\n",
    "\n",
    "##### Aliases\n",
    "\n",
    "For compatibility with existing Panel code, certain parameters have aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`DatetimeRangePicker` allows selecting a datetime range by clicking dates and setting times:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_range_picker = pmui.DatetimeRangePicker(\n",
    "    label='Datetime Range Picker',\n",
    "    value=(dt.datetime(2024, 4, 5, 9, 0), dt.datetime(2024, 4, 15, 17, 30)),\n",
    "    start=dt.datetime(2024, 4, 1),\n",
    "    end=dt.datetime(2024, 6, 30),\n",
    "    width=400\n",
    ")\n",
    "\n",
    "pmui.Row(datetime_range_picker, height=475)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `DatetimeRangePicker.value` returns a tuple of `datetime.datetime` objects:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_range_picker.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Military Time\n",
    "\n",
    "By default, the time inputs use 24-hour format. Set `military_time=False` for 12-hour (AM/PM) display:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ampm_picker = pmui.DatetimeRangePicker(\n",
    "    label='12-Hour Format',\n",
    "    value=(dt.datetime(2024, 4, 5, 9, 0), dt.datetime(2024, 4, 15, 17, 30)),\n",
    "    military_time=False\n",
    ")\n",
    "\n",
    "pmui.Row(ampm_picker, height=475)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enable Seconds\n",
    "\n",
    "Control whether seconds are editable with `enable_seconds`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "no_seconds = pmui.DatetimeRangePicker(\n",
    "    label='Without Seconds',\n",
    "    value=(dt.datetime(2024, 4, 5, 9, 0), dt.datetime(2024, 4, 15, 17, 30)),\n",
    "    enable_seconds=False\n",
    ")\n",
    "\n",
    "pmui.Row(no_seconds, height=475)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Date Range Restrictions\n",
    "\n",
    "Control the selectable date range by setting `start` and/or `end` parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "restricted = pmui.DatetimeRangePicker(\n",
    "    label='Restricted Range',\n",
    "    start=dt.datetime(2024, 4, 1),\n",
    "    end=dt.datetime(2024, 4, 30, 23, 59, 59),\n",
    "    value=(dt.datetime(2024, 4, 5, 8, 0), dt.datetime(2024, 4, 20, 18, 0))\n",
    ")\n",
    "\n",
    "pmui.Row(restricted, height=475)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "The `color` parameter allows you to visually distinguish the `DatetimeRangePicker` component:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    *[pmui.DatetimeRangePicker(\n",
    "        label=color,\n",
    "        value=(dt.datetime(2024, 4, 1, 9, 0), dt.datetime(2024, 4, 15, 17, 0)),\n",
    "        color=color\n",
    "    ) for color in ['primary', 'secondary', 'error', 'info', 'success', 'warning']],\n",
    "    pn.Spacer(height=475)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variant Styles\n",
    "\n",
    "The `variant` parameter controls the visual appearance of the input field:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.DatetimeRangePicker(label='Filled', value=(dt.datetime(2024, 4, 1, 9, 0), dt.datetime(2024, 4, 15, 17, 0)), variant='filled'),\n",
    "    pmui.DatetimeRangePicker(label='Outlined', value=(dt.datetime(2024, 4, 1, 9, 0), dt.datetime(2024, 4, 15, 17, 0)), variant='outlined'),\n",
    "    pmui.DatetimeRangePicker(label='Standard', value=(dt.datetime(2024, 4, 1, 9, 0), dt.datetime(2024, 4, 15, 17, 0)), variant='standard'),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled State\n",
    "\n",
    "The widget can be disabled with `disabled=True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.DatetimeRangePicker(\n",
    "    label='Disabled',\n",
    "    value=(dt.datetime(2024, 4, 1, 9, 0), dt.datetime(2024, 4, 15, 17, 0)),\n",
    "    disabled=True\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_range_picker.api(jslink=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References\n",
    "\n",
    "**Panel Documentation:**\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",
    "**react-day-picker:**\n",
    "- [react-day-picker Documentation](https://daypicker.dev/) - Complete documentation for the underlying calendar component"
   ]
  }
 ],
 "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
}