{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import panel as pn\n",
        "import panel_material_ui as pmui\n",
        "\n",
        "pn.extension()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The `StepperMenu` component is part of the `Menu` family of components. Like other menus it is driven by a declarative list of `items` and reports the user's position via the `active` and `value` parameters. It displays progress through a sequence of numbered steps and comes in two variants: a labelled `standard` strip and a `compact` mobile-style bar.\n",
        "\n",
        "## Item Structure\n",
        "\n",
        "In its simplest form each item is just a string label. For more control an item may be a dictionary with the following keys:\n",
        "\n",
        "- **`label`** (str, required): The text displayed for the step.\n",
        "- **`icon`** (str, optional): An icon name (or inline SVG) shown for pending steps.\n",
        "- **`active_icon`** (str, optional): Icon shown when the step is active or completed. Falls back to the filled version of `icon` when not provided.\n",
        "- **`completed`** (bool, optional): Whether the step is marked complete.\n",
        "- **`error`** (bool, optional): Whether the step is in an error state.\n",
        "- **`optional`** (bool, optional): Whether to show an \"Optional\" caption under the label.\n",
        "- **`disabled`** (bool, optional): Whether the step is disabled.\n",
        "- **`tooltip`** (str, optional): Tooltip text shown when hovering over the step.\n",
        "\n",
        "When one of the `items` is selected it becomes available on the `value` parameter. Since only the allowed keys are synced to the frontend, other information can be stored in the item dictionaries.\n",
        "\n",
        "## Parameters:\n",
        "\n",
        "### Core\n",
        "\n",
        "* **`active`** (`int`): The index of the currently active step.\n",
        "* **`items`** (`list`): List of step items.\n",
        "* **`value`** (`dict`): The currently selected item.\n",
        "\n",
        "##### Display\n",
        "\n",
        "* **`color`** (str): The color of the active and completed steps.\n",
        "* **`variant`** (str): The stepper variant, one of `'standard'` or `'compact'`.\n",
        "* **`alternative_label`** (bool): Place the label below the step icon (standard variant).\n",
        "* **`connector`** (bool): Whether to display the connector line between steps (standard variant).\n",
        "* **`non_linear`** (bool): Whether steps can be clicked to navigate non-linearly (standard variant).\n",
        "* **`orientation`** (str): The orientation of the steps, one of `'horizontal'` or `'vertical'` (standard variant).\n",
        "* **`indicator`** (str): The progress indicator in the compact variant, one of `'dots'`, `'progress'`, or `'text'`.\n",
        "* **`position`** (str): Positioning of the bar in the compact variant, one of `'bottom'`, `'static'`, or `'top'`.\n",
        "* **`back_text`** (str): Label for the back button (compact variant).\n",
        "* **`next_text`** (str): Label for the next button (compact variant).\n",
        "\n",
        "##### Styling\n",
        "\n",
        "- **`sx`** (dict): Component level styling API.\n",
        "- **`theme_config`** (dict): Theming API.\n",
        "\n",
        "#### Methods\n",
        "\n",
        "- **`next`**: Advance to the next step.\n",
        "- **`back`**: Return to the previous step.\n",
        "- **`reset`**: Reset to the first step.\n",
        "- **`on_click`**: Register a callback executed when a step is clicked.\n",
        "- **`remove_on_click`**: Remove a previously registered click callback.\n",
        "\n",
        "---\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Basic Usage\n",
        "\n",
        "At its simplest, pass a list of string labels. The `active` parameter (a zero-based index) controls which step is highlighted:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "stepper = pmui.StepperMenu(items=['Account', 'Shipping', 'Payment', 'Review'], active=1)\n",
        "\n",
        "stepper"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Steps before the active one are automatically marked as completed (shown with a check), the active step is highlighted, and later steps are greyed out.\n",
        "\n",
        "The current position is reflected on both the `active` (index) and `value` (item) parameters:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "print(f'Active: {stepper.active}')\n",
        "print(f'Value:  {stepper.value}')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Navigation\n",
        "\n",
        "The `next`, `back` and `reset` methods move between steps from Python. To react to step changes, watch the `active` parameter with `.param.watch`:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "stepper = pmui.StepperMenu(items=['Account', 'Shipping', 'Payment', 'Review'])\n",
        "\n",
        "log = pmui.Column('# Step Changes')\n",
        "stepper.param.watch(lambda e: log.append(f'Moved to step {e.new}'), 'active')\n",
        "\n",
        "back = pmui.Button(label='Back')\n",
        "back.on_click(lambda e: stepper.back())\n",
        "\n",
        "forward = pmui.Button(label='Next')\n",
        "forward.on_click(lambda e: stepper.next())\n",
        "\n",
        "pmui.Column(\n",
        "    stepper,\n",
        "    pmui.Row(back, forward),\n",
        "    log,\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "By default the stepper is linear and the steps are not clickable. Set `non_linear=True` to let users click a step to jump directly to it:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(items=['Account', 'Shipping', 'Payment', 'Review'], non_linear=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Step States\n",
        "\n",
        "Switching from string labels to dictionaries lets each step declare its own state via the `completed`, `error`, `optional` and `disabled` keys:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(\n",
        "    items=[\n",
        "        {'label': 'Account', 'completed': True},\n",
        "        {'label': 'Shipping', 'completed': True},\n",
        "        {'label': 'Payment', 'error': True},\n",
        "        {'label': 'Review', 'optional': True},\n",
        "        {'label': 'Confirm', 'disabled': True},\n",
        "    ],\n",
        "    active=2,\n",
        "    non_linear=True,\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Icons\n",
        "\n",
        "Add an `icon` to a step (any [Material Icon](https://fonts.google.com/icons) name) to replace the default numbered circle. The active and completed steps show the icon filled and in the active color, while pending steps show it outlined and greyed — so the current step stays clear:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(\n",
        "    items=[\n",
        "        {'label': 'Account', 'icon': 'person'},\n",
        "        {'label': 'Shipping', 'icon': 'local_shipping'},\n",
        "        {'label': 'Payment', 'icon': 'payment'},\n",
        "        {'label': 'Review', 'icon': 'check_circle'},\n",
        "    ],\n",
        "    active=1,\n",
        "    non_linear=True,\n",
        "\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Provide an `active_icon` to use a different icon once a step becomes active or completed. If omitted, the filled version of `icon` is used automatically:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(\n",
        "    items=[\n",
        "        {'label': 'Cart', 'icon': 'shopping_cart', 'active_icon': 'shopping_cart_checkout'},\n",
        "        {'label': 'Address', 'icon': 'home', 'active_icon': 'where_to_vote'},\n",
        "        {'label': 'Done', 'icon': 'task_alt'},\n",
        "    ],\n",
        "    active=1,\n",
        "    non_linear=True,\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Driving a View\n",
        "\n",
        "Because only the allowed keys are synced to the frontend, you can store arbitrary data on each item (such as a `view`) and use a reactive reference to the `value` to render the content for the active step:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "stepper = pmui.StepperMenu(\n",
        "    items=[\n",
        "        {'label': 'Welcome', 'icon': 'waving_hand', 'view': pmui.Typography('# Welcome 👋')},\n",
        "        {'label': 'Configure', 'icon': 'settings', 'view': pmui.Typography('# Configure your settings ⚙️')},\n",
        "        {'label': 'Finish', 'icon': 'flag', 'view': pmui.Typography('# All done! 🎉')},\n",
        "    ],\n",
        "    active=0,\n",
        "    non_linear=True,\n",
        ")\n",
        "\n",
        "pmui.Column(\n",
        "    stepper,\n",
        "    stepper.rx()['view'],\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Vertical Orientation\n",
        "\n",
        "Set `orientation='vertical'` to stack the steps from top to bottom, which suits narrow layouts such as a sidebar. It applies to the `standard` variant; icons, connectors and step states behave just as they do horizontally:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(\n",
        "    items=[\n",
        "        {'label': 'Account', 'icon': 'person'},\n",
        "        {'label': 'Shipping', 'icon': 'local_shipping'},\n",
        "        {'label': 'Payment', 'icon': 'payment'},\n",
        "        {'label': 'Review', 'icon': 'check_circle'},\n",
        "    ],\n",
        "    orientation='vertical',\n",
        "    active=1,\n",
        "    non_linear=True,\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Compact Variant\n",
        "\n",
        "Set `variant='compact'` for a minimal, mobile-style bar with back/next buttons. Step labels are not shown in this mode; the number of steps is derived from the number of `items`. Choose the indicator style with `indicator` (`'dots'`, `'progress'`, or `'text'`):\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "items = ['Account', 'Shipping', 'Payment', 'Review']\n",
        "\n",
        "pmui.Column(\n",
        "    pmui.StepperMenu(items=items, variant='compact', indicator='dots'),\n",
        "    pmui.StepperMenu(items=items, variant='compact', indicator='progress'),\n",
        "    pmui.StepperMenu(items=items, variant='compact', indicator='text'),\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The button labels can be customized with `back_text` and `next_text`:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(items=items, variant='compact', indicator='progress', back_text='Prev', next_text='Forward')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Color Options\n",
        "\n",
        "The `color` parameter sets the color of the active and completed steps:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.Column(*(\n",
        "    pmui.StepperMenu(items=['Account', 'Shipping', 'Payment', 'Review'], color=color, active=1, margin=10)\n",
        "    for color in pmui.StepperMenu.param.color.objects\n",
        "))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### API Reference\n",
        "\n",
        "#### Parameters\n",
        "\n",
        "The `StepperMenu` menu exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "pmui.StepperMenu(items=['Account', 'Shipping', 'Payment', 'Review']).api(jslink=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "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 Stepper:**\n",
        "\n",
        "- [Material UI Stepper Reference](https://mui.com/material-ui/react-stepper/) - Complete documentation for the underlying Material UI component\n",
        "- [Material UI Stepper API](https://mui.com/material-ui/api/stepper/) - Detailed API reference and configuration options\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "lumen",
      "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.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}