{
 "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 `Breadcrumbs` 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 `Breadcrumbs`, these items represent navigation steps or levels in a hierarchy.\n",
    "\n",
    "Each item in the `Breadcrumbs` 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",
    "- **`target`** (str, optional): A URL to link to. If provided, the breadcrumb becomes a link.\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",
    "* **`items`** (`list`): List of menu items.\n",
    "* **`value`** (dict): The currently selected item.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (str): The color variant of the breadcrumbs, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n",
    "* **`separator`** (str): The separator displayed between breadcrumb items.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (dict): Component level styling API.\n",
    "- **`theme_config`** (dict): Theming API.\n",
    "\n",
    "#### Methods\n",
    "\n",
    "- **`on_click`**: Registers a callback to be executed when the `MenuButton` is clicked.\n",
    "- **`remove_on_click`**: Removes a callback that was previously registered.\n",
    "\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cccba94-b316-4d37-bbce-81b59d19c086",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "`Breadcrumbs` 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": [
    "items = [\n",
    "    {'label': 'Documentation', 'icon': 'article'},\n",
    "    {'label': 'Reference Gallery', 'icon': 'category'},\n",
    "    {'label': 'Menus', 'icon': 'menu'},\n",
    "    {'label': 'Breadcrumbs', 'icon': 'grain'},\n",
    "]\n",
    "\n",
    "breadcrumbs = pmui.Breadcrumbs(items=items, active=3)\n",
    "\n",
    "breadcrumbs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb1d68aa-378b-470d-ae4a-ded784bf3e4b",
   "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": "efca39b8-b9c0-4398-8d75-ed9888617892",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f'Active: {breadcrumbs.active}')\n",
    "print(f'Value: {breadcrumbs.value}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18c1b827-7157-4a39-9c91-a0176c978caa",
   "metadata": {},
   "source": [
    "Alternatively you may also register `on_click` handlers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9cddd1a7-11d9-4f5b-ae63-e6dd660283ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "row = pmui.Column('# Click Events')\n",
    "\n",
    "breadcrumbs.on_click(row.append)\n",
    "\n",
    "row"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63694881-6b22-4ed6-b401-1eea584ae000",
   "metadata": {},
   "source": [
    "Try clicking on the `Breadcrumbs` and see the clicked `item` appear."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b89ef38d-8b2a-4627-a767-af38ddd2790d",
   "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": "c626206b-6b87-4d74-abbf-40848c65c072",
   "metadata": {},
   "outputs": [],
   "source": [
    "breadcrumbs = pmui.Breadcrumbs(\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",
    "    active=0,  # Start at the beginning of the journey\n",
    "    color='warning'\n",
    ")\n",
    "\n",
    "pn.Column(\n",
    "    breadcrumbs,\n",
    "    breadcrumbs.rx()['view']\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "09c729fc-827b-402c-84f8-c48e3f081760",
   "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": "2eed7343-ecc2-4e61-923d-7e4175eae0a9",
   "metadata": {},
   "source": [
    "### Max Items\n",
    "\n",
    "The number of items that are displayed can be limited with the `max_items` option, any further items are collapsed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d6b25432-2050-4002-9cb2-2622a06168ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Breadcrumbs(items=items, active=3, max_items=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c966e99-2509-4b80-a214-c5b8b3a6f122",
   "metadata": {},
   "source": [
    "### Separator\n",
    "\n",
    "The default `separator` can be replaced with a custom character:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25ac54c8-bf6c-47dc-b1e4-d72ddccf72b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Breadcrumbs(items=items, active=3, separator='|')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d4c54e6-411a-497a-9eb9-40e38d55f5a9",
   "metadata": {},
   "source": [
    "### Color Options\n",
    "\n",
    "The `color` parameter may be used to visually distinguish the selected `Breadcrumbs`. Available options include \"default\", \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", and \"danger\":\n",
    "\n",
    "The `color` of the selected breadcrumb can be set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "883e88db-c3c2-4965-ad0b-e4b07512fa3b",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(*(\n",
    "    pmui.Breadcrumbs(items=items, color=color, active=3) for color in pmui.Breadcrumbs.param.color.objects\n",
    "))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91f03c5c-acae-4f30-ac45-818e8dfc471c",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `Breadcrumbs` 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": "b7e5d0a7-dbab-4a4f-b6dc-5e3bb921a793",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Breadcrumbs(items=[\n",
    "    {'label': 'Documentation', 'icon': 'article'},\n",
    "    {'label': 'Reference Gallery', 'icon': 'category'},\n",
    "    {'label': 'Menus', 'icon': 'menu'},\n",
    "    {'label': 'Breadcrumbs', 'icon': 'grain'},\n",
    "]).api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db3e5017-65ce-4d86-9f9e-294fd2983b7e",
   "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
}