{
 "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 `DatePicker` component provides an intuitive interface for date selection in your Panel applications. Whether you're building scheduling interfaces, data filtering controls, or time-based analytics dashboards, the DatePicker offers a polished and accessible solution for date input.\n",
    "\n",
    "The `DatePicker` component is built on the powerful [Material UI `DatePicker`](https://mui.com/x/react-date-pickers/date-picker/), ensuring a consistent and professional user experience across all platforms.\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",
    "* **`clearable`** (`boolean`, `default=True`): Whether users can clear the selected date, returning the value to `None`.\n",
    "* **`disabled`** (`boolean`, `default=False`): Whether the widget is interactive or read-only.\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`): When `True`, prevents selection of future dates.\n",
    "* **`disable_past`** (`boolean`): When `True`, prevents selection of past dates.\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",
    "* **`format`** (`str`, `default='YYYY-MM-DD'`): The display format of the date shown in the input field.\n",
    "* **`end`** (`datetime.date | datetime.date | str`): The latest selectable date in the calendar range  as a `date` or `datetime` object or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`open_to`** (`str`): The default calendar view to display when opened (e.g., 'year', 'month', 'day').\n",
    "* **`show_today_button`** (`boolean`, `default=False`): Whether to display a \"Today\" button for quick date selection.\n",
    "* **`start`** (`datetime.date | datetime.date | str`): The earliest selectable date in the calendar range as a `date` or `datetime` object or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n",
    "* **`value`** (`datetime.date | datetime.date | str`): The currently selected date as a `date` or `datetime` object or `str` in [ISO format](https://en.wikipedia.org/wiki/ISO_8601). Always returns a `date` object.\n",
    "* **`views`** (`list[str]`, `default=['year', 'month', 'day']`): Available calendar views for navigation and selection.\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": [
    "`DatePicker` allows selecting a date. The date can be provided as a `date` or `datetime` object or as an ISO string:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker = pmui.DatePicker(label='Date Picker', value=dt.date(2024, 4, 14), start=\"2024-04-01\")\n",
    "\n",
    "pmui.Row(date_picker, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To ensure the calendar dropdown is fully visible in a notebook environment, we've placed it in a `Row` with a fixed height.\n",
    "\n",
    "The `DatePicker.value` always returns a `datetime.date` object that can be read or programmatically set like other Panel widgets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Date Range Restrictions\n",
    "\n",
    "Control the selectable date range by setting `start` and/or `end` parameters. This is particularly useful for booking systems, event planning, or any scenario where date selection needs boundaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt_picker = pmui.DatePicker(\n",
    "    label='Date Picker',\n",
    "    start=dt.date(2024, 4, 1),\n",
    "    end=dt.date(2024, 4, 7),\n",
    "    value=dt.date(2024, 4, 1)\n",
    ")\n",
    "\n",
    "pmui.Row(dt_picker, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disable Past or Future Dates\n",
    "\n",
    "The `disable_past` and `disable_future` options provide convenient ways to limit date selection relative to today. Perfect for scheduling future appointments or selecting historical dates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "disable_past = pmui.DatePicker(\n",
    "    disable_past=True,\n",
    "    label='Date Picker (disable_past)',\n",
    ")\n",
    "\n",
    "disable_future = pmui.DatePicker(\n",
    "    disable_future=True,\n",
    "    label='Date Picker (disable_future)',\n",
    ")\n",
    "\n",
    "pmui.Row(disable_past, disable_future, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enabled Dates\n",
    "\n",
    "Use the `enabled_dates` parameter to restrict selection to specific dates only. This is ideal for availability calendars, appointment booking, or event-specific date selection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker = pmui.DatePicker(\n",
    "    label='Date Picker (enabled_dates)',\n",
    "    enabled_dates=[dt.date(2024, 4, i) for i in range(1, 7)],\n",
    "    value=dt.date(2024, 4, 1)\n",
    ")\n",
    "\n",
    "pmui.Column(date_picker, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled Dates\n",
    "\n",
    "The `disabled_dates` parameter allows you to exclude specific dates while keeping all others available. Useful for blocking holidays, maintenance days, or unavailable periods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_picker = pmui.DatePicker(\n",
    "    label='Date Picker (disabled_dates)',\n",
    "    disabled_dates=[dt.date(2024, 4, i) for i in range(2, 7)],\n",
    "    value=dt.date(2024, 4, 1)\n",
    ")\n",
    "\n",
    "pmui.Column(date_picker, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Clearable Behavior\n",
    "\n",
    "Control whether users can clear the selected date using the `clearable` parameter. When enabled, users can reset the value to `None` using the clear button:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.DatePicker(label='Clearable', value=\"2024-04-01\", clearable=True),\n",
    "    pmui.DatePicker(label='Not Clearable', value=\"2024-04-01\", clearable=False),\n",
    "    height=425\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Date Format Display\n",
    "\n",
    "Customize how dates appear in the input field using the `format` parameter. This affects only the display format, not the underlying value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(pmui.DatePicker(label='Custom Format', value=\"2024-04-01\", format=\"MM/DD/YYYY\"), height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calendar Views\n",
    "\n",
    "The DatePicker supports three navigation views: \"day\", \"month\", and \"year\". By default, all three views are enabled, allowing users to navigate efficiently between different time scales. Customize the available views using the `views` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.DatePicker(label='\"year\", \"month\" and \"day\"', value=\"2024-04-01\", views=[\"year\", \"month\", \"day\"]),\n",
    "    pmui.DatePicker(label='\"day\"', value=\"2024-04-01\", views=[\"day\"]),\n",
    "    pmui.DatePicker(label='\"month\" and \"year\"', value=\"2024-04-01\", views=[\"month\", \"year\"]),\n",
    "    pn.Spacer(height=425)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Initial Calendar View\n",
    "\n",
    "By default, the calendar opens to the \"day\" view. Use the `open_to` parameter to change which view appears first when users open the calendar:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.DatePicker(label='\"year\"', open_to=\"year\"),\n",
    "    pmui.DatePicker(label='\"month\"', open_to=\"month\", views=[\"year\", \"month\", \"day\"]),\n",
    "    height=425\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "The `color` parameter allows you to visually distinguish the `DatePicker` component when it's active or focused. This helps create a cohesive visual hierarchy in your application. Available color options include \"default\", \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", and \"danger\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    *[pmui.DatePicker(label=color, value=\"2024-04-01\", color=color) for color in pmui.ColorPicker.param.color.objects], pn.Spacer(height=425)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variant Styles\n",
    "\n",
    "The `variant` parameter controls the visual appearance of the input field, allowing you to match your application's design aesthetic. Choose from \"filled\", \"outlined\" (default), or \"standard\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.DatePicker(label='Date Picker', value=\"2024-04-01\", variant=\"filled\"),\n",
    "    pmui.DatePicker(label='Date Picker', value=\"2024-04-01\", variant=\"outlined\"),\n",
    "    pmui.DatePicker(label='Date Picker', value=\"2024-04-01\", variant=\"standard\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled and Loading States\n",
    "\n",
    "Like other widgets, the `DatePicker` can be disabled to prevent interaction and/or show a loading indicator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.DatePicker(label='Disabled and Loading', value=\"2024-04-01\", disabled=True, loading=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime as dt\n",
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "pn.extension()\n",
    "\n",
    "date_picker = pmui.DatePicker(label='Date Picker', value=dt.datetime(2024,7,1))\n",
    "\n",
    "def create_message(selected_date):\n",
    "    today = dt.date.today()\n",
    "    days_diff = (selected_date - today).days\n",
    "    weekday = selected_date.strftime(\"%A\")\n",
    "\n",
    "    if days_diff == 0:\n",
    "        time_desc = \"🎯 Today\"\n",
    "    elif days_diff == 1:\n",
    "        time_desc = \"⏭️ Tomorrow\"\n",
    "    elif days_diff == -1:\n",
    "        time_desc = \"⏮️ Yesterday\"\n",
    "    elif days_diff > 0:\n",
    "        time_desc = f\"⏳ In {days_diff} days\"\n",
    "    else:\n",
    "        time_desc = f\"⏪ {abs(days_diff)} days ago\"\n",
    "\n",
    "    return f\"\"\"\n",
    "    ### Selected Date: {selected_date.strftime(\"%B %d, %Y\")}\n",
    "\n",
    "    **Day of the week:** {weekday}  \n",
    "    **Relative to today:** {time_desc}  \n",
    "    **ISO format:** {selected_date.isoformat()}\n",
    "    \"\"\"\n",
    "\n",
    "message = pn.bind(create_message, date_picker)\n",
    "\n",
    "pmui.Column(date_picker, message, height=425)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "date_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",
    "**Material UI DatePicker:**\n",
    "- [Material UI DatePicker Reference](https://mui.com/x/react-date-pickers/date-picker/) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI DatePicker API](https://mui.com/x/api/date-pickers/date-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
}