refactoring of the less infrastructure

customize.dist/src/less2/readme.md

@@ -1,19 +1,45 @@
 # CryptPad Styling
 
-How it works:
-* In this example, we use the index page, for each page we will have a corresponding class name and a corresponding less file.
-* The index page has a main div containing everything `<div id="cp-main" class="cp-page-index">`
-* There is a corresponding less file called `less2/pages/page-index.less`
-* Finally there is a corresponding line in main.less which imports that less file: `div#main.cp-page-index { @import "./pages/page-index.less"; }`
-  * cp-page-index class means:
-    * cp -> cryptpad
-    * page -> this is a style for accessing a page's less file
-    * index -> the name of the page and of the less file (page-index.less)
-* And everything which is standardized across pages is included from `page-index.less` as variables and mixins.
+## Linking Less/CSS
+
+In order to keep the amount of CSS generated under control, we use "linking", via the LessLoader.
+This makes use of CSS variables in order to work. The old solution was to put all of the content into less mixins
+which would be used inside of the scope where they should be, but this caused a state explosion because each app needed
+essentially the same mixins. However, these mixins had arguments such as colors which were different per-app.
+
+The new solution is to set CSS variables for the arguments (like color) and then put the bulk of the less at the global
+scope. When you include a dependency, the following happens:
+
+1. You `@include (reference) './include/dependency.less`. The (reference) argument which means it will not emit CSS,
+this is important because otherwise all of the dependencies of your app's less file would end up bundled with it, the
+state explosion problem.
+2. You invoke `.dependency_main(@arg1 @arg2)` inside of the scope you want it in, the name `dependency_main` is a
+convention, all less variables, mixins, or CSS variables which a file creates should be prefixed with the name of the
+file (in this case, "dependency").
+3. The mixin `.dependency_main` does a couple of things:
+  * First, it sets a CSS variable called `--LessLoader_require`, this is a special variable which the browser does not
+  use, the only objective of this variable is to inform LessLoader that another file is needed. To do this, there is a
+  helper function (also specified in LessLoader.js) called `LessLoader_currentFile()`. The syntax is:
+  `--LessLoader_require: LessLoader_currentFile();` and in the CSS, this outputs something like:
+  `--LessLoader_require: "/customize/src/less2/include/dependency.less?ver=2.4.0-1531572157592";`
+  * Secondly, it sets browser variables for it's arguments, making sure to avoid namespace collisions:
+  `--dependency-arg1: @arg1;`, `--dependency-arg2: @arg2;`. Sometimes a less transformation needs to be done on a
+  variable, unfortunately in this case the transformation must be done here and the transformed variable must be output.
+  `--dependency-arg1-l10: lighten(@arg1, 10%);`.
+4. After less processing is completed, the LessLoader caches the result of parsing, then scans the it for instances of
+`--LessLoader_require` variable and then processes them, but it does this separately. So even if dependency.less is
+required many times, it will only be processed by the less interpreter once.
+
+## Other convensions
 
-Rules:
 * All of our new classes and ids should start with `cp-`.
-* You may make as many files as you need, for different purposes, but they can only contain mixins and variables.
+* The document body has a class on it depending on the app/page, app classes begin with `cp-app-` and page classes begin
+with `cp-page-`.
+* Custom classes ought to begin with `cp-` and the name of the file where the rules are written for them (see help.less as
+an example of doing the right thing).
+* Since the include files generate CSS and the app cannot control the scope which it's run at, be considerate avoid
+making an include file which changes something significant (like making a rule for `li`). help.less is an excellent example
+of doing this well, infopages.less is the worst example (fortunately it doesn't get included in any of the apps).
 * All mixins and variables must be prefixed with the name of the file where they're defined and and underscore.
   * e.g. `@colortheme_toolbar-poll-bg: #006304;` defined in `colortheme.less`
 * All mixin / variable files go in an `/include/` directory.