{
 "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 `NestedBreadcrumbs` component is part of the `Menu` family. `Menu` components provide a structured way for users to navigate or choose between a defined set of items. Unlike `Breadcrumbs`, `NestedBreadcrumbs` represents a **tree**: for each level, a small chevron opens a menu to switch between **siblings at that depth**. Clicking a segment navigates to that depth.\n",
    "\n",
    "Each item in the `NestedBreadcrumbs` 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 segment.\n",
    "* **`href`** (`str`, optional): URL to link to (used on non-terminal segments).\n",
    "* **`target`** (`str`, optional): Link target (e.g. `\"_blank\"`).\n",
    "* **`icon`** (`str`, optional): Material icon name to render next to the label.\n",
    "* **`avatar`** (`str`, optional): A short avatar/text badge to show beside the label.\n",
    "* **`items`** (`list[dict]`, optional): Nested children for the next depth.\n",
    "* **`selectable`** (`bool`, optional): Whether this item can be selected in the sibling menu (defaults to `True`).\n",
    "\n",
    "Items are passed via the `items` parameter as a list containing a single **root** item. When a depth is selected, the explicit selection path is stored in `active` (see below).\n",
    "\n",
    "## Parameters\n",
    "\n",
    "### Core\n",
    "\n",
    "* **`active`** (`tuple[int, ...]`): The explicit selection path from the root (e.g. `(0, 2, 1)`).\n",
    "  The UI may **auto-descend** for rendering (first-child tails), but only the explicit part is stored here.\n",
    "* **`auto_descend`** (`bool`, default `True`): Controls whether the UI auto-descends via first children when rendering.\n",
    "  * `True`: The UI appends a first-child tail to `active` to compute `path` (for display).\n",
    "  * `False`: No auto-descent; if the last explicit node has children, the last breadcrumb renders as an unselected **“Select…”** segment with a chevron menu.\n",
    "* **`disabled`** (`bool`): Whether the breadcrumb control is disabled.\n",
    "* **`items`** (`list[dict]`): A list with **one** root item; children live in each item’s `items`.\n",
    "* **`path`** (`tuple[int, ...]`): The currently visible path.\n",
    "  The UI may **auto-descend** for rendering (first-child tails), but only the explicit part is stored here.\n",
    "\n",
    "### Display\n",
    "\n",
    "* **`color`** (`str`): Color variant for the **active** segment; one of your theme’s supported colors (e.g. `'primary'`, `'success'`, …).\n",
    "* **`separator`** (`str`, optional): Custom separator between segments. Defaults to the MUI NavigateNext icon.\n",
    "* **`max_items`** (`int`, optional): Maximum number of segments to display (older segments are collapsed per MUI behavior).\n",
    "\n",
    "### Styling\n",
    "\n",
    "* **`sx`** (`dict`): Component-level styling API.\n",
    "* **`theme_config`** (`dict`): Theming API.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2a353334-70ba-4afc-9408-102763f0f665",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "`NestedBreadcrumbs` like all menu components allows selecting between a number of `items` defined as dictionaries in a list. The "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03ca8d3f-1b72-49b6-b419-6f36ffe5981c",
   "metadata": {},
   "outputs": [],
   "source": [
    "breadcrumb_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",
    "        'items': [\n",
    "            {'label': 'Charts', 'icon': 'stacked_line_chart'},\n",
    "            {'label': 'Maps', 'icon': 'map', 'items': [\n",
    "                {'label': 'World', 'icon': 'public'},    \n",
    "            ]},\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",
    "        'selectable': False,\n",
    "        'items': [\n",
    "            {'label': 'Team', 'icon': 'groups'},\n",
    "            {'label': 'Contact', 'icon': 'mail'}\n",
    "        ]\n",
    "    },\n",
    "]\n",
    "\n",
    "breadcrumb_menu = pmui.NestedBreadcrumbs(\n",
    "    items=breadcrumb_items\n",
    ")\n",
    "\n",
    "pmui.Column(breadcrumb_menu, height=120)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86f8fb96-088d-494d-bc6a-db2e04f1cf8f",
   "metadata": {},
   "source": [
    "The `active` and `path` parameters represent the paths to the selected and rendered items expressed as tuples of indexes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6bcbc467-406c-436c-9f4c-8924a0fb7d8f",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.NestedBreadcrumbs(\n",
    "    items=breadcrumb_items, active=(1, 1), path=(1, 1, 0)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10363988-4d98-4d74-ad4f-13d988263405",
   "metadata": {},
   "source": [
    "By default, the component will automatically descend the tree (`auto_descend=True`), extending the visible breadcrumb path by following the first child at each level below the current selection.\n",
    "\n",
    "This behavior ensures that users always see a fully expanded path to a leaf item, even when only a higher-level node is explicitly selected. When `auto_descend=False`, the component instead stops at the last explicitly selected item and renders a “Select…” placeholder segment with a chevron menu, prompting the user to choose the next level manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34e8beb2-1e51-4fe7-993c-0a50b42798a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "descend_menu = pmui.NestedBreadcrumbs(\n",
    "    items=breadcrumb_items, auto_descend=False, active=(1, 1)\n",
    ")\n",
    "\n",
    "pmui.Column(descend_menu, height=120)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfa0964d-a065-433f-9a74-58986dbfcbc6",
   "metadata": {},
   "source": [
    "### Display Options\n",
    "\n",
    "#### `color`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2058915-4b7b-4e25-a3ac-1ac02ea4cbbd",
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.GridBox(*(\n",
    "    breadcrumb_menu.clone(color=color, label=color, active=0)\n",
    "    for color in pmui.NestedBreadcrumbs.param.color.objects\n",
    "), ncols=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "850389a7-296e-4b12-8677-46d5017d5a46",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `NestedBreadcrumbs` 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.NestedBreadcrumbs(items=breadcrumb_items).api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1716b823-fef1-4213-89a5-7a00dd75e6e2",
   "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 Breadcrumbs:**\n",
    "\n",
    "- [Material UI Breadcrumbs Reference](https://mui.com/material-ui/react-breadcrumbs) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Breadcrumbs API](https://mui.com/material-ui/api/breadcrumbs/) - 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
}