Improve Tap Inspector (#447)

This ports the tap inspector to `clerk/fragment` with the following benefits:
* stable react keys keep views from re-rendering
* support assigning custom width per tap, fixes #178

In addition, this fixes a regression of not respecting the custom per-result / fragment budgets which as introduced with #443.
---------

Co-authored-by: Martin Kavalar <[email protected]>

Author: zampino

notebooks/fragments.clj

@@ -10,7 +10,11 @@
  (clerk/plotly {::clerk/width :full} {:data [{:y [1 3 2]}]})
  (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-200])
  (clerk/fragment (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-300])
-                 (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-400])))
+                 (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-400])
+                 (reduce (fn [acc i] (vector i acc)) :fin (range 200 0 -1))
+                 (reduce (fn [acc i] (vector i acc)) :fin (range 200 0 -1))
+                 (clerk/with-viewer {} {::clerk/budget 5}
+                   (reduce (fn [acc i] (vector i acc)) :fin (range 15 0 -1)))))
 
 ;; ## Collapsible Sections
 ;; Fragments allow to hide (and in future versions of Clerk, probably fold) chunks of prose interspersed with results. That is, by using the usual visibility annotation

notebooks/pagination.clj

@@ -69,6 +69,9 @@
 ^{::clerk/budget 5}
 (reduce (fn [acc i] (vector i acc)) :fin (range 15 0 -1))
 
+(clerk/with-viewer {}
+  {::clerk/budget 5}
+  (reduce (fn [acc i] (vector i acc)) :fin (range 15 0 -1)))
 
 (clerk/html [:div
              [:h3 "Nesting Images inside " [:span.font-mono "clerk/html"]]
@@ -81,3 +84,9 @@
                [:p [:strong {:nextjournal/value (range 30)}]]]
               [:li "A slanted range:"
                [:p [:em {:nextjournal/value (range 100)}]]]]])
+
+(clerk/html
+ {::clerk/budget 5}
+ [:div
+  [:h3 "Configuring budget inside " [:span.font-mono "clerk/html"]]
+  {:nextjournal/value (reduce (fn [acc i] (vector i acc)) :fin (range 15 0 -1))}])

src/nextjournal/clerk/render.cljs

@@ -305,7 +305,7 @@
          :nested-prose "w-full max-w-prose"
          "w-full max-w-prose px-8")])))
 
-(defn render-result [{:as result :nextjournal/keys [fetch-opts hash presented]} {:as opts :keys [id auto-expand-results? path]}]
+(defn render-result [{:nextjournal/keys [fetch-opts hash presented]} {:keys [id auto-expand-results?]}]
   (let [!desc (hooks/use-state-with-deps presented [hash])
         !expanded-at (hooks/use-state (when (map? @!desc)
                                         (->expanded-at auto-expand-results? @!desc)))
@@ -359,10 +359,9 @@
   (< 1 (count xs)))
 
 (defn inspect-children [opts]
-  ;; TODO: move update function onto viewer
-  (map-indexed (fn [idx x]
-                 (cond-> [inspect-presented (update opts :path (fnil conj []) idx) x]
-                   (get-in x [:nextjournal/opts :id]) (with-meta {:key (str (get-in x [:nextjournal/opts :id]) "@" @!eval-counter)})))))
+  (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)})))))
 
 (def expand-style
   ["cursor-pointer"
@@ -719,9 +718,6 @@
   (when react-root
     (.render react-root (r/as-element [root]))))
 
-(defn render-with-react-key [x {:as _opts :keys [id]}]
-  (with-meta x {:key id}))
-
 (defn html-render [markup]
   (r/as-element
    (if (string? markup)
@@ -822,7 +818,6 @@
    [:path {:fill-rule "evenodd" :d "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z" :clip-rule "evenodd"}]])
 
 (defn render-code-block [code-string {:keys [id]}]
-  ^{:key id}
   [:div.viewer.code-viewer.w-full.max-w-wide {:data-block-id id}
    [code/render-code code-string]])
 
@@ -858,7 +853,6 @@
         [:span.ml-4.opacity-0.translate-y-full.group-hover:opacity-100.group-hover:translate-y-0.transition-all.delay-150.hover:text-slate-500
          {:class "text-[10px]"}
          "evaluated in 0.2s"]]
-       ^{:key id}
        [:div.code-viewer.mb-2.relative.code-viewer.w-full.max-w-wide {:data-block-id id :style {:margin-top 0}}
         [render-code code-string]]])))
 

src/nextjournal/clerk/render/code.cljs

@@ -87,14 +87,13 @@
                   (< pos to)
                   (concat [(.sliceString text pos to)]))))))))
 
-(defn render-code [^String code {:as _opts :keys [id]}]
+(defn render-code [^String code _]
   (let [builder (RangeSetBuilder.)
         _ (highlightTree (.. clojureLanguage -parser (parse code)) highlight-style
                          (fn [from to style]
                            (.add builder from to (.mark Decoration (j/obj :class style)))))
         decorations-rangeset (.finish builder)
         text (.of Text (.split code "\n"))]
-    ^{:key id}
     [:div.cm-editor
      [:cm-scroller
       (into [:div.cm-content.whitespace-pre]

src/nextjournal/clerk/tap.clj

@@ -4,7 +4,11 @@
   (:require [clojure.core :as core]
             [nextjournal.clerk :as clerk]
             [nextjournal.clerk.viewer :as v])
-  (:import (java.time LocalTime ZoneId)))
+  (:import (java.time Instant LocalTime ZoneId)))
+
+(defn inst->local-time-str [inst] (str (LocalTime/ofInstant inst (ZoneId/systemDefault))))
+(defn record-tap [x]
+  {::val x ::tapped-at (Instant/now) ::key (str (gensym))})
 
 (def switch-view
   (assoc v/viewer-eval-viewer
@@ -24,77 +28,54 @@
 ^{::clerk/sync true ::clerk/viewer switch-view ::clerk/visibility {:result :show}}
 (defonce !view (atom :stream))
 
-(defonce !taps (atom []))
+
+(defonce !taps (atom ()))
 
 (defn reset-taps! []
-  (reset! !taps [])
+  (reset! !taps ())
   (clerk/recompute!))
 
-#_(reset-taps!)
-
-(defn inst->local-time-str [inst]
-  (str (LocalTime/ofInstant inst (ZoneId/systemDefault))))
-
-#_(inst->local-time-str (Instant/now))
-
-(def tap-viewer
-  {:name `tap-viewer
-   :render-fn '(fn [{:keys [val tapped-at key]} opts]
-                 (with-meta
-                   [:div.border-t.relative.py-3
-                    [:span.absolute.rounded-full.px-2.bg-gray-300.font-mono.top-0
-                     {:class "left-1/2 -translate-x-1/2 -translate-y-1/2 py-[1px] text-[9px]"} (:nextjournal/value tapped-at)]
-                    [:div.overflow-x-auto [nextjournal.clerk.render/inspect-presented val]]]
-                   {:key (:nextjournal/value key)}))
-   :transform-fn (comp clerk/mark-preserve-keys
-                       (clerk/update-val #(update % :tapped-at inst->local-time-str)))})
-
-(clerk/add-viewers! [tap-viewer])
-
-(def taps-viewer
-  {:render-fn '#(into [:div.flex.flex-col.pt-2] (nextjournal.clerk.render/inspect-children %2) %1)
-   :transform-fn (clerk/update-val (fn [taps]
-                                     (mapv (partial clerk/with-viewer `tap-viewer) (reverse taps))))})
-
-^{::clerk/visibility {:result :show}
-  ::clerk/viewer (cond-> taps-viewer
-                   (= :latest @!view)
-                   (update :transform-fn (fn [orig] (comp orig (clerk/update-val (partial take-last 1))))))}
-@!taps
-
 (defn tapped [x]
-  (swap! !taps conj {:val x :tapped-at (java.time.Instant/now) :key (str (gensym))})
+  (swap! !taps conj (record-tap x))
   (clerk/recompute!))
 
-#_(tapped (rand-int 1000))
-
-#_(reset! @(find-var 'clojure.core/tapset) #{})
+(defonce tap-setup
+  (add-tap (fn [x] ((resolve `tapped) x))))
 
-(defonce setup
-  (add-tap tapped))
+(def tap-viewer
+  {:pred (v/get-safe ::val)
+   :render-fn '(fn [{::keys [val tapped-at]} opts]
+                 [:div.border-t.relative.py-3.mt-2
+                  [:span.absolute.rounded-full.px-2.bg-gray-300.font-mono.top-0
+                   {:class "left-1/2 -translate-x-1/2 -translate-y-1/2 py-[1px] text-[9px]"} (:nextjournal/value tapped-at)]
+                  [:div.overflow-x-auto [nextjournal.clerk.render/inspect-presented val]]])
+   :transform-fn (fn [{:as wrapped-value :nextjournal/keys [value]}]
+                   (-> 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
+                       (update-in [:nextjournal/value ::tapped-at] inst->local-time-str)))})
 
-#_ (remove-tap tapped)
 
+^{::clerk/visibility {:result :show}
+  ::clerk/viewers (v/add-viewers [tap-viewer])}
+(clerk/fragment (cond->> @!taps
+                  (= :latest @!view) (take 1)))
 
 (comment
   (last @!taps)
-
   (dotimes [_i 5]
     (tap> (rand-int 1000)))
-
   (tap> (shuffle (range (+ 20 (rand-int 200)))))
   (tap> (clerk/md "> The purpose of visualization is **insight**, not pictures."))
-  (tap> (v/plotly {:data [{:z [[1 2 3]
-                               [3 2 1]]
-                           :type "surface"}]}))
-  (tap> (javax.imageio.ImageIO/read (java.net.URL. "https://images.freeimages.com/images/large-previews/773/koldalen-4-1384902.jpg")))
-
+  (tap> (v/plotly {:data [{:z [[1 2 3] [3 2 1]] :type "surface"}]}))
+  (tap> (clerk/html  {::clerk/width :full} [:h1.w-full.border-2.border-amber-500.bg-amber-500.h-10]))
+  (tap> (clerk/table {::clerk/width :full} [[1 2] [3 4]]))
+  (tap> (clerk/plotly {::clerk/width :full} {:data [{:y [3 1 2]}]}))
+  (tap> (clerk/image "trees.png"))
   (do (require 'rule-30)
       (tap> (clerk/with-viewers (clerk/add-viewers rule-30/viewers) rule-30/rule-30)))
-
   (tap> (clerk/with-viewers (clerk/add-viewers rule-30/viewers) rule-30/board))
-
   (tap> (clerk/html [:h1 "Fin. 👋"]))
-
-  (reset-taps!)
-  )
+  (tap> (reduce (fn [acc _] (vector acc)) :fin (range 200)))
+  (reset-taps!))

src/nextjournal/clerk/viewer.cljc

@@ -313,7 +313,7 @@
 
 (defn into-markup [markup]
   (fn [{:as wrapped-value :nextjournal/keys [viewers opts]}]
-    (-> (with-viewer {:name `markdown-node-viewer :render-fn 'nextjournal.clerk.render/render-with-react-key} wrapped-value)
+    (-> (with-viewer {:name `markdown-node-viewer :render-fn 'identity} wrapped-value)
         mark-presented
         (update :nextjournal/value
                 (fn [{:as node :keys [text content] ::keys [doc]}]
@@ -474,24 +474,26 @@
 (defn transform-result [{:as wrapped-value :keys [path]}]
   (let [{:as _cell :keys [form id] ::keys [result doc]} (:nextjournal/value wrapped-value)
         {:keys [auto-expand-results? inline-results? bundle?]} doc
-        {:nextjournal/keys [value blob-id budget viewers]} result
+        {:nextjournal/keys [value blob-id viewers]} result
         blob-mode (cond
                     (and (not inline-results?) blob-id) :lazy-load
                     bundle? :inline ;; TODO: provide a separte setting for this
                     :else :file)
         #?(:clj blob-opts :cljs _) (assoc doc :blob-mode blob-mode :blob-id blob-id)
         opts-from-form-meta (-> result
-                                (select-keys [:nextjournal/css-class :nextjournal/width :nextjournal/opts])
+                                (select-keys [:nextjournal/css-class :nextjournal/width :nextjournal/opts :nextjournal/budget])
                                 (cond-> #_result
                                   (some? auto-expand-results?) (update :nextjournal/opts #(merge {:auto-expand-results? auto-expand-results?} %))))
-        presented-result (->> (present (cond-> (merge (->opts wrapped-value)
-                                                      (ensure-wrapped-with-viewers (or viewers (get-viewers *ns*)) value))
-                                         true (merge opts-from-form-meta)
-                                         true (assoc-in [:nextjournal/opts :id] (processed-block-id (str id "-result") path))
-                                         (seq path) (assoc-in [:nextjournal/opts :fragment-item?] true)
-                                         (contains? result :nextjournal/budget) (assoc :nextjournal/budget budget)))
-                              #?(:clj (process-blobs blob-opts)))
-
+        presented-result (-> (present (merge (dissoc (->opts wrapped-value) :!budget)
+                                             ;; reset budget from top level form for fragment items to have their own
+                                             (ensure-wrapped-with-viewers (or viewers (get-viewers *ns*)) value)
+                                             opts-from-form-meta))
+                             (update :nextjournal/opts
+                                     (fn [{:as opts existing-id :id}]
+                                       (cond-> opts
+                                         (seq path) (assoc :fragment-item? true)
+                                         (not existing-id) (assoc :id (processed-block-id (str id "-result") path)))))
+                             #?(:clj (->> (process-blobs blob-opts))))
         viewer-eval-result? (-> presented-result :nextjournal/value viewer-eval?)]
     #_(prn :presented-result viewer-eval? presented-result)
     (-> wrapped-value
@@ -1379,12 +1381,14 @@
   (:nextjournal/budget opts 200))
 
 (defn make-!budget-opts [opts]
-  (when-let [budget (->budget opts)]
-    {:!budget (atom budget)}))
+  (let [budget (->budget opts)]
+    (cond-> {:nextjournal/budget budget}
+      budget (assoc :!budget (atom budget)))))
 
 #_(make-!budget-opts {})
 #_(make-!budget-opts {:nextjournal/budget 42})
 #_(make-!budget-opts {:nextjournal/budget nil})
+#_(make-!budget-opts (make-!budget-opts {:nextjournal/budget nil}))
 
 (defn ^:private present-elision* [!path->wrapped-value {:as fetch-opts :keys [path]}]
   (if-let [wrapped-value (@!path->wrapped-value path)]
@@ -1497,8 +1501,7 @@
                (->opts (normalize-viewer-opts x)))
         !path->wrapped-value (atom {})]
     (-> (ensure-wrapped-with-viewers x)
-        (merge {:nextjournal/budget (->budget opts)
-                :store!-wrapped-value (fn [{:as wrapped-value :keys [path]}]
+        (merge {:store!-wrapped-value (fn [{:as wrapped-value :keys [path]}]
                                         (swap! !path->wrapped-value assoc path wrapped-value))
                 :present-elision-fn (partial present-elision* !path->wrapped-value)
                 :path (:path opts [])}

test/nextjournal/clerk/viewer_test.clj

@@ -312,7 +312,29 @@
             (->> (eval/eval-string "1\n(nextjournal.clerk/fragment 2 3 (nextjournal.clerk/fragment 4 5))\n6")
                  view/doc->viewer v/->value :blocks
                  (tree-seq coll? seq)
-                 (filter (every-pred map? :nextjournal/presented :nextjournal/blob-id))))))))
+                 (filter (every-pred map? :nextjournal/presented :nextjournal/blob-id)))))))
+
+  (testing "customizing budget, user-facing"
+    (is (= 5
+           (count
+            (->> (eval/eval-string "^{:nextjournal.clerk/budget 5}(reduce (fn [acc _i] (vector acc)) :fin (range 100 0 -1))")
+                 view/doc->viewer v/->value :blocks
+                 (tree-seq coll? seq)
+                 (filter (every-pred map? (comp #{'nextjournal.clerk.render/render-coll} :form :render-fn)))))))
+
+    (is (= 5
+           (count
+            (->> (eval/eval-string "(nextjournal.clerk/with-viewer {} {:nextjournal.clerk/budget 5} (reduce (fn [acc i] (vector acc)) :fin (range 15 0 -1)))")
+                 view/doc->viewer v/->value :blocks
+                 (tree-seq coll? seq)
+                 (filter (every-pred map? (comp #{'nextjournal.clerk.render/render-coll} :form :render-fn)))))))
+
+    (is (= 101
+           (count
+            (->> (eval/eval-string "^{:nextjournal.clerk/budget nil}(reduce (fn [acc i] (vector i acc)) :fin (range 101 0 -1))")
+                 view/doc->viewer v/->value :blocks
+                 (tree-seq coll? seq)
+                 (filter (every-pred map? (comp #{'nextjournal.clerk.render/render-coll} :form :render-fn)))))))))
 
 (deftest ->edn
   (testing "normal symbols and keywords"