{
 "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 `MenuList` 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 `MenuList`, these items represent a series of menu options, which may also be nested in a tree.\n",
    "\n",
    "Each item in the `MenuList` 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 breadcrumb item.\n",
    "- **`href`** (`str`, optional): A URL to link to. If provided, the breadcrumb becomes a link.\n",
    "- **`icon`** (`str`, optional): An icon to display next to the label.\n",
    "- **`avatar`** (`str`, optional): An avatar or image to show beside the label.\n",
    "- **`secondary`** (`str`, optional): The secondary text, e.g. for describing the item.\n",
    "- **`color`** (`str`, optional): The color of the list item (optional)\n",
    "- **`items`** (`list[dict]`, optional): Nested items.\n",
    "- **`actions`** (`list`, optional): Each menu item can have a list of actions associated with it which are accessible via a menu.\n",
    "- **`selectable`** (`boolean`, optional): Whether this item can be selected.\n",
    "- **`open`** (`boolean`, optional): Whether the menu item should be expanded by default (defaults to `True`).\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`** (`int | tuple[int, ...]`): Index of the selected item (`int` if flat, `tuple` if nested).\n",
    "* **`disabled`** (`boolean`): Whether the menu is disabled.\n",
    "* **`expanded`** (`list[int | tuple[int, ...]]`): Indexes of expanded nodes.\n",
    "* **`items`** (`list[dict]`): Menu items to select from.\n",
    "* **`value`** (`dict`): The currently selected item.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (`str`): The color variant indicating the selected list item, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "* **`dense`** (`boolean`): Whether to show the list items in a dense format, i.e. reduced margins.\n",
    "* **`highlight`** (`boolean`): Whether to highlight the currently selected menu item.\n",
    "* **`level_indent`** (`int`): Number of pixels each nested level is indented by.\n",
    "* **`show_children`** (`boolean`): Whether to render child items nested under `'items'`.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (`dict`): Component level styling API.\n",
    "- **`theme_config`** (`dict`): Theming API.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44a7ae29-0750-49f5-bcf6-a29c6d95ab49",
   "metadata": {},
   "source": [
    "Like all `Menu`-like components `MenuList` accepts a list of `items`, which each support sub-`items`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddb562b1-17a4-4ecb-91b5-c52f351f9c8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "items = [\n",
    "    {'label': 'Home', 'icon': 'home', 'secondary': 'Overview page'},\n",
    "    {'label': 'Gallery', 'icon': 'image', 'secondary': 'Visual overview'},\n",
    "    {'label': 'API', 'icon': 'code', 'secondary': 'API Reference'},\n",
    "    {'label': 'About', 'icon': 'info'},\n",
    "]\n",
    "\n",
    "menu_list = pmui.MenuList(items=items, active=3)\n",
    "\n",
    "menu_list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "666ef005-d429-491f-9fcc-3466c2ed6f6b",
   "metadata": {},
   "source": [
    "Clicking on a particular item will highlight it and set both `active` and `value` parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "efca39b8-b9c0-4398-8d75-ed9888617892",
   "metadata": {},
   "outputs": [],
   "source": [
    "menu_list.active, menu_list.value"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d079cc3-b9dc-40c6-b0b2-9e66a2223dca",
   "metadata": {},
   "source": [
    "## Nested Items\n",
    "\n",
    "Items may also contain sub-`items` making it possible to create a tree-like menu. You can also make items non-`selectable` and control the `expanded` state using the parameter. Much like `active` the `expanded` parameter represents a list of indexes to the selected items:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03ca8d3f-1b72-49b6-b419-6f36ffe5981c",
   "metadata": {},
   "outputs": [],
   "source": [
    "nested_list = pmui.MenuList(\n",
    "    items=[\n",
    "        {\n",
    "            'label': 'Home',\n",
    "            'icon': 'home',\n",
    "            'secondary': 'Overview page',\n",
    "            'items': [\n",
    "                {'label': 'Welcome', 'icon': 'handshake'},\n",
    "                {'label': 'Getting Started', 'icon': 'rocket'}\n",
    "            ]\n",
    "        },\n",
    "        {\n",
    "            'label': 'Gallery',\n",
    "            'icon': 'image',\n",
    "            'secondary': 'Visual overview',\n",
    "            'selectable': False,\n",
    "            'items': [\n",
    "                {'label': 'Charts', 'icon': 'stacked_line_chart'},\n",
    "                {'label': 'Maps', 'icon': 'map'},\n",
    "                {'label': 'Animations', 'icon': 'animation'}\n",
    "            ]\n",
    "        },\n",
    "        {\n",
    "            'label': 'API',\n",
    "            'icon': 'code',\n",
    "            'secondary': 'API Reference',\n",
    "            'items': [\n",
    "                {'label': 'Endpoints', 'icon': 'terminal'},\n",
    "                {'label': 'Schemas', 'icon': 'schema'}\n",
    "            ]\n",
    "        },\n",
    "        {\n",
    "            'label': 'About',\n",
    "            'icon': 'info',\n",
    "            'items': [\n",
    "                {'label': 'Team', 'icon': 'groups'},\n",
    "                {'label': 'Contact', 'icon': 'mail'}\n",
    "            ]\n",
    "        },\n",
    "    ],\n",
    "    dense=True,\n",
    "    expanded=[0, 1]\n",
    ")\n",
    "\n",
    "nested_list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ff29a45-f9be-4fc3-a95a-9294dc7893ba",
   "metadata": {},
   "source": [
    "### Actions\n",
    "\n",
    "`MenuList` items may also have a list of actions associated with it, which will be rendered into a menu:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4303cfb2-c56e-45ce-85db-b8fdc0b5739e",
   "metadata": {},
   "outputs": [],
   "source": [
    "actions = [\n",
    "    {'label': 'Favorite', 'icon': 'star', 'inline': True},\n",
    "    {'label': 'Edit', 'icon': 'edit'},\n",
    "    {'label': 'Delete', 'icon': 'delete'}\n",
    "]\n",
    "\n",
    "list_with_actions = pmui.MenuList(\n",
    "    items=[\n",
    "        {\n",
    "            'label': 'Notebook 1',\n",
    "            'icon': 'book',\n",
    "            'secondary': 'Last edited: Today',\n",
    "            'actions': actions\n",
    "        },\n",
    "        {\n",
    "            'label': 'Notebook 2',\n",
    "            'icon': 'book',\n",
    "            'secondary': 'Last edited: Yesterday',\n",
    "            'actions': actions\n",
    "        },\n",
    "        {\n",
    "            'label': 'Notebook 3',\n",
    "            'icon': 'book',\n",
    "            'secondary': 'Last edited: Last week',\n",
    "            'actions': actions\n",
    "        },\n",
    "    ]\n",
    ")\n",
    "\n",
    "actions = pn.Column()\n",
    "\n",
    "list_with_actions.on_action('Favorite', lambda item: actions.append(f\"Favorited {item['label']}\"))\n",
    "list_with_actions.on_action('Edit', lambda item: actions.append(f\"Edited {item['label']}\"))\n",
    "list_with_actions.on_action('Delete', lambda item: actions.append(f\"Deleted {item['label']}\"))\n",
    "\n",
    "pmui.Row(list_with_actions, actions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c9e423c-d6ed-43a9-91a7-c615880b2828",
   "metadata": {},
   "source": [
    "### Toggle Actions\n",
    "\n",
    "Inline `MenuList` actions may also be defined as toggles, switching between `True` and `False` states. This can be enabled by setting `toggle=True`. In this mode a few additional configuration options become available for the action:\n",
    "\n",
    "- `active_icon`: The icon rendered when the toggle value is True.\n",
    "- `active_color`: The color of the `active_icon` when the toggle value is True.\n",
    "- `value`: The current value of the toggle (True or False).\n",
    "\n",
    "For example here we render a toggle to favorite various notebooks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "47531b2c-a622-41be-a3a5-bd7284d8e95b",
   "metadata": {},
   "outputs": [],
   "source": [
    "actions = [\n",
    "    {'label': 'Favorite', 'icon': 'star_outline', 'active_icon': 'star', 'color': 'warning', 'inline': True, 'toggle': True, 'value': False},\n",
    "]\n",
    "list_with_toggle_action = pmui.MenuList(\n",
    "    items=[\n",
    "        {\n",
    "            'label': 'Notebook 1',\n",
    "            'icon': 'book',\n",
    "            'actions': actions\n",
    "        },\n",
    "        {\n",
    "            'label': 'Notebook 2',\n",
    "            'icon': 'book',\n",
    "            'actions': actions\n",
    "        },\n",
    "        {\n",
    "            'label': 'Notebook 3',\n",
    "            'icon': 'book',\n",
    "            'actions': actions\n",
    "        },\n",
    "    ]\n",
    ")\n",
    "\n",
    "toggle_actions = pn.Column()\n",
    "\n",
    "list_with_toggle_action.on_action('Favorite', lambda item: toggle_actions.append(f'{item[\"label\"]}: {item[\"actions\"][0][\"value\"]}'))\n",
    "\n",
    "pn.Row(list_with_toggle_action, toggle_actions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3157d7d-55ab-4060-b2ca-d4c4f40e6c8d",
   "metadata": {},
   "source": [
    "The `True`/`False` state of the toggle will be updated on the \"value\" key of the actions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a8e14c66-e2b7-4906-8509-746aff118d1f",
   "metadata": {},
   "outputs": [],
   "source": [
    "list_with_toggle_action.items"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d1e5553-2b0f-4584-a76f-d2e12a931c89",
   "metadata": {},
   "source": [
    "### Display Options\n",
    "\n",
    "#### `collapsed`\n",
    "\n",
    "The `collapsed` parameter allows toggling between a view showing just the icons to the expanded view:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea3f1e4c-5cf3-4990-930d-a5ef69dcd830",
   "metadata": {},
   "outputs": [],
   "source": [
    "collapsed = pmui.Switch(label='Collapsed', value=True)\n",
    "\n",
    "pmui.Column(collapsed, pmui.MenuList(items=items, active=2, collapsed=collapsed))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d61c9f0-d7c8-485f-92c6-2ef29fef77e4",
   "metadata": {},
   "source": [
    "#### `color`\n",
    "\n",
    "`MenuList` supports different `color`s to indicate which item is selected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2058915-4b7b-4e25-a3ac-1ac02ea4cbbd",
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.GridBox(*(\n",
    "    menu_list.clone(color=color, label=color, active=0, highlight=True)\n",
    "    for color in pmui.MenuList.param.color.objects\n",
    "), ncols=5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5afa499f-7e70-42b6-b757-bef6a3b3a755",
   "metadata": {},
   "source": [
    "#### `highlight`\n",
    "\n",
    "Highlighting can be disabled entirely by setting `highlight=False`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "864f919a-d546-4b7d-b1d9-713faef1112e",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MenuList(items=items, highlight=False, active=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "850389a7-296e-4b12-8677-46d5017d5a46",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `MenuList` 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": "eed95ed2-1889-4617-9a16-1b89a3edad4f",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MenuList(items=[\n",
    "    {'label': 'Open', 'icon': 'description'},\n",
    "    {'label': 'Save', 'icon': 'save'},\n",
    "    {'label': 'Exit', 'icon': 'close'},\n",
    "], label='File').api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c967e6ac-da57-408b-ab35-a6e4f5a1283c",
   "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
}