[CS2] JSX documentation, Try CoffeeScript improvements (#4583)

* Update browser compiler

* Argument parsing tests require CommonJS environment

* JSX section in the docs

* Breaking change note for < and > operators

* Fix JSX example

* Try CoffeeScript improvements: set the hash automatically, remove ‘link’ button, automatically save code in localStorage

* Fix the code editors’ handling of tab-indented code

* Fix JSX example to work with React

* Compiled, not rendered

Author: GeoffreyBooth

docs/v2/browser-compiler/coffeescript.js

@@ -0,0 +1,9 @@
+renderStarRating = ({ rating, maxStars }) ->
+  <aside title={"Rating: #{rating} of #{maxStars} stars"}>
+    {for wholeStar in [0...Math.floor(rating)]
+      <Star className="wholeStar" key={wholeStar} />}
+    {if rating % 1 isnt 0
+      <Star className="halfStar" />}
+    {for emptyStar in [Math.ceil(rating)...maxStars]
+      <Star className="emptyStar" key={emptyStar} />}
+  </aside>

docs/v2/index.html

@@ -0,0 +1,3 @@
+### JSX and the `<` and `>` Operators
+
+With the addition of [JSX](#jsx), the `<` and `>` characters serve as both the “less than” and “greater than” operators and as the delimiters for XML tags, like `<div>`. For best results, in general you should always wrap the operators in spaces to distinguish them from XML tags: `i < len`, not `i<len`. The compiler tries to be forgiving when it can be sure what you intend, but always putting spaces around the “less than” and “greater than” operators will remove ambiguity.

documentation/examples/jsx.coffee

@@ -6,7 +6,7 @@ The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produ
 
 Support for ES2015+ syntax is important to ensure compatibility with frameworks that assume ES2015. Now that CoffeeScript compiles classes to the ES `class` keyword, it’s possible to `extend` an ES class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like [function parameter default values](#breaking-changes-default-values) should behave the same in CoffeeScript as in JavaScript.
 
-Many ES2015+ features have been backported to CoffeeScript 1.11 and 1.12, including [modules](#modules), [`for…of`](#generator-iteration), and [tagged template literals](#tagged-template-literals). One major new feature unique to CoffeeScript 2 is support for ES2017’s [async functions](#async-functions). More details are in the [changelog](#changelog).
+Many ES2015+ features have been backported to CoffeeScript 1.11 and 1.12, including [modules](#modules), [`for…of`](#generator-iteration), and [tagged template literals](#tagged-template-literals). Major new features unique to CoffeeScript 2 are support for ES2017’s [async functions](#async-functions) and for [JSX](#jsx). More details are in the [changelog](#changelog).
 
 There are very few [breaking changes from CoffeeScript 1.x to 2](#breaking-changes); we hope the upgrade process is smooth for most projects.
 

documentation/images/link.svg

@@ -0,0 +1,13 @@
+## JSX
+
+[JSX](https://facebook.github.io/react/docs/introducing-jsx.html) is JavaScript containing interspersed XML elements. While conceived for [React](https://facebook.github.io/react/), it is not specific to any particular library or framework.
+
+CoffeeScript supports interspersed XML elements, without the need for separate plugins or special settings. The XML elements will be compiled as such, outputting JSX that could be parsed like any normal JSX file, for example by [Babel with the React JSX transform](https://babeljs.io/docs/plugins/transform-react-jsx/). CoffeeScript does _not_ output `React.createElement` calls or any code specific to React or any other framework. It is up to you to attach another step in your build chain to convert this JSX to whatever function calls you wish the XML elements to compile to.
+
+Just like in JSX and HTML, denote XML tags using `<` and `>`. You can interpolate CoffeeScript code inside a tag using `{` and `}`. To avoid compiler errors, when using `<` and `>` to mean “less than” or “greater than,” you should wrap the operators in spaces to distinguish them from XML tags. So `i < len`, not `i<len`. The compiler tries to be forgiving when it can be sure what you intend, but always putting spaces around the “less than” and “greater than” operators will remove ambiguity.
+
+```
+codeFor('jsx')
+```
+
+Older plugins or forks of CoffeeScript supported JSX syntax and referred to it as CSX or CJSX. They also often used a `.cjsx` file extension, but this is no longer necessary; regalar `.coffee` will do.

documentation/sections/breaking_changes_jsx_and_the_less_than_and_greater_than_operators.md

@@ -40,14 +40,14 @@ Once installed, you should have access to the `coffee` command, which can execut
 
 CoffeeScript 2 outputs the latest ES2015+ syntax. If you’re looking for a single tool that takes CoffeeScript input and generates JavaScript output that runs in any JavaScript runtime, assuming you opt out of certain newer features, stick to [CoffeeScript 1.x](/v1/). CoffeeScript 2 [breaks compatibility](#breaking-changes) with certain CoffeeScript 1.x features in order to conform with the ES2015+ specifications, and generate more idiomatic output (a CoffeeScript `=>` becomes an ES `=>`; a CoffeeScript `class` becomes an ES `class`; and so on).
 
-Since the CoffeeScript 2 compiler outputs ES2015+ syntax, it is your responsibility to either ensure that your target JavaScript runtime(s) support all these features, or that you pass the output through another transpiler like [Babel](http://babeljs.io/), [Rollup](https://github.com/rollup/rollup) or [Traceur Compiler](https://github.com/google/traceur-compiler). In general, [CoffeeScript 2’s output is supported as is by Node.js 7.6+](http://node.green/), except for modules which require transpilation.
+Since the CoffeeScript 2 compiler outputs ES2015+ syntax, it is your responsibility to either ensure that your target JavaScript runtime(s) support all these features, or that you pass the output through another transpiler like [Babel](http://babeljs.io/), [Rollup](https://github.com/rollup/rollup) or [Traceur Compiler](https://github.com/google/traceur-compiler). In general, [CoffeeScript 2’s output is supported as is by Node.js 7.6+](http://node.green/), except for modules and JSX which require transpilation.
 
 There are many great task runners for setting up JavaScript build chains, such as [Gulp](http://gulpjs.com/), [Webpack](https://webpack.github.io/), [Grunt](https://gruntjs.com/) and [Broccoli](http://broccolijs.com/). If you’re looking for a very minimal solution to get started, you can use [babel-preset-env](https://babeljs.io/docs/plugins/preset-env/) and the command line:
 
 ```bash
 npm install --global coffeescript@next
 npm install --save-dev coffeescript@next babel-cli babel-preset-env
-coffee -p *.coffee | babel --presets env > app.js
+coffee --print *.coffee | babel --presets env > app.js
 ```
 
 ### Node.js

documentation/sections/coffeescript_2.md

@@ -106,6 +106,9 @@
         <section id="embedded">
           <%= htmlFor('embedded') %>
         </section>
+        <section id="jsx">
+          <%= htmlFor('jsx') %>
+        </section>
       </section>
       <section id="literate">
         <%= htmlFor('literate') %>
@@ -166,6 +169,9 @@
         <section id="breaking-changes-super-extends">
           <%= htmlFor('breaking_changes_super_extends') %>
         </section>
+        <section id="breaking-changes-jsx-and-the-less-than-and-greater-than-operators">
+          <%= htmlFor('breaking_changes_jsx_and_the_less_than_and_greater_than_operators') %>
+        </section>
         <section id="breaking-changes-literate-coffeescript">
           <%= htmlFor('breaking_changes_literate_coffeescript') %>
         </section>

documentation/sections/jsx.md

@@ -13,17 +13,6 @@ $(document).ready ->
         window.location = event.target.href
       , 260 # Wait for the sidebar to slide away before navigating
 
-
-  # Try CoffeeScript
-  toggleTry = ->
-    $('#try, #try-link').toggleClass 'active'
-  closeTry = ->
-    $('#try, #try-link').removeClass 'active'
-
-  $('[data-toggle="try"]').click toggleTry
-  $('[data-close="try"]').click closeTry
-
-
   # Initialize Scrollspy for sidebar navigation; http://v4-alpha.getbootstrap.com/components/scrollspy/
   # See also http://www.codingeverything.com/2014/02/BootstrapDocsSideBar.html and http://jsfiddle.net/KyleMit/v6zhz/
   $('body').scrollspy
@@ -60,20 +49,46 @@ $(document).ready ->
       viewportMargin: Infinity
 
     # Whenever the user edits the CoffeeScript side of a code example, update the JavaScript output
+    # If the editor is Try CoffeeScript, also update the hash and save this code in localStorage
     if mode is 'coffeescript'
       pending = null
       editor.on 'change', (instance, change) ->
         clearTimeout pending
         pending = setTimeout ->
           lastCompilationStartTime = Date.now()
           try
-            output = CoffeeScript.compile editor.getValue(), bare: yes
+            coffee = editor.getValue()
+            if index is 0 and $('#try').hasClass('active') # If this is the editor in Try CoffeeScript and it’s still visible
+              # Update the hash with the current code
+              link = "try:#{encodeURIComponent coffee}"
+              window.history.pushState {}, 'CoffeeScript', "#{location.href.split('#')[0]}##{link}"
+              # Save this to the user’s localStorage
+              try
+                if window.localStorage?
+                  window.localStorage.setItem 'tryCoffeeScriptCode', coffee
+              catch exception
+            output = CoffeeScript.compile coffee, bare: yes
             lastCompilationElapsedTime = Math.max(200, Date.now() - lastCompilationStartTime)
           catch exception
             output = "#{exception}"
           editors[index + 1].setValue output
         , lastCompilationElapsedTime
 
+      # Fix the code editors’ handling of tab-indented code
+      editor.addKeyMap
+        'Tab': (cm) ->
+          if cm.somethingSelected()
+            cm.indentSelection 'add'
+          else if /^\t/m.test cm.getValue()
+            # If any lines start with a tab, treat this as tab-indented code
+            cm.execCommand 'insertTab'
+          else
+            cm.execCommand 'insertSoftTab'
+        'Shift-Tab': (cm) ->
+          cm.indentSelection 'subtract'
+        'Enter': (cm) ->
+          cm.options.indentWithTabs = /^\t/m.test cm.getValue()
+          cm.execCommand 'newlineAndIndent'
 
   # Handle the code example buttons
   $('[data-action="run-code-example"]').click ->
@@ -83,17 +98,27 @@ $(document).ready ->
     js = "#{js}\nalert(#{unescape run});" unless run is yes
     eval js
 
-  $('[data-action="link"]').click ->
-    index = $("##{$(@).data('example')}-coffee").data 'index'
-    coffee = editors[index].getValue()
-    link = "try:#{encodeURIComponent coffee}"
-    window.history.pushState {}, 'CoffeeScript', "#{location.href.split('#')[0]}##{link}"
+
+  # Try CoffeeScript
+  toggleTry = (checkLocalStorage = no) ->
+    if checkLocalStorage and window.localStorage?
+      try
+        coffee = window.localStorage.getItem 'tryCoffeeScriptCode'
+        if coffee?
+          editors[0].setValue coffee
+      catch exception
+    $('#try, #try-link').toggleClass 'active'
+  closeTry = ->
+    $('#try, #try-link').removeClass 'active'
+
+  $('[data-toggle="try"]').click toggleTry
+  $('[data-close="try"]').click closeTry
 
 
   # Configure the initial state
   if window.location.hash?
     if window.location.hash is '#try'
-      toggleTry()
+      toggleTry yes
     else if window.location.hash.indexOf('#try') is 0
       editors[0].setValue decodeURIComponent window.location.hash[5..]
       toggleTry()