Compiling nim to javascript

docsrc/caesar.nim

@@ -0,0 +1,61 @@
+import nimib
+
+nbInit
+
+
+nbKaraxCode:
+  import std / [strutils, math]
+
+  proc encryptChar(c: char, shift: int): char =
+    let c_normalized = c.ord - 'a'.ord # a is 0, z is 25
+    var c_encrypted = euclMod(c_normalized + shift, 26) + 'a'.ord
+    result = c_encrypted.char
+
+  proc encryptString(s: string, shift: int): string =
+    for c in s:
+      if c in 'a' .. 'z':
+        result.add encryptChar(c, shift)
+      else:
+        result.add c
+
+  var cipherText, plainText: string
+  let ciphertextId = "ciphertext"
+  let plaintextId = "plaintext"
+  let shiftSliderId = "shiftSlider"
+  let encodeButtonId = "encodeButton"
+  let decodeButtonId = "decodeButton"
+  var shiftString = "3"
+  karaxHtml:
+    label:
+      text "Plaintext"
+    textarea(id = plaintextId, placeholder = "You can encrypt this message or you can try to decrypt the message below...")
+    hr()
+    label:
+      text "Ciphertext"
+    textarea(id = ciphertextId):
+      text "oek vekdt jxu iushuj auo! weet meha! dem oek sqd uqj q squiqh iqbbqt qi q fhypu, okcco!"
+    hr()
+    label:
+      text "Shift/Key: " & shiftString
+    input(`type` = "range", min = "0", max = "25", value = "3", id = shiftSliderId):
+      proc oninput() =
+        let slider = getVNodeById(shiftSliderId)
+        shiftString = $slider.getInputText
+    button(id = encodeButtonId):
+      text "Encrypt"
+      proc onClick() =
+        let shift = ($getVNodeById(shiftSliderId).getInputText).parseInt
+        let plaintext = ($getVNodeById(plaintextId).getInputText).toLower
+        let ciphertext = encryptString(plaintext, shift)
+        getVNodeById(ciphertextId).setInputText ciphertext
+    button(id = decodeButtonId):
+      text "Decrypt"
+      proc onClick() =
+        let shift = ($getVNodeById(shiftSliderId).getInputText).parseInt
+        let ciphertext = ($getVNodeById(ciphertextId).getInputText).toLower
+        let plaintext = encryptString(ciphertext, -shift) # encrypt with -shift to decrypt
+        getVNodeById(plaintextId).setInputText plainText
+
+
+
+nbSave

docsrc/counters.nim

@@ -0,0 +1,125 @@
+import std / [strutils]
+import nimib
+
+nbInit
+
+nbText: hlMd"""
+# Counters - Creating reusable widgets
+
+This document will show you how to create reusable widgets using `nbCodeToJs`. Specifically we will make a counter:
+A button which increases a counter each time you click it. We will do this in two different ways, using `std/dom` and `karax`.
+## std/dom
+
+The first method is to use Nim like you would have used Javascript using `getElementById` and `addEventListener`: 
+"""
+nbCode:
+  ## 1:
+  template counterButton(id: string) =
+    let labelId = "label-" & id
+    let buttonId = "button-" & id
+    ## 2:
+    nbRawOutput: """
+<label id="$1">0</label>
+<button id="$2">Click me</button>
+""" % [labelId, buttonId]
+    ## 3:
+    nbCodeToJs(labelId, buttonId):
+      import std/dom
+      ## 4:
+      var label = getElementById(labelId.cstring)
+      var button = getElementById(buttonId.cstring)
+      ## 5:
+      var counter: int = 0
+      button.addEventListener("click",
+        proc (ev: Event) =
+          counter += 1
+          label.innerHtml = ($counter).cstring
+      )
+
+nbText: hlMd"""
+Let's explain each part of the code:
+1. We define a template called `counterButton` which will create a new counter button. So if you call it somewhere it will
+place the widget there, that's the reusable part done. But it also takes an input `id: string`. This is to solve the problem of each widget needing unique ids. It can also be done with `nb.newId` as will be used in the Karax example.
+2. Here we emit the `<label>` and `<button>` tags and insert their ids.
+3. `nbCodeToJs` is the template that will turn our Nim code into Javascript and we are capturing `labelId` and `buttonId` (Important that you capture all used variables defined outside the code block). `std/dom` is where many dom-manipulation functions are located.
+4. We fetch the elements we emitted above by their ids. Remember that most javascript functions want `cstring`s!
+5. We create a variable `counter` to keep track of the counter and add the eventlistener to the `button` element. There we increase the counter and update the `innerHtml` of the `label`.
+
+Here we have the button in action: `counterButton("uniqueString")`
+"""
+
+counterButton("uniqueString")
+
+nbText: """And here is another independent counter: `counterButton("anotherUniqueString")`"""
+
+counterButton("anotherUniqueString")
+
+nbText: hlMd"""
+## Karax
+
+The second method uses Karax to construct the HTML and attach an eventlistener to the button:
+"""
+
+nbCode:
+  template karaxButton() =
+    ## 1:
+    nbKaraxCode:
+      ## 2:
+      var counter = 0
+      ## 3:
+      karaxHtml:
+        label:
+          text "Counter: " & $counter
+        button:
+          text "Click me (karax)"
+          ## 4:
+          proc onClick() =
+            counter += 1
+
+
+nbText: hlMd"""
+Here's what each part of the code does:
+1. `nbKaraxCode` is a convinience template for writing karax components. Karax is automatically imported inside the code block.
+2. Setup `counter` to keep track of the count.
+3. `karaxHtml` is a convinience wrapper for the karax dsl. The code block will automatically be inserted inside a `buildHtml(tdiv)`.
+4. The eventlistener is inlined in the `button:`.
+
+Here is the button in action: `karaxButton()`
+"""
+
+karaxButton()
+
+nbText: """And here is another independent counter: `karaxButton()`"""
+
+karaxButton()
+
+nbText: hlMd"""
+## Exercise
+
+Modify the counter templates to include a reset button which sets the counter to 0 again like this:
+"""
+
+## Karax with reset button
+template karaxButtonWithReset() =
+  nbKaraxCode:
+    var counter = 0
+    karaxHtml:
+      label:
+        text "Counter: " & $counter
+      button:
+        text "Click me (karax)"
+        proc onClick() =
+          counter += 1
+      button:
+        text "Reset"
+        proc onClick() =
+          counter = 0
+
+karaxButtonWithReset()
+
+nbText: hlMd"""
+If you click "Show source" at the bottom of the page you can find this implemented in Karax in template `karaxButtonWithReset`.
+"""
+
+
+nbSave

docsrc/index.nim

@@ -5,7 +5,7 @@ nb.title = "Nimib Docs"
 
 let
   repo = "https://github.com/pietroppeter/nimib"
-  docs = "https://pietroppeter.github.io/nimib"
+  docs = if defined(useMdBackend): "https://pietroppeter.github.io/nimib" else: "."
   hello = read(nb.srcDir / "hello.nim".RelativeFile)
   assets = "docs/static"
   highlight = "highlight.nim.js"
@@ -83,6 +83,10 @@ in this repo:
 * [numerical]({docs}/numerical.html): example usage of NumericalNim (example of custom style, usage of latex)
 * [cheatsheet]({docs}/cheatsheet.html): markdown cheatsheet (example of a custom block, custom highlighting and a simple TOC)
 * [mostaccio]({docs}/mostaccio.html): examples of usage of nim-mustache and of dark mode.
+* [interactivity]({docs}/interactivity.html): shows the basic API of creating interactive elements using `nbCodeToJs`.
+* [counter]({docs}/counters.html): shows how to create reusable interactive widgets by creating a counter button.
+* [caesar]({docs}/caesar.html): a Caesar cipher implemented using `nbCodeToJs` and `karax`.
+
 
 elsewhere:
 

docsrc/interactivity.nim

@@ -0,0 +1,93 @@
+import nimib
+
+nbInit
+
+nbText: hlMd"""
+# Creating interactive components in Nimib
+
+Nimib can easily be used to create static content with `nbText` and `nbCode`, but did you know that you can create interactive
+content as well? And that you can do it all in Nim even! This can be achieved using either the `nbCodeToJs`-API or `nbKaraxCode`.
+They work by compiling Nim code into javascript and adding it to the resulting HTML file.
+This means that arbitrary Javascript can be written but also that Karax, which compiles to javascript, also can be used.
+
+## nbCodeToJsInit
+This is the fundamental API used for compiling Nim-snippets to javascript. It consists of three templates:
+- `nbCodeToJsInit` - Creates a new code script that further code can be added to later.
+- `addCodeToJs` - Adds to an existing code script
+- `addToDocAsJs` - Takes the Nim code in a script and compiles it to javascript. 
+Here is a basic example:
+"""
+
+nbCode:
+  let script = nbCodeToJsInit:
+    echo "Hello world!"
+  let x = 3.14
+  script.addCodeToJs(x):
+    echo "Pi is roughly ", x
+  ## Uncomment this line:
+  ##script.addToDocAsJs()
+script.addToDocAsJs()
+nbCodeToJsShowSource()
+
+
+nbText: hlMd"""
+The reason `script.addToDocAsJs()` is commented out is just a limitation of nimib not handling nested blocks well.
+If you now go to your browser's javascript console you should see `Hello world` and `Pi is roughly 3.14` printed there.
+What is up with `script.addCodeToJs(x)` though? Why is `(x)` needed? It is because we have to capture the value of `x`
+to be able to use it in the javascript. The code block will basically be copy-pasted into a separate file and
+compiled into javascript. And `x` isn't defined there so we have to capture it. This is true for any variable that
+we want to use that is defined outside the script blocks.
+
+## nbCodeToJs
+This is basically a shorthand for running `nbCodeToJsInit` and `addToDocAsJs` in a single call:
+```nim
+let x = 3.14
+nbJsCode(x):
+  echo "Pi is roughly ", x
+```
+
+## nbKaraxCode
+
+If you want to write a component using karax this is the template for you!
+A normal karax program has the following structure:
+```nim
+nbCodeToJs(rootId):
+  import karax / [kbase, karax, karaxdsl, vdom, compact, jstrutils, kdom]
+
+  karaxCode  # some code, set up global variables for example
+
+  proc createDom(): VNode =
+    result = buildHtml(tdiv):
+      karaxHtmlCode # html karax code
+
+  setRenderer(createDom, root=rootId.cstring)
+```
+where `karaxCode` and `karaxHtmlCode` can be arbitrary code. Using `nbKaraxCode` it can instead be written as:
+```nim
+nbKaraxCode:
+  karaxCode
+  karaxHtml:
+    karaxHtmlCode
+```
+This reduces the boilerplate and makes for more readable code! Karax is automatically imported for you (the modules in `karax / prelude`) and `karaxHtml`
+is a template that writes `createDom` and `setRenderer` for you so you only have to provide the body of the `buildHtml` call. Here's a basic example:
+"""
+
+nbCode:
+  template karaxExample =
+    let x = 3.14
+    nbKaraxCode(x):
+      var message = "Pi is roughly " & $x
+      karaxHtml:
+        p:
+          text message
+        button:
+          text "Click me!"
+          proc onClick() =
+            message = "Poof! Gone!"
+
+nbText: "This is the output this code produces:"
+
+karaxExample()
+
+nbSave

nimib.nimble

@@ -15,7 +15,7 @@ requires "mustache >= 0.2.1"
 requires "toml_serialization >= 0.2.0"
 
 task docsdeps, "install dependendencies required for doc building":
-  exec "nimble -y install [email protected] [email protected] nimoji nimpy"
+  exec "nimble -y install [email protected] [email protected] nimoji nimpy karax@#head"
 
 task test, "General tests":
   exec "nim r -d:nimibPreviewCodeAsInSource tests/tsources.nim"
@@ -38,6 +38,9 @@ task docs, "Build documentation":
   exec "nim r docsrc/cheatsheet.nim"
   exec "nim r docsrc/files.nim"
   exec "nim r docsrc/index.nim"
+  exec "nim r docsrc/interactivity.nim"
+  exec "nim r docsrc/counters.nim"
+  exec "nim r docsrc/caesar.nim"
   when not defined(nimibDocsSkipPenguins):
     exec "nim r docsrc/penguins.nim"
   exec "nimble readme"  

src/nimib.nim

@@ -1,6 +1,7 @@
-import std/[os, strutils, sugar]
-import nimib / [types, blocks, docs, boost, config, options, capture]
-export types, blocks, docs, boost, sugar
+import std/[os, strutils, sugar, strformat, macros, macrocache, sequtils, jsonutils, random]
+export jsonutils
+import nimib / [types, blocks, docs, boost, config, options, capture, jsutils]
+export types, blocks, docs, boost, sugar, jsutils
 # types exports mustache, tables, paths
 
 from nimib / themes import nil
@@ -16,7 +17,6 @@ template moduleAvailable*(module: untyped): bool =
 
 template nbInit*(theme = themes.useDefault, backend = renders.useHtmlBackend, thisFileRel = "") =
   var nb {.inject.}: NbDoc
-
   nb.initDir = getCurrentDir().AbsoluteDir
   loadOptions nb
   loadCfg nb
@@ -124,6 +124,36 @@ template nbRawOutput*(content: string) =
   newNbSlimBlock("nbRawOutput"):
     nb.blk.output = content
 
+
+template nbCodeToJsInit*(args: varargs[untyped]): NbBlock =
+  let (code, originalCode) = nimToJsString(true, args)
+  var result = NbBlock(command: "nbCodeToJs", code: originalCode, context: newContext(searchDirs = @[], partials = nb.partials), output: "")
+  result.context["transformedCode"] = code
+  result
+
+template addCodeToJs*(script: NbBlock, args: varargs[untyped]) =
+  let (code, originalCode) = nimToJsString(false, args)
+  script.code &= "\n" & originalCode
+  script.context["transformedCode"] = script.context["transformedCode"].vString & "\n" & code
+
+
+template addToDocAsJs*(script: NbBlock) =
+  nb.blocks.add script
+  nb.blk = script
+
+template nbCodeToJs*(args: varargs[untyped]) =
+  let script = nbCodeToJsInit(args)
+  script.addToDocAsJs
+
+template nbKaraxCode*(args: varargs[untyped]) =
+  let rootId = "karax-" & $nb.newId()
+  nbRawOutput: "<div id=\"" & rootId & "\"></div>"
+  nbKaraxCodeBackend(rootId, args)
+
+template nbCodeToJsShowSource* =
+  nb.blk.context["js_show_nim_source"] = true
+
+
 template nbClearOutput*() =
   if not nb.blk.isNil:
     nb.blk.output = ""

src/nimib/boost.nim

@@ -28,4 +28,14 @@ template hlPy*(s: string): string =
 template hlPyF*(s: string): string =
   ## Template for use with NimiBoost to mark strings to be syntax-highlighted as Python.
   ## Equivilent to ``&s`` so it applies string interpolation.
+  &s
+
+template hlNim*(s: string): string =
+  ## Template for use with NimiBoost to mark strings to be syntax-highlighted as Nim.
+  ## It is a no-op and returns the orginal string.
+  s
+
+template hlNimF*(s: string): string =
+  ## Template for use with NimiBoost to mark strings to be syntax-highlighted as Nim.
+  ## Equivilent to ``&s`` so it applies string interpolation.
   &s