Skip to content
rock3rPublic

About

Mermaid flowcharts as native Compose Multiplatform composables

Resources

Stars

42 stars

Watchers

0 watching

Forks

Repository files navigation

Maradona

Maradona renders Mermaid diagrams as native Compose Multiplatform composables on Desktop (JVM), Android, and iOS — without a WebView or JavaScript runtime. It is inspired by Pele: fast Mermaid rendering that adapts to your application's theme, built for Compose instead of the browser.

Maradona diagram showcase — Flowchart, Sequence, C4 Context, and Architecture diagrams rendered as native Compose UI

Highlights

  • All 23 Mermaid diagram families parsed and laid out in pure Kotlin (commonMain), from Flowcharts, Sequence, Class, State, and ER diagrams to C4, Architecture, ZenUML, Gantt, Mindmap, Sankey, XY Chart, Radar, Packet, Kanban, and Treemap.
  • Interactive Compose UI: pan, pinch/Ctrl+scroll zoom anchored at the pointer, double-tap to reset, click / link callbacks via onNodeClick, and per-node screen-reader accessibility traversal.
  • Live-editing resilience: when the input text is mid-edit and temporarily fails to parse, Maradona keeps the last valid diagram visible (dimmed) and displays a compact error banner at the bottom.
  • Host-customizable theming, live connectors & Jewel Markdown extension: built-in light(), dark(), jewelLight(), and jewelDark() presets, MaradonaTheme.fromHost(...), dedicated theme connectors for Material 3 (:maradona-material3 across Desktop, Android, and iOS) and JetBrains Jewel (:maradona-jewel on Desktop JVM), plus a Jewel Markdown extension (dev.maradona.markdown.jewel) that renders ```mermaid / ```mmd fenced code blocks natively inside Jewel's Markdown and LazyMarkdown composables.
  • Standalone SVG export: MaradonaSvgExporter.exportToSvg(source, theme) produces standalone SVG strings across all 23 families without needing a Compose window.

Try It in 30 Seconds

Clone the repository and launch the interactive desktop editor (which includes live examples for all 23 diagram families and theme switching):

./gradlew :sample-desktop:run                      # Desktop live editor & diagram preview
./gradlew :sample-desktop:run --args="--markdown"  # Desktop Jewel Markdown + Mermaid demo
./gradlew :sample-android:installDebug             # Android sample app (requires ANDROID_HOME)
open iosApp/iosApp.xcodeproj                       # iOS sample app (Apple Silicon simulator or device)

Adding Maradona to Your Build

Maradona 0.1.0 is published on Maven Central (dev.sebastiano.maradona):

// settings.gradle.kts or build.gradle.kts
repositories {
    mavenCentral()
    google()
}

// build.gradle.kts (commonMain or platform source set)
dependencies {
    // Core parser, 23 layout engines, MaradonaDiagram & MaradonaSvgExporter (Desktop JDK 25+, Android minSdk 24, iOS arm64 / simulatorArm64)
    implementation("dev.sebastiano.maradona:maradona:0.1.0")

    // Optional: live MaterialTheme connector (Desktop, Android, iOS)
    implementation("dev.sebastiano.maradona:maradona-material3:0.1.0")

    // Optional: live JetBrains Jewel theme connector & Jewel Markdown Mermaid extension (Desktop JVM / JDK 25+ only)
    implementation("dev.sebastiano.maradona:maradona-jewel:0.1.0")
}

Note for :maradona-jewel consumers: JetBrains Jewel 0.41.0-262.* artifacts are hosted in the JetBrains IntelliJ repository (maven("https://www.jetbrains.com/intellij-repository/releases") and maven("https://packages.jetbrains.team/maven/p/ij/intellij-dependencies/")); include those repositories alongside mavenCentral() when adding dev.sebastiano.maradona:maradona-jewel:0.1.0.


Quickstart

1. Render a Diagram (MaradonaDiagram)

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import dev.maradona.render.MaradonaDiagram
import dev.maradona.render.MaradonaTheme

@Composable
fun CheckoutFlowScreen() {
    MaradonaDiagram(
        source = """
            flowchart LR
              subgraph client[Client App]
                UI[Compose UI] --> VM[ViewModel]
              end
              subgraph engine[Maradona]
                P[Parser] --> L[Layout Engine]
                L --> R([Native Composables])
              end
              VM --> P
              R --> UI
        """.trimIndent(),
        theme = MaradonaTheme.light(), // or MaradonaTheme.dark(), jewelDark(), jewelLight()
        modifier = Modifier.fillMaxSize(),
    )
}

2. Theme Connectors: Material 3 & JetBrains Jewel

Maradona ships two optional theme connector modules so diagrams automatically derive their surfaces, borders, text, semantic accents, and typography from your active host theme while keeping desktop-only dependencies out of mobile builds:

  • dev.sebastiano.maradona:maradona-material3 (Desktop, Android, iOS): ProvideMaterial3MaradonaTheme, rememberMaterial3MaradonaTheme, and MaradonaTheme.fromMaterial3(colorScheme, typography) read MaterialTheme.colorScheme and MaterialTheme.typography.
  • dev.sebastiano.maradona:maradona-jewel (Desktop JVM only): ProvideJewelMaradonaTheme, rememberJewelMaradonaTheme, and MaradonaTheme.fromJewel(...) read JewelTheme.globalColors, JewelTheme.defaultTextStyle, JewelTheme.editorTextStyle, and JewelTheme.isDark (supporting both standalone IntUiTheme and IntelliJ IDE SwingBridgeTheme).

Material 3 and Jewel Desktop live theme connectors

import androidx.compose.material3.MaterialTheme
import dev.maradona.render.MaradonaDiagram
import dev.maradona.theme.jewel.ProvideJewelMaradonaTheme
import dev.maradona.theme.material3.ProvideMaterial3MaradonaTheme
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme

// Material 3 (Desktop, Android, iOS) — derives from active MaterialTheme.colorScheme & typography
MaterialTheme {
    ProvideMaterial3MaradonaTheme {
        MaradonaDiagram(source = mermaidSource)
    }
}

// JetBrains Jewel (Desktop JVM only) — derives from active JewelTheme.globalColors & text styles
IntUiTheme(isDark = true) {
    ProvideJewelMaradonaTheme(useToolwindowBackground = true) {
        MaradonaDiagram(source = mermaidSource)
    }
}

For custom design systems (or when you don't want a connector dependency), :maradona also includes MaradonaTheme.fromHost(...) and static MaradonaTheme.light(), dark(), jewelLight(), and jewelDark() presets:

Jewel Dark and Jewel Light themes in Maradona

3. Handle Node Clicks & Links (onNodeClick)

import dev.maradona.render.MaradonaDiagram

MaradonaDiagram(
    source = """
        flowchart LR
          Spec[Design Spec] --> PR[Pull Request]
          click Spec "https://example.com/spec" "Open design spec"
          click PR call openPullRequest("42") "Review PR #42"
    """.trimIndent(),
    onNodeClick = { event ->
        // event.nodeId, event.label, event.url, event.callback, event.tooltip
        println("Clicked ${event.nodeId}: url=${event.url}, callback=${event.callback}")
    },
)

4. Export Standalone SVG (MaradonaSvgExporter)

import dev.maradona.export.MaradonaSvgExporter
import dev.maradona.render.MaradonaTheme

val svgString: String = MaradonaSvgExporter.exportToSvg(
    source = mermaidSource,
    theme = MaradonaTheme.light(),
)

5. Render Mermaid Fenced Code Blocks in JetBrains Jewel Markdown (:maradona-jewel)

:maradona-jewel also provides a Jewel Markdown extension (dev.maradona.markdown.jewel) that turns ```mermaid and ```mmd fenced code blocks into interactive MaradonaDiagram composables inside Jewel's Markdown and LazyMarkdown while leaving standard code fences (kotlin, sql, json, etc.) to Jewel's syntax highlighter:

Jewel Markdown with embedded Maradona Mermaid diagrams in Dark and Light themes

import dev.maradona.markdown.jewel.rememberMaradonaMarkdownBlockRenderer
import dev.maradona.markdown.jewel.rememberMaradonaMarkdownProcessor
import org.jetbrains.jewel.intui.markdown.standalone.ProvideMarkdownStyling
import org.jetbrains.jewel.intui.markdown.standalone.styling.dark
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme
import org.jetbrains.jewel.markdown.Markdown
import org.jetbrains.jewel.markdown.rendering.MarkdownStyling

IntUiTheme(isDark = true) {
    val styling = MarkdownStyling.dark()
    val processor = rememberMaradonaMarkdownProcessor()
    val blockRenderer = rememberMaradonaMarkdownBlockRenderer(rootStyling = styling)
    ProvideMarkdownStyling(
        isDark = true,
        markdownStyling = styling,
        markdownProcessor = processor,
        markdownBlockRenderer = blockRenderer,
    ) {
        Markdown(
            markdown = """
                # Architecture Overview

                ```mermaid
                flowchart LR
                  MD[Markdown] --> Mara([MaradonaDiagram])
                ```
            """.trimIndent(),
        )
    }
}

Supported Diagram Families (All 23)

See docs/diagram-syntax.md for the complete syntax and directive reference for every family.

Diagram Family Mermaid Header Keywords Highlights
Flowchart flowchart, graph (TD/TB, BT, LR, RL) 12 node shapes, v2 @{ shape } metadata, nested subgraphs, click, style / classDef
Sequence sequenceDiagram participant & actor, activations (+/-), loop/alt/opt/par/critical/break/rect/box, Note, autonumber
Class classDiagram, classDiagram-v2 Generics (~T~), stereotypes, visibility & static/abstract classifiers, UML relations, lollipop interfaces, namespace
State stateDiagram, stateDiagram-v2 Composite states, concurrent -- regions, [*] start/end, <<choice>>, <<fork>>, <<join>>, notes
Entity-Relationship erDiagram Crow's-foot & natural-language cardinalities, { type name PK/FK/UK "comment" } tables, nested subgraph
Mindmap mindmap Indentation tree, 7 node shapes, ::icon(...), :::class, multi-line markdown labels
Gantt gantt section, done/active/crit/milestone/vert, after/until dependencies, excludes weekends, compact mode
Pie pie, pie showData Percentage slices, configurable donutHole, highlightSlice explosion, legend
GitGraph gitGraph (LR, TB, BT) commit (NORMAL/REVERSE/HIGHLIGHT), branch, checkout, merge, cherry-pick, tags
Timeline timeline section, multi-era periods, stacked event cards
User Journey journey section, task score tracks (1–5), actor dots & legend, satisfaction mood faces
Quadrant Chart quadrantChart 4 labeled quadrants, rotated Y-axis titles, normalized [x, y] points, classDef point styling
XY Chart xychart, xychart-beta Vertical & horizontal orientations, grouped bar series, line series with point labels
Kanban kanban Columns, task cards with @{ ticket, assigned, priority, icon }, ticketBaseUrl links
Sankey sankey, sankey-beta RFC-4180 CSV flows, proportional node bars, gradient/source/target Bezier ribbons
Requirement requirementDiagram 6 requirement stereotypes + element, risk & verify badges, contains (⊕) & trace relationships
Packet packet, packet-beta Bit-range (0-15), single-bit, and relative (+8) fields, automatic bitsPerRow word wrapping
Radar radar, radar-beta Radial axes, polygon & circle graticules, multi-curve overlays, legend
Block block, block-beta columns N, column spans, nested composite blocks, 15 block shapes & directional block arrows
Architecture architecture, architecture-beta group, service, junction, vector icons (cloud, database, disk, internet, server), port-to-port edges
Treemap treemap, treemap-beta Hierarchical sections & valued leaves, squarified proportional tile layout
C4 C4Context, C4Container, C4Component, C4Dynamic, C4Deployment Person, System, Container, Component, _Db/_Queue/_Ext, nested boundaries, Rel / RelIndex
ZenUML zenuml @Actor/@Boundary/@Database stereotypes, nested call blocks, if/else/while/try/catch, // comments

Supported Targets & Modules

Module Targets Purpose
:maradona jvm("desktop") (JDK 25+), android (minSdk 24, JDK 25+), iosArm64(), iosSimulatorArm64() Core parser, 23 layout engines, MaradonaDiagram, MaradonaTheme, MaradonaSvgExporter (compose-runtime, compose-foundation, compose-ui only)
:maradona-material3 jvm("desktop") (JDK 25+), android (minSdk 24, JDK 25+), iosArm64(), iosSimulatorArm64() Live MaterialTheme connector (ProvideMaterial3MaradonaTheme, rememberMaterial3MaradonaTheme, MaradonaTheme.fromMaterial3)
:maradona-jewel jvm("desktop") (Desktop JVM / JDK 25+ only) Live JetBrains JewelTheme connector (ProvideJewelMaradonaTheme, rememberJewelMaradonaTheme, MaradonaTheme.fromJewel) and Jewel Markdown Mermaid extension (MermaidMarkdownProcessorExtension, MermaidMarkdownRendererExtension, MaradonaMarkdownBlockRenderer)

All library code lives in commonMain across three layers:

  1. Parser (dev.maradona.parse.MaradonaParser) — Pure Kotlin. Detects the diagram header/frontmatter and parses the source into a typed MaradonaDiagramModel without Compose dependencies.
  2. Layout (dev.maradona.layout.*) — Pure Kotlin. Measures and positions nodes, containers, and edge routes (using a multiplatform port of Dagre/Sugiyama for directed graphs and dedicated layout engines for sequence, tree, timeline, chart, and grid families).
  3. Render & Export (dev.maradona.render.MaradonaDiagram, dev.maradona.export.MaradonaSvgExporter) — Compose Multiplatform layouts that measure real composable nodes (preserving native text shaping, click hit-testing, and accessibility semantics), draw underlay splines/containers on a single canvas layer, or export standalone SVG.

Maturity, Performance & Known Limitations

  • Release status & binary/API compatibility (0.1.0 on Maven Central): Maradona 0.1.0 is published on Maven Central. While pre-1.0, all three published modules (:maradona, :maradona-material3, :maradona-jewel) track binary and source compatibility across JVM, Android, and iOS KLib targets via Kotlin's built-in abiValidation() baselines (./gradlew checkKotlinAbi) and automated API-design/boundary lint (./gradlew verifyApiDesign), both enforced in CI and release workflows. Published -sources.jar artifacts carry complete KDoc for IDE quick-documentation; -javadoc.jar is an intentional JavadocJar.Empty() placeholder for Sonatype Central validation rather than generated Dokka HTML.
  • Structural vs. pixel parity with mermaid.js: Flowchart layout ports Dagre's ranking, crossing reduction, and Brandes–Köpf coordinate assignment (<= 5% node size and <= 2% centre tolerance against mermaid.js), while the other 22 families use independent pure-Kotlin layout engines. Renders are structurally faithful and verified across 71 fixtures on Desktop, Android, and iOS, not pixel-identical to Chromium mermaid.js.
  • Large diagram scalability: Inputs are capped at 50,000 characters, 5,000 nodes, and 5,000 edges. When zoomed in (viewportCullingEnabled = true, the default), Maradona lazily composes only on-screen nodes/labels and culls off-screen underlay elements across all 23 diagram families while keeping cross-viewport edges and off-screen accessibility actions intact (~2.6 ms/frame when panning a 400-node graph). When zoomed out so that thousands of nodes are simultaneously visible inside the viewport, layout and frame times remain CPU-bound.

Documentation

License

Apache License 2.0 — see LICENSE.

About

Mermaid flowcharts as native Compose Multiplatform composables

Resources

Stars

42 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages