{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2",
   "metadata": {},
   "source": [
    "The `Tooltip` displays informative text when users hover over, focus on, or tap a child element. It wraps a single child component and shows a configurable label.\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",
    "* **`object`** (Viewable): The child component to wrap with the tooltip.\n",
    "* **`open`** (bool or None): Explicitly control whether the tooltip is open. When None (default), the tooltip is managed automatically on hover/focus. Set to True or False for programmatic control.\n",
    "* **`title`** (str): The text to display inside the tooltip.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`arrow`** (bool): Whether the tooltip has an arrow indicating the element it refers to. Default is False.\n",
    "* **`describe_child`** (bool): Whether the tooltip acts as an accessible description rather than a label. Use when the child already has a visible label and the tooltip provides supplementary information. Default is False.\n",
    "* **`enter_delay`** (int): The number of milliseconds to wait before showing the tooltip. This can help avoid tooltips appearing on quick mouse passes. Default is 100.\n",
    "* **`follow_cursor`** (bool): Whether the tooltip follows the cursor position. Default is False.\n",
    "* **`leave_delay`** (int): The number of milliseconds to wait before hiding the tooltip. Default is 0.\n",
    "* **`placement`** (str): The placement of the tooltip relative to the child element - options include 'top', 'bottom' (default), 'left', 'right', and variants with '-start' or '-end' suffixes.\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",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "Wrap any component and provide a `title` to create a tooltip:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Tooltip(pmui.Button(label=\"Delete\", icon=\"delete\"), title=\"Remove this item\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1",
   "metadata": {},
   "source": [
    "### Arrow\n",
    "\n",
    "Use the `arrow` parameter to add an arrow pointing to the child element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Tooltip(pmui.Button(label=\"Save\"), title=\"Save your progress\", arrow=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1",
   "metadata": {},
   "source": [
    "### Placement\n",
    "\n",
    "The tooltip supports 12 placement options:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Row(\n",
    "        pmui.Tooltip(pmui.Button(label=\"Top Start\"), title=\"top-start\", placement=\"top-start\"),\n",
    "        pmui.Tooltip(pmui.Button(label=\"Top\"), title=\"top\", placement=\"top\"),\n",
    "        pmui.Tooltip(pmui.Button(label=\"Top End\"), title=\"top-end\", placement=\"top-end\"),\n",
    "    ),\n",
    "    pmui.Row(\n",
    "        pmui.Tooltip(pmui.Button(label=\"Left\"), title=\"left\", placement=\"left\"),\n",
    "        pmui.Tooltip(pmui.Button(label=\"Right\"), title=\"right\", placement=\"right\"),\n",
    "    ),\n",
    "    pmui.Row(\n",
    "        pmui.Tooltip(pmui.Button(label=\"Bottom Start\"), title=\"bottom-start\", placement=\"bottom-start\"),\n",
    "        pmui.Tooltip(pmui.Button(label=\"Bottom\"), title=\"bottom\", placement=\"bottom\"),\n",
    "        pmui.Tooltip(pmui.Button(label=\"Bottom End\"), title=\"bottom-end\", placement=\"bottom-end\"),\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1",
   "metadata": {},
   "source": [
    "### Follow Cursor\n",
    "\n",
    "Set `follow_cursor=True` to have the tooltip track the mouse position:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Tooltip(\n",
    "    pmui.Button(label=\"Hover and move\", variant=\"outlined\"),\n",
    "    title=\"I follow your cursor\",\n",
    "    follow_cursor=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1",
   "metadata": {},
   "source": [
    "### Delay\n",
    "\n",
    "Control how quickly the tooltip appears and disappears:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Tooltip(pmui.Button(label=\"Instant\"), title=\"No delay\", enter_delay=0),\n",
    "    pmui.Tooltip(pmui.Button(label=\"Slow\"), title=\"500ms delay\", enter_delay=500),\n",
    "    pmui.Tooltip(pmui.Button(label=\"Lingering\"), title=\"Stays 1s\", leave_delay=1000),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "g1",
   "metadata": {},
   "source": [
    "### Controlled Tooltip\n",
    "\n",
    "Use the `open` parameter for programmatic control:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "g2",
   "metadata": {},
   "outputs": [],
   "source": [
    "toggle = pmui.Switch(value=True, label=\"Show Tooltip\")\n",
    "\n",
    "tooltip = pmui.Tooltip(\n",
    "    pmui.Button(label=\"Controlled\"),\n",
    "    title=\"Programmatically opened\",\n",
    "    open=toggle, placement=\"right\"\n",
    ")\n",
    "\n",
    "pmui.Column(tooltip, toggle)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "h1",
   "metadata": {},
   "source": [
    "### Accessible Description\n",
    "\n",
    "When the child element already has a label, use `describe_child=True` so the tooltip acts as a description rather than a label:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "h2",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Tooltip(pmui.IconButton(icon=\"delete\"), title=\"Delete\"),\n",
    "    pmui.Tooltip(\n",
    "        pmui.Button(label=\"Add\"),\n",
    "        title=\"Does not add if it already exists.\",\n",
    "        describe_child=True,\n",
    "    ),\n",
    ")"
   ]
  }
 ],
 "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.14.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}