Address reviews so far.

Author: sjrd

doc/tutorial/getting-started/index.md

@@ -5,18 +5,20 @@ title: Getting Started with Scala.js, Vite, Laminar and ScalablyTyped
 
 This series of tutorials teaches you how to use Scala.js together with modern development tools.
 
+1. [Scala.js and Vite](./scalajs-vite.html):
+  * Set up a hello world project ready for live reloading in the browser.
+  * Generate minimized production assets.
+2. [Laminar and ScalablyTyped](./laminar-scalablytyped.html):
+  * Build UIs with Laminar using Function Reactive Programming (FRP), a hybrid model between imperative and functional programming particularly well suited for UI development in Scala.
+  * Integrate JavaScript libraries using ScalablyTyped.
+
 If you have time, reading and applying them in order will give you more in-depth knowledge about the development environment.
 
 If you are in a hurry, you can skip the ones you are not interested in.
-Each tutorial starts with a link to repo that you can clone to get off the ground.
+Each tutorial starts with a link to a repo that you can clone to get off the ground.
 
 In any case, make sure that you have the Prerequisites listed below covered.
 
-## Tutorials
-
-1. [Scala.js and Vite](./scalajs-vite.html): set up a hello world project ready for live reloading in the browser.
-2. [Laminar and ScalablyTyped](./laminar-scalablytyped.html): build UIs with Laminar, and integrate JavaScript libraries with ScalablyTyped.
-
 ## Prerequisites
 
 In any case, make sure that you have the following tools installed first:

doc/tutorial/getting-started/laminar-scalablytyped.md

@@ -12,10 +12,15 @@ If you prefer to navigate the end result for this tutorial directly, checkout [t
 
 ## Prerequisites
 
-Make sure to install [the prerequisites](./index.html) before continuing further.
+Make sure to install [the prerequisites](./index.html#prerequisites) before continuing further.
 
 ## Introducing Laminar
 
+[Laminar](https://laminar.dev/) is a Scala.js library to build UIs using Functional Reactive Programming (FRP).
+FRP is a hybrid model between imperative and functional programming.
+It is particularly well suited to developing UIs in Scala, as we can reason about relationships between immutable values while dealing with the changing nature of the UI.
+We will elaborate on this point later.
+
 To start off, we add a dependency on Laminar in our `build.sbt`:
 
 {% highlight diff %}
@@ -35,7 +40,7 @@ sbt:livechart> ~fastLinkJS
 [...]
 {% endhighlight %}
 
-If it was already running, stop it and `reload` it for changes in `build.sbt` to take effect.
+If sbt was already running, run `reload` for the changes in `build.sbt` to take effect, then start the incremental compiler with `~fastLinkJS`.
 
 Additionally, start Vite's development server if it wasn't already running:
 
@@ -44,7 +49,7 @@ $ npm run dev
 [...]
 {% endhighlight %}
 
-We can now change the contents of `src/main/scala/livechart/LiveChart.scala` to use Laminar instead of raw DOM APIs.
+We can now change the contents of `src/main/scala/livechart/LiveChart.scala` to use Laminar instead of vanilla DOM APIs.
 
 At the top, we use the following import:
 
@@ -142,6 +147,11 @@ We then use it in two *bindings*:
 We do not need to explicitly set the `innerHTML` attribute of the button.
 That is taken care of by the `<--` binding.
 
+Unlike frameworks based on a virtual DOM, Laminar bindings directly target the DOM element to update.
+With a virtual DOM, when the value of `counter` changes, we would build an entirely new VDOM representation for the button (and perhaps its parents), and the framework would later diff it and identify which DOM `HTMLButtonElement` to update.
+In Laminar, however, the `<--` binding remembers the precise instance of `HTMLButtonElement` to update, and directly modifies its text.
+This is more efficient than going through the VDOM indirection.
+
 Beside `:=`, the two binding arrows `<--` and `-->` are the only symbolic operators that Laminar defines.
 `:=` is a static binding.
 It can be seen as a `<--` with a time-immutable value on the right.

doc/tutorial/getting-started/scalajs-vite.md

@@ -4,7 +4,8 @@ title: Getting Started with Scala.js and Vite
 ---
 
 In this first tutorial, we learn how to get started with Scala.js and [Vite](https://vitejs.dev/).
-We use Vite to provide live-reloading of the Scala.js application in the browser.
+We use Vite to provide live-reloading of the Scala.js application in the browser for development.
+We also configure it to build a minimal bundle for production.
 
 Going through this tutorial will make sure you understand the basic building blocks.
 If you prefer to skip this step and directly write Scala.js code, you may jump to [Getting Started with Scala.js and Laminar](./laminar-scalablytyped.html).
@@ -13,25 +14,25 @@ If you prefer to navigate the end result for this tutorial directly, checkout [t
 
 ## Prerequisites
 
-Make sure to install [the prerequisites](./index.html) before continuing further.
+Make sure to install [the prerequisites](./index.html#prerequisites) before continuing further.
 
 ## Vite template
 
 We bootstrap our setup using the vanilla Vite template.
 Navigate to a directory where you store projects, and run the command
 
 {% highlight shell %}
-$ npm create vite@latest
+$ npm create vite@3.2.1
 {% endhighlight %}
 
 Choose a project name (we choose `livechart`).
 Select the "Vanilla" framework and the "JavaScript" variant.
 Our output gives:
 
 {% highlight shell %}
-$ npm create vite@latest
+$ npm create vite@3.2.1
 Need to install the following packages:
-  create-vite@latest
+  create-vite@3.2.1
 Ok to proceed? (y)
 ✔ Project name: … livechart
 ✔ Select a framework: › Vanilla
@@ -156,9 +157,9 @@ import scala.scalajs.js.annotation.*
 
 import org.scalajs.dom
 
-// import javaScriptLogo from "/javascript.svg"
+// import javascriptLogo from "/javascript.svg"
 @js.native @JSImport("/javascript.svg", JSImport.Default)
-val javaScriptLogo: String = js.native
+val javascriptLogo: String = js.native
 
 @main
 def LiveChart(): Unit =
@@ -168,7 +169,7 @@ def LiveChart(): Unit =
         <img src="/vite.svg" class="logo" alt="Vite logo" />
       </a>
       <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript" target="_blank">
-        <img src="$javaScriptLogo" class="logo vanilla" alt="JavaScript logo" />
+        <img src="$javascriptLogo" class="logo vanilla" alt="JavaScript logo" />
       </a>
       <h1>Hello Scala.js!</h1>
       <div class="card">
@@ -198,6 +199,39 @@ end setupCounter
 Note that the above is not idiomatic Scala, but rather a direct translation of the Vite template code into Scala.js.
 We will see in the next tutorial how to use Laminar to write it more idiomatically.
 
+For the most part, the Scala.js version uses straightforward Scala syntax corresponding to the original JavaScript code.
+The definition of `javascriptLogo` deserves some explanation.
+
+We translated it from the JavaScript import
+
+{% highlight javascript %}
+import javascriptLogo from "/javascript.svg"
+{% endhighlight %}
+
+which is actually a shorthand for
+
+{% highlight javascript %}
+import { default as javascriptLogo } from "/javascript.svg"
+{% endhighlight %}
+
+Many bundlers, Vite included, treat `import`s with asset files such as `.svg` as pseudo-modules whose `default` import is the *file path* to the corresponding asset in the processed bundle.
+Further down, we use it as the value for the `src` attribute an `<img>` tag.
+Read more about this mechanism [in the Vite documentation on static asset handling](https://vitejs.dev/guide/assets.html).
+
+The translation in Scala.js reads as
+
+{% highlight scala %}
+@js.native @JSImport("/javascript.svg", JSImport.Default)
+val javascriptLogo: String = js.native
+{% endhighlight %}
+
+The `@js.native` annotation tells Scala.js that `javascriptLogo` is provided externally by JavaScript.
+The `@JSImport("/javascript.svg", JSImport.Default)` is the translation of the `default` import from the `/javascript.svg` pseudo-module.
+Since it represents a file path, we declare `javascriptLogo` as a `String`.
+
+The `= js.native` is a Scala.js idiosyncrasy: we need a concrete value to satisfy the Scala typechecker.
+In an ideal world, it would not be required.
+
 We can now build the Scala.js project by opening a new console, and entering sbt:
 
 {% highlight shell %}
@@ -309,7 +343,7 @@ export default defineConfig({
 {% endhighlight %}
 
 While this may look scary, most of the complexity is concentrated into `printSbtTask`.
-That utility invokes a third-party process (sbt) in a platform-independent way (in particular, for Windows) and retries its `stdout` output.
+That utility invokes a third-party process (sbt) in a platform-independent way (in particular, for Windows) and retrieves its `stdout` output.
 Other than that, we are doing two things:
 
 1. Depending on `process.env.NODE_ENV`, we retrieve the output of the sbt task `fastLinkJSOutput` or `fullLinkJSOutput`.