mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-11-21 05:04:08 +01:00
Merge branch 'develop' into ipsep-cola
This commit is contained in:
shubham-mermaid
@@ -301,7 +301,7 @@ If you are adding a feature, you will definitely need to add tests. Depending on
|
||||
|
||||
Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run.
|
||||
|
||||
Unit tests are mandatory for all code except the renderers. (The renderers are tested with integration tests.)
|
||||
Unit tests are mandatory for all code except the layout tests. (The layouts are tested with integration tests.)
|
||||
|
||||
We use [Vitest](https://vitest.dev) to run unit tests.
|
||||
|
||||
@@ -327,6 +327,30 @@ When using Docker prepend your command with `./run`:
|
||||
./run pnpm test
|
||||
```
|
||||
|
||||
##### Testing the DOM
|
||||
|
||||
One can use `jsdomIt` to test any part of Mermaid that interacts with the DOM, as long as it is not related to the layout.
|
||||
|
||||
The function `jsdomIt` ([developed in utils.ts](../../tests/util.ts)) overrides `it` from `vitest`, and creates a pseudo-browser environment that works almost like the real deal for the duration of the test. It uses JSDOM to create a DOM, and adds objects `window` and `document` to `global` to mock the browser environment.
|
||||
|
||||
> \[!NOTE]
|
||||
> The layout cannot work in `jsdomIt` tests because JSDOM has no rendering engine, hence the pseudo-browser environment.
|
||||
|
||||
Example :
|
||||
|
||||
```typescript
|
||||
import { ensureNodeFromSelector, jsdomIt } from './tests/util.js';
|
||||
|
||||
jsdomIt('should add element "thing" in the SVG', ({ svg }) => {
|
||||
// Code in this block runs in a pseudo-browser environment
|
||||
addThing(svg); // The svg item is the D3 selection of the SVG node
|
||||
const svgNode = ensureNodeFromSelector('svg'); // Retrieve the DOM node using the DOM API
|
||||
expect(svgNode.querySelector('thing')).not.toBeNull(); // Test the structure of the SVG
|
||||
});
|
||||
```
|
||||
|
||||
They can be used to test any method that interacts with the DOM, including for testing renderers. For renderers, additional integration testing is necessary to test the layout though.
|
||||
|
||||
#### Integration / End-to-End (E2E) Tests
|
||||
|
||||
These test the rendering and visual appearance of the diagrams.
|
||||
|
||||
@@ -111,3 +111,13 @@ const themes = {
|
||||
```
|
||||
|
||||
The actual options and values for the colors are defined in **src/theme/theme-\[xyz].js**. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups.
|
||||
|
||||
## Examples
|
||||
|
||||
The `@mermaid-js/examples` package contains a collection of examples that are used by tools like mermaid.live to help users get started with the new diagram.
|
||||
|
||||
You can duplicate an existing diagram example file, eg: `packages/examples/src/examples/flowchart.ts`, and modify it with details specific to your diagram.
|
||||
|
||||
Then you can import the example in the `packages/examples/src/index.ts` file and add it to the `examples` array.
|
||||
|
||||
Each diagram should have at least one example, and that should be marked as default. It is good to add more examples to showcase different features of the diagram.
|
||||
|
||||
@@ -12,4 +12,4 @@
|
||||
|
||||
> `const` **configKeys**: `Set`<`string`>
|
||||
|
||||
Defined in: [packages/mermaid/src/defaultConfig.ts:278](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L278)
|
||||
Defined in: [packages/mermaid/src/defaultConfig.ts:290](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L290)
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
# Interface: ExternalDiagramDefinition
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:99](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L99)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:94](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L94)
|
||||
|
||||
## Properties
|
||||
|
||||
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/diagram-api/types.ts:99](https://github.com/me
|
||||
|
||||
> **detector**: `DiagramDetector`
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:101](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L101)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:96](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L96)
|
||||
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ Defined in: [packages/mermaid/src/diagram-api/types.ts:101](https://github.com/m
|
||||
|
||||
> **id**: `string`
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:100](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L100)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:95](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L95)
|
||||
|
||||
---
|
||||
|
||||
@@ -34,4 +34,4 @@ Defined in: [packages/mermaid/src/diagram-api/types.ts:100](https://github.com/m
|
||||
|
||||
> **loader**: `DiagramLoader`
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:102](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L102)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:97](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L97)
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
# Interface: Mermaid
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:418](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L418)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:429](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L429)
|
||||
|
||||
## Properties
|
||||
|
||||
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/mermaid.ts:418](https://github.com/mermaid-js/
|
||||
|
||||
> **contentLoaded**: () => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:436](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L436)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:447](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L447)
|
||||
|
||||
\##contentLoaded Callback function that is called when page is loaded. This functions fetches
|
||||
configuration for mermaid rendering and calls init for rendering the mermaid diagrams on the
|
||||
@@ -34,7 +34,7 @@ page.
|
||||
|
||||
> **detectType**: (`text`, `config`?) => `string`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:438](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L438)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:449](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L449)
|
||||
|
||||
Detects the type of the graph text.
|
||||
|
||||
@@ -86,11 +86,28 @@ A graph definition key
|
||||
|
||||
---
|
||||
|
||||
### getRegisteredDiagramsMetadata()
|
||||
|
||||
> **getRegisteredDiagramsMetadata**: () => `Pick`<[`ExternalDiagramDefinition`](ExternalDiagramDefinition.md), `"id"`>\[]
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:451](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L451)
|
||||
|
||||
Gets the metadata for all registered diagrams.
|
||||
Currently only the id is returned.
|
||||
|
||||
#### Returns
|
||||
|
||||
`Pick`<[`ExternalDiagramDefinition`](ExternalDiagramDefinition.md), `"id"`>\[]
|
||||
|
||||
An array of objects with the id of the diagram.
|
||||
|
||||
---
|
||||
|
||||
### ~~init()~~
|
||||
|
||||
> **init**: (`config`?, `nodes`?, `callback`?) => `Promise`<`void`>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:431](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L431)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:442](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L442)
|
||||
|
||||
## init
|
||||
|
||||
@@ -138,7 +155,7 @@ Use [initialize](Mermaid.md#initialize) and [run](Mermaid.md#run) instead.
|
||||
|
||||
> **initialize**: (`config`) => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:435](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L435)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:446](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L446)
|
||||
|
||||
Used to set configurations for mermaid.
|
||||
This function should be called before the run function.
|
||||
@@ -161,7 +178,7 @@ Configuration object for mermaid.
|
||||
|
||||
> **mermaidAPI**: `Readonly`<{ `defaultConfig`: [`MermaidConfig`](MermaidConfig.md); `getConfig`: () => [`MermaidConfig`](MermaidConfig.md); `getDiagramFromText`: (`text`, `metadata`) => `Promise`<`Diagram`>; `getSiteConfig`: () => [`MermaidConfig`](MermaidConfig.md); `globalReset`: () => `void`; `initialize`: (`userOptions`) => `void`; `parse`: (`text`, `parseOptions`) => `Promise`<`false` | [`ParseResult`](ParseResult.md)>(`text`, `parseOptions`?) => `Promise`<[`ParseResult`](ParseResult.md)>; `render`: (`id`, `text`, `svgContainingElement`?) => `Promise`<[`RenderResult`](RenderResult.md)>; `reset`: () => `void`; `setConfig`: (`conf`) => [`MermaidConfig`](MermaidConfig.md); `updateSiteConfig`: (`conf`) => [`MermaidConfig`](MermaidConfig.md); }>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:425](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L425)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:436](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L436)
|
||||
|
||||
**`Internal`**
|
||||
|
||||
@@ -175,7 +192,7 @@ Use [parse](Mermaid.md#parse) and [render](Mermaid.md#render) instead. Please [o
|
||||
|
||||
> **parse**: (`text`, `parseOptions`) => `Promise`<`false` | [`ParseResult`](ParseResult.md)>(`text`, `parseOptions`?) => `Promise`<[`ParseResult`](ParseResult.md)>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:426](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L426)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:437](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L437)
|
||||
|
||||
Parse the text and validate the syntax.
|
||||
|
||||
@@ -243,7 +260,7 @@ Error if the diagram is invalid and parseOptions.suppressErrors is false or not
|
||||
|
||||
> `optional` **parseError**: [`ParseErrorFunction`](../type-aliases/ParseErrorFunction.md)
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:420](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L420)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:431](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L431)
|
||||
|
||||
---
|
||||
|
||||
@@ -251,7 +268,7 @@ Defined in: [packages/mermaid/src/mermaid.ts:420](https://github.com/mermaid-js/
|
||||
|
||||
> **registerExternalDiagrams**: (`diagrams`, `opts`) => `Promise`<`void`>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:434](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L434)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:445](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L445)
|
||||
|
||||
Used to register external diagram types.
|
||||
|
||||
@@ -281,7 +298,7 @@ If opts.lazyLoad is false, the diagrams will be loaded immediately.
|
||||
|
||||
> **registerIconPacks**: (`iconLoaders`) => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:439](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L439)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:450](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L450)
|
||||
|
||||
#### Parameters
|
||||
|
||||
@@ -299,7 +316,7 @@ Defined in: [packages/mermaid/src/mermaid.ts:439](https://github.com/mermaid-js/
|
||||
|
||||
> **registerLayoutLoaders**: (`loaders`) => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:433](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L433)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:444](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L444)
|
||||
|
||||
#### Parameters
|
||||
|
||||
@@ -317,7 +334,7 @@ Defined in: [packages/mermaid/src/mermaid.ts:433](https://github.com/mermaid-js/
|
||||
|
||||
> **render**: (`id`, `text`, `svgContainingElement`?) => `Promise`<[`RenderResult`](RenderResult.md)>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:427](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L427)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:438](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L438)
|
||||
|
||||
#### Parameters
|
||||
|
||||
@@ -349,7 +366,7 @@ Deprecated for external use.
|
||||
|
||||
> **run**: (`options`) => `Promise`<`void`>
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:432](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L432)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:443](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L443)
|
||||
|
||||
## run
|
||||
|
||||
@@ -393,7 +410,7 @@ Optional runtime configs
|
||||
|
||||
> **setParseErrorHandler**: (`parseErrorHandler`) => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:437](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L437)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:448](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L448)
|
||||
|
||||
## setParseErrorHandler Alternative to directly setting parseError using:
|
||||
|
||||
@@ -424,4 +441,4 @@ New parseError() callback.
|
||||
|
||||
> **startOnLoad**: `boolean`
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:419](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L419)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:430](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L430)
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
# Interface: ParseOptions
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:59](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L59)
|
||||
Defined in: [packages/mermaid/src/types.ts:72](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L72)
|
||||
|
||||
## Properties
|
||||
|
||||
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:59](https://github.com/mermaid-js/mer
|
||||
|
||||
> `optional` **suppressErrors**: `boolean`
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:64](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L64)
|
||||
Defined in: [packages/mermaid/src/types.ts:77](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L77)
|
||||
|
||||
If `true`, parse will return `false` instead of throwing error when the diagram is invalid.
|
||||
The `parseError` function will not be called.
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
# Interface: ParseResult
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:67](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L67)
|
||||
Defined in: [packages/mermaid/src/types.ts:80](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L80)
|
||||
|
||||
## Properties
|
||||
|
||||
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:67](https://github.com/mermaid-js/mer
|
||||
|
||||
> **config**: [`MermaidConfig`](MermaidConfig.md)
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:75](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L75)
|
||||
Defined in: [packages/mermaid/src/types.ts:88](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L88)
|
||||
|
||||
The config passed as YAML frontmatter or directives
|
||||
|
||||
@@ -28,6 +28,6 @@ The config passed as YAML frontmatter or directives
|
||||
|
||||
> **diagramType**: `string`
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:71](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L71)
|
||||
Defined in: [packages/mermaid/src/types.ts:84](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L84)
|
||||
|
||||
The diagram type, e.g. 'flowchart', 'sequence', etc.
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
# Interface: RenderResult
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:85](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L85)
|
||||
Defined in: [packages/mermaid/src/types.ts:98](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L98)
|
||||
|
||||
## Properties
|
||||
|
||||
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:85](https://github.com/mermaid-js/mer
|
||||
|
||||
> `optional` **bindFunctions**: (`element`) => `void`
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:103](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L103)
|
||||
Defined in: [packages/mermaid/src/types.ts:116](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L116)
|
||||
|
||||
Bind function to be called after the svg has been inserted into the DOM.
|
||||
This is necessary for adding event listeners to the elements in the svg.
|
||||
@@ -45,7 +45,7 @@ bindFunctions?.(div); // To call bindFunctions only if it's present.
|
||||
|
||||
> **diagramType**: `string`
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:93](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L93)
|
||||
Defined in: [packages/mermaid/src/types.ts:106](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L106)
|
||||
|
||||
The diagram type, e.g. 'flowchart', 'sequence', etc.
|
||||
|
||||
@@ -55,6 +55,6 @@ The diagram type, e.g. 'flowchart', 'sequence', etc.
|
||||
|
||||
> **svg**: `string`
|
||||
|
||||
Defined in: [packages/mermaid/src/types.ts:89](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L89)
|
||||
Defined in: [packages/mermaid/src/types.ts:102](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L102)
|
||||
|
||||
The svg code for the rendered graph.
|
||||
|
||||
@@ -12,4 +12,4 @@
|
||||
|
||||
> **SVG**: `d3.Selection`<`SVGSVGElement`, `unknown`, `Element` | `null`, `unknown`>
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:130](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L130)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:126](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L126)
|
||||
|
||||
@@ -12,4 +12,4 @@
|
||||
|
||||
> **SVGGroup**: `d3.Selection`<`SVGGElement`, `unknown`, `Element` | `null`, `unknown`>
|
||||
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:132](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L132)
|
||||
Defined in: [packages/mermaid/src/diagram-api/types.ts:128](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagram-api/types.ts#L128)
|
||||
|
||||
@@ -12,4 +12,4 @@
|
||||
|
||||
> `const` **default**: [`Mermaid`](../interfaces/Mermaid.md)
|
||||
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:442](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L442)
|
||||
Defined in: [packages/mermaid/src/mermaid.ts:454](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaid.ts#L454)
|
||||
|
||||
189
docs/diagrams/flowchart-code-flow.mmd
Normal file
189
docs/diagrams/flowchart-code-flow.mmd
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
references:
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowDiagram.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowDb.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowDetector.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowDetector-v2.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowRenderer-v3-unified.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/styles.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/types.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/flowChartShapes.js"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/parser/flowParser.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/flowchart/elk/detector.ts"
|
||||
generationTime: 2025-07-23T10:31:53.266Z
|
||||
---
|
||||
flowchart TD
|
||||
%% Entry Points and Detection
|
||||
Input["User Input Text"] --> Detection{Detection Phase}
|
||||
|
||||
Detection --> flowDetector["flowDetector.ts<br/>detector(txt, config)"]
|
||||
Detection --> flowDetectorV2["flowDetector-v2.ts<br/>detector(txt, config)"]
|
||||
Detection --> elkDetector["elk/detector.ts<br/>detector(txt, config)"]
|
||||
|
||||
flowDetector --> |"Checks /^\s*graph/"| DetectLegacy{Legacy Flowchart?}
|
||||
flowDetectorV2 --> |"Checks /^\s*flowchart/"| DetectNew{New Flowchart?}
|
||||
elkDetector --> |"Checks /^\s*flowchart-elk/"| DetectElk{ELK Layout?}
|
||||
|
||||
DetectLegacy --> |Yes| LoadDiagram
|
||||
DetectNew --> |Yes| LoadDiagram
|
||||
DetectElk --> |Yes| LoadDiagram
|
||||
|
||||
%% Loading Phase
|
||||
LoadDiagram["loader() function"] --> flowDiagram["flowDiagram.ts<br/>diagram object"]
|
||||
|
||||
flowDiagram --> DiagramStructure{Diagram Components}
|
||||
DiagramStructure --> Parser["parser: flowParser"]
|
||||
DiagramStructure --> Database["db: new FlowDB()"]
|
||||
DiagramStructure --> Renderer["renderer: flowRenderer-v3-unified"]
|
||||
DiagramStructure --> Styles["styles: flowStyles"]
|
||||
DiagramStructure --> Init["init: (cnf: MermaidConfig)"]
|
||||
|
||||
%% Parser Phase
|
||||
Parser --> flowParser["parser/flowParser.ts<br/>newParser.parse(src)"]
|
||||
flowParser --> |"Preprocesses src"| RemoveWhitespace["Remove trailing whitespace<br/>src.replace(/}\s*\n/g, '}\n')"]
|
||||
RemoveWhitespace --> flowJison["parser/flow.jison<br/>flowJisonParser.parse(newSrc)"]
|
||||
|
||||
flowJison --> ParseGraph["Parse Graph Structure"]
|
||||
ParseGraph --> ParseVertices["Parse Vertices"]
|
||||
ParseGraph --> ParseEdges["Parse Edges"]
|
||||
ParseGraph --> ParseSubgraphs["Parse Subgraphs"]
|
||||
ParseGraph --> ParseClasses["Parse Classes"]
|
||||
ParseGraph --> ParseStyles["Parse Styles"]
|
||||
|
||||
%% Database Phase - FlowDB Class
|
||||
Database --> FlowDBClass["flowDb.ts<br/>FlowDB class"]
|
||||
|
||||
FlowDBClass --> DBInit["constructor()<br/>- Initialize counters<br/>- Bind methods<br/>- Setup toolTips<br/>- Call clear()"]
|
||||
|
||||
DBInit --> DBMethods{FlowDB Methods}
|
||||
|
||||
DBMethods --> addVertex["addVertex(id, textObj, type, style,<br/>classes, dir, props, metadata)"]
|
||||
DBMethods --> addLink["addLink(_start[], _end[], linkData)"]
|
||||
DBMethods --> addSingleLink["addSingleLink(_start, _end, type, id)"]
|
||||
DBMethods --> setDirection["setDirection(dir)"]
|
||||
DBMethods --> addSubGraph["addSubGraph(nodes[], id, title)"]
|
||||
DBMethods --> addClass["addClass(id, style)"]
|
||||
DBMethods --> setClass["setClass(ids, className)"]
|
||||
DBMethods --> setTooltip["setTooltip(ids, tooltip)"]
|
||||
DBMethods --> setClickEvent["setClickEvent(id, functionName, args)"]
|
||||
DBMethods --> setClickFun["setClickFun(id, functionName, args)"]
|
||||
|
||||
%% Vertex Processing
|
||||
addVertex --> VertexProcess{Vertex Processing}
|
||||
VertexProcess --> CreateVertex["Create FlowVertex object<br/>- id, labelType, domId<br/>- styles[], classes[]"]
|
||||
VertexProcess --> SanitizeText["sanitizeText(textObj.text)"]
|
||||
VertexProcess --> ParseMetadata["Parse YAML metadata<br/>yaml.load(yamlData)"]
|
||||
VertexProcess --> SetVertexProps["Set vertex properties<br/>- shape, label, icon, form<br/>- pos, img, constraint, w, h"]
|
||||
|
||||
%% Edge Processing
|
||||
addSingleLink --> EdgeProcess{Edge Processing}
|
||||
EdgeProcess --> CreateEdge["Create FlowEdge object<br/>- start, end, type, text<br/>- labelType, classes[]"]
|
||||
EdgeProcess --> ProcessLinkText["Process link text<br/>- sanitizeText()<br/>- strip quotes"]
|
||||
EdgeProcess --> SetEdgeProps["Set edge properties<br/>- type, stroke, length"]
|
||||
EdgeProcess --> GenerateEdgeId["Generate edge ID<br/>getEdgeId(start, end, counter)"]
|
||||
EdgeProcess --> ValidateEdgeLimit["Validate edge limit<br/>maxEdges check"]
|
||||
|
||||
%% Data Collection
|
||||
DBMethods --> GetData["getData()"]
|
||||
GetData --> CollectNodes["Collect nodes[] from vertices"]
|
||||
GetData --> CollectEdges["Collect edges[] from edges"]
|
||||
GetData --> ProcessSubGraphs["Process subgraphs<br/>- parentDB Map<br/>- subGraphDB Map"]
|
||||
GetData --> AddNodeFromVertex["addNodeFromVertex()<br/>for each vertex"]
|
||||
GetData --> ProcessEdgeTypes["destructEdgeType()<br/>arrowTypeStart, arrowTypeEnd"]
|
||||
|
||||
%% Node Creation
|
||||
AddNodeFromVertex --> NodeCreation{Node Creation}
|
||||
NodeCreation --> FindExistingNode["findNode(nodes, vertex.id)"]
|
||||
NodeCreation --> CreateBaseNode["Create base node<br/>- id, label, parentId<br/>- cssStyles, cssClasses<br/>- shape, domId, tooltip"]
|
||||
NodeCreation --> GetCompiledStyles["getCompiledStyles(classDefs)"]
|
||||
NodeCreation --> GetTypeFromVertex["getTypeFromVertex(vertex)"]
|
||||
|
||||
%% Rendering Phase
|
||||
Renderer --> flowRendererV3["flowRenderer-v3-unified.ts<br/>draw(text, id, version, diag)"]
|
||||
|
||||
flowRendererV3 --> RenderInit["Initialize rendering<br/>- getConfig()<br/>- handle securityLevel<br/>- getDiagramElement()"]
|
||||
|
||||
RenderInit --> GetLayoutData["diag.db.getData()<br/>as LayoutData"]
|
||||
GetLayoutData --> SetupLayoutData["Setup layout data<br/>- type, layoutAlgorithm<br/>- direction, spacing<br/>- markers, diagramId"]
|
||||
|
||||
SetupLayoutData --> CallRender["render(data4Layout, svg)"]
|
||||
CallRender --> SetupViewPort["setupViewPortForSVG(svg, padding)"]
|
||||
SetupViewPort --> ProcessLinks["Process vertex links<br/>- create anchor elements<br/>- handle click events"]
|
||||
|
||||
%% Shape Rendering
|
||||
CallRender --> ShapeSystem["flowChartShapes.js<br/>Shape Functions"]
|
||||
|
||||
ShapeSystem --> ShapeFunctions{Shape Functions}
|
||||
ShapeFunctions --> question["question(parent, bbox, node)"]
|
||||
ShapeFunctions --> hexagon["hexagon(parent, bbox, node)"]
|
||||
ShapeFunctions --> rect_left_inv_arrow["rect_left_inv_arrow(parent, bbox, node)"]
|
||||
ShapeFunctions --> lean_right["lean_right(parent, bbox, node)"]
|
||||
ShapeFunctions --> lean_left["lean_left(parent, bbox, node)"]
|
||||
|
||||
ShapeFunctions --> insertPolygonShape["insertPolygonShape(parent, w, h, points)"]
|
||||
ShapeFunctions --> intersectPolygon["intersectPolygon(node, points, point)"]
|
||||
ShapeFunctions --> intersectRect["intersectRect(node, point)"]
|
||||
|
||||
%% Styling System
|
||||
Styles --> stylesTS["styles.ts<br/>getStyles(options)"]
|
||||
stylesTS --> StyleOptions["FlowChartStyleOptions<br/>- arrowheadColor, border2<br/>- clusterBkg, mainBkg<br/>- fontFamily, textColor"]
|
||||
|
||||
StyleOptions --> GenerateCSS["Generate CSS styles<br/>- .label, .cluster-label<br/>- .node, .edgePath<br/>- .flowchart-link, .edgeLabel"]
|
||||
GenerateCSS --> GetIconStyles["getIconStyles()"]
|
||||
|
||||
%% Type System
|
||||
Parser --> TypeSystem["types.ts<br/>Type Definitions"]
|
||||
TypeSystem --> FlowVertex["FlowVertex interface"]
|
||||
TypeSystem --> FlowEdge["FlowEdge interface"]
|
||||
TypeSystem --> FlowClass["FlowClass interface"]
|
||||
TypeSystem --> FlowSubGraph["FlowSubGraph interface"]
|
||||
TypeSystem --> FlowVertexTypeParam["FlowVertexTypeParam<br/>Shape types"]
|
||||
|
||||
%% Utility Functions
|
||||
DBMethods --> UtilityFunctions{Utility Functions}
|
||||
UtilityFunctions --> lookUpDomId["lookUpDomId(id)"]
|
||||
UtilityFunctions --> getClasses["getClasses()"]
|
||||
UtilityFunctions --> getDirection["getDirection()"]
|
||||
UtilityFunctions --> getVertices["getVertices()"]
|
||||
UtilityFunctions --> getEdges["getEdges()"]
|
||||
UtilityFunctions --> getSubGraphs["getSubGraphs()"]
|
||||
UtilityFunctions --> clear["clear()"]
|
||||
UtilityFunctions --> defaultConfig["defaultConfig()"]
|
||||
|
||||
%% Event Handling
|
||||
ProcessLinks --> EventHandling{Event Handling}
|
||||
EventHandling --> setupToolTips["setupToolTips(element)"]
|
||||
EventHandling --> bindFunctions["bindFunctions(element)"]
|
||||
EventHandling --> runFunc["utils.runFunc(functionName, args)"]
|
||||
|
||||
%% Common Database Functions
|
||||
DBMethods --> CommonDB["commonDb.js functions"]
|
||||
CommonDB --> setAccTitle["setAccTitle()"]
|
||||
CommonDB --> getAccTitle["getAccTitle()"]
|
||||
CommonDB --> setAccDescription["setAccDescription()"]
|
||||
CommonDB --> getAccDescription["getAccDescription()"]
|
||||
CommonDB --> setDiagramTitle["setDiagramTitle()"]
|
||||
CommonDB --> getDiagramTitle["getDiagramTitle()"]
|
||||
CommonDB --> commonClear["clear()"]
|
||||
|
||||
%% Final Output
|
||||
ProcessLinks --> FinalSVG["Final SVG Output"]
|
||||
|
||||
%% Layout Algorithm Selection
|
||||
SetupLayoutData --> LayoutAlgorithm{Layout Algorithm}
|
||||
LayoutAlgorithm --> Dagre["dagre<br/>(default)"]
|
||||
LayoutAlgorithm --> DagreWrapper["dagre-wrapper<br/>(v2 renderer)"]
|
||||
LayoutAlgorithm --> ELK["elk<br/>(external package)"]
|
||||
|
||||
%% Testing Components
|
||||
FlowDBClass --> TestFiles["Test Files"]
|
||||
TestFiles --> flowDbSpec["flowDb.spec.ts"]
|
||||
TestFiles --> flowChartShapesSpec["flowChartShapes.spec.js"]
|
||||
TestFiles --> ParserTests["parser/*.spec.js files<br/>- flow-text.spec.js<br/>- flow-edges.spec.js<br/>- flow-style.spec.js<br/>- subgraph.spec.js"]
|
||||
|
||||
%% Configuration
|
||||
Init --> ConfigSetup["Configuration Setup"]
|
||||
ConfigSetup --> FlowchartConfig["cnf.flowchart config"]
|
||||
ConfigSetup --> ArrowMarkers["arrowMarkerAbsolute"]
|
||||
ConfigSetup --> LayoutConfig["layout config"]
|
||||
ConfigSetup --> SetConfig["setConfig() calls"]
|
||||
307
docs/diagrams/mermaid-api-sequence.mmd
Normal file
307
docs/diagrams/mermaid-api-sequence.mmd
Normal file
@@ -0,0 +1,307 @@
|
||||
---
|
||||
references:
|
||||
- "File: /packages/mermaid/src/mermaidAPI.ts"
|
||||
- "File: /packages/mermaid/src/mermaid.ts"
|
||||
generationTime: 2025-01-28T16:30:00.000Z
|
||||
---
|
||||
sequenceDiagram
|
||||
participant User as User/Browser
|
||||
participant Mermaid as mermaid.ts
|
||||
participant Queue as executionQueue
|
||||
participant API as mermaidAPI.ts
|
||||
participant Config as configApi
|
||||
participant Preprocessor as preprocessDiagram
|
||||
participant DiagramAPI as diagram-api
|
||||
participant Diagram as Diagram.fromText
|
||||
participant Renderer as diagram.renderer
|
||||
participant Styles as Styling System
|
||||
participant DOM as DOM/SVG
|
||||
|
||||
Note over User, DOM: Mermaid Complete API Flow
|
||||
|
||||
%% Initialization Phase
|
||||
User->>+Mermaid: mermaid.initialize(config)
|
||||
Mermaid->>+API: mermaidAPI.initialize(config)
|
||||
|
||||
API->>API: assignWithDepth({}, userOptions)
|
||||
API->>API: handle legacy fontFamily config
|
||||
API->>Config: saveConfigFromInitialize(options)
|
||||
|
||||
alt Theme Configuration Available
|
||||
API->>API: check if theme in theme object
|
||||
API->>API: set themeVariables from theme
|
||||
else Default Theme
|
||||
API->>API: use default theme variables
|
||||
end
|
||||
|
||||
API->>Config: setSiteConfig(options) or getSiteConfig()
|
||||
API->>API: setLogLevel(config.logLevel)
|
||||
API->>DiagramAPI: addDiagrams()
|
||||
|
||||
API-->>-Mermaid: initialization complete
|
||||
Mermaid-->>-User: ready to render
|
||||
|
||||
%% Content Loaded Event
|
||||
User->>DOM: document.load event
|
||||
DOM->>+Mermaid: contentLoaded()
|
||||
|
||||
opt startOnLoad is true
|
||||
Mermaid->>Config: getConfig()
|
||||
Config-->>Mermaid: { startOnLoad: true }
|
||||
Mermaid->>Mermaid: run()
|
||||
end
|
||||
|
||||
Mermaid-->>-DOM: event handling complete
|
||||
|
||||
%% Main Run Function
|
||||
User->>+Mermaid: mermaid.run(options)
|
||||
|
||||
Mermaid->>Mermaid: runThrowsErrors(options)
|
||||
Mermaid->>Config: getConfig()
|
||||
Config-->>Mermaid: configuration object
|
||||
|
||||
alt nodes provided
|
||||
Mermaid->>Mermaid: use provided nodes
|
||||
else querySelector provided
|
||||
Mermaid->>DOM: document.querySelectorAll(querySelector)
|
||||
DOM-->>Mermaid: nodesToProcess
|
||||
end
|
||||
|
||||
Mermaid->>Mermaid: new InitIDGenerator(deterministicIds, seed)
|
||||
|
||||
loop For each diagram element
|
||||
Mermaid->>DOM: check element.getAttribute('data-processed')
|
||||
|
||||
opt not processed
|
||||
Mermaid->>DOM: element.setAttribute('data-processed', 'true')
|
||||
Mermaid->>Mermaid: generate unique id
|
||||
Mermaid->>DOM: get element.innerHTML
|
||||
Mermaid->>Mermaid: entityDecode and clean text
|
||||
Mermaid->>Mermaid: detectInit(txt)
|
||||
|
||||
Mermaid->>Queue: render(id, txt, element)
|
||||
end
|
||||
end
|
||||
|
||||
Mermaid-->>-User: processing initiated
|
||||
|
||||
%% Render Function (Queued)
|
||||
activate Queue
|
||||
Queue->>+API: mermaidAPI.render(id, text, container)
|
||||
|
||||
API->>DiagramAPI: addDiagrams()
|
||||
API->>+Preprocessor: processAndSetConfigs(text)
|
||||
|
||||
Preprocessor->>Preprocessor: preprocessDiagram(text)
|
||||
Preprocessor->>Config: reset()
|
||||
Preprocessor->>Config: addDirective(processed.config)
|
||||
Preprocessor-->>-API: { code, config }
|
||||
|
||||
API->>Config: getConfig()
|
||||
Config-->>API: current configuration
|
||||
|
||||
opt text length > maxTextSize
|
||||
API->>API: text = MAX_TEXTLENGTH_EXCEEDED_MSG
|
||||
end
|
||||
|
||||
API->>API: setup id selectors and element IDs
|
||||
API->>API: determine security level (sandbox/loose)
|
||||
|
||||
%% DOM Setup
|
||||
alt svgContainingElement provided
|
||||
alt isSandboxed
|
||||
API->>DOM: sandboxedIframe(select(svgContainingElement), iFrameID)
|
||||
API->>DOM: select iframe contentDocument body
|
||||
else
|
||||
API->>DOM: select(svgContainingElement)
|
||||
end
|
||||
else no container
|
||||
API->>API: removeExistingElements(document, id, divId, iFrameId)
|
||||
alt isSandboxed
|
||||
API->>DOM: sandboxedIframe(select('body'), iFrameID)
|
||||
else
|
||||
API->>DOM: select('body')
|
||||
end
|
||||
end
|
||||
|
||||
API->>DOM: appendDivSvgG(root, id, enclosingDivID, fontFamily, XMLNS_XLINK_STD)
|
||||
|
||||
%% Diagram Creation
|
||||
API->>+Diagram: Diagram.fromText(text, { title: processed.title })
|
||||
|
||||
Diagram->>DiagramAPI: detect diagram type
|
||||
Diagram->>DiagramAPI: load appropriate diagram
|
||||
Diagram-->>-API: diagram instance
|
||||
|
||||
opt parsing error occurred
|
||||
API->>+Diagram: Diagram.fromText('error')
|
||||
Diagram-->>-API: error diagram
|
||||
API->>API: store parseEncounteredException
|
||||
end
|
||||
|
||||
%% Style Generation
|
||||
API->>DOM: get svg element and firstChild
|
||||
API->>Renderer: diag.renderer.getClasses(text, diag)
|
||||
Renderer-->>API: diagramClassDefs
|
||||
|
||||
API->>+Styles: createUserStyles(config, diagramType, diagramClassDefs, idSelector)
|
||||
|
||||
Styles->>Styles: createCssStyles(config, classDefs)
|
||||
|
||||
opt config.themeCSS defined
|
||||
Styles->>Styles: append themeCSS
|
||||
end
|
||||
|
||||
opt fontFamily configured
|
||||
Styles->>Styles: add CSS variables for fonts
|
||||
end
|
||||
|
||||
opt classDefs exist
|
||||
loop For each styleClassDef
|
||||
opt has styles
|
||||
Styles->>Styles: cssImportantStyles for each CSS element
|
||||
end
|
||||
opt has textStyles
|
||||
Styles->>Styles: cssImportantStyles for tspan elements
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Styles->>Styles: getStyles(graphType, userCSSstyles, themeVariables)
|
||||
Styles->>Styles: serialize(compile(svgId{allStyles}), stringify)
|
||||
Styles-->>-API: compiled CSS rules
|
||||
|
||||
API->>DOM: create style element
|
||||
API->>DOM: style.innerHTML = rules
|
||||
API->>DOM: svg.insertBefore(style, firstChild)
|
||||
|
||||
%% Diagram Rendering
|
||||
API->>+Renderer: diag.renderer.draw(text, id, version, diag)
|
||||
|
||||
Renderer->>Renderer: diagram-specific rendering logic
|
||||
Renderer->>DOM: create SVG elements
|
||||
Renderer->>DOM: apply positioning and styling
|
||||
Renderer-->>-API: rendered diagram
|
||||
|
||||
opt rendering error
|
||||
alt suppressErrorRendering
|
||||
API->>API: removeTempElements()
|
||||
API->>Mermaid: throw error
|
||||
else
|
||||
API->>Renderer: errorRenderer.draw(text, id, version)
|
||||
end
|
||||
end
|
||||
|
||||
%% Accessibility and Cleanup
|
||||
API->>DOM: select svg element
|
||||
API->>Diagram: diag.db.getAccTitle()
|
||||
API->>Diagram: diag.db.getAccDescription()
|
||||
API->>API: addA11yInfo(diagramType, svgNode, a11yTitle, a11yDescr)
|
||||
|
||||
API->>DOM: set xmlns for foreignobject elements
|
||||
API->>DOM: get innerHTML from enclosing div
|
||||
|
||||
API->>+API: cleanUpSvgCode(svgCode, isSandboxed, arrowMarkerAbsolute)
|
||||
|
||||
opt not useArrowMarkerUrls and not sandboxed
|
||||
API->>API: replace marker-end URLs with anchors
|
||||
end
|
||||
|
||||
API->>API: decodeEntities(svgCode)
|
||||
API->>API: replace <br> with <br/>
|
||||
API-->>-API: cleaned SVG code
|
||||
|
||||
alt isSandboxed
|
||||
API->>+API: putIntoIFrame(svgCode, svgEl)
|
||||
API->>API: calculate iframe height
|
||||
API->>API: toBase64 encode SVG content
|
||||
API->>API: create iframe with sandbox attributes
|
||||
API-->>-API: iframe HTML
|
||||
else not loose security
|
||||
API->>API: DOMPurify.sanitize(svgCode, options)
|
||||
end
|
||||
|
||||
API->>API: attachFunctions()
|
||||
API->>API: removeTempElements()
|
||||
|
||||
opt parseEncounteredException
|
||||
API->>Mermaid: throw parseEncounteredException
|
||||
end
|
||||
|
||||
API-->>-Queue: { diagramType, svg: svgCode, bindFunctions }
|
||||
|
||||
%% Return to Web Integration
|
||||
activate Mermaid
|
||||
Queue-->>Mermaid: render result
|
||||
Mermaid->>DOM: element.innerHTML = svg
|
||||
|
||||
opt postRenderCallback
|
||||
Mermaid->>User: postRenderCallback(id)
|
||||
end
|
||||
|
||||
opt bindFunctions exist
|
||||
Mermaid->>DOM: bindFunctions(element)
|
||||
end
|
||||
deactivate Mermaid
|
||||
|
||||
%% Parse Function Flow
|
||||
User->>+Mermaid: mermaid.parse(text, parseOptions)
|
||||
activate Queue
|
||||
|
||||
Queue->>+API: mermaidAPI.parse(text, parseOptions)
|
||||
|
||||
API->>DiagramAPI: addDiagrams()
|
||||
API->>Preprocessor: processAndSetConfigs(text)
|
||||
Preprocessor-->>API: { code, config }
|
||||
API->>Diagram: getDiagramFromText(code)
|
||||
Diagram-->>API: diagram instance
|
||||
API-->>-Queue: { diagramType: diagram.type, config }
|
||||
|
||||
Queue-->>-Mermaid: parse result
|
||||
Mermaid-->>-User: ParseResult or false
|
||||
|
||||
%% External Diagram Registration
|
||||
User->>+Mermaid: registerExternalDiagrams(diagrams, options)
|
||||
|
||||
Mermaid->>DiagramAPI: addDiagrams()
|
||||
Mermaid->>DiagramAPI: registerLazyLoadedDiagrams(...diagrams)
|
||||
|
||||
opt lazyLoad is false
|
||||
Mermaid->>DiagramAPI: loadRegisteredDiagrams()
|
||||
end
|
||||
|
||||
Mermaid-->>-User: registration complete
|
||||
|
||||
%% Error Handling
|
||||
Note over Mermaid, API: Error Handling Throughout
|
||||
alt Error occurs
|
||||
API->>Mermaid: throw error
|
||||
Mermaid->>+Mermaid: handleError(error, errors, parseError)
|
||||
|
||||
Mermaid->>Mermaid: log.warn(error)
|
||||
|
||||
alt isDetailedError
|
||||
Mermaid->>User: parseError(error.str, error.hash)
|
||||
else
|
||||
Mermaid->>User: parseError(error)
|
||||
end
|
||||
|
||||
opt not suppressErrors
|
||||
Mermaid->>User: throw error
|
||||
end
|
||||
|
||||
Mermaid-->>-User: error handled
|
||||
end
|
||||
|
||||
%% Configuration Details
|
||||
Note over Config: Configuration Functions
|
||||
Note right of Config: Functions:<br/>- reset()<br/>- getConfig()<br/>- setConfig()<br/>- getSiteConfig()<br/>- updateSiteConfig()<br/>- saveConfigFromInitialize()
|
||||
|
||||
Note over Styles: CSS Generation
|
||||
Note right of Styles: Features:<br/>- createCssStyles()<br/>- createUserStyles()<br/>- cssImportantStyles()<br/>- Theme integration<br/>- Class definitions
|
||||
|
||||
Note over API: Security Levels
|
||||
Note right of API: Modes:<br/>- sandbox: iframe isolation<br/>- loose: minimal sanitization<br/>- default: DOMPurify sanitization
|
||||
|
||||
Note over API: Helper Functions
|
||||
Note right of API: Utilities:<br/>- cleanUpSvgCode()<br/>- putIntoIFrame()<br/>- appendDivSvgG()<br/>- removeExistingElements()
|
||||
180
docs/diagrams/mindmap-implementation-sequence.mmd
Normal file
180
docs/diagrams/mindmap-implementation-sequence.mmd
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
references:
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/mindmap-definition.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/mindmapDb.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/detector.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/mindmapTypes.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/mindmapRenderer.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/styles.ts"
|
||||
- "File: /packages/mermaid/src/diagrams/mindmap/svgDraw.ts"
|
||||
generationTime: 2025-01-28T16:00:00.000Z
|
||||
---
|
||||
sequenceDiagram
|
||||
participant User as User Input Text
|
||||
participant Detector as detector.ts
|
||||
participant Loader as DiagramLoader
|
||||
participant Definition as mindmap-definition.ts
|
||||
participant Parser as parser/mindmap.jison
|
||||
participant DB as MindmapDB
|
||||
participant Renderer as mindmapRenderer.ts
|
||||
participant Cytoscape as cytoscape.js
|
||||
participant SVGDraw as svgDraw.ts
|
||||
participant Styles as styles.ts
|
||||
participant Output as Final SVG
|
||||
|
||||
Note over User, Output: Mindmap Implementation Flow
|
||||
|
||||
%% Detection Phase
|
||||
User->>Detector: /^\s*mindmap/ text input
|
||||
activate Detector
|
||||
Detector->>Detector: detector(txt) validates pattern
|
||||
Detector->>Loader: loader() function called
|
||||
deactivate Detector
|
||||
|
||||
activate Loader
|
||||
Loader->>Definition: import mindmap-definition.js
|
||||
deactivate Loader
|
||||
|
||||
%% Core Structure Setup
|
||||
activate Definition
|
||||
Definition->>DB: get db() → new MindmapDB()
|
||||
Definition->>Renderer: setup renderer
|
||||
Definition->>Parser: setup parser
|
||||
Definition->>Styles: setup styles
|
||||
deactivate Definition
|
||||
|
||||
%% Database Initialization
|
||||
activate DB
|
||||
Note over DB: MindmapDB Constructor
|
||||
DB->>DB: initialize nodes array
|
||||
DB->>DB: setup nodeType constants
|
||||
DB->>DB: bind methods
|
||||
DB->>DB: clear() state
|
||||
|
||||
%% Parsing Phase
|
||||
activate Parser
|
||||
User->>Parser: mindmap syntax text
|
||||
|
||||
loop For each node in hierarchy
|
||||
Parser->>DB: addNode(level, id, descr, type)
|
||||
activate DB
|
||||
DB->>DB: sanitizeText(id, descr)
|
||||
DB->>DB: getType(startStr, endStr)
|
||||
Note right of DB: Shape Detection:<br/>[ → RECT<br/>( → ROUNDED_RECT<br/>(( → CIRCLE<br/>)) → BANG<br/>{{ → HEXAGON
|
||||
DB->>DB: getParent(level)
|
||||
DB->>DB: create MindmapNode
|
||||
DB->>DB: add to hierarchy
|
||||
deactivate DB
|
||||
end
|
||||
|
||||
opt Icon/Class Decoration
|
||||
Parser->>DB: decorateNode(decoration)
|
||||
DB->>DB: set icon/class properties
|
||||
end
|
||||
deactivate Parser
|
||||
|
||||
%% Data Preparation
|
||||
Renderer->>DB: getData() for layout
|
||||
activate DB
|
||||
DB->>DB: collect all nodes
|
||||
DB->>DB: build parent-child relationships
|
||||
DB-->>Renderer: return node hierarchy
|
||||
deactivate DB
|
||||
|
||||
%% Rendering Pipeline
|
||||
activate Renderer
|
||||
Note over Renderer: Rendering Phase
|
||||
|
||||
Renderer->>Cytoscape: initialize cytoscape
|
||||
activate Cytoscape
|
||||
|
||||
loop For each node in mindmap
|
||||
Renderer->>Cytoscape: addNodes(mindmap, cy, conf, level)
|
||||
Cytoscape->>Cytoscape: create node data
|
||||
Cytoscape->>Cytoscape: set position (x, y)
|
||||
end
|
||||
|
||||
loop For parent-child relationships
|
||||
Renderer->>Cytoscape: add edges
|
||||
Cytoscape->>Cytoscape: create edge data
|
||||
end
|
||||
|
||||
Renderer->>Cytoscape: configure cose-bilkent layout
|
||||
Cytoscape->>Cytoscape: calculate optimal positions
|
||||
Cytoscape-->>Renderer: return positioned graph
|
||||
deactivate Cytoscape
|
||||
|
||||
%% SVG Generation
|
||||
Renderer->>SVGDraw: drawNodes(db, svg, mindmap, section, conf)
|
||||
activate SVGDraw
|
||||
|
||||
loop For each node recursively
|
||||
SVGDraw->>SVGDraw: select shape function
|
||||
|
||||
alt Default Shape
|
||||
SVGDraw->>SVGDraw: defaultBkg() - rounded rectangle
|
||||
else Rectangle Shape
|
||||
SVGDraw->>SVGDraw: rectBkg() - sharp corners
|
||||
else Circle Shape
|
||||
SVGDraw->>SVGDraw: circleBkg() - perfect circle
|
||||
else Cloud Shape
|
||||
SVGDraw->>SVGDraw: cloudBkg() - organic curves
|
||||
else Bang Shape
|
||||
SVGDraw->>SVGDraw: bangBkg() - explosion style
|
||||
else Hexagon Shape
|
||||
SVGDraw->>SVGDraw: hexagonBkg() - six sides
|
||||
end
|
||||
|
||||
SVGDraw->>SVGDraw: create SVG elements
|
||||
SVGDraw->>SVGDraw: add text labels
|
||||
SVGDraw->>SVGDraw: position node
|
||||
|
||||
opt Node has children
|
||||
SVGDraw->>SVGDraw: drawNodes() recursive call
|
||||
end
|
||||
end
|
||||
deactivate SVGDraw
|
||||
|
||||
%% Edge Rendering
|
||||
Renderer->>Renderer: drawEdges(edgesEl, cy)
|
||||
loop For each edge
|
||||
Renderer->>Renderer: extract edge bounds
|
||||
Renderer->>Renderer: draw SVG path
|
||||
end
|
||||
|
||||
%% Styling Application
|
||||
Renderer->>Styles: getStyles(options)
|
||||
activate Styles
|
||||
|
||||
Styles->>Styles: genSections(options)
|
||||
loop For THEME_COLOR_LIMIT sections
|
||||
Styles->>Styles: generate color scale
|
||||
Styles->>Styles: create CSS rules
|
||||
Note right of Styles: .section-X fills<br/>.edge-depth-X widths<br/>.node-icon-X colors
|
||||
end
|
||||
|
||||
Styles->>Styles: apply theme integration
|
||||
Styles-->>Renderer: return compiled CSS
|
||||
deactivate Styles
|
||||
|
||||
%% Final Assembly
|
||||
Renderer->>Output: selectSvgElement()
|
||||
Renderer->>Output: setupGraphViewbox()
|
||||
Renderer->>Output: apply styles
|
||||
Renderer->>Output: add interactive elements
|
||||
deactivate Renderer
|
||||
|
||||
activate Output
|
||||
Note over Output: Final Mindmap Features
|
||||
Output->>Output: responsive layout
|
||||
Output->>Output: accessibility attributes
|
||||
Output->>Output: hover effects
|
||||
Output->>Output: click handling
|
||||
Output-->>User: rendered mindmap
|
||||
deactivate Output
|
||||
|
||||
%% Configuration Details
|
||||
Note over DB, Styles: Configuration Options
|
||||
Note right of DB: Padding Calculations:<br/>Base padding from config<br/>RECT: ×2 padding<br/>ROUNDED_RECT: ×2 padding<br/>HEXAGON: ×2 padding
|
||||
Note right of Styles: Section Management:<br/>MAX_SECTIONS = 12<br/>Dynamic color generation<br/>Git theme integration
|
||||
Note right of Renderer: Layout Parameters:<br/>Cytoscape configuration<br/>coseBilkent settings<br/>Node spacing rules
|
||||
@@ -84,6 +84,7 @@ To add an integration to this list, see the [Integrations - create page](./integ
|
||||
LLM integrations to create mermaid diagrams using AI from text descriptions.
|
||||
|
||||
- [HueHive - Create mermaid diagrams with text](https://huehive.co/tools/diagrams)
|
||||
- [MCP Server Mermaid](https://github.com/hustcc/mcp-mermaid) - Generate mermaid diagram and chart with AI MCP dynamically.
|
||||
|
||||
### CRM/ERP
|
||||
|
||||
@@ -245,7 +246,7 @@ Communication tools and platforms
|
||||
| GitHub + Mermaid | - | [🦊🔗](https://addons.mozilla.org/firefox/addon/github-mermaid/) | - | - | [🐙🔗](https://github.com/BackMarket/github-mermaid-extension) |
|
||||
| Asciidoctor Live Preview | [🎡🔗](https://chromewebstore.google.com/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia) | - | - | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/asciidoctorjs-live-previ/pefkelkanablhjdekgdahplkccnbdggd?hl=en-US) | - |
|
||||
| Diagram Tab | - | - | - | - | [🐙🔗](https://github.com/khafast/diagramtab) |
|
||||
| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | [🔴🔗](https://addons.opera.com/en/extensions/details/markdown-diagrams/) | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) |
|
||||
| Markdown Diagrams | [🎡🔗](https://chromewebstore.google.com/detail/markdown-diagrams/pmoglnmodacnbbofbgcagndelmgaclel) | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-diagrams/) | - | [🌀🔗](https://microsoftedge.microsoft.com/addons/detail/markdown-diagrams/hceenoomhhdkjjijnmlclkpenkapfihe) | [🐙🔗](https://github.com/marcozaccari/markdown-diagrams-browser-extension/tree/master/doc/examples) |
|
||||
| Markdown Viewer | - | [🦊🔗](https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-chrome/) | - | - | [🐙🔗](https://github.com/simov/markdown-viewer) |
|
||||
| Extensions for Mermaid | - | - | [🔴🔗](https://addons.opera.com/en/extensions/details/extensions-for-mermaid/) | - | [🐙🔗](https://github.com/Stefan-S/mermaid-extension) |
|
||||
| Chrome Diagrammer | [🎡🔗](https://chromewebstore.google.com/detail/chrome-diagrammer/bkpbgjmkomfoakfklcjeoegkklgjnnpk) | - | - | - | - |
|
||||
|
||||
@@ -16,9 +16,7 @@ Applications that support Mermaid files [SHOULD](https://datatracker.ietf.org/do
|
||||
|
||||
### MIME Type
|
||||
|
||||
The recommended [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) for Mermaid media is `text/vnd.mermaid`.
|
||||
|
||||
Currently pending [IANA](https://www.iana.org/) recognition.
|
||||
The recommended [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) for Mermaid media is [`text/vnd.mermaid`](https://www.iana.org/assignments/media-types/application/vnd.mermaid).
|
||||
|
||||
## Showcase
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Try the Ultimate AI, Mermaid, and Visual Diagramming Suite by creating an accoun
|
||||
|
||||
Official Mermaid Chart plugins:
|
||||
|
||||
- [Mermaid Chart GPT](https://chat.openai.com/g/g-1IRFKwq4G-mermaid-chart)
|
||||
- [Mermaid Chart GPT](https://chatgpt.com/g/g-684cc36f30208191b21383b88650a45d-mermaid-chart-diagrams-and-charts)
|
||||
- [Confluence](https://marketplace.atlassian.com/apps/1234056/mermaid-chart-for-confluence?hosting=cloud&tab=overview)
|
||||
- [Jira](https://marketplace.atlassian.com/apps/1234810/mermaid-chart-for-jira?tab=overview&hosting=cloud)
|
||||
- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=MermaidChart.vscode-mermaid-chart)
|
||||
|
||||
@@ -1795,15 +1795,54 @@ It is possible to style the type of curve used for lines between items, if the d
|
||||
Available curve styles include `basis`, `bumpX`, `bumpY`, `cardinal`, `catmullRom`, `linear`, `monotoneX`, `monotoneY`,
|
||||
`natural`, `step`, `stepAfter`, and `stepBefore`.
|
||||
|
||||
For a full list of available curves, including an explanation of custom curves, refer to
|
||||
the [Shapes](https://d3js.org/d3-shape/curve) documentation in the [d3-shape](https://github.com/d3/d3-shape/) project.
|
||||
|
||||
Line styling can be achieved in two ways:
|
||||
|
||||
1. Change the curve style of all the lines
|
||||
2. Change the curve style of a particular line
|
||||
|
||||
#### Diagram level curve style
|
||||
|
||||
In this example, a left-to-right graph uses the `stepBefore` curve style:
|
||||
|
||||
```
|
||||
%%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%%
|
||||
---
|
||||
config:
|
||||
flowchart:
|
||||
curve: stepBefore
|
||||
---
|
||||
graph LR
|
||||
```
|
||||
|
||||
For a full list of available curves, including an explanation of custom curves, refer to
|
||||
the [Shapes](https://d3js.org/d3-shape/curve) documentation in the [d3-shape](https://github.com/d3/d3-shape/) project.
|
||||
#### Edge level curve style using Edge IDs (v\<MERMAID_RELEASE_VERSION>+)
|
||||
|
||||
You can assign IDs to [edges](#attaching-an-id-to-edges). After assigning an ID you can modify the line style by modifying the edge's `curve` property using the following syntax:
|
||||
|
||||
```mermaid-example
|
||||
flowchart LR
|
||||
A e1@==> B
|
||||
A e2@--> C
|
||||
e1@{ curve: linear }
|
||||
e2@{ curve: natural }
|
||||
```
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A e1@==> B
|
||||
A e2@--> C
|
||||
e1@{ curve: linear }
|
||||
e2@{ curve: natural }
|
||||
```
|
||||
|
||||
```info
|
||||
Any edge curve style modified at the edge level overrides the diagram level style.
|
||||
```
|
||||
|
||||
```info
|
||||
If the same edge is modified multiple times the last modification will be rendered.
|
||||
```
|
||||
|
||||
### Styling a node
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ This diagram type is particularly useful for developers, network engineers, educ
|
||||
## Syntax
|
||||
|
||||
```
|
||||
packet-beta
|
||||
packet
|
||||
start: "Block name" %% Single-bit block
|
||||
start-end: "Block name" %% Multi-bit blocks
|
||||
... More Fields ...
|
||||
@@ -28,7 +28,7 @@ start-end: "Block name" %% Multi-bit blocks
|
||||
Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `+<count>` to set the number of bits, thus:
|
||||
|
||||
```
|
||||
packet-beta
|
||||
packet
|
||||
+1: "Block name" %% Single-bit block
|
||||
+8: "Block name" %% 8-bit block
|
||||
9-15: "Manually set start and end, it's fine to mix and match"
|
||||
@@ -41,7 +41,7 @@ packet-beta
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet-beta
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
@@ -65,7 +65,7 @@ packet-beta
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet-beta
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
@@ -86,7 +86,7 @@ packet-beta
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
packet-beta
|
||||
packet
|
||||
title UDP Packet
|
||||
+16: "Source Port"
|
||||
+16: "Destination Port"
|
||||
@@ -96,7 +96,7 @@ title UDP Packet
|
||||
```
|
||||
|
||||
```mermaid
|
||||
packet-beta
|
||||
packet
|
||||
title UDP Packet
|
||||
+16: "Source Port"
|
||||
+16: "Destination Port"
|
||||
@@ -144,7 +144,7 @@ config:
|
||||
packet:
|
||||
startByteColor: red
|
||||
---
|
||||
packet-beta
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
|
||||
353
docs/syntax/treemap.md
Normal file
353
docs/syntax/treemap.md
Normal file
@@ -0,0 +1,353 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/treemap.md](../../packages/mermaid/src/docs/syntax/treemap.md).
|
||||
|
||||
# Treemap Diagram
|
||||
|
||||
> A treemap diagram displays hierarchical data as a set of nested rectangles. Each branch of the tree is represented by a rectangle, which is then tiled with smaller rectangles representing sub-branches.
|
||||
|
||||
> **Warning**
|
||||
> This is a new diagram type in Mermaid. Its syntax may evolve in future versions.
|
||||
|
||||
## Introduction
|
||||
|
||||
Treemap diagrams are an effective way to visualize hierarchical data and show proportions between categories and subcategories. The size of each rectangle is proportional to the value it represents, making it easy to compare different parts of a hierarchy.
|
||||
|
||||
Treemap diagrams are particularly useful for:
|
||||
|
||||
- Visualizing hierarchical data structures
|
||||
- Comparing proportions between categories
|
||||
- Displaying large amounts of hierarchical data in a limited space
|
||||
- Identifying patterns and outliers in hierarchical data
|
||||
|
||||
## Syntax
|
||||
|
||||
```
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2"
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20
|
||||
"Leaf 2.2": 25
|
||||
```
|
||||
|
||||
### Node Definition
|
||||
|
||||
Nodes in a treemap are defined using the following syntax:
|
||||
|
||||
- **Section/Parent nodes**: Defined with quoted text `"Section Name"`
|
||||
- **Leaf nodes with values**: Defined with quoted text followed by a colon and value `"Leaf Name": value`
|
||||
- **Hierarchy**: Created using indentation (spaces or tabs)
|
||||
- **Styling**: Nodes can be styled using the `:::class` syntax
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Treemap
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
### Hierarchical Treemap
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Products"
|
||||
"Electronics"
|
||||
"Phones": 50
|
||||
"Computers": 30
|
||||
"Accessories": 20
|
||||
"Clothing"
|
||||
"Men's": 40
|
||||
"Women's": 40
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Products"
|
||||
"Electronics"
|
||||
"Phones": 50
|
||||
"Computers": 30
|
||||
"Accessories": 20
|
||||
"Clothing"
|
||||
"Men's": 40
|
||||
"Women's": 40
|
||||
```
|
||||
|
||||
### Treemap with Styling
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2":::class1
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20:::class1
|
||||
"Leaf 2.2": 25
|
||||
"Leaf 2.3": 12
|
||||
|
||||
classDef class1 fill:red,color:blue,stroke:#FFD600;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2":::class1
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20:::class1
|
||||
"Leaf 2.2": 25
|
||||
"Leaf 2.3": 12
|
||||
|
||||
classDef class1 fill:red,color:blue,stroke:#FFD600;
|
||||
```
|
||||
|
||||
## Styling and Configuration
|
||||
|
||||
Treemap diagrams can be customized using Mermaid's styling and configuration options.
|
||||
|
||||
### Using classDef for Styling
|
||||
|
||||
You can define custom styles for nodes using the `classDef` syntax, which is a standard feature across many Mermaid diagram types:
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Main"
|
||||
"A": 20
|
||||
"B":::important
|
||||
"B1": 10
|
||||
"B2": 15
|
||||
"C": 5
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:2px;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Main"
|
||||
"A": 20
|
||||
"B":::important
|
||||
"B1": 10
|
||||
"B2": 15
|
||||
"C": 5
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:2px;
|
||||
```
|
||||
|
||||
### Theme Configuration
|
||||
|
||||
You can customize the colors of your treemap using the theme configuration:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
### Diagram Padding
|
||||
|
||||
You can adjust the padding around the treemap diagram using the `diagramPadding` configuration option:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
diagramPadding: 200
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
diagramPadding: 200
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
The treemap diagram supports the following configuration options:
|
||||
|
||||
| Option | Description | Default |
|
||||
| -------------- | --------------------------------------------------------------------------- | ------- |
|
||||
| useMaxWidth | When true, the diagram width is set to 100% and scales with available space | true |
|
||||
| padding | Internal padding between nodes | 10 |
|
||||
| diagramPadding | Padding around the entire diagram | 8 |
|
||||
| showValues | Whether to show values in the treemap | true |
|
||||
| nodeWidth | Width of nodes | 100 |
|
||||
| nodeHeight | Height of nodes | 40 |
|
||||
| borderWidth | Width of borders | 1 |
|
||||
| valueFontSize | Font size for values | 12 |
|
||||
| labelFontSize | Font size for labels | 14 |
|
||||
| valueFormat | Format for values (see Value Formatting section) | ',' |
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Value Formatting
|
||||
|
||||
Values in treemap diagrams can be formatted to display in different ways using the `valueFormat` configuration option. This option primarily uses [D3's format specifiers](https://github.com/d3/d3-format#locale_format) to control how numbers are displayed, with some additional special cases for common formats.
|
||||
|
||||
Some common format patterns:
|
||||
|
||||
- `,` - Thousands separator (default)
|
||||
- `$` - Add dollar sign
|
||||
- `.1f` - Show one decimal place
|
||||
- `.1%` - Show as percentage with one decimal place
|
||||
- `$0,0` - Dollar sign with thousands separator
|
||||
- `$.2f` - Dollar sign with 2 decimal places
|
||||
- `$,.2f` - Dollar sign with thousands separator and 2 decimal places
|
||||
|
||||
The treemap diagram supports both standard D3 format specifiers and some common currency formats that combine the dollar sign with other formatting options.
|
||||
|
||||
Example with currency formatting:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$0,0'
|
||||
---
|
||||
treemap-beta
|
||||
"Budget"
|
||||
"Operations"
|
||||
"Salaries": 700000
|
||||
"Equipment": 200000
|
||||
"Supplies": 100000
|
||||
"Marketing"
|
||||
"Advertising": 400000
|
||||
"Events": 100000
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$0,0'
|
||||
---
|
||||
treemap-beta
|
||||
"Budget"
|
||||
"Operations"
|
||||
"Salaries": 700000
|
||||
"Equipment": 200000
|
||||
"Supplies": 100000
|
||||
"Marketing"
|
||||
"Advertising": 400000
|
||||
"Events": 100000
|
||||
```
|
||||
|
||||
Example with percentage formatting:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$.1%'
|
||||
---
|
||||
treemap-beta
|
||||
"Market Share"
|
||||
"Company A": 0.35
|
||||
"Company B": 0.25
|
||||
"Company C": 0.15
|
||||
"Others": 0.25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$.1%'
|
||||
---
|
||||
treemap-beta
|
||||
"Market Share"
|
||||
"Company A": 0.35
|
||||
"Company B": 0.25
|
||||
"Company C": 0.15
|
||||
"Others": 0.25
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
Treemap diagrams are commonly used for:
|
||||
|
||||
1. **Financial Data**: Visualizing budget allocations, market shares, or portfolio compositions
|
||||
2. **File System Analysis**: Showing disk space usage by folders and files
|
||||
3. **Population Demographics**: Displaying population distribution across regions and subregions
|
||||
4. **Product Hierarchies**: Visualizing product categories and their sales volumes
|
||||
5. **Organizational Structures**: Representing departments and team sizes in a company
|
||||
|
||||
## Limitations
|
||||
|
||||
- Treemap diagrams work best when the data has a natural hierarchy
|
||||
- Very small values may be difficult to see or label in a treemap diagram
|
||||
- Deep hierarchies (many levels) can be challenging to represent clearly
|
||||
- Treemap diagrams are not well suited for representing data with negative values
|
||||
|
||||
## Related Diagrams
|
||||
|
||||
If treemap diagrams don't suit your needs, consider these alternatives:
|
||||
|
||||
- [**Pie Charts**](./pie.md): For simple proportion comparisons without hierarchy
|
||||
- **Sunburst Diagrams**: For hierarchical data with a radial layout (yet to be released in Mermaid).
|
||||
- [**Sankey Diagrams**](./sankey.md): For flow-based hierarchical data
|
||||
|
||||
## Notes
|
||||
|
||||
The treemap diagram implementation in Mermaid is designed to be simple to use while providing powerful visualization capabilities. As this is a newer diagram type, feedback and feature requests are welcome through the Mermaid GitHub repository.
|
||||
Reference in New Issue
Block a user