Add Complex DOM READMEs (#301)

Add READMEs for the big-dom-generator and each complex DOM variation.

---------

Co-authored-by: Issack John <[email protected]>
Co-authored-by: Sulekha Kulkarni <[email protected]>

resources/todomvc/architecture-examples/angular-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: Angular Complex DOM
+
+## Description
+
+This application embeds the Angular implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [Angular README.md](../angular/README.md) for more information on the Angular TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone Angular TodoMVC need to be built before building the Angular Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../angular && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:8080
+```

resources/todomvc/architecture-examples/backbone-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: Backbone Complex DOM
+
+## Description
+
+This application embeds the Backbone implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [Backbone README.md](../backbone/README.md) for more information on the Backbone TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone Backbone TodoMVC need to be built before building the Backbone Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../backbone && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/jquery-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: jQuery Complex DOM
+
+## Description
+
+This application embeds the jQuery implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [jQuery README.md](../jquery/README.md) for more information on the jQuery TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone jQuery TodoMVC need to be built before building the jQuery Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../jquery && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/preact-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: Preact Complex DOM
+
+## Description
+
+This application embeds the Preact implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [Preact README.md](../preact/README.md) for more information on the Preact TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone Preact TodoMVC need to be built before building the Preact Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../preact && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/react-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: React Complex DOM
+
+## Description
+
+This application embeds the React implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [React README.md](../react/README.md) for more information on the React TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone React TodoMVC need to be built before building the React Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../react && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/react-redux-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: React-Redux Complex DOM
+
+## Description
+
+This application embeds the React-Redux implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [React-Redux README.md](../react-redux/README.md) for more information on the React-Redux TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone React-Redux TodoMVC need to be built before building the React-Redux Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../react-redux && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/svelte-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: Svelte Complex DOM
+
+## Description
+
+This application embeds the Svelte implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [Svelte README.md](../svelte/README.md) for more information on the Svelte TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone Svelte TodoMVC need to be built before building the Svelte Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../svelte && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/architecture-examples/vue-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: Vue Complex DOM
+
+## Description
+
+This application embeds the Vue implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [Vue README.md](../vue/README.md) for more information on the Vue TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone Vue TodoMVC need to be built before building the Vue Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../vue && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7002
+```

resources/todomvc/big-dom-generator/README.md

@@ -1,49 +1,80 @@
-# TodoMVC embedded in a complex big static DOM
+# TodoMVC embedded in a complex static UI shell
 
-## The benchmark
+The complex DOM workloads embed the different TodoMVC implementations in a static UI shell that mimics a complex web page or application. This UI shell is made up of a large DOM and complex CSS. The purpose is to capture the performance impact on executing seemingly isolated actions (e.g. adding/deleting todo items) in the context of a complex website.
 
-This workload embeds the todoMVC benchmark in an html page with the following characteristics.
+CSS complexity is represented by rules composed by complex selectors and combinators. These CSS rules are further split into **matching** and **non-matching** rules. The matching selectors fully match an element added by the TodoMVC benchmark, but not elements in the UI shell. The non-matching selectors partially match elements added by the TodoMVC benchmark (at least the right most selectors do), but entirely match the elements in the UI shell. This ensures that the performance impact of both the matching and non-matching CSS rules is captured within the measured time.
 
--   The page is a big static DOM with around 4000 elements.
--   The page is styled using the @spectrum-css adobe library, which relies on css variables for uniform styling.
--   The @spectrum-css rules of the page are post processed using postcss and purgecss.
--   The page includes other 400 complex color css rules using different kinds of css selectors and combinators.
--   200 of the above rules will fully match elements added by the todoMVC benchmark, but not elements in the UI. E.g. `.toggle-all-container ~ ul > .li-6 > .view-6.targeted`.
--   200 of the above rules will partially match elements added by the todoMVC benchmark (the right most selector will match). E.g. `.header.just-span .header ~ .main .view-31`.
--   We added new classes `li-{index}` and `view-{index}` to the todoMVC benchmark list items to make it easier to match the elements. We also added a class `targeted` to them to avoid affecting other elements with the generated CSS.
+## Complex DOM workload description
+
+The static UI shell has the following characteristics:
+
+-   The DOM has around 6000 elements.
+-   The static UI shell is styled using the @spectrum-css Adobe library, which relies on css variables for uniform styling.
+-   The @spectrum-css rules of the static UI shell are post processed using postcss and purgecss.
+-   Additional styling is applied through ~50 non-matching CSS rules.
+    -   E.g. `.backlog-group li > div > :checked ~ label`.
+
+All TodoMVC implementations now have a `show-priority` class name in the `<ul>` element and a `data-priority` attribute in the `li` elements. These are used by the matching CSS rules.
+
+-   There are ~14 added matching CSS rules.
+    -   E.g. `.todo-area .show-priority li[data-priority="2"].completed`.
+    -   In the case of Javascript-web-components and lit TodoMVC, the `show-priority` class is added to the `<todo-list>` custom element and the `data-priority` attribute to the `<todo-item>` custom element.
+
+### Web Components based workloads
+
+The Shadow DOM isolation prevents global CSS rules to be applied to its children, hence, having matching or non-matching rules does not have the same impact as it has on the other architectures. Instead, the Complex DOM Web components and Lit workloads stress the use of CSS variables inherited though the shadow DOM boundary:
+
+-   Some default variables are defined in the `root` element.
+-   The `add-todo-list-extra-css.js` file defines a constructable stylesheet that will declare the priority colors only if the `show-priority` class is present in the host.
+-   The `add-todo-item-extra-css.js` file defines the rule to style the todo items based on their priority level.
+
+## Static UI shell
 
 <p align = "center">
-<img src="complex-dom-workload.png" alt="workload" width="800"/>
+<img src="complex-dom-workload.jpeg" alt="workload" width="800"/>
 </p>
 
+## The generator
+
+The big DOM is produced by the generator in a nodejs script that uses `renderToStaticMarkup` to generate the static html. It uses a random seedable library to synthesize a folder-like structure embedded in the sidebar. The generator takes the following parameters:
+
+-   `MAX_DEPTH` - Maximum depth of the generated DOM.
+-   `TARGET_SIZE` - Number of elements in the generated DOM.
+-   `CHILD_PROB` - Probability of each element of the sidebar to have children.
+-   `MAX_BREADTH` - Maximum number of children of each element of the sidebar.
+
 ## Structure of the folder
 
 -   _src_ Code to generate the big static DOM
 -   _dist_ - Output folder for the big static DOM generator.
--   _angular_ - Output folder for the angular generated.css.
+-   utils - Folder for the functions to generate the complex DOM versions of each TodoMVC implementation as well as add additional css.
 
-## How to run
+## Requirements
 
-`npm run build` - Generates the static html and corresponding css.
+The only requirement is an installation of Node, to be able to install dependencies and run scripts to serve a local server.
 
-`npm run serve` - Serves the dist folder in port 7002.
+* Node (min version: 18.13.0)
+* NPM (min version: 8.19.3)
 
-## The generator
+## How to run
 
-The generator is a nodejs script that uses `renderToStaticMarkup` to generate the static html.
+`npm install` - Installs the dependencies.
 
-### Dom Generator
+`npm run build` - Generates the static html and corresponding css.
 
--   Uses a random seedable library with a default seed for all its random operations.
--   Takes `MAX_DEPTH`, `TARGET_SIZE` and to randomly generate the big folder-like structure embedded in the sidebar.
--   To generate the sidebar, each node decides if it will have children based on the `CHILD_PROB` value. Then randomly chooses a number of children between 1 and `MAX_BREADTH`.
+`npm run serve` - Serves the dist folder in port 7002.
 
 ## Install using local path
 
-In the project where we want to use the big-dom-generator package, for example, `Speedometer/resources/todomvc/architecture-examples/react-complex` run:
+In the project where you want to use the big-dom-generator package, e.g. `Speedometer/resources/todomvc/architecture-examples/react-complex` run:
 
 ```bash
-$ npm install ../../big-dom-generator --save-dev
+npm install ../../big-dom-generator --save-dev
 ```
 
 The flag `--save-dev` will create an entry in the package.json if one doesn't already exist. Now you can use the package in the project as if it was installed from npm.
+
+## Developer notes
+
+-   The non-matching selectors for the static UI shell were written so that elements within the todoMVC matched more than the right-most selector, for example, the `label` element in the todo items matches the selector `backlog-group li > div > :checked ~ label` up to the `li` simple selector. If any changes are made to the DOM structure within the todoMVC, these selectors will need to be reevaluated and potentially rewritten.
+-   Angular uses custom elements, so the todoMVC elements might match a smaller part of a selector as compared to other architectures.

resources/todomvc/vanilla-examples/javascript-es5-complex/README.md

@@ -0,0 +1,29 @@
+# Speedometer 3.0: TodoMVC: JavaScript Es5 Complex DOM
+
+## Description
+
+This application embeds the JavaScript Es5 implementation of the TodoMVC application in a static UI shell that mimics a complex web page.
+
+Please refer to the [JavaScript Es5 README.md](../javascript-es5/README.md) for more information on the JavaScript Es5 TodoMVC implementation.
+
+Please refer to the [big-dom-generator README.md](../../big-dom-generator/README.md) for more information on the UI shell.
+
+## Build steps
+
+Big-dom-generator and standalone JavaScript Es5 TodoMVC need to be built before building the JavaScript Es5 Complex DOM TodoMVC.
+
+```
+terminal
+1. pushd ../../big-dom-generator && npm install && npm run build && popd
+2. pushd ../javascript-es5 && npm install && npm run build && popd
+3. npm run build
+```
+
+## Local preview
+
+```
+terminal:
+1. npm run serve
+browser:
+1. http://localhost:7001
+```