Merge branch 'main' into sci-async-3

# Conflicts:
#	render/deps.edn
#	src/nextjournal/clerk/sci_env.cljs

Author: mk

.gitattributes

@@ -1,3 +1,4 @@
 ;; always force unix line endings to make hashing consistent
 * text eol=lf
 *.png binary
+*.db binary

.github/workflows/main.yml

@@ -148,7 +148,7 @@ jobs:
           clojure -J-Dclojure.main.report=stderr -X:demo:nextjournal/clerk :git/sha '"${{ github.sha }}"' :git/url '"https://github.com/nextjournal/clerk"' :paths '["book.clj" "CHANGELOG.md" "editor.clj"]'
 
       - name: 🏗 Build Clerk Static App with default Notebooks
-        run: clojure -J-Dclojure.main.report=stderr -X:demo:nextjournal/clerk :git/sha '"${{ github.sha }}"' :git/url '"https://github.com/nextjournal/clerk"' :bundle true
+        run: clojure -J-Dclojure.main.report=stderr -X:demo:nextjournal/clerk :package :single-file
 
       - name: 📠 Copy book & static build to bucket under SHA
         run: |

CHANGELOG.md

@@ -8,6 +8,75 @@ Changes can be:
 
 ## Unreleased
 
+...
+
+## 0.16.1016 (2024-06-05)
+
+* 🥡 The whole cell context (e.g. its form, code text etc.) is now passed to viewer functions along with the wrapped result. In addition, a new cell-viewer has been added to possibly transform a cell's properties prior to presentation. This can be used, for instance, to alter a cell's visibility programmatically ([#575](https://github.com/nextjournal/clerk/issues/575)). 
+
+* 🪬 Allow viewer predicate functions to opt into recieving more context (the form with metadata, code text, etc) by providing putting the predicate function as value in a map with a `:wrapped` key, e.g. `{:pred {:wrapped (fn [x] ,,,)} ,,,}`. This makes Clerk's form metadata viewer selection extensible.
+
+* 💬 Add `clerk/comment` that behaves like `clojure.core/comment` outside of Clerk but shows the results like regular top-level forms in Clerk.
+
+* 💫 Allow to disable welcome page in `serve!` by specifying `:paths` or `:paths-fn`.
+
+* 💫 Support using Markdown syntax in `clerk/caption` text
+
+* 💫 Support toggling auto-expansion of results in tap viewer
+
+* 💫 Redesign examples viewer to be more readable and in a way that doesn't force `display: flex` onto contents.
+
+* 💫 Introduce client-side routing for static builds to make page transitions smoother by default. In addition, the option `:bundle?` for `clerk/build!` is now deprecated in favour of setting a new option `:package` to `:single-file` (the default for it being `:directory`).
+
+* 💫 Introduce a toc viewer for allowing customization of the table of contents
+
+* 🛠 Bump depdendencies
+
+  * `com.taoensso/nippy` to `3.4.2`
+  * `http-kit/http-kit` to `3.8.0`
+  * `io.github.nextjournal/markdown` to `0.5.146`
+  * `hiccup/hiccup` to `2.0.0-RC3`
+
+* 🐜 Fix blank screen caused by react unmounting when an exception occurs during `clerk/show!`, fixes [#586](https://github.com/nextjournal/clerk/issues/586) @elken
+
+* 🐜 Fix browser crashing when file watcher is used with `:show-filter-fn` option in notebooks with exceptions, fixes [#616](https://github.com/nextjournal/clerk/issues/616).
+
+* 🐜 Make edn transmission resilient to symbols and keywords containing multiple slashes like `foo/bar/baz`. Those can be read by `read-string` but not in ClojureScript which is based on `tools.reader`.
+
+* 🐞 Fix `:nextjournal.clerk/page-size` option throwing when set on string values, fixes [#584][https://github.com/nextjournal/clerk/issues/584]
+
+* 🐞 Fix caching behaviour of `clerk/image` and support overriding image-viewer by name
+
+* 🐞 Fix tap viewer keeping open/collapsed state [#543](https://github.com/nextjournal/clerk/issues/543) @teodorlu
+
+* 🐞  Fix `serve!` `:browse` option for default host & port
+
+* 🐞 Fix `unquote` in experimental cljs Clerk editor, fixes [#576](https://github.com/nextjournal/clerk/issues/576) @sritchie
+
+* 🐞 Fix `row` and `col` viewers not showing a first map argument, fixes [#567](https://github.com/nextjournal/clerk/issues/567) @teodorlu
+
+* 🐞 Fix long sidenotes overlapping with subsequent content, fixes [#564](https://github.com/nextjournal/clerk/issues/564) @hlship
+
+* 🐞 Fix image embedding regression in static build introduced in 424bf35040a266f71d00d8a581ba7cdfcfcd4a75
+
+* 🐞 Swallow git errors in shell-out-str instead of printing them to stdout/err
+
+* 🐞 Fix an issue in fragments which showed definitions as vars instead of their values
+
+* 🐞 Fix blank page when notebook contains latex errors in prose [#571](https://github.com/nextjournal/clerk/issues/571) @titonbarua and [#603](https://github.com/nextjournal/clerk/issues/603) @teodorlu
+
+* 🐞 Fix displaying images when expanding elided data [#612](https://github.com/nextjournal/clerk/issues/612) @a1exsh
+
+* 🐞 Elide end-location metadata from forms which otherwise crashes `honey.sql/format` [#646](https://github.com/nextjournal/clerk/issues/646) @borkdude
+
+## 0.15.957 (2023-09-28)
+
+* 🔌 Offline support
+
+  Support working fully offline by adding a ServiceWorker to intercept and cache network requests to remote assets in the browser. It works for Clerk's js bundle, its tailwind css script, fonts and as well as javascript dynamically loaded using d3-require like Clerk's Vega and Plotly viewers.
+
+  To use it, you need to open Clerk in the browser when online to populate the cache. Viewers that are dynamically loaded (e.g. Vega or Plotly) need to be used once while offline to be cached. We're considering loading them on worker init in a follow up.
+
 * 👁️ Improve viewer customization
 
     * Simplify customization of number of rows displayed for table viewer using viewer-opts, e.g. `(clerk/table {::clerk/page-size 7})`. Pass `{::clerk/page-size nil}` to display elisions. Can also be passed a form metadata. Fixes [#406](https://github.com/nextjournal/clerk/issues/406).
@@ -47,6 +116,8 @@ Changes can be:
 
 * 💫 Assign `:name` to every viewer in `default-viewers`
 
+* 🐜 Ensure `var->location` returns a string path location fixing `Cannot open <#object[sun.nio.fs.UnixPath ,,,> as an InputStream` errors
+
 * 🐞 Don't run existing files through `fs/glob`, fixes [#504](https://github.com/nextjournal/clerk/issues/504). Also improves performance of homepage.
 
 * 🐞 Show correct non-var return value for deflike form, fixes [#499](https://github.com/nextjournal/clerk/issues/499)

README.md

@@ -46,7 +46,7 @@ To use Clerk in your project, you'll need Java 11+ and [`clojure`](https://cloju
 following dependency to your `deps.edn`:
 
 ```edn
-{:deps {io.github.nextjournal/clerk {:mvn/version "0.14.919"}}}
+{:deps {io.github.nextjournal/clerk {:mvn/version "0.16.1016"}}}
 ```
 
 Require and start Clerk as part of your system start, e.g. in `user.clj`:

bb.edn

@@ -1,7 +1,7 @@
 {:min-bb-version "0.9.159"
  :paths ["bb"]
  :deps {io.github.nextjournal/dejavu {:git/sha "4980e0cc18c9b09fb220874ace94ba6b57a749ca"}
-        io.github.nextjournal/cas-client {:git/sha "84ab35c3321c1e51a589fddbeee058aecd055bf8"}}
+        io.github.nextjournal/cas-client {:git/sha "22ef8360689cd3938e43a3223023ab1b9711818f"}}
  :tasks
  {:requires
   ([tasks :as t]

book.clj

@@ -60,7 +60,7 @@
 ;; To use Clerk in your project, add the following dependency to your `deps.edn`:
 
 ;; ```edn
-;; {:deps {io.github.nextjournal/clerk {:mvn/version "0.14.919"}}}
+;; {:deps {io.github.nextjournal/clerk {:mvn/version "0.16.1016"}}}
 ;; ```
 
 ;; Require and start Clerk as part of your system start, e.g. in `user.clj`:
@@ -299,32 +299,47 @@ int main() {
 
 ;; ### 🏞 Images
 
-;; Clerk now has built-in support for the
-;; `java.awt.image.BufferedImage` class, which is the native image
-;; format of the JVM.
-;;
-;; When combined with `javax.imageio.ImageIO/read`, one can easily
-;; load images in a variety of formats from a `java.io.File`, an
-;; `java.io.InputStream`, or any resource that a `java.net.URL` can
-;; address.
+;; Clerk offers the `clerk/image` viewer to create a buffered image
+;; from a string or anything `javax.imageio.ImageIO/read` can take
+;; (URL, File or InputStream).
 ;;
 ;; For example, we can fetch a photo of De zaaier, Vincent van Gogh's
 ;; famous painting of a farmer sowing a field from Wiki Commons like
 ;; this:
 
-(ImageIO/read (URL. "https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/The_Sower.jpg/1510px-The_Sower.jpg"))
+(clerk/image "https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/The_Sower.jpg/1510px-The_Sower.jpg")
 
 ;; We've put some effort into making the default image rendering
 ;; pleasing. The viewer uses the dimensions and aspect ratio of each
 ;; image to guess the best way to display it in classic DWIM
 ;; fashion. For example, an image larger than 900px wide with an
 ;; aspect ratio larger then two will be displayed full width:
 
-(ImageIO/read (URL. "https://images.unsplash.com/photo-1532879311112-62b7188d28ce?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8"))
+(clerk/image "https://images.unsplash.com/photo-1532879311112-62b7188d28ce?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8")
 
 ;; On the other hand, smaller images are centered and shown using their intrinsic dimensions:
 
-(ImageIO/read (URL. "https://nextjournal.com/data/QmSJ6eu6kUFeWrqXyYaiWRgJxAVQt2ivaoNWc1dtTEADCf?filename=thermo.png&content-type=image/png"))
+(clerk/image "https://nextjournal.com/data/QmSJ6eu6kUFeWrqXyYaiWRgJxAVQt2ivaoNWc1dtTEADCf?filename=thermo.png&content-type=image/png")
+
+;; You can use `clerk/image` together with `clerk/caption` which will render a simple caption under the image:
+
+(clerk/caption
+ "Implements of the Paper Printing Industry"
+ (clerk/image "https://nextjournal.com/data/QmX99isUndwqBz7nj8fdG7UoDakNDSH1TZcvY2Y6NUTe6o?filename=image.gif&content-type=image/gif"))
+
+;; Captions aren't limited to images and work together with any arbitrary content that you provide, e.g. a table:
+
+^{::clerk/visibility {:code :fold}}
+(clerk/caption
+ "Modern Symmetrical Unary(7) in [Solresol](https://wiki.xxiivv.com/site/solresol.html)"
+ (clerk/table {:head ["Solfège" "French IPA" "English IPA" "Meaning"]
+               :rows [["Do"	"/do/" "/doʊ/" "no"]
+                      ["Re" "/ʁɛ/" "/ɹeɪ/" "and, also"]
+                      ["Mi" "/mi/" "/miː/" "or"]
+                      ["Fa" "/fa/" "/fɑː/" "at, to"]
+                      ["Sol" "/sɔl/" "/soʊl/" "but, if"]
+                      ["La" "/la/" "/lɑː/" "the, then"]
+                      ["Si" "/si/" "/siː/" "yes"]]}))
 
 ;; ### 📒 Markdown
 
@@ -363,13 +378,15 @@ int main() {
 ;; nice captions:
 
 (defn caption [text]
-  (clerk/html [:span.text-slate-500.text-xs.text-center.font-sans text]))
+  (clerk/html [:figcaption.text-center.mt-1 text]))
 
 (clerk/row
  (clerk/col image-1 (caption "Figure 1: Decorative A"))
  (clerk/col image-2 (caption "Figure 2: Decorative B"))
  (clerk/col image-3 (caption "Figure 3: Decorative C")))
 
+;; Note: the caption example is _exactly_ how `clerk/caption` is implemented in Clerk.
+
 ;; **Alternative notations**
 ;;
 ;; By default, `row` and `col` operate on `& rest` so you can pass any
@@ -531,7 +548,7 @@ v/default-viewers
 
 ;; #### ⚙️ Transform
 
-;; When writing your own viewer, the first extension point you should reach for is `:tranform-fn`.
+;; When writing your own viewer, the first extension point you should reach for is `:transform-fn`.
 
 #_ "exercise: wrap this in `v/present` and call it at the REPL"
 (v/with-viewer {:transform-fn v/inspect-wrapped-values}

build.clj

@@ -32,7 +32,12 @@
                       :connection "scm:git:git://github.com/nextjournal/clerk.git"
                       :developerConnection "scm:git:ssh://[email protected]/nextjournal/clerk.git"
                       :tag (str "v" version)}
-                :src-dirs ["src"]})
+                :src-dirs ["src"]
+                :pom-data
+                [[:licenses
+                  [:license
+                   [:name "ISC License"]
+                   [:url "https://opensource.org/license/isc-license-txt"]]]]})
   (b/copy-dir {:src-dirs ["src" "resources"]
                :target-dir class-dir
                :replace {}})

deps.edn

@@ -4,22 +4,22 @@
         org.clojure/tools.analyzer {:mvn/version "1.1.0"}
         org.clojure/tools.analyzer.jvm {:mvn/version "1.1.0"}
         babashka/fs {:mvn/version "0.2.14"}
-        borkdude/edamame {:mvn/version "1.0.16"}
+        borkdude/edamame {:mvn/version "1.4.24"}
         weavejester/dependency {:mvn/version "0.2.1"}
         com.nextjournal/beholder {:mvn/version "1.0.2"}
         org.flatland/ordered {:mvn/version "1.15.11"}
 
-        io.github.nextjournal/markdown {:mvn/version "0.5.144"}
+        io.github.nextjournal/markdown {:mvn/version "0.5.148"}
         babashka/process {:mvn/version "0.4.16"}
         io.github.nextjournal/dejavu {:git/sha "4980e0cc18c9b09fb220874ace94ba6b57a749ca"}
 
-        com.taoensso/nippy {:mvn/version "3.2.0"}
+        com.taoensso/nippy {:mvn/version "3.4.2"}
 
         mvxcvi/multiformats {:mvn/version "0.3.107"}
         com.pngencoder/pngencoder {:mvn/version "0.13.1"}
 
-        http-kit/http-kit {:mvn/version "2.6.0"}
-        hiccup/hiccup {:mvn/version "2.0.0-alpha2"}
+        http-kit/http-kit {:mvn/version "2.8.0"}
+        hiccup/hiccup {:mvn/version "2.0.0-RC3"}
 
         rewrite-clj/rewrite-clj {:mvn/version "1.1.45"}
 
@@ -35,23 +35,31 @@
                                :jvm-opts ["-Dclojure.main.report=stdout"]
                                :nextjournal.clerk/aliases [:demo]}
 
+           
            :sci {:extra-deps {io.github.nextjournal/clerk.render {:local/root "render"}}}
 
-           :dev {:extra-deps {org.clojure/clojure {:mvn/version "1.12.0-alpha3"} ;; for `:as-alias` & `add-lib` support but only in dev
+           :dev {:extra-deps {org.clojure/clojure {:mvn/version "1.12.0-beta1"} ;; for `:as-alias` & `add-lib` support but only in dev
                               arrowic/arrowic {:mvn/version "0.1.1"}
                               binaryage/devtools {:mvn/version "1.0.3"}
-                              cider/cider-nrepl {:mvn/version "0.29.0"}
+                              cider/cider-nrepl {:mvn/version "0.49.0"}
+                              nrepl/nrepl {:mvn/version "1.2.0"}
                               com.clojure-goes-fast/clj-async-profiler {:mvn/version "1.0.3"}
-                              io.github.nextjournal/cas-client {:git/sha "84ab35c3321c1e51a589fddbeee058aecd055bf8"}
+                              io.github.nextjournal/cas-client {:git/sha "22ef8360689cd3938e43a3223023ab1b9711818f"}
                               org.slf4j/slf4j-nop {:mvn/version "2.0.7"}
-                              org.babashka/cli {:mvn/version "0.5.40"}}
+                              org.babashka/cli {:mvn/version "0.5.40"}
+                              io.github.babashka/sci.nrepl {:git/sha "75f379c685bbd58c3e23f531339eb144e104937d"}}
                  :extra-paths ["dev" "notebooks"]
                  :jvm-opts ["-Dclerk.resource_manifest={\"/js/viewer.js\" \"/js/viewer.js\"}"
+                            "-Dclerk.render_repl={}"
                             "-Dpolyglot.engine.WarnInterpreterOnly=false" "-XX:-OmitStackTraceInFastThrow"
                             "-Djdk.attach.allowAttachSelf"]
                  :main-opts ["-m" "shadow.cljs.devtools.cli"]
                  :exec-fn nextjournal.clerk.dev-launcher/start}
 
+           :profile {:exec-fn user/profile
+                     :exec-args {:phase :analysis}
+                     :jvm-opts ["-Dclojure.main.report=stdout"]}
+
            :test {:extra-deps {nubank/matcher-combinators {:mvn/version "3.5.1"}
                                org.clojure/test.check {:mvn/version "1.1.1"}
                                lambdaisland/kaocha {:mvn/version "1.66.1034"}
@@ -66,16 +74,21 @@
            :demo {:extra-deps {com.github.seancorfield/next.jdbc {:mvn/version "1.2.659"}
                                io.github.applied-science/shapes {:git/sha "da44031cf79a649932cb502f17388db23f2b8ace"}
                                org.xerial/sqlite-jdbc {:mvn/version "3.34.0"}
+                               com.github.seancorfield/honeysql {:mvn/version "2.6.1126"}
                                org.clojure/data.csv {:mvn/version "1.0.0"}
                                hickory/hickory {:mvn/version "0.7.1"}
                                sicmutils/sicmutils {:mvn/version "0.20.0" :exclusions [org.babashka/sci]}
                                io.github.mentat-collective/emmy {:git/sha "b98fef51d80d3edcff3100562b929f9980ff34d7"
                                                                  :exclusions [org.babashka/sci]}
                                io.github.nextjournal/clerk-slideshow {:git/sha "11a83fea564da04b9d17734f2031a4921d917893"}}}
 
+           :nextjournal/garden {:exec-fn nextjournal.clerk/serve!
+                                :exec-args {:index "book.clj"}
+                                :nextjournal.garden/aliases [:demo]}
+
            :build {:deps {io.github.nextjournal/clerk {:local/root "."}
-                          io.github.nextjournal/cas-client {:git/sha "84ab35c3321c1e51a589fddbeee058aecd055bf8"}
-                          io.github.clojure/tools.build {:git/tag "v0.6.1" :git/sha "515b334"}
+                          io.github.nextjournal/cas-client {:git/sha "22ef8360689cd3938e43a3223023ab1b9711818f"}
+                          io.github.clojure/tools.build {:git/tag "v0.10.3" :git/sha "15ead66"}
                           io.github.slipset/deps-deploy {:git/sha "b4359c5d67ca002d9ed0c4b41b710d7e5a82e3bf"}}
                    :extra-paths ["bb" "src" "resources"] ;; for loading lookup-url in build
                    :ns-default build}

dev/user.clj

@@ -1,6 +1,10 @@
 (ns user
-  (:require [clojure.string :as str]
-            [nextjournal.clerk :as clerk]))
+  (:require [clj-async-profiler.core :as prof]
+            [clojure.java.io :as io]
+            [nextjournal.clerk :as clerk]
+            [nextjournal.clerk.analyzer :as analyzer]
+            [nextjournal.clerk.eval :as eval]
+            [nextjournal.clerk.parser :as parser]))
 
 (comment
   ;; start without file watcher & open browser
@@ -43,4 +47,40 @@
 
   (do (require 'kaocha.repl)
       (kaocha.repl/run :unit))
-  )
+
+  (do
+    (clerk/clear-cache!)
+    (reset! analyzer/!file->analysis-cache {})
+    (prof/profile
+      (-> (parser/parse-file {:doc? true} "book.clj")
+              analyzer/build-graph
+              analyzer/hash))
+    nil)
+  (prof/serve-ui 8080))
+
+(defmacro with-ex-data [sym body do-block]
+  `(try ~body
+        (catch Exception e#
+          (let [~sym (ex-data e#)]
+            ~do-block))))
+
+(defmulti profile :phase)
+
+(defmethod profile :analysis [_opts]
+  (let [test-docs [(parser/parse-file {:doc? true} (io/resource "clojure/core.clj"))
+                   (parser/parse-file {:doc? true} (io/resource "nextjournal/clerk/analyzer.clj"))
+                   (parser/parse-file {:doc? true} (io/resource "nextjournal/clerk.clj"))
+                   #_ more?]
+        times 5]
+    (let [{:keys [time-ms]}
+          (eval/time-ms
+           (dotimes [_i times]
+             (doseq [doc (shuffle test-docs)]
+               (-> (analyzer/build-graph doc) analyzer/hash))
+             (prn :done/pass _i)))
+          mean (/ time-ms (* times (count test-docs)))]
+      (println (format "Elapsed mean time: %f msec" mean)))))
+
+;; clj -X:dev:profile :phase :analysis
+;; Elapsed mean time: ~1700 msec (iMac i9, main)
+;; Elapsed mean time: ~1670 msec (iMac i9, analyzer-improvements)

garden.edn

@@ -0,0 +1 @@
+{:project "book-of-clerk"}