@zenuml/core 2.0.0

package/docs/asciidoc/contributor.adoc

@@ -0,0 +1,79 @@
+== 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
+yarn build
+# to build the web application
+yarn build:site
+....
+
+=== Customize vue.config.js
+
+==== Inline SVG
+When we build the library, SVG must be inlined.
+
+An inlined SVG looks like this:
+....
+<img src='data:image/svg+xml;base64,<svg ... > ... </svg>'>
+....
+
+[NOTE]
+====
+[TODO] Note that we use the `base64` encoding as it is the default behaviour of webpack 5
+asset module `asset/inline`. However, `utf8` has https://www.npmjs.com/package/svg-url-loader[the following advantages]:
+
+1. Resulting string is shorter (can be ~2 times shorter for 2K-sized icons);
+2. Resulting string will be compressed better when using gzip compression;
+3. Browser parses utf-8 encoded string faster than its base64 equivalent.
+
+This can be implemented with https://webpack.js.org/guides/asset-modules/#custom-data-uri-generator[custom data URI generator].
+====
+The default loader build in vue cli service for svg files will not inline the SVG,
+but give a url (relative path) to the svg resource like this:
+....
+<img src="/assets/arrow.svg">
+....
+Client applications will not be able to load the SVG properly.
+
+To inline the SVG, we need to use https://webpack.js.org/guides/asset-modules/#inlining-assets[asset module `asset/inline`].
+
+
+[source, javascript]
+....
+const svgRule = config.module.rule('svg')
+svgRule.store.clear();
+svgRule
+    .test(/\.svg$/)  // required because of store.clear()
+    .type('asset/inline')  // <1>
+    .end()
+....
+<1> `asset/inline` exports a data URI of the asset. Previously achievable by using `url-loader`. https://webpack.js.org/guides/asset-modules/#inlining-assets[See more]
+
+== 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.
+
+
+

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

@@ -0,0 +1,25 @@
+= 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
+
+== 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 stylebot browser extension, you can apply themes in any browsers.
+
+=== JetBrains
+
+=== app.zenuml.com
+
+== Tips
+
+=== Give occurrence a boarder
+
+
+

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

@@ -0,0 +1 @@
+<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

@@ -0,0 +1,277 @@
+: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/integration-guide.adoc

@@ -0,0 +1,121 @@
+= Integration Guide
+:icons: font
+
+== Audience
+This document is written for those want to integrate ZenUML to their applications. If you are an end
+user, please read tutorials; if your would like to contribute, please read contributor's guide.
+
+
+== Integration
+An important goal of this project is to be easily integrated into other projects.
+There are mainly two ways to do this.
+
+=== As a library
+
+ZenUML Core exposes a simple API for integration:
+
+[source, typescript]
+----
+interface IZenUml {
+  get code(): string | undefined;
+  get theme(): string | undefined;
+  // Resolve after rendering is finished.
+  render: (code: string | undefined, theme: string | undefined) => Promise<IZenUml>
+}
+
+// client code
+import ZenUml from '@ZenUML/core'
+const zenUml = new ZenUml(el)
+await zenUml.render('A.method', 'theme-blue')
+----
+
+==== When rendering is finished
+When rendering is finished, the `render` method will return a promise that resolves to the
+instance of `IZenUml`. The `html` properties of the instance will be updated to the rendered
+HTML.
+
+[NOTE]
+====
+Vue's reactive system works against the `data`, `props` and `computed` properties of a component.
+This means a parent component is not necessarily be notified when a child component is `mounted` or `updated`.
+So this means we can not use the `mounted` or `updated` hook on `LifelineLayer` to emit `rendered` event.
+====
+
+It is tricky to know when the rendering is finished. The `Lifeline` components used `$nextTick`
+in their `mounted` and `updated` hooks to set the top when a `creation` message is sent to it.
+We have to wait until all those `$nextTick` calls are finished.
+
+[NOTE]
+====
+It seems that (to be confirmed) the `$nextTick` calls are queued and executed in ONE tick. This
+makes it easier to control the timing when to resolve the `render` promise. We only need to wait
+ONE `$nextTick` call to be finished.
+====
+
+The diagram is rendered in the following steps:
+
+1. The lifeline layer;
+2. The message layer;
+3. Update lifeline layer with `setTimeout` for `creation` messages.
+
+=== As an iframe
+
+You can embed the ZenUML core renderer as an application within another app, where you store the diagram
+data in the host app. It takes around 5 minutes to get a basic example running.
+
+==== Quick test
+To test this out open `https://embed.zenuml.com/embed.html`. In the developer console, type in the
+following command.
+
+[source,js]
+----
+window.postMessage( {action: 'eval', args: { code: 'ZenUML.Hello' }})
+----
+==== The protocol
+
+The protocol is a simple JSON object with the following fields.
+
+[source,json]
+----
+{
+  "action": "eval",
+  "args": {
+    "code": "ZenUML.Hello",
+    "style": "#diagram { background-color: red; }",
+    "theme": "blue",
+    "css": "https://github.com/abruzzi/zenuml-css-overrides/blob/master/zenuml-override.css"
+  }
+}
+----
+
+==== Example
+
+[source,html]
+----
+<iframe src="https://embed.zenuml.com/embed.html" id="zenuml-iframe"
+        style="width: 100%; height: 100%; border: none;">
+
+</iframe>
+<script>
+  const iframe = document.getElementById('zenuml-iframe');
+  const message = {
+    action: 'eval',
+    args: {
+      code: 'ZenUML.Hello',
+      style: '#diagram { background-color: red; }',
+      theme: 'blue',
+      css: ''
+    }
+  };
+  setTimeout(() => {
+    iframe.contentWindow.postMessage(message, '*');
+  }, 1000);
+</script>
+----
+
+[source,js]
+----
+document.getElementsByTagName('iframe')[0] // get iframe
+    .contentWindow  // get target window
+    .postMessage({action: "eval", args: { code: 'A.m' }})
+----

package/docs/asciidoc/tutorial.adoc

@@ -0,0 +1,22 @@
+= 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

@@ -0,0 +1,78 @@
+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/highlighting-messages.md

@@ -0,0 +1,47 @@
+Since 1.0.63
+
+# Highlighting messages
+The renderer will highlight an `Interaction` based on the value of `cursor` in the store.
+For example, for DSL `A.x B.y`, if `cursor` is between [0, 3], `A.x` is highlighted in
+the diagram; if `cursor` is between [4, 7], `B.y` is highlighted. 
+
+## What elements can be highlighted?
+
+Theoretically, every element can be highlighted. The logic is different for 
+different types.
+
+We will focus on messages: Creation and Messages (Sync & Async).
+
+### Creation
+
+Creations parser definition is:
+```
+creationBody (SCOL | braceBlock)?
+```
+
+We will highlight the creation call and assignment but NOT the `braceBlock`. 
+The triggering cursor must be in between `creationBody`.
+
+### Message
+
+Message parser definition is:
+```
+messageBody (SCOL | braceBlock)?
+```
+We will highlight the message call and assignment but NOT the `braceBlock`.
+The triggering cursor must be in between `messageBody`.
+
+### Async Message
+
+Async message parser definition is:
+```
+source ARROW target COL content
+``` 
+We will highlight the whole message call.
+The triggering curso must bee in between `source ARROW target COL content`.
+
+
+## Implementation
+
+The global store has a state `cursor`. Each component check whether this cursor
+is in between the range that should set the `isCurrent` status of itself.