{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "22d177dc-6cfb-4de2-9509-f1eb45e10cf2",
   "metadata": {},
   "source": [
    "# Quick Start\n",
    "\n",
    "\n",
    "## Installation\n",
    "\n",
    "Install the `table_widget` package using pip:\n",
    "\n",
    "```bash\n",
    "pip install table_widget\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## Basic Usage\n",
    "\n",
    "Create an Instance of the Table Widget:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07fc24cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "table = TableWidget()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46142a13",
   "metadata": {},
   "source": [
    "### Add Data to the Table\n",
    "\n",
    "You can provide data either as a `pandas.DataFrame` or a dictionary of records."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2481e7c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "# Sample DataFrame\n",
    "data = pd.DataFrame({\n",
    "    \"name\": [\"Alice\", \"Bob\", \"Charlie\"],\n",
    "    \"score\": [95, 87, 73],\n",
    "    \"comment\": [\"Excellent\", \"Good\", \"Needs Improvement\"],\n",
    "    \"status\": [\"Active\", \"Inactive\", \"Active\"],\n",
    "})\n",
    "\n",
    "# Define column metadata\n",
    "columns = [\n",
    "    {\"field\": \"name\", \"headerName\": \"Name\", \"editable\": False},\n",
    "    {\"field\": \"score\", \"headerName\": \"Score\", \"type\": \"number\", \"editable\": True},\n",
    "    {\"field\": \"comment\", \"headerName\": \"Comment\", \"editable\": True},\n",
    "    {\"field\": \"status\", \"headerName\": \"Status\", \"type\": \"singleSelect\", \"valueOptions\": [\"Active\", \"Inactive\"], \"editable\": True},\n",
    "]\n",
    "\n",
    "# Load data into the table\n",
    "table.from_data(data, columns=columns)\n",
    "table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e40b814a",
   "metadata": {},
   "source": [
    "## Data format\n",
    "The table widget provides predefined column types. By default, columns are treated as strings, meaning they will use string-based sorting and align content to the left. Some column types require specific value types for their cells.\n",
    "\n",
    "#### Native Column Types and Value Requirements\n",
    "\n",
    "| Column Type       | Required Value Type            | Description                                              |\n",
    "|-------------------|--------------------------------|----------------------------------------------------------|\n",
    "| `'string'` (default) | `string`                      | Default type. Aligns content to the left and sorts lexically. |\n",
    "| `'number'`         | `number`                      | For numeric data. Aligns content to the right and sorts numerically. |\n",
    "| `'date'`           | `Date()` object               | For date values. Enables date-based sorting.             |\n",
    "| `'dateTime'`       | `Date()` object               | For date and time values.                               |\n",
    "| `'boolean'`        | `boolean`                    | For boolean (true/false) values.                       |\n",
    "| `'singleSelect'`   | A value in `.valueOptions`    | Allows selection from predefined options.               |\n",
    "| `'actions'`        | Not applicable               | Used for rendering actions, such as buttons.            |\n",
    "\n",
    "\n",
    "For example,\n",
    "\n",
    "```python\n",
    "# number column\n",
    "{\"field\": \"score\", \"headerName\": \"Score\", \"type\": \"number\", \"editable\": True},\n",
    "# singleSelect column\n",
    "{\"field\": \"status\", \"headerName\": \"Status\", \"type\": \"singleSelect\", \"valueOptions\": [\"Active\", \"Inactive\"], \"editable\": True},\n",
    "```\n",
    "\n",
    "For `link`, `button` and `checkbox` column types, please refer to the later sections. More details, please check the [Data Grid](https://mui.com/x/react-data-grid/column-definition/#column-types)\n",
    "\n",
    "\n",
    "### Column is editable\n",
    "\n",
    "To make a column editable, set the `editable` property to `True` in the column definition.\n",
    "\n",
    "```python\n",
    "    {\"field\": \"score\", \"headerName\": \"Score\", \"dataType\": \"number\", \"editable\": True},\n",
    "```\n",
    "\n",
    "### Initialize the visible columns\n",
    "\n",
    "By default, all columns are visible. To hide a column, set the `hide` property to `True` in the column definition.\n",
    "\n",
    "```python\n",
    "    {\"field\": \"score\", \"headerName\": \"Score\", \"dataType\": \"number\", \"hide\": True},\n",
    "```\n",
    "\n",
    "\n",
    "### Adding Links in Table Columns\n",
    "\n",
    "The widget supports rendering links inside table cells. Define the column with `dataType: \"link\"`, and ensure the cell value contains valid HTML for the link.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "518910bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "table = TableWidget()\n",
    "\n",
    "data = pd.DataFrame({\n",
    "    \"name\": [\"Alice\", \"Bob\", \"Charlie\"],\n",
    "    \"profile\": [\n",
    "        '<a href=\"https://example.com/alice\" target=\"_blank\">View Profile</a>',\n",
    "        '<a href=\"https://example.com/bob\" target=\"_blank\">View Profile</a>',\n",
    "        '<a href=\"https://example.com/charlie\" target=\"_blank\">View Profile</a>',\n",
    "    ],\n",
    "})\n",
    "\n",
    "columns = [\n",
    "    {\"field\": \"name\", \"headerName\": \"Name\", \"editable\": False},\n",
    "    {\"field\": \"profile\", \"headerName\": \"Profile\", \"dataType\": \"link\", \"editable\": False},\n",
    "]\n",
    "\n",
    "table.from_data(data, columns=columns)\n",
    "table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39176afc",
   "metadata": {},
   "source": [
    "### Adding Buttons in Table Columns\n",
    "\n",
    "You can add interactive buttons to table cells. Define the column with `dataType: \"button\"` and optionally customize the button label with `buttonLabel`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6c9ae3c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "table = TableWidget()\n",
    "\n",
    "data = pd.DataFrame({\n",
    "    \"name\": [\"Alice\", \"Bob\", \"Charlie\"],\n",
    "    \"action\": [\"\", \"\", \"\"],  # Placeholder column for button actions\n",
    "})\n",
    "\n",
    "columns = [\n",
    "    {\"field\": \"name\", \"headerName\": \"Name\", \"editable\": False},\n",
    "    {\n",
    "        \"field\": \"action\",\n",
    "        \"headerName\": \"Action\",\n",
    "        \"dataType\": \"button\",\n",
    "        \"buttonLabel\": \"Click Me\",  # Optional custom button label\n",
    "    },\n",
    "]\n",
    "\n",
    "table.from_data(data, columns=columns)\n",
    "table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0ebbcd8",
   "metadata": {},
   "source": [
    "### Adding Checkbox in Table Columns\n",
    "\n",
    "You can add interactive checkbox to table cells. Define the column with `type: \"checkbox\"`.\n",
    "```python\n",
    "    {\"field\": \"include\", \"headerName\": \"Include\", \"type\": \"checkbox\", \"editable\": True},\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21c9ba34",
   "metadata": {},
   "source": [
    "## Interactive Features\n",
    "\n",
    "### Row Update Observation\n",
    "\n",
    "The widget allows you to observe updates to rows and react to them. Use it to send the new values to the server and save them into a database or other storage method.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65a738d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "def on_row_update(change):\n",
    "    print(\"Updated row:\", change[\"new\"])\n",
    "\n",
    "table.observe(on_row_update, \"updatedRow\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea0726e6",
   "metadata": {},
   "source": [
    "\n",
    "### Dynamic Data Updates\n",
    "\n",
    "You can dynamically generate and update the data displayed in the table."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bceb1bc2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "import random\n",
    "\n",
    "table = TableWidget()\n",
    "\n",
    "def generate_data(N):\n",
    "    return pd.DataFrame({\n",
    "        \"name\": [f\"Person_{i}\" for i in range(N)],\n",
    "        \"score\": [random.randint(0, 100) for _ in range(N)],\n",
    "        \"comment\": [random.choice([\"Excellent\", \"Good\", \"Average\"]) for _ in range(N)],\n",
    "    })\n",
    "\n",
    "# Generate and load new data dynamically\n",
    "new_data = generate_data(10)\n",
    "table.from_data(new_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "625f8429",
   "metadata": {},
   "source": [
    "#### Button click Observation\n",
    "Use it to observe button clicks and react to them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5634e255",
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "def on_button_click(change):\n",
    "    print(f\"Button clicked for row ID: {change['new']['rowId']} in field: {change['new']['field']}\")\n",
    "\n",
    "table.observe(on_button_click, \"clickedButton\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4859fe8",
   "metadata": {},
   "source": [
    "### Row selection Observation\n",
    "Use it to observe row selection and react to it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9bb8f88b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# select a single row\n",
    "def on_single_row_select(change):\n",
    "    print(f\"Selected row ID: {change['new']}\")\n",
    "\n",
    "table.observe(on_single_row_select, \"selectedRowId\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64ea916a",
   "metadata": {},
   "source": [
    "#### Multi-Row Selection\n",
    "The widget supports selecting multiple rows. Use the `selectedRows` property to get the list of selected rows. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28870781",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "import pandas as pd\n",
    "import ipywidgets as ipw\n",
    "\n",
    "# Create a table widget\n",
    "table = TableWidget(style={\"height\": \"500px\"}, config={\"pagination\": True,\n",
    "                                                       \"checkboxSelection\": True,})\n",
    "\n",
    "# Generate data\n",
    "data = pd.DataFrame({\n",
    "    \"name\": [\"Alice\", \"Bob\", \"Charlie\"],\n",
    "    \"score\": [85, 90, 78],\n",
    "    \"comment\": [\"Good\", \"Excellent\", \"Average\"],\n",
    "})\n",
    "columns = [\n",
    "    {\"field\": \"name\", \"headerName\": \"Name\", \"editable\": False},\n",
    "    {\"field\": \"score\", \"headerName\": \"Score\", \"dataType\": \"number\", \"editable\": True},\n",
    "    {\"field\": \"comment\", \"headerName\": \"Comment\", \"editable\": True},\n",
    "]\n",
    "\n",
    "# Load data into the table\n",
    "table.from_data(data, columns=columns)\n",
    "\n",
    "# select a single row\n",
    "def on_rows_select(change):\n",
    "    print(f\"Selected rows: {change['new']}\")\n",
    "\n",
    "table.observe(on_rows_select, \"selectedRows\")\n",
    "\n",
    "table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b10d0c5",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "## Customization\n",
    "\n",
    "### Style Customization\n",
    "\n",
    "You can define the table's appearance using the `style` parameter.\n",
    "\n",
    "```python\n",
    "table.style = {\"height\": \"600px\", \"width\": \"100%\", \"fontSize\": \"16px\"}\n",
    "```\n",
    "\n",
    "### Configurable Options\n",
    "\n",
    "The table supports various configurations via the `config` parameter:\n",
    "\n",
    "| Config Option               | Description                            | Default Value |\n",
    "|-----------------------------|----------------------------------------|---------------|\n",
    "| `checkboxSelection`         | Enables checkbox selection.            | `False`       |\n",
    "| `pagination`                | Enables pagination.                    | `True`        |\n",
    "| `autoPageSize`              | Adjusts the page size automatically.   | `True`        |\n",
    "| `pageSize`                  | Set page size manually.                | `10`          |\n",
    "| `disableSelectionOnClick`   | Disables selection on row click.       | `False`       |\n",
    "\n",
    "Example:\n",
    "\n",
    "```python\n",
    "table.config = {\n",
    "    \"checkboxSelection\": True,\n",
    "    \"pagination\": True,\n",
    "    \"disableSelectionOnClick\": True,\n",
    "}\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## Example Notebook\n",
    "\n",
    "Below is an example of integrating the table widget into a Jupyter notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08e6c3c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from table_widget import TableWidget\n",
    "import pandas as pd\n",
    "import ipywidgets as ipw\n",
    "\n",
    "# Create a table widget\n",
    "table = TableWidget(style={\"height\": \"500px\"}, config={\"pagination\": True})\n",
    "\n",
    "# Generate data\n",
    "data = pd.DataFrame({\n",
    "    \"name\": [\"Alice\", \"Bob\", \"Charlie\"],\n",
    "    \"score\": [85, 90, 78],\n",
    "    \"profile\": [\n",
    "        '<a href=\"https://example.com/alice\" target=\"_blank\">View Profile</a>',\n",
    "        '<a href=\"https://example.com/bob\" target=\"_blank\">View Profile</a>',\n",
    "        '<a href=\"https://example.com/charlie\" target=\"_blank\">View Profile</a>',\n",
    "    ],\n",
    "    \"comment\": [\"Good\", \"Excellent\", \"Average\"],\n",
    "    \"status\": [\"Active\", \"Inactive\", \"Active\"],\n",
    "})\n",
    "columns = [\n",
    "    {\"field\": \"name\", \"headerName\": \"Name\", \"editable\": False},\n",
    "    {\"field\": \"score\", \"headerName\": \"Score\", \"dataType\": \"number\", \"editable\": True},\n",
    "    {\"field\": \"profile\", \"headerName\": \"Profile\", \"dataType\": \"link\", \"editable\": False},\n",
    "    {\"field\": \"comment\", \"headerName\": \"Comment\", \"editable\": True},\n",
    "    {\"field\": \"status\", \"headerName\": \"Status\", \"type\": \"singleSelect\", \"valueOptions\": [\"Active\", \"Inactive\"], \"editable\": True},\n",
    "]\n",
    "\n",
    "# Load data into the table\n",
    "table.from_data(data, columns=columns)\n",
    "table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd7625d8",
   "metadata": {},
   "source": [
    "Now you're ready to start using the **Table Widget** in your Jupyter notebooks! For any issues or questions, feel free to reach out to the repository or documentation."
   ]
  }
 ],
 "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.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}