@spec community_to_options(Yog.Community.Result.t(), options()) :: options()

Creates Mermaid options that color nodes by community assignment.

Each community gets a distinct color from a generated palette. The palette cycles through visually distinct hues using inline node styles.

Example

result = Yog.Community.Louvain.detect(graph)
options = Yog.Render.Mermaid.community_to_options(result)
mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)

@spec cut_to_options(Yog.Flow.MinCutResult.t(), options()) :: options()

Creates Mermaid options that color the source and sink sides of a min-cut.

Source-side nodes are colored with source_color (default: light blue), sink-side nodes with sink_color (default: light coral).

Requires the MinCutResult to have source_side and sink_side populated (use track_partitions: true or extract_min_cut/1).

Example

result = Yog.Flow.MinCut.global_min_cut(graph, track_partitions: true)
options = Yog.Render.Mermaid.cut_to_options(result)
mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)

@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"

@spec default_options_with(
  node_label: (Yog.node_id(), any() -> String.t()),
  edge_label: (any() -> String.t())
) :: options()

Creates default Mermaid options with custom label formatters for both nodes and edges.

Example

options = Yog.Render.Mermaid.default_options_with(
  node_label: fn id, data -> "#{data} (#{id})" end,
  edge_label: fn weight -> "#{weight} ms" end
)

@spec default_options_with_edge_formatter((any() -> String.t())) :: options()

Creates default Mermaid options with a custom edge formatter.

Use this when your graph has non-String edge data (e.g., Int, Float, custom types).

Example

# For a graph with Int edge weights
options = Yog.Render.Mermaid.default_options_with_edge_formatter(fn weight ->
  Integer.to_string(weight)
end)

@spec default_options_without_labels() :: options()

Creates default Mermaid options with all edge labels hidden.

Use this when you want a clean diagram without edge annotations.

Example

mermaid = Yog.Render.Mermaid.to_mermaid(graph,
  Yog.Render.Mermaid.default_options_without_labels()
)

@spec matching_to_options(%{required(Yog.node_id()) => Yog.node_id()}, options()) ::
  options()

Creates Mermaid options that highlight matched edges from a matching result.

Works with results from both Yog.Matching.hopcroft_karp/1 and Yog.Matching.hungarian/2 (the matching map component).

Example

matching = Yog.Matching.hopcroft_karp(graph)
options = Yog.Render.Mermaid.matching_to_options(matching)
mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)

@spec mst_to_options(Yog.MST.Result.t(), options()) :: options()

Creates Mermaid options that highlight an MST result.

MST edges are highlighted and MST nodes use default styling.

Example

result = Yog.MST.kruskal(graph)
options = Yog.Render.Mermaid.mst_to_options(result)
mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)

@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

@spec theme(atom()) :: options()

Returns a pre-configured theme as Mermaid options.

Available themes:

• :default — Yellow highlight, orange stroke (same as default_options/0)
• :dark — Dark-friendly colors with neon accent colors
• :minimal — Clean wireframe look with no fills and thin lines
• :presentation — Large strokes and bold colors for slides and demos

Examples

iex> opts = Yog.Render.Mermaid.theme(:dark)
iex> opts.highlight_fill
"#16213e"
iex> opts.highlight_stroke
"#e94560"

iex> opts = Yog.Render.Mermaid.theme(:minimal)
iex> opts.link_thickness
{:px, 1}

iex> opts = Yog.Render.Mermaid.theme(:presentation)
iex> opts.highlight_stroke_width
{:px, 4}

@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, styling, and to define subgraphs.

Time Complexity: O(V + E + S) where S is the total number of nodes across all subgraphs.

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:

```mermaid
graph TD
  1["Start"]
  2["Process"]
  3["End"]
  1 -->|5| 2
  2 -->|3| 3
```