{
 "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": [
    "`CircularProgress` indicators, commonly known as spinners, express an unspecified wait time or display the length of a process.\n",
    "\n",
    "Progress indicators inform users about the status of ongoing processes, such as loading an app, submitting a form, or saving updates. They enhance user experience by providing visual feedback during operations that require time to complete.\n",
    "\n",
    "- **Determinate** indicators display how long an operation will take\n",
    "- **Indeterminate** indicators visualize an unspecified wait time\n",
    "\n",
    "A progress indicator is essential for creating responsive user interfaces that keep users informed during data processing, file uploads, API calls, and other time-consuming operations. The `LoadingSpinner` component provides an elegant, Material UI-styled circular progress indicator.\n",
    "\n",
    "For an alternative progress indicator, see [`LinearProgress`](LinearProgress.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",
    "* **`value`** (boolean | int): Whether the indicator is spinning (boolean) or the progress percentage (int, 0-100) for determinate variant\n",
    "* **`variant`** (`Literal[\"determinate\", \"indeterminate\"]`): The variant of the progress indicator\n",
    "\n",
    "### Display\n",
    "\n",
    "* **`bgcolor`** (`Literal['light', 'dark'] | None`): The color of the spinner background segment - 'light', 'dark', or None for no background\n",
    "* **`color`** (str): The color variant of the spinning segment, which must be one of 'primary', 'secondary', 'success', 'info', 'warn', 'danger', 'light', 'dark'\n",
    "* **`label`** (str): A label to display alongside the spinner\n",
    "* **`size`** (int): The size of the spinner in pixels\n",
    "* **`thickness`** (float): The thickness of the loading spinner stroke\n",
    "* **`with_label`** (boolean): Whether to show a percentage label inside the loading spinner (when using the 'determinate' variant)\n",
    "\n",
    "### Styling\n",
    "\n",
    "- **`sx`** (dict): Component-level styling API for advanced customization\n",
    "- **`theme_config`** (dict): Theming API for consistent design system integration\n",
    "\n",
    "### Aliases\n",
    "\n",
    "For compatibility with Panel, certain parameters are allowed as aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Usage\n",
    "\n",
    "By default, the `CircularProgress` is initialized in a determinate, non-spinning state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can instantiate it in an indeterminate, spinning state by setting `value=True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may add a `label`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=True, label=\"Progress\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Size\n",
    "\n",
    "You can customize the `size` of the CircularProgress to fit your design requirements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=True, size=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Thickness\n",
    "\n",
    "You can adjust the thickness of the CircularProgress stroke for visual emphasis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=True, size=50, thickness=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color and Background\n",
    "\n",
    "You can customize both the `color` and `bgcolor` of the spinner to match your application's theme:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=True, color=\"warning\", bgcolor=\"dark\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's explore the full range of available `color` and `bgcolor` combinations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "grid = pn.GridBox(*[' ']+pmui.CircularProgress.param.color.objects, nrows=4)\n",
    "\n",
    "for bgcolor in pmui.CircularProgress.param.bgcolor.objects:\n",
    "    grid.append(bgcolor or 'None')\n",
    "    for color in pmui.CircularProgress.param.color.objects:\n",
    "        spinner = pmui.CircularProgress(size=40, value=True, bgcolor=bgcolor, color=color)\n",
    "        grid.append(spinner)\n",
    "\n",
    "grid"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Determinate\n",
    "\n",
    "When using the `determinate` variant, you can use the `CircularProgress` similarly to the `Progress` element to show specific completion percentages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=60, variant='determinate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Determinate with Label\n",
    "\n",
    "You can also enable a percentage label inside the spinner with `with_label=True` for better user feedback:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(value=42, variant='determinate', bgcolor='light', size=60, with_label=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Fetching Data\n",
    "\n",
    "Here's a practical example showing how to use the `CircularProgress` to provide feedback during data fetching operations:"
   ]
  },
  {
   "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 CircularProgress\n",
    "from time import sleep\n",
    "\n",
    "pn.extension()\n",
    "\n",
    "fetch_progress = pmui.CircularProgress(value=True, visible=False, size=40, height=45)\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": [
    "### Example: KPI Dashboard\n",
    "\n",
    "The `CircularProgress` with a percentage label can also be effectively used for displaying KPI (Key Performance Indicator) values in dashboards:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Paper(\n",
    "        pmui.Typography(\"Open PRs\", variant=\"h5\"),\n",
    "        pmui.CircularProgress(value=40, variant=\"determinate\", size=60, with_label=True, align=\"center\"),\n",
    "        margin=10\n",
    "    ),\n",
    "    pmui.Paper(\n",
    "        pmui.Typography(\"Closed PRs\", variant=\"h5\"),\n",
    "        pmui.CircularProgress(value=60, variant=\"determinate\", bgcolor='light', size=60, with_label=True, align=\"center\"),\n",
    "        margin=10\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API Reference\n",
    "\n",
    "Below is the complete API reference for the `CircularProgress` component:\n",
    "\n",
    "### Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.CircularProgress(height=40).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, enhancing user engagement and experience.\n",
    "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html) - Connect parameters between components and create reactive interfaces that update in real-time.\n",
    "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html) - Build parameter-driven applications that automatically update when parameters change.\n",
    "\n",
    "**Material UI Progress Documentation:**\n",
    "\n",
    "- [Material UI Circular Progress Reference](https://mui.com/material-ui/react-progress/#circular) - Complete documentation for the underlying Material UI component, including usage examples and customization options.\n",
    "- [Material UI Circular Progress API](https://mui.com/material-ui/api/circular-progress/) - Detailed API reference and configuration options for advanced customization and control."
   ]
  }
 ],
 "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
}