Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts (#517)

To clarify this options map is available as the second arg to parametrize the `:render-fn`. Still support the old name for now.

Author: mk

CHANGELOG.md

@@ -16,6 +16,8 @@ Changes can be:
 
     * Support first-class `:add-viewers` attribute on viewer map which will do `clerk/add-viewers` before passing viewers down the tree. Use it in `table-viewer` and `markdown-viewer`. Both these viewers can now be customized more easily. For example, you can customize the `table-viewer` to show missing values differently, see [Book of Clerk](https://book.clerk.vision/#tables).
 
+* 🚨 Rename `:nextjournal.clerk/opts` to `:nextjournal.clerk/render-opts` to clarify this options map is available as the second arg to parametrize the `:render-fn`. Still support the `:nextjournal.clerk/opts` for now.
+
 * 💫 Assign `:name` to every viewer in `default-viewers`
 
 * 🐞 Show correct non-var return value for deflike form, fixes [#499](https://github.com/nextjournal/clerk/issues/499)

notebooks/onwards.md

@@ -88,18 +88,27 @@ Notes about what currently breaks 💥 and what could be better tomorrow.
 - [x] Set expanded state depending on shape (width) of the data
 - [x] Allow to control viewer expansion state programmatically
 - [x] Support cherry as alternative js evaluator
-- [ ] Make `doc-url` work in live app using `v/clerk-eval` with homepage, 404 and symbol links
+- [x] Make `doc-url` work in live app using `v/clerk-eval` with homepage, 404 and symbol links
+- [x] Build static build on CI
+- [x] Hook up new table viewer
+- [x] Status log
+- [x] Rename `:nextjournal.clerk/opts` to `:nextjournal.clerk/render-opts`
+- [ ] Improve page load performance of large documents like book (probably by evaluating each `:render-fn` only once)
+- [ ] Introduce window/session concept to support opening concurrent documents
+- [ ] Introduce per-session/connection state for sync
+- [ ] Make clerk sync recomputations more granular (only recompute deps of changed atom)
 - [ ] Global config with consistent inheritance to ns, expression
-- [ ] Add sync atoms to book
-- [ ] Add tap inspector to book
-- [ ] Add customizing clerk: markdown backtick eval example to book
 - [ ] Tap & eval viewer window
 - [ ] Add multiviewer to default viewers
 - [ ] Make stacktraces clickable
 - [ ] Mark uncacheable results in browser window including explanation
-- [x] Build static build on CI
-- [x] Hook up new table viewer
 - [ ] Add CAS storage option for static builds
-- [x] Status log
+- [ ] Improve performance of analysis & presentation
+## 📖 Book Updates
+- [ ] Explain `render-opts` and `viewer-opts` in book
+- [ ] Add sync atoms to book
+- [ ] Add tap inspector to book
+- [ ] Add customizing clerk: markdown backtick eval example to book
+- [ ] Add example for cross-document table of contents
 ## 💡 Ideas
 - [ ] Hook up distributed caching using CAS + cloud bucket

src/nextjournal/clerk.clj

@@ -125,7 +125,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([viewer x] (with-viewer viewer {} x))
   ([viewer viewer-opts x] (v/with-viewer viewer viewer-opts x)))
 
@@ -217,7 +217,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([x] (v/html x))
   ([viewer-opts x] (v/html viewer-opts x)))
 
@@ -228,7 +228,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([x] (v/md x))
   ([viewer-opts x] (v/md viewer-opts x)))
 
@@ -239,7 +239,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([x] (v/plotly x))
   ([viewer-opts x] (v/plotly viewer-opts x)))
 
@@ -254,7 +254,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([x] (v/vl x))
   ([viewer-opts x] (v/vl viewer-opts x)))
 
@@ -279,7 +279,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([xs] (v/table xs))
   ([viewer-opts xs] (v/table viewer-opts xs)))
 
@@ -292,7 +292,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   [& xs] (apply v/row xs))
 
 (defn col
@@ -304,7 +304,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   [& xs] (apply v/col xs))
 
 (defn tex
@@ -314,7 +314,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([x] (v/tex x))
   ([viewer-opts x] (v/tex viewer-opts x)))
 
@@ -351,7 +351,7 @@
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/opts`: a map argument that will be passed to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
   ([code-string-or-form] (v/code code-string-or-form))
   ([viewer-opts code-string-or-form] (v/code viewer-opts code-string-or-form)))
 

src/nextjournal/clerk/parser.cljc

@@ -52,7 +52,7 @@
   #{:nextjournal.clerk/auto-expand-results?
     :nextjournal.clerk/budget
     :nextjournal.clerk/css-class
-    :nextjournal.clerk/opts
+    :nextjournal.clerk/render-opts
     :nextjournal.clerk/page-size
     :nextjournal.clerk/render-evaluator
     :nextjournal.clerk/visibility

src/nextjournal/clerk/render.cljs

@@ -325,7 +325,7 @@
       (cond-> viewer-css-class
         (string? viewer-css-class) vector)
       ["viewer"
-       (when (get-in x [:nextjournal/opts :fragment-item?]) "fragment-item")
+       (when (get-in x [:nextjournal/render-opts :fragment-item?]) "fragment-item")
        (when viewer-name (name viewer-name))
        (when inner-viewer-name (name inner-viewer-name))
        (case (or (viewer/width x)
@@ -392,8 +392,8 @@
 
 (defn inspect-children [opts]
   (map (fn [x] (cond-> [inspect-presented opts x]
-                 (get-in x [:nextjournal/opts :id])
-                 (with-meta {:key (str (get-in x [:nextjournal/opts :id]) "@" @!eval-counter)})))))
+                 (get-in x [:nextjournal/render-opts :id])
+                 (with-meta {:key (str (get-in x [:nextjournal/render-opts :id]) "@" @!eval-counter)})))))
 
 (def expand-style
   ["cursor-pointer"
@@ -615,7 +615,7 @@
        ;; each view function must be called in its own 'functional component' so that it gets its own hook state.
        ^{:key (str (:hash viewer) "@" (peek (:path opts)))}
        [(:render-fn viewer) value (merge opts
-                                         (:nextjournal/opts x)
+                                         (:nextjournal/render-opts x)
                                          {:viewer viewer :path path})]))))
 
 (defn inspect [value]

src/nextjournal/clerk/tap.clj

@@ -53,7 +53,7 @@
                    (-> wrapped-value
                        v/mark-preserve-keys
                        (merge (v/->opts (v/ensure-wrapped (::val value)))) ;; preserve opts like ::clerk/width and ::clerk/css-class
-                       (assoc-in [:nextjournal/opts :id] (::key value)) ;; assign custom react key
+                       (assoc-in [:nextjournal/render-opts :id] (::key value)) ;; assign custom react key
                        (update-in [:nextjournal/value ::tapped-at] inst->local-time-str)))})
 
 

src/nextjournal/clerk/viewer.cljc

@@ -163,7 +163,7 @@
 
 (def viewer-opts-normalization
   "Normalizes ns for viewer opts keywords `:nextjournal.clerk/x` => `:nextjournal/x`"
-  (into {}
+  (into {:nextjournal/opts :nextjournal/render-opts}
         (map (juxt #(keyword "nextjournal.clerk" (name %))
                    #(keyword "nextjournal" (name %))))
         (conj parser/block-settings :viewer :viewers)))
@@ -179,8 +179,8 @@
                       {:width width :css-class css-class}))))
   opts)
 
-(defn normalize-viewer-opts [opts]
-  (throw-when-viewer-opts-invalid (set/rename-keys opts viewer-opts-normalization)))
+(defn normalize-viewer-opts [viewer-opts]
+  (throw-when-viewer-opts-invalid (set/rename-keys viewer-opts viewer-opts-normalization)))
 
 (defn normalize-viewer [viewer]
   (cond (keyword? viewer) viewer
@@ -330,12 +330,12 @@
     (with-viewer (keyword "nextjournal.markdown" (name type)) wrapped-value)))
 
 (defn into-markup [markup]
-  (fn [{:as wrapped-value :nextjournal/keys [viewers opts]}]
+  (fn [{:as wrapped-value :nextjournal/keys [viewers render-opts]}]
     (-> (with-viewer {:name `markdown-node-viewer :render-fn 'identity} wrapped-value)
         mark-presented
         (update :nextjournal/value
                 (fn [{:as node :keys [text content] ::keys [doc]}]
-                  (into (cond-> markup (fn? markup) (apply [(merge opts node)]))
+                  (into (cond-> markup (fn? markup) (apply [(merge render-opts node)]))
                         (cond text [text]
                               content (mapv #(-> (ensure-wrapped-with-viewers viewers (assoc % ::doc doc))
                                                  (with-md-viewer)
@@ -507,7 +507,7 @@
                                                                          opts-from-block
                                                                          (ensure-wrapped-with-viewers (or viewers (get-viewers *ns*)) value))
         presented-result (-> (present to-present)
-                             (update :nextjournal/opts
+                             (update :nextjournal/render-opts
                                      (fn [{:as opts existing-id :id}]
                                        (cond-> opts
                                          auto-expand-results? (assoc :auto-expand-results? auto-expand-results?)
@@ -574,7 +574,7 @@
 
 (defn md-image->viewer [doc block-id idx {:keys [attrs]}]
   (with-viewer `html-viewer
-    #?(:clj {:nextjournal/opts {:id (processed-block-id block-id [idx])}
+    #?(:clj {:nextjournal/render-opts {:id (processed-block-id block-id [idx])}
              :nextjournal/width (try (image-width (read-image (:src attrs)))
                                      (catch Throwable _ :prose))})
     [:div.flex.flex-col.items-center.not-prose.mb-4
@@ -598,7 +598,7 @@
                 (mapcat (fn [fragment]
                           (if (= :image (:type (first fragment)))
                             (map #(md-image->viewer doc id (swap! !idx inc) %) fragment)
-                            [(with-viewer `markdown-viewer {:nextjournal/opts {:id (processed-block-id id [(swap! !idx inc)])}}
+                            [(with-viewer `markdown-viewer {:nextjournal/render-opts {:id (processed-block-id id [(swap! !idx inc)])}}
                                (process-sidenotes {:type :doc
                                                    :content (vec fragment)
                                                    ::doc doc} doc))]))
@@ -610,8 +610,8 @@
             (cond-> []
               code?
               (conj (with-viewer (if fold? `folded-code-block-viewer `code-block-viewer)
-                      {:nextjournal/opts (assoc (select-keys cell [:loc])
-                                                :id (processed-block-id (str id "-code")))}
+                      {:nextjournal/render-opts (assoc (select-keys cell [:loc])
+                                                       :id (processed-block-id (str id "-code")))}
                       (dissoc cell :result)))
               (or result? eval?)
               (conj (cond-> (ensure-wrapped (-> cell (assoc ::doc doc) (set/rename-keys {:result ::result})))
@@ -719,7 +719,7 @@
     :transform-fn (update-val #(with-viewer `html-viewer
                                  [:div.code-viewer.code-listing
                                   (with-viewer `code-viewer
-                                    {:nextjournal/opts {:language (:language % "clojure")}}
+                                    {:nextjournal/render-opts {:language (:language % "clojure")}}
                                     (str/trim-newline (md.transform/->text %)))]))}
 
    ;; marks
@@ -886,7 +886,7 @@
   {:name `mathjax-viewer :render-fn 'nextjournal.clerk.render/render-mathjax :transform-fn mark-presented})
 
 (defn ->opts [wrapped-value]
-  (select-keys wrapped-value [:nextjournal/budget :nextjournal/css-class :nextjournal/width :nextjournal/opts
+  (select-keys wrapped-value [:nextjournal/budget :nextjournal/css-class :nextjournal/width :nextjournal/render-opts
                               :nextjournal/render-evaluator
                               :!budget :store!-wrapped-value :present-elision-fn :path :offset]))
 
@@ -935,7 +935,7 @@
   {:name `code-viewer
    :render-fn 'nextjournal.clerk.render/render-code
    :transform-fn (comp mark-presented
-                       #(update-in % [:nextjournal/opts :language] (fn [lang] (or lang "clojure")))
+                       #(update-in % [:nextjournal/render-opts :language] (fn [lang] (or lang "clojure")))
                        (update-val (fn [v] (if (string? v) v (str/trim (with-out-str (pprint/pprint v)))))))})
 
 (def reagent-viewer
@@ -995,11 +995,11 @@
                      (-> wrapped-value
                          (assoc :nextjournal/viewer `table-markup-viewer)
                          (update :nextjournal/width #(or % :wide))
-                         (update :nextjournal/opts merge {:num-cols (count (or head (first rows)))
-                                                          :number-col? (into #{}
-                                                                             (comp (map-indexed vector)
-                                                                                   (keep #(when (number? (second %)) (first %))))
-                                                                             (not-empty (first rows)))})
+                         (update :nextjournal/render-opts merge {:num-cols (count (or head (first rows)))
+                                                                 :number-col? (into #{}
+                                                                                    (comp (map-indexed vector)
+                                                                                          (keep #(when (number? (second %)) (first %))))
+                                                                                    (not-empty (first rows)))})
                          (assoc :nextjournal/value (cond->> []
                                                      (seq rows) (cons (with-viewer `table-body-viewer (merge (-> applied-viewer
                                                                                                                  (select-keys [:page-size])

test/nextjournal/clerk/viewer_test.clj

@@ -182,14 +182,14 @@
   (testing "opts are not propagated to children during presentation"
     (let [count-opts (fn [o]
                        (let [c (atom 0)]
-                         (w/postwalk (fn [f] (when (= :nextjournal/opts f) (swap! c inc)) f) o)
+                         (w/postwalk (fn [f] (when (= :nextjournal/render-opts f) (swap! c inc)) f) o)
                          @c))]
-      (let [presented (v/present (v/col {:nextjournal.clerk/opts {:width 150}} 1 2 3))]
-        (is (= {:width 150} (:nextjournal/opts presented)))
+      (let [presented (v/present (v/col {:nextjournal.clerk/render-opts {:width 150}} 1 2 3))]
+        (is (= {:width 150} (:nextjournal/render-opts presented)))
         (is (= 1 (count-opts presented))))
 
       (let [presented (v/present (v/table {:col1 [1 2] :col2 '[a b]}))]
-        (is (= {:num-cols 2 :number-col? #{0}} (:nextjournal/opts presented)))
+        (is (= {:num-cols 2 :number-col? #{0}} (:nextjournal/render-opts presented)))
         (is (= 1 (count-opts presented))))))
 
   (testing "viewer opts are normalized"
@@ -329,7 +329,7 @@
                    view/doc->viewer v/->value :blocks
                    (tree-seq coll? seq)
                    (filter (every-pred map? :nextjournal/presented))
-                   (map (comp :id :nextjournal/opts :nextjournal/presented)))]
+                   (map (comp :id :nextjournal/render-opts :nextjournal/presented)))]
       (is (= 5 (count ids)))
       (is (every? (every-pred not-empty string?) ids))
       (is (distinct? ids))))