Merge pull request #1538 from NeilCuzon/develop

documentation for config and other changes, with minor cosmetic changes to ReadMe

docs/8.6.0_docs.md

@@ -0,0 +1,120 @@
+# Version 8.6.0 Changes
+**Edit this Page** [![N|Solid](https://github.com/NeilCuzon/mermaid/blob/develop/docs/img/GitHub-Mark-32px.png)](https://github.com/NeilCuzon/mermaid/edit/develop/docs/8.6.0_docs.md)
+
+**Try out the Beta Version of the [[New Mermaid Live-Editor](https://mermaid-js.github.io/docs/mermaid-live-editor-beta/#/edit/eyJjb2RlIjoiJSV7aW5pdDoge1widGhlbWVcIjogXCJmb3Jlc3RcIiwgXCJsb2dMZXZlbFwiOiAxIH19JSVcbmdyYXBoIFREXG4gIEFbQ2hyaXN0bWFzXSAtLT58R2V0IG1vbmV5fCBCKEdvIHNob3BwaW5nKVxuICBCIC0tPiBDe0xldCBtZSB0aGlua31cbiAgQyAtLT58T25lfCBEW0xhcHRvcF1cbiAgQyAtLT58VHdvfCBFW2lQaG9uZV1cbiAgQyAtLT58VGhyZWV8IEZbZmE6ZmEtY2FyIENhcl1cblx0XHQiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGFyayJ9fQ)]**
+
+With version 8.6.0 comes the release of directives for mermaid and a new system for configurations, with the aim of establishing centralized, sane defaults and simple implementation.
+
+the init directive is the main method of configuration for Site and Current Levels.
+
+The three levels of are Configuration, Global, Site and Current.
+
+| Level of Configuration | Description |
+| --- | --- |
+| Global Configuration| Default Mermaid Configurations|
+| Site Configuration| Configurations made by site owner|
+| Current Configuration| Configurations made by Implementors|
+
+
+# Limits to Modifying Configurations
+secure Array
+
+| Parameter | Description |Type | Required | Values|
+| --- | --- | --- | --- | --- |
+| secure | Array of parameters excluded from init directive| Array | Required | Any parameters|
+
+The modifiable parts of the Configuration are limited by the secure array, which is an array of immutable parameters, this array can be expanded by site owners.
+
+**Notes**: secure arrays work like nesting dolls, with the Global Configurations’ secure array being the default and immutable list of immutable parameters, or the smallest doll, to which site owners may add to, but implementors may not modify it.
+
+# Secure Arrays
+
+Site owners can add to the **secure** array using this command:
+mermaidAPI.initialize( { startOnLoad: true, secure: ['parameter1', 'parameter2'] } );
+
+default values for the **secure array** consists of: ['secure', 'securityLevel', 'startOnLoad', 'maxTextSize']. These default values are immutable.
+
+Implementors can only modify configurations using directives, but cannot change the **secure** array.
+
+# Modifying Configurations and directives:
+The Two types of directives: are “init” or “initialize” and “wrap”.
+
+**Notes**: All directives are enclosed in %%{ }%%.
+
+Older versions of mermaid will not parse directives because %% will comment out the directive.
+
+# Init
+init, or initialize: the init or initialize directive gives the user the ability to overwrite and change the values for configuration parameters, with respect to the secure array that is in effect.
+
+| Parameter | Description |Type | Required | Values|
+| --- | --- | --- | --- | --- |
+| init | modifies configurations| Directive| Optional | Any parameters not included in the secure array|
+
+**Notes:** 
+
+init would be an argument-directive: %%{init: { **insert argument here**}}%%
+
+The json object that is passed as {**argument** } must be valid, quoted json or it will be ignored.
+    **for example**:
+%%{init: {"theme": default, "logLevel": 1 }}%%
+
+Configurations that are passed through init cannot change the parameters in secure arrays of higher levels. In the event of a conflict, mermaid will give priority to secure arrays and parse the request, without changing the values of the parameters in conflict.
+
+When deployed within code, init is called before the graph/diagram description.
+**for example**:
+ %%{init: {"theme": "default", "logLevel": 1 }}%%
+  graph LR
+   a-->b
+   b-->c
+   c-->d
+   d-->e
+   e-->f
+   f-->g
+   g-->
+
+# Wrap
+| Parameter | Description |Type | Required | Values|
+| --- | --- | --- | --- | --- |
+| wrap | a callable text-wrap function| Directive| Optional | %%{wrap}%%|
+
+**Notes:**
+
+Wrap is a function that is currently only deployable for sequence diagrams.
+
+wrap respects manually added <br\> so if the user wants to break up their text, they have full control over those breaks by adding their own <br\> tags.
+
+It is a non-argument directive and can be executed thusly:
+
+%%{wrap}%%.
+
+**an example of text wrapping in a sequence diagram**:
+
+![Image showing wrapped text](https://github.com/NeilCuzon/mermaid/blob/develop/docs/img/wrapped%20text.png)
+
+
+# Resetting Configurations:
+There are two more functions in the mermaidAPI that can be called by site owners: **reset** and **globalReset**.
+
+**reset**: resets the configuration to whatever the last configuration was. This can be done to undo more recent changes to the last mermaidAPI.initialize({...}) configuration.
+
+**globalReset** will reset both the current configuration AND the site configuration back to the global defaults.
+
+**Notes**:  both reset and globalReset are only available to site owners, as such implementors would have to edit their configs with init.
+
+# Additional Utils to mermaid
+•	**memoize**: simple caching for computationally expensive functions. It reduces the rendering time for computationally intensive diagrams by about 90%.
+
+•	**assignWithDepth** - this is an improvement on previous functions with config.js and Object.assign. The purpose of this function is to provide a sane mechanism for merging objects, similar to object.assign, but with depth.
+
+Example of **assignWithDepth**:
+
+![Image showing assignWithDepth](https://github.com/NeilCuzon/mermaid/blob/develop/docs/img/assignWithDepth.png)
+
+
+Example of **object.Assign**:
+
+![Image showing object.assign without depth](https://github.com/NeilCuzon/mermaid/blob/develop/docs/img/object.assign%20without%20depth.png)
+
+•	**calculateTextDimensions, calculateTextWidth,** and **calculateTextHeight** - for measuring text dimensions, width and height.
+
+**Notes**:For more information on usage, parameters, and return info for these new functions take a look at the jsdocs for them in the utils package.

docs/README.md

@@ -16,6 +16,9 @@ Check out the list of [Integrations and Usages of Mermaid](./integrations.md)
 
 **Mermaid was nominated and won the JS Open Source Awards (2019) in the category "The most exciting use of technology"!!! Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project.**
 
+# New [Configuration Protocols in version 8.6.0](https://github.com/NeilCuzon/mermaid/edit/develop/docs/8.6.0_docs.md)
+
+
 ## New diagrams in 8.5
 
 With version 8.5 there are some bug fixes and enhancements, plus a new diagram type,  entity relationship diagrams.
@@ -161,16 +164,31 @@ Replace `<version>` with expected version number.
 
 Example: https://unpkg.com/mermaid@7.1.0/dist/
 
-### Node.js
+##Incorporating mermaid to a website
+to support mermaid on your website, all you have to do is add Mermaid’s JavaScript package 
 
 ```
-yarn add mermaid
+1.You will need to isntall node v10 or 12, which would have npm
+
+2. download yarn using npm
+
+2. yarn add mermaid
+
+3. yarn add --dev mermaid
 ```
 
-## Documentation
+## To install mermaid without a bundler, one can use the script tag like so:
+
+<script src="https://unpkg.com/mermaid/"></script>
+<script>mermaid.initialize({startOnLoad:true});</script>
+
+## it can then be followed by the diagram definitions as could be found in the examples in the documentation.
+
+# Documentation
 
 https://mermaidjs.github.io
 
+
 ## Sibling projects
 
 - [mermaid CLI](https://github.com/mermaidjs/mermaid.cli)

docs/Setup.md

@@ -11,7 +11,15 @@ It is is then up to the user of the API to make use of the svg, either insert it
 
 In addition to the render function, a number of behavioral configuration options are available.
 
-## Configuration
+# Configuration 
+
+
+
+# **Configuration methods in Mermaid version 8.6.0 have been updated, to learn more[[click here](https://github.com/NeilCuzon/mermaid/blob/develop/docs/8.6.0_docs.md)].**
+
+
+
+## **What follows are config instructions for older versions**
 
 These are the default options which can be overridden with the initialization call like so:
 **Example 1:**
@@ -49,9 +57,11 @@ A summary of all options and their defaults is found [here][2]. A description of
 theme , the CSS style sheet
 
 theme , the CSS style sheet
+
 | Parameter | Description |Type | Required | Values|
-\| --- \| --- \| --- \| --- \| --- \|
+| --- | --- | --- | --- | --- |
-| Theme |Built in Themes| String | Optional | Values include, default, forest, dark, neutral, null|
+| Theme |Built in Themes| String | Optional |  default, forest, dark, neutral, null|
+
 **Notes:**To disable any pre-defined mermaid theme, use "null".
 
 <pre>

src/mermaidAPI.spec.js

@@ -65,6 +65,28 @@ describe('when using mermaidAPI and ', function() {
       expect(mermaidAPI.getSiteConfig()).toEqual(siteConfig)
       expect(mermaidAPI.getConfig()).toEqual(siteConfig);
     });
+    it('should allow site config secure to global defaults', function() {
+      let config = {
+        logLevel: 0,
+        secure: ['foo']
+      };
+      mermaidAPI.initialize(config);
+      const siteConfig = mermaidAPI.getSiteConfig();
+      expect(mermaidAPI.getConfig().logLevel).toBe(0);
+      expect(mermaidAPI.getConfig().secure).toContain('foo');
+      config = {
+        logLevel: 3,
+        securityLevel: 'loose',
+        secure: ['foo', 'bar']
+      };
+      mermaidAPI.reinitialize(config);
+      expect(mermaidAPI.getConfig().secure).toEqual(mermaidAPI.getSiteConfig().secure);
+      expect(mermaidAPI.getConfig().securityLevel).toBe('strict');
+      expect(mermaidAPI.getConfig().secure).not.toContain('bar');
+      mermaidAPI.reset();
+      expect(mermaidAPI.getSiteConfig()).toEqual(siteConfig)
+      expect(mermaidAPI.getConfig()).toEqual(siteConfig);
+    });
     it('should prevent changes to site defaults (sneaky)', function() {
       let config = {
         logLevel: 0

src/utils.js

@@ -443,6 +443,13 @@ export const assignWithDepth = function(dst, src, config) {
   if (Array.isArray(src) && !Array.isArray(dst)) {
     src.forEach(s => assignWithDepth(dst, s, config));
     return dst;
+  } else if (Array.isArray(src) && Array.isArray(dst)) {
+    src.forEach(s => {
+      if (dst.indexOf(s) === -1) {
+        dst.push(s);
+      }
+    });
+    return dst;
   }
   if (typeof dst === 'undefined' || depth <= 0) {
     if (dst !== undefined && dst !== null && typeof dst === 'object' && typeof src === 'object') {