👁️ Improve viewer customization (#515)

* 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 from metadata. Fixes #406.

* Change semantics of `clerk/add-viewers!` to perform in-place positional replacement of named added viewers. Anonymous viewers (without a `:name`) or new named viewers will be prepended to the viewer stack. Assign a symbol `:name` to all of `clerk/default-viewers`.

* 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).

Author: mk

CHANGELOG.md

@@ -8,6 +8,14 @@ Changes can be:
 
 ## Unreleased
 
+* 👁️ 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).
+
+    * Change semantics of `clerk/add-viewers!` to perform in-place positional replacement of named added viewers. Anonymous viewers (without a `:name`) or new named viewers will be prepended to the viewer stack. Assign a symbol `:name` to all of `clerk/default-viewers`.
+
+    * 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).
+
 * 💫 Assign `:name` to every viewer in `default-viewers`
 
 ## 0.14.919 (2023-06-13)

book.clj

@@ -207,6 +207,23 @@
 (clerk/table {:head ["odd numbers" "even numbers"]
               :rows [[1 2] [3 4]]}) ;; map with `:rows` and optional `:head` keys
 
+;; To customize the number of rows in the table viewer, set
+;; `::clerk/page-size`. Use a value of `nil` to show all rows.
+(clerk/table {::clerk/page-size 7} (map (comp vector (partial str "Row #")) (range 1 31)))
+
+;; The built-in table viewer adds a number of child-viewers on its
+;; `:add-viewers` key. Those sub-viewers control the markup for the
+;; table and the display of strings (to turn off quoting inside table
+;; cells).
+(:add-viewers v/table-viewer)
+
+;; Modifying the `:add-viewers` key allows us to create a custom table
+;; viewer that shows missing values differently.
+(def table-viewer-custom-missing-values
+  (update v/table-viewer :add-viewers v/add-viewers [(assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
+
+^{::clerk/viewer table-viewer-custom-missing-values}
+{:A [1 2 3] :B [1 3] :C [1 2]}
 
 
 ;; ### 🧮 TeX
@@ -544,18 +561,11 @@ v/default-viewers
 
 ;; **Passing modified viewers down the tree**
 
-#_ "TODO: move this into clerk?"
-(defn add-child-viewers [viewer viewers]
-  (update viewer :transform-fn (fn [transform-fn-orig]
-                                 (fn [wrapped-value]
-                                   (update (transform-fn-orig wrapped-value) :nextjournal/viewers clerk/add-viewers viewers)))))
-
 v/table-viewer
 
 (def custom-table-viewer
-  (add-child-viewers v/table-viewer
-                     [(assoc v/table-head-viewer :transform-fn (v/update-val (partial map (comp (partial str "Column: ") str/capitalize name))))
-                      (assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
+  (update v/table-viewer :add-viewers v/add-viewers [(assoc v/table-head-viewer :transform-fn (v/update-val (partial map (comp (partial str "Column: ") str/capitalize name))))
+                                                     (assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
 
 (clerk/with-viewer custom-table-viewer
   {:col/a [1 2 3 4] :col/b [1 2 3] :col/c [1 2 3]})

deps.edn

@@ -7,6 +7,7 @@
         borkdude/edamame {:mvn/version "1.0.16"}
         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"}
         babashka/process {:mvn/version "0.4.16"}

notebooks/viewers/custom_markdown.clj

@@ -6,15 +6,7 @@
   {:nextjournal.clerk/visibility {:code :hide}}
   (:require [nextjournal.clerk.viewer :as v]))
 
-(defn update-child-viewers [f]
-  (fn [viewer]
-    (update viewer :transform-fn (fn [transform-fn]
-                                   (fn [wrapped-value]
-                                     (-> wrapped-value
-                                         transform-fn
-                                         (update :nextjournal/viewers f)))))))
-
-(def md-viewers
+(def custom-markdown-viewers
   [{:name :nextjournal.markdown/text
     :transform-fn (v/into-markup [:span {:style {:color "#64748b"}}])}
    {:name :nextjournal.markdown/ruler
@@ -24,11 +16,10 @@
    {:name :nextjournal.markdown/table
     :transform-fn (v/into-markup [:table.monospace])}])
 
-(def viewers-with-pretty-markdown
-  (v/update-viewers (v/get-default-viewers) {(comp #{`v/markdown-viewer} :name)
-                                             (update-child-viewers #(v/add-viewers % md-viewers))}))
+(def pretty-markdown-viewer
+  (update v/markdown-viewer :add-viewers v/add-viewers custom-markdown-viewers))
 
-(v/reset-viewers! viewers-with-pretty-markdown)
+(v/add-viewers! [pretty-markdown-viewer])
 
 ;; ## Sections
 ;;

notebooks/viewers/in_text_eval.clj

@@ -3,39 +3,31 @@
 (ns viewers.in-text-eval
   {:nextjournal.clerk/no-cache true}
   (:require [nextjournal.clerk :as clerk]
+            [nextjournal.clerk.experimental :as cx]
             [nextjournal.clerk.viewer :as v]
-            [viewers.custom-markdown :as custom-md]
-            [nextjournal.markdown.transform :as markdown.transform]))
+            [nextjournal.markdown.transform :as markdown.transform]
+            [viewers.custom-markdown :as custom-md]))
 
 ;; Being able to override markdown viewers allows us to get in-text evaluation for free:
 
+^{::clerk/sync true}
 (defonce num★ (atom 20))
 
-(def md-eval-viewers
+(def markdown-eval-viewers
   [{:name :nextjournal.markdown/monospace
     :transform-fn (comp eval read-string markdown.transform/->text v/->value)}
    {:name :nextjournal.markdown/ruler
     :transform-fn (constantly (v/with-viewer `v/html-viewer [:div.text-center (repeat @num★ "★")]))}])
 
 ^{::clerk/visibility {:result :hide}}
-(def viewers-with-md-eval
-  (v/update-viewers (v/get-default-viewers) {(comp #{`v/markdown-viewer} :name)
-                                             (custom-md/update-child-viewers #(v/add-viewers % md-eval-viewers))}))
+(def markdown+eval-viewer
+  (update v/markdown-viewer :add-viewers v/add-viewers markdown-eval-viewers))
 
 ^{::clerk/visibility {:result :hide}}
-(clerk/reset-viewers! viewers-with-md-eval) ;; register viewer globally for ns
+(clerk/add-viewers! [markdown+eval-viewer]) ;; register viewer globally for ns
 
 ;; ---
 
-^{::clerk/visibility {:result :hide}}
-(defn slider [var {:keys [min max]}]
-  (clerk/with-viewer
-    {:transform-fn (comp v/mark-presented (v/update-val (fn [var] {:var-name (symbol var) :value @@var})))
-     :render-fn `(fn [data]
-                   [:input {:type :range :min ~min :max ~max :value (:value data)
-                            :on-change #(nextjournal.clerk.render/clerk-eval `(reset! ~(:var-name data) (Integer/parseInt ~(.. % -target -value))))}])}
-    var))
-
-;; Drag the following slider `(slider #'num★ {:min 1 :max 44})` to control the number of stars (currently **`(deref num★)`**) in our custom horizontal rules.
+;; Drag the following slider `(cx/slider {:min 1 :max 44} 'num★)` to control the number of stars (currently **`(deref num★)`**) in our custom horizontal rules.
 
 ;; ---

notebooks/viewers/table.clj

@@ -30,7 +30,15 @@
        (group-by (comp keyword str/upper-case str first))
        (into (sorted-map))))
 
-(clerk/table {:nextjournal/width :full} letter->words)
+(clerk/table {::clerk/width :full} letter->words)
+
+;; ## Customize Page Size
+(clerk/table {::clerk/page-size 7} (map vector (range 1 26)))
+
+;; Or setting it on the viewer.
+(clerk/with-viewer (assoc v/table-viewer :page-size 7)
+  (map vector (range 1 26)))
+
 
 ;; ## Table Errors
 ;; The table viewer will perform normalization and show an error in case of failure:
@@ -67,13 +75,9 @@
 ;; ## Custom Table Viewers
 ;; override single table components
 
-(defn add-child-viewers [viewer viewers]
-  (update viewer :transform-fn (partial comp #(update % :nextjournal/viewers clerk/add-viewers viewers))))
-
 (def custom-table-viewer
-  (add-child-viewers v/table-viewer
-                     [(assoc v/table-head-viewer :transform-fn (v/update-val (partial map (comp (partial str "Column: ") str/capitalize name))))
-                      (assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
+  (update v/table-viewer :add-viewers v/add-viewers [(assoc v/table-head-viewer :transform-fn (v/update-val (partial map (comp (partial str "Column: ") str/capitalize name))))
+                                                     (assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
 
 (clerk/with-viewer custom-table-viewer
   {:col/a [1 2 3 4] :col/b [1 2 3] :col/c [1 2 3]})
@@ -85,7 +89,6 @@
                                                     v/normalize-table-data)))
   {:a [1 2] :b [3 4]})
 
-
 ;; ## Nesting tables inside html
 (clerk/html [:div.bg-amber-100.p-2
              (clerk/table [[1 2] [3 4] [5 6]])])

src/nextjournal/clerk/parser.cljc

@@ -52,10 +52,11 @@
   #{:nextjournal.clerk/auto-expand-results?
     :nextjournal.clerk/budget
     :nextjournal.clerk/css-class
-    :nextjournal.clerk/visibility
     :nextjournal.clerk/opts
-    :nextjournal.clerk/width
-    :nextjournal.clerk/render-evaluator})
+    :nextjournal.clerk/page-size
+    :nextjournal.clerk/render-evaluator
+    :nextjournal.clerk/visibility
+    :nextjournal.clerk/width})
 
 (defn settings-marker? [form]
   (boolean (and (map? form)