{
  "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 `DateRangePicker` allows selecting a date range using a calendar-based picker with two months displayed side by side. It provides an intuitive way to select start and end dates for filtering, scheduling, or analytics.\n",
        "\n",
        "The `DateRangePicker` 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",
        "* **`enabled_dates`** (`list[datetime.date | str]`): Dates to make available for selection; others will be unavailable.\n",
        "* **`end`** (`datetime.date | str`): The latest selectable date.\n",
        "* **`format`** (`str`, `default='YYYY-MM-DD'`): The display format of the dates shown in the input field.\n",
        "* **`start`** (`datetime.date | str`): The earliest selectable date.\n",
        "* **`value`** (`tuple[datetime.date, datetime.date]`): The selected date range as a tuple of two dates.\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": [
        "`DateRangePicker` allows selecting a date range by clicking a start and end date on the calendar:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "date_range_picker = pmui.DateRangePicker(\n",
        "    label='Date Range Picker',\n",
        "    value=(dt.date(2024, 4, 5), dt.date(2024, 4, 15)),\n",
        "    start=dt.date(2024, 4, 1),\n",
        "    end=dt.date(2024, 6, 30)\n",
        ")\n",
        "\n",
        "pmui.Row(date_range_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 `DateRangePicker.value` returns a tuple of `datetime.date` objects:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "date_range_picker.value"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "You can also access the individual bounds via `value_start` and `value_end`:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "date_range_picker.value_start, date_range_picker.value_end"
      ]
    },
    {
      "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.DateRangePicker(\n",
        "    label='Restricted Range',\n",
        "    start=dt.date(2024, 4, 1),\n",
        "    end=dt.date(2024, 4, 30),\n",
        "    value=(dt.date(2024, 4, 5), dt.date(2024, 4, 20))\n",
        ")\n",
        "\n",
        "pmui.Row(restricted, height=425)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Enabled Dates\n",
        "\n",
        "Use the `enabled_dates` parameter to restrict selection to specific dates only:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "enabled = pmui.DateRangePicker(\n",
        "    label='Only Weekdays',\n",
        "    enabled_dates=[dt.date(2024, 4, i) for i in range(1, 30) if dt.date(2024, 4, i).weekday() < 5],\n",
        "    value=(dt.date(2024, 4, 1), dt.date(2024, 4, 5))\n",
        ")\n",
        "\n",
        "pmui.Row(enabled, 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:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "disabled_picker = pmui.DateRangePicker(\n",
        "    label='No Weekends',\n",
        "    disabled_dates=[dt.date(2024, 4, i) for i in range(1, 30) if dt.date(2024, 4, i).weekday() >= 5],\n",
        "    value=(dt.date(2024, 4, 1), dt.date(2024, 4, 12))\n",
        ")\n",
        "\n",
        "pmui.Row(disabled_picker, height=425)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Date Format Display\n",
        "\n",
        "Customize how dates appear in the input field using the `format` parameter:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.Row(\n",
        "    pmui.DateRangePicker(label='Custom Format', value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), format='MM/DD/YYYY'),\n",
        "    height=425\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Color Options\n",
        "\n",
        "The `color` parameter allows you to visually distinguish the `DateRangePicker` component:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.FlexBox(\n",
        "    *[pmui.DateRangePicker(label=color, value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), color=color)\n",
        "      for color in ['primary', 'secondary', 'error', 'info', 'success', 'warning']],\n",
        "    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:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.FlexBox(\n",
        "    pmui.DateRangePicker(label='Filled', value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), variant='filled'),\n",
        "    pmui.DateRangePicker(label='Outlined', value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), variant='outlined'),\n",
        "    pmui.DateRangePicker(label='Standard', value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), 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.DateRangePicker(label='Disabled', value=(dt.date(2024, 4, 1), dt.date(2024, 4, 15)), disabled=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### API Reference\n",
        "\n",
        "#### Parameters"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "date_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
}