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