{
 "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 `LinearProgress` widget displays the status of ongoing processes, providing visual feedback to users about task completion. It supports two primary modes:\n",
    "\n",
    "- **Determinate mode**: Shows specific progress with a known completion percentage.\n",
    "- **Indeterminate mode**: Displays ongoing activity without a specific completion time\n",
    "\n",
    "This component is essential for creating responsive user interfaces that keep users informed during data processing, file uploads, API calls, and other time-consuming operations.\n",
    "\n",
    "For an alternative progress indicator see [`CircularProgress`](CircularProgress.ipynb).\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "For details on other options for customizing the component see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`active`** (boolean): Whether to animate the progress bar when in indeterminate mode\n",
    "* **`max`** (int): The maximum progress value (defaults to 100)\n",
    "* **`value`** (float): The current progress value; set to -1 or omit for indeterminate state\n",
    "* **`value_buffer`** (int): The buffer value for buffered progress (only available with `buffer` variant)\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (str): The color variant of the progress bar, which must be one of 'default', 'primary' (default), 'secondary', 'success', 'info', 'warning', 'danger', 'light', 'dark'\n",
    "* **`variant`** (`Literal[\"determinate\", \"indeterminate\", \"buffer\", \"query\"]`): The visual style variant of the progress indicator\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (dict): Component level styling API.\n",
    "- **`theme_config`** (dict): Theming API.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a determinate progress bar by specifying both the current `value` and optional `max` value (defaults to 100). This shows users exactly how much of a task has been completed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "progress = pmui.LinearProgress(label='LinearProgress', value=20, width=200)\n",
    "progress"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The progress `value` can be dynamically updated from Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "progress.value = 80"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's reset it back to 20:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "progress.value = 20"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For operations with unknown duration, create an indeterminate progress bar that continuously animates to indicate ongoing activity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "indeterminate = pmui.LinearProgress(label='Indeterminate LinearProgress', variant=\"indeterminate\", width=200)\n",
    "indeterminate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `LinearProgress` widget supports a comprehensive range of color themes to match your application's design:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.GridBox(\n",
    "    \"default\", pmui.LinearProgress(value=40, color=\"default\", width=300, margin=22),\n",
    "    \"primary\", pmui.LinearProgress(value=40, color=\"primary\", width=300, margin=22),\n",
    "    \"secondary\", pmui.LinearProgress(value=40, color=\"secondary\", width=300, margin=22),\n",
    "    \"error\", pmui.LinearProgress(value=40, color=\"error\", width=300, margin=22),\n",
    "    \"info\", pmui.LinearProgress(value=40, color=\"info\", width=300, margin=22),\n",
    "    \"success\", pmui.LinearProgress(value=40, color=\"success\", width=300, margin=22),\n",
    "    \"warning\", pmui.LinearProgress(value=40, color=\"warning\", width=300, margin=22),\n",
    "    \"light\", pmui.LinearProgress(value=40, color=\"light\", width=300, margin=22),\n",
    "    \"dark\", pmui.LinearProgress(value=40, color=\"dark\", width=300, margin=22),\n",
    "    \"danger\", pmui.LinearProgress(value=40, color=\"danger\", width=300, margin=22),\n",
    "    ncols=2,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variants\n",
    "\n",
    "The `LinearProgress` widget offers several variants to suit different use cases:\n",
    "\n",
    "- **Determinate**: Shows specific progress with a known completion percentage\n",
    "- **Indeterminate**: Displays ongoing activity without a specific completion time\n",
    "- **Buffer**: Shows both primary progress and a buffer value (useful for streaming content)\n",
    "- **Query**: Indicates a query operation in progress"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.GridBox(\n",
    "    \"Determinate\", pmui.LinearProgress(value=60, variant=\"determinate\", width=300, margin=22),\n",
    "    \"Indeterminate\", pmui.LinearProgress(variant=\"indeterminate\", margin=22),\n",
    "    \"Buffer\", pmui.LinearProgress(value=60, value_buffer=80, variant=\"buffer\", width=300, margin=22),\n",
    "    \"Query\", pmui.LinearProgress(variant=\"query\", margin=22),\n",
    "    ncols=2,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Best Practices\n",
    "\n",
    "**When to use each variant:**\n",
    "- Use **determinate** progress when you can calculate the completion percentage (e.g., file uploads, data processing)\n",
    "- Use **indeterminate** progress for operations with unknown duration (e.g., server requests, initialization)\n",
    "- Use **buffer** variant for streaming scenarios where you want to show both loaded and buffered content\n",
    "- Choose appropriate colors that align with your application's theme and accessibility requirements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Processing Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "from panel_material_ui import LinearProgress\n",
    "from time import sleep\n",
    "\n",
    "pn.extension()\n",
    "\n",
    "run_progress = pmui.LinearProgress(value=0, variant=\"determinate\", visible=False, width=200)\n",
    "\n",
    "def process_data(event):\n",
    "    with run.param.update(disabled=True):\n",
    "        with run_progress.param.update(visible=True, value=0):\n",
    "            for i in range(1, 100):\n",
    "                run_progress.value = i\n",
    "                sleep(0.03)\n",
    "\n",
    "run = pmui.Button(label=\"Process Data\", variant=\"contained\", on_click=process_data, icon=\"directions_run\", width=200)\n",
    "\n",
    "pmui.Column(run, run_progress,)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Fetching Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "from panel_material_ui import LinearProgress\n",
    "from time import sleep\n",
    "\n",
    "pn.extension()\n",
    "\n",
    "fetch_progress = LinearProgress(visible=False, variant=\"indeterminate\", width=200)\n",
    "\n",
    "def fetch_data(event):\n",
    "    with fetch.param.update(disabled=True):\n",
    "        with fetch_progress.param.update(visible=True):\n",
    "            sleep(2.5)\n",
    "\n",
    "fetch = pmui.Button(label=\"Fetch Data\", variant=\"contained\", on_click=fetch_data, icon=\"directions_run\", width=200)\n",
    "\n",
    "pmui.Column(fetch, fetch_progress,)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "progress.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 Progress Documentation:**\n",
    "\n",
    "- [Material UI Linear Progress Reference](https://mui.com/material-ui/react-progress/#linear) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Linear Progress API](https://mui.com/material-ui/api/linear-progress/) - 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": 4
}