# `Yog.Render.Mermaid`
[🔗](https://github.com/code-shoily/yog_ex/blob/v0.97.0/lib/yog/render/mermaid.ex#L1)

Mermaid.js format export for embedding diagrams in web pages and documents.

This module exports graphs to [Mermaid](https://mermaid.js.org/) syntax,
a JavaScript-based diagramming tool that renders diagrams from text definitions.
Mermaid is supported natively in GitHub, GitLab, Notion, and many other platforms.

## Quick Start

    # Export to Mermaid syntax
    mermaid = Yog.Render.Mermaid.to_mermaid(my_graph, Yog.Render.Mermaid.default_options())

    # Use in Markdown:
    # ```mermaid
    # graph TD
    #     A[Node 1] --> B[Node 2]
    # ```

## Supported Diagram Types

This module generates flowchart-style diagrams:
- **Graph TD**: Top-down (vertical) layout
- **Graph LR**: Left-to-right (horizontal) layout
- **Graph BT**: Bottom-to-top layout
- **Graph RL**: Right-to-left layout

## Customization

Control styling via `t:options/0`:
- Node shapes (rounded, rectangular, circular, rhombus, hexagon, etc.)
- Labels and edge annotations
- Highlight specific nodes or edges
- Direction and orientation
- CSS-based styling with custom lengths

## Embedding Options

| Platform | Method |
|----------|--------|
| GitHub/GitLab | Native Markdown support |
| Notion | Mermaid code block |
| VS Code | Mermaid extension |
| Static site | Mermaid.js library |
| Jupyter | Mermaid magic commands |

## Live Editor

Test and refine diagrams at [Mermaid Live Editor](https://mermaid.live/).

## References

- [Mermaid Syntax](https://mermaid.js.org/syntax/flowchart.html)
- [GitHub Mermaid Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)

# `css_length`

```elixir
@type css_length() ::
  {:px, integer()}
  | {:em, float()}
  | {:rem, float()}
  | {:percent, float()}
  | {:custom, String.t()}
```

CSS length unit for styling.

Mermaid supports various CSS length units:
- `:px` - Pixels (most common)
- `:em` - Ems (relative to font size)
- `:rem` - Rems (relative to root font size)
- `:percent` - Percentage
- `{:custom, string}` - Custom CSS value (for advanced users)

# `direction`

```elixir
@type direction() :: :td | :lr | :bt | :rl
```

Direction for graph layout

# `node_shape`

```elixir
@type node_shape() ::
  :rounded_rect
  | :stadium
  | :subroutine
  | :cylinder
  | :circle
  | :asymmetric
  | :rhombus
  | :hexagon
  | :parallelogram
  | :parallelogram_alt
  | :trapezoid
  | :trapezoid_alt
```

Node shape options for Mermaid diagrams.

Each shape has a specific Mermaid syntax:
- `:rounded_rect` - `[label]` - Rectangle with rounded corners
- `:stadium` - `([label])` - Stadium shape (pill)
- `:subroutine` - `[[label]]` - Subroutine shape (rectangle with side lines)
- `:cylinder` - `[(label)]` - Cylindrical shape (database)
- `:circle` - `((label))` - Circle
- `:asymmetric` - `>label]` - Asymmetric shape (flag)
- `:rhombus` - `{label}` - Rhombus (decision)
- `:hexagon` - `{{label}}` - Hexagon
- `:parallelogram` - `[/label/]` - Parallelogram
- `:parallelogram_alt` - `[\label\]` - Parallelogram alt
- `:trapezoid` - `[/label\]` - Trapezoid
- `:trapezoid_alt` - `[\label/]` - Trapezoid alt

# `options`

```elixir
@type options() :: %{
  node_label: (Yog.node_id(), any() -> String.t()),
  edge_label: (any() -> String.t()),
  highlighted_nodes: [Yog.node_id()] | nil,
  highlighted_edges: [{Yog.node_id(), Yog.node_id()}] | nil,
  direction: direction(),
  node_shape: node_shape(),
  highlight_fill: String.t(),
  highlight_stroke: String.t(),
  highlight_stroke_width: css_length(),
  link_thickness: css_length(),
  highlight_link_stroke: String.t(),
  highlight_link_stroke_width: css_length()
}
```

Options for customizing Mermaid diagram rendering

# `default_options`

```elixir
@spec default_options() :: options()
```

Creates default Mermaid options with simple labeling.

Uses node ID as label and edge weight as-is.
Default configuration:
- Direction: Top-to-bottom (TD)
- Node shape: Rounded rectangle
- Highlight: Yellow fill with orange stroke

## Examples

    iex> opts = Yog.Render.Mermaid.default_options()
    iex> opts.direction
    :td
    iex> opts.node_shape
    :rounded_rect
    iex> opts.highlight_fill
    "#ffeb3b"

# `path_to_options`

```elixir
@spec path_to_options(map(), options()) :: options()
```

Converts a shortest path result to highlighted Mermaid options.

Creates a copy of the base options with the path's nodes and edges
set to be highlighted.

## Example

    case Yog.Pathfinding.Dijkstra.shortest_path(...) do
      {:ok, path} ->
        options = Yog.Render.Mermaid.path_to_options(path, Yog.Render.Mermaid.default_options())
        mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)
      :error ->
        ""
    end

# `to_mermaid`

```elixir
@spec to_mermaid(Yog.graph(), options()) :: String.t()
```

Converts a graph to Mermaid diagram syntax.

The graph's node data and edge data must be convertible to strings.
Use the options to customize labels and highlight specific paths.

**Time Complexity:** O(V + E)

## Example

    graph =
      Yog.directed()
      |> Yog.add_node(1, "Start")
      |> Yog.add_node(2, "Process")
      |> Yog.add_node(3, "End")
      |> Yog.add_edge_ensure(from: 1, to: 2, with: "5")
      |> Yog.add_edge_ensure(from: 2, to: 3, with: "3")

    # Basic rendering
    diagram = Yog.Render.Mermaid.to_mermaid(graph, default_options())

    # Highlight a path
    options = %{
      default_options() |
      highlighted_nodes: [1, 2, 3],
      highlighted_edges: [{1, 2}, {2, 3}]
    }
    highlighted = Yog.Render.Mermaid.to_mermaid(graph, options)

The output can be embedded in markdown:
````markdown
```mermaid
graph TD
  1["Start"]
  2["Process"]
  3["End"]
  1 -->|5| 2
  2 -->|3| 3
```
````

---

*Consult [api-reference.md](api-reference.md) for complete listing*