diff --git a/docs/syntax/img/zenuml-participant-annotators.png b/docs/syntax/img/zenuml-participant-annotators.png new file mode 100644 index 000000000..13789371f Binary files /dev/null and b/docs/syntax/img/zenuml-participant-annotators.png differ diff --git a/docs/syntax/zenuml.md b/docs/syntax/zenuml.md new file mode 100644 index 000000000..a9c7c0f4b --- /dev/null +++ b/docs/syntax/zenuml.md @@ -0,0 +1,410 @@ +> **Warning** +> +> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. +> +> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/zenuml.md](../../packages/mermaid/src/docs/syntax/zenuml.md). + +# ZenUML + +> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order. + +Mermaid can render sequence diagrams with ZenUML. Note that ZenUML uses a different +syntax than the original Sequence Diagram in mermaid. + +```mermaid-example +zenuml + title Demo + Alice->John: Hello John, how are you? + John->Alice: Great! + Alice->John: See you later! +``` + +```mermaid +zenuml + title Demo + Alice->John: Hello John, how are you? + John->Alice: Great! + Alice->John: See you later! +``` + +## Syntax + +### Participants + +The participants can be defined implicitly as in the first example on this page. The participants or actors are +rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a +different order than how they appear in the first message. It is possible to specify the actor's order of +appearance by doing the following: + +```mermaid-example +zenuml + title Declare participant (optional) + Bob + Alice + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +```mermaid +zenuml + title Declare participant (optional) + Bob + Alice + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +### Annotators + +If you specifically want to use symbols instead of just rectangles with text you can do so by using the annotator syntax to declare participants as per below. + +```mermaid-example +zenuml + title Annotators + @Actor Alice + @Database Bob + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +```mermaid +zenuml + title Annotators + @Actor Alice + @Database Bob + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +Here are the available annotators: +![img.png](img/zenuml-participant-annotators.png) + +### Aliases + +The participants can have a convenient identifier and a descriptive label. + +```mermaid-example +zenuml + title Aliases + A as Alice + J as John + A->J: Hello John, how are you? + J->A: Great! +``` + +```mermaid +zenuml + title Aliases + A as Alice + J as John + A->J: Hello John, how are you? + J->A: Great! +``` + +## Messages + +Messages can be one of: + +1. Sync message +2. Async message +3. Creation message +4. Reply message + +### Sync message + +You can think of a sync (blocking) method in a programming language. + +```mermaid-example +zenuml + title Sync message + A.SyncMessage + A.SyncMessage(with, parameters) { + B.nestedSyncMessage() + } +``` + +```mermaid +zenuml + title Sync message + A.SyncMessage + A.SyncMessage(with, parameters) { + B.nestedSyncMessage() + } +``` + +### Async message + +You can think of an async (non-blocking) method in a programming language. +Fire an event and forget about it. + +```mermaid-example +zenuml + title Async message + Alice->Bob: How are you? +``` + +```mermaid +zenuml + title Async message + Alice->Bob: How are you? +``` + +### Creation message + +We use `new` keyword to create an object. + + new A1 + new A2(with, parameters) + +### Reply message + +There are three ways to express a reply message: + + // 1. assign a variable from a sync message. + a = A.SyncMessage() + + // 1.1. optionally give the variable a type + SomeType a = A.SyncMessage() + + // 2. use return keyword + A.SyncMessage() { + return result + } + + // 3. use @return or @reply annotator on an async message + @return + A->B: result + +The third way `@return` is rarely used, but it is useful when you want to return to one level up. + +```mermaid-example +zenuml + title Reply message + Client->A.method() { + B.method() { + if(condition) { + return x1 + // return early + @return + A->Client: x11 + } + } + return x2 + } +``` + +```mermaid +zenuml + title Reply message + Client->A.method() { + B.method() { + if(condition) { + return x1 + // return early + @return + A->Client: x11 + } + } + return x2 + } +``` + +## Nesting + +Sync messages and Creation messages are naturally nestable with `{}`. + +```mermaid-example +zenuml + A.method() { + B.nested_sync_method() + B->C: nested async message + } +``` + +```mermaid +zenuml + A.method() { + B.nested_sync_method() + B->C: nested async message + } +``` + +## Comments + +It is possible to add comments to a sequence diagram with `// comment` syntax. +Comments will be rendered above the messages or fragments. Comments on other places +are ignored. Markdown is supported. + +See the example below: + + // a comment on a participent will not be rendered + BookService + // a comment on a message. + // **Markdown** is supported. + BookService.getBook() + +## Loops + +It is possible to express loops in a ZenUML diagram. This is done by any of the +following notations: + +1. while +2. for +3. forEach, foreach +4. loop + + + + while(condition) { + ...statements... + } + +See the example below: + +```mermaid-example +zenuml + Alice->John: Hello John, how are you? + while(true) { + John->Alice: Great! + } +``` + +```mermaid +zenuml + Alice->John: Hello John, how are you? + while(true) { + John->Alice: Great! + } +``` + +## Alt + +It is possible to express alternative paths in a sequence diagram. This is done by the notation + + if(condition1) { + ...statements... + } else if(condition2) { + ...statements... + } else { + ...statements... + } + +See the example below: + +```mermaid-example +zenuml + Alice->Bob: Hello Bob, how are you? + if(is_sick) { + Bob->Alice: Not so good :( + } else { + Bob->Alice: Feeling fresh like a daisy + } +``` + +```mermaid +zenuml + Alice->Bob: Hello Bob, how are you? + if(is_sick) { + Bob->Alice: Not so good :( + } else { + Bob->Alice: Feeling fresh like a daisy + } +``` + +## Opt + +It is possible to render an `opt` fragment. This is done by the notation + + opt { + ...statements... + } + +See the example below: + +```mermaid-example +zenuml + Alice->Bob: Hello Bob, how are you? + Bob->Alice: Not so good :( + opt { + Bob->Alice: Thanks for asking + } +``` + +```mermaid +zenuml + Alice->Bob: Hello Bob, how are you? + Bob->Alice: Not so good :( + opt { + Bob->Alice: Thanks for asking + } +``` + +## Parallel + +It is possible to show actions that are happening in parallel. + +This is done by the notation + + par { + statement1 + statement2 + statement3 + } + +See the example below: + +```mermaid-example +zenuml + par { + Alice->Bob: Hello guys! + Alice->John: Hello guys! + } +``` + +```mermaid +zenuml + par { + Alice->Bob: Hello guys! + Alice->John: Hello guys! + } +``` + +## Try/Catch/Finally (Break) + +It is possible to indicate a stop of the sequence within the flow (usually used to model exceptions). + +This is done by the notation + + try { + ...statements... + } catch { + ...statements... + } finally { + ...statements... + } + +See the example below: + +```mermaid-example +zenuml + try { + Consumer->API: Book something + API->BookingService: Start booking process + } catch { + API->Consumer: show failure + } finally { + API->BookingService: rollback status + } +``` + +```mermaid +zenuml + try { + Consumer->API: Book something + API->BookingService: Start booking process + } catch { + API->Consumer: show failure + } finally { + API->BookingService: rollback status + } +``` diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index 2ca53b348..1076a51f2 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -120,6 +120,7 @@ function sidebarSyntax() { { text: 'C4C Diagram (Context) Diagram 🦺⚠️', link: '/syntax/c4c' }, { text: 'Mindmaps 🔥', link: '/syntax/mindmap' }, { text: 'Timeline 🔥', link: '/syntax/timeline' }, + { text: 'Zenuml 🔥', link: '/syntax/zenuml' }, { text: 'Other Examples', link: '/syntax/examples' }, ], }, diff --git a/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts b/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts index 4752a1c01..47e238692 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts @@ -1,6 +1,10 @@ import mermaid, { type MermaidConfig } from 'mermaid'; +import zenuml from '../../../../../mermaid-zenuml/dist/mermaid-zenuml.core.mjs'; + +const init = mermaid.registerExternalDiagrams([zenuml]); export const render = async (id: string, code: string, config: MermaidConfig): Promise => { + await init; mermaid.initialize(config); const { svg } = await mermaid.render(id, code); return svg; diff --git a/packages/mermaid/src/docs/syntax/img/zenuml-participant-annotators.png b/packages/mermaid/src/docs/syntax/img/zenuml-participant-annotators.png new file mode 100644 index 000000000..13789371f Binary files /dev/null and b/packages/mermaid/src/docs/syntax/img/zenuml-participant-annotators.png differ diff --git a/packages/mermaid/src/docs/syntax/zenuml.md b/packages/mermaid/src/docs/syntax/zenuml.md new file mode 100644 index 000000000..03081f2b9 --- /dev/null +++ b/packages/mermaid/src/docs/syntax/zenuml.md @@ -0,0 +1,297 @@ +# ZenUML + +> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order. + +Mermaid can render sequence diagrams with ZenUML. Note that ZenUML uses a different +syntax than the original Sequence Diagram in mermaid. + +```mermaid-example +zenuml + title Demo + Alice->John: Hello John, how are you? + John->Alice: Great! + Alice->John: See you later! +``` + +## Syntax + +### Participants + +The participants can be defined implicitly as in the first example on this page. The participants or actors are +rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a +different order than how they appear in the first message. It is possible to specify the actor's order of +appearance by doing the following: + +```mermaid-example +zenuml + title Declare participant (optional) + Bob + Alice + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +### Annotators + +If you specifically want to use symbols instead of just rectangles with text you can do so by using the annotator syntax to declare participants as per below. + +```mermaid-example +zenuml + title Annotators + @Actor Alice + @Database Bob + Alice->Bob: Hi Bob + Bob->Alice: Hi Alice +``` + +Here are the available annotators: +![img.png](img/zenuml-participant-annotators.png) + +### Aliases + +The participants can have a convenient identifier and a descriptive label. + +```mermaid-example +zenuml + title Aliases + A as Alice + J as John + A->J: Hello John, how are you? + J->A: Great! +``` + +## Messages + +Messages can be one of: + +1. Sync message +2. Async message +3. Creation message +4. Reply message + +### Sync message + +You can think of a sync (blocking) method in a programming language. + +```mermaid-example +zenuml + title Sync message + A.SyncMessage + A.SyncMessage(with, parameters) { + B.nestedSyncMessage() + } +``` + +### Async message + +You can think of an async (non-blocking) method in a programming language. +Fire an event and forget about it. + +```mermaid-example +zenuml + title Async message + Alice->Bob: How are you? +``` + +### Creation message + +We use `new` keyword to create an object. + +``` +new A1 +new A2(with, parameters) +``` + +### Reply message + +There are three ways to express a reply message: + +``` +// 1. assign a variable from a sync message. +a = A.SyncMessage() + +// 1.1. optionally give the variable a type +SomeType a = A.SyncMessage() + +// 2. use return keyword +A.SyncMessage() { + return result +} + +// 3. use @return or @reply annotator on an async message +@return +A->B: result +``` + +The third way `@return` is rarely used, but it is useful when you want to return to one level up. + +```mermaid-example +zenuml + title Reply message + Client->A.method() { + B.method() { + if(condition) { + return x1 + // return early + @return + A->Client: x11 + } + } + return x2 + } +``` + +## Nesting + +Sync messages and Creation messages are naturally nestable with `{}`. + +```mermaid-example +zenuml + A.method() { + B.nested_sync_method() + B->C: nested async message + } +``` + +## Comments + +It is possible to add comments to a sequence diagram with `// comment` syntax. +Comments will be rendered above the messages or fragments. Comments on other places +are ignored. Markdown is supported. + +See the example below: + +``` +// a comment on a participent will not be rendered +BookService +// a comment on a message. +// **Markdown** is supported. +BookService.getBook() +``` + +## Loops + +It is possible to express loops in a ZenUML diagram. This is done by any of the +following notations: + +1. while +2. for +3. forEach, foreach +4. loop + +``` +while(condition) { + ...statements... +} +``` + +See the example below: + +```mermaid-example +zenuml + Alice->John: Hello John, how are you? + while(true) { + John->Alice: Great! + } +``` + +## Alt + +It is possible to express alternative paths in a sequence diagram. This is done by the notation + +``` +if(condition1) { + ...statements... +} else if(condition2) { + ...statements... +} else { + ...statements... +} +``` + +See the example below: + +```mermaid-example +zenuml + Alice->Bob: Hello Bob, how are you? + if(is_sick) { + Bob->Alice: Not so good :( + } else { + Bob->Alice: Feeling fresh like a daisy + } +``` + +## Opt + +It is possible to render an `opt` fragment. This is done by the notation + +``` +opt { + ...statements... +} +``` + +See the example below: + +```mermaid-example +zenuml + Alice->Bob: Hello Bob, how are you? + Bob->Alice: Not so good :( + opt { + Bob->Alice: Thanks for asking + } +``` + +## Parallel + +It is possible to show actions that are happening in parallel. + +This is done by the notation + +``` +par { + statement1 + statement2 + statement3 +} +``` + +See the example below: + +```mermaid-example +zenuml + par { + Alice->Bob: Hello guys! + Alice->John: Hello guys! + } +``` + +## Try/Catch/Finally (Break) + +It is possible to indicate a stop of the sequence within the flow (usually used to model exceptions). + +This is done by the notation + +``` +try { + ...statements... +} catch { + ...statements... +} finally { + ...statements... +} +``` + +See the example below: + +```mermaid-example +zenuml + try { + Consumer->API: Book something + API->BookingService: Start booking process + } catch { + API->Consumer: show failure + } finally { + API->BookingService: rollback status + } +```