panel-mermaid 0.2.1
A project providing a Mermaid JS widget for use with HoloViz Panel.
Requires Python: >=3.11

# ✨ panel-mermaid

[![License](https://img.shields.io/badge/License-MIT%202.0-blue.svg)](https://opensource.org/licenses/MIT)
[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/awesome.panel.org/panel-mermaid-basic)

`panel-mermaid` provides the `MermaidDiagram` *pane* designed to integrate [Mermaid diagramming](https://mermaid.js.org/intro/) functionality with notebooks and [Panel](https://panel.holoviz.org/) data apps.

![panel-mermaid in notebook](https://github.com/awesome-panel/panel-mermaid/blob/main/static/panel-mermaid-notebook.png?raw=true)

It is based on [Mermaid JS](https://mermaid.js.org/).

## Key Features

- **Interactive Mermaid Diagrams**: Easily create flowcharts, sequence diagrams, class diagrams, and more using the familiar Mermaid syntax.
- **Configurable Themes and Looks**: Choose from a variety of themes (`default`, `dark`, `forest`, etc.) and looks (`classic`, `handDrawn`).
- **Real-time Configuration Updates**: Use the `MermaidConfiguration` widget to dynamically update your diagram’s configuration.
- **Customizable Events**: Handle diagram interactions with event subscriptions (e.g., click, mouseover).
- **Font-Awesome Icon Support**: Leverage Font-Awesome icons in your diagrams by including the Font-Awesome CSS in your application.

## Installation

You can install the package using `pip`:

```bash
pip install panel-mermaid
```

## Usage

### 1. Basic Mermaid Diagram

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/awesome.panel.org/panel-mermaid-basic)

[![panel-mermaid](https://github.com/awesome-panel/panel-mermaid/blob/main/static/panel-mermaid-bootstrap.png?raw=true)](https://py.cafe/awesome.panel.org/panel-mermaid-basic)

Here’s how to create a simple Mermaid diagram using the `MermaidDiagram` widget:

```python
import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension()

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    )
).servable()
```

### 2. Basic Mermaid Configuration

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/snippet/panel/v1#c=H4sIAHzmC2cAA41STY_aMBD9K9GcQAoRBEJEqq3U_ZD20ErVHroHgipDBuLWsV3HwCKU_94xTvZLrFj7kLyZ53njNz7CShUIGfBKK2MDzSSKgNWBljnttVGVj_2u0FSMF0FL_OHhLWcbwyrH1TLCJ4uy5kr2-i7yltPLZUBLLf_gyl61yK0cTvsZE1mXwfeHl4hb3-b3KIRaBIPB1-B6_tM15cHd_FEZUSze8Sl102tb6Hti8OW8aj_035WSa77ZGmbpDlfHHIRSf3PIiFwyWdwatpc5hARtiRX6zFoZrG0ODRXpRzWaHVsK9A5ACAb_bbkhtrQ1-XwyMzdkl_sZtK4Szx60m8MpTJBp_YvjHrI1EzWGgAW3d9JVhsyaLUX0wZZKuiMHVfACB7thFE-jmA4LdlBbC9kRdmjcPCCLqROl7IOiksdOzBAKYVVyURgk0vw5Y9myRkvJPS9sCdkoGYZQcfno4dije-SbknQcpEtksOYCr6kquXCjpGVcovlAwVEHS88limauLkCzaMIzXbRCs3GUDuNkkqTpbDxN0tmH3b-UJCcjfaDxnE-_nk9kn-zbDrxDnfxoSP7O0kkyiePhdDyJRxfcu-xY68AltzqjzttTdv2lyWc0LT06Lpm4JNrxnKrbTXiaGj3j-aL5DzUufts6BAAA)

Use the `configuration` parameter to modify the [Mermaid diagram configuration](https://mermaid.js.org/schemas/config.schema.json):

```python
import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension()

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    configuration={"look": "handDrawn", "theme": "forest"},
).servable()
```

### 3. The MermaidConfiguration Widget

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/snippet/panel/v1#c=H4sIAD_iC2cAA41STY_aMBD9K9acQAoRGwgRqahUdrfaQytVe-geCKoMGYhbx04d8yXEf-84H8tSsWLtA7zx83uTNz7CUqcIMYi80MaygiuUjJesUAntldF5XfuVo8m5SFlD_F7DB8HXhudei--1Won1xnArdKVQKB_3FlVJuNN1leVbCptcvdmRWv-ZJJBxlT4YvlMJeMxmmCMVV9pgaRMgtbS2P6s0_XQSxWjpxW9c2kmD3Eqg2q-YyEXGvj2fK259mT2hlHrOer3PbDr74QKowePsRRuZzv_j09F9p2mhWxPZp-uuXa_-vYhhcoGIUSVF2X2VuJ_qfefynDXf3fVLNFu-kOiiBQ8M_t0IQzEpW9JQq8klhpTcn14zQuLZQ-GGXpUJ8qL4KXAH8YrLEj3AVNhH5XQhtmZDleJgM63clYNORYq9bd8PRn5AlyU_6I2F-AhbNG7MEAfUidb2WZPksTUzhDxYZkKmBok0ez2xfFGipcOdSG0G8V3Y9yAX6qWGgxo9oVhn5OMgfUQMKyFxSqqUAT0ey4VC846Do_YWNZcoBXe6AKf5ybvSRWM0HvhRPwiHYRSNB6MwGr_b_VmSkvSLA1zKno_fzse3e3vZQZ1Qa3_Xp3zH0TAcBkF_NBgGdzfSu51Yk8CttNqgrseTtf1F4Uc8LT06obi8ZdrynKvbJ6-aGj3j2fz0DwPoDvWnBAAA)

The `MermaidConfiguration` widget allows you to adjust diagram styling and themes interactively, making it simple to adapt to various visual preferences. You can customize:

- **Look**: Choose between `classic` or `handDrawn`.
- **Theme**: Choose from several themes like `default`, `dark`, `forest`, etc.

Example:

```python
import panel as pn

from panel_mermaid import MermaidDiagram, MermaidConfiguration

pn.extension()

configuration = MermaidConfiguration(look="handDrawn", theme="forest")
diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    configuration=configuration,
)

pn.FlexBox(configuration, diagram).servable()
```

### 4. Event Handling

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/snippet/panel/v1#c=H4sIAOHiC2cAA41SbW_aMBD-K9F9AilENBAiMjFpdJ2qaW_qpPVDgiqTHMSbY2eOoSDEf985L6WtqJgtQZ7z43vunvMBUpUhRMCLUmnjlEyicFjllDKhvdKqaGIPBeqC8cxpiV8b-JGztWaF2-FrJVd8vdHMcFVnKKWHO4OyItzr20jWXHFmr3L0EunQUsvfmJpZi-xKoN5PmMhl7ny5O0Xs-hDfohBq4QwG7515_MMW3YCb-F5pkS1e8enouteW0G-Izrvzqn23-cctSvOQPu9xFvcSSAVP_yTg0iVPkp8J9Emt7pb6_yRwN1e7Xtu4S9561lPv88_v37ooRexvreA6JscCZwkIvs4NZet7FeotWwq0HoILGv9uuCaSNBVNrx5RoknOfgzaWRHP7Es73TpMkJXlL46PEK2YqNAFzLi5kTYvREZvKFLuTa6kvbJXGc9wsB16_sTz6bJge7UxEB1gi9rOEyKfKlHK3ClKeejENCEX0pyLTCOR4qcTw5YVGjp85JnJIboKhi4UXN43cNSgW7RdN5CaiGDFBc4pK3lA78swLlG_oWCpg2XDJUrJbF6A4-LonqmiFZqOvHDoB-MgDKejSRBO36z-lJKc9Mo9vEx7On4-H8_szMsKGoc6-ash-TsNx8HY94eT0di_uuDeZcdaBy651Rl13p68qy8M_kfT0KPjkolLoh3Pqtp9dOup0TOOF8d_ekI_p5AEAAA)

You can also add event listeners to the diagram, allowing interactivity such as responding to clicks on diagram nodes:

```python
import panel as pn

from panel_mermaid import MermaidDiagram, MermaidConfiguration

pn.extension()

diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    event_configuration=[("click", ".node")]
)

pn.FlexBox(diagram, pn.pane.JSON(diagram.param.event, theme="light")).servable()
```

In this example we will subscribe to all `click` events on elements with the `.node` class.

### 5. Mermaid SVG Value

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/snippet/panel/v1#c=H4sIAJkHDGcAA41TbW_aMBD-K5E_gRSiNEARTKnUV7XSpk1dtX4gqDL1FTw5tuc4FIT47zvHSXkZFXMkwt09fp7z48uavCoGZETejMoDrgKea2Vs8NMaLmcP3zNZJzSVIAJaBFpmsgJXmZccTE45a_Z98-ENpzND8wyxWkawtCALrmSr7TLMF4P0AN3KZIBLTX_Dq03ryK2MVM9HjGA9D74-bjNuXY7vQQg1CTqdi-Bq_MO154Pb8bMygk0O8Fi6btUttD0w-HJctR36d6kZtfCyoKKE9MmUgPnqTHjKOwHLK7Ws-8bEtRJlLnfOUR-85trJRJq63132GtQIH6PD3DtnM7BF9IQWXxqgD1KXtuXb2-f2pChY0KkA5psP5sBnc5smcdwIHRDfcQE36l0KRdmOtFtvWEoROuWStZp5cQr_yLbDCixpDmlGGkCxmO1eatOAe7ejAszCNeomhoTEwJ-SG8hB2gKHtRq9zKDt7k-nnsGLNI6SKEa4XWk301UVQ6r1Lw7vZPRGRQEhAcbtrXT0ZGSdD0Sv7FxJt2WlGGfQWSDVeZTgZkFXqrRktCYLMG6IySjBhpSyjwop142YwSgkr3MumAEEjT8qlk4LsFhEU-2cjM76cUhyLp992PXRfXUVPuTMfZFo2RWyohXXSlrKJZhPFBy0M_VYhGjqeAnZTDbhkS5qoWE3GsRJv9cfDIbd8_5g-Gn3W0p0MtIrsk-7Le9eU2SXdr8D71Ajfxajv8NBr99Lkvi820vOTrh32rHagVNuNUYdt8d_EtjfoP8_mhZnj0sqTok2OKfqnk1Y3RpO83iy-QsSF5cFhgUAAA)

If you would like the Mermaid SVG `value` to be updated would will need to set `update_value=True`:

```python
from io import StringIO
import panel as pn
from panel_mermaid import MermaidDiagram

pn.extension()

diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    update_value=True,
)

pn.FlexBox(
    pn.Column(
        diagram,
        diagram.param.update_value,
    ),
    pn.Column(
        pn.widgets.TextAreaInput(value=diagram.param.value, disabled=True, height=200),
        pn.widgets.FileDownload(
            file=pn.bind(StringIO, diagram.param.value), filename="diagram.svg"
        ),
    ),
).servable()
```

### 6. Font-Awesome Icons

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/snippet/panel/v1#c=H4sIAPfmC2cAA41STY_aMBD9K5FPrJQ4EL5EKip1tyvtoZWqPXQPBCGTDMTIsV3bfBXx3zsmZCkVK2pfPJ7xm-f35kByVQBJCa-0Mi7QTIIImA20zHAvjKrqu1kFpmK8CM6F3-vwK2dLwypfqyWFnQNpuZIty39zuZxVCD7OiHUGXF7OtrxwZUbCILd2tuAC7HiSkdI5bdM4zgu5sjQXal0sBDNAc1XFbMV2seBzGy-UdBHbglUVxAM6oO0YYWImBK24pHjOyPTBM7nm1spkgEvNV5C78TnyKyOn_R5jsS6Db6-XG7--TF5ACDUNouhz8DhZsHTBorxkxkUWtRAQ_PD61PnnyZsyopj-A4Gpp1b9sqhJRdooz6fR8aF-Hny6TQ-_9UAtmA2bC2hhREJi4NeaG6hAOosGnlzKDPrgD9HZLqxze-0NPl1jyLT-yWFLkIywEBIouHuWHpekzqzxRu9dqaR_slcFLyDatGkyoAk-Fmyv1o6kB7IB440maYJMlHKvCiEPTTODUUjykovCABZN3jOOzS04TJ5mgaSdfjsk6N9bHXbr6AX4ssQ-PsRPpMQPyyOiogZPOAeMSzAfdPCl0byuxRLNPC4hx-kxvMHi3GjUpcN20u_1h8NRd9Afjj5kf4FEJanek2vYS_pvf6jbuWsGtUJN-04b9R0Ne_1ekrQH3V7SuaPefcXOCtxTqxHqtjxlw2_Y_5-eDoeOSybuNW3qfFe_j-HJNRzjyfT4Bxzh8HCTBAAA)

To use Font-Awesome icons in your Mermaid diagrams, include the Font-Awesome CSS. Once included, you can add icons to your diagrams by prefixing with `fa:`:

```python
import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension(sizing_mode="stretch_width", css_files=["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.6.0/css/all.min.css"])

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[fa:fa-chart-simple Panel] --> E[World]
            A-->C(fa:fa-diagram-project Mermaid) --> E ;
        """
    )
).servable()
```

## API

### Parameters

- `object` (str): A valid Mermaid string.
- `value` (str): The SVG Value corresponding to Mermaid `object`. Will only be updated if `update_value` is True.
- `update_value`: If True the `value` will be updated. Default is False to save resources.
- `configuration` (dict): The mermaid configuration as described in [Mermaid | config.schema.json](https://mermaid.js.org/schemas/config.schema.json).
- `event` (dict): An event from interacting with the diagram.
- `event_configuration`: List of (event name, query selector string) tuples to subscribe to. For example `[("click", ".node")]` or `[("mouseover", ".node")]`.

## Mermaid Editor

[![py.cafe](https://py.cafe/badge.svg)](https://py.cafe/awesome.panel.org/panel-mermaid-editor)

[Open the Mermaid Editor](https://py.cafe/awesome.panel.org/panel-mermaid-editor) to explore the features and documentation of the `PanelMermaid` pane interactively.

[![Panel Mermaid | Diagram Editor](https://github.com/awesome-panel/panel-mermaid/blob/main/static/panel-mermaid-editor.gif?raw=true)](https://py.cafe/awesome.panel.org/panel-mermaid-editor)

## ❤️ Contributions

Contributions and co-maintainers are very welcome! Please submit issues or pull requests to the [GitHub repository](https://github.com/awesome-panel/panel-xml). Check out the [DEVELOPER_GUIDE](DEVELOPER_GUIDE.md) for more information.

## Alternative Projects

- [mermaid-py](https://github.com/ouhammmourachid/mermaid-py)
- [PyMermaid](https://github.com/QuattroMusic/PyMermaid)
- [pymermaider](https://github.com/diceroll123/pymermaider)
- [python-mermaid](https://github.com/Dynnammo/python_mermaid)
- [streamlit-mermaid](https://github.com/neka-nat/streamlit-mermaid)

---

Start building rich, interactive diagrams directly in your Python applications with `panel-mermaid`!