{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8603430",
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5336985",
   "metadata": {},
   "source": [
    "The `Avatar` component displays profile pictures, user initials, or icons in a compact, circular or square format. Avatars are commonly used throughout user interfaces to represent users, brands, or entities in a visually consistent manner.\n",
    "\n",
    "The component supports multiple content types including images, text initials, and icons, with automatic fallback handling when images fail to load.\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",
    "* **`clicks`** (int): The number of times the avatar has been clicked (read-only). Default is 0.\n",
    "* **`content`** (str): The content to display - can be an image URL/path or text initials.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`alt_text`** (str): Alternative text for screen readers and when images fail to load.\n",
    "* **`color`** (str): Background color for text and icon avatars - supports CSS color values.\n",
    "* **`size`** (str): Size of the avatar - options include 'small', 'medium' (default), and 'large'.\n",
    "* **`variant`** (str): Shape variant - either 'rounded' (default) or 'square'.\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",
    "#### Constructor Arguments\n",
    "\n",
    "* **`on_click`** (callable): A Python callback to be triggered when the avatar is clicked\n",
    "\n",
    "#### Methods\n",
    "\n",
    "* **`on_click`** (callable): Registers a Python callback to be executed when the Avatar is clicked\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a357073f",
   "metadata": {},
   "source": [
    "### Basic Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1e28c80",
   "metadata": {},
   "source": [
    "Create a simple image avatar by providing an image URL or local path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c899dd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Avatar(\n",
    "    content=\"https://mui.com/static/images/avatar/1.jpg\",\n",
    "    alt_text=\"User Profile\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d50c2929",
   "metadata": {},
   "source": [
    "### Sizes\n",
    "\n",
    "The `Avatar` component supports different sizes to fit various layout requirements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "699cfa21",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\", size=\"small\", margin=10),\n",
    "    pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\", size=\"medium\", margin=10),\n",
    "    pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\", size=\"large\", margin=10),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97f0b54b",
   "metadata": {},
   "source": [
    "### Variants\n",
    "\n",
    "The `Avatar` component offers different shape variants:\n",
    "\n",
    "- **Rounded**: Default style with rounded corners for a softer appearance\n",
    "- **Square**: Sharp corners for a more geometric look"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6e38dac3",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\", variant=\"rounded\", margin=10),\n",
    "    pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\", variant=\"square\", margin=10),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "568508e6-63ae-47a3-9bb9-cd95ef220610",
   "metadata": {},
   "source": [
    "### Text Based Avatars\n",
    "\n",
    "You can also define text based avatars"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4708006-e257-4ef9-bfe7-d8682dce10b7",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Row(\n",
    "    pmui.Avatar(content=\"P\", variant=\"rounded\", margin=10),\n",
    "    pmui.Avatar(content=\"R\", variant=\"square\", margin=10),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72a0facc",
   "metadata": {},
   "source": [
    "### Colors\n",
    "\n",
    "Customize avatar background colors for text and icon avatars to match your design system or indicate different user types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e01545c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.FlexBox(\n",
    "    pmui.Avatar(content=\"A\", color=\"#f44336\", margin=10),\n",
    "    pmui.Avatar(content=\"B\", color=\"#2196f3\", margin=10),\n",
    "    pmui.Avatar(content=\"C\", color=\"#4caf50\", margin=10),\n",
    "    pmui.Avatar(content=\"D\", color=\"#ff9800\", margin=10),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b92b9ff",
   "metadata": {},
   "source": [
    "### Handling Clicks\n",
    "\n",
    "The `Avatar` component supports click events through the `clicks` parameter and `on_click` method. This makes avatars interactive and useful for user profile actions or navigation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5db217a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "clickable_avatar = pmui.Avatar(content=\"JD\", color=\"#2196f3\", variant=\"square\")\n",
    "click_display = pmui.Typography(f\"Clicks: {clickable_avatar.clicks}\", variant=\"body2\")\n",
    "\n",
    "pn.bind(lambda event: click_display.param.update(object=f\"Clicks: {clickable_avatar.clicks}\"), clickable_avatar.param.clicks, watch=True)\n",
    "\n",
    "pmui.Row(clickable_avatar, click_display)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9f50265",
   "metadata": {},
   "source": [
    "You can also use the `on_click` method to register a callback function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15fbd54c",
   "metadata": {},
   "outputs": [],
   "source": [
    "profile_avatar = pmui.Avatar(content=\"https://mui.com/static/images/avatar/2.jpg\", alt_text=\"Profile\")\n",
    "status_text = pmui.Typography(\"Click the avatar to view profile\", variant=\"body2\")\n",
    "\n",
    "def handle_profile_click(event):\n",
    "    status_text.object = f\"Profile clicked! Total clicks: {profile_avatar.clicks}\"\n",
    "\n",
    "profile_avatar.on_click(handle_profile_click)\n",
    "\n",
    "pmui.Row(profile_avatar, status_text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b1d5598",
   "metadata": {},
   "source": [
    "### JavaScript Callbacks\n",
    "\n",
    "For client-side interactions, you can use the `js_on_click` method to register JavaScript callbacks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a26b3476",
   "metadata": {},
   "outputs": [],
   "source": [
    "javascript_code = \"\"\"\n",
    "alert('Avatar clicked! This is a client-side JavaScript callback.');\n",
    "\"\"\"\n",
    "\n",
    "js_avatar = pmui.Avatar(content=\"JS\", color=\"#ff5722\", variant=\"square\")\n",
    "js_avatar.js_on_click(code=javascript_code)\n",
    "\n",
    "pmui.Column(\n",
    "    pmui.Typography(\"Click the avatar below to trigger a JavaScript alert:\", variant=\"body2\"),\n",
    "    js_avatar,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36c8faa9",
   "metadata": {},
   "source": [
    "### Fallback Handling\n",
    "\n",
    "Avatars automatically handle fallbacks when images fail to load. The component will attempt to display alternative content based on the `alt_text` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d875e1d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Avatar(\n",
    "    content=\"https://broken-image-url.jpg\",\n",
    "    alt_text=\"John Doe\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c93e2591-483b-455d-bef4-1fa43eaa8a1e",
   "metadata": {},
   "source": [
    "### Loading"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "372d6b1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Avatar(\n",
    "    content=\"https://mui.com/static/images/avatar/1.jpg\",\n",
    "    loading=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5b627be",
   "metadata": {},
   "source": [
    "### Example: Interactive Avatar Grid\n",
    "\n",
    "Here's a practical example showing clickable avatars in a user selection interface:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68fa836e",
   "metadata": {},
   "outputs": [],
   "source": [
    "users = [\n",
    "    {\"name\": \"Alice\", \"initials\": \"AL\", \"color\": \"#e91e63\"},\n",
    "    {\"name\": \"Bob\", \"initials\": \"BO\", \"color\": \"#2196f3\"},\n",
    "    {\"name\": \"Charlie\", \"initials\": \"CH\", \"color\": \"#4caf50\"},\n",
    "    {\"name\": \"Diana\", \"initials\": \"DI\", \"color\": \"#ff9800\"},\n",
    "]\n",
    "\n",
    "selected_user = pmui.Typography(\"Select a user by clicking their avatar\", variant=\"h6\")\n",
    "\n",
    "def create_user_avatar(user):\n",
    "    avatar = pmui.Avatar(content=user[\"initials\"], color=user[\"color\"], size=\"large\", margin=5)\n",
    "\n",
    "    def handle_user_click(event):\n",
    "        selected_user.object = f\"Selected: {user['name']} (clicked {avatar.clicks} times)\"\n",
    "\n",
    "    avatar.on_click(handle_user_click)\n",
    "    return avatar\n",
    "\n",
    "avatar_grid = pmui.Row(*[create_user_avatar(user) for user in users])\n",
    "\n",
    "pmui.Column(\n",
    "    pmui.Typography(\"User Selection\", variant=\"h5\"),\n",
    "    avatar_grid,\n",
    "    selected_user,\n",
    "    width=600,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f2ce3e1",
   "metadata": {},
   "source": [
    "### Example: User Profile Card\n",
    "\n",
    "Here's a practical example showing how to use avatars in a user profile context with reactive updates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86b7ed25",
   "metadata": {},
   "outputs": [],
   "source": [
    "import param\n",
    "\n",
    "class UserProfile(param.Parameterized):\n",
    "    user_name = param.String(default=\"John Doe\")\n",
    "    profile_image = param.String(default=\"https://mui.com/static/images/avatar/1.jpg\")\n",
    "    avatar_size = param.Selector(objects=[\"small\", \"medium\", \"large\"], default=\"medium\")\n",
    "    avatar_variant = param.Selector(objects=[\"rounded\", \"square\"], default=\"rounded\")\n",
    "\n",
    "    def create_profile_card(self):\n",
    "        avatar = pmui.Avatar(\n",
    "            content=self.param.profile_image,\n",
    "            alt_text=self.param.user_name,\n",
    "            size=self.param.avatar_size,\n",
    "            variant=self.param.avatar_variant,\n",
    "        )\n",
    "\n",
    "        name_text = pmui.Typography(\n",
    "            object=self.param.user_name,\n",
    "            variant=\"h6\",\n",
    "        )\n",
    "\n",
    "        return pmui.Card(\n",
    "            pmui.Row(\n",
    "                avatar,\n",
    "                pmui.Column(\n",
    "                    name_text,\n",
    "                    pmui.Typography(object=\"Software Developer\", variant=\"body2\"),\n",
    "                    margin=(0, 20),\n",
    "                ),\n",
    "                margin=20,\n",
    "            ),\n",
    "            width=300, collapsible=False,\n",
    "        )\n",
    "\n",
    "profile = UserProfile()\n",
    "\n",
    "controls = pn.Param(\n",
    "    profile,\n",
    "    parameters=['user_name', 'avatar_size', 'avatar_variant'],\n",
    "    widgets={\n",
    "        'user_name': pmui.widgets.TextInput,\n",
    "        'avatar_size': pmui.widgets.RadioButtonGroup,\n",
    "        'avatar_variant': pmui.widgets.RadioButtonGroup,\n",
    "    },\n",
    "    width=300,\n",
    ")\n",
    "\n",
    "pn.Row(profile.create_profile_card(), controls)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15005676",
   "metadata": {},
   "source": [
    "### API Reference"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b936c14b",
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Avatar(content=\"https://mui.com/static/images/avatar/1.jpg\").api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a210ed3a",
   "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 components\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 Avatar:**\n",
    "\n",
    "- [Material UI Avatar Reference](https://mui.com/material-ui/react-avatar/) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Avatar API](https://mui.com/material-ui/api/avatar/) - 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.14.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}