@zenuml/core 3.47.8 → 3.48.0

package/docs/ai-context/system-integration.md

@@ -1,21 +0,0 @@
-# System Integration Documentation
-
-This document contains cross-component integration patterns and system-wide architectural decisions.
-
-## Purpose
-
-This template serves as a placeholder for documenting:
-- Cross-component communication patterns
-- Data flow architectures between services
-- Integration strategies with external systems
-- Performance optimization patterns
-- Testing strategies for integrated systems
-- Error handling across service boundaries
-
-## Implementation Note
-
-Replace this template with your actual system integration documentation as your project develops. Focus on patterns that AI agents need to understand when working across component boundaries or implementing features that span multiple services.
-
----
-
-*Customize this template based on your specific integration patterns and architectural requirements.*

package/docs/asciidoc/contributor.adoc

@@ -1,54 +0,0 @@
-== Audience
-:icons: font
-
-This document is written for the contributors. If you want to integrate ZenUML in your application,
-you should read index.adoc; if you want to create themes, you should read create-my-own-theme.adoc.
-
-== Build
-This project is built with vue cli. It has two types of target: the web application and the library.
-
-....
-# to build the library
-bun run build
-# to build the web application
-bun run build:site
-....
-
-== Demo pages
-In the public folder, there are some demo pages for testing the library.
-
-=== How do they work?
-
-The demo pages^1^ are built with vue cli service. On the page, there needs to be a `pre`
-element with class `zenuml` and the content being the ZenUML DSL code.
-
-For example:
-[source, html]
-....
-<pre class="zenuml">
-A.method
-</pre>
-....
-
-The entry point of the demo pages is `src/main.ts`. It will find all the `pre` elements with
-class `zenuml` and render the ZenUML DSL code in it.
-
-== Parser
-
-We use antlr4 to parse the ZenUML DSL code. The grammar files are:
-
-1. Parser: `./src/g4/sequenceParser.g4`
-2. Lexer: `./src/g4/sequenceLexer.g4`
-
-=== How to generate the parser and lexer
-
-Run `bun run antlr` to generate the parser and lexer.
-
-=== Setup local development environment
-
-Run `bun run antlr:setup` (`python3 -m pip install antlr4-tools`) to install the antlr4 command and the runtime.
-
-To test the setup, go to `src/g4-unit/hello-world` folder, and run:
-
-1.
-

package/docs/asciidoc/create-my-own-theme.adoc

@@ -1,149 +0,0 @@
-= Creat my own theme
-
-Since the elements on the rendered diagram is based on HTML Dom (and svg), it is simple
-to create your own theme. There is a repository on GitHub that have some themes collected
-by third party. You may be able to get some inspiration from there. https://github.com/abruzzi/zenuml-css-overrides
-
-== The Information Architecture
-image::./images/three-layer-info-arch.png[width=600]
-
-The diagram is rendered in two layers. The back layer is the lifeline layer. The front layer
-is the message layer.
-
-Key information on the diagram can be grouped in the following structure:
-
-Text messages are internally styled at four levels:
-
-1. text-skin-base: used for all messages
-2. text-skin-muted: used for comments
-3. text-skin-link: used for links
-4. text-skin-secondary: used for everything else, such as title, participant, divider notes, etc.
-
-When it comes to branding, the following elements are the most important:
-
-1. Canvas background, however, it can easily be overwhelming if you use high contrast color to the
-overall page background.
-2. Title background, participant background and fragment header background are the most attractive
-elements to brand. These are where your brand color should be used.
-3. The background of the occurrence (message bar) is also a good place to use your brand color, but
-less attractive than the above three.
-4. The borders of the frame, participant, fragment, occurrence and lifeline can add a bit
-of color to the diagram.
-5. The color of the message and the arrow  are the most important information on
-the diagram. Choose a striking and comfortable color for them. You can use the brand color here, but
-they should not be the only elements that reflect your brand color. Same principles apply to the
-background and text color for hover state.
-6. Then is the color of link and control. They should avoid attracting too much attention
-
-[%autowidth]
-|===
-|Category | Diagram Frame |Lifeline Layer | Message Layer
-
-h|Text Info
-a|* Title
-* Brand
-a|* Participant name
-* Stereotype
-* Comment
-
-a|* Message name
-* Fragment type
-* Fragment condition
-* Comment
-* Divider name
-
-h|Shapes
-a|* Security (icon)
-* Tips (icon)
-a|* Participant box (rectangle)
-* Lifeline (vertical line)
-a|* Message arrow (line and head)
-* Fragment (rectangle)
-* Divider line (left and right)
-
-|===
-
-Each of the elements has a semantic selector that can be used to customize the appearance.
-
-The component has basic styling in itself mostly to support layout and positioning. Then
-the core renderer comes with a default theme that defines the appearance of the elements.
-
-[source,css]
-----
-
-----
-
-A typical custom theme will be like below:
-
-[source,css]
-----
-----
-
-== What can a theme change?
-
-A theme can change two aspects of the diagram:
-
-1. colors
-2. slightly change the layout (e.g. padding, margin, etc.). For example, you can make the
-diagram more compact by reducing the padding.
-
-== where can I apply themes
-
-You can apply themes on the follow products:
-
-. JetBrains plugins (Intellij IDEA, WebStore, PhpStore, etc.)
-. https://app.zenuml.com
-
-With https://chrome.google.com/webstore/detail/user-css/okpjlejfhacmgjkmknjhadmkdbcldfcb[User CSS]
-browser extension, you can apply themes anywhere (e.g. https://zenuml.cn).
-
-== Principles of creating themes
-
-=== 1. Do not override tailwind classes
-The tailwind classes directly applied on the elements are important for layout so
-they are NOT meant be overridden.
-
-For example,
-[html]
-....
-// Participant.vue
-<div class="participant relative flex flex-col justify-center z-10 h-10"
-....
-
-=== 2. Use provided class selectors
-Important elements are provided with a semantic class selector. You can use them
-to override the style.
-
-For the above example, the class selector is `participant`. You can override the
-style by using this selector.
-
-[css]
-....
-// use `.zenuml .sequence-diagram` to increase specificity
-.zenuml .sequence-diagram .participant {
-  background-color: #f00;
-}
-....
-
-=== 3. Debug your theme
-
-You can use the browser extension https://chrome.google.com/webstore/detail/user-css/okpjlejfhacmgjkmknjhadmkdbcldfcb[User CSS]
-to debug your theme.
-
-image::user-css.png[User CSS]
-
-Alternatively, you can use our web app https://app.zenuml.com[app.zenuml.com]. Go to the CSS tab
-and paste your theme there. You can see the result immediately.
-
-image::theme-debug-web-app.png[]
-
-=== JetBrains
-
-=== app.zenuml.com
-
-== Tips
-
-=== Give occurrence a boarder
-
-
-

package/docs/asciidoc/images/vertical-alignment.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 202.624 202.624" style="enable-background:new 0 0 202.624 202.624" xml:space="preserve"><path d="M202.621 97.416h-38.966V58.45a3.896 3.896 0 0 0-3.897-3.897h-38.966a3.896 3.896 0 0 0-3.897 3.897v38.966H85.724V35.07a3.896 3.896 0 0 0-3.897-3.897H42.862a3.896 3.896 0 0 0-3.897 3.897v62.345H0v7.793h38.966v62.345a3.896 3.896 0 0 0 3.897 3.897h38.966a3.896 3.896 0 0 0 3.897-3.897v-62.345h31.172v38.966a3.896 3.896 0 0 0 3.897 3.897h38.966a3.896 3.896 0 0 0 3.897-3.897v-38.966h38.966v-7.793h-.003zm-124.69 0v66.241H46.759V38.968h31.172v58.448zm77.931 0v42.862H124.69V62.346h31.172v35.07z"/></svg>

package/docs/asciidoc/index.adoc

@@ -1,277 +0,0 @@
-:icons: font
-
-== Font
-Font [.underline]#must# be *preloaded*. Font mainly have impact to Creation
-rendering. The font will impact the width of the participant box which then
-impacts the with of message container for creation.
-
-The following code should help with preloading google fonts. But it is not super
-reliable. Specifically, when you disable cache in Chrome. It is not preloaded
-where you can see the impact.
-
-....
-<link rel='preconnect' href='https://fonts.gstatic.com' crossorigin>
-<link rel='preload stylesheet' as='style' href='https://fonts.googleapis.com/css2?family=Roboto+Slab:wght@300;400;500;700&display=swap'>
-....
-
-We have to use `setTimeout` to delay the calculation of the width of the
-message container.
-
-== The two layer structure
-At the highest level, the diagram is rendered in two layers:
-the lifeline layer and the message layer.
-
-....
-<div class="sequence-diagram">
-    <div class="life-line-layer absolute h-full">
-    </div>
-    <div class="message-layer">
-    </div>
-</div>
-....
-
-=== Key classes
-==== .absolute
-The `absolute` class is used to remove the lifeline layer from the normal
-flow of the document.
-
-==== .h-full
-The `h-full` class is used to make the lifeline layer as tall as the parent
-element. The parent element get the height from the `message-layer`.
-
-== The message layer
-
-=== Occurrence
-_TODO_: explain misalignment of the occurrence concept and the spec.
-
-image::images/occurrence.png[width=304,alt="occurrence"]
-
-The occurrence is the bar (or invisible bar for async messages) that
-represents the execution of a message.
-
-It has a width of 15px and border of 2px. These two values #must not#
-be overridden in themes.
-
-It has a padding-left of 5px which pushes the children `interaction` to
-the middle of the occurrence.
-....
-(occurrenceWidth - occurrenceBorderWidth x 2 - lifelineWidth) / 2
-= (15 - 2 x 2 - 1) / 2
-= 5
-....
-
-Because the lifeline has width of 1px, for normal (left to right) `interaction` s
-we give it a margin left of 1px to avoid the overlap of the lifeline and the
-interaction border. See `interaction` for more details.
-
-=== Interaction
-The `interaction` is one of the key conceptual elements. It works with
-the `occurrence` to influence high-level layout. The `interaction` is the container
-of the message, children interactions and the response.
-
-The `interaction` has a border of 5px. This value #must not# be overridden in themes.
-....
-(occurrenceWidth - occurrenceBorderWidth x 2 - lifelineWidth) / 2
-= (15 - 2 x 2 - 1) / 2
-= 5
-....
-
-Within Interaction, the DOM structure is like below:
-
-....
-<div class="interaction">
-    <div class="occurrence source"></div>
-    <comment/>
-    <invocation/> <1>
-    <occurrence/>
-    <message type="return">
-</div>
-
-....
-<1> SelfInvocation or Message
-
-
-==== Do not add margin to interaction
-It is on purpose that interaction box overlaps source lifeline but not the target
-lifeline. Do not add #margin# to interaction components. This margin will cause
-interaction's right board overlaps target lifeline and that is accumulative.
-
-==== Debugging
-Disable transparency of the interaction borders.
-
-=== Common features among Interaction, Interaction and Creation
-
-All the three work as a container for the message, children interactions and the
-response. In the normal direction (left to right), they start with the middle
-of the source lifeline and end with the middle of the target lifeline.
-
-=== Return message
-
-The return message is the message that is sent back to the sender of the original
-message. It is rendered as a dashed line.
-
-A return message is rendered from three syntax:
-
-* `return x` which matches `RETURN expr? SCOL?`
-* `@return A->B: ret` which matches `ANNOTATION_RET asyncMessage EVENT_END?`
-* `x=A.m` or `x=new A()` which matches `assignment? ((from ARROW)? to DOT)? func` or `assignment? NEW construct(OPAR parameters? CPAR)?`
-
-
-==== Statement `return x` or `@return A->B: ret`
-
-`return x` or `@return A->B: ret` is implemented via the `Return` component.
-In such cases, it has its own context and can have a comment. Then it
-delegates to `SelfInvocation` or `Message`.
-
-===== When do we need `@return A->B: ret`?
-
-....
-Browser->BookController.onPost() {
-  BookLibService.Borrow(id) {
-      receipt = process(id)
-      if (receipt != null) {
-        return receipt
-        @return BookController->Browser: receipt
-      } else {
-        return null
-        @return BookController->Browser: 404
-      }
-  }
-}
-....
-
-If the statement is the last statement we set the height of the message to 0px,
-so that it does not push the message down further. This is because a return message
-does not have children and does not need an occurrence.
-
-....
-.statement-container:last-child>.return {
-    height: 0;
-}
-....
-
-==== Return message from `x=A.m` or `x=new A`
-This is implemented in Interaction and Creation components.
-
-....
-<message class="return transform -translate-y-full"/>
-....
-
-==== Conflicting return messages
-We provide two ways in DSL to represent `return` messages:
-
-....
-// option 1
-x = A.method
-// option 2
-A.method() {
-  return y
-}
-....
-
-If you use both, we will render both with overlapping. This is on purpose to expose
-the conflict to the user.
-
-.Return message conflict
-image::images/return-message-conflict.png[width=200,alt="return message conflict"]
-
-=== Message arrow
-.Message arrow (the dashed line and arrow head)
-image::images/creation-component.png[width=224]
-
-This time we focus on how to align the arrow line and the arrow head.
-We use a similar approach as pattern #vertically aligning# with pattern
-#shift half the height#. Instead of `items-center` we use `items-end`.
-Then we use `translate-y-1/2` to shift the arrow head down half the
-height of the arrow head. (See Message.vue)
-....
-  <div class="message flex items-end"
-    <div class="name flex-grow" style="padding-left: 10px">{{content}}</div>
-    <point class="flex-shrink-0 transform translate-y-1/2 -my-px" :fill="fill" :rtl="rtl"/>
-  </div>
-....
-
-==== Key classes
-===== .flex .items-end
-The `flex` and `items-end` classes are used to align the arrow line
-and the arrow head at the bottom of the message.
-
-===== .flex-grow
-The `flex-grow` class is used to make the message name grow to fill
-the available space.
-
-===== .flex-shrink-0
-The `flex-shrink-0` class is used to make the arrow head not shrink
-when the message name is too long.
-
-===== .transform .translate-y-1/2
-The `transform` and `translate-y-1/2` classes are used to shift the
-arrow head down half the height of the arrow head.
-
-=== Message arrow right to left
-image::images/message-arrow-rtl.png[width=200,alt="message arrow right to left"]
-
-....
-  <div class="message flex items-end" :class="{'flex-row-reverse': rtl}">
-    <div class="name flex-grow"
-          >{{content}}</div>
-    <point class="flex-shrink-0 transform translate-y-1/2 -my-px"/>
-  </div>
-....
-
-==== Key classes
-===== .flex-row-reverse
-The `flex-row-reverse` class is used to reverse the order of the name and
-the arrow head.
-
-=== Creation
-image::images/creation-component.png[width=240]
-
-==== Pattern 1: Vertically aligning
-image::images/vertical-alignment.svg[width=40]
-
-....
-<div class="flex items-center">
-  <div class="w-10 h-8 bg-blue-200"></div>
-  <div class="w-10 h-20 bg-green-200"></div>
-</div>
-....
-
-==== Pattern 2: Shift half the height
-image::images/shift-up-half-the-height.png[width=50]
-
-The message arrow is supposed to point to the middle of the participant
-box. It is not he whole message that is aligned with the participant
-box. So we have to shift the message up half the height of the message.
-....
-<div class="flex items-center m-10">
-  <div class="w-10 h-8 bg-blue-200 transform -translate-y-1/2"></div>
-  <div class="w-10 h-20 bg-green-200"></div>
-</div>
-....
-
-This pattern is also used at the arrows. See the image for creation.
-
-=== Creation participant top
-While all normal participants have their name boxes at the top of the
-diagram, creation participant boxes need to be pushed down to align
-with the message arrow.
-
-To implement this, we add a `padding-top` to the containing lifeline
-of the corresponding participant.
-
-The padding top is calculated by subtracting the top of message from
-the top of participant's original value.
-
-==== Challenge
-When the message container is mounted, it does not have the correct
-participant box offsetWidth.
-
-=== Creation right to left
-image::images/creation-rtl.png[width=240,alt="creation right to left"]
-
-On top of normal Creation, we need to flip the participant placeholder
-and the message container. We use the `flex-row-reverse` class to flip.
-See "Message right to left" for example using `flex-row-reverse`.
-
-

package/docs/asciidoc/tutorial.adoc

@@ -1,22 +0,0 @@
-= User's guide
-
-== Audience
-This document is written for end users of the software. If you want to integrate
-ZenUML into your own application, please refer to the integration guide. If you
-want to contribute to the development of ZenUML, please refer to the contributor's
-guide.
-
-== Introduction
-> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
-
-ZenUML is a tool for creating sequence diagrams from text. It runs completely
-in the browser, so you don't need to worry about data privacy or security. See
-https://link[data privacy and security] for more information.
-
-++++
-<iframe src="https://embed.zenuml.com/smoke-creation.html"></iframe>
-++++
-
-== Syntax
-
-=== Participants

package/docs/async-vs-sync-parser-rules.md

@@ -1,81 +0,0 @@
-Async:
-
-```
-asyncMessage
- : source ARROW target COL content
- | source (MINUS | ARROW) target?
- ;
-
-content
- : EVENT_PAYLOAD_LXR
- ;
-
-source
- : ID | STRING
- ;
-
-target
- : ID | STRING
- ;
-```
-
-Sync:
-
-```
-message
- : messageBody (SCOL | braceBlock)?
- ;
-
-// Order of 'func | (to DOT)' is important. Otherwise A.m will be parsed as to messages
-messageBody
- : assignment? ((from ARROW)? to DOT)? func
- | assignment
- | to DOT
- ;
-
-// func is also used in exp as parameter with expr: (to DOT)? func;
-func
- : signature (DOT signature)*
- ;
-
-from
- : ID | STRING
- ;
-
-signature
- : methodName invocation?
- ;
-
-// We have removed the alternative rule with single OPAR as we are improving the editor to always close the brackets.
-invocation
- : OPAR parameters? CPAR
- ;
-
-assignment
- : (type? assignee ASSIGN)
- ;
-```
-
-First of all, `from->to` and `source->target` are very similar. Let's first merge them.
-
-      if(!this.rightToLeft) {
-        if(this.outOfBand) {
-          // A    B     C
-          // inh  pro   to
-          const dist = this.distance2(this.origin, this.providedFrom)
-          return dist - indent + fragmentOff
-        } else {
-          // A    B
-          // inh  to
-          // No self call indent here. It is used only for width.
-          return fragmentOff
-        }
-      } else {
-        // A    B     C
-        // to   pro   origin
-        // OR
-        // A    B
-        // to   origin
-        const dist = this.distance2(this.to, this.origin)
-        return (dist - indent - fragmentOff) * (-1)
-      }

package/docs/divider-parser-allow-spaces.md

@@ -1,38 +0,0 @@
-This document describe the design of parsing rules for the `divider` statement.
-
-## Typical use case
-
-The `divider` statement is used to separate the sequence of statements into logical
-groups.
-
-For example, a HTTPS sequence can be separated into three logical groups:
-
-1. Connect establishment
-2. TLS handshake
-3. HTTP request/response
-
-```
-Client->Server: TCP SYNC
-Server->Client: TCP SYN+ACK
-Client->Server: TCP ACK
-== Connection Established ==
-Client->Server: TLS Client Hello
-Server->Client: TLS Server Hello
-Server->Client: TLS Certificate
-Server->Client: TLS Server Hello Done
-== Certificate Check ==
-Client->Server: TLS Client Key Exchange
-Client->Server: TLS Change Cipher Spec
-Client->Server: TLS Finished
-Server->Client: TLS Change Cipher Spec
-Server->Client: TLS Finished
-== Key Exchange, Handshake Completed ==
-Client->Server: HTTP Request
-Server->Client: HTTP Response
-```
-
-## The Lexer
-
-## `divider` is a statement
-
-`divider` is treated as a statement as any other messages.