{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55e7b392-14c0-4411-bfcf-a46e7e117368",
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1183801-6081-4061-8795-d7fd8e5e8f38",
   "metadata": {},
   "source": [
    "The `MenuButton` component is part of the `Menu` family of components. `Menu` components provide a structured way for users to navigate or choose between a series of defined items. In the case of `MenuItem`, these items represent a series of actions to select from after opening the menu on a button click.\n",
    "\n",
    "Each item in the `MenuButton` list is defined by a dictionary with several supported keys:\n",
    "\n",
    "#### Item Structure\n",
    "\n",
    "Each item can include the following keys:\n",
    "\n",
    "- **`label`** (`str`, required): The text displayed for the menu item.\n",
    "- **`icon`** (`str`, optional): An icon to display next to the label.\n",
    "- **`icon_size`** (`str`, optional): The size of the icon to display next to the label, e.g. `\"12px\"` or `\"1em\"`.\n",
    "- **`href`** (`str`, optional): A URL to link to. If provided, the menu item becomes a link.\n",
    "- **`target`** (`str`, optional): Specifies where to open the linked document (e.g., `_blank`).\n",
    "\n",
    "These dictionaries are passed to the component via the items parameter as a list. When one of the `items` is selected it will be available on the `value` parameter.\n",
    "\n",
    "Since only the allowed keys are synced with the frontend, other information can be stored in the item dictionaries.\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`active`** (`boolean`): Whether the dialog is visible.\n",
    "* **`disabled`** (boolean): Whether the button is clickable.\n",
    "* **`items`** (`list`): Menu  items to select from.\n",
    "* **`value`** (dict): The currently selected item.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (str): A button theme; should be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "* **`description`** (str | Bokeh Tooltip | pn.widgets.TooltipIcon): A description which is shown when the widget is hovered.\n",
    "* **`icon`** (str): An icon to render to the left of the button label. Either an SVG or an icon name which is loaded from [Material UI Icons](https://mui.com/material-ui/material-icons).\n",
    "* **`icon_size`** (str): Size of the icon as a string, e.g. 12px or 1em.\n",
    "* **`label`** (str): The title of the widget.\n",
    "* **`variant`** (str): The button style, either 'solid', 'outlined', 'text'.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (dict): Component level styling API.\n",
    "- **`theme_config`** (dict): Theming API.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "083c0657-d3c2-4a41-8777-ffcaf5bf72a7",
   "metadata": {},
   "source": [
    "### Basic Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cccba94-b316-4d37-bbce-81b59d19c086",
   "metadata": {},
   "source": [
    "`MenuButton` like all menu components allows selecting between a number of `items` defined as dictionaries in a list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddb562b1-17a4-4ecb-91b5-c52f351f9c8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "menu_button = pmui.MenuButton(items=[\n",
    "    {'label': 'Open', 'icon': 'description'},\n",
    "    {'label': 'Save', 'icon': 'save'},\n",
    "    {'label': 'Exit', 'icon': 'close'},\n",
    "], label='File', icon='storage')\n",
    "\n",
    "pmui.Column(menu_button, height=150)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eec49872-dd14-4686-81e0-d137293b70b4",
   "metadata": {},
   "source": [
    "The items require a label but may also include other information including an `icon` or `avatar` and `href` and `target` value to declare a link.\n",
    "\n",
    "Clicking on a particular item will highlight it and set both `active` and `value` parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d88bd5a8-1905-4778-a33c-c6ef06aab81e",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f'Active: {menu_button.active}')\n",
    "print(f'Value: {menu_button.value}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "43c38aa2-79eb-4d2d-ba5d-38698743f10a",
   "metadata": {},
   "source": [
    "Alternatively you may also register `on_click` handlers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "09773773-1c59-41d9-9824-beca8baf2f06",
   "metadata": {},
   "outputs": [],
   "source": [
    "row = pmui.Column('# Click Events')\n",
    "\n",
    "menu_button.on_click(row.append)\n",
    "\n",
    "row"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b3ebf93-5e38-4416-acd0-eb171dc824bb",
   "metadata": {},
   "source": [
    "Try clicking on the `MenuButton` and see the clicked `item` appear."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6921fe28-b986-4889-85e5-9e08cfb3e975",
   "metadata": {},
   "source": [
    "### Custom Item Keys\n",
    "\n",
    "Like all menus the `items` only sync the allowed keys. This means you can easily store other information in the items, e.g. you can use it to easily select between different views to be displayed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9f977839-ac4e-46f1-be9c-d14f48d79c2d",
   "metadata": {},
   "outputs": [],
   "source": [
    "breadcrumbs = pmui.MenuButton(\n",
    "    items=[\n",
    "        {'label': '🏰 Kingdom', 'view': pmui.Typography('# 🏰 Welcome to the Kingdom')},\n",
    "        {'label': '🌲 Enchanted Forest', 'view': pmui.Typography('# 🌲 You enter the Enchanted Forest...')},\n",
    "        {'label': '🐉 Dragon\\'s Lair', 'view': pmui.Typography('# 🐉 Beware! You approach the Dragon\\'s Lair.')},\n",
    "        {'label': '💎 Treasure Room', 'view': pmui .Typography('# 💎 Congratulations! You found the Treasure.')},\n",
    "    ],\n",
    "    label='Select a menu item',\n",
    "    active=0,  # Start at the beginning of the journey\n",
    "    color='warning'\n",
    ")\n",
    "\n",
    "pn.Column(\n",
    "    breadcrumbs,\n",
    "    pn.param.ParamRef(breadcrumbs.rx()['view']),\n",
    "    height=300\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "515291b6-7107-4015-b1da-d93d205ff411",
   "metadata": {},
   "source": [
    "In the above example we take advantage of the fact that `Widget.rx()` returns a reactive reference to the `value` parameter and then access the `view` on that item. Rendering this expression allows us to control the current view with the menu."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c39e9c3-627d-436d-858f-a44b06d27147",
   "metadata": {},
   "source": [
    "### Separators"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "279bc961-d727-47d8-a653-c4ab7d1c7427",
   "metadata": {},
   "source": [
    "The `MenuButton` also allows separating options into groups by adding a `None` in between:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3be9d56d-6a05-43e8-b531-11abdf30b413",
   "metadata": {},
   "outputs": [],
   "source": [
    "separated_menu = pmui.MenuButton(label=\"File\", icon=\"save\", items=[\n",
    "    {\"label\": \"License\", \"icon\": \"law\"},\n",
    "    None,\n",
    "    {\"label\": \"About\", \"icon\": \"info\"}\n",
    "])\n",
    "\n",
    "pmui.Column(separated_menu, height=150)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ed3907d-9398-4448-b7b1-cd0102622adf",
   "metadata": {},
   "source": [
    "### Disabled and Loading\n",
    "\n",
    "Like any other widget the `MenuButton` can be `disabled` and / or set to `loading`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "875e2649-05a1-4f11-b52d-2ccf115dae18",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MenuButton(label=\"Loading\", disabled=True, loading=True, color=\"primary\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66273dbd-7658-434b-88c8-7364a0d716a7",
   "metadata": {},
   "source": [
    "### Color Options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "759c18d6-02eb-415f-8077-755a98d31083",
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.GridBox(*(\n",
    "    menu_button.clone(color=color)\n",
    "    for color in pmui.MenuButton.param.color.objects\n",
    "), ncols=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c459182-6d01-4edd-b592-e999bdb3499c",
   "metadata": {},
   "source": [
    "### Sizes\n",
    "\n",
    "For larger or smaller buttons, use the `size` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7822cc36-13d1-4216-a983-a0504b1bae45",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Row(\n",
    "        pmui.MenuButton(size=\"small\", label=\"Small\", align=\"center\"), \n",
    "        pmui.MenuButton(size=\"medium\", label=\"Medium\", align=\"center\"),\n",
    "        pmui.MenuButton(size=\"large\", label=\"Large\", align=\"center\"),\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "005ccc52-76db-46a7-b859-640218d945c1",
   "metadata": {},
   "source": [
    "### Variants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d00de31-3f51-49cc-9af6-fbb05f506667",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(*(\n",
    "    menu_button.clone(variant=variant)\n",
    "    for variant in pmui.MenuButton.param.variant.objects\n",
    "))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2fcd52d5-a4ce-434b-864b-25e5a2ca63a5",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `MenuButton` menu 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,
   "id": "0793e79e-ed6f-4c9b-8741-b741ec4f9c04",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MenuButton(items=[\n",
    "    {'label': 'Open', 'icon': 'description'},\n",
    "    {'label': 'Save', 'icon': 'save'},\n",
    "    {'label': 'Exit', 'icon': 'close'},\n",
    "], label='File', icon='storage').api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1ffeb51-ddf3-4a92-8c4e-edb6c22ff3b3",
   "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 Button:**\n",
    "\n",
    "- [Material UI Button Reference](https://mui.com/material-ui/react-breadcrumbs) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Button API](https://mui.com/material-ui/api/breadcrumbs/) - Detailed API reference and configuration options\n",
    "\n",
    "**Material UI Menu:**\n",
    "\n",
    "- [Material UI Menu Reference](https://mui.com/material-ui/react-menu) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Menu API](https://mui.com/material-ui/api/menu/) - 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": 5
}