{
 "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",
    "Avatars are versatile components that can be used in various contexts:\n",
    "\n",
    "- User profiles and account displays\n",
    "- Comment sections and social feeds\n",
    "- Team member listings\n",
    "- Navigation bars and headers\n",
    "- Contact lists and directories\n",
    "- Interactive user selection interfaces\n",
    "\n",
    "The component supports multiple content types including images, text initials, and icons, with automatic fallback handling when images fail to load. Avatars can also be made interactive with click event handling.\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",
    "* **`object`** (str): The content to display - can be an image URL/path, text initials, or icon name\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 with rounded corners) 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",
    "* **`js_on_click`** (str): JavaScript code 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",
    "* **`js_on_click`** (callable): Allows defining JavaScript callbacks with `args` and `code` to be triggered 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": [
    "image_avatar = pmui.Avatar(\n",
    "    \"https://mui.com/static/images/avatar/1.jpg\",\n",
    "    alt_text=\"User Profile\"\n",
    ")\n",
    "image_avatar"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "95c3b16f",
   "metadata": {},
   "source": [
    "Create text-based avatars using initials or short text:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ee500f2",
   "metadata": {},
   "source": [
    "The avatar content can be dynamically updated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ea7f101",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_avatar.object = \"https://mui.com/static/images/avatar/2.jpg\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b96f329f",
   "metadata": {},
   "source": [
    "Let's reset it back:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bd924d6d",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_avatar.object = \"https://mui.com/static/images/avatar/1.jpg\""
   ]
  },
  {
   "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(\"https://mui.com/static/images/avatar/1.jpg\", size=\"small\", margin=10),\n",
    "    pmui.Avatar(\"https://mui.com/static/images/avatar/1.jpg\", size=\"medium\", margin=10),\n",
    "    pmui.Avatar(\"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(\"https://mui.com/static/images/avatar/1.jpg\", variant=\"rounded\", margin=10),\n",
    "    pmui.Avatar(\"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(\"P\", variant=\"rounded\", margin=10),\n",
    "    pmui.Avatar(\"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(\"A\", color=\"#f44336\", margin=10),  # Red\n",
    "    pmui.Avatar(\"B\", color=\"#2196f3\", margin=10),  # Blue  \n",
    "    pmui.Avatar(\"C\", color=\"#4caf50\", margin=10),  # Green\n",
    "    pmui.Avatar(\"D\", color=\"#ff9800\", margin=10),  # Orange\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(\"JD\", color=\"#2196f3\", variant=\"square\")\n",
    "click_display = pmui.Typography(f\"Clicks: {clickable_avatar.clicks}\", variant=\"body2\")\n",
    "\n",
    "# Update display when avatar is clicked\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(\"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(\"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": [
    "# This will fallback gracefully since the image URL is broken\n",
    "fallback_avatar = pmui.Avatar(\n",
    "    object=\"https://broken-image-url.jpg\",\n",
    "    alt_text=\"John Doe\"\n",
    ")\n",
    "fallback_avatar"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c93e2591-483b-455d-bef4-1fa43eaa8a1e",
   "metadata": {},
   "source": [
    "### Loading"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "372d6b1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "loading_avatar = pmui.Avatar(\n",
    "    \"https://mui.com/static/images/avatar/1.jpg\",\n",
    "    loading=True\n",
    ")\n",
    "loading_avatar"
   ]
  },
  {
   "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(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",
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()\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",
    "            object=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",
    "# Control panel for dynamic updates\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(\"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.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}