| 1 | --- |
| 2 | references: |
| 3 | - "File: /packages/mermaid/src/mermaidAPI.ts" |
| 4 | - "File: /packages/mermaid/src/mermaid.ts" |
| 5 | generationTime: 2025-01-28T16:30:00.000Z |
| 6 | --- |
| 7 | sequenceDiagram |
| 8 | participant User as User/Browser |
| 9 | participant Mermaid as mermaid.ts |
| 10 | participant Queue as executionQueue |
| 11 | participant API as mermaidAPI.ts |
| 12 | participant Config as configApi |
| 13 | participant Preprocessor as preprocessDiagram |
| 14 | participant DiagramAPI as diagram-api |
| 15 | participant Diagram as Diagram.fromText |
| 16 | participant Renderer as diagram.renderer |
| 17 | participant Styles as Styling System |
| 18 | participant DOM as DOM/SVG |
| 19 | |
| 20 | Note over User, DOM: Mermaid Complete API Flow |
| 21 | |
| 22 | %% Initialization Phase |
| 23 | User->>+Mermaid: mermaid.initialize(config) |
| 24 | Mermaid->>+API: mermaidAPI.initialize(config) |
| 25 | |
| 26 | API->>API: assignWithDepth({}, userOptions) |
| 27 | API->>API: handle legacy fontFamily config |
| 28 | API->>Config: saveConfigFromInitialize(options) |
| 29 | |
| 30 | alt Theme Configuration Available |
| 31 | API->>API: check if theme in theme object |
| 32 | API->>API: set themeVariables from theme |
| 33 | else Default Theme |
| 34 | API->>API: use default theme variables |
| 35 | end |
| 36 | |
| 37 | API->>Config: setSiteConfig(options) or getSiteConfig() |
| 38 | API->>API: setLogLevel(config.logLevel) |
| 39 | API->>DiagramAPI: addDiagrams() |
| 40 | |
| 41 | API-->>-Mermaid: initialization complete |
| 42 | Mermaid-->>-User: ready to render |
| 43 | |
| 44 | %% Content Loaded Event |
| 45 | User->>DOM: document.load event |
| 46 | DOM->>+Mermaid: contentLoaded() |
| 47 | |
| 48 | opt startOnLoad is true |
| 49 | Mermaid->>Config: getConfig() |
| 50 | Config-->>Mermaid: { startOnLoad: true } |
| 51 | Mermaid->>Mermaid: run() |
| 52 | end |
| 53 | |
| 54 | Mermaid-->>-DOM: event handling complete |
| 55 | |
| 56 | %% Main Run Function |
| 57 | User->>+Mermaid: mermaid.run(options) |
| 58 | |
| 59 | Mermaid->>Mermaid: runThrowsErrors(options) |
| 60 | Mermaid->>Config: getConfig() |
| 61 | Config-->>Mermaid: configuration object |
| 62 | |
| 63 | alt nodes provided |
| 64 | Mermaid->>Mermaid: use provided nodes |
| 65 | else querySelector provided |
| 66 | Mermaid->>DOM: document.querySelectorAll(querySelector) |
| 67 | DOM-->>Mermaid: nodesToProcess |
| 68 | end |
| 69 | |
| 70 | Mermaid->>Mermaid: new InitIDGenerator(deterministicIds, seed) |
| 71 | |
| 72 | loop For each diagram element |
| 73 | Mermaid->>DOM: check element.getAttribute('data-processed') |
| 74 | |
| 75 | opt not processed |
| 76 | Mermaid->>DOM: element.setAttribute('data-processed', 'true') |
| 77 | Mermaid->>Mermaid: generate unique id |
| 78 | Mermaid->>DOM: get element.innerHTML |
| 79 | Mermaid->>Mermaid: entityDecode and clean text |
| 80 | Mermaid->>Mermaid: detectInit(txt) |
| 81 | |
| 82 | Mermaid->>Queue: render(id, txt, element) |
| 83 | end |
| 84 | end |
| 85 | |
| 86 | Mermaid-->>-User: processing initiated |
| 87 | |
| 88 | %% Render Function (Queued) |
| 89 | activate Queue |
| 90 | Queue->>+API: mermaidAPI.render(id, text, container) |
| 91 | |
| 92 | API->>DiagramAPI: addDiagrams() |
| 93 | API->>+Preprocessor: processAndSetConfigs(text) |
| 94 | |
| 95 | Preprocessor->>Preprocessor: preprocessDiagram(text) |
| 96 | Preprocessor->>Config: reset() |
| 97 | Preprocessor->>Config: addDirective(processed.config) |
| 98 | Preprocessor-->>-API: { code, config } |
| 99 | |
| 100 | API->>Config: getConfig() |
| 101 | Config-->>API: current configuration |
| 102 | |
| 103 | opt text length > maxTextSize |
| 104 | API->>API: text = MAX_TEXTLENGTH_EXCEEDED_MSG |
| 105 | end |
| 106 | |
| 107 | API->>API: setup id selectors and element IDs |
| 108 | API->>API: determine security level (sandbox/loose) |
| 109 | |
| 110 | %% DOM Setup |
| 111 | alt svgContainingElement provided |
| 112 | alt isSandboxed |
| 113 | API->>DOM: sandboxedIframe(select(svgContainingElement), iFrameID) |
| 114 | API->>DOM: select iframe contentDocument body |
| 115 | else |
| 116 | API->>DOM: select(svgContainingElement) |
| 117 | end |
| 118 | else no container |
| 119 | API->>API: removeExistingElements(document, id, divId, iFrameId) |
| 120 | alt isSandboxed |
| 121 | API->>DOM: sandboxedIframe(select('body'), iFrameID) |
| 122 | else |
| 123 | API->>DOM: select('body') |
| 124 | end |
| 125 | end |
| 126 | |
| 127 | API->>DOM: appendDivSvgG(root, id, enclosingDivID, fontFamily, XMLNS_XLINK_STD) |
| 128 | |
| 129 | %% Diagram Creation |
| 130 | API->>+Diagram: Diagram.fromText(text, { title: processed.title }) |
| 131 | |
| 132 | Diagram->>DiagramAPI: detect diagram type |
| 133 | Diagram->>DiagramAPI: load appropriate diagram |
| 134 | Diagram-->>-API: diagram instance |
| 135 | |
| 136 | opt parsing error occurred |
| 137 | API->>+Diagram: Diagram.fromText('error') |
| 138 | Diagram-->>-API: error diagram |
| 139 | API->>API: store parseEncounteredException |
| 140 | end |
| 141 | |
| 142 | %% Style Generation |
| 143 | API->>DOM: get svg element and firstChild |
| 144 | API->>Renderer: diag.renderer.getClasses(text, diag) |
| 145 | Renderer-->>API: diagramClassDefs |
| 146 | |
| 147 | API->>+Styles: createUserStyles(config, diagramType, diagramClassDefs, idSelector) |
| 148 | |
| 149 | Styles->>Styles: createCssStyles(config, classDefs) |
| 150 | |
| 151 | opt config.themeCSS defined |
| 152 | Styles->>Styles: append themeCSS |
| 153 | end |
| 154 | |
| 155 | opt fontFamily configured |
| 156 | Styles->>Styles: add CSS variables for fonts |
| 157 | end |
| 158 | |
| 159 | opt classDefs exist |
| 160 | loop For each styleClassDef |
| 161 | opt has styles |
| 162 | Styles->>Styles: cssImportantStyles for each CSS element |
| 163 | end |
| 164 | opt has textStyles |
| 165 | Styles->>Styles: cssImportantStyles for tspan elements |
| 166 | end |
| 167 | end |
| 168 | end |
| 169 | |
| 170 | Styles->>Styles: getStyles(graphType, userCSSstyles, themeVariables) |
| 171 | Styles->>Styles: serialize(compile(svgId{allStyles}), stringify) |
| 172 | Styles-->>-API: compiled CSS rules |
| 173 | |
| 174 | API->>DOM: create style element |
| 175 | API->>DOM: style.innerHTML = rules |
| 176 | API->>DOM: svg.insertBefore(style, firstChild) |
| 177 | |
| 178 | %% Diagram Rendering |
| 179 | API->>+Renderer: diag.renderer.draw(text, id, version, diag) |
| 180 | |
| 181 | Renderer->>Renderer: diagram-specific rendering logic |
| 182 | Renderer->>DOM: create SVG elements |
| 183 | Renderer->>DOM: apply positioning and styling |
| 184 | Renderer-->>-API: rendered diagram |
| 185 | |
| 186 | opt rendering error |
| 187 | alt suppressErrorRendering |
| 188 | API->>API: removeTempElements() |
| 189 | API->>Mermaid: throw error |
| 190 | else |
| 191 | API->>Renderer: errorRenderer.draw(text, id, version) |
| 192 | end |
| 193 | end |
| 194 | |
| 195 | %% Accessibility and Cleanup |
| 196 | API->>DOM: select svg element |
| 197 | API->>Diagram: diag.db.getAccTitle() |
| 198 | API->>Diagram: diag.db.getAccDescription() |
| 199 | API->>API: addA11yInfo(diagramType, svgNode, a11yTitle, a11yDescr) |
| 200 | |
| 201 | API->>DOM: set xmlns for foreignobject elements |
| 202 | API->>DOM: get innerHTML from enclosing div |
| 203 | |
| 204 | API->>+API: cleanUpSvgCode(svgCode, isSandboxed, arrowMarkerAbsolute) |
| 205 | |
| 206 | opt not useArrowMarkerUrls and not sandboxed |
| 207 | API->>API: replace marker-end URLs with anchors |
| 208 | end |
| 209 | |
| 210 | API->>API: decodeEntities(svgCode) |
| 211 | API->>API: replace <br> with <br/> |
| 212 | API-->>-API: cleaned SVG code |
| 213 | |
| 214 | alt isSandboxed |
| 215 | API->>+API: putIntoIFrame(svgCode, svgEl) |
| 216 | API->>API: calculate iframe height |
| 217 | API->>API: toBase64 encode SVG content |
| 218 | API->>API: create iframe with sandbox attributes |
| 219 | API-->>-API: iframe HTML |
| 220 | else not loose security |
| 221 | API->>API: DOMPurify.sanitize(svgCode, options) |
| 222 | end |
| 223 | |
| 224 | API->>API: attachFunctions() |
| 225 | API->>API: removeTempElements() |
| 226 | |
| 227 | opt parseEncounteredException |
| 228 | API->>Mermaid: throw parseEncounteredException |
| 229 | end |
| 230 | |
| 231 | API-->>-Queue: { diagramType, svg: svgCode, bindFunctions } |
| 232 | |
| 233 | %% Return to Web Integration |
| 234 | activate Mermaid |
| 235 | Queue-->>Mermaid: render result |
| 236 | Mermaid->>DOM: element.innerHTML = svg |
| 237 | |
| 238 | opt postRenderCallback |
| 239 | Mermaid->>User: postRenderCallback(id) |
| 240 | end |
| 241 | |
| 242 | opt bindFunctions exist |
| 243 | Mermaid->>DOM: bindFunctions(element) |
| 244 | end |
| 245 | deactivate Mermaid |
| 246 | |
| 247 | %% Parse Function Flow |
| 248 | User->>+Mermaid: mermaid.parse(text, parseOptions) |
| 249 | activate Queue |
| 250 | |
| 251 | Queue->>+API: mermaidAPI.parse(text, parseOptions) |
| 252 | |
| 253 | API->>DiagramAPI: addDiagrams() |
| 254 | API->>Preprocessor: processAndSetConfigs(text) |
| 255 | Preprocessor-->>API: { code, config } |
| 256 | API->>Diagram: getDiagramFromText(code) |
| 257 | Diagram-->>API: diagram instance |
| 258 | API-->>-Queue: { diagramType: diagram.type, config } |
| 259 | |
| 260 | Queue-->>-Mermaid: parse result |
| 261 | Mermaid-->>-User: ParseResult or false |
| 262 | |
| 263 | %% External Diagram Registration |
| 264 | User->>+Mermaid: registerExternalDiagrams(diagrams, options) |
| 265 | |
| 266 | Mermaid->>DiagramAPI: addDiagrams() |
| 267 | Mermaid->>DiagramAPI: registerLazyLoadedDiagrams(...diagrams) |
| 268 | |
| 269 | opt lazyLoad is false |
| 270 | Mermaid->>DiagramAPI: loadRegisteredDiagrams() |
| 271 | end |
| 272 | |
| 273 | Mermaid-->>-User: registration complete |
| 274 | |
| 275 | %% Error Handling |
| 276 | Note over Mermaid, API: Error Handling Throughout |
| 277 | alt Error occurs |
| 278 | API->>Mermaid: throw error |
| 279 | Mermaid->>+Mermaid: handleError(error, errors, parseError) |
| 280 | |
| 281 | Mermaid->>Mermaid: log.warn(error) |
| 282 | |
| 283 | alt isDetailedError |
| 284 | Mermaid->>User: parseError(error.str, error.hash) |
| 285 | else |
| 286 | Mermaid->>User: parseError(error) |
| 287 | end |
| 288 | |
| 289 | opt not suppressErrors |
| 290 | Mermaid->>User: throw error |
| 291 | end |
| 292 | |
| 293 | Mermaid-->>-User: error handled |
| 294 | end |
| 295 | |
| 296 | %% Configuration Details |
| 297 | Note over Config: Configuration Functions |
| 298 | Note right of Config: Functions:<br/>- reset()<br/>- getConfig()<br/>- setConfig()<br/>- getSiteConfig()<br/>- updateSiteConfig()<br/>- saveConfigFromInitialize() |
| 299 | |
| 300 | Note over Styles: CSS Generation |
| 301 | Note right of Styles: Features:<br/>- createCssStyles()<br/>- createUserStyles()<br/>- cssImportantStyles()<br/>- Theme integration<br/>- Class definitions |
| 302 | |
| 303 | Note over API: Security Levels |
| 304 | Note right of API: Modes:<br/>- sandbox: iframe isolation<br/>- loose: minimal sanitization<br/>- default: DOMPurify sanitization |
| 305 | |
| 306 | Note over API: Helper Functions |
| 307 | Note right of API: Utilities:<br/>- cleanUpSvgCode()<br/>- putIntoIFrame()<br/>- appendDivSvgG()<br/>- removeExistingElements() |