Open NicolasNewman opened 2 months ago
Name | Link |
---|---|
Latest commit | 3f039562b9793be06b95e4cd590dfacfb951c5e0 |
Latest deploy log | https://app.netlify.com/sites/mermaid-js/deploys/664e0a7af82f2a000830a8e6 |
Deploy Preview | https://deploy-preview-5452--mermaid-js.netlify.app |
Preview on mobile | Toggle QR Code...Use your smartphone camera to open QR code link. |
To edit notification comments on pull requests, go to your Netlify site configuration.
Attention: Patch coverage is 0.35300%
with 1976 lines
in your changes are missing coverage. Please review.
Project coverage is 5.48%. Comparing base (
cf20ccb
) to head (b09dc5d
).:exclamation: Current head b09dc5d differs from pull request most recent head 3f03956
Please upload reports for the commit 3f03956 to get more accurate results.
@sidharthv96 Continuing our conversation from the issue, I commented on SVG loading and my thought process behind how the layout is handled. Let me know what your thoughts are.
Additionally, an example of what forked edges would look like once implemented:
Regarding multiple edges going into one side of a service, it's possible but I'll need to spend some time figuring out the cleanest way to implement that functionality. Ultimately I was planning on using forked edges to handle that scenario but after looking at your example the arrows can't be as neatly represented the same way through forked edges.
Here is where the renderer currently stands.
From a stylistic standpoint I'm considering: 1) shortening the edges so they don't overlap with the service label. 2) removing the rotation of the labels for Y/XY edges (or adding a config option)
Regarding the icons it would be awesome if it's possible to use any of those:
Maybe they could be shipped as icon library? From a license PoV this should be okey and would immediately add many icons.
More generic default icons? If anyone has ideas let me know and I can put something together in Illustrator
Or take some of the good ones as default so you don't need to build them yourself.
Solid progress @NicolasNewman 👍
Minor note regarding readability of labels.
I feel the label that goes from top to bottom and right to left is more readable.
Update on diagram syntax changes:
One limitation of fcose is the 3 constraint parameters don't factor in groups. Since this prevented me from directly having edges between group nodes, I had to implement a work-around by extended the parser to signal that an edge endpoint should connect to the group border and not the node itself. In practice, the implementation looks like:
architecture
group left_group(cloud)[Left]
group right_group(cloud)[Right]
group top_group(cloud)[Top]
group bottom_group(cloud)[Bottom]
group center_group(cloud)[Center]
service left_disk(disk)[Disk] in left_group
service right_disk(disk)[Disk] in right_group
service top_disk(disk)[Disk] in top_group
service bottom_disk(disk)[Disk] in bottom_group
service center_disk(disk)[Disk] in center_group
left_disk{group} (R--L) center_disk{group}
right_disk{group} (L--R) center_disk{group}
top_disk{group} (B--T) center_disk{group}
bottom_disk{group} (T--B) center_disk{group}
Note that the {group}
modifier doesn't have to be applied to both ends.
I decided to handle this problem with the concept of a junction node. Internally, its positioned and rendered almost identically to service nodes with the exception that its entirely transparent with no label associated.
architecture
service left_disk(disk)[Disk]
service top_disk(disk)[Disk]
service bottom_disk(disk)[Disk]
service top_gateway(internet)[Gateway]
service bottom_gateway(internet)[Gateway]
junction juncC
junction juncR
left_disk R--L juncC
top_disk B--T juncC
bottom_disk T--B juncC
juncC R--L juncR
top_gateway B--T juncR
bottom_gateway T--B juncR
architecture
group left
group right
service left_disk(disk)[Disk] in left
service top_disk(disk)[Disk] in left
service bottom_disk(disk)[Disk] in left
service top_gateway(internet)[Gateway] in right
service bottom_gateway(internet)[Gateway] in right
junction juncC in left
junction juncR in right
left_disk R--L juncC
top_disk B--T juncC
bottom_disk T--B juncC
top_gateway (B--T juncR
bottom_gateway (T--B juncR
juncC{group} R--L) juncR{group}
As of now, the primary features that remain are: 1) Controlling arrow orientation for junction edges 2) Flexible styling 3) Unit tests 4) Finalize the docs
@sidharthv96 1) Should a mode be added which handles the positioning on its own? I've mentioned my opinion on that earlier where I feel that it would then be very similar to flowcharts. I personally think it would make more sense to update flowcharts to have the same svg icon support. 2) How to handle the inclusion of AWS/Azure/etc icons. Should it be included with Mermaid and dynamically loaded? Should it be split off into its own package? If so, who will host it? (that could also serve as a template for anyone who would like to make their own icon library)
Just to share some opinions
- Should a mode be added which handles the positioning on its own?
Imho, yes. Architecture diagrams tend to get very large and sometimes some manual positioning would be extremely helpful
- How to handle the inclusion of AWS/Azure/etc icons. Should it be included with Mermaid and dynamically loaded?
I would include them and offer the possibility to reference external images. The reason for this is that otherwise we will run into CORS issues e.g. in the GitHub integration as external SVGs cannot be loaded to prevent XSS.
:bookmark_tabs: Summary
Architecture diagrams allows users to show relations between services
Resolves #5367
:straight_ruler: Design Decisions
Parser
Terminology
Syntax
Currently, the syntax is defined as:
service {id}({icon})[{title}] (in {group_name})?
group {id}[{title}] (in {group_id})?
{id_1} ( ( )?(L|R|T|B)--(L|R|T|B)( ) )? {id_2}
Once I transition from jison to Langium, I plan to add the following extensions:
group {id}({icon})[{title}] (in {group_id})?
{id_1} ( ( )?(L|R|T|B)-([{label}])-(L|R|T|B)( ) )? {id_2}
service {id}( ({icon}) | ("{text}") )[{title}] (in {group_name})?
Additionally, the syntax for groups (and potentially forked edges?) will be modified to better follow a declare then organize approach
Layout
Comments
As mentioned in the issue, the LRTB syntax goes against the ethos of Mermaid. Additionally, while the spatial map creates very neatly organized layouts, it prevents users from having multiple edges going out of one side. Part of the reason I began designing it this way was to avoid this diagram type from essentially being a flowchart with icons.
Going forward, there's a few options that can fix this problem:
fcose
and let it figure things out on its own.No matter which option we choose, the LRTB syntax should be extended to:
SVG Icons
SVG icons are currently created and accessed through helper functions inside of rendering-util/svgRegister.ts. A global object stores the mapping of icon names to
IconResolvers
defined asIconResolvers can easily be created through the helper function
createIcon
. This function takes the SVG code as a string along with the original resolution. It returns a CB function taking the element to inject the SVG into and optionally a different size to scale it by.A few generic icons I've created are located in rendering-utils/svg/. Additional icons can be added through the new
iconLibraries
config option. The types insvgRegister.ts
are now exported frommermaid.ts
, allowing developers to create their own icon library packages.Alternatives
From conversations in the linked issue, ZenUML already handles SVG icons on their end. Upon furthur inspection, they rely on declaring an svg module which essentially resolves the imported SVG as a string. Since the end result of both of these approaches are the same (having the SVG code as a string), personally I think it's debatable if we want to go through with this extra step. The main con I foresee is that it'll add more work for people who want to make their own icon library package as they will need to setup the declarations themselves.
On a side note, it looks like ZenUML directly added the official AWS icons to their repo here. IANAL but the terms Amazon states are:
This may mean we can make official icon packs in seperate packages, or have them be lazy loaded as needed. Ultimately I'll leave that decision up to you as that isn't my area of specialties.
Todo
:clipboard: Tasks
Make sure you
MERMAID_RELEASE_VERSION
is used for all new features.develop
branch