ES module version of compiler for use in browsers; dynamic import() docs; revised Stage 3 policy (#5177)

* Build both a legacy and modern browser compiler

* Dynamic import example and documentation

* Update the docs to use the modern browser compiler if the browser supports it

* Update policy regarding Stage 3 features

* This never made sense, and assigning a string to index 0 *of a string* throws in Module mode (and silently does nothing in Script mode) so remove this unneeded code that throws when compiling `fn for i from from iterable` in Module mode

* Have browser-based tests use the ES module version if supported

* Simplify building logic

* Update output

* For the ES module version of the browser compiler, don't automatically attach the runScripts event handler

* Consistent comments

* Fix comment

Author: GeoffreyBooth

Cakefile

@@ -66,15 +66,18 @@ build = (callback) ->
   buildParser()
   buildExceptParser callback
 
-transpile = (code) ->
+transpile = (code, options = {}) ->
+  options.minify =    process.env.MINIFY isnt 'false'
+  options.transform = process.env.TRANSFORM isnt 'false'
   babel = require '@babel/core'
   presets = []
   # Exclude the `modules` plugin in order to not break the `}(this));`
   # at the end of the `build:browser` code block.
-  presets.push ['@babel/env', {modules: no}] unless process.env.TRANSFORM is 'false'
-  presets.push ['minify', {mangle: no, evaluate: no, removeUndefined: no}] unless process.env.MINIFY is 'false'
+  presets.push ['@babel/env', {modules: no}] if options.transform
+  presets.push ['minify', {mangle: no, evaluate: no, removeUndefined: no}] if options.minify
   babelOptions =
-    compact: process.env.MINIFY isnt 'false'
+    compact: not options.minify
+    comments: not options.minify
     presets: presets
     sourceType: 'script'
   { code } = babel.transform code, babelOptions unless presets.length is 0
@@ -140,13 +143,18 @@ task 'build:browser', 'merge the built scripts into a single file for use in a b
         return module.exports;
       })();
     """
+  # From here, we generate two outputs: a legacy script output for all browsers
+  # and a module output for browsers that support `<script type="module">`.
   code = """
+    var CoffeeScript = function() {
+      function require(path){ return require[path]; }
+      #{code}
+      return require['./browser'];
+    }();
+  """
+  scriptCode = transpile """
     (function(root) {
-      var CoffeeScript = function() {
-        function require(path){ return require[path]; }
-        #{code}
-        return require['./browser'];
-      }();
+      #{code}
 
       if (typeof define === 'function' && define.amd) {
         define(function() { return CoffeeScript; });
@@ -155,10 +163,20 @@ task 'build:browser', 'merge the built scripts into a single file for use in a b
       }
     }(this));
   """
-  code = transpile code
-  outputFolder = "docs/v#{majorVersion}/browser-compiler"
-  fs.mkdirSync outputFolder unless fs.existsSync outputFolder
-  fs.writeFileSync "#{outputFolder}/coffeescript.js", header + '\n' + code
+  moduleCode = """
+    #{code}
+
+    export default CoffeeScript;
+    const { VERSION, compile, eval: evaluate, load, run, runScripts } = CoffeeScript;
+    export { VERSION, compile, evaluate as eval, load, run, runScripts };
+  """
+  for folder in ['browser-compiler', 'browser-compiler-modern']
+    outputFolder = "docs/v#{majorVersion}/#{folder}"
+    fs.mkdirSync outputFolder unless fs.existsSync outputFolder
+    fs.writeFileSync "#{outputFolder}/coffeescript.js", """
+      #{header}
+      #{if folder is 'browser-compiler' then scriptCode else moduleCode}
+    """
 
 task 'build:browser:full', 'merge the built scripts into a single file for use in a browser, and test it', ->
   invoke 'build:browser'

docs/browser-compiler-modern

@@ -0,0 +1 @@
+v2/browser-compiler-modern

docs/v2/annotated-source/browser.html

@@ -262,7 +262,7 @@ <h1>browser.coffee</h1>
 
             </div>
 
-            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">runScripts</span> = -&gt;</span>
+            <div class="content"><div class='highlight'><pre>CoffeeScript.runScripts = <span class="hljs-function">-&gt;</span>
   scripts = <span class="hljs-built_in">window</span>.<span class="hljs-built_in">document</span>.getElementsByTagName <span class="hljs-string">'script'</span>
   coffeetypes = [<span class="hljs-string">'text/coffeescript'</span>, <span class="hljs-string">'text/literate-coffeescript'</span>]
   coffees = (s <span class="hljs-keyword">for</span> s <span class="hljs-keyword">in</span> scripts <span class="hljs-keyword">when</span> s.type <span class="hljs-keyword">in</span> coffeetypes)
@@ -321,14 +321,19 @@ <h1>browser.coffee</h1>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
-              <p>Listen for window load, both in decent browsers and in IE.</p>
+              <p>Listen for window load, both in decent browsers and in IE.
+Only attach this event handler on startup for the
+non-ES module version of the browser compiler, to preserve
+backward compatibility while letting the ES module version
+be importable without side effects.</p>
 
             </div>
 
-            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-built_in">window</span>.addEventListener
-  <span class="hljs-built_in">window</span>.addEventListener <span class="hljs-string">'DOMContentLoaded'</span>, runScripts, <span class="hljs-literal">no</span>
-<span class="hljs-keyword">else</span>
-  <span class="hljs-built_in">window</span>.attachEvent <span class="hljs-string">'onload'</span>, runScripts</pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-keyword">this</span> <span class="hljs-keyword">is</span> <span class="hljs-built_in">window</span>
+  <span class="hljs-keyword">if</span> <span class="hljs-built_in">window</span>.addEventListener
+    <span class="hljs-built_in">window</span>.addEventListener <span class="hljs-string">'DOMContentLoaded'</span>, CoffeeScript.runScripts, <span class="hljs-literal">no</span>
+  <span class="hljs-keyword">else</span>
+    <span class="hljs-built_in">window</span>.attachEvent <span class="hljs-string">'onload'</span>, CoffeeScript.runScripts</pre></div></div>
 
         </li>